0 Fork 0

Files

T

AskaEth ea150ceea9 docs(contract): §2.0 端点计数回补（14+18+40=72）+ S6 未确证项收口（V4）

- writeAuth 17→18、总数 71→72（并写明自 v0.76 起 −1 的滞后已修正；历史版本条目保留原写法）
- S6 的未确证项逐条核对：能验的给代码级证据，验不了的写明「为什么验不了」（无凭据/禁重启）
- 契约版本仍 v0.80（同版内记账回补，零形状变更）

2026-10-06 20:25:14 +08:00

305 KiB

Raw Blame History

Cyrene v2 客户端 API 契约

契约版本：v0.80（上一版 v0.79，其条目见 §6；v0.78 / v0.77 / v0.76 / v0.75 / v0.74 / v0.73 / v0.72 / v0.71 及更早见本文件 §6，v0.67 及更早的基线已归档、只读：Docs/archive/api-client.v0.65.md）。读者：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等跨平台客户端开发者。 唯一真源 = 当前代码（internal/services/gateway/* 等）。本文档由代码逐条核对得出；与代码不符时以代码为准，并回改本文档。 旧的超详细版已归档、只读：Docs/archive/api-client.v0.65.md（412 KB，含 v0.28→v0.65 全部历史条目）与 Docs/archive/api-reference.v0.65.md（170 KB，后端全量字段级文档）。归档的原因是结构性臃肿 + 历史条目并列 + 长期漂移；本文档不复制那段历史，需要考古时去归档。 维护铁律：每实现/变更一个 REST 端点、WS 事件、admin API 立即改本文档；契约变更必须版本化，不破坏既有客户端。 准确性 > 详尽度：宁少写也别写错；写不了确证的写「未确证」，见 §7。 ⚠️ v0.67 是「契约先行」登记版：本版新增的三批 —— 语音消息（播放端点 + 消息 DTO voice）、非消息事件查询面、账号在线状态 —— 登记时都还没有实现，形状取自设计文档（design/24 §10.11、design/26 §4.5 / §2.6）而非代码核对。已落地：账号在线状态（52dac45）、非消息事件查询面（切片 E6）—— 见 §2.4；语音消息的「用户可见面」已由 v0.79 落地（切片 L45：DTO voice + GET /api/v1/media/{name} + 副本落盘；残留缺口——WS 实时帧/握手回放不带 voice、AMR 不落副本（后者已由 v0.80 修复）——见 §4.5 / §7.2 / §7.4-29）。已在 §7.2 逐条如实标注。本文档其余内容仍以代码为真源。 v0.68 是纯增量版（已实现，非契约先行）：新增 1 条管理只读端点 GET /api/v1/admin/config-facts（配置事实面，见 §2.2 B12），并给 GET /api/v1/admin/backthink 的条目加 2 个可选字段（urgency / quietHoursBypassed，见 §2.2 B8）。无破坏性变更，老客户端零影响。 v0.69 是缺口修复版（已实现）：PUT /api/v1/admin/channels/{platform}/config 现在接收并原样落盘账号顶层 directMsgPerMin，GET /api/v1/admin/channels 的账号元素也如实回显它（§2.2 A5 / §2.3 C28 注）。修的是「面板保存一次渠道配置，就把主人手配的关闭流控（-1）静默重置回 0 = 保护性默认 6 条/分」。无破坏性变更（老客户端不带该键，行为与 v0.68 相同）。 v0.70 是精确化版（已实现，纯增量）：GET /api/v1/admin/backthink 的 urgency 默认就是该轮实际生效的精确档位（随记录落库），另加可选 urgencyLowerBound:true 专门标记旧行的下限推导值；实时 backthink 帧自本版起也带记录里的 urgency（§2.2 B8 / §4.10(b)，并更正 §4.10(b) 原「实时帧不带这两键」的表述）。无破坏性变更（新键可选，老客户端不读即零影响；urgency 的既有取值域与 quietHoursBypassed 语义都未改）。 v0.71 是链路图补版（已实现，纯增量）：新增 1 条管理只读端点 GET /api/v1/admin/flow/graph，把 ws.graph_update 的最近一轮快照从「只能靠实时帧拿」变成「打开页面即可只读拉取」（§2.2 B13 / §4.11）。修的是「页面在轮次结束后才打开（或刷新过）⇒ /#/admin/flow 与后台思考行的『查看完整链路导图』永远空着」—— graph_update 只走实时帧，前端图桶（flowGraphs）不持久化，此前没有任何补拉通路。无破坏性变更（新端点；graph_update 帧形状、角色门、发布会话范围一字未改）。

v0.72 是主动推送可见性版（已实现，含一处行为变更）：proactive_message 那条消息现在落进主会话历史（web / assistant / mode:"chat"，先落库再发帧），帧新增可选 id/createdAt（主会话历史行的权威 id 与时间戳）供客户端把实时气泡对齐到历史行（§3.4.5 与随后的「落库口径」说明）。修的是主人 2026-10-05 报的「后台思考的主动推送一个都没推出来」—— 活跃客户端路由此前只广播帧、一行都不写，刷新即丢且前端零消费点。两条路由互斥 ⇒ 主会话里恰好一条（不双份）；proactive_message 帧逐字不变的部分是既有全部键，客户端不读新键即行为与 v0.71 相同（只会多看到那条历史行）。

v0.73 是链路图本地落盘版（已实现，纯增量）：链路图从「只活在进程内存」变成每轮一行落进本地库（新表 flow_graphs，迁移 0022），GET /api/v1/admin/flow/graph 在 v0.71 之上增量：新增可选查询参数 turnId（省略 = 最近一轮；先查内存 LastGraph，miss 才回退落盘）、响应新增 turnId / source / turns[] 三键（多轮历史回放，design/19 §4 的 P3）。修的是主人 2026-10-05 追加要求的那句「链路流程应该有本地数据，不然每次重载之后页面就没数据了」—— v0.71 只覆盖「后端进程活着时的最近一轮」，后端一重启、或翻更早的轮次，仍然什么都查不到。无破坏性变更（旧键 sessionId/graph 形状语义不变，graph_update 帧、角色门、发布会话范围一字未改；老客户端不读新键即行为与 v0.71 相同）。落盘范围只有发布会话白名单内的会话（flowSessionAllowed），隔离渠道会话绝不入库。详见 §2.2 B13 / §4.11。

v0.74 是 IM 路由主动消息的提醒版（已实现，纯增量）：message_persisted 的 data 新增可选结构化判据 proactive:true —— IM 路由（im_bridge）的主动推送在落库之后追加一条带该键的同类帧，客户端据此在非前台补一发浏览器通知（此前通知只挂在 proactive_message 上，而 auto 提示在主人有已连接 IM 渠道时优先走 IM ⇒ 实际最可能发生的路径恰恰不弹）。判据是结构化字段（不是正文/提示词）：普通消息（Web 回合 / IM 回复 / IM 镜像）的帧永不带该键 ⇒ 不可能被误判成主动消息。同一行仍照旧发一条不带该键的普通镜像帧（v0.72 起的行为逐字不变，两帧同 id ⇒ 客户端按 id 去重后仍是一个气泡、仍只提醒一次）。详见 §3.4.4 后的「message_persisted 的 proactive 判据」。

v0.76 是三面增量版（⚠️ 逐条状态不同：① 已在 v0.78 实现、覆盖率又由 v0.79 补齐；②③ 已实现）：① 消息读取面新增 toolCalls[]（工具回看面）—— ✅ 已实现（v0.78，切片 CODE-TC），覆盖率已于 v0.79 补齐至全部编排回合：GET /api/v1/sessions/{id}/messages 的消息对象加可选 toolCalls（omitempty），每条含工具名 / 状态（ok/error/unknown）/ 耗时毫秒 / 已脱敏的入参与结果摘要；数据源是已落盘的轮次链路图（flow_graphs，迁移 0022；v0.78 加迁移 0023 的按路查询键，保留期 168h），不从正文反解。🔴 缺席语义：图取不到（超保留期 / 该轮未落盘 / 隔离渠道会话从不入库 / 该路标识查不到图）⇒ 字段整体缺席，绝不回空数组冒充「这一轮没调过工具」。⚠️ 历史说明（v0.76 登记时未实现的原因，实测确认非推断）：chat_messages.turn_id 与 flow_graphs.turn_id 不同源 ⇒ 两者无法按消息字面 join，按时间窗猜映射项目口径不做；补齐需先让链路图带上按路的回合标识、并补一个按路查图的读侧入口。v0.78 已把这两件都补上 ⇒ toolCalls[] 已实现；🔴 v0.78 时只有真并行路能回看（普通单路回合的图当时不带权威 turnId）—— 已由 v0.79（切片 CODE-TC-2）补齐（见 §4.4、§7.2、§7.4-23 与 §6 的 v0.78 ① / v0.79 ④）。② 未读面（✅ 已实现） —— message_persisted 的 data 加可选 unreadCount（omitempty：只在 >0 且确实算得出来时出现；缺席 = 老行为），GET /api/v1/sessions 列表项同键（该键自 D4 起就已在，本版未改它）。口径 = 绝对未读 + 主人单一已读游标（chat_sessions.read_at）⇒ 多端共享（Web 读了移动端也清），这是与安卓侧已对齐的取舍，不是缺陷。详见 §3.4.4、§4.13。③ 记忆整理试算加性异步 —— POST /api/v1/admin/memories/tidy/dry-run?async=1 ⇒ 202 + runId；新增 GET /api/v1/admin/memories/tidy/dry-run/{runId} 轮询；不带 async 仍是原同步行为。无破坏性变更（新键 / 新可选参数 / 新端点；老客户端零影响）。详见 §1（会话列表与消息读取）、§2.2 B15 / §4.12.1、§3.4.4。

v0.77 是链路图按路分桶 + 记忆整理护栏/异步落地版（已实现；纯增量）：① graph_update 按路分桶（切片 FV2）—— 帧 data 新增可选 turnId（该图的路的权威回合标识）与 round（会话轮次号）；真并行（parallel:true）时同一会话每一路各发自己的帧（data.id / data.turnId 各不相同），两路不再互相顶掉；GET /api/v1/admin/flow/graph 响应新增 lanes[]（最近一轮每一路的图，恒为非 null 数组），graph 语义不变（最新一路 / 指定轮 / null 诚实空态）⇒ 老的读取方零改动。无破坏性变更（两个新键可选；单路时 turnId 缺席 ⇒ 客户端行为与 v0.75 逐字相同）。详见 §2.2 B13 / §3.4.5 / §4.11 / §7.4-19。② 记忆整理护栏抬高 + 诚实截断 + 试算异步落地（切片 MT-A）—— 每分区候选上限 MEMORY_TIDY_CANDIDATE_LIMIT 默认值 20 → 200、两两比对上限改为 env 键新键 MEMORY_TIDY_COMPARE_LIMIT（默认 2000，原先写死 400）；配置事实面 12 → 13 条；truncated 新增第 4 种标签 (budget)（墙钟时间预算截断）；v0.76 ③ 的加性异步已落地（?async=1 + B15 轮询可用；新错误码 tidy_run_not_found）。详见 §2.2 B14/B15 / §4.10(a) / §4.12 / §4.12.1 / §5。③ 「入库前审查」的 4 个 env 键登记（切片 MT-B，纯增量）—— MEMORY_REVIEW_ENABLED（true）/ MEMORY_REVIEW_QUEUE_SIZE（256）/ MEMORY_REVIEW_SCAN_LIMIT（200）/ MEMORY_REVIEW_TIMEOUT_SEC（20）；⚠️ 该切片的面板读侧 / 回滚端点目前没有 HTTP 入口（见 §7.2）。详见 §5。

v0.80 是三批增量版（均已实现**，纯增量、无破坏性变更）：① 链路图时间轴出口（切片 W1，design/19 §7）—— 新增 1 条管理只读端点 GET /api/v1/admin/flow/timeline（§2.2 B18 / §4.11.1），把「链路图」从「最近一轮 + 已落盘轮次的键列表**」扩到按时间正序的多轮时间轴（每轮含该轮每一路），支持 limit（缺省 50 / 硬上限 200）与 before 游标向更早翻页；响应另给 retentionHours / retentionEnabled / truncated，供面板如实标注「更早的轮次已过保留期」。修的是主人 2026-10-06 的原话「web 后台的全链路流程图我要的是所有消息按时间顺序串起来的流程图，而不是只有最新一个来回」。老端点 GET /api/v1/admin/flow/graph（B13）逐字未改（老客户端零改动）。② 搜索 provider 热重载 + 主 provider / 降级链（切片 W3；裁决 2026-10-06 #1 / #2）—— plugin.saveProvider 成功落盘后，组合根按落盘后的配置重建 web-search 工具并原子替换能力注册表里的条目（registry.ReplaceTool，保留运行期策略）⇒ 下一轮对话即用新配置、不需要重启；若这次改动会让 web-search 没有可用后端（下次启动会 fail-fast）⇒ 文件按字节回滚 + 409 config_unstartable。同一次提交可带两个文件级字段 primary / fallback[]（缺位 = 不改动）；响应新增机器可读事实 hotReload:{applied,registered}；新增错误码 primary_not_configured(400) / config_unstartable(409)。🔴 本版把三处已成假话的旧口径改正（§4.14(b)(c) / §7.2）—— 此前写的「面板保存后不热替换运行中的工具、需重启」与「面板无主 provider / 降级链字段」都不再成立。⚠️ 未确证（如实）：真机面板上「新增/改一家 provider → 下一次搜索真的走它」的端到端、以及真机探针打真实上游，都没跑。③ 入站语音 AMR 也可回放（切片 W4；裁决 #11）—— 组合根补齐 channelbridge.Options.VoiceTranscoder 注入（cmd/cyrene/wire_channels.go）⇒ 不可播格式的入站语音在落盘之前先转成 .wav 再落副本（mime: audio/wav；本期唯一必需的转码路 = QQ OneBot v11 的 amr → wav，见 internal/runtime/voice/playable.go），客户端从此能拿到可回放的字节；此前走 category=transcode_not_wired 的诚实 WARN、不落副本。形状零变化（DTO voice 的键集合与语义一字未改；可播格式仍原样落、一次转码都不发生）。🔴 同批改正 §4.5 / §7.1 / §7.2 / §7.4 里已成假话的「组合根未注入 VoiceTranscoder ⇒ AMR 不落副本」（transcode_not_wired 从此只剩「引擎未装配 / 构造失败」一档；旧版本横幅保留当时状态，另加「已由 v0.80 修复」注）。⚠️ 未确证（如实）：③ 的生产端到端未跑（红线：不重启后端）⇒ 本期证据是 channelbridge 的行为单测（真 AMR 夹具 → 真引擎 → RIFF/WAVE）与 cmd/cyrene 的源码级接线用例。详见 §6。

v0.79 是「面板动作真可用 + 记忆审查/语音用户可见面 + 链路图回合标识全覆盖」版（四批，均已实现**；唯一一处形状变化）：① 插件面板动作真可用（切片 L1/PLG-2 的执行面接线）—— POST /api/v1/admin/plugins/{id}/actions/{action} 不再一律 501：web-search 的四个动作 + 下拉候选来源（plugin.providers）都已登记生产处理器**，真读写 $DATA_DIR/config/plugins/web-search.json、探针真发一次 HTTP；失败回结构化非 2xx（错误码/文案/状态由插件侧给出，宿主只透传），新增 invalid_payload / unknown_provider / not_configured / config_unreadable / config_write_failed 与一批探针码（502）；只有「已声明但宿主未登记处理器」才回 501 action_not_implemented（不再是兜底档）。审计新增附加字段 code（不进 DB 记录体、不含请求体）。详见 §2.1 A14 / §4.1 / §4.14 / §7.2。② 「入库前审查」（D3）的管理面落地（切片 L45）—— 新增 2 条 writeAuth 端点 GET /api/v1/admin/memories/reviews?limit=（留痕列表，不含记忆正文；limit 缺省 100 / ≤0 同缺省 / >500 钳位 / 非整数 400）与 POST /api/v1/admin/memories/{id}/revert（撤销一次软合并，无损可逆，落审计 memory.review.revert）；未接线 ⇒ 500 memory_review_unavailable（绝不回空数组假装没有留痕）。详见 §2.2 B16/B17 / §4.1。③ 语音消息的用户可见面落地（切片 L45）—— 消息 DTO 的 voice 现在真的填充（REST 读取面 + message_edited），新增 GET /api/v1/media/{name}（200/206/304/416/HEAD；audio/* 内联 + nosniff + Accept-Ranges；无 ETag；名字非法 / 穿越 / 缺失统一 404 media_not_found），副本真落 $DATA_DIR（documents.SaveAudio，内容寻址、0600）。⚠️ 残留缺口（如实）：message_persisted / channel_persisted 帧与握手 history 回放仍不带 voice；组合根未注入 VoiceTranscoder ⇒ AMR 不落副本（可播格式照落）—— ✅ AMR 这一项已由 v0.80（切片 W4）修复。详见 §1.2 U19 / §3.4.4 / §4.1 / §4.4 / §4.5 / §7.2。④ 🔴 链路图的权威回合标识覆盖到全部编排回合（切片 CODE-TC-2）—— 编排器驱动的每一路（含普通单路回合与队首续跑路）的图现在都带权威 turnId，取值 = 该轮消息行的 chat_messages.turn_id ⇒ GET /sessions/{id}/messages 的 toolCalls[] 覆盖率从「只有真并行路」扩大到「全部编排回合」（普通单路聊天与队首续跑回复现在也能回看工具）。🔴 唯一形状变化：graph.id 的 #{回合标识} 后缀现在单路也追加（web-7 → web-7#turn-…）⇒ 客户端一律使用响应里给出的 graph.id / turns[].turnId，不要自己拼 {会话}-{序号}。缺席语义一字未改：拿不到权威标识的写入路径（未接编排器的调用方、后台思考 sess-backthink、旧后端）turnId 仍缺席、toolCalls 仍整体缺席；v0.79 之前的单路历史行不回填。详见 §4.4 / §4.11 / §7.2 / §7.4-23。无破坏性变更（新端点 / 新可选键 / 新错误码；老客户端若不自己拼 graph.id 则零改动）。

v0.78 是六面增量版（⚠️ ①~⑤ 已实现；⑥ 只到落库面（用户可见面已由 v0.79 补齐**）；以纯增量为主，无破坏性变更）：① 消息读取面 toolCalls[] 落地（切片 CODE-TC）—— v0.76 ① 从「未实现」改为已实现**（数据源 flow_graphs + 迁移 0023 的按路查询键 lane_turn_id）；🔴 v0.78 时覆盖率受限（如实）：只有真并行路的图带权威 turnId，普通单路回合查不到图 ⇒ 字段缺席（契约允许，但不是想要的覆盖率）—— 已由 v0.79 补齐（见 §6 v0.79 ④）。详见 §4.4 / §7.2 / §7.4-23。② 插件管理面板接入点（管理面新增两条路由 + 一条 WS 帧）（切片 PLG-2）—— 新增 GET /api/v1/admin/panels（按调用者角色过滤后的接入点快照，viewer 可读）与 POST /api/v1/admin/plugins/{id}/actions/{action}（只接受该插件声明过的动作名，未声明 ⇒ 404 action_not_declared；写动作 writeAuth + 审计）；WS 下行帧 panels_changed（插件生命周期变化后推，只发 owner/admin）。⚠️ 动作执行器在 v0.78 无生产实现 ⇒ 当时所有已声明动作都回 501 action_not_implemented —— 已由 v0.79 接线（见 §6 v0.79 ① 与 §4.14）。详见 §2.1 A13/A14 / §3.4.5 / §4.14。③ 搜索 provider 可变源（切片 PLG-4）—— 插件 web-search 的配置从 .env 迁到 $DATA_DIR/config/plugins/web-search.json（0600，文件名 = 插件 id），组合根「先可变源、缺失回落 .env 播种」；面板数据面 = plugin.listProviders / plugin.saveProvider / plugin.testProvider / plugin.reauthProvider 四个动作。🔴 不新增任何 env 键（.env 已冻结为引导面）。详见 §4.14(c)。④ 账号上下线落事件 + 渠道事件实时帧（切片 E7）—— 账号 online/offline 迁移落进 internal/runtime/events（复用迁移 0021，tier=t2 / category=lifecycle），并经既有进程内 bus 推成 WS 下行帧 channel_event（只发 owner/admin，viewer 走 REST 只读档）。⚠️ 当前只覆盖账号状态迁移这一路；覆盖其余全部渠道事件的装饰器未接线（见 §7.2）。详见 §3.4.5。⑤ 微信 iLink 账号状态三态（切片 CODE-F3）—— GET /api/v1/admin/channels/{platform}/login-status 新增可选 authState / authDetail（有效 / 被拒 / 未知）；🔴 errcode=-14 是「被拒」不是「过期」，未知同样不许写成「过期」。⚠️ GET /admin/channels 的 accounts[] 每账号三态未实现（见 §7.2）。详见 §2.4(c)。⑥ 语音消息落库面（切片 CODE-VOICE）—— 迁移 0020 给 chat_messages 加 voice 列（TEXT NOT NULL DEFAULT ''）；用户可见面（DTO voice + GET /api/v1/media/{name}）在 v0.78 时未实现，已由 v0.79 落地（切片 L45，见 §6 v0.79 ③）；残留缺口（WS 实时帧 / 握手回放不带 voice；AMR 那一项已由 v0.80 修复）见 §4.5 / §7.2。无破坏性变更（新端点 / 新可选键 / 新帧；老客户端零影响）。

v0.75 是记忆整理试算版（已实现，纯增量）：新增 1 条管理端点 POST /api/v1/admin/memories/tidy/dry-run（只读语义的 POST，writeAuth = owner/admin）—— 跑同一套记忆整理规则（召回门 + 包含判定 + 规则否决，与低峰定时轮共用代码路径），把候选直接回在响应里，一行都不写（不写 memory_tidy_candidates / memory_tidy_runs，绝不改 memory_items）。修的是「整理器只在 23:00–07:00 跑（design/23 §4），在它第一次开跑前面板只能空着」——主人要「现在就想看到在 736 条上它会建议合并哪些」。零副作用是硬约束（后端有逐行快照单测钉死）；失败一律如实作答（tidy_unavailable / tidy_disabled / tidy_recall_unavailable / tidy_timeout），绝不回空候选数组假装「没有建议」。无破坏性变更（新端点；既有端点/帧一字未改）。详见 §2.2 B14 / §4.12。

0. 基础约定

0.1 基址与版本

Base URL：http://<host>:<PORT>。PORT 默认 8080（env:"PORT" default:"8080"）；生产一般经反代/HTTPS，运行实例可能自定义端口。
唯一对外端口：单二进制、单端口（运行实例实测 :10942）。REST、WS、管理 API、静态资源全在同一端口；不另有监听端口（唯一登记例外：qq-obv11 渠道 OneBot 反连 server 模式，见 design/08 §4，与客户端契约无关）。
版本前缀：
- 用户侧 REST：/api/v1/{resource}
- 管理侧 REST：/api/v1/admin/*
- 实时：/ws/chat（WebSocket）
破坏性变更升 v2；本文档内的纯增量变更不升。

0.2 认证与授权

凭据	用法	作用面	备注
Bearer JWT	`Authorization: Bearer <JWT>`	用户侧 + 管理侧全部已认证端点	RBAC：`owner` > `admin` > `viewer`（递增）。access token TTL 24h（`tokenTTL`）。
`X-API-Key`	请求头 `X-API-Key: <key>`	用户侧 + 管理侧全部已认证端点	命中签发表即 `owner` 级（不做角色分档，裁决 15.4.3）。带该头时只走 key 分支：未知/已吊销/空值 → `401`，绝不回落 Bearer（fail-closed）。key 表未注入 = 空表（带头一律 401）。
WS 握手	`?token=<JWT>` 查询参数或 `Authorization: Bearer <JWT>`	仅 `/ws/chat`	只认 JWT（`auth.Verify`）。不接受 `X-API-Key`。失败在升级前回 `401 {"error":{"code":"unauthorized",...}}`。

JWT claims 的 role 决定授权分档；sub 是账号标识。
X-API-Key 命中后 sub 记作 apikey:<脱敏 id>（审计可定位哪把 key，但绝不含密钥材料）。
身份/权限绝不来自提示词或 LLM 判断（项目红线）：一律由 channel 层强类型 actor 元数据 + 白名单 + 策略引擎决定。

0.3 响应信封

成功：{"data": <载荷>}（个别端点直接回二进制，见 §4.5 语音）。
失败：{"error":{"code":"<机器可读码>","message":"<人读文案>"}}。
状态码全集（代码实际使用）：200 201 202 206 304 400 401 403 404 409 413 415 416 429 500 501 502 503。
- ⚠️ 502 是 v0.78 引入（插件动作执行失败 ⇒ POST /admin/plugins/{id}/actions/{action} 的 action_failed，见 §4.14(b)）；其余状态码集合未变。
- ⚠️ 206 / 304 / 416 是 v0.79 起「实际使用」（GET /api/v1/media/{name} 落地，见 §1.2 U19 / §4.5）：206（Range 部分内容）/ 304（条件请求）由 Go 标准库给出；416（Range 语法非法或范围不可满足）是非信封的 —— 标准库直写 text/plain + Content-Range: bytes */<size>，不套 {"error":…} ⇒ 客户端不要拿 error.code 去解析 416。
客户端按 error.code 分支，不要按 message 文本（文案会随修改变动）。

0.4 三档标注惯例

本文档与「变更记录」用三档描述每次变更对客户端的影响：

纯增量：只新增端点 / 帧 / 可选字段 / 取值。老客户端不读新键时行为逐字不变。
行为变更：既有端点/帧的语义或响应面变了，客户端需改处理（如新状态码、新时点）。
破坏性：既有字段/形状被移除或改义，老客户端会坏。

0.5 未接依赖时的诚实边界（fail-visible）

后端某些端点依赖注入的存储/服务；未接线时明确报错或退化为诚实空结果，绝不返回假数据：

依赖	未接线时的行为
`HistoryStore`	`GET /sessions` 回退到渠道会话视图；`POST /sessions`、`GET /sessions/{id}/messages`、`PATCH/DELETE /sessions/{id}`、`POST /sessions/{id}/read`、`PATCH/DELETE /messages/{id}` → `501 not_implemented`
语音服务	`POST /audio/*` → `500 voice_unavailable`；WS `voice_input` → `error` 帧 `{"message":"voice unavailable"}`
渠道事件存储（`internal/runtime/events`）	`GET /admin/channels/events` 与 `.../events/counters` → `500 channel_events_unavailable`（v0.67 已实现，见 §2.4(a)；绝不回全 0 假汇总）
LLM usage 出口	`GET /admin/llm/usage` → `500 usage_unavailable`（绝不回全 0 假汇总）
活跃 SQLite 连接	`GET /admin/system/storage` → `500 storage_unavailable`
可观测日志缓冲	`GET /admin/observability/logs` → `501`（组合根注入前）

1. 用户侧 REST 端点

1.1 公开端点（无需认证）

#	方法	路径	状态码	要点
P1	GET	`/api/v1/health`	200	存活探针 → `{data:{status:"ok"}}`
P2	POST	`/api/v1/auth/login`	200 / 400 / 401 / 500	body `{username,password}` → `{data:{token,expiresAt,role,refreshToken?}}`。access 24h；`role` 恒 `owner`；`refreshToken` 仅在接了 refresh 存储时出现（`AUTH_REFRESH_TTL` 默认 720h）。凭据错 → `401 unauthorized`。
P3	POST	`/api/v1/auth/refresh`	200 / 400 / 401 / 500	body `{refreshToken}` → 新 access + 新 refresh（默认单次使用轮换）。未知/已吊销/过期 → `401 invalid_grant`。`AUTH_REFRESH_ROTATE_DISABLED=true` 时旧 token 保持有效、不返回新 refresh。未接存储 → `500 refresh_unavailable`。
P4	POST	`/api/v1/auth/logout`	200 / 400 / 401 / 500	带 `{refreshToken}` → 撤单份 `{data:{revoked:bool}}`（幂等，未知也 200）；带 Bearer 且无 body → 撤该账号全部 `{data:{revoked,revokedCount}}`（两种响应形状不同）。两者都无 → `400`。

登录/刷新/登出公开是刻意的：非透明 refresh token 本身就是凭据，故过期 access 的客户端仍能轮换/吊销它。它们对非法 token fail-closed。

1.2 用户端点

