企业官网建设流程全解析

先聊个话题，最近几天我的后台几乎被同一个问题刷屏了：“Pi 手动添加到底怎么弄？”

这里的 Pi，大概率指的是那款开源的终端 AI 编程智能体 pi-coding-agent，不是树莓派，也不是工控领域那套 PI System 数据库。它是一款跑在命令行里的 agent：你给它一句话，它自己去读文件、改代码、跑命令、看报错，再把结果回给你，中间几乎不需要你插手。

“手动添加”这四个字，我在不同场景里被问过太多次，而且大家问的其实不是同一件事。有人是想手动安装 Pi 本体，因为一键脚本在公司内网跑不动；有人是想在项目里手动添加一个 workflow，让 Pi 按团队规范干活；还有人想手动把自己的工具链加进 Pi 的技能库，让它下次能主动调用。我这次干脆把三种“手动添加”全拆开讲一遍，按真实操作顺序来，从环境准备到最后排查，直接可以照着抄。

适合看的读者大概是这几类：受够了自动安装脚本、想精确控制版本的开发者；想用 workflow 把 AI 编程智能体纳入团队流程的工程负责人；以及刚接触 Pi、看着一堆配置不知道该动哪里的新手。我会尽量把每一步的“为什么”也讲清楚，不光是给你一串命令。

1. 先搞清楚：Pi 是什么，以及为什么需要手动添加

1.1 不是树莓派，是终端里的 AI 智能体

Pi 这类工具，本质上是把大模型从“对话框”搬进了终端。传统用法是你把代码粘给 ChatGPT，让它给建议，你再手动改、手动跑。Pi 不一样，它自己就有终端权限，能直接执行命令、运行测试、查看报错、修改文件，然后继续迭代。整个循环是闭环的：指令 -> 执行 -> 观察结果 -> 再调整。

和它同类的工具还有 OpenAI 官方的 Codex CLI、社区很活跃的 OpenCode。Pi 的差异点在于对 workflow 和 skill 的内建支持更强，结构化的任务模板更容易沉淀下来。0.5 这个版本在社区里讨论度很高，好多人做 benchmark 复现都指定它，说明它作为“稳定基线”是站得住脚的。所以手动添加时，我强烈建议固定版本，别跟着 latest 走。

1.2 一键安装很方便，但手动添加解决真问题

多数开源工具都会提供一条自动安装命令，比如npm install -g或者一条 curl 脚本。但实际用下来，一键安装只适合个人电脑上的尝鲜场景。一旦你到了下面几种环境，手动安装反而是唯一选择：

• 公司内网 / 离线环境，无法直接访问公共仓库，得走内部镜像或离线包；
• 需要精确控制版本，团队所有成员和 CI 用的必须完全一致；
• 安装目录、权限、隔离策略都有特殊要求；
• 想在容器镜像里预装 Pi，自动安装脚本会引入太多不确定性。

手动添加还有个隐藏好处：你在安装过程中会把工具的目录结构、依赖关系、配置文件位置全部过一遍，后面出了问题排查快得多。我见过太多用一键脚本装完就报command not found的人，连全局 bin 目录在哪都不知道，更别说改了。

2. 手动安装前的环境准备

2.1 运行时版本与包管理器选择

Pi 这代终端 agent 基本都是用 Node.js/TypeScript 那套技术栈构建的，所以手动安装的第一步，是确认你机器上的 Node.js 版本。我的建议是直接上 LTS，最好是 Node 20 或以上。版本太老容易出现 API 不兼容的问题，不是装不上，就是装上了某些功能莫名奇妙崩。

检查方法很简单：

node -v npm -v

如果你装了 nvm 或者 fnm，记得先切到合适的版本再继续。包管理器方面，npm 是默认选择，但同时装 pnpm、yarn、bun 的开发者也不少。我的个人建议是：能用 pnpm 就用 pnpm，它对依赖的隔离更严格，磁盘占用也小。不过别在同一个项目里反复横跳包管理器，lockfile一旦混了，版本解析会很乱。手动添加最怕的就是这个“乱”字。

