AIClaw 的 Harness Runtime：Agent 不拿到证据不结束

这几天 AIClaw 在 origin/master 上连续落了三组相关提交：

• 2026-07-02 feat: add harness execution protocol
• 2026-07-06 refactor(agent): integrate harness runtime verifier
• 2026-07-09 feat(agent): align harness execution runtime

这组改动集中在一个新执行层上：Harness Runtime。

它解决的问题很直接：很多 Agent 系统会把“模型说自己做完了”当成完成信号，但真实执行里，工具证据、文件产物、计划终态、阻塞原因，往往都还没闭环。

AIClaw 这次把“模型提议完成”和“执行层放行完成”明确拆开了。

先说问题

常见的 Agent 失败模式其实很像：

1. 模型先给出计划。
2. 调了几个工具。
3. 输出一段看起来很像总结的话。
4. 但实际没有足够证据，或者承诺的文件没交付，甚至只是在汇报“我接下来继续做”。

如果运行时直接接受这类答复，执行记录表面上成功，实际却把未完成任务包装成了完成。

AIClaw 的 Harness Runtime，就是为了解决这个问题。

README 里现在把它描述成一个独立运行层：先根据任务构造 Contract，再记录 Evidence，在工具前后和最终答复前后做 Validate，必要时再用 Correct 机制要求模型纠偏。

核心设计：Contract -> Evidence -> Validate -> Correct

设计文档里把整体模型抽象成四段：

Contract -> Evidence -> Validate -> Correct

对应到代码里，大致是这样：

• TaskContract：根据用户目标、Agent profile、工具数量、附件、Plan State 等信息，推导这次执行到底要求什么。
• EvidenceLedger：记录执行过程中真正发生了什么。
• Validator：在不同阶段判断当前状态能不能继续。
• CorrectionState：如果校验失败，生成结构化纠偏提示，让模型继续补齐。

这里最关键的一点是，AIClaw 不再只看最终输出文本，而是看“这条回答背后有没有足够执行证据”。

Contract 到底约束什么

pkg/harness/contract.go 里现在会推导多个关键约束：

• 是否要求 Plan
• 是否要求 Tool Evidence
• 是否要求最终答复
• 是否要求文件产物
• 输出模式是 text、file、mixed 还是 json
• 最多允许几次纠偏

比如一个“修改代码并生成文件”的任务，Contract 会自然倾向于要求：

• 需要 Plan
• 需要工具执行证据
• 需要产物校验
• 最终不能只给一句“我已经处理好了”

这让执行层有了明确的放行标准。

Evidence 记录的不只是工具成功

EvidenceLedger 现在采集的信息很完整，不只是“调用过哪个工具”。

它会记录：

• 实际执行过的业务工具
• 每个工具轮的 ToolEvent
• 文件产物与附件信息
• 当前 Plan 快照
• 校验事件与纠偏事件
• 阻塞证据，例如权限不足、认证失败、策略拦截、资源不存在、限流、超时

这点很重要，因为很多真实失败并不是“工具报错”这么简单，而是不同类型的 blocker 需要不同的最终答复策略。

例如：

• 权限问题应该明确告诉用户缺什么权限
• 认证问题应该提示重新登录或补授权
• 资源不存在应该让用户确认名称或配置
• 可恢复的超时和限流，则可以先重试或解释外部服务状态

四个校验关口

AIClaw 现在把校验拆成四个阶段：

这种拆分比“最后统一判断一次”更实用。

因为不同问题出现的位置不同：

• 有些是工具还没跑就该拦住
• 有些是工具跑了但失败类型需要进入证据系统
• 有些是最终答复看起来完整，其实只是进度汇报
• 有些是任务要求交文件，但回答里没有真正可引用的文件标识

Harness Runtime 正是在这些位置上逐层收口。

它怎么识别“假完成”

这次实现里我觉得特别实用的一点，是 pkg/harness/outcome.go 对最终结果做了更细的分类：

• success
• blocked
• partial
• progress_only
• unknown

这意味着 AIClaw 不会再把“非空文本”直接当成完成。

如果模型输出的是：

• “我接下来继续生成”
• “请稍等，我正在处理”
• “下一步我会整理文件”

这类内容会更容易被视为 progress_only，在 pre_final 阶段被拦下来。

反过来，如果工具失败是因为权限或认证问题，Harness 也能要求最终答复显式解释阻塞原因，而不是给出一段模糊总结。

纠偏不是无限重试

校验失败后，AIClaw 不会立刻结束，也不会无上限地让模型重试。

internal/agent/harness_verifier.go 里把纠偏统一成了一个有预算的 nudge 机制。像这些情况都会消耗同一套纠偏预算：

• final gate 被拒绝
• tool round 证据不足
• 模型输出被截断
• 流式中断或空输出后的恢复提示

如果还有剩余次数，就追加 correction prompt，让模型补证据、补结果、补阻塞说明。

如果次数耗尽，系统就会明确失败收口，而不是把未完成结果包装成完成。

和 Runtime Plan State 的配合更完整了

这组改动不是孤立功能，它和 AIClaw 现有的 Runtime Plan State 是联动的。

当 Contract 推导出这次任务需要 Plan，而当前会话又没有 active plan 时，Harness 可以直接 bootstrap 一个初始计划模板，大致包括：

1. 理解目标和依赖信息
2. 执行必要工具并收集证据
3. 校验证据和输出要求
4. 汇总结果并交付最终答复

这样做的好处是，Plan 仍然是运行时状态的一部分，不会退回到聊天正文里的 TODO 文本；而 verifier 又能确保 plan 到达终态后，最终答复才允许结束。

新增的 finish 工具也很关键

2026-07-09 的对齐工作里，还新增了一个内置 finish 工具。

它的意义不是“让模型更容易结束”，而是让模型可以用结构化方式提交“这是最终答复”，然后再由 Harness 做一次 explicit final gate 校验。

也就是说：

• 模型可以声明“我准备结束了”
• 但真正决定能不能结束的，还是执行层

这个边界很清晰，也更方便在执行日志里排查问题。

对使用者有什么实际价值

这不是一个“让回答更像 AI” 的功能，恰恰相反，它是在压缩 Agent 幻觉式完成的空间。

对于真正做生产任务的系统，这类能力会直接影响可操作性：

• 更少“看起来完成，实际没完成”的结果
• 更清晰的 blocker 说明
• 更稳定的附件与文件交付校验
• 出问题时，execution log 里能看到明确的 harness 校验/纠偏轨迹

README 里现在把 AIClaw 定位成一个强调显式执行轨迹、可观察运行状态、少一点“隐形魔法”的自托管 Agent 平台。Harness Runtime 正是这个方向里非常核心的一步。

想继续看代码，可以从这些文件开始

• docs/design/agent-harness-runtime.md
• internal/agent/harness.go
• internal/agent/harness_verifier.go
• internal/agent/finish_tool.go
• pkg/harness/contract.go
• pkg/harness/runtime.go
• pkg/harness/outcome.go

如果你也在做 Agent 执行层，这部分很值得细看。它讨论的不是“提示词怎么写更聪明”，而是“模型给出完成信号之后，系统凭什么相信它真的完成了”。