From 58cba0b8d2ba459c47a9e7f53c73bc36f7472098 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 4 Oct 2026 13:07:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20api-client=20=E2=86=92=20v0.53?= =?UTF-8?q?=EF=BC=88=E9=98=B6=E6=AE=B5=205=20=E5=85=A8=E9=83=A8=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=EF=BC=89+=20api-reference=20=E5=90=8C=E6=AD=A5=20+=20?= =?UTF-8?q?.env.example=20=E8=A1=A5=209=20=E9=94=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新端点 GET /admin/llm/catalog 全契约（200/gzip/503 catalog_unavailable/快照副作用/不进热路径/审计 llm.catalog） - models.json 组级三键：reasoning.kind（形状）+ personaModels/personaProviders（角色级模型/协议路由）， 含「缺省=保留、给出=整块/整表替换」语义、Group.Validate 的 400 口径、回落与 WARN 规则 - GET /admin/llm 新增恒下发的 reasoning 与两个取值域（reasoningKinds/personaProviderOptions） - 语义修正（此前文档写反）：multimodal = 主模型能否收图；LLM_VISION_MODEL/LLM_OCR_MODEL 只配视觉/OCR 工具 - 新工具 image-crop（x/y/width/height、50MiB/16MP/8MiB 上限、越界报错不 clamp、策略默认 owner-only） - 推理开关按形状下发：替换 v0.41「Qwen 只 WARN 不发」；effort 非法值改为丢弃+WARN（不降档）、effort:none 显式关思考 - .env.example 新增 9 键（LLM_REASONING_KIND / LLM_OCR_MODEL / LLM_LOCAL_* / CAPACITY_L3_*），默认均为保守值 - 权限矩阵计数按 routes.go 校正 56→59（owner/admin 只读档 9→10，含 /admin/llm/catalog） --- .env.example | 35 ++++++++++++++++++-- Docs/api-client.md | 75 +++++++++++++++++++++++++++++++++++++------ Docs/api-reference.md | 13 +++++--- 3 files changed, 106 insertions(+), 17 deletions(-) diff --git a/.env.example b/.env.example index 147d86e..efdb58f 100644 --- a/.env.example +++ b/.env.example @@ -50,10 +50,20 @@ LLM_FALLBACK_MODEL=gpt-4o-mini # 且该模型组未在 models.json 设 maxTokens、请求也未显式给 MaxTokens 时生效； # 0 = 关闭该兜底（改用适配器默认，如 anthropic 8192）。每模型组预算见 models.json 的 maxTokens。 LLM_FALLBACK_MAX_TOKENS=8192 +# 推理开关的【提供商形状】声明（裁决 03.4.2 / 08.4.1）：auto（默认，= 留空）/ deepseek / +# openai / vllm / dashscope。形状决定把思考开关下发改成哪个字段（如 vllm = +# chat_template_kwargs.enable_thinking、dashscope = 顶层 enable_thinking），必须按端点真实形状 +# 声明——发错形状会被上游拒。留空/auto = 按模型名与 base URL 推断厂商，形状有歧义时一个字段都不发。 +# ⚠️ 本键只作用于 .env 合成的模型组：存在有效 models.json 时，以该组的 reasoning.kind 为准 +# （面板可编辑，见「LLM 模型」页）。 +LLM_REASONING_KIND= -# ---- LLM 视觉模型（多模态路由：含图片的请求路由到此模型） ---- -# 不配置则图片路由回主模型；仅当启用多模态能力时设置。 +# ---- LLM 视觉模型（视觉/OCR 工具用的模型；与「主模型能否收图」无关） ---- +# 语义（v0.53 修正）：主模型自己能不能收图，看 models.json 生效组的 multimodal 字段（面板可勾选）， +# 不是看这里；本节的模型【只供 vision / ocr 工具】调用。都不配置时工具回落用主模型（LLM_MODEL）。 # LLM_VISION_MODEL=gpt-4o-mini +# OCR 工具单独用另一个模型（可选）：留空 = 复用 LLM_VISION_MODEL。 +# LLM_OCR_MODEL=qwen-vl-ocr # Provider = anthropic：Anthropic Messages /v1/messages（tool_use.input 为结构化对象，工具循环更稳） # ANTHROPIC_BASE_URL=https://api.anthropic.com @@ -64,6 +74,18 @@ LLM_FALLBACK_MAX_TOKENS=8192 # （deepseek-flash / deepseek-v4-pro）：不认识的名称（如 claude-*）会被服务端【静默映射成 deepseek-flash】， # 配置错了不会报错。旧的 deepseek-chat / deepseek-reasoner 已于 2026-07-24 停用。 +# ---- LLM 本地第三级（降级链末端；默认关，裁决 03.4.3） ---- +# 降级链为「主 → 备 → 本地」；本地这一级默认关闭（当前设备跑本地模型困难），链保持两级。 +# 开启需要三个条件同时满足：LLM_LOCAL_ENABLED=true + LLM_LOCAL_BASE_URL + LLM_LOCAL_MODEL； +# 只开开关不配端点/模型会被记 WARN 并跳过（不会半配成一个只会失败的链尾步）。 +LLM_LOCAL_ENABLED=false +# 本地端点协议：openai（llama.cpp / ollama / vLLM 兼容）或 anthropic；留空 = openai。 +# LLM_LOCAL_PROVIDER=openai +# LLM_LOCAL_BASE_URL=http://127.0.0.1:8080/v1 +# 本地服务通常不需要 key；留空即可。 +# LLM_LOCAL_API_KEY= +# LLM_LOCAL_MODEL=qwen3-4b-instruct + # ---- 记忆嵌入（可选，真语义） ---- # 不配置时使用内置 n-gram / FTS 向量（dim=256）。配置后必须真实走语义路径。 # EMBEDDING_API_URL 是【完整 /embeddings 端点】（不是 base）——例：Ollama / llama.cpp = http://localhost:11434/v1/embeddings @@ -120,6 +142,15 @@ THINK_KIND_WINDOW_SEC=7200 QUIET_START_HOUR=23 QUIET_END_HOUR=7 +# ---- 唤醒式能力渐进（capacity 意图判定，design/14 §2.2） ---- +# L3 = 模型辅助的意图分类：仅当 L1 启发式与 L2 上下文仍拿不准时介入一次轻量模型调用。 +# 默认关闭（纯启发式够日常，且该层要多花一次模型调用）；关闭时该层从不运行， +# L1/L2/L4 的行为与接线前逐字节一致。 +CAPACITY_L3_ENABLED=false +# L3 判定结果的缓存 TTL（Go duration，如 5m）：同一段回合文本在此窗口内复用判定，避免每轮都问模型； +# 留空 = 5m；0 或解析不出 = 不缓存。 +CAPACITY_L3_CACHE_TTL=5m + # ---- 子代理（orchestration，design/05 §7） ---- # 单个子代理整次运行的时限（秒）。默认 600 = 10 分钟（裁决 02.4.4：agent_timeout # 可配置）；模型派发时可用 subagent_spawn 的 timeout_seconds 参数按调用覆盖。 diff --git a/Docs/api-client.md b/Docs/api-client.md index 79d64be..52be7fa 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -25,7 +25,7 @@ | 1a | `/api/v1/auth/refresh` | POST | refreshToken | ✅ | **静默续期**（B2）：body `{refreshToken}` → `{data:{token,expiresAt,refreshToken?}}`（新 access + 新 refresh，**默认单次使用旋转**——旧 refresh 立即作废，并发重放 fail-closed `401 invalid_grant`）。`AUTH_REFRESH_ROTATE_DISABLED=true` 关闭轮换时旧 token 保持有效、不返回新 refresh。过期/已撤销/乱串统一 `401 {error:{code:"invalid_grant"}}`；成功才审计 | | 1b | `/api/v1/auth/logout` | POST | refreshToken 或 JWT | ✅ | **登出**（B2）：body `{refreshToken}` 撤**单个** grant（幂等）；带 `Authorization: Bearer ` 且无 body → 撤**该账号全部** grant（全设备登出，返回 `{revokedCount}`）。refresh 相关操作成功才审计 | | 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` | -| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06）——**真视觉需配 `LLM_VISION_MODEL`/凭据，无凭据时降级为主模型直接看图或视觉·OCR 工具文本描述**；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `

` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` | +| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,deviceId?,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉路由（design/06 §0；**v0.53 语义修正**）——**主模型能不能收图看生效组的 `multimodal`**（`models.json` 组键，面板可保存、热更新）；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**，**与主模型能否收图无关**（裁决 14.4.1）；主模型不收图时由视觉·OCR 工具的**文本描述**替代（图像不占上下文，只有工具结果占）；`deviceId` 为**客户端生成的具体端标识**（design/16 §4.5，如 `web:chrome:a1b2c3`，可选），落库到消息、便于主人知道从哪个端发来；`mode` 为**行为模式**（design/01 §3 / design/16 §5.1，如 `chat`/`code`/`home`/`docs`/…，可选），随该轮次落库——IM 恒 `chat`、缺省回落 `chat`，供前端按模式渲染气泡（仅 `chat` 才解析 `

` 拆气泡）。**会话编排（design/15）**：非流式且该会话「正忙」时**不阻塞**，返回 `202` `{data:{queued:true,queueDepth}}`（稍后按上下文续接）；待处理队列满时返回 `409` `{error:{code:"chat_busy"}}` | | 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}`。**会话持久化（design/16）**：注入 HistoryStore 后返回持久化会话元数据 `{data:[{id,type("main"|"sub"),title?,createdAt,pinned,unreadCount,lastMessage?,personaId?}]}`（**排序（D5）：`pinned=true` 优先，其次主会话 `id="web"` 恒在前，再按 `createdAt` 升序**；次级 `web:`；`pinned` 恒返回 bool；**`unreadCount`（D4）恒返回整数**——该会话中 `createdAt >` 已读游标的消息条数（0 = 无未读），与 `lastMessage` **同一条 SQL 派生**、无 N+1；`lastMessage` 为**最后一条消息预览** `{content,role(user|assistant),createdAt}`，content 折叠空白截前 60 rune，空会话省略；**`personaId`（v0.42，可选）**=该会话绑定的角色 id（design/22 §2/§4.5），**空/缺省 = 继承全局默认角色**（`owner.yaml:defaultPersona`），客户端据此渲染激活会话的角色名/头像）；未注入时退化回渠道会话列表 | | 5 | `/api/v1/sessions` | POST | JWT(owner/admin) | ✅ | **新建次级会话** → `201 {data:{sessionId,personaId?}}`（`sessionId="web:"`）。body **可选**（可完全省略或空 body）：`{personaId?}`（v0.42）在创建时就把新会话绑到该角色（design/22 §2：渠道级只作"新会话的初始角色提供者"；**会话角色只在创建时写入、之后不可变**，见 §1 行 8 / design/22 §8-1）；`personaId` 为**未知角色**回 `400 bad_request`；省略/空 = 不绑（`persona_id=''`，继承全局默认）；**`personaId` 非空时响应回显它**（省略时响应形状与 v0.41 完全一致）；未注入 HistoryStore 回 `501 not_implemented`；注入了**不支持角色绑定**的 HistoryStore 且显式传 `personaId` 时也回 `501`（不假装写入） | | 6 | `/api/v1/sessions/{id}/messages` | GET | JWT(owner/admin) | ✅ | **热分页拉历史**：`?limit=&before=&platform=&after=`（A5）默认 `limit=50`（上限 200）。**`before`**=上一页最旧 `createdAt`（毫秒），按时间**倒序**；**`after`**=<`createdAt` 毫秒>，按时间**升序**返回 `created_at > after` 的消息（**正向增量**，客户端把上次看到的 `createdAt` 当游标补断线期间漏的，解决重连只回放 50 条的缺口）；**`after` 与 `before` 互斥**，同传回 `400`；负数/非数字回 `400`。`platform` 为**可选**来源平台过滤（design/16 §4.4）——Web 端不传（=全量共享主会话），IM 适配器传**本平台**（如 `telegram`）只拉本渠道消息；`deviceId` 为**客户端具体端标识**；`senderName` 为**第三方发送者昵称**；**`personaId`（v0.42，可选）**=**该消息说话时的角色 id**（design/22 §7-5：逐条记录"谁说的"——会话角色在创建时固定，§8-1；assistant 消息 = 生成它的角色，user 消息 = 当回合角色；**空 = 全局默认角色**，即 v0.42 之前的全部历史消息），客户端据此按角色渲染名字/头像；**`q`**（D2）=**会话内内容搜索**（大小写不敏感 ASCII LIKE，`%`/`_`/`\` 已转义为字面量），仍按时间**倒序**、`before`/`limit` 同分页语义；`q` 与 `after` **互斥**（同传 `400`），空 `q` 视为未传（走普通分页），搜索**严格限定在 `{id}` 会话内**（绝不跨会话，群聊/陌生人隔离会话不会外泄）；非法 `limit`/`before`/`after` 回 `400`；未注入 HistoryStore 回 `501` | @@ -110,7 +110,7 @@ - Web 端镜像实现在 `frontend/web/src/lib/enums.ts`（`labelFor(kind, value)` 对未知值返回原值），权威仍以本端点为准。 - **反漂移保证（后端）**：后端有测试断言「每个内置适配器的 `Name()` 都在 `platforms` 表内」「`moods` 与 persona 情绪状态机的内置状态一致」「`modes` 与前端 `MODES` 九模式一致」——漏登记即 CI FAIL，客户端拿到的表不会滞后于代码。 -> **契约版本 `v0.52`**（**工具策略落盘 + 主代理代审小字 + 流程图节点参数摘要**，依据 design/11 §3/§4/§8（裁决 1.3 / 10.4.2 / 13.4.3）与 design/19 §1/§1.1（裁决 11.4.2 / 11.4.3 / 13.4.1），2026-10-04 落实）：① **工具策略（`allowInGroup`/`allowInStranger`）落盘 SQLite `tool_policies`（迁移 `0012_tool_policy`），重启保留**——`registry.SetPolicy` **先落库后改内存**，落盘失败则内存保持旧值并返回错误（见 §2 行 5）；② 新增下行帧 **`approval_notice`**（§3.11）：敏感操作经主代理代审后推一行小字（`explain` 由**后端产出**、客户端原样渲染），审计口径 `who`=角色名 / `what`=`approval.<工具名>` / `result`=`granted|denied`，**仅 `owner` + `admin`**（fail-closed 默认）；③ `graph_update` 节点 `props` 新增四类**纯增量可选**键（tool `args_keys`/`args_summary`、guardrail `action`/`allow`/`elapsed_ms`、memory `action`/`scope`/`hits`/`bytes`/`count`/`failed`、orchestration `subagent`/`persona`），`memory`/`guardrail`/`orchestration` 旁路节点 span **首次真进图**，值在发布前已脱敏——**帧名、事件名、顶层字段集一字未动**（见 §3.5）。**上一版 `v0.51`**：（**后台子代理结果登 WS 帧 + 回填父会话**，依据 design/05 §9「子代理完成 → 结果回填主会话并提示用户」，裁决 02.4.3，2026-10-04 落实）：新增下行帧 **`subagent_result`**（`{type, sessionId, data:{sessionId, status:"done", summary, agents:[{id, goal, role?, mode?, status, summary?, text?, steps?}]}}`，见 §3.10）——`subagent_spawn` 的批次转后台后结算时，编排层发布在 bus 主题 `subagent.result` 上的合并结果，此前**没有任何消费者**（中继既非 `ws.*` 也不认该 4 段以外的 subject）⇒ 结果上不了前台、只剩进度帧；现在该 subject 被登记为中继并成形为这一帧，**帧壳 `sessionId` = 派生该批次的父会话**，结果因此落回**父会话的实时流**。**角色门**：新帧属内容帧 → **只发 `owner` + `admin`**（fail-closed 默认，未扩 7 个状态机信号白名单）。**向后兼容**：纯新增帧，老客户端按未知帧忽略即可，既有帧/端点/鉴权一律不变。**诚实边界**：结果**不落库**（父会话转录里没有新消息、重连回放不补发）、**未**经 design/15 会话消息编排器续接、**前端尚无该帧 handler**（今天的效果是「帧到达 owner/admin 连接」）。**同版另含管理面（D 组，2026-10-04 落实）**：① **`X-API-Key` 真正接线**（裁决 15.4.2）：管理/用户侧已认证端点同时接受该头，命中签发表即通过且**一律 `owner` 级**（裁决 15.4.3 取消 role 分级），带该头时只走 key 分支、未知/已吊销/空值回 `401` 且不回落 Bearer（fail-closed），WS 握手仍只认 Bearer；② **新增主人白名单档案读写** `GET`/`PUT /api/v1/admin/owner-profile`（裁决 10.4.5，**owner-only**，写带审计 `owner.profile.update`）——面板的「保存」从此是**真保存**（落盘 `configs/users/owner.yaml` 0600 原子写 + 热替换活档案，渠道 actor 判定立即生效），不再是只改本地 state 的假成功；③ **persona `identity.systemPrompt` 改必填**（裁决 08.4.2）：缺失/空白回 `400 bad_request`，**不再派生默认说明串**，写出的 YAML 必能被载入期同一规则重新载入。见下方「管理面板写操作契约」。**上一版 `v0.50`**：（**事件批：流式帧的结构化补齐**，依据 design/04 §1.1，裁决 01.4.1 / 01.4.2 / 01.4.3 / 03.4.4，2026-10-04 落实）：① **`tool_execution` 拆三事件**——旧单帧 `tool_execution.update {id,index,delta}`（phase 与工具名拼在 `delta` 字符串里）被 **`tool_execution.start`**（进入执行，`phase:"running"`）/ **`tool_execution.update`**（运行中进度/局部输出，可多帧）/ **`tool_execution.end`**（完成或失败，`phase:"done"|"error"`）替换，载荷改为结构化 `{tool, phase, id?}`（`tool` = 工具名；`phase` = 细粒度执行阶段，与 §3.5 流程图节点 status 同一套 `running/done/error` 枚举；`id` = provider 工具调用 id，可与 `tool_call.*` 帧关联）——**phase 不再塞进 `delta`**；loop 现已真实发出 start/end（update 的 wire 映射已实现并验证，但工具分发器尚无中途进度上报源，**暂无生产者**，见 §3.1）。② **`streamId`（模型流帧 `data` 内新增可选字段）**：同一次模型流（一次 ChatStream 调用）的多帧共享同一 `streamId`，多步工具轮的第二次模型调用取新 id；与帧壳的 `turnId`（整个回合恒定）分工——`turnId` 标记「这轮回答」，`streamId` 标记「这轮里的哪一条流式消息」。③ **`turn.start` / `turn.end`（新帧）**：loop 在回合边界发出、经 ws_bridge 下行；**无 `data` 载荷**（帧壳的 `sessionId`/`turnId`/`seq` 即边界信号；回合终态信息仍由既有 `stream_end` 携带）；`turn.end` 覆盖回合的所有出口（最终答案 / 工具循环安全网终止 / 预算耗尽 / 步骤出错），被静音的内部流程（backthink / 子代理）不发出。④ **向后兼容**：`turn.start/end` 与 `streamId` 为纯新增，老客户端可安全忽略；**破坏性**在旧 `tool_execution.update` 单帧——loop 不再产生它，按旧形状（解析 `delta` 里的 `phase:工具名` 拼串）消费的客户端必须迁移到三事件；现有 Web 前端未消费这些帧，行为不变。⑤ 本批新帧全部落在 v0.48 下行帧门的「仅 `owner` + `admin`」档（fail-closed 默认，无需扩白名单）。⑥ **`graph_update` 会话范围口径修正**（裁决 01.4.5，随实现事实补记）：`web` / `web:` / `sess-backthink` 三范围（见 §3.5）。见 §3.1 与 v0.50 变更记录。**上一版 `v0.49`**：（**WS 握手回放与上行帧的角色门（design/11 §7.2）**：补上 §7.1 下行门之外的**同一类缺口的另两处**，对 `viewer` **继续收紧**，`owner` / `admin` 行为不变，**无端点、无字段形状变更**——① **握手 `history` 回放改为仅 `owner` + `admin`**：此前任意角色一连上 `/ws/chat` 就会收到主会话最近 50 条消息正文（`thinking` 已剥离，但**正文本身**就是主人的对话），`viewer` 从此**不收**；② **上行 JSON 帧按角色授权（fail-closed）**：非 `owner`/`admin` 连接发来的**任何**上行 JSON 帧一律拒绝，**定向**（只回发送者）回 `{type:"error",data:{code:"forbidden"}}`，**不广播、不驱动模型、不落库、不返回任何内容**——被拒帧含 `chat`（此前 `viewer` 可**真的驱动模型并落库**）、`interrupt`、`subagent_ask` / `task_output_query`（其应答是**定向**帧、能绕过 §7.1 下行门把子代理上下文/任务输出直接回给 `viewer`）、`voice_input`、`mode_switch`，且**未登记的新上行帧默认拒**；**协议级帧（ping/pong、close）不受影响**。③ **合口径**：`viewer` = **可连接、可读 12 条只读监控 REST（v0.40）、可收 7 个状态机信号帧（v0.48）**；**除此以外 WS 上拿不到任何内容、也发不出任何指令**。见 §3 开头的「上行帧与握手回放的角色门」与 v0.49 变更记录。**上一版 `v0.48`**：（**WS 下行帧的角色门（design/11 §7.1）**：hub 的下行现在是**按帧类型分档**的——只有 7 个**状态机信号**（`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full` / `session_read`，**均不含任何内容**）继续发给**所有已认证连接**（含 `viewer`），**其余全部下行帧**（流式内容 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` / `stream_chunk` / `stream_end` / `thinking`；持久化 `message_persisted` / `message_edited` / `message_deleted` / `channel_persisted`；系统内部 `graph_update` / `subagent_event` / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`；私有状态 `mood` / `device_update` / `reminder`）**改为仅发 `owner` + `admin`**）。**对 `viewer` 是收紧**：此前它连上 `/ws/chat` 就能收到角色回复正文与推理内容，现在收不到；**`owner` / `admin` 行为不变**；**无端点、无字段形状变更**——`viewer` 的 12 条只读监控 REST 端点（`viewerAuth`，v0.40）与 `/ws/chat` 的连接鉴权都**照旧**；**新帧类型默认只发 owner/admin**（fail-closed）。见 §3 开头的「下行帧的角色门」与 v0.48 变更记录。**上一版 `v0.47`**：（**`graph_update` 子代理泳道根节点新增可选 `props.persona`**：派发子代理时若指定了目标角色，该分支根节点的 `props` 就多一个 `persona` 键，标注它**正在扮演的角色**——用途是让流程图能显示「这个子代理是以谁的身份在替班」，而不只是子代理 id；**纯增量**：不带角色派发时该键不出现，老客户端忽略未知键即可，见 §3.5 与 v0.47 变更记录）。**上一版 `v0.46`**：（**`PATCH /api/v1/sessions/{id}` 的 `personaId` 由「可重新绑定该会话的角色」改为「出现即 `400`」**：**会话角色在创建时确定、之后不可变**，要换角色请新开会话（design/22 §8-1）——**明确拒绝**而非静默忽略/200 空操作；**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request` 且消息点名 `personaId`，该检查**先于**会话存在性检查（未知会话 + `personaId` 也回 `400` 而不是 `404`）。**破坏性**：按 v0.42–v0.45 旧文实现、依赖「PATCH 换角色 / 显式 `""` 解绑」的客户端必须改为**新建会话**选角色；`title`/`pinned` 行为与 `POST /sessions {personaId}`（创建时绑定）**完全不变**，不再有 `501/200 {personaId}` 的 PATCH 路径）。上一版 `v0.45`：`PUT /admin/channels/{platform}/config` 的 `personaId` 由「省略/`""` 都 = 解绑」修订为三态（**省略（或 `null`）= 保留已存绑定**、**显式 `""` = 解绑**、**非空 id = 绑定**，未知角色仍 `400`）。 +> **契约版本 `v0.53`**（**阶段 5 落地：模型目录端点 + per-persona 路由 / 本地三级 / capacity L3 / 视觉·OCR 独立模型 / `image-crop` 工具 / 按 provider 形状下发推理开关**，依据 design/04 §3/§3.1/§3.2（裁决 03.4.1 / 03.4.2 / 03.4.3 / 08.4.1）、design/06 §0/§3（裁决 14.4.1 / 14.4.5）、design/14 §2.2/§3/§4（裁决 14.4.2 / 14.4.3 / 14.4.4），2026-10-04 落实）：① **新增管理只读端点 `GET /api/v1/admin/llm/catalog`**（**owner|admin** 读，`?refresh=1` 强制在线刷新）→ `200 {data:{source:"cache"|"models.dev", fetchedAt?, stale?, warning?, providers:[{id,name,api?,doc?,env?,npm?,models:[{id,name,attachment,reasoning,toolCall,contextLimit?,outputLimit?}]}]}}`；**既无本地快照又抓不到** → `503 {error:{code:"catalog_unavailable", message}}`；客户端带 `Accept-Encoding: gzip` 时响应带 `Content-Encoding: gzip`（**信封形状不变**）。**副作用只有一处**：落盘快照 `/llm_catalog.json`（**不含任何凭据**、`data/` 已 gitignore、TTL 24h），**不改 `models.json`**；**抓取只发生在本端点内，不进运行时热路径**（模型请求链路从不读外网目录）。详见 §2「模型配置契约（v0.53）」。② **`models.json` 组级新增键**（载体是组，**可热更新**，未声明时该键不出现）：`reasoning: {kind: "auto"|"deepseek"|"openai"|"vllm"|"dashscope"}` 决定该组用哪种**提供商开关形状**下发推理指令（**非法值被 `Group.Validate` 直接拒绝**；anthropic 组上声明 openai 系形状同样拒绝）、`personaModels: {personaId: modelId}` 与 `personaProviders: {personaId: "openai"|"anthropic"}` 为**角色级模型/提供商路由**（**非法 provider 值同样拒绝**；未绑定/未知角色回落该组默认）。③ **语义修正（重要）**：**`multimodal` = 主模型自身能否收图**；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**——两者互不代表（见 §1 行 3）。④ **`.env` 新增 9 键**（见 §2「模型配置契约（v0.53）」表与 `.env.example`）：`LLM_REASONING_KIND`（默认空 = `auto`）、`LLM_OCR_MODEL`、`LLM_LOCAL_ENABLED`（默认 `false`）/`LLM_LOCAL_PROVIDER`/`LLM_LOCAL_BASE_URL`/`LLM_LOCAL_API_KEY`/`LLM_LOCAL_MODEL`、`CAPACITY_L3_ENABLED`（默认 `false`）/`CAPACITY_L3_CACHE_TTL`（默认 `5m`）。⑤ **内置工具新增 `image-crop`**（按区域裁切图片：`x`/`y`/`width`/`height` → PNG data URI + 裁切尺寸；供大图分区精读；**策略默认 owner-only**）。⑥ **推理开关按形状下发（旧陈述修正）**：v0.41 的「Qwen 一类只 WARN、请求一字不改」**已作废**——形状由 `reasoning.kind` 声明后**真下发**（→ 字段名映射表见 changelog v0.53 条），**只有形状未知/有歧义时才 WARN 且一个字段都不发**；`reasoning_effort` 的非法值由「降级到最近一档」改为**丢弃并记 WARN（不降档）**，`effort:none` 一律翻成**显式关思考**。**未做**：DashScope 形状的 `auto` 推断（只能在显式声明 `reasoning.kind=dashscope` 时下发，绝不从模型名/BaseURL 猜）、Qwen 的 `/think` 前导消息软开关（与 design 口径冲突，未实现）。**上一版 `v0.52`**：（**工具策略落盘 + 主代理代审小字 + 流程图节点参数摘要**，依据 design/11 §3/§4/§8（裁决 1.3 / 10.4.2 / 13.4.3）与 design/19 §1/§1.1（裁决 11.4.2 / 11.4.3 / 13.4.1），2026-10-04 落实）：① **工具策略（`allowInGroup`/`allowInStranger`）落盘 SQLite `tool_policies`（迁移 `0012_tool_policy`），重启保留**——`registry.SetPolicy` **先落库后改内存**，落盘失败则内存保持旧值并返回错误（见 §2 行 5）；② 新增下行帧 **`approval_notice`**（§3.11）：敏感操作经主代理代审后推一行小字（`explain` 由**后端产出**、客户端原样渲染），审计口径 `who`=角色名 / `what`=`approval.<工具名>` / `result`=`granted|denied`，**仅 `owner` + `admin`**（fail-closed 默认）；③ `graph_update` 节点 `props` 新增四类**纯增量可选**键（tool `args_keys`/`args_summary`、guardrail `action`/`allow`/`elapsed_ms`、memory `action`/`scope`/`hits`/`bytes`/`count`/`failed`、orchestration `subagent`/`persona`），`memory`/`guardrail`/`orchestration` 旁路节点 span **首次真进图**，值在发布前已脱敏——**帧名、事件名、顶层字段集一字未动**（见 §3.5）。**上一版 `v0.51`**：（**后台子代理结果登 WS 帧 + 回填父会话**，依据 design/05 §9「子代理完成 → 结果回填主会话并提示用户」，裁决 02.4.3，2026-10-04 落实）：新增下行帧 **`subagent_result`**（`{type, sessionId, data:{sessionId, status:"done", summary, agents:[{id, goal, role?, mode?, status, summary?, text?, steps?}]}}`，见 §3.10）——`subagent_spawn` 的批次转后台后结算时，编排层发布在 bus 主题 `subagent.result` 上的合并结果，此前**没有任何消费者**（中继既非 `ws.*` 也不认该 4 段以外的 subject）⇒ 结果上不了前台、只剩进度帧；现在该 subject 被登记为中继并成形为这一帧，**帧壳 `sessionId` = 派生该批次的父会话**，结果因此落回**父会话的实时流**。**角色门**：新帧属内容帧 → **只发 `owner` + `admin`**（fail-closed 默认，未扩 7 个状态机信号白名单）。**向后兼容**：纯新增帧，老客户端按未知帧忽略即可，既有帧/端点/鉴权一律不变。**诚实边界**：结果**不落库**（父会话转录里没有新消息、重连回放不补发）、**未**经 design/15 会话消息编排器续接、**前端尚无该帧 handler**（今天的效果是「帧到达 owner/admin 连接」）。**同版另含管理面（D 组，2026-10-04 落实）**：① **`X-API-Key` 真正接线**（裁决 15.4.2）：管理/用户侧已认证端点同时接受该头，命中签发表即通过且**一律 `owner` 级**（裁决 15.4.3 取消 role 分级），带该头时只走 key 分支、未知/已吊销/空值回 `401` 且不回落 Bearer（fail-closed），WS 握手仍只认 Bearer；② **新增主人白名单档案读写** `GET`/`PUT /api/v1/admin/owner-profile`（裁决 10.4.5，**owner-only**，写带审计 `owner.profile.update`）——面板的「保存」从此是**真保存**（落盘 `configs/users/owner.yaml` 0600 原子写 + 热替换活档案，渠道 actor 判定立即生效），不再是只改本地 state 的假成功；③ **persona `identity.systemPrompt` 改必填**（裁决 08.4.2）：缺失/空白回 `400 bad_request`，**不再派生默认说明串**，写出的 YAML 必能被载入期同一规则重新载入。见下方「管理面板写操作契约」。**上一版 `v0.50`**：（**事件批：流式帧的结构化补齐**，依据 design/04 §1.1，裁决 01.4.1 / 01.4.2 / 01.4.3 / 03.4.4，2026-10-04 落实）：① **`tool_execution` 拆三事件**——旧单帧 `tool_execution.update {id,index,delta}`（phase 与工具名拼在 `delta` 字符串里）被 **`tool_execution.start`**（进入执行，`phase:"running"`）/ **`tool_execution.update`**（运行中进度/局部输出，可多帧）/ **`tool_execution.end`**（完成或失败，`phase:"done"|"error"`）替换，载荷改为结构化 `{tool, phase, id?}`（`tool` = 工具名；`phase` = 细粒度执行阶段，与 §3.5 流程图节点 status 同一套 `running/done/error` 枚举；`id` = provider 工具调用 id，可与 `tool_call.*` 帧关联）——**phase 不再塞进 `delta`**；loop 现已真实发出 start/end（update 的 wire 映射已实现并验证，但工具分发器尚无中途进度上报源，**暂无生产者**，见 §3.1）。② **`streamId`（模型流帧 `data` 内新增可选字段）**：同一次模型流（一次 ChatStream 调用）的多帧共享同一 `streamId`，多步工具轮的第二次模型调用取新 id；与帧壳的 `turnId`（整个回合恒定）分工——`turnId` 标记「这轮回答」，`streamId` 标记「这轮里的哪一条流式消息」。③ **`turn.start` / `turn.end`（新帧）**：loop 在回合边界发出、经 ws_bridge 下行；**无 `data` 载荷**（帧壳的 `sessionId`/`turnId`/`seq` 即边界信号；回合终态信息仍由既有 `stream_end` 携带）；`turn.end` 覆盖回合的所有出口（最终答案 / 工具循环安全网终止 / 预算耗尽 / 步骤出错），被静音的内部流程（backthink / 子代理）不发出。④ **向后兼容**：`turn.start/end` 与 `streamId` 为纯新增，老客户端可安全忽略；**破坏性**在旧 `tool_execution.update` 单帧——loop 不再产生它，按旧形状（解析 `delta` 里的 `phase:工具名` 拼串）消费的客户端必须迁移到三事件；现有 Web 前端未消费这些帧，行为不变。⑤ 本批新帧全部落在 v0.48 下行帧门的「仅 `owner` + `admin`」档（fail-closed 默认，无需扩白名单）。⑥ **`graph_update` 会话范围口径修正**（裁决 01.4.5，随实现事实补记）：`web` / `web:` / `sess-backthink` 三范围（见 §3.5）。见 §3.1 与 v0.50 变更记录。**上一版 `v0.49`**：（**WS 握手回放与上行帧的角色门（design/11 §7.2）**：补上 §7.1 下行门之外的**同一类缺口的另两处**，对 `viewer` **继续收紧**，`owner` / `admin` 行为不变，**无端点、无字段形状变更**——① **握手 `history` 回放改为仅 `owner` + `admin`**：此前任意角色一连上 `/ws/chat` 就会收到主会话最近 50 条消息正文（`thinking` 已剥离，但**正文本身**就是主人的对话），`viewer` 从此**不收**；② **上行 JSON 帧按角色授权（fail-closed）**：非 `owner`/`admin` 连接发来的**任何**上行 JSON 帧一律拒绝，**定向**（只回发送者）回 `{type:"error",data:{code:"forbidden"}}`，**不广播、不驱动模型、不落库、不返回任何内容**——被拒帧含 `chat`（此前 `viewer` 可**真的驱动模型并落库**）、`interrupt`、`subagent_ask` / `task_output_query`（其应答是**定向**帧、能绕过 §7.1 下行门把子代理上下文/任务输出直接回给 `viewer`）、`voice_input`、`mode_switch`，且**未登记的新上行帧默认拒**；**协议级帧（ping/pong、close）不受影响**。③ **合口径**：`viewer` = **可连接、可读 12 条只读监控 REST（v0.40）、可收 7 个状态机信号帧（v0.48）**；**除此以外 WS 上拿不到任何内容、也发不出任何指令**。见 §3 开头的「上行帧与握手回放的角色门」与 v0.49 变更记录。**上一版 `v0.48`**：（**WS 下行帧的角色门（design/11 §7.1）**：hub 的下行现在是**按帧类型分档**的——只有 7 个**状态机信号**（`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full` / `session_read`，**均不含任何内容**）继续发给**所有已认证连接**（含 `viewer`），**其余全部下行帧**（流式内容 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` / `stream_chunk` / `stream_end` / `thinking`；持久化 `message_persisted` / `message_edited` / `message_deleted` / `channel_persisted`；系统内部 `graph_update` / `subagent_event` / `task_output` / `task_done` / `tool_used` / `capacity_awaken` / `mode_switch`；私有状态 `mood` / `device_update` / `reminder`）**改为仅发 `owner` + `admin`**）。**对 `viewer` 是收紧**：此前它连上 `/ws/chat` 就能收到角色回复正文与推理内容，现在收不到；**`owner` / `admin` 行为不变**；**无端点、无字段形状变更**——`viewer` 的 12 条只读监控 REST 端点（`viewerAuth`，v0.40）与 `/ws/chat` 的连接鉴权都**照旧**；**新帧类型默认只发 owner/admin**（fail-closed）。见 §3 开头的「下行帧的角色门」与 v0.48 变更记录。**上一版 `v0.47`**：（**`graph_update` 子代理泳道根节点新增可选 `props.persona`**：派发子代理时若指定了目标角色，该分支根节点的 `props` 就多一个 `persona` 键，标注它**正在扮演的角色**——用途是让流程图能显示「这个子代理是以谁的身份在替班」，而不只是子代理 id；**纯增量**：不带角色派发时该键不出现，老客户端忽略未知键即可，见 §3.5 与 v0.47 变更记录）。**上一版 `v0.46`**：（**`PATCH /api/v1/sessions/{id}` 的 `personaId` 由「可重新绑定该会话的角色」改为「出现即 `400`」**：**会话角色在创建时确定、之后不可变**，要换角色请新开会话（design/22 §8-1）——**明确拒绝**而非静默忽略/200 空操作；**键出现**（任何取值：`"yuki"` / `""` / `null` / 未知 id / 空白串）一律 `400 bad_request` 且消息点名 `personaId`，该检查**先于**会话存在性检查（未知会话 + `personaId` 也回 `400` 而不是 `404`）。**破坏性**：按 v0.42–v0.45 旧文实现、依赖「PATCH 换角色 / 显式 `""` 解绑」的客户端必须改为**新建会话**选角色；`title`/`pinned` 行为与 `POST /sessions {personaId}`（创建时绑定）**完全不变**，不再有 `501/200 {personaId}` 的 PATCH 路径）。上一版 `v0.45`：`PUT /admin/channels/{platform}/config` 的 `personaId` 由「省略/`""` 都 = 解绑」修订为三态（**省略（或 `null`）= 保留已存绑定**、**显式 `""` = 解绑**、**非空 id = 绑定**，未知角色仍 `400`）。 ## 2. REST 端点（管理，`/api/v1/admin/*`） @@ -118,20 +118,20 @@ ### 2.0 管理侧权限矩阵（v0.40 起，与 `internal/services/gateway/routes.go` 逐条一致） -- **匿名（无 token / token 无效）**：任意 `/api/v1/admin/*` → `401 {error:{code:"unauthorized"}}`（fail-closed，全部 56 条管理路由无一例外）。 +- **匿名（无 token / token 无效）**：任意 `/api/v1/admin/*` → `401 {error:{code:"unauthorized"}}`（fail-closed，全部 **59** 条管理路由无一例外 —— 12 条 viewer 档 + 10 条 owner/admin 档 + 37 条 owner-only 档）。 - **角色分档**（`✅` 放行，`❌` 回 `403 forbidden`；owner>admin>viewer 递增）： | 端点组 | owner | admin | viewer | |------|:---:|:---:|:---:| | **只读监控档**（12 条 GET，见下①） | ✅ | ✅ | ✅ | -| **owner/admin 只读档**（9 条，见下②） | ✅ | ✅ | ❌ | +| **owner/admin 只读档**（10 条，见下②） | ✅ | ✅ | ❌ | | **owner-only 写/凭据档**（37 条，见下③） | ✅ | ❌ | ❌ | ① **`viewer` 可读的 12 条只读监控档**（`viewerAuth` = owner/admin/viewer）——模块清单 + 运行时指标/日志/通知，全部是**非敏感投影**（无凭据、无他人账号数据、无消息正文）： `GET /admin/personas`、`GET /admin/sessions`、`GET /admin/plugins`、`GET /admin/plugins/installed`、`GET /admin/channels`、`GET /admin/iot`、`GET /admin/automations`、`GET /admin/rag`、`GET /admin/observability/metrics`、`GET /admin/observability/trace`、`GET /admin/observability/logs`、`GET /admin/notifications`。 -② **仅 `owner`/`admin` 的 9 条**（`viewer` → `403`；理由：含**他人数据 / 隐私正文 / 完整导出 / 审计流水 / 全局凭据面**）： -`GET /admin/memories`（私人记忆正文）、`GET /admin/channels/messages`、`GET /admin/channels/{platform}/messages`（完整 IM 消息流/转录）、`GET /admin/llm`（provider/模型配置面）、`GET /admin/users`（账号与 API key 列表）、`GET /admin/backthink`（后台思考记录）、`GET /admin/observability/audit`（审计流水）、`GET /admin/sessions/{id}/export`（会话导出）、`POST /admin/rag/query`（知识库检索，语义上是读，但按「全局知识面」归此档）。 +② **仅 `owner`/`admin` 的 10 条**（`viewer` → `403`；理由：含**他人数据 / 隐私正文 / 完整导出 / 审计流水 / 全局凭据面**）： +`GET /admin/memories`（私人记忆正文）、`GET /admin/channels/messages`、`GET /admin/channels/{platform}/messages`（完整 IM 消息流/转录）、`GET /admin/llm`（provider/模型配置面）、`GET /admin/llm/catalog`（模型目录候选面，**v0.53 新增**）、`GET /admin/users`（账号与 API key 列表）、`GET /admin/backthink`（后台思考记录）、`GET /admin/observability/audit`（审计流水）、`GET /admin/sessions/{id}/export`（会话导出）、`POST /admin/rag/query`（知识库检索，语义上是读，但按「全局知识面」归此档）。 ③ **仅 `owner` 的 37 条**（`admin` 与 `viewer` 均 `403`）——全部写操作，外加**凭据获取路径**（`login-qr`/`login-status`，`view`/`friends`，渠道连接/测试/配置）与**主人身份档案**（决定谁能进 owner 车道，连读都不给 admin）： `GET /admin/channels/{platform}/login-qr`、`login-status`、`view`、`friends`；`POST /admin/channels/{platform}/friend/handle`、`message/test`；`PUT|DELETE /admin/channels/{platform}/config`；`POST /admin/channels/open|close|test`；`POST /admin/plugins/policy|install|uninstall`；`POST /admin/personas`、`PUT /admin/personas/{id}`；`GET|PUT /admin/owner-profile`（v0.51）；`POST /admin/users`、`POST /admin/users/apikey`、`DELETE /admin/users/apikey/{id}`；`POST /admin/iot/{id}/control`、`POST /admin/iot/scenarios`、`POST /admin/iot/rules`；`POST /admin/automations`、`POST /admin/automations/{id}/run`、`DELETE /admin/automations/{id}`；`POST /admin/llm`、`POST /admin/llm/test`；`POST /admin/memories`、`POST /admin/memories/search`；`POST /admin/rag`、`POST /admin/rag/delete`；`POST /admin/system/revoke-keys|rotate-jwt|backup|restore`。 @@ -150,7 +150,8 @@ | 6 | `/api/v1/admin/channels` | GET | ✅ | 渠道列表/健康 + 每平台已配账号（脱敏 token 掩码，design/04 §3.1）；已连接渠道的账号附 **bot 身份**（`botId`/`botUsername`/`botNickname`，如 KOOK `GET /api/v3/user/me` 自动获取）；适配器要求重新授权时附 **`needsRescan`** + **`lastError`**（v0.39，仅微信 iLink 返回 `errcode=-14`、会话被 iLink 侧拒绝这一种）；**每账号附可选 `personaId`（v0.44）**=该账号的**渠道级角色绑定**（design/22 §2 方案 b；缺省 = 未绑定，非敏感、不掩码） | | 7 | `/api/v1/admin/iot` | GET | ✅ | IoT 设备列表 | | 8 | `/api/v1/admin/users` | GET/POST | ✅(GET) | 用户/角色/API key（GET 已实现；**key 的签发/吊销已实现**——`POST`/`DELETE /admin/users/apikey`，见下方写操作契约；`POST` 创建**用户**仍 `501`） | -| 9 | `/api/v1/admin/llm` | GET/POST | ✅ | LLM 多厂商多模型（models.json）：GET 列表（APIKey 脱敏，含 `provider` 协议与 `maxTokens` 预算）；POST 保存组→落盘 `models.json`→**热更新**运行中的 LLM stack（design/04 §3.1，无需重启） | +| 9 | `/api/v1/admin/llm` | GET/POST | ✅ | LLM 多厂商多模型（models.json）：GET 列表（APIKey 脱敏，含 `provider` 协议与 `maxTokens` 预算）；POST 保存组→落盘 `models.json`→**热更新**运行中的 LLM stack（design/04 §3.1，无需重启）。**v0.53**：组级新增 `reasoning` / `personaModels` / `personaProviders` 三键（见下方「模型配置契约（v0.53）」） | +| 9a | `/api/v1/admin/llm/catalog` | GET | ✅ | **模型目录候选**（owner/admin 读，v0.53；`?refresh=1` 强制在线刷新）——面板「添加提供商 / 添加模型」的 baseURL / 模型清单 / 能力位来源，服务端快照 + 离线兜底；失败 `503 catalog_unavailable`。见下方「模型配置契约（v0.53）」 | | 10 | `/api/v1/admin/automations` | GET/POST | ✅(GET) | 自动化与提醒（GET 已实现；POST 创建 M10） | | 11 | `/api/v1/admin/backthink` | GET | ✅ | 后台思考记录 | | 12 | `/api/v1/admin/rag` | GET | ✅ | 知识库文档列表（分块/嵌入状态）；带 `?query=` 时并入检索结果 | @@ -170,6 +171,47 @@ > **M10 前端契约补充（管理面板）**：`GET /api/v1/admin/users` · `GET /api/v1/admin/llm` · `GET /api/v1/admin/automations` · `GET /api/v1/admin/backthink` · `GET /api/v1/admin/rag` · `POST /api/v1/admin/rag/query` · `GET /api/v1/admin/observability/metrics` · `GET /api/v1/admin/observability/trace` · `GET /api/v1/admin/observability/audit` · `GET /api/v1/admin/observability/logs` · `GET /api/v1/admin/notifications` 已实现，返回真实数据（**日志 tail 见下方「可观测性契约」**；未注册 `GET /api/v1/admin/logs`）。**写操作已补齐**（见下方「管理面板写操作契约」）：人格/API key/设备控制/自动化/LLM 测试/渠道连接与识别测试/记忆检索/会话导出/插件卸载**真实持久化或真实生效**；**系统设置安全与存储类**（吊销 API key / 轮换 JWT 密钥 / 备份 / 恢复）也已**真实实现**（见下方「系统设置契约」）；**主人档案保存（v0.51）同样已实现**——`GET`/`PUT /api/v1/admin/owner-profile` 真实落盘 + 热替换活档案，面板的「保存」不再是假成功；仍为后置 M10：**新增用户**、**IoT 场景与规则**、**编辑环境变量/重启服务/检查更新**——后端如实返回 `501 not_implemented`，不伪造成功。（**知识库删除已实现**：`POST /admin/rag/delete` 真实删除，见下方写操作契约；**插件安装已实现**：v1 为 MCP server 热安装。） +**模型配置契约（v0.53）**（依据 design/04 §3/§3.1/§3.2（裁决 03.4.1 / 03.4.2 / 03.4.3 / 08.4.1）与 design/06 §0/§3（裁决 14.4.1 / 14.4.5）；判定与校验以 `internal/config/runtimeconfig` + `internal/services/gateway/admin_llm*.go` 为准）： + +- **`GET /api/v1/admin/llm/catalog`（owner|admin 读，v0.53）** → `200 {data:{...}}`： + - **请求**：`?refresh=1` = 强制在线刷新；不带时，本地快照仍在 **24h TTL** 内就直接用它（不每次打开面板都打外网）。 + - **响应 `data`**：`{source:"cache"|"models.dev", fetchedAt?, stale?, warning?, providers:[{id,name,api?,doc?,env?,npm?,models:[{id,name,attachment,reasoning,toolCall,contextLimit?,outputLimit?}]}]}` + - `source` 说明这份候选从哪来（`models.dev` = 本次在线抓取，`cache` = 本地快照）；`fetchedAt` 为快照抓取时间（RFC3339，无快照时省略）；**`stale:true` + `warning` 只在「在线刷新失败、返回上次快照」时出现**（离线兜底，**绝不编造候选**）。 + - `api` = 该供应商 baseURL（目录未标注时省略，面板提示需手填）；`doc` = 文档地址、`env` = 目录标注的官方 key 环境变量名（仅提示，面板不写 `.env`）、`npm` = SDK 包名。 + - 每个模型：`attachment`（接受图片/文件输入 → 面板预填 `multimodal`）、`reasoning`、`toolCall`、`contextLimit?`/`outputLimit?`（目录未标注时为 `0` 而省略；`outputLimit` 直接作 `maxTokens` 建议值）。 + - 供应商与模型都**按 id 排序**（输出确定、便于前端 diff）；**没有模型清单的供应商不进列表**（避免噪声行）。 + - **失败**：**既无本地快照又抓不到** → `503 {error:{code:"catalog_unavailable", message}}`（message 给出「可改用粘贴导入」的指引）；**有快照但刷新失败** → **仍 `200`**（`source:"cache"` + `stale:true` + `warning`）；快照文件损坏/为空只记 WARN 并按「无快照」继续在线抓取，**不影响本次回答**。 + - **压缩**：客户端带 `Accept-Encoding: gzip` 时响应带 **`Content-Encoding: gzip`**（目录约 1MB 量级）；**信封 `{data}` 形状不变**，浏览器与 Go 客户端透明解压；不带该头时返回明文并带 `Content-Length`。 + - **副作用（只有这一处）**：落盘快照 `/llm_catalog.json`（与 `models.json` 同目录、`data/` 已 gitignore、**不含任何凭据**、TTL 24h）；**不修改 `models.json`**。LLM stack 未注入时快照落到系统临时目录，**绝不往工作树写文件**。 + - **抓取只发生在本端点内**（数据源 `https://models.dev/api.json`，单次超时 20s、体积上限 64MiB）：**不进运行时热路径**——模型请求链路从不读这份外网目录。 + - **审计**：成功记 `llm.catalog` / `ok`，返回过期快照记 `stale`，失败记 `error`（可用 `GET /admin/observability/audit` 查）。 +- **`models.json` 组级新键（v0.53，可热更新；`GET`/`POST /api/v1/admin/llm` 已同步这三个键的读与写）**： + - **`reasoning: {kind}`**：`kind` ∈ `"auto"`（= 缺省）/`"deepseek"`/`"openai"`/`"vllm"`/`"dashscope"`，决定该组用哪种**提供商开关形状**下发推理指令（vLLM → `chat_template_kwargs.enable_thinking`；DashScope → 顶层 `enable_thinking`；DeepSeek → 顶层 `thinking:{type}` + `reasoning_effort`；OpenAI 系 → 只有 `reasoning_effort`；`auto` = 按模型名/baseURL 推断厂商，**形状有歧义就不下发任何字段**）。 + - **校验**：不在上列取值 → 组校验失败（`POST /admin/llm` 回 `400 bad_request`）；**anthropic 组上声明 `deepseek`/`openai`/`vllm`/`dashscope` 同样拒绝**（Anthropic 用自己的 `thinking` 形状）。 + - **请求语义**：`reasoning` 键**缺失 = 保留已存形状**；给出（哪怕 `{}`）= 整块替换（`kind` 缺失/空串 = 回到「未声明」）。 + - **响应语义**：每组的 `reasoning` **恒下发**（`kind:""` = 未声明形状，不是「后端没报告」）；顶层另下发 **`reasoningKinds`**（合法形状取值域，**不含空串**——`""` 是「不声明形状」而非一个形状名，面板另行给出该选项）与 **`personaProviderOptions`**（合法协议名域，即 `openai`/`anthropic`）供面板渲染下拉框——取值域由后端常量直接生成，**面板无需硬编码**。 + - **`personaModels: {personaId: modelId}`** = **角色级模型路由**（「角色」= 该回合答话的 persona，**不是**消息作者的 role）；**`personaProviders: {personaId: "openai"|"anthropic"}`** = **角色级协议路由**（跨协议换 adapter，配合 `personaModels` 使用）。 + - **校验**：persona id / 值不得为空，`personaProviders` 的值必须是 `openai` 或 `anthropic`，否则组校验失败（`400`）；键值首尾空白会被规整，**规整后撞键直接报错**（不静默丢一条）。 + - **回落**：未绑定 / 绑定到未知 persona → 该组默认模型；`personaProviders` 声明的协议在 `models.json` 里**没有对应组** → 记 WARN 并**跳过**（该角色仍走默认链，**不半建一条只会失败的链**）。 + - **请求语义**：两个键**缺失 = 保留已存表**；给出（含 `{}`）= **整表替换**（用整表替换而非合并，面板才能删除一条已存路由）；未声明时响应中该键不出现（`omitempty`）。 + - **语义修正（重要）**：`multimodal` = **主模型自身能否收图**（**不是**「本部署有没有视觉能力」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**，与 `multimodal` 互不代表（裁决 14.4.1，见 §1 行 3）。 +- **`.env` 新增 9 键（v0.53；`.env` 是 `models.json` 的兜底，对齐 `.env.example`）**： + + | 键 | 默认 | 语义 | + |---|---|---| + | `LLM_REASONING_KIND` | 空（= `auto`） | **仅供 `.env` 合成组**的推理开关形状声明（**无有效 `models.json` 时**才生效，取值同 `reasoning.kind`；有 `models.json` 时以该组的 `reasoning.kind` 为准） | + | `LLM_OCR_MODEL` | 空 | **OCR 工具**用的模型；空 = 复用 `LLM_VISION_MODEL`，两者都空 = 复用主模型（`LLM_MODEL`） | + | `LLM_LOCAL_ENABLED` | `false` | 降级链**第三级（本地模型）**总开关；默认关，链保持「主 → 备」两级 | + | `LLM_LOCAL_PROVIDER` | `openai` | 本地端点协议（`openai`/`anthropic`） | + | `LLM_LOCAL_BASE_URL` | 空 | 本地端点 base URL（如 `http://127.0.0.1:8080/v1`） | + | `LLM_LOCAL_API_KEY` | 空 | 本地端点 key（本地服务通常为空） | + | `LLM_LOCAL_MODEL` | 空 | 本地模型名 | + | `CAPACITY_L3_ENABLED` | `false` | capacity 意图判定的 **L3（模型辅助分类）**开关；默认关，只走 L1/L2 启发式 | + | `CAPACITY_L3_CACHE_TTL` | `5m` | L3 意图判定结果缓存 TTL | + + - `LLM_LOCAL_*` **三个条件缺一不可**：`LLM_LOCAL_ENABLED=true` **且** `LLM_LOCAL_BASE_URL` 非空 **且** `LLM_LOCAL_MODEL` 非空；只开开关而不配端点/模型时**记 WARN 并跳过该级**（绝不半配一个只会失败的链尾步）。 +- **内置工具新增 `image-crop`（v0.53）**：按区域裁切图片（参数 `image` + `x`/`y`/`width`/`height`，**0 基像素、区域须完整落在图内**）→ 返回 `{image:"data:image/png;base64,…", format:"image/png", width, height, region:{x,y,width,height}, source:{width,height}}`；用途是**上游可能压缩分辨率、大图细节会丢**，让模型自行裁出区域再交给 vision/OCR 工具精读（design/06 §3，裁决 14.4.5）。上限：源图 ≤50MiB、区域 ≤16MP、返回载荷 ≤8MiB（超出**报错**而非截断/降采样）；源可以是本地路径（走 file 工具同一沙箱）/ http(s) URL（同 SSRF 守卫）/ base64 data URI。**策略与其它工具一致**：`tool_policies` 无行时按最严默认 **owner-only**（群聊/陌生人的调用被策略层拒，见 §2 行 5）。 + **管理面板写操作契约**（`POST/PUT/DELETE /api/v1/admin/*`，均 **owner-only**，读为 owner/admin；写操作经 audit 落 `audit_logs`；成功 `{data}` / 失败 `{error:{code,message}}`）： - `POST /admin/personas` body `{id,name,role,systemPrompt,characterRef?,modes?/mode?,memoryNamespace?,thinking?}` → `201 {data:PersonaSummary}`（**v0.43 起与读端点同形状：含 `mood` + `thinking?`**；注册进 persona registry + 持久化到 `configs/personas/.yaml`）；id 已存在回 `409 duplicate`。**`systemPrompt` 自 v0.51 起必填**（落的 YAML 键是 `identity.systemPrompt`）：**缺失/空白 → `400 bad_request`**（消息 `"systemPrompt is required (identity.systemPrompt must not be empty)"`），**不再派生默认说明串**回落——载入期（`loader.Load`）执行同一规则，因此写出的 YAML 必能被重新载入。 - `PUT /admin/personas/{id}` body 同上（不含 id）→ `200 {data:PersonaSummary}`（**v0.43 起与读端点同形状：含 `mood` + `thinking?`**，面板可直接用它回填）；不存在回 `404`。**`systemPrompt` 与创建同一把门**：v0.51 起同样必填，缺失/空白回 `400 bad_request`（同一条消息）——**不派生默认串、也不静默沿用旧值**，请求被拒即不落盘。 @@ -178,7 +220,7 @@ - **未配置的人格：`thinking` 键完全不出现**（不是全零对象）——与写侧「省略 `thinking` 对象 = 保留已存」互为镜像，客户端可有样学样地「原样回填 / 原样省略」。 - 已配置时 **四个键都出现**：`budgetTokens`（number，未设为 `0`）、`effort`（string，未设为 `""`）、`showToUser`、`mode`（string，未设为 `""`）。 - **`showToUser` 是三态、且读侧如实三态**：**`null` = 未配置（保持现行为：thinking 帧照常推客户端）**；`true`/`false` = 显式选择（`false` = 只落库不回显）。**服务端不会把 `null` 拍平成 `false`**（写侧用的是 `*bool`，读侧同样保留指针语义），否则「没配过」会被面板误显示成「关」。 - - **能力提示由服务端负责，客户端不要假装**：`effort` 的**有效白名单随当前生效 provider** 而定（OpenAI 兼容系 `none/minimal/low/medium/high/xhigh/max`；DeepSeek 仅 `none/low/high/max`，别名 `minimal→low`/`medium→high`/`xhigh→high`/`ultra→max`；未知 provider 不支持）。**服务端在模型层按 provider 校验，非法/不被支持时降级并记 WARN**（design/04 §3.2）；读端点只回读**已存配置**，**不承诺**该值在上游真的生效。面板可给出提示与前端枚举校验，但**不得**把「配了 effort」呈现为「上游已启用」。 + - **能力提示由服务端负责，客户端不要假装**：`effort` 的**有效白名单随当前生效 provider** 而定（OpenAI 兼容系 `none/minimal/low/medium/high/xhigh/max`；DeepSeek 仅 `none/low/high/max`，别名 `minimal→low`/`medium→high`/`xhigh→high`/`ultra→max`；未知 provider 不支持）。**服务端在模型层按 provider / 形状校验，非法或该形状不支持的字段一律丢弃并记 WARN（不降档、也不静默无效）**（design/04 §3.2 / v0.53）；读端点只回读**已存配置**，**不承诺**该值在上游真的生效。面板可给出提示与前端枚举校验，但**不得**把「配了 effort」呈现为「上游已启用」。 - `POST /admin/users` → `501 not_implemented`（**无用户表**：登录仅用 `.env` 单 admin `ADMIN_USERNAME`/`ADMIN_PASSWORD`，角色为 `owner>admin>viewer` 常量；多用户存储 + 登录接入需先设计——design/11 单用户为主。不做「建了却登不进」的假用户）。 - `POST /admin/users/apikey`（**无请求体**，v0.51 取消 role 分级）→ `201 {data:{id:<掩码>, key:<明文·仅此一次>, role:"owner"}}`；`key` **仅此响应出现一次**，任何有效 key 鉴权后即 `owner`（裁决 15.4.3：key 不做角色分档；旧的 `{"role":…}` 请求体被忽略，表里也没有角色维度）。 - `DELETE /admin/users/apikey/{id}`（`id`=列表掩码）→ `200 {data:{id,revoked:true}}`；未命中 `404`。 @@ -189,7 +231,7 @@ - `POST /admin/automations` body `{name,kind:"cron|event",expression}` → `201 {data:{id,name,kind}}`（真实注册规则）；无效 cron/规则回 `400 invalid_cron|invalid_rule`。 - `POST /admin/automations/{id}/run` → `200 {data:{id,output}}`（手动触发）；`404`。 - `DELETE /admin/automations/{id}` → `200 {data:{id,deleted:true}}`；`404`。 -- `POST /admin/llm` body `{id?,provider?,baseUrl,apiKey?,model,multimodal?,fallback?,maxTokens?}` → `201 {data:{provider:{id,name,provider,baseUrl,model,multimodal,enabled,fallback?,maxTokens?}, persisted:true, path}}`。**真实持久化**：读-改-写 `models.json`（本地、gitignore），保存组提升为**生效组**（index 0），并**热更新**运行中的 LLM provider（`path` 为落盘文件路径）；API key 写入文件但**永不回显/不落日志**。`provider` 为空默认 `openai`；缺 `baseUrl`/`model` 回 `400`；`maxTokens` 为负回 `400`；未注入 LLM stack 回 `500 llm_unavailable`、写盘失败 `500 llm_persist_failed`、热重载失败 `500 llm_reload_failed`。`maxTokens` 缺省/`0` = 未设（回落 `LLM_FALLBACK_MAX_TOKENS` / 适配器默认）。`.env` 为兜底。 +- `POST /admin/llm` body `{id?,provider?,baseUrl,apiKey?,model,multimodal?,fallback?,maxTokens?,reasoning?,personaModels?,personaProviders?}` → `201 {data:{provider:{id,name,provider,baseUrl,model,multimodal,enabled,fallback?,maxTokens?,reasoning,personaModels?,personaProviders?}, persisted:true, path}}`。**真实持久化**：读-改-写 `models.json`（本地、gitignore），保存组提升为**生效组**（index 0），并**热更新**运行中的 LLM provider（`path` 为落盘文件路径）；API key 写入文件但**永不回显/不落日志**。`provider` 为空默认 `openai`；缺 `baseUrl`/`model` 回 `400`；`maxTokens` 为负回 `400`；未注入 LLM stack 回 `500 llm_unavailable`、写盘失败 `500 llm_persist_failed`、热重载失败 `500 llm_reload_failed`。`maxTokens` 缺省/`0` = 未设（回落 `LLM_FALLBACK_MAX_TOKENS` / 适配器默认）。`.env` 为兜底。**v0.53 新增三键**（`reasoning.kind` / `personaModels` / `personaProviders`，语义与校验见上方「模型配置契约（v0.53）」）：三者**缺省 = 保留已存值**，给出则 `reasoning` 整块替换、两张 persona 表**整表替换**；非法 `kind` / 非法协议名 / 未知 anthropic 形状 → `400 bad_request`。 - `POST /admin/llm/test` body `{provider?,baseUrl,model,apiKey?,prompt?}` → `200 {data:{ok,provider,model,reply,tokens}}`（**真实模型调用**）；无效/失败回 `400 invalid_provider` / `500 llm_test_failed`。API key 仅本次请求内使用，不落库、不进 wire。 - `POST /admin/channels/open`、`POST /admin/channels/close` body `{name}` → `200 {data:{name,connected}}`（真实 Connect/Disconnect）；`404`（未注册渠道）/`409 session_rejected`（微信 iLink 侧拒绝/作废了该会话，重连无法修复，须先「扫码登录」重新绑定，v0.39）/`409 needs_login`（微信 iLink 尚无 token）/`500`（其它凭据缺失等连接失败）。 - `POST /admin/channels/test` body `{platform?,accountId,isGroup}` → `200 {data:{role,owner,isGroup,env,verdict}}`。**结构性判定**：channel 层 actor 元数据 × `configs/users/owner.yaml` 白名单，绝不靠提示词。 @@ -415,6 +457,19 @@ - 语音：上行 `voice_input`（base64 音频或已转写 text），下行 `voice_output`（合成音频 base64 + text）。 ## 5. 变更记录 +- `v0.53`（**阶段 5 落地：模型目录端点 + per-persona 路由 / 本地三级 / capacity L3 / 视觉·OCR 独立模型 / `image-crop` 工具 / 按 provider 形状下发推理开关**，依据 design/04 §3/§3.1/§3.2（裁决 03.4.1 / 03.4.2 / 03.4.3 / 08.4.1）、design/06 §0/§3（裁决 14.4.1 / 14.4.5）、design/14 §2.2/§3/§4（裁决 14.4.2 / 14.4.3 / 14.4.4），2026-10-04 落实）：① **新增管理只读端点 `GET /api/v1/admin/llm/catalog`（owner|admin）**——面板「添加提供商 / 添加模型」的候选目录（baseURL / 模型 id / 能力位 / 输出上限），数据源 `https://models.dev/api.json`；`?refresh=1` 强制在线刷新，否则 24h TTL 内的本地快照直接复用。`200 {data:{source:"cache"|"models.dev", fetchedAt?, stale?, warning?, providers:[{id,name,api?,doc?,env?,npm?,models:[{id,name,attachment,reasoning,toolCall,contextLimit?,outputLimit?}]}]}}`；**既无快照又抓不到** → `503 {error:{code:"catalog_unavailable"}}`；**有快照但刷新失败** → 仍 `200` + `stale:true` + `warning`（离线兜底，不编造候选）；带 `Accept-Encoding: gzip` 时响应带 `Content-Encoding: gzip`（信封形状不变）。**副作用只有一处**：落盘快照 `/llm_catalog.json`（**无凭据**、`data/` 已 gitignore、TTL 24h），**不改 `models.json`**；**抓取只发生在本端点内，不进运行时热路径**。审计动作 `llm.catalog`（`ok`/`stale`/`error`）。详见 §2「模型配置契约（v0.53）」。② **`models.json` 组级新增三键**（可热更新，`GET`/`POST /api/v1/admin/llm` 已同步读写；**未声明时该键不出现**）：`reasoning: {kind}` 声明该组的推理开关**形状**；`personaModels: {personaId: modelId}` 与 `personaProviders: {personaId: "openai"|"anthropic"}` 是**角色级模型/协议路由**（「角色」= 该回合答话的 persona，不是消息作者 role）。**校验在 `Group.Validate`**：非法 `kind`（只认 `auto`/`deepseek`/`openai`/`vllm`/`dashscope`）、anthropic 组上声明 openai 系形状、`personaProviders` 的非法协议名、空 persona id/空值 → **写端点回 `400 bad_request` 且不落盘**；persona 表键值会 trim，**trim 后撞键直接报错**（不静默丢条目）。**请求语义**：三键缺省 = 保留已存值（`reasoning` 整块给出即整块替换，persona 表给出即**整表替换**——否则面板无法删除一条已存路由）；**响应语义**：每组的 `reasoning` **恒下发**（`kind:""` = 未声明形状，不是「后端没报告」），`personaModels`/`personaProviders` 为空则省略；顶层新增 **`reasoningKinds`** 与 **`personaProviderOptions`** 两个取值域数组（由后端常量直接生成，面板无需硬编码枚举）。**回落**：未绑定/未知 persona → 该组默认模型；`personaProviders` 声明的协议在 `models.json` 里没有对应组 → 记 WARN 并跳过（该角色仍走默认链，**不半建一条只会失败的链**）。③ **语义修正（重要，此前文档写反了）**：**`multimodal` = 主模型自身能否收图**（不是「本部署有没有视觉能力」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**（OCR 空则复用视觉模型，两者都空则复用主模型），与 `multimodal` **互不代表**（裁决 14.4.1）。④ **`.env` 新增 9 键**：`LLM_REASONING_KIND`（默认空 = `auto`；**只在无有效 `models.json`（走 env 合成组）时生效**，有 `models.json` 时以该组 `reasoning.kind` 为准）、`LLM_OCR_MODEL`、`LLM_LOCAL_ENABLED`（默认 `false`）/`LLM_LOCAL_PROVIDER`（默认 `openai`）/`LLM_LOCAL_BASE_URL`/`LLM_LOCAL_API_KEY`/`LLM_LOCAL_MODEL`（本地第三级：`Enabled` + `BaseURL` + `Model` 三者齐备才成为链尾一步，只开开关则 WARN 并跳过）、`CAPACITY_L3_ENABLED`（默认 `false`）/`CAPACITY_L3_CACHE_TTL`（默认 `5m`）。⑤ **内置工具新增 `image-crop`**：按区域裁切图片（`image` + `x`/`y`/`width`/`height`，0 基像素、区域须完整落在图内）→ PNG data URI + 裁切尺寸 + 源图尺寸；供**大图被上游压缩后分区精读**（design/06 §3）。上限：源图 ≤50MiB、区域 ≤16MP、载荷 ≤8MiB（超出**报错**，不截断）；源可为本地路径（file 工具同一沙箱）/ http(s) URL（同 SSRF 守卫）/ base64 data URI。**策略默认 owner-only**（`tool_policies` 无行时 fail-closed）。⑥ **推理开关按 provider 形状下发（替换 v0.41 的「只 WARN 不发」）**——形状由 `reasoning.kind` 声明（未声明 = `auto`：按模型名/baseURL 推断厂商，**形状有歧义就不下发**），字段名映射表： + + | 形状 `kind` | 线上字段 | 说明 | + |---|---|---| + | `deepseek` | 顶层 `thinking:{type:"enabled"\|"disabled"}` + `reasoning_effort` | 思考**默认开**，「不传」≠「关」：要关必须显式 `disabled` 或 `effort:"none"`；`none` 胜过 `enable:true`（关思考优先）；`budget_tokens` 在该协议上无对应字段，记 WARN 丢弃 | + | `openai` | 仅 `reasoning_effort` | 该系没有布尔思考开关；`thinking.enable` 记 WARN 丢弃（官方关推理路径 = `effort:"none"`） | + | `vllm` | 顶层 `chat_template_kwargs.enable_thinking` | 只有布尔开关，无 `reasoning_effort`；**`effort:"none"` 一律翻译成显式关思考**（不得降成任何强度档） | + | `dashscope` | 顶层 `enable_thinking` | 同上；**只在显式声明该形状时下发**，绝不从模型名/BaseURL 推断 | + | `auto`/未声明 | 无 | `deepseek`/`openai` 可推断时按其形状下发；**形状有歧义（如 Qwen 可能由 vLLM 或 DashScope 承载）或厂商未知 → 一个字段都不发**，逐项 WARN 并给出配置指引 | + + - `reasoning_effort` 校验：按**厂商白名单**（OpenAI 系 `none/minimal/low/medium/high/xhigh/max`；DeepSeek `none/low/high/max`）——非法值**丢弃并记 WARN，不再「降级到最近一档」**（降档会反转调用方意图）；DeepSeek 的别名 `minimal→low`/`medium→high`/`xhigh→high`/`ultra→max` 归一化后发送并记一条 WARN。Anthropic 组继续走自己的 `thinking:{type,budget_tokens}`（`reasoning.kind` 在其上被拒）。 + - 同批另含两条**对客户端无端点/帧/字段变更**的实现：**persona `awakening` 档位真生效**（`configs/personas/*.yaml` 的 `awakening` 块归一化为 `quiet|awake|full` 并进 capacity 决策；非法档位/越界阈值载入期报错、块缺席 = 无覆盖继续走全局默认，design/14 §3）、**工具越出本轮允许集的软判并回**（越界调用**仍然执行**——能力≠边界；结果里带 `not_allowed` 提示回灌模型，并记审计 `tool.reject.not_allowed`，design/14 §4）。`capacity_awaken` / `approval_notice` 等既有帧形状**一字未动**。 + ⑦ **向后兼容**：新端点、新组键、新 `.env` 键、新工具都是**纯增量**；既有端点 / WS 帧 / 字段形状**无破坏性变更**（`GET /admin/llm` 只多出 `reasoning`/`personaModels`/`personaProviders`/`reasoningKinds`/`personaProviderOptions` 这些新键，消费旧键的客户端不受影响）。**未做（诚实边界）**：DashScope 形状的 `auto` 推断（需显式声明 `reasoning.kind=dashscope`）、Qwen 的 `/think` 前导消息软开关（与 design 口径冲突，本批未实现）。⑧ **实现落点**：目录 `internal/services/gateway/admin_llm_catalog{,_cache,_source}.go` + 路由 `routes.go`；组键与读侧 `internal/config/runtimeconfig/models.go`（`ReasoningOptions`/`PersonaModels`/`PersonaProviders`/`Validate`）、写读端点 `internal/services/gateway/admin_llm_provider.go` + `admin_write_llm_channels.go` + `admin.go`/`admin_query.go`；形状下发 `internal/runtime/model/reasoning_shape.go`（+ `reasoning.go` 的厂商白名单/别名、`openai_encode.go` 的线上字段）；per-persona 路由 `internal/runtime/model/{router,persona_stack,runtime}.go`；本地第三级 `internal/runtime/model/factory.go`（`localChainStep`）+ `internal/config/config.go`；capacity L3 `internal/runtime/capacity/{capacity,classifier,l3}.go`；awakening `internal/persona/loader/awakening.go`；软判 `internal/runtime/tool/allowset.go` + `internal/runtime/loop/tool_policy.go`；工具 `plugins/tools/io/crop.go`。对应提交：`63e5b70`（目录端点）、`fa33c79`（per-persona 路由 / 本地三级 / L3 / OCR 独立模型 / image-crop）、`38b4527`（工具软判）、`71fefe5`（persona awakening）、`8890c30`（按形状下发推理开关 + per-persona 提供商链）。 - `v0.52`（**阶段 4 三组落地：工具策略落盘 + 主代理代审小字 + 流程图节点参数摘要**，依据 design/11 §3/§4/§8（裁决 1.3 / 10.4.2 / 13.4.3）与 design/19 §1/§1.1（裁决 11.4.2 / 11.4.3 / 13.4.1），2026-10-04 落实）：① **工具策略落盘**：`allowInGroup` / `allowInStranger` 的载体改为 SQLite 表 **`tool_policies`**（迁移 `0012_tool_policy`，唯一索引 `idx_tool_policies_name` 承载 upsert 冲突目标），`POST /api/v1/admin/plugins/policy` 从此**重启保留**——不再是「面板保存成功、一重启就复位」的假持久化（见 §2 行 5）。**写入路径先落库、后改内存**（`registry.SetPolicy` → 落盘成功才改内存并记入快照）：**落盘失败则内存保持旧值并返回错误**，不会出现「面板说成功、内存已改、库里没有」的分叉；启动时 `AttachPolicyStore` 立即 Load 全量策略套到**已注册**能力上，此后 `Register` 进来的能力（MCP 热装、插件刷新）同样套上落盘值；**没有行的能力按默认（两布尔均 false = owner-only）处理**（fail-closed）。策略存储不可用/加载失败时**保持最严默认并记 WARN**，不静默降级成内存态、也不假装读出了策略。**对客户端无端点、无字段形状变更**。② **新增下行帧 `approval_notice`**（§3.11，design/11 §4）：loop 的工具准入门（`ToolLoopHooks.CallAdmit`）判定某次调用属敏感操作（执行命令 / 修改文件 / 网络**写**方法）→ 经主代理代审后广播 `{type:"approval_notice", sessionId, data:{actor, tool, op, detail, explain, allowed, at}}`；`explain` 是**后端产出的固定文案**「 想要干什么，我审查后批准了」/「…我审查后拒绝了」（客户端**原样渲染**，不要自拼），`detail` 为动作摘要（工具 + 关键参数，目标部分截断到 80 rune），`allowed=false` 表示该敏感调用**被拦截未执行**（无代审者 / 代审报错同样 fail-closed 拦截，小字同为「拒绝了」）。**非敏感调用不产生该帧**；**子代理的敏感调用归属到派生它的父会话**（与 §3.10 同口径），小字因此落在主人正在看的那个会话里，而不是一个没人看的子代理 id 下。**审计**：每次代审在 `audit_logs` 落一行（批准与拒绝**各一行**）——`who`=角色名、`what`=`approval.<工具名>`、`result`=`granted|denied`，查询走既有 `GET /api/v1/admin/observability/audit` 与 `GET /api/v1/admin/notifications`。**角色门**：内容帧 → **仅 `owner` + `admin`**（fail-closed 默认，未扩那 7 个状态机信号白名单）。**前端已渲染**（`frontend/web/src/lib/ws/handlers/approval.ts` + `frontend/web/src/components/status.tsx` 的 `ApprovalNoticeHint`）：按同一会话过滤规则把 `explain` 作为聊天流里的一行小字、`detail` 作副文本。**向后兼容**：纯新增帧，不改既有帧 / 端点 / 鉴权，老客户端按未知帧忽略即可。③ **`graph_update` 节点 `props` 新增四类可选键**（裁决 11.4.2 / 11.4.3，见 §3.5）：**旁路节点的 span 首次真进图**——`memory.recall` / `memory.write` / `guardrail.input` / `guardrail.output` / `orchestration.spawn` 现在都由**真实生产者**产生，`kind` 因此会实际出现 `memory` / `guardrail` / `orchestration`；tool 节点另带 `args_keys`（该次调用的**全部参数名**）与 `args_summary`（**仅放行表内、且非密钥类**的键才给值，**密钥类键连值都不给**，单值 ≤**80 rune**、最多 **24** 条）；旁路节点只带元数据（`action` / `scope` / `hits` / `bytes` / `count` / `failed` / `allow` / `subagent` / `elapsed_ms`），**不含记忆正文、不含提示词、不含密钥**。值在**发布前已脱敏**（凭据形状 → `[redacted]`、长文本截断），前端对未放行的键显示「值未展示」。**帧名、事件名、顶层字段集一字未动**——以上只是节点 `props` 内的**纯增量可选键**。④ **本版未做 / 诚实边界**：**代审是「记录并批准」**——「敏感与否」与「是否放行」仍由上层策略层判定，`orchestration/audit.Approver` 只做校验、记录、叙述并返回结果模型，**不构成新的权限边界**（身份/权限判定始终来自 channel 层 `actor` 元数据 + 白名单 + 策略引擎）；**`agent.RunStep`（静音 / 非流式内部流程，如 backthink）的输出侧护栏仍同步内联**（其裁决是 `StepResult` 的一部分、不落在主会话关键路径上），只有**主会话流式关键路径**的输出侧护栏改为**后台异步**（`loop.checkOutputAsync`，裁决 13.4.1：真并发、不阻塞回合，拦截仍写审计留痕；**输入侧前置门依旧同步拦下**）。⑤ **实现落点**：策略落盘 `internal/capability/registry/policy_store.go` + `registry.go` 的 `SetPolicy`、迁移 `internal/db/migrations/0012_tool_policy.{up,down}.sql`；代审 `internal/capability/restrict/{sensitive,approve}.go` + `internal/runtime/orchestration/audit/approval.go` + `internal/services/gateway/admin_approval.go` + 组合根 `cmd/cyrene/wire_runtime.go` 的 `toolAdmissionHooks`；流程图 `internal/runtime/loop/{spanlog,memory,stream}.go` + `internal/runtime/agent/step.go` + `internal/runtime/orchestration/scheduler_spans.go` + `internal/runtime/trace/{graph_props,graph_build,redact}.go`。 - `v0.51`（**后台子代理结果登 WS 帧 + 回填父会话**：新增下行帧 `subagent_result`；依据 design/05 §9「子代理完成 → 结果回填主会话并提示用户」，裁决 02.4.3，2026-10-04 落实）：① **问题**：`subagent_spawn` 的批次前台只等 2 秒（design/04 §8.5），转后台后结算时编排层已把合并结果发布到 bus 主题 `subagent.result`，但 gateway 的中继**不认这个 subject**（既非 `ws.*`，也不是已登记的 4 段广播形态 `cyrene.agent.*.event`）⇒ 结果**永远到不了前台**，前端唯一可见的是逐代理进度帧 `subagent_event`（「跑起来了/跑完了」，但**拿不到结论**）。② **新增帧 `subagent_result`**：`{type:"subagent_result", sessionId, data:{sessionId, status:"done", summary, agents:[{id, goal, role?, mode?, status, summary?, text?, steps?}]}}`——`data` 与派发工具返回给模型的结果**同形同值**（同一处投影、同一处 4000 字截断，`text` 即子代理的结论正文）；**帧壳 `sessionId` = 派生该批次的父会话**，客户端据此把结果归到**那个会话**的实时流（多会话并发不串话），而不是当成一张全局帧。详见 §3.10。③ **回填边界（诚实说明）**：本版把「结果可见」做到了**会话作用域的实时帧**——结果现在真的到达父会话的 WS 流（此前被中继静默丢弃）。**未做**：不落库（父会话的持久化转录里**没有**新增一条消息，重连/回放不会补发它），也**未**经 design/15 的会话消息编排器排队续接；**现有 Web 前端也没有该帧的 handler**（按未知帧忽略，故今天的可见效果是「帧到达 owner/admin 连接」而非「聊天气泡里出现结果」）。REST/历史接口**逐条不变**：`GET /sessions/{id}/messages` 不会多出这条结果。④ **角色门（fail-closed）**：新帧属**内容帧** → **只发 `owner` + `admin`**，`viewer` 收不到；**未**扩那 7 个状态机信号白名单（design/11 §7.1，白名单要进须先在设计登记「不含内容」的理由）。⑤ **向后兼容**：**纯新增帧**——老客户端按未知帧忽略即可；不改任何既有帧的类型/字段、不改端点、不改鉴权；`owner`/`admin` 只是多收一帧。⑥ **实现落点**：生产者 `internal/runtime/orchestration/spawntool.go`（`SubagentResultEvent` 载荷带上派发回合的父会话）；中继 `internal/services/gateway/ws_bridge.go`（`bridgePatterns` 订阅该 subject + `normalizeEvent` 专用成形：帧壳 `sessionId` 取自载荷父会话；载荷形状不符预期时退回通用映射，两路都只发 `owner`+`admin`）。⑦ **验证**：进程内两端各一条——编排侧断言后台批次发布的载荷**类型/键集/父会话/逐代理结果**；gateway 侧**真 bus Publish → 真 `/ws/chat` 连接**（真 JWT × `owner`/`admin`/`viewer`）断言 `owner` 与 `admin` 各收到**恰好 1 帧** `subagent_result`（帧壳 `sessionId` = 父会话，`data` 的汇总与逐代理字段逐项对得上）+ 1 帧哨兵状态信号，而 `viewer` **只**收到哨兵（收不到结果帧）。**变异验证**：① 把 `orchestration.SubagentResultSubject` 从 `bridgePatterns` 去掉 → 「owner 收到 `subagent_result`」必须 FAIL；② 把 `subagent_result` 加进 `frameReachesAll` → 「`viewer` 收不到」必须 FAIL（两条均已跑，还原后复绿）。⑧ **同版另含管理面（D 组，2026-10-04 落实，与上列同属 v0.51 一版）**：**① `X-API-Key` 真正接线**（裁决 15.4.2）——`Authorize` 之上叠加 key 分支，管理/用户侧已认证端点同时接受该头，签发出去的 key **真的能用**；**且 key 一律超管、取消 role 分级**（裁决 15.4.3，主人原话「key 始终给超级管理员权限」）：签发端点**不再读 `role` 请求体**、响应恒 `role:"owner"`、任何有效 key 鉴权后即 `owner`。**fail-closed**：请求带该头时**只走 key 分支**，未知/已吊销/空值（或 key 表未注入）一律 `401`，**不回落 Bearer**；不带该头时 Bearer 路径**一字不变**；**WS 握手仍只认 Bearer**。**破坏性边界**：此前文档写的 `{"role":"admin|viewer"}` 请求体自本版起**被忽略**——若曾有客户端指望签一把只读 key，它拿到的其实是 owner key（这正是裁决要的效果：取消分级，不给「以为只读、实则超管」的错觉）。**② 新增主人档案读写 `GET`/`PUT /api/v1/admin/owner-profile`**（裁决 10.4.5，**owner-only**——这份档案决定谁能进 owner 车道，故连读都不给 `admin`；写带审计 `owner.profile.update`，读不审计；全新安装 `GET` 回 `200` + 空白档案而非 `404`）：消灭前端**假保存**——面板的「保存」从此真的落盘 `configs/users/owner.yaml`（0600 原子写）并**热替换活档案**，渠道层 actor 判定立即生效、无需重启；校验失败（`id`/`displayName` 缺失或 accounts 项半空）**不落盘**并回 `400 bad_request`，写盘失败回 `500 owner_profile_persist_failed`，档案损坏/读不出回 `500 owner_profile_unreadable`（不返回看似正常的空档案）。**③ persona `identity.systemPrompt` 改必填**（裁决 08.4.2）：`POST`/`PUT /admin/personas` 缺失或空白一律 `400 bad_request`（`"systemPrompt is required (identity.systemPrompt must not be empty)"`），**不再派生默认说明串**回落——载入期执行同一规则，写出的 YAML 必能被重新载入，不会出现「一条没有身份的人格被静默降级成拼凑串」。**文档同步**：§0 认证、§1 行 8、§2.0 权限矩阵（owner-only 档 35 → 37 条）与本「管理面板写操作契约」已按实现改写。 - `v0.50`（**事件批：流式帧的结构化补齐**——`tool_execution` 三事件 + `streamId` + `turn.start/end` + `graph_update` 三范围口径；依据 design/04 §1.1（裁决 01.4.1 / 01.4.2 / 01.4.3 / 03.4.4）与裁决 01.4.5（design/20 §2），2026-10-04 落实）：① **`tool_execution` 拆三事件（破坏性替换）**：旧单帧 `tool_execution.update {id,index,delta}`（`delta` 为 `"start:工具名"` / `"end:error:工具名"` 拼串）**不再由 loop 产生**，替换为 `tool_execution.start`（`{tool, phase:"running", id?}`，进入执行）/ `tool_execution.update`（`{tool, phase:"running", delta?, id?}`，运行中进度，可多帧）/ `tool_execution.end`（`{tool, phase:"done"|"error", id?}`，完成或失败）——**phase 与工具名是结构化字段，不再塞进 `delta`**；`id` 复用 provider 工具调用 id（可关联 `tool_call.*` 帧，无 id 时省略该键）。**迁移**：按旧 `delta` 拼串解析的客户端必须改读 `phase`/`tool` 字段；`tool_call.*` 帧形状不变。**诚实边界**：start/end 由 loop 在每次工具执行的首尾真实发出；`update` 的 wire 映射已实现并有单测锁定，但工具分发器尚无中途进度上报源，**loop 暂不产出 update 帧**（未来接入进度上报无需再改契约）。② **`streamId`（新增可选字段，位于模型流帧的 `data` 内）**：`message.*` / `thinking.*` / `tool_call.*` 帧的 `data` 带 `streamId`——loop 在**每次模型流**（一次 ChatStream 调用）开始时生成，同流多帧共享，多步工具轮的下一个模型调用取新 id；与帧壳 `turnId`（整轮恒定）分工：`turnId` = 哪轮回答，`streamId` = 这轮里的哪条流式消息。`tool_execution.*` / `turn.*` 帧不带。③ **`turn.start` / `turn.end`（新帧，无 `data` 载荷）**：loop 在 Run 起止发出、经 ws_bridge 下行（`model.StreamEvent` 新 kind → hub `broadcastStream` 映射）；帧壳 `sessionId`/`turnId`/`seq` 即边界信号；`turn.end` 覆盖所有出口（最终答案 / 工具循环安全网终止 / 预算耗尽 / 步骤出错）；回合终态仍由 `stream_end` 携带（分工不重叠）；被静音的内部流程（backthink / 子代理）不发出。④ **`graph_update` 三范围口径**（01.4.5，随实现事实补记）：发布范围为 `web` / `web:` / `sess-backthink` 三类（此前文档只写「web 及其子会话」，漏了 backthink 思考链路图这一实现事实；实现侧 `cmd/cyrene/wire_runtime.go` 的 allow 谓词本就如此，本批零代码变更）；并补记 **tool 节点 `status` 由 phase 驱动**（与 §3.1 `tool_execution.*` 的 `phase` 同枚举同决策：`trace.FlowStatusForPhase` 消费 tool span 上的 phase，缺省回落 span 终态）。⑤ **角色门**：本批新帧（`tool_execution.start/end`、`turn.start/end`）全部落 v0.48 下行门的「仅 `owner` + `admin`」档（fail-closed 默认，白名单未扩）；`viewer` 行为不变。⑥ **向后兼容总结**：新增帧与新增键（`streamId`、`data.tool`、`data.phase`）可被老客户端安全忽略；唯一破坏点是旧 `tool_execution.update` 单帧消失（见 ①）；**现有 Web 前端未消费 `tool_execution.*` / `turn.*` / `streamId`，本批对它零影响**。⑦ **验证**：loop 包断言三事件顺序/phase/工具名/id/Delta 为空、同流共享 streamId 跨流相异、turn 边界成对且覆盖错误出口、静音 run 零事件、flow 图 tool 节点 running→done/error 与 phase 一致；gateway 包真 WS 帧端到端（真 loop + 真 dispatcher + bus → relay → broadcastStream）：按 seq 排序断言完整帧序 `turn.start → message.delta → tool_execution.start → tool_execution.end → message.delta → turn.end`（+`stream_end`）、`streamId` 每流独立、`tool_execution` 帧无 `delta`/`streamId` 键、turn 帧无载荷；帧门矩阵补 5 行（三事件 + turn 两帧 × 三角色）。**变异验证**：去掉 loop 的 `ev.StreamID = streamID` 透传 → 「streamId 每流独立/前缀」断言 FAIL（已跑，还原后复绿）。 @@ -426,7 +481,7 @@ - `v0.44`（**渠道级选角 + 「谁说的」进模型上下文**，对客户端**新增两个可选字段**，向后兼容；design/22 批次 2 后端 = §2 裁决规则 + §4.4 + §7-3/§7-4/§7-5）：① **`PUT /api/v1/admin/channels/{platform}/config` body 新增可选 `personaId`**（渠道级绑定，design/22 §2 方案 b）：=该账号答话时的角色 id；**未知角色 `400 bad_request`**，~~**省略/`""` = 解绑**（写盘时该账号不带 `personaId` 键）~~（**本条的「省略」一项已由 v0.45 修订为「保留已存绑定」；只有显式 `""` 才解绑**，见上）；沿用既有「读当前配置 → `UpsertChannel` → 落盘 `channels.json`(0600) → `bridge.Reload(platform)` 热更新」路径，保存即生效（下一批入站消息），**无新端点**。② **`GET /api/v1/admin/channels` 每账号新增可选 `personaId`**（非敏感，不掩码），供面板回填。③ **角色解析优先级明确化（对客户端语义澄清，无形状变更）**：**会话绑定 > 渠道绑定 > 全局默认角色**；渠道绑定**只**作用于该账号的**主人私聊**且仅当主会话自身未绑角色（§7-3：IM 主人私聊镜像随主会话角色）；**群聊/陌生人隔离会话强制默认角色**（§7-4，更保守，仍只读）。④ **模型上下文新增角色归属标注（§7-5 的剩下一半）**：一回合上下文改为该会话**最近 20 条**持久化消息 + 本回合新消息（此前只带新消息本身），每条 assistant 历史消息按其说话角色出具 `[发言归属] 以下发言来自「<名字>」（），不是你说的。` 独立 system 标注 + 一条 `[会话角色] …` 当前角色声明；**消息正文一字不改**（标注只走 system 消息，design/11 §10），**对客户端透明**（无新字段）。前端无需改动即可继续工作；面板可选用 ① 让每个 IM 账号挂角色。⑤ **向后兼容**：纯新增可选字段；未配置 `personaId` 的账号与不读新字段的客户端行为不变（渠道绑定缺省 = 全局默认角色，与 v0.43 完全一致）。 - `v0.43`（**人格读侧合并批：admin 回读 `thinking` + 用户侧角色级 `mood`**，对客户端**新增两个可选字段**，向后兼容；design/01 §2/§2.1、design/04 §3.2）：① **`GET /api/v1/admin/personas` 每项新增可选 `thinking`**（`{budgetTokens,effort,showToUser,mode}`），与写侧同构、供面板回填编辑。**未配置的人格不带 `thinking` 键**（不是全零对象），与 `PUT` 的「省略 `thinking` = 保留已存」互为镜像。② **`showToUser` 三态原样回读**：**`null` = 未配置 → 保持现行为（thinking 帧照常推客户端）**，`true`/`false` = 显式开关；**服务端不把 `null` 拍平成 `false`**（否则面板会把「没配过」误显示为「关」，v0.41 的语义会被读侧丢掉）。③ **`GET /api/v1/personas` 每项新增 `mood`（角色级）**：= 该角色**当前情绪状态**（取值同 `GET /meta/enums` 的 `moods`；`""` = 暂无被跟踪情绪，不伪造）。**情绪跟随角色、与会话无关**——同一角色的所有会话看到同一 `mood`；客户端登录/加载角色目录时用它**播种心情徽标**（按角色 id 分桶），消除「刷新后徽标短暂为空」，随后仍以 WS `mood` 帧为准。**用户侧不暴露 `thinking`**（模型调用旋钮属管理侧）。④ **`effort` 的能力提示归服务端**：读端点只回读**已存配置**，**不承诺**该值在当前 provider 上生效——白名单校验/降级/WARN 仍在模型层（design/04 §3.2），客户端不得把「配了」呈现为「已启用」。⑤ **向后兼容**：纯新增字段；不读新字段的客户端行为逐字节不变（旧面板仍可编辑并保留已存 `thinking`）。 - `v0.42`（**多角色并存 + 按会话选角**，对客户端**新增可选字段/可选请求字段**，向后兼容；design/22 批次 1 = 后端会话级绑定）：① **`chat_sessions` 新增 `persona_id TEXT NOT NULL DEFAULT ''`、`chat_messages` 新增 `persona_id TEXT NOT NULL DEFAULT ''`**（同一迁移 **0011**，down 可逆，**不回填**）。`''` **= 继承全局默认角色**（`owner.yaml:defaultPersona`），所以**既有一切行升级后行为逐字节不变**，且默认角色改名后这些行跟着变（design/22 §4.7/§7-6）。② **`GET /api/v1/sessions` 每项新增可选 `personaId`**（=会话绑定角色）；**消息 DTO（REST `GET /sessions/{id}/messages`、WS `history` 回放、`message_persisted`/`message_edited` 广播）新增可选 `personaId`**（=**说话时的角色**，design/22 §7-5）。③ **`POST /api/v1/sessions` body 新增可选 `{personaId}`**（创建即绑定；未知角色 `400`；响应仅在非空时回显 `personaId`，故**省略时响应形状与 v0.41 完全一致**）；~~**`PATCH /api/v1/sessions/{id}` body 新增可选 `{personaId}`**（重新绑定，**显式 `""` 解绑**，未知角色 `400`；只回显变更字段）~~（**本条的「PATCH 重新绑定/解绑」已由 v0.46 作废**：会话角色在创建时确定、之后不可变，PATCH 一旦收到 `personaId` 即回 `400`，见 §1 行 8 / §8-1）。④ **回合语义**：角色决定**系统提示词 / 记忆命名空间 / 情绪与好感度 / 思考预算**四者**同源**解析（design/22 §4.2）；~~换角色**保留上下文**、**不动已存消息**，**下一回合**起生效~~（**已由 v0.46 作废**：会话内不再换角色——角色在创建时定死，`chat_messages.persona_id` 仍逐条记录"谁说的"）；**记忆口径 = 保持 persona 隔离**（design/22 §3）：不同角色的会话互不浮现，同角色的多个会话互相可见。⑤ **请求级覆盖（每次发送临时指定角色）本批未实现**（design/22 §2 裁决规则 1 仍待批次 2/后续）；**渠道级绑定（IM 账号/群默认角色）本批未实现**（design/22 §4.4 批次 2），故 IM 路径仍按默认角色解析。⑥ **契约内新增内部读接口**：网关经窄接口类型断言读取 `history.Store.SessionPersona/SetSessionPersona/NewSubSessionFor`（**v0.46 起**请求路径不再调用 `SetSessionPersona`——PATCH 的 persona 写路径已整体移除；「注入的 HistoryStore **不支持**角色绑定」只在 `POST /sessions` **显式传** `personaId` 时回 `501`，而非假成功）。 -- `v0.41`（**人格 `thinking` 配置 + 推理旋钮按 provider 映射**，对客户端**新增一个可选请求字段**，向后兼容）：① `POST /admin/personas` / `PUT /admin/personas/{id}` body 新增可选 **`thinking`** 对象 `{budgetTokens?,effort?,showToUser?,mode?}`（design/01 §2.1），原样写入并持久化到 `configs/personas/.yaml` 的 `thinking` 节；非法 `mode`/负预算回 **`400 bad_request`**；**`PUT` 省略该对象时保留已存 `thinking`**（旧面板/脚本不会抹掉它）；该字段只描述**呈现/资源**，不构成能力边界。② **`showToUser` 语义**：**缺省 = 照常把 `thinking.*` 流帧推给客户端**（现行为），显式 `false` = 仅落库/剥离语义不变、**不推帧**（展示与落库解耦）。③ **服务端推理映射**（对客户端透明，仅影响上游请求）：Anthropic 系在 persona 配置 `budgetTokens`/`mode: on` 时发 `thinking:{type:"enabled",budget_tokens:N}`，并**保证 `budget_tokens + 正文留量 ≤ max_tokens`**（不足则抬高 `max_tokens` 并记 WARN，绝不把正文吃空）；OpenAI 兼容系按**识别到的厂商白名单**校验 `reasoning_effort`（OpenAI 系 `none…max`、DeepSeek 仅 `low/high/max`），非法值**降级到最近一档并记 WARN**；**未知 provider/未识别模型、以及 Qwen 的 `enable_thinking` 硬开关（协议无统一 wire 形状）** 一律记 **WARN（含 provider/字段/取值）并保持请求不变**，绝不静默无效。详见 design/04 §3.2。 +- `v0.41`（**人格 `thinking` 配置 + 推理旋钮按 provider 映射**，对客户端**新增一个可选请求字段**，向后兼容）：① `POST /admin/personas` / `PUT /admin/personas/{id}` body 新增可选 **`thinking`** 对象 `{budgetTokens?,effort?,showToUser?,mode?}`（design/01 §2.1），原样写入并持久化到 `configs/personas/.yaml` 的 `thinking` 节；非法 `mode`/负预算回 **`400 bad_request`**；**`PUT` 省略该对象时保留已存 `thinking`**（旧面板/脚本不会抹掉它）；该字段只描述**呈现/资源**，不构成能力边界。② **`showToUser` 语义**：**缺省 = 照常把 `thinking.*` 流帧推给客户端**（现行为），显式 `false` = 仅落库/剥离语义不变、**不推帧**（展示与落库解耦）。③ **服务端推理映射**（对客户端透明，仅影响上游请求）：Anthropic 系在 persona 配置 `budgetTokens`/`mode: on` 时发 `thinking:{type:"enabled",budget_tokens:N}`，并**保证 `budget_tokens + 正文留量 ≤ max_tokens`**（不足则抬高 `max_tokens` 并记 WARN，绝不把正文吃空）；OpenAI 兼容系按**识别到的厂商白名单**校验 `reasoning_effort`（OpenAI 系 `none…max`、DeepSeek 仅 `low/high/max`），非法值~~**降级到最近一档并记 WARN**~~（**已由 v0.53 修订为「丢弃并记 WARN、不降档」**——降档会反转调用方意图，`none` = 关思考，绝不翻成任何强度档）；~~**未知 provider/未识别模型、以及 Qwen 的 `enable_thinking` 硬开关（协议无统一 wire 形状）** 一律记 **WARN（含 provider/字段/取值）并保持请求不变**，绝不静默无效~~（**本条已由 v0.53 作废**：开关形状改由组键 `reasoning.kind` 显式声明并**真下发**，**只有形状未知/有歧义时才 WARN 且一个字段都不发**，见 v0.53 变更记录）。详见 design/04 §3.2。 - `v0.40`（**`viewer` 角色真正接线：只读监控档**，对客户端**收紧/放宽若干 admin 读的鉴权**，无端点/字段形状变更）：此前 `viewer` 只是常量（`internal/auth` 的 `RoleViewer` 注释写着「只读 dashboard/logs/monitoring」）而**从未接线**——管理侧 24 条 GET 全走 owner/admin，`viewer` 一条都读不到（**全 403**）。本版新增第四道门 `viewerAuth = owner+admin+viewer`，并把 **12 条只读监控 GET** 从 owner/admin 放宽到 owner/admin/**viewer**：`GET /admin/personas`、`/admin/sessions`、`/admin/plugins`、`/admin/plugins/installed`、`/admin/channels`、`/admin/iot`、`/admin/automations`、`/admin/rag`、`/admin/observability/metrics`、`/admin/observability/trace`、`/admin/observability/logs`、`/admin/notifications`。**明确不放给 viewer**（含凭据获取路径、他人数据、完整消息/导出明文、审计流水，或 `admin` 也不给）：`GET /admin/memories`、`/admin/llm`、`/admin/users`、`/admin/backthink`、`/admin/observability/audit`、`/admin/channels/messages`、`/admin/channels/{platform}/messages`、`/admin/sessions/{id}/export`、`POST /admin/rag/query`（这 9 条 owner/admin）以及其余 **35 条 owner-only**（全部写操作 + `login-qr`/`login-status`/`view`/`friends`/渠道连接与配置/`plugins/*`/`users/*`/`system/*`）。**匿名**：任意 admin 路由仍 `401`（fail-closed）。**向后兼容**：`owner`/`admin` 语义不变（放行集合是超集），仅 `viewer` 的可见面从「全 403」变为 12 条只读监控；不依赖 `viewer` 的客户端行为不变。完整分档见 §2.0「管理侧权限矩阵」。 - `v0.39`（**微信 iLink 会话被拒可见化 + 不再假 OK**，对客户端**新增两个可选字段、一处错误码**，向后兼容）：① **`GET /api/v1/admin/channels` 每平台行新增可选 `needsRescan`（bool，`omitempty`）+ `lastError`（string，`omitempty`）**——仅当适配器**真的**要求重新授权时出现（今天只有微信 iLink 返回 `errcode=-14` 这一种），取值来自适配器新增的**可选能力接口** `RescanRequired() (bool, string)`，网关**经类型断言**读取（主 `PlatformAdapter` 契约**不变**；未实现该能力的平台字段**缺省不出现**）。用途：把「需要重新扫码」与「主人自己关掉的未连接」区分开——后者仅 `connected:false`。② **`POST /admin/channels/open`** 对「iLink 已拒绝该会话」回 **`409 session_rejected`**（message 明确要求用「扫码登录」重新绑定），**不再**吞掉错误回 200；`409 needs_login`（尚无 token，v0.8 起）不变。③ **适配器行为**：iLink `errcode=-14` 进入**显式被拒态**——`IsConnected()` 恒 `false`；`Connect()` 返回被拒错误（**不再**对被拒会话报成功）；`HealthCheck` 区分「会话被拒」与「未连接」；并以 **`ERROR`** 级日志写明「本次会话已被 iLink 拒绝，需要重新扫码绑定」（只带 `bot_id` 等非敏感标识，**token 永不入日志**）。被拒态在读循环与发送两条路径**都会**置位，并仅在**扫码登录拿到新 token** 或**配置换了新 token**（保存 + 热重载）时清除。④ 扫码登录侧：被拒期间 `login-status` 报 **`failed` + 被拒原因**（**不再**假报 `confirmed`，否则面板会把已作废凭据当成功重新落盘）；`login-qr` 仍可正常出码（**不**回 `already_logged_in`，否则重新扫码这条路被堵死）；`get_bot_qrcode` 不再携带已被拒的 token（否则服务端以「已绑定」应答、**不**发新凭据）。**向后兼容**：只新增可选字段与一处更诚实的错误码；不读新字段、不处理 409 的客户端行为不变（此时面板显示「未连接」，仍可用「扫码登录」恢复）。**语义澄清（本次仅措辞，不改契约形状、不另起版本号——v0.39 尚未被任何客户端采用）**：iLink 的 bot token 是**长期凭据**（实测一个月前扫码得到的 token 仍可用），`errcode=-14` 表示 **iLink 侧拒绝/作废了该会话凭据**，**不是时间性过期**。详见 §2 行 6 与「微信 iLink『会话被拒』契约」。 - `v0.38`（**B4 客户端共享枚举权威表 + 未知值回落约定**，对客户端**新增一个只读 REST 端点**）：新增 **`GET /api/v1/meta/enums`**（**任意已认证角色可读**，与 `GET /sessions` 同级；无 token `401`）→ `200 {data:{platforms,moods,modes,unknown}}`，每项 `{id,label}`：① **`platforms`**（6）= `web`/`kook`/`qq-obv11`/`weixin-ilink`/`telegram`/`webhook`——即各内置适配器 `Name()` + Web 主会话来源 `web`；② **`moods`**（5）= `calm`/`happy`/`excited`/`sad`/`angry`，与 persona 情绪状态机内置状态一致（该状态机**可扩展**，故非封闭集合）；③ **`modes`**（9）= `chat`/`code`/`home`/`work`/`docs`/`voice`/`vision`/`agents`/`settings`（design/07 §1）；④ **`unknown`** 恒 `"display-raw"` = **未知值回落约定机器可读**：客户端遇不在表中的取值**原样显示原始字符串**（**不丢弃、不报错、不占位符**），**服务端新增取值视为非破坏性变更**（forward-compatible）。**单一事实来源在 Go 侧**（`internal/contract/enums`），并有**反漂移测试**断言适配器 `Name()` / 情绪内置状态 / 前端九模式与三张表一致，漏登记即 CI FAIL。Web 侧镜像 `frontend/web/src/lib/enums.ts`（`labelFor` 未知值返回原值），顶栏/侧栏/消息气泡的「心情」标签已改用它渲染。**向后兼容**：仅新增端点，既有契约形状不变。详见 §1 行 15 与 §1.1。 diff --git a/Docs/api-reference.md b/Docs/api-reference.md index 0d7d821..a1709dd 100644 --- a/Docs/api-reference.md +++ b/Docs/api-reference.md @@ -1,6 +1,6 @@ # Cyrene v2 后端 API 参考（api-reference.md） -> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.52`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。** +> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.53`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。** > **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。 > **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**仍未登记的端点 / WS 事件清单见 `DevDocs/audit/00-总览.md` §4④**，属后续「文档补全」批次，本文件暂不补全。 > **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。 @@ -42,7 +42,7 @@ ### 0.3 上传 / 媒体（重要确认） -- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉真推理，见 §6 流式与直连）。 +- **`POST /api/v1/upload`**（B1）上传图片 → 返回**同源 URL**（`/api/v1/files/`），可直接作 `chat.image`；也可继续用 **base64 data: URI** 或 http(s) URL 走 `POST /api/v1/chat` / WS `chat` 的 `image` 字段（入视觉路由，见 §6 流式与直连）。**语义（v0.53 修正，见 api-client §1 行 3）**：**主模型能否收图 = 生效 `models.json` 组的 `multimodal`**（不是「有没有配独立视觉模型」）；`LLM_VISION_MODEL` / `LLM_OCR_MODEL` **只配视觉/OCR 工具用的模型**；主模型不收图时由 vision/OCR 工具返回**文本描述**（另有 `image-crop` 工具可裁区域后重读，便于大图分区精读）。 - **REST 语音端点已存在**：`POST /api/v1/audio/transcribe`（STT）、`POST /api/v1/audio/speech`（TTS）、`POST /api/v1/audio/voice-clone`（声音复刻），均 owner-only + 审计，绕开 WS 4KB 帧限。语音也可走 WS `voice_input`（上行）/`voice_output`（下行）。 - 管理端导入知识文档（RAG）走 JSON body 文本（`POST /api/v1/admin/rag`），非文件上传。 @@ -208,7 +208,7 @@ curl -s -X POST http://:8080/api/v1/auth/login \ |------|------|:---:|------| | `sessionId` | string | 否 | 目标会话 id；缺省 `"web"`（主会话）。子会话用 `web:` | | `text` | string | 是* | 用户文本。`text` 与 `image` 至少一项非空 | -| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn | +| `image` | string | 否 | 视觉输入：base64 **data: URI** 或 http(s) URL；入 vision/OCR 工具或主模型多模态（design/06）。图文并存则为带图 + 文本的 turn。**语义（v0.53）**：主模型能否收图看生效组的 `multimodal`；`LLM_VISION_MODEL`/`LLM_OCR_MODEL` 只配视觉/OCR **工具**的模型（见 api-client §1 行 3） | | `deviceId` | string | 否 | 客户端生成的端标识（design/16 §4.5，如 `web:chrome:a1b2c3`），落库到消息，可选 | | `mode` | string | 否 | 行为模式（design/01 §3、design/16 §5.1，如 `chat`/`code`/…）；随该轮落库供气泡渲染；**IM 恒 `chat`、缺省回落 `chat`**（`chatRequest.Mode`） | | `stream` | bool | 否 | `true` = 经 WS 触发流式（`publishChatStream` 发 `ws.chat`），**立即返回**；缺省 / `false` = 同步返回完整回复（Go bool 零值即 false，仍**无「必填」约束**） | @@ -493,10 +493,13 @@ curl -s http://:8080/api/v1/admin/iot -H "Authorization: Bearer $TOKEN" -H ### 4.9 GET /api/v1/admin/llm - **响应**：`200 {"data":{"providers":[...]}}`（`AdminLlmConfig`）。 -- `AdminLlmProvider`：`{id, name, provider, baseUrl, model, multimodal, enabled, fallback?, maxTokens?}`。 +- `AdminLlmProvider`：`{id, name, provider, baseUrl, model, multimodal, enabled, fallback?, maxTokens?, reasoning, personaModels?, personaProviders?}`（**v0.53 新增三键**，见 api-client 的「模型配置契约（v0.53）」）；顶层 response 另含 `reasoningKinds` / `personaProviderOptions` 两个取值域数组（面板表单选项的唯一来源）。**`multimodal` = 主模型自己能否收图**（裁决 14.4.1）——它**不**表示「本部署有视觉能力」；视觉/OCR **工具**的模型由 `.env` 的 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 单独配置，与 `multimodal` 无关。`reasoning` 恒下发（`{kind}`，`kind:""` = 未声明形状）。 - `provider` 协议 ∈ `openai|anthropic`；`name` 为友好标签（OpenAI/Anthropic 或组 id）。 - `enabled`：index 0 的组为生效组 = `true`。 - `maxTokens`：该组的 token 预算（`omitempty`，缺省/0 = 未设）；缺省时链末端回退步回落 `LLM_FALLBACK_MAX_TOKENS`（`.env`，默认 8192），再回落适配器默认（anthropic 8192）。 + - `reasoning`（v0.53，恒下发）：`{kind}` —— `kind` ∈ `auto|deepseek|openai|vllm|dashscope`，决定该组用哪种**提供商开关形状**下发推理指令（`""`/`auto` = 按模型名/baseURL 推断，形状有歧义就不下发）；详见 api-client「模型配置契约（v0.53）」。 + - `personaModels` / `personaProviders`（v0.53，`omitempty`）：**角色级模型 / 协议路由表**（`{personaId: modelId}` / `{personaId: "openai"|"anthropic"}`）；未配置 = 该键不出现。 + - `multimodal`：**主模型自己能否收图**（= 面板的「多模态」勾选）；视觉/OCR **工具**的模型是 `.env` 的 `LLM_VISION_MODEL`/`LLM_OCR_MODEL`，与本字段无关（裁决 14.4.1 修语义）。 - **API key 永不返回**（wire 无 key 字段）。 - 数据源：`models.json` 各组（index 0 = 生效组）；无 `models.json` 时按 `.env` 合成单组。curl： @@ -726,7 +729,7 @@ curl -s -X DELETE http://:8080/api/v1/admin/automations/ -H "Authoriza ``` ### 5.13 POST /api/v1/admin/llm -- **Body**（`llmProviderRequest`）：`{"id?","name?","provider?","baseUrl","apiKey?","model","multimodal?","fallback?","maxTokens?"}`。`baseUrl`+`model` 必填；`provider` 空默认 `openai`（仅允许 `openai|anthropic`）；`maxTokens` 缺省/`0` = 未设，负数回 `400`。 +- **Body**（`llmProviderRequest`）：`{"id?","name?","provider?","baseUrl","apiKey?","model","multimodal?","fallback?","maxTokens?","reasoning?","personaModels?","personaProviders?"}`。`baseUrl`+`model` 必填；`provider` 空默认 `openai`（仅允许 `openai|anthropic`）；`maxTokens` 缺省/`0` = 未设，负数回 `400`。**v0.53 三键**缺省 = 保留已存值（`reasoning` 整块给出即整块替换；两张 persona 表给出即整表替换）；非法 `reasoning.kind`、非法协议名、anthropic 组声明 openai 系形状 → `400 bad_request`（`Group.Validate` 报错，不落盘）。契约见 api-client「模型配置契约（v0.53）」。 - **响应**：`201 {"data":{"provider":,"persisted":true,"path":""}}`。**真实持久化**：读-改-写 `models.json`，保存组**提升为生效组**（index 0），并**热重载**运行中的 LLM stack（无需重启）。 - **错误**：`400`（缺 baseUrl/model / invalid provider）；`500`（LLM 服务未注入 / 写盘失败 / 热重载失败）。**API key 写入文件但永不回显、不落日志**。 - **审计**：`llm.addProvider`。curl：