核验范围：harness 不是标准化产品名，不同框架对它的边界划分不同。本文讨论的是通用运行机制，不据此断言某个闭源产品的内部实现。文中的 LangGraph、OpenAI Agents SDK 和 Anthropic 文档只用来核对公开概念；代码是教学用伪代码，不是可直接部署的安全实现。

你让一个 Agent “把 inbox/ 里的 Markdown 按主题整理到 notes/，重复文件先报告，不要删除”。它读了几个文件，建了两个目录，接着某个文件名里带了空格，命令失败。它第二轮又执行了一次同样的命令，最后回复你：”已整理完成。”

模型未必不知道什么叫文件夹，问题出在模型以外。谁把文件列表交给它？谁真的执行命令？命令失败后，谁把错误原样带回去？已经建好的目录要不要记住？最后谁检查 notes/ 里是否真的有预期文件、inbox/ 是否没有被误删？围绕这些问题的一层运行程序，通常就叫 Agent Harness。

很多文章把 harness 说成 “模型外的一切”。这句话不算错，但对初学者没有操作价值。读完本文，你不需要背下一个新名词；你应该能回答下面这些实际问题：

• 模型每一轮究竟看到了什么，为什么它会重复调用工具？
• 一个工具调用从模型输出到真正执行，中间需要过哪些关？
• 任务被取消或进程崩溃后，怎样继续而不重复产生副作用？
• “模型说完成” 和 “任务真的完成” 差在哪里？
• 一个小项目何时只需循环，何时才需要检查点、人工确认和子 Agent？

本文一直沿用上面的文件整理任务。这个例子故意很小，因为它同时有读取、写入、重复检测、失败恢复和验收，足以把 Harness 的骨架讲清楚。换成代码修复、网页操作或客服工单，骨架仍然是同一套。

先建立阅读地图

先记住最短的一条链：任务 → 组装上下文 → 模型决定下一步 → 执行工具 → 观察结果 → 下一轮或结束。

模型负责根据当前信息提出下一步。Harness 负责保存事实、执行受控动作、决定是否还能继续，并给最后的结果找证据。ReAct 论文把 “推理” 与 “行动” 交替放在同一个过程里，这是理解这条链的一个早期参考。ReAct

后文会把这些层拆开，但不要把它们当成十二个必须采购的模块。一个本地脚本一开始只要循环、两个只读工具和明确的停止条件。任务变长、涉及写入或要交给别人使用时，再往上加。

一、Harness 到底是什么，它又不是什么

可以把 LLM 看成一个依据当前上下文生成下一段输出的组件。它没有磁盘权限，也不会真的发 HTTP 请求。即使模型输出了一个长得很像 read_file({"path":"inbox/a.md"}) 的结构，这仍然只是一段文本或结构化数据。Harness 接住这份请求，检查它是否合规，调用真实函数，把函数返回值变成一条工具结果消息，再交给下一轮模型。

因此，Harness 不是某一个类，也不等于提示词、工作流框架或多 Agent 系统。它是一组运行责任：

  flowchart LR
  U["用户任务"] --> H["Harness：组装上下文、调度、限制动作"]
  H --> M["LLM：提出下一步"]
  M --> H
  H --> T["工具与外部系统"]
  T --> H
  H --> R["结果与证据"]
  

“模型是 CPU，Harness 是操作系统” 是个能帮助理解的比喻，但别把它当成严格映射。Beren Millidge 提出的 scaffolded LLM 视角更接近重点：上下文、外部存储和工具共同扩展了模型一次生成所能完成的事。Scaffolded LLMs as natural language computers

这个区分很有用。比如 Agent 把 inbox/todo.md 移错了位置：

• 如果模型从没见到 “不要移动重复文件” 这条约束，是上下文装配问题。
• 如果模型传了 {path: "../../secrets"}，执行器仍放行，是权限问题。
• 如果移动成功后进程挂掉，重启又移动一次，是状态与幂等问题。
• 如果文件其实没移动成功，系统却回复完成，是验证问题。

