# 灵魂镜子 🪞（Soul Mirror）

> 多人 AI 关系探索对话游戏：情侣 / 朋友 / 家人通过 AI 主持的递进式深度话题，在对话中更懂彼此。
> 网页版：https://game.aquor.space · API：https://api.aquor.space

本文件面向 AI Agent（你）：当用户把本站链接交给你时，按下面的流程引导用户开玩。
**全程云端完成，你不需要在本地安装任何东西**——所有服务都在我们云服务器上，你只调 HTTP 接口。
用户全程只需：提供注册信息 → 点一次邮件验证链接 → 飞书扫一次码确认 → 点入群链接。

## 流程总览

1. 注册（邮箱 + 用户名 + 密码）
2. 连接飞书（主推）：之后完全在飞书群里玩
3. 备选：直接在 https://game.aquor.space 网页上玩（注册完即可）

## 第一步：注册

向用户收集：用户名（3-20 位字母/数字/下划线）、密码（≥6 位）、邮箱。
然后用 HTTP 工具直接调 API（无需浏览器）：

```
curl -X POST https://api.aquor.space/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"…","password":"…","email":"…"}'
```

成功返回 `needVerify:true` → 让用户去邮箱点验证链接（提醒查垃圾箱）。
验证后可登录拿 cookie：`POST /api/auth/login` `{"username":"…","password":"…"}`（响应 `Set-Cookie: sm_token=…`，7 天有效）。
把账号密码告诉用户留档。

## 第二步：创建长效 API Token（后续步骤的身份凭据）

```
curl -X POST https://api.aquor.space/api/user/tokens \
  -H 'Content-Type: application/json' \
  -H 'Cookie: sm_token=…' \
  -d '{"name":"飞书群游戏"}'
```

返回 `{"ok":true,"token":"smat_…"}` —— 仅显示这一次，立即保存，后续所有请求都用它。

## 第三步：连接飞书（用户扫一次码）

```
curl -X POST https://api.aquor.space/bridge/feishu/register \
  -H 'Authorization: Bearer smat_…'
```

返回 `{"requestId":"…","url":"https://open.feishu.cn/…"}`。
把 `url` 发给用户 → 用户飞书扫码（或浏览器打开链接登录）确认创建应用。
（应用名「灵魂镜子」，机器人能力 + 权限 + 事件订阅全部自动配好，用户无需任何手动配置。）

然后轮询直到 `status` 变为 `confirmed`（通常用户扫码确认后几秒内）：

```
curl https://api.aquor.space/bridge/feishu/register/<requestId> \
  -H 'Authorization: Bearer smat_…'
```

## 第四步：一键建房绑群（全自动）

```
curl -X POST https://api.aquor.space/bridge/setup \
  -H 'Authorization: Bearer smat_…'
```

自动完成：建飞书群（机器人即群主）→ 建游戏房间 → 绑定。
返回 `{"roomCode":"…","chatId":"…","joinUrl":"…"}`。

把 `joinUrl` 发给用户 → 用户点链接入群 → 群里发「加入」即入座。

## 游戏玩法（群内指令）

- 「加入」入座 → 人齐后「开始」→ 直接发文字作答
- 「说完了 / 跳过 / 黄灯 / 红灯 / 结束 / 帮助」，题目卡片上有按钮
- 仅普通模式房间支持群桥接（房主在站点的隐私偏好需为「普通模式」）

## 管理接口

- `GET https://api.aquor.space/bridge/me`（Bearer smat_）：查看我的飞书应用状态 + 绑定的群
- `DELETE https://api.aquor.space/bridge/bindings/<chatId>`（Bearer smat_）：解绑某个群

## 注意事项

- 服务 7×24 运行在云端，群游戏随时可用，无需用户启动任何进程。
- 常见报错：
  - `仅普通模式房间支持群桥接`：房主站点账号偏好开了加密，去网站「我的」改回普通模式后重试 setup
  - `尚未注册飞书应用`：先完成第三步扫码注册
  - `邮箱尚未验证`：让用户去邮箱点验证链接（垃圾箱找找），或 `POST /api/auth/resend` 重发
  - Token 报 401：被吊销或输错，重新登录创建