From c4e09afd381741a4a0a77149376a65e4f6cb4375 Mon Sep 17 00:00:00 2001 From: AskaEth Date: Sun, 4 Oct 2026 19:44:53 +0800 Subject: [PATCH] =?UTF-8?q?feat(admin):=20=E9=9D=A2=E6=9D=BF=E3=80=8C?= =?UTF-8?q?=E5=AD=98=E5=82=A8=E3=80=8D=E5=8D=A1=E7=89=87=E6=8E=A5=E7=9C=9F?= =?UTF-8?q?=E6=95=B0=E6=8D=AE=EF=BC=88=E5=90=AB=20PG=20=E5=A2=9E=E5=BC=BA?= =?UTF-8?q?=E7=8A=B6=E6=80=81=EF=BC=89+=20=E5=A5=91=E7=BA=A6=20v0.60?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 现状：overviewMetrics.ts:188 的「存储」卡是写死的 value:"SQLite"，后端也没有对应读端点（/admin/system/* 只有 revoke-keys/rotate-jwt/backup/restore 四个动作端点）。 - 新增只读端点 GET /api/v1/admin/system/storage（ownerAuth）：main{kind,path,fileBytes,walBytes,shmBytes,pageSize,pageCount,freelistPages,freeBytes} + documents{count,bytes} + vector{kind,enabled,ready}；只读（SELECT/PRAGMA + os.Stat）、复用活连接不开新池、**绝不含凭据**（只回 kind，不回 host/DSN）、失败一律 500 storage_unavailable（不回全 0 假快照；表缺失也 500 而不是静默 0）。 - vector 真源 = 组合根 app.vectorState()（Configured = DB_PG_URL 非空；Live = 向量索引类型断言成功），零新探测 ⇒ 面板现在能区分「未启用（未配置 DB_PG_URL）/ 启用（pgvector·ready）/ 已配置但未就绪（连接失败，检索降级）」，正好解答主人对「面板只写 SQLite」的困惑。 - 前端：卡片显示真实体积 + WAL/页数/空闲页 + documents 件数与占用 + PG 那一行；取数走与已接线卡片同一条加载/错误态（失败显示 '—' + 端点报错，不静默显示 0）。 - 契约 v0.60（项目红线）：api-client（版本段 + 端点表 + 存储状态契约小节 + changelog）与 api-reference（版本号 + 端点表 + 详情小节）同步；字段名三方（代码/Docs/前端）逐字对齐。 - 主会话独立验收：隔离 worktree（ST1 的 14 文件，排除 B1 在途的 chat_documents.go/documents_pdf_test.go）build/vet 绿、全树 59 包 0 FAIL、存储端点 7 用例 PASS、双平台交叉编译绿。 - ⚠️ 该切片自首一起事故：为通过 cmd/cyrene 类型检查跑了 go build ./cmd/cyrene/（单 main 包）⇒ 覆盖了仓库根 cyrene.exe（49,675,264 B / 19:32:19，脏树未 strip）；上一个权威产物仍在 cyrene.exe~（39,507,968 B / 19:25:13）。运行中的 PID 477964 未受影响；主会话将在整树干净后重跑 ctrl.bat build 恢复权威产物。 --- Docs/api-client.md | 35 +- Docs/api-reference.md | 46 ++- cmd/cyrene/wire_frontend.go | 24 ++ .../admin/modules/dashboard/MiniMetric.tsx | 11 +- .../modules/dashboard/overviewMetrics.ts | 53 ++- .../modules/dashboard/useDashboardExtras.ts | 9 +- frontend/web/src/lib/api.ts | 1 + frontend/web/src/lib/api/adminSystem.ts | 11 + frontend/web/src/lib/types/adminWrite.ts | 37 +++ .../services/gateway/admin_system_storage.go | 185 +++++++++++ .../gateway/admin_system_storage_test.go | 311 ++++++++++++++++++ internal/services/gateway/deps.go | 28 ++ internal/services/gateway/routes.go | 3 + internal/services/gateway/server.go | 10 + 14 files changed, 751 insertions(+), 13 deletions(-) create mode 100644 internal/services/gateway/admin_system_storage.go create mode 100644 internal/services/gateway/admin_system_storage_test.go diff --git a/Docs/api-client.md b/Docs/api-client.md index a71b0ab..4b8dc3c 100644 --- a/Docs/api-client.md +++ b/Docs/api-client.md @@ -195,7 +195,7 @@ > **发现的不一致（如实登记）**：design/24 §9.2 与本题面任务书写「白名单 **23** 项」，但设计所列清单与代码 `documentExtAllowed` 均为 **22** 项（见上表）——**以代码的 22 项为准**。另：design/24 §6.2 的 `document_unreadable`(400) **在代码里没有对应 REST 错误码**，它只以 `document-read` 的工具错误形态存在（见本节 ⑤）。 -> **契约版本 `v0.59`**（**文档进对话（`F1/F2`）+ 上下文预算按窗口推导（`T1`）+ 语音回合进编排（`G5/C1/C3`）+ `thinking` 可达性口径**，依据 design/24 §3/§4/§6（切片 S1–S5）、design/04 §1.3 + 附录 A.3（主人裁决 2026-10-04）与 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 G5/C1/C3，commit `a8851dc` / `a4789ec` / `20c1edb` / `5b2b385` / `72b95df` / `3a01b4e`，2026-10-04 落实）：**A. 文档存储与摄取（两个新端点 + 一个可选请求字段 = 纯增量；DTO 形状变更是破坏性，但单数形状从未发布，故无兼容期）**——① **新增 `POST /api/v1/documents`**（owner|admin，`multipart/form-data`，字段 `file`）→ 首次 `201 {data:{name,url,mime,size,sha256,deduped:false}}`；**同字节同扩展名重复上传 → `200` + 同一 `name` + `deduped:true`**（客户端可当成功处理）；单文件上限 **`CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB = 20971520）**，`≤0` 视为用默认；它与图片上限 `CHAT_IMAGE_MAX_BYTES` **刻意解耦**（改文档上限不会静默改掉图片行为）。② **新增 `GET /api/v1/documents/{name}`**：**必须带 Bearer（owner|admin）**——与图片读侧（免鉴权的能力 URL）**刻意相反**（文档摄取在服务端完成，不需要被 ``/provider 直接消费），响应带 `Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`（浏览器永不内联渲染）。③ **类型裁决（重要）**：**字节嗅探是唯一裁决者**（`http.DetectContentType`，放行的嗅探基类型只有 `text/plain`），**客户端声明的 `Content-Type` 与原始文件名只作参考、可被嗅探否决**；**扩展名白名单 deny-by-default，实际 **22** 个**：`.txt .md .markdown .csv .tsv .json .jsonl .yaml .yml .log .ini .cfg .toml .go .ts .tsx .java .c .h .cpp .rs .sql`（⚠️ design/24 §9.2 写「23 项」但所列清单与代码均为 **22** 项，**以代码 22 为准**，见 §1.2「发现的不一致」）；**明令拒绝** `text/html`、SVG/XML、zip 及其封装（docx/xlsx）、可执行/脚本（exe/dll/bat/cmd/ps1/js/mjs/sh/py）——即便 `.js`/`.py` 嗅探成 `text/plain` 也拒（判定 = 扩展名 ∧ 嗅探的**合取**）。④ **边界（勿与图片混用）**：`url` 是**相对路径**（`/api/v1/documents/<32hex>.`；图片侧是绝对 URL）；`mime` 是**嗅探所得基类型**（故 `data.json` 返回 `text/plain`，不是 `application/json`）；落盘名 = `sha256(bytes)[:32] + ext`（**内容寻址**，原始文件名永不参与路径 ⇒ 同字节同扩展名天然同名去重）。⑤ **4 个错误码**：`unsupported_media_type`(415) / `document_too_large`(413) / `document_not_found`(404，含名字形态非法与路径穿越) / `too_many_documents`(400)。⑥ **`chat` 请求新增可选 `"documents":[{"name":"<32hex>."}]`**（REST 同步 / REST `stream:true` / WS `chat` **三处同形**）：**≤5 条**（超出 `too_many_documents` 400，且**先于任何文件系统访问**）；**只收服务端存储名、绝不收 URL**（不重开 F3 那种「服务端代取 URL」的 SSRF 面）；客户端多带的 `mime/url/size` **一律被服务端覆盖**（MIME/大小取自落盘字节）；名非法/穿越/不存在 → `document_not_found`(404)；**任一条不合规都让整个请求被拒**，绝不「丢掉这条附件但照样起回合」（WS 侧经 `error` 帧带 `data.code` 下发并中止本回合，REST 侧回对应状态码）。⑦ **响应 / 历史 DTO 由 `document`（单对象）改为 `documents`（数组，≤5）**——元素形状 `{"name","mime","size","chars","truncated","status"}`，`status ∈ extracted|listed|unreadable`；**0 个附件时该键省略**；同一 DTO 供 `GET /sessions/{id}/messages`、`message_persisted`、`message_edited`、WS 握手回放 **四处同时生效**（同一个 `historyMessage` 结构）。⚠️ **原单数形状从未发布过**（不在任何已发布版本号里）⇒ **无兼容期**，直接换数组（design/24 §6.1 那句 `"document":{…}` 已随之作废）。⚠️ **`chars`/`truncated` 改为「本回合注入侧」语义**：`chars` = **本回合注入**模型上下文的字符数、`truncated` = **注入**是否被截断（**不是**「原文件是否被截断」）；**全文长度**只有 `document-read` 的 `totalChars` 能看到。⑧ **内置工具 `document-read`**（模型侧工具，客户端一般只需知道它存在）：`{name, offset?, limit?}` → `{name,status,offset,limit,totalChars,truncated,nextOffset,text,extractTruncated?}`；`limit` 默认 **8000** 字符、上限 **64K**；`offset` 单位是**字符（rune）**、0 基、起点 = sidecar 正文（含 CSV/TSV 摘要行）第 0 个字符；`offset<0` 或 `>totalChars` → 错误（`==totalChars` 合法，读到末尾空片段）；`extractTruncated=true` **专指**「撞上 8 MiB sidecar 安全上限」（≠ 本回合注入被截断）；策略默认 **owner-only**（群聊/陌生人天然读不到主人的文件）。**B. 配置面（纯增量 + 一处语义变更）**——① **`models.json` 组级新增 `contextWindow`**（正整数 = 该组模型的上下文窗口；`0`/省略 = 未声明 ⇒ 后端按 **131072** 保守估算并记**恰好一条** WARN；**负数 = 组校验失败**，写端点回 `400`）。 ② **`.env` 新增/变更 4 键**：`LLM_CONTEXT_WINDOW`（**per-group 播种**，等价于 `models.json` 的 `contextWindow`）、`CONTEXT_BUDGET_RATIO`（默认 **2/3**，接受 `2/3` 或 `0.6667`，非法值记 WARN 后回落）、`DOCUMENT_MAX_INJECT_CHARS`（单份附件注入上下文的字符上限；未设 = 按推导出的预算自动算）、**`CONTEXT_MAX_TOKENS` 语义变更（关键）**：**未设置 ⇒ 按窗口推导**（`budget = min(窗口 × 比例, 窗口 − 输出保留)`，输出保留 = `max(32768, 该组 maxTokens)` 且**封顶 `窗口/2`**；**1M 窗口 ⇒ 699050 tokens**）；`>0` = 显式覆盖（原样使用）；`0`/负 = **关闭压缩**。⇒ **`.env` 里若仍写着 `CONTEXT_MAX_TOKENS=32768`，它就是显式覆盖、推导不生效**（这是设计语义，**不是 bug**；本次已把 `.env.example` 里该行改成注释形式）。③ **`.env` → 面板配置的 materialize 语义（欠账，本次补登记）**：进程**每次启动**跑一次；**面板配置非空 ⇒ 组集合完全由面板决定**（env 不新增、不复活被面板删掉的组）；**键级只在面板缺该键时用 env 补**，面板已有的键（含**显式空值 / 显式 `false` / 显式 `null`**）**绝不覆盖**；面板配置缺失/为空时才由 env 播种出合成组；**「面板改一次、重启被打回」是硬约束**（有专门用例钉住）；每次启动记「补了哪些 / 跳了哪些」，**凭据绝不进日志**；范围目前**仅 `models.json` 一族**（`channels.json` / `plugins.json` 未纳入）。④ **面板读写面**：`GET /api/v1/admin/llm` 的组 DTO **含 `contextWindow`**（`omitempty`，与 `maxTokens` 同形：未声明时该键省略），`POST /api/v1/admin/llm` **接受可选 `contextWindow`**——**缺失 = 保留已存窗口**、**显式 `0` 与缺失同义**（都 = 未声明）、**负值 `400 bad_request` 且不落盘**；面板 LLM 页据此显示/编辑该键。**C. 语音（有行为变更，见 §3.15）**——语音轮次**现在走与文本同一条路径**：会**落库**（用户消息 = 转写文本，助手消息 = 回复）、会发 `message_persisted` 与流式帧、**跨端同步**、忙时按编排器既有规则**排队**（`pending_ack`/`pending_drain`/`session_busy` 语义零变化，只是多了一个消费者）；`deviceId` 照旧落库、`platform` 走存储默认 `web`；`voice_input` 上行增可选 `clientMsgId`（与 `chat` 帧同形 ⇒ 语音也有幂等；重复到达回既有 `chat_duplicate`，**不产生新回合、不发音频**）；`voice_output`（定向）载荷增 `sessionId`（恒有）与 `deviceId`（非空才有）；**空正文**与 **TTS 失败/降级**都走既有 `provider` 降级信号（客户端据此提示「没生成声音」；**不再**把 `stopReason` 当语音内容）；**时点**：`voice_output` 在**该回合结算时**才到（可能晚于若干状态帧，甚至由续跑回合或被 steer 注入的那一回合产生）；定向目标是**发起 `voice_input` 的那条连接本身**（服务端**不按 deviceId 路由**）；连接断开后**不补投**，客户端重连后带上同一 `clientMsgId` 可安全重试。**D. `G5`（纯增量：广播帧 +2 个可选键；新增一条定向错误帧，见 §3.2）**——① **`pending_full` 广播载荷**增 `clientMsgId?` / `messageId?`：前者 = **被拒那条消息**的幂等键（未携带则**整个键缺席**）；后者**仅当该消息此前已落库/已认领时**才回填——**服务端绝不在此处新铸 id**（队列满的拒绝发生在幂等键认领之前，代铸会让客户端重试被判成「重复到达」而永远进不来）。② **新增定向帧（此前无文档登记）**：`{type:"error", data:{code:"chat_busy", message, sessionId, clientMsgId?, messageId?}}`，**只发发送者那条连接**、不广播；`code` 与 REST `409 chat_busy` **同码**（客户端一个 code 覆盖两条入口）。**E. `E3`：`thinking` 可达性口径（不改行为，只是把话说清）**——消息体的 **`thinking` 字段**在**实时帧**（`message_persisted` / `channel_persisted` / `message_edited`）与**握手回放**中**一律为空**（隐私与带宽的**有意**默认；实时思维链仍由 §3.1 的 `thinking.*` 流帧按 owner/admin 档下发）；**历史消息的思维链**只有 `GET /sessions/{id}/messages`（owner|admin）返回。**上一版 `v0.58`**：（**新增 `.env` 键 `LLM_MULTIMODAL`（`bool`，默认 `false`）：让 env-only 部署能声明「主模型自身能否收图」**，依据裁决 14.4.1 / design/06 §0（commit `4adfc9a`），2026-10-04 落实）：**A. 新键语义（见 §2「模型配置契约」表）**——**`LLM_MULTIMODAL` 是 `models.json` 组 `multimodal` 的 env 等价物**，**只作用于 `.env` 合成组**（**无有效 `models.json` 时才生效**；有组文件时以该组的 `multimodal` 为准，与 `LLM_REASONING_KIND` 同口径）：`true` = 图片**直进主模型上下文**（省掉工具那一轮模型调用、也不做有损文本摘要），**留空 / `false`（默认）= 把图交给 vision/OCR 工具换成文本描述**；**绝不凭 base URL / 模型名猜测**端点是否收图（声称端点不具备的能力，比把图交给工具更糟——工具至少回一段文本，design/06 §0 首条）。**B. 与 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 的关系**——后两者配的是**视觉/OCR 工具调用的模型**，**不代表主模型能收图**，与本键互不代表（见 §1 行 3）。**C. 兼容性（默认值即旧行为）**——默认 `false` ⇒ **老部署行为逐字不变**（引入本键之前，env-only 部署没有任何键能声明该能力，图片恒走 vision 工具）；**非 bool 值（如 `maybe`）在配置解码阶段直接报错、启动失败**（fail-fast，**不静默回退成 `false`**——静默的「配了当没配」正是本键要消灭的）。**`LLM_MULTIMODAL=true` 后图片走主模型直收，属部署者显式选择**（形状由部署者声明，后端不替它猜）。**D. 实现落点**——`internal/config/config.go`（`LLMConfig.Multimodal`，默认 `false`）+ `internal/config/runtimeconfig/models.go`（`GroupFromEnv` 把两 provider 分叉都透传进合成组）+ `internal/config/runtimeconfig/multimodal_env_test.go`（默认 false / 显式 true 抵达合成组 / 进程 env 端到端 / 组文件优先 四组测试）。**无端点、无帧、无字段形状变更**（纯新增 env 键）。**上一版 `v0.57`**：（**13.4.5 目标态 steer 落地登记：新下行帧 `steer_ack`**，依据 design/15 §2.0/§2.1/§2.4/§3.x/§5（裁决 13.4.5 目标态，commit `3d8822c`），2026-10-04 落实：**A. 新下行帧 `steer_ack`（见 §3.14）**——`{type:"steer_ack", sessionId, data:{messageId, atStep}}`：忙时会话里新到的用户消息**被在飞回合吃进同一回合**时下发（`messageId` = 那条用户消息的**权威 id**，`atStep` = 吃进它的**模型步序号，1 基**）；语义＝「**该消息已被本回合吃进（已从 pending 移除）、尚未被正面回答**」⇒ 客户端应把对应气泡渲染为「已读、未答」的**灰态**，直到该回合的 `message.*` / `turn.end` 到达（**不需要第二个确认帧**）。**角色门**：它**携带具体消息身份**（客户端能定位到某一条气泡，而不只是会话忙闲），因此**不登记**进 `frameReachesAll` 的 7 个状态机信号白名单，落 fail-closed 默认档——**只发 `owner` + `admin`**（`viewer` 收不到）；经编排器状态通道**由 hub 直接广播、不经 bus**，帧壳带 `sessionId`、**不带** `turnId`/`seq`。**触发时机**：只在**回合内边界**（loop 每一步开头：上一次模型步与它那一批工具调用**都已结束**、下一次模型调用**尚未开始**，此刻没有工具在飞）产生，且**只有该边界真的匹配到 pending 里、且已落库的消息时才发**——**不是每个 step 都发**（没可注入消息的边界一帧都不发，这是常态）。**B. 转向的三条不变量（design/15 §2.0）**——**I1（同会话在途回合数恒为 1）**：转向只注入、不取消，**绝不新开第二个回合**（loop 侧结构性地没有任何「起新回合」的分支，注入只是把消息并进**当前回合**下一次模型调用的视图）；**I2（消息恰好被处理一次）**：注入＝已消费——被注入的消息立刻从该会话 pending **移除**（按 pending 序号认领），**绝不被第二个回合再答一遍**，去重键＝后端 `message.id`，且候选必须**同时**满足「在该会话转录里（最近 20 条窗口内）」与「在本编排器的 pending 里」；**I3（转向不取消已发起的工具）**：注入点只在回合内边界，此刻没有任何工具在飞，正在执行的工具**永远跑完**。**C. 注入的范围（口径）**：注入**只影响本轮视图**（每一步边界重新并入），**不写回运行窗口** ⇒ 既不进该回合的 **checkpoint 快照**、也不进**后台记忆提取的输入面**；被注入的消息**本身早在到达时已落库**（pending 路径即时持久化），注入**不新增、也不改写任何行**。**D. 失败一律让路**：未接转录存储 / 读转录失败 / 该消息尚未落库 / 本回合世代已被打断或被更新的回合取代（认领 `pending` 失败）时，**不发 `steer_ack` 也不注入**——该消息**留在 pending**，照旧作为自己的回合被回答，**绝不静默消失**。**E.** 另含一处**链路图纯增量键**（注入时该轮图的 input 节点带 `props.steered:true`，图仍只有一条主干——不是被画成第二轮），以及**纯新增帧**的兼容性口径（老客户端按未知帧忽略即可）。**上一版 `v0.56`**：（**协同项 A2 / G1 / G2 / G3 / G4 / F3 落地登记：`interrupt` 支持 `scope` + REST `stream:true` 不再静默失败 + `chat.image` 上限 + `clientMsgId` 幂等 + 视觉链路 URL 取回与类型裁决 + 既有错误陈述更正**，依据 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 A2 / G1 / G2 / G3 / G4 / F3（commit `7512d59` 等，2026-10-04 落实）：**A. 上行 `interrupt` 新增可选 `scope`（A2）**——`{sessionId}` → `{sessionId, scope?}`，取值域 `{"", "all", "current"}`（**省略 / 空串 / `"all"` 三者同义**）：`all` = 取消当前任务 + 清空待处理队列（**逐字不变的现状语义**）；**`"current"` = 只取消当前任务、保留待处理队列**（队列消息按编排器正常续跑规则继续执行、带上会话尾部上下文）；**其余取值 → 只回发送者** `{type:"error",data:{code:"bad_request"}}`（**定向**：不广播、不打断任何会话，绝不静默按默认执行）；命中空闲会话为 no-op。下行 `session_interrupted` 帧形状**零变化**（`{sessionId, mode, dropped}`），但 `dropped` 恒等于**真的被丢弃**的待处理条数——`scope:"current"` 时为 `0`，且 `mode` 是该会话当时的**忙碌通道**（`thinking|executing|subagent`，**不是 `idle`**）；`scope:"all"` 时 `mode` 为 `idle`、`dropped` 为清空的 pending 条数。**B. REST `stream:true` 不再静默失败（G2，行为变更）**——该分支改为与 WS `chat` 帧**同一条直达编排器的路径**（design/15 §2.1「会话消息不得被 drop」），**响应面**：受理成功后才回 `200 {data:{stream:true}}` / 正忙已续接排队 `202 {data:{stream:true,queued:true,queueDepth:n}}` / 队列满 `409 {error:{code:"chat_busy"}}` / 幂等键重复 `200 {data:{duplicate:true,messageId,sessionId}}`；**未接 loop → `500 {error:{code:"chat_unavailable"}}`**（旧文写 `200 {stream:true}`，现与同步路径同口径）；仅**未接编排器**才回退总线派发，其失败回 `503 {error:{code:"chat_dispatch_failed"}}`（此前 `Publish` 的错误被吞掉，且传的是**请求作用域** ctx）。**`202`/`409` 从此真的会出现**（修复前因提前 `return 200` 永不出现）。派发用的回合上下文与请求作用域脱钩（`context.WithoutCancel` + 30 分钟上限），回合不会在客户端刚收到 200 时被连带取消。**向后兼容**：`stream:false` 与既有同步响应形状一字未动；依赖「任何情况都拿到 200」的客户端必须按上表分支，别再假设 `stream:true` 恒 `200`。**C. `chat.image` 上限（G3）**——`POST /api/v1/chat` 的 `image` 新增硬上限：**解码后 5 MiB**（与 `POST /api/v1/upload` 同口径；base64 字符串上限 = `ceil(n/3)*4 + 64` 字符，覆盖 data: URI 前缀），超限 → `400 {error:{code:"image_too_large", message}}`（文案指路 `POST /api/v1/upload`），在**任何解码 / 落库 / 入模型之前**拦下（超大 base64 因此不进历史、也不会被重连回放重传）。**事实（勿误读为「WS 也有这条 400」）**：WS `chat` 帧**今天已被传输层关死**——WS 读上限 `wsReadLimit = 4096` 字节/帧，超限直接断连，**到不了**这条判定 ⇒ **WS 上发真实图片本就必须「上传 + URL」**。**D. `clientMsgId` 幂等（G4）**——上行**新增可选** `clientMsgId`（REST `chat` 体与 WS `chat` 帧都支持；**省略 = 老行为逐字不变，老客户端零影响**）：同一会话内同一个非空值只承认第一条。**重复到达**：REST → `200 {data:{duplicate:true,messageId,sessionId}}`；WS → 新下行帧 **`chat_duplicate`**（`{type:"chat_duplicate", sessionId, data:{sessionId, clientMsgId, messageId}}`，见 §3.13）；重复**不落库、不起回合、不发任何内容 / 流式新帧**。**判重由 SQLite 部分唯一索引原子裁决**（`(session_id, client_msg_id) WHERE client_msg_id != ''`），并发的两次重发只有一个赢家，不存在「先查再插」的竞态窗口。`clientMsgId` 另**回填进消息 DTO** ⇒ `message_persisted` / `channel_persisted` / 握手 `history` 回放与 `GET /sessions/{id}/messages` 等读接口可见（空则省略），客户端据此把本地乐观气泡对齐到服务端真相（替代「靠文本相等」的脆弱匹配）。**迁移**：新增 `0013_chat_client_msg_id`（up：加列 + 部分唯一索引 `idx_chat_messages_client_msg_id`；down：先删索引再删列；全新库由 `history.NewStore` 幂等前滚）。**E. 视觉链路事实修正（F3）**——`chat.image` 的 http(s) URL（含 `/api/v1/files/`）现在由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再原样转给上游**；同源 upload 产物优先走**本地文件读取**。**类型裁决**：**字节嗅探是唯一裁决权**（声明的 Content-Type / 扩展名只作参考且可被否决），嗅探为文本（HTML / PROXY 错误页 / SVG）或判不定且来源未声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默当 PNG**。**对客户端无端点 / 帧 / 字段变更**。**F. 修正既有错误陈述（G1）**——`Docs/api-reference.md` §6.2 帧壳表与 §6.6 曾声称结构化流帧只带 `seq`、没有轮次标识，**是错的**：**v0.36 起**结构化流帧（`message.*` / `thinking.*` / `tool_call.*`）就带 `sessionId` + `turnId`（`broadcastStream` 从 `model.StreamEvent` 取，loop 在回合边界注入），v0.50 起另带 `streamId`；已按实现更正（与本文档 v0.36 条目一致）。**G. 环境变量登记**——`.env.example` 新增 **`OWNER_IDENTITY_INJECTION`**（`owner_only` 默认 / `always` / `off`；**非法值回退 `owner_only` 并记 WARN**），并登记 **`CONTEXT_MAX_TOKENS`**（默认 `32768`；`0` / 负 = 关闭压缩）与 **`GUARDRAIL_KEYWORDS`**（逗号分隔；留空 = 不挂关键词护栏），三键见 §2「安全 / 上下文环境变量（v0.56）」。**无新端点、无帧形状破坏**（唯一新增帧 `chat_duplicate` 为**纯新增**；REST `stream:true` 的响应面属**行为变更**，兼容点已在 B 写明）。**上一版 `v0.55`**：（**阶段 7 落地项登记：路径式安全入口 + 数据目录 `platform` + OneBot v11 四端 + 可观测实时推送**，依据裁决 1.6 / 16.4.7 / 12.4.2（commit `a398dc9`）、1.4 / 12.4.1（commit `9253fef`）、05.4.3 + 16.4.3-WS（commit `0e1f163`），以及 13.4.5 面内三条（commit `74b12d8`）、MCP 官方 SDK（commit `a1083a3`），2026-10-04 落实）：**A. 安全入口 `ADMIN_PATH`（裁决 1.6 / 16.4.7，前端路由面）**——① env 新增 **`ADMIN_PATH`**（默认 `admin`）：面板**前端**路由前缀 = `/` + 值（`admin` → `/admin`，`xxx/admin` → `/xxx/admin`；**非法值回退 `/admin`**——容忍首尾斜杠与空白，拒绝 `.`/`..` 段与 `?`/`#`）。② HTTP 行为：`/` 与其深链返回**注入了 `` 与 `window.__CYRENE_ADMIN_ENTRY__={"prefix":"..."}` 的 index.html**（`Cache-Control: no-store`）；**形如面板入口（路径里出现 `admin` 段）但前缀不符的路径 → `404`**（不回落用户端聊天壳、不泄露正确前缀）；`/` 若恰好命中 `dist` 真实文件则仍走文件服务器。③ **API 不藏**：`/api/v1/*`、`/api/v1/admin/*`、`/ws/chat`、webhook 一律原样，**无新端点、无帧变更**。④ **口径**：用户端 HTML **永不携带该前缀串**（后端只在命中前缀时注入）⇒ 用户端既无管理入口链接、也解析不出面板路由（design/07 §0.2；前端路由改**路径式**：`frontend/web/src/admin/router.ts` 只读注入、无硬编兜底、移除 hash 入口）。**B. 数据目录（同 commit，裁决 12.4.2）**——`DATA_DIR` 新增可接受值 **`platform`**（大小写不敏感）→ 平台标准目录；默认 `./data` 与显式路径行为不变；**显式空值行为不变**（仍走原兜底）。**C. OneBot v11 四端（`9253fef`，裁决 1.4 / 12.4.1）**——① 配置面（channels.json 账号 `config` + 适配器 `Config()` 快照）新增 `transport`（`ws`|`http`，默认 `ws`，未知值回落 `ws`）/ `api_base_url` / `report_path`（默认 `/`）；快照 camelCase 为 `transport`/`apiBaseURL`/`reportPath`；`remoteURL` 快照值 = `remote_url`、为空时回落 `api_base_url`（语义即「出站远端地址」），**既有键与值不变**。② env 兜底 `CHANNEL_QQ_OBV11_TRANSPORT`（默认 `ws`）/ `CHANNEL_QQ_OBV11_API_BASE_URL` / `CHANNEL_QQ_OBV11_REPORT_PATH`。③ 四端语义：`ws+client` Cyrene 拨号、收发同一 WS；`ws+server` OneBot 反连、收发同一 WS；`http+client` Cyrene→OneBot（`POST {api_base_url}/{action}`，纯出站）；`http+server` OneBot→Cyrene（POST 到 `listen_addr`+`report_path`，纯入站，fail-closed 鉴权、10MiB 体上限）。④ 取舍：`mode` 决定**哪一半必需**（server 必需 `listen_addr`、client 必需 `api_base_url`），另一半给齐字段就一并启用 ⇒ 单个适配器即可「收上报 + 回消息」。⑤ 端口例外：`http+server` 用 `listen_addr`，属 `AGENTS.md` §9 已登记的**同一豁免**（design/13 §0 原文即写「WS server / HTTP server」）；`listen_addr` 为空则报错、**绝不开端口**。**D. 可观测实时推送（`0e1f163`，裁决 05.4.3 + 16.4.3-WS）——新增一节 §3.12**：三个**下行新帧** `observability_log`（`{entries:[{time,level,source,msg}…]}`，最新在前，上限 200 条）/ `observability_trace`（`{spans:[…]}`，上限 100 条）/ `observability_metrics`（`AdminMetrics` 本体、扁平），均**纯新增**（既有帧名/形状零改动）、帧壳**不带** `sessionId`/`turnId`/`seq`；三者**不在** `frameReachesAll` 白名单 ⇒ fail-closed **只发 owner+admin**（viewer 继续走 REST 只读档）；订阅 = owner/admin 凭据**读取** `GET /admin/observability/{logs,metrics,trace}` 任一个（该次读取照常返回完整引导数据），该凭据 WS 连接全断即退订并停循环（**不是轮询、无常驻 goroutine**）；**REST 端点完全不变**，`?level=` 分级过滤改由**客户端本地**做（帧广播给所有 `owner`/`admin` 连接，订阅只决定循环跑不跑）。**E. 其余（各一句）**：① **13.4.5 面内三条**（`74b12d8`）——续接窗口 `Recent` 在同毫秒并列时改为取**最新** n 条且按插入序（**无 API 变化**，但客户端可观察到的「握手回放 / 续接上下文」顺序更正确）；上行 `chat` 不再经**可丢弃**的 bus（**帧序列不变**）；被**取消**回合的 checkpoint 不再顶掉下一条消息，新增内部常量 `loop.StopReasonCanceled`（`checkpoints.state.stop_reason` 可能出现该值，**不经 REST/WS 暴露**）。② **MCP**（`a1083a3`）——协议层换成**官方 Model Context Protocol Go SDK v1.8.0**，**REST/WS/env/数据目录零变更**（`MCP_SERVERS_JSON`、`MCP_*`、`transport` 枚举 `stdio|http|streamable|sse` 全不变）。**未做（诚实边界）**：DashScope 形状的 `auto` 推断、Qwen 的 `/think` 前导消息软开关、`get_group_list` 枚举、上游显式退订帧（当前退订只发生在订阅凭据的连接全断时）、审计 tab 仍 5s REST 轮询（未做 `observability_audit` 帧）。**上一版 `v0.54`**：（**渠道配置写路径改 patch 语义（修 P0 级凭据静默丢失） + 阶段 6 前端批的纯前端行为登记**，依据 design/04 §3.1、design/22 §2 方案 b（与 `personaId` 同构的裁决延续，commit `4ae7148`）与裁决 16.4.1 / 16.4.2 / 16.4.3 / 16.4.4 / 16.4.5 / 16.4.6（commit `f454273` / `b480b04` / `c1a98d7` / `8d70f6d`））：① **`PUT /api/v1/admin/channels/{platform}/config` 的 `config` 由「整条替换」改为「按 id 打补丁」**（`runtimeconfig.PatchChannel`，**与 `personaId` 同构的三态**）——**键省略（该键不在 `config` 里，或 `config` 整体缺席 / 为 `null`）= 保留该账号已存值**、**给出非空值 = 覆盖该键**、**显式 `null` 或 `""` = 清除该键**（`0` / `false` 是真实取值，**不算空**）；顶层便捷字段（`token` / `baseURL` / …）是普通 `string`，**只在非空时**并入补丁 ⇒ **要清除 `bot_token` 必须走 `config` 的显式 `null` / `""`**；`allowGroups` / `denyGroups` / `allowUsers` / `denyUsers` 与三个限流键**仍是整值替换**（省略 = 清空）。② **破坏性提示**：按旧文实现、依赖「省略某 `config` 键 = 删掉它」的客户端，必须改为**显式传 `null` / `""`** 才能清除该键。③ **修掉的数据安全问题**：面板只发送用户本次碰过的平台字段，后端却整条替换 ⇒ 保存**微信(iLink)**账号卡会抹掉 `bot_token` / `bot_id` / `owner_id` / `get_updates_buf`（**iLink token 是长期凭据**）、**Telegram** 只填 `webhook_url` 而不重填 token 会让 `cleanAccounts` **丢掉整个账号**。④ **未改**：token 要求型平台**显式**清 token 仍按 `cleanAccounts` 丢账号；「本次一个 `config` 键都没给出」在**非 `weixin-ilink`** 平台仍回 `400`。⑤ **无新端点 / 新字段 / 响应形状变更**。**同版另含阶段 6 前端批（纯前端行为，无 API 变化）**：① **16.4.1 静默/活动态与预约切换**——唯一入口 `frontend/web/src/components/modeSwitch.ts`：她活动时用户切换只登记「已预约」、静默时落地；② **16.4.5 会话级消息缓存**——帧按自己的 `sessionId` 落进该会话的消息桶（切会话不清空），**只有单槽忙态**仍按激活会话判定；`graph_update` 按 `data.sessionId` 入**图桶**，管理端 Flow 页取激活会话、Backthink 页取 `sess-backthink`（裁决 16.4.2）；③ **16.4.3 / 16.4.6 虚拟滚动与专属页只读卡**——长列表超阈值窗口化、专属页只读展示该平台完整字段；④ **16.4.4 双档 UI 模式**——性能档 = 现状（默认）、华丽档落 `:root.ui-mode-fancy`，持久化键 `cyrene.ui-mode`（纯前端，对应 `design/07 §0.1`，不改后端契约）。**上一版 `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`）。 +> **契约版本 `v0.60`**（**管理侧只读「存储状态」端点 + 面板存储卡接真数据**，依据主人 2026-10-04 实测反馈（面板首页「存储」卡一直是占位「SQLite」）与 design/10 §3 模块 14（系统设置）/ design/03 §3（pgvector 可选增强），2026-10-04 落实）：**A. 新增 `GET /api/v1/admin/system/storage`**（**owner-only**、只读、**无审计动作**）→ `200 {data:{main,documents,vector}}`——① `main` = `{kind:"sqlite",path,fileBytes,walBytes,shmBytes,pageSize,pageCount,freelistPages,freeBytes}`（`path` 与备份/恢复端点同源；`walBytes`/`shmBytes` 边车不存在时如实为 `0`；`freeBytes = pageSize × freelistPages`）；② `documents` = `{count,bytes}`（读 `documents` 表，**不 walk 目录**；空表 `bytes` 为 `0` 而非 `null`）；③ `vector` = `{kind:"pgvector"|"none",enabled,ready}`——`kind` 说「配没配 `DB_PG_URL`」，`ready` 说「现在真的在跑什么」（配了但连接/schema 准备失败 ⇒ `enabled:true` + `ready:false`，客户端显示「已配置但未就绪（检索已降级）」，**别把 `enabled` 当生效**）。**B. 两条纪律**：① **不含凭据**——DSN / 用户名 / 密码 / `postgres://` 全文**一个字都不回**（`vector` 段只有三个键；有用例断言响应体里搜不到这些串）；② **只读**——只有 `SELECT`/`PRAGMA` + `os.Stat`，复用组合根注入的**活连接**（不新开连接池、不写、不迁移、不备份，调用前后 `documents` 行数与数据目录文件集合均不变）。**C. `vector` 的真源**：组合根 `cmd/cyrene/wire_frontend.go` 的 `app.vectorState()` —— `Configured` 取 `DB_PG_URL` 非空、`Live` 取活索引的具体类型（`*vector.PGVectorIndex`）；网关**只读这份注入值**，不读环境变量、不新开 PG 连接、不自行探测（避免面板与运行时给出两个答案）。**D. 失败不伪装**：未接活连接 / 路径未配置 / 读不到页级统计或 `documents` 表（例如库没跑迁移）⇒ `500 {error:{code:"storage_unavailable",message}}`，**绝不回一个全 0 的假快照**。**E. 面板**：`frontend/web` 的存储卡改为真数据（`value` = `SQLite 12.3 MiB`；`hint` = WAL / 页数 / 空闲页；详情两行 = `documents N 件 · …` 与 `PG 增强 …`），取数走与其它已接线卡片**同一条**加载/错误态（数据没到就显示「端点报错：…」，不回退成 `0`）。**F. 兼容性**：**纯新增端点 + 纯新增前端行为**，既有端点 / WS 帧 / 字段形状**一字未动**（前端 `MiniMetricSpec` 新增的 `extra?: string[]` 为可选补充详情行，不传时渲染与旧版逐字等价）。**上一版 `v0.59`**：（**文档进对话（`F1/F2`）+ 上下文预算按窗口推导（`T1`）+ 语音回合进编排（`G5/C1/C3`）+ `thinking` 可达性口径**，依据 design/24 §3/§4/§6（切片 S1–S5）、design/04 §1.3 + 附录 A.3（主人裁决 2026-10-04）与 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 G5/C1/C3，commit `a8851dc` / `a4789ec` / `20c1edb` / `5b2b385` / `72b95df` / `3a01b4e`，2026-10-04 落实）：**A. 文档存储与摄取（两个新端点 + 一个可选请求字段 = 纯增量；DTO 形状变更是破坏性，但单数形状从未发布，故无兼容期）**——① **新增 `POST /api/v1/documents`**（owner|admin，`multipart/form-data`，字段 `file`）→ 首次 `201 {data:{name,url,mime,size,sha256,deduped:false}}`；**同字节同扩展名重复上传 → `200` + 同一 `name` + `deduped:true`**（客户端可当成功处理）；单文件上限 **`CHAT_DOCUMENT_MAX_BYTES`（默认 20 MiB = 20971520）**，`≤0` 视为用默认；它与图片上限 `CHAT_IMAGE_MAX_BYTES` **刻意解耦**（改文档上限不会静默改掉图片行为）。② **新增 `GET /api/v1/documents/{name}`**：**必须带 Bearer（owner|admin）**——与图片读侧（免鉴权的能力 URL）**刻意相反**（文档摄取在服务端完成，不需要被 ``/provider 直接消费），响应带 `Content-Disposition: attachment` + `X-Content-Type-Options: nosniff`（浏览器永不内联渲染）。③ **类型裁决（重要）**：**字节嗅探是唯一裁决者**（`http.DetectContentType`，放行的嗅探基类型只有 `text/plain`），**客户端声明的 `Content-Type` 与原始文件名只作参考、可被嗅探否决**；**扩展名白名单 deny-by-default，实际 **22** 个**：`.txt .md .markdown .csv .tsv .json .jsonl .yaml .yml .log .ini .cfg .toml .go .ts .tsx .java .c .h .cpp .rs .sql`（⚠️ design/24 §9.2 写「23 项」但所列清单与代码均为 **22** 项，**以代码 22 为准**，见 §1.2「发现的不一致」）；**明令拒绝** `text/html`、SVG/XML、zip 及其封装（docx/xlsx）、可执行/脚本（exe/dll/bat/cmd/ps1/js/mjs/sh/py）——即便 `.js`/`.py` 嗅探成 `text/plain` 也拒（判定 = 扩展名 ∧ 嗅探的**合取**）。④ **边界（勿与图片混用）**：`url` 是**相对路径**（`/api/v1/documents/<32hex>.`；图片侧是绝对 URL）；`mime` 是**嗅探所得基类型**（故 `data.json` 返回 `text/plain`，不是 `application/json`）；落盘名 = `sha256(bytes)[:32] + ext`（**内容寻址**，原始文件名永不参与路径 ⇒ 同字节同扩展名天然同名去重）。⑤ **4 个错误码**：`unsupported_media_type`(415) / `document_too_large`(413) / `document_not_found`(404，含名字形态非法与路径穿越) / `too_many_documents`(400)。⑥ **`chat` 请求新增可选 `"documents":[{"name":"<32hex>."}]`**（REST 同步 / REST `stream:true` / WS `chat` **三处同形**）：**≤5 条**（超出 `too_many_documents` 400，且**先于任何文件系统访问**）；**只收服务端存储名、绝不收 URL**（不重开 F3 那种「服务端代取 URL」的 SSRF 面）；客户端多带的 `mime/url/size` **一律被服务端覆盖**（MIME/大小取自落盘字节）；名非法/穿越/不存在 → `document_not_found`(404)；**任一条不合规都让整个请求被拒**，绝不「丢掉这条附件但照样起回合」（WS 侧经 `error` 帧带 `data.code` 下发并中止本回合，REST 侧回对应状态码）。⑦ **响应 / 历史 DTO 由 `document`（单对象）改为 `documents`（数组，≤5）**——元素形状 `{"name","mime","size","chars","truncated","status"}`，`status ∈ extracted|listed|unreadable`；**0 个附件时该键省略**；同一 DTO 供 `GET /sessions/{id}/messages`、`message_persisted`、`message_edited`、WS 握手回放 **四处同时生效**（同一个 `historyMessage` 结构）。⚠️ **原单数形状从未发布过**（不在任何已发布版本号里）⇒ **无兼容期**，直接换数组（design/24 §6.1 那句 `"document":{…}` 已随之作废）。⚠️ **`chars`/`truncated` 改为「本回合注入侧」语义**：`chars` = **本回合注入**模型上下文的字符数、`truncated` = **注入**是否被截断（**不是**「原文件是否被截断」）；**全文长度**只有 `document-read` 的 `totalChars` 能看到。⑧ **内置工具 `document-read`**（模型侧工具，客户端一般只需知道它存在）：`{name, offset?, limit?}` → `{name,status,offset,limit,totalChars,truncated,nextOffset,text,extractTruncated?}`；`limit` 默认 **8000** 字符、上限 **64K**；`offset` 单位是**字符（rune）**、0 基、起点 = sidecar 正文（含 CSV/TSV 摘要行）第 0 个字符；`offset<0` 或 `>totalChars` → 错误（`==totalChars` 合法，读到末尾空片段）；`extractTruncated=true` **专指**「撞上 8 MiB sidecar 安全上限」（≠ 本回合注入被截断）；策略默认 **owner-only**（群聊/陌生人天然读不到主人的文件）。**B. 配置面（纯增量 + 一处语义变更）**——① **`models.json` 组级新增 `contextWindow`**（正整数 = 该组模型的上下文窗口；`0`/省略 = 未声明 ⇒ 后端按 **131072** 保守估算并记**恰好一条** WARN；**负数 = 组校验失败**，写端点回 `400`）。 ② **`.env` 新增/变更 4 键**：`LLM_CONTEXT_WINDOW`（**per-group 播种**，等价于 `models.json` 的 `contextWindow`）、`CONTEXT_BUDGET_RATIO`（默认 **2/3**，接受 `2/3` 或 `0.6667`，非法值记 WARN 后回落）、`DOCUMENT_MAX_INJECT_CHARS`（单份附件注入上下文的字符上限；未设 = 按推导出的预算自动算）、**`CONTEXT_MAX_TOKENS` 语义变更（关键）**：**未设置 ⇒ 按窗口推导**（`budget = min(窗口 × 比例, 窗口 − 输出保留)`，输出保留 = `max(32768, 该组 maxTokens)` 且**封顶 `窗口/2`**；**1M 窗口 ⇒ 699050 tokens**）；`>0` = 显式覆盖（原样使用）；`0`/负 = **关闭压缩**。⇒ **`.env` 里若仍写着 `CONTEXT_MAX_TOKENS=32768`，它就是显式覆盖、推导不生效**（这是设计语义，**不是 bug**；本次已把 `.env.example` 里该行改成注释形式）。③ **`.env` → 面板配置的 materialize 语义（欠账，本次补登记）**：进程**每次启动**跑一次；**面板配置非空 ⇒ 组集合完全由面板决定**（env 不新增、不复活被面板删掉的组）；**键级只在面板缺该键时用 env 补**，面板已有的键（含**显式空值 / 显式 `false` / 显式 `null`**）**绝不覆盖**；面板配置缺失/为空时才由 env 播种出合成组；**「面板改一次、重启被打回」是硬约束**（有专门用例钉住）；每次启动记「补了哪些 / 跳了哪些」，**凭据绝不进日志**；范围目前**仅 `models.json` 一族**（`channels.json` / `plugins.json` 未纳入）。④ **面板读写面**：`GET /api/v1/admin/llm` 的组 DTO **含 `contextWindow`**（`omitempty`，与 `maxTokens` 同形：未声明时该键省略），`POST /api/v1/admin/llm` **接受可选 `contextWindow`**——**缺失 = 保留已存窗口**、**显式 `0` 与缺失同义**（都 = 未声明）、**负值 `400 bad_request` 且不落盘**；面板 LLM 页据此显示/编辑该键。**C. 语音（有行为变更，见 §3.15）**——语音轮次**现在走与文本同一条路径**：会**落库**（用户消息 = 转写文本，助手消息 = 回复）、会发 `message_persisted` 与流式帧、**跨端同步**、忙时按编排器既有规则**排队**（`pending_ack`/`pending_drain`/`session_busy` 语义零变化，只是多了一个消费者）；`deviceId` 照旧落库、`platform` 走存储默认 `web`；`voice_input` 上行增可选 `clientMsgId`（与 `chat` 帧同形 ⇒ 语音也有幂等；重复到达回既有 `chat_duplicate`，**不产生新回合、不发音频**）；`voice_output`（定向）载荷增 `sessionId`（恒有）与 `deviceId`（非空才有）；**空正文**与 **TTS 失败/降级**都走既有 `provider` 降级信号（客户端据此提示「没生成声音」；**不再**把 `stopReason` 当语音内容）；**时点**：`voice_output` 在**该回合结算时**才到（可能晚于若干状态帧，甚至由续跑回合或被 steer 注入的那一回合产生）；定向目标是**发起 `voice_input` 的那条连接本身**（服务端**不按 deviceId 路由**）；连接断开后**不补投**，客户端重连后带上同一 `clientMsgId` 可安全重试。**D. `G5`（纯增量：广播帧 +2 个可选键；新增一条定向错误帧，见 §3.2）**——① **`pending_full` 广播载荷**增 `clientMsgId?` / `messageId?`：前者 = **被拒那条消息**的幂等键（未携带则**整个键缺席**）；后者**仅当该消息此前已落库/已认领时**才回填——**服务端绝不在此处新铸 id**（队列满的拒绝发生在幂等键认领之前，代铸会让客户端重试被判成「重复到达」而永远进不来）。② **新增定向帧（此前无文档登记）**：`{type:"error", data:{code:"chat_busy", message, sessionId, clientMsgId?, messageId?}}`，**只发发送者那条连接**、不广播；`code` 与 REST `409 chat_busy` **同码**（客户端一个 code 覆盖两条入口）。**E. `E3`：`thinking` 可达性口径（不改行为，只是把话说清）**——消息体的 **`thinking` 字段**在**实时帧**（`message_persisted` / `channel_persisted` / `message_edited`）与**握手回放**中**一律为空**（隐私与带宽的**有意**默认；实时思维链仍由 §3.1 的 `thinking.*` 流帧按 owner/admin 档下发）；**历史消息的思维链**只有 `GET /sessions/{id}/messages`（owner|admin）返回。**上一版 `v0.58`**：（**新增 `.env` 键 `LLM_MULTIMODAL`（`bool`，默认 `false`）：让 env-only 部署能声明「主模型自身能否收图」**，依据裁决 14.4.1 / design/06 §0（commit `4adfc9a`），2026-10-04 落实）：**A. 新键语义（见 §2「模型配置契约」表）**——**`LLM_MULTIMODAL` 是 `models.json` 组 `multimodal` 的 env 等价物**，**只作用于 `.env` 合成组**（**无有效 `models.json` 时才生效**；有组文件时以该组的 `multimodal` 为准，与 `LLM_REASONING_KIND` 同口径）：`true` = 图片**直进主模型上下文**（省掉工具那一轮模型调用、也不做有损文本摘要），**留空 / `false`（默认）= 把图交给 vision/OCR 工具换成文本描述**；**绝不凭 base URL / 模型名猜测**端点是否收图（声称端点不具备的能力，比把图交给工具更糟——工具至少回一段文本，design/06 §0 首条）。**B. 与 `LLM_VISION_MODEL` / `LLM_OCR_MODEL` 的关系**——后两者配的是**视觉/OCR 工具调用的模型**，**不代表主模型能收图**，与本键互不代表（见 §1 行 3）。**C. 兼容性（默认值即旧行为）**——默认 `false` ⇒ **老部署行为逐字不变**（引入本键之前，env-only 部署没有任何键能声明该能力，图片恒走 vision 工具）；**非 bool 值（如 `maybe`）在配置解码阶段直接报错、启动失败**（fail-fast，**不静默回退成 `false`**——静默的「配了当没配」正是本键要消灭的）。**`LLM_MULTIMODAL=true` 后图片走主模型直收，属部署者显式选择**（形状由部署者声明，后端不替它猜）。**D. 实现落点**——`internal/config/config.go`（`LLMConfig.Multimodal`，默认 `false`）+ `internal/config/runtimeconfig/models.go`（`GroupFromEnv` 把两 provider 分叉都透传进合成组）+ `internal/config/runtimeconfig/multimodal_env_test.go`（默认 false / 显式 true 抵达合成组 / 进程 env 端到端 / 组文件优先 四组测试）。**无端点、无帧、无字段形状变更**（纯新增 env 键）。**上一版 `v0.57`**：（**13.4.5 目标态 steer 落地登记：新下行帧 `steer_ack`**，依据 design/15 §2.0/§2.1/§2.4/§3.x/§5（裁决 13.4.5 目标态，commit `3d8822c`），2026-10-04 落实：**A. 新下行帧 `steer_ack`（见 §3.14）**——`{type:"steer_ack", sessionId, data:{messageId, atStep}}`：忙时会话里新到的用户消息**被在飞回合吃进同一回合**时下发（`messageId` = 那条用户消息的**权威 id**，`atStep` = 吃进它的**模型步序号，1 基**）；语义＝「**该消息已被本回合吃进（已从 pending 移除）、尚未被正面回答**」⇒ 客户端应把对应气泡渲染为「已读、未答」的**灰态**，直到该回合的 `message.*` / `turn.end` 到达（**不需要第二个确认帧**）。**角色门**：它**携带具体消息身份**（客户端能定位到某一条气泡，而不只是会话忙闲），因此**不登记**进 `frameReachesAll` 的 7 个状态机信号白名单，落 fail-closed 默认档——**只发 `owner` + `admin`**（`viewer` 收不到）；经编排器状态通道**由 hub 直接广播、不经 bus**，帧壳带 `sessionId`、**不带** `turnId`/`seq`。**触发时机**：只在**回合内边界**（loop 每一步开头：上一次模型步与它那一批工具调用**都已结束**、下一次模型调用**尚未开始**，此刻没有工具在飞）产生，且**只有该边界真的匹配到 pending 里、且已落库的消息时才发**——**不是每个 step 都发**（没可注入消息的边界一帧都不发，这是常态）。**B. 转向的三条不变量（design/15 §2.0）**——**I1（同会话在途回合数恒为 1）**：转向只注入、不取消，**绝不新开第二个回合**（loop 侧结构性地没有任何「起新回合」的分支，注入只是把消息并进**当前回合**下一次模型调用的视图）；**I2（消息恰好被处理一次）**：注入＝已消费——被注入的消息立刻从该会话 pending **移除**（按 pending 序号认领），**绝不被第二个回合再答一遍**，去重键＝后端 `message.id`，且候选必须**同时**满足「在该会话转录里（最近 20 条窗口内）」与「在本编排器的 pending 里」；**I3（转向不取消已发起的工具）**：注入点只在回合内边界，此刻没有任何工具在飞，正在执行的工具**永远跑完**。**C. 注入的范围（口径）**：注入**只影响本轮视图**（每一步边界重新并入），**不写回运行窗口** ⇒ 既不进该回合的 **checkpoint 快照**、也不进**后台记忆提取的输入面**；被注入的消息**本身早在到达时已落库**（pending 路径即时持久化），注入**不新增、也不改写任何行**。**D. 失败一律让路**：未接转录存储 / 读转录失败 / 该消息尚未落库 / 本回合世代已被打断或被更新的回合取代（认领 `pending` 失败）时，**不发 `steer_ack` 也不注入**——该消息**留在 pending**，照旧作为自己的回合被回答，**绝不静默消失**。**E.** 另含一处**链路图纯增量键**（注入时该轮图的 input 节点带 `props.steered:true`，图仍只有一条主干——不是被画成第二轮），以及**纯新增帧**的兼容性口径（老客户端按未知帧忽略即可）。**上一版 `v0.56`**：（**协同项 A2 / G1 / G2 / G3 / G4 / F3 落地登记：`interrupt` 支持 `scope` + REST `stream:true` 不再静默失败 + `chat.image` 上限 + `clientMsgId` 幂等 + 视觉链路 URL 取回与类型裁决 + 既有错误陈述更正**，依据 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 A2 / G1 / G2 / G3 / G4 / F3（commit `7512d59` 等，2026-10-04 落实）：**A. 上行 `interrupt` 新增可选 `scope`（A2）**——`{sessionId}` → `{sessionId, scope?}`，取值域 `{"", "all", "current"}`（**省略 / 空串 / `"all"` 三者同义**）：`all` = 取消当前任务 + 清空待处理队列（**逐字不变的现状语义**）；**`"current"` = 只取消当前任务、保留待处理队列**（队列消息按编排器正常续跑规则继续执行、带上会话尾部上下文）；**其余取值 → 只回发送者** `{type:"error",data:{code:"bad_request"}}`（**定向**：不广播、不打断任何会话，绝不静默按默认执行）；命中空闲会话为 no-op。下行 `session_interrupted` 帧形状**零变化**（`{sessionId, mode, dropped}`），但 `dropped` 恒等于**真的被丢弃**的待处理条数——`scope:"current"` 时为 `0`，且 `mode` 是该会话当时的**忙碌通道**（`thinking|executing|subagent`，**不是 `idle`**）；`scope:"all"` 时 `mode` 为 `idle`、`dropped` 为清空的 pending 条数。**B. REST `stream:true` 不再静默失败（G2，行为变更）**——该分支改为与 WS `chat` 帧**同一条直达编排器的路径**（design/15 §2.1「会话消息不得被 drop」），**响应面**：受理成功后才回 `200 {data:{stream:true}}` / 正忙已续接排队 `202 {data:{stream:true,queued:true,queueDepth:n}}` / 队列满 `409 {error:{code:"chat_busy"}}` / 幂等键重复 `200 {data:{duplicate:true,messageId,sessionId}}`；**未接 loop → `500 {error:{code:"chat_unavailable"}}`**（旧文写 `200 {stream:true}`，现与同步路径同口径）；仅**未接编排器**才回退总线派发，其失败回 `503 {error:{code:"chat_dispatch_failed"}}`（此前 `Publish` 的错误被吞掉，且传的是**请求作用域** ctx）。**`202`/`409` 从此真的会出现**（修复前因提前 `return 200` 永不出现）。派发用的回合上下文与请求作用域脱钩（`context.WithoutCancel` + 30 分钟上限），回合不会在客户端刚收到 200 时被连带取消。**向后兼容**：`stream:false` 与既有同步响应形状一字未动；依赖「任何情况都拿到 200」的客户端必须按上表分支，别再假设 `stream:true` 恒 `200`。**C. `chat.image` 上限（G3）**——`POST /api/v1/chat` 的 `image` 新增硬上限：**解码后 5 MiB**（与 `POST /api/v1/upload` 同口径；base64 字符串上限 = `ceil(n/3)*4 + 64` 字符，覆盖 data: URI 前缀），超限 → `400 {error:{code:"image_too_large", message}}`（文案指路 `POST /api/v1/upload`），在**任何解码 / 落库 / 入模型之前**拦下（超大 base64 因此不进历史、也不会被重连回放重传）。**事实（勿误读为「WS 也有这条 400」）**：WS `chat` 帧**今天已被传输层关死**——WS 读上限 `wsReadLimit = 4096` 字节/帧，超限直接断连，**到不了**这条判定 ⇒ **WS 上发真实图片本就必须「上传 + URL」**。**D. `clientMsgId` 幂等（G4）**——上行**新增可选** `clientMsgId`（REST `chat` 体与 WS `chat` 帧都支持；**省略 = 老行为逐字不变，老客户端零影响**）：同一会话内同一个非空值只承认第一条。**重复到达**：REST → `200 {data:{duplicate:true,messageId,sessionId}}`；WS → 新下行帧 **`chat_duplicate`**（`{type:"chat_duplicate", sessionId, data:{sessionId, clientMsgId, messageId}}`，见 §3.13）；重复**不落库、不起回合、不发任何内容 / 流式新帧**。**判重由 SQLite 部分唯一索引原子裁决**（`(session_id, client_msg_id) WHERE client_msg_id != ''`），并发的两次重发只有一个赢家，不存在「先查再插」的竞态窗口。`clientMsgId` 另**回填进消息 DTO** ⇒ `message_persisted` / `channel_persisted` / 握手 `history` 回放与 `GET /sessions/{id}/messages` 等读接口可见（空则省略），客户端据此把本地乐观气泡对齐到服务端真相（替代「靠文本相等」的脆弱匹配）。**迁移**：新增 `0013_chat_client_msg_id`（up：加列 + 部分唯一索引 `idx_chat_messages_client_msg_id`；down：先删索引再删列；全新库由 `history.NewStore` 幂等前滚）。**E. 视觉链路事实修正（F3）**——`chat.image` 的 http(s) URL（含 `/api/v1/files/`）现在由**服务端自己取回并内联为 `data:` URI** 再交 provider，**不再原样转给上游**；同源 upload 产物优先走**本地文件读取**。**类型裁决**：**字节嗅探是唯一裁决权**（声明的 Content-Type / 扩展名只作参考且可被否决），嗅探为文本（HTML / PROXY 错误页 / SVG）或判不定且来源未声明 `image/*` → **明确报错**（`vision.ErrNotImage`），**绝不静默当 PNG**。**对客户端无端点 / 帧 / 字段变更**。**F. 修正既有错误陈述（G1）**——`Docs/api-reference.md` §6.2 帧壳表与 §6.6 曾声称结构化流帧只带 `seq`、没有轮次标识，**是错的**：**v0.36 起**结构化流帧（`message.*` / `thinking.*` / `tool_call.*`）就带 `sessionId` + `turnId`（`broadcastStream` 从 `model.StreamEvent` 取，loop 在回合边界注入），v0.50 起另带 `streamId`；已按实现更正（与本文档 v0.36 条目一致）。**G. 环境变量登记**——`.env.example` 新增 **`OWNER_IDENTITY_INJECTION`**（`owner_only` 默认 / `always` / `off`；**非法值回退 `owner_only` 并记 WARN**），并登记 **`CONTEXT_MAX_TOKENS`**（默认 `32768`；`0` / 负 = 关闭压缩）与 **`GUARDRAIL_KEYWORDS`**（逗号分隔；留空 = 不挂关键词护栏），三键见 §2「安全 / 上下文环境变量（v0.56）」。**无新端点、无帧形状破坏**（唯一新增帧 `chat_duplicate` 为**纯新增**；REST `stream:true` 的响应面属**行为变更**，兼容点已在 B 写明）。**上一版 `v0.55`**：（**阶段 7 落地项登记：路径式安全入口 + 数据目录 `platform` + OneBot v11 四端 + 可观测实时推送**，依据裁决 1.6 / 16.4.7 / 12.4.2（commit `a398dc9`）、1.4 / 12.4.1（commit `9253fef`）、05.4.3 + 16.4.3-WS（commit `0e1f163`），以及 13.4.5 面内三条（commit `74b12d8`）、MCP 官方 SDK（commit `a1083a3`），2026-10-04 落实）：**A. 安全入口 `ADMIN_PATH`（裁决 1.6 / 16.4.7，前端路由面）**——① env 新增 **`ADMIN_PATH`**（默认 `admin`）：面板**前端**路由前缀 = `/` + 值（`admin` → `/admin`，`xxx/admin` → `/xxx/admin`；**非法值回退 `/admin`**——容忍首尾斜杠与空白，拒绝 `.`/`..` 段与 `?`/`#`）。② HTTP 行为：`/` 与其深链返回**注入了 `` 与 `window.__CYRENE_ADMIN_ENTRY__={"prefix":"..."}` 的 index.html**（`Cache-Control: no-store`）；**形如面板入口（路径里出现 `admin` 段）但前缀不符的路径 → `404`**（不回落用户端聊天壳、不泄露正确前缀）；`/` 若恰好命中 `dist` 真实文件则仍走文件服务器。③ **API 不藏**：`/api/v1/*`、`/api/v1/admin/*`、`/ws/chat`、webhook 一律原样，**无新端点、无帧变更**。④ **口径**：用户端 HTML **永不携带该前缀串**（后端只在命中前缀时注入）⇒ 用户端既无管理入口链接、也解析不出面板路由（design/07 §0.2；前端路由改**路径式**：`frontend/web/src/admin/router.ts` 只读注入、无硬编兜底、移除 hash 入口）。**B. 数据目录（同 commit，裁决 12.4.2）**——`DATA_DIR` 新增可接受值 **`platform`**（大小写不敏感）→ 平台标准目录；默认 `./data` 与显式路径行为不变；**显式空值行为不变**（仍走原兜底）。**C. OneBot v11 四端（`9253fef`，裁决 1.4 / 12.4.1）**——① 配置面（channels.json 账号 `config` + 适配器 `Config()` 快照）新增 `transport`（`ws`|`http`，默认 `ws`，未知值回落 `ws`）/ `api_base_url` / `report_path`（默认 `/`）；快照 camelCase 为 `transport`/`apiBaseURL`/`reportPath`；`remoteURL` 快照值 = `remote_url`、为空时回落 `api_base_url`（语义即「出站远端地址」），**既有键与值不变**。② env 兜底 `CHANNEL_QQ_OBV11_TRANSPORT`（默认 `ws`）/ `CHANNEL_QQ_OBV11_API_BASE_URL` / `CHANNEL_QQ_OBV11_REPORT_PATH`。③ 四端语义：`ws+client` Cyrene 拨号、收发同一 WS；`ws+server` OneBot 反连、收发同一 WS；`http+client` Cyrene→OneBot（`POST {api_base_url}/{action}`，纯出站）；`http+server` OneBot→Cyrene（POST 到 `listen_addr`+`report_path`，纯入站，fail-closed 鉴权、10MiB 体上限）。④ 取舍：`mode` 决定**哪一半必需**（server 必需 `listen_addr`、client 必需 `api_base_url`），另一半给齐字段就一并启用 ⇒ 单个适配器即可「收上报 + 回消息」。⑤ 端口例外：`http+server` 用 `listen_addr`，属 `AGENTS.md` §9 已登记的**同一豁免**（design/13 §0 原文即写「WS server / HTTP server」）；`listen_addr` 为空则报错、**绝不开端口**。**D. 可观测实时推送（`0e1f163`，裁决 05.4.3 + 16.4.3-WS）——新增一节 §3.12**：三个**下行新帧** `observability_log`（`{entries:[{time,level,source,msg}…]}`，最新在前，上限 200 条）/ `observability_trace`（`{spans:[…]}`，上限 100 条）/ `observability_metrics`（`AdminMetrics` 本体、扁平），均**纯新增**（既有帧名/形状零改动）、帧壳**不带** `sessionId`/`turnId`/`seq`；三者**不在** `frameReachesAll` 白名单 ⇒ fail-closed **只发 owner+admin**（viewer 继续走 REST 只读档）；订阅 = owner/admin 凭据**读取** `GET /admin/observability/{logs,metrics,trace}` 任一个（该次读取照常返回完整引导数据），该凭据 WS 连接全断即退订并停循环（**不是轮询、无常驻 goroutine**）；**REST 端点完全不变**，`?level=` 分级过滤改由**客户端本地**做（帧广播给所有 `owner`/`admin` 连接，订阅只决定循环跑不跑）。**E. 其余（各一句）**：① **13.4.5 面内三条**（`74b12d8`）——续接窗口 `Recent` 在同毫秒并列时改为取**最新** n 条且按插入序（**无 API 变化**，但客户端可观察到的「握手回放 / 续接上下文」顺序更正确）；上行 `chat` 不再经**可丢弃**的 bus（**帧序列不变**）；被**取消**回合的 checkpoint 不再顶掉下一条消息，新增内部常量 `loop.StopReasonCanceled`（`checkpoints.state.stop_reason` 可能出现该值，**不经 REST/WS 暴露**）。② **MCP**（`a1083a3`）——协议层换成**官方 Model Context Protocol Go SDK v1.8.0**，**REST/WS/env/数据目录零变更**（`MCP_SERVERS_JSON`、`MCP_*`、`transport` 枚举 `stdio|http|streamable|sse` 全不变）。**未做（诚实边界）**：DashScope 形状的 `auto` 推断、Qwen 的 `/think` 前导消息软开关、`get_group_list` 枚举、上游显式退订帧（当前退订只发生在订阅凭据的连接全断时）、审计 tab 仍 5s REST 轮询（未做 `observability_audit` 帧）。**上一版 `v0.54`**：（**渠道配置写路径改 patch 语义（修 P0 级凭据静默丢失） + 阶段 6 前端批的纯前端行为登记**，依据 design/04 §3.1、design/22 §2 方案 b（与 `personaId` 同构的裁决延续，commit `4ae7148`）与裁决 16.4.1 / 16.4.2 / 16.4.3 / 16.4.4 / 16.4.5 / 16.4.6（commit `f454273` / `b480b04` / `c1a98d7` / `8d70f6d`））：① **`PUT /api/v1/admin/channels/{platform}/config` 的 `config` 由「整条替换」改为「按 id 打补丁」**（`runtimeconfig.PatchChannel`，**与 `personaId` 同构的三态**）——**键省略（该键不在 `config` 里，或 `config` 整体缺席 / 为 `null`）= 保留该账号已存值**、**给出非空值 = 覆盖该键**、**显式 `null` 或 `""` = 清除该键**（`0` / `false` 是真实取值，**不算空**）；顶层便捷字段（`token` / `baseURL` / …）是普通 `string`，**只在非空时**并入补丁 ⇒ **要清除 `bot_token` 必须走 `config` 的显式 `null` / `""`**；`allowGroups` / `denyGroups` / `allowUsers` / `denyUsers` 与三个限流键**仍是整值替换**（省略 = 清空）。② **破坏性提示**：按旧文实现、依赖「省略某 `config` 键 = 删掉它」的客户端，必须改为**显式传 `null` / `""`** 才能清除该键。③ **修掉的数据安全问题**：面板只发送用户本次碰过的平台字段，后端却整条替换 ⇒ 保存**微信(iLink)**账号卡会抹掉 `bot_token` / `bot_id` / `owner_id` / `get_updates_buf`（**iLink token 是长期凭据**）、**Telegram** 只填 `webhook_url` 而不重填 token 会让 `cleanAccounts` **丢掉整个账号**。④ **未改**：token 要求型平台**显式**清 token 仍按 `cleanAccounts` 丢账号；「本次一个 `config` 键都没给出」在**非 `weixin-ilink`** 平台仍回 `400`。⑤ **无新端点 / 新字段 / 响应形状变更**。**同版另含阶段 6 前端批（纯前端行为，无 API 变化）**：① **16.4.1 静默/活动态与预约切换**——唯一入口 `frontend/web/src/components/modeSwitch.ts`：她活动时用户切换只登记「已预约」、静默时落地；② **16.4.5 会话级消息缓存**——帧按自己的 `sessionId` 落进该会话的消息桶（切会话不清空），**只有单槽忙态**仍按激活会话判定；`graph_update` 按 `data.sessionId` 入**图桶**，管理端 Flow 页取激活会话、Backthink 页取 `sess-backthink`（裁决 16.4.2）；③ **16.4.3 / 16.4.6 虚拟滚动与专属页只读卡**——长列表超阈值窗口化、专属页只读展示该平台完整字段；④ **16.4.4 双档 UI 模式**——性能档 = 现状（默认）、华丽档落 `:root.ui-mode-fancy`，持久化键 `cyrene.ui-mode`（纯前端，对应 `design/07 §0.1`，不改后端契约）。**上一版 `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/*`） @@ -253,6 +253,7 @@ | 21 | `/api/v1/admin/system/rotate-jwt` | POST | ✅(写) | 轮换 JWT 密钥（owner-only，审计）；body `{newSecret}`（≥32 位，不强校验熵）→ `{rotated:true,note,refreshTokensRevoked}`——**现有 access token 立即失效需重新登录，且**所有 refresh token 一并作废（`refreshTokensRevoked` 为删除条数）；新密钥**不回显、不落日志** | | 22 | `/api/v1/admin/system/backup` | POST | ✅(写) | 备份数据（owner-only，审计）；用 SQLite `VACUUM INTO` 快照（含已提交 WAL 内容）到 `/backup-.db` → `{path,size}` | | 23 | `/api/v1/admin/system/restore` | POST | ✅(写) | 恢复数据（owner-only，审计）；body `{path}` → 校验路径在 dataDir 内→**先备份当前**→替换 DB 文件→`{restored:true,backup,note:"需重启后生效"}`（运行进程持有 DB 句柄，热替换需重启可见） | +| 24 | `/api/v1/admin/system/storage` | GET | ✅ | **存储状态（只读，v0.60）**：owner-only、**无审计动作**；`{data:{main:{kind:"sqlite",path,fileBytes,walBytes,shmBytes,pageSize,pageCount,freelistPages,freeBytes},documents:{count,bytes},vector:{kind:"pgvector"|"none",enabled,ready}}}`——**绝不含凭据**（DSN/密码/`postgres://` 全文一个字都不回）；未接活连接 / 路径未配置 / `documents` 表读不到 → `500 storage_unavailable`（**不回全 0 假快照**）。详见下方「系统设置契约」 | > **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 热安装。） @@ -387,6 +388,37 @@ - `POST /system/backup`（无 body）→ `200 {data:{path,size}}`。**备份数据**：经 SQLite `VACUUM INTO`（含已提交 WAL 内容）快照到 `/backup-.db`，`path` 为备份文件绝对路径、`size` 为字节数；数据库路径未配置回 `500 backup_unavailable`、快照失败回 `500 backup_failed`。 - `POST /system/restore` body `{path}` → `200 {data:{restored:true,backup,note:"已安排恢复，需重启服务后生效"}}`。**恢复数据**：`path` 须为 **dataDir 内**的备份文件（**路径穿越防护**——`filepath.Rel` 校验，`..` 逃逸回 `400`）；文件不存在回 `404`；**先自动备份当前数据库**（`backup` 为快照路径）再替换 DB 文件；运行进程持有 DB 句柄，**替换后需重启服务生效**；数据库路径未配置回 `500 backup_unavailable`、替换失败回 `500 restore_failed`。 +**存储状态契约（`GET /api/v1/admin/system/storage`，v0.60）** —— 上面四条是**动作**（写 + 审计），这一条是**只读查询**：owner-only、**不审计**、**只读**（只有 `SELECT`/`PRAGMA` + `os.Stat`，复用组合根注入的活连接——不新开连接池、不写、不迁移、不备份）。它回答「现在这台机器上到底存了什么」，是面板首页「存储」卡的数据源。 + +- **请求**：无 body、无 query。`Authorization: Bearer `（role=owner）或 `X-API-Key`；**无凭据 / 非 owner → `401`**。 +- **响应 `200 {data:…}`**（三块，字段名逐字对齐 `internal/services/gateway/admin_system_storage.go`）： + +```json +{"data":{ + "main":{"kind":"sqlite","path":"/srv/cyrene/data/cyrene.db","fileBytes":12894208, + "walBytes":107872,"shmBytes":32768,"pageSize":4096,"pageCount":3148, + "freelistPages":12,"freeBytes":49152}, + "documents":{"count":37,"bytes":2143567}, + "vector":{"kind":"none","enabled":false,"ready":false} +}} +``` + + - `main.kind` 恒为 `"sqlite"`（当前唯一的主库引擎）；`main.path` = 组合根实际打开的库文件路径（与备份/恢复端点同一个来源）。 + - `main.fileBytes` = 主库文件字节数（`os.Stat`）；`walBytes`/`shmBytes` = `-wal` / `-shm` 边车文件字节数，**合法地不存在时如实为 `0`**（已 checkpoint 或库未开 WAL）。 + - `main.pageSize`/`pageCount`/`freelistPages` 来自 `PRAGMA page_size` / `page_count` / `freelist_count`（一条 SELECT 取完）；`freeBytes = pageSize × freelistPages`，即「已分配但空闲、VACUUM 可回收」的量级。 + - `documents` = `documents` 表的**行数**与 `SUM(size)`（读表，**不 walk 目录**）；空表时 `bytes` 为 `0`（`COALESCE`），**不是** `null`。 + - `vector` = 可选 pgvector 增强的**运行时真相**（主人 2.4 的困惑点：面板只写「SQLite」会让人以为 PG 没生效）： + - `kind`：`"pgvector"` = 已配置 `DB_PG_URL`；`"none"` = 未配置（前端显示「未启用（未配置 `DB_PG_URL`）」）。 + - `enabled`：开关在不在（等价于 `kind != "none"`）。 + - `ready`：**活着的**向量索引确实是 PostgreSQL+pgvector 后端。配了 PG 但连接/schema 准备失败 ⇒ `enabled:true` + `ready:false`（检索已降级），客户端应显示「已配置但未就绪」，**不要**把 `enabled` 当成「生效了」。 + - 真源 = 组合根的运行时状态（`DB_PG_URL` 非空 + 活索引的具体类型），网关**不自行探测**。 + - **不含凭据（红线）**：DSN / 用户名 / 密码 / `postgres://` 全文**一个字都不回**，`vector` 段只有 `kind`/`enabled`/`ready` 三个键（有专门用例断言响应体里搜不到这些串）。 +- **错误**： + - `401`（无凭据 / 非 owner / 凭据无效——与其它 `ownerAuth` 端点同档）； + - `500 {error:{code:"storage_unavailable",message}}`：数据库**路径**未配置、活**连接**未注入、或页级统计 / `documents` 表读不到（例如库没跑迁移）。**诚实边界**：此时**不返回**任何全 0 的假快照，客户端应显示错误而不是 `0`。 +- **只读保证**：调用前后 `documents` 行数与数据目录内的文件集合均不变（有用例钉住：既没有写、也没有顺手备份）。 +- **前端用法**：`adminSystemStorage()`（`frontend/web/src/lib/api/adminSystem.ts`）→ 卡片 `value` = `SQLite 12.3 MiB`、`hint` = WAL/页数/空闲页、详情行 = `documents N 件` 与 `PG 增强 …`；取数走与其它已接线卡片同一条加载/错误态。 + **知识库 RAG 契约**： - `GET /admin/rag` → `{"data":{"documents":[{id,name,desc?,chunks,embedded}],"hits"?:[{docId,docName,chapter?,text,score,semantic}]}}`。`hits` 仅在携带 `?query=` 时出现；`embedded` 反映部署是否配置向量增强（未配置为待嵌入）。 - `POST /admin/rag` body `{"name","desc?","content"}` → `201 {"data":{"name"}}`。**导入文档**：后端分块（空行分段，超长段按固定长度切）并落项目索引（项目+章节），立即可被关键词/行上下文检索；未注入 `RagStore` 回 `501`。语义/向量嵌入为优雅降级（知识库 Store 不直属向量索引，导入文档走 keyword/line 路径；语义检索仍对既有 project-linked 记忆生效）。 @@ -666,6 +698,7 @@ - 语音：上行 `voice_input`（base64 音频或已转写 text，**v0.59 起可带 `clientMsgId` 幂等**），下行 `voice_output`（合成音频 base64 + text + **`sessionId`/`deviceId?`**，**定向回发起那条连接、回合结算时才到**，空正文/TTS 失败带 `provider` 降级信号）；**语音回合与文本回合走同一条路**（落库 / 跨端 / 忙时排队），见 §3.15。 ## 5. 变更记录 +- `v0.60`（**管理侧只读「存储状态」端点 + 面板存储卡接真数据**，依据主人 2026-10-04 实测反馈（面板首页「存储」卡一直是占位「SQLite」，看不出 PG 增强有没有生效）与 design/10 §3 模块 14（系统设置）/ design/03 §3（pgvector 可选增强），2026-10-04 落实）。**一句话**：**纯新增一个只读端点**，既有端点 / WS 帧 / 字段形状**一字未动**；面板那张假卡换成真数据。**A. 新端点** `GET /api/v1/admin/system/storage`（**owner-only**、**只读**、**无审计动作**，与四条 `POST /system/*` 动作端点同门不同档）→ `200 {data:{main,documents,vector}}`：`main` = `{kind:"sqlite",path,fileBytes,walBytes,shmBytes,pageSize,pageCount,freelistPages,freeBytes}`（`path` 与备份/恢复端点同源；WAL/SHM 边车**合法地不存在**时如实为 `0`；`freeBytes = pageSize × freelistPages`）、`documents` = `{count,bytes}`（读 `documents` 表，**不 walk 目录**，空表 `bytes` 为 `0` 而非 `null`）、`vector` = `{kind:"pgvector"|"none",enabled,ready}`。**B. `vector` 的语义（主人 2.4 的困惑点）**：`kind` 说「配没配 `DB_PG_URL`」，`enabled` 说「开关在不在」（等价于 `kind != "none"`），`ready` 说「**活着的**向量索引真的是 pgvector 后端吗」—— 配了但连接/schema 准备失败 ⇒ `enabled:true` + `ready:false`，客户端必须显示「已配置但未就绪（检索已降级）」，**不要把 `enabled` 当成生效**。客户端显示建议：`none` → 「未启用（未配置 `DB_PG_URL`）」、`enabled && ready` → 「启用（`pgvector` · ready）」、`enabled && !ready` → 未就绪。**C. 两条纪律**：① **不含凭据**——DSN / 用户名 / 密码 / `postgres://` 全文**一个字都不回**（`vector` 段只有 `kind`/`enabled`/`ready` 三个键；有用例断言响应体里搜不到这些串）；② **只读**——只有 `SELECT`/`PRAGMA` + `os.Stat`，且复用组合根注入的**活连接**（不新开连接池、不写、不迁移、不备份；调用前后 `documents` 行数与数据目录内文件集合均不变，有用例钉住）。**D. 真源（`vector`）**：组合根 `cmd/cyrene/wire_frontend.go` 的 `app.vectorState()` —— `Configured` 取 `DB_PG_URL` 非空、`Live` 取活索引的具体类型（`*vector.PGVectorIndex`）；网关**只读这份注入值**，不读环境变量、不新开 PG 连接、不自行探测（否则面板与运行时会给出两个答案）。**E. 失败不伪装**：未接活连接 / 数据库路径未配置 / 读不到页级统计或 `documents` 表（例如库没跑迁移）⇒ `500 {error:{code:"storage_unavailable",message}}`，**绝不回一个全 0 的假快照**；无凭据 → `401`。**F. 面板**：`frontend/web` 的存储卡（`admin/modules/dashboard/overviewMetrics.ts`）改为真数据 —— `value` = `SQLite 12.3 MiB`（`main.fileBytes` 的人类可读量级）、`hint` = `WAL … · N 页（空闲 M 页 / …）`、新增两行详情 = `documents N 件 · …` 与 `PG 增强 …`；取数走与其它已接线卡片**同一条** `useAsyncData` 加载/错误态（数据没到就显示「端点报错：…」，**不回退成 0、不假装成功**）。**G. 实现落点**：`internal/services/gateway/admin_system_storage.go`（新文件）+ `routes.go`（注册）+ `deps.go`/`server.go`（注入 `Deps.Database` / `Deps.Vector`）+ `cmd/cyrene/wire_frontend.go`（组合根真源）+ 前端 `lib/types/adminWrite.ts` / `lib/api/adminSystem.ts` / `admin/modules/dashboard/{useDashboardExtras,overviewMetrics,MiniMetric}`。**H. 兼容性**：**纯新增**——新端点为纯增量；前端 `MiniMetricSpec` 新增的 `extra?: string[]` 是**可选**补充详情行，不传时卡片渲染与旧版**逐字等价**（其它卡片一字未改）。**未做 / 诚实边界**：`main` 只报 SQLite（当前唯一主库引擎）；`vector` 只报 `kind`/`enabled`/`ready`（**刻意不回 host**，把泄漏面压到最小）；不报表级明细、不报备份文件列表（`documents` 之外的占用仍要下钻到备份/文件系统看）。 - `v0.59`（**文档进对话 + 上下文预算按窗口推导 + 语音回合进编排 + `thinking` 可达性口径**，依据 design/24 §3/§4/§6（切片 S1–S5）、design/04 §1.3 + 附录 A.3（主人裁决 2026-10-04）与 `Cyrene-For-Android/devdocs/02-前后端协同事项.md` 的 G5 / C1 / C3；commit `a8851dc` / `a4789ec` / `20c1edb` / `5b2b385` / `72b95df` / `3a01b4e`，2026-10-04 落实）。**三档标注**：**纯增量** = 两个 documents 端点、`chat.documents` 可选字段、4 个文档错误码、`models.json` 组键 `contextWindow`、4 个 `.env` 键、`document-read` 工具、`pending_full` 的 `clientMsgId?`/`messageId?`、定向 `error{code:"chat_busy"}` 帧、`voice_input.clientMsgId`、`voice_output.sessionId`/`deviceId`；**行为变更** = ① 语音回合改走编排器（落库 / 流式 / 跨端 / 忙时排队）② `CONTEXT_MAX_TOKENS` **未设置时改为按窗口推导**（`.env` 里写着 `32768` 仍是显式覆盖）③ 队列满时新增**定向回执**（此前 WS 无等价物）；**破坏性** = ① `historyMessage` 的 `document`（单对象）→ **`documents`（数组，≤5）** ——**但单数形状从未随任何已发布版本号发布过**，故**无兼容期** ② `chars` / `truncated` 的语义由「抽取侧」改为 **「本回合注入侧」**（全文长度只有 `document-read` 的 `totalChars` 能看到）。**A. 文档（新增 §1.2 + §1 行 16/17）**——`POST /api/v1/documents`（multipart `file`，上限 `CHAT_DOCUMENT_MAX_BYTES` 默认 20 MiB）→ `201 {name,url,mime,size,sha256,deduped:false}`；**同字节同扩展名重复上传 → `200` + 同一 `name` + `deduped:true`**；`GET /api/v1/documents/{name}` **必须带 Bearer（owner|admin）**（与图片读侧的免鉴权能力 URL 刻意相反）+ `Content-Disposition: attachment` + `nosniff`；**字节嗅探是唯一类型裁决**（放行基类型只有 `text/plain`），**扩展名白名单 22 项** deny-by-default，`mime` 是嗅探基类型（`data.json` → `text/plain`）、`url` 是**相对路径**；错误码 `unsupported_media_type`(415) / `document_too_large`(413) / `document_not_found`(404) / `too_many_documents`(400)；`chat` 请求（REST 同步 / REST `stream:true` / WS **三处同形**）增可选 `documents:[{name}]`（**≤5、只收服务端存储名、不收 URL**，先于任何 FS 访问判条数，客户端多带的 `mime/url/size` 被服务端覆盖）；DTO 四处同源（`GET /sessions/{id}/messages` / `message_persisted` / `message_edited` / 握手回放）改 `documents` 数组，元素 `{name,mime,size,chars,truncated,status}`、`status ∈ extracted|listed|unreadable`、无附件时省略该键；内置工具 `document-read`（`{name,offset?,limit?}` → `totalChars`/`truncated`/`nextOffset`/`text`/`extractTruncated?`，`limit` 默认 8000、上限 64K、`offset` 为 0 基 rune，策略默认 owner-only）。**B. 配置（§2「上下文窗口与预算契约（v0.59）」）**——`models.json` 组级新增 `contextWindow`（0/省略 = 未声明 ⇒ 131072 保守估算 + **恰好一条 WARN**；负数 = 校验失败）；`.env` 新增 `LLM_CONTEXT_WINDOW` / `CONTEXT_BUDGET_RATIO`（默认 `2/3`）/ `DOCUMENT_MAX_INJECT_CHARS`，并**变更 `CONTEXT_MAX_TOKENS` 语义**（未设置 ⇒ 按窗口推导；`>0` 覆盖；`0`/负 = 关闭压缩）——推导 `budget = min(窗口 × 比例, 窗口 − 输出保留)`，输出保留 = `max(32768, 该组 maxTokens)` 封顶 `窗口/2`，**1M 窗口 ⇒ 699050 tokens**；另**补登记 `.env` → 面板的 materialize 语义**（每次启动一次；面板非空 ⇒ 组集合由面板决定、env 不复活被删的组；键级只在面板缺该键时补，面板的**显式空值/`false`/`null` 绝不覆盖**；「面板改一次、重启被打回」为硬约束；凭据不进日志；范围仅 `models.json` 一族）。**C. 语音（新增 §3.15）**——语音轮次**现在走与文本同一条路径**（落库 = 转写文本 + 助手回复、发 `message_persisted` 与流式帧、跨端同步、忙时按既有规则排队，`pending_ack`/`pending_drain`/`session_busy` 语义零变化）；`deviceId` 照旧落库、`platform` 走存储默认 `web`；`voice_input` 增可选 `clientMsgId`（重复到达回 `chat_duplicate`，不产生新回合、不发音频）；`voice_output` 增 `sessionId`（恒有）/ `deviceId`（非空才有），**空正文与 TTS 失败/降级都走既有 `provider` 降级信号**（不再把 `stopReason` 当语音内容）；**时点** = 回合结算时才到（可能晚于若干状态帧、也可能由续跑或被 steer 注入的那一回合产生）；**定向目标 = 发起 `voice_input` 的那条连接本身**（不按 `deviceId` 路由）、**断线不补投**（带来源 WARN），重连带同一 `clientMsgId` 重试安全。**D. `G5`（§3.2）**——`pending_full` **广播**载荷增 `clientMsgId?` / `messageId?`（前者 = 被拒那条消息的幂等键，未携带则整个键缺席；后者**仅当该消息此前已落库/已认领时**才回填——**绝不在此处新铸 id**，否则客户端重试会被判成「重复到达」而永远进不来）；**新增定向帧** `{type:"error", data:{code:"chat_busy", message, sessionId, clientMsgId?, messageId?}}`，**只发发送者那条连接**、不广播，`code` 与 REST `409 chat_busy` **同码**。**E. `thinking` 口径（§4.4，不改行为）**——消息体 `thinking` 字段在**实时帧**（`message_persisted` / `channel_persisted` / `message_edited`）与**握手回放**中**一律为空**（隐私与带宽的**有意**默认）；实时思维链仍走 §3.1 的 `thinking.*` 流帧（owner/admin）；**历史消息的思维链**只有 `GET /sessions/{id}/messages`（owner|admin）返回。**实现落点**：文档 `internal/services/gateway/documents.go` + `chat_documents.go` + `session_transcript.go` + `internal/runtime/history/document.go`（DTO）+ `internal/runtime/loop/document.go`（装配期注入与结论回写）+ `plugins/tools/io/document_read.go`；预算 `internal/config/context_budget.go` + `context.go` + `llm.go` + `internal/config/runtimeconfig/models.go`（`contextWindow`）+ `materialize.go` + `cmd/cyrene/wire_context.go`；语音/G5 `internal/services/gateway/voice.go` + `session_voice.go` + `session_reject.go` + `ws_route.go`（`wsChatBusyCode`）+ `session_orchestrator.go`。**未做 / 诚实边界**：`document_unreadable`(400) 目前只有工具错误形态（无 REST 错误码）；文档白名单实际为 **22** 项（design/24 §9.2 写 23，以代码为准）；文档的配额/引用计数与 GC（design/24 S7）、PDF/Office 解析（S6）与 IM 侧 `msg.Media` 摄取**均未做**。 - `v0.58`（**纯新增 env 键：`LLM_MULTIMODAL`——让 env-only 部署也能声明「主模型自身能收图」**，依据裁决 14.4.1 / design/06 §0（commit `4adfc9a`），2026-10-04 落实）。**新增 1 个 `.env` 键**：`LLM_MULTIMODAL`（`bool`，**默认 `false`**）= `models.json` 组 `multimodal` 的 **env 等价物**，**只在没有有效 `models.json`（走 `.env` 合成组）时生效**（有组文件时以该组的 `multimodal` 为准，与 `LLM_REASONING_KIND` 同口径）；`true` = 图片**直进主模型上下文**；**留空 / `false` = 把图交给 vision/OCR 工具换成文本描述**；**非 bool 值（如 `maybe`）启动即报错**（fail-fast，不静默回退）。**兼容性**：默认 `false` ⇒ **老部署行为逐字不变**（引入本键之前，env-only 部署没有任何键能声明该能力，图片恒走 vision 工具）；**`LLM_MULTIMODAL=true` 后图片走主模型直收，属部署者显式选择**。**无端点 / 帧 / 字段形状变更**（纯新增 env 键，见 §2「模型配置契约」表与 §1 行 3）。 - `v0.57`（**13.4.5 目标态 steer 落地登记：新下行帧 `steer_ack`（回合内转向的消费回执）**，依据 design/15 §2.0 / §2.1 / §2.4 / §3.x / §5（**13.4.5 目标态规格**，commit `3d8822c`），2026-10-04 落实；**本版是已实现并已推库行为的登记，只有一处纯新增帧 + 一处链路图纯增量键，无其它契约变更**）。**A. 新下行帧 `steer_ack`（见 §3.14）**——`{type:"steer_ack", sessionId, data:{messageId, atStep}}`：忙时会话里新到的用户消息**被在飞回合吃进同一回合**时下发，`messageId` 是那条用户消息的**权威 id**（与 `message_persisted` 的 `data.message.id` 同源）、`atStep` 是吃进它的**模型步序号（1 基）**；同一批次吃进 N 条就发 N 帧、**不合并**。语义＝「**已被本回合吃进（已从 pending 移除）、尚未被正面回答**」⇒ 客户端应把对应气泡渲染为「**已读、未答**」的**灰态**，直到该回合的 `message.*` / `turn.end` 到达，**不需要第二个确认帧**（与「忙『稍后回』」的 pending 气泡不是同一个态）。**角色门**：它**携带具体消息身份**，因此**不登记**进 `frameReachesAll` 的 7 个状态机信号白名单，落 fail-closed 默认档——**只发 `owner` + `admin`**（`viewer` 收不到）；经编排器状态通道**由 hub 直接广播、不经 bus**；帧壳带 `sessionId`、**不带** `turnId`/`seq`。**触发时机**：只在**回合内边界**（loop 每一步开头：上一次模型步与它那一批工具调用都已结束、下一次模型调用尚未开始，此刻没有工具在飞）产生，且**只有该边界真的匹配到 pending 里、且已落库的消息时才发**——**不是每个 step 都发**（无可注入消息的边界一帧都不发）。**B. 转向的三条不变量（design/15 §2.0）**——**I1（同会话在途回合数恒为 1）**：转向只注入、不取消，**绝不新开第二个回合**（loop 侧结构性地没有任何「起新回合」的分支，注入只是把消息并进**当前回合**下一次模型调用的视图）；**I2（消息恰好被处理一次）**：注入＝**已消费**——被注入的消息立刻从该会话 pending **移除**（按 pending 序号认领），绝不被第二个回合再答一遍；去重键＝后端 `message.id`，候选必须**同时**满足「在该会话转录里」与「在本编排器的 pending 里」（**不用时间戳**：Windows `time.Now()` 步长约 0.44ms，连发常同毫秒并列，任何毫秒基线都会漏注入或重复注入）；**I3（转向不取消已发起的工具）**：注入点只在回合内边界，此刻没有任何工具在飞，正在执行的工具**永远跑完**（与 Cline PR #13958「只打断在飞的模型请求、工具与整轮继续」同口径）。**C. 注入的范围（重要口径）**——注入**只影响本轮视图**（每一步边界重新并入），**不写回运行窗口** ⇒ 既不进该回合的 **checkpoint 快照**、也不进**后台记忆提取的输入面**；被注入的消息**本身早在到达时已落库**（pending 路径即时持久化），注入**不新增、也不改写任何行**（它与 `message_persisted` 是两回事：后者在该消息落库时发，前者在该消息被吃进时发）。最新性＝**每个边界重读该会话转录**（`history.Recent`），不靠回合开始那一次播种（回合开始前已有的消息由 `startTurnMessages` 播种，**绝不重复注入**）。**D. 失败一律让路（诚实边界）**——未接转录存储 / 读转录失败 / 该消息尚未落库 / 本回合世代已被打断或被更新的回合取代（认领 `pending` 失败）时，**不发 `steer_ack` 也不注入**：该消息**留在 pending**、照旧作为自己的回合被回答，**绝不静默消失**（转向是增益，任何一处失败都不该让已经在跑的回合失败）。**未做**：**没有「取回 / 撤回 pending 消息」的上行帧**（design/15 §5 提到的队列取回暂无协议面），也没有「已撤回」类下行帧；`steer_ack` 只报「**吃进**」，**不报「回答」**（回答由既有的 `message.*` / `turn.end` 表达）。**E. 一处随实现落地的链路图纯增量键**——注入时给该轮图的 **input 节点**打 `props.steered:true`（`loop.FlowPublisher.MarkInputSteered`），让流程图如实表达「这一轮的输入在回合中途被追加过」；图仍**只有一条主干**（**不是**被画成第二轮，与 I1 一致），标记只并入既有 input 节点、**不新建节点、不改标签**。**F. 实现落点**——loop 侧 `internal/runtime/loop/steer.go`（`SteerRequest` / `SteerSource` / `WithSteerSource` / `steerAtBoundary`）+ `run.go` 的边界调用点 + `flow.go` 的 `MarkInputSteered`；网关侧 `internal/services/gateway/session_steer.go`（每回合一份的 `steerTurn` 游标 / `match` / `consumePending`）+ `session_orchestrator.go`（回合启动与每次续跑各挂一份转向源）+ `ws_bridge.go`（`wsSteerAck` 帧名与其语义注释）；**组合根零改动**（per-turn 状态用 ctx 承载）。**G. 兼容性**——**纯新增帧**，老客户端按未知帧忽略即可；**无 REST / `.env` / 既有帧 / 鉴权变更**，`session_busy` / `pending_ack` / `pending_drain` / `session_idle` / `session_interrupted` / `pending_full`（§3.2）与 `chat_duplicate`（§3.13）的形状与语义**一字未动**。**验证**：网关侧**真路径** e2e（真 WS `chat` 帧 → 真编排器 pending → 真 loop → 真 SQLite 转录 → 真 `/ws/chat` 连接 × 真 JWT）断言「忙时新消息在**下一个回合内边界**被注入**同一回合**、模型第 2 步窗口里有它、整轮**只有一次**助手回答、pending 被清空、`steer_ack` 恰好 1 帧且 `owner`/`admin` 都收到而 `viewer` 收不到（以白名单哨兵到达为前提）」+「消息尚未落库时留在 pending、绝不静默消失」；loop 侧断言注入边界序列、同流去重、恰好一次、以及未接线转向源时窗口逐字不变。**变异反证**（均已还原复绿）：删 `consumePending` → 模型步数 4≠3；注入写回 `msgs` → checkpoint 快照被污染；批次中途注入 → 边界序列异常；把 `steer_ack` 加进白名单 → `viewer` 收到帧。 diff --git a/Docs/api-reference.md b/Docs/api-reference.md index 04fead6..91844f4 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.58`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。** +> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.60`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。** > **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。 > **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**§1 的 REST 端点表已于 2026-10-04 按 `internal/services/gateway/routes.go` 逐条核对并补登记**（补上此前缺失的 `POST /auth/refresh`、`POST /auth/logout`、`POST /upload`、`GET /files/{name}`、三支 `/audio/*`、`GET /admin/llm/catalog`、`GET /admin/observability/logs`、`GET /admin/notifications`、`GET /admin/plugins/installed`、`GET|PUT /admin/owner-profile`、`POST /admin/automations/reminders`）。**仍未补全的是 WS 事件帧清单**：§6.4 自述「并非全表」，`DevDocs/audit/00-总览.md` §4④ 列出的 `session_read` / `message_edited` / `message_deleted` 等仍未逐行登记。 > **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。 @@ -154,10 +154,11 @@ | 59 | POST | `/api/v1/admin/system/rotate-jwt` | **owner** | 200 | 轮换 JWT 密钥 | M10/M11 | | 60 | POST | `/api/v1/admin/system/backup` | **owner** | 200 | 备份数据库 | M10/M11 | | 61 | POST | `/api/v1/admin/system/restore` | **owner** | 200 | 恢复数据库 | M10/M11 | +| 69 | GET | `/api/v1/admin/system/storage` | **owner** | 200/500 | **存储状态（只读，v0.60）**：SQLite 文件/WAL/页级统计 + `documents` 表件数与占用 + 向量增强真假（`kind`/`enabled`/`ready`）；**不含凭据**（DSN 一个字都不回）；路径/活连接未接入或读不到表 → `500 storage_unavailable`（见 §5.35） | M10/M11 | **另**：外部 webhook 回调（如 `webhook` 渠道的 HMAC 回调）由 composition root 通过 `Deps.Webhooks` 动态挂载，**不走网关鉴权**（handler 自校验签名/授权）；路径由调用方决定，不在上表枚举。 -**补登记说明（2026-10-04）**：上表中 `#62`–`#68` 是本次按 `routes.go` 逐条核对后新增的行（`plugins/installed` / `observability/logs` / `notifications` / `llm/catalog` / `owner-profile` GET+PUT / `automations/reminders`），插在各自的鉴权分档里、**既有编号一律未动**。§1.1 的 `#3`/`#4`（`auth/refresh`、`auth/logout`）与 §1.2 的 `#14`–`#18`（`upload`、`files/{name}`、三支 `audio/*`）同理。**v0.59 再补两行**：§1.2 的 `#19`/`#20`（`POST /api/v1/documents`、`GET /api/v1/documents/{name}`，均按 `routes.go` 的 `writeAuth` 注册核对）——同样取本表下一个可用号、不动既有编号。**仍未登记的是 WS 事件帧**（见 §6.4 与本文档开头的历史包袱说明）。 +**补登记说明（2026-10-04）**：上表中 `#62`–`#68` 是本次按 `routes.go` 逐条核对后新增的行（`plugins/installed` / `observability/logs` / `notifications` / `llm/catalog` / `owner-profile` GET+PUT / `automations/reminders`），插在各自的鉴权分档里、**既有编号一律未动**。§1.1 的 `#3`/`#4`（`auth/refresh`、`auth/logout`）与 §1.2 的 `#14`–`#18`（`upload`、`files/{name}`、三支 `audio/*`）同理。**v0.59 再补两行**：§1.2 的 `#19`/`#20`（`POST /api/v1/documents`、`GET /api/v1/documents/{name}`，均按 `routes.go` 的 `writeAuth` 注册核对）——同样取本表下一个可用号、不动既有编号。**v0.60 再补一行**：`#69` GET `/api/v1/admin/system/storage`（owner-only 只读，按 `routes.go` 的 `ownerAuth` 注册核对；**无审计动作**——它是查询不是动作），同样取下一个可用号、既有编号未动。**仍未登记的是 WS 事件帧**（见 §6.4 与本文档开头的历史包袱说明）。 **WS**：`GET /ws/chat`（握手，JWT，见 §6）。 @@ -1146,6 +1147,47 @@ curl -s -X POST http://:8080/api/v1/admin/system/restore \ -d '{"path":"/abs/path/data/backup-20260908T000000.000000000Z.db"}' ``` +### 5.35 GET /api/v1/admin/system/storage（v0.60，只读） + +- **鉴权**：**owner**（`ownerAuth`，与四条 `POST /system/*` 动作端点同门）。无凭据 / 非 owner → `401`。 +- **Body / query**：无。 +- **性质**：**只读查询**，**没有审计动作**（审计只覆盖动作）。实现只有 `SELECT`/`PRAGMA` 与 `os.Stat`，且复用组合根注入的**活连接**（`Deps.Database`）——**不新开连接池、不写、不迁移、不备份**。调用前后 `documents` 行数与数据目录内文件集合均不变。 +- **响应**：`200` + +```json +{"data":{ + "main":{"kind":"sqlite","path":"/srv/cyrene/data/cyrene.db","fileBytes":12894208, + "walBytes":107872,"shmBytes":32768,"pageSize":4096,"pageCount":3148, + "freelistPages":12,"freeBytes":49152}, + "documents":{"count":37,"bytes":2143567}, + "vector":{"kind":"none","enabled":false,"ready":false} +}} +``` + + | 字段 | 类型 | 说明 | + |------|------|------| + | `main.kind` | string | 恒 `"sqlite"`（当前唯一主库引擎） | + | `main.path` | string | 组合根实际打开的库文件路径（与备份/恢复端点同源） | + | `main.fileBytes` | int | 主库文件字节数（`os.Stat`） | + | `main.walBytes` / `main.shmBytes` | int | `-wal` / `-shm` 边车字节数；**合法地不存在时如实为 `0`**（已 checkpoint / 未开 WAL） | + | `main.pageSize` / `main.pageCount` / `main.freelistPages` | int | `PRAGMA page_size` / `page_count` / `freelist_count`（一条 SELECT 取完） | + | `main.freeBytes` | int | `pageSize × freelistPages`（已分配但空闲、VACUUM 可回收的量级） | + | `documents.count` | int | `documents` 表行数 | + | `documents.bytes` | int | `SUM(documents.size)`；空表为 `0`（`COALESCE`），**不是** `null` | + | `vector.kind` | string | `"pgvector"` = 已配置 `DB_PG_URL`；`"none"` = 未配置 | + | `vector.enabled` | bool | 增强开关在不在（等价于 `kind != "none"`） | + | `vector.ready` | bool | **活着的**向量索引确实是 PostgreSQL+pgvector 后端 | + +- **`vector` 的读法（重要）**：`kind` 说「配没配 `DB_PG_URL`」，`ready` 说「现在真的在跑什么」。配了 PG 但连接/schema 准备失败 ⇒ `enabled:true` + `ready:false`（检索已降级），客户端应显示「已配置但未就绪」，**不要把 `enabled` 当成生效**。`kind:"none"` 时前端显示「未启用（未配置 `DB_PG_URL`）」。**真源** = 组合根 `cmd/cyrene/wire_frontend.go` 的 `app.vectorState()`（`DB_PG_URL` 非空 + 活索引的具体类型），网关不读环境变量、不新开 PG 连接、不自行探测。 +- **不含凭据（红线）**：DSN / 用户名 / 密码 / `postgres://` 全文**一个字都不回**，`vector` 段只有 `kind`/`enabled`/`ready` 三个键（有用例断言响应体里搜不到这些串）。 +- **错误**：`401`（无凭据 / 非 owner）；`500 {"error":{"code":"storage_unavailable","message":…}}` —— 数据库**路径**未配置、活**连接**未注入、或页级统计 / `documents` 表读不到（例如库没跑迁移）。**诚实边界**：此时**不返回**任何全 0 的假快照。 +- **前端落点**：`frontend/web/src/lib/api/adminSystem.ts` 的 `adminSystemStorage()` → 面板首页「存储」卡（`admin/modules/dashboard/overviewMetrics.ts`）：`value` = `SQLite 12.3 MiB`、`hint` = WAL / 页数 / 空闲页、详情两行 = `documents N 件 · …` 与 `PG 增强 …`。取数走与其它已接线卡片同一条加载/错误态（失败显示端点错误，不回退成 `0`）。curl： + +```bash +curl -s http://:8080/api/v1/admin/system/storage \ + -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1' +``` + --- ## 6. WebSocket 实时协议（`GET /ws/chat`） diff --git a/cmd/cyrene/wire_frontend.go b/cmd/cyrene/wire_frontend.go index f471e68..538da38 100644 --- a/cmd/cyrene/wire_frontend.go +++ b/cmd/cyrene/wire_frontend.go @@ -3,11 +3,13 @@ package main import ( "context" "fmt" + "strings" "git.yeij.top/AskaEth/Cyrene_v2/internal/auth" "git.yeij.top/AskaEth/Cyrene_v2/internal/channel/adapter" "git.yeij.top/AskaEth/Cyrene_v2/internal/logger" "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/knowledge" + "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory/vector" "git.yeij.top/AskaEth/Cyrene_v2/internal/services/gateway" ) @@ -76,6 +78,8 @@ func (a *app) wireFrontend() error { Webhooks: a.channelBridge.WebhookHandlers(), DatabasePath: a.dbPath, DataDir: resolveDataDir(a.cfg), + Database: a.db, + Vector: a.vectorState(), }) if err != nil { return fmt.Errorf("gateway: %w", err) @@ -111,3 +115,23 @@ func (a *app) wireFrontend() error { } return nil } + +// vectorState 把「PG 增强到底有没有生效」的**运行时真相**报给网关，供管理侧 +// 「存储状态」只读端点作答（design/03 §3；面板首页的存储卡）。 +// +// 真源就在本组合根，且只有两项事实，因此这里**复用**运行时状态而不新造探测： +// +// - Configured = `DB_PG_URL` 是否配置（非空即算）—— 开关在不在； +// - Live = 活着的向量索引确实落在 pgvector 后端上 —— 真的在不在跑。 +// +// 两者会不一致：配置了 PG 但连接/schema 准备失败时，wireMemory 把 vindex 留成 +// nil（语义检索降级），此时 Configured=true、Live=false，面板据此显示「已配置但 +// 未就绪」，而不是把「配了」当成「生效了」。这里绝不新开 PG 连接去探测：那既多 +// 一次网络往返，也可能与运行中的索引给出不同答案。 +func (a *app) vectorState() gateway.VectorState { + _, live := a.vindex.(*vector.PGVectorIndex) + return gateway.VectorState{ + Configured: strings.TrimSpace(a.cfg.DB.PGURL) != "", + Live: live, + } +} diff --git a/frontend/web/src/admin/modules/dashboard/MiniMetric.tsx b/frontend/web/src/admin/modules/dashboard/MiniMetric.tsx index 4392a3b..076a279 100644 --- a/frontend/web/src/admin/modules/dashboard/MiniMetric.tsx +++ b/frontend/web/src/admin/modules/dashboard/MiniMetric.tsx @@ -13,6 +13,10 @@ export interface MiniMetricSpec { label: string; value: string; hint: string; + /** 可选的补充详情行：逐行渲染在 `hint` 下方。**不传时卡片与既有形状 + * 逐字等价**（其它卡片因此一字未改）；存储卡用它把 PG 增强状态单独 + * 摆一行，而不是挤进 `hint`。 */ + extra?: string[]; state: MetricState; /** Admin module this card drills down to; absent = not a link. */ section?: AdminSectionId; @@ -25,7 +29,7 @@ const STATE_BADGE: Record = { placeholder: { label: "占位", tone: "warn" }, }; -export function MiniMetric({ icon, label, value, hint, state, section }: MiniMetricSpec): ReactNode { +export function MiniMetric({ icon, label, value, hint, extra, state, section }: MiniMetricSpec): ReactNode { const badge = STATE_BADGE[state]; const body = ( <> @@ -36,6 +40,11 @@ export function MiniMetric({ icon, label, value, hint, state, section }: MiniMet
{value}
{hint}
+ {extra?.map((line) => ( +
+ {line} +
+ ))} ); const base = diff --git a/frontend/web/src/admin/modules/dashboard/overviewMetrics.ts b/frontend/web/src/admin/modules/dashboard/overviewMetrics.ts index b338e2c..d84d9ea 100644 --- a/frontend/web/src/admin/modules/dashboard/overviewMetrics.ts +++ b/frontend/web/src/admin/modules/dashboard/overviewMetrics.ts @@ -10,6 +10,8 @@ import type { AdminLlmConfig, AdminObservabilityMetrics, AdminRagResponse, + AdminStorageStatus, + AdminStorageVector, AdminUserRecord, InstalledPlugin, } from "../../../lib/types"; @@ -21,6 +23,10 @@ import type { DashboardExtras, Loaded } from "./useDashboardExtras"; * 8 rounds before the agent must answer. Shown as a fact, not as a metric. */ const TOOL_LOOP_CAP = 8; +/** 字节单位阶梯（1 KiB = 1024 B）。 */ +const BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB"] as const; +const BYTE_STEP = 1024; + export function buildOverviewMetrics(extras: DashboardExtras): MiniMetricSpec[] { return [ llmMetric(extras.llm), @@ -30,7 +36,7 @@ export function buildOverviewMetrics(extras: DashboardExtras): MiniMetricSpec[] userMetric(extras.users), gatewayMetric(extras.metrics), agentCallMetric(extras.metrics), - storageMetric(), + storageMetric(extras.storage), ]; } @@ -179,20 +185,51 @@ function agentCallMetric(m: Loaded): MiniMetricSpec { }; } -/** Storage has no read-only endpoint in `lib/api.ts` (backup/restore are writes - * that would touch the filesystem), so this card states the configured default - * and names the missing endpoint instead of showing a made-up figure. */ -function storageMetric(): MiniMetricSpec { +/** 存储卡（v0.60）：取 `GET /admin/system/storage` 的真实快照 —— 主库体积 + * （`value`）、WAL / 页数 / 空闲页、`documents` 件数与占用，以及 PG/pgvector + * 增强到底有没有生效（主人 2.4 的困惑点：只写「SQLite」会让人以为 PG 没接上）。 + * + * 取数与其它已接线卡片同一条路：数据没到就 `pending(...)`（显示端点错误， + * **绝不**回退成 0 或假装成功）。 */ +function storageMetric(storage: Loaded): MiniMetricSpec { + if (storage.data == null) { + return pending("storage", "存储", "SQLite 主库 · WAL · documents · PG/pgvector 增强", storage, "system"); + } + const { main, documents, vector } = storage.data; return { icon: "storage", label: "存储", - value: "SQLite", - hint: "默认引擎 · PG/pgvector 可选增强；缺只读查询端点（未在 lib/api.ts 暴露）", - state: "placeholder", + value: `SQLite ${formatBytes(main.fileBytes)}`, + hint: `WAL ${formatBytes(main.walBytes)} · ${main.pageCount} 页（空闲 ${main.freelistPages} 页 / ${formatBytes(main.freeBytes)}）`, + extra: [ + `documents ${documents.count} 件 · ${formatBytes(documents.bytes)}`, + `PG 增强 ${vectorLabel(vector)}`, + ], + state: "ok", section: "system", }; } +/** PG 增强一行：未配置 / 已就绪 / 已配置但未就绪（降级）三者必须可区分 —— + * 绝不把「配了」写成「生效了」。 */ +function vectorLabel(vector: AdminStorageVector): string { + if (vector.kind === "none" || !vector.enabled) return "未启用（未配置 DB_PG_URL）"; + if (vector.ready) return `启用（${vector.kind} · ready）`; + return `已配置但未就绪（${vector.kind} 连接失败，检索已降级）`; +} + +/** 字节数 → 「12.3 MiB」这类人类可读量级；0 如实显示 `0 B`。 */ +function formatBytes(bytes: number): string { + if (!Number.isFinite(bytes) || bytes <= 0) return "0 B"; + let value = bytes; + let unit = 0; + while (value >= BYTE_STEP && unit < BYTE_UNITS.length - 1) { + value /= BYTE_STEP; + unit += 1; + } + return `${value.toFixed(unit === 0 || value >= 100 ? 0 : 1)} ${BYTE_UNITS[unit]}`; +} + /** ISO → local "MM-DD HH:mm"; absent or unparseable values render as an em dash. */ function formatTime(iso?: string): string { if (!iso) return "—"; diff --git a/frontend/web/src/admin/modules/dashboard/useDashboardExtras.ts b/frontend/web/src/admin/modules/dashboard/useDashboardExtras.ts index 69ec45c..d877a4b 100644 --- a/frontend/web/src/admin/modules/dashboard/useDashboardExtras.ts +++ b/frontend/web/src/admin/modules/dashboard/useDashboardExtras.ts @@ -5,6 +5,7 @@ import { adminListRag, adminListUsers, adminObservabilityMetrics, + adminSystemStorage, } from "../../../lib/api"; import { useAsyncData } from "../../../lib/useAsyncData"; import type { @@ -12,6 +13,7 @@ import type { AdminLlmConfig, AdminObservabilityMetrics, AdminRagResponse, + AdminStorageStatus, AdminUserRecord, InstalledPlugin, } from "../../../lib/types"; @@ -32,6 +34,7 @@ export interface DashboardExtras { automations: Loaded; rag: Loaded; users: Loaded; + storage: Loaded; } /** The secondary dashboard sources, all from endpoints that already exist in @@ -44,11 +47,15 @@ export function useDashboardExtras(): DashboardExtras { const automations = useAsyncData(adminListAutomations, []); const rag = useAsyncData(adminListRag, []); const users = useAsyncData(adminListUsers, []); + // 存储快照（v0.60）：只读端点，取数的加载/错误态与其它卡片同一条路。 + const storage = useAsyncData(adminSystemStorage, []); useAutoReload(llm.reload, 30000); useAutoReload(metrics.reload, 15000); useAutoReload(installed.reload, 30000); useAutoReload(automations.reload, 30000); useAutoReload(rag.reload, 30000); useAutoReload(users.reload, 30000); - return { llm, metrics, installed, automations, rag, users }; + // 库体积/页数变化很慢，比其它卡片再放慢一档（仍是同一个 useAutoReload）。 + useAutoReload(storage.reload, 60000); + return { llm, metrics, installed, automations, rag, users, storage }; } diff --git a/frontend/web/src/lib/api.ts b/frontend/web/src/lib/api.ts index e4e0cd4..4fa7767 100644 --- a/frontend/web/src/lib/api.ts +++ b/frontend/web/src/lib/api.ts @@ -115,4 +115,5 @@ export { adminSystemRestore, adminSystemRevokeKeys, adminSystemRotateJWT, + adminSystemStorage, } from "./api/adminSystem"; diff --git a/frontend/web/src/lib/api/adminSystem.ts b/frontend/web/src/lib/api/adminSystem.ts index ab042dd..600b5d7 100644 --- a/frontend/web/src/lib/api/adminSystem.ts +++ b/frontend/web/src/lib/api/adminSystem.ts @@ -4,6 +4,7 @@ import type { AdminNotification, AdminNotificationQuery, AdminObservabilityMetrics, + AdminStorageStatus, AdminTraceSpan, AuditRecord, BackthinkItem, @@ -65,6 +66,16 @@ export function adminListNotifications( * All four are implemented (not 501) — they return real data. * -------------------------------------------------------------------------- */ +/** GET /api/v1/admin/system/storage — the **read-only** storage snapshot behind the + * dashboard's 存储 card (v0.60): SQLite file/WAL/page stats, the documents table's + * count+bytes, and whether the optional pgvector enhancement is configured and + * actually live. The `vector` block never carries credentials (no DSN, no password). + * owner-only; the backend answers `500 storage_unavailable` rather than a fake + * all-zero snapshot when the live DB handle is not wired. */ +export function adminSystemStorage(): Promise { + return request("/admin/system/storage"); +} + /** POST /api/v1/admin/system/revoke-keys — revokes every registered API key. */ export function adminSystemRevokeKeys(): Promise { return request("/admin/system/revoke-keys", { method: "POST" }); diff --git a/frontend/web/src/lib/types/adminWrite.ts b/frontend/web/src/lib/types/adminWrite.ts index d0944c9..28a0c9d 100644 --- a/frontend/web/src/lib/types/adminWrite.ts +++ b/frontend/web/src/lib/types/adminWrite.ts @@ -187,3 +187,40 @@ export interface SystemRestoreResp { backup: string; note: string; } + +/* --- System storage status (read-only, v0.60). Field names mirror the gateway DTOs + * in internal/services/gateway/admin_system_storage.go. --- */ + +/** 主库（SQLite）段：文件体积 + 页级统计。 */ +export interface AdminStorageMain { + kind: "sqlite"; + path: string; + fileBytes: number; + walBytes: number; + shmBytes: number; + pageSize: number; + pageCount: number; + freelistPages: number; + freeBytes: number; +} + +/** `documents` 表段：件数与占用字节。 */ +export interface AdminStorageDocuments { + count: number; + bytes: number; +} + +/** 向量增强段：`kind` 说配了什么、`ready` 说现在真的在跑什么。 + * **绝不含凭据**（DSN 一个字都不回）。 */ +export interface AdminStorageVector { + kind: "pgvector" | "none"; + enabled: boolean; + ready: boolean; +} + +/** GET /api/v1/admin/system/storage — the read-only storage snapshot (owner-only). */ +export interface AdminStorageStatus { + main: AdminStorageMain; + documents: AdminStorageDocuments; + vector: AdminStorageVector; +} diff --git a/internal/services/gateway/admin_system_storage.go b/internal/services/gateway/admin_system_storage.go new file mode 100644 index 0000000..ea56e0f --- /dev/null +++ b/internal/services/gateway/admin_system_storage.go @@ -0,0 +1,185 @@ +package gateway + +import ( + "context" + "database/sql" + "fmt" + "net/http" + "os" + "strings" + + apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors" + "git.yeij.top/AskaEth/Cyrene_v2/internal/logger" +) + +// 存储状态**只读**端点（GET /api/v1/admin/system/storage，仅 owner；design/10 §3 +// 模块 14 系统设置 + design/03 §3 记忆的向量增强）。面板首页的「存储」卡此前 +// 只能写死「SQLite」（`overviewMetrics.ts` 的占位），主人看不出 PG 增强到底 +// 有没有生效 —— 这个端点把三件事一起答清楚：主库实际多大、文档表存了多少、 +// 向量增强现在**跑的是什么**。 +// +// 三条纪律（本文件全部实现都必须遵守）： +// +// 1. **只读**：只有 SELECT / PRAGMA 与 os.Stat —— 不写、不迁移、不备份、 +// 不建连接池（用组合根注入的活连接，见 Deps.Database）。 +// 2. **不回显凭据**：向量段只回 kind/enabled/ready；DSN（可能含密码）一个 +// 字都不回，也因此没有任何「原样回显 DSN」的代码路径。 +// 3. **不猜**：读不到就回 500 + 明确 code，绝不用 0 假装成功（面板据此 +// 显示错误，而不是一个看着正常的假数字）。 +const storageLogSource = "gateway/admin_system_storage" + +// 向量增强的 kind 枚举（契约值，Docs/api-client.md 与前端逐字比对）。 +const ( + vectorKindPGVector = "pgvector" + vectorKindNone = "none" +) + +// storageKindSQLite 是主库段的 kind 取值（当前唯一的主库引擎）。 +const storageKindSQLite = "sqlite" + +// SQLite WAL 模式的边车文件后缀：`-wal` / `-shm`。 +const ( + storageWALSuffix = "-wal" + storageSHMSuffix = "-shm" +) + +// storageMain 是主库（SQLite）段：文件体积 + 页级统计。页级信息取自 +// `PRAGMA page_size/page_count/freelist_count`，freeBytes = 空闲页 × 页大小， +// 即「已分配但未使用」的空间（VACUUM 能回收的量级）。 +type storageMain struct { + Kind string `json:"kind"` + Path string `json:"path"` + FileBytes int64 `json:"fileBytes"` + WALBytes int64 `json:"walBytes"` + SHMBytes int64 `json:"shmBytes"` + PageSize int64 `json:"pageSize"` + PageCount int64 `json:"pageCount"` + FreelistPages int64 `json:"freelistPages"` + FreeBytes int64 `json:"freeBytes"` +} + +// storageDocuments 是 `documents` 表段：件数与占用字节（读表，不 walk 目录）。 +type storageDocuments struct { + Count int64 `json:"count"` + Bytes int64 `json:"bytes"` +} + +// storageVector 是向量增强段。kind 说「配了什么」（`pgvector` / `none`）， +// ready 说「现在真的在跑什么」：配置了 PG URL 但连接失败时 enabled 为 true、 +// ready 为 false，前端据此显示「已降级」而不是假装增强生效。 +type storageVector struct { + Kind string `json:"kind"` + Enabled bool `json:"enabled"` + Ready bool `json:"ready"` +} + +// storageStatus 是响应 data 本体。 +type storageStatus struct { + Main storageMain `json:"main"` + Documents storageDocuments `json:"documents"` + Vector storageVector `json:"vector"` +} + +// adminStorageStatus 处理 GET /api/v1/admin/system/storage。它只读，因此不审计 +// （与其它管理读端点同档：审计只覆盖动作）。 +func (s *Server) adminStorageStatus(w http.ResponseWriter, r *http.Request) { + if strings.TrimSpace(s.dbPath) == "" { + writeError(w, apperr.Wrap(apperr.ErrInternal, "storage_unavailable", "数据库路径未配置")) + return + } + if s.db == nil { + writeError(w, apperr.Wrap(apperr.ErrInternal, "storage_unavailable", "数据库连接未配置")) + return + } + st, err := storageStatusOf(r.Context(), s.db, s.dbPath, s.vector) + if err != nil { + logger.WithSource(s.log, storageLogSource).Error("read storage status", "err", err) + writeError(w, apperr.Wrap(apperr.ErrInternal, "storage_unavailable", "读取存储状态失败")) + return + } + writeJSON(w, http.StatusOK, st) +} + +// storageStatusOf 采集一次存储快照。conn 必须是组合根已打开的**活连接** +// （Deps.Database）—— 本函数绝不自己开池，也不写任何东西。 +func storageStatusOf(ctx context.Context, conn *sql.DB, dbPath string, vec VectorState) (storageStatus, error) { + main, err := storageMainOf(ctx, conn, dbPath) + if err != nil { + return storageStatus{}, err + } + docs, err := storageDocumentsOf(ctx, conn) + if err != nil { + return storageStatus{}, err + } + return storageStatus{Main: main, Documents: docs, Vector: vectorStatusOf(vec)}, nil +} + +// storageMainOf 读主库的文件体积与页级统计。 +func storageMainOf(ctx context.Context, conn *sql.DB, dbPath string) (storageMain, error) { + var pageSize, pageCount, freelistPages int64 + // 三个 pragma_* 表值函数在一条 SELECT 里取完，避免三次往返。 + const pageStats = `SELECT + (SELECT page_size FROM pragma_page_size), + (SELECT page_count FROM pragma_page_count), + (SELECT freelist_count FROM pragma_freelist_count)` + if err := conn.QueryRowContext(ctx, pageStats).Scan(&pageSize, &pageCount, &freelistPages); err != nil { + return storageMain{}, fmt.Errorf("read sqlite page stats: %w", err) + } + fileBytes, err := storageFileBytes(dbPath) + if err != nil { + return storageMain{}, err + } + return storageMain{ + Kind: storageKindSQLite, + Path: dbPath, + FileBytes: fileBytes, + WALBytes: storageSidecarBytes(dbPath + storageWALSuffix), + SHMBytes: storageSidecarBytes(dbPath + storageSHMSuffix), + PageSize: pageSize, + PageCount: pageCount, + FreelistPages: freelistPages, + FreeBytes: pageSize * freelistPages, + }, nil +} + +// storageFileBytes 返回主库文件的字节数。文件不存在是**硬错误**：组合根已经 +// 打开了这条路径，stat 不到说明报出来的 path 与实际在用的文件不是同一份， +// 这时给出一个 0 会让面板显示一个看着正常的假体积。 +func storageFileBytes(path string) (int64, error) { + info, err := os.Stat(path) + if err != nil { + return 0, fmt.Errorf("stat database file: %w", err) + } + return info.Size(), nil +} + +// storageSidecarBytes 返回 WAL/SHM 边车文件的字节数。两者可以合法地不存在 +// （已 checkpoint 过、或库根本没开 WAL），此时如实地算 0 字节。 +func storageSidecarBytes(path string) int64 { + info, err := os.Stat(path) + if err != nil { + return 0 + } + return info.Size() +} + +// storageDocumentsOf 读 `documents` 表的件数与占用。空表时 SUM(size) 为 NULL， +// 用 COALESCE 收敛成 0；表不存在（迁移没跑过）则直接报错，不静默报 0。 +func storageDocumentsOf(ctx context.Context, conn *sql.DB) (storageDocuments, error) { + const docsStats = `SELECT COUNT(*), COALESCE(SUM(size), 0) FROM documents` + var docs storageDocuments + if err := conn.QueryRowContext(ctx, docsStats).Scan(&docs.Count, &docs.Bytes); err != nil { + return storageDocuments{}, fmt.Errorf("read documents stats: %w", err) + } + return docs, nil +} + +// vectorStatusOf 把组合根注入的运行时状态翻成契约形状：kind = 配了什么、 +// enabled = 开关在不在、ready = 现在真的跑的是什么。未配置时三者收成 +// `none`（前端显示「未启用（未配置 DB_PG_URL）」）。 +func vectorStatusOf(vec VectorState) storageVector { + if !vec.Configured { + return storageVector{Kind: vectorKindNone} + } + return storageVector{Kind: vectorKindPGVector, Enabled: true, Ready: vec.Live} +} diff --git a/internal/services/gateway/admin_system_storage_test.go b/internal/services/gateway/admin_system_storage_test.go new file mode 100644 index 0000000..52894ae --- /dev/null +++ b/internal/services/gateway/admin_system_storage_test.go @@ -0,0 +1,311 @@ +package gateway + +import ( + "context" + "database/sql" + "encoding/json" + "net/http" + "os" + "path/filepath" + "strings" + "testing" + + "git.yeij.top/AskaEth/Cyrene_v2/internal/auth" + "git.yeij.top/AskaEth/Cyrene_v2/internal/db" +) + +// storageTestDB 在 dir 下打开一个真实 SQLite 文件库、跑迁移，并按 sizes 插入 +// 等量的 documents 行（每行 size 取该元素值），返回路径与**仍打开**的活连接 +// —— 存储状态端点用的就是这条连接（Deps.Database）。 +func storageTestDB(t *testing.T, dir string, sizes []int64) (string, *sql.DB) { + t.Helper() + ctx := context.Background() + path := filepath.Join(dir, "cyrene.db") + conn, err := db.Open(ctx, path, gwTestLogger()) + if err != nil { + t.Fatalf("open file db: %v", err) + } + t.Cleanup(func() { _ = conn.Close() }) + if err := db.MigrateUp(ctx, conn, gwTestLogger()); err != nil { + t.Fatalf("migrate: %v", err) + } + for i, size := range sizes { + name := "doc-" + string(rune('a'+i)) + ".txt" + if _, err := conn.ExecContext(ctx, + `INSERT INTO documents (name, sha256, mime, size) VALUES (?, ?, ?, ?)`, + name, strings.Repeat("a", 64), "text/plain", size); err != nil { + t.Fatalf("insert document %d: %v", i, err) + } + } + return path, conn +} + +// storageStatusDTO 是端点的响应形状（与 internal/services/gateway/admin_system_storage.go +// 的字段逐字对齐）；测试用它反解，字段名写错就会解不出来。 +type storageStatusDTO struct { + Main struct { + Kind string `json:"kind"` + Path string `json:"path"` + FileBytes int64 `json:"fileBytes"` + WALBytes int64 `json:"walBytes"` + SHMBytes int64 `json:"shmBytes"` + PageSize int64 `json:"pageSize"` + PageCount int64 `json:"pageCount"` + FreelistPages int64 `json:"freelistPages"` + FreeBytes int64 `json:"freeBytes"` + } `json:"main"` + Documents struct { + Count int64 `json:"count"` + Bytes int64 `json:"bytes"` + } `json:"documents"` + Vector struct { + Kind string `json:"kind"` + Enabled bool `json:"enabled"` + Ready bool `json:"ready"` + } `json:"vector"` +} + +// getStorageStatus 以一个 owner token 取一次存储状态，返回状态码与原始响应体。 +func getStorageStatus(t *testing.T, url string, jwt *auth.JWTService) (int, []byte) { + t.Helper() + tok := signAny(t, jwt, "acct", auth.RoleOwner) + resp, body := doReq(t, http.MethodGet, url+"/api/v1/admin/system/storage", nil, tok) + return resp.StatusCode, body +} + +func decodeStorageStatus(t *testing.T, body []byte) storageStatusDTO { + t.Helper() + var st storageStatusDTO + if err := json.Unmarshal(decodeBody(t, body)["data"], &st); err != nil { + t.Fatalf("decode storage status: %v (body=%s)", err, body) + } + return st +} + +// --- GET /api/v1/admin/system/storage（存储状态只读端点） -------------------- + +func TestAdminStorageStatusReportsRealValues(t *testing.T) { + t.Parallel() + dir := t.TempDir() + dbPath, conn := storageTestDB(t, dir, []int64{11, 22, 33}) + _, ts, jwt := buildEnv(t, cfgDefault(), Deps{DatabasePath: dbPath, Database: conn}) + + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200 (body=%s)", status, body) + } + st := decodeStorageStatus(t, body) + + if st.Main.Kind != "sqlite" { + t.Fatalf("main.kind = %q, want sqlite", st.Main.Kind) + } + if st.Main.Path != dbPath { + t.Fatalf("main.path = %q, want %q", st.Main.Path, dbPath) + } + if st.Main.PageSize <= 0 || st.Main.PageCount <= 0 { + t.Fatalf("page stats = (%d, %d), want both > 0", st.Main.PageSize, st.Main.PageCount) + } + info, err := os.Stat(dbPath) + if err != nil { + t.Fatalf("stat db: %v", err) + } + if st.Main.FileBytes != info.Size() { + t.Fatalf("main.fileBytes = %d, want stat size %d", st.Main.FileBytes, info.Size()) + } + if st.Main.FreeBytes != st.Main.PageSize*st.Main.FreelistPages { + t.Fatalf("main.freeBytes = %d, want pageSize*freelistPages = %d", + st.Main.FreeBytes, st.Main.PageSize*st.Main.FreelistPages) + } + if st.Main.WALBytes < 0 || st.Main.SHMBytes < 0 { + t.Fatalf("sidecar bytes negative: wal=%d shm=%d", st.Main.WALBytes, st.Main.SHMBytes) + } + // documents 段必须与插入的行逐字对上（把 count 写死 0 的变异在这里变红）。 + if st.Documents.Count != 3 || st.Documents.Bytes != 66 { + t.Fatalf("documents = %+v, want count 3 bytes 66", st.Documents) + } + // 未配置 PG ⇒ 如实报 none，且不假装 ready。 + if st.Vector.Kind != "none" || st.Vector.Enabled || st.Vector.Ready { + t.Fatalf("vector = %+v, want {none false false}", st.Vector) + } +} + +func TestAdminStorageStatusUnauthenticated(t *testing.T) { + t.Parallel() + dir := t.TempDir() + dbPath, conn := storageTestDB(t, dir, nil) + _, ts, _ := buildEnv(t, cfgDefault(), Deps{DatabasePath: dbPath, Database: conn}) + + resp, body := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/system/storage", nil, "") + if resp.StatusCode != http.StatusUnauthorized { + t.Fatalf("status = %d, want 401 (body=%s)", resp.StatusCode, body) + } + wantErrorShape(t, body) +} + +// TestAdminStorageStatusHidesCredentials 钉住红线：PG URL（可能含密码）绝不 +// 出现在响应体里；只回 kind/enabled/ready。 +func TestAdminStorageStatusHidesCredentials(t *testing.T) { + t.Parallel() + const dsn = "postgres://cyrene_user:s3cret-pw@db.internal:5432/cyrene?sslmode=disable" + dir := t.TempDir() + dbPath, conn := storageTestDB(t, dir, nil) + cfg := cfgDefault() + cfg.DB.PGURL = dsn + _, ts, jwt := buildEnv(t, cfg, Deps{ + DatabasePath: dbPath, + Database: conn, + Vector: VectorState{Configured: true, Live: false}, + }) + + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200 (body=%s)", status, body) + } + for _, secret := range []string{dsn, "s3cret-pw", "postgres://", "cyrene_user", "db.internal", "sslmode"} { + if strings.Contains(string(body), secret) { + t.Fatalf("response body leaks %q: %s", secret, body) + } + } + st := decodeStorageStatus(t, body) + // 配置了但索引没跑起来 ⇒ enabled 为真、ready 为假（面板显示「已降级」）。 + if st.Vector.Kind != "pgvector" || !st.Vector.Enabled || st.Vector.Ready { + t.Fatalf("vector = %+v, want {pgvector true false}", st.Vector) + } +} + +func TestAdminStorageStatusVectorReady(t *testing.T) { + t.Parallel() + dir := t.TempDir() + dbPath, conn := storageTestDB(t, dir, nil) + _, ts, jwt := buildEnv(t, cfgDefault(), Deps{ + DatabasePath: dbPath, + Database: conn, + Vector: VectorState{Configured: true, Live: true}, + }) + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200 (body=%s)", status, body) + } + st := decodeStorageStatus(t, body) + if st.Vector.Kind != "pgvector" || !st.Vector.Enabled || !st.Vector.Ready { + t.Fatalf("vector = %+v, want {pgvector true true}", st.Vector) + } +} + +// TestAdminStorageStatusUnwired 覆盖三种「没接线」：路径空 / 连接空 / 两者都空。 +// 一律 500 + storage_unavailable，绝不回一个全 0 的假快照。 +func TestAdminStorageStatusUnwired(t *testing.T) { + t.Parallel() + dir := t.TempDir() + barePath, conn := storageBareDB(t, dir, "unwired.db") + + cases := []struct { + name string + deps Deps + }{ + {"no path no conn", Deps{}}, + {"conn but no path", Deps{Database: conn}}, + {"path but no conn", Deps{DatabasePath: barePath}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + _, ts, jwt := buildEnv(t, cfgDefault(), tc.deps) + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusInternalServerError { + t.Fatalf("status = %d, want 500 (body=%s)", status, body) + } + wantErrorShape(t, body) + var env struct { + Code string `json:"code"` + } + if err := json.Unmarshal(decodeBody(t, body)["error"], &env); err != nil { + t.Fatalf("decode error envelope: %v", err) + } + if env.Code != "storage_unavailable" { + t.Fatalf("error code = %q, want storage_unavailable", env.Code) + } + }) + } +} + +// TestAdminStorageStatusMissingDocumentsTable 钉住「不静默报 0」：库没跑迁移 +// （documents 表不存在）时如实 500，而不是回 documents.count = 0。 +func TestAdminStorageStatusMissingDocumentsTable(t *testing.T) { + t.Parallel() + dir := t.TempDir() + barePath, conn := storageBareDB(t, dir, "bare.db") + _, ts, jwt := buildEnv(t, cfgDefault(), Deps{DatabasePath: barePath, Database: conn}) + + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusInternalServerError { + t.Fatalf("status = %d, want 500 (body=%s)", status, body) + } + wantErrorShape(t, body) +} + +// TestAdminStorageStatusIsReadOnly 钉住「只读」：查询前后 documents 行数与数据 +// 目录里的文件集合都不变（既没有写、也没有顺手备份）。 +func TestAdminStorageStatusIsReadOnly(t *testing.T) { + t.Parallel() + dir := t.TempDir() + dbPath, conn := storageTestDB(t, dir, []int64{5, 7}) + _, ts, jwt := buildEnv(t, cfgDefault(), Deps{DatabasePath: dbPath, Database: conn}) + before := listDir(t, dir) + + status, body := getStorageStatus(t, ts.URL, jwt) + if status != http.StatusOK { + t.Fatalf("status = %d, want 200 (body=%s)", status, body) + } + var count int64 + if err := conn.QueryRowContext(context.Background(), + `SELECT COUNT(*) FROM documents`).Scan(&count); err != nil { + t.Fatalf("count documents: %v", err) + } + if count != 2 { + t.Fatalf("documents rows = %d, want 2 (endpoint wrote something)", count) + } + after := listDir(t, dir) + if !sameFileSet(before, after) { + t.Fatalf("data dir changed: before=%v after=%v", before, after) + } +} + +// storageBareDB 打开 dir/name 的 SQLite 文件库但**不跑迁移**（用于演练 +// 「表不存在」「连接未接线」这两类边界）。 +func storageBareDB(t *testing.T, dir, name string) (string, *sql.DB) { + t.Helper() + path := filepath.Join(dir, name) + conn, err := db.Open(context.Background(), path, gwTestLogger()) + if err != nil { + t.Fatalf("open bare db: %v", err) + } + t.Cleanup(func() { _ = conn.Close() }) + return path, conn +} + +// listDir 返回 dir 下的文件名集合，用于「端点没动文件系统」的断言。 +func listDir(t *testing.T, dir string) map[string]bool { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatalf("read dir: %v", err) + } + names := make(map[string]bool, len(entries)) + for _, e := range entries { + names[e.Name()] = true + } + return names +} + +// sameFileSet 比较两个文件名集合（与顺序无关）。 +func sameFileSet(a, b map[string]bool) bool { + if len(a) != len(b) { + return false + } + for name := range a { + if !b[name] { + return false + } + } + return true +} diff --git a/internal/services/gateway/deps.go b/internal/services/gateway/deps.go index d229dcc..7516b7d 100644 --- a/internal/services/gateway/deps.go +++ b/internal/services/gateway/deps.go @@ -1,6 +1,7 @@ package gateway import ( + "database/sql" "io/fs" "log/slog" "net/http" @@ -10,6 +11,23 @@ import ( "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model" ) +// VectorState 是组合根报告的向量增强（pgvector）运行状态，供管理侧 +// 「存储状态」端点回答「PG 到底有没有生效」（design/03 §3）。 +// +// 它是**复用**而非探测：网关不读环境变量、不新开 PG 连接、不 +// 自行 ping —— 真相只有组合根知道（DB_PG_URL 是否配置 + 活的向量 +// 索引是哪个后端），因此由它注入，避免面板看到与运行时不一致的 +// 第二个判断。 +type VectorState struct { + // Configured 报告 DB_PG_URL 是否已配置（非空即算），即 + // 增强开关在不在。 + Configured bool + // Live 报告当前活的向量索引确实是 PostgreSQL+pgvector 后端。 + // 配置了但连接/schema 准备失败时为 false —— 此时语义检索已降级， + // 面板必须显示「未就绪」而不是假装增强生效。 + Live bool +} + // Deps 承载网关被注入的依赖。除 Auth 外每个字段都容忍 // nil，Auth 是必需的（认证支撑登录与每一个 RBAC // 决策）。Registry/Loop 由具体的 *capability.Registry 与 @@ -91,6 +109,16 @@ type Deps struct { // 图片上传存储（/uploads）及其静态路由。可选； // 为空时上传 handler 回退到 cfg.DataDir。 DataDir string + // Database 是组合根已打开的活 SQLite 连接池。管理侧的 + // 「存储状态」只读端点用它读页级统计与 documents 表 —— + // 复用既有池，端点自身不另开连接或连接池。可选；为 nil 时 + // 该端点诚实作答（500 storage_unavailable），绝不假装 + // 拿到了数据。 + Database *sql.DB + // Vector 是组合根报告的向量增强（pgvector）运行时状态， + // 见 VectorState。网关只读它，绝不自行探测。可选；零值 + // 表示「未配置」（kind:"none"），与未启用增强的部署一致。 + Vector VectorState // Streaming 标记注入的 Loop 具备流式能力（其 OnStream // 已接线为发布 ws.stream_chunk）。设置后 hub 会跳过它自己的 // 单次最终 stream_chunk 发送，因为增量已通过 OnStream 流出。 diff --git a/internal/services/gateway/routes.go b/internal/services/gateway/routes.go index 8bfbbc2..8e4781f 100644 --- a/internal/services/gateway/routes.go +++ b/internal/services/gateway/routes.go @@ -227,6 +227,9 @@ func (s *Server) registerAdminWriteRoutes(mux *http.ServeMux, ownerAuth func(htt mux.Handle("POST /api/v1/admin/system/rotate-jwt", ownerAuth(http.HandlerFunc(s.adminRotateJWT))) mux.Handle("POST /api/v1/admin/system/backup", ownerAuth(http.HandlerFunc(s.adminBackup))) mux.Handle("POST /api/v1/admin/system/restore", ownerAuth(http.HandlerFunc(s.adminRestore))) + // 存储状态**只读**查询（面板首页「存储」卡的数据源，v0.60）：只读、不审计， + // 因此与四个动作端点同门（owner）但不带审计动作。 + mux.Handle("GET /api/v1/admin/system/storage", ownerAuth(http.HandlerFunc(s.adminStorageStatus))) } // mountWebhooks 挂载外部提供的入站回调（例如 webhook diff --git a/internal/services/gateway/server.go b/internal/services/gateway/server.go index 4a4081b..e777df5 100644 --- a/internal/services/gateway/server.go +++ b/internal/services/gateway/server.go @@ -20,6 +20,7 @@ package gateway import ( "context" + "database/sql" "fmt" "io" "io/fs" @@ -79,6 +80,13 @@ type Server struct { // （尽力而为）。见 Deps.OwnerRegistrar。 ownerRegistrar OwnerRegistrar webhooks map[string]http.Handler + // db 是组合根注入的活 SQLite 连接池（见 Deps.Database）。管理侧 + // 「存储状态」只读端点用它读页级统计与 documents 表；为 nil 时该 + // 端点回 500 storage_unavailable（不另开池、不假装有数据）。 + db *sql.DB + // vector 是组合根报告的 pgvector 增强运行时状态（见 + // Deps.Vector / VectorState）。零值 = 未配置。 + vector VectorState // envResolver 解析会话每轮的 loop 环境（其角色）。见 // persona_env.go / design/22 §4.5。 envResolver turnEnvResolver @@ -124,6 +132,8 @@ func New(cfg *config.Config, deps Deps) (*Server, error) { webhooks: deps.Webhooks, dbPath: deps.DatabasePath, dataDir: deps.DataDir, + db: deps.Database, + vector: deps.Vector, log: sourcedLog(deps.Log), } // 一个角色解析器由 Server 各处理器与 hub 共用，使每个面向 owner