qinglong/docs/adr/ADR-0401-optional-local-mcp-run-comparison-surface.md

ADR-0401：可选本机 MCP Run 对比产品入口

• 状态：Accepted
• 日期：2026-08-14
• 关联 RFC：QL-RFC-0001 D-309、Phase 2
• 关联 ADR：ADR-0347、ADR-0351、ADR-0400

问题

ADR-0400 已在 Runtime Core 建立 qinglong.run.compare@1.0.0 的稳定 Definition、低敏 projection 和受信 adapter，但尚无产品 composition 使用它。QingLong 3.0 的外部 AI 客户端 因此只能分别调用两个 Run 点查，再自行拼接差异；这无法让服务端统一执行输入约束、Project 屏蔽、差值算法和一致性声明，也没有独立的调用审计理由。

本机已经有由 ADR-0347 建立的可选 ql3-mcp stdio 进程。它逐调用执行认证、Tool Policy、 durable Security Audit、credential fence confirmation 和有界 SQLite read，且只在部署者显式 选择 edge-mcp|standalone-mcp 制品时加载 MCP SDK。新增对比能力不应再造进程、package、 数据库 authority 或后台服务，也不能把 MCP 依赖带入默认低配 Profile。

决策

1. 在既有 @qinglong/local-mcp-server 静态只读 Tool 集合中注册 qinglong.run.compare@1.0.0。Definition 与执行投影必须直接来自 Runtime Core 的 /builtin-run-compare-projection 显式 subpath；MCP 不复制 schema、字段裁剪或差值算法。
2. 调用沿用同一固定顺序：每次重新认证 → 授权 tool.call:qinglong.run.compare → 授权 run.read → durable audit → confirm credential fence → baseline/candidate 两次有序 Project-scoped point read。允许审计理由固定为 tool_qinglong_run_compare，repository/投影失败只返回稳定 run_compare_unavailable。
3. MCP Tool 继续声明 readOnlyHint=true、destructiveHint=false、 idempotentHint=true、openWorldHint=false。Project ID 只来自私有进程配置，客户端不能 选择；找不到与跨 Project 均由共享投影输出 found:false。
4. 该入口属于 ADR-0347 的轻量交互式只读 surface：它持久记录安全 admission，但不冒充 ADR-0163 的 encrypted Tool execution completion、StepRun 或模型 Trace。Agent/Copilot 内部经 Run/StepRun 执行受信 Tool 时仍必须走完整 start/result completion 链；未来如需让 MCP 调用本身成为 Run，必须独立设计 correlation 与重放语义，不能在本协议中静默增加写入。
5. 不新增 workspace package、依赖、migration、表、索引、连接、timer、listener、watcher、 cache 或网络 endpoint。LocalSqliteMcpReadDatabase 现有 findRunById authority 已足够，不扩大其读写接口。

低配与部署影响

• 默认 Edge/Standalone application 与制品继续不导入 MCP package；未选择 MCP 的路由设备 没有新增安装体积、模块加载或空闲 RSS。
• 选择 MCP 的设备只增加一个静态 descriptor；单次对比最多增加两次串行 Run 点查，不产生 并发数据库连接或后台采样。
• Cluster Control 不通过本 ADR 开放 MCP endpoint。Cluster 的受信 Tool composition、远程 身份、限流和 PostgreSQL completion 仍须独立门禁。
• 实现留在已有 deployable MCP package 内，不为单个 adapter 创建微型 package，也不把 MCP-only glue 移入 Runtime Core。

被否决方案

1. 复制 Run compare 到 MCP tool-projection：该语义已有 Runtime Core adapter 和 MCP 两个消费者，复制会产生 Definition 与差值漂移。
2. 让客户端组合两次 run.get：服务端无法冻结读取顺序、一致性声明和审计语义。
3. 把 MCP Server 加入默认 Edge application：会让不使用 AI 的低配设备承担 MCP SDK 依赖与约 40 MiB 级加载成本。
4. 为 compare 新建 package 或数据库 adapter：没有独立生命周期、authority 或依赖隔离 收益，现有窄 reader 已满足需求。
5. 把交互式 MCP 读取伪装成完整 Trusted Tool completion：缺少 StepRun/Artifact/key/ replay correlation 事实，会给恢复和审计造成错误承诺。

当前验证

1. Local MCP 46/46：Tool discovery、固定 read-only annotations、双 permission、allowed audit reason、credential confirm、两个有序读取和共享差值投影全部通过。真实 stdio E2E 使用 fresh production migration SQLite、真实 Owner credential 与 Project Policy，比较两个真实 Run 后验证第九条 durable allowed audit。
2. 最终 18-package clean build/test 退出 0；backend 1,208 项为 1,206 pass、2 条平台条件 skip、0 fail。package boundary 保持 18 个 package，singleSourcePackages=[]、 shallowSourcePackages=[]；Cluster dependency、Edge import 与 Cluster deployment 审计 均无 finding。
3. 默认 Edge artifact 为 2,589,812 bytes/315 files/56 loaded modules，import RSS 增量 11,091,968 bytes，继续完全裁掉 MCP Server 与 SDK。Edge-MCP 为 7,219,977 bytes/ 792 files/217 modules、RSS 增量 38,649,856 bytes；Standalone-MCP 为 7,220,085 bytes/ 792 files/217 modules、RSS 增量 38,043,648 bytes，均低于 16 MiB/1,536 files/48 MiB 门。
4. GitNexus 对 LOCAL_MCP_READ_TOOLS 报告 LOW、0 上游； createQingLongLocalMcpServer 为 LOW、1 个直接产品调用方、0 条 execution flow。 dependency firewall 的 auditSourceImports 为 LOW、1 个直接测试调用方、0 条 flow； allowlist 只增加 exact compare projection subpath，宽 authority 负向门仍通过 53/53。

后续门禁

1. 增加按 Task 有界选择最近成功/失败 Run 的服务端 Tool，禁止模型执行无界搜索；
2. 日志解释另建 Artifact range、redaction、prompt-injection 和字节预算协议；
3. Copilot 调用走 Run/StepRun 与 encrypted result completion，建立模型/Tool Trace correlation；
4. 固定物理 Edge MCP 延迟/RSS 和真实撤权竞态证据。