第一个 Agent 从 Pi 开始

学习Agent开发，入口往往比模型API更先把人卡住。不少开发者第一天就去研究memory、MCP、skills、multi-agent、Agent OS等概念，这些方向本身没有问题，但落到代码实现时，最先撞上的问题往往非常具体：模型怎么看文件？怎么修改文件？怎么执行命令？执行失败了怎么办？上下文溢出了怎么办？它说做完了，证据在哪里？这些看似简单的基础问题，才是真正考验工程能力的地方。

Harness到底解决了什么问题

建议从Pi项目开始学习。Pi在coding-agent README中将自己定位为「minimal terminal coding harness」——最小化终端编码工具。这个定位非常精准。它没有停留在聊天壳的层面，也没有把几十个概念堆在一起做演示。默认情况下，Pi先给模型一组很小的身体能力：read、write、edit、bash。除此之外，还内置了grep、find、ls这类只读检索工具。再往外，才是session、context files、compaction、skills、extensions、TUI、RPC、SDK等层次。这个顺序把Agent的底层工程暴露得很清楚：能力不会从概念里自动长出来，它靠一层层工程边界托住。

Pi的分层架构设计

凡是让Agent趋近于目标的一切工程化手段，都是harness。用工程语言来说，harness做的事情包括：让模型能观察环境，能采取动作，动作前能被限制，动作后能被记录，失败后能继续修复，最后能拿证据判断任务有没有完成。用户说“帮我修一下这个bug”，模型本身只能生成文本。它不会天然知道项目结构，不会真的打开文件，不会运行测试，也不会记住刚才改了什么。要让它从“建议你怎么修”走到“自己去修”，至少要补齐几件事：读取项目、修改文件、执行命令、把工具结果送回模型、保存行动轨迹、裁剪上下文、拦截风险动作、用真实证据判断完成状态。这些加起来，就是harness。Pi的价值在于：它把最小coding harness拆成了模型、loop、工具、session、上下文和扩展点，没有多余包装，骨架直接暴露出来。

工具不是函数，是合约

先看Pi的分层架构。Pi的monorepo分得很清楚：packages/ai是多provider的LLM API适配层；packages/agent是通用agent runtime，处理tool calling、state、event streaming；packages/coding-agent是终端coding harness，也就是pi本身；packages/tui和packages/web-ui是界面层。这几个包之间的关系大概是：Provider API → agent loop → coding tools → session/context/compaction → terminal UI/RPC/SDK。这个分层比抽象概念更容易落到工程判断上。写Agent最常见的坏习惯，是把模型请求、工具执行、UI输出、文件读写、会话存储全塞进一个函数里。刚开始能跑，后面一加权限、一加压缩、一加恢复，就会变成难以调试的隐式状态机。Pi的边界更清楚：模型适配是一层，agent loop是一层，coding tools是一层，session/context是一层，UI只是外围投影。

Context要按轮装配

Pi默认给模型的工具很朴素：read、write、edit、bash。这四个工具刚好对应coding agent的基本身体能力。工具设计的重点不在数量，而在合约。 以read为例，如果它只是fs.readFile，很快就会出问题：大文件怎么办？图片怎么办？二进制文件怎么办？输出太长怎么办？敏感文件要不要拦？Pi的read tool支持offset/limit，文本输出会按行数和字节数截断，内容被截断时还会提示下一次该从哪个offset继续读。这个细节背后是实战经验：工具结果很容易吃掉上下文窗口，read和bash尤其明显。bash也是同样思路，命令输出通常保留尾部，因为错误大多在最后；输出太大时会截断，并把完整输出写到临时文件；执行过程支持timeout和abort。edit更典型，它要求模型提供精确的oldText/newText replacement，oldText必须唯一不能重叠，执行后返回diff。这个设计比整文件重写稳得多，修改范围收窄了，结果也方便展示和审计。 不少人把context理解成“把资料塞给模型”，做Agent时这个理解会带来问题。一个coding age

如有侵权，请联系删除。