工具调用守卫 PHM-Audit/dsh-action-guard

@phm-audit/dsh-action-guard

一个确定性的执行前工具调用守卫插件，服务于 DeepSeek Harness（dsh），通过官方 monotonic guard seam（ctx.tools.guard）注册。

DeepSeek Harness 遵循「一切皆插件」架构。这个插件填上一个具体的槽位：基于规则、由操作者声明的守卫，判定可复现，决策有记录。

门禁测试产物：2009 帧确定性命令流（2000 条良性 + 7 条注入违规 + 确定性/账本/病态输入检查，无 RNG，无网络）——良性样本 0 误报，所有注入违规都被预期规则捕获，12/12 vitest 用例全绿（2026-10-13）。运行：bash run_demo.sh。

端到端冒烟：Cordis 封装层还额外对照 已发布的 npm 包 @deepseek-ai/dsh-system-prompt + @deepseek-ai/dsh-tools 0.0.1-rc.1 做了验证（2026-10-13）——按 cordis 方式加载（ctx.plugin、static inject 解析成功），注册了真实工具，并对非白名单工具发起真实 execute() 调用，经由实际流水线以预期的 R-unknown 理由拒绝（3/3 冒烟用例）。版本锁定冒烟：harness 仍在活跃开发中；请针对你部署的版本重新运行 npx vitest run tests/smoke.harness.spec.ts。

检查什么（全部由操作者声明，全部确定性）

- R-unknown —— 工具必须在声明的白名单内
- R-keys —— 每个工具的禁用参数键
- R-equals —— 每个工具的拒绝参数值
- R-bounds —— 每个工具的数值参数边界（含端点）
- Fail-closed —— 内部评估出错时以独特理由拒绝（坏掉的守卫绝不会悄悄变成漏洞）
- Decision ledger —— 每条判定都追加到本地 JSONL 账本，带 chain id（用于事故取证的相关性产物；基于 FNV 的 chain id，不构成防篡改保证）

方法源流 —— PHM

这个插件是 PHM 确定性验证方法论（门禁优先、证据优先）在 harness 上的原生表达，其母项目 agent-action-verifier 已在 AgentDojo 官方基准、真实 LLM 在环下验证（v2.2 重跑无 ASR/FP 事件，FP 修复周期 16 → 1 → 0 已公开，所有产物开放并带 SHA-256 链，第三方讨论串互动有记录）。

这条源流具体意味着什么，对比（拥挤的、155 个插件的）Security & Permissions 分类：

1. 官方第三方基准源流 —— 母方法在 AgentDojo 上测量，而非只在自建样本上（2026-10-13 对 10 个直接竞品仓库抽样验证：无一引用行业标准基准；最接近的 dsh-defend 用的是自建 105 样本红队集）。
2. 跨域部署记录 —— 同一套门禁标准（良性 FP=0 / 注入 FN=0 / 可重复的确定性 / 失败即关闭 / 审计账本）在机器人（Unitree 官方 URDF 门禁）、交通流（845k 帧 NGSIM）和 SDK 契约三条线上都跑过 —— 这是有实战记录的方法，不是一次性插件。
3. 开放、可重算的证据 —— 本 README 里的每条结论都有磁盘上的产物对应：tests/ 里的门禁计数、针对已发布 npm 版本跑的 tests/smoke.harness.spec.ts 冒烟测试、SHA-256SUMS 清单。

「赛道拥挤」这句是故意写的：这个插件的价值在证据链和标准接口示范，不在功能独特性。

渠道事实（来自 #9614 评审 —— 感谢 @argszero）

guard 接缝有四条性质，界定了本插件的账本和规则能声称什么。以下均已对照 master（d743267388）上的 packages/core/tools/src/index.ts 核实：

1. 账本是 guard 层的记录，不是完整决策记录。 只有 pre-execute waterfall 返回 allow（且用户没有拒绝 ask，且调用没有在上游被取消）时，guard 才会运行。其他层做出的拒绝永远不会进入 guard —— 完整的审计记录需要 tools/pre-execute + tools/post-execute 作为写入方。我们的 JSONL 账本描述的正是这一层，仅此而已。
2. R-unknown 是名称允许列表，不是工具允许列表。 execution.name 在不同作用域下可能解析到不同的已注册定义（作用域注册会遮蔽继承来的条目）。同名遮蔽的预设，对 guard 来说无法区分。
3. PTC 模式改变了流量形态。 模型直接调用原生工具名，会在策略流水线之前被上游拒绝（UNKNOWN_TOOL）；嵌套的子派发确实会到达 guard（继承 rootCallId）。因此策略必须覆盖子派发的参数形态，而允许列表只能看到实际到达的东西。
4. 结构化拒绝元数据是渠道强制的外部产物。 guard 只能返回字符串；流水线里的 denialInfo 来自 waterfall 的决策。单独的 JSONL 账本是渠道的要求，不是风格选择 —— 而且拒绝原因面向模型（工具结果是 Error: <reason>），所以原因要写短，并带上规则 id（action-guard: … (R-bounds)），方便和账本关联。

为什么选 guard 接缝（而不是 tools/pre-execute 监听器）： guard 是单调的 —— 其他层无法强制放行它已拒绝的调用；而 pre-execute 监听器待在一个它并不拥有的 waterfall 里，一个早早的 allow 就会终结它之后所有人的链条。确定性、同步、基于名称+参数的策略属于这里；面向操作者的 ask 属于 waterfall。
挂载点说明： 所有守卫都是单调拒绝，所以结果与顺序无关——但上报的原因是第一个被找到的（先全局，再按作用域链从最远开始）。如果你的策略能从两层拒绝同一次调用，就固定单一挂载点，让上报的规则 id 保持明确。

诚实的适用范围

诚实的适用范围

诚实的适用范围

- 策略由运维方声明——它不是通用的安全预言机，也不替代 harness 自带的权限／沙箱／审批层；它在守卫接缝处与这些层协同。
- 同源修复循环不是独立的稳定性试验。2009 帧这道门槛是机制演示，不是统计结论。
- 守卫核心是纯函数（src/guard-core.ts，零依赖）；Cordis 包装层（src/index.ts）从已发布的 @deepseek-ai/dsh-tools 包导入 ToolGuard，并按上文所述做了冒烟测试。早先有一个修订版导入了错误的内部专用包名；针对 npm 包的冒烟测试就是防这类错误的手段。
- 账本写入是尽力而为且受隔离的；它们影响不了判定路径。

插件形态（符合 harness 插件约定）

export const name = 'action-guard'
export const inject = ['tools']
export interface Config { policy: GuardPolicy; ledger?: { path: string } }
export default apply // registers one ToolGuard via ctx.tools.guard()

许可证

MIT。

PHM 证据链——聚合账本：phm-evidence-ledger（5,000,086,001 单位，四层，开放指标 + SHA-256 清单）· 方法父项目：agent-action-verifier（经 AgentDojo 验证）· PHM-Audit profile