把失败归到可检查的层，才有办法修。把它统称为 “模型幻觉”，通常只会让你继续加一段更长的 prompt。

二、先把五个最容易混淆的词分开

这些词经常在同一段介绍里出现，却指向不同东西。

最常见的坑是把所有东西都塞进聊天历史。这样做一开始很省事，长任务就会出现三种后果：成本升高，重要信息被长输出淹没，恢复时模型只得到一段散文而不是可执行状态。长上下文也不是自动可靠。研究发现，当关键信息落在长序列中间时，模型可能利用得更差。Lost in the Middle

另一个坑是把 “状态” 当成一个抽象的大字。为了能恢复，你要先写清楚恢复时究竟需要哪些字段。例如：

1
2
3
4
5
6
7
8
9
10
11

{
  "run_id": "run_20260719_001",
  "goal": "整理 inbox 下的 Markdown，重复文件只报告",
  "phase": "executing",
  "scanned": ["inbox/a.md", "inbox/b.md"],
  "moved": [{"from": "inbox/a.md", "to": "notes/ai/a.md"}],
  "duplicates": ["inbox/b.md"],
  "pending_action": null,
  "max_turns": 12,
  "turn": 4
}

这份状态不是给模型写作文用的。它是运行程序恢复时的事实来源。模型可以读它的摘要来继续推理，但不要让模型自由改写它。

三、最小可运行 Harness：一段循环到底在做什么

一个最小 Agent 并不神秘。下面的伪代码省略了 SDK 细节，保留了真正需要做决定的地方：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

state = new_run(user_task)

while state.turn < state.max_turns:
    messages = build_context(state)
    response = model.generate(messages, tools=available_tools(state))

    if response.has_final_answer and not response.tool_calls:
        return finish_after_verification(state, response.text)

    if not response.tool_calls:
        return stop(state, "模型未调用工具，也没有给出可交付结果")

    for call in response.tool_calls:
        decision = authorize_and_validate(call, state)
        if decision.needs_human:
            save_checkpoint(state, waiting_for_approval(call))
            return pause(state)

        result = execute_with_timeout(decision)
        append_tool_observation(state, call, result)
        save_checkpoint(state)

    state.turn += 1

return stop(state, "达到最大轮次，已保留现场供继续处理")

真正的循环还要处理流式输出、并发调用、模型调用失败、用户取消和 token 预算，但这些复杂性都围绕相同的六步。重要的是不要把它写成一团。每一步都有清楚的输入、输出和责任。

  flowchart TD
  A["从状态组装本轮上下文"] --> B["请求模型"]
  B --> C{"模型请求工具？"}
  C -->|"否，给出答案"| D["执行最终验证"]
  D --> E{"证据足够？"}
  E -->|"是"| F["交付结果"]
  E -->|"否"| G["把失败证据写回状态"]
  C -->|"是"| H["schema、权限、预算检查"]
  H --> I{"需要人工确认？"}
  I -->|"是"| J["保存检查点并暂停"]
  I -->|"否"| K["执行工具并设超时"]
  K --> L["记录观察结果，写检查点"]
  L --> A
  G --> A
  

3.1 不要把 “模型输出” 和 “工具执行” 混在一起

早期 Demo 常让模型输出一段命令，然后从文本里用正则提取 bash(...)。这能演示思路，却很脆弱：参数里的引号、多个调用、模型解释文字和注入内容都会让解析变复杂。现代 API 的工具调用会把工具名与 JSON 参数分开返回，减少这一层文本解析工作。Anthropic 的工具调用文档和 OpenAI 的函数调用文档都把工具定义、模型请求、应用执行、工具结果回传作为基本流程。Anthropic tool use OpenAI function calling

但结构化不等于安全。下面这个请求即使能通过 JSON 解析，也不该直接执行：

1

{"name":"move_file","arguments":{"from":"inbox/a.md","to":"../../Documents/a.md"}}

