企业官网建设流程全解析

上个月我接了个需求，原始描述只有两句话：做一个内部工具，用户能登录、能提交表单、能看历史记录。看着需求简单，实际从零到能跑通用了整整两周。整个开发过程我没写几行代码，全程靠 pi agent 在终端里驱动，从项目初始化、建表、写接口、调页面，到测试、修 bug、补文档，一步步把“毛坯房”装成了能住人的房子。这篇文章不打算写成一个标准教程，更像一份装修踩坑记录：哪些坑我替你趟过了，哪些决策回头想想是错的，哪些习惯如果从一开始就有，能少熬好几个夜。

如果你是第一次听说 pi agent，或者刚下载完还没想清楚拿它干什么，又或者你已经用它写过几个 demo 但一碰真实项目就各种不对劲，这篇应该能帮你省点时间。我尽量把命令、配置和踩坑现场都还原出来，你可以照着走，也可以拿来当避坑清单。

1. 开工之前：认清 pi agent 能干什么，别把它当魔法棒

1.1 pi agent 到底是个什么东西

先对齐一下概念。pi agent 是一个跑在终端里的编程代理（coding agent），不是 IDE 插件，也不是那种聊聊天帮你补全代码的 AI 助手。你把任务用自然语言描述给它，它会自己去读项目文件、分析代码结构、修改文件、执行命令、看运行结果，再根据结果决定下一步做什么。整个过程是一个“理解—行动—观察—再行动”的循环，而不是一次性给你吐一段代码就完事。

我第一次用的时候最大的误判是：以为它是个更聪明的 ChatGPT，把需求甩过去等结果就行。实际不是。它更像一个刚入职、学习能力很强但缺乏项目背景的实习生。你得给它项目上下文，告诉它技术栈是什么、代码放在哪、要做到什么程度、哪些约束不能碰，它才能干出像样的活。你要是只说“帮我做个登录功能”，它大概率能写出来，但可能用了你没打算用的框架，或者把整个项目结构都改了。

跟 Copilot 这类补全工具比，pi agent 的优势在于它能处理“一整块任务”。补全工具是你写一行它补三行，整体架构还是你脑子里的；pi agent 是你把“做一个带分页的用户列表页”整个任务扔出去，它自己去建组件、写接口、处理 loading 状态、把样式调好。劣势也很明显：它干的活越多，越需要你把控方向，否则装修到一半发现墙砌错位置了，返工成本比从头写还高。

1.2 毛坯房比喻：这个工具适合干什么

我把用 pi agent 做项目比作毛坯房装修，是认真想过的。毛坯房的特点是：墙是墙、地是地，水电管线都在，但没有任何居住功能。一个空目录加一个 git 仓库就是数字世界的毛坯房。pi agent 负责的是装修，但设计图纸、预算上限、验收标准，都得你自己定。你不定，它就按自己理解的默认值来，最后交付的可能是你根本没想要的风格。

那它适合用来干什么？

• 适合：从零搭一个 CRUD 应用、写后端接口、做数据迁移脚本、写单元测试、重构一个模块、补充文档和注释。
• 适合：你有明确技术栈和经验，但不想浪费时间在重复性编码上，想把想法快速落地成可运行的原型。
• 不适合：你对需求都还没想清楚，指望 agent 帮你把需求也一并想了。它不是产品经理。
• 不适合：项目极其冷门、依赖全是小众库、网上资料稀少。agent 的训练数据里没有足够的样本，它只能瞎猜，然后你帮它擦屁股。

我踩的第一个坑就是把一个“还没想清楚”的需求直接扔给 pi agent。结果它给我设计了一个带角色权限、多租户、消息通知的系统，而我只想要一个能记录“今天做了什么”的表格。所以现在我的习惯是：动工之前，先把需求在纸上捋一遍，哪怕只是几行要点，也要让需求边界清清楚楚。

1.3 装车清单：环境准备与最小化验证

开工之前先把工具链备齐。我是 macOS 环境，用的终端是 iTerm2，shell 是 zsh。pi agent 安装本身不复杂，去官网或者 GitHub releases 页面下载对应平台的安装包或安装脚本，按 README 里的说明装就行。如果你用的是 Windows，建议优先考虑 WSL2 环境，别直接在 PowerShell 里硬扛，很多路径、权限和脚本兼容问题在 WSL 里会少很多。

