先说个我最近的感受电脑里的AI助手我们用了大概不到半年从最初只在网页上聊聊天、问问题到后来慢慢让它帮忙改代码、写正则、补单测再到最近这一个月我真的开始把一整块需求丢给它让它自己翻代码库、拆任务、跑验证。这中间的分水岭就是我开始认真使用Pi coding agent这类真正意义上的“编码代理”而不只是“对话机器人”。Pi是什么简单说它是一个跑在终端里的AI程序员能读你的仓库结构、定位相关文件、跨文件修改代码、执行测试命令来验证结果还能把一个大任务拆给多个子代理subagent并行处理并且通过skill机制把高频操作沉淀成可复用的技能包。它同时提供了终端版、桌面版Pi Desktop和Web端最近的社区热度很高。这篇文章不谈概念主要记录我这些天把Pi从“试玩”推到“日常主力工具”的全过程包括为什么换到它、怎么上手、subagent和skill怎么配置、三端怎么分工、以及我在真实项目里踩过的一些坑。如果你是一个被重复劳动磨得没脾气的独立开发者或者正准备给团队引入一套可落地、可约束的AI编码工作流这篇内容应该能帮你少走不少弯路。1. 从“聊天窗口式的AI”到“能进代码库干活的代理”1.1 我之前用过的AI编码工具各自让我放弃的点先说背景。早先我用的是通用型的对话助手遇到问题就复制报错贴进去它给我一段解释和示例代码。它的优势是知识宽泛什么都能聊两句缺点是它根本不知道我的项目长什么样我贴多少上下文它就只能看多少让我自己挑文件、截长段代码、解释业务背景说得越多它错得越离谱有时候费半天劲还不如自己修。后来也试过集成在IDE里的补全和聊天插件。补全适合写样板代码但对“改一个跨模块的交互逻辑”这种任务基本帮不上忙聊天插件虽然能引用当前文件可一旦任务涉及多个文件、需要跑命令验证就又会退化成“给我一段建议代码你自己粘回去跑”的模式。我要的不是“建议”是“有人把事情办完”。1.2 Pi的定位终端优先但不止终端Pi给我的第一感觉是它把“编码代理”这件事做得非常纯粹你像给同事派活一样给它一个任务它自己会去看代码、改文件、运行命令、汇报结果。它的核心入口是终端用pi命令启动对话也可以直接在命令后面带上任务描述比如pi 查看当前仓库的README和目录结构帮我梳理这个项目主要解决了什么问题输出一份简要架构说明它不只是一个shell工具还配套了Pi Desktop桌面版和Web端。终端版适合快速执行和日常改动桌面版适合对比改动前后的文件差异、拖拽截图、多窗口查看代理执行过程Web端则适合在别的机器上跑长任务或者做演示。1.3 选型逻辑我要的不是“聊天窗口”而是“能扛事的副驾驶”我最终留下来主要还是因为它解决了三个具体问题能自己读代码库。它不依赖我手动贴上下文自己会去找相关文件、看调用关系。这一点对老项目尤其关键很多库和工具类的逻辑埋得很深人肉翻很费时间。能自己跑命令。改完代码它能自己执行测试、自己看报错然后根据报错继续修形成一个“改—跑—修”的闭环而不是把半成品丢给我。有subagent和skill体系。单个代理的上下文和精力有限但多个子代理并行处理就完全是另一个量级而skill机制能让团队沉淀自己的AI工作规范新人上手也能保持一致的产出质量。相比之下那些只能聊天的工具更像“搜索引擎加强版”Pi更像一个可以渐进式培养的项目成员——前提是你愿意分给它一点耐心先把边界和规则定清楚。2. 安装、配置和第一次跑通真实任务别把时间浪费在“hello world”上2.1 安装和环境准备不同系统下的安装方式略有差异但主流方式是通过包管理器安装我这边用的是npm install -g pi-ai/cli安装后先确认版本pi --version然后需要配置模型接入。Pi本身不自带模型它相当于一个调度层需要对接大模型API。在首次启动时它会引导你配置provider和API key我的建议是日常任务用响应速度快的模型省token适合频繁迭代复杂重构或大型代码库分析时切换到推理能力更强的长上下文模型。这些配置写在全局配置里一般位于~/.pi/config.toml我习惯把常用模型和默认参数提前写清楚避免每次初始化都问一遍[model] default fast-model [model.agents] review strong-model [behavior] auto_run_tests true max_diff_chars 20000提示这里配置的是API Key和模型路由。不要在任何公开仓库提交你的配置文件建议用环境变量或系统密钥管理工具来注入。2.2 全局配置与项目级记忆文件Pi支持在项目根目录放一个记忆文件来告诉它这个仓库的基本规则类似给新人看的团队wiki。文件名是AGENTS.md也可以叫pi.md如果两个都存在会合并读取。我强烈建议每个仓库都放一份哪怕只有三行# 项目约定 - 这是一个前后端分离项目前端在web/目录后端在server/目录。 - 后端接口遵循RESTful风格所有新增接口需要补充OpenAPI文档。 - 禁止修改migrations/目录下已发布的迁移文件。 - 提交信息使用 conventional commits 规范。有了这个文件Pi每次进入工作会话都会先读它。这比你在prompt里反复强调规则靠谱得多它更像一种持久化的“团队约定”而不是一次性指令。2.3 第一次实操让它把TODO变成实现我建议第一次尝试别选太简单的“写个冒泡排序”之类的例子因为那根本无法体现代理的真实能力。第一次就直接拿一个你仓库里真实存在的TODO事项来试。我当时指定了一个服务里的遗留方法pi 在 PaymentService 里有一个方法 calculateRefundAmount 标了TODO需要根据完整的退款规则实现它。先去读一下相关测试和上游调用方式然后实现代码并补全测试它做的事情包括定位PaymentService、搜索所有调用方、读取测试文件里的预期行为、补充实现代码、运行相关测试、根据失败反馈修正边界条件。最终给出一份diff总结。整个过程里我只在开始时说了那句话中途没有干预。这个体验非常关键——它告诉你一个合格的编码代理应该完整地走过“理解需求—定位代码—修改实现—验证结果”的闭环。如果某款工具还需要你一步步把相关文件丢给它那它本质上还是聊天窗口。2.4 理解Pi的三种执行模式plan、act、reviewPi内置了几种执行模式第一次用的时候很容易忽略但对后续工作流影响很大plan模式只分析、只出方案不改代码。适合在动手前先理清楚思路尤其是在复杂重构场景下我会先让它输出一份实施计划确认方向没问题再放行。act模式默认模式直接改文件、跑命令、迭代修复。review模式针对指定改动做代码评审输出问题列表和改进建议不改代码。日常使用中我的习惯是大改动先plan小修复直接act涉及合并提交之前用review过一遍。3. subagent和skill单兵模式和小队模式是两个世界3.1 subagent是什么和主对话的区别单个代理最怕什么上下文太长做到后面忘了前面的细节或者是“手里只有一个任务没法并行”。subagent解决的就是这两件事。Pi允许你在主对话中派生出多个独立的子代理每个子代理有自己独立的上下文和任务范围。它可以并行处理多个文件、多类检查然后由主代理汇总结果。和主对话相比subagent更像“临时工”它只接受你分配给它的那一个任务范围它的上下文更聚焦不容易被无关信息干扰它可以并发运行但要注意任务边界不重叠否则可能互相覆盖改动。3.2 我常用的一组subagent编排评审、测试、安全扫描并行跑最典型的例子是代码评审。之前我改完一个模块需要自己先把diff看一遍再跑测试再想想有没有安全隐患。现在我会派一组subagent同时做三件事pi agent spawn review 审查当前工作区未提交的改动重点看事务边界和异常处理是否合理输出问题清单 pi agent spawn test 为本次新增的接口补全单元测试运行测试命令修复失败用例 pi agent spawn security 扫描本次改动涉及的用户输入处理检查是否存在注入、越权和敏感信息泄露风险这三个subagent并行工作最后主代理会汇总三份报告并交叉标注冲突项。比如test代理发现了某个边界测试失败security代理同时发现该边界条件下存在未授权访问的可能——这两个信息放在一起比单独看到任何一份报告都有价值得多。这里有一个重要教训派subagent时任务边界一定要切割清楚。你要是让两个子代理同时去改同一个文件基本上必冲突。我一般按文件、按功能模块、按检查类型分工尽量保证没有重叠。3.3 skill把高频操作固化成技能如果说subagent是临时工那skill就是“标准作业流程”。它的本质是一个指令模板头部用YAML描述名称和用途正文是一段具体的操作流程。Pi执行某个skill时会把它的内容注入上下文引导代理按既定步骤干活。一个最典型的应用场景是“规范化提交信息”。我们团队要求commit message遵循conventional commits规范但人写起来总会有各种自由发挥。于是我写了一个skill--- name: commit description: 生成符合 conventional commits 规范的提交信息 --- 请根据当前工作区的git diff和暂存区状态生成3条可选的提交信息要求 - type只允许使用 feat/fix/refactor/docs/test/chore - subject不超过50个字符 - 正文分条列出主要改动点尽可能使用具体文件或函数名 - 输出格式为type(scope): subject这个skill文件放在~/.pi/skills/commit/SKILL.md。之后只需要在会话里说“用commit技能总结本次改动”它就会严格按这套流程走。测试、写CHANGELOG、做版本对比都可以沉淀成你自己的skill。3.4 从Web导入skill的正确姿势社区里已经有不少人分享现成的skill包Pi的Web端和命令行都支持导入。pi skills install https://example.com/skills/commit-check.md不过我建议大家导入时留个心眼先看三样东西YAML头里的name和description是否清晰避免模糊命名导致调用时不知道哪个该用正文里的指令是否包含危险操作比如有没有要求代理执行rm -rf、修改全局配置、把密钥写入文件之类的行为这类skill不建议导入是否匹配你的技术栈一套为前端项目写的review规则拿到后端仓库里用会产生大量噪音。导入并安装后可以用pi skills list查看已安装的技能列表也可以在项目目录放.pi/skills/来让某个skill只在当前仓库生效。这里呼应一下热搜词里提到的“pi web导入skill”——实际操作其实就是从网页上复制skill原始文件内容或下载链接然后通过命令行安装。我后来更习惯的做法是所有团队核心skill都放进Git仓库管理跟着项目走新人clone下来就能用而不是依赖各自的本地目录否则团队里会出现“你机器上有这个技能但我没有”的割裂状态。4. 终端、桌面、Web三端怎么选我日常的用法分流4.1 三端定位差异Pi的每个端并不是同一套界面的简单换皮它们的定位差别很大终端CLI核心主战场。日常的读代码、改代码、跑测试、派subagent全部在这里完成。它最轻、最快也最适合跟现有终端工作流git、docker、shell脚本融合。桌面版Pi Desktop给你一个可视化窗口来观察代理执行过程。适合复杂任务、多文件diff展示、截图粘贴、对阶段性结果做人工确认。Web端适合在远程环境或临时机器上使用不依赖本地安装也适合在演示、评审时让别人通过浏览器围观代理干活的过程不需要他们本地搭环境。4.2 桌面版适合什么场景我最初觉得桌面版是多余的“终端里能做的事情为什么要开个窗口”后来在做一个跨模块重构时改变了看法。那次任务涉及十几个文件终端里滚动输出完全看不过来。打开Pi Desktop后它会把文件改动以类似IDE的diff视图呈现每一个文件的修改前后都清晰对照我可以随时暂停代理、指出来“这个改动方向不对”它会根据反馈调整后续步骤。另外桌面版支持直接把截图拖进对话。比如遇到一个前端布局问题我可以把页面截图拖给它让它“根据这个截图里的样式定位到对应组件并修复”这种交互在纯终端里实现起来很别扭。我的经验是快速单文件改动留在终端多文件重构和视觉相关的任务打开桌面版。4.3 Web端和“oh my pi”这类社区壳Web端在功能上大约是终端版的八成主要的差别是不能运行本地命令——毕竟它跑在服务器/浏览器里没法直接操作你电脑上的文件系统。所以我一般用它做远程代码库的问答或者在第一台机器上跑长任务然后在另一台电脑上用Web端查看进度。社区里还有不少人把Pi的终端版做了进一步包装比如“oh my pi”这类配置集合和美化主题有点像当年给终端加主题的社区玩法。它本质上是一套预设的别名、主题和skill集合装完之后默认行为更现代、更好看。但我要提醒一句美化和功能增强可以让体验变好但也可能引入额外的配置兼容问题。如果你正在用稳定版本的核心工作流建议先把官方版用顺了再考虑套壳方案。我自己是保持“核心工具最小化”原则能不用插件就不用插件。4.4 我实际的三端分工用了两三周之后我的固定模式基本稳定下来80%的日常修改和代码问答在终端完成因为它跟git、docker、编辑器的衔接最自然15%的重构、批量改文件、视觉排错在桌面版完成可视化diff帮了大忙5%的远程查看和演示在Web端开会的时候把链接丢给同事就能围观不需要大家装环境。三端共用同一套会话同步机制我在终端开着的会话切到桌面版可以接着看这个体验很舒服。5. 真实项目里踩过的三个坑和一个固定工作流5.1 坑一让它改一个小函数它重写了整个文件有一次我让Pi修复一个工具函数里的空指针问题结果它把整个文件按照“更优雅的方式”重写了函数签名没动但内部实现全部换掉甚至连注释风格都变了。代码review时我差点当场崩溃。后来我学会了在派活时明确约束范围。比如pi 修复 utils/date.ts 中 formatDate 函数的空指针问题。只修改该函数内部逻辑不要改动其他函数保持现有代码风格和注释习惯输出时用diff形式列出改动点这就涉及到skill的价值——把“最小变更原则”写进一个项目级skill每次派活都自动带上这个约束比每次手写强多了。5.2 坑二subagent之间互相覆盖改动并行派subagent的时候我一开始没有严格划分边界。测试代理和重构代理同时处理同一个业务模块一个在改文件、一个在跑测试顺手修改了文件格式结果合并时出现大量冲突甚至一度把代码改坏。之后我定的规矩是subagent的任务描述里必须写明涉及哪些文件路径如果两个任务都要读一个公共文件其中一个只读不写必须在描述里注明“只读禁止修改”涉及多个模块的大改动先后让各个subagent完成而不是同时保证文件系统层面的互不干扰。5.3 坑三上下文太长token费用爆炸编码代理用多了最大的开销不是在“写代码”而是在“读代码”。一个几千文件的大仓库里它为了定位一个接口要翻很多文件上下文烧得很快。有次我让它梳理整个微服务模块之间的调用链一个任务烧掉了平时一周的token量。应对策略有几个先做小范围搜索不要一上来就“梳理全项目”先用关键词、文件路径缩小范围用plan模式让它先汇报计划确认它在正确的路径上再让act模式开工拆分成多次会话一次只处理一个子任务避免一个长会话承载太多内容定期清理会话历史Pi支持在长会话里做上下文压缩复杂任务进行到一半时我有意识地主动压缩一次后面继续干。5.4 我的一套标准工作流从需求到MR现在我在团队里的固定工作流是这样的在AGENTS.md里写清楚本次迭代的背景和目标。用plan模式让Pi输出实施方案包括涉及的模块、接口改动、测试计划我先review方案。方案确认后按功能拆任务按文件边界分配subagent并行实现。全部完成后运行全量测试和lint把所有报错丢回给Pi修复。让review模式的subagent做代码评审重点检查事务、异常、安全和边界。review通过后用commit skill生成规范的提交信息人工push后创建MR。这套流程跑下来一个中型功能从需求到MR的时间比以前缩短了大概一半而且很多琐碎的检查项被自动化了我的精力可以放到真正的业务决策上。5.5 给团队的协作约定如果是团队一起用Pi我建议在仓库里建立一个AGENTS.md并强制约束几条红线不允许代理修改的目录比如数据库迁移历史、生成代码、vendor目录明确列出来风格的强制要求比如“禁止使用any类型”、“所有对外接口必须写文档”验证命令让Pi改完代码自己跑对应模块的测试而不是只交代码提交规范跟commit skill配合使用。这些约定的意义不在于限制而在于降低不确定性。代理工具发挥好坏很大程度上取决于你有没有给它清晰边界——这一点和带实习生的逻辑是相通的。6. 别把它只当写代码工具Pi的隐藏玩法和其他“Pi”6.1 用Pi处理DevOps脚本和容器编排很多人把Pi默认当成“写业务代码的”但它的能力范围其实广得多。我用它写过一整套docker compose编排包括服务依赖、健康检查、卷映射也让它生成过GitLab CI流水线配置。对于这类“偏配置、繁琐、规则多”的内容人写很容易漏而代理反而能稳定地输出完整结构。有一次我让它“根据当前仓库的Dockerfile写一份docker-compose.yml包含postgres和redis两个依赖服务并配置健康检查”它直接参考了Dockerfile里暴露的端口和依赖环境变量产出的配置开箱即用。这就是它能读仓库上下文的价值。6.2 用Pi做代码评审和知识库问答代码评审除了前面提到的subagent用法还有一种更省事的方式直接把MR的diff粘贴给它或让它读取然后要求它用review模式输出问题清单。很多低级的错误比如事务没提交、空指针未判、日志重复打印、方法参数用了魔法数字它都能挑出来。人类的真评审精力可以集中到架构层面而不是去抓低级笔误。它还非常适合做“知识库问答”。接手一个没文档的老项目时让它先通读一遍目录结构、模块说明和核心类然后你直接提问“这个项目的库存扣减逻辑在哪个模块、怎么确保并发安全”它会基于读过的代码给出带文件路径的答案比人肉翻代码快得多。6.3 彩蛋同样是“Pi”不同领域说的根本不是一回事因为这个项目我最近在一些技术群里提到“Pi”时发现大家的理解完全分裂数学领域Pi指圆周率π很多人做数值计算、蒙特卡洛模拟时都在折腾它嵌入式领域热词里有“raspberry pi 2040 oled 0.96”这是树莓派PicoRP2040驱动0.96英寸OLED屏幕的小项目这类小屏显示温度、IP、时钟是电子DIY圈子里的常青树电力电子/控制领域热词里的“MMC环流抑制器的pi参数”和“PLL pi控制带宽fb”这里的PI是比例积分控制器是闭环控制里的经典结构做电机控制、并网逆变器的人都天天和它打交道硬件工程师领域热词“si pi”则是信号完整性Signal Integrity和电源完整性Power Integrity的缩写做高速PCB的人对这个再熟悉不过AI编码工具领域才是我们今天聊的Pi coding agent。每次初聊都得先确认一下“你说的Pi是哪个Pi”这种多义性还挺有意思的。我甚至试过在一台树莓派上安装Pi coding agent去写一个模拟π的计算程序——套娃套到极致。6.4 一个完整副驾驶日常的片段最后分享一个我印象很深的工作片段。那天下午接到一个临时需求给现有的消息推送服务增加“定时发送”能力。我打开终端输入pi 阅读消息推送服务的整体结构和定时任务模块的现状输出一个增加定时发送功能的实施方案它花了大约一分钟输出方案从数据库增加调度时间字段、到定时扫描待发送消息、再到状态机流转连失败重试策略都给了。我确认方案后它开始实现中途跑测试失败两次自己修复后通过。等到下班前MR已经躺在待评审列表里附带的review报告列出了两个它自己建议优化的点。那一刻我确实觉得工具形态的进化比我想象中快得多。但我也很清楚它能干到这个程度靠的不只是模型变强了更是那套能让代理“读仓库、跑命令、有边界、可沉淀”的工作流设计。工具给你的是可能性真正让效率落地的是你怎么给它立规矩。如果你也打算把Pi纳入日常开发我的建议是从一个小型真实任务开始先写一份三行的AGENTS.md再把它跑通一个完整的“读代码—改代码—跑测试”闭环然后逐步加上skill和subagent。别急着一次性上全套让代理先在你熟悉的项目里建立信任再慢慢扩大它的权限和任务范围这个节奏是最稳的。 
长河君 · 2026/10/4 8:20:09 · 阅读 1.2k Pi编码代理实战：从试玩到日常主力工具
先说个我最近的感受电脑里的AI助手我们用了大概不到半年从最初只在网页上聊聊天、问问题到后来慢慢让它帮忙改代码、写正则、补单测再到最近这一个月我真的开始把一整块需求丢给它让它自己翻代码库、拆任务、跑验证。这中间的分水岭就是我开始认真使用Pi coding agent这类真正意义上的“编码代理”而不只是“对话机器人”。Pi是什么简单说它是一个跑在终端里的AI程序员能读你的仓库结构、定位相关文件、跨文件修改代码、执行测试命令来验证结果还能把一个大任务拆给多个子代理subagent并行处理并且通过skill机制把高频操作沉淀成可复用的技能包。它同时提供了终端版、桌面版Pi Desktop和Web端最近的社区热度很高。这篇文章不谈概念主要记录我这些天把Pi从“试玩”推到“日常主力工具”的全过程包括为什么换到它、怎么上手、subagent和skill怎么配置、三端怎么分工、以及我在真实项目里踩过的一些坑。如果你是一个被重复劳动磨得没脾气的独立开发者或者正准备给团队引入一套可落地、可约束的AI编码工作流这篇内容应该能帮你少走不少弯路。1. 从“聊天窗口式的AI”到“能进代码库干活的代理”1.1 我之前用过的AI编码工具各自让我放弃的点先说背景。早先我用的是通用型的对话助手遇到问题就复制报错贴进去它给我一段解释和示例代码。它的优势是知识宽泛什么都能聊两句缺点是它根本不知道我的项目长什么样我贴多少上下文它就只能看多少让我自己挑文件、截长段代码、解释业务背景说得越多它错得越离谱有时候费半天劲还不如自己修。后来也试过集成在IDE里的补全和聊天插件。补全适合写样板代码但对“改一个跨模块的交互逻辑”这种任务基本帮不上忙聊天插件虽然能引用当前文件可一旦任务涉及多个文件、需要跑命令验证就又会退化成“给我一段建议代码你自己粘回去跑”的模式。我要的不是“建议”是“有人把事情办完”。1.2 Pi的定位终端优先但不止终端Pi给我的第一感觉是它把“编码代理”这件事做得非常纯粹你像给同事派活一样给它一个任务它自己会去看代码、改文件、运行命令、汇报结果。它的核心入口是终端用pi命令启动对话也可以直接在命令后面带上任务描述比如pi 查看当前仓库的README和目录结构帮我梳理这个项目主要解决了什么问题输出一份简要架构说明它不只是一个shell工具还配套了Pi Desktop桌面版和Web端。终端版适合快速执行和日常改动桌面版适合对比改动前后的文件差异、拖拽截图、多窗口查看代理执行过程Web端则适合在别的机器上跑长任务或者做演示。1.3 选型逻辑我要的不是“聊天窗口”而是“能扛事的副驾驶”我最终留下来主要还是因为它解决了三个具体问题能自己读代码库。它不依赖我手动贴上下文自己会去找相关文件、看调用关系。这一点对老项目尤其关键很多库和工具类的逻辑埋得很深人肉翻很费时间。能自己跑命令。改完代码它能自己执行测试、自己看报错然后根据报错继续修形成一个“改—跑—修”的闭环而不是把半成品丢给我。有subagent和skill体系。单个代理的上下文和精力有限但多个子代理并行处理就完全是另一个量级而skill机制能让团队沉淀自己的AI工作规范新人上手也能保持一致的产出质量。相比之下那些只能聊天的工具更像“搜索引擎加强版”Pi更像一个可以渐进式培养的项目成员——前提是你愿意分给它一点耐心先把边界和规则定清楚。2. 安装、配置和第一次跑通真实任务别把时间浪费在“hello world”上2.1 安装和环境准备不同系统下的安装方式略有差异但主流方式是通过包管理器安装我这边用的是npm install -g pi-ai/cli安装后先确认版本pi --version然后需要配置模型接入。Pi本身不自带模型它相当于一个调度层需要对接大模型API。在首次启动时它会引导你配置provider和API key我的建议是日常任务用响应速度快的模型省token适合频繁迭代复杂重构或大型代码库分析时切换到推理能力更强的长上下文模型。这些配置写在全局配置里一般位于~/.pi/config.toml我习惯把常用模型和默认参数提前写清楚避免每次初始化都问一遍[model] default fast-model [model.agents] review strong-model [behavior] auto_run_tests true max_diff_chars 20000提示这里配置的是API Key和模型路由。不要在任何公开仓库提交你的配置文件建议用环境变量或系统密钥管理工具来注入。2.2 全局配置与项目级记忆文件Pi支持在项目根目录放一个记忆文件来告诉它这个仓库的基本规则类似给新人看的团队wiki。文件名是AGENTS.md也可以叫pi.md如果两个都存在会合并读取。我强烈建议每个仓库都放一份哪怕只有三行# 项目约定 - 这是一个前后端分离项目前端在web/目录后端在server/目录。 - 后端接口遵循RESTful风格所有新增接口需要补充OpenAPI文档。 - 禁止修改migrations/目录下已发布的迁移文件。 - 提交信息使用 conventional commits 规范。有了这个文件Pi每次进入工作会话都会先读它。这比你在prompt里反复强调规则靠谱得多它更像一种持久化的“团队约定”而不是一次性指令。2.3 第一次实操让它把TODO变成实现我建议第一次尝试别选太简单的“写个冒泡排序”之类的例子因为那根本无法体现代理的真实能力。第一次就直接拿一个你仓库里真实存在的TODO事项来试。我当时指定了一个服务里的遗留方法pi 在 PaymentService 里有一个方法 calculateRefundAmount 标了TODO需要根据完整的退款规则实现它。先去读一下相关测试和上游调用方式然后实现代码并补全测试它做的事情包括定位PaymentService、搜索所有调用方、读取测试文件里的预期行为、补充实现代码、运行相关测试、根据失败反馈修正边界条件。最终给出一份diff总结。整个过程里我只在开始时说了那句话中途没有干预。这个体验非常关键——它告诉你一个合格的编码代理应该完整地走过“理解需求—定位代码—修改实现—验证结果”的闭环。如果某款工具还需要你一步步把相关文件丢给它那它本质上还是聊天窗口。2.4 理解Pi的三种执行模式plan、act、reviewPi内置了几种执行模式第一次用的时候很容易忽略但对后续工作流影响很大plan模式只分析、只出方案不改代码。适合在动手前先理清楚思路尤其是在复杂重构场景下我会先让它输出一份实施计划确认方向没问题再放行。act模式默认模式直接改文件、跑命令、迭代修复。review模式针对指定改动做代码评审输出问题列表和改进建议不改代码。日常使用中我的习惯是大改动先plan小修复直接act涉及合并提交之前用review过一遍。3. subagent和skill单兵模式和小队模式是两个世界3.1 subagent是什么和主对话的区别单个代理最怕什么上下文太长做到后面忘了前面的细节或者是“手里只有一个任务没法并行”。subagent解决的就是这两件事。Pi允许你在主对话中派生出多个独立的子代理每个子代理有自己独立的上下文和任务范围。它可以并行处理多个文件、多类检查然后由主代理汇总结果。和主对话相比subagent更像“临时工”它只接受你分配给它的那一个任务范围它的上下文更聚焦不容易被无关信息干扰它可以并发运行但要注意任务边界不重叠否则可能互相覆盖改动。3.2 我常用的一组subagent编排评审、测试、安全扫描并行跑最典型的例子是代码评审。之前我改完一个模块需要自己先把diff看一遍再跑测试再想想有没有安全隐患。现在我会派一组subagent同时做三件事pi agent spawn review 审查当前工作区未提交的改动重点看事务边界和异常处理是否合理输出问题清单 pi agent spawn test 为本次新增的接口补全单元测试运行测试命令修复失败用例 pi agent spawn security 扫描本次改动涉及的用户输入处理检查是否存在注入、越权和敏感信息泄露风险这三个subagent并行工作最后主代理会汇总三份报告并交叉标注冲突项。比如test代理发现了某个边界测试失败security代理同时发现该边界条件下存在未授权访问的可能——这两个信息放在一起比单独看到任何一份报告都有价值得多。这里有一个重要教训派subagent时任务边界一定要切割清楚。你要是让两个子代理同时去改同一个文件基本上必冲突。我一般按文件、按功能模块、按检查类型分工尽量保证没有重叠。3.3 skill把高频操作固化成技能如果说subagent是临时工那skill就是“标准作业流程”。它的本质是一个指令模板头部用YAML描述名称和用途正文是一段具体的操作流程。Pi执行某个skill时会把它的内容注入上下文引导代理按既定步骤干活。一个最典型的应用场景是“规范化提交信息”。我们团队要求commit message遵循conventional commits规范但人写起来总会有各种自由发挥。于是我写了一个skill--- name: commit description: 生成符合 conventional commits 规范的提交信息 --- 请根据当前工作区的git diff和暂存区状态生成3条可选的提交信息要求 - type只允许使用 feat/fix/refactor/docs/test/chore - subject不超过50个字符 - 正文分条列出主要改动点尽可能使用具体文件或函数名 - 输出格式为type(scope): subject这个skill文件放在~/.pi/skills/commit/SKILL.md。之后只需要在会话里说“用commit技能总结本次改动”它就会严格按这套流程走。测试、写CHANGELOG、做版本对比都可以沉淀成你自己的skill。3.4 从Web导入skill的正确姿势社区里已经有不少人分享现成的skill包Pi的Web端和命令行都支持导入。pi skills install https://example.com/skills/commit-check.md不过我建议大家导入时留个心眼先看三样东西YAML头里的name和description是否清晰避免模糊命名导致调用时不知道哪个该用正文里的指令是否包含危险操作比如有没有要求代理执行rm -rf、修改全局配置、把密钥写入文件之类的行为这类skill不建议导入是否匹配你的技术栈一套为前端项目写的review规则拿到后端仓库里用会产生大量噪音。导入并安装后可以用pi skills list查看已安装的技能列表也可以在项目目录放.pi/skills/来让某个skill只在当前仓库生效。这里呼应一下热搜词里提到的“pi web导入skill”——实际操作其实就是从网页上复制skill原始文件内容或下载链接然后通过命令行安装。我后来更习惯的做法是所有团队核心skill都放进Git仓库管理跟着项目走新人clone下来就能用而不是依赖各自的本地目录否则团队里会出现“你机器上有这个技能但我没有”的割裂状态。4. 终端、桌面、Web三端怎么选我日常的用法分流4.1 三端定位差异Pi的每个端并不是同一套界面的简单换皮它们的定位差别很大终端CLI核心主战场。日常的读代码、改代码、跑测试、派subagent全部在这里完成。它最轻、最快也最适合跟现有终端工作流git、docker、shell脚本融合。桌面版Pi Desktop给你一个可视化窗口来观察代理执行过程。适合复杂任务、多文件diff展示、截图粘贴、对阶段性结果做人工确认。Web端适合在远程环境或临时机器上使用不依赖本地安装也适合在演示、评审时让别人通过浏览器围观代理干活的过程不需要他们本地搭环境。4.2 桌面版适合什么场景我最初觉得桌面版是多余的“终端里能做的事情为什么要开个窗口”后来在做一个跨模块重构时改变了看法。那次任务涉及十几个文件终端里滚动输出完全看不过来。打开Pi Desktop后它会把文件改动以类似IDE的diff视图呈现每一个文件的修改前后都清晰对照我可以随时暂停代理、指出来“这个改动方向不对”它会根据反馈调整后续步骤。另外桌面版支持直接把截图拖进对话。比如遇到一个前端布局问题我可以把页面截图拖给它让它“根据这个截图里的样式定位到对应组件并修复”这种交互在纯终端里实现起来很别扭。我的经验是快速单文件改动留在终端多文件重构和视觉相关的任务打开桌面版。4.3 Web端和“oh my pi”这类社区壳Web端在功能上大约是终端版的八成主要的差别是不能运行本地命令——毕竟它跑在服务器/浏览器里没法直接操作你电脑上的文件系统。所以我一般用它做远程代码库的问答或者在第一台机器上跑长任务然后在另一台电脑上用Web端查看进度。社区里还有不少人把Pi的终端版做了进一步包装比如“oh my pi”这类配置集合和美化主题有点像当年给终端加主题的社区玩法。它本质上是一套预设的别名、主题和skill集合装完之后默认行为更现代、更好看。但我要提醒一句美化和功能增强可以让体验变好但也可能引入额外的配置兼容问题。如果你正在用稳定版本的核心工作流建议先把官方版用顺了再考虑套壳方案。我自己是保持“核心工具最小化”原则能不用插件就不用插件。4.4 我实际的三端分工用了两三周之后我的固定模式基本稳定下来80%的日常修改和代码问答在终端完成因为它跟git、docker、编辑器的衔接最自然15%的重构、批量改文件、视觉排错在桌面版完成可视化diff帮了大忙5%的远程查看和演示在Web端开会的时候把链接丢给同事就能围观不需要大家装环境。三端共用同一套会话同步机制我在终端开着的会话切到桌面版可以接着看这个体验很舒服。5. 真实项目里踩过的三个坑和一个固定工作流5.1 坑一让它改一个小函数它重写了整个文件有一次我让Pi修复一个工具函数里的空指针问题结果它把整个文件按照“更优雅的方式”重写了函数签名没动但内部实现全部换掉甚至连注释风格都变了。代码review时我差点当场崩溃。后来我学会了在派活时明确约束范围。比如pi 修复 utils/date.ts 中 formatDate 函数的空指针问题。只修改该函数内部逻辑不要改动其他函数保持现有代码风格和注释习惯输出时用diff形式列出改动点这就涉及到skill的价值——把“最小变更原则”写进一个项目级skill每次派活都自动带上这个约束比每次手写强多了。5.2 坑二subagent之间互相覆盖改动并行派subagent的时候我一开始没有严格划分边界。测试代理和重构代理同时处理同一个业务模块一个在改文件、一个在跑测试顺手修改了文件格式结果合并时出现大量冲突甚至一度把代码改坏。之后我定的规矩是subagent的任务描述里必须写明涉及哪些文件路径如果两个任务都要读一个公共文件其中一个只读不写必须在描述里注明“只读禁止修改”涉及多个模块的大改动先后让各个subagent完成而不是同时保证文件系统层面的互不干扰。5.3 坑三上下文太长token费用爆炸编码代理用多了最大的开销不是在“写代码”而是在“读代码”。一个几千文件的大仓库里它为了定位一个接口要翻很多文件上下文烧得很快。有次我让它梳理整个微服务模块之间的调用链一个任务烧掉了平时一周的token量。应对策略有几个先做小范围搜索不要一上来就“梳理全项目”先用关键词、文件路径缩小范围用plan模式让它先汇报计划确认它在正确的路径上再让act模式开工拆分成多次会话一次只处理一个子任务避免一个长会话承载太多内容定期清理会话历史Pi支持在长会话里做上下文压缩复杂任务进行到一半时我有意识地主动压缩一次后面继续干。5.4 我的一套标准工作流从需求到MR现在我在团队里的固定工作流是这样的在AGENTS.md里写清楚本次迭代的背景和目标。用plan模式让Pi输出实施方案包括涉及的模块、接口改动、测试计划我先review方案。方案确认后按功能拆任务按文件边界分配subagent并行实现。全部完成后运行全量测试和lint把所有报错丢回给Pi修复。让review模式的subagent做代码评审重点检查事务、异常、安全和边界。review通过后用commit skill生成规范的提交信息人工push后创建MR。这套流程跑下来一个中型功能从需求到MR的时间比以前缩短了大概一半而且很多琐碎的检查项被自动化了我的精力可以放到真正的业务决策上。5.5 给团队的协作约定如果是团队一起用Pi我建议在仓库里建立一个AGENTS.md并强制约束几条红线不允许代理修改的目录比如数据库迁移历史、生成代码、vendor目录明确列出来风格的强制要求比如“禁止使用any类型”、“所有对外接口必须写文档”验证命令让Pi改完代码自己跑对应模块的测试而不是只交代码提交规范跟commit skill配合使用。这些约定的意义不在于限制而在于降低不确定性。代理工具发挥好坏很大程度上取决于你有没有给它清晰边界——这一点和带实习生的逻辑是相通的。6. 别把它只当写代码工具Pi的隐藏玩法和其他“Pi”6.1 用Pi处理DevOps脚本和容器编排很多人把Pi默认当成“写业务代码的”但它的能力范围其实广得多。我用它写过一整套docker compose编排包括服务依赖、健康检查、卷映射也让它生成过GitLab CI流水线配置。对于这类“偏配置、繁琐、规则多”的内容人写很容易漏而代理反而能稳定地输出完整结构。有一次我让它“根据当前仓库的Dockerfile写一份docker-compose.yml包含postgres和redis两个依赖服务并配置健康检查”它直接参考了Dockerfile里暴露的端口和依赖环境变量产出的配置开箱即用。这就是它能读仓库上下文的价值。6.2 用Pi做代码评审和知识库问答代码评审除了前面提到的subagent用法还有一种更省事的方式直接把MR的diff粘贴给它或让它读取然后要求它用review模式输出问题清单。很多低级的错误比如事务没提交、空指针未判、日志重复打印、方法参数用了魔法数字它都能挑出来。人类的真评审精力可以集中到架构层面而不是去抓低级笔误。它还非常适合做“知识库问答”。接手一个没文档的老项目时让它先通读一遍目录结构、模块说明和核心类然后你直接提问“这个项目的库存扣减逻辑在哪个模块、怎么确保并发安全”它会基于读过的代码给出带文件路径的答案比人肉翻代码快得多。6.3 彩蛋同样是“Pi”不同领域说的根本不是一回事因为这个项目我最近在一些技术群里提到“Pi”时发现大家的理解完全分裂数学领域Pi指圆周率π很多人做数值计算、蒙特卡洛模拟时都在折腾它嵌入式领域热词里有“raspberry pi 2040 oled 0.96”这是树莓派PicoRP2040驱动0.96英寸OLED屏幕的小项目这类小屏显示温度、IP、时钟是电子DIY圈子里的常青树电力电子/控制领域热词里的“MMC环流抑制器的pi参数”和“PLL pi控制带宽fb”这里的PI是比例积分控制器是闭环控制里的经典结构做电机控制、并网逆变器的人都天天和它打交道硬件工程师领域热词“si pi”则是信号完整性Signal Integrity和电源完整性Power Integrity的缩写做高速PCB的人对这个再熟悉不过AI编码工具领域才是我们今天聊的Pi coding agent。每次初聊都得先确认一下“你说的Pi是哪个Pi”这种多义性还挺有意思的。我甚至试过在一台树莓派上安装Pi coding agent去写一个模拟π的计算程序——套娃套到极致。6.4 一个完整副驾驶日常的片段最后分享一个我印象很深的工作片段。那天下午接到一个临时需求给现有的消息推送服务增加“定时发送”能力。我打开终端输入pi 阅读消息推送服务的整体结构和定时任务模块的现状输出一个增加定时发送功能的实施方案它花了大约一分钟输出方案从数据库增加调度时间字段、到定时扫描待发送消息、再到状态机流转连失败重试策略都给了。我确认方案后它开始实现中途跑测试失败两次自己修复后通过。等到下班前MR已经躺在待评审列表里附带的review报告列出了两个它自己建议优化的点。那一刻我确实觉得工具形态的进化比我想象中快得多。但我也很清楚它能干到这个程度靠的不只是模型变强了更是那套能让代理“读仓库、跑命令、有边界、可沉淀”的工作流设计。工具给你的是可能性真正让效率落地的是你怎么给它立规矩。如果你也打算把Pi纳入日常开发我的建议是从一个小型真实任务开始先写一份三行的AGENTS.md再把它跑通一个完整的“读代码—改代码—跑测试”闭环然后逐步加上skill和subagent。别急着一次性上全套让代理先在你熟悉的项目里建立信任再慢慢扩大它的权限和任务范围这个节奏是最稳的。