docs(contract): v0.94 MCP 管理面与工具 origin + v0.95 渠道静默窗口，含写门不对称与呈现隔离口径

Docs/api-client.md

@@ -1,6 +1,6 @@
 # Cyrene v2 客户端 API 契约
 
-> **契约版本：`v0.91`**（上一版 `v0.90`，其条目见 §6；`v0.89` / `v0.88` / `v0.87` / `v0.86` / `v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。
+> **契约版本：`v0.95`**（上一版 `v0.94`，其条目见 §6；`v0.89` / `v0.88` / `v0.87` / `v0.86` / `v0.85` / `v0.84` / `v0.83` / `v0.82` / `v0.81` / `v0.80` / `v0.79` / `v0.78` / `v0.77` / `v0.76` / `v0.75` / `v0.74` / `v0.73` / `v0.72` / `v0.71` 及更早见本文件 §6，`v0.67` 及更早的基线已归档、只读：`Docs/archive/api-client.v0.65.md`）。
 > **读者**：Web 前端 / 移动端原生客户端（含 Android）/ IM 桥接等**跨平台客户端开发者**。
 > **唯一真源 = 当前代码**（`internal/services/gateway/*` 等）。本文档由代码逐条核对得出；与代码不符时**以代码为准**，并回改本文档。
 > **旧的超详细版已归档、只读**：`Docs/archive/api-client.v0.65.md`（412 KB，含 v0.28→v0.65 全部历史条目）与 `Docs/archive/api-reference.v0.65.md`（170 KB，后端全量字段级文档）。归档的原因是**结构性臃肿 + 历史条目并列 + 长期漂移**；本文档**不复制**那段历史，需要考古时去归档。
@@ -161,7 +161,8 @@
 
 **管理路由总数 = 18 + 43 + 43 = 104 条（2026-10-24 实测，`routes.go` 逐条枚举）。**
 > 🔴 **本节计数曾长期偏低，已按实测改正**：`14 + 25 + 40 = 79`（v0.85–v0.91）与 `14 + 27 + 40 = 81`（v0.92）**都对不上代码**。2026-10-24 由复审逐条解析 `routes.go` 得到：**base（含 M22 前）`total=102` → 分组 `18 / 41 / 43`**；**合入 M23（coalesce 两端点）后 `total=104` → 分组 `18 / 43 / 43`**（`writeAuth` 41 → **43**，新增 `GET/PUT /api/v1/admin/channels/coalesce`）。三组口径：`viewerAuth`=18 / `writeAuth`=43 / `ownerAuth`=43，另有 `anyAuth`=3、`unwrapped`=1 未计入本表三段。
-> ⚠️ **v0.94（MCP 管理页 + 按上游分节的 `origin`）与 v0.95（coalesce 两端点 + 窗口语义）的条目尚未逐条登记**——本节计数已按实测更新，但**形状级条目仍待补**，见 §7.1。
+> ✅ **v0.94（MCP 管理页 + 按上游分节的 `origin`）与 v0.95（coalesce 两端点 + 窗口语义）的形状级条目已登记**，见 §6 v0.94 / v0.95。
+> ⚠️ **但本节上面的三条清单（A 14 / B 27 / C 40 = 81 行）仍落后于实测的 104 条路由**（差 23 条历史遗漏行）：计数以 `routes.go` 实测为准，清单尚未逐行补齐 —— 这是**已知文档债**，不是「没有那些端点」。补齐登记进行中（切片 CONTRACTMATRIX）。
 
 > **v0.78 计数变更**：`viewerAuth` 段新增两条（A13 `GET /admin/panels`、A14 `POST /admin/plugins/{id}/actions/{action}`）⇒ 12 → **14**、总数 66 → **68**。A14 走 `viewerAuth` 中间件，但**写动作在 handler 内按 owner/admin 收紧**（路由中间件只能有一道门）—— 因此它**是**本表的一行，读写面却不同档，详见 §2.1 A14 与 §4.14。
 
@@ -1575,7 +1576,49 @@ curl -s -X POST -H "X-API-Key: $KEY" \
 > 只保留最近若干版（**v0.60 起**）；更早的全部历史见归档 `Docs/archive/api-client.v0.65.md` §5（v0.28 → v0.59）。
 > 每版一句话 + 三档标注。**三档定义见 [§0.4](#04-三档标注惯例)。**
 
-### v0.93（当前契约版本）
+### v0.95（当前契约版本）
+
+**「渠道静默窗口可写」版 —— 群里「一鼓作气打三句」只回一次，且参数在面板上调（切片 M23）**
+
+- **新增 `GET /api/v1/admin/channels/coalesce`（读）** 与 **`PUT` 同路径（写）**。门 = `writeAuth`（owner｜admin；`viewer` → 403、未认证 → 401），与 `admin_memory_tuning` 同档：它写的是**面板配置文件**，不是身份/凭据面。GET 只读不审计；PUT 落审计 **`channels.coalesce`**（`result` ∈ `ok|error`）。
+- **写面是「三态补丁」**（键缺位 ⇒ 不动；合法值 ⇒ 采用；非法值 ⇒ **`400 invalid_payload` 且盘上一个字节都不动** —— 校验全部发生在落盘之前）：
+  | 键 | 含义 |
+  | --- | --- |
+  | `enabled` | 是否启用静默窗口合并（bool） |
+  | `windowMs` | 首条到达后再等多久收批（ms） |
+  | `maxWaitMs` | **硬上限**：从首条算起最多等多久，到点就发车 |
+  | `maxBatchMessages` | 一批最多攒几条，够数立即发车 |
+  | `applyToStrangers` | 是否对陌生人/成员车道也应用（bool） |
+  | `strangerWindowMs` | 陌生人/成员车道的独立窗口（ms） |
+- **每会话覆盖**：请求/响应带 `conversations` 映射（会话 id → 同一组键的补丁），因此窗口是**按会话**算的，不是适配器顶层一个值。
+- **热生效是事实不是承诺**：桥每次发车从**同一个** store 实例读生效值 ⇒ 保存后下一次发车即用新值，响应里 `hot:true`。
+- 🔴 **主人私聊不受此设置影响，且没有任何键能翻转它**：车道类型由 actor 元数据决定（`!msg.IsGroup() && actor.IsOwner()` ⇒ direct 车道、**没有窗口对象、拿不到定时器工厂**）。响应里下发 `ownerPrivate:"never"` 是**只读事实**，面板据此只显示一行说明、不给开关。
+- 🔴 **一批 = 一个 `turnID` = 一次 `loop.Run` = 一条助手回复**，但批内 N 条仍是**各自一行 `user`**（同 `turnID`、顺序 = 到达顺序），助手回复与它们同 `turnID`。⇒ 客户端按 `turnID` 聚合时，一个回合会看到 N 条用户消息 + 1 条助手消息。
+- **零新 `.env` 键**（design/13 §2.1）：配置落 `$DATA_DIR/config/coalesce.json`。
+
+### v0.94
+
+**「MCP 管理面 + 工具来源」版 —— 新增一页声明式管理面板，并给能力条目加可选 `origin`（切片 M20 / M30）**
+
+- **前端路由 `/admin/plugin/mcp/servers`**。它**不是新路由/新端点**：这是在既有面板目录里声明的一页（`id = mcp`，`panel = servers`），字段与动作都由 `pkg/plugins/sdk` 的 `Panel` 描述，前端用**既有通用渲染器**画。
+- **所有动作走既有的通用分发端点 `POST /api/v1/admin/plugins/mcp/actions/<action>`**（插件只给动作名、不给 URL）。**7 个动作**：
+  | 动作名 | 档 | 作用 |
+  | --- | --- | --- |
+  | `plugin.mcpServers` | 读 | 全部 server 的状态快照（表格数据源） |
+  | `plugin.mcpTransports` | 读 | 传输形态候选（`stdio` / `sse` / `http`） |
+  | `plugin.installMcpServer` | 写 | 安装（或刷新）一台 server |
+  | `plugin.reconnectMcpServer` | 写 | 断开重连并重新发现工具 |
+  | `plugin.enableMcpServer` | 写 | 启用一台被停用的 server |
+  | `plugin.disableMcpServer` | 写 | 停用一台 server |
+  | `plugin.uninstallMcpServer` | 写 | 卸载一台 server |
+- **鉴权在两处**：路由挂 `viewerAuth`（读动作 viewer 可用），**写动作由分发器再查 `callerHasWrite`（owner｜admin）**，每次写动作落审计。失败码是**稳定闭集**（前端按码本地化，不解析文案）：`invalid_config` / `install_failed` / `reconnect_failed` / `enable_failed` / `disable_failed` / `uninstall_failed` / `server_not_found` / `server_disabled`。
+- 🔴 **安全提示（客户端/运维必读）**：`transport=stdio` 的 `command` + `args` 等于**在本机执行任意命令**，安装即生效。⚠️ **本版存在一处档位不对称（已 file finding，未在本版修）**：面板的写动作是 **owner｜admin**，而 REST 的 `POST /api/v1/admin/plugins/install` 与 `/uninstall` 是 **owner-only**（`ownerAuth`）⇒ 一个非 owner 的 `admin` 可以通过面板动作装上一台 stdio server，却走不通 REST 安装口。单 admin 部署无实际差别，多账号部署请把 admin 视同 owner 收敛。
+- **工具条目新增可选 `origin` 对象**：`{ "kind": "mcp", "server": "<server 名>", "transport": "stdio|sse|http" }`。**宿主内置能力整键缺席**（不是空对象）—— 「没有 `origin`」正是「宿主自己提供」的表达。
+  - 🔴 **归属只来自注册那一刻的元数据，绝不解析工具名字前缀**：MCP server 的工具名由它自己给，宿主不加前缀；实测一台 `halo` server 的工具分属 4 个不同前缀族 ⇒ 按前缀猜归属必错。
+  - **这是呈现隔离，不是权限隔离**：`tool_policies` 没有 server 维度，`mcp:<server>` 策略行是惰性的 ⇒ **本版不提供「按 server 开关工具」，也不给假开关**。
+
+### v0.93
+
 
 **「审查预算的唯一真源」版 —— 一个 env 默认值两处副本导致的静默失效**（实现切片 M16；起因 = **塔在部署后读真实启动行时发现** v0.92 那批修复里的 F1 **根本没生效**）