下午两点半我对着app.js里那六百多行路由发呆。这个内部后台系统是我半年前写的当时图省事所有接口全怼在一个文件里。现在要加一组新的订单导出功能每个路由文件都快滚出滚动条了。我本来想手动拆但一想到要连带改中间件挂载顺序、处理 require 循环、再跑一遍几十个接口用例整个人都不太想动。于是我打开了 Pi一个之前在社区里看到的 AI 编码代理工具准备把这事交给它试试。也正是从这天起我正式进入了用 AI 编码实践改造真实项目的阶段。这篇文章就记录一下我上手 Pi 的完整过程它是什么、怎么装、在真实仓库里怎么用、跑了快一个月后踩了哪些坑以及我总结下来的兜底打法希望能给同样在折腾 AI 编程的朋友一点参考。1. 上手前先弄明白Pi 是 IDE 插件还是独立 Agent第一次在热搜里看到pi agent 官网和pi coding agent的时候我下意识觉得它跟 Cursor 一样是个装在编辑器里的 AI 助手。真正装完才发现完全不是一回事。Pi 是一个跑在终端里的编程代理它不依附于任何 IDE直接在你项目根目录下干活。你给它一个任务描述它自己去读代码、定位文件、改代码、跑测试全程你只需要在命令行里看它的操作记录。1.1 Pi 的定位终端里跑起来的编码代理我拿它和几类常见工具对比了一下发现定位其实很鲜明Cursor / Copilot 这类是编辑器内辅助它们的强项是补全你正在写的代码、做局部修改你主导它辅助。OpenCode、Codex CLI 这类是终端里的自主代理你提需求它自己看代码、跨文件修改、执行命令主动性更强。Pi 也属于第二类而且它对多文件重构 测试验证这类任务特别上心。我第一次让它拆路由时它先扫了目录结构读了app.js、package.json还主动确认了测试脚本是npm test然后才动手改文件。这个定位带来的一个直接好处是你不用被绑死在某个编辑器生态里。我在服务器上用nano改配置在本地用 VS Code在笔记本上用 ZedPi 都能跑因为它面对的是目录和文件本身不是某个编辑器的插件接口。1.2 和其他 Agent 的横向对比OpenCode、Codex、Pi 各自擅长什么很多人在热搜里问opencode codex pi 哪个 agent 好用说实话这个问题没有标准答案因为三个工具的目标场景有细微差别。我自己在本地各跑了小两周列了一张比较直观的对照表工具交互方式擅长场景相对短板Pi终端 CLI任务式交互多文件重构、模块拆分、按测试驱动改代码上手需要一点 CLI 习惯OpenCode终端 CLI支持交互式会话快速问答、单文件修改、探索性编码长链路任务容易跑偏Codex CLI终端 CLI偏沙箱执行复杂命令编排、自动化流程需要更明确的步骤指令我的建议是别在哪个更好上纠结太久。如果你跟我一样主要痛点是老项目结构乱、要跨文件改逻辑、还得保证测试能过那 Pi 的干活路径跟需求非常匹配。如果你的任务大多是帮我看看这段代码为什么报错那 OpenCode 这类轻交互工具反而更快。工具是死的场景是活的。2. 安装与初始化命令看着简单坑都在后面Pi 的安装本身不算复杂官方提供了一键脚本也支持通过 npm 之类的包管理器全局安装。我这边因为经常在 Node 项目里折腾用的是 npm 方式npm install -g pi/cli # 示例具体包名和安装方式以官方文档为准 pi --version如果你在服务器上装建议先确认 Node 版本在 18 以上太老的内存管理分配容易出问题。装好之后pi --help会列出一堆子命令这一步通常很顺利。真正坑人的是接下来的初始化和模型配置。2.1 登录鉴权与模型路由先用哪个模型Pi 本身不内置大模型推理能力它需要对接模型 API。首次运行pi init时会让你配置模型供应商和 API Key。这里有两个选择思路如果你用某个固定模型在config.toml里把默认模型写死就行。如果你想省钱可以做一个简单的模型路由简单问答用便宜模型涉及多文件修改的重活切到更强的模型。我的配置逻辑是日常任务走中等能力模型涉及复杂重构或测试驱动修改时我会在任务说明里显式指定用强模型。理由也很直白——重构任务一旦理解跑偏返工成本比多花的 token 贵多了。2.2 路径的中文目录索引报错我踩的第一个真坑安装配置的当天晚上我就在一个路径含中文的项目里翻了车。现象是pi启动后扫目录报了ENOENT错误说找不到某个文件。当时我第一反应是项目里的软链接坏了排查了半天才发现是中文目录名在某个内部处理环节没转义导致的问题。解决方式有两种一是临时把项目挪到纯英文路径下做任务二是配置环境变量让工具走兼容模式。我后来图省事直接把项目路径改成英文了反正不影响代码逻辑。如果你也遇到类似的报错先别急着怀疑项目损坏检查下路径里有没有非 ASCII 字符通常就是它的问题。2.3 初始化时最容易忽略的 .gitignore 问题另一个容易被忽略的细节是Pi 会在项目根目录生成一个状态目录用来存放任务会话记录和中间产物。如果你项目本身用 Git记得把这个状态目录加进.gitignore不然每次任务结束git status都会冒出一堆你不认识的文件看着非常心慌。# .gitignore 追加 .pi/这个操作我在第三天才想起来当时已经被多余的变更记录烦得不行。加上之后整个工作区总算清爽了。3. 让它在真实仓库里干活第一轮实战记录初始化搞定后我决定拿那个order-admin后台系统试试水。任务就是把app.js里的三组路由拆到独立文件。这个任务很典型涉及多文件读写需要保持接口兼容还要回归测试。它同时包含了重构和验证两个环节非常适合测试 AI 编码工具的真实水平。3.1 任务背景一个堆积了半年路由的 Express 老模块这个后台系统用 Express EJS 写的app.js里堆了大概 600 多行路由包括订单、用户、报表三块逻辑。订单相关接口最快还有不少是附近几个页面共用的谁都不敢乱动。我的目标很明确拆成routes/order.js、routes/user.js、routes/report.js三个文件保持原有路径和响应结构不变。3.2 给 Pi 的提示词需求描述怎么写才不翻车第一次用 AI 代理干活提示词千万不能只丢一句帮我拆一下路由。你得把边界、约束、验收方式全部说清楚。我当时写的提示词大致长这样当前仓库/data/projects/order-admin 请把 app.js 中 /api/order、/api/user、/api/report 三组路由拆到独立文件 - routes/order.js - routes/user.js - routes/report.js 约束 1. 保持现有接口路径和响应结构完全不变 2. 拆完后在 app.js 中按原顺序挂载三条路由 3. 不要动 models/ 和 middlewares/ 下的代码 4. 完成后先执行 npm test确保测试全绿再报告结果这里有几个小心机。第一我给了根目录路径省得它到处找仓库。第二我明确说了不要动哪些代码这是最重要的约束AI Agent 特别喜欢顺手优化它觉得不合理的地方。第三我用先跑 npm test全绿再报告把验收条件前置逼它自己验证。3.3 执行过程它怎么拆文件、怎么改挂载、怎么跑测试按下回车后Pi 开始执行。它的操作记录在终端里一步步刷出来先是ls和递归扫描目录确认项目结构。接着读app.js再读package.json确认测试命令和项目类型。然后它把三个路由文件逐一创建出来把对应的router定义和 handler 搬进去。下一步修改app.js把三段路由代码替换成require引入和app.use挂载。最后执行npm test测试通过后它输出了一份简短总结。整个过程大概 6 分多钟。坦白说第一次看它折腾我心里是悬着的特别是看到它连续输出大段 diff 时手都放在 CtrlC 上了。但它确实按计划走完了流程。3.4 结果验收哪些直接可用哪些需要手改任务结束后我先git diff快速过了一眼改动。三个新文件结构干净每个文件的模块导出和 require 都对应得上app.js里的挂载顺序也保持了原来的先后逻辑这点我很满意。跑了一遍常用接口用例订单列表和用户详情的响应结构都没变。不过有一个地方必须人工改原本app.js里有一段处理所有/api前缀的中间件是放在路由定义之前的。Pi 在拆路由时把中间件挂载代码保留在原来的位置但三个路由文件的挂载方式变成了各自app.use(/api/order, orderRouter)这就导致中间件只对订单和用户两组接口生效报表组绕过了它。虽然测试没挂但实际业务里会出问题。我花了几分钟把中间件挂载提前再把三个路由统一挂到/api上才正常。这个案例说明两件事第一AI 代理确实能处理真实重构第二你不能全信它尤其是涉及中间件执行顺序这类隐式依赖的时候。4. 让 Pi 更懂项目Skill 配置和上下文管理跑完第一轮任务我对 Pi 有了基本信任但很快发现一个问题每次新开任务它都要重新读一遍项目结构、重新理解代码规范效率和稳定性都有点碰运气。后来我研究了一下发现 Pi 支持配 skill官方叫法是编码技能。说白了就是一组项目级的规则说明让代理在开始干活前先读一遍相当于给它一本项目工作手册。4.1 Skill 到底是什么你可以把 skill 理解成一份 Markdown 文件里面写了这个项目的关键背景和操作规范。比如项目用的技术栈和核心依赖目录结构说明哪些目录不能动代码风格约定比如用什么命名方式、是否强制分号测试怎么跑lint 怎么跑常见的坑比如不要动中间件挂载顺序Pi 在处理任务时会自动加载这份 skill 内容并且在计划阶段参考它。有了 skill 之后你再开新任务就不用在提示词里反复重复项目背景节省了大量 token也能减少理解偏差。4.2 我配置的一套最小可用 Skill我给我的order-admin项目配了一个极简 skill核心内容如下# order-admin 项目规则 - 技术栈Express 4 EJS数据库用 Sequelize - 路由文件统一放在 src/routes/ 目录禁止在 app.js 里新增路由 - 中间件加载顺序auth - bodyParser - routes不要随意调整 - 所有接口返回 JSON 格式{ code, data, message } - 测试命令npm test测试文件放在 test/ 目录 - 禁止修改 src/models/ 目录下的任何文件如果确实需要改先向用户确认这份 skill 非常简短但每一句都有用。它把之前翻车的中间件顺序问题前置成规则把哪些不能动的边界说清楚任务出错的概率明显降下来了。4.3 上下文管理的三个原则除了 skill我把跑了几周后积累的上下文管理心得也一起写在这里这三个原则我觉得比任何参数调优都有用一次只让它处理一个目标。不要让它顺便把日志模块也优化一下目标越多它越容易在某一个小目标上过度发挥。你要做的是把大任务拆成多个小任务逐个给 Pi 执行。把关键文件路径直接贴在提示词里。别指望它每次都能精准找到你要它改的文件。路径写清楚它能少走很多弯路。先搜后读别让它盲目扫描。Pi 支持执行 grep / ripgrep 之类的搜索命令在任务描述里提示它先定位再读文件能有效降低大规模读文件带来的上下文混乱。这三条看着简单但能显著提升 AI 编码实践的稳定度。我现在每个新任务开始前都会先花三十秒想清楚任务边界再写提示词后面基本不会跑偏。5. 跑了几周之后Pi 的边界与我的兜底清单任何工具用久了你都会摸到它的脾气。Pi 能帮我省大量机械活但它不是神。几周用下来我总结了几类最容易翻车的场景也形成了一套强制性的兜底流程。5.1 最容易翻车的地方隐式依赖和过度自信第一类容易翻车的是隐式依赖问题。就像刚才说的中间件顺序代码里很多关键约束不在你明说的需求里而是藏在项目的历史逻辑里。AI 代理看不到隐式约定它只看得到文件内容和文字指令。所以凡是你觉得这应该是常识吧的东西在提示词里就得明说。第二类翻车是过度自信地补全。有一回我让它给一个列表接口加分页参数它不仅改了接口代码还顺手在数据库查询里加了order by createdAt desc。逻辑没错但性能上并不合适因为表里的数据量还没到需要排序页码的场景。这类自作主张的优化是最需要防范的因为它不改功能逻辑测试全绿但行为跟预期不一致。第三类是幻觉文件。我在一次任务中看它的操作记录发现它尝试require一个不存在的utils/logger.js。原因是它觉得这个项目应该有日志模块可实际根本没有。这就是没有先验证文件存在就动手写的典型表现。好在我盯着 diff及时发现了。5.2 幻觉现场的取证方法怎么高效审 diff既然要防幻觉那审 diff 就是必修课。我给自己定了一个死规矩Pi 每次任务结束git diff必须逐行看一遍。实操技巧如下git diff --stat # 先看改了哪些文件范围是否合理 git diff -- app.js # 再看关键文件的具体改动 git diff --check # 检查空白和冲突标记git diff --check这个命令强烈推荐它能自动扫出重复空格、冲突标记这些不容易肉眼发现的问题。如果你不习惯看大段 diff还可以让 Pi 自己写一个变更说明再对照说明逐项打勾验收。不过注意变更说明也不能全信它只是给你一个检查提纲最终判断还是要你自己下。5.3 我的兜底工作流分支、提交、验证三步走跑了几周之后我形成了一套固定的兜底流程已经成了肌肉记忆每次任务独立开分支。不管任务多小从 main 拉一个新分支再让 Pi 干活。任务完成审完 diff 后合回主干。这样做的好处是万一出了问题直接删分支重来不影响主分支稳定性。每个逻辑点单独提交。不要让 Pi 把一堆改动混在同一个 commit 里。我会引导它分阶段提交比如先提交路由拆分再提交中间件调整。这样 review 起来非常清晰哪个提交引入问题一目了然。强制测试 关键路径人工验证。npm test通过只是底线不是充分条件。凡是跟支付、权限、数据导出相关的核心路径我必须自己手动跑一遍接口确认。AI 代理不会知道你的业务里哪些场景最敏感这个判断只能靠人。有一次线上用户反馈导出订单的 Excel 里多了一列就是因为 Pi 在优化查询语句时顺手取出了某个隐藏字段。测试没报错但业务上明显不对。幸好字段本身无敏感信息不然问题就大了。从那之后我对它的改动审得更狠了。6. 最后说点题外话我用 Agent 编码的一点心态变化写这篇小记之前我特意翻了一下自己在社区里收藏的几篇 AI 编程讨论帖。大家都纠结同一个问题Agent 到底能不能信任我自己的答案也在变从最初的试试看到中间的有点慌再到现在随时盯着但放心让它干。现在我更倾向于把 Pi 当成一个速度很快但偶尔自作聪明的新同事它不是取代我而是把从 0 到 80 分的过程做完我来盯最后的 20 分。在实际使用中我还发现一件有点意外的事让 AI 代理帮我改代码反而倒逼我把项目的代码规范变得比以前清晰了。因为只有项目本身有明确约束Agent 才不容易跑偏。现在我的每个项目根目录下都会放一份简洁的项目说明文档这份文档同时在给人看和给代理看省掉了很多无效沟通。这个内容后续还可以往两个方向扩展一是给 Pi 配更细分的 skill 库不同项目类型加载不同规则二是接入 CI 流程让它在提交后自动跑一轮代码 review把 Agent 的产出在合入前再滤一遍。我现在已经在第二个方向试验了等跑稳一点再单独写一篇实践记录。