2.2 从 npm registry 拉取并安装指定版本

安装前先看清楚 npm 上这个包到底发布了哪些版本，别闭着眼睛装 latest。用下面的命令查：

npm view pi-coding-agent versions --json

包名以 npm registry 实际发布名为准，有的版本会用@openai/pi-agent这种 scope 包，查一下你就知道了。确认版本列表后，指定版本安装：

npm install -g pi-coding-agent@0.5.x

把0.5.x换成你查到的具体版本号。全局安装的好处是终端里任何位置都能直接运行；如果你不想污染全局环境，也可以用本地安装加npx的方式：

npm install --save-dev pi-coding-agent npx pi-coding-agent

这条命令只把 Pi 装在当前项目里，适合做团队统一管理。注意的一点是：不同操作系统安装后的全局路径不一样，Windows 下 npm 全局 bin 通常在%APPDATA%\npm，macOS/Linux 通常在/usr/local/bin或者 nvm 对应的 node 路径下。装完如果提示命令找不到，先别急着重装，检查这个路径有没有在PATH环境变量里，这个问题占了安装失败案例的一大半。

提示：手动安装时把版本号显式写死，是对自己负责。别用@latest，因为上游发版可能带破坏性变更，你今天能跑，下个月同事装上就报错，那体验非常酸爽。

3. 项目里的手动添加：workflow 与 skill 配置

3.1 配置文件放到哪里，为什么这么设计

很多朋友装好了 Pi，却不知道项目里怎么“手动添加”自己的规则。其实 Pi 的设计思路很类似 Git 的配置分层：全局配置放在用户主目录，项目级配置放在仓库根目录。拿我常用的目录结构举例：

项目根目录/ ├── .pi/ │ ├── workflows/ │ │ └── release-check.md │ └── skills/ │ └── git-commit/ │ └── SKILL.md └── package.json

.pi/workflows放的是可复用的多步骤任务，pi run <workflow>可以直接调用；.pi/skills放的是技能说明文件，让 Pi 在合适的场景下主动把某个能力纳入执行流程。这种文件即配置的方式比 Web 后台改设置要轻量得多，也天然适合走 Git 评审：谁想改团队规范，提个 PR 就行，改动全留痕。

3.2 写一个能落地的 workflow

Workflow 的格式细节，从 0.5 版本开始逐步收敛了，核心结构基本是“描述 + 步骤”。我给你一个发布前检查的完整示例，照这个改就能用：

--- name: release-check description: 在发布前执行完整性检查：跑测试、检查未提交变更、确认版本号。 --- 1. 运行项目的测试命令，通常是 `npm test` 或 `pytest`，如果失败就停止并汇报。 2. 检查当前 Git 工作区是否有未提交的变更，如果有，列出清单。 3. 读取项目版本文件，确认本次发布版本号已经更新。 4. 汇总以上结果，输出发布建议。

关键点在第一行的name和description。name是你在命令行里调用的标识，description是让模型判断“什么时候应该用这个 workflow”的输入信号。写描述时一定要写触发条件和执行目标，比如“在发布前执行”，而不是干巴巴的“发布检查”。我见过很多刚开始用的人，description 写得太抽象，结果 Pi 在根本不相关的任务里把 workflow 调起来了。

调用方式很简单：

pi run release-check

如果遇到 workflow 不生效，优先检查三件事：文件扩展名和 frontmatter 格式对不对、YAML 缩进有没有混用 Tab 和空格、name是否和调用时完全一致。后面我专门列一节排查。

3.3 skill 手动添加：把当前目录加进技能库

Workflow 解决的是“固定流程”，Skill 解决的是“动态能力”。比如我写 Python 测试时习惯用pytest写参数化用例，那我就把这个习惯写成一条 skill，让 Pi 在写测试时自动遵守。

在.pi/skills/下建一个目录，里面写SKILL.md：

