0.2 学习路线：从六大组件到 mini-harness
0.2 学习路线：从六大组件到 mini-harness
本节摘要：地图有了，怎么走？本节给出两条贯穿全书的路线——体系化路线（认识 → 组件 → 自研 → 生产，四篇十二章顺序推进）与速成动手路线（用最短路径在第 10 章写出自己的 mini-harness），并给出面向平台建设者、安全工程师等角色的按需跳读组合。随后是一份先修自查清单：Python、LLLM API、function calling 三项缺一项该补什么。最后声明全书约定：数字属性标注（官方 / 实测 / 社区 / 示意）、示意代码规则、跨教程引用规则，以及最重要的免责边界——本书教你造车，不替你承担试车风险。
学习目标
阅读完本节，你应当能够：
- 选定自己的学习路线并估计所需时间。
- 对照先修清单确认自己可以直接上路。
- 复述全书四条约定，知道在哪里核对每个数字的来源属性。
一、两条主路线
路线 A：体系化路线（约 6~8 小时）
按四篇顺序推进，适合想建立完整知识体系的读者：
| 阶段 | 章节 | 你获得什么 |
|---|---|---|
| 认识（约 90 分钟） | 第 0~2 章 | 定义与边界、六大组件全景图、主流实现解剖 |
| 组件（约 4 小时） | 第 3~9 章 | 每个组件的原理、设计空间与可复用的示意代码 |
| 自研（约 2 小时） | 第 10 章 | 约 500 行可运行的 mini-harness，亲手拼装 |
| 生产（约 1 小时） | 第 11 章 + 附录 | 成本、可靠性、安全边界与检查单 |
每章的读法固定：先读支柱页（地图），再进小节（路径）。支柱页的 mermaid 图与 ASCII 框图是刻意压缩的结构记忆点，读完小节回看支柱页，一章就闭环了。
路线 B：速成动手路线（约 2 小时）
目标是"今天就要有一个能跑的 agent"：
1.3 六组件全景图（10 分钟，知道要造哪六样东西） → 第 3 章 主循环（30 分钟，mini_loop.py 是核心） → 第 4 章 工具系统（30 分钟，至少看 4.1 注册器） → 第 10 章 mini-harness（50 分钟，缺什么回第 5/7 章补）
💡 速成路线的隐藏收益：你会带着"第 10 章缺一块"的具体痛感回去读组件篇，比空白状态读快得多。
按角色跳读
- 平台建设者（自建内部 Agent 平台）：第 2 → 5 → 6 → 9 → 11 章。
- 安全 / 合规向：第 5 章全章 → 第 6 章 → 第 11 章。
- 做判断类组件（路由、护栏）：第 4.2 → 5.3 节，配合《Jev 决策编程》第 6.2 / 7.3 节。
- 想读真实源码：任意章末的「延伸阅读」指向 同站教程库的 9 本单项目精读。
二、先修自查清单
| 先修 | 达标线 | 不达标补什么 |
|---|---|---|
| Python | 能写类与装饰器、能读 type hints、会用 asyncio 更佳 |
任何一门 Python 进阶课的面向对象部分 |
| LLM API | 理解 messages 列表、system/user/assistant 角色、无状态语义 | 各家 API 官方 quickstart（30 分钟） |
| function calling | 知道工具 schema 长什么样、模型如何返回 tool call | 官方 function calling 文档 + 跑一次 demo |
| 命令行与 Git | 天天用 | ——（做编码智能体的 harness，得先懂被自动化的对象） |
环境准备：一个大模型 API Key（任何支持 function calling 的主流模型均可）+ Python 3.10+。第 10 章之前的大部分章节，读代码不需要 Key，动手跑才需要。
三、全书约定与声明
仿照《Jev 决策编程》0.2 节的体例，把"地雷先标出来"：
- 数字属性标注：本书所有关键数字标注来源属性——（官方）厂商自报；（实测）本教程作者实测；（社区）第三方统计或泄露资料整理；（示意）教学假设。例如"OpenClaw 约 39 万 star"是（社区，2026-09），"Jev 单次判断约 100ms"是（官方自报）。
- 示意代码：所有代码块首行注释标注来源文件名；教学示意代码首行注明「写法示意，以官方文档为准」——本书刻意不绑定任何厂商 SDK 的精确接口，接口签名以各家官方文档为准，绝不虚构"精确 API"。
- 交叉引用：指向其他教程的引用一律纯文字，如「详见《Jev 决策编程》第 6.2 节」「延伸阅读：同站教程库《smolagents》」；教程内部链接只指向确实存在的章节文件。
- 时效：事实基准 2026-09。Claude Code 的内部设计基于公开泄露资料与官方文档（社区），细节可能随版本变动；OpenClaw 的 star 数写作本书时仍在快速增长。
属性标注的三个例子，帮你建立对这四个标签的手感：
| 标注 | 含义 | 本书中的一例 |
|---|---|---|
| （官方） | 厂商自报 | Jev 单次判断约 100ms（TypeSafe AI 自报） |
| （社区） | 第三方统计或泄露资料整理 | OpenClaw 约 39 万 star（2026-09 统计） |
| （示意） | 教学假设数字 | 终端任务期望打断次数的健康区间为个位数 |
⚠️ 风险与免责：本书第 5、6 章讨论权限、沙箱与危险操作拦截，示例中会出现
rm -rf、数据外传等危险命令的字面样例——它们只用于教学。把任何 agent 接入真实环境前，必须完成你自己的安全评估；本书给的框架是起点，不是免责条款。
四、一个建议：边读边造
本书的章节安排保证了一个性质：第 3~5 章每章都会产出一个可直接复用的零件——mini_loop.py（主循环）、registry.py（工具注册器）、gates.py（多闸门护栏）。读完前半，你的手里应该已经有三块积木；第 10 章只是把它们和沙箱、上下文、观测拼成整车。因此最好的读法是开一个自己的仓库，每读完一章就把代码抄进去、改跑一遍——harness 工程是手艺活，光读不写，第 10 章会变成抄书。
本节要点回顾
- 两条主路线：体系化（四篇顺序，约 6~8 小时）与速成动手（1.3 → 3 → 4 → 10，约 2 小时），另有按角色跳读组合。
- 先修三项：Python（装饰器级）、LLM API（messages 与无状态）、function calling（工具 schema）；环境只需一个支持工具调用的 API Key。
- 四条约定：数字属性标注、示意代码声明、纯文字交叉引用、2026-09 时效基准；安全示例仅供教学。
- 读法建议：第 3~5 章各留一块积木，边读边攒，第 10 章拼整车。
路线清楚了，约定立好了。从下一章开始进入正题：先把 harness 的疆域丈量清楚——它不是模型、不是沙箱、不是框架，这四者的边界画在哪里，就是第 1 章第一个要解决的问题。