Agent Engineering 101｜00｜Reading Guide
这是一份 mini-agent-harness 系列阅读指南：用一个最小教学实现，理解模型之外的 Agent Runtime、工具、状态、上下文、压缩、扩展和产品外壳。
这组文章在讲什么
配套代码仓库： github.com/llm-101/mini-agent-harness
这组文章用一个最小教学实现 mini-agent-harness，解释 Agent Engineering 里最容易被低估的一件事：模型之外的运行时。
一个模型 API 可以生成文本，也可以生成工具调用意图。但它不会自动管理上下文、执行工具、保存状态、压缩长历史、做权限判断、恢复任务、发出 UI 事件，也不会把这些能力包装成 SDK 或扩展系统。
这些都属于 Harness。
本系列的目标不是复刻 Claude Code、Codex、Cursor 或任何生产级 Agent 产品，而是把一个可运行的最小 Harness 拆开，让每一层都足够小、足够清楚，也足够接近真实系统会遇到的问题。
适合谁读
适合：
- 想从“调用模型 API”走向“构建 Agent Runtime”的工程师；
- 想理解 tool calling、context engineering、memory、session、compaction、extensions 之间关系的读者；
- 想用一个小型代码框架作为学习样本，而不是直接啃大型生产代码库的人。
不适合：
- 只想找一个现成 Agent 平台直接上线的人；
- 只关心 prompt 技巧，不关心运行时边界的人；
- 期待这套教学实现具备生产级权限、安全、并发、评估和运维能力的人。
贯穿例子
为了避免每章变成孤立概念，本系列反复使用同一个任务：
用户说：“帮我修复这个 repo 里的 failing tests。”
这个任务会穿过整个 Harness：
- Product Shell 接收用户输入；
- Context Builder 选择当前模型需要看到什么；
- LLM Call 请求模型给出下一步；
- Agent Loop 解析模型意图；
- Tool Runtime 读取文件、运行测试、写入修改；
- Session Store 保存消息和工具结果；
- Tree History 支持回退、分支和重放；
- Compaction 在长任务中保留连续性；
- Skills 和 Prompt Templates 让调试流程可复用；
- Policy Extensions 在危险操作前介入；
- TUI 把运行过程展示给用户；
- Packages / SDK 让这些能力可以被其他产品嵌入。
阅读路线
| 阶段 | 章节 | 你会建立的心智模型 |
|---|---|---|
| Runtime 主路径 | 01–04 | Harness 是什么，如何从模型调用变成连续行动 |
| 状态与历史 | 05–07 | Message、Event、Session、Tree 如何支撑长任务 |
| 工具与上下文 | 08–10 | 工具执行、工作集构造、长上下文压缩如何协作 |
| 可复用能力 | 11–14 | Skills、Templates、Extensions、Policy 如何进入运行时 |
| 产品化 | 15–16 | TUI、Packages、SDK 如何承载同一个 runtime |
如果只想快速理解主线，先读 01、02、04、08、09、10。
如果要亲手实现一个最小 Agent Runtime，建议按 01–16 顺序读，因为后面的能力依赖前面的边界。
核心术语
| 术语 | 人话解释 |
|---|---|
| Harness | 模型之外的运行时和控制系统，让模型意图进入真实世界 |
| Runtime | 任务真正跑起来时负责调度、状态、工具、错误和事件的系统 |
| Boundary | 谁可以知道谁、谁可以调用谁、变化应该停在哪里 |
| Agent Loop | 把模型输出、工具执行、结果回灌和下一轮推理串起来的主循环 |
| Message | 会话里的持久事实，例如用户输入、assistant 回复、工具结果 |
| Event | 运行过程里的信号，例如 text delta、tool started、usage update |
| Context Builder | 每轮模型调用前，选择模型当前必须看到的工作集 |
| Compaction | 把旧历史折成可继续工作的 summary，而不是简单删除 |
| Skill | 可复用任务知识和流程约束 |
| Extension | 在稳定 hook 点介入 runtime 的能力包 |
| Product Shell | CLI、TUI、Web UI、SDK 等用户接触到的外壳 |
读完之后应该得到什么
读完本系列，你不一定会得到一个生产级 Agent 平台，但应该能回答：
- 一个 Agent 系统除了模型调用，还必须有哪些运行时部件？
- 为什么 tool calling、context、memory、session、UI 不能都塞进一个大 loop？
- 长任务 Agent 如何保存状态、恢复任务、压缩历史和展示过程？
- 哪些能力应该属于 core runtime，哪些应该作为 extension、skill、template 或 product shell？
- 如何从一个小型 Harness 学习真实 Agent 产品背后的工程结构？
这就是 Harness 101 的学习目标：先把边界看清楚，再讨论规模化和生产化。