--- name: pytest-parametrize description: 当需要为 Python 函数编写单元测试时，优先使用 pytest 的 parametrize 方式覆盖边界输入。 --- 编写 Python 单元测试时： 1. 使用 pytest 框架。 2. 对纯函数优先使用 @pytest.mark.parametrize 构造输入输出表。 3. 至少覆盖正常输入、边界值、异常输入三种情况。 4. 测试命名以 test_ 开头，文件放在 tests/ 目录。

手动添加 skill 之后，Pi 会不会调用，取决于它在执行任务时是否读到了这条 skill 的description。所以描述里那句“当……时”特别重要，它相当于触发开关。想让某条 skill 在当前会话里立刻生效，可以先告诉 Pi“读一下 .pi/skills 下的 pytest-parametrize”，让它把内容加载进来再干活。

实操心得：skill 不是越多越好。我见过有人一口气加了几十条，结果 agent 的注意力被分散，反而更容易挑错工具。每一条 skill 都应该是你真正做过、验证过、值得复用的经验，而不是把网上的最佳实践全都塞进去。

4. 实操过程：从命令行执行到交互验证

4.1 验证安装和查看帮助

安装完成后，第一件事不是急着跑任务，而是确认环境是否正常。依次执行：

pi --version pi --help

--version输出应该和你手动安装时指定的版本一致，如果对不上，大概率是全局环境下有多个版本冲突。--help能看到当前支持的子命令，不同版本的命令名可能有差异，以你手上的版本输出为准。这个习惯非常重要：说得再天花乱坠，都不如亲自过一遍 help。

4.2 配置模型与鉴权信息

Pi 本身只是个运行时，真正干活的是背后的模型。首次运行前，你需要让它知道该调用哪个模型、用什么凭证。最常用的方式是设置环境变量：

export OPENAI_API_KEY="你的密钥" export PI_MODEL="gpt-5-mini"

模型名这个东西变化很快，建议以官方文档当前支持的模型列表为准。注意一点：环境变量只在当前终端会话有效，如果你开了新终端又报鉴权失败，多半是忘记重新 export。更稳妥的做法是写进当前项目的.env文件，再在.gitignore里把.env忽略掉。密钥这东西一旦进 Git 历史，后面再撤就非常痛苦。

还有一类情况是公司内部已经搭好了兼容接口，那就不需要官方密钥，改配置base_url指向内部服务即可。具体字段名看pi --help里的环境变量说明，不同小版本可能有调整。

4.3 完整回放：初始化 Python 项目并让 Pi 写测试

理论讲了这么多，不如直接来一次完整回放。假设我现在要在一个空目录里初始化一个 Python 项目，并让 Pi 把核心模块和测试都写了。

第一步，手动添加最基础的 pytest workflow，放.pi/workflows/write-tests.md：

--- name: write-tests description: 为 Python 函数补齐单元测试，使用 pytest 参数化覆盖边界情况。 --- 1. 分析当前项目中被 @param 标记或指定需要测试的函数。 2. 在 tests/ 目录下创建对应测试文件。 3. 使用 pytest 和 parametrize 编写测试。 4. 执行 pytest，确保全部用例通过。

第二步，启动交互会话，直接下指令：

pi

然后输入：

用 Python 写一个计算斐波那契数列的函数，放到 fib.py，然后运行 write-tests 工作流补测试，最后跑一遍 pytest 确认通过。

注意这里我把“放到 fib.py”和“运行 write-tests 工作流”都塞进了同一句话。实际用下来，Pi 会把任务拆成几个阶段：先写代码，再读 workflow，再执行测试，最后根据测试结果决定要不要修代码。你不需要反复复制粘贴报错信息，把执行权完全交给它就好。

整个过程终端里会持续滚动它执行过的命令、读取的文件和测试结果。如果你看到它卡在某一步拿不定主意，可以打断输入补充约束条件，比如“不要用递归，用循环实现”。这个反馈机制是终端 agent 比人工拷代码高效的关键。

5. 关键选型对比：Pi、OpenCode、Codex 到底怎么选

5.1 三者差异速览

现在终端 AI 编程智能体已经不是一个新鲜概念了，除了 Pi，OpenCode 和 Codex CLI 也是被问得最多的两个。我给一个比较直观的对照表，方便你按情况选：

