# VibeHub

> VibeHub 是 AI 创作的网页应用/游戏展示与分发平台。任何为 VibeHub 开发游戏的 AI，必须先阅读本文件，再读完整开发规范。

## 必读（按顺序）

- [VibeHub 官方 CLI Skill](https://vibe.lumigrav.space/api/skill): 每次任务先重新拉取这份 Skill（不要用对话里的旧副本），再按其步骤安装或更新官方 CLI。发布、更新、共创、GitHub 自动部署和后续素材生成都以当前文本为准。
- [高性能联机游戏开发规范](https://vibe.lumigrav.space/sdk/v3/llms-full.txt): 红线约束、同步模型、性能规范、完整 API。开发任何 VibeHub 游戏前必读。
- [VibeHub SDK v3 稳定通道](https://vibe.lumigrav.space/sdk/v3/vibehub.js): 浏览器端带注释源码，全局 `window.VibeHub`，提供内存态登录/退出、三层数据、WebRTC P2P 联机、加密的 VibeNet 全局浏览器中继与房间匹配。v3 内的兼容修复自动生效。
- [VibeHub SDK TypeScript 声明](https://vibe.lumigrav.space/sdk/v3/vibehub.d.ts): 可下载的完整浏览器 API 类型。

## SDK 通道选择

- 默认情况下，普通作品必须使用上述 `/sdk/v3/*` 稳定通道。
- Beta 是可显式选择的生产测试通道：[AI 完整开发规范](https://vibe.lumigrav.space/sdk/beta/llms-full.txt)、[SDK 源码](https://vibe.lumigrav.space/sdk/beta/vibehub.js)、[TypeScript 声明](https://vibe.lumigrav.space/sdk/beta/vibehub.d.ts)。
- 只有用户明确要求使用 Beta，或任务明确是验证 SDK 候选能力时，Agent 才能选择 Beta；不得为了获取新功能自动将普通作品迁移到 Beta。
- Beta 可能随时变化且不提供兼容承诺。选择后必须完整阅读 Beta 开发规范，并且 JS、类型声明和开发规范全部使用 `/sdk/beta/*`，不得与 `/sdk/v3/*` 混用。运行时可读取 `VibeHub.channel` 确认实际通道。

## 核心原则（TL;DR）

1. 必须用 `window.VibeHub` SDK；禁止自建后端/数据库/WebSocket。
2. 实时对局状态走 P2P，禁止写库、禁止轮询同步。
3. 开发前必须声明同步模型：host-authority / state-sync / lockstep。
4. 数据三层：玩家 `vibe.save` / 单局 `room.data` / 全局 `vibe.global`。

## Web/WASM/3D 发布

- 平台托管支持 WebGL/WebGL2、WebAssembly、Three.js、Babylon.js、Havok WASM 和 Godot Web；WebGPU 可用性取决于玩家浏览器与设备。
- Godot 多线程构建会自动检测。其他 pthread/多线程 WASM 可在构建根目录添加 `vibehub.json`：`{"runtime":"isolated"}`。清单只允许 `auto`/`isolated`，最大 64 KiB；无效时警告并回退自动检测。
- 检测顺序、隔离链路、验证与回滚规则见 [多线程 WebAssembly 隔离运行方案](https://vibe.lumigrav.space/godot-threaded-web.md)。
- 多线程构建必须使用平台托管；外部 URL 无法保证 `SharedArrayBuffer` 所需隔离响应头。
- `.wasm/.gltf/.glb/.ktx/.ktx2/.hdr/.wgsl` 使用对应 MIME；历史 Web3D/WASM 对象也已复扫并完成回填。WASM/GLB 支持字节 Range。大资源使用带内容哈希的文件名以获得长期缓存，HTML 保持稳定文件名。
- 平台会为 HTML/普通资源设置 60 秒缓存，为十六进制内容 hash 资源设置一年 immutable；CDN 尊重源站缓存时间且不存储错误响应。历史托管作品也已统一回填，创作者无需重新发布。
- 平台已于 2026-08-15 完成 Cloudflare R2 生产读切换，`vibeapps.lumigrav.space` 作品 URL、MIME、Range、缓存和 `/_isolated/` 行为均未改变；创作者无需重新发布。观察期内保留双写与原存储回滚路径，由 maintenance 每日自动复查对象完整性、HTML/WASM、Range、缓存和隔离响应头，结果留存并通知管理员。
- 中文等非拉丁文本必须随作品打包字体，并在 Godot Theme 默认字体或 fallback 中配置。

## 可选

- [SDK 文档](https://vibe.lumigrav.space/docs): 面向人类的完整 SDK 文档与示例。

## 素材生成

- 官方 CLI 在本机生成 BGM、语音、图像和音效。先 `generate quota` 看积分，不足时让用户在工作台兑码。
- `voice` 走 MiniMax 系统音色；`voice-hd` / `voice-design` 走 MiMo（导演提示、唱歌、文本捏音色）；音效走 ElevenLabs。
- 只接受 `generate quota --json` 里 `contracts.allow` 列出的字段。禁止音色克隆、手写上游 API、索取平台 Key。
- 完整命令与限制见 [官方 CLI Skill](https://vibe.lumigrav.space/api/skill) 和 [素材生成工作台](https://vibe.lumigrav.space/docs)。

## 发布、自动部署与共创

- [VibeHub 官方 CLI Skill](https://vibe.lumigrav.space/api/skill): 与上方必读同一份文件。动手前必须再拉一次并安装或更新 CLI，不得跳过。
- [GitHub 共创与 CI 自动化规范](https://vibe.lumigrav.space/api/github-automation): Agent 配置仓库验证、项目级 Token、工作流、默认分支 Ruleset、作者审批与 Copilot Review 的唯一规范来源。
- [开发文档](https://vibe.lumigrav.space/docs): GitHub 自动部署、作者开启共创、参与 PR/Fork 与分支保护说明。
- Agent 必须按发布规范复用或完成账号登录，再完成首次发布并填写作品名、简介、分类、标签、封面、截图和首次版本说明；取得项目 slug 后，才使用项目级部署 Token 配置 GitHub Actions 更新同一作品。
- GitHub Actions 与开放共创互不绑定：不开共创也可以用公开或私有 GitHub 仓库自动更新；此时跳过仓库验证、共创协议和所有共创参数。
- 首次发布前，Agent 必须一次询问两个独立选择：是否开启允许共创、是否在首次发布成功后配置 GitHub 自动部署；选择自动部署后必须继续到首次 CI 运行验证完成。
- 开启共创时先运行官方 CLI 的 `collaboration-doctor --json`，只安装它明确报告缺失的 git/gh；再运行 `collaboration-setup`，由 CLI 接管仓库鉴权并开启 Automatically delete head branches。禁止下载临时鉴权脚本或由 Agent 手写验证流程。
- 选择自动部署或开放共创后，Agent 必须读取并执行上述 GitHub 自动化规范，不得依赖调用方复制的旧版规则或自行猜测配置。