装完之后别急着上大项目，先做一个最小化验证，确认三件事：

1. pi agent 能正常启动，能读取当前目录下的文件。
2. 它能在项目目录里新建文件、修改文件。
3. 它能在终端里执行命令并读到输出。

我当时的验证方式很原始：在一个空目录里，让 pi agent 初始化一个 Node.js 项目，创建 index.js，在控制台打印 Hello World，然后运行它。如果这一条链路能跑通，说明它的“读取—修改—执行—观察”闭环是正常的，可以开工了。如果连这个都跑不通，先别急着排查业务问题，把环境问题解决干净再说。

注意：pi agent 的版本迭代很快，不同版本在参数、权限配置上可能有差异。我下面涉及的命令和配置项，在不同版本里可能略有出入，以你当前使用的官方文档为准。

2. 水电进场：项目初始化与工程规范的坑

2.1 别让 agent 自己猜技术栈

毛坯房装修的第一步不是刷墙，是定水电点位。项目的第一步也不是写功能，是定技术栈和目录结构。这一步如果交给 pi agent 自由发挥，基本等于把装修风格的决定权交给了一个没见过你家的包工头。

我第一个项目就是这么翻车的。我告诉它“做一个待办事项应用”，它自作主张选了个 Express + SQLite 的组合。不能说错，但这个选择意味着我后续得手动维护原生 SQL、自己处理数据库连接，而我想用的其实是一个带 ORM、带自动迁移的框架。等发现的时候，基础代码已经写了一千多行，推倒重来又舍不得。

后来我学乖了：在项目根目录放一个 AGENTS.md 文件，把关键决策写清楚。这相当于给 pi agent 的一份“项目说明书”。每次它开始干活之前，我先让它读一遍这个文件。文件里我一般写这些内容：

# 技术栈 - 后端：Node.js 20 + Fastify + Prisma + PostgreSQL - 前端：React 18 + Vite + Tailwind - 禁止引入未在 package.json 中声明的依赖 # 目录结构 - src/api 路由和控制器 - src/services 业务逻辑 - src/models 数据模型 - tests 测试文件，与 src 结构对应 # 代码风格 - TypeScript 严格模式 - 函数命名使用驼峰，组件命名使用 PascalCase - 错误处理统一抛 HttpError，由全局中间件捕获 # 约束 - 不修改 src/api 之外的文件来实现业务功能 - 所有数据库变更必须通过 Prisma migration

这个文件不需要写得多长，但必须把“不能动的底线”和“必须遵守的规范”写清楚。pi agent 是服从性很高的工具，你给它明确的规则，它就会照做；你不给，它就会自己发明规则。

2.2 依赖拉不下来，先分清是网络问题还是配置问题

项目初始化的第二个坑出现在拉依赖环节。npm install 跑了十几分钟还在转圈，最后报一堆 ETIMEDOUT。当时我第一反应是网络问题，换了几个公共 npm 镜像也没根本解决。折腾半天发现，pnpm 的全局存储路径配置得不对，导致它在反复重新下载同一个包。

这个坑给我的教训是：遇到依赖安装慢，先别忙着换源，按顺序排查三层：

1. 包管理器本身配置是否正确（缓存路径、存储路径、registry 地址）。
2. 是否存在版本冲突，导致包管理器在反复解析依赖树。
3. 网络链路是否真的慢，用小体积包单独测一次安装耗时。

用一个临时目录验证最直接：新建空目录，执行 npm install lodash，如果秒过，说明基础链路是通的；如果也卡死，那才是网络层面的问题，需要配置更稳定的镜像源或调整超时参数。这个排查顺序能避免在错误的方向上浪费大量时间。

另外提一句，pi agent 在拉依赖失败后的第一反应往往是“重试”。它不会主动去分析是不是源的问题，也不会去看配置。所以你最好在 AGENTS.md 里写一条：遇到依赖安装失败，先检查 registry 配置和网络，不要盲目重试。否则你会看到它反复执行同一条命令，像个复读机。

2.3 建仓打 tag：任何时候都能回退到毛坯状态