#	方法	路径	鉴权	状态码	要点
U1	POST	`/api/v1/chat`	owner/admin	200 / 202 / 400 / 409 / 500 / 503	主对话入口，见 §4.6。body `{sessionId?,text,image?,deviceId?,mode?,clientMsgId?,documents?,parallel?,stream?}`。
U2	GET	`/api/v1/sessions`	任意已认证	200 / 500	会话列表 `{data:[{id,type,title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`。排序：`pinned DESC, (type='main') DESC, created_at ASC` —— 置顶的次级会话会排在主会话之前，勿假定 index 0 是主会话。主会话 `id="web"`、`type="main"`；子会话 `web:<uuid>`、`type="sub"`。history 未注入时回退渠道会话视图。
U3	GET	`/api/v1/personas`	任意已认证	200	角色目录 `{data:[{id,name,character,isDefault,mode,memoryNamespace,avatar?,chatBackground?,mood}]}`。`mood` 为空 = 该角色暂无被跟踪情绪（不伪造）。不含 admin 专属 `thinking` 旋钮。
U4	GET	`/api/v1/meta/enums`	任意已认证	200	共享枚举权威表 `{data:{platforms,moods,modes,unknown}}`；每项 `{id,label}`。`unknown` 恒 `"display-raw"`。未知取值原样显示，不要丢弃/报错（服务端新增取值是非破坏性变更）。详见 §4.7。
U5	POST	`/api/v1/audio/transcribe`	owner	200 / 400 / 500	STT。body `{audio,format?,deviceId?}` → `{data:{text, provider?}}`。`provider` 只在结果为空/降级时出现（如 `"silent"`）。空 audio → `400`；未接语音 → `500 voice_unavailable`；识别失败 → `500 stt_failed`。owner-only + 审计。
U6	POST	`/api/v1/audio/speech`	owner	200 / 400 / 500	TTS。body `{text,voice?,format?,instruction?}` → `200` 原始音频字节（`Content-Type: audio/<format>`，非 JSON 信封）。空 text → `400`；未接语音 → `500 voice_unavailable`；失败 → `500 tts_failed`；静默空音频 → `500 tts_empty` 且响应头 `X-Voice-Provider: silent`。owner-only + 审计。
U7	POST	`/api/v1/audio/voice-clone`	owner	200 / 400 / 500	声音复刻建音色。body `{url,prefix?}` → `{data:{voiceId}}`。参考 URL 绝不进日志/审计。空 url → `400`；失败 → `500 voice_clone_failed`。
U8	POST	`/api/v1/upload`	owner/admin	201 / 400 / 413 / 415 / 500	图片上传，`multipart/form-data` 字段 `file`（光栅图，单文件字节 ≤ 5 MiB，即 `maxUploadBytes = 5 << 20`）→ `{data:{url,size,mime,name}}`。`url` 是绝对同源 URL，可直接作 `chat.image`（该路径的 5 MiB 在上传时定死，与 `chat.image` 的字符长度判据无关，见 §4.5）。嗅探裁决 png/jpeg/gif/webp/bmp（拒 SVG/HTML）；原始文件名丢弃，用 128-bit 随机名。缺文件/空文件 `400`、超限 `413 payload_too_large`、非白名单 `415 unsupported_media_type`。带审计。
U9	GET	`/api/v1/files/{name}`	无需（能力 URL）	200 / 404	上传文件读取。`name` 仅接受「32 位小写 hex + 白名单扩展名」；路径穿越全形态拒绝。GET 不鉴权是该 URL 为 128-bit 随机能力地址（`<img>`/provider 无法带 token）；任何持有 URL 者可取，勿外泄。
U10	POST	`/api/v1/documents`	owner/admin	201 / 200 / 400 / 413 / 415 / 500	文档上传，`multipart/form-data` 字段 `file`。首次 `201 {data:{name,url,mime,size,sha256,deduped:false}}`；同字节同扩展名重复上传 → `200` + 同 `name` + `deduped:true`（可当成功）。单文件上限 `CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB，`≤0` 用默认）。见 §4.5。
U11	GET	`/api/v1/documents/{name}`	owner/admin（必须 Bearer）	200 / 404	文档读取。与图片读侧刻意相反（必须鉴权）。响应 `Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`，永不内联渲染。名字非法/穿越/不存在统一 `404 document_not_found`。
U12	GET	`/api/v1/sessions/{id}/messages`	owner/admin	200 / 400 / 404 / 500 / 501	热分页历史。query `?limit=&before=&after=&platform=&q=`，见 §4.2。会话不存在/已删除 → `404 session_not_found`；存在但无消息 → `200 {"data":[]}`。
U13	POST	`/api/v1/sessions`	owner/admin	201 / 400 / 501	新建子会话。body 可选 `{personaId?}` → `{data:{sessionId,personaId?}}`（`sessionId="web:<uuid>"`）。未知 personaId → `400`。会话角色创建时固定、之后不可变（见 U15）。
U14	DELETE	`/api/v1/sessions/{id}`	owner/admin	200 / 403 / 500 / 501	删除子会话及其消息 → `{data:{deleted:<id>}}`。主会话不可删 → `403 forbidden`。
U15	PATCH	`/api/v1/sessions/{id}`	owner/admin	200 / 400 / 404 / 500 / 501	会话元数据。body `{title?,pinned?}`（至少一个）。`title` trim、≤80 rune、空/纯空白 → `400 "title must not be blank"`（空串不能清空标题）。`personaId` 键出现即 `400`（任何取值，含 `null`/`""`），且先于会话存在性检查（未知会话 + personaId 也回 `400`）。响应只回显本次变更字段 `{data:{id,title?}}` / `{id,pinned?}`。
U16	POST	`/api/v1/sessions/{id}/read`	owner/admin	200 / 400 / 404 / 500 / 501	推进已读游标。body `{before?}`（毫秒；缺省=现在）→ `{data:{sessionId,readAt}}`。游标会话级单所有者、只进不退（读一处 = 该账号所有端已读）。成功广播 `session_read` 帧；失败不广播。
U17	PATCH	`/api/v1/messages/{id}`	owner/admin	200 / 400 / 404 / 500 / 501	编辑单条消息。body `{content}`（非空、≤4000 rune）→ `{data:<消息 DTO>}`（`data` 直接就是完整消息，不再包一层 `message`）。只改 `content`。成功广播 `message_edited`。
U18	DELETE	`/api/v1/messages/{id}`	owner/admin	200 / 404 / 500 / 501	删除单条消息 → `{data:{deleted:<id>}}`。成功广播 `message_deleted`。
U19	GET	`/api/v1/media/{name}`	owner/admin（必须 Bearer）	200 / 206 / 304 / 401 / 403 / 404 / 416	语音副本播放 / 取字节（v0.67 登记，v0.79 已实现，切片 L45）。`Content-Type: audio/`（按存储名扩展名映射，不查库、不嗅探）；`Content-Disposition: inline; filename="<name>"`；`X-Content-Type-Options: nosniff`；`Accept-Ranges: bytes`；`Cache-Control: private, max-age=86400, immutable`；无 `ETag`（条件请求走 `Last-Modified`）；支持 `Range` 与 `HEAD`；名字非法 / 穿越 / 不存在统一 `404 media_not_found`。⚠️ `416` 不是 JSON 信封（标准库直写 `text/plain` + `Content-Range: bytes /<size>`）。详见 §4.5 语音。

GET /api/v1/files/{name} 无鉴权（能力 URL）；GET /api/v1/media/{name} 与 GET /api/v1/documents/{name} 必须 Bearer owner/admin（与图片读侧「128-bit 名即凭据」的取向刻意相反）；其余全部用户端点至少要求已认证。

2. 管理侧端点与权限矩阵

仅管理面板与授权客户端使用。RBAC owner/admin/viewer；写操作全程审计。本节与 internal/services/gateway/routes.go 逐条一致。

2.0 权限矩阵（口径与计数）

匿名（无 token / token 无效）：任意 /api/v1/admin/* → 401 unauthorized（fail-closed，全部管理路由无一例外）。
角色分档（✅ 放行，❌ 403 forbidden）：

档位	中间件	条数	说明
只读监控档	`viewerAuth`（owner/admin/viewer）	14	非敏感投影：无凭据、无他人账号数据、无消息正文。v0.78 新增两条：面板接入点快照（A13）与插件动作分发（A14，写门落在 handler 内，见 A14 行注）
owner/admin 读档	`writeAuth`（owner/admin）	18	viewer 不得看到的一切：记忆、LLM 栈、账号/key、后台思考、审计链、渠道消息日志、完整会话导出、配置事实面（v0.68）、最近一轮链路图快照（v0.71）、记忆整理试算（v0.75）、入库前审查留痕与回滚（v0.79，B16/B17）、链路图时间轴（v0.80，B18）
owner-only 档	`ownerAuth`（owner）	40	带审计的策略写、每个获取凭据的渠道端点、其余全部变更

管理路由总数 = 14 + 18 + 40 = 72 条。

v0.78 计数变更：viewerAuth 段新增两条（A13 GET /admin/panels、A14 POST /admin/plugins/{id}/actions/{action}）⇒ 12 → 14、总数 66 → 68。A14 走 viewerAuth 中间件，但写动作在 handler 内按 owner/admin 收紧（路由中间件只能有一道门）—— 因此它是本表的一行，读写面却不同档，详见 §2.1 A14 与 §4.14。

v0.79 计数变更：writeAuth 段新增两条（B16 GET /admin/memories/reviews、B17 POST /admin/memories/{id}/revert，切片 L45）⇒ 14 → 16、总数 68 → 70。⚠️ 同批落地的 GET /api/v1/media/{name}（§1.2 U19）是用户侧端点，不进入本矩阵。

v0.80 计数变更：writeAuth 段新增一条（B18 GET /admin/flow/timeline，切片 W1）⇒ 段内实有 18 条、管理路由总数实有 72 条（14 + 18 + 40）。本版一并回补了自 v0.76 起累积的 −1 记账滞后（见下一段），故上表「条数」记 17 → 18、总数记 71 → 72。它只读、不审计，与同族的 B13（GET /admin/flow/graph）同门同档。

✅ 记账滞后已修正（2026-10-06，本版回补）：按上一段「计数口径」那句（= 三张清单列出的行数）核，§2.2 实有 18 行（B1–B18）、§2.1 实有 14 行（A1–A14）、§2.3 实有 40 行 ⇒ 逐行相加 14 + 18 + 40 = 72，与上表「条数」序列（writeAuth 18 / 总数 72）已一致（routes.go 交叉核对：admin 侧经 writeAuth 挂载 20 条，减去 §2.4(a) 按历史口径不计入本表的 channels/events 与 .../counters ⇒ 18）。根因（S6 报告 §6.1 发现）：v0.76 新增 B15 时漏把条数 +1，此后 v0.78 / v0.79 / v0.80 各版沿旧序列 +1 而未回补 ⇒ 那个 −1 滞后从 v0.76 一路带到 v0.80 的登记值。 ⚠️ 上面 v0.78 / v0.79 两个计数段的绝对值仍沿用当时未回补的写法（其增量正确 —— viewerAuth 12 → 14、writeAuth 各版 +1 / +2 —— 但绝对值比真实行数少 1）；§6 里各版条目（v0.76 ~ v0.80）的同类计数同理。按本文件「历史条目保留当时状态」的惯例不逐版改数，以本表 + 三张清单的行数为准。

计数口径（v0.71 明确）：总数是 §2.1 / §2.2 / §2.3 三张清单里列出的行数（与 v0.68 起的口径一致）。⚠️ internal/services/gateway/routes.go 里实际经 writeAuth 挂载的 admin 路由比 §2.2 多：v0.67 登记的 GET /admin/channels/events 与 .../counters（见 §2.4(a)）未计入本表——这是历史口径，本版未改，也未把它算进上面的 18。逐条以代码为准。

⚠️ 与归档版不一致（已更正）：Docs/archive/api-client.v0.65.md §2.0 写「12 + 11 + 38 = 61」（其 v0.62 条目又写「12 + 10 + 38 = 60」，自相矛盾）。以代码为准 = 12 + 11 + 40 = 63。

2.1 viewer 可读（14 条，`viewerAuth`）

#	方法	路径	要点
A1	GET	`/api/v1/admin/personas`	人格清单（含 admin 专属 `thinking` 块）
A2	GET	`/api/v1/admin/sessions`	会话清单
A3	GET	`/api/v1/admin/plugins`	能力/插件清单
A4	GET	`/api/v1/admin/plugins/installed`	已安装插件清单
A5	GET	`/api/v1/admin/channels`	渠道清单。`accounts[]` 各元素可能带可选 `connected:bool`（v0.66）：该账号自己的适配器是否已连接；键缺席 = 状态未知（该账号没有活适配器），不等于「未连接」—— 面板据此决定是否给「断开」按钮。v0.67 已实现（本次落地；落地前基线 `f91a83f`）：各元素另可能带可选 `accountOnline:bool`（账号在平台上是否在线，与 `connected` 是两件事；键缺席 = 状态未知 ≠ 离线）—— 见 §2.4(b)；各元素可能带可选 `directMsgPerMin:number`（v0.69 新增，已实现）：该账号非主人私聊（陌生人）每分钟每发送者上限，是账号顶层字段（与 `groupMsgPerMin` 同一条写路径，不在 `config` 里）。语义：键缺席或 `0` ⇒ 保护性默认 6 条/分（陌生人必须有流控，缺省绝不解释成「关闭」）、正值 ⇒ 该值、负值 ⇒ 关闭该限制（主人的显式选择）。⚠️ 因 `omitempty`，`0` 与未设置线上同形（既有约定，未改）不含任何凭据
A6	GET	`/api/v1/admin/iot`	IoT 设备清单
A7	GET	`/api/v1/admin/automations`	自动化与提醒清单
A8	GET	`/api/v1/admin/rag`	知识库文档清单（名字/描述 + 切分/嵌入状态）；`?query=` 搜索亦只读
A9	GET	`/api/v1/admin/observability/metrics`	运行时指标快照
A10	GET	`/api/v1/admin/observability/trace`	运行时 span
A11	GET	`/api/v1/admin/observability/logs`	后端日志尾部（最新优先，`?level=&limit=`；缓冲未注入时 501）
A12	GET	`/api/v1/admin/notifications`	统一通知 feed（审计链 + 后台思考推送的只读投影）
A13	GET	`/api/v1/admin/panels`	插件管理面板接入点快照（v0.78 新增，切片 PLG-2）：按调用者角色过滤后的导航条目集合 —— viewer 只拿到只读区块（`status`/`log`/`table`，且 table 的行内动作被摘空、`form` 整体不出现、区块全空的面板整条不出现）。响应 `{data:{role,groups[],pluginIds[]}}`。未接面板中枢 → `501 panels_unavailable`（绝不回空列表）。形状与两条给客户端的口径见 §4.14(a)
A14	POST	`/api/v1/admin/plugins/{id}/actions/{action}`	插件动作分发（v0.78 新增，切片 PLG-2）。⚠️ 读写面不同档：路由走 `viewerAuth`，但写动作在 handler 内按 owner/admin 收紧（`form.submit` / `table.rowActions` 是写；`table`/`log` 的 `source` 与下拉 `optionsFrom` 是读，对 viewer 开放）。只接受该插件声明过的动作名（未声明 ⇒ `404 action_not_declared`，不是「没权限」）。请求体可选 JSON（空体 ⇒ `payload=null`）；宿主不接受任何来自声明的请求地址（不给插件开 SSRF 面）。✅ v0.79：生产执行器已接线（切片 L1/PLG-2）—— 内置 `web-search` 的四个动作 + 候选来源 `plugin.providers` 都已登记生产处理器，真可用（真读写可变源、探针真发一次 HTTP）；只有「已声明但宿主未登记处理器」才回 `501 action_not_implemented`（不再是兜底档）。错误码与响应形状见 §4.14(b)(c)

A13 / A14 的角色门依据（routes.go 紧邻注释）：快照端点对 viewer 开放是因为它回的本来就是被裁掉写面的只读投影；动作端点的读来源动作对 viewer 可见，写门落在 handler 内（路由中间件只能有一道门）。panels_changed 帧（§3.4.5）不进 frameReachesAll 白名单 ⇒ viewer 收不到该帧，需自行刷新/轮询重拉 A13。

2.2 owner/admin 读（18 条，`writeAuth`）

#	方法	路径	要点
B1	GET	`/api/v1/admin/memories`	记忆条目（含他人账号数据）
B2	GET	`/api/v1/admin/channels/messages`	适配器消息日志，`?adapter=&platform=` 三档粒度（`before`/`limit`）
B3	GET	`/api/v1/admin/channels/{platform}/messages`	单平台跨隔离会话消息（最新优先）
B4	GET	`/api/v1/admin/llm`	LLM provider 栈（组 DTO，含 `contextWindow` 等）
B5	GET	`/api/v1/admin/llm/usage`	LLM 用量汇总（切片 U1，v0.64）。`?since=&until=&purpose=`；缺省近 24h、跨度上限 90 天（超 → `400`）；`hitRate = cacheHit/(cacheHit+cacheMiss)`，分母 0 ⇒ `0`。不含凭据与消息正文。未接线 → `500 usage_unavailable`
B6	GET	`/api/v1/admin/llm/catalog`	模型目录候选（`?refresh=1` 强制在线刷新）。既无快照又抓不到 → `503 catalog_unavailable`
B7	GET	`/api/v1/admin/users`	账号/API key 清单
B8	GET	`/api/v1/admin/backthink`	后台思考记录。每条可能带可选 `urgency`（`"routine"`/`"warning"`/`"critical"`，`internal/urgency` 词汇；默认是精确档位，带 `urgencyLowerBound:true` 时才是下限，见 §4.10(b)）与可选 `quietHoursBypassed:true`（该轮穿透了安静时段）—— v0.68 新增；档位的精确语义与 `urgencyLowerBound` 为 v0.70
B9	GET	`/api/v1/admin/observability/audit`	审计链
B10	GET	`/api/v1/admin/sessions/{id}/export`	完整会话导出
B11	POST	`/api/v1/admin/rag/query`	知识库检索（带审计的读型 POST）
B12	GET	`/api/v1/admin/config-facts`	配置事实面（v0.68 新增，只读；v0.75 追加 3 键；v0.77 追加 1 键）：记忆整理 8 键 + 后台思考心跳 3 键（`ENABLE_BACKGROUND_THINKING`/`THINK_INTERVAL_SEC`/`THINK_QUIET_INTERVAL_SEC`）+ 安静时段 `QUIET_START_HOUR`/`QUIET_END_HOUR` 的进程生效值，逐条带 `default`/`isDefault`。不含任何密钥/令牌值（连「是否已配置」都不回凭据类的）。形状见 §4.10
B13	GET	`/api/v1/admin/flow/graph`	链路图快照 / 多轮历史回放（v0.71 新增；v0.73 增量；v0.77 增量），只读、不审计。`?sessionId=`（省略 = 主会话 `web`）+ v0.73 新增 `?turnId=`（省略 = 最近一轮，先内存后落盘）。响应 `{data:{sessionId,turnId,source,graph,lanes[],turns[]}}`：`graph` 是一份 §3.4.5 `graph_update` 同形快照，没有该轮时如实为 `null`（绝不画假图）；`source` ∈ `live`（内存最近一轮）/`persisted`（落盘的历史轮）/`none`；v0.77 新增 `lanes[]`（最近一轮每一路的图，每项 `{turnId,graph}`，按路的开始时间升序，恒为非 null 数组 —— 真并行时这才是全貌，`graph` 只给最新一路），`graph` 的既有语义一字未改 ⇒ 老读取方零改动；`turns[]`（`{turnId,createdAt}`，最新在前）供面板选历史轮（v0.73）。未接线图源 → `500 flow_unavailable`。语义见 §4.11
B14	POST	`/api/v1/admin/memories/tidy/dry-run`	记忆整理「试算」（v0.75 新增，只读语义的 POST）：跑同一套整理规则、把候选直接回在响应里，零副作用（不写任何表）。请求体可为空。响应 `{data:{dryRun:true,recallMode,durationMs,ruleVersion,partitions,scanned,compared,pairs,vetoed,vetoReasons,truncated?,candidates[]}}`；`candidates` 恒为非 null 数组（空数组 = 「算过了，没有建议」，与「没算出来」的错误响应必须能区分）。失败：未接线 → `500 tidy_unavailable`、配置关闭 → `409 tidy_disabled`、语义召回不可用 → `500 tidy_recall_unavailable`、超时 → `503 tidy_timeout`。不审计（只读计算）。语义与形状见 §4.12
B15	GET	`/api/v1/admin/memories/tidy/dry-run/{runId}`	异步试算结果查询（v0.76 新增 · ✅ 已实现（v0.77 校正））：配合 `POST …/memories/tidy/dry-run?async=1`（后者仍属 B14，`async=1` 时回 `202` + `{data:{runId,status:"running",startedAt}}`）轮询取回结果。响应 `{data:{status:"running"｜"done"｜"failed", result?, error?}}`：`running` 时 `result`/`error` 两键都缺席（绝不回一个空 `result` 冒充「跑完了但没有建议」）；`done` 时 `result` 与 §4.12 同步响应的 `data` 逐字节同形（同一套 JSON，不是第二份）；`failed` 时 `error` 为 `{code,message}`（`code` 沿用 §4.12 的失败码）。⚠️ 结果只活在进程内存（单二进制、零跨进程）：TTL 30 分钟（从完成时刻起算）、同时只允许 1 个在跑（第二个请求复用既有 `runId`，不引入新错误码）；进程重启后旧 `runId` 如实失效 ⇒ `404 tidy_run_not_found`，绝不假装还在跑。鉴权与 B14 同档（`writeAuth` = owner/admin）、同样不审计。语义见 §4.12.1
B16	GET	`/api/v1/admin/memories/reviews`	入库前审查（D3）留痕列表（v0.79 新增，切片 L45；✅ 已实现）。`?limit=`：缺省 100、`≤0` 同缺省、> 500 钳到 500、非整数 → `400 bad_request`（钳位不报错，与渠道事件查询面同一约定）。响应 `{data:[…]}`，元素键 camelCase：`id` / `itemId` / `personaId` / `scope` / `projectId`（可选）/ `decision` ∈ `skip\|merge\|modify\|create` / `reason`（可选，规则依据）/ `veto`（可选，命中的否决规则）/ `targetId`（可选，命中的既有条目）/ `mergedIds`（恒为数组）/ `score` / `recallMode`（可选）/ `degraded` / `ruleVersion` / `sessionId`（可选）/ `createdAt`（UTC RFC3339）。🔴 不含记忆正文（命中的 id 由客户端回表取原文）。未接线 → `500 memory_review_unavailable`（绝不回空数组假装没有留痕）；读取失败 → `500 reviews_failed`。只读、不审计
B17	POST	`/api/v1/admin/memories/{id}/revert`	撤销一次软合并（v0.79 新增，切片 L45；✅ 已实现；design/23 §8「回滚」）。无请求体。200 `{data:{reverted:"<id>"}}`；该行不在 `merged` 状态（id 拼错 / 已回滚过）→ `404 not_found`；未接线 → `500 memory_review_unavailable`；存储失败 → `500 revert_failed`。无损可逆：被吸收行复原为 `active` + `merged_into=''`，并从存活行 `merged_from` 摘除、`merge_count` 减 1（下限 1）；行永不物理删除。落审计 `memory.review.revert`（who / result ∈ `ok\|error`；只记 item id，不记正文）。⚠️ 门是 `writeAuth`（owner\|admin）；`design/23 §11` 表格对同族 `candidates/{id}/revert` 标的是 owner-only —— 口径差异待主会话裁决（若以设计为准，路由换成 `ownerAuth` 即可）

| B18 | GET | /api/v1/admin/flow/timeline | 链路图时间轴 / 多轮串联（v0.80 新增，切片 W1），只读、不审计。?sessionId=（省略 = 主会话 web）+ ?limit=（缺省 50、> 200 钳到 200、非整数 400 bad_request、≤0 同缺省）+ ?before=（游标：取开始时刻严格早于它的轮次；省略 = 最新那一页；取值 = 响应里的 nextBefore，也接受 RFC3339 或 Unix 毫秒，非法 → 400 bad_request）。响应 {data:{sessionId,source,rounds[],nextBefore,hasMore,truncated,retentionHours,retentionEnabled}}：rounds 按时间正序（最早在前），每项 {turnId,round,startedAt,endedAt,lanes[]}（lanes[] 每项 {turnId,graph}，graph 与 graph_update 同形）；round 为 null = 未知（老行），endedAt 为空串 = 尚未收尾（在飞轮）；source ∈ persisted（本页至少一轮来自落盘）/live（本页全部来自内存）/none。未接线（内存 + 落盘都没接）→ 500 flow_unavailable。语义与空态见 §4.11.1 |

读取 GET /admin/observability/{logs,metrics,trace} 兼任可观测推送的订阅握手（该凭据的连接全部断开即退订）。REST 响应形状不变。

2.3 owner-only（40 条，`ownerAuth`）

#	方法	路径	要点
C1	POST	`/api/v1/admin/plugins/policy`	设置能力可达性标记（工具策略，落盘 `tool_policies`）
C2	POST	`/api/v1/admin/personas`	创建人格
C3	PUT	`/api/v1/admin/personas/{id}`	更新人格（`identity.systemPrompt` 必填，缺失/空白 → `400`）
C4	GET	`/api/v1/admin/owner-profile`	主人档案读取
C5	PUT	`/api/v1/admin/owner-profile`	主人档案写（落盘 `configs/users/owner.yaml` + 热更新活档案；审计 `owner.profile.update`）
C6	POST	`/api/v1/admin/users`	创建账号
C7	POST	`/api/v1/admin/users/apikey`	签发 API key（明文仅返回一次）
C8	DELETE	`/api/v1/admin/users/apikey/{id}`	吊销 API key
C9	POST	`/api/v1/admin/iot/{id}/control`	控制设备
C10	POST	`/api/v1/admin/iot/scenarios`	IoT 场景写
C11	POST	`/api/v1/admin/iot/rules`	IoT 规则写
C12	POST	`/api/v1/admin/automations`	创建自动化
C13	POST	`/api/v1/admin/automations/reminders`	创建定时提醒（到点发 `reminder.trigger`）
C14	POST	`/api/v1/admin/automations/{id}/run`	手动运行自动化
C15	DELETE	`/api/v1/admin/automations/{id}`	删除自动化
C16	POST	`/api/v1/admin/llm`	添加/更新 LLM provider（写 `models.json` + 热重载）
C17	POST	`/api/v1/admin/llm/test`	连通性测试
C18	POST	`/api/v1/admin/llm/reset-from-env`	重置为 env 默认（切片 R1，v0.62；body 必须 `{"confirm":true}`，否则 `400` 且一个字节都不动；审计 `llm.resetFromEnv`）
C19	POST	`/api/v1/admin/channels/open`	打开渠道（v0.66 增 `accountId`，见下注）
C20	POST	`/api/v1/admin/channels/close`	关闭渠道（v0.66 增 `accountId`，见下注）
C21	POST	`/api/v1/admin/channels/test`	渠道连通测试
C22	GET	`/api/v1/admin/channels/{platform}/login-qr`	取登录二维码（获取凭据，故 owner-only）
C23	GET	`/api/v1/admin/channels/{platform}/login-status`	查扫码登录状态
C24	GET	`/api/v1/admin/channels/{platform}/view`	平台专属只读视图
C25	GET	`/api/v1/admin/channels/{platform}/friends`	好友/联系人清单
C26	POST	`/api/v1/admin/channels/{platform}/friend/handle`	好友申请处理
C27	POST	`/api/v1/admin/channels/{platform}/message/test`	发测试消息
C28	PUT	`/api/v1/admin/channels/{platform}/config`	保存渠道账号配置（按 id patch 语义，见 C29 注）
C29	DELETE	`/api/v1/admin/channels/{platform}/config`	删除渠道账号。必须显式寻址：`?id=<账号 id>` 或 `?empty=1`（v0.66），见下注
C30	POST	`/api/v1/admin/plugins/install`	安装插件
C31	POST	`/api/v1/admin/plugins/uninstall`	卸载插件
C32	POST	`/api/v1/admin/memories`	写记忆
C33	POST	`/api/v1/admin/memories/search`	搜记忆
C34	POST	`/api/v1/admin/rag`	索引文档（切分 + 嵌入）
C35	POST	`/api/v1/admin/rag/delete`	删文档（项目条目 + 级联章节）
C36	POST	`/api/v1/admin/system/revoke-keys`	全部吊销 API key
C37	POST	`/api/v1/admin/system/rotate-jwt`	轮换 JWT 密钥
C38	POST	`/api/v1/admin/system/backup`	备份
C39	POST	`/api/v1/admin/system/restore`	恢复
C40	GET	`/api/v1/admin/system/storage`	存储状态只读（v0.60）。`{data:{main,documents,vector}}`；不含凭据；未接活连接 → `500 storage_unavailable`

C28 的 patch 语义（v0.54 起）：config 内键省略 = 保留已存值；给出非空值 = 覆盖；显式 null/"" = 清除该键（0/false 是真实取值，不算空）。顶层便捷字段（token/baseURL 等）只在非空时并入补丁，要清 bot_token 必须走 config 的显式 null/""。 C28 的账号级限流字段（v0.69 修正）：groupMsgPerMin / msgPerMin / maxMessages / directMsgPerMin 都是账号顶层字段（不在 config 里，C28 的 patch 三态不适用于它们）。它们是值语义：请求体省略 ⇒ 0 = 未设置（对 directMsgPerMin 即保护性默认 6 条/分）。要保住已设的值必须把它回送；面板先由 GET /admin/channels 回显、再原样写回（frontend/web/src/admin/modules/channels/channelUtils.ts 的 limitInitialOf / limitRequestBody）。⚠️ v0.68 及更早的后端完全忽略 directMsgPerMin：老客户端不受影响，但要表达「关闭流控（-1）」必须对 v0.69+ 后端发。 C18 破坏性：只覆盖 .env 声明过非空值的键（provider/baseUrl/apiKey/model/contextWindow），fallback/multimodal/maxTokens/reasoning/personaModels 永不被改；组集合不增减。 C19/C20 的 accountId（v0.66，多账号平台必需）：请求体 = {name, accountId?}（name 必填：平台名或精确适配器名）。

给出 accountId ⇒ 只驱动该账号的适配器（账号 id 非敏感；"default" 映射到该平台的裸适配器名，即无 id 账号的注册口径）。账号完全不存在 ⇒ 404 account_not_found（文案附该平台已知账号 id 列表）；账号已配置但当前没有活适配器 ⇒ 409 account_not_registered（常见原因：缺该账号必需凭据、或保存后尚未重载）。两种都零连接，绝不静默回落到第一条（「点了连接却连上别的账号」正是此改动要修的缺口）。

缺省 accountId ⇒ 平台级旧语义（老客户端零影响）：精确同名适配器 → 该平台 channels.json 有效配置顺序第一条 → 裸平台名兜底；仍找不到 ⇒ 404 not_found。⚠️ 第 2 步在 v0.66 起是确定性的（此前走注册表 map 顺序，多账号平台上每次可能落到不同账号）。

响应（open/close 同形）：{data:{name, resolved, connected, accountId?}} —— name 是请求里的名字（旧契约不变），resolved 是实际被驱动的适配器注册名（多账号平台上与平台名不同），accountId 仅在请求指定时回显，connected 为操作后的状态。凭据永不出现。审计动作名不变（channel.open / channel.close）。 C29 的两种寻址（v0.66，都必须显式给出）：

?id=<账号 id> ⇒ 删该 id 那一条。⚠️ id 不存在时仍回 200（removed:1），与「刚删过」不可区分 —— 客户端按幂等处理。

?empty=1 ⇒ 删该平台上全部无 id 的历史条目（这类条目改不动：带空 id 保存会被当成新账号另开一条）。无可删 ⇒ 404 not_found，不写盘、不重载、不假装删过。

id 与 empty=1 同时给出 ⇒ 400 bad_request；两者都缺 ⇒ 400 bad_request（绝不把「id 缺失」默认解释成删无 id 条目 —— 那是一次没有字面证据的批量删除）。?empty= / ?empty=0 / ?empty=false 一律是「否」。

响应：{data:{persisted, path, platform, accountId, empty, removed}}（empty/removed 是 v0.66 新增）；removed = 实际删除的条目数。删空后平台键整个消失（与按 id 删除的收尾口径一致）。

2.4 v0.67 登记的管理面（渠道事件查询 + 账号在线状态）—— (a) 已实现 / (b) 已实现；v0.78 追加 (c) iLink 凭据三态

⚠️ 本节两项都已落地（账号在线状态 52dac45；渠道事件查询面本切片 E6）：形状取自设计文档（design/26 §4.5、§2.6），落地时已按代码核对。§2.0 的计数（12 + 11 + 40 = 63）原本不含本节端点；两个渠道事件端点已登记进 routes.go（owner|admin 档），下版改文档时应把它们并入 §2.1/§2.2 并更新计数。本行留在此处仅为与 v0.67 冻结版对照。

(a) 渠道事件（非消息事件）只读查询 —— 已实现

#	方法	路径	要点
D1	GET	`/api/v1/admin/channels/events`	非消息事件列表（倒序）。query：`platform` / `tier` / `category` / `channelId` / `since` / `until` / `limit` / `offset`。响应 `{data:{events:[…], total}}`。`since` / `until` 按 UTC ISO-8601 定宽字符串做字典序比较（与 `GET /admin/llm/usage` 同口径）；跨度上限 90 天（超 → `400`）；`platform` 未知 → `400`。不含正文、不含任何媒体 URL、不含任何凭据 / `flag`
D2	GET	`/api/v1/admin/channels/events/counters`	逐类计数汇总（近似值）。query：`platform`。响应 `{data:{approx:true, counters:[{platform,accountId,tier,category,platformType,count,firstSeenAt,lastSeenAt}]}}`，`approx:true` 如实标注「计数为聚合近似值」（计数是内存聚合 + 周期 flush，非逐条实时）。落地口径：`approx` 与 `counters` 同级（都在 `data` 内，见 §7.4-11 的落地记录）

RBAC 档位已定（落地口径）：两个端点走 owner|admin（writeAuth），与同族的渠道消息日志面（§2.1 B2/B3、/admin/channels/messages）同档 —— 事件行带群 id / 成员 id / 关联消息 id，属私有内容面，不是给 viewer 的监控投影。viewer 为 403（已进 rbac_viewer_test.go 的 ownerAdminReadRoutes 覆盖）。
参数缺省与错误码（落地口径，见 §7.4-11）：limit ≤0 或未给 ⇒ 用存储层缺省 100；超硬上限 ⇒ 钳到 500（不报错，total 仍如实给出筛选条件下的总条数）；非法整数（如 limit=abc）⇒ 400 bad_request；since/until 非法 ⇒ 400 bad_request；platform 未知 ⇒ 400 bad_request；tier 非 t1/t2/t3 ⇒ 400 bad_request。⚠️ category 不做白名单校验：类别轴的权威在适配器层且会持续增加，未知类别是一次精确匹配（返回空），不是 400。
时间窗缺省（落地口径）：没给 since/until 就不注入时间条件（不是「近 24h」）—— 端点绝不替客户端造一个下界（那正是「静默裁剪」）。只给 since 时按「现在」判跨度（超 90 天 ⇒ 400），但不把「现在」写进过滤条件。
数据源两张表（design/26 §4.1，表名复数）：channel_events（tier 为 t2/t3 的事件与所有 unknown 逐条留存，参与保留期 GC）与 channel_event_counters（t1 与所有帧的计数，按 (platform, account_id, platform_type) upsert，不参与 GC）。
tier 取值域：t1（只计数）/ t2 / t3（逐条留存；T3 是「谁对谁做了什么」的定向交互记录）。category 取值域（归一化类别，设计原文给出 heartbeat / lifecycle / join / leave / recall / ban / admin / friend_request / group_request / poke / reaction / button / vote / item / link / unknown，并在末位带 … ⇒ 非穷举，客户端未知取值原样展示、不报错）。
events[] 元素 = 一条 channel_events 行的投影。落地口径（见 §7.4-9）：键名一律 camelCase，逐字如下 —— id / platform / accountId / tier / category / platformType / channelId / channelType / groupId / actorId / actorRole（owner/member/system/unknown，结构化解析所得）/ targetId / selfRelated（bool）/ messageId / summary / createdAt / updatedAt（后两者是 UTC RFC3339，与 llm/usage 的时间回显同口径）。actorId/targetId 是 id 不是昵称；summary 是固定文案（如「群成员加入」，不含任何平台原文）。无数据时 events 是 []（不是 null）。
未接线存储时：两个端点都回 500 channel_events_unavailable（对齐 usage_unavailable / storage_unavailable 的诚实边界口径，绝不回全 0 假汇总）。读库失败同样是 500 channel_events_unavailable（错误文案不同）。
三个新 env 键（design/26 §4.4，已登记进 §5）：CHANNEL_EVENT_RETENTION（默认 720h）、CHANNEL_EVENT_GC_INTERVAL（默认 1h）、CHANNEL_EVENT_COUNTER_FLUSH（默认 30s）。
⚠️ 微信渠道不提供非消息事件：查询面 / 面板对该渠道如实显示空 + 说明文字，绝不伪造、绝不用别的渠道事件顶替（落地时已有测试钉住：platform=weixin-ilink 的响应里绝不出现别的平台的事件）。

(b) `GET /api/v1/admin/channels` 的账号项：`accountOnline`

accounts[] 元素可能带可选 accountOnline:bool（v0.67 登记，已实现 —— 管理面已落地，见 §7.2）：该账号在平台侧是否在线。
与 connected 是两件事（这是本案的全部理由）：connected = 本项目的适配器是否连着（WS 会话连通）；accountOnline = 账号本身在平台上是否在线。OneBot 实现（NapCat 等）的进程与正向 WS 可以一直连着，而背后的 QQ 账号已经掉线 —— 此时 connected:true 而 accountOnline:false，消息既收不到也发不出。
三态（known 口径）：accountOnline:true = 确知在线；accountOnline:false = 确知离线；键缺席 = 状态未知（尚未探到：探活未接线 / 刚启动 / 一直失败 / 该平台没有独立账号状态面）。绝不可把「未知」画成「离线」，也不可画成「在线」—— 那正是 2026-10-05 事故里「面板仍显示已连接、日志一片空白」的同一类坑。
状态源：AccountStatus()（plugins/channels/qq_obv11/probe.go），其 known 区分「确知离线」与「尚未探到」；本字段的缺席即承载 known=false。当前只有 qq-obv11 有这条独立状态面：周期约 60s 主动探活 OneBot get_status（读 {online, good}），与上游可配的 meta_event 心跳并列（心跳优先、探活兜底），只在状态变化时记一条带 source 的日志。
已实现口径（本次落地）：管理列表按可选接口断言读它 —— 适配器实现了 AccountStatus() 才读，否则键缺席；known=false 时同样键缺席（绝不用 false 冒充离线）。不另发 known 同级键：缺席本身即承载 known=false。当前只有 qq-obv11 会带该键（telegram / webhook 等没有独立状态面）。
⚠️ 字段名（accountOnline）是本契约所拟：设计只规定「独立状态面 + AccountStatus() + known」，未给管理面字段名（见 §7.4-13）。实现沿用了本契约所拟的名字（未改名）。

(c) `GET /api/v1/admin/channels/{platform}/login-status` 的账号项：`authState` / `authDetail`（v0.78 新增，切片 CODE-F3，已实现）

该端点响应新增可选 authState:string + authDetail:string（omitempty）：该账号会话凭据的三态与如实的中文说明。无新端点、无新路由（沿用既有扫码登录状态端点，owner-only，v0.39 起就有）。
取值是闭集："active"（有效：iLink 接受过当前凭据）｜"rejected"（被拒：iLink 以 errcode=-14 拒绝/作废了这份会话凭据，需要重新扫码绑定）｜"unknown"（未知：没有凭据，或有凭据但还没有一次被 iLink 接受的调用可以作证）。
与 status 是两件事（本字段的全部理由）：status 是扫码登录流程的状态机（idle/waiting/confirmed/failed/need_verifycode）；authState 是凭据在 iLink 侧是否有效的结论。一次 confirmed 的扫码只说明「拿到了凭据」—— 它是否被接受要等一次成功的调用（那时 authState 才从 unknown 变 active）。因此允许出现 status:"confirmed" 且 authState:"unknown"：这是事实，不是矛盾。
🔴 errcode=-14 是「被拒」不是「过期」：iLink 的 bot token 是长期凭据（实测一个月前扫码得到的 token 仍可用）；-14 表示 iLink 不再接受这个会话（已解绑 / 在别处重新登录 / 协议层拒绝），不是时间性过期。authState:"rejected" 的说明只说「已被 iLink 拒绝，需要重新扫码绑定」。未知同样绝不许写成「过期」（也不许写成「未连接」）—— 服务端文案已由测试钉死（响应体全文不得出现「过期」）。
键缺席 ≠ unknown：适配器没有这条状态面时两个键缺席（缺席 = 该账号没有这个状态面）；"unknown" 是值，表示有状态面但尚未确认 —— 面板必须能区分这两件事。
数据源 = 适配器的可选能力接口 SessionStatus() (state, detail string)（plugins/channels/weixin_ilink/session_status.go），网关经类型断言读取（internal/services/gateway/admin_channel_status.go 的 sessionStatusAware，穿 namedAdapter 包装）。当前只有 weixin-ilink 会带这两个键；其它平台字段缺席，行为一字不变。
authDetail 绝不含任何凭据。
行为变更 / 破坏性：无（两个键可选、纯增量；status / botId / botToken / err 与 v0.39 起逐字一致）。
🔴 同域但未实现的面：GET /api/v1/admin/channels 的 accounts[] 元素尚未带每账号 authState/authDetail（缺 AdminChannelAccount 两字段与合并器的接线）—— 见 §7.2。
⚠️ 未确证（真机）：真实 errcode=-14 至今从未在日志里观测到 ⇒ rejected 分支只有单测 / httptest 证据，没有真机证据（见 §7.4-26）。

3. WebSocket `/ws/chat`

3.1 握手

GET /ws/chat，凭据取自 ?token=<JWT> 或 Authorization: Bearer <JWT>（只认 JWT）。
校验失败：升级前回 401 {"error":{"code":"unauthorized",...}}。
方法非 GET → 400 bad_request。
帧大小：读上限 4096 字节/帧（wsReadLimit）。超限由传输层直接断连 —— 因此真实音频/图片二进制必须走 REST，WS 只发小载荷。
keepalive：服务端周期 Ping（54s），客户端应回 Pong；读超时 60s。
非 JSON 帧 → 定向 {"type":"error","data":{"message":"invalid json"}}（连接保留）。

3.2 握手 `history` 回放（角色门：只发 owner+admin）

连接注册后，仅当该连接是 owner/admin 时，服务端定向发送一帧：

{"type":"history","sessionId":"web","data":{"messages":[ <historyMessage> ... ]}}

内容 = 主会话最近 50 条（wsReplayLimit），thinking 恒缺席（见 §3.4.4 口径更正）；每条可能带可选 turnId（v0.66，空则键省略）。🔴 voice 不在握手回放里（v0.67 登记时曾计划覆盖）：v0.79 的 voice 只填在 4 个 REST 读取面 + message_edited，握手 history 回放不带该键（见 §6 v0.79 ③ / §4.4 / §7.2）。
viewer 连接完成握手时完全不做回放（其只读窗口是 REST 监控面）。
回放是尽力而为：存储未接或读出错静默跳过。

3.3 上行帧（客户端 → 服务端）

角色门（fail-closed）：只有 owner/admin 连接可以发送任何应用内上行帧。非 owner/admin 发任何上行 JSON 帧 → 定向回 {"type":"error","data":{"code":"forbidden"}}（只到发送者，不广播、不驱动模型、不落库）。该门是 route() 的第一条语句且默认拒：未登记的新帧类型在显式登记前一律被拒。协议级帧（ping/pong/close）由 gorilla 内部处理，不受影响。

帧壳：{"type":"<type>","reqId?":"<string>","data":{...}}。reqId 保留未用。

type	data	语义
`chat`	`{sessionId?,text,image?,deviceId?,mode?,clientMsgId?,documents?,parallel?}`	会话消息。与 REST `POST /chat` 同形。见 §4.6。
`interrupt`	`{sessionId,scope?,turnId?}`	打断。见 §4.8。
`voice_input`	`{audio,format?,text?,sessionId?,deviceId?,clientMsgId?}`	语音回合：STT → 编排器 → 结算时 TTS 定向回本连接。见 §4.5。
`mode_switch`	任意（透传）	行为模式广播；服务端以 `mode_switch` 下行帧回放给（owner/admin）连接。
`subagent_ask`	`{id,mode?,n?,query?}`	审计某子代理上下文。`mode` ∈ `""/full/tail/keyword`。定向回 `subagent_event`；未接 auditor → `error {"message":"subagent audit unavailable"}`。
`task_output_query`	`{taskId}`	取任务输出。定向回 `task_output`；未接 task store → `error {"message":"task output unavailable"}`。

上行错误应答（均定向，{"type":"error","data":{...}}）：

情形	data
非 owner/admin 发送任意上行帧	`{"code":"forbidden"}`
未知 type	`{"message":"unknown event type"}`
非 JSON	`{"message":"invalid json"}`
`interrupt` scope 非法	`{"code":"bad_request"}`
`interrupt` 指定 `turnId` 不存在（仅 scope:"current"）	`{"code":"bad_request"}`
`chat` 待处理队列满	`{"code":"chat_busy","message":...,"sessionId":...,"clientMsgId?":...,"messageId?":...}`（只发发送者；同时广播 `pending_full` 状态帧）
`chat` 携带的文档不合法	`{"code":"<too_many_documents\|document_not_found\|chat_documents_unavailable>"}`
`voice_input` 无 audio 也无 text	`{"message":"voice audio or text required"}`
`voice_input` 未接语音服务	`{"message":"voice unavailable"}`

3.4 下行帧（服务端 → 客户端）与角色门

唯一投递入口 hub.broadcast 即角色门：它按帧类型查 frameReachesAll 表决定受众。

全员白名单（7 个「状态机信号」，owner/admin/viewer 都收）：session_busy、pending_ack、pending_drain、session_idle、session_interrupted、pending_full、session_read。它们只报告会话忙闲/游标，不含任何内容。

其余全部下行帧 = fail-closed 默认档：只发 owner + admin。新增帧类型在有人显式登记前一律落此档（漏分类不泄露内容）。

分类表在 internal/services/gateway/ws_frame_scope.go，扩白名单属契约变更。

帧壳：{"type":"<type>","turnId?":"...","seq?":<int>,"sessionId?":"...","data":{...}}（turnId/seq 为空则键省略）。

3.4.1 全员白名单（7 帧）

type	帧壳	data	说明
`session_busy`	sessionId	`{sessionId,mode,activeTurns}`	会话转忙。`mode` ∈ `thinking/executing/subagent`
`pending_ack`	sessionId	`{sessionId,mode,queueDepth,reason?}`	忙时消息入队。`reason` 仅在显式声明 `parallel` 却落回排队时出现，取值 `"parallel_limit"`
`pending_drain`	sessionId	`{sessionId,mode:"thinking",queueDepth,activeTurns}`	续跑弹出队首
`session_idle`	sessionId	`{sessionId,mode:"idle",activeTurns:0}`	转空闲。时点收紧（v0.65）：所有在途路收尾且 pending 空才发（单路时与旧行为逐字相同）。见 §4.6
`session_interrupted`	sessionId	`{sessionId,mode,dropped,cancelledTurns,activeTurns}`	打断结果。`scope:"all"` ⇒ `mode:"idle"`、`dropped`=清空的 pending 数、`activeTurns:0`；`scope:"current"` ⇒ `mode` 是当时忙碌通道（非 idle）、`dropped:0`
`pending_full`	sessionId	`{sessionId,mode,max,clientMsgId?,messageId?}`	队列满（`max` 为上限）。`clientMsgId` = 被拒消息的幂等键（未携带则键缺席）；`messageId` 仅当该消息此前已落库/已认领时出现（服务端绝不在此处新铸 id）
`session_read`	sessionId	`{readAt}`	已读游标推进（毫秒）。同账号所有端据此清角标

3.4.2 结构化流帧（owner+admin；帧壳带 sessionId + turnId + seq）

type	data
`message.start` / `message.delta` / `message.end`	`{index, delta?, streamId?}`
`thinking.start` / `thinking.delta` / `thinking.end`	`{index, delta?, streamId?}`
`tool_call.start` / `tool_call.delta` / `tool_call.end`	`{id, index, delta?, streamId?}`
`tool_execution.start` / `tool_execution.update` / `tool_execution.end`	`{tool, phase, id?, delta?}`（`phase` ∈ `running/done/error`；phase 绝不塞进 delta）
`turn.start` / `turn.end`	无 data（帧壳即边界信号）
`stream_chunk`	`{delta}`（非流式路径的单段文本）
`stream_end`	`{stopReason, steps?, error?}`

streamId（可选）= 同一次模型流（一次 ChatStream 调用）的多帧关联键；turnId = 整个回合恒定。两者分工不同。 tool_execution.update：wire 映射已实现，但工具分发器目前没有中途进度上报源，故实际暂无生产者（start/end 真实发出）。

3.4.3 编排帧（owner+admin）

type	帧壳	data	说明
`turn_begin`	sessionId + turnId	`{kind,messageIds,leg,activeTurns}`	每起一路（含续跑路）恰好发一帧（v0.66 落地）。`kind` ∈ `"turn"`（新回合/续跑）/`"parallel"`（显式并行且照准，仅供展示）；`messageIds` = 该路已落库用户消息的权威 id 数组（可为空数组，恒为数组不为 null）；`leg` = 会话内路序号（1 基，会话内单调递增）；`activeTurns` 同忙态帧。客户端据此把气泡置「已受理·回答中」并按 `sessionId + turnId` 两级分桶；服务端口径是「按 `messageIds` 是否含本气泡的 `messageId`」判定归属，`kind` 不是判据。
`steer_ack`	sessionId + turnId	`{messageId,atStep}`	忙时新消息被在飞回合吃进同一回合：`messageId` 是权威 id，`atStep` 是模型步序号（1 基）。语义 = 「已读、未答」⇒ 客户端把该气泡渲染灰态，直到该路 `message.`/`turn.end` 到达（不需要第二个确认帧*）。帧壳 `turnId` 与吃进它的那一路 `turn_begin` 同值（v0.66 落地）—— 并行下没有它配不上正确的 `turn.end`。
`chat_duplicate`	sessionId	`{sessionId,clientMsgId,messageId}`	`clientMsgId` 判重命中：没有新回合、没有新内容帧，客户端把本地乐观气泡对齐到既有 `messageId`

turn_begin 的帧序（v0.66，按实现）：session_busy（新回合）或 pending_drain（续跑）→ message_persisted(user) → turn_begin。顺序是刻意的、不可调换：turn_begin.data.messageIds 必须是已落库的权威 id，因此它只能在用户消息落库之后发；客户端因此总能先看到 message_persisted，再收到把该气泡钉到某一路的 turn_begin。起第 1 路与起并行路共用同一条启动路径，帧序完全同形 —— 客户端只需实现一遍「turn_begin → 灰态」。

3.4.4 持久化 / 历史帧（owner+admin）

type	帧壳	data	说明
`message_persisted`	sessionId	`{message:<historyMessage>,unreadCount?:<int>,proactive?:true}`	Web 主会话及 `web:` 子会话的消息落库实时同步。`thinking` 恒缺席；可能带可选 `turnId`（v0.66，空则键省略）；可能带可选 `unreadCount`（v0.76，该会话此刻的绝对未读数，只在 >0 且算得出来时*出现 —— 见 §4.13）；可能带可选结构化判据 `proactive:true`（v0.74，仅 IM 路由的主动推送 —— 见下方说明，普通消息永不带它）
`channel_persisted`	sessionId	`{message:<historyMessage>}`	隔离渠道会话（`sess-`）的消息落库，供 IM 日志页。`thinking` 恒缺席*；可能带可选 `turnId`（v0.66）
`message_edited`	sessionId	`<historyMessage>`（data 直接就是 DTO）	编辑单条消息。`thinking` 恒缺席；可能带可选 `turnId`（v0.66）
`message_deleted`	sessionId	`{id}`	删除单条消息

thinking 可达性口径（v0.66 口径更正）：消息 DTO 的 thinking 在全部读取面（GET /sessions/{id}/messages、GET /admin/channels[/{platform}]/messages、握手 history 回放、message_persisted / channel_persisted / message_edited）恒为缺席。原因不是「有意清空」，而是 history.Message.Thinking 全仓没有任何写入者（loop.Result 没有该字段、Anthropic 流式收尾直接丢弃思考文本）⇒ 该键在线上永远不会出现。

message_persisted 的 proactive 判据（v0.74，纯增量）：帧 data 里可选的布尔键 proactive:true 是「这条是她主动说的话」在线上唯一的结构化判据，由后端的主动推送通道打上（gateway.BroadcastProactivePersisted）。客户端读到它就应走与 proactive_message 同一套提醒逻辑（页面不在前台时补一发浏览器通知、同一条只打扰一次），因此「她该不该提醒我」与后端走了哪条路由无关。

为什么需要它：auto 提示在主人有已连接 IM 渠道时优先走 IM，而 IM 路由过去只发普通 message_persisted —— 浏览器通知挂在 proactive_message 上 ⇒ 实际最可能发生的路径恰恰不弹。修的是这条边界（主人 2026-10-05 裁定「她说话该不该提醒我，与走哪条路由无关」）。

判据为什么不会误伤普通消息：只有主动推送那条通道会调用带判据的广播入口；普通消息（Web 回合 / IM 回复 / IM 镜像）走的仍是原入口，那条路径永不往帧顶放该键。客户端只应做 data.proactive === true 的严格相等判断 —— 缺失、false、非布尔值都按「不是主动消息」处理。

去重键 = message.id：主动推送镜像回主会话时，同一条消息会先发一条不带判据的普通帧（v0.72 起的行为，逐字不变，任何客户端都能渲染），随后追加一条带判据的帧。两帧同 message.id ⇒ 合并成一个气泡（消息 store 按 id 去重），提醒也只发一次（提醒去重表按同一个 id 记）。proactive_message 与带判据的 message_persisted 同时到达时同样只提醒一次。

落库失败时不发判据帧：没有落库行就没有权威 id，而 message_persisted 的载荷要求非空 id（缺了客户端会整帧丢弃）⇒ 那种情况下只记 WARN、不弹通知（绝不发一条会被丢掉的帧假装提醒过）。

⚠️ 判据不落库：它只活在实时帧上（写入那一刻才知道这条是不是主动推送），库里的行没有对应列（不改 schema）。因此刷新后从 GET /sessions/web/messages / 握手 history 回放读到的那一行不带该信息 —— 这是预期的：通知只对「实时到达」有意义，翻历史不该弹提醒。 思维链的唯一出口是实时帧：§3.4.2 的 thinking.start / thinking.delta / thinking.end（owner/admin 档）。客户端不要为「从历史里读回思维链」写任何代码。 ⚠️ 本行更正本文档 v0.65 及更早的写法（旧版称「历史思维链只有 GET /sessions/{id}/messages（owner/admin）返回」）—— 那是文档写错了，与实现不符。见 §7.3。另注：管理面板人格清单里的 thinking 是人格旋钮（GET /admin/personas 的 thinking 块），与消息 DTO 的 thinking 不是同一个字段。 voice 覆盖同一批读取面（v0.67 登记；🔴 v0.79 只落地了其中一部分）：消息 DTO 的可选 voice 对象设计上一次覆盖 message_persisted / channel_persisted / message_edited 与握手 history 回放（形状与语义见 §4.4）。🔴 v0.79 实测覆盖：只有 message_edited（与 §4.4 列出的 4 个 REST 读取面）会带它；message_persisted / channel_persisted 与握手 history 回放仍不带 voice（补齐需给 history.Message 加字段，未做）⇒ 客户端不要在实时帧 / 握手回放上等 voice。WS 协议本身零变化：无新帧、无新上行字段；voice 只是既有 DTO 的新可选键。

3.4.5 子代理 / 任务 / 系统帧（owner+admin）

type	帧壳	data（要点）
`subagent_event`	—	`{id,name,status,role,mode}`（进度：dispatched/started/done/failed/aborted）；`subagent_ask` 的应答另有 `AuditResult` 形状
`subagent_result`	sessionId = 父会话	批次结果 `{sessionId,status,summary,agents:[{id,goal,role?,mode?,status,summary?,text?,steps?}]}`。不落库（父会话转录无新消息、重连回放不补发）
`task_output`	—	`{taskId,output,status}`（`task_output_query` 应答）；亦桥接自 `task.output` 主题
`task_done`	—	桥接自 `task.done`
`device_update`	—	桥接自 `iot.device_update`
`automation_result`	—	桥接自 `automation.result`
`reminder`	—	桥接自 `reminder.trigger`
`graph_update`	—	实时 flow 图快照（`data.sessionId` 标会话；v0.77 起 `data` 另可带 `turnId`（该图的路的权威回合标识）与 `round`（会话轮次号） ⇒ 真并行时同一会话每一路各发自己的帧，两路不再互相顶掉）。⚠️ 纯实时、不重放：断开/刷新期间的那一轮不会补发 ⇒ 打开页面时用 `GET /api/v1/admin/flow/graph`（§2.2 B13 / §4.11）拉最近一轮快照（该端点 v0.77 起另有 `lanes[]` 给出每一路）。缺席语义见 §4.11(d)
`capacity_awaken`	sessionId	`{fromState,toState,tool}`
`mood`	（无 sessionId）	`{mood,personaId,affection}`；角色级情绪，仅变化时发
`proactive_message`	—	`{platform,channelId,channelType,content,contentType,sender,timestamp,messageId,id?,createdAt?}`（已消毒，绝不含凭据/媒体字节）。v0.72：`id`/`createdAt` 是这条消息在主会话历史里的权威行 id 与落库时间戳（同现/同省），落库失败时键缺席 —— 客户端据此把实时气泡对齐到历史行（按 id 去重、刷新后仍在）
`approval_notice`	sessionId	`{actor,tool,op,detail,explain,allowed,at}`（主代理代审小字；`explain` 由后端产出、客户端原样渲染）
`mode_switch`	—	上行 `mode_switch` 的回放（透传 `data`）
`observability_log`	—	`{entries:[{time,level,source,msg}...]}`，上限 200，最新在前
`observability_trace`	—	`{spans:[...]}`，上限 100，最新在前
`observability_metrics`	—	扁平 `AdminMetrics` 快照
`panels_changed`	（无 sessionId）	插件面板集合变更信号（v0.78 新增，切片 PLG-2）：`{reason,pluginId}`；`reason ∈ {declare,install,uninstall,enable,disable}`，`pluginId` 可为空串（无法归因到单个插件时）。🔴 帧刻意不带任何面板内容 ⇒ 客户端据此按自己的角色重拉一次 `GET /api/v1/admin/panels`（A13）。只发 owner/admin（未进 `frameReachesAll` 白名单 ⇒ viewer 收不到，须自行刷新/轮询）。传输 = 进程内 bus 主题 `ws.panels_changed`（零新端口）
`channel_event`	（无 sessionId）	渠道事件实时帧（v0.78 新增，切片 E7）：`{event:{…}}`，`data.event` 与 `GET /admin/channels/events` 的 `events[]` 元素同一个对象（v0.67 登记的 `ChannelEventJSON`，键名 camelCase）。⚠️ `id` 键可能整个缺席（实时帧对应刚落库、id 尚未回读的那一行；列表端点读已落盘行，`id` 恒有值）。只发 owner/admin（未进 `frameReachesAll` 白名单；viewer 走 REST 只读档）。🔴 增量提示、不是权威列表：帧是 best-effort（hub 发送缓冲满即丢该连接的那一帧）⇒ 客户端必须保留 REST 轮询兜底；去重建议按（`platform`,`accountId`,`platformType`,`createdAt`）或以轮询结果为准重排。⚠️ 当前只覆盖账号状态迁移这一路（见 §7.2）

observability_ 的订阅*：owner/admin 凭据读取 GET /admin/observability/{logs,metrics,trace} 任一个即订阅；该凭据的 WS 连接全断即退订（无轮询、无常驻 goroutine）。

channel_event 当前实际会产生的事件（v0.78，切片 E7）：只有账号状态迁移 —— 即「她自己的账号上线 / 离线 / 未知」这一路。落库行为 platform（如 qq-obv11）/ accountId / tier="t2"（高价值 ⇒ 逐条落行）/ category="lifecycle" / platformType ∈ {get_status, meta_event.heartbeat, meta_event.lifecycle, account_status} / selfRelated:true / actorId:"" / actorRole:"system" / channelId·channelType·groupId·messageId 均空 / summary = 九句固定文案之一（账号在线（首次确知）、账号离线（首次确知）、账号状态未知（尚未探到）、账号离线（在线→离线）、账号上线（离线→在线）、账号上线（未知→在线）、账号离线（未知→离线）、账号状态未知（在线→未知）、账号状态未知（离线→未知），不含任何平台原文）。采样由网关常驻（约 60s 一拍，不看面板也在跑），未知（known=false）也照常落行（「尚未探到」≠ 离线）。当前唯一有账号状态面的平台是 qq-obv11；将来若把 meta_event 心跳也接进同一状态面，platformType 会跟着变。

proactive_message 的落库口径（v0.72，行为变更）：后台思考决定「此刻主动开口」时，这条消息现在是主会话（web）历史里的一条真实 assistant 消息 —— 走活跃客户端路由（在线 owner/admin 连接）的那一路此前只广播帧、一行都不写 ⇒ 刷新/重载后什么都补不回来（既不显示气泡，也补不出历史）。本版 SendProactive 先落库、再发帧：

落库行：sessionId="web"、role="assistant"、content = 帧里的 content（后端已净化的同一份文本，系统元数据绝不进正文）、platform = 帧里的 platform、mode="chat"、turn_id 留空（主动推送不属于任何一路回合）。因此 GET /sessions/web/messages、握手 history 回放、message_persisted 都能读到它。

id/createdAt 随帧下发，客户端应据此把实时气泡对齐到历史行（按 id 去重；刷新后由历史行接续，不是第二个气泡）。落库失败时这两个键缺席，但同时：帧照发（实时气泡不丢），后端记 WARN 并返回错误 ⇒ 后台思考记录里的 route/detail 会写明未落库（不会再说成「已推送」）。

无在线 owner/admin 连接时也会落库：推送器如实报告「没有活跃客户端」（pushed=false），这条话仍作为一条真实记录留在主会话里，下次打开就能看到。

IM 路由（v0.74 起也提醒）：im_bridge 路由本就把消息镜像回主会话并广播 message_persisted（逐条一条，不双份），v0.74 起在落库之后追加一条帧顶带 proactive:true 的同类帧 ⇒ 客户端走与 proactive_message 同一套提醒逻辑（见 §3.4.4 后的「message_persisted 的 proactive 判据」）。两条路由在一次推送里互斥（web 提示只走活跃客户端，其余先 IM、IM 投递失败才降级活跃客户端），因此同一条主动消息在主会话里恰好一条。

3.4.6 定向帧（不经 `hub.broadcast`，只到指定连接）

type	说明
`history`	握手回放（§3.2，仅 owner/admin）
`voice_output`	语音回合结算后定向回发起 `voice_input` 的那条连接。帧壳无 sessionId；data `{audio(base64),format,text,reply,sessionId,deviceId?,provider?}`。定向目标是连接本身，服务端不按 deviceId 路由；连接已断不补投
`error`	上行拒绝 / 处理函数级失败（形状见 §3.3 与 §4.1）

4. 契约细节

4.1 错误响应与错误码

形状：{"error":{"code":"<string>","message":"<string>"}}。
中间件级（Bearer/角色门）固定：401 unauthorized / 403 forbidden。
常用业务码（按状态分组）：

状态	code（示例）	场景
400	`bad_request`、`image_too_large`、`too_many_documents`、`invalid_payload`（v0.79）、`unknown_provider`（v0.79）、`not_configured`（v0.79）、`primary_not_configured`（v0.80）	请求体/字段非法、图片超限（`image` 字符串长度，仅 base64 / `data:` 形态会触发，见 §4.5）、附件超条数；插件动作的载荷形状错 / provider 名未登记 / 该家没配齐（这三个码自 v0.79 起由动作处理器给出，见 §4.14(b)(c)）；面板保存的 `primary` 指名一家「已登记但未配齐」的家（v0.80，写盘之前就拒 —— 那份配置会让后端下次起不来，见 §4.14(c)）
401	`unauthorized`、`invalid_grant`	无/坏凭据；refresh token 非法
403	`forbidden`、`unknown_role`（v0.78，面板快照的角色无法识别，理论不可达、fail-closed）	角色不足；主会话不可删；插件写动作的调用者不是 owner/admin（v0.78，见 §4.14(b)）
404	`not_found`、`session_not_found`、`document_not_found`、`account_not_found`、`media_not_found`（v0.67 登记、v0.79 已实现）、`tidy_run_not_found`（v0.77 登记、已实现）、`action_not_declared`（v0.78 登记、已实现）	资源缺失；消息列表的会话不存在；文档缺失（含名字非法/穿越）；渠道账号 id 不存在（C19/C20）；语音副本缺失（含名字非法/穿越，三者同一响应，见 §4.5）；异步试算的 `runId` 未知 / 超 TTL / 进程重启后查不到（三种原因刻意不区分，见 §4.12.1）；插件动作名未在该插件声明里出现过（不是「没权限」，见 §4.14(b)）；回滚的记忆条目不在被合并状态（`not_found`，v0.79，见 §2.2 B17）
409	`chat_busy`、`account_not_registered`、`plugin_disabled`（v0.78）、`config_unstartable`（v0.80）	待处理队列满；渠道账号已配置但没有已注册适配器（C19/C20，v0.66）；插件已被显式停用，其声明还在但入口与动作都下线（v0.78，见 §4.14(b)）；这次面板保存的结果会让 web-search 起不来（主 provider 未配齐 / 未登记 ⇒ 下次启动 fail-fast）⇒ 已按字节回滚、运行中的工具保持原样（v0.80，见 §4.14(c)）
413	`payload_too_large`、`document_too_large`	上传/文档超限
415	`unsupported_media_type`	图片/文档类型拒绝
429	`rate_limited`	限流（框架级）
500	`internal`、`chat_unavailable`、`chat_failed`、`voice_unavailable`、`stt_failed`、`tts_failed`、`tts_empty`、`voice_clone_failed`、`usage_unavailable`、`storage_unavailable`、`channel_events_unavailable`（v0.67 已实现，见 §2.4(a)）、`refresh_unavailable`、`sessions_failed`、`messages_failed`、`session_failed`、`message_failed`、`document_upload_failed`、`login_failed`、`memory_review_unavailable`（v0.79 新增，切片 L45：入库前审查留痕存储未接线 —— 列表与回滚共用）、`reviews_failed`（v0.79：读留痕失败）、`revert_failed`（v0.79：回滚写失败）、`config_unreadable`（v0.79：面板可变源存在但读不出来，不覆盖原文件）、`config_write_failed`（v0.79：可变源写不进去，本次改动没有生效）	内部错误或依赖未接线（绝不伪装成功）
501	`not_implemented`、`panels_unavailable`（v0.78）、`action_not_implemented`（v0.78）	HistoryStore 等未注入；插件面板中枢未接线（见 §4.14(a)）；动作已声明，但宿主没有登记它的处理器 —— 🔴 v0.79 起不再是兜底档：内置 `web-search` 的动作已全部登记（见 §4.14(b)(c)），这条只在「声明写了却没实现」时出现
502	`action_failed`（v0.78）、探针码 `unauthorized` / `rate_limited` / `quota_exceeded` / `network` / `upstream` / `bad_response` / `no_results` / `unknown`（v0.79）	插件动作执行失败（结构化错误码 + 文案，详细原因只进后端日志）；后一组是 `plugin.testProvider` 探针的上游结论（其中 `no_results` = 连通正常但没查到结果），见 §4.14(b)(c)
503	`timeout`、`chat_dispatch_failed`、`catalog_unavailable`	派发/上游不可用

未确证：conflict(409) 的通用码存在（框架级 ErrConflict），但除了 chat_busy 之外，本文档未逐一确证还有哪些端点会带它。 ⚠️ 416 不是错误信封（v0.67 登记，v0.79 已实现）：GET /api/v1/media/{name} 的 Range 语法非法或范围不可满足时，由 Go 标准库直写 416（text/plain + Content-Range: bytes */<size>），不套 {"error":{…}} ⇒ 客户端不要拿 error.code 去解析它（见 §4.5）。这是字节流端点的既有事实（/audio/speech 的 200、/documents/{name} 的 200 同样不是 JSON 信封），不是本版新引入的怪癖。 400 的渠道事件用法（v0.67 已实现，见 §2.4(a)）：GET /admin/channels/events 对 platform 未知、tier 非法、since/until 跨度 > 90 天、since/until 时间点非法、limit/offset 非整数都回 400（落地用的 code 是通用的 bad_request，见 §7.4-11）。

4.2 分页与游标

GET /api/v1/sessions/{id}/messages：

limit：默认 50，生效范围 [1,200]（大于 200 钳到 200，不报错）；非数字或 <1 → 400。
before（毫秒 createdAt）：返回严格早于 before 的消息，倒序（默认方向，向后翻历史）。
after（毫秒 createdAt）：返回严格新于 after 的消息，正序（重连后的前向增量追赶）。
before 与 after 互斥（同传且都 >0 → 400）；after 非数字/负 → 400。
q：会话内内容搜索（大小写不敏感 ASCII LIKE，%/_/\ 已转义），倒序、仍遵守 before/limit；q 与 after 互斥；空 q = 未传。
platform：可选来源平台过滤（Web 端不传 = 全量；IM 适配器传本平台）。
形状校验（limit/before/after 非法、互斥冲突）先于 404 判定：形状错就是 400，与目标会话存在性无关。

4.3 幂等（`clientMsgId`）

上行可选字段（REST chat body 与 WS chat 帧同形；voice_input 亦然）。
同一会话内同一个非空 clientMsgId 只承认第一条。重复到达：
- REST → 200 {"data":{"duplicate":true,"messageId":...,"sessionId":...}}
- WS → 下行帧 chat_duplicate（§3.4.3）
- 不落库、不起回合、不发任何内容/流式新帧。
判重由 SQLite 部分唯一索引 (session_id, client_msg_id) WHERE client_msg_id != '' 原子裁决（并发重发只有一个赢家）。
clientMsgId 回填进消息 DTO（空则省略），读接口与 message_persisted 给出同一答案 —— 客户端据此对齐本地乐观气泡（替代「靠文本相等」的脆弱匹配）。
省略它时行为逐字不变（老客户端零影响）。

4.4 消息 DTO（`historyMessage`）

GET /sessions/{id}/messages 的数组元素、PATCH /messages/{id} 的响应 data、GET /admin/channels[/{platform}]/messages 的元素、message_persisted / channel_persisted 的 data.message、message_edited 的 data、握手 history 回放的 messages[] —— 同一个结构体：

{
  "id": "<消息 id>",
  "sessionId": "web",
  "role": "user|assistant",
  "content": "...",
  "mode": "chat",
  "mood": "",
  "image": "",
  "documents": [ {"name":"...","mime":"...","size":123,"chars":8000,"truncated":false,"status":"extracted"} ],
  "thinking": "...",           // 恒缺席（全仓无写入者；见 §3.4.4 口径更正）
  "platform": "web",
  "deviceId": "web:chrome:a1b2c3",
  "senderName": "...",         // 第三方发送者显示名；空 = 主人
  "adapterId": "kook:3bef...", // IM 来源适配器；Web 来源为空
  "personaId": "...",          // 空 = 全局默认角色
  "clientMsgId": "...",        // 空则省略
  "turnId": "turn-…",          // v0.66；空则省略（老消息/未接管路径）
  "toolCalls": [               // v0.78；🔴 只在 GET /sessions/{id}/messages 这一个出口填充（见下）
    { "name": "web_search", "status": "ok", "durationMs": 1200,
      "argsSummary": "{\"query\":\"明天天气\"}", "resultSummary": "晴，18~26℃" }
  ],
  "voice": {                   // v0.67 登记，v0.79 已实现（切片 L45）；非语音消息键缺席；🎤 判据 = 本键存在
    "source": "asr",           // "asr"（服务端识别，含云端）| "platform"（渠道平台自带转写）
    "status": "transcribed",   // "transcribed" | "empty" | "failed"（闭集三态）
    "name": "a1b2c3….ogg",     // 音频副本存储名；无副本 ⇒ 键省略
    "mime": "audio/ogg",
    "size": 12345,
    "durationMs": 3200,        // 可选：渠道如实给出时才有（绝不估算）
    "url": "/api/v1/media/a1b2c3….ogg" // 与 name 同生共死（服务端相对路径）
  },
  "createdAt": 1700000000000
}

字段省略规则：mode/mood/image/thinking/platform/deviceId/senderName/adapterId/personaId/clientMsgId/turnId/toolCalls/voice 均为 omitempty（空时键缺席；voice 是指针，非语音消息整键缺席，不是 {} 也不是 null；toolCalls 见下）。

⚠️ toolCalls 只在一个出口填充（v0.78，切片 CODE-TC）：字段加在共享 DTO 上，但只有 GET /api/v1/sessions/{id}/messages 的 handler 会填它 —— 其余出口（PATCH /messages/{id} 响应、GET /admin/channels[/{platform}]/messages、message_persisted / channel_persisted / message_edited、握手 history 回放）逐字不变（有单测钉住它们不产出该键）。客户端不要在那些面上等 toolCalls。

turnId 语义（v0.66，可选）：

形状：字符串，与该路的实时流帧帧壳 turnId、以及 turn_begin 帧壳 turnId 同值（编排器生成，见 §3.4.3 / §4.8）。
同一路的 user 行与 assistant 行同值 ⇒ 客户端在重连 / 回放时可用它精确配对「回复 ↔ 提问」，并恢复回复侧的分组小标（真并行下两路回答交错，只按顺序渲染会配错）。
退化为空（键省略）的三类情形：① 加入该列（迁移 0018）之前的历史行；② 未经编排器的写入路径（IM 渠道桥等，其行 turn_id 留空是预期行为）；③ 忙时入队 / 被转向吃进的消息 —— 它们落库那一刻还没有自己的路，那一帧 message_persisted 因此不带 turnId，客户端从随后的 turn_begin（帧壳 turnId + data.messageIds）得知归属；行本身由实际处理它的那一路随后补写（先到先得）。
列口径：chat_messages.turn_id TEXT NOT NULL DEFAULT ''（不用 NULL，于是「旧行」与「没写」是同一个值）。

toolCalls 语义（v0.78 落地，切片 CODE-TC；可选，仅 GET /sessions/{id}/messages）：

形状：数组，每条 {name,status,durationMs?,argsSummary?,resultSummary?}。name / status 恒在；status ∈ {ok,error,unknown}（闭集三态）；后三个键 omitempty（图上给不出该项时键缺席）。
name = 图的工具节点里 props.tool（回落节点 label）。status 映射：图节点 done → ok、error → error、其余（running/idle/空）→ unknown —— 未知一律落 unknown，绝不把没结论的调用说成成功。
durationMs = 图上量到的起止差（毫秒）；缺任一时间戳、或不足 1ms ⇒ 键缺席，绝不估算、绝不回 0 冒充。
argsSummary / resultSummary 逐字来自已落盘的轮次链路图（flow_graphs）里出图时已脱敏的 props（args_summary / result_summary）；失败的调用在 resultSummary 里给的是图上的 error 摘要（与面板同一份已脱敏文本）。读侧不做二次脱敏、也不放宽。两者各自 ≤ 500 字符（超长按 rune 截断，末位 …）。
单条消息最多 20 条（超出按图序取前 20 条）。
🔴 缺席语义（契约核心）：toolCalls 出现 ⇔ 这条消息所属的那一轮确实调用过工具；图取不到（超保留期 / 该轮未落盘 / 隔离渠道会话从不入库 / 该路标识查不到图 / 图源未接线）以及这一轮没调过工具，都是键缺席，绝不回 [] 冒充「没调过工具」 ⇒ 客户端只做正向断言（有键 ⇒ 调过工具），不得把「没有这个键」读成「没调过工具」。
数据源接线：Deps.FlowGraphs（*flowgraph.SQLStore）为 nil 时只是没有这一面 —— 端点仍 200、正文一字不变（不像管理端点那样回 500 flow_unavailable）。查图失败只记一条带来源的 WARN 并让字段缺席（不让可视化存档的故障把整页历史变成 500）。
✅ 覆盖率已补齐（v0.79，切片 CODE-TC-2）：编排器驱动的每一路（含普通单路回合与队首续跑路）的图现在都带权威 turnId（= 该轮消息行的 chat_messages.turn_id）⇒ 这些回复都能回看到工具（此前只有真并行路可以）。仍缺席的只剩两类：① 拿不到权威标识的写入路径 —— 未接编排器的调用方、后台思考（sess-backthink 在发布会话白名单内，但它的 ctx 上没有权威标识）、旧后端；② v0.79 之前落盘的历史单路行（lane_turn_id 为空且无可回填来源 —— 那时的图里根本没存这个标识，用会话 id / 时间戳 / 消息表 join 去补都是编造身份）。见 §7.2、§7.4-23、§7.4-25。
🔴 一处形状变化（v0.79）：graph.id 的 #{回合标识} 后缀现在单路也追加（web-7 → web-7#turn-…）—— 客户端若要给 GET /admin/flow/graph?turnId= 取值，一律用响应里的 graph.id / turns[].turnId，不要自己拼 {会话}-{序号}（老客户端自拼的 web-7 查不到新行）。见 §4.11(a)(d)。
新增的读侧依赖：FlowGraphStore 增只读方法 GraphsByTurnID(ctx, sessionID, laneTurnIDs)（一页一次 IN 批量查，禁 N+1）；新表列 flow_graphs.lane_turn_id（迁移 0023，等值索引 idx_flow_graphs_lane_turn_id (session_id, lane_turn_id)）。老行（v0.77 之前的落盘）该列回填后仍为空 ⇒ 如实查不到。

voice 语义（v0.67 登记；✅ v0.79 已实现，切片 L45 —— 覆盖率见本节末）：

形状：{source,status,name?,mime?,size?,durationMs?,url?}，omitempty（非语音消息键缺席，与引入语音前逐字相同）。
🎤 判据 = voice 键存在（这条消息来自一条语音消息）。客户端绝不从 content 正文里认媒体类型：QQ 语音正文里那个 [语音] 占位标记自 v0.67 起不再下发（见 §6 的 v0.67 行为变更），正文里也可能出现用户自己打出的 [语音] 字样。只认 voice 键。
source ∈ "asr"（服务端语音识别所得，含云端）/ "platform"（渠道平台自带转写，微信 iLink 的 voice_item.text）。
status ∈ "transcribed"（正文即转写文本）/ "empty"（转写成功但没识别出文字）/ "failed"（没拿到转写文本 —— 正文是那行中文诚实提示）。客户端按 status 分支，绝不按正文文案分支（§0.3 的同一纪律）。设计还刻意不下发 failed 的机器可读细分（未配置 / 鉴权 / 欠费 / 限流 / 超时 / 格式不支持 / 无字节 ⇒ 分类只进服务端日志，正文给的是人读的原因方向）。
name / mime / size / url 四者同生共死：有音频副本时全在，无副本时全缺席（不会出现 url 指着一个不存在的 name 这种形状）。
durationMs 只有渠道如实给出时才有；读不出来就省略键，绝不估算（当前未确证各渠道是否都给得出，见 design/24 §10.12-8）。
url 是服务端相对路径 /api/v1/media/<name>（唯一派生字段，由服务端一处拼出）⇒ 客户端绝不自己拼路径。
落库形状 = DTO 形状减去 url（列 chat_messages.voice TEXT NOT NULL DEFAULT ''，JSON 单对象；用空串不用 NULL，与 turn_id 同一口径）。音频原件复用文档那一套存储 / 元数据表 / 引用计数 / GC（同一 <DataDir>/uploads/documents 目录），但不进文档的抽取 / 注入链路：不被抽取、不进 documents DTO 数组、不占注入预算、不出现在附件清单行里。
一条消息只落一份音频副本（= 被转写的那一条语音）；同一条消息里的第 2..N 条语音既不转写也不落盘，DTO 里也没有它们（刻意的边界，不是遗漏）。
⚠️ 微信（weixin-ilink）语音没有音频副本、不可回放：按既有裁决「平台自带转写就不白下载那份音频」⇒ source:"platform" 且�� name/mime/size/url，只保留 🎤 标记。
✅ 覆盖率（v0.79，如实）：voice 已在这 4 个读取面填充 —— GET /sessions/{id}/messages、GET /admin/channels/messages、GET /admin/channels/{platform}/messages、PATCH /messages/{id} 的响应与 message_edited 广播帧。🔴 尚未填充：message_persisted / channel_persisted（broadcast.go）与握手 history 回放（ws_history.go）—— 需要给 history.Message 加 voice 字段（未做）；且入站语音的 voice 列是消息落库之后回填的，message_persisted 那一帧在落库那一刻发出，即使加了字段也拿不到值。⇒ 客户端不要在实时帧上等 voice（见 §7.2、§7.4-29）。
⚠️ 列被外部改坏时可见地缺席：非法 JSON / 闭集破坏时不静默当「不是语音」 —— 记一条带来源与消息 id（不含正文）的 WARN，并让该字段缺席。契约的 voice 没有「读不出」这一态，因此缺席是唯一诚实的表达（与 documents 回一条 unreadable 不同）。

documents 数组语义（核心）：

形状：{name,mime,size,chars,truncated,status,reason?}，≤5 条/回合，顺序 = 客户端发送顺序。
0 个附件时该键省略（不是 []，与引入文档前逐字相同）。
status ∈ extracted（正文已进上下文）/ listed（只给了模型附件清单，正文没进上下文）/ unreadable（读不到正文）。
chars / truncated 是「本回合注入侧」语义：chars = 本回合注入模型上下文的字符数（截断时为截断后值），不是文件字数；truncated = 注入是否被预算截断，不是文件是否被截断。全文长度只有 document-read 工具的 totalChars 能看到。
reason（可选，omitempty）：只在 status:"unreadable" 时下发（extracted/listed 时键缺席）。逐字就是服务端注入给模型的那份原因（同一字符串），客户端不必自己拼。当前文案集合（服务端常量，逐字）：
- 无法抽取正文：这是图片型/无文本层 PDF，需要 OCR 才能读（当前未做）
- 无法抽取正文：PDF 已加密（无法用空口令打开），请解除密码后重新上传
- 无法抽取正文：PDF 损坏或无法解析
- 无法抽取正文：本期不支持 Word/Excel/PPT 解析（无文本层）
- 无法抽取正文：内容不在可抽取的纯文本范围内
- 无法抽取正文：文档文件不存在或已被清理 / …：读取文档失败 / …：文档引用形态非法 / …：文档上传目录未配置
- 无法读取或解析失败（解析器整条消息失败时的诚实兜底）
- ⚠️ 只放文案：不含落盘路径、不含凭据；原始错误只进服务端日志。
不含正文（结构上保证：正文若从历史回传，每翻一页都要背着它）。
时点：status/chars/truncated/reason 由回合结束后的回写写进 document 列 ⇒ 只在读取面（GET /sessions/{id}/messages、握手回放）可见；message_persisted 在用户消息落库时就发出（那时还没有结论）。
列被写坏时（外部改动/格式变更）绝不静默当无附件：回一条 status:"unreadable" 的最小引用。

4.5 图片 / 文档 / 语音链路

图片：

两条入口：POST /api/v1/upload（multipart，单文件字节 ≤ 5 MiB）取绝对同源 URL；或 chat.image 直接内联 base64 data: URI / http(s) URL。
⚠️ 按形态写清（v0.66 补充说明，更正旧措辞「解码后 5 MiB」）：chat.image 的唯一入口判据是 image 字符串长度，不是「解码后字节数」 —— POST /api/v1/chat 的 handleChat 在解码 / 落库 / 入模型之前调用 checkChatImageSize(image, limit)（internal/services/gateway/rest.go），判定就是 len(image) <= limit；limit = CHAT_IMAGE_MAX_BYTES（默认 5242880）按 base64 膨胀 4/3 换算出的字符上限 = ceil(n/3)*4 + 64，默认 6990572 字符（那 64 字符是 data: 前缀余量）。超一字符即 400 {"error":{"code":"image_too_large"}}（message 带上限与本次长度，文案指路先上传）。
- base64 / data: URI 形态：受上述 6990572 字符约束，等价于解码后约 5 MiB。data: 前缀越长，留给载荷的字符越少；裸 base64（无前缀）在恰界（正好 6990572 字符）时解码 ≈ 5242929 字节 = 5 MiB + 49 字节 ⇒ 「解码后 5 MiB」是换算口径，逐字节的硬判据在代码里不存在（视觉解码层的兜底预检 vision/limits.go 同样是按字符串长度判 MaxInlineImageChars）。要与「一张图 5 MiB」严格对齐，客户端按 ceil(n/3)*4 + 64 自查即可，不要按解码字节数试探。
- http(s) URL 形态（含 /api/v1/upload 返回的 /api/v1/files/<32hex>.<ext>）：判据与形态无关（任何短于 6990572 字符的串都通过），而正常 URL 只有约 60 字符 ⇒ 实践中 image_too_large 不会因 URL 形态触发。URL 形态真正的天花板在视觉取回层：internal/runtime/multimodal/vision/image.go 的 maxFetchedBody = maxImageBytes = 50 << 20（50 MiB；其视觉/OCR 工具路径下同源 upload 产物优先走本地直读 readFile，用同一常量，而主模型直收路径仍走一次 HTTP 自取），另有 30 s 取回超时。⚠️ 该 50 MiB 是 io.LimitReader 的截断上限 —— 超出部分被静默丢弃、不返回错误 ⇒ 客户端不要把「服务端会拒绝超大 URL 图」当契约，也不要把 50 MiB 当成能用满的额度。
- upload 形态：POST /api/v1/upload 自带 5 MiB 单文件硬上限（maxUploadBytes = 5 << 20；超限 413 {"error":{"code":"payload_too_large"}}）⇒ 经 upload 拿到的同源 URL 图，有效上限仍是 5 MiB，在上传那一刻定死，与本接口的字符串长度判据无关。
上限来源 CHAT_IMAGE_MAX_BYTES：≤0 = 用默认（不存在「禁用上限」的取值）；只能收紧、不能放宽（钳到 vision 解码层硬顶 vision.MaxInlineImageBytes = 5 MiB）。
data: 前缀与类型嗅探都不参与这个体积判据：前缀只通过那 64 字符余量影响能塞多少；类型裁决（字节嗅探为唯一裁决权；HTML/SVG/判不定 → 明确报错，绝不静默当 PNG）发生在视觉层，属回合内错误，不是入口 400。
WS chat 帧到不了这条判定：WS 上行（streamChat）没有任何图片体积校验，读上限 4096 字节/帧由传输层直接断连 ⇒ WS 上发真实图片必须「上传 + URL」。
视觉 URL 由服务端取回内联为 data: URI 再交 provider。主模型能否收图看生效组的 multimodal（见 §5），与 LLM_VISION_MODEL/LLM_OCR_MODEL 无关。

文档：

上传 POST /api/v1/documents（owner/admin，字段 file，上限 CHAT_DOCUMENT_MAX_BYTES 默认 20 MiB）。
类型裁决 = 字节嗅探（唯一裁决）∧ 扩展名白名单（23 项，含 .pdf），成对判定（.pdf 必须嗅探为 application/pdf，纯文本类必须 text/plain）。HTML 改名 .pdf ⇒ 415；PDF 改名 .txt ⇒ 415。mime 是嗅探基类型（data.json → text/plain；真 PDF → application/pdf）。
落盘名 = sha256(bytes)[:32] + ext（内容寻址；原始文件名永不参与路径 ⇒ 同字节同扩展名天然去重）。
读取 GET /api/v1/documents/{name} 必须 Bearer owner/admin，一律 attachment + nosniff（永不内联）。
对话携带：chat.documents = [{"name":"<服务端存储名>"}]（只给 name，绝不接受 URL；多带的 mime/url/size 一律被服务端覆盖）。≤5 条，超出 400 too_many_documents（先于任何文件系统访问）；任一条非法/不存在 → 整个请求被拒（404 document_not_found），绝不静默丢附件。附件部件挂在同一条 user 消息上；纯附件回合（无文本、无图片）同样成立。
内置工具 document-read（模型侧，客户端一般只需知道它存在）：注入被截断时清单行给续读游标 offset。策略默认 owner-only（群聊/陌生人天然读不到）。
PDF（v0.61）：文本层 PDF ⇒ extracted；扫描件/图片型 PDF（无文本层）⇒ 诚实拒绝 unreadable；加密与损坏可区分。

语音：

REST 源（/api/v1/audio/*，均 owner-only + 审计，绕开 WS 4KB 帧限）：见 U5–U7。
- /transcribe：{audio,format?,deviceId?} → {data:{text,provider?}}。
- /speech：{text,voice?,format?,instruction?} → 原始音频字节（Content-Type: audio/<format>）。instruction（≤100 字符，汉字记 2）只对复刻/设计音色生效，系统音色 longxiaochun_v3 被忽略。
- /voice-clone：{url,prefix?} → {data:{voiceId}}。⚠️ 真建音色需公网参考音频 URL（当前无，待主人提供）+ 北京地域 API Key。
WS 语音回合（voice_input）：与文本回合走同一条路（进编排器 → 落库 → 流式 → 跨端同步 → 忙碌/排队语义一致）。转写文本落库为用户消息、助手回复落库；deviceId/clientMsgId 与 chat 帧同形。
voice_output 在该回合结算时才定向回发起连接（可能晚于若干状态帧，甚至由续跑回合或被 steer 注入的那一回合产生）。空正文 / TTS 失败/降级都走 provider 降级信号（silent 等），不把 stopReason 当语音内容；连接断开不补投，客户端带回同一 clientMsgId 可安全重试。

入站语音的音频副本与播放端点（v0.67 登记；✅ v0.79 已实现，切片 L45；残留缺口见下）：

✅ v0.79 落地进展（切片 L45，如实登记）：已实现 —— ① documents.Store.SaveAudio（音频白名单 / 内容寻址 / 同字节去重 / 目录 0700、文件 0600 / 元数据写同一张 documents 表、引用计数并入同一套 documents.ref_count）；② history.Store.UpdateMessageVoice + VoiceColumns（chat_messages.voice 列的读写两条路）⇒ channelbridge 的入站副本链端到端可落地；③ 网关 DTO voice（含唯一派生字段 url） 与 GET /api/v1/media/{name}（§1.2 U19 / 下表）。🔴 残留缺口（如实，不美化）：① ✅ 已修（v0.80，切片 W4 / 裁决 #11）：组合根已注入 VoiceTranscoder（cmd/cyrene/wire_channels.go 的 channelbridge.Options）⇒ 不可播格式（amr）也落副本（落盘前先转 .wav，mime: audio/wav）；transcode_not_wired 只剩「引擎未装配 / 构造失败」一档。⚠️ 生产端到端仍未跑；可播格式（ogg/wav/mp3/m4a/aac/flac/webm/oga/opus）仍原样落、不转码；② WS 实时帧 / 握手回放不带 voice（见 §3.4.4 与 §4.4 覆盖率）；③ 消息 / 会话被删除时音频副本的引用计数不被释放（refs.go 的增减点只认 document 列）⇒ 副本 ref_count 偏高（后果是晚回收 / 不回收，绝不早删）；④ 生产端到端未跑（禁止重启后端）⇒ 「真机 IM 语音 → 盘上 0600 副本 → 客户端取到字节」只有替身 + 临时库/临时目录级证据。

v0.78 已落地的基础件（切片 CODE-VOICE；v0.79 已在其上补齐用户可见面）：① 迁移 0020_chat_message_voice 给 chat_messages 加 voice TEXT NOT NULL DEFAULT '' 列（JSON 单对象，形状 = 下面的 DTO voice 减去 url）；② internal/runtime/voice/** 新包（Source/Status 闭集、Ref 编解码、格式级可播表 + amr→wav 转码归一）；③ channelbridge 入站语音「归一（最前端）→ 闸门之后落副本 → 落库后写 voice 列」全链打通（落盘内容寻址、复用文档存储与 GC，但不进文档抽取/注入链路）。唯一已生效且客户端可见的既有变化：IM 语音在「音频格式不在可转写白名单内」时正文诚实提示由「…（需要先转码，当前未做）」改为「…（服务端只把白名单内的音频送语音识别），这条语音没有转写。」—— 形状不变（正文仍是转写文本或一行诚实提示；客户端本就不该按正文文案分支）。

音频副本何时产生：渠道适配器入站拿到语音字节后，转写在流水线最前端归一（见上），而落盘在闸门之后 —— 被会话解析 / 黑白名单 / 最小打扰拦下的语音盘上不留任何文件（与 IM 附件同一纪律）。落盘 = 内容寻址（sha256(bytes)[:32] + ext，同字节同扩展名天然去重），产出该消息的 voice 引用（DTO 见 §4.4）。不可播格式（amr）在落盘之前先转成可播副本（amr→wav）；转码不可用时不落副本、不打假 url、消息一个字不丢（带稳定 category 的 WARN；10 类：no_bytes/not_playable/transcode_not_wired/unsupported_format/input_too_large/output_too_large/decode_failed/encode_failed/timeout/busy）。⚠️ 现状（v0.80 / 切片 W4 起）：组合根已注入 VoiceTranscoder ⇒ amr 先转 .wav 再落副本（mime: audio/wav）；可播格式仍原样落、不转码。⚠️ transcode_not_wired 从此只剩「引擎未装配 / 构造失败」一档（生产装配下不再出现）。
播放端点 GET /api/v1/media/{name}（owner/admin，必须 Bearer，与 GET /api/v1/documents/{name} 同一套门）：

项	口径
名字形态	32 位小写十六进制主名 + 音频白名单扩展名（10 项：`.wav` `.mp3` `.aac` `.ogg` `.oga` `.opus` `.m4a` `.webm` `.flac` `.amr`）；`..` 等路径穿越全形态拒绝
`Content-Type`	按存储名的扩展名映射，*恒为 `audio/`（`.wav→audio/wav`、`.mp3→audio/mpeg`、`.aac→audio/aac`、`.ogg`/`.oga`/`.opus→audio/ogg`、`.m4a→audio/mp4`、`.webm→audio/webm`、`.flac→audio/flac`、`.amr→audio/amr`）。不查库、不重新嗅探（扩展名与字节在保存时**已成对裁决）
`Content-Disposition`	`inline; filename="<name>"` —— 与文档读侧的 `attachment` 刻意相反（音频要被播放器消费；因下发类型恒 `audio/*` + `nosniff`，内联不构成文档侧那类 XSS 面）
其他响应头	`X-Content-Type-Options: nosniff`；`Accept-Ranges: bytes`；`Cache-Control: private, max-age=86400, immutable`；不设 `ETag`（不自造语义，条件请求走 `Last-Modified`）
状态码	`200` 全量 / `206 Partial Content`（`Range: bytes=0-`、`bytes=N-M`、`bytes=-N`，由 Go 标准库 `http.ServeContent` 处理 —— 客户端不要自研 range 解析）/ `304 Not Modified`（条件请求）/ `404 media_not_found`（名字形态非法 / 路径穿越 / 文件不存在三者同一响应，不泄露「存在与否」以外的信息）/ `401` / `403`（中间件）
`HEAD`	支持（`GET` 模式同时匹配 `HEAD`）⇒ 客户端可先探长度再决定要不要整段拉
⚠️ `416`	不是 JSON 信封：`Range` 语法非法或范围不可满足 ⇒ 标准库直写 `text/plain` + `Content-Range: bytes /<size>`，不套 `{"error":{…}}`。唯一例外：空文件* + 范围不可满足 ⇒ 忽略 `Range` 回 `200`（标准库的特别处理）
日志	404 不记错误日志（可预期的输入问题）；不记任何字节内容

三条读侧路的边界（别混）：

端点	鉴权	Disposition	名字形态	语义
`GET /api/v1/files/{name}`	无（能力 URL）	`inline`（按图 MIME）	128-bit 随机名 + 图片扩展名	图片，给 `<img>` / provider 直接吃
`GET /api/v1/documents/{name}`	Bearer owner/admin	`attachment`	32 hex + 文档白名单（23 项）	文档，永不内联渲染
`GET /api/v1/media/{name}`（v0.67 登记 · v0.79 已实现）	Bearer owner/admin	`inline; filename=…`	32 hex + 音频白名单（10 项）	语音副本，供播放器消费

⚠️ 音频 URL 不能直接贴进 <audio src>：读侧要 Bearer（与图片读侧「128-bit 名即凭据」刻意相反 —— 语音是私密内容，不是「谁拿到 URL 谁就能听」）⇒ 客户端须带 token 取字节（Web：fetch → blob: → 播放；原生：认证 HTTP 客户端）。这是有意的设计，不是缺陷。
⚠️ 可播放性未逐一实测：amr / flac / opus 在部分浏览器内核上播不了 ⇒ 客户端以实测为准，播不了就照实提示（不假装；绝不给一个播不了的 url）。「能播」必须是格式级结论，不得靠「扩展名看起来像音频」就宣称可播。
⚠️ 没有「删除一条语音副本」的 API：保留期 GC 是唯一出口（DOCUMENT_RETENTION，默认 168h）。

4.6 `chat` 请求与响应面

请求体（POST /api/v1/chat 与 WS chat 帧 data 同形）：

{"sessionId":"web","text":"...","image":"<base64/data:/URL>","deviceId":"web:chrome:a1b2c3",
 "mode":"chat","clientMsgId":"<uuid>","documents":[{"name":"a1b2....md"}],"parallel":true,"stream":false}

sessionId 省略 → "web"。
deviceId：客户端端标识（如 web:chrome:a1b2c3），随消息落库。
mode：行为模式（如 chat/code/home/…），随该回合落库；缺省回落 chat。
image：base64 data: URI、裸 base64 或 http(s) URL。上限按形态不同（判据是字符串长度，不是解码后字节），见 §4.5。
stream：仅 REST 用，见下。

同步（非 stream）响应面：

情形	状态	载荷
正常跑完	`200`	`{data:{reply,steps,stopReason}}`
幂等键重复	`200`	`{data:{duplicate:true,messageId,sessionId}}`
忙、已续接排队	`202`	`{data:{queued:true,queueDepth}}`
忙、显式并行且照准	`202`	`{data:{parallel:true,turnId:"turn-…"}}`（拿不到同步 reply；文本经 WS 流式到达）
队列满	`409`	`{error:{code:"chat_busy"}}`
空回合（无 text/image/documents）	`400`	`{error:{code:"bad_request"}}`
`image` 字符串超长（仅 base64 / `data:` 形态会触发；URL 形态不会）	`400`	`{error:{code:"image_too_large"}}` —— 在解码/落库/入模型之前拒；上限 = `CHAT_IMAGE_MAX_BYTES` 换算出的字符上限（默认 6990572 字符），见 §4.5
未接 loop	`500`	`{error:{code:"chat_unavailable"}}`
回合内部报错	`500`	`{error:{code:"chat_failed"}}`

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}}`
已升为独立并行路	`200`	`{data:{stream:true,parallel:true,turnId:"turn-…"}}`
未接 loop	`500`	`{error:{code:"chat_unavailable"}}`
仅未接编排器时的总线派发失败	`503`	`{error:{code:"chat_dispatch_failed"}}`

不再有「先回 200 再看有没有落地」；202/409 真的会出现。派发用的回合上下文与请求作用域脱钩（WithoutCancel + 30 分钟上限），回合不会在客户端刚收到 200 时被连带取消。

忙时并行（v0.65 起，parallel:true，仅显式声明时生效）：

触发权在客户端：服务端不做任何启发式自动升级。空闲时 parallel 无效果（照常起第 1 路）。
会话忙且单会话并发额度未满（默认 2，硬上限 3）⇒ 本条升为一条独立并行路立即起（见上表 {parallel:true,turnId}；该 turnId 随后出现在这一路的 turn_begin 帧壳与全部流帧帧壳上）。
额度已满、或真并行被 <2 关掉 ⇒ 落回排队语义（202 {queued:true,queueDepth}）并在 pending_ack 带 reason:"parallel_limit"。
在途路数经 activeTurns 出现在忙态帧（session_busy/session_idle/pending_drain/session_interrupted）与 turn_begin.data 中。
session_idle 时点收紧（仅并行时与旧行为不同）：所有在途路收尾且 pending 空才报空闲（单路时逐字不变）。
每一路起跑都发一帧 turn_begin（v0.66 落地，见 §3.4.3）——客户端据此把用户气泡钉到路、并按 sessionId + turnId 两级分桶。
省略 parallel 的客户端行为逐字不变。
⚠️ env CHAT_MAX_PARALLEL_TURNS 未接线（见 §5、§7）：生产恒为默认 2。

4.7 枚举权威表

GET /api/v1/meta/enums → {data:{platforms,moods,modes,unknown}}，每项 {id,label}。

platform：web、kook、qq-obv11、weixin-ilink、telegram、webhook。
mood：calm、happy、excited、sad、angry（可扩展，非封闭集合）。
mode：chat、code、home、work、docs、voice、vision、agents、settings。
unknown 恒 "display-raw"：未知取值原样显示——不丢弃、不报错、不替换占位符。判定只比对 id（大小写敏感）；label 仅默认显示。服务端新增取值是非破坏性变更。
⚠️ 未确证：上表逐值取自 internal/contract/enums（本文档经归档版转述，未逐一回代码核对）。客户端应直接读本端点而非硬编码。

4.8 `interrupt` 的 `scope` 与 `turnId`

上行 {"type":"interrupt","data":{"sessionId":"web","scope":"current","turnId":"turn-…"}}。

scope 取值域 {"", "all", "current"}（大小写敏感，只容忍首尾空白）：
- 省略 / "" / "all"：取消全部在途路并清空待处理队列（历史语义）。
- "current"：只取消在途路（多路时为每一路），保留待处理队列（队列消息按正常续跑规则继续执行）。
- 其它取值 → 定向回发送者 {"type":"error","data":{"code":"bad_request"}}（不广播、不打断任何会话，绝不静默按默认执行）。
turnId（v0.66 落地）：只在 scope:"current" 时生效，只取消该 turnId 那一路（其余在途路与待处理队列不受影响）。省略 scope 或 scope:"all" 时按契约忽略 turnId（服务端只留一条 debug 日志，响应面不变）。
- 目标不存在（已收尾/已取消/id 写错）⇒ 定向回 {"code":"bad_request"}（只到发送者，不广播、不动任何会话），绝不静默降级成「停全部」。
- 省略 turnId 的 scope:"current" = 作用于每一路（v0.65 原口径，逐字不变）。
scope:"all" 不发 session_idle：客户端靠 session_interrupted 收口。
命中空闲会话为 no-op。

4.9 会话角色绑定

会话角色（personaId）创建时确定、之后不可变（design/22 §8-1）：POST /sessions {personaId} 在创建时绑定；PATCH /sessions/{id} 携带 personaId 键一律 400。
空/缺省 = 继承全局默认角色（owner.yaml:defaultPersona）。
消息 DTO 的 personaId = 该消息说话时的角色（assistant = 生成它的角色，user = 当回合角色；空 = 默认角色）。

4.10 v0.68 新增：配置事实面与后台思考行的紧急度

(a) `GET /api/v1/admin/config-facts`（只读，`owner`/`admin`）

响应 {data:{facts:[…], quietHours:{…}}}：

键	类型	说明
`facts[].key`	string	env 键名，与 `.env.example` 逐字一致（后端有测试钉住）
`facts[].value`	string	进程生效值（已解析：bool → `"true"`/`"false"`；整数 → 十进制；比例 → 归一化小数如 `"0.8"`）。不是 `.env` 原文
`facts[].default`	string	该键的声明默认值（`internal/config` 结构体 `default:"…"` 标签，唯一真源）
`facts[].isDefault`	bool	`value == default` ⇒ 面板显示「默认」（不代表 `.env` 里没写过这个键：网关按红线不读 `.env`，无从不区分「默认层」与「结构体默认」）
`quietHours.startHour` / `endHour`	int	安静时段的生效钟点（本地时区小时）。⚠️ 报的是运行时真正生效的那一个：两端都写 0 时按「未填」回落到声明默认（见下 `fallbackToDefault`）
`quietHours.disabled`	bool	窗口是否关闭（两个相等的非 0 钟点，如 `23/23`）
`quietHours.label`	string	面板可直接显示的文案：`"23:00-07:00"` 或 `"已关闭"`
`quietHours.fallbackToDefault`	bool，可选（`true` 才出现）	两端都被写成 `0` ⇒ 视为未填，运行时回落到默认窗口（`23:00-07:00`，此时 `startHour`/`endHour` 已是回落后的值）。⚠️ `0/0` 不是「关闭」：backthink 与记忆整理都会做这次回落，事实面按同一口径报，否则会把「未填」谎报成「已关闭」

固定 13 条事实（记忆整理 8 键 + 后台思考心跳 3 键 + 安静时段 2 键）：MEMORY_TIDY_ENABLED、MEMORY_TIDY_INTERVAL_SEC、MEMORY_TIDY_QUIET_START_HOUR、MEMORY_TIDY_QUIET_END_HOUR、MEMORY_TIDY_RECALL_THRESHOLD、MEMORY_TIDY_SCAN_LIMIT、MEMORY_TIDY_CANDIDATE_LIMIT、MEMORY_TIDY_COMPARE_LIMIT、ENABLE_BACKGROUND_THINKING、THINK_INTERVAL_SEC、THINK_QUIET_INTERVAL_SEC、QUIET_START_HOUR、QUIET_END_HOUR。
🆕 v0.75 追加（同一端点、无版本化形状变更）：ENABLE_BACKGROUND_THINKING / THINK_INTERVAL_SEC / THINK_QUIET_INTERVAL_SEC 三键并入事实表（design/12 §N A4）—— 安静时段降频上线后，面板必须能读到「普通心跳周期」与「安静窗口内的心跳周期」。⚠️ THINK_QUIET_INTERVAL_SEC ≤0 = 关闭降频（回落普通间隔，不是「半夜不思考」），事实面照原值回，不替用户改写。⚠️ 这几个键都是启动期读取的：改了要重启才生效（不可热改）。⚠️ ENABLE_BACKGROUND_THINKING 是未接线的死配置（全仓无消费者，见 §5「配了不生效」）：它被列进事实表是为了让面板看得见，value 只是它解析出来的值，不代表它会生效；面板文案必须标明（见 frontend/web/src/admin/modules/configFacts.ts）。
🆕 v0.77 追加（同一端点、无版本化形状变更）：MEMORY_TIDY_COMPARE_LIMIT 并入事实表（切片 MT-A）—— 它是每分区每轮真正参与两两比对的条目上限，默认 2000；此前写死为 400 且没有 env 键（实测后果：459 条的分区被截到 400 ⇒ compared(705) < scanned(784)，观测口径被上限决定）。列进事实表是为了让面板看清「这项是不是还是默认值」。与记忆整理那组键一样是启动期读取的：改了要重启才生效。
🔴 不含任何凭据：响应里不出现 JWT 密钥 / LLM API key / 渠道 token / 数据库 DSN 的值（后端有哨兵测试钉死），也不回凭据类键的「是否已配置」 —— 本端点只覆盖上面 13 个非敏感调参键。
「默认 / 已改」怎么读：isDefault:true ⇒ 面板显示「默认」（生效值等于该键的声明默认值）；isDefault:false ⇒ 显示「已改」。⚠️ 它不是「.env 里没写过这个键」的断言 —— 网关按红线不读 .env，无从不区分「.env 给的值恰好等于默认」与「完全没配」。哪一项没配因此不会被伪造成一个值：面板拿 value + isDefault 如实展示即可。
13 条事实的 default 必须都能取到（后端有测试逐条钉住非空）：取不到即「配置结构体 ↔ 事实表」漂移，属缺陷，不是「未配置」。
安静时段的语义（重要，别照旧实现写文案）：安静时段只服务「定时主动思考 → 主动搭话」（design/12 §6 策略五），不静默回复 —— 白天晚上的聊天回复都不受它约束；群聊也没有夜间静默（主人裁决 10）。因此面板文案不得写成「夜间全静默」。

(b) `GET /api/v1/admin/backthink` 条目的紧急度字段（v0.68 引入；v0.70 起是精确档位）

键	类型	说明
`urgency`	string，可选	`"routine"` / `"warning"` / `"critical"`（`internal/urgency` 的档位词汇）。默认 = 该轮实际生效的精确档位（随记录落库）。只有与 `urgencyLowerBound:true` 同时出现时才读作「下限」（`warning` = 至少 high、可能更高）
`urgencyLowerBound`	bool，可选（`true` 才出现，v0.70 新增）	该行没有落库档位（`urgency` 列出现之前的旧行，或从未走到档位判定点的行）⇒ `urgency` 是由安静时段窗口规则反推出的下限，不是精确档位
`quietHoursBypassed`	bool，可选（`true` 才出现）	该轮穿透了安静时段：轮次时间落在安静时段窗口内且该轮判定为「要推送」

取值优先级（v0.70，客户端按这个顺序读）：
1. urgency 存在且 urgencyLowerBound 缺席 ⇒ 精确档位，可直接显示（critical 即安全域，warning 即 high）；
2. urgency 存在且 urgencyLowerBound:true ⇒ 下限，只可显示为「≥ X」（≥ 高 = 至少 high、可能更高；≥ 例常 = 只确定不低于最低档），不得显示成精确值；
3. urgency 缺席 ⇒ 未知（存档里没有这个事实），面板显示「未知」而不是「例常」——把未知画成「例常」与把下限画成精确值，是同一类「把猜当事实」。
三个键都可能缺席，缺席 ≠ 常规档位。旧行（urgency 缺席）出现 urgencyLowerBound:true 的情况不存在：没有值就没有可标记的下限。
旧行（无落库档位）与 quietHoursBypassed 的口径（v0.68 起不变）：只在该轮时间落在安静时段窗口内时给出下限 —— 窗口内被放行 ⇒ warning（由 backthink.Decide 的级联可证：安静时段只放行 ≥ high 的轮次）且 quietHoursBypassed:true；窗口内被扣下 ⇒ routine。窗口之外的旧行判定不看档位、存档里也没有档位，故不下发。窗口口径与 B12 的 quietHours 同一份（含「0/0 视为未填、回落到默认」这条），因此 0/0 的部署也不会漏报穿透。
quietHoursBypassed 与既有的 bypassed（v0.66 前已有，含义是事件驱动绕过限频闸）是两件事，别混用：前者说「安静时段」，后者说「限频门」。
⚠️ 实时帧（v0.70 更正）：/ws/chat 下行的 backthink 帧其 data 是 bus 上发布的原始 backthink.Record（Go 字段名 ID/Trigger/ShouldPush/PushResult…）。该记录自 v0.70 起带 urgency（该轮实际生效的精确档位，非下限） ⇒ 实时行同样可显示精确档位，不必等重开页面。但实时帧仍不带 urgencyLowerBound 与 quietHoursBypassed：这两个键是网关读历史时按安静时段窗口推导的，不在记录里（urgencyLowerBound 对实时行也不会出现——实时行要么有精确档位、要么无档位）。⚠️ 原 v0.68 表述「实时帧不带这两个键」对 urgency 已过期，本版更正；对 quietHoursBypassed 仍然成立。

(c) 档位的来源与诚实边界（v0.70 重写）

精确档位（默认路径）：backthink.Record.Urgency 由 backthink 在档位判定点原样落库（该轮实际生效的档位，含她自报紧急度上抬后的结果）⇒ 网关优先读它并原样下发，与安静时段窗口、与时间戳都无关。因此「白天的一轮」如今也有精确档位（v0.68 时代窗口之外一律显示「未知」）。
下限推导（只对没有落库档位的行）：该列为空的行 —— 该列出现之前的旧行，以及从未走到档位判定点的行（系统事件降级、思考失败）—— 才回落到 v0.68 的安静时段窗口推导，并必须带 urgencyLowerBound:true。⚠️ 旧行不得被显示成精确档位，未知也不得被显示成某个档位。
每轮 Import 落库（urgency 列）在 X2a 切片实现（213aff2）；「该轮实际生效」的取数点见 internal/services/backthink/backthink.go 的判定点。⚠️ 本版不改 quietHoursBypassed 的语义。

4.11 链路图快照 + 多轮历史回放（`GET /api/v1/admin/flow/graph`；v0.71 新增，v0.73 增量，v0.77 增量）

为什么有这条：graph_update（§3.4.5）是纯实时帧 —— 后端在每个 span 开始/结束时广播一次，不重放；前端把图存在内存的会话图桶里（flowGraphs）。于是「轮次结束后才打开页面」或「刷新过页面」看到的永远是空态（/#/admin/flow 的「暂无流程」、后台思考行「查看完整链路导图」的「该会话还没有 graph_update 快照」）。v0.71 补上打开页面时按会话只读拉一次最近一轮的快照；v0.73 再补上本地落盘 + 多轮历史回放 —— 图从「只活在进程内存」变成每轮一行落进本地库（新表 flow_graphs，迁移 0022），后端重启后仍能查回，且可按 turnId 翻更早的轮次（design/19 §4 的 P3）。

(a) 请求与响应

项	值
方法 / 路径	`GET /api/v1/admin/flow/graph`
鉴权档	`writeAuth`（owner / admin；`viewer` → `403`，未认证 → `401`）。与 `design/19 §3`「flow 可视化仅 owner/admin」一致
查询参数	`sessionId`（可选）。省略 / 空串 ⇒ 主会话 `web`（`internal/runtime/history.MainSessionID`）。其它取值就是该会话 id，如 `sess-backthink`（后台思考，design/20 §2）、`web:<uuid>`（次级会话）。v0.73 新增 `turnId`（可选）：省略 / 空串 ⇒ 最近一轮（先查内存 `loop.FlowPublisher.LastGraph`，miss 才回退落盘 ⇒ 最新一轮永远是最新的）；给了就是该会话已落盘的某一轮 —— 取值一律用响应里的 `turns[].turnId` / `graph.id`（🔴 v0.79 起单路也带 `#{回合标识}` 后缀，形如 `web-7#turn-3f9c…`；不要自己拼 `{会话}-{序号}`），且该值可能含 `#`、作 query 值必须 URL 编码
响应体	`{data:{sessionId, turnId, source, graph, lanes, turns}}`（v0.73；v0.71 只有 `{sessionId,graph}`；v0.77 新增 `lanes`）。`sessionId` = 解析后的会话；`turnId` = 实际返回的那一轮的标识（无图时 `""`）；`source` ∈ `"live"`（内存最近一轮）/`"persisted"`（落盘的历史轮）/`"none"`（没有图）；`graph` = 该轮的图或 `null`；`lanes` = 最近一轮每一路的图 `[{turnId,graph}]`，按路的开始时间升序（最早的在前）—— 与 `?turnId=` 无关（翻历史轮时 `lanes` 仍报「当前这一轮的各路」，`graph` 才是你指定的那一轮），恒为非 null 数组（图源未接线 / 没有路时是 `[]`）；`turns` = 该会话已落盘轮次摘要 `[{turnId,createdAt}]`，最新在前（未接线持久化或没有轮次时是 `[]`，恒为非 null 数组）
`graph` / `lanes[].graph` 形状	与 `graph_update` 帧的 `data` 逐字同形（§3.4.5：`{id,nodes[],edges[],sessionId,turnId?,round?,startedAt,endedAt}`，节点 `props`/`log` 同 §1.1 的脱敏口径）。`turnId` / `round` 为 v0.77 新增的可选键（缺席语义见下方 (d)）
归档	不审计（只读查询，与同档的 `/admin/llm`、`/admin/config-facts` 一致）
失败	图源（内存 + 落盘）都没接线 ⇒ `500 {"code":"flow_unavailable"}`（不假装「这一轮没有图」）；该轮确实没有图 / 该 `turnId` 不存在 ⇒ `200` + `graph:null`（`source:"none"`）。落盘查询本身失败（库不可用）⇒ 同样 `500 flow_unavailable`（不把「读库失败」伪装成「没有这一轮」）

(b) 语义硬约束（客户端必须照这个读）

省略 turnId = 「最近一轮」而不是「你要的那一轮」。 省略或空串时后端先取内存里该会话最新的一张图（loop.FlowPublisher.LastGraph，即正在跑/刚跑完的那一轮），取不到才回退到落盘的最新一行 —— 因此「最新一轮永远是最新的」。不给 turnId 就不要假定它等于你眼前那条记录那一轮：后台思考行上点开的图可能不是该行那轮 ⇒ 面板必须说明（当前实现：frontend/web/src/admin/modules/flow/FlowSnapshotHint.tsx）。要精确取某轮就带上 turns[].turnId。
给了 turnId = 精确取那一轮。 该 turnId 正好等于内存里最新一轮 ⇒ 回内存图（source:"live"，更实时）；否则读落盘行（source:"persisted"）。该轮不存在 ⇒ graph:null + source:"none"（诚实空态），绝不用别的轮次顶替。
只读、不发布。 拉快照不产生 graph_update 帧、不改变发布白名单、不改变任何会话的实时图、也不落盘。
graph:null 是诚实的空。 该会话从未跑过有 span 的轮次、或图源里没有该会话（如发布白名单之外的隔离渠道会话 sess-xxx 从未建图、也从不落盘）时返回 null ⇒ 客户端必须渲染空态，绝不允许补画任何节点/假图。
落盘只覆盖发布会话白名单内的会话，且每轮一行（EndRound 时写入，不是每 span 一行）：图里可能含用户输入文本 ⇒ 客户端按既有 §1.1 脱敏口径读即可，但不得把图当成「有全部原文」的凭据。落盘件按保留期清扫（FLOW_GRAPH_RETENTION，默认 168h），过期轮次会被回收 ⇒ turns[] 只反映「仍在保留期内」的轮次。
快照会晚于实时帧到达，反之亦然。 客户端已有实时图时不应被快照覆盖（实时图更新；快照只是补冷启动的洞）——当前实现只在本会话还没有任何图时才拉。
不替代 graph_update。实时帧仍是「正在跑的那一轮」的唯一来源；本端点补的是「已经跑完、帧已经错过」的那些轮次（最近一轮 + 可选的任意历史轮）。
lanes[] = 最近一轮每一路的全貌（v0.77）。 真并行（parallel:true）时同一会话同一轮有多条路，后端每一路各建一张图、各落一行；本端点的 graph 只给其中最新的一路（向后兼容，老的读取方零改动），lanes[] 才是全部（每项 {turnId,graph}，按路的开始时间升序，恒为非 null 数组；前端在 lanes.length > 1 时按并列泳道呈现）。⚠️ lanes[] 不跟随 ?turnId=：它恒报「当前这一轮的各路」（取内存里的实时图），graph 才是你要的那一轮。

(c) 与 design/19 的关系

design/19 §4 把「多轮历史回放」列为 P3；v0.71 落实了 P3 里最小的一步（每会话最近一轮的只读快照），v0.73 把 P3 补全（本地落盘 + 按 turnId 取任意保留期内的轮次 + 轮次列表）；v0.77（切片 FV2）补上 lanes[]，并把图按 {会话}#{路} 分桶（此前同一会话并行两路会互相顶掉，见 §7.4-19）。三者都不改 design/19 §1 的发布会话范围（web / web:<uuid> / sess-backthink，裁决 01.4.5）、不改前端图桶的按会话分桶口径（裁决 16.4.2）。落盘载体是新表 flow_graphs（迁移 0022），GC 口径照 events/documents（env 键 + 启动期扫一次 + 定时扫 + 失败不退出）。v0.80（切片 W1）另开 §4.11.1 的时间轴端点（GET /api/v1/admin/flow/timeline）负责「多轮按时间串联」—— 本小节的语义（最近一轮 / 按 turnId 取某一轮 / lanes[] / turns[]）一字未改（两条出口读同一份落盘数据，分工见 §4.11.1(c)）。

(d) `turnId` / `round` 的增量键与缺席语义（v0.77）

graph_update 帧的 data 与本端点返回的每张图（graph / lanes[].graph）同一个结构；v0.77 起多两个可选键（老客户端忽略未知键仍可用）。⚠️ v0.79 变化：turnId 不再只对真并行路出现 —— 编排器驱动的每一路（含普通单路回合与队首续跑路）都带它，且 graph.id 据此对单路也追加 #{回合标识}（见下）；round 的语义一字未改。

键	类型	语义
`turnId`	string	这张图所属路的权威回合标识（与 `turn_begin` / `steer_ack` / 流帧帧壳的 `turnId` 同值，design/15 §2.5.9）。缺席语义：这一路没有权威标识（未接编排器的调用方、后台思考 `sess-backthink`、旧后端，以及 v0.79 之前的单路历史帧）—— 此时客户端按「该会话那一张图」处理，不得臆造一个 id。⚠️ v0.79 起编排器驱动的每一路（含普通单路回合与队首续跑路）都带该键 ⇒ 它不再只对真并行路出现。⚠️ 它不是 `?turnId=` 的参数（后者是 `graph.id`，两者不同源，见 §7.4-23）
`round`	number	这张图所属的会话轮次号（每会话单调；同一条消息引出的多条路共享同一个值）。客户端据此只保留最新一轮的泳道、丢掉更早轮次的路。缺席（`0`）语义：旧后端 / 未设置 —— 客户端保守处理（保留已收到的路，不按轮次淘汰），不得臆造轮次号

真并行（上行 chat.parallel）时同一会话每一路各发自己的帧（data.id / data.turnId 各不相同），因此两路不再互相覆盖；每路的图也各占一行落盘（flow_graphs 的唯一键 (session_id, turn_id) 因此不再把另一路整行顶掉）。
graph.id 的形状自 v0.77 起是 {会话}-{序号}[#{权威回合标识}]（序号是发布器进程内的建图序号、重启即从头开始）。🔴 v0.79 起后缀对单路也追加（此前只对真并行路）—— 即每一条编排回合的 graph.id 都含 #（web-7 → web-7#turn-3f9c…）；老行（v0.79 之前落盘的单路行）仍是 {会话}-{序号}。它是 ?turnId= 的参数值，不透明，可能含 # ⇒ 作 query 值必须 URL 编码（Web 前端用 URLSearchParams，已正确编码），且客户端一律用响应给出的值、不要自拼。

4.11.1 链路图时间轴（`GET /api/v1/admin/flow/timeline`；v0.80 新增，切片 W1）

为什么有这条：§4.11 的老端点回答的是「最近一轮」与「已落盘轮次的键列表（turns[]）」—— 两者都不足以把多轮按时间串起来；graph_update 又只覆盖当前这一轮。于是面板上「所有消息按时间顺序串起来」这件事此前没有任何数据出口（主人 2026-10-06 原话）。本端点补上它，且不改老端点的任何语义。

(a) 请求与响应

项	值
方法 / 路径	`GET /api/v1/admin/flow/timeline`
鉴权档	`writeAuth`（owner / admin；`viewer` → `403`，未认证 → `401`）。与 B13 / `design/19 §3` 同档
查询参数	`sessionId`（可选；省略 / 空串 ⇒ 主会话 `web`）、`limit`（可选；缺省 50、硬上限 200（超上限即钳住）、`≤0` 同缺省、非整数 → `400 bad_request`）、`before`（可选游标；省略 = 最新那一页；给定时只返回开始时刻严格早于它的轮次；取值 = 上一次响应里的 `nextBefore`，也接受 RFC3339 或 Unix 毫秒；非法 → `400 bad_request`）
响应体	`{data:{sessionId,source,rounds[],nextBefore,hasMore,truncated,retentionHours,retentionEnabled}}`
`rounds[]`	恒为非 null 数组（没有轮次时是 `[]`），按时间正序（最早在前）。每项 `{turnId,round,startedAt,endedAt,lanes[]}`；`lanes[]` 恒为非 null 数组（每项 `{turnId,graph}`，按路的开始时刻升序）
`rounds[].turnId`	这一轮首路的图 id（`graph.id`，真 id）。多路时它只代表首路，全貌在 `lanes[]`（每路的图 id 见 `lanes[].graph.id`、每路的路标识见 `lanes[].turnId`）⚠️ 与 `lanes[].turnId` 不同源（前者是图 id = 老端点的 `?turnId=` 参数值；后者是路标识，见 §4.11(d)）
`rounds[].round`	number 或 `null`。`null` = 未知（那批行早于轮次号落库）⇒ 客户端不要当成 `0`；不保证连续（轮次号 = 该轮首路的建图序号，真并行时中间会跳号）
`rounds[].startedAt` / `endedAt`	UTC RFC3339 毫秒（与本端点游标同一口径）。`endedAt` 为空串 = 这一轮尚未收尾（内存里的在飞轮）⇒ 面板显示「进行中」，不得补一个结束时刻
`rounds[].lanes[].graph`	与 `graph_update` 帧的 `data` 逐字同形（§3.4.5；`{id,nodes[],edges[],sessionId,turnId?,round?,startedAt,endedAt}`，节点 `props`/`log` 同 §1.1 的脱敏口径）
`source`	`"persisted"`（本页至少有一轮来自落盘；可能同时含内存里的在飞路）/`"live"`（本页全部来自内存：落盘源未接线，或该会话还没有落盘轮）/`"none"`（没有任何轮次）
`nextBefore`	本页最早一轮的开始时刻（无轮次时 `""`）。`hasMore:true` 时原样回带成下一次请求的 `before` 即可继续向更早翻页
`hasMore`	库里还有更早的轮次没被本次返回（用 `nextBefore` 继续取）
`truncated`	本次不是全部：`hasMore`（分页未到底）或落盘源未接线（只剩内存最近一轮）。面板据此标注「更早的轮次未显示」，绝不静默少一块
`retentionHours` / `retentionEnabled`	落盘保留期（小时，下取整）与它是否启用（`FLOW_GRAPH_RETENTION`，既有 env 键、默认 168h）。`retentionEnabled:false` ⇒ 「更早的轮次」不是被清扫掉的，不要说成过期
归档	不审计（只读查询，与 B13 同档）
失败	内存与落盘都没接线 ⇒ `500 {"code":"flow_unavailable"}`（不假装「这个会话没有轮次」）；落盘读取失败 ⇒ 同样 `500 flow_unavailable`（不把「读库失败」伪装成「没有这一轮」）；`limit` / `before` 非法 ⇒ `400 bad_request`

(b) 语义硬约束（客户端必须照这个读）

它是「多轮并联」，不是「最近一轮」。 老端点（§4.11）继续负责「最近一轮 + lanes[] + turns[]」，本端点负责「按时间串起来的多轮」。两者读同一份落盘数据，但语义不同：本端点的 rounds[] 是时间轴（正序、分页），老端点的 graph 是你要的那一轮。
🔴 一句话轮（round）与路（leg）不可混用（design/19 §6.0）：rounds[] 的一格 = 一轮（一条用户消息引出的全部工作），一轮里每一路在 lanes[] 里各有 {turnId,graph}。真并行时同一轮会有 2~3 条路 —— 不要把两条路画成两轮。
🔴 保留期只说真话：过期轮次不会出现在 rounds[] 里（已被清扫），本端点不猜、不补空块。面板要说明「更早的轮次已过保留期」时，判据只能是 retentionEnabled + retentionHours + truncated（三者一起读），不得因为「返回的轮次比想象中少」就断言被清扫了。
分页不重不漏：before 恒为「严格更早」，nextBefore 恒为「本页最早一轮」。逐页往更早翻时，已返回过的轮次不会再出现。⚠️ 游标精度到毫秒（与 startedAt 字符串同一口径）；同一毫秒里启动的两个不同轮次在极端情况下可能被一并跳过 —— 实际不成立（同一会话的轮次启动间隔远大于 1ms），但这是真实存在的理论边界，不作隐瞒。正解（若将来需要）是复合游标 (startedAt, roundKey)，属新契约、本版未做。
内存里的在飞轮会出现（source 可能是 live、endedAt 可能是空串），这是有意的：面板打开时最新一轮还在跑，不该在时间轴上缺席。它与刚落盘的那一份同一条路只出现一次（按图 id 去重，以落盘那份为准）。
只读、不发布、不落盘：拉时间轴不产生 graph_update 帧、不改任何会话的实时图、不动保留期、不写审计。
白名单外的会话是诚实空态：隔离渠道会话（群聊/陌生人 sess-xxx）从不建图、也从不落盘 ⇒ rounds:[] + source:"none"。这不是「这一轮没有链路」。
不替代 graph_update：实时帧仍是「正在跑的那一轮」的实时来源；本端点补的是「多轮 + 已错过帧」。

(c) 与老端点 `turns[]` 的分工（别把两者混成一条时间轴）

§4.11 的 turns[] 是**按路（leg）列的条目（一轮两路会显示两条，形状 {turnId,createdAt}）；本端点的 rounds[] 是按轮（round）**分组的时间轴（一轮两路并进同一格的 lanes[]）。⇒ 面板要「轮次列表（含各路）」就用本端点；要「按图 id 精确取某一轮」仍用老端点的 ?turnId=。

(d) 未确证（如实）

graph_json 破损行：SQL 侧用嵌套 json_valid 保护（坏行不会拖垮整条查询），但该行若落进本页，解码会如实报错 ⇒ 500 flow_unavailable（与既有 graph / graph_turns 口径一致：读不懂就报错，绝不把坏行当「没有图」）。这条路径没有测试（2026-10-06 复核：internal/services/gateway/admin_flow_timeline_test.go 现有 9 条用例，无一条喂坏 graph_json ⇒ 结论仍是「未确证」）。
前端渲染与真机面板联调不在本条证据内（后端出口的单测覆盖见切片 W1 报告）。代码级已确证：前端有 view="timeline" 模式（frontend/web/src/admin/modules/Flow.tsx）+ flow/TimelineView.tsx / useFlowTimeline.ts；真机 GET /api/v1/admin/flow/timeline（无凭据）回 401 unauthorized（路由已随在跑产物部署，不是 404）。仍未确证：浏览器里真面板跑通 —— 为什么验不了：本轮禁重启后端 / 禁换产物，且取不到 owner 凭据，无法做面板联调（红线：不重启后端、只读验证）。

4.12 记忆整理「试算」（`POST /api/v1/admin/memories/tidy/dry-run`；v0.75 新增）

为什么有这条：记忆整理是一件低峰定期后台任务（design/23 §4）：默认只在安静时段（MEMORY_TIDY_QUIET_START_HOUR–_END_HOUR，默认 23:00–07:00）由心跳开跑。于是在它第一次开跑之前，库里既没有候选也没有轮次留痕 ⇒ 面板只能空着，主人无法判断「整理会不会乱合并」。本端点把同一套规则当场算一遍：候选直接回在响应里，一行都不写。

(a) 请求与响应

项	值
方法 / 路径	`POST /api/v1/admin/memories/tidy/dry-run`
鉴权档	`writeAuth`（owner / admin；`viewer` → `403`，未认证 → `401`）。与同页的 `/admin/config-facts`、`/admin/memories` 同档
请求体	可为空（端点不读 body）。没有参数：阈值/上限一律取进程生效的既有配置（`MEMORY_TIDY_RECALL_THRESHOLD` / `_SCAN_LIMIT` / `_CANDIDATE_LIMIT` / `_COMPARE_LIMIT`（v0.77 新增）），端点自己不带任何旋钮
响应体	`{data:{dryRun,recallMode,durationMs,ruleVersion,partitions,scanned,compared,pairs,vetoed,vetoReasons,truncated,candidates[]}}`
`dryRun`	恒为 `true`。它是结构化判据：这份响应没有改动任何记忆（客户端不必只靠本地硬编码文案说明这件事）
`recallMode`	`"embedding"`（语义向量召回）或 `"lexical"`（零依赖词项余弦，仅当进程没有接 embedder）
`durationMs`	本次试算的墙钟耗时（毫秒）
`ruleVersion`	规则集版本（`internal/runtime/memory` 的 `TidyRuleVersion`，进候选幂等键；改判定规则必须同时升它）
观测口径	`partitions`（含在册条目的分区数）/ `scanned`（扫描条数）/ `compared`（真正参与两两比对的条数，受 `MEMORY_TIDY_COMPARE_LIMIT` 与时间预算两道闸约束 —— 因此 `compared < scanned` 时要看 `truncated` 是不是指出了原因）/ `pairs`（相似度 ≥ 召回门的对数）/ `vetoed` 与 `vetoReasons`（否决数与原因分布，如 `scope`/`persona`/`project`/`source`/`temporal`/`numeric`/`conflict`/`low_confidence`）
`truncated`	可选数组：被护栏截断的分区标签（`<分区>(scan)` / `(compare)` / `(candidates)` / `(budget)`）。它不是候选；键缺席 = 本轮没有任何闸被打满（客户端可把 `candidates:[]` 读成「规则判过了，确实没有」）。前三种说明「配置的配额比本轮实际看到的少」；`(budget)` 是 v0.77 新增的第 4 种 —— 被墙钟时间预算截断（整分区跳过，或两两比对中途收手）：成因是本次调用的时间上限而不是配置配额（运维动作不同），命中它时「候选少」由预算而非规则决定
`candidates[]`	恒为非 null 数组（没有建议时是 `[]`）。每个元素见下表
归档	不审计：它是只读计算（跑规则、不落库），与 `/admin/config-facts`、`/admin/flow/graph` 同一档

候选元素（candidates[i]）：

字段	说明
`action`	`merge` / `link` / `archive` / `reclassify`（`keep` 不进候选队列）。`link` = 相似但互不包含 ⇒ 只建链接、绝不合并（design/23 §1.3 的「红牛 vs 冰美式」）
`sourceIds`	被处理的记忆 id 数组（恒为非 null）。`merge` 时是被并入方（可多条）；`link` 时是那两条
`targetId`	`merge` 时的存活条目（超集）；其余动作为 `""`（键省略）
`personaId` / `scope` / `projectId` / `kind`	分区键与被处理条目的 kind
`proposedContent` / `mergedContent`	`merge` 的 diff 预览：被并入的原文 / 存活条目的内容（其余动作为 `""`）
`reason`	机器可读理由（如 `containment_a_subset_b` / `similar_but_not_contained` / `one_off_event` / `kind_mismatch`）。客户端按它分支，不要按本地文案
`ruleVersion` / `scoreMin` / `scoreMax`	规则版本与召回分数区间（当前实现两者相等：一对一个分数）
`evidence`	判定证据：`similarity`（只用它召回，不是判据）、`recall_mode`、`containment`（`a_subset_b`/`b_subset_a`/`both`/`none`）、`containment_evidence[]`（缺哪一要素）、`veto_reason`、`kind_a`/`kind_b`/`proposed_kind`、`content_a`/`content_b`（两条原文，供面板 diff 预览）

(b) 硬约束（客户端必须照这个读）

🔴 零副作用：本端点不写任何表 —— 不写 memory_tidy_candidates、不写 memory_tidy_runs、绝不改 memory_items 的任何列。后端有「调用前后三张表逐行快照比对」的单测把它钉死。因此试算不会让面板的「候选队列」多出东西，也不影响当晚那次真跑的结果。
🔴 同一套规则，不是第二套实现：候选由与低峰定时轮共用的代码路径产出（同一召回门 + 同一包含判定 + 同一规则否决 + 同一每分区候选上限）。后端另有一条单测：同一批数据上「试算候选」与「真跑一轮落库的候选」逐字段一致。
🔴 失败绝不伪装成「没有建议」：未接线 / 配置关闭 / 语义召回不可用 / 超时都如实回错误码（见下表），不回 candidates:[]。客户端不得把 candidates:[] 与错误态渲染成同一件事 —— 前者是「算过了，这一轮确实没有建议」，后者是「没算出来」。
语义召回不可用时不静默降级：若进程接了 embedder 而它不可用（如 llama.cpp / :11434 连不上），试算报 tidy_recall_unavailable 而不是偷偷回退到词项余弦 —— 否则面板会把「语义路径没跑起来」当成「没有候选」。⚠️ 这是试算专属的严格：低峰定时轮与手动轮仍按既有口径回退到零依赖的词项余弦（recallMode:"lexical" 时可从 evidence.recall_mode 逐条读到）。
只算不写 ⇒ 不审计，也不产生候选队列：本端点不写审计链、不产生任何后续动作；apply/reject 是另外的、尚未实现的写端点（design/23 §11，本版不做）。
它是「现在就能看」，不是「调度改了」：试算不受安静时段约束（低峰窗口是心跳的调度口径，不是规则的一部分），也不改变整理周期与心跳（试算不写 lastRun、不影响 nextDelay）。面板按下才跑：它是一次真实规则计算（扫描 + 两两召回 + 包含判定），不是看板指标 ⇒ 客户端不要自动轮询它。

(c) 失败码

状态	`error.code`	触发条件	客户端应做什么
`500`	`tidy_unavailable`	组合根未注入试算出口（仅异常部署/测试）	显示「未接线」，不要显示「没有建议」
`409`	`tidy_disabled`	`MEMORY_TIDY_ENABLED=false`（显式关闭整理）	提示「整理已被配置关闭」，并指向该 env 键
`500`	`tidy_recall_unavailable`	语义召回（embedding 服务）不可用	显示具体原因类别；不要显示 0 候选
`503`	`tidy_timeout`	试算超过服务端墙钟上限（3 分钟）	可提示重试；不要显示 0 候选
`500`	`tidy_dry_run_failed`	其它内部失败（分区查询/规则执行出错）	显示错误；原始内部细节不会出现在 `message` 里

⚠️ 本端点的错误 message 只说明原因类别，原始错误（可能含内网地址等内部细节）只进服务端日志。

4.12.1 记忆整理「试算」的加性异步（`?async=1` + B15；v0.76 新增 · ✅ 已实现（v0.77 校正））

为什么有这条：试算在真机上实测 89.9 秒 / 744 条（784 条那轮同量级）。同步 HTTP 会被反代/客户端超时切断，而把上限抬高（治理「护栏被打满 ⇒ 候选数被上限而不是规则决定」）只会让它更慢。因此加一条可选的异步路径：默认行为一字不改（不带 async 仍是 §4.12 的同步语义），只在显式带 async=1 时改走后台。

项	口径
触发	`POST /api/v1/admin/memories/tidy/dry-run?async=1`（请求体与 §4.12 同：可为空）。只有字面量 `1` 触发异步：`?async=0` / `?async=true` / 缺省 / 空值一律走同步（老客户端逐字不变）
立即响应	`202` + `{data:{runId,status:"running",startedAt}}`；`runId` 为进程内不透明字符串（客户端当不透明值用，不要解析其结构）；`startedAt` 是那次运行真正开始的墙钟时刻（UTC RFC3339）—— 它是那次运行的时间，不是本次请求的时间
轮询	`GET /api/v1/admin/memories/tidy/dry-run/{runId}`（B15）⇒ `running` / `done`（带 `result`）/ `failed`（带 `error`）；`running` 时 `result` 与 `error` 两键都缺席（不造空 `result` 冒充「跑完了但没有建议」）
结果形状	`done` 时的 `result` = §4.12 同步响应的 `data` 逐字节同形（两条路径走同一个投影函数，后端有单测按原始 JSON 逐字节比对；含 `candidates` 恒非 null）
并发	同时只允许 1 个在跑；第二个请求复用既有 `runId`（实现取「复用」而非「拒绝」⇒ 不引入新错误码），回的 `startedAt` 是那次正在跑的运行的开始时刻；上一个跑完后，新请求才是新 `runId`
墙钟上限	与同步同一个 3 分钟（`tidy_timeout` 的语义对两条路径都成立）；超时 ⇒ 轮询回 `failed` + `tidy_timeout`（错误链含 `context.DeadlineExceeded`）
生命周期	进程内存（不落库、不新开端口）；TTL 30 分钟（从完成时刻起算，`running` 的记录不会被 TTL 淘汰；另有 32 条的条数闸兜底）；进程重启 ⇒ 旧 `runId` 失效
未知 / 过期 runId	`404` + `{error:{code:"tidy_run_not_found"}}`（见 §4.1 的 404 行）；「从未存在」「超 TTL」「进程重启过」三种原因刻意不区分（进程内不留跨重启痕迹）
鉴权	与 B14 同档（`writeAuth` = owner/admin）；不审计
零副作用	🔴 与同步路径同一条硬约束：异步跑的是同一个 `TidyService.DryRun`（同一套规则）⇒ 同样一行都不写 `memory_tidy_candidates` / `memory_tidy_runs`、绝不改 `memory_items`（memory 包与网关两侧都有逐行快照比对的测试钉住）
失败	沿用 §4.12 的失败码（`tidy_unavailable` / `tidy_disabled` / `tidy_recall_unavailable` / `tidy_timeout` / `tidy_dry_run_failed`）；`failed.error = {code,message}` 走同一个失败码映射点 ⇒ 两条路径不可能漂移；不回空候选数组假装「没有建议」。⚠️ `MEMORY_TIDY_ENABLED=false` 时异步仍接受（回 `202`），失败在轮询里如实报 `tidy_disabled`（同步路径仍是立刻 `409`）
破坏性	无（新可选参数 + 新端点；老客户端逐字不变）

✅ 落地校正（v0.77）：本小节与 B15 在 v0.76 登记时是「契约先行、尚未落地」；切片 MT-A 已落地（internal/runtime/memory/tidy_dryrun_async.go、internal/services/gateway/admin_memory_tidy_async.go、routes.go 注册 GET …/dry-run/{runId}）。上表各行即实现口径，不再有「实现口径见提交」的占位。仍然如实的两条边界：① 后台运行不随进程关停取消（关停时在途的异步轮次会被丢掉 ⇒ 客户端自然拿到 404）；② 结果不是缓存（每次调用重算，两次之间数据变了结果就可能不同）。

4.13 未读实时面：`message_persisted.data.unreadCount`（v0.76 新增 · ✅ 已实现）

帧形状（纯增量）

{"type":"message_persisted","sessionId":"web",
 "data":{"message":{…，见 §4.4},"unreadCount":3}}

项	口径
键名 / 类型	`data.unreadCount`，整数
含义	该会话此刻的绝对未读数 = 比会话读游标（`chat_sessions.read_at`）严格更新的消息条数。不是「自上次以来新增几条」，也不是每端各一份
口径来源	与 `GET /api/v1/sessions` 的元素 `unreadCount` 同一个谓词（`created_at > read_at`）、同一条游标 ⇒ 两条面在同一时刻给出同一个数字（后端有单测逐会话比对两者相等）
出现条件	只在 `>0` 且确实算得出来时出现（Go 的 `omitempty` 语义）。缺席 = 老行为（v0.75 及更早即如此），客户端忽略未知键即可
缺席的三种情形	① 未注入历史存储；② 注入的存储没有单会话未读视图；③ 该会话没有会话行（隔离渠道会话 `sess-`、后台思考会话 —— 它们连读游标都没有）。三种情形后端都不写 `unreadCount:0`：「算不出来」绝不冒充「已读完」*
何时该用	客户端落下这帧时直接用该数字刷新角标（不必再拉一次 `GET /sessions`）。键缺席时保持原值并回落 `GET /sessions` 收敛 —— 不要当成 0
何时会归零	由 `session_read` 帧（§3.4.1 状态帧表 / §1 U16）在任一客户端 `POST /sessions/{id}/read` 后广播；多端共享单游标：Web 读了，移动端的红点也清

多端共享单游标的取舍（与安卓侧已对齐，不是缺陷）

后端只有一个主人账号、这一层没有按设备的身份 ⇒ 游标是会话作用域、单所有者（chat_sessions.read_at，迁移 0010）：任一端已读即所有端已读。因此 unreadCount 是「主人还没看过的消息数」，不是「这台设备还没同步的消息数」。

🔴 客户端不得把它当「本端未读」渲染成「这条消息我没收到」（那就把跨端同步误报成了漏消息）。
🔴 不要自行改成「每端独立未读」（会引入第二份游标、并在多端之间互相打脸）；如确需改，属契约裁定事项，须先写进本节。

兼容性（逐字无破坏）

纯增量：新可选键，无新帧、无新端点、无既有键改名或语义变化。
老客户端（不读 unreadCount）行为逐字不变；新客户端读到缺键时的正确答案是「不知道」，不是「0」。
channel_persisted（隔离渠道会话）走同一个载荷构造函数 ⇒ 口径天然一致；实践上它永远不带该键（那类会话没有 chat_sessions 行，见上表第 4 行）。

服务端实现位置（供对照，非契约）：internal/services/gateway/broadcast.go（帧构造，Web 路径与 IM 路径共用同一个函数）、internal/services/gateway/session_read.go（unreadCountOf + 可选窄接口 sessionUnreadCounter）、internal/runtime/history/session_read.go（UnreadCount）。

4.14 插件管理面板接入点与动作分发（v0.78 新增，切片 PLG-2 / PLG-4）

(a) `GET /api/v1/admin/panels` —— 面板接入点快照（v0.78）

门：viewerAuth（owner / admin / viewer 皆可，见 §2.1 A13）。响应按调用者角色过滤：viewer 只拿到只读区块（status / log / table，且 table 的行内动作被摘空、form 整体不出现、区块全空的面板整条不出现）。未接线面板中枢时回 501 panels_unavailable（绝不回空列表把「没接线」伪装成「没有页面」）。

响应 data：

{
  "role": "owner",              // 本次快照按哪个角色裁剪（回显，便于客户端自检）
  "groups": [                   // §5.2.1 的 nav.group 一级
    {
      "id": "plugins",          // 分组 id（本期闭集只有 plugins）
      "title": "插件",          // 分组显示名 = 宿主文案（分组本身没有声明）
      "order": 20,              // 分组排序 = 组内最小 order
      "items": [                // nav.item
        {
          "pluginId": "web-search",
          "id": "providers",
          "title": "搜索提供商",
          "description": "…",   // 可选，缺省省略
          "icon": "search",     // 可选（宿主内置图标名），缺省省略
          "order": 20,
          "route": "plugin/web-search/providers",  // **相对**管理面板前缀
          "sections": [ /* design/09 §5.2 的 section 声明**原样**下发（字段名逐字同形） */ ]
        }
      ]
    }
  ],
  "pluginIds": ["web-search"]   // **声明过面板**的插件 id（已排序）；≠ 已安装列表
}

