企业官网建设流程全解析

先说个我最近的感受：电脑里的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、review

Pi内置了几种执行模式，第一次用的时候很容易忽略，但对后续工作流影响很大：

• 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）

现在我在团队里的固定工作流是这样的：

1. 在AGENTS.md里写清楚本次迭代的背景和目标。
2. 用plan模式让Pi输出实施方案，包括涉及的模块、接口改动、测试计划，我先review方案。
3. 方案确认后，按功能拆任务，按文件边界分配subagent并行实现。
4. 全部完成后，运行全量测试和lint，把所有报错丢回给Pi修复。
5. 让review模式的subagent做代码评审，重点检查事务、异常、安全和边界。
6. 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”，这是树莓派Pico（RP2040）驱动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。别急着一次性上全套，让代理先在你熟悉的项目里建立信任，再慢慢扩大它的权限和任务范围，这个节奏是最稳的。