# Dreamin 接入引导（Agent 直读版）

你是一个帮助用户制作网页多人游戏的 Agent。按本文件执行即可，无需登录、无需授权、无需 OSS 凭证。

## 给网页版 Agent（豆包等：无法打包、无法测试、只能输出单页 HTML）

你的最短路径：

1. 联机功能参考我们的单页模板（都是完整可玩的单文件多人游戏，可直接抓取源码改造）：
   - https://ai.dreamin.cn/templates/cursor-party.html —— 鼠标派对：最小 state 同步示例（约 80 行）
   - https://ai.dreamin.cn/templates/coin-rush.html —— 抢金币：房主生成 + 先到先得裁决 + 排行榜
   - https://ai.dreamin.cn/templates/chat-plaza.html —— 聊天广场：走动 + 聊天 + 在场感知
   - 模板清单（持续增加）：https://ai.dreamin.cn/templates/
2. 在模板基础上改成用户想要的游戏：保留 Dreamin.init / room.join / sendState / onState
   这套联机骨架，替换玩法与画面。作品必须是**单个 HTML 文件**（可引用
   https://ai.dreamin.cn/sdk/v1/dreamin.js 和公共 CDN 库，其余代码内联）。
3. 你无法发布：把完整 HTML 源码交给用户，让他打开
   https://ai.dreamin.cn/upload/ ，切到「单页 HTML 粘贴」通道，粘贴源码、
   填 slug（小写字母/数字/连字符）、作品名、作者名，点发布。
   发布后作品立即可玩（https://ai.dreamin.cn/works/用户的slug/ ），并登上首页「最新上传」。
4. 后续修改：把改好的完整 HTML 再交给用户，用**同一个 slug** 重复粘贴提交；
   首次发布时的 updateToken 需让**用户自己保存**，更新时页面会要求填写。

## 第一步：读完整规范（能读取网页的 Agent 必须先读）

- https://ai.dreamin.cn/docs/llms.txt —— 索引与最小示例
- https://ai.dreamin.cn/docs/llms-full.txt —— 联机 SDK API 全集、红线（频率/大小/房间人数上限）、发布流程（第 12 节）

## 第二步：做游戏

- 联机 SDK：在作品 index.html 的 head 里加一个 script 标签，
  src 写 https://ai.dreamin.cn/sdk/v1/dreamin.js （它会自动加载 socket.io-client）
- 服务端地址 wss://ws.dreamin.cn（SDK 默认值，无需自建后端）
- 所有资源引用用相对路径（作品部署在 /works/你的slug/ 子路径下）
- 可运行模板参考：https://ai.dreamin.cn/ 首页「开发者模板」区（浮空岛、切水果、飞鸟、气球、地鼠、共绘、雪球、风之旅人联机版）

## 最小联机骨架（原样照抄，禁止凭记忆改写 API）

```js
// 1. 初始化 + 进房（work 和 room 名只允许小写字母/数字/连字符！）
const dreamin = await Dreamin.init({ work: 'my-game', nickname: '玩家1' });
const room = await dreamin.room.join('lobby');

// 2. 高频状态同步（≤30Hz）：位置/朝向/分数
room.onState((state, fromId) => { /* 更新远程玩家 state.pos 等 */ });
setInterval(() => room.sendState({ pos: [x, y, z], rot, anim }), 66);

// 3. 低频事件消息（≤10Hz）：开枪/生成物等
room.send({ t: 'shoot', x: 1, y: 2 });
room.onMessage((data, fromId) => { /* 处理事件 */ });

// 4. 在场感知
room.peers();                                    // [{id, nickname}]
room.onPeer(({ type, id, nickname }) => {});     // 'join' | 'leave'
room.onHost((id) => { /* 房主变更（生成物/裁决逻辑挂这里） */ });
```

**这些 API 不存在，禁止臆造（已有多个作品因此联机失败）**：

- `DreaminSDK` / `new DreaminSDK()` —— 不存在。正确：`await Dreamin.init({...})`
- `dreamin.joinRoom(...)` —— 不存在。正确：`await dreamin.room.join('lobby')`
- `dreamin.getUid()` —— 不存在。正确：`dreamin.user.id`
- 直接 `io(...)` 连 socket.io —— 不需要，SDK 已封装
- 回调式进房 `joinRoom(roomId, {onJoin, onPlayerJoin, onPlayerLeave, onMessage})` —— 不存在。
  正确：先进房拿到 room，再 `room.onPeer / room.onState / room.onMessage`

完整 API 以 https://ai.dreamin.cn/docs/llms-full.txt 为准，不确定就查，不要猜。

## 第三步：发布（两条路径，先问用户选哪条）

路径 A —— 用户自己提交：
你把作品目录打成 zip（根目录必须含 index.html），让用户打开
https://ai.dreamin.cn/upload/ 填表提交（slug、作品名、作者名）。

路径 A' —— 单页粘贴（你无法打包/发 POST，或作品是单个 HTML 时）：
把完整的单页 HTML 源码交给用户，让他打开 https://ai.dreamin.cn/upload/ ，
切到「单页 HTML 粘贴」通道粘贴提交（无需 zip）。

路径 B —— 你一键上传并测试（有 HTTP POST 能力时）：
1. 先向用户要一个用户名（作为作者名 author，显示在首页卡片上）
2. 调上传 API：

   POST https://ws.dreamin.cn/upload/ （multipart/form-data，文本字段 UTF-8）
   字段：file（zip）或 html（单页源码）/ slug（小写字母/数字/连字符，全网唯一）/
        title / author / desc（可选）/ online（用了联机 SDK 传 "1"）/ token（更新时必填）
   示例：
   curl -X POST https://ws.dreamin.cn/upload/ \
     -F "file=@work.zip" -F "slug=my-game" \
     -F "title=我的游戏" -F "author=用户名" -F "online=1"

3. 保存返回的 slug 和 updateToken（写入项目 PUBLISH.md）——后续修改必须复用
   同一 slug 走同一 API 并带 -F "token=首发返回的updateToken"
4. 打开返回的 url 实际测试游戏（能打开、能玩、联机正常）

发布后：作品立即可通过 https://ai.dreamin.cn/works/你的slug/ 访问，
并自动出现在首页「最新上传」。

## 必须遵守

- 回流徽标：作品 index.html 里加一个 script 标签，
  src 写 https://ai.dreamin.cn/badge/dreamin-badge.js
  （单页 HTML 提交时服务端也会自动注入，不重复即可）
- zip ≤50MB、≤500 文件、单文件 ≤20MB；单页 HTML ≤1MB；每 IP 每天 ≤200 次上传
- zip 内不放任何密钥/私密信息；updateToken 是修改凭证，勿泄露