12 · Harness：长时任务的骨架

⏱ 28 分钟 ｜ ⭐⭐ 本教程最重要的一节

🔗 可运行实践： 持久化审批与故障恢复 。

🎯 一句话

Harness = 把原始模型智能变成可用 Agent 的那一整套东西（循环 + 工具 + 上下文管理 + 护栏）。 而这一节最重要的一句话是：

「Harness 的每个组件都编码了一个『模型自己做不到某事』的假设—— 而这些假设会随模型进步而过时。」

🧠 一、长任务为什么会失败

让 Agent 连跑几小时到几天（做完整 App、迁移代码库），朴素做法必撞的五头怪：

所有 harness 设计都是在对付这五头怪。 记住它们，你就知道每个组件为什么存在。

🏗️ 二、Harness 的四个组成

💡 模型生成文本，harness 决定这些文本能触碰什么。

📉 三、Harness 减法的三种模式

核心心态：harness 设计不只是「我还该加什么」，更重要的是「我可以停止做什么」。

模式一：依靠模型，而非 harness

💡 为什么通用工具更好：模型在训练中见过海量 bash/文件操作的例子， 而你发明的 my_custom_edit_tool 它一次都没见过。熟悉度本身就是能力。

模式二：给 harness 做减法

模式三：谨慎设置边界

🧬 四、长时运行架构的三代演进

这是本章最有价值的部分——它展示了 harness 是怎么随模型进步而变化的。

第一代：初始化 Agent + 编码 Agent

要解决：过度野心 + 过早宣告完成

两个关键细节：

第二代：GAN 式生成-评估分离

核心洞察：

⭐ 模型评估自己的工作时有系统性正面偏差，主观任务上尤其明显。 把生成与评估分离，远比让生成者自我批判有效。

⭐ 让主观评估可行的关键技巧：

成本对比（复古游戏制作器案例）：

💡 20 倍成本买的是「能用 vs 不能用」，不是「好 vs 更好」。

⚠️ 但要注意演进：对某一代模型必不可少的 Sprint 级分解， 到下一代反而成了多余开销。

🔑 「有用的 harness 设计空间不会随模型进步而缩小，而是会移动。」

第三代：模型自己写 harness

Claude 可以为当前任务现场写出专属的多 Agent 系统（JavaScript 文件 + 派生子 Agent 的函数）。

要对抗的三种失败：

六种常用模式：分类后执行、扇出后综合、对抗式验证、生成后过滤、锦标赛、循环到完成。

⚠️ 什么时候别用： - 没有真正并行需求的常规编码 - 不值得多 Agent 协调开销的任务 - 一个上下文窗口就能解决的问题

🧰 五、可以照抄的最小 harness

# 一个能对付"五头怪"的最小骨架
class MinimalHarness:
    def __init__(self, model, tools, goal):
        self.goal = goal
        self.state_file = "progress.json"      # ⭐ 对付"状态丢失"
        self.max_steps = 50                     # ⭐ 护栏
        self.token_budget = 100_000

    def run_session(self):
        state = self.load_state()               # 从文件恢复，不靠上下文
        # ⭐ 对付"目标漂移"：每个会话开头重申目标 + 当前状态
        system = f"""目标：{self.goal}

当前进度：{state['done']} / {state['total']} 项已完成
下一项：{state['next_task']}

规则：
1. 一次只做【一个】功能项，做完立即更新 progress.json 并提交
2. 宣布完成前必须运行验证脚本并通过     ← 对付"过早宣告完成"
3. 不要开始新功能，直到当前这个通过验证  ← 对付"过度野心"
"""
        for step in range(self.max_steps):
            if self.tokens_used > self.token_budget * 0.75:
                self.compact()                  # ⭐ 对付"上下文焦虑"
            ...
        self.save_state(state)                  # 会话结束前落盘

这个骨架里每一行都对应一头怪——这就是 harness 设计的思维方式。

⭐ progress.json 有个正式名字：工作记忆（working memory）。 它是04b · Agent 记忆四层结构里的一层——只服务于当前这个任务，任务做完就该整个丢掉。 知道它是「哪一层」很有用，因为四层的写入和淘汰规则完全不同，混在一起就会烧钱或者出错：

这里的东西	是哪一层	任务结束后
progress.json 里的 next_task / done	工作记忆	⭐ 整个丢掉，留着只会污染下一个任务
「这个项目用 pnpm 不用 npm」	长期记忆	留下，下次开工直接生效
「上次改这个文件把 CI 跑挂了」	情景记忆	留下，是下次的避坑依据

⚠️ 最常见的错法是把三者全塞进同一个 progress.json——文件越滚越大， 每个会话开头都要整个读回上下文，Token 成本随任务时长线性上涨，而其中大部分早就没用了。 04b 讲的就是怎么分层、怎么判断一条该不该写、以及过期的怎么忘掉。

🔁 六、Harness 的定期体检

每次模型升级后，问这五个问题：

⚠️ 注意第 ⑤ 条：功能性的变通可以删，安全边界不能删（第 15 章）。 「模型现在更聪明了所以不用沙箱了」是错误的推论—— 安全护栏防的是外部攻击，不是模型能力不足。

🕳️ 七、六个常见坑

📚 延伸阅读

• Agent Harness 设计的三种模式
• 长时运行 Agent 的有效 Harness
• 长时应用开发的 Harness 设计
• 一任务一 Harness：动态工作流

👉 这一节对应的框架：LangGraph 主攻的正是这里最难的半截 —— 状态怎么外置、断了怎么接着跑。对照关系在 16b · 框架这层皮。

✅ 检查点

1. Harness 是哪四部分组成的？
2. 长任务失败的五头怪是什么？
3. 本章最重要的那句话是什么？它的实践含义是什么？
4. 减法的三种模式分别是什么？
5. 为什么长时任务的状态文件推荐 JSON？
6. 为什么要把生成和评估分离？
7. 「这个设计美吗」该怎么改写才能让评估可行？
8. 模型升级后哪些 harness 组件可以删，哪些不能？

🛑 可以停在这里

⚡ 走神救援

下一节 👉 13-多Agent协作.md