qinglong/docs/adr/ADR-0348-bounded-local-mcp-run-event-list.md

# ADR-0348：有界、低敏的本机 MCP Run 事件诊断

- 状态：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-260、D-261
- 关联 ADR：ADR-0028、ADR-0049、ADR-0052、ADR-0087、ADR-0155、ADR-0195、ADR-0276、ADR-0345、ADR-0346、ADR-0347

## 背景

ADR-0347 建立的 `qinglong.run.get` 能回答 Run 的当前低敏快照，但不能解释状态如何演进。桌面 Agent 和本机 AI Client 在诊断排队、重试、取消与终态收敛时需要有序事件元数据；RunEvent payload、Actor identity、Artifact/Log reference 等字段可能包含命令、错误或租户信息，不能因为增加诊断能力而进入 MCP 公共输出。

新增能力也不能让可选 MCP sidecar 获得写、调度、迁移或管理 authority，不能增加 SQLite connection、后台任务或默认 Edge/Standalone 闭包。一个新的只读 projection 没有独立部署、生命周期或消费者边界，因此不构成新增 workspace package 的理由。

## 决策

在既有 `@qinglong/local-mcp-server` 中增加第二个只读 Tool：`qinglong.run.events.list@1.0.0`。当前本机 MCP 只发布 `qinglong.run.get` 与 `qinglong.run.events.list` 两个 Tool，不开放动态注册。

输入固定为 `{runId, afterSequence?, limit?}`：`limit` 默认 32、最大 64，repository 最多读取 `limit+1` 条以计算下一页；输出固定为 `{found, events, hasMore, nextAfterSequence}`，其中每个 event 只含 `sequence`、`type`、`actorType` 与 `createdAtMs`。事件必须严格按 sequence 递增，分页游标只来自已返回的最后一条事件。

输出不得包含 RunEvent payload、event ID、dedupeKey、actorId、attemptId、stepRunId、Artifact/Log reference、命令、错误详情或数据库 row。Run 不存在与跨 Project 必须同样返回 `found=false`、空 events，且不得继续查询事件。存储故障或损坏顺序统一映射为低敏 unavailable error。

每次调用继续执行 ADR-0347 的逐调用 admission：

1. API Credential authentication；
2. Tool Registry 解析 exact Definition，并依次检查 `tool.call:qinglong.run.events.list` 与 `run.read`；
3. durable Security Audit 记录 `operationId=mcp.tool.call` 以及精确 Tool reason；
4. credential `confirm()` 关闭撤权窗口；
5. Project-scoped Run point read 确认所有权，再执行有界事件读取。

两个 Tool 通过 package-private descriptor registry 复用同一 admission 编排，避免各自复制认证、Policy、Audit 与 fence。`@qinglong/local-sqlite/mcp-read-database` 在同一 SQLite connection、operation authority、queue 与 close fence 上增加窄 `listEvents` reader；不取得 migration、management、repair、Run mutation、Shell、Secret、listener、timer、watcher 或 scheduler authority，也不增加 connection、cache、service、package 或第三方依赖。

Runtime Core 在既有 `tool-execution/` owning domain 增加 `builtin-run-event-list-projection` 公共子路径。它只承载稳定 Definition、严格输入验证、低敏投影和有界分页，不复用 Trusted Tool 的 executable authority，也不为单个 Tool 新拆 package。

## Package 与资源边界

本增量没有新增 workspace package 或 production dependency。MCP source import gate 只增加精确 runtime-core projection subpath；默认十档 Profile 仍不加载 MCP SDK。

当前 Edge/Standalone MCP 制品分别为 9,785,975/9,786,083 bytes、939 files、185 loaded modules，完整 import RSS 增量为 43,008,000/42,565,632 bytes，继续低于独立 16 MiB/1,536 files/48 MiB 门。最紧默认 Standalone Application AI 制品为 6,248,558 bytes，距离 6 MiB 门仅余 42,898 bytes；因此后续不得把 MCP SDK、事件 repository 或诊断缓存引入默认 application。

## 被否决方案

1. 返回完整 RunEvent payload：会把未来新增字段自动变成公共泄露面，也无法为 Secret、命令和错误内容提供稳定低敏保证。
2. 一次返回完整历史或提供无限 limit：设备成本随历史增长，恶意 Client 可放大 SQLite 延迟和内存。
3. 直接按 runId 查询事件：会泄露跨 Project Run 的存在性，并绕过当前 Policy 对象范围。
4. 复用 Workflow/Owner 管理 repository：会让 stdio session 持有无关 mutation、migration 或 destructive authority。
5. 同批开放 start、cancel、Shell 或事件写入：副作用 Tool 需要独立批准、幂等、限流和未知结果恢复设计。
6. 为 event projection、reader 或 registry 新增 package/service：没有独立部署或资源边界，只会增加 importer、SBOM 和低配设备成本。

## 验收证据

- Runtime Core 450/450：Definition、输入上限、严格有序分页、payload-free projection、跨 Project 屏蔽和故障关闭。
- Local SQLite 203/203：事件读取复用同一 operation authority、queue、connection 与 close fence。
- Local MCP 7/7：双 Tool 列表、逐调用 permission/admission 顺序、精确 durable audit reason 与真实 stdio JSON-RPC/SQLite 分页 E2E。
- package-boundary/dependency 定向 59/59；17-package ledger compatible，970 个 QL3 source 中 944 个 nested、26 个 root，未新增浅包。
- 默认十档与两个 MCP artifact 共十二档 compatible；默认 Profile loaded-module 数不变，MCP 制品只增加约 10 KiB 与 1 file。
- 本批未修改 SQL、migration、PostgreSQL 或 Cluster runtime，因此 PostgreSQL HA 不属于该变更的相关门，不能宣称由本批重新验证。

## 后续约束

事件 payload、Artifact/Log content、subscription/streaming、远程 transport 以及任何写 Tool 都必须另立 ADR，并证明字段级脱敏、租户隔离、限流、取消/幂等、durable audit 与资源预算。新增只读 Tool 也必须进入同一静态 descriptor registry，并逐调用经过认证、exact Tool permission、业务 permission、durable audit 与 credential fence；不得用 wrapper 绕过 admission。