前言¶
智能体 Harness（调度循环）在处理工具调用、状态管理和错误恢复时，容易出现导致循环失效的故障模式。传统的审计方式依赖人工阅读代码，效率低下且容易遗漏；而依赖大模型进行自动审计则可能产生“幻觉”，即给出没有代码依据的结论。
dsh-harness-audit 旨在解决这两个问题。这是一个由 Leeaoyin 维护的工作流类 DSH 插件，它通过机器强制执行的证据验证，对 Harness 进行自动化审计。它拒绝任何无法在代码中找到证据的发现，并生成基于代码而非模型生成的摘要报告。
核心能力¶
插件包含以下核心功能：
- 十五项检查机制：覆盖智能体循环的各个关键环节，每个检查对应一个特定的故障模式。
- 机器强制证据验证：所有发现必须能被代码中的具体行、文本或路径证明，否则将被拒绝。
- 自包含安装：安装插件即完成所有判断标准的安装，无需额外配置。
- 代码驱动摘要：报告的最终总结由代码编写，不依赖大模型生成，确保客观性。
- 后台作业执行：审计命令立即返回，作为后台任务运行，不阻塞会话。
- 报告与指标：在
outputDir（默认.harness-audit/）生成 Markdown 和 JSON 报告，并提供子代理质量监控的“拒绝率”指标。
检查清单¶
插件包含 15 项检查，分为五个组别。其中 p1 代表 7 个关键检查（标记为 ★）。以下是各检查的具体内容：
| 组别 | 检查代码 | 检查内容 |
|---|---|---|
| State stays self-consistent | C1 | 工具调用配对完整性：确保所有执行结束方式（错误、超时、取消）都有记录，且并行批次中的失败不会丢弃其他结果。 |
| C2 | 历史追加：确保消息添加后不可编辑。 | |
| C3 | 崩溃与检查点语义：检查多部分写入间进程死亡时的状态可见性与可检测性。 | |
| Untrusted input is treated as untrusted | C4 | 模型输出解析：处理畸形参数、截断流或重复调用 ID，而非信任它们。 |
| C5 | 路径与沙盒边界：解析并检查模型提供的路径是否在工作区根目录内。 | |
| C6 | 密钥与环境：检查模型生成命令继承的环境变量中是否包含密钥。 | |
| Failure is a first-class outcome | C7 | 错误分类与重试性：确保失败携带明确的错误代码分类（可重试/不可重试/致命）。 |
| C8 | 部分成功：检查独立结果是否合并为一个单一状态，导致隐藏或丢弃成功。 | |
| C9 | 幂等性与副作用安全：检查重试包装器内的写入、命令或出站消息是否会被重复执行。 | |
| Boundaries can be closed | C10 | 取消传播：检查取消信号是否真正到达出站请求和子进程。 |
| C11 | 超时分层：检查工具调用层与底层资源的超时大小关系。 | |
| C12 | 循环与预算限制：检查轮次、工具调用、时钟时间、Token 和委托深度的硬性上限。 | |
| Finite resources are accounted for | C13 | 上下文管理与截断边界：检查上下文是否随会话增长而管理，以及截断是否破坏调用/结果对。 |
| C14 | 提示前缀确定性：检查运行间系统提示、工具定义、历史消息的字节一致性。 | |
| The run is observable | C15 | 追踪完整性与重放：检查运行是否留下足够的事件记录以重建过程。 |
执行流程¶
一次审计运行包含三个阶段：
- Recon（侦察）：一个子代理定位关键地标（如 Agent 循环、请求组装、工具执行），并通过
report_landmark报告。 - Fan-out（分发）：为每个检查启动一个一次性子代理，每个子代理仅接收与其相关的地标和特定的检查标准。如果缺少必要地标，该检查不会被分发。
- Summary（汇总）：由纯代码生成最终报告。模型不参与撰写摘要，而是通过代码将“疑似”标记转化为“确认”或移除无证据的声明。
使用方法¶
插件提供命令行接口，支持指定检查维度或运行全部检查。
基本命令¶
/harness-audit # 询问需要审计哪些维度，显示纯语言菜单
/harness-audit C1 # 审计单个维度
/harness-audit C1,C9 # 审计多个维度
/harness-audit p1 # 运行 7 个关键检查（★ 标记的项）
/harness-audit all # 运行全部 15 项检查
报告与后台作业¶
命令执行后会立即返回，审计作为后台任务运行。完成后 Agent 会被唤醒并汇报。
查看后台作业输出：
job_output <id>
报告文件默认保存在 .harness-audit/ 目录下，按时间和维度命名：
report-2026-08-17_095736-C1.md
report-2026-08-17_095736-C1.json
证据验证与指标¶
插件内置严格的证据验证机制，确保审计结论的可信度。report_finding 拒绝以下情况的发现：
1. 检查不属于本次运行。
2. 路径不是第一方代码（如 .venv, site-packages）。
3. 文件不在工作区内。
4. 引用的行不存在。
5. 引用的文本不在引用行附近 ±3 行内。
6. “疑似”结论缺少“确认提示”。
拒绝率是核心指标。如果拒绝率过高，意味着子代理在捏造 claims，需要调整提示。拒绝无法解析的输入也是插件的设计原则，避免静默的错误处理。
注意事项¶
- 安装方式：已核实事实中未提供明确的安装命令。插件作为 DSH 插件管理，请参考官方目录或仓库获取安装指引。
- 权限与范围：插件以当前 DSH 进程权限运行。作用域强制机制防止插件审计第三方库（如 vendored 代码），确保审计对象是项目自身代码。
- 误报控制：在未找到目标地标时运行检查是产生误报的主要原因。插件会自动跳过未找到地标的检查。
生态背景¶
DeepSeek Harness (DSH) 采用“一切皆插件”的理念。dsh-harness-audit 是社区贡献的一个工作流插件，旨在帮助开发者构建更健壮的智能体系统。如需了解更多或获取最新版本，请访问：
* 插件目录
* GitHub 仓库