schema 只能证明字段名和类型大致正确。路径是否仍在允许根目录内、目标是否会覆盖现有文件、用户是否授权移动，这些必须由 Harness 自己判断。

3.2 工具定义本身就是给模型看的接口

工具太宽泛时，模型会把很多意图塞进一个接口；工具太碎时，它会在相近选择里摇摆。文件整理的起步工具可以只有这四个：

把写操作拆成 plan 和 apply，不是所有项目都必需。它很适合有后果的动作，因为 Harness 可以在计划阶段显示差异、做审批或一次性验证。对于只读检索，额外一层反而会拖慢。

工具描述也要说清失败形态。不要只写 “移动文件”，而要让模型知道：目标已存在时返回 CONFLICT，源哈希变化时返回 STALE_PLAN，不会自动覆盖。模型拿到可区分的错误，才有可能采取不同补救动作。

3.3 终止条件不是 while True

模型不再调用工具，不代表任务完成。它可能只是没想到下一步，也可能在同一个失败命令上打转。因此停止要由 Harness 决定，至少包含：

• 任务完成且验收通过。
• 用户取消，保存足够的进度和未完成项。
• 达到最大轮次、时间或费用预算。
• 连续相同工具调用或相同错误超过阈值。
• 等待人工确认，主动暂停。
• 遇到不可恢复的权限或前置条件错误。

停止时不要伪装成成功。好的终止结果应该写出：做成了什么、没有做什么、停在何处、怎样恢复。对文件整理任务而言，”移动了 18 个文件，发现 2 个重复项未移动，第 19 个文件因目标冲突暂停” 比 “任务完成” 有用得多。

四、让模型看见该看见的东西：上下文工程的实际做法

上下文不是一块越大越好的内存。它更像本轮决策的工作台。build_context(state) 至少要区分以下内容：

1
2
3
4
5
6

系统规则：允许目录、禁止动作、审批规则、最终输出格式
任务目标：用户这次真正要完成的事和不能违反的限制
稳定状态摘要：已完成、待处理、已知冲突、下一步
近期消息：尚未被摘要的用户要求与工具结果
可用工具：名称、用途、参数 schema、限制
当前观察：本轮最相关的文件内容或错误

这个顺序不是唯一答案，却能避免一个常见错误：把几十 KB 的命令输出和最重要的安全限制平铺在一起。你希望模型在需要决定时先看见约束、当前目标和下一步可用的事实。

4.1 工具输出应该是观察，不是聊天记录

假设 read_file 读出一本电子书的全文。把全文原样塞回每一轮，模型既浪费窗口，也更难发现真正的笔记标题。Harness 可以让工具返回更合适的观察：

1
2
3
4
5
6
7
8

{
  "path": "inbox/llm-notes.md",
  "sha256": "…",
  "bytes": 184233,
  "excerpt": "# LLM 记忆\n…",
  "truncated": true,
  "next": "可用 search_in_file(path, query) 获取指定片段"
}

这里的截断不是偷偷丢数据。结果明确标记了 truncated，并告诉模型怎样取回细节。对于日志、网页和数据库查询，也应采用类似策略：默认返回摘要、关键行和分页游标，需要时再钻取。否则一个很长的 stderr 就可能挤掉整条用户约束。

4.2 摘要必须能回到证据

长任务总会压缩历史。可恢复的摘要至少应包含目标、约束、已经产生的副作用、未解决错误、下一步和引用 ID。下面这种摘要看起来顺，却无法恢复：

已经完成大部分整理，遇到了一些问题，接下来继续处理即可。

更有用的版本是：

目标：按主题整理 inbox/，重复文件不移动。已移动：a.md → notes/ai/a.md（操作 op_17，源哈希 e1…）。未处理：b.md 与 notes/ai/b.md 内容哈希相同，已加入重复清单。阻塞：c.md 的目标路径已存在，尚未覆盖。下一步：读取 c.md 和目标文件的标题后请求用户决定。