sections[] 就是 pkg/plugins/sdk 的 Section 形状（type / id / title / fields / submit.action / source.action / columns / rowActions / limit），宿主不翻译；插件不注入任何 JS/CSS/HTML。type ∈ {form,status,table,log}（form 是可写区块，其余只读）。
route 是相对片段（plugin/<pluginId>/<panelId>，不含 ADMIN_PATH 前缀）⇒ 前端拼成 <prefix>/plugin/<pluginId>/<panelId>。
pluginIds 是给「插件与能力」页做对照用的：拿它与 GET /api/v1/admin/plugins/installed 的 name/id 求差集即可得到「已装但未声明任何页面」的插件，客户端应把这类插件如实显示成「未声明管理页面」，不得藏掉。

错误：501 {error:{code:"panels_unavailable"}}（未接线）；403 unknown_role（角色无法识别，理论不可达，fail-closed）。

⚠️ 当前运行期快照不是空的：内置插件 web-search（plugins/tools/io/search 的 AdminPanels()）在组合根装配期声明给中枢 ⇒ 正常部署下 pluginIds == ["web-search"]。热装插件（MCP 等）目前恒为「未声明管理页面」（声明来源 manifest.json 的读取未实现，见 §7.2）。

(b) `POST /api/v1/admin/plugins/{id}/actions/{action}` —— 插件动作分发（v0.78）

