qinglong/docs/adr/ADR-0403-bounded-redacted-run-log-tail-tool.md

ADR-0403：有界、脱敏且不授予行动权的 Run 日志尾部 Tool

• 状态：Accepted
• 日期：2026-08-14
• 关联 RFC：QL-RFC-0001 D-311、Phase 2
• 关联 ADR：ADR-0347、ADR-0377、ADR-0400、ADR-0401、ADR-0402

问题

失败日志解释需要向模型提供足够的执行上下文，但 Run 日志同时具备四类风险：体积可能无界， 可能包含 credential 或任意业务敏感数据，内容本身可能携带 Prompt 注入指令，而且日志在读取 过程中仍可能增长。把文件路径、Artifact ID、任意 offset/length 或 cursor 交给模型，会使读取 成本和泄露面不可证明；把整份日志读入内存再截断，也不适合只有很少内存与闪存的路由设备。

ADR-0377 已提供 profile-aware、Project-scoped 的 Run Attempt 日志 range reader：Local 使用私有 Artifact 文件，Cluster 使用 S3 兼容对象存储。为 AI 再建设一套 SQLite/PostgreSQL/对象存储 reader 会形成双重真源、额外连接与 package 碎片；直接把原始 range reader 暴露给模型则绕过了 脱敏和不可信内容边界。

决策

1. 增加 qinglong.run.log.excerpt@1.0.0。输入精确为 runId、attemptId，Project 只来自 受信 execution context；不接受 Artifact ID、路径、URI、bucket/key、offset、length、limit、 cursor 或查询表达式。Definition 固定为 read/medium、artifact.read、5 秒 deadline。
2. Tool 只选择日志尾部。第一次以 Number.MAX_SAFE_INTEGER 和 1 byte 对既有 range reader 做 总长度探测，第二次从 max(0, probedTotalBytes - profileWindow) 读取固定窗口；单次调用最多 两次读取，不循环、不分页，输出也不提供 nextOffset。窗口固定为 Edge 4 KiB、Standalone 8 KiB、Cluster Control 16 KiB；Worker profile 拒绝装配。
3. 输出以 consistency=bounded_tail_probe_then_range_read 明确表达两次独立读取，不声称事务 快照。若第二次读取时日志增长或长度发生变化，selection.tailComplete=false；调用方不得把 该片段解释为当时完整尾部。
4. 原始 bytes 先以非致命 UTF-8 解码，并显式报告 invalid UTF-8；CRLF/CR 归一为 LF，终端 C0、 DEL、零宽字符和双向文本控制符替换为 U+FFFD，避免终端控制与视觉重排。最坏情况下每个 source byte 可扩张为三字节 U+FFFD，因此模型文本硬上限分别为 12/24/48 KiB。
5. recognized_credentials_v1 以确定性、保持或缩短字符数的掩码处理 Authorization、常见 credential assignment、PEM private key、URL userinfo、JWT、云访问密钥和常见 opaque token。 输出必须携带命中的类别与次数，同时永久标记 residualSensitivity=potentially_sensitive：该规则只能识别约定格式，不能宣称任意业务秘密 已被证明移除。
6. 所有日志内容无条件标记为 untrusted_execution_output、 data_only_never_execute、actionAuthority=none。启发式检测 instruction override、role impersonation、secret exfiltration 与 tool coercion 只用于提示与审计；真正安全边界是日志 永远只作数据、Tool Policy/Approval 独立裁决，不能让日志文字授予任何 Tool 或命令权限。
7. Trusted adapter 必须同时绑定 reviewed Definition、显式 profile、artifact.read 与 database.read authorities、redaction/audit contract，恢复模式为 retry-safe read。任何 binding 漂移、跨 Project/Run/Attempt 返回、畸形 range、超预算内容或底层错误均失败关闭。
8. 复用 Runtime Core 的 RunAttemptLogReadService、Local 的 LocalRunAttemptLogRangeReader 与 Cluster 的 S3ClusterRemoteWorkerArtifactStore；本阶段 只交付共享 Trusted Tool kernel，不提前开放 MCP、HTTP 或 Cluster Copilot 产品入口。后续 composition 必须重新经过认证、Policy、durable audit、credential fence 与完整 Trusted Tool completion 门禁。

