知识点思维导图
25 个知识节点
Harness Engineering（14） - 构建生产级命令行 Agent
读完后，你应能完成以下任务：
- 绘制“Harness Engineering（14） - 构建生产级命令行 Agent / 先想清楚：要造什么、用哪些零件”的关键对象与数据流，解释“看到这张表你应该有底了——实战不是学新东西，是把学过的拼起来。”，并用源码位置、日志或 Trace 标注证据。
- 为“Harness Engineering（14） - 构建生产级命令行 Agent / 组装的关键：分层清晰，各管一段”设计正常与异常输入，验证“每一层只管自己的事，通过清晰的接口衔接。”，输出首个偏差位置与回归测试结果。
- 实现“Harness Engineering（14） - 构建生产级命令行 Agent / 把核心循环组装出来”的最小代码或配置，检验“这是把第 02、06、08、10 章拧在一起的中枢。”，输出命令、结果与 Diff，并说明不适用边界。
前 10 章把 harness 的零件一个个讲透了。这一章，我们把它们全部捏在一起，造一个真能在终端里用的命令行 Agent——一个迷你版的 Claude Code。 这是检验你是否真懂的时刻：不是抄某一章的片段，而是把循环、工具、系统提示、上下文、权限、日志组装成一个协调的整体。
一、先想清楚：要造什么、用哪些零件
目标：一个终端对话式 Agent，能帮你在当前项目里读文件、列目录、写文件、答疑。 安全、可用、看得见过程。
零件清单（每个都标了来自哪一章，方便你回看）：
| 零件 | 作用 | 来自 |
|---|---|---|
| 核心循环 | 驱动 Agent 转起来，带轮次上限 | 第 02 章 |
| 工具集 | list / read / write 文件 | 第 03、04 章 |
| 工具 schema | 让模型选对工具 | 第 04 章 |
| 系统提示词 | 给 Agent 立身份和规矩 | 第 05 章 |
| 上下文管理 | 历史过长时截断保命 | 第 06 章 |
| 权限门卫 | 写文件等操作前确认 | 第 08 章 |
| 日志 hook | 记录每次工具调用 | 第 10 章 |
| 对话入口 | 终端交互界面 | 第 03 章 |
看到这张表你应该有底了——实战不是学新东西，是把学过的拼起来。这正是综合实战的意义。
二、组装的关键：分层清晰，各管一段
别把所有逻辑糊成一坨。一个清爽的结构是这样分层的：
┌─────────────────────────────────────┐
│ 对话入口（main）：读用户输入、显示回答 │ ← 最外层，跟人打交道
├─────────────────────────────────────┤
│ 核心循环（run_agent）：想→做→看→喂回 │ ← 中枢，驱动一切
├─────────────────────────────────────┤
│ 门卫 + hook：执行前确认、执行后记日志 │ ← 横切关注点，包在工具执行外
├─────────────────────────────────────┤
│ 工具集（list/read/write）+ schema │ ← 最底层，实际干活的手
└─────────────────────────────────────┘
每一层只管自己的事，通过清晰的接口衔接。 这样哪层出问题就改哪层，互不牵连——这也是为什么第 10 章强调"核心循环要薄"。
三、把核心循环组装出来
这是把第 02、06、08、10 章拧在一起的中枢。 注意看注释标的"这一步来自第几章"：
短短二十行，集齐了大半本小册的知识点。 这就是 harness 的魅力——核心朴素，靠各层协作撑起复杂行为。
四、迭代的智慧：先跑通最小闭环，再加料
千万别想着一次写完美。正确的实战节奏是小步迭代：
第 1 步：先让"循环 + 一个 read_file 工具"跑通 → 有了最小闭环
第 2 步：加 list_files、write_file → 工具变丰富
第 3 步：给 write_file 加门卫确认 → 安全兜底
第 4 步：加日志 hook、加上下文管理 → 健壮起来
第 5 步：打磨系统提示词、优化交互体验 → 好用起来
每一步都保证能跑、能测，再进入下一步。 这样即使出 bug，范围也被锁在刚加的那一小块里，好排查。
💡 这其实也是 Agent 自己干活的方式（第 02 章）——走一步、验证一步、再走下一步。造 Agent 和 Agent 干活，是同一种智慧。
五、常见错误
❌ **错误 1：一上来追求大而全。 ** 十个工具、各种花活一起写，出 bug 找不到北。 **先最小闭环，再逐步加。 **
❌ **错误 2：层次糊成一坨。 ** 门卫、日志、工具逻辑全塞进循环，循环变成几百行的怪物，没法维护。 **分层，各管一段。 **
❌ **错误 3：忘了上下文管理，长对话直接崩。 ** 在终端里聊久了上下文撑爆，Agent 报错。 务必加上第 06 章的截断/压缩。
❌ **错误 4：交互体验差。 ** 不显示 Agent 在调什么工具，用户一脸懵以为卡死了。 把过程可视化（哪怕简单 print），体验天差地别。
六、最佳实践
✅ 先列零件清单，明确每块来自哪、干嘛用，做到心里有数再动手。 ✅ 分层组装：入口 / 循环 / 门卫+hook / 工具，各司其职，接口清晰。 ✅ 小步迭代：每步都保证能跑能测，再加下一块。 ✅ 必加上下文管理，否则长对话必崩。 ✅ 过程可视化 + 友好提示，让用户看得见 Agent 在干嘛。
七、动手实践：Mini Claude Code：组装一个可用的命令行 Agent
集成的能力（括号是来源章节）：
- 核心循环 + 轮次上限（02）
- 工具集：list_files / read_file / write_file（03、04）
- 工具 schema（04）
- 系统提示词（05）
- 上下文管理：历史过长自动截断保住 system（06）
- 权限门卫：write_file 执行前确认（08）
- 日志 hook：记录每次工具调用（10）
7.1 两个版本
| 文件 | 说明 | 需要 Key |
|---|---|---|
agent_mock.py |
离线版，跑一段内置对话演示完整流程 | ❌ |
agent.py |
真实 Anthropic SDK 版，可在终端真对话 | ✅ |
7.2 怎么跑
离线版（先看这个，一键演示全流程）：
python agent_mock.py
会自动跑几轮对话：列目录 → 读文件 → 写文件（触发门卫确认）； 每步都有日志 hook 记录，结尾打印工具调用日志。
真实版：
pip install anthropic
export ANTHROPIC_API_KEY="你的key"
python agent.py
# 然后在终端里跟它对话，比如："这个目录有哪些文件？读一下 agent.py 开头讲了什么"
7.3 看点
- 分层结构：对照第 11 章的四层图，看代码怎么把入口/循环/门卫+hook/工具分开。
- 核心循环集大成：
run_agent一个函数里能数出 6 个章节的知识点。 - 门卫 + 日志包在工具执行外：核心循环本身很薄，安全和日志是"挂上去"的。
- 这就是一个最小但完整的"Claude Code"骨架——你已经会造了。
八、总结
- 先想清楚：要造什么、用哪些零件：看到这张表你应该有底了——实战不是学新东西，是把学过的拼起来。
- 组装的关键：分层清晰，各管一段：每一层只管自己的事，通过清晰的接口衔接。
- 把核心循环组装出来：这是把第 02、06、08、10 章拧在一起的中枢。
- 迭代的智慧：先跑通最小闭环，再加料：💡 这其实也是 Agent 自己干活的方式（第 02 章）——走一步、验证一步、再走下一步。
学完自测
选择所有正确答案；提交后逐项核对判断依据。