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

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 基线。