docs(api): api-client → v0.56（协同 A2/G2/G3/G4 契约 + 三个环境变量 + 修正两处错误陈述）
- A2：interrupt 新增 scope（{"","all","current"}），三态语义 + 非法值定向 bad_request；
session_interrupted 形状零变化但 dropped 恒为真丢弃数
- G2：stream:true 直达编排器；响应面补 202 {queued} / 409 chat_busy / 503 chat_dispatch_failed；
未接 loop 由 200 改 500 chat_unavailable（行为变更已写明兼容性）
- G3：image 解码后 5 MiB 上限 → 400 image_too_large（指路上传）；**如实写明 WS 侧到不了这条判定**
（wsReadLimit=4096 传输层直接断连，发真实图片必须「上传 + URL」）
- G4：新增可选 clientMsgId（两端）⇒ 幂等；REST 200 {duplicate:true,messageId}、WS 新帧 chat_duplicate
（owner+admin，fail-closed）；键回填进 message_persisted/channel_persisted/读接口；迁移 0013
- .env.example + api-client 新增三个环境变量：OWNER_IDENTITY_INJECTION(owner_only 默认) /
CONTEXT_MAX_TOKENS(32768；0/负 = 关) / GUARDRAIL_KEYWORDS(留空 = 不挂)
- 修正两处错误陈述：api-reference §6.2 与 §6.6 的「OnStream 只填 seq、不带 turnId」（v0.36 起即带
sessionId+turnId，v0.50 起带 streamId）；上传上限 50MB → 5 MiB
This commit is contained in:
AskaEth committed
1 parent
7512d593c2
commit
8c6c796a29
3 files changed
+70
-25
No files matched your search
@@ -178,6 +178,12 @@ CONTEXT_MAX_TOKENS=32768
|
||||
# 内定的安全默认值，不对外开放配置（见 cmd/cyrene/wire_guardrail.go）。
|
||||
# GUARDRAIL_KEYWORDS=
|
||||
|
||||
# ---- 主人身份说明书注入范围（design/11 §0 红线） ----
|
||||
# 主人身份说明书（owner.yaml identityFile）注入范围：owner_only(默认，仅主人会话) | always(所有会话，含群聊/陌生人，仅自测) | off。
|
||||
# owner_only 按渠道层强类型 actor 元数据判定；非法值回退 owner_only 并记 WARN（绝不静默放行）。
|
||||
# 它只决定那段知识进不进该会话的上下文，不参与任何身份/权限判定（身份始终看 actor 元数据 + 白名单）。
|
||||
OWNER_IDENTITY_INJECTION=owner_only
|
||||
|
||||
# ---- 推送出口（D1，主动推送的两级投递）----
|
||||
# 主动消息在 WS/IM 投递之外，异步镜像到「主人自建统一推送服务」（主通道）。
|
||||
# 该服务不可达/未配时，日志注明「个推(Getui)回退待接入」——当前无 Getui SDK，不伪造投递。
|
||||
|
||||
+38
-11
@@ -27,10 +27,10 @@
|
||||
| 1a | `/api/v1/auth/refresh` | POST | refreshToken | ✅ | **静默续期**（B2）：body `{refreshToken}` → `{data:{token,expiresAt,role,refreshToken?}}`（新 access + 新 refresh；**`role` 恒返回** = 该 refresh grant 记录的角色 `owner|admin|viewer`），**默认单次使用旋转**——旧 refresh 立即作废，并发重放 fail-closed `401 invalid_grant`）。`AUTH_REFRESH_ROTATE_DISABLED=true` 关闭轮换时旧 token 保持有效、不返回新 refresh。过期/已撤销/乱串统一 `401 {error:{code:"invalid_grant"}}`；成功才审计 |
|
||||
| 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）→ `{data:{revoked:<bool>}}`；带 `Authorization: Bearer <jwt>` 且无 body → 撤**该账号全部** grant（全设备登出）→ `{data:{revoked:<bool>,revokedCount:<n>}}`。**两种响应形状不同**——单撤**没有** `revokedCount`；两者都不给回 `400 bad_request`。refresh 相关操作成功才审计 |
|
||||
| 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
|
||||
| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06 §0；**v0.53 语义修正**）——**主模型能不能收图看生效组的 `multimodal`**（`models.json` 组键，面板可保存、热更新）；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**，**与主模型能否收图无关**（裁决 14.4.1）；主模型不收图时由视觉·OCR 工具的**文本描述**替代（图像不占上下文，只有工具结果占）；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `<p>` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` |
|
||||
| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,clientMsgId?,stream?}` → `{data:{reply}}`；`stream:true` 时**直达会话编排器**（v0.56/G2：不再经可丢弃的 bus，成功受理后才回，见本行末尾「`stream:true` 响应面」）。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06 §0；**v0.53 语义修正**）——**主模型能不能收图看生效组的 `multimodal`**（`models.json` 组键，面板可保存、热更新）；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**，**与主模型能否收图无关**（裁决 14.4.1）；主模型不收图时由视觉·OCR 工具的**文本描述**替代（图像不占上下文，只有工具结果占）；**`image` 上限（v0.56，G3）**：解码后 **5 MiB**（与 `POST /api/v1/upload` 同口径；base64 字符串上限 = `ceil(n/3)*4 + 64` 字符，已含 data: URI 前缀余量），超限一律 `400 {error:{code:"image_too_large", message}}`（文案指路 `POST /api/v1/upload`）；**WS `chat` 帧到不了这条判定**——WS 读上限 `wsReadLimit = 4096` 字节/帧，超限由传输层直接断连，故 WS 上发真实图片本就必须「上传 + URL」；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `<p>` 拆气泡）。`clientMsgId`（v0.56，G4）为**客户端自带的幂等键**（可选）：同一会话内同一个非空值只承认第一条，重复到达回 `200 {data:{duplicate:true,messageId,sessionId}}` 且**不落库、不起回合、不发新内容帧**；省略 = 与加入该字段前逐字相同（详见 §3.13）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}`。**`stream:true` 响应面（v0.56，G2，行为变更）**：受理成功后才回——空闲已起回合 = `200 {data:{stream:true}}`、正忙已续接排队 = `202 {data:{stream:true,queued:true,queueDepth}}`、队列满 = `409 {error:{code:"chat_busy"}}`、幂等键重复 = `200 {data:{duplicate:true,messageId,sessionId}}`；**未接 loop 改为 `500 {error:{code:"chat_unavailable"}}`**（旧文写 `200 {stream:true}`，现与同步路径同口径）；仅当**未接编排器**才回退总线派发，其失败回 `503 {error:{code:"chat_dispatch_failed"}}`——**不再有「先回 200 再看有没有落地」**，故 `202`/`409` 从此**真的会出现**（修复前因提前 return 永不出现） |
|
||||
| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：以代码为准 = `pinned DESC, (type='main') DESC, created_at ASC`**——`pinned=true` 最前，其次是未置顶的主会话，最后是未置顶子会话（按 `createdAt` 升序）；⚠️ **置顶的次级会话会排在主会话之前**，客户端定位主会话请按 `id=="web"` / `type=="main"`，**不要假定 index 0 就是主会话**；次级 `web:<uuid>`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 |
|
||||
| 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:<uuid>"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色（design/22 §2：渠道级只作"新会话的初始角色提供者"；**会话角色只在创建时写入、之后不可变**，见 §1 行 8 / design/22 §8-1）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） |
|
||||
| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：逐条记录"谁说的"——会话角色在创建时固定，§8-1；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` |
|
||||
| 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：逐条记录"谁说的"——会话角色在创建时固定，§8-1；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`clientMsgId`（v0.56，可选，G4）**=该消息的**客户端幂等键**（带 `clientMsgId` 发的 user 消息会回填它；空则省略），客户端据此把本地乐观气泡对齐到服务端真相；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` |
|
||||
| 6a | `/api/v1/messages/{id}` | PATCH | JWT(owner/admin) | ✅ | **编辑单条消息**（D3）：body `{content}`（非空、≤4000 rune，空/纯空白/超长回 `400`）→ **`{data:<消息DTO>}`**（`data` **直接就是**更新后的完整消息 DTO，含 `id/sessionId/role/content/.../createdAt`，**无 `message` 包一层**；**只改 `content`**，role/时间戳/平台保持不变）；消息不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_edited`**（§3.8，账号其它端免刷新同步）。**重发不单独设端点**——客户端用「编辑后的内容再 `POST /chat`」即可（避免重复轮次语义） |
|
||||
| 6b | `/api/v1/messages/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除单条消息**（D3）→ `{data:{deleted:<id>}}`；不存在回 `404 not_found`；未注入 HistoryStore 回 `501`。**成功后广播下行 `message_deleted`**（§3.8，账号其它端按 `id` 移除） |
|
||||
| 7 | `/api/v1/sessions/{id}` | DELETE | JWT(owner/admin) | ✅ | **删除次级会话及其消息** → `{data:{deleted:<id>}}`；主会话不可删回 `403 forbidden`；未注入 HistoryStore 回 `501` |
|
||||
@@ -112,7 +112,7 @@
|
||||
- Web 端镜像实现在 `frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 对未知值返回原值），权威仍以本端点为准。
|
||||
- **反漂移保证（后端）**：后端有测试断言「每个内置适配器的 `Name()` 都在 `platforms` 表内」「`moods` 与 persona 情绪状态机的内置状态一致」「`modes` 与前端 `MODES` 九模式一致」——漏登记即 CI FAIL，客户端拿到的表不会滞后于代码。
|
||||
|
||||
> **契约版本 `v0.55`**（**阶段 7 落地项登记：路径式安全入口 + 数据目录 `platform` + OneBot v11 四端 + 可观测实时推送**，依据裁决 1.6 / 16.4.7 / 12.4.2（commit `a398dc9`）、1.4 / 12.4.1（commit `9253fef`）、05.4.3 + 16.4.3-WS（commit `0e1f163`），以及 13.4.5 面内三条（commit `74b12d8`）、MCP 官方 SDK（commit `a1083a3`），2026-10-04 落实）：**A. 安全入口 `ADMIN_PATH`（裁决 1.6 / 16.4.7，前端路由面）**——① env 新增 **`ADMIN_PATH`**（默认 `admin`）：面板**前端**路由前缀 = `/` + 值（`admin` → `/admin`，`xxx/admin` → `/xxx/admin`；**非法值回退 `/admin`**——容忍首尾斜杠与空白，拒绝 `.`/`..` 段与 `?`/`#`）。② HTTP 行为：`/<ADMIN_PATH>` 与其深链返回**注入了 `<base href="/">` 与 `window.__CYRENE_ADMIN_ENTRY__={"prefix":"..."}` 的 index.html**（`Cache-Control: no-store`）；**形如面板入口（路径里出现 `admin` 段）但前缀不符的路径 → `404`**（不回落用户端聊天壳、不泄露正确前缀）；`/<ADMIN_PATH>` 若恰好命中 `dist` 真实文件则仍走文件服务器。③ **API 不藏**：`/api/v1/*`、`/api/v1/admin/*`、`/ws/chat`、webhook 一律原样，**无新端点、无帧变更**。④ **口径**：用户端 HTML **永不携带该前缀串**（后端只在命中前缀时注入）⇒ 用户端既无管理入口链接、也解析不出面板路由（design/07 §0.2；前端路由改**路径式**：`frontend/web/src/admin/router.ts` 只读注入、无硬编兜底、移除 hash 入口）。**B. 数据目录（同 commit，裁决 12.4.2）**——`DATA_DIR` 新增可接受值 **`platform`**（大小写不敏感）→ 平台标准目录；默认 `./data` 与显式路径行为不变；**显式空值行为不变**（仍走原兜底）。**C. OneBot v11 四端（`9253fef`，裁决 1.4 / 12.4.1）**——① 配置面（channels.json 账号 `config` + 适配器 `Config()` 快照）新增 `transport`（`ws`|`http`，默认 `ws`，未知值回落 `ws`）/ `api_base_url` / `report_path`（默认 `/`）；快照 camelCase 为 `transport`/`apiBaseURL`/`reportPath`；`remoteURL` 快照值 = `remote_url`、为空时回落 `api_base_url`（语义即「出站远端地址」），**既有键与值不变**。② env 兜底 `CHANNEL_QQ_OBV11_TRANSPORT`（默认 `ws`）/ `CHANNEL_QQ_OBV11_API_BASE_URL` / `CHANNEL_QQ_OBV11_REPORT_PATH`。③ 四端语义：`ws+client` Cyrene 拨号、收发同一 WS；`ws+server` OneBot 反连、收发同一 WS；`http+client` Cyrene→OneBot（`POST {api_base_url}/{action}`，纯出站）；`http+server` OneBot→Cyrene（POST 到 `listen_addr`+`report_path`，纯入站，fail-closed 鉴权、10MiB 体上限）。④ 取舍：`mode` 决定**哪一半必需**（server 必需 `listen_addr`、client 必需 `api_base_url`），另一半给齐字段就一并启用 ⇒ 单个适配器即可「收上报 + 回消息」。⑤ 端口例外：`http+server` 用 `listen_addr`，属 `AGENTS.md` §9 已登记的**同一豁免**（design/13 §0 原文即写「WS server / HTTP server」）；`listen_addr` 为空则报错、**绝不开端口**。**D. 可观测实时推送（`0e1f163`，裁决 05.4.3 + 16.4.3-WS）——新增一节 §3.12**：三个**下行新帧** `observability_log`（`{entries:[{time,level,source,msg}…]}`，最新在前，上限 200 条）/ `observability_trace`（`{spans:[…]}`，上限 100 条）/ `observability_metrics`（`AdminMetrics` 本体、扁平），均**纯新增**（既有帧名/形状零改动）、帧壳**不带** `sessionId`/`turnId`/`seq`；三者**不在** `frameReachesAll` 白名单 ⇒ fail-closed **只发 owner+admin**（viewer 继续走 REST 只读档）；订阅 = owner/admin 凭据**读取** `GET /admin/observability/{logs,metrics,trace}` 任一个（该次读取照常返回完整引导数据），该凭据 WS 连接全断即退订并停循环（**不是轮询、无常驻 goroutine**）；**REST 端点完全不变**，`?level=` 分级过滤改由**客户端本地**做（帧广播给所有 `owner`/`admin` 连接，订阅只决定循环跑不跑）。**E. 其余（各一句）**：① **13.4.5 面内三条**（`74b12d8`）——续接窗口 `Recent` 在同毫秒并列时改为取**最新** n 条且按插入序（**无 API 变化**，但客户端可观察到的「握手回放 / 续接上下文」顺序更正确）；上行 `chat` 不再经**可丢弃**的 bus（**帧序列不变**）；被**取消**回合的 checkpoint 不再顶掉下一条消息，新增内部常量 `loop.StopReasonCanceled`（`checkpoints.state.stop_reason` 可能出现该值，**不经 REST/WS 暴露**）。② **MCP**（`a1083a3`）——协议层换成**官方 Model Context Protocol Go SDK v1.8.0**，**REST/WS/env/数据目录零变更**（`MCP_SERVERS_JSON`、`MCP_*`、`transport` 枚举 `stdio|http|streamable|sse` 全不变）。**未做（诚实边界）**：DashScope 形状的 `auto` 推断、Qwen 的 `/think` 前导消Line truncated
|
||||
> **契约版本 `v0.56`**（**协同项 A2 / G1 / G2 / G3 / G4 / F3 落地登记：`interrupt` 支持 `scope` + REST `stream:true` 不再静默失败 + `chat.image` 上限 + `clientMsgId` 幂等 + 视觉链路 URL 取回与类型裁决 + 既有错误陈述更正**，依据 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 A2 / G1 / G2 / G3 / G4 / F3（commit `7512d59` 等，2026-10-04 落实）：**A. 上行 `interrupt` 新增可选 `scope`（A2）**——`{sessionId}` → `{sessionId, scope?}`，取值域 `{"", "all", "current"}`（**省略 / 空串 / `"all"` 三者同义**）：`all` = 取消当前任务 + 清空待处理队列（**逐字不变的现状语义**）；**`"current"` = 只取消当前任务、保留待处理队列**（队列消息按编排器正常续跑规则继续执行、带上会话尾部上下文）；**其余取值 → 只回发送者** `{type:"error",data:{code:"bad_request"}}`（**定向**：不广播、不打断任何会话，绝不静默按默认执行）；命中空闲会话为 no-op。下行 `session_interrupted` 帧形状**零变化**（`{sessionId, mode, dropped}`），但 `dropped` 恒等于**真的被丢弃**的待处理条数——`scope:"current"` 时为 `0`，且 `mode` 是该会话当时的**忙碌通道**（`thinking|executing|subagent`，**不是 `idle`**）；`scope:"all"` 时 `mode` 为 `idle`、`dropped` 为清空的 pending 条数。**B. REST `stream:true` 不再静默失败（G2，行为变更）**——该分支改为与 WS `chat` 帧**同一条直达编排器的路径**（design/15 §2.1「会话消息不得被 drop」），**响应面**：受理成功后才回 `200 {data:{stream:true}}` / 正忙已续接排队 `202 {data:{stream:true,queued:true,queueDepth:n}}` / 队列满 `409 {error:{code:"chat_busy"}}` / 幂等键重复 `200 {data:{duplicate:true,messageId,sessionId}}`；**未接 loop → `500 {error:{code:"chat_unavailable"}}`**（旧文写 `200 {stream:true}`，现与同步路径同口径）；仅**未接编排器**才回退总线派发，其失败回 `503 {error:{code:"chat_dispatch_failed"}}`（此前 `Publish` 的错误被吞掉，且传的是**请求作用域** ctx）。**`202`/`409` 从此真的会出现**（修复前因提前 `return 200` 永不出现）。派发用的回合上下文与请求作用域脱钩（`context.WithoutCancel` + 30 分钟上限），回合不会在客户端刚收到 200 时被连带取消。**向后兼容**：`stream:false` 与既有同步响应形状一字未动；依赖「任何情况都拿到 200」的客户端必须按上表分支，别再假设 `stream:true` 恒 `200`。**C. `chat.image` 上限（G3）**——`POST /api/v1/chat` 的 `image` 新增硬上限：**解码后 5 MiB**（与 `POST /api/v1/upload` 同口径；base64 字符串上限 = `ceil(n/3)*4 + 64` 字符，覆盖 data: URI 前缀），超限 → `400 {error:{code:"image_too_large", message}}`（文案指路 `POST /api/v1/upload`），在**任何解码 / 落库 / 入模型之前**拦下（超大 base64 因此不进历史、也不会被重连回放重传）。**事实（勿误读为「WS 也有这条 400」）**：WS `chat` 帧**今天已被传输层关死**——WS 读上限 `wsReadLimit = 4096` 字节/帧，超限直接断连，**到不了**这条判定 ⇒ **WS 上发真实图片本就必须「上传 + URL」**。**D. `clientMsgId` 幂等（G4）**——上行**新增可选** `clientMsgId`（REST `chat` 体与 WS `chat` 帧都支持；**省略 = 老行为逐字不变，老客户端零影响**）：同一会话内同一个非空值只承认第一条。**重复到达**：REST → `200 {data:{duplicate:true,messageId,sessionId}}`；WS → 新下行帧 **`chat_duplicate`**（`{type:"chat_duplicate", sessionId, data:{sessionId, clientMsgId, messageId}}`，见 §3.13）；重复**不落库、不起回合、不发任何内容 / 流式新帧**。**判重由 SQLite 部分唯一索引原子裁决**（`(session_id, client_msg_id) WHERE client_msg_id != ''`），并发的两次重发只有一个赢家，不存在「先查再插」的竞态窗口。`clientMsgId` 另**回填进消息 DTO** ⇒ `message_persisted` / `channel_persisted` / 握手 `history` 回放与 `GET /sessions/{id}/messages` 等读接口可见（空则省略），客户端据此把本地乐观气泡对齐到服务端真相（替代「靠文本相等」的脆弱匹配）。**迁移**：新增 `0013_chat_client_msg_id`（up：加列 + 部分唯一索引 `idx_chat_messages_client_msg_id`；down：先删索引再删列；全新库由 `history.NewStore` 幂等前滚）。**E. 视觉链路事实修正（F3）**——`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）现在由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再原样转给上游**；同源 upload 产物优先走**本地文件读取**。**类型裁决**：**字节嗅探是唯一裁决权**（声明的 Content-Type / 扩展名只作参考且可被否决），嗅探为文本（HTML / PROXY 错误页 / SVGLine truncated
|
||||
|
||||
## 2. REST 端点（管理，`/api/v1/admin/*`）
|
||||
|
||||
@@ -214,6 +214,14 @@
|
||||
- `LLM_LOCAL_*` **三个条件缺一不可**：`LLM_LOCAL_ENABLED=true` **且** `LLM_LOCAL_BASE_URL` 非空 **且** `LLM_LOCAL_MODEL` 非空；只开开关而不配端点/模型时**记 WARN 并跳过该级**（绝不半配一个只会失败的链尾步）。
|
||||
- **内置工具新增 `image-crop`（v0.53）**：按区域裁切图片（参数 `image` + `x`/`y`/`width`/`height`，**0 基像素、区域须完整落在图内**）→ 返回 `{image:"data:image/png;base64,…", format:"image/png", width, height, region:{x,y,width,height}, source:{width,height}}`；用途是**上游可能压缩分辨率、大图细节会丢**，让模型自行裁出区域再交给 vision/OCR 工具精读（design/06 §3，裁决 14.4.5）。上限：源图 ≤50MiB、区域 ≤16MP、返回载荷 ≤8MiB（超出**报错**而非截断/降采样）；源可以是本地路径（走 file 工具同一沙箱）/ http(s) URL（同 SSRF 守卫）/ base64 data URI。**策略与其它工具一致**：`tool_policies` 无行时按最严默认 **owner-only**（群聊/陌生人的调用被策略层拒，见 §2 行 5）。
|
||||
|
||||
**安全 / 上下文环境变量（v0.56）**（`.env` / 环境变量；与 `.env.example` 逐键对齐）：
|
||||
|
||||
| 键 | 默认 | 语义 |
|
||||
|---|---|---|
|
||||
| `OWNER_IDENTITY_INJECTION` | `owner_only` | **主人身份说明书（`owner.yaml:identityFile`）注入范围**：`owner_only`（默认，**仅主人会话**，按**渠道层强类型 actor 元数据**判定）/ `always`（**所有会话**，含群聊与陌生人私聊，**仅本地自测/排障**——它显式开启红线例外）/ `off`（完全关闭，连主人会话也不注入）。取值**大小写不敏感、容忍首尾空白**；**非法值回退 `owner_only` 并记 WARN**（绝不静默放行、也绝不静默失效）。它只决定「那段知识进不进该会话的上下文」，**不参与任何身份/权限判定**（design/11 §0）：文件内容既不参与 `IsOwner`，也不改变授权。 |
|
||||
| `CONTEXT_MAX_TOKENS` | `32768` | **上下文溢出压缩预算**（token，离线估算；默认值与 `loop.DefaultMaxContextTokens` 同源，有测试锁死两者不许漂移）。会话估算上下文超过它时，更早的轮次被摘要成一条前导摘要消息，近期尾部（含尾部工具结果）原样保留；**`0` 或负数 = 关闭压缩**（行为与接线前一致）。 |
|
||||
| `GUARDRAIL_KEYWORDS` | 空 | **内容策略关键词表**（逗号分隔，大小写不敏感的子串匹配）。**留空 = 不挂关键词护栏**（项目不内置任何词表，只有你显式声明过的词才会被拦）。敏感信息（API key / bearer token / 密码 / 私钥）走**阻断档**、请求与响应各有长度上限——这两项是代码内定的安全默认值，**不对外开放配置**（`cmd/cyrene/wire_guardrail.go`）。 |
|
||||
|
||||
**管理面板写操作契约**（`POST/PUT/DELETE /api/v1/admin/*`，均 **owner-only**，读为 owner/admin；写操作经 audit 落 `audit_logs`；成功 `{data}` / 失败 `{error:{code,message}}`）：
|
||||
- `POST /admin/personas` body `{id,name,role,systemPrompt,characterRef?,modes?/mode?,memoryNamespace?,thinking?}` → `201 {data:PersonaSummary}`（**v0.43 起与读端点同形状：含 `mood` + `thinking?`**；注册进 persona registry + 持久化到 `configs/personas/<id>.yaml`）；id 已存在回 `409 duplicate`。**`systemPrompt` 自 v0.51 起必填**（落的 YAML 键是 `identity.systemPrompt`）：**缺失/空白 → `400 bad_request`**（消息 `"systemPrompt is required (identity.systemPrompt must not be empty)"`），**不再派生默认说明串**回落——载入期（`loader.Load`）执行同一规则，因此写出的 YAML 必能被重新载入。
|
||||
- `PUT /admin/personas/{id}` body 同上（不含 id）→ `200 {data:PersonaSummary}`（**v0.43 起与读端点同形状：含 `mood` + `thinking?`**，面板可直接用它回填）；不存在回 `404`。**`systemPrompt` 与创建同一把门**：v0.51 起同样必填，缺失/空白回 `400 bad_request`（同一条消息）——**不派生默认串、也不静默沿用旧值**，请求被拒即不落盘。
|
||||
@@ -299,13 +307,13 @@
|
||||
## 3. WebSocket `/ws/chat`（实时）
|
||||
|
||||
- **握手**: `ws://<host>:8080/ws/chat?token=<JWT>` 或 `Authorization: Bearer`；未认证在握手前回 `401` JSON。
|
||||
- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?, sessionId?}`（`turnId`/`seq` 为流式关联字段，见 §3.1；`sessionId` 为**会话持久化（design/16）新增**，能确定会话的事件带上，供客户端把该帧路由到**它自己那个会话**的消息桶（**v0.54 起：非激活会话的帧不再被丢弃**）；**v0.36 起结构化流帧 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*` 也带 `sessionId` + `turnId`**——多会话并发流式时客户端据此把 delta 落到各帧自身 `sessionId` 的消息桶，见 §3.1）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end`（以上模型流帧的 `data` 另带 `streamId`，v0.50）/ `tool_execution.start/update/end`（工具执行三事件，v0.50）/ `turn.start` / `turn.end`（回合边界帧，v0.50）（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood`(情绪变化，见 §3.7) / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event`(逐代理进度) / **`subagent_result`**(后台批次的最终结果，见 §3.10) / **`approval_notice`**(主代理代审小字，见 §3.11) / `graph_update` / **`message_persisted`**（会话持久化增量，见 §3.3）/ **`message_edited`**、**`message_deleted`**（消息编辑/删除增量，见 §3.8）/ **`session_read`**（已读游标推进，见 §3.9）/ **`observability_log`**、**`observability_trace`**、**`observability_metrics`**（可观测实时推送，见 §3.12，v0.55）。**会话编排状态（design/15，均为广播，`data.sessionId` 区分会话）**：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（见 §3.2）。语音回复走 `voice_output`（定向回请求连接，非广播）。
|
||||
- **下行帧的角色门（v0.48，design/11 §7.1）**: 下行帧按**类型**分两类，由后端**唯一一处**收口判定（**不在白名单里的帧默认只发 `owner` + `admin`**，fail-closed）：① **状态机信号**（白名单，**不含任何内容**）→ **所有已认证连接**（含 `viewer`）：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（§3.2）、`session_read`（§3.9）；② **其余全部** → **仅 `owner` + `admin`**：流式内容 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.start/update/end` / `turn.start` / `turn.end`（**v0.50 新增的这几种同属本档**——工具进度与回合边界对 `viewer` 也是内容相邻信息，fail-closed 默认即只发 owner+admin，未扩白名单）/ `stream_chunk` / `stream_end` / `thinking`（§3.1）、持久化 `message_persisted`（§3.3）/ `channel_persisted`（§3.4）/ `message_edited` / `message_deleted`（§3.8）、系统内部 `graph_update`（§3.5）/ `subagent_event` / **`subagent_result`（§3.10，v0.51 新增的这帧同属本档）** / **`approval_notice`（§3.11，v0.52 新增，同属本档）** / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`、私有状态 `mood`（§3.7）/ `device_update` / `reminder`、**可观测推送 `observability_log` / `observability_trace` / `observability_metrics`（§3.12，v0.55 新增，同属本档——未进 7 个状态机信号白名单，fail-closed 只发 owner+admin）**。
|
||||
- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?, sessionId?}`（`turnId`/`seq` 为流式关联字段，见 §3.1；`sessionId` 为**会话持久化（design/16）新增**，能确定会话的事件带上，供客户端把该帧路由到**它自己那个会话**的消息桶（**v0.54 起：非激活会话的帧不再被丢弃**）；**v0.36 起结构化流帧 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*` 也带 `sessionId` + `turnId`**——多会话并发流式时客户端据此把 delta 落到各帧自身 `sessionId` 的消息桶，见 §3.1）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end`（以上模型流帧的 `data` 另带 `streamId`，v0.50）/ `tool_execution.start/update/end`（工具执行三事件，v0.50）/ `turn.start` / `turn.end`（回合边界帧，v0.50）（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood`(情绪变化，见 §3.7) / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event`(逐代理进度) / **`subagent_result`**(后台批次的最终结果，见 §3.10) / **`approval_notice`**(主代理代审小字，见 §3.11) / `graph_update` / **`message_persisted`**（会话持久化增量，见 §3.3）/ **`message_edited`**、**`message_deleted`**（消息编辑/删除增量，见 §3.8）/ **`session_read`**（已读游标推进，见 §3.9）/ **`observability_log`**、**`observability_trace`**、**`observability_metrics`**（可观测实时推送，见 §3.12，v0.55）。**会话编排状态（design/15，均为广播，`data.sessionId` 区分会话）**：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（见 §3.2）、**`chat_duplicate`**（客户端幂等键重复到达的明确回执，v0.56 新增，见 §3.13）。语音回复走 `voice_output`（定向回请求连接，非广播）。
|
||||
- **下行帧的角色门（v0.48，design/11 §7.1）**: 下行帧按**类型**分两类，由后端**唯一一处**收口判定（**不在白名单里的帧默认只发 `owner` + `admin`**，fail-closed）：① **状态机信号**（白名单，**不含任何内容**）→ **所有已认证连接**（含 `viewer`）：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（§3.2）、`session_read`（§3.9）；② **其余全部** → **仅 `owner` + `admin`**：流式内容 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.start/update/end` / `turn.start` / `turn.end`（**v0.50 新增的这几种同属本档**——工具进度与回合边界对 `viewer` 也是内容相邻信息，fail-closed 默认即只发 owner+admin，未扩白名单）/ `stream_chunk` / `stream_end` / `thinking`（§3.1）、持久化 `message_persisted`（§3.3）/ `channel_persisted`（§3.4）/ `message_edited` / `message_deleted`（§3.8）、系统内部 `graph_update`（§3.5）/ `subagent_event` / **`subagent_result`（§3.10，v0.51 新增的这帧同属本档）** / **`approval_notice`（§3.11，v0.52 新增，同属本档）** / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`、私有状态 `mood`（§3.7）/ `device_update` / `reminder`、**可观测推送 `observability_log` / `observability_trace` / `observability_metrics`（§3.12，v0.55 新增，同属本档——未进 7 个状态机信号白名单，fail-closed 只发 owner+admin）**、**`chat_duplicate`（§3.13，v0.56 新增，同属本档——它虽由编排器状态通道下发，但未进那 7 个状态机信号白名单，故 fail-closed 只发 owner+admin）**。
|
||||
- **上行帧与握手回放的角色门（v0.49，design/11 §7.2）**: 与上面那条下行门**成对**，收的是同一个缺口的两处残余——① **客户端→服务端（上行）JSON 帧**：只有 `owner` / `admin` 连接可以发；非 `owner`/`admin`（即 `viewer`）连接发来的**任何**上行 JSON 帧都**默认被拒**，回复是**定向**（只回发送者）的 `{type:"error", data:{code:"forbidden"}}`，**不广播、不驱动模型、不落库、不返回任何内容**。被拒帧：`chat` / `interrupt` / `subagent_ask` / `task_output_query` / `voice_input` / `mode_switch`——**未登记的新上行帧同样默认拒**，要放行必须先在 design/11 §7.2 登记白名单（实现上那把「默认拒」也必须同步改为登记表，不能直接删）。② **握手 `history` 回放**：仅 `owner` + `admin` 连接收到；`viewer` 连接建立后**不收**回放。**协议级帧不受影响**：WS ping/pong 与正常 close 照常（否则连接会掉），被拒的上行帧也不会关掉连接。
|
||||
|
||||
> **这是「谁被主动推送」的门，不是数据可见性**：`viewer` 的 12 条只读监控端点（`viewerAuth`，v0.40）**照旧**（含 `GET /personas` 的角色级 `mood`）；`viewer` **仍可连** `/ws/chat`（连接鉴权不变），只是收不到第 ② 类帧。定向回请求连接的帧（`voice_output` 等）不受影响。**上一条的门只管「推给谁」；「谁能发、谁能拿回放」见上面 v0.49 那条**——`viewer` 连上后**发不出任何指令**、也**收不到 `history` 回放**。
|
||||
|
||||
> **`history` 回放事件（design/16，新增）**：WS 握手升级成功后、该连接下一帧即收到 `{type:"history", sessionId:"web", data:{messages:[{id,sessionId,role,content,mode?,mood?,image?,platform?,deviceId?,personaId?,createdAt}]}}`——回放主会话最新 50 条（`thinking` 已剥离；默认主会话，次级会话由客户端按激活会话走 `GET /sessions/{id}/messages` 拉取）。客户端据此在重连/新开连接后补全上下文。消息体含 `senderName?`（第三方昵称，design/16 §4.6，主人私聊为空）与 `personaId?`（v0.42，说话时的角色，design/22 §7-5，空 = 默认角色）。**角色门（v0.49，design/11 §7.2 A）**：这条回放**只发 `owner` + `admin` 连接**；`viewer` 连接建立后**不会**收到 `history` 帧（它若需要只读数据，走 §1 的只读 REST 端点）。
|
||||
> **`history` 回放事件（design/16，新增）**：WS 握手升级成功后、该连接下一帧即收到 `{type:"history", sessionId:"web", data:{messages:[{id,sessionId,role,content,mode?,mood?,image?,platform?,deviceId?,personaId?,clientMsgId?,createdAt}]}}`——回放主会话最新 50 条（`thinking` 已剥离；默认主会话，次级会话由客户端按激活会话走 `GET /sessions/{id}/messages` 拉取）。客户端据此在重连/新开连接后补全上下文。消息体含 `senderName?`（第三方昵称，design/16 §4.6，主人私聊为空）与 `personaId?`（v0.42，说话时的角色，design/22 §7-5，空 = 默认角色）。**角色门（v0.49，design/11 §7.2 A）**：这条回放**只发 `owner` + `admin` 连接**；`viewer` 连接建立后**不会**收到 `history` 帧（它若需要只读数据，走 §1 的只读 REST 端点）。
|
||||
|
||||
### 3.1 结构化流事件（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*` / `turn.start/end`）
|
||||
- **事件壳**：`{type, sessionId?, turnId?, seq?, data}`, `data` 为**类型化结构**（非 `any`）。`seq` 为 hub 级单调递增序号，供客户端将一次突发的流式事件排序关联。**`sessionId` 为事件所属会话、`turnId` 为该轮助手回合 id（均 v0.36 起带上）**：`sessionId` 由 loop 在回合边界注入（模型适配器在 loop 之下、不感知会话，恒留零值；loop 外无会话上下文的事件该字段为空），`turnId` 由网关每个回合新生成并挂进运行上下文——同一会话同时只有一个 in-flight 回合，故**同轮内所有帧的 `turnId` 一致**。客户端据此把 `message.delta` / `thinking.delta` / `tool_call.*` / `tool_execution.*` **路由到该帧自己 `sessionId` 的会话消息桶**（**v0.54 起：非激活会话的帧不再被丢弃**——后台会话的正文继续累积、切过去即可看到完整这一轮）；**只有「单槽忙态」**（`session_busy` / `session_idle` / `session_interrupted` 与 `stream_end` 的 `sessionBusy` 收口，见 §3.2）**仍按 `sessionId === activeSessionId` 判定**，以免别的会话的忙/闲帧串到屏幕上的会话。
|
||||
@@ -320,7 +328,12 @@
|
||||
- **向后兼容（v0.50 对 `tool_execution` 的替换说明）**：v0.49 及之前的单帧 `tool_execution.update {id,index,delta}`（`delta` 形如 `"start:工具名"` / `"end:error:工具名"` 的拼串）**不再由 loop 产生**——按旧拼串解析的客户端必须迁移到三事件（`tool_call.*` 帧形状不变）。`turn.start/end` 与各帧 `data` 里的 `streamId` 为纯新增键，老客户端按未知帧/未知键忽略即可。现有 Web 前端未消费这些新帧，行为不变。
|
||||
- **向后兼容**：未映射/无法确定的事件仍走 `stream_chunk` + `stream_end`（非流式回退路径）。
|
||||
- **上行（客户端→服务端）**: `mode_switch` / `chat`（跑 loop 并广播流式） / `voice_input` / `subagent_ask` / `task_output_query` / `interrupt`。
|
||||
- **`interrupt`**（上行，客户端→服务端）：`{sessionId}` → 会话编排器中断（design/15 §3）——取消该会话当前在跑的任务（context cancel）、清空其待处理队列、回 `session_interrupted`；用户说「停下/算了/换个话题」时发。命中空闲会话为 no-op。
|
||||
- **`interrupt`**（上行，客户端→服务端）：`{sessionId, scope?}`（**`scope` 为 v0.56/A2 新增**）→ 会话编排器中断（design/15 §3）——取消该会话当前在跑的任务（context cancel）并回 `session_interrupted`；用户说「停下/算了/换个话题」时发。**`scope` 取值域 `{"", "all", "current"}`**（**大小写敏感，只容忍首尾空白**）：
|
||||
- **省略 / 空串 / `"all"`**（三者同义）= 取消当前任务 **+ 清空待处理队列**，会话立即回到空闲（**逐字不变的现状语义**，老客户端只发 `{sessionId}` 的行为完全不变）；`session_interrupted.dropped` = 被清空的 pending 条数、`mode` = `idle`。
|
||||
- **`"current"`** = **只取消当前任务、保留待处理队列**：队列里的消息按编排器正常续跑规则继续执行（带上会话尾部上下文），一条都不丢；它**不递增代次**，因此被取消回合的结算仍属当代。此时 `dropped` 恒为 **`0`**，`mode` 如实报告该会话当时的**忙碌通道**（`thinking`/`executing`/`subagent`，**不是 `idle`**）。用途：客户端「打断」与「追加队列」是两种模式，若打断一律连队列清空，用户选「打断」时连发的多条消息会被静默丢弃、只剩一个 `dropped` 数字。
|
||||
- **其它取值** → **只回发送者** `{type:"error",data:{code:"bad_request"}}`（**定向**：不广播、**不打断任何会话**）；显式报错，绝不静默按默认执行（否则客户端以为队列保住了、实际被清空，正是 A2 要修掉的那类缺陷）。
|
||||
- 命中空闲会话为 no-op（两种 scope 都是）。
|
||||
- **`chat` 帧的 `clientMsgId`**（上行，v0.56/G4）：`{sessionId, text, image?, deviceId?, mode?, clientMsgId?}`——`clientMsgId` 为**客户端自带的幂等键**（可选）：同一会话内同一个非空值只承认第一条，重复到达**不落库、不起回合**，回新下行帧 **`chat_duplicate`**（§3.13）；省略 = 与加入该字段之前逐字相同。**REST `POST /api/v1/chat` 同名可选项语义相同**（重复回 `200 {data:{duplicate:true,messageId,sessionId}}`，见 §1 行 3）。
|
||||
- **`voice_input`**（上行，客户端→服务端）：`_{audio?, format?, text?, sessionId?, deviceId?}`。`audio` 为 base64（或 data: URI）音频，`format` 为其编码（`wav`/`mp3`/`ogg`）；`text` 为已转写文本时跳过 STT；`deviceId` 为**客户端具体端标识**（design/16 §4.5，如 `voiceassist:myapp:v1`，可选），随该语音轮次落库、聊天气泡可标注来源。服务端走 STT→agent 聊天→TTS（design/06 §1），回复经 `voice_output` 定向回该连接。**真 STT/TTS 已接通阿里百炼**（`DASHSCOPE_API_KEY` 必填：STT=`qwen-audio-3.0-asr-flash`、TTS=`cosyvoice-v3-flash`+`longxiaochun_v3`）；无凭据时后端走降级链（cloud → edge-tts/espeak（未实现）→ `silent` 空音频）。无注入语音服务时回 `error` 帧（`voice unavailable`）。
|
||||
- **`voice_output`**（下行，服务端→客户端）：`{audio, format, text, reply, provider?}`。`audio` 为 base64 合成音频，`format` 为其编码，`text` 为识别文本，`reply` 为助手回复文本；**当合成音频为空（silent 降级）时带 `provider`**（如 `"silent"`，非空音频省略）——客户端据此提示「没生成声音」，但该帧**仍照常发出、不算业务错误**。
|
||||
- **向后兼容**：未映射/无法确定的事件仍走 `stream_chunk` + `stream_end`（非流式回退路径）。
|
||||
@@ -335,20 +348,20 @@
|
||||
- **`pending_ack`**：忙时新消息已入队（`{sessionId, mode, queueDepth}`）——「收到，稍后回」。
|
||||
- **`pending_drain`**：忙完开始消费下一待处理消息（`{sessionId, mode, queueDepth}`）。
|
||||
- **`session_idle`**：会话回到空闲、队列清空（`{sessionId, mode}`）。
|
||||
- **`session_interrupted`**：用户 `interrupt` 中断，当前任务取消、pending 清空（`{sessionId, mode, dropped}`）。
|
||||
- **`session_interrupted`**：用户 `interrupt` 中断（`{sessionId, mode, dropped}`）——**帧形状零变化**，语义随 `scope`（v0.56/A2）：`scope:"all"`（省略 / 空串同义）= 当前任务取消、pending 清空，此时 `mode = idle`、`dropped` = 被清空的 pending 条数；**`scope:"current"` = 只取消当前任务、pending 保留**，此时 `dropped` 恒为 **`0`**、`mode` 为该会话当时的**忙碌通道**（`thinking`/`executing`/`subagent`，**非 `idle`**）。`dropped` 恒等于**真的被丢弃**的条数（绝不把「保留」报成丢弃）。
|
||||
- **`pending_full`**：单会话 pending 达上限（默认 5）拒绝入队（`{sessionId, mode, max}`）——防无限积压（design/15 §4）。
|
||||
- **上下文续接**：忙完重开时新回合**带上一轮上下文**（`{mode, queueDepth}` 之外的续接由服务端完成），非清空重来（design/15 §2.2）。
|
||||
- **客户端侧（v0.54）**：`sessionBusy` / `pendingCount` 是**单槽全局**状态（不按会话分桶）——前端只在帧的 `sessionId === activeSessionId` 时置忙/置闲（`frontend/web/src/lib/ws/handlers/session.ts`，置忙与置闲两侧同一把尺子），与「消息按自己的 `sessionId` 入桶、非激活会话不丢弃」不同（见 §3.1）。这是 `design/16 §4.2` 已登记的**单槽债**（多会话并发时忙态徽标只反映屏幕上的会话）。
|
||||
|
||||
### 3.3 消息持久化增量事件（`message_persisted`，design/16）
|
||||
- **触发**：每一条 user / assistant 消息**落库后**由编排层广播——Web 主会话路径走 `persistUserMessages`/`persistAssistantReply`，**IM 渠道主人私聊**（design/16 §4.4）由 channelbridge 把消息**落主会话 `web`**（带 `platform` 标记）后复用**同一** `message_persisted` 广播（同一 hub 的 `BroadcastPersisted`），保证 Web 端实时镜像 IM 消息。
|
||||
- **载荷**：`{type:"message_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, mood?, image?, platform?, deviceId?, senderName?, personaId?, createdAt}}}`——`role` ∈ `user|assistant`；`id` 为**后端生成的消息 id**（客户端据此去重）；`platform` 为**来源平台**（`web` 或渠道如 `telegram`/`weixin-ilink`/`qq-obv11`）；`deviceId` 为**具体端/客户端标识**（design/16 §4.5，如 `web:chrome:a1b2c3` / `weixin-ilink:conf0:wx_uid`）；`senderName` 为**第三方发送者昵称**（design/16 §4.6，群聊/陌生人消息带，主人私聊为空，`omitempty`）；**`personaId`（v0.42，`omitempty`）=该消息说话时的角色 id**（design/22 §7-5；空 = 全局默认角色，即升级前的全部历史），客户端据此按角色渲染名字/头像；`thinking` 已剥离（design/16 §6）。
|
||||
- **载荷**：`{type:"message_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, mood?, image?, platform?, deviceId?, senderName?, personaId?, createdAt}}}`——`role` ∈ `user|assistant`；`id` 为**后端生成的消息 id**（客户端据此去重）；`platform` 为**来源平台**（`web` 或渠道如 `telegram`/`weixin-ilink`/`qq-obv11`）；`deviceId` 为**具体端/客户端标识**（design/16 §4.5，如 `web:chrome:a1b2c3` / `weixin-ilink:conf0:wx_uid`）；`senderName` 为**第三方发送者昵称**（design/16 §4.6，群聊/陌生人消息带，主人私聊为空，`omitempty`）；**`personaId`（v0.42，`omitempty`）=该消息说话时的角色 id**（design/22 §7-5；空 = 全局默认角色，即升级前的全部历史），客户端据此按角色渲染名字/头像；**`clientMsgId`（v0.56，`omitempty`，G4）= 客户端自带的幂等键**（空 = 该消息没有幂等键：老客户端、IM 镜像、历史行），客户端据此把本地乐观气泡对齐到服务端真相；`thinking` 已剥离（design/16 §6）。
|
||||
- **注：群聊/陌生人（非主人）消息**只在**该 IM 适配器日志界面**以消息流显示，**不**经 `message_persisted` 进 Web 主会话（design/16 §4.6 §3-4）；该日志流由 `GET /api/v1/admin/channels/{platform}/messages` 拉取，落库后另经 `channel_persisted`（§3.4）实时推送。
|
||||
- **客户端处理**：把帧按 `data.message.sessionId`（缺省时用帧壳 `sessionId`）写进**该会话自己的消息桶**（**v0.54 起：非激活会话的消息不再被丢弃**，切过去即可见，见 §3.1）；按 `id` upsert——本端已预建的**同 role 乐观气泡**（本地 `uid` 无后端 `id`）被**归一**（`uid` → 后端 `id`），异端无本地气泡则直接追加，两者最终收敛为**同一条 `id` 相同的消息**，「A 发消息、A 与 B 都无需刷新且各出现一次」。
|
||||
|
||||
### 3.4 适配器消息实时事件（`channel_persisted`，design/16）
|
||||
- **触发**：每一条**群聊/陌生人（非主人 / 隔离 sess-xxx）消息**落库后由 channelbridge `persistIsolated` 广播；该消息**只写自己的隔离会话**，**绝不**写主会话 `web`，`channel_persisted` 仅是事件通知，不是把内容塞进主会话/Web 上下文（design/16 §4.6 §3-4）。
|
||||
- **载荷**：`{type:"channel_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, platform?, deviceId?, adapterId?, senderName?, createdAt}}}`——与 `historyMessage` wire 一致；`adapterId` 为**产生该消息的适配器注册名**（如 `kook:3bef...`，`adapter != ''`）；`sessionId` 为隔离会话 id（`sess-xxx`，**非** `web`）；`role` ∈ `user|assistant`；`senderName` 为第三方昵称。
|
||||
- **载荷**：`{type:"channel_persisted", sessionId, data:{message:{id, sessionId, role, content, mode?, platform?, deviceId?, adapterId?, senderName?, createdAt}}}`——与 `historyMessage` wire 一致；`adapterId` 为**产生该消息的适配器注册名**（如 `kook:3bef...`，`adapter != ''`）；`sessionId` 为隔离会话 id（`sess-xxx`，**非** `web`）；`role` ∈ `user|assistant`；`senderName` 为第三方昵称；**`clientMsgId`（v0.56，`omitempty`，G4）= 客户端自带的幂等键**（空 = 无幂等键，如渠道入站消息）。
|
||||
- **事件类型分流**（`BroadcastPersisted` 按 `sessionId` 分流）：`sessionId == "web"` 或其 `web:<uuid>` 前缀 → **`message_persisted`**（Web 聊天实时同步）；**其它**（隔离 `sess-xxx`）→ **`channel_persisted`**（适配器日志专用）。
|
||||
- **客户端处理**：Web 聊天**无** `channel_persisted` handler，天然忽略、不进会话；**IM 适配器日志页**订阅该事件，按 `adapterId === 当前适配器`（或总览 `adapterId != ''`）过滤后**仅追加**（按 `id` 去重、不整页重载），首次拉取仍由 `GET /api/v1/admin/channels/messages` + 轮询兜底。
|
||||
|
||||
@@ -446,6 +459,18 @@
|
||||
- **前端落点**：`frontend/web/src/lib/ws.ts` 的 `subscribeObservabilityFrames()`（帧**不进应用 store**，只有打开着面板的视图在听，其余时候安静丢弃）；面板挂载时各读一次对应 REST 作为引导（logs 用 `limit=200`），推送帧**按业务键去重合并、倒序、窗口 200**（`frontend/web/src/admin/modules/observabilityStream.ts`）。
|
||||
- **向后兼容**：纯新增帧，老客户端按未知帧忽略即可；既有 REST 与其它帧/端点/鉴权一律不变。
|
||||
|
||||
### 3.13 客户端幂等回执（`chat_duplicate`，v0.56 / 协同 G4）
|
||||
|
||||
> **角色门**：`chat_duplicate` **不在** `frameReachesAll` 的 7 个状态机信号白名单里 ⇒ fail-closed **只发 `owner` + `admin`**（`viewer` 收不到）。它由编排器的状态通道（与 `session_busy` 等同一出口）下发，因此**帧壳带 `sessionId`，没有 `turnId` / `seq`**。
|
||||
|
||||
- **触发**：`chat` 上行（REST `POST /api/v1/chat` 或 WS `chat` 帧）带了**非空** `clientMsgId`，而同一会话内**已经认领过同一个值**——即弱网 / 切后台下的客户端超时重发。判重由 `(session_id, client_msg_id)` 的**部分唯一索引**原子裁决（只覆盖非空键），因此并发重发只有一个赢家，不存在「先查再插」的竞态窗口。
|
||||
- **载荷**：`{type:"chat_duplicate", sessionId, data:{sessionId, clientMsgId, messageId}}`——`messageId` = **既有那条用户消息的 id**（客户端据此把本地乐观气泡对齐到服务端真相，替代「靠文本相等」的脆弱匹配）。它是**广播给所有 `owner` / `admin` 连接**的状态信号（hub 无按会话订阅），没发过该 `clientMsgId` 的客户端按值自行忽略即可。
|
||||
- **不做什么（红线）**：重复到达**不落库、不起回合、不发任何内容 / 流式新帧**——第二次绝不产生第二条用户消息、第二个模型调用。
|
||||
- **REST 侧同义**：`POST /api/v1/chat` 的**同步**与 **`stream:true`** 两条路径重复到达都回 `200 {data:{duplicate:true,messageId,sessionId}}`（见 §1 行 3）。
|
||||
- **回填与可见性**：`clientMsgId` 随消息落库并**回填进消息 DTO** ⇒ `message_persisted`（§3.3）/ `channel_persisted`（§3.4）/ 握手 `history` 回放 / `GET /sessions/{id}/messages`（§1 行 6）都能看到（**空则省略**），客户端可在重连后从读接口收敛本地乐观消息。
|
||||
- **向后兼容**：上行 `clientMsgId` 是**可选**字段——**省略时行为与加入该字段之前逐字相同**（老客户端零影响，历史行该键为空）；`chat_duplicate` 为**纯新增帧**，老客户端按未知帧忽略即可。
|
||||
- **迁移**：新增 `0013_chat_client_msg_id`（up：`ALTER TABLE chat_messages ADD COLUMN client_msg_id TEXT NOT NULL DEFAULT ''` + 部分唯一索引 `idx_chat_messages_client_msg_id ON chat_messages (session_id, client_msg_id) WHERE client_msg_id != ''`；down：**先删索引再删列**——SQLite 的 `DROP COLUMN` 在列仍被索引引用时会失败；全新库由 `history.NewStore` 幂等前滚同一列与索引）。
|
||||
|
||||
## 4. 客户端接入指引（Web / 移动 / 原生 / IM bridge 通用）
|
||||
|
||||
### 4.1 一次性接入流程（三步走）
|
||||
@@ -471,7 +496,8 @@
|
||||
- 返回**按时间倒序**，需 `reverse()` 成旧→新用于渲染。
|
||||
- **编辑 / 删除单条消息**：`PATCH /api/v1/messages/{id}` `{content}`（≤4000 rune）→ `{data:<消息DTO>}`（裸 DTO，无 `message` 包裹）；`DELETE /api/v1/messages/{id}` → `{data:{deleted:<id>}}`。不存在回 `404`。**重发**用「编辑后内容再 `POST /chat`」即可（无独立重发端点）。两者成功后都会广播（`message_edited` / `message_deleted`，§3.8），同账号其它端**免刷新**同步。
|
||||
- **实时增量**：连接 WS 后，消息落库会广播 `message_persisted`（§3.3）——**用其中的 `id` 去重**，按 `sessionId` 写进该会话自己的桶（**v0.54 起非激活会话的帧不再丢弃**）；新开/重连连接首帧即 `history` 回放（主会话最近 50 条）。**消息被编辑/删除**则分别广播 `message_edited` / `message_deleted`（§3.8）——同一 `sessionId` 路由规则，前者按 `id` 原位改 `content`、后者按 `id` 移除，都不需要重拉整页。
|
||||
- **发消息**：`POST /api/v1/chat` `{text, deviceId?, image?, stream:true}`。`stream:true` 走 WS 流式；非流式返回完整 `reply`（会话正忙时 `202 queued`、排队满 `409 chat_busy`，见 §3.2）。
|
||||
- **发消息**：`POST /api/v1/chat` `{text, deviceId?, image?, mode?, clientMsgId?, stream?}`。`stream:true` **直达会话编排器**（v0.56/G2）：受理成功后才回 `200 {stream:true}`；会话正忙已续接排队 `202 {stream:true,queued:true,queueDepth}`、队列满 `409 chat_busy`、**未接 loop `500 chat_unavailable`**、仅未接编排器时的兜底派发失败 `503 chat_dispatch_failed`。非流式返回完整 `reply`（会话正忙时 `202 {queued:true,queueDepth}`、排队满 `409 chat_busy`，见 §3.2）。`image` 解码后上限 **5 MiB**（超限 `400 image_too_large`，文案指路 `POST /api/v1/upload`）；**WS `chat` 帧受 4096 字节读上限约束**（超限断连），故 WS 上发大图必须走「上传 → URL」。
|
||||
- **幂等发送（v0.56/G4）**：给自己生成的每条消息带一个**非空** `clientMsgId`（如本地乐观气泡的本地 id），服务端在同一会话内只承认第一条：重复（超时重发 / 切后台重发）**不再落库、不再起回合**——WS 回 `chat_duplicate`（§3.13）、REST 回 `200 {data:{duplicate:true,messageId,sessionId}}`；该键也会**回填进消息 DTO**，供重连后对齐本地气泡。**省略它 = 老行为逐字不变**。
|
||||
|
||||
### 4.3 deviceId 与 platform 规范（design/16 §4.4-4.5）
|
||||
- **`platform`**（来源平台）：`web` / 渠道如 `telegram`、`weixin-ilink`、`qq-obv11`。Web 端恒 `web`；IM 渠道消息带各自平台。**同一平台多个端 → 相同 platform、不同 deviceId。**
|
||||
@@ -490,6 +516,7 @@
|
||||
- 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。
|
||||
|
||||
## 5. 变更记录
|
||||
- `v0.56`（**契约债一次补齐（协同项 A2 / G1 / G2 / G3 / G4 / F3）：`interrupt` 支持 `scope` + REST `stream:true` 不再静默失败 + `chat.image` 上限 + `clientMsgId` 幂等 + 视觉链路 URL 取回事实 + 既有错误陈述修正**，依据 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 A2 / G1 / G2 / G3 / G4 / F3（commit `7512d59` 等），2026-10-04 落实）。**A. `interrupt` 支持 `scope`（A2，纯新增可选字段）**——上行 `interrupt` 由 `{sessionId}` 扩为 `{sessionId, scope?}`，取值域 `{"", "all", "current"}`（省略 / 空串 / `"all"` **三者同义**，= 现状语义：取消在跑回合 + **清空**待处理队列；老客户端只发 `{sessionId}` 的行为**逐字不变**）。**新增 `"current"` = 只取消在跑回合、保留待处理队列**，队列消息按编排器正常续跑规则继续执行（带上会话尾部上下文）——修的是「客户端『打断』与『追加队列』两种模式被后端当成一种」：打断一律连队列清空时，用户选「打断」后连发的多条消息会被**静默丢弃**，只剩一个 `dropped` 数字。**其余取值 → 定向回** `{type:"error",data:{code:"bad_request"}}`（只回发送者，**不广播、不打断任何会话**），显式报错而绝不静默按默认执行。**下行 `session_interrupted` 帧形状零变化**（`{sessionId, mode, dropped}`），语义改为「如实上报」：`dropped` 恒等于**真的被丢弃**的待处理条数（`scope:"current"` 时为 `0`），且该档 `mode` 为会话当时的**忙碌通道**（`thinking|executing|subagent`，**不是 `idle`**）。实现落点 `internal/services/gateway/session_interrupt.go`（`InterruptScope` / `InterruptScope()`，从编排器主文件拆出以守住 ≤500 行）与 `ws_hub_turn.go` 的 `interruptRequest.Scope` + `parseInterruptScope`（**大小写敏感**、只容忍首尾空白）。**B. REST `stream:true` 不再静默失败（G2，行为变更，客户端必读）**——见 §1 行 3 与 §4.2：该分支改为与 WS `chat` 帧**同一条直达编排器的路径**（design/15 §2.1「会话消息不得被 drop」）。**响应面**：受理成功后才回 `200 {data:{stream:true}}`；正忙已续接 `202 {data:{stream:true,queued:true,queueDepth}}`；队列满 `409 {error:{code:"chat_busy"}}`；幂等键重复 `200 {data:{duplicate:true,messageId,sessionId}}`；**未接 loop 由 `200 {stream:true}` 改为 `500 {error:{code:"chat_unavailable"}}`**（与同步路径同口径）；仅**未接编排器**时回退总线派发，其失败回 `503 {error:{code:"chat_dispatch_failed"}}`（修复前 `Publish` 的错误被吞掉、且传的是**请求作用域** ctx）。**`202` / `409` 从此真的会出现**（修复前因「先 return 200」永不出现）。派发用的回合上下文与请求作用域脱钩（`context.WithoutCancel` + 30 分钟上限），回合不会在客户端刚收到 200 时被连带取消。**兼容性**：`stream:false` 与既有响应形状**一字未动**；**依赖「任何情况都拿到 200」的客户端必须按上表分支**。**C. `chat.image` 上限（G3，纯新增校验）**——`POST /api/v1/chat` 的 `image` 新增硬上限：**解码后 5 MiB**（与 `POST /api/v1/upload` 同口径；base64 字符串上限 = `ceil(n/3)*4 + 64` 字符，覆盖 data: URI 前缀余量），超限 → `400 {error:{code:"image_too_large", message}}`（文案指路 `POST /api/v1/upload`），在**任何解码 / 落库 / 入模型之前**拦下（超大 base64 因此不进历史、也不会被重连回放重传；校验按**字符串长度**做——入口层唯一零分配的一步，先拦再接）。**事实（诚实边界）**：**WS `chat` 帧到不了这条 400**——WS 读上限 `wsReadLimit = 4096` 字节/帧，超限由传输层直接断连 ⇒ **WS 上发真实图片本就必须「上传 + URL」**（图片有「上传」与「内联」两条入口，两边给出同一个「一张图能有多大」的答案）。**D. `clientMsgId` 幂等（G4，纯新增可选字段 + 纯新增帧）**——见 §3.13：上行新增**可选** `clientMsgId`（REST `chat` 体与 WS `chat` 帧都支持），同一会话内同一非空值只承认第一条；重复到达 REST 回 `200 {data:{duplicate:true,messageId,sessionId}}`、WS 回**新下行帧 `chat_duplicate`**（`{type:"chat_duplicate", sessionId, data:{sessionId, clientMsgId, messageId}}`，**未进 7 个状态机信号白名单 ⇒ fail-closed 只发 `owner` + `admin`**），且**不落库、不起回合、不发任何内容 / 流式帧**。判重由 `(session_id, client_msg_id)` 的**部分唯一索引**（`WHERE client_msg_id != ''`，空键刻意排除在外——否则同一会话第二条空键消息就会撞唯一约束）**原子裁决**，并发重发只有一个赢家；非空键的写入走 `ON CONFLICT DO NOTHING`。`clientMsgId` 另**回填进消息 DTO** ⇒ `message_persisted` / `channel_persisted` / 握手 `hisLine truncated
|
||||
- `v0.55`（**阶段 7 落地项登记：路径式安全入口 + 数据目录 `platform` + OneBot v11 四端 + 可观测实时推送**，依据裁决 1.6 / 16.4.7 / 12.4.2（commit `a398dc9`）、1.4 / 12.4.1（commit `9253fef`）、05.4.3 + 16.4.3-WS（commit `0e1f163`），以及 13.4.5 面内三条（commit `74b12d8`）、MCP 官方 SDK（commit `a1083a3`），2026-10-04 落实；**本版全部是已实现并已推库行为的登记，无新代码**）。**A. 安全入口（`ADMIN_PATH`，裁决 1.6 / 16.4.7，**前端路由面——不是 REST 契约**）**——① **新增 env `ADMIN_PATH`**（默认 `admin`）：面板前端路由前缀 = `/` + 值（`admin` → `/admin`；`xxx/admin` → `/xxx/admin`）；**非法值回退 `/admin`**——容忍首尾斜杠与空白，拒绝空段、`.`/`..` 段与含 `?`/`#` 的段（宁可挂回默认，也不挂到不可预测的路径上）。② **HTTP 行为**：`/<ADMIN_PATH>` 与其深链（`/<前缀>/<section>`）返回**注入了 `<base href="/">` 与 `window.__CYRENE_ADMIN_ENTRY__={"prefix":"..."}` 的 index.html**（`Cache-Control: no-store`；`<base href="/">` 必在资源引用之前，否则多段前缀/深链下 Vite 的 `./assets/...` 会解析到错误目录）；**形如面板入口但前缀不符的路径 → `404`**（判定 = 路径里出现 `admin` 段；既不回落用户端聊天壳、也不回显正确前缀）；`/<ADMIN_PATH>` 若**恰好命中 `dist` 真实文件**则仍走文件服务器（面板入口页绝不顶掉 SPA 资源）。③ **API 不藏**：`/api/v1/*`、`/api/v1/admin/*`、`/ws/chat`、webhook 一律原样——**无新端点、无帧变更**，安全靠 JWT + 角色门（design/07 §0.1）。④ **口径**：**用户端 HTML 永不携带该前缀串**（后端只在命中前缀时注入）⇒ 用户端既无管理入口链接、也解析不出面板路由（design/07 §0.2）。前端路由随之改**路径式**（`frontend/web/src/admin/router.ts` 只读注入、**无硬编兜底**、移除 hash 入口；模块切换走 history）。**B. 数据目录（同 commit，裁决 12.4.2）**——`DATA_DIR` 新增可接受值 **`platform`**（大小写不敏感）→ 平台标准数据目录（Windows `%APPDATA%\Cyrene`、macOS `~/Library/Application Support/Cyrene`、Linux `~/.local/share/cyrene`）；**默认 `./data` 与显式路径行为不变**；**显式空值行为不变**（仍走组合根原兜底，避免正在运行的实例突然换库）。**C. OneBot v11 四端（`9253fef`，裁决 1.4 / 12.4.1）**——① **配置面**（channels.json 账号 `config` + 适配器 `Config()` 快照）新增：`transport`（`ws`|`http`，默认 `ws`；**未知值一律回落 `ws`**，绝不静默改走 HTTP）、`api_base_url`（OneBot HTTP API 基址，必须显式给出——**不从 `remoteURL` 推导**，v1 那种「剥掉最后一段路径」的推导是有损的）、`report_path`（默认 `/`，无前导 `/` 时补齐）；快照里 camelCase 为 `transport` / `apiBaseURL` / `reportPath`；`remoteURL` 快照值 = `remote_url`、为空时回落 `api_base_url`（语义即「**出站远端地址**」）。**既有键与值不变**——不给出任何新配置时行为与改造前逐字节一致（`transport=ws`、`mode=server`）。② **env 兜底**：`CHANNEL_QQ_OBV11_TRANSPORT`（默认 `ws`）/ `CHANNEL_QQ_OBV11_API_BASE_URL` / `CHANNEL_QQ_OBV11_REPORT_PATH`。③ **四端语义（谁向谁发数据）**：`ws+client` Cyrene 拨号 OneBot、收发同一 WS；`ws+server` OneBot 反连 Cyrene、收发同一 WS；`http+client` Cyrene→OneBot（`POST {api_base_url}/{action}`、等响应、按 `retcode` 判成败，**纯出站**、无长连接、token 只走 `Authorization: Bearer`）；`http+server` OneBot→Cyrene（POST 到 `listen_addr` + `report_path`，**纯入站**；**fail-closed 鉴权**——配了 `access_token` 时 `Authorization: Bearer` 或 `?access_token=` 不匹配回 `403`，`access_token` 为空则放行，与既有 `ws+server` 同口径）、**10MiB 请求体上限**（超出 `413`）、方法非 `POST` 回 `405`、成功回 `204`。④ **关键取舍**：`mode` 决定**哪一半必需**（server 必需 `listen_addr`、client 必需 `api_base_url`），另一半只要给齐字段就**一并启用** ⇒ **单个适配器即可完成「收上报 + 回消息」闭环**，四端仍各自可独立选择与测试；任一端配置有误即 `Connect` 失败（先做纯配置校验并构造出站客户端，再绑监听端口），**绝不留下半开的端口**。⑤ **端口例外**：`http+server` 会用 `listen_addr`，属 `AGENTS.md` §9 已登记的**同一豁免**（design/13 §0 原文即写「WS server / HTTP server」）；`listen_addr` 为空则报错、**绝不开端口**（无默认值）。⑥ **未接**：`get_group_list` 枚举（后续）。**D. 可观测实时推送（`0e1f163`，裁决 05.4.3 + 16.4.3-WS）——新增 §3.12**：日志 / 指标 / trace 从「面板 1s 轮询 REST」改为 **WS Line truncated
|
||||
|
||||
- `v0.54`（**契约债一次补齐：渠道配置写路径改 patch 语义（修 P0 级凭据静默丢失） + 阶段 6 前端批登记 + 三处过时陈述修正**，依据 design/04 §3.1、design/22 §2 方案 b 与裁决 16.4.1 / 16.4.2 / 16.4.3 / 16.4.4 / 16.4.5 / 16.4.6；commit `4ae7148` / `f454273` / `b480b04` / `c1a98d7` / `8d70f6d`，2026-10-04 落实）。**A. 渠道配置写路径由「整条替换」改为「按 id 打补丁」（P0 级数据安全，破坏性语义变更）**——① **语义变更**：`PUT /api/v1/admin/channels/{platform}/config` 的 `config` 从「整条替换该账号配置」改为「**按 id 打补丁**」（`runtimeconfig.PatchChannel`，**与 `personaId` 同构的三态**）：**键省略（该键不在 `config` 里，或 `config` 整体缺席 / 为 `null`）= 保留该账号已存值**、**给出非空值 = 覆盖该键**、**显式 `null` 或 `""` = 清除该键**（适配器回落零值；`0` / `false` 是真实取值，**不算空**）。**破坏性提示**：按旧文实现、依赖「省略某 `config` 键 = 删掉它」的客户端，**必须改为显式传 `null` / `""`** 才能清除该键。② **修掉的数据安全问题**：面板只发送用户本次**碰过**的平台字段，后端却整条替换 ⇒ ⓐ 保存**微信(iLink)**账号卡会抹掉 `bot_token` / `bot_id` / `owner_id` / `get_updates_buf`（**iLink token 是长期凭据**，被抹掉即掉线且不可恢复）；ⓑ **Telegram** 只填 `webhook_url` 而不重填 token ⇒ `bot_token` 变空 ⇒ `cleanAccounts` **丢掉整个账号**。两条在修复前都是「面板保存成功、盘上凭据没了」的静默丢失。③ **保留清除能力**：显式 `null` / `""` 仍能真正删除该键，未触碰的兄弟键不受影响。④ **未改**：token 要求型平台（kook / telegram）上**显式**清 `bot_token` 仍按 `cleanAccounts` 丢掉该账号（明确要求清除凭据，不是误删）；「本次请求一个 `config` 键都没给出」在**非 `weixin-ilink`** 平台仍回 `400`（`weixin-ilink` 豁免以便先建账号再扫码）。⑤ **无新端点 / 新字段 / 响应形状变更**：请求体与 `201 {data:{persisted,path,platform,accountId}}` 一字未动，只有 `config` 的解释规则变了；`allowGroups` / `denyGroups` / `allowUsers` / `denyUsers` 与 `groupMsgPerMin` / `msgPerMin` / `maxMessages` **仍是整值替换**（省略 = 清空，客户端须回传完整列表 / 非零值）。⑥ **实现落点**：`internal/config/runtimeconfig/channels.go` 新增 `PatchChannel` / `mergeChannelConfig` / `isEmptyConfigValue`；`internal/services/gateway/admin_write_channel_config.go` 的 `adminSaveChannelConfig` 改调 `PatchChannel`（`channelConfigFromRequest` 返回**补丁**而非完整配置）。**验证**：`go test ./internal/services/gateway/ -run TestAdminSaveChannelConfigKeeps -v`（微信 iLink 凭据保留 / 空补丁三形态 / Telegram 账号存活 / 显式清除 / 无基线新建）+ `go test ./internal/config/... -run TestPatchChannel -v`；**变异验证 3 条**——把写路径改回**整条替换**（旧 upsert 语义）后，「省略键保留」「Telegram 账号存活」「空补丁不改凭据」三类断言**精确复现** `bot_token` / `get_updates_buf` 被抹掉与账号被 `cleanAccounts` 删掉的旧缺陷 ⇒ 变异必红。**B. 阶段 6 前端批（纯前端行为，无 API 变化）**——① **16.4.1 静默 / 活动态与预约切换**（`f454273`，帧缺口补 `b480b04`）：输入模式切换的唯一入口 `frontend/web/src/components/modeSwitch.ts`——**她活动**（`sessionBusy || 屏上 streaming || sending`）时用户切换只登记「**已预约**」（不改当前模式、不上行、不清除既有预约），**她静默**时立即生效并上行 `mode_switch`；提前切 → **下次静默态落地**（徽章「已预约 · X（她静默后生效）」）；预约状态**纯前端**、不进后端契约。② **16.4.5 会话级消息缓存**（`b480b04`）：**帧按自己的 `sessionId` 落进该会话的消息桶**（新增 `frontend/web/src/store/sessionCache.ts` 纯函数 + `useAppStore.sessionMessages`），**切会话「存回 / 取出」不再清空**、非激活会话的帧**不再被丢弃**；**只有「单槽忙态」**（`session_busy` / `session_idle` / `session_interrupted` / `stream_end` 的 `sessionBusy` 收口）仍按激活会话判定（见 §3.1 / §3.2）。③ **16.4.2 导图口径**（`b480b04`）：`graph_update` 按 `data.sessionId` 入**图桶**（上限 12 张）——管理端 Flow / Agents 页取**激活会话**的图、**Backthink 页取 `sess-backthink`** 的图，后台思考图不再顶掉「当前会话」图（见 §3.5）。④ **16.4.3 / 16.4.6 虚拟滚动与专属页只读卡**（`c1a98d7`）：管理端长列表超过阈值走**窗口化**（`AdminTable` / 新增可复用 `VirtualList` / 适配器消息日志，DOM 行数与数据量解耦）；专属页**只读展示该平台Line truncated
|
||||
|
||||
+26
-14
@@ -1,6 +1,6 @@
|
||||
# Cyrene v2 后端 API 参考（api-reference.md）
|
||||
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.55`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.56`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。
|
||||
> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**仍未登记的端点 / WS 事件清单见 `DevDocs/audit/00-总览.md` §4④**，属后续「文档补全」批次，本文件暂不补全。
|
||||
> **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。
|
||||
@@ -14,7 +14,7 @@
|
||||
- **响应统一信封**：
|
||||
- 成功：`{"data": <payload>}`（HTTP 200 / 201 / 202 / 204）。
|
||||
- 失败：`{"error": {"code": <string>, "message": <string>}}`（HTTP 400/401/403/404/409/500/501 等）。
|
||||
- **错误码**：业务错误带稳定字符串 `code`（如 `unauthorized` / `not_found` / `bad_request` / `chat_busy` / `not_implemented`），便于客户端分支；`message` 面向人读。
|
||||
- **错误码**：业务错误带稳定字符串 `code`（如 `unauthorized` / `not_found` / `bad_request` / `chat_busy` / `not_implemented`，以及 **v0.56** 新增的 `image_too_large`（`chat.image` 超 5 MiB）与 `chat_dispatch_failed`（流式兜底派发失败）），便于客户端分支；`message` 面向人读。
|
||||
- **CORS**：`Access-Control-Allow-Origin` 为配置的 `ALLOWED_ORIGINS` 白名单（`*` 时放开）；`Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`；`Allow-Headers: Authorization, Content-Type, X-API-Version`；`Access-Control-Expose-Headers: X-Voice-Provider`（跨域浏览器可读语音降级信号头）；`Max-Age: 600`。`OPTIONS` 预检直接回 `204`。同源/无 Origin 请求放行。**注意：`X-API-Version` 仅作**advisory**惯例头（见 §0.2）——CORS 已放行但它**不参与服务端版本协商**，服务端当前不校验、不据此改变行为。**
|
||||
- **请求日志**：每个请求由 `logging` 中间件记录一行（method/path/status/duration_ms），并计入可观测性指标。panic 由 `recover` 中间件兜底为 `500 {error:{code:internal,...}}`，不崩溃进程。
|
||||
- **超时**：WS 连接 ping 周期 54s、pong 等待 60s、写超时 10s；读上限 4096 字节/帧。
|
||||
@@ -45,7 +45,7 @@
|
||||
|
||||
### 0.3 上传 / 媒体（重要确认）
|
||||
|
||||
- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。
|
||||
- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/<name>`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。**内联上限（v0.56）**：`chat.image` 解码后 **5 MiB**（字符串上限 `ceil(n/3)*4 + 64`），超限 `400 {"error":{"code":"image_too_large",...}}`；WS `chat` 帧受 4096 字节读上限约束（超限断连），故 WS 发大图必须走「上传 → URL」。**视觉链路的 URL 取回（v0.56，实现事实）**：`chat.image` 的 http(s) URL（含 `/api/v1/files/<name>`）由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再把 URL 原样转给上游**（同源 upload 产物优先走**本地文件读取**，`vision.WithUploadsDir`；取回沿用 http/https 白名单 + 50MiB 上限 + 取回超时）。**类型裁决（同一批实现事实）**：**字节嗅探是唯一裁决权**——按真实字节判白名单光栅图（png/jpeg/gif/webp/bmp），声明的 Content-Type / 扩展名只作参考且可被否决；嗅探为文本（HTML/PROXY 错误页、SVG）或判不定且来源没声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默回退成 `image/png`**（旧文若写「非图片响应会被当 PNG」即按此更正）。
|
||||
- **REST 语音端点已存在**：`POST /api/v1/audio/transcribe`（STT）、`POST /api/v1/audio/speech`（TTS）、`POST /api/v1/audio/voice-clone`（声音复刻），均 owner-only + 审计，绕开 WS 4KB 帧限。语音也可走 WS `voice_input`（上行）/`voice_output`（下行）。
|
||||
- 管理端导入知识文档（RAG）走 JSON body 文本（`POST /api/v1/admin/rag`），非文件上传。
|
||||
|
||||
@@ -66,7 +66,7 @@
|
||||
|
||||
| # | 方法 | 路径 | 鉴权 | 状态 | 说明 | 里程碑 |
|
||||
|---|------|------|------|:---:|------|:---:|
|
||||
| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/409 | 发消息（同步回复或触发 WS 流式） | M8/M15 |
|
||||
| 3 | POST | `/api/v1/chat` | owner\|admin | 200/202/400/409/500/503 | 发消息（同步回复或触发 WS 流式）；**v0.56**：`stream:true` 受理成功才回（`202` 续接排队 / `409` 队列满 / `500 chat_unavailable` 未接 loop / `503 chat_dispatch_failed` 兜底派发失败）、`image` 超 5 MiB → `400 image_too_large`、`clientMsgId` 重复 → `200 {duplicate:true}` | M8/M15 |
|
||||
| 4 | GET | `/api/v1/sessions` | JWT | 200 | 会话列表（持久化会话 or 渠道会话回退） | M16 |
|
||||
| 5 | GET | `/api/v1/personas` | JWT | 200 | 人格列表 | M8 |
|
||||
| 6 | GET | `/api/v1/sessions/{id}/messages` | owner\|admin | 200 | 会话消息热分页 | M16 |
|
||||
@@ -217,7 +217,8 @@ curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 工具或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn。**语义（v0.53）**：主模型能否收图看生效组的 `multimodal`；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` 只配视觉/OCR **工具**的模型（见 api-client §1 行 3） |
|
||||
| `deviceId` | string | 否 | 客户端生成的端标识（design/16 §4.5，如 `web:chrome:a1b2c3`），落库到消息，可选 |
|
||||
| `mode` | string | 否 | 行为模式（design/01 §3、design/16 §5.1，如 `chat`/`code`/…）；随该轮落库供气泡渲染；**IM 恒 `chat`、缺省回落 `chat`**（`chatRequest.Mode`） |
|
||||
| `stream` | bool | 否 | `true` = 经 WS 触发流式（`publishChatStream` 发 `ws.chat`），**立即返回**；缺省 / `false` = 同步返回完整回复（Go bool 零值即 false，仍**无「必填」约束**） |
|
||||
| `clientMsgId` | string | 否 | **客户端幂等键（v0.56，G4）**：同一会话内同一个非空值只承认第一条，重复到达回 `200 {"data":{"duplicate":true,"messageId":...,"sessionId":...}}` 且**不落库、不起回合**；省略 = 与加入该字段前逐字相同（老客户端零影响）。原生端用它把本地乐观气泡对齐到服务端真相 |
|
||||
| `stream` | bool | 否 | `true` = **直达会话编排器**的流式提交（v0.56/G2：接了编排器就直接 `Submit`，**不再经可丢弃的 bus**；未接编排器才回退 `publishChatStream` 发 `ws.chat`），**受理成功后才回响应**；缺省 / `false` = 同步返回完整回复（Go bool 零值即 false，仍**无「必填」约束**） |
|
||||
|
||||
```json
|
||||
{"sessionId":"web","text":"你好","deviceId":"web:chrome:a1b2c3","stream":false}
|
||||
@@ -226,13 +227,17 @@ curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
- **响应**：
|
||||
- 同步（`stream=false`，会话空闲）`200` `{"data":{"reply":"<助手文本>","steps":<int>,"stopReason":"<string>"}}`（`chatResponse`）。`steps` 为工具循环步数，`stopReason` 为停止原因（如 `stop`/`idle`/`error`）。
|
||||
- 同步但会话**正忙**（`SubmitSync` 返回 `Pending`）`202` `{"data":{"queued":true,"queueDepth":<int>}}`（非阻塞 ack，稍后按上下文续接）。
|
||||
- 流式（`stream=true`）`200` `{"data":{"stream":true}}` —— 实际文本经 WS 推送（见 §6）。
|
||||
- 同步且 **`clientMsgId` 重复到达**（`SubmitSync` 返回 `Duplicate`）`200` `{"data":{"duplicate":true,"messageId":<id>,"sessionId":<id>}}`（**v0.56/G4**：不落库、不起回合，`messageId` 是既有那条的 id）。
|
||||
- 流式（`stream=true`，**v0.56 行为变更**）：**受理成功后才回** —— 空闲已起回合 `200` `{"data":{"stream":true}}`；正忙已续接排队 `202` `{"data":{"stream":true,"queued":true,"queueDepth":<int>}}`；待处理满 `409` `{"error":{"code":"chat_busy",...}}`；幂等键重复 `200` `{"data":{"duplicate":true,"messageId":<id>,"sessionId":<id>}}`（**不落库、不起回合**）。实际文本经 WS 推送（见 §6）。**修复前**该分支在问编排器之前就回 `200 {"data":{"stream":true}}`，故 `202`/`409` 永不出现；**未接 loop 时由 `200 {stream:true}` 改为 `500 chat_unavailable`**（与同步路径同口径）。
|
||||
- **错误**：
|
||||
- `400` `{"error":{"code":"bad_request","message":"text or image is required"}}`（空消息）。
|
||||
- `400` `{"error":{"code":"image_too_large",...}}`（**v0.56/G3**：`image` 解码后超 **5 MiB**；base64 字符串上限 `ceil(n/3)*4+64`，与 `POST /api/v1/upload` 同口径，文案指路该端点）。
|
||||
- `409` `{"error":{"code":"chat_busy","message":"会话正忙，待处理消息已满"}}`（pending 队列满，`PendingFull`）。
|
||||
- `500` `{"error":{"code":"chat_unavailable",...}}`（`runner` 未注入）/ `{"error":{"code":"chat_failed",...}}`（回合运行出错）。
|
||||
- `503` `{"error":{"code":"chat_dispatch_failed",...}}`（**v0.56/G2**：仅**未接编排器**时的总线兜底派发失败——本轮**未提交**，不再是静默 200）。
|
||||
- **备注**：
|
||||
- **会话编排（design/15）**：同会话正忙时新消息**不阻塞**、入 pending（默认上限 5）；满则 `409 chat_busy`。状态经 WS 状态事件通知（§6.4）。
|
||||
- **幂等（v0.56/G4）**：带 `clientMsgId` 的用户轮次由 `(session_id, client_msg_id)` 的**部分唯一索引**原子判重（写在 `internal/runtime/history/store.go` 的 `AppendFull` + `client_msg_id.go`），重复到达**不落库、不起回合**；该键随后出现在消息 DTO（含 `GET /sessions/{id}/messages`）。
|
||||
- 主会话 `web` 绑定**全量访问 env**（`loop.OwnerEnv()`：记忆读写 + 行为不变）。
|
||||
- 敏感字段（`image` 可能为 base64）不走日志明文。
|
||||
- curl：
|
||||
@@ -1080,7 +1085,7 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:---:|------|
|
||||
| `type` | string | 是 | 事件类型（见 §6.3 表） |
|
||||
| `turnId` | string | 否 | 一轮交换的关联 id（流式；`turn-<hex>`）；OnStream 结构化流路径**不带** |
|
||||
| `turnId` | string | 否 | 一轮交换的关联 id（流式；`turn-<hex>`）。**v0.36 起结构化流帧（`message.*`/`thinking.*`/`tool_call.*`）同样带 `turnId`**（`broadcastStream` 从 `model.StreamEvent` 取，loop 在回合边界注入）；v0.50 起这些帧的 `data` 内另带 `streamId`（见 §6.6）。**旧文曾说这条路径只有 `seq`、没有轮次标识，那是错的，已更正** |
|
||||
| `seq` | int | 否 | hub 级单调递增序号，供客户端排序关联流式突发 |
|
||||
| `sessionId` | string | 否 | 能确定会话的事件带上，客户端按它把帧路由到该会话的消息桶（v0.54 起非激活会话的帧不再丢弃；只有单槽忙态仍按激活会话判定，见 `api-client.md` §3.1/§3.2/§3.3）；可观测推送三帧（`observability_log`/`observability_trace`/`observability_metrics`，v0.55）**不带**该字段，帧壳只有 `{type,data}` |
|
||||
| `data` | any | 否 | 类型化负载（每个事件见 §6.3） |
|
||||
@@ -1099,23 +1104,23 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
| type | 数据负载 | 服务端行为 | 结果 |
|
||||
|------|----------|-----------|------|
|
||||
| `mode_switch` | 任意（如 `{"mode":"chat"}`） | 发布 `ws.mode_switch` → hub 规范化广播 | 下行 `mode_switch`（广播） |
|
||||
| `chat` | `{sessionId?, text, image?, deviceId?, mode?}` | **直达会话编排器的非阻塞 `Submit`（v0.55 起：上行 chat 不再经可丢弃的 bus——会话消息不得被 drop；编排器未注入时回退发布 `ws.chat`）** → `streamChat`（跑 loop 并流式） | 下行 `stream_chunk`/`stream_end` 或 `message.*/thinking.*/tool_call.*`（广播） |
|
||||
| `interrupt` | `{sessionId}` | 会话编排器中断：取消在跑 turn + 清空 pending | 下行 `session_interrupted` |
|
||||
| `chat` | `{sessionId?, text, image?, deviceId?, mode?, clientMsgId?}` | **直达会话编排器的非阻塞 `Submit`（v0.55 起：上行 chat 不再经可丢弃的 bus——会话消息不得被 drop；编排器未注入时回退发布 `ws.chat`）** → `streamChat`（跑 loop 并流式）。`clientMsgId`（**v0.56/G4**）非空且重复到达 → **不落库、不起回合**，只回下行 `chat_duplicate` | 下行 `stream_chunk`/`stream_end` 或 `message.*/thinking.*/tool_call.*`（广播）；重复时下行 `chat_duplicate` |
|
||||
| `interrupt` | `{sessionId, scope?}` | 按 `scope` 中断（**v0.56/A2**）：省略 / `""` / `"all"` = 取消在跑 turn + **清空 pending**（现状语义）；`"current"` = **只取消在跑 turn、保留 pending**（队列按编排器续跑规则继续执行）；**其它取值 → 定向回 `error{bad_request}`，不打断任何会话** | 下行 `session_interrupted`（`{sessionId,mode,dropped}`；`dropped` = **真的被丢弃**的 pending 条数，`scope:"current"` 时为 `0` 且 `mode` 为当时的忙碌通道） |
|
||||
| `voice_input` | `{audio?, format?, text?, sessionId?}` | STT→chat→TTS（缺省 sessionId=`web`） | 下行 `voice_output`（**定向回请求连接**） |
|
||||
| `subagent_ask` | `{id, mode?(""/full/tail/keyword), n, query?}` | 审计子代理上下文（缺省 `mode`=full） | 下行 `subagent_event`（或 `error`） |
|
||||
| `task_output_query` | `{taskId}` | 查询后台任务输出 | 下行 `task_output`（或 `error`） |
|
||||
|
||||
**上行各负载字段**
|
||||
|
||||
- **`chat`**（`chatStreamRequest`）：`{sessionId`(缺省`"web"`), `text`, `image?`(base64 data: URI 或 URL), `deviceId?`, `mode?`(行为模式，缺省回落 `chat`)}。text+image 至少一项；`runner` 未注入或两者皆空 → 直接广播 `stream_end{stopReason:"idle"}`。主会话 `web` 绑定全量 env（`loop.OwnerEnv()`）。`chat` 进入时若该会话正忙 → 由编排器入队（见 §6.4），非阻塞。**仅 owner/admin 连接可发**（见本节角色门）。
|
||||
- **`interrupt`**：`{sessionId}`。命中空闲会话为 no-op。
|
||||
- **`chat`**（`chatStreamRequest`）：`{sessionId`(缺省`"web"`), `text`, `image?`(base64 data: URI 或 URL), `deviceId?`, `mode?`(行为模式，缺省回落 `chat`), `clientMsgId?`(客户端幂等键，**v0.56/G4**：同一会话内同一非空值只承认第一条，重复到达回下行 `chat_duplicate` `{sessionId,clientMsgId,messageId}`，且**不落库、不起回合**；省略 = 老行为逐字不变)}。text+image 至少一项；`runner` 未注入或两者皆空 → 直接广播 `stream_end{stopReason:"idle"}`。主会话 `web` 绑定全量 env（`loop.OwnerEnv()`）。`chat` 进入时若该会话正忙 → 由编排器入队（见 §6.4），非阻塞。**仅 owner/admin 连接可发**（见本节角色门）。
|
||||
- **`interrupt`**（**v0.56/A2**）：`{sessionId, scope?}`。`scope` 省略 / `""` / `"all"` = 取消当前任务 + 清空待处理队列（现状语义）；`"current"` = **只取消当前任务、保留待处理队列**（队列按编排器续跑规则继续执行）；**其它取值 → 定向回** `{type:"error",data:{code:"bad_request"}}`，**不广播、不打断任何会话**。命中空闲会话为 no-op（两种 scope 都是）。
|
||||
- **`voice_input`**：`{audio`(base64 或 data: URI), `format`(`wav|mp3|ogg|webm|mpeg`，空由 mime 猜，默认 `wav`), `text`(已转写则跳过 STT), `sessionId?`}。无 `voice` 服务 → `{type:"error",data:{message:"voice unavailable"}}`。
|
||||
- **`subagent_ask`**：`{id`(必填), `mode`(空/full/tail/keyword), `n`(tail 查询窗长), `query`(keyword 查询词)}。无 auditor → `error`；id 缺失 → `error`。
|
||||
- **`task_output_query`**：`{taskId}`。无 task store → `error`；运行中任务返回截至目前输出；输出拼接 `stdout + "\n" + stderr`。
|
||||
|
||||
### 6.4 下行事件全表
|
||||
|
||||
> **角色门（design/11 §7.1，fail-closed）**：下行帧按类型分档，收口在 `internal/services/gateway/ws_frame_scope.go` 的 `frameReachesAll`（**唯一一处判定**，各调用点不自行决定可见性）。**只有 7 个不含内容的状态机信号**发给**所有已认证连接**（含 `viewer`）：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full` / **`session_read`**。**其余全部只发 `owner`+`admin`**：流式内容（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` / `stream_chunk` / `stream_end`）、持久化（`message_persisted` / `message_edited` / `message_deleted` / `channel_persisted`）、系统内部（`graph_update` / `subagent_event` / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`）、私有状态（`mood` / `device_update` / `reminder` / `proactive_message`）、**可观测推送（`observability_log` / `observability_trace` / `observability_metrics`，v0.55）**；**未登记的新帧类型默认只发 owner/admin**。**本表并非全表**：`session_read` / `message_edited` / `message_deleted` 等已实现事件尚未逐行登记于此；**权威清单与逐帧口径见 `Docs/api-client.md` §3**。
|
||||
> **角色门（design/11 §7.1，fail-closed）**：下行帧按类型分档，收口在 `internal/services/gateway/ws_frame_scope.go` 的 `frameReachesAll`（**唯一一处判定**，各调用点不自行决定可见性）。**只有 7 个不含内容的状态机信号**发给**所有已认证连接**（含 `viewer`）：`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full` / **`session_read`**。**其余全部只发 `owner`+`admin`**：流式内容（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` / `stream_chunk` / `stream_end`）、持久化（`message_persisted` / `message_edited` / `message_deleted` / `channel_persisted`）、系统内部（`graph_update` / `subagent_event` / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`）、私有状态（`mood` / `device_update` / `reminder` / `proactive_message`）、**可观测推送（`observability_log` / `observability_trace` / `observability_metrics`，v0.55）**、**`chat_duplicate`（v0.56/G4：虽由编排器状态通道下发，但未进白名单）**；**未登记的新帧类型默认只发 owner/admin**。**本表并非全表**：`session_read` / `message_edited` / `message_deleted` 等已实现事件尚未逐行登记于此；**权威清单与逐帧口径见 `Docs/api-client.md` §3**。
|
||||
>
|
||||
> **来源标记**：`[direct]` 网关直接 emit；`[relay]` hub 从 bus `ws.>` 规范化（任意 `ws.X` 主题 → 类型 `X`）；`[bridge]` 桥接 producer 主题；`[target]` 仅定向特定连接。
|
||||
|
||||
@@ -1138,8 +1143,9 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
| `pending_ack` | direct(编排) | `{sessionId, mode, queueDepth}` | 忙时新消息已入队「收到，稍后回」 |
|
||||
| `pending_drain` | direct(编排) | `{sessionId, mode, queueDepth}` | 忙完开始消费下一待处理消息 |
|
||||
| `session_idle` | direct(编排) | `{sessionId, mode}` | 会话回到空闲、队列清空 |
|
||||
| `session_interrupted` | direct(编排) | `{sessionId, mode, dropped}` | 用户 interrupt，当前任务取消、pending 清空 |
|
||||
| `session_interrupted` | direct(编排) | `{sessionId, mode, dropped}` | 用户 `interrupt`。**v0.56/A2**：帧形状零变化——`scope:"all"`（省略 / 空串同义）= 任务取消 + pending 清空（`mode=idle`、`dropped`=清空条数）；`scope:"current"` = **只取消任务、保留 pending**（`dropped` 恒 `0`、`mode` 为当时忙碌通道） |
|
||||
| `pending_full` | direct(编排) | `{sessionId, mode, max}` | 单会话 pending 达上限（默认 5）拒绝入队 |
|
||||
| `chat_duplicate` | direct(编排) | `{sessionId, clientMsgId, messageId}` | **v0.56/G4（新增帧）**：同一会话内**重复到达**的 `clientMsgId` 的明确回执——**不落库、不起回合、不发任何内容帧**。帧壳带 `sessionId`；**未进 7 个状态机信号白名单 ⇒ fail-closed 只发 `owner`+`admin`**（发过该 `clientMsgId` 的客户端用它把本地乐观气泡对齐到既有 `messageId`，其它客户端按值自行忽略） |
|
||||
| `message_persisted` | direct | `{message:historyMessage}`（sessionId 设） | 每条 user/assistant 消息落库后广播（主会话 `web`/`web:<uuid>`），thinking 剥离 |
|
||||
| `channel_persisted` | direct | `{message:historyMessage}`（sessionId=`sess-xxx`） | 群聊/陌生人（非主人）消息落库后广播，供 IM 适配器日志页 |
|
||||
| `voice_output` | direct/target | `{audio, format, text, reply}` | 语音合成回复（定向回请求连接） |
|
||||
@@ -1176,6 +1182,7 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
| `deviceId` | string | `omitempty` |
|
||||
| `senderName` | string | `omitempty`（第三方昵称，主人私聊为空） |
|
||||
| `adapterId` | string | `omitempty`（仅 `channel_persisted` 常见，如 `kook:3bef...`） |
|
||||
| `clientMsgId` | string | `omitempty`（**v0.56/G4**：客户端自带的幂等键——由 `chat` 上行带 `clientMsgId` 的 user 消息写入，之后在 `message_persisted` / `channel_persisted` / `history` 回放 / `GET /sessions/{id}/messages` 中原样回填；空 = 无幂等键，即老客户端 / IM 镜像 / 历史行） |
|
||||
| `createdAt` | int64 | Unix 毫秒 |
|
||||
|
||||
**事件类型分流**（`BroadcastPersisted`）：`sessionId == "web"` 或以 `web:` 前缀 → **`message_persisted`**（Web 聊天实时同步）；其它（隔离 `sess-xxx`）→ **`channel_persisted`**（IM 适配器日志专用）。Web 聊天无 `channel_persisted` handler，天然忽略。
|
||||
@@ -1189,7 +1196,7 @@ curl -s -X POST http://<host>:8080/api/v1/admin/system/restore \
|
||||
|
||||
### 6.6 流式关联（`turnId` / `seq`）
|
||||
|
||||
- `turnId`：`runTurn` 每次生成 `turn-<hex>`（crypto/rand），用于关联一轮流式突发；`stream_end`/`stream_chunk`（回退路径）带 `turnId`。**OnStream 结构化流路径（`message.*` 等）由 `broadcastStream` 只填 `seq`、不带 `turnId`**（OnStream bus 负载未携带 turn 身份）。
|
||||
- `turnId`：`runTurn` 每次生成 `turn-<hex>`（crypto/rand），用于关联一轮流式突发；`stream_end`/`stream_chunk`（回退路径）带 `turnId`。**结构化流路径（`message.*` / `thinking.*` / `tool_call.*`）自 v0.36 起同样带 `sessionId` + `turnId`**——`broadcastStream` 直接把 `model.StreamEvent` 的 `SessionID`/`TurnID` 填进帧壳，loop 在回合边界把 `turnId` 挂进运行上下文（同轮所有帧一致）。**旧文曾说这条路径只有 `seq`、缺轮次标识，是错的，本版按实现更正**（与 api-client 的 v0.36 条目一致）。v0.50 起这些帧的 `data` 内另带 `streamId`（同一次模型流的多帧共享，多步工具轮的第二次模型调用取新 id）；`tool_execution.*` 与 `turn.start/end` 帧**不带** `streamId`。
|
||||
- `seq`：hub 级单调递增 `atomic.Uint64`，保证一次突发有序，即便 loop 多 goroutine 触发。
|
||||
|
||||
### 6.7 WS 示例
|
||||
@@ -1214,6 +1221,11 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
|
||||
# 4) 上行 interrupt
|
||||
# {"type":"interrupt","data":{"sessionId":"web"}}
|
||||
# 下行：{"type":"session_interrupted","data":{"sessionId":"web","mode":"idle","dropped":2}}
|
||||
# v0.56/A2：只打断当前那一轮、保留待处理队列 → scope:"current"（此时 dropped 恒 0、mode 为当时忙碌通道，如 thinking）
|
||||
# {"type":"interrupt","data":{"sessionId":"web","scope":"current"}}
|
||||
# 下行：{"type":"session_interrupted","data":{"sessionId":"web","mode":"thinking","dropped":0}}
|
||||
# 非法 scope：{"type":"interrupt","data":{"sessionId":"web","scope":"cancel"}}
|
||||
# 定向回发送者：{"type":"error","data":{"code":"bad_request"}}（不广播、不打断任何会话）
|
||||
|
||||
# 5) 上行 voice_input
|
||||
# {"type":"voice_input","data":{"audio":"<base64>","format":"wav","sessionId":"web"}}
|
||||
|
||||
Reference in new issue
Block a user