路径：{id} = 插件 id（面板目录键，本期即插件名，如 web-search）；{action} = 插件声明过的动作名（如 plugin.listProviders）。

门：路由中间件 viewerAuth，写动作在 handler 内再按 owner/admin 收紧（见 §2.1 A14）。

情形	状态	`error.code`	说明
面板中枢未接线	501	`panels_unavailable`	未接线就说未接线
动作名未在声明里出现过	404	`action_not_declared`	§5.2.1「只接受该插件声明过的动作名」；未声明不是「没权限」
插件已被显式停用	409	`plugin_disabled`	声明还在，入口与动作都下线
`kind=write` 且调用者不是 owner/admin	403	`forbidden`	写面 = `form.submit` + `table.rowActions`（§5.4.1）
已声明，但宿主没有登记它的处理器	501	`action_not_implemented`	✅ v0.79 起不是兜底档：内置 web-search 的动作已全部登记 ⇒ 这条只在「声明写了却没实现」时出现
请求体不是合法 JSON，或超过 1 MiB	400	`bad_request`	绝不把坏体当空体继续跑
载荷形状不对（缺 `values` / 缺 `provider` / 类型错）	400	`invalid_payload`	v0.79；由动作处理器给出（`pluginmgr.ActionCodeInvalidPayload`）
provider 名本期未登记	400	`unknown_provider`	v0.79；`plugin.saveProvider` / `plugin.testProvider` / `plugin.reauthProvider`
该家没配齐（缺 key 或缺接口地址）	400	`not_configured`	v0.79；`plugin.testProvider`
可变源存在但读不出来（损坏/权限）	500	`config_unreadable`	v0.79；不覆盖原文件
可变源写不进去（磁盘/权限）	500	`config_write_failed`	v0.79；本次改动没有生效
探针（`plugin.testProvider`）的上游结论	502	`unauthorized` / `rate_limited` / `quota_exceeded` / `network` / `upstream` / `bad_response` / `no_results` / `unknown`	v0.79；`no_results` 的文案明说「连通正常但没查到结果」
其它执行失败（内部错误）	502	`action_failed`	兜底档；详细原因只进后端日志

