AIClaw Harness运行时：Agent必须获得证据才能结束

先说几个核心判断：AIClaw 近期在 origin/master 分支上连续提交了三组相关更新，核心目标均指向一个全新执行层——Harness Runtime。这个设计的意图很明确：许多 Agent 系统往往将“模型声称执行完毕”视为任务完成的标志，但在实际执行过程中，工具调用证据、生成的文件产物、计划终态以及阻塞原因往往并未真正闭环。AIClaw 此次将“模型提议完成”与“执行层准入完成”进行了明确分离。

• 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

先说问题

常见的 Agent 失败模式其实非常相似：模型先制定计划，调用几个工具，输出一段看似总结的文字，但实际缺乏充分的证据支撑，或者承诺的文件没有交付，甚至只是在汇报“我接下来会继续处理”。如果执行层直接接受这类响应，执行记录看似成功，实则将未完成任务包装成了已完成状态。

Harness Runtime 正是为了解决这一痛点而设计。根据项目 README 的描述，它被定位为一个独立的执行层：首先根据任务构建 Contract，然后记录 Evidence，在工具调用前后以及最终答复前后执行 Validate，必要时通过 Correct 机制要求模型进行纠偏。

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

设计文档将整体流程抽象为四个阶段：Contract -> Evidence -> Validate -> Correct。映射到代码结构中，大致如下：

• TaskContract：根据用户目标、Agent 角色配置、工具数量、附件以及计划状态等信息，推导本次执行所需满足的具体要求。
• EvidenceLedger：记录执行过程中实际发生的真实事件与数据。
• Validator：在不同阶段判断当前状态是否满足继续执行的条件。
• CorrectionState：当校验失败时，生成结构化的纠偏提示，引导模型补充缺失内容。

这里最关键的一点是，AIClaw 不再仅仅依赖最终输出的文本，而是评估“这条回答背后是否有足够的执行证据支撑”。

Contract 到底约束什么

pkg/harness/contract.go 文件中现在会推导多个关键约束：是否要求计划、是否要求工具调用证据、是否要求最终答复、是否要求文件产物、输出模式是 text、file、mixed 还是 json，以及最多允许的纠偏次数。

以“修改代码并生成文件”的任务为例，Contract 自然倾向于要求：需要计划、需要工具执行证据、需要产物校验，最终不能仅仅给出“我已经处理好了”这样的模糊表述。这使得执行层拥有了明确的放行标准。

Evidence 记录的不只是工具成功

EvidenceLedger 现在采集的信息非常全面，不仅仅记录“调用过哪些工具”。它会记录：实际执行过的业务工具、每个工具轮的 ToolEvent、文件产物与附件信息、当前计划快照、校验事件与纠偏事件，还包括阻塞证据——例如权限不足、认证失败、策略拦截、资源不存在、限流、超时等。

这点非常重要，因为许多真实失败并非简单的“工具报错”，而是不同类型的 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 推导出本次任务需要计划，而当前会话又没有 active plan 时，Harness 可以直接引导出一个初始计划模板，大致包括：理解目标和依赖信息、执行必要工具并收集证据、校验证据和输出要求、汇总结果并交付最终答复。

这样做的好处是，Plan 仍然是运行时的状态变量，不会退化为聊天正文中的 TODO 文本；而 verifier 又能确保计划到达终态后，最终答复才被允许结束。

新增的 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 执行层的开发，这部分内容非常值得细读。它讨论的不是“如何编写更聪明的提示词”，而是“模型给出完成信号之后，系统凭什么相信它真的完成了”。