1. 从pi这个极简名字说起它到底是个什么东西第一次看到pi这个名字我以为是那个圆周率或者是树莓派Raspberry Pi的缩写。直到我在几个技术社区反复刷到pi agent、pi coding agent、pi subagent、pi desktop这些词才意识到这是一个正在被频繁讨论的coding agent CLI 工具。它的名字起得极其克制就两个字母但背后指向的东西一点都不简单——一个跑在终端里的、能自己调用 LLM API、自己循环执行任务的智能编码代理。先把定位说清楚。pi属于coding agent CLI这个品类和你在终端里敲命令的那种传统 CLI 不一样。传统 CLI 是你给一条指令它执行一条执行完就结束。而pi这类工具的核心是agent loop——它会自己规划、自己调用工具、自己看结果、自己决定下一步直到任务完成或者它认为该停下来问你。这个循环是它区别于普通脚本的本质。那它解决什么问题举个我自己的场景。以前我要改一个跨了七八个文件的重构得自己一个个打开、改、跑测试、看报错、再改。这个过程里大量的时间花在机械地搬运上下文上。pi这类工具的价值就在于它把这个循环接管了你描述目标它去读文件、改代码、跑命令、根据输出调整你只需要在关键节点做决策。它适合谁适合已经有一定工程经验、清楚自己要什么、但想把手上的重复劳动压缩掉的开发者。新手也能用但如果你连自己要改什么逻辑都说不清楚agent 帮不了你。关键词里还有几个值得单独拎出来说的TUI终端用户界面、LLM API、subagent、web 导入 skill。这几个词基本勾勒出了pi的能力边界——它有交互界面、它靠 LLM API 驱动、它支持子代理分工、它能从 web 侧导入技能。后面我会一个个拆开讲。提示pi这个名字在搜索时噪音极大圆周率、树莓派、各种数学库都会混进来。找资料时建议直接带上coding agent或agent loop这类限定词能省掉大量筛选时间。2. agent loop 才是 pi 的心脏不是那个命令行外壳很多人第一次接触pi注意力都放在哇它能在终端里跟我对话上。但真正决定它好不好用的是底下那个agent loop。外壳TUI只是皮循环才是心脏。这一节我把这个循环拆开讲因为不理解它你后面遇到的所有它怎么不按我想的做的问题都无从下手。2.1 一次完整的循环里到底发生了什么一个标准的 agent loop粗略分是这么几步接收目标 → 规划下一步 → 选择工具 → 执行 → 观察结果 → 判断是否继续。听起来简单但每一步都有坑。拿帮我把这个函数的错误处理补全举例。pi收到目标后第一步不是直接改代码而是先去读上下文——它要找到这个函数在哪、被谁调用、项目里现有的错误处理风格是什么。这一步对应的是工具调用里的读文件/搜索。然后它规划是先看测试还是先看调用方这个规划质量直接取决于模型能力和你给的上下文。接着它执行修改执行完观察结果——可能是跑了一遍测试也可能是 lint 报错。如果报错它回到规划步骤重新决定怎么改。这个观察-再规划的闭环就是 agent loop 和一次性生成代码最大的区别。一次性生成是开环agent loop 是闭环。我实测下来闭环的质量高度依赖两件事工具返回的信息够不够干净以及循环的终止条件设得对不对。前者是工具设计问题后者是配置问题。2.2 为什么循环容易跑飞以及怎么拴住它pi最常见的翻车方式不是它不会做而是它做过头。你让它修一个 bug它顺手把周边三个文件也重构了最后 diff 大得你根本不敢 merge。这就是循环没有边界导致的。拴住它的办法有几个我按有效性排序明确任务边界在指令里写清楚只改 X 文件不要动其他文件。这句话对 agent 的约束力比你想的强。设置最大迭代次数大多数 agent CLI 都有类似max_iterations或max_steps的配置。别设太大我一般设 15 到 25 之间够处理中等任务又不至于让它无限试探。用 subagent 隔离把探索性的工作丢给子代理主循环只负责决策。这个后面单独讲。人工确认关键操作涉及删除文件、执行危险命令时让它先问你。注意不要指望一句小心一点就能约束住 agent。约束要靠机制不是靠语气。把边界写进配置和指令模板里比每次口头叮嘱靠谱得多。2.3 循环里的上下文预算是个隐形杀手这一点是很多教程不会告诉你的。agent loop 每转一圈都会往上下文里塞东西——读到的文件内容、命令输出、它自己的思考。转个十几圈上下文就爆了。爆了之后会发生什么要么被截断丢失早期关键信息要么直接报错。我踩过的坑是一个任务跑到一半pi突然开始忘记最开始的需求改着改着方向就偏了。排查半天才发现是上下文被挤爆早期的任务描述被挤出去了。应对办法把长任务拆成短任务每个任务控制在循环 10 次以内能完成的粒度。另外善用总结类工具让 agent 在上下文快满时把已完成的部分压缩成摘要。有些实现里这个叫 compaction看到这个词你就知道它在干这件事。3. TUI 启动就报错account/read failed 的排查链路热词里有一条特别扎眼error: account/read failed during tui bootstrap: account/read failed: worksp。这个报错我太熟了因为它几乎是我第一次跑pi时遇到的第一堵墙。这一节我把完整的排查链路还原出来你照着走一遍基本能定位。3.1 先读懂这个报错在说什么拆开看during tui bootstrap说明错误发生在 TUI 启动阶段也就是界面还没渲染出来之前。account/read failed说明它在读账户信息时失败了。worksp大概率是workspace被截断了指向工作区相关的读取。所以这不是网络问题也不是模型问题而是启动时读取本地账户/工作区配置失败。方向对了排查就快。3.2 我的逐步排查顺序我一般按这个顺序走从最可能到最不可能检查配置文件是否存在且格式正确。pi的账户信息通常存在一个 JSON 或 TOML 配置里。文件不存在、路径不对、或者 JSON 少了个逗号都会导致read failed。先用编辑器打开看一眼别嫌麻烦。检查文件权限。如果配置文件是 root 创建的而你用普通用户跑读不了。ls -l看一眼权限位。检查工作区路径。worksp指向工作区如果你在一个不存在的目录里启动或者工作区路径里有特殊字符读取就会挂。检查环境变量。有些实现把账户信息放在环境变量里变量没设或者设错了同样报这个错。看完整日志。TUI 报错往往只给一行真正的堆栈在日志文件里。找到日志目录看完整信息。我遇到的那次根因是第 3 条——我在一个已经被删掉的目录里启动了pi工作区路径失效。换个目录就好了。这种问题看着吓人其实特别蠢。3.3 一个容易被忽略的点首次启动的初始化有些 agent CLI 首次启动需要先跑一个初始化命令类似pi init或pi login生成账户和工作区配置。如果你跳过了这步直接启动 TUI就会撞上account/read failed。这不是 bug是流程没走完。提示遇到任何bootstrap阶段的报错第一反应应该是初始化流程走完了吗而不是是不是网络问题。启动阶段的错误九成和本地状态有关。4. subagent 与 skill 导入把 pi 从能用推到好用如果你只用pi的主循环它能干活但干得不够漂亮。真正让它上一个台阶的是subagent和skill 导入这两个机制。热词里pi subagent和pi web导入skill都出现了说明这是大家真正在用的功能。4.1 subagent 解决的是注意力污染问题主循环有个天然缺陷所有信息都堆在一个上下文里。探索性的搜索、临时的试错、失败的尝试全都会污染主上下文让主循环越来越糊涂。subagent 的思路是分工。主代理负责决策和整合把具体的、独立的子任务丢给子代理去做。子代理在自己的上下文里折腾只把结论返回给主代理。这样主上下文始终干净。举个实际例子。我要给一个项目加一个新功能需要先搞清楚现有的数据流。我会让主代理派一个 subagent 去探索数据流并返回一份摘要subagent 读十几个文件、画依赖关系最后只返回一段结论。主代理拿到结论直接进入实现阶段完全没被那十几个文件的内容污染。用 subagent 的经验子任务要独立如果一个子任务需要主代理的上下文才能做那它不适合拆出去。返回格式要约定让 subagent 返回结构化结果比如固定字段的 JSON 或固定小标题的 Markdown主代理好解析。别拆太碎拆成三五个子任务合理拆成二十个就是过度设计调度开销比收益还大。4.2 skill 导入把重复经验固化下来pi web导入skill这个热词指向一个很实用的能力——从 web 侧导入技能包。所谓 skill本质是预定义的能力描述 工具组合 提示模板。你把一类任务的正确做法固化成一个 skill以后遇到同类任务直接调用不用每次重新描述。比如你团队有一套固定的代码审查规范你可以把它做成一个 skill包含审查清单、常用检查命令、输出格式模板。以后让pi审查代码直接调这个 skill输出质量稳定得多。导入 skill 时要注意来源要可信从 web 导入意味着你在引入外部定义的指令来源不明的 skill 可能包含不安全的操作。只导入你信任的来源。导入后先审一遍看看它到底会执行什么命令、读什么文件。别闭眼用。按需裁剪导入的 skill 往往带一堆你用不上的东西裁掉保持精简。4.3 主循环、subagent、skill 三者的配合关系这三者不是并列的是分层的。skill 是能力库定义了能做什么subagent 是执行单元负责把某件事做完主循环是调度中心决定现在该做什么。我常用的一个组合模式是主循环识别任务类型 → 匹配到某个 skill → 派 subagent 按 skill 执行 → 主循环整合结果。这套跑顺了之后处理重复性任务的效率提升非常明显。5. 从零跑通一个 pi 任务的实操记录前面讲的都是机制这一节我把一次完整的实操记录下来你能看到每个环节的真实样子。任务设定给一个已有的小项目补一个配置文件加载模块。5.1 环境准备阶段我做了什么第一步不是急着敲命令而是确认工作区干净。git status看一眼确保没有未提交的改动。这一步很重要因为 agent 会改文件如果工作区本来就脏出了问题你分不清是谁改的。第二步确认pi的账户和工作区配置正常就是上一节排查的那套。启动 TUI看到界面正常渲染说明 bootstrap 过了。第三步准备好任务描述。我习惯把任务写成一个小文档包含目标、约束、验收标准。比如这次我写的是新增配置加载模块支持 JSON 和 YAML不改动现有调用方附带单元测试。这三句话直接决定了 agent 的行为边界。5.2 任务执行中我盯的三个点任务跑起来后我不会完全放手会盯三个地方它读的第一个文件是什么。这能看出它对任务的理解对不对。如果它上来就读了个八竿子打不着的文件说明任务描述有歧义赶紧打断重来。它的第一次修改。第一次修改往往定调如果第一次就改错了方向后面越走越偏。它跑测试的时机。好的 agent 会在改完后主动跑测试而不是等你催。如果它改完就停你得在指令里明确要求改完跑测试。这次任务里pi先读了项目结构然后定位到现有的模块组织方式新建了配置文件写了加载逻辑最后补了测试。中间有一次它想改现有的调用方被我拦下了——因为我在约束里写了不改动现有调用方。这说明约束是有效的。5.3 收尾阶段必须做的检查agent 说完成了不等于真的完成了。我收尾必做三件事看 diffgit diff从头到尾过一遍。重点看有没有它顺手改的无关文件。跑全量测试不只是它跑的那几个跑整个测试套件确保没破坏别的东西。检查边界情况agent 写的代码往往 happy path 很顺边界处理潦草。配置文件不存在怎么办格式错误怎么办这些得自己补。这次收尾我发现它没处理配置文件不存在的情况直接抛了未捕获异常。补上之后才算真正完成。6. 那些没人告诉你但一定会踩的坑这一节是我攒下来的实战教训都是文档里不会写、但实际用起来一定会遇到的东西。6.1 模型选型不是越强越好很多人一上来就用最强的模型觉得越强越靠谱。但实际用下来强模型在 agent loop 里不一定最优。原因有两个一是强模型倾向于想太多一个简单任务它能规划出五步反而慢二是强模型贵agent loop 会反复调用成本是普通对话的好几倍。我的做法是分级简单的、机械的任务用中等模型复杂的、需要推理的用强模型。有些实现支持在循环里动态切换那就更好了。6.2 工具返回的信息质量决定一切agent 的判断完全基于工具返回的信息。如果工具返回一堆噪音agent 就被带偏。我踩过的坑是某个搜索工具返回结果时带了一堆无关的匹配agent 基于这些噪音做了错误判断改错了文件。解决办法是精简工具输出。能返回结构化结果就别返回原始文本能过滤就别全量返回。这个优化做一次长期受益。6.3 别在 agent 运行时改文件这个坑很隐蔽。agent 正在读文件、改文件的时候你手动去编辑同一个文件会导致它的上下文和实际文件不一致行为变得诡异。要么等它跑完要么先打断它再改。6.4 长任务的上下文管理要主动干预前面提过上下文预算的问题。实际操作里我会在任务跑到一半时主动检查上下文占用快满了就让它先总结再继续。别等它自己爆掉爆掉之后恢复很麻烦。6.5 版本升级后先跑回归pi这类工具迭代快升级后行为可能变。我每次升级后都会拿一个熟悉的小任务跑一遍确认行为符合预期再上生产任务。这个习惯帮我躲过了好几次升级引入的回归问题。7. 关于 pi 这类 coding agent 的一些个人判断用了一段时间pi之后我对这类工具的看法有了些变化。最开始我以为它的价值是帮我写代码用久了发现它真正的价值是帮我维持任务的连续性。写代码本身不难难的是在一个跨多文件、多步骤的任务里保持上下文不丢、方向不偏。agent loop 恰好擅长这个。但它也有明确的天花板。它不擅长需要领域直觉的判断——比如这个设计虽然能跑但三个月后一定会出问题这种判断它给不了。它也不擅长处理需求本身模糊的任务你越模糊它越乱。所以我的用法是把清晰的部分交给它把模糊的部分留给自己。subagent 和 skill 这两个机制我认为是这类工具未来的分水岭。谁能把分工和技能固化做得更顺谁就能从玩具变成工具。pi在这两个方向上都有布局值得持续关注。最后分享一个我自己的小习惯我会给常用的几类任务各写一个指令模板存在本地。每次用pi直接套模板比每次重新描述省事得多而且输出质量稳定。模板这东西写一次用一年性价比极高。 
长河君 · 2026/10/31 20:53:28 · 阅读 1.2k pi coding agent 深度解析：agent loop、subagent 与 skill 导入实战
1. 从pi这个极简名字说起它到底是个什么东西第一次看到pi这个名字我以为是那个圆周率或者是树莓派Raspberry Pi的缩写。直到我在几个技术社区反复刷到pi agent、pi coding agent、pi subagent、pi desktop这些词才意识到这是一个正在被频繁讨论的coding agent CLI 工具。它的名字起得极其克制就两个字母但背后指向的东西一点都不简单——一个跑在终端里的、能自己调用 LLM API、自己循环执行任务的智能编码代理。先把定位说清楚。pi属于coding agent CLI这个品类和你在终端里敲命令的那种传统 CLI 不一样。传统 CLI 是你给一条指令它执行一条执行完就结束。而pi这类工具的核心是agent loop——它会自己规划、自己调用工具、自己看结果、自己决定下一步直到任务完成或者它认为该停下来问你。这个循环是它区别于普通脚本的本质。那它解决什么问题举个我自己的场景。以前我要改一个跨了七八个文件的重构得自己一个个打开、改、跑测试、看报错、再改。这个过程里大量的时间花在机械地搬运上下文上。pi这类工具的价值就在于它把这个循环接管了你描述目标它去读文件、改代码、跑命令、根据输出调整你只需要在关键节点做决策。它适合谁适合已经有一定工程经验、清楚自己要什么、但想把手上的重复劳动压缩掉的开发者。新手也能用但如果你连自己要改什么逻辑都说不清楚agent 帮不了你。关键词里还有几个值得单独拎出来说的TUI终端用户界面、LLM API、subagent、web 导入 skill。这几个词基本勾勒出了pi的能力边界——它有交互界面、它靠 LLM API 驱动、它支持子代理分工、它能从 web 侧导入技能。后面我会一个个拆开讲。提示pi这个名字在搜索时噪音极大圆周率、树莓派、各种数学库都会混进来。找资料时建议直接带上coding agent或agent loop这类限定词能省掉大量筛选时间。2. agent loop 才是 pi 的心脏不是那个命令行外壳很多人第一次接触pi注意力都放在哇它能在终端里跟我对话上。但真正决定它好不好用的是底下那个agent loop。外壳TUI只是皮循环才是心脏。这一节我把这个循环拆开讲因为不理解它你后面遇到的所有它怎么不按我想的做的问题都无从下手。2.1 一次完整的循环里到底发生了什么一个标准的 agent loop粗略分是这么几步接收目标 → 规划下一步 → 选择工具 → 执行 → 观察结果 → 判断是否继续。听起来简单但每一步都有坑。拿帮我把这个函数的错误处理补全举例。pi收到目标后第一步不是直接改代码而是先去读上下文——它要找到这个函数在哪、被谁调用、项目里现有的错误处理风格是什么。这一步对应的是工具调用里的读文件/搜索。然后它规划是先看测试还是先看调用方这个规划质量直接取决于模型能力和你给的上下文。接着它执行修改执行完观察结果——可能是跑了一遍测试也可能是 lint 报错。如果报错它回到规划步骤重新决定怎么改。这个观察-再规划的闭环就是 agent loop 和一次性生成代码最大的区别。一次性生成是开环agent loop 是闭环。我实测下来闭环的质量高度依赖两件事工具返回的信息够不够干净以及循环的终止条件设得对不对。前者是工具设计问题后者是配置问题。2.2 为什么循环容易跑飞以及怎么拴住它pi最常见的翻车方式不是它不会做而是它做过头。你让它修一个 bug它顺手把周边三个文件也重构了最后 diff 大得你根本不敢 merge。这就是循环没有边界导致的。拴住它的办法有几个我按有效性排序明确任务边界在指令里写清楚只改 X 文件不要动其他文件。这句话对 agent 的约束力比你想的强。设置最大迭代次数大多数 agent CLI 都有类似max_iterations或max_steps的配置。别设太大我一般设 15 到 25 之间够处理中等任务又不至于让它无限试探。用 subagent 隔离把探索性的工作丢给子代理主循环只负责决策。这个后面单独讲。人工确认关键操作涉及删除文件、执行危险命令时让它先问你。注意不要指望一句小心一点就能约束住 agent。约束要靠机制不是靠语气。把边界写进配置和指令模板里比每次口头叮嘱靠谱得多。2.3 循环里的上下文预算是个隐形杀手这一点是很多教程不会告诉你的。agent loop 每转一圈都会往上下文里塞东西——读到的文件内容、命令输出、它自己的思考。转个十几圈上下文就爆了。爆了之后会发生什么要么被截断丢失早期关键信息要么直接报错。我踩过的坑是一个任务跑到一半pi突然开始忘记最开始的需求改着改着方向就偏了。排查半天才发现是上下文被挤爆早期的任务描述被挤出去了。应对办法把长任务拆成短任务每个任务控制在循环 10 次以内能完成的粒度。另外善用总结类工具让 agent 在上下文快满时把已完成的部分压缩成摘要。有些实现里这个叫 compaction看到这个词你就知道它在干这件事。3. TUI 启动就报错account/read failed 的排查链路热词里有一条特别扎眼error: account/read failed during tui bootstrap: account/read failed: worksp。这个报错我太熟了因为它几乎是我第一次跑pi时遇到的第一堵墙。这一节我把完整的排查链路还原出来你照着走一遍基本能定位。3.1 先读懂这个报错在说什么拆开看during tui bootstrap说明错误发生在 TUI 启动阶段也就是界面还没渲染出来之前。account/read failed说明它在读账户信息时失败了。worksp大概率是workspace被截断了指向工作区相关的读取。所以这不是网络问题也不是模型问题而是启动时读取本地账户/工作区配置失败。方向对了排查就快。3.2 我的逐步排查顺序我一般按这个顺序走从最可能到最不可能检查配置文件是否存在且格式正确。pi的账户信息通常存在一个 JSON 或 TOML 配置里。文件不存在、路径不对、或者 JSON 少了个逗号都会导致read failed。先用编辑器打开看一眼别嫌麻烦。检查文件权限。如果配置文件是 root 创建的而你用普通用户跑读不了。ls -l看一眼权限位。检查工作区路径。worksp指向工作区如果你在一个不存在的目录里启动或者工作区路径里有特殊字符读取就会挂。检查环境变量。有些实现把账户信息放在环境变量里变量没设或者设错了同样报这个错。看完整日志。TUI 报错往往只给一行真正的堆栈在日志文件里。找到日志目录看完整信息。我遇到的那次根因是第 3 条——我在一个已经被删掉的目录里启动了pi工作区路径失效。换个目录就好了。这种问题看着吓人其实特别蠢。3.3 一个容易被忽略的点首次启动的初始化有些 agent CLI 首次启动需要先跑一个初始化命令类似pi init或pi login生成账户和工作区配置。如果你跳过了这步直接启动 TUI就会撞上account/read failed。这不是 bug是流程没走完。提示遇到任何bootstrap阶段的报错第一反应应该是初始化流程走完了吗而不是是不是网络问题。启动阶段的错误九成和本地状态有关。4. subagent 与 skill 导入把 pi 从能用推到好用如果你只用pi的主循环它能干活但干得不够漂亮。真正让它上一个台阶的是subagent和skill 导入这两个机制。热词里pi subagent和pi web导入skill都出现了说明这是大家真正在用的功能。4.1 subagent 解决的是注意力污染问题主循环有个天然缺陷所有信息都堆在一个上下文里。探索性的搜索、临时的试错、失败的尝试全都会污染主上下文让主循环越来越糊涂。subagent 的思路是分工。主代理负责决策和整合把具体的、独立的子任务丢给子代理去做。子代理在自己的上下文里折腾只把结论返回给主代理。这样主上下文始终干净。举个实际例子。我要给一个项目加一个新功能需要先搞清楚现有的数据流。我会让主代理派一个 subagent 去探索数据流并返回一份摘要subagent 读十几个文件、画依赖关系最后只返回一段结论。主代理拿到结论直接进入实现阶段完全没被那十几个文件的内容污染。用 subagent 的经验子任务要独立如果一个子任务需要主代理的上下文才能做那它不适合拆出去。返回格式要约定让 subagent 返回结构化结果比如固定字段的 JSON 或固定小标题的 Markdown主代理好解析。别拆太碎拆成三五个子任务合理拆成二十个就是过度设计调度开销比收益还大。4.2 skill 导入把重复经验固化下来pi web导入skill这个热词指向一个很实用的能力——从 web 侧导入技能包。所谓 skill本质是预定义的能力描述 工具组合 提示模板。你把一类任务的正确做法固化成一个 skill以后遇到同类任务直接调用不用每次重新描述。比如你团队有一套固定的代码审查规范你可以把它做成一个 skill包含审查清单、常用检查命令、输出格式模板。以后让pi审查代码直接调这个 skill输出质量稳定得多。导入 skill 时要注意来源要可信从 web 导入意味着你在引入外部定义的指令来源不明的 skill 可能包含不安全的操作。只导入你信任的来源。导入后先审一遍看看它到底会执行什么命令、读什么文件。别闭眼用。按需裁剪导入的 skill 往往带一堆你用不上的东西裁掉保持精简。4.3 主循环、subagent、skill 三者的配合关系这三者不是并列的是分层的。skill 是能力库定义了能做什么subagent 是执行单元负责把某件事做完主循环是调度中心决定现在该做什么。我常用的一个组合模式是主循环识别任务类型 → 匹配到某个 skill → 派 subagent 按 skill 执行 → 主循环整合结果。这套跑顺了之后处理重复性任务的效率提升非常明显。5. 从零跑通一个 pi 任务的实操记录前面讲的都是机制这一节我把一次完整的实操记录下来你能看到每个环节的真实样子。任务设定给一个已有的小项目补一个配置文件加载模块。5.1 环境准备阶段我做了什么第一步不是急着敲命令而是确认工作区干净。git status看一眼确保没有未提交的改动。这一步很重要因为 agent 会改文件如果工作区本来就脏出了问题你分不清是谁改的。第二步确认pi的账户和工作区配置正常就是上一节排查的那套。启动 TUI看到界面正常渲染说明 bootstrap 过了。第三步准备好任务描述。我习惯把任务写成一个小文档包含目标、约束、验收标准。比如这次我写的是新增配置加载模块支持 JSON 和 YAML不改动现有调用方附带单元测试。这三句话直接决定了 agent 的行为边界。5.2 任务执行中我盯的三个点任务跑起来后我不会完全放手会盯三个地方它读的第一个文件是什么。这能看出它对任务的理解对不对。如果它上来就读了个八竿子打不着的文件说明任务描述有歧义赶紧打断重来。它的第一次修改。第一次修改往往定调如果第一次就改错了方向后面越走越偏。它跑测试的时机。好的 agent 会在改完后主动跑测试而不是等你催。如果它改完就停你得在指令里明确要求改完跑测试。这次任务里pi先读了项目结构然后定位到现有的模块组织方式新建了配置文件写了加载逻辑最后补了测试。中间有一次它想改现有的调用方被我拦下了——因为我在约束里写了不改动现有调用方。这说明约束是有效的。5.3 收尾阶段必须做的检查agent 说完成了不等于真的完成了。我收尾必做三件事看 diffgit diff从头到尾过一遍。重点看有没有它顺手改的无关文件。跑全量测试不只是它跑的那几个跑整个测试套件确保没破坏别的东西。检查边界情况agent 写的代码往往 happy path 很顺边界处理潦草。配置文件不存在怎么办格式错误怎么办这些得自己补。这次收尾我发现它没处理配置文件不存在的情况直接抛了未捕获异常。补上之后才算真正完成。6. 那些没人告诉你但一定会踩的坑这一节是我攒下来的实战教训都是文档里不会写、但实际用起来一定会遇到的东西。6.1 模型选型不是越强越好很多人一上来就用最强的模型觉得越强越靠谱。但实际用下来强模型在 agent loop 里不一定最优。原因有两个一是强模型倾向于想太多一个简单任务它能规划出五步反而慢二是强模型贵agent loop 会反复调用成本是普通对话的好几倍。我的做法是分级简单的、机械的任务用中等模型复杂的、需要推理的用强模型。有些实现支持在循环里动态切换那就更好了。6.2 工具返回的信息质量决定一切agent 的判断完全基于工具返回的信息。如果工具返回一堆噪音agent 就被带偏。我踩过的坑是某个搜索工具返回结果时带了一堆无关的匹配agent 基于这些噪音做了错误判断改错了文件。解决办法是精简工具输出。能返回结构化结果就别返回原始文本能过滤就别全量返回。这个优化做一次长期受益。6.3 别在 agent 运行时改文件这个坑很隐蔽。agent 正在读文件、改文件的时候你手动去编辑同一个文件会导致它的上下文和实际文件不一致行为变得诡异。要么等它跑完要么先打断它再改。6.4 长任务的上下文管理要主动干预前面提过上下文预算的问题。实际操作里我会在任务跑到一半时主动检查上下文占用快满了就让它先总结再继续。别等它自己爆掉爆掉之后恢复很麻烦。6.5 版本升级后先跑回归pi这类工具迭代快升级后行为可能变。我每次升级后都会拿一个熟悉的小任务跑一遍确认行为符合预期再上生产任务。这个习惯帮我躲过了好几次升级引入的回归问题。7. 关于 pi 这类 coding agent 的一些个人判断用了一段时间pi之后我对这类工具的看法有了些变化。最开始我以为它的价值是帮我写代码用久了发现它真正的价值是帮我维持任务的连续性。写代码本身不难难的是在一个跨多文件、多步骤的任务里保持上下文不丢、方向不偏。agent loop 恰好擅长这个。但它也有明确的天花板。它不擅长需要领域直觉的判断——比如这个设计虽然能跑但三个月后一定会出问题这种判断它给不了。它也不擅长处理需求本身模糊的任务你越模糊它越乱。所以我的用法是把清晰的部分交给它把模糊的部分留给自己。subagent 和 skill 这两个机制我认为是这类工具未来的分水岭。谁能把分工和技能固化做得更顺谁就能从玩具变成工具。pi在这两个方向上都有布局值得持续关注。最后分享一个我自己的小习惯我会给常用的几类任务各写一个指令模板存在本地。每次用pi直接套模板比每次重新描述省事得多而且输出质量稳定。模板这东西写一次用一年性价比极高。