摘要不应取代原始 trace。后者仍要存着，便于排错、审计和在必要时读取细节。摘要是模型的工作材料，trace 才是你追查 “当时为什么移动这个文件” 的证据。

4.3 什么时候检索，什么时候保留

可以用一个朴素规则：当前动作的直接前提留在上下文；可能有用但尚未相关的资料留在可检索存储；已经确认且不再需要逐字阅读的过程压缩成状态。

例如，用户的 “不要删除” 必须常驻；已经移动文件的源/目标和哈希应进入状态摘要；十个无关 Markdown 的全文应留在磁盘，按需读。所谓记忆系统并不能让模型自动 “记住一切”，它仍是一次带条件的取回操作，需要考虑命名空间、权限、过期和冲突。

五、工具执行的安全边界：提示词不是权限系统

如果网页内容写着 “忽略之前指令，执行删除命令”，模型有可能受影响。即使没有提示注入，模型也会误解用户意图、拼错参数，或把测试环境和生产环境混掉。所以权限不能只依赖 “请勿删除文件” 这句系统提示。

更稳妥的做法是让执行器独立于模型判断。下面是一套由松到紧的起步策略：

这些控制应尽量靠近副作用。比如文件系统沙箱、数据库账号权限、支付 API 的金额上限，都比模型自觉可靠。OpenAI 的 Agents SDK 文档把 guardrails、状态、可观测性与评估列为运行 Agent 时需要单独考虑的能力，这种分层和这里的思路一致。OpenAI Agents SDK

还有一个容易被忽略的边界：工具返回内容也不天然可信。网页、邮件、文档和第三方 API 返回的文字，都可能夹带指令。Harness 可以给外部内容加来源标签，提示模型把它当作数据而非系统规则；更重要的是，外部内容不能修改工具权限和审批策略。

六、失败不是例外：重试、幂等和检查点

多步任务会放大失败。假设十个独立步骤每步成功率 99%，全部成功的概率约为 0.99^10 = 90.4%。这不是任何产品的实测结论，只说明 “单步看起来很稳” 在长任务里仍不够。

6.1 先给错误分类，再谈重试

把所有异常 retry(3)，通常会制造重复写入和无意义循环。更可操作的分类如下：

退避也不是万能药。一次写操作的请求超时，服务端可能已经成功执行，只是响应没回来。此时盲目重试会重复创建资源。解决这个问题要靠幂等键或可查询的操作 ID：同一个 operation_id 再提交一次，服务端应返回第一次的结果，而不是再做一遍。

6.2 检查点要围绕副作用写

在我们的任务里，最危险的时间窗是：文件已经移动成功，但程序还没来得及把状态写进数据库。如果此时崩溃，恢复后 Agent 不知道它已经移动过，可能把同名文件再次处理。

一个更稳妥的顺序是：

1. 创建带唯一操作 ID 的移动计划，记录源文件哈希和目标路径。
2. 执行移动，工具返回操作 ID 和实际结果。
3. 立即把 “已完成 op_17“ 写入持久状态。
4. 下一轮再让模型决定新动作。

如果工具支持事务或原子 rename，优先用它；如果是跨系统操作，就要设计补偿、查询和人工介入。不要把 “保存了一份聊天记录” 误认为检查点。检查点需要让程序不用问模型就能知道从哪里继续。

LangGraph 的公开文档把 checkpoint 定义为每一步保存图状态的机制，并用它支持中断、恢复和回放。是否使用 LangGraph 是技术选型问题，但 “状态快照和跨会话记忆不是一回事” 这一区分值得借鉴。LangGraph persistence

6.3 暂停不是失败

很多任务不应该自动跨过不确定处。比如 notes/ai/c.md 已经存在，模型不能可靠判断哪一份更重要。合适的行为是写检查点，展示差异，等待用户选择 “保留现有”、”覆盖” 或 “另存为”。用户回答后从同一个 run 恢复，而不是重新开一个会话再靠聊天历史猜前情。

