1. 验房阶段：毛坯房不等于空壳子，装 pi agent 前先看看地基
拿到一套毛坯房，大多数人第一反应是"终于可以按自己的想法来了"，但真到动工那天才发现，墙面要铲、地面要平、水电要重新规划，连个放工具的地方都得自己收拾。我接触 pi agent 那会儿就是这种心态——以为装完就能让它自动写代码、自动修 bug，结果光"毛坯验收"就折腾了一下午。这里说的"毛坯"，不是指项目本身空，而是指 pi agent 的工作环境默认什么都不会替你决定：模型要你自己接，权限要你自己定，工作流要你自己搭。它给的是一个能跑起来的空壳，里面装什么、怎么装，全看你怎么"装修"。
先说清楚 pi agent 是什么。它本质上是一个面向编码场景的智能体工作流工具，跟那些 IDE 里装个插件就自动补全的助手不一样，它的工作方式是：你给它一个任务描述，它会自己规划步骤、调用命令行工具、读写项目文件、执行测试，然后根据结果调整策略，直到任务完成。换句话说，它从"帮你写几行代码"升级成了"帮你把一个活干完"。但代价也很明显——它需要访问你的终端、你的文件系统、你的 Git 仓库，所以配置起来必然比普通插件复杂得多。
我自己的"验房"经历是从一条安装命令开始的。社区里流传的安装方式有好几种，最省事的是下载预编译好的发布包，其次是走包管理器，再就是源码编译。我当时图快，直接下载了发布包，解压到本地目录，把可执行文件软链到了/usr/local/bin下面，结果运行pi --version时报错说找不到动态库。排查了半天才发现是解压目录里的依赖文件路径写的是绝对路径，换个位置就失效了。这种问题在官方文档里未必会写，但遇到一次你就记住了：预编译包这东西，装完最好放在固定目录，别随手扔到临时文件夹里。
如果你打算从源码编译，那"地基"检查就更重要了。pi agent 的代码仓库依赖比较重，至少需要 Node.js 18 以上版本和 Git，某些分支还要求 Rust 工具链。我第一次在旧项目里跑构建，直接卡在依赖安装上——不是网络问题，而是本机的 Node 版本太低，编译器提示语法不兼容。后来用nvm切到 LTS 版本才顺利通过。所以我的建议是：正式安装之前，先花十分钟确认你自己的环境版本，把 Node、Git、包管理器这些基础工具列个清单，别等报错再回头查。
还有个细节容易被忽略：pi agent 安装完成后的"自检"环节。很多装完就跑pi --version，看到版本号输出了就以为完事了，其实版本号只能说明二进制文件能执行，不等于依赖的服务都能连上。我建议你跑一次自检命令，比如pi doctor或者pi config validate，它会把当前环境里缺的东西一次性列出来——哪些命令找不到、哪些配置项没填、哪些端口连不通。这一步就相当于毛坯房验收时敲敲墙壁、看看有没有空鼓，虽然朴素，但能帮你避开后面一大半的雷。
2. 水电改造：安装和网络配置里的那些隐坑，比墙面空鼓更折腾人
毛坯房装修里最让人头疼的不是刷墙贴砖，而是水电改造——墙一铲开，问题全冒出来了。pi agent 的"水电改造"环节，对应的是安装后的依赖管理和网络连通性。这里的水，指的是模型服务的接入；这里的电，指的是终端命令的执行链路。两样不通，后面什么工作流都白搭。
先说依赖安装。我在一个全新环境的服务器上装 pi agent 时，遇到过依赖解析冲突：两个核心库各自锁定了同一个底层包的不同版本，npm 直接报ERESOLVE错误。这种问题在本地开发机上一般不出现，因为本地会慢慢积累兼容的包版本，但全新环境里就是会触发。我当时干了一件蠢事——看到报错就加了--force参数强行安装，结果确实装上了，但跑起来之后行为非常怪异，agent 计划的命令执行一半就莫名中断。后来我把node_modules清掉，改用一个干净的目录重新安装，才恢复正常。所以这个坑的经验是：依赖冲突先别急着"强拆"，优先用npm ci做确定性安装，或者干脆换一个 Node 版本再试，比--force安全得多。
网络问题更现实。咱们这边访问 GitHub 和 npm 官方源的速度，大家心里都有数。pi agent 安装时要从 GitHub Releases 拉二进制，依赖要从 npm 源拉包，任何一个环节卡住都会让你怀疑人生。我的做法是给包管理器配镜像源：npm 这边用国内镜像，GitHub 这边的下载则通过镜像站点中转。注意，镜像站点属于常规技术手段，不要为了"提速"去碰那些不合规的代理工具——合规环境里最稳妥的解法就是切镜像源，实测速度提升非常明显，npm install 从几分钟缩到几十秒。
但有个坑连镜像源都救不了：某些模型的接口地址本身就不在国内可直连的范围。pi agent 的模型配置里，base_url如果填了官方海外地址，你会发现任务刚启动就卡死在请求阶段，日志里全是超时重试。这种情况下，我的应对思路是换一个国内可访问的模型服务商，或者在配置中指定通过企业已有的合规网关来转发请求。核心原则是：模型能不能连上，比模型本身强不强更重要。一个响应慢但稳定的本地模型，体验远好于一个号称顶级但永远连不上的接口。
版本兼容也是"水电改造"里容易被忽略的一环。pi agent 迭代很快，不同版本之间配置文件的字段经常变。我遇到过最典型的情况是：从旧版本升到新版后，原本能跑的配置直接失效，报错提示unknown field。后来养成一个习惯——升级前先看CHANGELOG里关于配置格式的部分，升级后跑一次自检命令，让工具自己把废弃字段标出来。另外，不要盲目追求最新版，如果你的项目里已经跑通了一套工作流，而新版没有带来你必须的功能，那晚点再升也完全没问题。装修讲究的是住得舒服，不是为了住在最新款的样板间里。
3. 墙面地面：配置文件与权限模型，就是你这套房子的户型图
毛坯房装修中，墙面地面决定了房子的骨架和日常动线。对 pi agent 来说，这个"骨架"就是配置文件，而"动线"就是权限模型。换句话说，你在配置里写什么、允许 agent 做什么，直接决定了它在你项目里能走多深、跑多远。
先认识一下 pi agent 的配置体系。它一般分为两级：全局配置放在用户主目录下，作用于所有项目；项目配置放在项目根目录下，只对当前仓库生效。全局配置通常存通用的模型接入信息、默认的上下文参数、全局的命令白名单；项目配置则放与当前代码库强相关的内容，比如项目特有的规则、需要忽略的目录、指定的测试命令。两者是合并关系，项目配置的优先级更高，但如果你想在项目里禁用某个全局行为，直接覆盖就行。
实际操作中，最常接触的配置入口是pi init生成的模板文件，一般是一个 JSON 或 YAML 格式的配置，里面有几个关键字段：
model：模型提供方，常见的有 OpenAI 兼容接口、本地模型（如 Ollama 起服务）、或者云厂商的自研模型base_url和api_key：接口地址和密钥。注意，很多人在 Git 仓库里直接提交了含密钥的配置，这是个很不好的习惯，建议使用环境变量替换，让 pi agent 在运行时读环境变量而不是写死在文件里context相关项：控制 agent 能感知多少上下文，比如最大 token 数、是否自动裁减无用文件permissions：命令白名单与文件访问范围，这是整个配置里最要害的一块
说起权限模型，很多人会嫌它麻烦——默认情况下 pi agent 对命令执行是持"先问过你"的态度的，比如它想运行npm test或者修改某个源文件，会先在终端里征求意见。不熟悉的人会觉得这样很啰嗦，恨不得把auto_accept打开，让 agent 直接执行一切命令。我可以负责任地说：在项目里开全局自动接受，约等于在装修时把承重墙直接拆了。
我自己在最开始使用时，为了图省事把自动接受打开了，结果 agent 在修复一个测试失败时，顺手把构建脚本的配置改了，跑了整整一轮才发现。不是因为 agent 有意搞破坏，而是它在上下文窗口里"看见"的项目信息有局限，它的每一步决策在局部来看都合理，但串起来就可能偏离你的真实意图。后来我把自动接受关掉，只对几个高频、无副作用的命令（比如npm test、git diff）设置白名单，其余操作全部手动确认，项目的稳定性明显上升。
白名单的写法也有讲究。它不是简单地允许或拒绝，而是可以带参数模式的。比如你可以允许npm run lint但不允许npm run lint --fix，因为--fix会直接改动源文件。同样，你可以允许 agent 执行git add .，但不允许git push——这样它可以把代码提交到本地分支，而推送远端这件事永远由人来决定。这套设计思路说白了就是：把不危险的权限放开，把有副作用的权限留着人审。我强烈建议你在配权限时列一个清单：哪些命令是只读的（git diff、cat、ls），哪些会改动文件系统（git commit、sed -i、rm），哪些会产生外部影响（git push、docker build、npm publish），然后按这个分类决定白名单。
配置里还有一类容易被忽视的内容是"规则注入"。你可以在项目配置的rules字段里写一些自然语言或结构化提示，告诉 pi agent 这个仓库的编码规范、目录约定、禁止事项。比如我在一个 Python 项目的规则里写了"所有日志必须使用 logging 模块，不允许 print 调试；新增模型文件必须放到models/目录下"，pi agent 在执行任务时就会把这些规则当作约束条件，大幅减少"改完代码却不符合团队风格"的返工。这个机制的原理其实不复杂——agent 每轮决策前都会把规则内容拼进提示词里，相当于你派了一个项目经理在它耳边反复念要求。
4. 贴砖验收：Plan/Act 工作流实测，真正把"会说话"变成"会干活"
毛坯房装到一半，最激动人心的时刻是厨卫贴完砖、做完防水，这时候你能直观看到"房子真的在变好"。pi agent 对应的这个阶段，是它真正在你的项目里跑通一个完整任务。能不能干活，不看它聊天多流畅，而看它在真实代码库里的 Workflow 稳不稳。这里必须得聊 Plan 和 Act 两套工作流的区别，以及怎么把它们组合成适合自己项目的节奏。
Plan 模式是"先想后做"。它由 agent 生成一份计划，列出它准备执行的步骤、要改动的文件、以及可能的风险，然后停下来等你说"开始"或"修改计划"。Act 模式则是"边想边做"——agent 规划完直接执行，遇到测试失败就自动修，修完再跑，循环往复直到任务完成。两种模式没有绝对好坏，纯粹看任务类型：改一个函数、修一个 bug，Plan 模式更稳，能避免 agent 在句法正确但逻辑错误的路上一路狂奔；新增一个大模块、重构一段核心逻辑，Act 模式的效率优势又很明显，因为它能持续迭代，不需要每跑一步都回来问你。
我自己总结的节奏是"三步法"。第一步用 Act 模式让 agent 自由探索：给它一个目标，比如"找出购物车总价计算错误的原因"，同时明确告诉它不要去改任何文件，只做分析。这个时候 Act 模式的探索效率就体现出来了——它自己读代码、跑测试、打日志，很快能定位问题范围。第二步切换到 Plan 模式，让 agent 针对上一步的结论给出修复方案："基于你发现的原因，列出你将修改的文件、改动内容和验证方式"。第三步再用 Act 模式执行方案，并且明确要求它跑完测试再汇报。这样一轮下来，agent 的每个动作都有依据，你也能在每个关口介入调整方向。
不过实测中最容易翻车的，恰恰是第二步和第三步之间的衔接。有一次我让 pi agent 修复一个因边界条件导致的分页 bug，它在 Plan 模式里提出要改pagination.py里的一个判断条件，我扫了一眼觉得没问题就让它执行。结果 Act 模式一跑，它不光改了那个判断，还顺手重构了整个分页函数的参数签名，理由是"让代码更具扩展性"。虽然测试全绿了，但调用这个函数的其他模块全部报类型错误。这就是 Plan 和 Act 的"语义缝隙"：计划里描述的是目标，执行时 agent 会自己脑补手段。所以我的应对方式是，在 Act 执行前明确加一句"只允许按计划逐条执行，不得扩大改动范围"。这句话能有效把 agent 的"装修欲望"按在计划之内。
再分享一个提升成功率的小技巧：善用测试作为"验收标准"。pi agent 对测试失败的迭代能力，比对需求文本的解析能力可靠得多。我有一个快被跑坏的经验是，当你说"功能有问题"时，agent 往往会从需求角度反复猜测；但当你说"测试用例test_calculate_total失败了，请修复到通过"时，它立刻进入收敛模式。所以我现在写任务描述时，能附测试就附测试，不附测试就让它先写测试再写实现。配上一个命令白名单允许pytest或者npm test，这个"测试驱动 agent"的工作流非常稳。
如果你用的 pi agent 支持--dry-run参数，那这个参数简直就是装修时的"打样"环节。它会在不实际改动文件的情况下，把每一步要执行的命令和改动内容预览出来。我习惯在大改之前先跑一次pi run "实现标签页切换功能" --dry-run，看看它心里的施工图长什么样——如果预览结果里出现了我完全没想让动的文件，那说明任务描述本身有歧义，我会先调整描述再让它真干，而不是让它直接上手。
5. 软装进场：日志、上下文与回滚策略，踩过的坑最后都成了验收单
硬装基本完工，房子开始有了样子，但真正的居住体验，还得看软装——家具摆位、灯光层次、收纳动线。pi agent 用久了你就会发现，决定它好不好用的，往往不是模型多聪明，而是几个看起来不起眼的运维细节：日志怎么看、上下文怎么管、出错怎么回滚。这一章节是我踩坑最密集的区域，也是我认为最值得写下来的部分。
先说日志。pi agent 默认输出的信息其实挺精简的，失败时往往只给一句话"任务执行失败"，光靠这个你根本无从排查。后来我习惯在所有执行命令后面加--verbose参数，它会把每轮 agent 的思考摘要、每次命令的完整输出、每个文件改动的 diff 都打印出来。信息量大了很多，但刚开始读起来非常吃力——满屏都是 token 统计和中间步骤。这是工具使用的正常横跳，建议你先跑一个小任务，把 verbose 日志从头到尾读一遍，很快就能分清哪些行是"决策理由"、哪些行是"动作记录"、哪些行才是"错误根源"。我个人的经验法则是：先在日志里搜error和fail，确认失败类型；如果是网络超时或 rate limit，大概率重试就能解决；如果是命令执行返回非零退出码，就要往下翻到具体的命令输出，看是语法错误还是业务逻辑报错。
上下文管理是另一个大坑。pi agent 每次能携带的上下文长度是有限的，项目稍微大一点，它读几个关键文件就可能把窗口撑满。一旦上下文超限，表现非常迷惑：agent 会突然忘记最初的任务目标，开始自我发挥，或者反复重读同一批文件，效率断崖下跌。这时候你不能怪它——模型的处理能力就这么多，问题的根源在于你没有帮它做"注意力管理"。我的解决办法是在项目配置里维护一个.piignore文件，把node_modules、dist、build、vendor这些目录全部排除在外，并且对某些大型资源文件明确标注"不要读取"。另外，在描述任务时尽量精简，一个任务只聚焦一个目标，不要指望一个 prompt 让 агент从重构到测试到部署一条龙搞定。
上下文问题最经典的"症状"就是 agent 开始重复修改同一个文件、改来改去又回到原样，然后在对话里告诉你说"我已经修复完成"——实际一跑测试还是红的。遇到这种情况，我建议直接终止任务，清空会话，重新描述一遍问题，并且这次把范围写得更小。不要试图在同一个长会话里靠"继续"硬掰回来，越掰越乱。这跟跟人沟通很像，信息过载之后最好的办法不是继续补充，而是重新对齐目标。
回滚策略是装修中的"备用钥匙"。既然 agent 会自主改动文件，那就必须保证每一步都可以反悔。我现在的铁律是：所有 pi agent 执行的任务，必须在一个干净的 Git 工作区里进行，开工前确认git status没有未提交的修改。执行过程中，如果 agent 分多步改了很多文件，我每隔几步就会去看一眼git diff，小步验证没问题就提交一次。这样就算 agent 中途跑偏，我也能精确回到上一个正常节点。还有个很实用的小招：给每次提交写清楚关联的任务编号，比如fix: shopping cart total calculation，后续用git log --oneline翻起来一目了然。
最后再提一个容易被忽略的权限坑。pi agent 默认白名单如果没有配置好，它很容易对不该动的文件下手，比如自动格式化整份文件导致无关行全部变动，或者改写 lockfile 引发依赖变更。我的应对方法是把"格式化"和"lockfile 更新"从自动执行改成手动确认，任务描述里也写明"不要运行任何格式化工具"。这样虽然每轮多了一步确认，但你的 git diff 会干净很多，review 代码的时候心情也会好很多。
6. 入住前的最后检查：从踩坑清单到日常使用习惯
装修收尾阶段，最怕的是住进去才发现有问题。pi agent 的"装修"也是一样，靠一次两次成功任务远远不够，真正让它成为日常开发的一部分，需要养成几个使用习惯。我自己折腾了一段时间之后，沉淀下来一套固定的"入住检查流程"，每次接新项目或者换新环境都按这个顺序走一遍：先做环境自检，确认 Node 版本和 Git 状态；再跑最小任务（比如让 agent 帮我生成一个函数的单元测试），验证模型连通和基本权限；然后检查.piignore和规则文件有没有跟着项目走；最后确认白名单配置里没有放开高风险命令。
还有一个小习惯值得推荐：定期让 agent 自己回顾它在这个仓库里做过的改动。我隔几天会跑一次pi run "根据最近的 git log 总结我们这个项目的代码演进趋势，并指出潜在的技术债"，这种元层面的分析任务消耗不大，但经常能给出很实在的提醒——比如"最近一个月有三个地方都在重复实现日期格式化，建议抽成公共工具函数"。这种用法不需要 agent 权限很高，纯读取模式就能完成，堪称性价比之王。
我在这套"毛坯房"上住了也有一阵子了，最大的体会是：pi agent 这类 coding agent，真正的价值不在于替你把代码写完，而在于把你从"重复劳动"和"琐碎检查"里解放出来。但它能不能发挥这个价值，完全取决于你愿意花多少心思去配置它、约束它、理解它的行为模式。如果你把它当玩具，它就会给你玩具级的产出；如果你把它当工程工具，它就能承担起工程级的任务。装完这套房子，住得舒不舒服，说到底还是看你自己在"装修"时下的功夫。
