最近想系统学一遍 coding agent 的 harness 设计。网上的资料很多，但大部分不是配置合集，就是把 GitHub stars 和 X 上的热度当作质量。看了一圈之后，我发现自己需要的其实很具体：

  1. 先看懂最小 agent loop。
  2. 亲手写出一个能读写文件、执行命令的 mini coding agent。
  3. 再读真实工程，理解上下文、权限、会话、工具和评测怎么组合起来。

下面是我筛选后的学习路线。标准很简单：有可运行代码，作者和来源可核实，学完能自己写 harness。文中链接于 2026 年 7 月 19 日检查。

最短路径

  1. 用 Claude Code 官方文档理解 agentic loop。
  2. 跟写一个 50 到 400 行的 coding agent，不先学框架。
  3. 读 Pi 和 mini-swe-agent，看极简原型如何变成可维护的 runtime。
  4. 再学上下文压缩、权限、长任务和评测。

如果只选一个仓库，我会选 earendil-works/pi。如果只选一篇跟写教程，Go 选 How to Build an Agent，Python 选 Building a minimal AI agent from scratch。

第一梯队：必看

Claude Code 官方机制文档

How Claude Code works 讲 agentic loop、内置工具、会话、上下文窗口、checkpoint 和权限。先用它统一概念，不要一开始就扎进第三方的“Claude Code 内幕”。

读完后应该能画出 gather context -> take action -> verify -> repeat 循环，也应该知道用户在哪些位置可以中断或授权。

不到 400 行的 Go 教程

Thorsten Ball: How to Build an Agent 从空文件开始，先写对话循环，再加 read_file、list_files、edit_file 和 tool result 回传。它把“Agent 其实就是模型、循环和工具”讲得很透。

这篇最好亲手敲一遍。第一遍先保留它的粗糙处，跑通后再补超时、路径边界和命令授权。

Python 最小教程与可运行仓库

教程先用约 50 到 60 行 Python 实现请求模型、解析 action、执行命令和追加结果。mini-swe-agent 则把这个思路做成了有测试、环境隔离、模型适配和评测能力的项目，核心 agent class 仍然只有百行左右。

这组资料很适合对比“最小核心”与“可重现的工程实现”之间到底差了什么。

Pi 的设计复盘与源码

Pi 现在的仓库在 earendil-works/pi，旧的 badlogic/pi-mono 会重定向过去。先读作者的设计复盘，再看代码：

  • packages/ai：模型 API、流式事件、tool call、上下文交接和成本记录
  • packages/agent：agent loop、工具执行、参数校验、状态和事件流
  • packages/coding-agent：会话、工具、项目上下文和扩展
  • packages/tui：终端 UI，开始时可以跳过

有效的读法是跟一次真实 tool call 的代码路径，而不是从目录第一个文件开始逐行通读。

Anthropic 的 Agent 设计原则

Building effective agents 区分 workflow 和 agent，并给出 prompt chaining、routing、parallelization、orchestrator-workers 等模式。其中最实用的建议是：先用模型 API 和可组合的小模式，只在实际问题要求时增加框架复杂度。

第二梯队：遇到问题再读

长任务与跨上下文窗口

重点看 initializer agent、feature list、增量交付、progress file、Git 历史和端到端验证。它解决的不是 agent loop，而是“新会话如何继续旧工作”。

阶段式练习清单

shareAI-lab/learn-claude-code 从 s01_agent_loop 到 s20_comprehensive，包括 tool use、permission、hooks、subagent、context compact、memory、error recovery 和 worktree isolation。

我更愿意把它当课程目录和练习题，而不是生产架构的标准答案。先做 s01 到 s08，然后回到 Pi 或 mini-swe-agent 对比真实实现，没必要一口气做完 20 阶段。

工具设计：MCP 还是 CLI

MCP vs CLI: Benchmarking Tools for Coding Agents 实现了同等的 MCP 和 CLI 工具，比较 token、耗时和成功率。等到需要设计工具协议、控制输出量时，这篇很有用。

Claude Code 架构与源码分析

Karan Prasad 的材料信息密度很高，适合查启动、权限、Bash 解析、上下文压缩和终端渲染等子系统。Rungta 的文章更像架构概览，对 loop、primitive tools、context economy 和权限的关系解释得比较清楚。

两者都是第三方分析。Karan 的文章基于 2026 年 source-map 事件后获得的代码材料；Rungta 说明它基于运行记录、文件产物、行为测试和公开文档。可以用它们找问题和看设计思路，具体事实还是要和官方文档、当前版本交叉检查。没必要下载或复制泄露源码。

只作查阅的大型资料库

  • FlorianBruniaux/claude-code-ultimate-guide：适合查 hooks、skills、MCP、安全和模板，不适合从头线性阅读。
  • affaan-m/ECC（原 everything-claude-code）：大型 skills/rules/hooks 集合。等已经有可运行 harness 后，再按问题挑选模块。
  • anthropics/claude-code：适合看官方 README、issue 和发布信息，不是完整可读的源码仓库。

三个仓库怎么选

仓库最适合的目标它不会提供什么
earendil-works/pi学习可扩展的 TypeScript agent runtime，或实验自己的 coding agent开箱即用的企业权限和治理平台
SWE-agent/mini-swe-agent学最小 Python Agent、环境隔离、轨迹和可重现评测Claude Code 的产品功能复刻
shareAI-lab/learn-claude-code用阶段练习补齐 harness 知识点生产架构的最终答案

亲手写 mini harness 时，先做什么

第一版只要：

  1. 一个模型提供商和流式响应。
  2. user -> model -> tool call -> tool result -> model 循环。
  3. read、write、edit、bash 四个工具。
  4. 取消、超时、最大循环次数和原始消息保存。

第二版再加会话恢复、上下文压缩、路径边界、命令授权、diff、分类重试和固定评测集。先不做 MCP、多模型、多 Agent、长期记忆和复杂 TUI，否则很容易在没看懂核心前就陷入功能堆叠。

Pi 用于企业 Agent 的边界

Pi 适合做 Agent 内核、内部开发者工具或垂直 Agent 原型，但不是企业平台。它的 README 明确说明：Pi 没有内置文件系统、进程、网络和凭据权限系统，默认继承启动用户和进程的权限。需要边界时，要自行加容器、micro-VM 或策略沙箱。

企业落地至少还要补：

  • 身份、RBAC 和租户隔离
  • 工具策略、沙箱和凭据管理
  • 审计、追踪、成本限额和结果持久化
  • 评测回归、版本管理和故障恢复

如果有平台团队，又想控制 runtime 和工具边界，Pi 值得采用或借鉴。如果团队要的是 SSO、多租户、合规审计和 SLA 开箱即用，应该选更完整的平台，而不是直接部署 Pi。

最后的阅读顺序

  1. 读 How Claude Code works。
  2. 按语言选择 Amp 的 Go 教程或 minimal-agent 的 Python 教程，亲手跟写。
  3. 读 Pi 设计复盘，再跟一次 packages/ai -> packages/agent -> packages/coding-agent 的调用路径。
  4. 读 mini-swe-agent 的 agent、environment、model 和 tests，给自己的 mini 版本加评测。
  5. 需要长任务时再读 Anthropic 长任务 harness；需要工具扩展时再读 MCP vs CLI。
  6. 最后用 Karan Prasad 的分析补权限、压缩和终端等生产细节。

我现在的目标不是再收集一批配置和教程，而是按这条路径写出自己的 mini harness。等它能稳定完成一组固定任务后，再决定要不要加 MCP、子 Agent 和长期记忆。这样学得慢一点，但至少知道每一层复杂度是从哪里来的。