如果自行构建 Harness，需要完成哪些工作？

自行构建 Harness，需要把模型输出接成可执行、可观察、可恢复的任务系统。最小闭环包括模型适配、上下文组装、工具执行、运行循环和任务状态；可用于真实任务时，还要补权限与隔离、超时和取消、持久化恢复、运行预算以及独立验收。

例如修复一个登录缺陷：模型决定读哪些代码、怎样修改；Harness 负责在允许范围内读写文件、启动检查，收集真实结果并交回模型。模型提出完成时，系统检查修改是否满足需求、相关验证是否完成，再结束任务。

实现可以先放在一个进程里，把接口和状态分清楚，不需要一开始就拆成多服务或多 Agent。

模型适配层处理输入消息、结构化调用、流式事件和接口异常。上下文层为每轮准备目标、约束、当前进度、必要历史与工具说明；长日志放外部，返回关键摘要和可继续读取的位置。

循环至少区分四个分支：提出工具调用、需要用户补充、提出完成、运行失败。工具执行器检查参数和权限，再调用处理器，返回成功、失败或未知状态。动作结果要与调用标识关联并更新任务状态，不能把“准备执行”写成“执行成功”。

工具可以从读文件、应用补丁和运行检查开始；后续再按需求接 MCP 等外部能力。增加工具前先确定它的输入、结果、错误和副作用，避免只堆能力名称。

任务状态需要保存目标、约束、当前阶段、产物、已经完成的动作和未决操作。聊天历史可以作为上下文材料，但不能代替业务状态。

假设补丁已经写入文件，服务在记录成功前崩溃。恢复时应先查看文件和操作记录，确认补丁是否生效，再决定继续验证或重新执行。直接从旧快照重复所有动作，可能造成重复修改或重复业务请求。

检查点也不等于自动回滚。以 LangGraph 为例，恢复中断时节点会从开头重新执行，暂停前的副作用可能重复发生；要拆分准备、等待和执行，或使用业务幂等机制。内存检查点只适合单进程演示，跨重启恢复需要持久存储。

可以用一个带故障的任务验证整套运行层：工具超时、执行后断连、重启恢复、用户中途取消、模型提前声称完成，分别检查状态是否正确、操作是否重复和剩余工作能否解释。

必须有 Todo、长期记忆和多 Agent 吗？

不必须。待办清单能帮助长任务，长期记忆解决跨任务经验，多 Agent 解决分工；它们都不是最小执行闭环的必选项。

有 checkpoint 就能保证只执行一次吗？

不能。保存状态与外部动作通常不是同一个事务。需要动作标识、结果查询、幂等或业务补偿，才能处理两者之间的失败窗口。

回放是否需要重新执行所有工具？

调试回放可以读取历史结果来分析决策；重新执行可能改变环境，应与只读回放分开，并标明使用历史结果还是现场结果。

国内：JavaGuide：Harness Engineering 详解：采用模型之外的执行环境、上下文和验证分工，组织最小闭环与后续模块。
国内：Datawhale：构建你的智能体框架：借鉴模块分层和轻量起步的设计，说明为何先明确模型、消息与工具接口。
国内：小林：如何设计一个完整的 Agent Harness？：采用工具执行、未决操作核对和独立验收的过程，展开补丁落盘后崩溃的恢复问题。
国内：AgentScope：State/Session Management：参考运行状态与会话状态的保存加载机制，说明聊天文本不等于完整运行状态。
国外：Anthropic：Effective harnesses for long-running agents：采用长任务需要可交接进度与明确完成条件的经验，说明压缩聊天本身不足以保证任务持续推进。
国外：LangGraph：Interrupts：核对中断恢复需要检查点和同一任务标识、节点会重执行，说明检查点不提供外部动作只执行一次保证。