先说几个核心判断：AIClaw 近期在 origin/master 分支上连续提交了三组相关更新，核心目标均指向一个全新执行层——Harness Runtime。这个设计的意图很明确：许多 Agent 系统往往将“模型声称执行完毕”视为任务完成的标志，但在实际执行过程中，工具调用证据、生成的文件产物、计划终态以及阻塞原因往往并未真正闭环。AIClaw 此次将“模型提议完成”与“执行层准入完成”进行了明确分离。
2026-07-02feat: add harness execution protocol2026-07-06refactor(agent): integrate harness runtime verifier2026-07-09feat(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 现在将校验拆分为四个阶段：
| Stage | 作用 |
|---|---|
pre_tool | 工具调用前，先检查策略是否允许执行 |
post_tool | 工具轮结束后，检查当前证据是否足够支撑后续流程 |
pre_final | 模型准备结束时，检查最终答复是否具备可交付性 |
pre_sa ve | 渲染完附件链接后，保存前再次确认交付内容没有遗漏 |
这种拆分比“最后统一判断一次”更加实用。因为不同问题出现在不同阶段：有些问题在工具尚未执行时就应该被拦截；有些工具执行后失败类型需要进入证据系统；有些最终答复看似完整，实则只是进度汇报；有些任务要求交付文件，但回答中缺乏可引用的文件标识。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.mdinternal/agent/harness.gointernal/agent/harness_verifier.gointernal/agent/finish_tool.gopkg/harness/contract.gopkg/harness/runtime.gopkg/harness/outcome.go
如果你也在从事 Agent 执行层的开发，这部分内容非常值得细读。它讨论的不是“如何编写更聪明的提示词”，而是“模型给出完成信号之后，系统凭什么相信它真的完成了”。
