# group.aquor.space — 飞书群聊 AI 助手托管平台 API

> 本文档面向 AI agent / 自动化脚本：本站全部功能均可通过 HTTP API 完成，无需浏览器界面。
> Base URL: https://group.aquor.space

## 认证

两种方式（所有 /api/v1/* 接口通用）：

1. **PAT（推荐 agent 使用）**: `Authorization: Bearer gapt_...`
   - Token 需用户登录网站后在 Dashboard「API Token」页创建（一次性显示）
   - 用户登录方式为邮件 Magic Link：`POST /api/auth/magic-link {"email": "..."}`
     发送登录链接（邮件由网站自建通道发送，须管理员已在后台配置），
     agent 无法替用户点击邮件链接，PAT 仍需用户首次手动创建
2. **浏览器 Cookie**: 用户在网站登录后 Dashboard 自动使用

## 核心流程（组织一场群游戏）

```
1. GET  /api/v1/model-presets            # 查看可用模型（或用户已添加自备模型）
2. POST /api/v1/skills                   # 创建技能（人设 prompt + 模型，可自动分配）
3. POST /api/v1/sessions                 # 开一场游戏（两种模式，见下）
4. GET  /api/v1/sessions                 # 查看状态；群内玩家也可发「总结」「结束」
5. DELETE /api/v1/sessions/{id}          # 收场：AI 总结发群 → 主持人下线
```

飞书侧由平台统一托管：全站共用一个飞书机器人（管理员配置的全局应用，
已开启「对外共享」），用户无需接触飞书开放平台。

## 接口明细

### 认证

- `POST /api/auth/magic-link` `{"email"}` — 发送 Magic Link 登录邮件
- `POST /api/auth/signout` — 退出登录

### 用户

- `GET /api/v1/me` — 我的信息 + 平台飞书机器人状态 + bridge 在线状态

### 技能（skill = 群聊助手的配置）

- `GET /api/v1/templates` — 内置技能模板（文字冒险/狼人杀/话题夜谈），创建 skill 时可直接复制其 system_prompt
- `GET /api/v1/skills` — 我的技能列表
- `POST /api/v1/skills` `{"name", "systemPrompt", "modelPresetId"?, "userModelId"?, "config"?}` — 创建
  - 模型可不指定（推荐）：都不传 = 自动分配（用户自备优先，其次网站预设；多模型轮转、失败自动切换）
  - 也可指定其一：`modelPresetId`（网站预设）或 `userModelId`（自备）
- `GET|PATCH|DELETE /api/v1/skills/{id}` — 查询/修改/删除（删除前需收场所有使用中的会话）

### 模型

- `GET /api/v1/model-presets` — 网站预设模型（enabled 且已配 Key 的才 usable）
- `GET|POST /api/v1/user-models`，`PATCH|DELETE /api/v1/user-models/{id}` — 用户自备模型（OpenAI 兼容）
  - POST body: `{"name", "baseUrl", "model", "apiKey"}`；baseUrl 含 /v1，如 `https://api.deepseek.com/v1`
  - PATCH body: `{"name"?, "baseUrl"?, "model"?, "apiKey"?}`（留空字段不改动）
  - 常见供应商端点：智谱 `https://open.bigmodel.cn/api/paas/v4`（glm-4-flash 免费）、DeepSeek `https://api.deepseek.com/v1`（deepseek-chat）、Kimi `https://api.moonshot.cn/v1`（kimi-k2.6）、OpenAI `https://api.openai.com/v1`（gpt-4o-mini）
  - 管理员停用预设后，绑定该预设的技能会建会话失败（自动分配的技能不受影响，会自动切换到其他可用模型）

### 游戏会话

- `GET /api/v1/sessions` — 会话列表（含 summary）
- `POST /api/v1/sessions` `{"skillId", "mode"?, "groupName"?}` — 开一场游戏，两种模式：
  - `mode: "create"`（默认，平台建群）：返回 `{sessionId, chatId, joinUrl, external, warning}`
    - 把 joinUrl 发给玩家，玩家用飞书打开链接入群（外部群支持组织外用户），群里发「开始」即开局
    - external=false 时为企业内部群（外部用户无法加入）
  - `mode: "bind"`（绑定已有群）：返回 `{bindCode, botName, expiresAt, instructions}`
    - 用户先把平台机器人拉进目标群（群设置 → 群机器人 → 添加机器人，搜索 botName）
    - 然后在群里发送：`绑定 {bindCode}`，机器人验证后开局
    - 绑定码 30 分钟有效、一次性；agent 可将 bindCode 转告用户在群里发送
- `GET /api/v1/sessions/{id}` — 会话详情
- `DELETE /api/v1/sessions/{id}` — 收场（AI 总结 → 发群 → 主持人下线；机器人建群任群主时解散群，否则保留群）

### Token

- `GET|POST /api/v1/tokens`，`DELETE /api/v1/tokens/{id}` — PAT 管理（创建仅限浏览器会话）

### 群内指令（玩家侧，无需 API）

`帮助` / `开始` / `总结` / `结束` — 机器人即 responds；普通发言由 AI 主持人按人设回应
未绑定的群里发 `绑定 CODE` 可开局（需先在网站生成绑定码）

## 速率与限制

- 绑定码 30 分钟过期、一次性使用；一个群同时只能有一场进行中的游戏
- 收场后：机器人建群任群主的群会被解散；用户/绑定群保留（机器人不再应答，群主可移除）