Pi手动添加全攻略：终端AI编程智能体从安装到workflow与skill配置

先聊个话题最近几天我的后台几乎被同一个问题刷屏了“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-agent0.5.x把0.5.x换成你查到的具体版本号。全局安装的好处是终端里任何位置都能直接运行如果你不想污染全局环境也可以用本地安装加npx的方式npm install --save-dev pi-coding-agent npx pi-coding-agent这条命令只把 Pi 装在当前项目里适合做团队统一管理。注意的一点是不同操作系统安装后的全局路径不一样Windows 下 npm 全局 bin 通常在%APPDATA%\npmmacOS/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 写一个能落地的 workflowWorkflow 的格式细节从 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_MODELgpt-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 编程智能体已经不是一个新鲜概念了除了 PiOpenCode 和 Codex CLI 也是被问得最多的两个。我给一个比较直观的对照表方便你按情况选维度PiOpenCodeCodex CLI定位终端原生智能体重视结构化流程轻量 CLI Agent追求快速接入OpenAI 官方命令行工具workflow/skill 支持内建且成熟适合团队沉淀支持方式较基础偏重对话式交互适用场景多步骤任务、规范落地、benchmark 复现日常小任务、快速改写代码深度依赖官方生态的团队学习成本中等配置项较多低拿来就用中等版本稳定性0.5 版本被社区大量复现口碑稳定迭代快变化较大跟随官方节奏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:$PATHWindows 用户直接用 PowerShell 检查$env:APPDATA\npm是否在系统 Path 里不在就手动加进去然后重开终端。这个操作看起来基础但真能解决一大半问题。6.2 workflow 不生效的 3 个检查点workflow 写好却不生效很多人第一反应是卸载重装千万别。按下面 3 个检查点来目录位置是否正确。项目级 workflow 必须放在项目根目录的.pi/workflows/放错层级就找不到。frontmatter 格式是否合法。name和description必须写在两组---之间字段名不能拼错尤其别把description写成desc。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-agent0.5.0我的经验是大版本刚发出来的前两三天先别急着升级等社区把典型问题暴露得差不多了再动。毕竟我们用的是工具不是帮着测新版本 bug 的。踩过几次坑之后我越来越觉得“Pi 手动添加”这件事本质上不是安装命令的差别而是你把控制权从脚本手里拿了回来。只有亲手装了、配了、写了 workflow你才真正知道这个 agent 的边界在哪里。第一次折腾的时候别贪多先把版固定下来再落地一条最简单的 workflow跑通一次完整任务。等你习惯了它的工作方式再逐步往技能库里加东西效率和稳定性都会比一开始就堆配置高出一大截。