低配、集群与 package 布局

• 默认 Edge/Standalone 不新增 daemon、listener、timer、watcher、cache、连接、migration、表或 索引；未装配 AI/MCP 时显式 subpath 应从发布制品中裁掉。单次调用只保留一个 4/8 KiB source window 和至多三倍的规范化文本。
• Cluster Control 使用调用方已有对象存储 client 和元数据查询链，不新建 PostgreSQL pool 或 S3 client；16 KiB 窗口仍保持固定两次对象读取。Worker 不具备模型上下文投影能力。
• workspace package 保持 18 个。新能力放入 Runtime Core 既有 run/log-projection/ 与 tool-execution/builtin-run-log-excerpt/；Local/Cluster 只增加对既有 adapter 的集成证明，不创建单文件微型 package，也不回到 src 根目录平铺。
• Runtime Core 只提供三个精确 subpath，package root 不导出日志 Tool，避免无意扩大默认入口。

被否决方案

1. 返回整份日志后在 Prompt 层截断：存储、内存、网络和模型输入均可能无界。
2. 让模型传 offset/length 或 cursor：模型可以循环扩大读取范围，低配成本与泄露面不可证明。
3. 只读固定头部：失败原因通常出现在尾部；头部还更容易包含启动环境和 credential。
4. 只依赖正则并标记“已安全”：任意业务秘密不可穷举，因此必须保留 residual sensitivity。
5. 把 Prompt 注入检测当授权边界：启发式存在漏报；内容无行动权和独立 Policy 才是边界。
6. 返回原始内容哈希：对低熵日志可形成额外指纹，不是解释失败所需字段。
7. 新建 AI Artifact reader/package：会重复 ADR-0377 真源并加剧 package 碎片。

当前验证

1. Runtime Core 定向测试覆盖七类 credential、Prompt 注入 taint、invalid UTF-8、控制与 bidi 字符、最坏三倍扩张、三档预算、Worker 拒绝、固定两次尾读、增长竞态、无 cursor、非内容 状态、畸形存储、严格输入与 Definition/binding 漂移。
2. Local 集成以真实私有 Artifact 文件经 LocalRunAttemptLogRangeReader → RunAttemptLogReadService → Tool 验证只读取尾部并脱敏；Cluster 集成以真实 S3 adapter 请求 链验证相同共享投影，不引入第二实现。
3. 最终 18-package clean build/test 退出 0；backend 1,208 项为 1,206 pass、2 条平台条件 skip、0 fail。package/dependency/Edge import/Cluster deployment 审计零 finding；package 保持 18 个，singleSourcePackages=[]、shallowSourcePackages=[]，Runtime Core 为 168/167 nested。
4. 14 个 Local Profile 制品门全部通过。默认 Edge 为 2,589,812 bytes/315 files/56 modules， 证明未装配的新精确 subpath 被完全裁掉；Edge AI 为 3,121,108 bytes/368 files/61 modules， Edge MCP 为 7,237,187 bytes/795 files/220 modules。对应 RSS 增量分别为 10,977,280、 11,108,352、38,010,880 bytes，均在各自 16/16/48 MiB 门内。
5. PostgreSQL 18.4 arm64 HA 125/125 Gate 通过，timeline 1→2，报告 SHA-256 为 1a0df2518d39db22ecf4bbaf2e06c9e6893e1bbf507b4026b2e0ef055eb2fd90；容器、网络与卷零残留。

后续门禁

1. 可选 Local MCP 与 Cluster Copilot composition 接入，分别证明认证、Policy、durable audit、 credential fence 和 Trusted Tool encrypted completion；
2. 在最终 Prompt builder 中以结构化 delimiter 固定日志为 untrusted data，并把 residual sensitivity 纳入模型 egress policy；
3. 增加 SecretRef-aware 的精确脱敏与固定物理 Edge 单次读取延迟/RSS 证据，但不得因此把 v1 的 residual sensitivity 改成“安全”。