Appearance
4.8 Agent = Model + Harness：脚手架工程
你可能见过这个公式：Agent = Model + Harness。它是理解"为什么同一个模型，有的 Agent 好用、有的难用"的钥匙。这一节把 Harness 内部的设计零件一个个讲清楚。
一个贯穿全节的比喻：烈马与挽具
"Harness"这个词本意就是马的挽具（缰绳、马鞍、车辕那一整套）。这个比喻几乎完美：
- Model（模型）= 一匹烈马：力量惊人，但方向不可控、容易受惊乱跑、不懂红绿灯。
- Harness（脚手架）= 挽具 + 缰绳 + 车夫 + 马车：把这股力量套住、引导，让它去拉车、走对路、安全到站。
光有一匹烈马 → 力量大，但乱跑，拉不了货
光有挽具马车 → 没有动力，动不了
烈马 + 挽具 → 才是能干活的"马车"（Agent）💡 关键认知：Agent 的表现，很大一部分不来自模型本身，而来自外面这套挽具。 同一匹马（模型），配好挽具能拉货跑长途，没挽具只能在原地撒野。所以"调 Agent"很多时候是在调 Harness，不是换更强的模型。
那 Harness 这套"挽具"具体由哪些零件组成？下面逐个看。
零件一：Control Flow Design（控制流设计）
人话：设计 Agent 的"行动流程图"——它该按什么顺序做事、什么时候循环、什么时候分支、什么时候停。
🐴 比喻：车夫心里的行车规矩——"先看地图规划路线 → 上路 → 每到一个路口检查走对没 → 到站了就停"。没有规矩的马车，烈马想往哪冲就往哪冲。
最基础的控制流就是 2.3 节的 Agentic Loop（思考→行动→观察→再思考）。但生产级 Harness 会设计得更严谨，常见套路：
Plan（先规划） → Execute（执行） → Verify（验证） → 没过就回到 Execute
↓ 过了
完成这种"阶段门控"（一步没验证通过，不准进下一步）能极大减少 2.4 推理雪崩。控制流设计的本质，就是不让烈马一口气狂奔到底，而是分段、设卡、可回头。
零件二：Error Recovery（错误恢复）
人话：工具调用 / 命令出错时，Harness 不让 Agent 假装没事继续走，而是把完整的错误信息喂回给模型，让它自己看着报错去修。
🐴 比喻：马车轮子陷进泥坑，车夫不是继续抽鞭子（那只会越陷越深），而是把"前轮陷泥、右倾 15 度"这个路况如实报给驾驭者，让他调整策略。
javascript
try {
result = await runTool(call)
} catch (e) {
// ❌ 错的做法：吞掉错误，或只说"失败了"
// ✅ 对的做法：把完整报错栈喂回去
result = `工具执行失败：\n${e.stack}`
}
messages.push({ role: "tool", tool_call_id: call.id, content: result })为什么有效？模型特别擅长看着具体报错改自己的参数——你给它确切的错误栈，它往往一次就修对了；你只说"失败了"，它只能瞎猜。这正是 2.4 模式三（工具出错却继续）的解药。
零件三：Feedback Loops（反馈回路）
人话：Agent 每做完一步，用客观手段检查做得对不对，把"对/错+原因"作为信号反馈回去，而不是任由它自我感觉良好。
🐴 比喻：每走一段就用 GPS 和路标核对"是不是走对了"，错了立刻纠偏，而不是闷头开到终点才发现跑错省了。
常见的"检查员"：
- Linter / 类型检查：代码格式、类型对不对
- 测试运行器：跑测试，红了就是错了
- LLM-as-Judge：用另一个模型给输出质量打分（2.5 节）
- 输出校验器：JSON schema、规则校验（2.7 Guardrails）
💡 Error Recovery 和 Feedback Loops 的区别：前者处理"明确报错了"（车陷泥），后者主动检查"有没有悄悄走偏"（核对 GPS）。两者都是把"客观现实"灌回给模型——这是 Agent 可靠性的命根子。
零件四：Plan Tracking（计划追踪）
人话：把任务拆成一个待办清单，做一项勾一项，时刻让 Agent "看见"还剩什么没做、当前在哪一步。
🐴 比喻：长途送货的行程单——"第1站取货✓、第2站加油✓、第3站卸货⏳、第4站返程"。贴在驾驶台上，马车再跑多远，车夫都不会忘了还要去哪。
为什么需要？长任务里上下文越来越长，早期目标容易被 稀释/遗忘。一个显式的、不断更新的计划清单，相当于给 Agent 一个"外置记忆 + 进度条"，它每一步都能对照"我的总目标是什么、做到哪了"。
💡 你天天用的 Claude Code，那个会列出待办、做一项划掉一项的清单，就是 Plan Tracking 的实现——它不是给你看好看的，是给模型自己锚定进度、防跑偏用的。
零件五：Dynamic Intensity（动态强度）
人话：Harness 根据任务难度，动态调节投入的"努力/算力"——简单的事少花力气快速过，难的事才调动全力深思。
🐴 比喻：平路上让马小跑省力，遇到陡坡才扬鞭让它全力拉。一路都用全力，既累垮马、又浪费。
体现在哪：
- 简单子任务用小/快模型，难子任务才上强模型或推理模型
- 给模型的"思考预算"（如
reasoning_effortlow/medium/high）按难度调 - 简单步骤少给上下文、少调工具，难步骤才展开
这本质是成本与质量的动态平衡（呼应 1.6 选模型档位）：好的 Harness 不会对每件小事都火力全开。
零件六：Compensatory Code（补偿性代码）
人话：Harness 里专门写来替模型兜底、补它短板的那部分确定性代码——凡是模型不擅长、不可靠的事，就别指望它，用普通代码硬保证。
🐴 比喻：马不会看红绿灯、不会算精确距离，于是车上装了自动刹停和里程表替它做这些。不是让马变聪明，而是用机械装置补上它天生不行的部分。
典型场景（都呼应 0.3 能力边界）：
- 模型数不准 / 算不准 → 用代码精确计数、精确计算
- 模型偶尔输出非法 JSON → 用代码做解析兜底 + 重试
- 模型可能漏掉必填字段 → 用 schema 校验强制
- 模型可能调用危险操作 → 用代码做权限门禁拦住
💡 一句话：模型负责"聪明"，补偿性代码负责"靠谱"。 高质量 Harness 的很多代码，都是在替模型擦屁股、设护栏。
零件七：Background Notifications（后台通知）
人话：长任务在后台跑，跑完（或需要你拍板时）主动通知你，不用你一直盯着屏幕。
🐴 比喻：货送到了，车夫按一声喇叭通知你来收，而不是要你全程跟车跑。
体现：任务完成提醒、需要人工确认时弹通知、出错时报警。Claude Code 里任务完成的提示音、Stop Hook 触发的通知脚本（4.4 节）都属于这类——让"人机协作"不必时刻在场。
不想自己造挽具：现成的 Harness 框架
上面这些零件，你可以自己写，也可以用现成框架。它们本质就是"帮你搭好挽具"的工具：
| 框架 | 一句话 |
|---|---|
| LangChain / LangGraph | 最老牌的 LLM 应用框架，LangGraph 专门用图来描述 Agent 的控制流 |
| AutoGen（微软） | 主打多 Agent 对话协作，让多个角色 Agent 互相讨论完成任务 |
| LlamaIndex | 偏 RAG / 数据接入的框架 |
| Vercel AI SDK / Mastra | 前端/全栈友好的轻量 Agent 框架 |
⚠️ 框架帮你省事，但也藏起了细节。先理解 Harness 这些零件在干嘛，再用框架——否则框架一出问题你完全不知道哪儿坏了。很多团队最后选择自己写一个薄薄的 Harness，而不是扛着重框架。
🛠️ 实战练习：拆解你天天用的 Harness
Claude Code 本身就是一套成熟的 Harness。对照本节零件，观察它：
- 控制流：你给个复杂任务，它是不是先列计划再干？（Plan-Execute）
- 错误恢复：故意让它跑一个会报错的命令，看它是不是把报错读进去然后自己改。
- 反馈回路：让它"改完跑测试直到全绿"，观察它如何根据测试结果迭代。
- 计划追踪：复杂任务时它的待办清单是怎么更新的。
- 补偿性代码：想想它哪些行为其实是"代码在替模型兜底"（比如权限确认、文件改动前的校验）。
期望结果：你会发现"Claude Code 好用"很大程度是这套挽具好，而不只是模型强——理解了这点，你能更好地驾驭它，也能自己给 Agent 搭挽具。
📌 关键结论
- Agent = Model + Harness：表现一大半来自模型外的脚手架；调 Agent 常常是在调 Harness
- Harness 像给烈马套挽具：把强大但失控的模型力量，套住、引导成能干活的马车
- 七个核心零件：控制流设计、错误恢复、反馈回路、计划追踪、动态强度、补偿性代码、后台通知
- 核心原则——模型负责聪明，Harness 负责靠谱：凡模型不可靠的地方，用确定性代码兜底
- 可以用 LangChain / AutoGen 等框架搭挽具，但先理解零件再用框架，别被框架黑箱坑住
下一节：4.9 上下文工程