装修最怕什么？最怕改到一半发现方向错了，想回到动工之前，结果墙已经拆了。代码项目也一样，所以我强烈建议在 pi agent 第一次动手之前，先初始化 git 仓库并打一个 tag，比如 v0.0.0-init。

这个操作本身很简单，但它给了你一个“时间机器”。pi agent 改代码的速度非常快，快到你反应不过来它已经把某个文件改成了你不认识的样子。有 tag 在手，随时可以 git reset --hard 回到初始状态，重新下指令再让它干。没有这个基线，你只能靠 Ctrl+Z 或者凭记忆手动还原，效率极低且容易遗漏。

我还习惯在每次阶段性任务完成之后打一个 tag 或至少 commit 一次。pi agent 执行的是一连串操作，我们要的是“每一步都可回退”，而不是“最后成功了一次”。这一步在我的整个项目过程中帮了大忙，至少三次在改动失控后，我都能干净利落地回到上一个稳定点。

3. 硬装阶段：核心功能开发与 Agent 工作流的真实用法

3.1 任务描述的四要素：目标、约束、验收、参考

等环境就绪、规范确立之后，才进入真正的硬装阶段——让 pi agent 开始写业务代码。这个阶段最关键的技能，是怎么把需求翻译成它听得懂的任务描述。

我刚开始给 pi agent 下任务的时候，习惯用口语描述：“帮我写一个用户注册接口，手机号验证码那种。”结果它给我写了个用邮箱注册的接口，验证码是假的，只是 console.log 打出来。不能说它写错了，只能说我没说清楚。

后来我把任务描述固定成四个部分：目标（做什么）、约束（在哪些限制下做）、验收（怎么算完成）、参考（可以参考哪些文件或接口风格）。写成一个模板，大概是这样的：

目标：在 src/api/auth.ts 中新增一个注册接口 POST /api/register 约束： - 使用 Prisma 操作数据库 - 手机号必须是 11 位数字，校验失败返回 400 - 密码使用 bcrypt 加密存储 - 不修改 src/models 下已有的模型文件 验收： - 运行 npm test 中 auth 相关测试全部通过 - 使用 curl 请求接口，传合法参数返回 201，非法手机号返回 400 参考： - 参照 src/api/login.ts 的现有代码风格

这种描述方式看起来很啰嗦，但它能显著减少 pi agent 的“自由发挥空间”。它自由发挥的空间越小，你后面返工的成本就越低。说白了就是把装修图纸画清楚，再让工人动工。

3.2 上下文管理：别让 agent 忘记它自己改过什么

pi agent 能处理的任务长度是有限的，越长的对话上下文越容易出问题。我在项目进行到第二周时发现，pi agent 开始“失忆”——它明明十分钟前改过一个函数，重新提问时却说没有改过，或者给出了一个基于旧代码的建议。

这个问题的根源是上下文窗口被撑满了，前面的信息被截断或丢弃。解决思路不是去增大窗口，而是把关键信息“固化”到文件里。

我的做法是：在项目里维护一个 PROGRESS.md 文件，记录每天完成了哪些模块、改过哪些文件、下一步打算做什么。每次让 pi agent 开始新任务之前，先让它读这个文件。这样即使会话断掉、从头开一个新会话，它也能通过文件快速恢复上下文。

还有一个习惯值得养成：一个会话只干一件事。想让它加接口，就只聊加接口；想让它在同一批文件里改样式，另开新会话。混在一起聊，不仅上下文消耗快，还容易让 agent 产生任务优先级误判，把 A 任务做到一半突然去干 B 任务。

3.3 人工审查：agent 写代码，人做验收

这是我最想强调的一点：pi agent 写出来的代码，本质上是初稿。它可能功能正确，但不代表风格良好、边界处理完备、没有隐藏问题。你必须是那个“最后拍板的人”。

我建立了一个简单的代码审查清单，每次 agent 完成一个任务，我不急着让它做下一个，先对照清单检查：

拿实际的例子说。有一次让 pi agent 写一个文件上传接口，它在能跑通的路径上一切正常，但只要上传空文件就报 500，而且没捕获错误就直接抛给前端。功能“能跑”，但离“能用”差远了。如果没有审查清单，这种问题会一直藏在代码里，直到线上出事故。