请求体：可选 JSON。空体 ⇒ payload=null（读来源动作通常无参）。原样交给执行器，宿主不解释插件的数据形状、不认识任何 URL（不给插件开 SSRF 面）。

响应 data：{pluginId,action,kind,result} —— kind ∈ {read,write}（read = table/log 的 source 与字段下拉的 optionsFrom；write = form.submit / table.rowActions；同名动作同时出现在读面与写面时一律按 write）；result = 动作处理器返回值原样透传。

审计：每一次结算都落一行，what = "plugin.action"，result ∈ {ok,error,denied,not_declared,unimplemented,unavailable,bad_request}。⚠️ 持久化审计记录仍只有 who/what/when/result 四字段 ⇒ 未含 pluginId / action（它们只在结构化日志行里，见 §7.2）；v0.79 新增：服务端日志行附加结构化失败码 code —— 只进日志，不进 DB 记录体、不含请求体。

✅ v0.79 的生产路径事实（切片 L1/PLG-2 执行面接线）：组合根在 wirePanelHub 里调用 wireBuiltinPluginActions，把内置 web-search 的四个动作 + 下拉候选来源登记到面板中枢 ⇒ 这些动作真的执行（真读写可变源、探针真发一次 HTTP），不再一律 501；装配期另把「声明了却没有实现」的动作与候选来源各记一条 WARN（action_not_implemented 因此是缺口信号而非常态）。⚠️ 残留（如实，见 §7.2）：✅ v0.80 起已热重载（保存后重建工具 + 原子替换注册表条目，下一轮生效、不需要重启；若新配置会让后端下次起不来则按字节回滚并回 409 config_unstartable）；探针只用 httptest 假上游验证过，未对真实上游做过一次连通验证（此项仍未做）。

(c) `web-search` 插件的动作面（v0.78 声明，v0.79 起真可用，切片 PLG-4 / L1；v0.80 起可配主 provider / 降级链 + 保存后热重载，切片 W3；供上面 (b) 的分发面使用）

插件 id web-search；可变源落点 $DATA_DIR/config/plugins/web-search.json（0600、temp+rename）—— ⚠️ 不进客户端契约（客户端一律走动作端点，不直连文件）。组合根「先读可变源、缺失回落 .env 播种」：文件一旦落盘，.env 的 WEB_SEARCH_* 只在文件缺失时起作用（⚠️ 运维视角的行为变更，见 §5）。🔴 不新增任何 env 键（.env 已冻结为引导面；本切片未改 .env / .env.example）。

plugin.listProviders 返回的表格行（rows[] 元素）：{ "provider": "bocha", "state": "ok", "enabled": true }（凭据与地址都不回）。state 取值（闭集）与判定顺序（根因在前）：unknown（名字本期没登记）→ disabled（显式停用）→ not_configured（名字已登记但没配齐：云家缺 key / searxng 缺地址）→ ok（其余）。⚠️「凭据失效」不是 state 取值（它只能由一次真实调用得知，属 plugin.testProvider 的结论）。

四个动作 + 一个候选来源（本插件声明的全部动作；全部已登记生产处理器）：

动作名	语义	面	请求体	成功响应 `result`
`plugin.listProviders`	列出各条 provider 配置	read（table `source`）	`{}`	`{"rows":[{"provider":"searxng","state":"ok\|not_configured\|disabled\|unknown","enabled":true}]}`（凭据/地址不回）
`plugin.providers`	下拉候选：本期全部已登记的 provider 名	read（字段 `optionsFrom:"plugin:providers"`）	`{}`	`{"options":["aliyun_iqs","baidu_qianfan","bocha","searxng","volcengine","zhipu"]}`（稳定排序，含尚未配置的家）
`plugin.saveProvider`	新增/修改一条（按 `provider` upsert）；同一次提交可带两个文件级字段 `primary` / `fallback`（主 provider 与降级链，缺位 = 不改动）	write（form `submit`）	`{"values":{"provider":"bocha","apiKey":"…","baseUrl":"https://…","enabled":true,"primary":"bocha","fallback":["searxng"]}}`	`{"saved":true,"provider":"bocha","created":true,"enabled":true,"primary":"bocha","fallback":["searxng"],"hotReload":{"applied":true,"registered":true}}`（`primary` / `fallback` 是落盘后的取值，没给也如实回显；`hotReload` 见下）
`plugin.testProvider`	测试连通（真发一次最小检索）	write（table `rowActions`）	`{"row":{"provider":"bocha"}}`（亦可给 `{"values":{…}}` 或顶层 `provider`）	`{"ok":true,"provider":"bocha","count":1,"latencyMs":123}`；没通 = 非 2xx（见错误表），不在 200 里回 `ok:false`
`plugin.reauthProvider`	重配凭据：把该条带回表单	write（table `rowActions`）	`{"row":{"provider":"bocha"}}`	`{"values":{"provider":"bocha","apiKey":"**cdef","baseUrl":"https://api.bocha.cn","enabled":true,"primary":"bocha","fallback":["searxng"]}}`（`apiKey` 只回掩码；前端对 secret 字段一律不回填输入框，空 = 不改动）。⚠️ v0.80 起 `values` 另带两个文件级字段 `primary`（字符串）/ `fallback`（字符串数组）—— 不带它们的话，面板「清空降级链」在客户端三态写回里会落成「缺位 = 不改动」（清不掉**）

plugin.saveProvider 的三态写回哨兵（写侧语义，前端须照此送值）：values.apiKey 缺位 ⇒ 保留盘上原值；空串 ⇒ 显式清空；非空 ⇒ 覆盖。values.baseUrl / values.enabled 缺位 ⇒ 保留；给出（含 "" / false）⇒ 采用（enabled 给非布尔值 ⇒ 400 invalid_payload，不静默保留）。values.provider 必填，且必须是本期已登记的接入位（searxng / zhipu / aliyun_iqs / bocha / volcengine / baidu_qianfan），否则 400 unknown_provider。

（v0.80 新增）两个文件级字段的三态写回（与条目字段同一套哨兵语义）：values.primary 缺位 ⇒ 保留盘上值；给字符串（含空串 / off / none）⇒ 采用 —— 空串与 off / none 都是「关掉这把工具」的哨兵（off / none 大小写与空白不敏感），WEB_SEARCH_PROVIDER 与面板共用同一套关闭语义（不另造第二套）。values.primary 指名一家已登记但未配齐的家 ⇒ 400 primary_not_configured（写盘之前就拒，因为那份配置会让后端下次起不来）。values.fallback 缺位 ⇒ 保留；给数组（或逗号 / 顿号 / 分号 / 换行分隔的字符串）⇒ 采用（去空白、去重、丢空项）；元素未登记 ⇒ 400 unknown_provider；给非数组 / 非字符串 ⇒ 400 invalid_payload（不静默当空数组 —— 那等于一次保存悄悄清空降级链）。降级链允许放本期已登记但尚未配齐的家（运行期会跳过它）。

落盘：$DATA_DIR/config/plugins/web-search.json（0600 + temp+rename），重启后仍然生效，且 v0.80 起保存后立即生效（热重载）：plugin.saveProvider 成功落盘后，组合根会按落盘后的配置重建 web-search 工具并替换能力注册表里的条目 ⇒ 下一轮对话即用新接线，不需要重启后端（design/09 §5.5 的端到端判据）。响应新增机器可读事实 hotReload:{applied,registered}：applied=true 表示这次保存真的触发了热重载（false = 宿主没有能力注册表可换，只落了盘）；registered 报告保存之后 web-search 在不在模型的工具面里（主 provider / 端点被显式关闭时为 false —— 这是设计语义，不是失败；⚠️ applied:false 时该键恒为 false、不携带信息）。

保存是一次事务：若这次改动会让 web-search 没有可用后端（design/27 §3 的启动期 fail-fast：主 provider 未登记 / 未配齐），端点返回 409 config_unstartable，且文件按字节回滚、运行中的工具保持原样（决不留「盘上新、内存旧」，也决不留「重启后起不来」的配置）。⚠️ 回滚本身也失败时如实回 500 config_write_failed 并明说「盘上可能已经变了」，不假装改动没发生。

⚠️ 触发面只有本动作：直接改写可变源文件（不经面板）不会触发热重载 ⇒ 仍需重启后端（或从面板点一次保存）。这是本动作的明确边界（不做文件监听）。

plugin.testProvider 失败时不回 200：走上面 (b) 的错误表（unknown_provider / not_configured ⇒ 400；unauthorized / rate_limited / quota_exceeded / network / upstream / bad_response / no_results / unknown ⇒ 502）。🔴 no_results 表示「连通正常但没查到结果」（空结果 ≠ 不通）⇒ 前端文案必须与真正的失败区分开，别把它显示成「该家不可用」。🔴 错误响应绝不含上游 URL 与凭据（只给稳定码 + 固定文案）。

⚠️ v0.79 行为变化（登记）：optionsFrom 声明的候选来源现在会进动作索引 ⇒ plugin.providers 从「404 action_not_declared」变为可调用的读动作。前端此前对该动作 404 的降级分支（文本框 + 「候选项未能加载」）因此不再触发。⚠️ 另有一条前端缺口（不属本契约面）：行内动作的成功分支只显示「已完成，正在刷新」，丢弃 result ⇒ 探针成功时的 count / latencyMs 在界面上仍不可见。

5. env 与模型配置（与契约相关）

.env vs 面板文件：面板「LLM 模型」页保存写 <DATA_DIR>/models.json（默认 ./data/models.json）；「渠道管理」页写 <DATA_DIR>/channels.json。只要文件存在且有效，运行时优先用它，.env 只作兜底/播种层。.env.example 与实现同步（键名逐字一致、值占位符）。

键	默认	与契约的关系
`PORT`	`8080`	网关唯一端口（含 REST/WS/admin）
`HOST`	`0.0.0.0`	监听地址
`ADMIN_PATH`	`admin`	管理面板前端路由前缀（`/`+值）。不是 REST 契约：`/api/v1/admin/*` 一律不藏。非法值回退 `/admin`；路径形如面板入口但前缀不符 → `404`
`CHAT_IMAGE_MAX_BYTES`	`5242880`（5 MiB）	`chat.image` 字符串长度上限的换算源（单位是字节，按 base64 4/3 膨胀换成字符：`ceil(n/3)4 + 64`，默认 6990572 字符；只作用于 base64 / `data:` 形态，URL 形态不走这道检查）。`≤0` = 用默认；只能收紧*，钳到 vision 硬顶（见 §4.5）
`CHAT_DOCUMENT_MAX_BYTES`	`20971520`（20 MiB）	`POST /documents` 单文件上限（`≤0` 用默认；与图片上限刻意解耦）
`AUTH_REFRESH_TTL`	`720h`	refresh token 有效期（access 固定 24h）
`AUTH_REFRESH_ROTATE_DISABLED`	`false`	`true` = 关闭 refresh 单次轮换
`ADMIN_USERNAME` / `ADMIN_PASSWORD`	占位	登录凭据（`POST /auth/login`）；必填
`JWT_SECRET`	占位	必填、≥32 字符（签名 JWT）
`DATA_DIR`	`./data`	数据目录；接受保留字 `platform`（大小写不敏感）→ 平台标准目录
`DB_SQLITE_PATH`	`./data/cyrene.db`	SQLite 路径
`DB_PG_URL`	空	pgvector 可选增强；配置了必须真实走语义/向量路径。是否生效另由 `GET /admin/system/storage` 的 `vector.{enabled,ready}` 如实报告
`ALLOWED_ORIGINS`	示例值	CORS + WS Origin 白名单（同 host 与回环别名额外放行）
`WS_MAX_CONNECTIONS`	`1000`	WS 连接上限（配置项，未确证是否在网关强制生效 —— 代码只见解析，未见到接线点）
`LLM_MULTIMODAL`	`false`	主模型自身能否收图的 `.env` 等价物（只作用于 `.env` 合成组；有有效 `models.json` 时以该组 `multimodal` 为准）。`true` = 图片直进主模型；`false`/留空 = 图片交 vision/OCR 工具。非法值启动即报错
`LLM_VISION_MODEL` / `LLM_OCR_MODEL`	空	只供视觉/OCR 工具调用；不代表主模型能收图
`LLM_CONTEXT_WINDOW`	空 → 131072	上下文窗口（预算推导依据）；负数启动报错
`CONTEXT_MAX_TOKENS`	空 → 按窗口推导	`>0` 显式覆盖；`0`/负 = 关闭压缩。⚠️ 若 `.env` 里还留着 `32768`，它就是显式覆盖、推导不生效
`CONTEXT_BUDGET_RATIO`	`2/3`	预算占窗口比例（接受 `2/3` 或 `0.6667`）
`DOCUMENT_MAX_INJECT_CHARS`	空 → 预算 1/8	单份附件注入上限
`GUARDRAIL_MAX_INPUT_CHARS` / `GUARDRAIL_KEYWORDS`	空	请求侧字符上限 / 关键词护栏
`VOICE_STT_TIMEOUT_SEC`	`20`	只约束 IM 渠道入站语音转写；Web 客户端 `voice_input` 不受它约束
`VOICE_TTS_VOICE_ID` / `VOICE_TTS_FORMAT` / `VOICE_TTS_MODEL`	空	`POST /audio/speech` 当前遵循的服务端配置（请求体 `voice`/`format` 为前向兼容接受但暂不生效）
`VOICE_TTS_INSTRUCTION`	空	系统音色 `longxiaochun_v3` 固定格式、不使用自由 instruction
`LLM_PROVIDER` / `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL` / `LLM_FALLBACK_MODEL` / `LLM_REASONING_KIND` 等	见模板	LLM provider 组的 `.env` 合成组兜底（有有效 `models.json` 时被其覆盖）
`DOCUMENT_GC_INTERVAL` / `DOCUMENT_RETENTION`	`1h` / `168h`	文档 GC（`0`/负 = 关闭 GC）
`LLM_USAGE_RETENTION`	`720h`	`llm_usage` 保留期（`0`/负 = 关闭清理）
`THINK_` / `QUIET_`	见模板	后台思考与主动推送策略。`QUIET_START_HOUR`（`23`）/ `QUIET_END_HOUR`（`7`）是本地钟点的安静时段窗口（跨午夜可用；两个相等的非 0 钟点 = 关闭；两端都为 0 = 未填 ⇒ 回落默认 `23/7`）：只服务「定时主动思考 → 主动搭话」，不静默回复（v0.68 起可经 B12 读到生效值）。`THINK_INTERVAL_SEC`（`900`）/ `THINK_QUIET_INTERVAL_SEC`（`3600`，v0.75 新增）：落在安静窗口内时，周期性心跳改用后者降频、窗外回落前者；`≤0` = 关闭降频（回落普通间隔，不是「半夜不思考」）。⚠️ 它只降周期性心跳：事件驱动（安全域/急性事件）照旧立刻触发、照旧穿透安静时段
`MEMORY_TIDY_ENABLED`	`true`	记忆整理总开关（`design/23 §4`）。关闭 ⇒ 完全不跑（日志写明）；整理只产建议、绝不自动改记忆。v0.75 起：关闭时试算端点（B14）也拒绝作答（`409 tidy_disabled`），不绕过这个选择
`MEMORY_TIDY_INTERVAL_SEC`	`86400`	整理周期（秒），是下限：实际在低峰窗口起点跑 ⇒ 真实间隔取「窗口每天一次」与本值的较长者
`MEMORY_TIDY_QUIET_START_HOUR` / `MEMORY_TIDY_QUIET_END_HOUR`	`23` / `7`	记忆整理的低峰窗口（本地钟点，默认与 backthink 同值）；两端相等且非 0 = 关闭窗口、改为纯周期；两端都为 0 = 未填，运行时回落到默认 `23/7`。⚠️ 窗口只管心跳调度：试算端点（B14）不受它约束（否则「现在就想看」正是它存在的理由）
`MEMORY_TIDY_RECALL_THRESHOLD`	`0.80`	候选召回门（余弦），不是合并判据（可否合并由包含关系 + 规则否决决定）。试算端点（B14）用同一个值
`MEMORY_TIDY_SCAN_LIMIT` / `MEMORY_TIDY_CANDIDATE_LIMIT`	`5000` / `200`	每分区每轮的扫描上限 / 候选上限（⚠️ 两者都是每分区的量，不是全库）。候选上限的默认值 v0.77 由 `20` 抬到 `200`（首轮真跑四个分区同时打满旧值 ⇒ 候选数由上限而不是规则决定）；命中它时响应 `truncated` 带 `<分区>(candidates)`。试算端点（B14）用同一对上限（不另造一套）
`MEMORY_TIDY_COMPARE_LIMIT`	`2000`	v0.77 新增：每分区每轮真正参与两两比对的条目上限（性能护栏，两两相似度是 O(n²·dim)）。此前写死为 `400` 且没有 env 键，实测把 459 条的分区截到 400 ⇒ `compared(705) < scanned(784)`（观测口径被上限决定）⇒ v0.77 抬到 `2000` 并开放为 env。命中它时响应 `truncated` 带 `<分区>(compare)` + 日志 WARN。`≤0` = 用默认
`MEMORY_REVIEW_ENABLED`	`true`	v0.77 登记：记忆「入库前审查」（`design/23 §15.1 D3`，切片 MT-B）总开关。新记忆落库后由独立的记忆管理会话（复用 `sess-memorytidy` 装配）在有界后台队列里判定 `skip`/`merge`/`modify`/`create`，结论以软合并回写（`status` + `merged_into`/`merged_from`/`merge_count`，可 revert、绝不改既有行 `content`）。`false` ⇒ 组合根不建、不接，写入路径逐字回到改动之前。默认开启是因为判定是纯规则、零模型调用（T1 灰区模型判定未实现）
`MEMORY_REVIEW_QUEUE_SIZE`	`256`	v0.77 登记：有界审查队列长度。⚠️ 队列满 ⇒ 该条不做审查（记忆本身早已落库，绝不因队列满而丢记忆），只记一条带来源的 WARN
`MEMORY_REVIEW_SCAN_LIMIT`	`200`	v0.77 登记：每条审查在同一分区内最多看多少条既有记忆（top-K 上限）
`MEMORY_REVIEW_TIMEOUT_SEC`	`20`	v0.77 登记：单条审查的墙钟上限（秒）。超时 ⇒ 不做任何改写（记忆照旧保留）+ WARN
（`MEMORY_REVIEW_*` 的共用口径）	—	上面四个键 `≤0` 一律视为「用默认」（由 memory 包 normalize 收敛，避免一个笔误让进程起不来）；召回门复用 `MEMORY_TIDY_RECALL_THRESHOLD`，不另立键。⚠️ 本版只登记已实现的部分：审查的读侧 / 回滚目前没有 HTTP 端点（见 §7.2）

