feat(ql3): add bounded copilot mcp surface

docs/QINGLONG_3_0_ARCHITECTURE_RFC.md

@@ -11,6 +11,7 @@
 
 最新增量证据（2026-08-16）：
 
+- D-325/ADR-0417（已接受）：Cluster Copilot 现已提供独立、受限、可部署的 MCP stdio 产品面。实现没有扩展旧 2.x Web UI，也没有把 Cluster authority 塞入 Edge/Standalone 的 `@qinglong/local-mcp-server`；而是在既有 `@qinglong/cluster-admin` 的内聚 `copilot-mcp/` 目录新增 `ql3-copilot-mcp` 与 `./copilot-mcp` export，workspace 仍保持 18 package。四个静态 Tool 只接收 Project、source Run、diagnosis request、trace/mutation identity，并直接调用 D-324 的共享 TypeScript client；不启动 CLI 子进程、不写 command 临时文件、不监听网络、不直连数据库/application capability，也不允许调用者提供 URL、header、credential、Model/Provider、Artifact、usage/cost 或 Policy fence。owner-private 0600 配置只保存 client config/credential 路径和显式 `1..16` 并发上限；credential 每次 Tool call 都重新执行 canonical/private/TOCTOU 与 token 校验，rotation 下一次调用立即生效。满载即时返回 `copilot_mcp_busy`，没有隐藏 queue、retry、poller、timer、watcher 或 cache。所有结果使用 exact `qinglong/cluster-copilot-mcp-result@v1`，固定 `instructionPolicy=data_only_never_execute` 与 `actionAuthority=none`；只有 output Tool 标为 `potentially_sensitive`/`untrusted_model_output`，远端错误仅投影有界 status/code/request identity/Retry-After。真实 stdio + TLS 1.3 E2E 已覆盖 initialize、discovery、四次直接请求、Bearer credential 热轮换、无 client certificate、敏感输出标注与 graceful close；并发和未知字段均失败关闭。Cluster Admin 完整测试 361 pass/3 条件 skip，18-package clean build/test 退出 0，backend 1,207 pass/2 条件 skip/0 fail；package/dependency/Edge import/Cluster deployment 四项审计零 finding，Cluster Admin 为 116 个源码且 115 个位于嵌套职责目录。Cluster Admin 镜像精确加入已固定的 `@modelcontextprotocol/server@2.0.0`，SBOM 为 91 components/87 external/4 internal；Cluster Control 和全部 Local 闭包不变。14 档 Local artifact 全部通过，默认 Edge/Standalone 仍为 2,589,890/2,589,968 bytes、315 files、56 modules，证明 Cluster MCP 没有进入低配路由设备；本 Gate 无 schema、migration、SQL、role、Pool、连接或部署拓扑变化，因此不重跑物理 HA，继续引用 D-323 PostgreSQL 18.6 arm64 142/142、timeline `1→2` 基线。下一独立 Gate 应冻结 Cluster UI ownership 或增加 MCP host 的明确部署清单/运维面，仍必须复用同一 API，不得回接 2.x controller/session 或扩大 credential authority。
 - D-324/ADR-0416（已接受）：Cluster Copilot failure diagnosis 已获得首个可直接部署的有界产品客户端。既有 `@qinglong/cluster-admin` 在内聚的 `copilot-client/` 目录提供共享 client 与 `ql3-copilot-client`，统一 `ql3-cluster-admin copilot` 静态委托同一 binary；没有为三个实现文件新增 workspace package。客户端只接受 owner-private 0600 的绝对 `--config`、`--command`、`--credential` 文件路径，Project API credential 固定为独立 `ql3c_` Bearer authority，禁止写入 argv 值、环境、stdin、command 或 operator context，也不复用管理面的 User JWT/mTLS client certificate。`diagnose|inspect|output|cancel` 四个 operation 只调用 D-321 至 D-323 的既有 API，TLS 固定 1.3、显式 CA/DNS、无连接复用/压缩/redirect/proxy/ambient CA；diagnose request identity、cancel mutation identity 和只读 transport identity 必须与唯一响应 `x-request-id` exact matching。成功响应重新执行 schema、target、状态机、digest、usage/cost 与 UTF-8 byte exact validation；只有调用者显式选择 `output` 才向 stdout 返回诊断文本，远端失败只投影 status、稳定 code、request identity 与有界 Retry-After。operator context 只能保存 Copilot config 路径，并新增离线 validate 与无认证固定 `GET /readyz` probe，不能保存 credential/command 或获得调用 authority。workspace 保持 18 package、`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Cluster Admin 从 109 增至 112 个源码，其中 111 个在嵌套职责目录，未新增生产依赖、schema、migration、SQL、role、Pool、连接、进程、timer、watcher、queue、cache、Pod、Service 或 Kubernetes 权限。Copilot/产品 CLI 定向 19/19、Cluster Admin 354 pass/3 条件 skip、18-package clean build/test 退出 0、backend 1,207 pass/2 条件 skip/0 fail；package/dependency/Edge import/Cluster deployment 四项审计零 finding，14 档 Local artifact 全部通过。默认 Edge/Standalone 仍为 2,589,890/2,589,968 bytes、315 files、56 modules，证明 Cluster-only client 没有进入低配路由设备闭包。本 Gate 没有数据库或部署拓扑变更，因此不重跑物理 HA，继续引用 D-323 的 PostgreSQL 18.6 arm64 142/142、timeline `1→2` 与 SHA-256 `5dbcffb74a3181aabee66a8f68ecfa7a65e0491a6f2ba24e2bc903c83da9d766` 基线。下一独立 Gate 可让 UI/MCP 复用同一公开 API/contract，不能执行 CLI 子进程、直连 application capability/数据库或扩大 credential authority。
 - D-323/ADR-0415（已接受）：Cluster Copilot failure diagnosis 已补齐受围栏的 request-keyed 取消 mutation。`POST /api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}/cancellation` 复用 exact `qinglong/run-cancellation@v1` body、`run.stop` 当前 Policy、durable audit 与通用 PostgreSQL Run cancellation transaction；调用方只能提供 `mutationId`，diagnosis Run、Event、reason、Provider 与终态均由服务端从 admission plan/receipt 和 durable authority 派生。pre-Model 取消立即与 Model start 通过 Run/Step/version fence 竞争并原子 terminalize；Model start 获胜时只返回 `model_in_flight` durable intent，不伪造 Provider abort、终态、usage 或 cost，真实 completion/finalization 仍可成为最终 winner。相同或不同 mutation 都不能追加第二个 intent/Event 或覆盖首次 reason/time。能力只注入默认关闭的 Cluster AI profile，复用既有 AI Pool、repository、Policy pipeline 与进程，不新增 package、schema、Pool、连接、timer、watcher、queue、cache、端口、Pod、Service 或 Kubernetes 权限，Edge/Standalone 与普通 Cluster Control 均无该 route。目录审计曾拒绝 `failure-diagnosis` 达到 12 个直属源码文件；最终删除仅做 re-export 的单文件 façade，让公开 package subpath 直接指向 `cancellation/service`，而不是再拆 package 或放宽阈值。workspace 保持 18 package，`singleSourcePackages=[]`、`shallowSourcePackages=[]`，AI 194 个源码中 193 个、Cluster Control 64 个源码中 62 个位于嵌套职责目录。AI 254 pass/3 条件 skip、Cluster Control 261 pass/2 条件 skip、18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail；四项架构审计和 14 档 Local artifact 全部通过。默认 Edge/Standalone 为 2,589,890/2,589,968 bytes，Edge/Standalone AI application 为 4,493,043/4,493,175 bytes，证明 Cluster-only mutation 未进入低配闭包。PostgreSQL 18.6 arm64 physical HA 142/142、timeline `1→2`，覆盖 intent/Event/terminal receipt 同步复制、promotion 后 exact replay 与 in-flight 不伪造终态；报告 SHA-256 为 `5dbcffb74a3181aabee66a8f68ecfa7a65e0491a6f2ba24e2bc903c83da9d766`，离线审计零 finding。下一独立 Gate 可选择 CLI/UI/MCP 客户端或带 Provider abort acknowledgement 的取消语义，不得在没有 durable acknowledgement 时宣称外部调用已停止。
 - D-322/ADR-0414（已接受）：Cluster Copilot failure diagnosis 已补齐 request-keyed 产品读模型。`GET /api/v3/projects/{projectId}/runs/{runId}/copilot/failure-diagnoses/{requestId}` 只需 `run.read`，投影 running/terminal、取消/失败 stage/reason、authoritative admission/finalization time 与 durable usage/settled cost；同路径 `/output` 独立要求 `artifact.read`，只在 admission plan/receipt、Project/source Run、finalization、invocation 和 encrypted Artifact 全部 exact binding 且 current Project Policy 再授权后解析 historical key。调用者不能提交 Artifact、diagnosis Run、Model invocation、provider/model、价格、usage、outcome 或 key identity；deny/approval/absent/cross-target 统一 404，存储/Policy/key/decrypt/cipher 冲突统一 503。写 `capability` 与 `readCapability` 接口隔离，production 复用既有 AI PostgreSQL Pool、repository、Project Policy 与 projected output keyring，不新增 package、进程、端口、Pool、timer、watcher、queue、cache、Pod、Service 或 Kubernetes 权限；普通 Cluster Control、Edge/Standalone 均无这些 route。workspace 保持 18 package、`singleSourcePackages=[]`、`shallowSourcePackages=[]`，AI 193 个源码中 192 个、Cluster Control 62 个源码中 60 个位于嵌套领域目录。AI 249 pass/3 条件 skip、Cluster Control 256 pass/2 条件 skip、18-package clean build/test 与 backend 1,207 pass/2 条件 skip/0 fail，四项架构审计和 14 档 Local artifact 全部通过；默认 Edge/Standalone 仍为 2,589,890/2,589,968 bytes，Edge/Standalone AI 为 3,069,143/3,069,233 bytes。PostgreSQL 18.6 arm64 physical HA 139/139、timeline `1→2`，成功密文输出在 standby 可读，提升后 request-keyed exact replay 且 provider 调用为零；报告 SHA-256 为 `22decb54cfb8735bf787fe0665c877c201fc7b44d3c3de16fdbfdab31b7ac2cd`，离线审计零 finding。下一独立 Gate 可评审取消 mutation、CLI/UI/MCP 客户端或真实 Provider，不得把它们混入读边界。

docs/adr/ADR-0417-bounded-cluster-copilot-mcp-stdio-surface.md

@@ -0,0 +1,38 @@
+# ADR-0417：有界 Cluster Copilot MCP stdio 产品面
+
+- 状态：Accepted
+- 日期：2026-08-16
+- 关联 RFC：QL-RFC-0001 D-325、Phase 2
+
+## 背景
+
+D-324 已提供受审的 Cluster Copilot 共享客户端与一次性 CLI，但 Agent/MCP host 若只能启动 CLI 子进程，就会复制 command 文件、错误投影与进程生命周期，并可能把 credential 放进 argv、环境变量或临时文件。现有 `@qinglong/local-mcp-server` 明确拥有 Edge/Standalone 的本地 SQLite、Owner credential 与 Artifact authority；让它依赖 Cluster Admin 会把 Kubernetes、PostgreSQL 和 Cluster 客户端闭包带进低配 MCP 制品，也会混淆本地 Owner 与远程 Project API credential 两种安全域。
+
+QingLong 3.0 尚无独立的 Cluster Web UI ownership。此时直接修改 2.x 前端会让新 API 重新依赖旧 controller/session 语义。Cluster Copilot MCP stdio 是更小但完整的产品面：它能直接复用 D-324 library 和 D-321 至 D-323 的服务端认证、Policy、audit、quota 与 durable state，同时保持 UI 以后也只能走同一 HTTP contract。
+
+## 决策
+
+1. 在既有 `@qinglong/cluster-admin` 的 `copilot-mcp/` 嵌套职责目录增加 `ql3-copilot-mcp`；不新增 workspace package，不修改 `@qinglong/local-mcp-server`，也不让任何 Edge/Standalone importer 依赖 Cluster Admin。
+2. MCP server 使用已固定版本的 `@modelcontextprotocol/server` 和 stdio transport，不监听网络端口。进程只接受一个 owner-private 0600 配置文件路径；配置只含 D-324 client config 路径、API credential 文件路径和显式 `1..16` 并发上限，不含 credential value、Project、Run、Prompt、输出或 Policy。
+3. 暴露四个静态 Tool：`qinglong.cluster.copilot.failure_diagnose`、`qinglong.cluster.copilot.failure_diagnosis.get`、`qinglong.cluster.copilot.failure_diagnosis.output.get`、`qinglong.cluster.copilot.failure_diagnosis.cancel`。输入只含构造 D-324 exact command 所需的 Project、source Run、diagnosis request、trace 或 mutation identity；调用者不能提交 URL、header、credential、diagnosis Run、Artifact、Model/Provider、reason、outcome、usage、cost 或服务端 Policy fence。
+4. MCP handler 直接调用共享 TypeScript client，不启动 CLI 子进程、不写 command 临时文件、不直连 application capability、AI repository 或数据库。D-324 文件型 CLI 继续兼容；共享 client 新增 command-object 入口并与文件入口复用同一 TLS、credential、request identity、response validation 和内存清理实现。
+5. API credential 文件在每次 Tool call 重新执行 canonical/private/TOCTOU 与 token 格式校验；进程只保留路径，不缓存 secret。credential rotation 因此在下一次调用生效，失效或权限漂移立即失败关闭。
+6. 并发达到配置上限时立即返回 `copilot_mcp_busy`，不建立隐藏队列、timer、poller、retry、watcher、cache 或后台任务。每个请求仍受 D-324 的 TLS request timeout、2 MiB response cap 与服务端 quota 约束。
+7. 所有成功结果都使用 exact `qinglong/cluster-copilot-mcp-result@v1` envelope，标记 `instructionPolicy=data_only_never_execute`、`actionAuthority=none`。diagnose/inspect/cancel 标记 `low`；output 明确标记 `potentially_sensitive` 与 `untrusted_model_output`，只有调用该 Tool 才返回诊断文本。MCP annotation 将 diagnose 标为有成本的非只读调用、cancel 标为 destructive，read/output 标为只读。
+8. MCP 失败只返回稳定 code；远端拒绝可附带 bounded status、response code、request identity 与 Retry-After，不返回 response body/header、credential、路径、TLS/文件异常或 output。stdio transport 错误与启动错误也只写低敏 stderr fact。
+9. 本 Gate 不新增 route、数据库 schema/migration/role/Pool/连接、Kubernetes Pod/Service/RBAC 或 Cluster Control 进程。Cluster Admin 生产依赖允许复用 workspace 已固定的 MCP server 版本；Cluster deployment audit 必须显式记录新增依赖闭包，Local 14 档 artifact 必须证明低配闭包字节数不变。
+
+## 不选择
+
+- **让 MCP host 调用 `ql3-copilot-client` 子进程**：重复文件和进程协议，难以稳定标注 potentially-sensitive output，也绕开共享并发边界。
+- **扩展 `@qinglong/local-mcp-server` 支持 Cluster**：会污染 Edge/Standalone MCP 依赖与本地 Owner 安全域。
+- **新建 `@qinglong/cluster-mcp-server` package**：当前只有四个同域 Tool，会再次形成过细 package 并突破 18-package 硬上限。
+- **直接接入旧 Web UI controller/session**：3.0 尚未冻结 Cluster UI ownership，会把新 API 绑定回 2.x 语义。
+- **在 MCP 进程缓存 credential 或自动轮询 diagnosis**：扩大 secret 生命周期和隐藏资源消耗，并混淆 transport timeout 与 durable 状态。
+
+## 验收
+
+1. 覆盖四个 Tool 的 exact discovery/input/annotation、command mapping、成功 trust/sensitivity envelope、远端低敏错误、并发立即拒绝和未知字段失败关闭。
+2. 真实 TLS 1.3 fixture 证明 MCP 直接复用 client、每次重读 credential、无 client certificate、无 CLI 子进程，并覆盖 diagnose/inspect/output/cancel。
+3. stdio E2E 覆盖 initialize、tools/list、四个 tools/call、potentially-sensitive output、低敏 stderr 与 graceful close；进程退出后不得残留 listener、timer 或 child process。
+4. Cluster Admin、18-package clean build/test、backend、package/dependency/Edge import/Cluster deployment 和 14 档 Local artifact 全部通过后才允许 D-325 阶段提交；本 Gate 无数据库变更，不重复物理 HA，继续引用 D-323 基线。

docs/adr/README.md

@@ -420,6 +420,7 @@
 | [ADR-0414](./ADR-0414-copilot-failure-diagnosis-read-model.md)                                    | Copilot 故障诊断请求键读模型                                                                                                                                | Accepted |
 | [ADR-0415](./ADR-0415-fenced-copilot-failure-diagnosis-cancellation.md)                            | 受围栏的 Copilot 故障诊断取消入口                                                                                                                            | Accepted |
 | [ADR-0416](./ADR-0416-bounded-cluster-copilot-product-client.md)                                  | 有界 Cluster Copilot 产品客户端                                                                                                                              | Accepted |
+| [ADR-0417](./ADR-0417-bounded-cluster-copilot-mcp-stdio-surface.md)                               | 有界 Cluster Copilot MCP stdio 产品面                                                                                                                        | Accepted |
 
 ## 规则