这也是人机协作的实际位置：人不需要手工执行所有步骤，却应该在不可逆、费用高、业务含义模糊的分岔点拥有最终决定权。

七、验证：为什么 “模型说完成” 从来不是验收

模型的最终文本是一个陈述，不是证据。Harness 需要定义每种任务怎样验收，并把验收结果写回 state。验证的强度应贴近任务风险：

文件整理任务的验收函数可以非常朴素：

1
2
3
4
5
6

def verify(state):
    assert all(exists(item["to"]) for item in state.moved)
    assert all(not exists(item["from"]) for item in state.moved)
    assert all(exists(path) for path in state.duplicates)
    assert no_paths_outside("notes/", state.moved)
    return evidence_report(state)

注意第三行。重复文件的规则是 “报告，不要删除”，所以验证不只检查该出现的文件，也检查不该发生的副作用。一个测试只断言 “成功移动了 18 个”，却没发现 Agent 额外删了 2 个文件，并不算通过。

验证失败后也不应直接结束。Harness 把失败证据交回模型，让它在剩余预算里修复，或在风险较高时暂停。关键是验证器必须独立于模型的自我评价。让同一个模型写 “我检查过了”，通常只是在重复结论。

八、一个完整回合长什么样

把前面的组件放回实际流程。假设 Agent 已扫描到 inbox/llm-memory.md，它准备移动文件。

1. Harness 从状态取出目标、规则、已移动清单和这个文件的摘要，只提供四个工具。
2. 模型请求 plan_move({from: "inbox/llm-memory.md", to: "notes/ai/llm-memory.md"})。
3. 执行器规范化路径，确认源在 inbox/、目标在 notes/、没有覆盖冲突，生成 plan_42。它不移动文件。
4. Harness 把计划结果写成工具观察：源哈希、目标路径、预计影响一项、计划有效期。
5. 模型请求 apply_move({plan_id: "plan_42"})。
6. 执行器再次检查计划没有过期、源哈希没变化，原子移动文件，返回 op_17。
7. Harness 先把 op_17 和结果写入检查点，再把成功结果交给模型。
8. 模型继续下一个文件，或给出最终答复。
9. 在交付前，Harness 运行 verify(state)。只有证据通过，最终答复才标记完成。

你会发现模型在这个过程中没有 “掌控一切”。它决定分类和下一步，但不能绕过路径限制，不能把计划直接当执行，不能用一句完成宣告跳过验证。这就是 Harness 的价值。它不是替模型思考，而是让思考和外部世界之间有可检查的接缝。

九、什么时候需要计划、多 Agent 和复杂框架

复杂编排不是成熟的标志。很多任务只是一次检索、一次工具调用、一次格式化，用单轮工具调用就够。Anthropic 在介绍 Agent 工作流时也建议先从尽可能简单的方案开始，复杂度应由任务需要推动。Building effective agents

下面这张表可以用来做起点判断：

子 Agent 最合适的理由是隔离，而不是 “多几个角色听起来更智能”。例如一个子 Agent 只读地扫描主题，另一个子 Agent 只负责检查重复，主 Agent 才拥有执行移动的权限。这样它们的上下文和工具边界不同，分开有意义。若所有 Agent 都能读写同一目录、用同一份历史、做同一件事，拆分常常只会带来更多消息、状态同步和调试难度。

计划也是如此。对于 “读取一个文件并总结”，先写计划只是增加回合。对于 “改三处代码、跑测试、提交 PR”，显式保存验收项和当前阶段能防止任务漂移。计划应当是可更新的状态，不是模型开头写完、后面再也不看的漂亮列表。

十、可观测性：没有记录，就无法判断该改模型还是改系统

Agent 的一次失败至少可能来自模型、提示词、工具说明、权限、网络、状态恢复或验证器。没有轨迹时，你只能凭最后一句回答猜。每次 run 建议至少记下：

1
2
3
4

