qinglong/docs/adr/ADR-0354-exact-local-mcp-approval-preview.md

ADR-0354：精确、双授权的本机 MCP Approval 预览

• 状态：Accepted
• 日期：2026-08-10
• 关联 RFC：QL-RFC-0001 D-05、D-06、D-08、D-13、D-17、D-28、D-75、D-85、D-87、D-157、D-257、D-259、D-260、D-263、D-265、D-266
• 关联 ADR：ADR-0138、ADR-0347、ADR-0351、ADR-0353

背景

qinglong.approval.list 可以说明动作处于 pending、approved、rejected 或 consumed，但故意不返回 preview。AI Client 若无法看见经过 redaction contract 生成的动作摘要，就不能做有意义的人工转交；若直接取得完整 Approval 或 Tool Invocation Artifact，又会泄露 action reference、digest、主体与密文入口。现有 Approval 和 Tool preview 表已经分别保存 同一个 Project/action binding，缺口是最窄的精确关联读端口，而不是新表、Artifact 解密或审批写流程。

决策

1. 增加 qinglong.approval.get@1.0.0，输入只允许 requestId，Project 只能来自私有 MCP 配置。
2. 调用固定要求 exact tool.call:qinglong.approval.get、approval.read 和 artifact.read。两个既有只读权限缺一不可； 之后仍须 durable Security Audit 和 credential fence confirm。
3. SQLite/PostgreSQL 先按 Project+request ID 读取并复验 canonical Approval、request digest 与更新时间镜像；只有 tool.invoke 才按 projectId/actionRef/actionDigest/previewDigest 四元组 LEFT JOIN 已有 preview 表。
4. Adapter 必须规范化完整 preview Artifact，并复验 artifact/project/action/digest/redaction/size/time 的所有镜像；任何 漂移映射为稳定 unavailable。无匹配 preview 是合法的 previewAvailable=false，不得猜测或扫描。
5. Runtime read port 只携带 Approval record 与已经验证的 preview document。MCP package 不得 import Tool Invocation Artifact subpath，不得取得 artifact ID、repository、input ciphertext、key、nonce、auth tag、任一 digest 或解密 authority。
6. 输出只含 Approval list 已公开的低敏元数据、previewAvailable，以及有界 title、summary、最多 16 个 field 和 8 个 warning。redacted field 省略 value；不返回 Project、action reference、主体 ID、fence 或决定/消费/派发证据。
7. 不新增 package、dependency、migration、连接、listener、timer、watcher、cache 或写 authority。SQLite 复用 MCP 的唯一 connection/operation queue/close fence；PostgreSQL 实现同一 port 供未来 Cluster 产品组合使用，但本 ADR 不建立 Cluster MCP。

Package 粒度裁决

公共 read contract 属于 Runtime Core 的现有 approved-action/ domain；双方言完整 Artifact 关联归各自 storage adapter； 单一 MCP 消费者的字段投影归现有 local-mcp-server/tool-projection/。因此只新增一个嵌套 projection 文件，没有新 workspace package。当前为 17 package/999 source、973 nested、26 root，无单源或 shallow package。

被否决方案

1. 只要求 approval.read：把索引观察权限隐式扩大为 Artifact 内容权限。
2. MCP 直接使用 Artifact repository：会把密文存储面和未来解密能力带入协议进程。
3. Client 提供 action reference/digest 或 artifact ID：暴露内部证据，并形成跨请求枚举面。
4. 把 preview 复制进 Approval 表：需要 migration、重复事实和双写一致性协议。
5. 为 detail/source/projection 新建 package：没有独立制品、依赖、authority 或版本生命周期收益。
6. 同时开放 approve/consume：缺少强人类 ceremony、事务 start barrier 与写恢复产品门。

验证

• Runtime Core 451/451、Local SQLite 208/208、Local MCP 38/38、PostgreSQL 290 pass/1 条件 skip。
• 真实 SQLite migration/row corruption、PostgreSQL 参数化关联、in-memory MCP admission 与真实 stdio/API Credential/Audit 均覆盖。
• package boundary、dependency 和 edge import 审计 compatible；MCP 对 Artifact subpath 的一次越权 import 被门禁发现并通过 document-only port 消除，而不是放宽规则。
• 十二档 artifact compatible。Standalone Application AI 为 6,261,021 bytes/637 files，余 30,435 bytes；Standalone MCP 为 9,857,149 bytes/947 files/203 modules，RSS 40,632,320 bytes。
• PostgreSQL 18.4 arm64 HA gates.passed=true，结束后 QingLong 临时 Docker 容器、卷、网络均为零。

后续约束

人工 approve/reject、consume/dispatch 和实际 Tool execution 必须分别定义强认证、职责分离、幂等命令、原子审计、start barrier 与响应丢失恢复协议。不得因为 preview 已可读就把任何写能力加入当前 MCP read authority。