学 Agent,入口经常比模型 API 更先把人卡住。
不少人第一天就去研究 memory、MCP、skills、multi-agent、Agent OS。概念都对,但落到代码实现时,最先撞上的问题往往很具体:模型怎么看文件?怎么改文件?怎么跑命令?跑错了怎么办?上下文溢出了怎么办?它说做完了,证据在哪里?
我的建议是,从 Pi[1] 这种项目看起。
Pi 在 coding-agent README 里把自己称为一个 minimal terminal coding harness。这个定位很准确。它没有停在聊天壳,也没有把几十个概念堆在一起做演示。默认情况下,它先给模型一组很小的身体能力:read、write、edit、bash。除此之外,Pi 还内置了 grep、find、ls 这类只读检索工具,适合只读模式或按需 allowlist。
再往外,才是 session、context files、compaction、skills、extensions、TUI、RPC、SDK。
Pi 这个顺序把 Agent 的底层工程暴露得很清楚:能力不会从概念里自动长出来,它靠一层层工程边界托住。
推荐参考阅读:
- 深度解析:Harness Engineering
- Agent Memory 架构本质
- 深度解析:Claude Code 源码
- 深度解读:OpenClaw 架构及生态
- AI 操作系统:从指令到意图
- 深度解析:Codex Pet Skill
- 从 Prompt Engineering 到 Context Engineering
- 深度解析:Anthropic MCP 协议
- 顶层思维
- ...
Harness 到底补齐了什么
今天群里有人问什么是 harness,我说:凡是让 Agent 趋近于目标的一切工程化手段,都是 harness(意图 → harness 工程 → 趋近目标)。
这句话可以保留,但还不够落地。
换成工程语言,harness 做的是这些事:让模型能观察环境,能采取动作,动作前能被限制,动作后能被记录,失败后能继续修,最后能拿证据判断任务有没有完成。
用户说:“帮我修一下这个 bug。”
模型本身只能生成文本。它不会天然知道项目结构,不会真的打开文件,不会运行测试,也不会记住刚才改了什么。要让它从“建议你怎么修”走到“自己去修”,至少要补齐几件事:
- 读取项目
- 修改文件
- 执行命令
- 把工具结果送回模型
- 保存行动轨迹
- 裁剪上下文
- 拦截风险动作
- 用真实证据判断完成状态
这些加起来,就是 harness。
别把 harness 想成一个新名词。它就是模型进入真实任务后绕不开的那套工程外壳。
Pi 的价值就在这里:它把最小 coding harness 拆成了模型、loop、工具、session、上下文和扩展点。没有多余包装,骨架直接暴露出来。
先看 Pi 的分层
先别急着把 pi-mono 当成一个 CLI。它的 monorepo 分得很清楚:
packages/ai:多 provider 的 LLM API 适配层packages/agent:通用 agent runtime,处理 tool calling、state、event streamingpackages/coding-agent:终端 coding harness,也就是pipackages/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 只是外围投影。
这个分层处理的都是硬问题:工具调用要不要并发?参数谁来校验?工具失败怎么回给模型?流式输出怎么给 UI?session 怎么落盘?模型看到的上下文和用户看到的界面消息是不是同一份东西?
这些问题都不能只靠 prompt 解决。
Agent 的心跳:先把 loop 写稳
从零写 Agent,先把 loop 写稳,再谈 memory 和 multi-agent。
一个最小 loop 大概长这样:
user goal -> build context -> call model -> stream assistant output -> detect tool calls -> validate tool args -> execute tools -> append tool results -> call model again -> stop with evidence
看起来很简单,写起来全是细节。
流式输出不能只打印到屏幕。你要维护一条正在增长的 assistant message,因为 tool call 可能在流中逐步出现。
工具执行这一步也容易被低估。工具参数要校验,执行过程要能取消,结果要进入 session,错误要返回给模型。多个工具并行执行时,UI 可以按完成顺序展示,但进入下一轮模型上下文的 tool result 最好保持原始 tool call 顺序。否则同一个任务会因为工具返回速度不同,产生不同上下文,后面很难调。
Pi 的 agent core 支持 sequential 和 parallel 两种工具执行模式,还提供 beforeToolCall 和 afterToolCall 钩子。前者发生在工具实际执行前,适合做参数、路径、权限、风险动作检查;后者发生在工具结果返回后,适合做审计、截断、结构化补充和错误标记。
风险拦截适合落在 runtime 层,不能只写进 prompt。命令已经生成,路径已经解析,这时候检查比在 prompt 里写“不要做危险操作”可靠得多。
Agent 工程的第一项基本功,是把 loop 当 runtime 写。不要写成一段模型调用脚本。
工具不是函数,是合约
Pi 默认给模型的工具很朴素:read、write、edit、bash。
这四个工具刚好对应 coding agent 的基本身体能力:
read:观察项目write:创建或覆盖文件edit:做局部修改bash:运行测试、构建、查看环境反馈
grep、find、ls 这类只读工具也很有用。它们看起来只是把 shell 命令拆出来,但能减少模型乱跑命令的机会,也让文件检索更可控。Pi 默认不把它们放进那组四个 coding tools 里,但 built-in tool 集合和只读模式里都有它们的位置。
重点不在工具数量,而在工具合约。
以 read 为例。如果它只是 fs.readFile,很快就会出问题:大文件怎么办?图片怎么办?二进制文件怎么办?输出太长怎么办?敏感文件要不要拦?
Pi 的 read tool 支持 offset/limit,文本输出会按行数和字节数截断。内容被截断时,还会提示下一次该从哪个 offset 继续读。这个细节背后是实战经验:工具结果很容易吃掉上下文窗口,read 和 bash 尤其明显。
bash 也是同样的思路。命令输出通常保留尾部,因为错误大多在最后;输出太大时会截断,并把完整输出写到临时文件;执行过程支持 timeout 和 abort。模型拿到的是整理后的观察结果,不是未经处理的原始输出。
edit 更典型。它要求模型提供精确的 oldText/newText replacement,oldText 必须唯一,不能重叠。执行后返回 diff。这个设计比整文件重写稳得多。修改范围收窄了,结果也方便展示和审计。
工具设计至少要守住几条线:
- 输入有 schema
- 输出适合模型消费
- 大输出要截断
- 截断后要能续读
- 有副作用的工具要返回 diff 或 details
- 工具失败也要回到 loop
如果工具只是把某个 API 包一下,Agent 很快会变成一个不可控的 API 调用器。
Context 要按轮装配
不少人把 context 理解成“把资料塞给模型”。做 Agent 时,这个理解会带来问题。
一个 coding agent 每一轮都可能有很多材料:系统规则、用户目标、项目约定、历史消息、工具调用、工具结果、错误日志、压缩摘要、已读文件、已改文件、当前模型、可用工具、技能描述。
全塞进去,模型会被噪声拖慢;塞少了,它又会忘掉关键约束;顺序乱了,它会抓错重点;旧错误一直留着,它会反复修已经修好的问题。
Pi 的 packages/agent 把这里拆成两步:
transformContext():在 AgentMessage 层做裁剪、注入、压缩convertToLlm():把应用自己的消息类型转成模型能理解的 user / assistant / toolResult
没有这条边界,UI 状态、审计状态、模型上下文会混成一份东西,后面很难拆。UI-only message、bash execution message、compaction summary、branch summary、extension state,并不都应该原样进入模型请求。有些给用户看,有些给审计留,有些只存在 session 里。
Pi 的 SessionManager 里也刻意区分了 custom 和 custom_message:前者是扩展状态,不参与 LLM context;后者才会被构造成模型可见的 custom message。这个细节足够说明一件事:Agent 里的“发生过”和“模型该看到”不是同一个集合。
Pi 的 coding-agent 还会加载 context files,比如全局和项目里的 AGENTS.md / CLAUDE.md。这类文件不用神化。它们更像项目约定入口:常用命令、目录边界、编码风格、不要碰的文件、验证方式。
context engineering 要反复回答几个问题:
- 这轮模型需要知道什么?
- 哪些历史已经过期?
- 哪些工具结果只要摘要?
- 哪些约定需要放到高优先级位置?
- 当前任务推进到哪一步?
回答不好…