上面 13 个键（记忆整理 8 + 后台思考心跳 3 + 安静时段 2）自 v0.68 起可经 GET /api/v1/admin/config-facts 读到「进程生效值 + 声明默认值」（3 个心跳键自 v0.75 起并入、MEMORY_TIDY_COMPARE_LIMIT 自 v0.77 起并入）；在此之前面板没有任何 env 读取面。⚠️ MEMORY_REVIEW_* 四个键不在事实面里（那是「入库前审查」的另一组配置）。 | SUBAGENT_TIMEOUT_SEC | 600 | 单个子代理整次运行时限 | | MCP_SERVERS_JSON | 空 | MCP server 注册表（JSON 数组）。⚠️ 扁平 MCP_NAME/MCP_COMMAND/… 为未接线残留键，配了不生效 | | CHANNEL_* / CHANNELS_JSON | 见模板 | 渠道接入（.env 为兜底，面板 channels.json 优先） | | CHANNEL_EVENT_RETENTION | 720h | v0.67 登记，已接线（E4 afe9afb；.env.example 同步于 f9c5b56）：channel_events 保留期 —— 比文档的 168h 长，因为事件表的核心用途是事后定案（一周太短）；≤0 = 关闭 GC | | CHANNEL_EVENT_GC_INTERVAL | 1h | v0.67 登记，已接线（E4 afe9afb）：渠道事件 GC 扫描间隔（与 DOCUMENT_GC_INTERVAL 同范式） | | CHANNEL_EVENT_COUNTER_FLUSH | 30s | v0.67 登记，已接线（E4 afe9afb）：计数内存聚合的 flush 间隔。计数是尽力而为的近似值（进程崩丢 ≤30s），查询面以 approx:true 如实标注（见 §2.4(a)） | | FLOW_GRAPH_RETENTION | 168h | v0.73 新增，已接线（切片 F2）：flow_graphs 轮次图保留期；≤0 = 关闭 GC（显式选择，「配了却不生效」不存在）。过期轮次从 turns[] 消失（见 §4.11(b)-5 / §7.4-20） | | FLOW_GRAPH_GC_INTERVAL | 1h | v0.73 新增，已接线（切片 F2）：链路图保留期清扫间隔（与 CHANNEL_EVENT_GC_INTERVAL / DOCUMENT_GC_INTERVAL 同范式；启动期扫一次 + 定时 + 失败不退出） | | WEB_SEARCH_*（WEB_SEARCH_PROVIDER / _FALLBACK / _MAX_RESULTS / _ENDPOINT / _TIMEOUT / 各家 _API_KEY / _BASE_URL） | 见模板 | v0.78 起语义收窄（切片 PLG-4，运维视角的行为变更）：web-search 的可变源改为 $DATA_DIR/config/plugins/web-search.json（0600、文件名 = 插件 id）。组合根先读可变源、文件缺失才回落 .env 播种（即 .env 只作引导面）：文件一旦落盘，改 .env 不再影响运行中的部署。🔴 不新增任何 env 键（.env 已冻结）；客户端一律走插件动作端点（§4.14(c)），不直连该文件 |

⚠️ v0.78 的「.env 只播种」口径（切片 PLG-4）：这与 §5 开头「只要文件存在且有效，运行时优先用它，.env 只作兜底/播种层」是同一条原则在搜索 provider 上的落地 —— 此前 web-search 是纯 .env 面，v0.78 起它也有了面板/文件配置面。无 env 键新增/删除；模板里既有 WEB_SEARCH_* 键保持现状。

与契约相关但「配了不生效」的键：

CHAT_MAX_PARALLEL_TURNS：未接线。编排器有构造期旋钮 Deps.MaxParallelTurns，但组合根未从任何 env 读它 ⇒ 生产恒为默认 2（.env 里配了不生效）。本文档不把它登记为可用旋钮。
ENABLE_BACKGROUND_THINKING / THINK_SILENCE_TIMEOUT_SEC：未接线（全仓无消费者；DevDocs/audit/07-backthink-automation-iot.md §1-17，是否接线待主人拍板）。ENABLE_BACKGROUND_THINKING 自 v0.75 起被列进 B12 的只读事实面 —— 那是为了让面板看得见这个死开关，不是「它已生效」的声称：facts[].value 只是解析值，配 false 也不会关掉后台思考。THINK_SILENCE_TIMEOUT_SEC 未列入事实面。
旧 MCP_* 扁平键：生产装配只读 MCP_SERVERS_JSON。
GETUI_*：SDK 未接入，预留占位、当前不生效。

6. 变更记录

只保留最近若干版（v0.60 起）；更早的全部历史见归档 Docs/archive/api-client.v0.65.md §5（v0.28 → v0.59）。每版一句话 + 三档标注。三档定义见 §0.4。

v0.80（当前契约版本）

三批增量 —— ① 链路图时间轴出口（切片 W1）｜② 搜索 provider 热重载 + 主 provider / 降级链（切片 W3）｜③ 入站语音 AMR 也可回放（切片 W4）（依据：主人 2026-10-06 要「web 后台的全链路流程图 = 所有消息按时间顺序串起来，而不是只有最新一个来回」；面板的意义就是「不改 .env 不重启」⇒ 配置面必须真热生效；微信 / QQ 的 AMR 入站语音不落副本 = 无法回放 / 多端同步。）

① 链路图时间轴出口（切片 W1，design/19 §7）：新增 1 条 writeAuth（owner|admin）只读、不审计端点 GET /api/v1/admin/flow/timeline（?sessionId=&limit=&before=）—— 把多轮链路图按时间正序返回，每轮 {turnId,round,startedAt,endedAt,lanes[]}（lanes[] 每项 {turnId,graph}，graph 与 graph_update 同形）。数据源 = 已落盘的 flow_graphs（迁移 0022/0023，保留期 FLOW_GRAPH_RETENTION 默认 168h）+ 内存里的最近一轮（在飞 / 刚落盘失败的那一轮）；limit 缺省 50 / 硬上限 200（超上限钳住、≤0 同缺省、非整数 400 bad_request）；before 游标取「开始时刻严格早于它」的轮次、响应回带 nextBefore（原样回带即可连续翻页，分页不重不漏）；响应另给 retentionHours / retentionEnabled / truncated 供面板如实标注「更早的轮次已过保留期」。未接线（内存 + 落盘都没接）⇒ 500 flow_unavailable，绝不回空 rounds（不假装「这个会话没有轮次」）。权限矩阵：writeAuth 段实有 18 / 总数实有 72（本版同时回补了自 v0.76 起的 −1 记账滞后，见 §2.0）。🔴 老端点 GET /admin/flow/graph（B13）逐字未改（admin_flow.go 零改动，routes.go 只加一行路由 + 注释）⇒ 老客户端零影响。§2.0 / §2.2 B18 / §4.11.1。
② 搜索 provider 热重载 + 主 provider / 降级链（切片 W3；裁决 2026-10-06 #1 / #2）：plugin.saveProvider 成功落盘后，组合根按落盘后的配置重建 web-search 工具并原子替换能力注册表里的条目（新增窄方法 registry.ReplaceTool —— 不是 Remove+Register：中间无空窗，且保留运行期策略）⇒ 下一轮对话即用新配置，不需要重启（design/09 §5.5）。保存是一次事务：快照文件 → 落盘 → 重建 → 换条目；③ 失败 ⇒ 文件按字节回滚（temp+rename）+ 409 config_unstartable（会 make-下次起不来的配置绝不留在盘上）；回滚也失败 ⇒ 如实 500 config_write_failed。响应新增机器可读事实 hotReload:{applied,registered}。声明面增补两个文件级字段 primary（select）/ fallback（multiSelect，候选来源 plugin:providers）—— 缺位 = 不改动；primary 给空串 / off / none = 关掉这把工具（与 WEB_SEARCH_PROVIDER 共用同一套关闭语义）；点名「已登记但未配齐」的家 ⇒ 400 primary_not_configured（写盘之前就拒）；fallback 元素未登记 ⇒ 400 unknown_provider、形状错 ⇒ 400 invalid_payload。plugin.reauthProvider 的 values 追加 primary / fallback（否则面板「清空降级链」在客户端三态写回里清不掉）。新增错误码：primary_not_configured(400) / config_unstartable(409)。🔴 本版改正三处已成假话的旧口径（此前写「面板保存后不热替换运行中的工具、需重启」、「面板无主 provider / 降级链字段」）：§4.14(b) / §4.14(c) / §7.2 / §7.4-26 / §7.4-27 已改。⚠️ 触发面只有本动作：直接改写可变源文件（不经面板）不触发热重载，仍需重启。§4.1 / §4.14(b)(c) / §7.2。
③ 入站语音 AMR 也可回放（切片 W4；裁决 #11）：组合根补齐 channelbridge.Options.VoiceTranscoder（cmd/cyrene/wire_channels.go）—— 注入的是 wireTranscode 装配的同一个引擎实例（与工具面 transcode 工具同源，不是第二条降级链）。⇒ 不可播格式的入站语音在落盘之前先转成 .wav 再落副本（mime: audio/wav；本期唯一必需的转码路 = QQ OneBot v11 的 amr → wav），客户端的 voice 从此带副本事实（name / mime / size / durationMs / url）；此前这些键缺席（走 category=transcode_not_wired 的诚实 WARN、不落副本）。形状零变化（DTO voice 的键集合与语义一字未改）；可播格式（ogg/wav/mp3/m4a/aac/flac/webm/oga/opus）仍原样落、一次转码都不发生。稳定 category 列表不变（10 类），但 transcode_not_wired 在生产装配下不再出现（它现在只剩「引擎未装配 / 构造失败」这一档）。🔴 本版改正 6 处已成假话的「组合根未注入 VoiceTranscoder ⇒ AMR 不落副本」：§4.5（缺口① + 现状行）/ §7.1（对照注）/ §7.2（语音面行 ②）/ §7.4-16（前向提示）/ §7.4-29（②）/ 旧版本横幅与 §6 旧版条目（v0.67 / v0.78 / v0.79）。§4.5 / §7.2 / §7.4-29。
行为变更：① 无（新端点；老端点逐字未改）；② 有（面板保存由「需重启生效」变为下一轮即生效；新增两个可配字段与两个错误码；plugin.saveProvider / plugin.reauthProvider 的响应形状加键）；③ 无（DTO voice 的键集合与语义未变，只是此前缺席的键现在会出现）。
破坏性：无（新端点 / 新可选键 / 新错误码；新增的响应键都是加性的，老客户端不读即行为不变）。
⚠️ 诚实边界：① 时间轴的前端渲染 / 真机面板联调不在后端出口的证据内；graph_json 破损行的 500 路径无测试；游标精度到毫秒（同一毫秒起跑的两个不同轮次在极端情况下可能被一并跳过 —— 理论边界，已写进 §4.11.1(b)-4）。② 热重载的真机面板端到端未跑、真机探针未打真实上游；启用态不跨重启持久化。③ 语音生产端到端未跑（红线：不重启后端）⇒ 证据是 channelbridge 行为单测（真 AMR 夹具 → 真引擎 → RIFF/WAVE）与 cmd/cyrene 的源码级接线用例；WS 实时帧 / 握手回放仍不带 voice；删除消息 / 会话时音频副本引用计数仍不释放。逐条见 §7.2 / §7.3 / §7.4。

v0.79（上一版）

四批增量 —— ① 插件面板动作真可用（切片 L1/PLG-2 的执行面接线）｜② 「入库前审查」（D3）管理面落地（切片 L45）｜③ 语音消息的用户可见面落地（切片 L45）｜④ 链路图权威回合标识覆盖到全部编排回合（切片 CODE-TC-2，唯一一处形状变化）（依据：面板动作此前一律 501 ⇒ 面板「点了没反应」；主人要「入库前审查可查、可回滚」；安卓/Web 要「语音能回放、消息能标出语音来源」；toolCalls[] 覆盖率此前只到真并行路 ⇒ 普通单路聊天与队首续跑回复回看不了工具。）

① 插件面板动作真可用（切片 L1/PLG-2）：插件管理器新增动作处理器登记面（Manager.RegisterActions → Panels.RegisterActions，取代单一全局执行器；声明仍是唯一闸门 —— 登记≠可执行）；组合根在 wirePanelHub 里登记内置 web-search 的四个动作 + 下拉候选来源（plugin.providers）⇒ POST /api/v1/admin/plugins/{id}/actions/{action} 不再一律 501 —— 真读写 $DATA_DIR/config/plugins/web-search.json（0600 + temp+rename，重启仍生效；v0.80 起保存后即热重载，见 §6 v0.80 ②）、探针真发一次最小 HTTP 检索。失败回结构化非 2xx（码/文案/状态由动作处理器给出，宿主只透传、状态越界回落 502）：新增 invalid_payload(400) / unknown_provider(400) / not_configured(400) / config_unreadable(500) / config_write_failed(500)，以及探针码 unauthorized / rate_limited / quota_exceeded / network / upstream / bad_response / no_results / unknown(502)；501 action_not_implemented 只在「已声明但宿主未登记处理器」时出现（不再是兜底档）；兜底执行失败仍是 502 action_failed。审计仍 what="plugin.action"，服务端日志新增附加字段 code（不进 DB 记录体、不含请求体）。§2.1 A14 / §4.1 / §4.14。
② 「入库前审查」（D3）的管理面（切片 L45）：新增 2 条 writeAuth（owner|admin）端点 —— GET /api/v1/admin/memories/reviews?limit=（留痕列表：limit 缺省 100、≤0 同缺省、>500 钳位、非整数 400；元素含 decision ∈ skip\|merge\|modify\|create、mergedIds 恒为非 null 数组、createdAt UTC RFC3339；🔴 不含记忆正文）与 POST /api/v1/admin/memories/{id}/revert（撤销一次软合并：被吸收行复原 active、从存活行 merged_from 摘除、merge_count 减 1；行永不物理删除）。未接线 ⇒ 500 memory_review_unavailable（绝不回空数组）；回滚落审计新动词 memory.review.revert（只记 item id）。权限矩阵：writeAuth 14 → 16、总数 68 → 70。§2.0 / §2.2 B16/B17 / §4.1。
③ 语音消息的用户可见面（切片 L45）：消息 DTO 的 voice（含服务端唯一派生的 url）在 4 个 REST 读取面 + message_edited 真实填充；新增 GET /api/v1/media/{name}（writeAuth；audio/* 内联 + nosniff + Accept-Ranges + Cache-Control: private, max-age=86400, immutable；无 ETag；Range ⇒ 206、条件请求 ⇒ 304、支持 HEAD、不可满足 Range ⇒ 416（非 JSON 信封）；名字非法 / 穿越 / 缺失统一 404 media_not_found）；副本落盘走新增 documents.Store.SaveAudio（内容寻址、0600、元数据进同一张 documents 表、并入同一套引用计数），chat_messages.voice 列读写两条路补齐（history.Store.UpdateMessageVoice / VoiceColumns）。⚠️ 残留缺口（如实）：message_persisted / channel_persisted 帧与握手 history 回放仍不带 voice（需给 history.Message 加字段，未做；且 message_persisted 在落库那一刻发出，天生拿不到落库后才回填的值）；组合根未注入 VoiceTranscoder ⇒ AMR 不落副本（可播格式照落）—— ✅ 该缺口已由 v0.80（切片 W4）修复（组合根已注入，见 §6 v0.80 ③ / §4.5 / §7.2）。§0.3 / §1.2 U19 / §3.4.4 / §4.1 / §4.4 / §4.5。
④ 🔴 链路图权威回合标识覆盖到全部编排回合（切片 CODE-TC-2）：新增 loop.FlowPublisher.StartRoundWithTurnID(ctx, owner, text)（权威回合标识取自 ctx 的 TurnIDFrom），run.go 的唯一生产建图点改走它 ⇒ 编排器驱动的每一路（普通单路回合、队首续跑路、真并行路）的图都带与 chat_messages.turn_id 同值的 turnId ⇒ 消息面 toolCalls[] 覆盖率从「只有真并行路」扩大到「全部编排回合」（普通单路聊天与队首续跑回复现在也能回看工具）。🔴 唯一形状变化：graph.id 的 #{权威回合标识} 后缀现在单路也追加（web-7 → web-7#turn-…）—— 该键仍不透明、仍可能含 #；客户端一律使用响应里的 graph.id / turns[].turnId，不要自己拼 {会话}-{序号}（自拼的老客户端查不到新行）。缺席语义一字未改：拿不到权威标识的写入路径（未接编排器的调用方、后台思考 sess-backthink、旧后端）turnId 仍缺席、toolCalls 仍整体缺席（绝不回空数组）；v0.79 之前的单路历史行不回填（lane_turn_id 为空且无可回填来源）。§4.4 / §4.11 / §7.2 / §7.4-23。
行为变更：① 有（面板动作由「全 501」变为真执行）+ 新增一批错误码；② 无（新端点；老客户端零影响）；③ 无（voice 是既有 DTO 的可选键、GET /media/{name} 是新端点）；④ 有（唯一一处形状变化）：graph.id 对单路也追加后缀 ⇒ 自拼 id 的读取方须改用响应值（其余形状与缺席语义一字未改）。
破坏性：无（新端点 / 新可选键 / 新错误码；④的形状变化只影响「自己拼 graph.id」的读取方，而本文档自 v0.73 起就写明该键不透明、应从响应取）。
⚠️ 诚实边界：① 面板动作热重载未做（保存后运行中的 web-search 工具不换接线，需重启）—— ✅ 已由 v0.80（切片 W3）修复（见 §6 v0.80 ②）、探针只用 httptest 假上游（未对真实上游连通，仍未做）；② 回滚端点与 design/23 §11 的 owner-only 口径有差异（待裁决）、留痕列表无分页游标、memory_ingest_reviews 无 TTL/GC；③ 语音生产端到端未跑、WS 实时帧/握手回放不带 voice、AMR 不落副本（✅ 已由 v0.80 修复）、删除消息/会话时音频副本引用计数不释放；④ 单路 toolCalls[] 的HTTP 出口端到端未由本切片确证（写侧已验，网关读侧由主会话补验）、turns[] 仍按路列条目、真机未验。逐条见 §7.2 / §7.4。

v0.78（上一版）

六面增量 —— ① 消息读取面 toolCalls[] 落地（覆盖率受限）｜② 插件管理面板接入点（GET /admin/panels + 插件动作分发端点 + panels_changed 帧）｜③ 搜索 provider 可变源（web-search 插件）｜④ 账号上下线落事件 + 渠道事件实时帧 channel_event｜⑤ 微信 iLink 凭据三态（authState/authDetail）｜⑥ 语音消息落库面（迁移 0020）（依据：安卓侧要「回看这条回复当时调了什么工具」；design/09 §5.2.1 的插件面板接入点 + §5.4 的安全与权限；design/27 的网络搜索提供商 + design/13 §2.1 的插件配置落点；design/26 §2.6/§4.5 的账号状态事件与实时面；errcode=-14 被读成「过期」的误判风险；design/24 §10 的语音落库面。）

① 消息读取面 toolCalls[] 落地（切片 CODE-TC）：GET /api/v1/sessions/{id}/messages 的消息对象新增可选 toolCalls（omitempty），每条 {name,status,durationMs?,argsSummary?,resultSummary?}（name/status 恒在，status ∈ {ok,error,unknown} 闭集三态；后三键图上给不出时缺席）。数据源 = 已落盘的轮次链路图 flow_graphs；🔴 缺席语义：图取不到 ⇒ 字段整体缺席，绝不回 []（客户端只做正向断言）。为打通读侧补齐：迁移 0023_flow_graphs_lane_turn_id 给 flow_graphs 加按路查询键 lane_turn_id（等值索引 idx_flow_graphs_lane_turn_id (session_id, lane_turn_id)）+ 回填；FlowGraphStore 增只读方法 GraphsByTurnID（一页一次 IN 批量查，禁 N+1）；history.go 的 handleListMessages 在编码前调 attachToolCalls。只在该出口填充（其余 DTO 出口逐字不变，有单测钉住）。⚠️ 覆盖率受限（如实，v0.78 时）：只有真并行路的图带权威 turnId ⇒ 普通单路回合的回复查不到图、toolCalls 缺席（补齐在 internal/runtime/loop/** 写侧，不在本版）。→ ✅ v0.79 已补齐（切片 CODE-TC-2：编排器驱动的每一路都带权威 turnId ⇒ 覆盖率扩大到全部编排回合；见 §6 v0.79 ④）。§4.4 / §7.2 / §7.4-23 / §2.2 B13。
② 插件管理面板接入点（切片 PLG-2，纯增量为主）：新增 1 条 viewer 读端点 GET /api/v1/admin/panels（按调用者角色过滤后的接入点快照 {role,groups[],pluginIds[]}，viewer 只拿只读区块；未接线 ⇒ 501 panels_unavailable）与 1 条动作分发端点 POST /api/v1/admin/plugins/{id}/actions/{action}（只接受该插件声明过的动作名，未声明 ⇒ 404 action_not_declared；写动作 owner/admin 收紧 ⇒ 未授权 403 forbidden；停用插件 ⇒ 409 plugin_disabled；每次结算都落审计 what="plugin.action"；插件只给动作名、不给 URL ⇒ 不开 SSRF 面）；WS 下行帧 panels_changed（{reason,pluginId}，reason ∈ {declare,install,uninstall,enable,disable}，只发 owner/admin，不带内容⇒ 客户端按角色重拉快照）。权限矩阵：viewerAuth 12 → 14、总数 66 → 68。🔴 v0.78 时生产路径硬事实：无任何生产动作执行器 ⇒ 当时所有已声明动作都回 501 action_not_implemented —— 已由 v0.79 接线（见 §6 v0.79 ① 与 §4.14）。§2.1 A13/A14 / §3.4.5 / §4.14(a)(b)。
③ 搜索 provider 可变源（切片 PLG-4）：插件 web-search 新增可变源 $DATA_DIR/config/plugins/web-search.json（0600、temp+rename、文件名 = 插件 id），组合根「先可变源、缺失回落 .env 播种」；面板数据面 = 四个动作 plugin.listProviders / plugin.saveProvider / plugin.testProvider / plugin.reauthProvider（表格行 {provider,state,enabled}，state ∈ {unknown,disabled,not_configured,ok}；testProvider 的 errorCode 闭集十项，⚠️ no_results 时「空结果 ≠ 不通」）。🔴 不新增任何 env 键（.env 已冻结）；.env 的 WEB_SEARCH_* 自此只在文件缺失时生效（运维视角的行为变更，如实登记）。§4.14(c) / §5。
④ 账号上下线落事件 + 渠道事件实时帧（切片 E7）：internal/runtime/events 增「账号状态迁移」这一路 —— 三态归一（未知也照常落行，不整类丢弃）→ 落一行 tier=t2 / category=lifecycle（复用迁移 0021）→ 经既有进程内 bus 的主题 channel.event 推成 WS 下行帧 channel_event（data.event 与 REST events[] 同一个对象；⚠️ 实时帧的 id 键可能整缺；只发 owner/admin，viewer 走 REST 只读档）。采样常驻（约 60s 一拍，不看面板也在跑）。⚠️ 当前只覆盖账号状态迁移这一路（其余渠道事件的实时装饰器未接线，见 §7.2）；采样通道目前唯一来源是 qq-obv11 的探活。§3.4.5。
⑤ 微信 iLink 凭据三态（切片 CODE-F3）：GET /api/v1/admin/channels/{platform}/login-status 新增可选 authState / authDetail（"active" 有效 / "rejected" 被拒且需重扫 / "unknown" 未知；闭集）。🔴 文案口径写死：errcode=-14 是「被拒」不是「过期」、未知原因不许写成「过期」/「未连接」（响应体全文由测试钉住）。键缺席 = 该账号没有这条状态面，≠ unknown。无新端点、无新路由（沿用 v0.39 起的端点）。⚠️ GET /admin/channels 的 accounts[] 每账号三态未实现（见 §7.2）。§2.4(c)。
⑥ 语音消息落库面（切片 CODE-VOICE）：迁移 0020_chat_message_voice 给 chat_messages 加 voice TEXT NOT NULL DEFAULT ''（JSON 单对象，形状 = DTO voice 减去 url；刻意不建索引）；internal/runtime/voice/** 新包（Source/Status 闭集、Ref 编解码、格式级可播表 + amr→wav 转码归一）；channelbridge 入站语音「归一 → 闸门之后落副本 → 落库后写 voice 列」全链打通（落盘内容寻址、复用文档存储与 GC、不进文档抽取/注入链路）。⚠️ 用户可见面（DTO voice + GET /api/v1/media/{name}）在 v0.78 时未实现，已由 v0.79 落地（切片 L45，见 §6 v0.79 ③）；残留缺口（WS 实时帧/握手回放不带 voice；AMR 那一项已由 v0.80 修复）见 §4.5 / §7.2。唯一已生效的客户端可见变化：IM 语音在「格式不在可转写白名单内」时正文诚实提示改口径（形状不变，客户端本就不该按正文文案分支）。§4.5 / §7.2。
行为变更：① 无（新可选键 + 新迁移列/索引）；② 无（新端点 / 新帧 / 新可选键；老客户端零影响）—— ⚠️ 但新增了 502 状态码（仅插件动作执行器失败路径）与一批插件动作错误码；③ 有（运维视角：.env 的 WEB_SEARCH_* 仅在可变源文件缺失时生效）；④ 无（新帧 + 新事件行；REST 形状未变）；⑤ 无（两个可选键；status/botId/botToken/err 与 v0.39 起逐字一致）；⑥ 有（轻微）：IM 语音「不可转写格式」的正文诚实提示改口径（形状不变）。
破坏性：无。
⚠️ 诚实边界：① toolCalls[] v0.78 时覆盖率只到真并行路（普通单路回合查不到图 ⇒ 缺席）—— 已由 v0.79 补齐（见 §6 v0.79 ④），且未做真机端到端（真并行路的 lane_turn_id 与 chat_messages.turn_id 逐字相等仍是代码级推论）；② 插件动作生产无执行器（全回 501）—— 已由 v0.79 接线（见 §6 v0.79 ①）、热装插件的声明来源缺、panels_changed 对 viewer 不可见、启用态不跨重启持久化、审计持久化记录未含 pluginId/action（都在 §7.2）；③ web-search 声明已就绪但**「面板加一家 provider」未做真机端到端**；④ channel_event 只覆盖账号状态迁移这一路（组合根装饰器未接线），且未做真机端到端；⑤ iLink rejected 分支只有单测/httptest 证据（真实 errcode=-14 至今 0 次观测）；⑥ 语音生产端到端未跑 —— 用户可见面已由 v0.79 落地（见 §6 v0.79 ③），但 WS 帧/握手回放仍不带 voice；AMR 不落副本已由 v0.80 修复（见 §6 v0.80 ③）。

v0.77（上一版）

链路图按路分桶（FV2）+ 记忆整理护栏抬高 / 诚实截断 / 试算异步落地（MT-A）+ 「入库前审查」env 键登记（MT-B）—— 三批都是纯增量（依据：主人 2026-10-05 报「并行两路时流程图互相顶掉」、以及「工具回看面要先让链路图带上按路的回合标识」；「护栏被打满 ⇒ 候选数由上限而不是规则决定」要治；design/23 §15.1 D3 的入库前审查上线）。

① graph_update 按路分桶（切片 FV2）：帧 data 新增可选 turnId（这张图所属路的权威回合标识，与 turn_begin / steer_ack / 流帧帧壳同值）与 round（会话轮次号）；图按 {会话}#{路} 归属桶建（单路的桶逐字等于会话 id ⇒ 单路行为逐字不变），因此真并行时每一路各发自己的帧、各落一行（flow_graphs 的唯一键 (session_id, turn_id) 不再把另一路整行顶掉）。GET /api/v1/admin/flow/graph 响应新增 lanes[]（最近一轮每一路的图 [{turnId,graph}]，按路开始时间升序，恒为非 null 数组；graph 仍是「最新一路」⇒ 老的读取方零改动），前端在 ≥2 路时按并列泳道呈现 —— §2.2 B13 / §3.4.5 / §4.11(a)(d) / §7.2 / §7.4-19。⚠️ 留白：turns[] 仍按路列条目（一轮两路显示两条），按轮分组需新迁移 0023（未做）；Agents 页 / 后台思考页仍只显示最新一路。
② 记忆整理护栏抬高 + 诚实截断 + 试算异步落地（切片 MT-A）：每分区候选上限 MEMORY_TIDY_CANDIDATE_LIMIT 默认 20 → 200；两两比对上限从写死的 400 改为 env 键 MEMORY_TIDY_COMPARE_LIMIT（默认 2000）；配置事实面 12 → 13 条；truncated 新增第 4 种标签 (budget)（被墙钟时间预算截断：整分区跳过，或两两比对中途收手 —— 成因是本次调用的时间上限而不是配置配额）；v0.76 ③ 的加性异步已落地（?async=1 + B15 轮询：并发复用既有 runId、与同步同一个 3 分钟墙钟、done 的 result 与同步 data 逐字节同形、running 时 result/error 双缺席、重启后旧 runId 如实 404）—— §4.10(a) / §4.12 / §4.12.1 / §5。
③ 「入库前审查」（D3）的 4 个旋钮（切片 MT-B）：MEMORY_REVIEW_ENABLED（true）/ MEMORY_REVIEW_QUEUE_SIZE（256）/ MEMORY_REVIEW_SCAN_LIMIT（200）/ MEMORY_REVIEW_TIMEOUT_SEC（20）—— 队列满 ⇒ 该条不审查但记忆不丢（只 WARN）、超时 ⇒ 零改写 + WARN、≤0 = 用默认、召回门复用 MEMORY_TIDY_RECALL_THRESHOLD。🔴 这 4 个键不进 .env 模板（主人 2026-10-06：.env 冻结为「只保证最小化功能可跑」的引导面、不再新增键）⇒ 有效行为 = 上面这组代码默认值，调优入口将由配置文件 / 面板提供（未接线）。⚠️ 该切片的面板读侧端点（GET /admin/memories/reviews）与回滚端点（POST /admin/memories/{id}/revert）目前没有 HTTP 入口，本版不登记为可用（见 §7.2）。
行为变更：无（① 两个新键可选、lanes[] 纯增量、单路行为逐字不变；② 只改默认值 / 新增一个截断标签，同步试算的响应形状未变；③ 只多了一组以代码默认值生效的旋钮，不进 .env、不改变任何既有行为）。
破坏性：无。
⚠️ 诚实边界：① 真并行未做真机端到端（线上产物是旧构建；真并行是在单测层用「真 Loop.Run × 2 + 网关照同的 ctx 通道」复现的）—— 见 §7.4-24；② 上面 ②「抬高后真机 compared == scanned」尚未被真机证实（只有单测与量级推算支持）；③ MT-B 的入库前审查未在生产库上跑过。

v0.76（上一版 · ⚠️ 逐条状态不同 —— ①已由 v0.78 实现（覆盖率受限）；②③已实现）

三面增量 —— ① 消息读取面 toolCalls[]（工具回看 · ✅ 已由 v0.78 落地）｜② 未读面 unreadCount（多端共享单游标 · 已实现）｜③ 记忆整理试算的加性异步（已由 v0.77 落地校正）（依据：安卓侧 Cyrene-For-Android/devdocs/02 明确「工具回看面比未读面更重要、且要带工具输出/摘要」，以及主人 2026-10-05 裁定的「抬高 + 治入库太宽」导致试算更慢）。

① 工具回看面（✅ 已在 v0.78 实现 —— 见 §6 v0.78 ① 与 §4.4；覆盖率受限）：GET /api/v1/sessions/{id}/messages 的消息对象加可选 toolCalls（omitempty）—— 每条含 name / status（ok｜error｜unknown）/ durationMs / argsSummary / resultSummary（后两者是图里已有的、已脱敏内容并按上限截断）。数据源 = 已落盘的轮次链路图（flow_graphs，迁移 0022；v0.78 补迁移 0023 的按路查询键，保留期 168h），不从正文反解、不从内存态猜。🔴 缺席语义：图取不到 ⇒ 字段整体缺席（绝不回空数组冒充「没调过工具」）。修的是安卓侧「回看这条回复时看不到它当时调了什么」。⚠️ 历史说明（v0.76 登记时未实现的原因，实测确认非推断）：chat_messages.turn_id 与 flow_graphs.turn_id 不同源（前者 = 编排器生成的随机路标识 turn-<16 hex>，后者 = trace.FlowGraph.ID，进程内递增的建图序号）⇒ 无法按消息 join 到它那一轮的图。⚠️ v0.78 校正（切片 CODE-TC）：v0.77 已给链路图加按路的回合标识，v0.78 又补上按路查图的读侧入口（迁移 0023 的 lane_turn_id + GraphsByTurnID）⇒ toolCalls[] 已实现；但🔴 v0.78 时只有真并行路能回看（普通单路回合的图当时不带权威 turnId）—— 已由 v0.79（切片 CODE-TC-2）补齐：编排器驱动的每一路都带权威标识 ⇒ 覆盖率扩大到全部编排回合（见 §6 v0.79 ④ / §4.4、§7.2、§7.4-23）。
② 未读面（纯增量 · ✅ 已实现）：message_persisted 的 data 加可选 unreadCount（omitempty，只在 >0 且确实算得出来时出现；缺席 = 老行为），GET /api/v1/sessions 的列表项同键（该键自 D4 起就已在，本版未改它）。口径 = 绝对未读 + 主人单一已读游标（chat_sessions.read_at，迁移 0010）⇒ 多端共享：Web 读了，移动端的红点也清 —— 这是与安卓侧已对齐的取舍（他们明确赞成），不是缺陷，不许改成「每端独立未读」而不经裁定。形状、缺席语义与三种缺席情形见 §4.13；帧表已同步（§3.4.4）。
③ 记忆整理试算加性异步：POST …/memories/tidy/dry-run?async=1 ⇒ 202 + runId（新增 B15 轮询端点）。不带 async 仍是同步 ⇒ 老客户端（含现有面板）逐字不变。结果活在进程内存（TTL 30 min、并发 1、重启即失效 ⇒ 如实 404）。⚠️ v0.77 落地校正：本项登记的时点标注「契约先行」，切片 MT-A 已实现，实现口径见 §4.12.1（并发=复用既有 runId、与同步同一个 3 分钟墙钟、result 与同步 data 逐字节同形、新错误码 tidy_run_not_found）。
行为变更：无（②只在既有帧里加可选键；③只在显式带参时改变路径；①未落地 ⇒ 无变更）。
破坏性：无。
⚠️ 迁移号预告：本版实现若需新迁移，编号从 0023 起（0020 预留给语音切片、0021/0022 已用）。

v0.75

记忆整理「试算」端点 —— 新增 POST /api/v1/admin/memories/tidy/dry-run：跑同一套整理规则、把候选直接回在响应里，且一行都不写（依据主人 2026-10-05 要求「现在就想看到在 736 条上它会建议合并哪些，而不等到 23:00」；对齐 design/23 §4「低峰定期后台任务 + 手动可触发的只读试算」）。

纯增量：新增 1 条 writeAuth（owner/admin）管理的只读语义 POST（§2.2 B14 / §4.12）。既有端点、既有帧、既有 env 键语义一字未改。
同版追加（无形状变更）：GET /api/v1/admin/config-facts 的事实表由 9 条扩到 12 条 —— 并入 ENABLE_BACKGROUND_THINKING / THINK_INTERVAL_SEC / THINK_QUIET_INTERVAL_SEC（安静窗口内心跳周期，默认 3600；≤0 = 关闭降频），支撑 design/12 §N「静默时段降频」（§2.2 B12 / §4.10(a)）。facts[] 形状与 quietHours 一字未改，只是多了 3 个元素 ⇒ 老客户端零影响。
零副作用是硬约束：端点走的是与低峰定时轮共用的规则路径（同一召回门 + 同一包含判定 + 同一规则否决 + 同一每分区候选上限），但候选不落库 —— 不写 memory_tidy_candidates、不写 memory_tidy_runs、绝不改 memory_items 的任何列。后端有「调用前后三张表逐行快照比对」的单测钉死（另有一条断言「试算候选 == 真跑一轮落库的候选」）。
失败绝不伪装成「没有建议」：未接线 → 500 tidy_unavailable、MEMORY_TIDY_ENABLED=false → 409 tidy_disabled、语义召回（embedding）不可用 → 500 tidy_recall_unavailable、超时 → 503 tidy_timeout、其余内部失败 → 500 tidy_dry_run_failed。不回 candidates:[] 来表示失败 —— 空数组唯一含义是「算过了，这一轮没有建议」。
试算专属的严格：语义召回不可用时，试算报错而不静默降级到词项余弦（否则面板会把「语义路径没跑起来」读成「没有候选」）。低峰定时轮与手动轮的降级口径不变。
不审计、不调度：它是只读计算（不写审计链），不受安静时段约束（窗口只是心跳调度口径），也不改变心跳节奏与周期。
行为变更：无。
破坏性：无（老客户端不发这个请求就零影响）。
⚠️ 本版不做：apply / reject / revert 候选的写端点仍是 design/23 §11 的未实现项（见 §7），面板当前只做「看建议」。

v0.74（上一版）

IM 路由的主动消息也补浏览器通知 —— message_persisted 新增可选结构化判据 proactive:true（依据主人 2026-10-05 裁定 C 的必然推论「她说话该不该提醒我，与走哪条路由无关」；对齐 design/12 §3 的主动推送与 design/16 §4.4 的镜像口径）。

纯增量： ① message_persisted 的 data 新增可选键 proactive:true：IM 路由（im_bridge）的主动推送在落库之后追加一条带该键的同类帧 —— 帧类型、角色门、message DTO 形状一字未改，只多一个布尔键（§3.4.4）。 ② 客户端据此走与 proactive_message 同一套提醒逻辑（非前台补一发通知；去重键同为 message.id）。老客户端不读该键即行为与 v0.73 完全相同。
修的是什么（根因）：auto 提示在主人有已连接 IM 渠道时优先走 IM，而 IM 路由此前只发普通 message_persisted —— 浏览器通知挂在 proactive_message 上 ⇒ 实际最可能发生的路径恰恰不弹。这就是 P0（v0.72）如实报回的边界。
判据是结构化的：主会话落库行的 platform/adapter_id 区分不出主动推送与普通回复（主动推送写的是解析后的真实平台，例如 weixin-ilink，与普通回复行同一形状）⇒ 判据放在落库那一刻的通知通道上（gateway.BroadcastProactivePersisted），随帧顶到达客户端。绝不读正文关键词、绝不用提示词/模型判断（项目红线：身份与判定靠元数据）。
不误伤：普通消息（Web 回合 / IM 回复 / IM 镜像）走的仍是原入口 BroadcastPersisted，那条路径永不放该键 ⇒ 客户端不可能把普通消息误判成主动消息。客户端只应做 data.proactive === true 的严格相等判断。
行为变更：无（普通镜像帧照旧发一条；主会话里仍恰好一条行，P0 的「不双份」红线未动）。
破坏性：无。
⚠️ 诚实边界：① 判据不落库（不改 schema）⇒ 刷新后从历史读回的行不带它（预期：通知只对实时到达有意义）。② 落库失败时不发判据帧：没有权威 id 的 message_persisted 会被客户端整帧丢弃，发它等于假装提醒过 —— 那种情况下只记 WARN。③ 「她主动说的话」在三类帧上到达的完整清单见 §3.4.4 与 §3.4.5。

v0.73（上一版）

链路图本地落盘 + 多轮历史回放 —— 图从「只活在进程内存」变成每轮一行落进本地库，GET /api/v1/admin/flow/graph 增量支持按 turnId 取历史轮（依据主人 2026-10-05 追加要求「链路流程应该有本地数据，不然每次重载之后页面就没数据了」；对齐 design/19 §4 的 P3「多轮历史回放」—— v0.71 只做了其中最小一步）。

纯增量： ① 落盘：每轮收尾（EndRound）把该轮的图写进新表 flow_graphs（迁移 0022），每轮一行（不是每 span 一行）；只落发布会话白名单内的会话（复用 flowSessionAllowed，与实时发布同一判据）。新 env 键 FLOW_GRAPH_RETENTION（默认 168h）/ FLOW_GRAPH_GC_INTERVAL（默认 1h），GC 口径照 events/documents（启动期扫一次 + 定时 + 失败不退出；≤0 = 关闭；不许无限增长）。 ② GET /api/v1/admin/flow/graph 新增 ?turnId=：省略 = 最近一轮（先查内存 LastGraph，miss 才回退落盘 ⇒ 最新一轮永远最新）；给了 = 精确取该落盘轮。 ③ 响应新增三键 turnId / source / turns[]：source ∈ live/persisted/none；turns[]（{turnId,createdAt}，最新在前）供面板选历史轮 —— graph/sessionId 两键的既有语义一字未改。 —— §2.2 B13 / §4.11。 ④ 前端：图桶 flowGraphs 纳入 store 持久化（刷新即刻有图）+ 历史轮次选择 UI + 诚实文案（白名单外会话永远没有图；未跑新轮次前的旧轮次靠落盘）。
行为变更：无（graph_update 帧形状、角色门、发布会话范围全部未改；graph/sessionId 语义未改）。
破坏性：无（新查询参数可选、新响应键可选；老客户端不读即行为与 v0.71 相同）。
⚠️ 诚实边界：落盘只覆盖保留期内的轮次（默认 7 天）—— turns[] 不是全历史；graph_update 两路互顶的既有裁决本版未动（§7.4-19）。当前仍没有图的轮次见 §7.4-20。

v0.72（上一版）

主动推送可见性 —— 主动消息成为主会话里的一条真实消息，并给帧补上权威行 id（依据主人 2026-10-05 报「后台思考的主动推送一个都没推出来」；对齐 design/12 §3 的主动推送与 design/16 §4.4 的镜像口径）。

行为变更： ① proactive_message 那条消息现在会落进主会话历史（web、role: assistant、mode: "chat"、turn_id 留空）。此前后台思考走活跃客户端路由时只广播 WS 帧、一行都不写 ⇒ 刷新/重载后既不显示气泡、也补不出历史；那句 delivered to 2 active client(s) 只表示「帧被 2 个连接收下」，不代表进了会话。顺序改为先落库、再发帧。 ② 帧新增两个可选键 id / createdAt（同现/同省）：这条消息在主会话历史里的权威行 id 与落库时间戳。客户端据此把实时气泡对齐到历史行（按 id 去重、刷新后由历史行接续）。落库失败时两键缺席 —— 客户端不应把「没有 id」当成一条可持久化的消息。 ③ 没有在线 owner/admin 连接时也落库：推送器如实回 pushed=false（没有活跃客户端），但那句话仍作为真实记录留在主会话里。 ④ 后台思考记录里的 PushResult.Detail 措辞：活跃客户端路由改为 delivered to N active client(s), persisted to main session（未落库时写明 not persisted…，无在线客户端但已落库时写明 no active client, recorded in main session）—— 面板因此不会把「帧发出去了、刷新就没了」误读成「已推送」。
纯增量：帧的形状只在新增可选键；落库行的形状就是既有 historyMessage（§4.4），因此既有读取面（GET /sessions/web/messages、握手 history 回放、message_persisted）逐字不变。
破坏性：无。老客户端按未知键忽略 id/createdAt 即可；但它会把主动消息多看到一次（历史行）—— 这是本版的目的，不是缺陷。
不双份（已验证）：两条路由在一次推送里互斥（web 提示只走活跃客户端；其余先 IM 桥、IM 投递失败才降级活跃客户端），而 IM 路由本就把消息镜像回主会话 ⇒ 同一条主动消息在主会话里恰好一条。契约细节见 §3.4.5 后的「proactive_message 的落库口径」。
⚠️ 诚实边界：被频率门（PushGate）拒绝的推送不落库（限流就是「这一条不发」，绝不留下一条它没发过的记录）。

v0.71（上一版）

链路图补版 —— 新增只读端点 GET /api/v1/admin/flow/graph，让「轮次结束后才打开的页面」也能看到最近一轮的链路图（依据主人 2026-10-05 第二次报「/#/admin/flow 停在暂无流程图数据 + 后台思考行提示该会话还没有 graph_update 快照」；对齐 design/19 §4 的 P3「多轮历史回放」里的最小一步）。

纯增量： ① 新 admin 只读端点 GET /api/v1/admin/flow/graph?sessionId=<id>（owner/admin，?sessionId= 省略 = 主会话 web）：返回 {data:{sessionId,graph}}，graph 与 graph_update 帧的 data 逐字同形；该会话还没有图 ⇒ 如实 null（绝不画假图）；图源未接线 ⇒ 500 flow_unavailable（不假装「这一轮没有图」）—— §2.2 B13 / §4.11。权限矩阵随之更新：writeAuth 12 → 13，总数 64 → 65。 ② §3.4.5 graph_update 行补一句「纯实时、不重放」并指向本端点。 ③ §7.4 新增两条诚实边界：「最近一轮」≠「你要的那一轮」（后台思考行上的图可能不是该行那轮；面板必须在图上说明）、图源是进程内内存（后端重启后如实回 null）。
修的是什么（根因）：graph_update 只走实时帧，前端图桶 flowGraphs 不持久化（store/persistOptions.ts 的 partialize 不含它），且此前没有任何 REST/WS 补拉通路 ⇒ 页面在轮次结束后打开、或刷新过页面，就永远空着。本端点补上唯一缺的那一环。
行为变更：无（既有端点/帧一字未动）。
破坏性：无（新端点；graph_update 帧形状、frameReachesAll 角色门、发布会话范围（裁决 01.4.5）全部未改）。
⚠️ 诚实边界：只回每会话最近一轮；多轮历史回放（按 turn/时间点取任意一轮）仍未实现（design/19 §4 P3）—— 见 §7.4-18。graph_update 两路互顶的既有裁决本版未动（§7.4-19）。

v0.70（上一版）

后台思考行的紧急度精确化 —— urgency 默认即精确档位，另加 urgencyLowerBound 标记下限（依据主人 2026-10-05 裁定「要精确」；P4 只能给下限，本版把精确值送到两面：管理 REST 与实时帧）。

纯增量： ① GET /api/v1/admin/backthink 条目的 urgency 默认语义改为该轮实际生效的精确档位（backthink 在档位判定点随记录落库，含她自报紧急度上抬后的结果）—— §2.2 B8 / §4.10(b)(c)。 ② 新增可选 urgencyLowerBound:true（只在为 true 时出现）：标记该 urgency 是旧行的下限推导值而不是精确档位（旧行 = urgency 列出现之前的行，以及从未走到档位判定点的行）。客户端据此区分「精确档位」/「≥ 下限」/「未知」三态。 ③ 实时 backthink 帧带上记录里的 urgency（精确值）⇒ 本次会话新到的行不必等重开页面就有档位。⚠️ 实时帧仍不带 urgencyLowerBound / quietHoursBypassed（两者由网关按安静时段窗口推导，不在记录里）—— 更正 §4.10(b) 原「实时帧不带这两个键」的表述。 ④ §7.4-17 补「客户端不得把『下限』显示成精确值、不得把缺席显示成『例常』」。面板三态文案与悬停说明见 frontend/web/src/admin/modules/backthinkUrgency.ts。
行为变更：urgency 的读法变了（v0.68/0.69 一律读作下限；v0.70 默认读作精确值，唯有带 urgencyLowerBound:true 才是下限）。取值域（routine/warning/critical）与 quietHoursBypassed 语义一字未改。
破坏性：无（新键可选；把 urgency 当「下限」显示的老客户端最坏是显示得比事实保守，不会谎报精确值）。
⚠️ 诚实边界：旧行（本列之前落下的）没有精确档位可显示 —— 它们仍走下限额推导并带 urgencyLowerBound:true；未知仍是未知（不编值）。见 §4.10(c) / §7.4-17。

v0.69（上一版）

directMsgPerMin 的 gateway 写入路径修复（切片 P1-T；缺口 = 面板保存一次渠道配置就把主人手配的「关闭流控（-1）」静默重置回 0 = 保护性默认 6 条/分）。

纯增量 / 缺口修复：PUT /api/v1/admin/channels/{platform}/config 现在接收并原样落盘账号顶层 directMsgPerMin，GET /api/v1/admin/channels 的账号元素也如实回显它 —— §2.2 A5 行 / §2.3 C28 注 / §7.2。
行为变更：无（对不带该键的老客户端，行为与 v0.68 相同）。
破坏性：无。
⚠️ 诚实边界：账号级限流字段仍是值语义（请求体省略 ⇒ 0 = 未设置），要保住已设的值必须回送 —— 见 §7.3。

v0.68（上一版）

管理面「配置事实」只读端点 + 后台思考行的紧急度/穿透字段（依据主人指正「你多久没把新功能同步管理面板更新了？」与裁决 14；本版全部已实现、非契约先行）。

纯增量： ① 新 admin 端点 GET /api/v1/admin/config-facts（owner/admin，只读、不审计）：返回 9 条配置事实（记忆整理 7 键 + QUIET_START_HOUR/QUIET_END_HOUR）的进程生效值（value）+ 声明默认值（default）+ isDefault，外加 quietHours{startHour,endHour,disabled,label} 的窗口解释 —— §2.2 B12 / §4.10(a)。不含任何凭据值（连凭据类键的「是否已配置」都不回）。权限矩阵随之更新：writeAuth 11 → 12、总数 63 → 64。 ② GET /api/v1/admin/backthink 的条目增 2 个可选字段：urgency（routine/warning/critical）与 quietHoursBypassed（true 才出现）—— §2.2 B8 / §4.10(b)。语义：urgency 是存档可证的下限（warning = 至少 high），quietHoursBypassed = 「这轮在安静时段里仍被放行发出去」。 ③ §5 登记 9 个键的默认值与语义（此前只以 THINK_*/QUIET_* 概括）。
行为变更：无（既有两个端点的既有键一字未改；新字段都是可选键，老客户端不读即零影响）。
破坏性：无。
⚠️ 诚实边界：后台思考的精确档位（high 还是 critical）在存档里已丢失（backthink.Record 不带重要度，推送成功的行其 detail 被投递说明覆盖）⇒ 本版只下发可证下限，窗口外的轮次干脆不下发（面板显示「未知」），绝不猜。见 §4.10(c) / §7.4-17。