提示：审查不是重新写一遍，而是像验收精装房一样，逐项对照标准看。发现问题就让 agent 改，直到满足清单为止。人盯结果，agent 盯实现，角色要分清楚。

3.4 实测记录：一个增删改查模块的全过程复盘

写点具体的。我项目里有个“项目管理”模块，要求很基础：项目列表、新建项目、编辑项目名称、删除项目。听起来毫无难度，但这是最能体现 agent 工作流价值的场景，因为逻辑简单、链路完整，可以完整观察它从接到任务到交付的全过程。

我下发的任务描述包括：技术栈约束（Prisma + Fastify）、路由路径（/api/projects）、字段定义（id、name、createdAt、updatedAt）、验证规则（name 必填且不超过 50 字）、验收标准（相关测试通过）。

第一轮，它很快生成了 Prisma model 和迁移文件，然后写好了路由和 service。看起来不错的初稿，但我在审查时发现，新增和编辑接口没有做 name 长度校验，直接入库。我把这个反馈给它，让它补上。

第二轮，它补上了校验，但又引入了一个新问题：删除接口在项目不存在时返回 404 的逻辑写错了，写成了返回 success。我继续反馈，让它修正。

第三轮，功能逻辑全部正确了，但它又往代码里塞了一堆没用的注释。我追加了一条规范：“不要添加无意义的注释，代码本身要表达意图。”它把注释清干净了。这时候测试也过了，我才算验收通过。

整个过程用了不到四十分钟，其中有十分钟是它在跑测试。如果是我自己写，不算测试时间，大概也得两三个小时。这就是 agent 的价值所在——但不是“完全托管”的价值，而是“你出图纸、它砌墙、你验收”的分工价值。

4. 软装阶段：调试、测试与迭代的踩坑实录

4.1 测试是装修图纸，先画图纸再动工

硬装结束了，房子能住了，但还不能急着入住，得做竣工验收——在软件项目里就是测试。这个环节的坑在于：让 pi agent“顺便写个测试”和“先写测试再做功能”，效果天差地别。

我最早是让 agent 先写功能再补测试。结果是：测试确实写了，但都是那种“断言代码能运行”的空壳测试，覆盖率倒是好看，一点实际问题都查不出来。因为 agent 写功能时它知道代码内部逻辑，写测试时会不自觉地避开自己没实现好的分支。

后来我换了个顺序：每个任务描述里，先写测试要求，再写功能要求。让 agent 先基于需求文档写测试用例，然后再去实现功能。这样测试就是“图纸”，功能是照着图纸施工，而不是“房子盖完再画图纸”。实测下来，这种方式能让 agent 自己发现不少问题，因为它写测试的过程就是重新理解需求的过程，理解不到位的地方在测试里就会暴露。

我一般要求测试里至少覆盖三种场景：正常输入、异常输入、边界条件。比如一个删除接口，正常场景是删除存在的项目，异常场景是删除不存在的项目，边界场景是删除已被其他表引用的项目。三个场景都能测过，这个接口才算合格。

4.2 报错速查表：依赖冲突、路径问题、环境变量、端口占用

开发过程中难免遇到各种运行时问题。pi agent 擅长修代码，但遇到环境层面的问题，它往往比较迟钝。我把这段时间遇到的典型报错整理成了一个速查表，供大家参考：

这些问题的共同特点是：它们不是逻辑错误，而是“环境上下文”错误。pi agent 面对这类报错时，倾向于反复修改业务代码来碰运气，但正确做法是先查环境再改代码。我在 AGENTS.md 里专门加了一条：遇到环境类错误，先执行诊断命令（比如打印环境变量、查看端口占用），把结果贴出来再决定怎么改，禁止盲目改代码。

4.3 迭代策略：一轮改动只做一件事

项目后期，我开始追求效率，让 pi agent 一次性改好几个模块：改完接口再顺便把前端页面调一下，再把文档更新了。结果就是改动之间互相影响，测试挂了不知道是哪个改动导致的，代码回退也不知道该回退到哪个 commit。

这个教训让我总结出一条迭代纪律：一轮改动只做一件事。哪怕这件事很小，比如只改一个接口的返回格式，也要经历“下任务—实现—审查—测试—提交”的完整循环。改完一个，跑一遍测试，提交一次，再开始下一个。