5.2 什么时候选 Pi，什么时候别选

我不是那种“某某工具天下第一”的博主，工具选型一定要看场景。如果任务是单轮的，比如“帮我把这段代码格式化一下”，OpenCode 就很轻快，没必要上 Pi。但如果任务是多步骤、多文件的，比如“给项目加一个数据库迁移脚本，跑通后更新 API 文档，再补集成测试”，Pi 的 workflow 机制优势就很明显了。

还有一个容易被忽略的差异：在复现 benchmark 的时候，工具版本对结果影响很大。所以像“Pi 0.5 复现”这类需求，问你“opencode codex pi 哪个 agent 好用”的人，我一般会反问一句：你的目标是稳定复现，还是追新功能？追新可以三个都装，稳定复现就直接锁死 Pi 0.5，别动。

注意：只要定位为“团队统一工具”，就一定要把版本和配置纳入 Git 管理。建议把版本号写进 README 或者.tool-versions，不然团队成员各装各的，最后排查问题成本高得离谱。

6. 常见问题与排查技巧实录

6.1 command not found 了怎么办

这个话题我起码被问到几十次。command not found最常见的原因不是没装上，而是装到了 npm 全局目录，但那个目录不在PATH里。排查思路按顺序来：

npm prefix -g

输出结果就是全局安装目录，再看对应的bin目录有没有pi或pi-coding-agent这个可执行文件。没有，说明安装过程有问题；有，说明PATH没配好。macOS/Linux 下在 shell 配置里加一行：

export PATH="$(npm prefix -g)/bin:$PATH"

Windows 用户直接用 PowerShell 检查$env:APPDATA\npm是否在系统 Path 里，不在就手动加进去，然后重开终端。这个操作看起来基础，但真能解决一大半问题。

6.2 workflow 不生效的 3 个检查点

workflow 写好却不生效，很多人第一反应是卸载重装，千万别。按下面 3 个检查点来：

1. 目录位置是否正确。项目级 workflow 必须放在项目根目录的.pi/workflows/，放错层级就找不到。
2. frontmatter 格式是否合法。name和description必须写在两组---之间，字段名不能拼错，尤其别把description写成desc。
3. YAML 缩进是否规范。我见过最隐蔽的坑是复制文档里的代码时，缩进混用了 Tab 和空格，解析器直接报错。全部换成空格缩进最稳。

检查完这三项还不行，再考虑是不是版本差异问题，去翻一下当前版本对 workflow 的字段定义。

6.3 调用模型报错 401/400

跑任务时如果报鉴权或参数相关的错误，先分清是哪一类。401 基本是密钥问题：环境变量没设置、密钥失效、或者当前终端会话没重新加载。400 通常是模型名或参数问题：你填的模型名不在当前服务商支持范围内，或者某个参数格式不对。

我建议在项目根目录准备一个.env.example，把需要的环境变量名写清楚，后面新同事接入直接复制成.env填值就行，能少踩很多坑。

6.4 版本升级与回滚指南

最后讲一下升级策略。手动安装最大的好处就是升级和回滚都可控。查看当前版本和最新版本：

npm list -g pi-coding-agent npm view pi-coding-agent version

确定要升级时，同样指定版本号安装，不要直接npm update。升级后先跑一遍你最常用的两三个 workflow，确认行为没变。如果发现不兼容，用之前的版本号重装即可：

npm install -g pi-coding-agent@0.5.0

我的经验是：大版本刚发出来的前两三天，先别急着升级，等社区把典型问题暴露得差不多了再动。毕竟我们用的是工具，不是帮着测新版本 bug 的。

踩过几次坑之后，我越来越觉得“Pi 手动添加”这件事，本质上不是安装命令的差别，而是你把控制权从脚本手里拿了回来。只有亲手装了、配了、写了 workflow，你才真正知道这个 agent 的边界在哪里。第一次折腾的时候别贪多，先把版固定下来，再落地一条最简单的 workflow，跑通一次完整任务。等你习惯了它的工作方式，再逐步往技能库里加东西，效率和稳定性都会比一开始就堆配置高出一大截。