v0.67（上一版）

三批已在设计文档定稿的新增面一次性登记：语音消息（播放端点 + 消息 DTO voice + 音频副本口径）、非消息事件查询面、账号在线状态（依据 design/24 §10.11、design/26 §4.5 / §2.6）。登记时三批都还没有实现；其中账号在线状态（52dac45）与非消息事件查询面（本切片 E6）已落地（见下）。

⚠️ 本版是「契约先行」登记：登记的三批里，账号在线状态（见 §2.4(b)）与非消息事件查询面（见 §2.4(a)）已落地；语音消息当时未实现，那一批的形状取自设计文档而非代码核对 —— v0.79 已把用户可见面落地（切片 L45，见 §6 v0.79 ③ / §4.5 / §7.2），残留缺口（WS 实时帧/握手回放不带 voice；AMR 的那一项已由 v0.80 修复）仍按「未确证/未实现」读。

纯增量： ① 新端点 GET /api/v1/media/{name}（用户侧，owner/admin 必须 Bearer）：200 字节流 / 206 Partial Content / 304 Not Modified；Content-Type: audio/*；Content-Disposition: inline; filename="<name>"；nosniff；Accept-Ranges: bytes；Cache-Control: private, max-age=86400, immutable；支持 Range 与 HEAD；404 media_not_found；401/403 由中间件给出。⚠️ 416 是标准库直写的非 JSON 响应（见 §0.3、§4.1、§4.5）。 ② 消息 DTO 增可选 voice 对象（omitempty；非语音消息键缺席）：{source,status,name?,mime?,size?,durationMs?,url?}；source ∈ asr/platform，status ∈ transcribed/empty/failed，name/mime/size/url 四者同生共死（有副本时才在）；url 是服务端相对路径 /api/v1/media/<name>。🎤 判据 = voice 键存在。⚠️ v0.79 校正（实测覆盖）：真正会带 voice 的读取面只有 GET /sessions/{id}/messages、GET /admin/channels[/{platform}]/messages、PATCH /messages/{id} 响应与 message_edited；message_persisted / channel_persisted 与握手 history 回放不带（见 §3.2、§3.4.4、§4.4 覆盖率的「尚未填充」）。 ③ 新错误码 media_not_found（404） → 加进 §4.1 的 404 行（与 document_not_found 并列；刻意不复用它，否则客户端分不清缺的是文档还是语音）。 ④ 新错误形态 416（非信封，标准库直写）→ §0.3 / §4.1 / §4.5。 ⑤ 新 admin 端点 GET /api/v1/admin/channels/events（非消息事件列表，倒序；?platform=&tier=&category=&channelId=&since=&until=&limit=&offset=；响应 {data:{events:[…],total}}；since/until 按 UTC ISO-8601 定宽字符串字典序比较、跨度上限 90 天；不含正文、不含媒体 URL、不含任何凭据 / flag）—— §2.4(a)。已落地（owner|admin 档；元素键名 camelCase，逐字见 §2.4(a)；未给窗口 ⇒ 不注入窗口）。 ⑥ 新 admin 端点 GET /api/v1/admin/channels/events/counters（逐类计数汇总 {data:{approx:true,counters:[{platform,accountId,tier,category,platformType,count,firstSeenAt,lastSeenAt}]}}）—— §2.4(a)；未接线存储 ⇒ 500 channel_events_unavailable（新增错误码，绝不回全 0 假汇总）。已落地（approx 与 counters 同级；platform 未知 ⇒ 400 bad_request）。 ⑦ GET /api/v1/admin/channels 的 accounts[] 增可选 accountOnline（账号在平台侧是否在线，与 connected（适配器/WS 是否连着）是两件事；键缺席 = 状态未知 ≠ 离线）—— §2.4(b)。已落地（管理面按可选接口断言读 AccountStatus()；known=false 或适配器无该状态面 ⇒ 键缺席）。 ⑧ 新 env 键 3 个：CHANNEL_EVENT_RETENTION（720h）/ CHANNEL_EVENT_GC_INTERVAL（1h）/ CHANNEL_EVENT_COUNTER_FLUSH（30s）—— 已在 §5 登记（本切片不新增语音相关 env 键；语音上限/保留期复用既有常量与 DOCUMENT_*）。 ⑨ WS 协议零变化：media 是 REST 端点；无新帧、无新上行字段。
行为变更： ⑩ QQ 语音消息的 content 不再含 [语音] 占位标记（旧行为 → 移除）：今天从正文里认 [语音] 的客户端必须改为看结构化字段（voice 键存在 = 语音消息）。⚠️ 这是本版唯一会打到老客户端的地方（见 §7.2）。 ⑪ GET /api/v1/admin/system/storage 的 documents 段（件数 / 字节）自此包含语音副本（音频副本与文档同表：SELECT COUNT(*), SUM(size) FROM documents）—— 形状不变，变的只是口径（面板文案宜标注「含语音副本」）。
破坏性：无（新端点、新可选字段、新错误码都是增量；documents / /upload / /files / /audio/* 的既有端点一字未改；WS 零变化）。

v0.66（上一版）

并行帧层上线 + 消息回合标识落库 + 渠道按账号操作；并修正 v0.65 的两处过期/写错的陈述（依据 design/15 §2.5、design/08 §4；提交 c0dc435 / d64b26d + d804c4e / 42279b7 / a918819 / 679cee0）。

纯增量： ① 新下行帧 turn_begin（owner+admin，不进 frameReachesAll 白名单）：帧壳 {type,sessionId,turnId}、data {kind,messageIds,leg,activeTurns}，每起一路（含续跑路）恰好一帧（c0dc435）。 ② steer_ack 增帧壳 turnId（data {messageId,atStep} 不变）（c0dc435）。 ③ 上行 interrupt.turnId：仅 scope:"current" 生效（其它 scope 按契约忽略）；目标路不存在 ⇒ 定向 {type:"error",data:{code:"bad_request"}}（复用既有 code），不广播、不动会话（c0dc435）。 ④ 消息 DTO 增可选 turnId（omitempty，空则键省略；同一路的 user 与 assistant 同值）—— 一次覆盖 GET /sessions/{id}/messages、PATCH /messages/{id} 响应、GET /admin/channels[/{platform}]/messages、WS message_persisted / channel_persisted / message_edited、握手 history 回放（d64b26d + d804c4e；迁移 0018）。 ⑤ POST /admin/channels/open|close 请求体增可选 accountId；未知 id ⇒ 404 account_not_found，已配置未注册 ⇒ 409 account_not_registered；响应增 resolved / accountId（42279b7）。 ⑥ DELETE /admin/channels/{platform}/config 增显式 ?empty=1（与 ?id= 互斥 ⇒ 400；无可删 ⇒ 404）；响应增 empty / removed（42279b7）。 ⑦ GET /admin/channels 的 accounts[] 增可选 connected（键缺席 = 状态未知 ≠ 未连接）（42279b7）。 ⑧ 新 env 键 VOICE_STT_TIMEOUT_SEC（默认 20；只约束 IM 入站语音，Web voice_input 不受其约束）（a918819）—— 已在 §5 登记。
行为变更： ⑨ IM 用户消息现在带 documents（同一 DTO、无新字段；0 附件仍省略该键）（679cee0）—— v0.65 曾预告，本次随该提交真正上线。 ⑩ turn_begin 的帧序：session_busy/pending_drain → message_persisted(user) → turn_begin（messageIds 必须是已落库的权威 id，故只能在落库之后发）（c0dc435）。 ⑪ 不带 accountId 的 open/close 目标现在是确定性的：按 channels.json 有效配置顺序第一条（此前走注册表 map 顺序，多账号平台上每次可能落到不同账号）（42279b7）。 ⑫ DELETE .../config?empty=1 由「被当成 id 缺失 ⇒ 400」变为真的删除无 id 条目（显式化；?id= / ?empty= 语义边界见 §2.3 注）（42279b7）。
破坏性：无（新帧对新客户端可见、老客户端忽略即可；所有新增字段皆可选；无既有字段被移除或改义）。
⚠️ 本版更正 v0.65 的两处陈述（文档写错，不是代码变更）：
- thinking 口径：本文档曾写「历史思维链只有 GET /sessions/{id}/messages（owner/admin）返回」—— 与实现不符。history.Message.Thinking 全仓没有任何写入者（loop.Result 无该字段、finalizeAnthropicStream 直接丢弃思考文本）⇒ 该键在所有读取面恒缺席；思维链的唯一出口是实时 thinking.* 帧（owner/admin）。已在 §3.4.4、§4.4 按实测改写。
- v0.65 §7 的「未实现」清单：turn_begin / steer_ack.turnId / interrupt.turnId / chat_messages.turn_id / 写类工具文件级互斥 —— 现已全部实现并上线（c0dc435、d64b26d+d804c4e、354b08a），§7 已相应改写。
⚠️ v0.66 补充说明（描述性更正，不动形状/阈值，不升版本号）：chat.image 的体积判据是「字符串长度」而不是「解码后字节」 —— 旧措辞「内联上限 = 解码后 5 MiB」只对 base64 / data: 形态成立，且它本身是换算口径（len(image) <= 6990572 字符，见 §4.5）。URL 形态不触发 image_too_large（URL 串约 60 字符，必然通过）：其天花板在视觉取回层的 50 MiB（io.LimitReader，超出静默截断、不报错）；POST /api/v1/upload 自身是 5 MiB 字节硬限（413 payload_too_large）。四处已按实现写清（§4.5 图片、§4.6 响应面、§5 环境变量表、U8 行 + 错误码表）。无端点 / 帧 / 字段形状变更，无默认值变更。

v0.65

忙时并行回合基础管线（I1′ 有条件放宽）+ 六条登记（依据 design/15 §2.5，主人 2026-10-05 裁决 B）。

纯增量：① 上行 chat.parallel?:bool（WS chat 帧 + REST 三入口同形）；② session_busy/session_idle/pending_drain/session_interrupted 的 data 增 activeTurns:int；③ session_interrupted.data 增 cancelledTurns:int；④ pending_ack.data 增可选 reason:"parallel_limit"；⑤ REST 两条新应答形状（同步 202 {parallel:true,turnId} / stream:true 的 200 {stream:true,parallel:true,turnId}）；⑥ 新 env 键 VOICE_STT_TIMEOUT_SEC（默认 20s）。
行为变更：⑦ IM 入站附件引用真的写进落库的用户消息（documents 列，同一 DTO、无新字段）；⑧ IM 各渠道语音进上下文（云端 ASR 转写为文本，失败落一行中文诚实提示）；⑨ session_idle 时点收紧为「所有在途路收尾且 pending 空」（仅并行时生效）。
破坏性：无（省略 parallel / 不读新键的客户端行为逐字不变）。
⚠️ 回填：上条 ⑦（IM 附件引用落库）与 ⑥（VOICE_STT_TIMEOUT_SEC）在 v0.65 冻结时尚未提交，已分别在 679cee0 / a918819 落地，见 v0.66。

v0.64

LLM 用量落库 + 只读汇总端点 + 面板用量小卡。

纯增量：新端点 GET /api/v1/admin/llm/usage（owner/admin 读）、新迁移 0017_llm_usage、新 env 键 LLM_USAGE_RETENTION（默认 720h，≤0 = 关闭清理）。
行为变更 / 破坏性：无（model 层新增的是可选 sink，不注入时行为逐字不变）。
⚠️ v0.64 曾写「llm_usage.session_id 恒为 NULL」，已由 v0.65 更正：loop 已把会话 id 播种进运行 ctx 并落库（空串仍映射 NULL）；但 GET /admin/llm/usage 仍不按 session_id 过滤/分组，响应形状不变。

v0.63

客户端登记两条落地：documents[] 增可选 reason + GET /sessions/{id}/messages 对不存在会话回 404 session_not_found。

纯增量：① documents[] 元素增可选 reason（omitempty，只在 status:"unreadable" 时下发）。
行为变更：② GET /api/v1/sessions/{id}/messages 对不存在/已删除会话由 200 {"data":[]} 改为 404 session_not_found（客户端须处理 404）。判据是会话注册表 chat_sessions：隔离 sess-* 也回 404（其消息走 /admin/channels/{platform}/messages）。
破坏性：无。

v0.62

面板「重置为 env 默认」动作：新增 owner-only POST /api/v1/admin/llm/reset-from-env（body 必须 {"confirm":true}）。

纯增量：新端点 + 新审计动作 llm.resetFromEnv + 2 个新错误码（env_defaults_unreadable / models_unreadable），复用既有 llm_persist_failed/llm_reload_failed/llm_unavailable。
行为变更 / 破坏性：无。

v0.61

PDF 文本层抽取：白名单第 23 项 .pdf + 类型裁决改为 (扩展名, 嗅探) 成对裁决。

行为变更：① .pdf 由「一律 415」变为「可上传 + 可读取 + 文本层可抽取」；② 类型裁决收紧为成对判定（HTML/纯文本改名 .pdf ⇒ 415；PDF 改名 .txt ⇒ 415）。
纯增量：白名单 22 → 23 项（唯一新增 .pdf），其余 22 个文本类判定与响应一字未变。
破坏性：无。

v0.60

管理侧只读「存储状态」端点 + 面板存储卡接真数据：新增 GET /api/v1/admin/system/storage（owner-only、只读、无审计动作）→ {data:{main,documents,vector}}。

纯增量：新端点 + 前端新行为；既有端点/帧/字段形状一字未动。
行为变更 / 破坏性：无。

更早版本（v0.28 → v0.59）：见归档 Docs/archive/api-client.v0.65.md §5。 未实现的契约变更记录：归档 §5 里 v0.56–v0.59 的多条「未做/诚实边界」在 §7 重新登记。

7. 在飞切片与「未实现 / 未确证」

本节是诚实边界：让客户端不要以为已有、也不要误以为没有。

7.1 在飞切片

v0.66 及更早登记的在飞项已全部冻结、客户端可直接依赖（下表）。⚠️ v0.67 新登记的三批中，账号在线状态（accounts[].accountOnline）与非消息事件查询面都已落地（见 §7.2）；语音消息的用户可见面已由 v0.79 落地（仍残留 WS 帧/握手回放不带 voice；AMR 不落副本已由 v0.80 修复 —— 见 §7.2 / §7.4-29），不在本表，逐条见 §7.2。

项	状态	冻结位置
新下行帧 `turn_begin`	已上线（`c0dc435`）	§3.4.3；`session_events.go`、`session_parallel.go`
`steer_ack` 的帧壳 `turnId`	已上线（`c0dc435`）	§3.4.3；`session_steer.go`（`emitTurnState`）
`interrupt.turnId`	已上线（`c0dc435`）	§4.8；`ws_hub_turn.go`、`session_interrupt.go`
消息 DTO `turnId`（含 `chat_messages.turn_id` 迁移 `0018`）	已上线（`d64b26d` + `d804c4e`）	§4.4；`history.go`、`session_turn_id.go`
写类工具文件级互斥（读共享 / 读写与写写互斥，被占住回 `ErrFileBusy` 文案给模型）	已上线（`354b08a`、`ef3dcb6`）—— 纯服务端行为，无客户端可见契约面	`internal/runtime/tool/{fileclaims.go,legfile.go,tool.go}`、`loop/tools.go`

⚠️ 工作树另有未提交改动（未冻结、未登记为契约项）：当前工作树存在与本文档无关的未提交改动（例如助手回复的 <p> 段落包裹规整 internal/runtime/turnreply/、前端 turn 分桶接线等）。它们尚未 commit、未经契约评审，本文档不逐项登记其形状；客户端不要按当前工作树形态编程 —— 等它们冻结成下一版契约条目后再对齐（本表只登记已冻结的项）。归档版 v0.65 §J 曾把上表前四项列为「未实现」——那是归档时的代码状态，已过期。

7.2 确认为「未实现」（别当已有）

项	现状
✅ v0.67 登记的「语音消息面」（`GET /api/v1/media/{name}` + 消息 DTO `voice` + 入站语音音频副本落盘）	用户可见面已实现（v0.79，切片 L45）：端点 / 字段 / 副本口径见 §1.2 U19、§4.4、§4.5。落地：`documents.Store.SaveAudio`（音频白名单 / 内容寻址 / 0600）、`history.Store.UpdateMessageVoice` + `VoiceColumns`（`chat_messages.voice` 列读写两条路）、网关 DTO `voice`（含唯一派生 `url`）与 `GET /api/v1/media/{name}`。🔴 残留缺口（如实）：① `message_persisted` / `channel_persisted` 帧与握手 `history` 回放仍不带 `voice`（需给 `history.Message` 加字段，未做；且 `message_persisted` 在落库那一刻发出，天生拿不到落库后才回填的值）⇒ 客户端不要在实时帧/握手回放上等 `voice`；② ✅ 已修（v0.80，切片 W4 / 裁决 #11）：组合根已注入 `VoiceTranscoder` ⇒ AMR 也落副本（落盘前转成 `.wav`，`mime: audio/wav`）；`transcode_not_wired` 只剩「引擎未装配 / 构造失败」一档（生产装配下不再出现）；③ 消息/会话被删除时音频副本引用计数不被释放（`refs.go` 只认 `document` 列 ⇒ `ref_count` 偏高，后果是晚回收，绝不早删）；④ 生产端到端未跑（未重启后端）。⚠️ 同批的口径变更（`/admin/system/storage` 的 `documents` 段含语音副本）仍尚未生效；已生效的是 IM 语音「不可转写格式」正文提示改口径（形状不变，见 §4.5）。权威设计 `design/24 §10`
✅ v0.67 登记的「非消息事件查询面」（`GET /admin/channels/events`、`GET /admin/channels/events/counters`）	已实现（v0.67 登记项本切片落地）：形状与错误码见 §2.4(a)（已按代码核对：元素键名 camelCase、`approx` 与 `counters` 同级、`400 bad_request`、`owner\|admin` 档）；权威设计 `design/26 §4.5`。未接线存储 ⇒ `500 channel_events_unavailable`。⚠️ 本行留在此表仅为与上一版对照，下版改文档时应移入 §7.1 在飞切片表并回填 §2.1/§2.2 的端点计数
✅ v0.67 登记的「账号在线状态」（`GET /admin/channels` 的 `accounts[].accountOnline`）	已实现（v0.67 登记项本次落地；落地前基线 `f91a83f`，本切片 commit 由主会话补记）：形状见 §2.4(b)。管理面按可选接口断言读 `AccountStatus()`（`plugins/channels/qq_obv11/probe.go`，`a79fe96`）；适配器没有该状态面、或实现了但 `known=false` ⇒ 键缺席（未知 ≠ 离线，绝不用 `false` 冒充）。当前只有 `qq-obv11` 会带该键。⚠️ 本行留在此表仅为与上一版对照，下版改文档时应移入 §7.1 在飞切片表
✅ P1-T：`directMsgPerMin` 的 gateway 写入路径（`GET /admin/channels` 的 `accounts[].directMsgPerMin` + `PUT .../config` 的顶层 `directMsgPerMin`）	已实现（v0.69）：缺口 = gateway 面没让该字段通过 ⇒ 面板保存一次渠道配置就把主人手配的「关闭流控（-1）」静默重置回 `0` = 保护性默认 6 条/分。现 5 处透传（`AdminChannelAccount` DTO / `channelConfigRequest` / `config.ChannelAccount` 拷贝 / `adminChannelAccountOf` / 微信扫码重建账号）。形状见 §2.2 A5 与 §2.3 C28 注
✅ 「工具回看面」（消息 DTO `toolCalls[]`）	已实现（v0.78 落地，v0.79 起覆盖全部编排回合）（切片 CODE-TC + CODE-TC-2）：形状、缺席语义与覆盖率见 §4.4；读侧依赖 = 迁移 `0023` 的 `flow_graphs.lane_turn_id`（等值索引）+ `FlowGraphStore.GraphsByTurnID`（一页一次 `IN` 批量查，禁 N+1）。✅ v0.79：编排器驱动的每一路（含普通单路回合与队首续跑路）的图都带权威 `turnId` ⇒ 普通单路聊天与队首续跑回复现在也能回看工具。⚠️ 仍缺席：后台思考（`sess-backthink`）、未接编排器的调用方、v0.79 之前的单路历史行。⚠️ 单路在 HTTP 出口的端到端未由本切片确证（写侧已验，gateway 读侧待补）。见 §7.4-23 / §7.4-25
✅ v0.76 登记的「未读面」（`message_persisted.data.unreadCount`）	已实现（本切片）：形状、缺席语义与三条缺席路径见 §4.13，帧表见 §3.4.4。⚠️ `GET /api/v1/sessions` 的同名键自 D4 起就已在（`historySessionSummary.UnreadCount`），本片未改它 —— 所以「加同键」这句对列表面其实是既有事实，不是本版新增
`graph_update` 按路分桶	✅ 已实现（v0.77，切片 FV2）：帧 `data` 新增每路的 `turnId` 与 `round`，图按 `{会话}#{路}` 分桶 ⇒ 每一路各发自己的帧、各落一行（不再互相顶掉）；管理面 `GET /admin/flow/graph` 新增 `lanes[]`。形状与缺席语义见 §3.4.5 / §4.11(a)(d)，登记见 §7.4-19。⚠️ 真并行未做真机端到端（见 §7.4-24）
第二路进行态 system 摘要（`WithParallelNotice`）	未实现：全仓无该符号；`session_parallel.go` 明示留待后续切片
env `CHAT_MAX_PARALLEL_TURNS`	未接线：`Deps.MaxParallelTurns` 是构造期旋钮，但组合根未从任何 env 读它 ⇒ 生产恒为默认 2
`tool_execution.update` 的生产者	wire 映射已实现，但工具分发器暂无中途进度上报源（全仓无 `StreamKindToolExecutionUpdate` 的生产者）⇒ 实际暂无生产者（`start`/`end` 真实发出）
`chat_messages.turn_id` 上的 IM 行	IM 渠道桥不走网关编排器 ⇒ 其行 `turn_id` 留空属预期（契约里该键缺席），不是缺陷
记忆整理候选的 apply / reject / revert + 候选列表 + 运行历史（`design/23 §11`）	未实现（v0.75 只加了「试算」B14）：试算只「算给我看」、不改任何记忆。`GET /admin/memories/candidates`、`POST .../candidates/{id}/{apply,reject,revert}`、`GET /admin/memories/tidy/runs`、`POST /admin/memories/tidy/run` 均尚未实现。客户端不要假定它们存在（`design/23` 的第一版口径本就是「只产建议，apply 才写记忆」，apply 未做的前置原因见该节开放点）。⚠️ 别与 v0.79 的 `POST /admin/memories/{id}/revert` 混淆：后者是入库前审查（D3）软合并的回滚（§2.2 B17），与「整理候选」是两件事
`GET /api/v1/admin/memories` 的整理相关字段（`kind` / `tags` / `confidence` / `createdAt` / `updatedAt` / `sourceConversation` / `status` / `mergedInto` / `mergeCount`）	未实现：该端点当前仍只回 `{id,scope,text}`（`design/23 §11` 登记的读侧缺口）。v0.75 未改它的形状 ⇒ 面板暂时无法在这一页按 kind/status 过滤（试算端点 B14 的候选自带这些分区键与 kind）
✅ 记忆「入库前审查」的面板面（`GET /api/v1/admin/memories/reviews`、`POST /api/v1/admin/memories/{id}/revert`）	已实现（v0.79，切片 L45；v0.77 登记时无 HTTP 入口）：两条都走 `writeAuth`（owner\|admin），形状见 §2.2 B16/B17。⚠️ 残留：① 留痕列表只有 `limit`、没有分页游标（无 `before`/`offset`）；② `memory_ingest_reviews` 无 TTL / GC；③ 回滚只回滚「被吸收行」这一侧（不恢复存活行被抬高的 `confidence`）；④ 门与 `design/23 §11` 表格的 owner-only 有差异（待裁决）。同样是新审计动词 `memory.review.revert`（`design/23 §16.4` 表里还没有它，需设计侧补记）
✅ v0.78 插件动作的「执行器」（`POST /admin/plugins/{id}/actions/{action}` 的动作本体）	已接线（v0.79，切片 L1/PLG-2 执行面接线）：插件管理器新增动作处理器登记面（`Manager.RegisterActions`；单一全局 `SetExecutor` 已删除），组合根在 `wirePanelHub` 里登记内置 `web-search` 的四个动作 + 候选来源 `plugin.providers` ⇒ 这些动作真执行（真读写可变源、探针真发一次 HTTP）。`501 action_not_implemented` 只在「已声明但宿主未登记处理器」时出现（不再是兜底档）。✅ v0.80（切片 W3）：面板保存后热重载（重建工具 + 原子替换注册表条目，下一轮生效、不需重启；会让后端下次起不来的配置 ⇒ 按字节回滚 + `409 config_unstartable`）；面板已可配主 provider / 降级链（`primary` / `fallback[]`）。⚠️ 残留：探针只用 `httptest` 假上游（未对真实上游连通）；启用态不跨重启持久化；真机面板端到端未跑。见 §4.14(b)(c) / §7.4-26 / §7.4-27
🔴 v0.78 热装插件的面板声明来源（`plugins/<id>/manifest.json` 读取）	未实现（切片 PLG-2 / PLG-1）：目录能键热装插件、生命周期已接，但没人喂声明 ⇒ 热装插件在 `GET /admin/panels` 的 `pluginIds` / `groups` 里恒为「未声明管理页面」。当前唯一有声明的是内置 `web-search`（组合根装配期 `Declare`）
`PUT/POST /api/v1/admin/plugins/{id}/enable\|disable`	未实现（切片 PLG-2）：`Manager.SetEnabled` 已实现并有测试，但没有 HTTP 面 ⇒ 客户端不得假定能经 REST 启停插件（`panels_changed` 的 `enable`/`disable` 两种 `reason` 因此当前不会在运行期出现）。⚠️ 且启用态不跨重启持久化（`PluginConfig` 无 `enabled` 字段，`SetEnabled(false)` 只在进程内生效，重启按「已安装」恢复为启用）
`panels_changed` 帧对 `viewer` 可见	未实现（刻意）：该帧未登记进 `frameReachesAll` 白名单 ⇒ 按 fail-closed 默认档只发 owner/admin，viewer 收不到（须自行刷新/轮询重拉 A13）。放开需先改 `ws_frame_scope.go` + 在 `design/11 §7.1` 登记理由（不在本版）
插件动作审计的持久化粒度	未含 pluginId / action（切片 PLG-2）：持久化审计记录沿用既有 `AuditStore.Append(ctx, who, what, result, ts)` 四字段 ⇒ 只落 `what="plugin.action"`；插件 id 与动作名只在结构化日志行里。要进持久化记录需改 `AuditStore` 签名（不在本版）
🔴 v0.78 渠道事件实时面的「其余全部事件」	未接线（切片 E7）：覆盖桥接层写入的全部渠道事件的 `events.PublishingStore` 装饰器已实现但组合根未接（`grep` 全仓无 `NewPublishingStore` 的生产调用点）⇒ 目前只有账号状态迁移这一路会产生 `channel_event` 帧；其余渠道事件仍只能靠 REST 轮询。接线只需组合根两处（`events.NewPublishingStore(...)` + 把 `wire_channels.go` 的 `EventStore` 换成它），⚠️ 只装饰这一处（网关侧 `Deps.EventStore` 不要也换，否则账号状态行会被推两次）
🔴 v0.78 `GET /admin/channels` 的 `accounts[]` 每账号凭据三态	未实现（切片 CODE-F3）：`authState`/`authDetail` 只落在 `GET /admin/channels/{platform}/login-status`（§2.4(c)）；每账号版本需要给 `AdminChannelAccount` 加两字段 + 一个合并器 + 一次取数（收集器 `liveAccountAuthStates()` 已实现并有单测，无调用方）⇒ 客户端不得假定 A5 的 `accounts[]` 会带这两个键

⚠️ 本表（§7.2）的两条口径：① 标 ✅ 的行（如 v0.67 的两项、directMsgPerMin、graph_update 按路分桶、toolCalls[]、unreadCount）留在表里仅为与上一版对照，它们已经是可用契约面，见各行指向的章节；② 标 🔴 的行不要当已有。

7.3 诚实边界（既有事实）

subagent_result 不落库：父会话转录里没有新消息、重连回放不补发。
proactive_message（v0.72 起）落库：成为主会话 web 的一条 assistant 行（见 §3.4.5 后的「落库口径」）。仍未落库的情形（都是如实、预期的）：① 被 PushGate（频率门 / 冷却 / 按风格窗口）或安静时段挡下的推送 —— 「这一条不发」就没有记录，绝不留下一条它没发过的消息；② 后端未接线历史存储（HistoryStore: nil，仅测试与异常部署）时只发帧不写库，进程重启即丢。
task_done / automation_result / subagent_result 不是会话消息：它们不进消息 store、不是气泡（后端也没有把它们写成 chat_messages 行；subagent_result 更是错过即永久丢）。客户端应把它们落到自己的可观测面（Web 端落在本端 WS 事件回显 + 任务日志）。
GET /api/v1/files/{name} 无鉴权（能力 URL）；文档读侧相反、必须 Bearer。
GET /admin/llm/usage 不按 session_id 过滤/分组（尽管该列已落库）。
POST /audio/speech 的请求体 voice/format 当前不生效（合成遵循服务端 VOICE_TTS_VOICE_ID/VOICE_TTS_FORMAT）。
/audio/voice-clone 真建音色需公网参考音频 URL（当前无，待提供）+ 北京地域 API Key。
可观测三帧 observability_*：?level= 分级过滤由客户端本地做（帧广播给所有 owner/admin 连接，订阅只决定循环跑不跑）。审计 tab 仍 5s REST 轮询（未做 observability_audit 帧）。
thinking 恒缺席（v0.66 口径更正）：消息 DTO 的 thinking 在所有读取面都不出现（history.Message.Thinking 全仓无写入者）。思维链只有实时 thinking.* 帧（owner/admin）。旧文档称「历史思维链可由 GET /sessions/{id}/messages 返回」是错的，见 §3.4.4。
消息 DTO 的 turnId 只在 Web/网关回合存在：IM 渠道桥不经过网关编排器 ⇒ 其落库行的 turn_id 为空、DTO 里 turnId 键缺席（预期行为）。turn_begin / steer_ack / interrupt.turnId 同理只存在于网关回合。
GET /api/v1/media/{name} 读侧要 Bearer owner/admin（v0.67 登记）：音频 URL 不能直接贴进 <audio src>（浏览器不带 token）⇒ 客户端须带 token 取字节（Web：fetch → blob:）。这是有意的（语音是私密内容，与图片读侧「128-bit 名即凭据」的取向刻意相反）。
微信（weixin-ilink）入站语音没有音频副本、不可回放（v0.67 登记）：按既有裁决「平台自带转写就不白下载那份音频」⇒ voice.source:"platform" 且无 name/url，只保留 🎤 标记。
416 不是 JSON 信封（v0.67 登记）：GET /api/v1/media/{name} 的 Range 错误由 Go 标准库直写 text/plain，不套 {"error":{…}} ⇒ 客户端别拿 error.code 解析它（§0.3 / §4.1 / §4.5）。
账号级限流字段是「值语义」，不是三态（v0.69 明确）：groupMsgPerMin/msgPerMin/maxMessages/directMsgPerMin 在请求体里省略即 0（未设置）—— 一次「只改 token」的 PUT 若不带这四个键，会把已设限额（含 directMsgPerMin:-1）重置为 0。要保住就必须回送（面板已如此做）。这是 v0.68 起既有的顶层字段口径，v0.69 未改。
后台思考行的实时帧只带记录里的字段（v0.70 边界）：urgency 在实时帧上一定是精确档位（记录落库值），urgencyLowerBound / quietHoursBypassed 不在记录里、因此实时帧不带 —— 它们由网关读历史时按安静时段窗口推导（见 §4.10(b)）。⇒ 实时行的「穿透安静时段」标记要等重开页面/历史拉取才出现，这不等于「这一轮没有穿透」。
toolCalls 只在 GET /sessions/{id}/messages 填充（v0.78 边界；覆盖率 v0.79 已补齐）：共享 DTO 上的新键，但只有该 handler 会填它；其余出口（PATCH /messages/{id} 响应、GET /admin/channels[/{platform}]/messages、message_persisted / channel_persisted / message_edited、握手 history 回放）逐字不变（有单测钉住）。⚠️ v0.78 时覆盖率只到真并行路 —— 已由 v0.79（切片 CODE-TC-2）补齐至全部编排回合；仍缺席的是后台思考会话与 v0.79 之前的单路历史行（见 §4.4 / §7.2）。
voice 只在 4 个 REST 读取面 + message_edited 填充（v0.79 边界）：message_persisted / channel_persisted 帧与握手 history 回放仍不带 voice（需给 history.Message 加字段，未做）；且入站语音的 voice 列是落库之后回填的 ⇒ 即使加了字段，message_persisted（在落库那一刻发出）也拿不到值。客户端不要在实时帧 / 握手回放上等 voice（见 §3.4.4 / §4.4 / §4.5）。
memory.review.revert 是新审计动词（v0.79）：design/23 §16.4 的 memory.* 表里还没有它（需设计侧补记）；回滚只记 item id、不记正文。
web-search 的「.env 只播种」（v0.78 行为变更）：可变源文件 $DATA_DIR/config/plugins/web-search.json 一旦落盘，.env 的 WEB_SEARCH_* 只在文件缺失时起作用 ⇒ 改 .env 不再影响运行中的部署（这是 design/09 §5.7 E 要的「.env 只播种、面板是配置面」，但运维视角上是行为变更）。🔴 不是 env 键新增/删除。
channel_event 是 best-effort 增量提示、且当前只覆盖一路（v0.78 边界）：帧可能在 hub 发送缓冲满时丢掉该连接的那一帧 ⇒ 客户端必须保留 REST 轮询兜底（以轮询结果为准重排）。且目前只有账号状态迁移会产帧（其余渠道事件的实时装饰器未接线，见 §7.2）；帧里那行的 id 可能整缺（刚落库、id 尚未回读）。
panels_changed 只发 owner/admin（v0.78 边界）：该帧不在 frameReachesAll 白名单 ⇒ viewer 收不到「插件面板变了」的通知，须自行刷新/轮询重拉 GET /admin/panels。且当前运行期只可能在装配期推一次（内置声明 declare），enable/disable/install/uninstall 四种 reason 需要没有 HTTP 面的 SetEnabled / 插件安装端点才会出现（见 §7.2）。

7.4 「未确证」清单（客户端请以实测/代码为准）

GET /meta/enums 逐值（platforms/moods/modes）取自归档转述，本文档未逐一回 internal/contract/enums 核对。客户端应直接读端点，不要硬编码。
conflict(409) 通用错误码除 chat_busy 外，还有哪些端点会带它 —— 未逐一确证。
各管理写端点的精确请求体字段与状态码：本文档 §2.3 只给「方法/路径/鉴权/一句话要点」，未逐字段展开（归档 Docs/archive/api-reference.v0.65.md 有历史详细版，但可能漂移）。客户端实现管理写操作前请回代码或参考该归档并以代码为准。
observability_metrics 的完整 AdminMetrics 字段集：本文档只说明它是扁平快照，未展开字段。
subagent_event 在 subagent_ask 应答路径上的精确字段（orchestration.AuditResult 形状）：未展开。
account_not_registered(409) 的适用面：本文档只确证了 C19/C20（open/close）会带它；POST /admin/channels/test、/{platform}/message/test 等其它渠道端点是否也有等价的账号级错误码 —— 未逐一确证。
turn_begin.data.leg 在长会话中的取值范围：代码里是会话内单调递增序号（非「1/2 路」固定枚举），但本文档未确证客户端应如何展示 >2 的取值 —— 建议只当诊断信息用。
GET /admin/channels 的 accounts[] 除 connected 外的字段集：本文档未逐字段展开（该结构在 v0.66 只是新增一个可选键；v0.67 另登记了一个可选 accountOnline，见 §2.4(b)）。
（v0.67 登记 · 已落地确证）GET /admin/channels/events 的 events[] 元素 JSON 键名：已定为 camelCase，逐字与 internal/services/gateway/admin_channel_events.go 的 channelEventDTO 一致：id / platform / accountId / tier / category / platformType / channelId / channelType / groupId / actorId / actorRole / targetId / selfRelated / messageId / summary / createdAt / updatedAt（时间为 UTC RFC3339；counters[] 同为 camelCase，风格一致）。客户端可以硬编码这些键名了。
（v0.67 登记 · 已落地确证）events.total 的语义：是筛选条件下的总条数（不受 limit/offset 影响；与 events 同源条件），因此 total > events.length 是正常的分页状态。
（v0.67 登记 · 已落地确证）渠道事件查询的参数默认值与错误码名：limit 未给 / ≤0 ⇒ 存储层缺省 100；超硬上限 ⇒ 钳到 500（不报错）；offset 负值 ⇒ 0；非法整数 ⇒ 400 bad_request。platform 未知 / tier 非 t1|t2|t3 / since-until 跨度超 90 天 / 时间点非法 ⇒ 一律 400 + code:"bad_request"（未新造专用错误码）。category 不做白名单（未知类别 = 精确匹配 ⇒ 空结果）。approx 的嵌套层级已定为 data.approx（与 data.counters 同级）。
（v0.67 登记 · 已落地确证）两个渠道事件端点的 RBAC 档位：owner|admin（writeAuth），与渠道消息日志面（B2/B3）同档；viewer 为 403。依据：事件行带群 id / 成员 id / 关联消息 id，属私有内容面，不是 viewer 的监控投影。
（v0.67 登记 · 已确证）accounts[].accountOnline 的字段名与是否有 known 同级键：字段名 accountOnline 为本契约所拟（设计只规定「独立状态面 / AccountStatus() / known 三态」，未给管理面字段名），实现沿用了它、未改名；不发 known 同级键 —— 「未知」由键缺席承载。哪些平台会带该键已确证：只有适配器实现了 AccountStatus() 的平台（当前仅 qq-obv11）。
（v0.67 登记）音频各容器在各客户端的可播放性：amr / flac / opus 在部分浏览器内核上播不了（design/24 §10.6 明确「未逐一实测」）⇒ 客户端以实测为准，播不了就照实提示。
（v0.67 登记）GET /admin/system/storage 的 documents 段是否拆出语音副本：设计本期不拆（不新增 kind 列 / 不按 ext 聚合）⇒ 该段只增口径、不变形状，客户端不要指望能分开统计。
（v0.67 登记 · 前向提示）voice.url 指向的可能不是原件，而是转码后的副本：design/24 §10.14 已把「源格式不可播 ⇒ 转码成可播副本（唯一必需的路 = amr → wav）」立为口径，转码能力规格见 design/25-转码能力.md（已接线：工具面 transcode 工具（cmd/cyrene/wire_transcode.go）+ 入站语音副本归一；v0.80 切片 W4 补齐了 channelbridge 侧的 VoiceTranscoder 注入 ⇒ amr → wav 这条路在生产装配下真的会走）⇒ 客户端不要假定 url 一定是某一种音频格式，一律按响应的 Content-Type / mime 如实处理，播不了就照实提示（绝不给一个播不了的 url 假装能播）。⚠️ 本条不在 design/24 §10.11 的差异清单内（§10.11 与 §10.13 均无「零转码」绑定表述），登记它是因为「url 的字节格式」会直接影响播放端；最终口径以 design/25 为准。
（v0.68 登记 · v0.70 更正）urgency 的「下限」与「精确」之分：
- v0.68 原文（当时成立，现已过期）：urgency 一律是「档位下限」，warning 读作「至少 high（也可能是 critical）」；窗口之外的轮次不下发该键（backthink.Record 不带重要度、推送成功的行 detail 被投递说明覆盖 ⇒ 无损精确档位已不可能），要精确档位需 backthink 侧把每轮 Import 落进记录（当时未做）。
- v0.70 更正：每轮 Import 已落库 ⇒ urgency 默认就是精确档位（含窗口之外/白天的轮次）；只有与 urgencyLowerBound:true 同时出现时才是下限（旧行 / 从未走到档位判定点的行，值由安静时段窗口规则推导）。实时 backthink 帧也带 urgency（精确值），但不带 urgencyLowerBound / quietHoursBypassed（见 §4.10(b) 更正）。
- 客户端两条硬约束（v0.70 新增）：① 不得把带 urgencyLowerBound:true 的「下限」显示成精确档位（≥ 高 ≠ 高；同形就等于把推导冒充事实）；② 不得把键缺席显示成「例常 / routine」（缺席 = 存档里没有这个事实），也不得据此推断安全域。
（v0.71 登记 · v0.73 更新）「最近一轮」≠「你要的那一轮」：GET /api/v1/admin/flow/graph（§4.11）在省略 turnId 时回该会话最新的一张图（先内存 loop.FlowPublisher.LastGraph，miss 才落盘）。后台思考行上点开的图因此可能不是该行那一轮 ⇒ 面板必须在图上说明（当前 frontend/web/src/admin/modules/flow/FlowSnapshotHint.tsx），客户端不得把它渲染成「这一行的链路」。v0.73 起客户端要精确取某轮就带 turns[].turnId（多轮历史回放已实现，design/19 §4 的 P3）。
（v0.71 登记 · v0.73 更新 · v0.77 更新）图源是进程内内存**，但每轮收尾会落盘（v0.73）：loop.FlowPublisher 的每会话最近一图仍是内存**（design/19 §1 的实时口径），但 EndRound 会把该轮写进 flow_graphs（迁移 0022）⇒ 后端重启后、该会话还没跑新轮次时，省略 turnId 的查询回退落盘即可拿到最近一轮（source:"persisted"），不再一律 graph:null。⚠️ 仍会 graph:null 的情形：该会话本就在发布会话白名单之外（隔离渠道会话，从不建图也从不落盘）、或该会话从未跑过带 span 的轮次、或该轮已被保留期 GC 回收（默认 168h）。两路互顶已在 v0.77 修复（切片 FV2，登记裁决改为「按路分桶 + 会话级并列泳道」）：图按 {会话}#{路} 归属桶建（单路的桶逐字等于会话 id ⇒ 单路逐字不变），每一路各发自己的帧（帧 data 带该路 turnId 与 round）、各占一行落盘（flow_graphs 的唯一键 (session_id, turn_id) 因此不再把另一路整行顶掉），管理面 GET /admin/flow/graph 用 lanes[] 一次给出最近一轮每一路的图、前端 ≥2 路时按并列泳道呈现（见 §4.11(a)(d)）。⚠️ 仍如实的留白：turns[] 仍按路列条目（一轮两路会显示两条），按轮分组需新迁移 0023（未做）；Agents 页 / 后台思考页仍只显示最新一路；真并行未做真机端到端（见 §7.4-24）。
（v0.73 登记）落盘只覆盖「保留期内」且只覆盖白名单会话：turns[] 是已落盘且未被 GC 回收的轮次摘要，不是全历史（FLOW_GRAPH_RETENTION 默认 168h，≤0 = 关闭 GC ⇒ 那时才会无限增长，属显式选择）。落盘范围与实时发布同一白名单（flowSessionAllowed：web / web:<uuid> / sess-backthink）—— 群聊 / 陌生人会话永远不会出现在 turns[] 里。此外正在跑、尚未 EndRound 的那一轮不会在 turns[] 中出现（它是内存里的「实时」那一轮，source:"live"），这是如实而非缺失。
（v0.74 登记）message_persisted 的 proactive 判据只活在实时帧上，不落库：它是「这条是她主动说的话」在线上唯一的结构化判据（帧顶布尔键，由 gateway.BroadcastProactivePersisted 打上），没有对应数据库列（本片不动 schema）。因此 ① GET /sessions/{id}/messages、握手 history 回放、GET /admin/channels/** 读到的历史行不带它（预期：通知只对实时到达有意义）；② 客户端不得从 platform / adapterId / turnId 等行字段反推「是不是主动消息」—— 主会话里主动推送写的是解析后的真实平台（例如 weixin-ilink），与普通回复行同一形状，反推必然误伤。落库失败时不发该帧（没有权威 id 的 message_persisted 会被客户端整帧丢弃）。
（v0.75 登记）试算端点（B14）是「只读计算」，它不改任何状态：它不写 memory_tidy_candidates / memory_tidy_runs、不改 memory_items、不写审计链、也不推进心跳（不写 lastRun、不影响 nextDelay）。因此 ① 试算不会让「候选队列」（尚未实现，见 §7.2）多出任何东西；② 试算结果不是缓存：每次调用都重新算一遍，两次调用之间数据变了结果就可能不同（这是「同一套规则」的正常语义，不是不确定性），客户端不要把它当成会稳定的列表去 diff 或自动轮询；③ recallMode:"lexical" 是降级信号：它表示这轮没有走到语义向量（进程没接 embedder），此时召回更保守（命中更少）—— 若进程接了 embedder 而它不可用，试算直接报错（tidy_recall_unavailable），不会在响应里假装成 lexical。
（v0.76 登记 · v0.77 更新 · v0.79 更新）消息 DTO 的 turnId 与链路图的轮次键：图已带上每路的回合标识**，但两者仍是两套标识**：
- 消息侧：chat_messages.turn_id = 编排器发的那一路的随机路标识（turn- + 16 位十六进制；同路的 user 行与 assistant 行同值）。
- 图侧两个键：① graph.turnId（v0.77 新增）＝该图所属路的权威回合标识，与 turn_begin / steer_ack / 流帧帧壳的 turnId 同源同值 ⇒ 客户端可以用它把图与消息行按路配对**；v0.79 起编排器驱动的每一路（含普通单路回合）都带它；② graph.id / flow_graphs.turn_id 仍是图侧轮次键（形状 {会话}-{序号}[#{权威回合标识}]，不透明；序号是发布器进程内递增的建图序号、重启即从头开始），也就是 GET /admin/flow/graph?turnId= 的参数值。
- 客户端三条硬约束：① 要路标识就读 graph.turnId，不得解析 graph.id 去取它；② 仍不得拿消息的 turnId 当 ?turnId= 用（两者不同源）；③ 也不得把图上的序号当成会话里的回合序号（重启后序号会重复）。
- 🔴 graph.id 形状变化（v0.79，唯一一处）：#{权威回合标识} 后缀现在单路也追加（web-7 → web-7#turn-…）；老行（v0.79 前落盘的单路行）仍是 {会话}-{序号}。⇒ 一律使用响应里的 graph.id / turns[].turnId，不要自己拼（自拼的 web-7 查不到新行）；该值可能含 #，作 query 值须 URL 编码。
- toolCalls[] 覆盖率（v0.79 已补齐）：v0.77 起每路各落一行、图带 graph.turnId；v0.78 补上按路查图的读侧入口（迁移 0023 的 flow_graphs.lane_turn_id + FlowGraphStore.GraphsByTurnID）；v0.79（切片 CODE-TC-2）让每一路（含普通单路回合与队首续跑路）都带权威标识 ⇒ 普通单路聊天与队首续跑的回复现在也能回看工具。⚠️ 仍缺席：后台思考（sess-backthink）、未接编排器的调用方、v0.79 之前的单路历史行。⚠️ graph.id 仍不等于消息的 turn_id（两者不同源，不能用 graph.id 当 chat_messages.turn_id）。见 §4.4、§7.2、§7.4-25。
（v0.77 登记）「按路分桶」尚未做真机端到端：真并行（上行 chat.parallel）的修复是在单测层验证的（真 Loop.Run × 2 + 网关照同的 ctx 通道；网关侧走真 HTTP 处理器 + 真发布器），没有对运行中的后端发过一次真实 chat.parallel —— 因为线上产物是旧构建、且换二进制 / 重启有专门流程。因此未确证：真 WS 客户端在真并行下看到的两路帧时序（形状与分桶已由单测钉死，时序上等价但无实测）。另有一条已知的窄竞态（未观测、也未加锁消除）：若一路恰好在另一路起跑的瞬间收尾，第二条路可能被算作新的一轮（此时两路仍各有各的图与落盘行，只是面板不把它们并排展示）。
（v0.78 登记 · v0.79 更新）toolCalls[] 的覆盖率与端到端未确证：✅ 覆盖率已补齐（v0.79，切片 CODE-TC-2） —— 编排器驱动的每一路（含普通单路回合与队首续跑路）的图都带权威 turnId ⇒ 字段不再只覆盖真并行路。⚠️ 仍未确证 / 仍缺席的点：① 单路在 HTTP 出口的端到端未由本切片确证 —— 写侧（loop 的 3 个新用例，含真 Run → 真库 → 按消息那个 id 查回）已验，但网关读侧（internal/services/gateway/history_toolcalls_gap_test.go 那条「钉住现状缺口」的用例走的是老入口 StartRound，其前提句已失效）由主会话补验；没有对运行中的后端发过一次真消息来实测 GET /sessions/web/messages 拿到单路 toolCalls。② 「存库里的 lane_turn_id 与 chat_messages.turn_id 逐字相等」仍是代码级结论（两处都取 ctx 上的权威标识）。③ 老行（v0.79 之前的单路落盘）该列仍为空，不可能补齐（那时的图里没有该字段）。④ 后台思考（sess-backthink）仍缺席。⑤ 生产库 data/cyrene.db 现存行的回填命中率未统计（未碰生产库）。
（v0.78 登记 · v0.79 更新）插件管理面板接入点 / 动作执行面的真机未确证：GET /api/v1/admin/panels 与 POST /admin/plugins/{id}/actions/{action} 的真实运行期响应未在 :10942 上验过（换产物 / 重启有专门流程，本切片禁止）。所有证据来自 httptest + 进程内 bus。⇒ 未确证：真机上 data.pluginIds == ["web-search"]、groups[0].items[0].sections 的两段声明、route 的前缀拼接姿势（相对片段，前端拼 <prefix>/plugin/<pluginId>/<panelId>）。v0.79 新增未确证项：① 面板动作（plugin.listProviders 等）在真机上真的回 200 + result（单测层已用 httptest 真发 HTTP 验过探针）；② 真机探针未打过真实上游（无 key）；③ ~~面板保存 provider 后运行中的 web-search 工具不换接线（需重启）~~ ⇒ v0.80（切片 W3）已改为保存后热重载（hotReload:{applied,registered}），真机端到端仍未跑（真机上「保存后下一轮真的走新配置」未验；未换产物前旧二进制里仍是启动期接线）。另：panels_changed 的分组文案「插件」是宿主文案（design 未规定文案来源），改口径只改一个函数。⚠️ 且未换产物前，旧二进制里没有这些路由，属预期。为什么验不了（2026-10-06 复核）：本波禁换产物 / 禁重启后端，且取不到 owner 凭据 ⇒ 真机面板 e2e 无法做；代码侧已复核确证「非对象响应不追加 hotReload」（cmd/cyrene/websearch_reload.go 的 withReloadOutcome：非 map[string]any 原样返回）。
（v0.78 登记 · v0.79 更新）web-search 可变源的运行期口径未确证：组合根「先可变源、缺失回落 .env 播种」已有单测钉住（含「凭据不复活」「损坏文件不改写」「停用主 provider ⇒ 启动 fail-fast」等 7 条），并有一条真机 SearXNG e2e（provider=searxng 真返回结果）证明既有链路未被打断。v0.79：动作执行器已接线 ⇒ plugin.saveProvider 的落盘链路在 cmd/cyrene 的单测里真跑过（临时目录 + 真 runtimeconfig.SaveWebSearch）。⚠️ 仍未确证：「在真机面板上新增一家 provider → 下一次搜索真的走它」这条端到端（✅ v0.80 起保存后工具热重载：换注册表条目、下一轮生效（见 §4.14(c)），但真机端到端仍未跑，见 §7.2 / §6 v0.80 ②）。为什么验不了（2026-10-06 复核）：真机面板 e2e 需要 owner 凭据 + 真在面板上改一次配置（本波禁改数据、禁换产物 / 禁重启后端），且无任何第三方 key ⇒ 只能停在 httptest + 单测级证据。
（v0.78 登记）渠道事件实时面未做真机端到端：channel_event 的「采样 → 落行 → 推帧 → 只投 owner/admin」由真 SQLite + 真 bus + 真 WS 连接的单测/端到端用例覆盖，但运行中的 cyrene.exe 未重启（红线：主会话换产物）⇒ 没有真机日志证据。且当前 QQ 已停连 ⇒ 若真机启动，qq-obv11 账号为 known=false，首拍会落一行 账号状态未知（尚未探到）。另：心跳通道（meta_event.heartbeat/lifecycle）驱动的迁移仍未接（需适配器把状态投影进状态面，属 plugins/**），当前唯一迁移来源是探活（qq_obv11/probe.go）。
（v0.78 登记 · v0.79 更新）语音的端到端未确证：internal/runtime/voice/** 与 channelbridge 入站副本链有真 transcode.Engine（真 AMR 夹具 ⇒ RIFF/WAVE + 时长可确证）的走通用例；v0.79 补齐了网关侧（media_test.go 用真 httptest 真发 GET/Range/HEAD/条件请求，断言响应头与字节逐字相符 ⇒ 端点可用是「真跑过」的），并新增 documents.SaveAudio（含 0600 断言）+ history 的 voice 列读写。⚠️ 仍未确证：① 生产端到端未跑（禁止重启后端）⇒ 「真机 IM 语音 → 盘上有 0600 副本 → 客户端取到字节」只有替身 + 临时库/临时目录级证据；② ✅ 已修（v0.80，切片 W4 / 裁决 #11）：组合根已注入 VoiceTranscoder ⇒ AMR 转 .wav 后落副本 ⇒ 「Web 上能点开听 AMR 语音」的接线已成立（① 的生产端到端仍未跑，未重启后端）；③ message_persisted / channel_persisted / 握手 history 回放不带 voice（见 §4.4 / §7.3）；④ amr / flac / opus 在部分浏览器内核上可播放性未逐一实测（判据是设计登记的 MDN 规范级结论）；⑤ 删除消息/会话时音频副本引用计数不释放（ref_count 偏高 ⇒ 晚回收，绝不早删）。weixin-ilink 语音无副本、不可回放是刻意的（平台自带转写就不白下载音频）。

本文件由「以代码为真源」维护（当前 v0.80；v0.79 / v0.78 / v0.77 / v0.76 / v0.75 / v0.74 / v0.73 / v0.72 / v0.71 / v0.70 / v0.69 / v0.68 见本文件 §6，v0.67 及更早见本文件 §6 与 Docs/archive/）。范围：v0.80（三批 —— W1 链路图时间轴出口 / W3 搜索 provider 热重载 + 主 provider·降级链 / W4 入站语音 AMR 转码落副本）同步了 internal/runtime/flowgraph/**（timeline.go / timeline_test.go）、internal/services/gateway/**（admin_flow_timeline.go / admin_flow_timeline_test.go / history_toolcalls_gap_test.go / routes.go）、internal/capability/registry/**（registry.go / replacetool_test.go）、plugins/tools/io/search/**（panel.go / panel_test.go）、cmd/cyrene/**（websearch_reload.go / websearch_reload_test.go / websearch_selection.go / websearch_selection_test.go / websearch_testenv_test.go / websearch_action_data.go / wire_io_tools.go / wire_plugin_actions.go / wire_channels.go / wire_channels_test.go）与本文件（§2.0 / §2.2 B18 / §4.1 / §4.5 / §4.11.1 / §4.14 / §6 / §7.1 / §7.2 / §7.3 / §7.4）；v0.79（四批 —— L1/PLG-2 插件动作执行面接线 / L45 入库前审查管理面 / L45 语音用户可见面 / CODE-TC-2 链路图回合标识覆盖全部编排回合）同步了 internal/capability/plugin/**（actions.go / panelactions.go / panels.go）、internal/services/gateway/**（admin_panels.go / admin_memory_review.go / history.go / history_write.go / history_voice.go / media.go / routes.go）、internal/runtime/voice/media.go、internal/runtime/documents/store_audio.go、internal/runtime/history/voice_column.go、internal/runtime/loop/**（flow.go / run.go）、internal/runtime/trace/graph.go、internal/runtime/flowgraph/flowgraph.go、plugins/tools/io/search/**（paneldata.go / probe.go）、cmd/cyrene/**（wire_plugin_actions.go / websearch_action_data.go / websearch_probe.go / wire_frontend.go）与本文件（§0.3 / §1.2 U19 / §2.0 / §2.1 A13-A14 / §2.2 B16-B17 / §3.4.4 / §4.1 / §4.4 / §4.5 / §4.11 / §4.14 / §6 / §7.2 / §7.3 / §7.4）；v0.78（六面 —— CODE-TC toolCalls[] / PLG-2 插件面板接入点 / PLG-4 搜索 provider 可变源 / E7 账号状态事件与 channel_event / CODE-F3 iLink 凭据三态 / CODE-VOICE 语音落库面）同步了 internal/db/migrations/0023_flow_graphs_lane_turn_id.*、internal/db/migrations/0020_chat_message_voice.*、internal/runtime/flowgraph/**、internal/services/gateway/**（history.go / history_toolcalls.go / contracts.go / admin_panels.go / admin_channels_weixin.go / admin_channel_status.go / ws_channel_events.go / ws_bridge.go / ws_hub.go / routes.go）、internal/capability/plugin/**（panels.go / manager.go）、internal/capability/paneldecl/**、internal/config/runtimeconfig/websearch.go、internal/config/websearch.go、plugins/tools/io/search/**（panel.go / paneldata.go / probe.go）、plugins/channels/weixin_ilink/**（session_status.go / poll.go / send.go）、internal/runtime/events/**、internal/runtime/voice/**、internal/services/channelbridge/**（inbound_voice*.go）、pkg/plugins/sdk/panel.go、cmd/cyrene/**（wire_frontend.go / wire_io_tools.go）与本文件（§0.3 / §1.2 U19 / §2.0 / §2.1 A13-A14 / §2.4(c) / §3.2 / §3.4.4 / §3.4.5 / §4.1 / §4.4 / §4.5 / §4.14 / §5 / §6 / §7.2 / §7.3 / §7.4）；v0.77（链路图按路分桶 FV2 + 记忆整理护栏/异步 MT-A + 入库前审查 env 键 MT-B）同步了 internal/runtime/trace/graph.go、internal/runtime/loop/**（flow.go / flow_branch.go / run.go / steer.go）、internal/runtime/orchestration/**、internal/runtime/flowgraph/**、internal/runtime/memory/**（tidy*.go / preinsert*.go）、internal/config/**（config.go / memory_review.go）、internal/services/gateway/**（admin_flow.go / contracts.go / admin_config_facts.go / admin_memory_tidy*.go / routes.go）、frontend/web/src/store/**、frontend/web/src/admin/modules/flow/** 与本文件（§2.2 B12/B13/B15 / §3.4.5 / §4.1 / §4.10(a) / §4.11 / §4.12 / §4.12.1 / §5 / §6 / §7.2 / §7.4）；v0.76 的未读面（②）同步了 internal/services/gateway/**（broadcast.go / session_read.go）、internal/runtime/history/session_read.go 与本文件（§3.4.4 / §4.13 / §6 / §7.2 / §7.4），并按代码 + 库中真实数据实测确证了 chat_messages.turn_id 与 flow_graphs.turn_id 不同源 —— 该阻塞已由 v0.78（CODE-TC 的迁移 0023 + GraphsByTurnID）解除，toolCalls[] 已实现（覆盖率已由 v0.79 的 CODE-TC-2 补齐至全部编排回合）；v0.76 的 ③ 试算加性异步已由 v0.77（MT-A）落地校正；v0.75 同步了 internal/services/gateway/**（admin_memory_tidy.go / routes.go / deps.go / server.go）、internal/runtime/memory/**（tidy_dryrun.go / tidy_recall.go / tidy.go）、cmd/cyrene/wire_frontend.go、frontend/web/src/** 与本文件；v0.74 同步了 internal/services/gateway/**（proactive.go / broadcast.go）、internal/services/channelbridge/**（proactive.go / persist.go / proactive_notify.go）、cmd/cyrene/wire_frontend.go、frontend/web/src/lib/ws/handlers/** 与本文件；v0.73 同步了 internal/services/gateway/**、internal/runtime/loop/flow.go、internal/runtime/flowgraph/**、internal/db/migrations/0022_flow_graphs.*、frontend/web/src/** 与本文件；v0.72 同步了 internal/services/gateway/**（proactive*）、internal/services/backthink/**、frontend/web/src/** 与本文件；v0.71 同步了 internal/services/gateway/**、internal/runtime/loop/flow.go、frontend/web/src/** 与本文件。

305 KiB Raw Blame History Unescape Escape

Cyrene v2 客户端 API 契约

0. 基础约定

0.1 基址与版本

0.2 认证与授权

0.3 响应信封

0.4 三档标注惯例

0.5 未接依赖时的诚实边界（fail-visible）

1. 用户侧 REST 端点

1.1 公开端点（无需认证）

1.2 用户端点

2. 管理侧端点与权限矩阵

2.0 权限矩阵（口径与计数）

2.1 viewer 可读（14 条，viewerAuth）

2.2 owner/admin 读（18 条，writeAuth）

2.3 owner-only（40 条，ownerAuth）

2.4 v0.67 登记的管理面（渠道事件查询 + 账号在线状态）—— (a) 已实现 / (b) 已实现；v0.78 追加 (c) iLink 凭据三态

(a) 渠道事件（非消息事件）只读查询 —— 已实现

(b) GET /api/v1/admin/channels 的账号项：accountOnline

(c) GET /api/v1/admin/channels/{platform}/login-status 的账号项：authState / authDetail（v0.78 新增，切片 CODE-F3，已实现）

3. WebSocket /ws/chat

3.1 握手

3.2 握手 history 回放（角色门：只发 owner+admin）

3.3 上行帧（客户端 → 服务端）

3.4 下行帧（服务端 → 客户端）与角色门

3.4.1 全员白名单（7 帧）

3.4.2 结构化流帧（owner+admin；帧壳带 sessionId + turnId + seq）

3.4.3 编排帧（owner+admin）

3.4.4 持久化 / 历史帧（owner+admin）

3.4.5 子代理 / 任务 / 系统帧（owner+admin）

3.4.6 定向帧（不经 hub.broadcast，只到指定连接）

4. 契约细节

4.1 错误响应与错误码

4.2 分页与游标

4.3 幂等（clientMsgId）

4.4 消息 DTO（historyMessage）

4.5 图片 / 文档 / 语音链路

4.6 chat 请求与响应面

4.7 枚举权威表

4.8 interrupt 的 scope 与 turnId

4.9 会话角色绑定

4.10 v0.68 新增：配置事实面与后台思考行的紧急度

(a) GET /api/v1/admin/config-facts（只读，owner/admin）

(b) GET /api/v1/admin/backthink 条目的紧急度字段（v0.68 引入；v0.70 起是精确档位）

(c) 档位的来源与诚实边界（v0.70 重写）

4.11 链路图快照 + 多轮历史回放（GET /api/v1/admin/flow/graph；v0.71 新增，v0.73 增量，v0.77 增量）

(a) 请求与响应

(b) 语义硬约束（客户端必须照这个读）

(c) 与 design/19 的关系

(d) turnId / round 的增量键与缺席语义（v0.77）

4.11.1 链路图时间轴（GET /api/v1/admin/flow/timeline；v0.80 新增，切片 W1）

(a) 请求与响应

(b) 语义硬约束（客户端必须照这个读）

(c) 与老端点 turns[] 的分工（别把两者混成一条时间轴）

(d) 未确证（如实）

4.12 记忆整理「试算」（POST /api/v1/admin/memories/tidy/dry-run；v0.75 新增）

(a) 请求与响应

(b) 硬约束（客户端必须照这个读）

(c) 失败码

4.12.1 记忆整理「试算」的加性异步（?async=1 + B15；v0.76 新增 · ✅ 已实现（v0.77 校正））

4.13 未读实时面：message_persisted.data.unreadCount（v0.76 新增 · ✅ 已实现）

4.14 插件管理面板接入点与动作分发（v0.78 新增，切片 PLG-2 / PLG-4）

(a) GET /api/v1/admin/panels —— 面板接入点快照（v0.78）

(b) POST /api/v1/admin/plugins/{id}/actions/{action} —— 插件动作分发（v0.78）

(c) web-search 插件的动作面（v0.78 声明，v0.79 起真可用，切片 PLG-4 / L1；v0.80 起可配主 provider / 降级链 + 保存后热重载，切片 W3；供上面 (b) 的分发面使用）

5. env 与模型配置（与契约相关）

6. 变更记录

v0.80（当前契约版本）

v0.79（上一版）

v0.78（上一版）

v0.77（上一版）

v0.76（上一版 · ⚠️ 逐条状态不同 —— ①已由 v0.78 实现（覆盖率受限）；②③已实现）

v0.75

v0.74（上一版）

v0.73（上一版）

v0.72（上一版）

v0.71（上一版）

v0.70（上一版）

v0.69（上一版）

v0.68（上一版）

305 KiB

Raw Blame History

2.1 viewer 可读（14 条，`viewerAuth`）

2.2 owner/admin 读（18 条，`writeAuth`）

2.3 owner-only（40 条，`ownerAuth`）

(b) `GET /api/v1/admin/channels` 的账号项：`accountOnline`

(c) `GET /api/v1/admin/channels/{platform}/login-status` 的账号项：`authState` / `authDetail`（v0.78 新增，切片 CODE-F3，已实现）

3. WebSocket `/ws/chat`

3.2 握手 `history` 回放（角色门：只发 owner+admin）

3.4.6 定向帧（不经 `hub.broadcast`，只到指定连接）

4.3 幂等（`clientMsgId`）

4.4 消息 DTO（`historyMessage`）

4.6 `chat` 请求与响应面

4.8 `interrupt` 的 `scope` 与 `turnId`

(a) `GET /api/v1/admin/config-facts`（只读，`owner`/`admin`）

(b) `GET /api/v1/admin/backthink` 条目的紧急度字段（v0.68 引入；v0.70 起是精确档位）

4.11 链路图快照 + 多轮历史回放（`GET /api/v1/admin/flow/graph`；v0.71 新增，v0.73 增量，v0.77 增量）

(d) `turnId` / `round` 的增量键与缺席语义（v0.77）

4.11.1 链路图时间轴（`GET /api/v1/admin/flow/timeline`；v0.80 新增，切片 W1）

(c) 与老端点 `turns[]` 的分工（别把两者混成一条时间轴）

4.12 记忆整理「试算」（`POST /api/v1/admin/memories/tidy/dry-run`；v0.75 新增）

4.12.1 记忆整理「试算」的加性异步（`?async=1` + B15；v0.76 新增 · ✅ 已实现（v0.77 校正））

4.13 未读实时面：`message_persisted.data.unreadCount`（v0.76 新增 · ✅ 已实现）

(a) `GET /api/v1/admin/panels` —— 面板接入点快照（v0.78）

(b) `POST /api/v1/admin/plugins/{id}/actions/{action}` —— 插件动作分发（v0.78）

(c) `web-search` 插件的动作面（v0.78 声明，v0.79 起真可用，切片 PLG-4 / L1；v0.80 起可配主 provider / 降级链 + 保存后热重载，切片 W3；供上面 (b) 的分发面使用）