这么做的好处是：问题定位极其清晰。测试挂了，看一眼最后一个 commit 改了什么，基本就能锁定原因。而且 pi agent 在单任务模式下表现更稳定，它不需要在多个目标之间切换，反而更容易把当前任务做好。

我知道有人会觉得这样太慢，但实测下来，单任务循环的总耗时反而比多任务并行更短。多任务并行省下的时间，全都在排查问题、回退代码里加倍赔回去了。

5. 入住之后：复盘与长效维护的几条经验

5.1 收尾验收：让 agent 补文档、清理、做最后的自检

功能全部完成后，别忘了收尾。这一步相当重要，直接决定了项目是“能跑”还是“能交接”。

我做收尾的顺序是：先让 pi agent 跑一遍完整的测试套件，确认所有测试通过；然后生成一份 README，包含启动方式、环境变量说明、目录结构；接着更新 PROGRESS.md，把最终状态记录下来，方便以后接手的人（包括未来的我自己）快速了解项目；最后清理掉项目里的调试日志、临时文件和没有用到的依赖。

这里有个小技巧：在让 pi agent 清理依赖时，不要直接说“把没用的依赖清理掉”，它会根据自己记忆里的代码来判断。更可靠的方式是，跑一遍 lint 和 build，看有没有引用缺失的包，或者直接用 depcheck 之类的工具扫描。让数据说话，而不是让 agent 凭印象做事。

5.2 三张备忘清单：开工前、开发中、收尾时各一张

我把这次的经历沉淀成了三张清单，每次用 pi agent 开工我都会过一遍：

开工前：

• 项目技术栈是否固定并写入 AGENTS.md？
• 目录结构是否有明确约定？
• git 仓库是否初始化并打了基线 tag？
• 依赖环境是否验证过最小安装链路？

开发中：

• 每个任务是否包含“目标、约束、验收、参考”四要素？
• 是否每轮改动只做一件事？
• 是否每次改动后都跑了测试并提交？
• 是否定期更新 PROGRESS.md？

收尾时：

• 全部测试是否通过？
• README 是否完整？
• 临时文件和调试代码是否清除？
• 依赖是否精简并验证可正常构建？

这三张清单一开始觉得繁琐，但用习惯了反而轻松，因为每一张都是在帮 pi agent 减少自由发挥空间，也是在帮我自己减少返工次数。

5.3 给新手的三个建议

如果你正准备开始用 pi agent 做自己的第一个真实项目，我给你三条建议。

第一，先拿一个玩具项目练手。不要一上来就重构老项目，更不要直接拿生产环境测试。找个需求清晰、逻辑简单的小工具，从头到尾走一遍完整流程，体验一下“下任务—反馈—修正—验收”的节奏，建立手感。

第二，学会从小处入手，但把话说完整。一个任务拆得越小，成功率越高。小任务不是让你每次只说一句话，而是让你把一句话能讲清楚的事情，用足够的背景信息包裹好。背景信息多一点，agent 的发挥就更稳一点。

第三，永远保留人工审查这一步。这点我再强调都不为过。pi agent 是一个效率工具，但它不是质量保障。质量保障是你自己的审查清单、你的测试用例、你的验收标准。工具有多强，不代表交付物就有多好，关键还是看你怎么用它。

写在最后

说实话，用 pi agent 做这个项目的经历，比我预想的要曲折得多。刚开始我把它想像成一个能听懂人话的编程机器人，结果发现它更像一个需要明确指令和严格验收的施工队。毛坯房装修踩的坑，大多不是因为“工具不够聪明”，而是因为我作为“甲方”没有把需求、边界和验收标准想清楚。

现在我再拿到新需求，第一件事已经不是打开终端叫 pi agent 开工了，而是先把需求在文档里写明白：要做什么、不做什么、怎么算做好。这个过程看起来跟写代码无关，但恰恰是它，决定了后面 pi agent 是帮你干活还是帮你添乱。

如果你正准备踏上这条路，我希望这篇记录能帮你少踩几个坑。工具会越来越强，但这套“先定规范、再动工、全程验收”的工作方法，什么时候都不过时。