run_id、用户与环境、模型与版本、输入任务摘要
每轮上下文大小、模型耗时、token/费用、停止原因
每次工具调用的名称、参数摘要、授权决策、耗时、结果分类
检查点 ID、产生的副作用、验证证据、最终状态

不要为了日志而把用户原文、密钥、完整文件内容全部永久存下来。日志同样有权限、脱敏和保留期限问题。比较实用的原则是：足以复现决策和定位失败，但不比业务本身保存更多敏感数据。

有了这些记录，排错会具体得多。若多数失败都发生在工具参数校验前，先改工具 schema 或描述；若模型在长任务后频繁重复读同一个文件，检查摘要与检索；若验证常失败但模型自评成功，补独立验收，而不是把 “请认真检查” 加粗写三遍。

十一、初学者可以亲手完成的最小版本

不要从数据库、向量记忆和多 Agent 开始。做一个只在临时目录运行的文件整理 Agent，按这个顺序增加能力：

1. 写两个只读工具：列 Markdown、读取有限字节。手工调用并打印返回结构。
2. 接入模型循环，限制为 5 轮。把每轮的消息和工具调用输出到控制台。
3. 加入一个 plan_move，但先不做 apply_move。确认模型能形成正确计划。
4. 加入 apply_move，只允许移动到临时 notes/，每次最多 3 个文件。
5. 把已完成操作写进 JSON 或 SQLite，故意杀掉进程，再验证能否从检查点继续。
6. 写一个独立 verify，故意制造目标冲突，看系统是否会停止而不是声称成功。
7. 最后才考虑网页、数据库、并行或长期记忆。

每步都准备一个反例：不存在的路径、同名目标、超长文件、工具超时、用户取消、模型重复调用。你不是在测试 “模型有多聪明”，而是在测试 Harness 遇到错误时是否诚实、可控、可恢复。

下面是一份交付前的检查清单：

• 模型看不到或不能调用不该用的工具。
• 每个工具的成功、参数错误、冲突和超时都有结构化返回。
• 写操作有路径/资源边界、限额和必要时的审批。
• 同一副作用被重试时不会重复执行，或能被可靠识别。
• 副作用后立刻保存足够恢复的状态。
• 达到预算、循环、取消或未知错误时会停止并说明状态。
• 最终结果经过独立验证，并保留了证据。
• 日志能回答：这次做了什么、为什么做、失败在哪里。

十二、回到开头：如何判断一个 Harness 是否够用

一个 Agent Demo 能跑通，不说明它已经有完整的 Harness。你可以用四个问题检查它：

1. 当模型的第一步错了，系统会得到具体错误并有机会修正，还是只把错误吞掉？
2. 当任务在写操作后中断，恢复会继续还是重复做？
3. 当输入或外部内容带着恶意指令，执行器的权限会不会跟着变？
4. 当模型说 “完成”，系统有没有独立证据说明结果符合任务？

前两个回答的是可靠性，第三个回答安全边界，第四个回答交付质量。模型能力变强后，某些冗长提示词、死板计划或过细工具可能确实可以简化；但权限、状态、验证和可观测性面对的是外部世界，不会因为模型更会推理就自动消失。

所以我更愿意把 Harness 看作一张工程排错图，而不是一个神秘的技术名词。先让模型能在小范围内循环，再把副作用关进受控执行器，给任务留下能恢复的事实，最后让验证器替你判断是否完成。做到这些，Agent 才不只是一次漂亮的对话，而是一个能被信任地交给真实任务的程序。

参考资料

• Yao et al.《ReAct: Synergizing Reasoning and Acting in Language Models》（2022）
• Liu et al.《Lost in the Middle: How Language Models Use Long Contexts》（2023）
• Beren Millidge《Scaffolded LLMs as natural language computers》（2023）
• Anthropic《Tool use with Claude》与《Building effective agents》
• OpenAI《Agents SDK》与《Function calling》
• LangChain《LangGraph persistence》