这段时间一直在折腾 AI 编程助手陆陆续续把 opencode、codex 都试了一圈最后停在了 Pi 上。倒不是说它一定比别的强多少而是它的“手动添加”方式太对我这种不喜欢一键脚本的人胃口了——所有配置都摊在你面前自己动手加出了问题自己心里也有数。这篇文章就把手动添加 Pi 的完整过程、踩过的坑、以及怎么把常用编码 skill 加进去一次性说清楚给正准备入坑 Pi 的朋友一份能照着做的清单。我默认你用的是 macOS 或 LinuxWindows 的路径差不太多遇到不一样的地方我会单独标出来。整个流程不需要你懂很深但我会把每一步背后的逻辑讲明白这样就算以后版本变了你也能自己摸着改。1. 开始之前先弄明白 Pi 是什么以及为什么偏要手动添加1.1 一个会自己写代码的终端 AgentPi 本质上是一个跑在终端里的 AI 编码代理coding agent你给它一个任务比如“把这个 Python 脚本里的循环改成并发”它不是只甩给你一段代码而是会自己去读项目目录、改文件、跑测试、看报错再根据结果继续调整直到任务完成。简单说普通 AI 是“问答式”Pi 是“干活式”你可以把它理解成一个招进来不用发工资、且 24 小时不打瞌睡的实习生你说需求它动手做做完还知道自己检查一遍。和很多同类工具一样Pi 的核心能力分两块一是底层的模型推理能力靠接入各种大模型 API 来实现二是上层的编码技能skill也就是告诉它“遇到什么情况应该用什么姿势处理”的规则集。这两块都不是非得用官方默认配置不可手动添加的意义就在这里——你可以自己指定模型、自己写 skill让 Pi 真正按你的习惯办事。1.2 官方脚本没问题但手动添加可控性更高官方其实提供了安装脚本跑一下就能拉起一个可用环境。那我为什么还要费劲手动添加原因有三第一脚本默认做了一堆“智能判断”比如自动检测你机器上有没有 Node、有没有 Python帮你把依赖全装了。听起来省事但它默认装的版本和存放位置不一定是你想要的。手动添加可以完全掌控每个组件放哪、用哪个版本后边排查问题的时候少很多玄学。第二脚本拉取的配置模板是普适的但每个人的 API 来源、模型偏好、代理设置指本地网络代理这类常规配置都不一样手动添加可以按自己的实际场景写配置而不是在模板上反复打补丁。第三也是最重要的一点手动添加一次之后你对整个工具的目录结构、配置格式、运行机制会有一个非常直观的认识。以后想加一个 skill、换一个模型、改一个参数你根本不用翻文档直接改文件就行。这就像自己组装过一次电脑的人以后换内存条比谁都利索。1.3 这篇文章适合谁如果你属于下面任一情况这篇文章可以用得上被“一键安装”折腾过装完不知道东西在哪、想改配置无从下手需要给 Pi 接入自己买的 API Key而不是用官方内置的免费额度想自定义编码 skill让 Pi 更贴合自己团队的代码规范遇到 Pi 装了但跑不起来想搞明白到底哪一步出了问题。接下来我就按自己实际操作的顺序从环境准备讲到 skill 编写尽量把每一步为什么这么做都说清楚。2. 动手之前先把环境和依赖检查明白这一步很多人会跳过去觉得“我电脑肯定没问题”。但根据我的经验Pi 手动添加失败一半以上的原因出在环境依赖上。提前花五分钟检查能省掉后面一整晚的排查时间。2.1 运行环境要求Pi 是一个基于 Node.js 的命令行工具所以第一前提是你的机器上有 Node.js而且版本不能太老。我建议至少 Node.js 18 以上20 LTS 更稳妥。这里有个小知识点Pi 的很多依赖用到了较新的 JavaScript 语法老版本 Node 解析不了表现就是装完一运行就报SyntaxError而且报错位置五花八门看着像代码问题其实纯粹是运行时版本太旧。检查命令很简单node -v npm -v如果node -v输出的版本低于 18建议先去官网装一个新版 LTS。Windows 用户我推荐用 nvm-windows 来管理 Node 版本macOS 用户直接用 nvm 或者 Homebrew 都可以别图省事从官网下一个安装包装完就不管了——多个项目之间切换版本的时候有个版本管理器会舒服很多。2.2 检查几个容易被忽略的依赖除了 Node 本体还有几个东西容易被忽略gitPi 在执行任务时需要读取项目里的 git 信息比如当前分支、变更文件列表。没装 git 或者没加入 PATH它很多操作会莫名失败。Python可选但建议如果你让 Pi 写 Python 项目它需要调用 Python 解释器来跑测试和语法检查。不装的话Pi 也能工作但是“跑一遍验证”这个能力就废了。终端环境变量有些网络环境下npm 需要走代理才能装包。这个属于常规的网络代理配置不在本文讨论范围内但如果你装依赖一直超时可以检查一下 npm 的 proxy 配置是否正确。检查完这些我建议顺手把 npm 源确认一下。因为 Pi 的安装包通常会带上不少依赖如果源不稳定安装过程会非常痛苦而且经常会“装到一半卡住然后告诉你校验和不一致”。这不是 Pi 的问题是网络传输的问题换个稳定的镜像源基本能解决。2.3 先准备好 API Key否则后面白忙Pi 本身不生产模型能力它需要调用大模型 API。所以手动添加之前你必须有一个可用的 API Key。这个 Key 是你从模型服务商那边申请的各家申请流程不一样但核心要点是一致的拿到手先自己写个小请求测试一下确认这个 Key 能正常返回结果再接到 Pi 里。我见过太多人配置好了 Pi 却总是报鉴权失败最后发现是 Key 本身复制多了空格、或者申请的是另一个服务的 Key。先单独验证能排除掉这个最基础的坑。另外要注意不同 API 的兼容格式不一样。Pi 在配置里需要你指定模型的 base URL 和模型名称如果你用的是兼容 OpenAI 格式的服务那 base URL 一般长这样https://api.example.com/v1。这一块拿不准的话去你申请 API 的文档里找“base URL”字段别自己猜。3. 核心环节手动添加 Pi 的全流程记录环境确认没问题之后下面就是整个手动添加的核心流程。我会按我实际操作的顺序来写每一步都给命令和说明你照着做就行。3.1 下载并放置 Pi 本体Pi 作为一个 npm 包手动安装其实就是用 npm 全局安装npm install -g pi-agent这里我建议加-g全局安装这样任何目录下都能直接敲pi命令启动。如果你不想全局装也可以在某个固定目录里局部安装然后每次用npx pi来调用但不是特别推荐——npx第一次调用会下载响应速度明显慢体验不好。安装完成后用下面的命令确认一下版本pi --version如果这里输出了版本号说明本体已经装好了。没输出的情况下先别急九成是 PATH 的问题。npm 全局安装的 bin 目录没有被加进 PATH你检查一下npm prefix -g的输出把它下面的bin目录加到 PATH 里就行。这一步算是整个过程中唯一比较“系统级”的操作弄好之后后面的配置就是纯文本操作了。3.2 手动创建配置文件Pi 的配置目录默认在用户主目录下一般叫.pi不同版本可能略有差异以官方文档为准。没有的话自己建一个mkdir -p ~/.pi然后在这个目录下创建主配置文件通常叫config.json或者config.toml具体格式取决于你装的版本。我用的版本是 JSON 格式结构大概长这样{ model: { provider: openai-compatible, baseUrl: https://api.example.com/v1, name: gpt-4o-mini, temperature: 0.2 }, agent: { autoRunTests: true, maxIterations: 20, workspace: ./ } }这里解释一下关键字段provider模型提供方的类型。openai-compatible表示兼容 OpenAI 接口格式的服务这也是目前最通用的一种。baseUrlAPI 的地址前缀刚才申请 Key 的时候在文档里能找到。name模型名必须和你的 API 服务支持的名字完全一致大小写都不能错。temperature采样温度数值越低回答越保守、越按部就班写代码我建议 0 到 0.3 之间太高了容易发挥过头。maxIterations这是 Pi 执行一个任务最多能自己迭代多少轮的次数。设太小复杂的重构任务做到一半就停设太大万一它跑偏了会一直绕圈。我一般设 20写大一点也没事看到不对手动 CtrlC 就行。配置文件写好后可以先跑一个最简单的命令测试pi 输出 hello world如果能正常返回结果说明配置文件的路径和格式都对了。3.3 往配置里手动添加 API 凭据这其实有两种做法一种是直接写在配置文件里一种是放到单独的环境变量文件里。这两种我都试过各有适用场景。我自己更推荐用环境变量的方式原因很直接配置文件可能会被分享、提交到 git 仓库Key 一旦写进去就相当于裸奔。把 Key 放在~/.pi/.env文件里然后在主配置中用变量引用这样即使配置文件不小心泄露敏感信息也不会跟着出去。.env文件的内容大概是这样PI_API_KEYsk-你的密钥 PI_BASE_URLhttps://api.example.com/v1然后在config.json里改成引用变量{ model: { baseUrl: ${PI_BASE_URL}, apiKey: ${PI_API_KEY} } }注意这里的前提是你的 Pi 版本支持自动加载.env文件。如果不支持你可以在 shell 的配置文件里 export 这两个变量效果一样。手动添加 Key 的核心逻辑就是需要 Key 的不是配置文件而是运行 Pi 的那个进程。所以 Key 只要能以环境变量形式“喂”给进程就行放哪里其实不关键关键是别硬编码进会提交到仓库的文件里。3.4 验证安装是否成功配置好之后完整验证一遍比直接上手干大活要稳得多。我的验证顺序是三连第一跑一个无项目上下文的简单问题确认模型调用没问题pi 用一句话解释什么是递归第二进入一个真正的代码项目让 Pi 做一个很小的改动例如在某个文件里加一行注释看它能不能正确读写文件。这一步验证的是文件操作能力如果 Pi 无法读取项目文件说明工作目录或权限配置有问题。第三让它跑一次现有测试看看它能不能正确调用终端命令。这个可选但如果你的项目里有现成的测试脚本最好确认一下。三步全过说明手动添加这件事基本就成了。4. 进阶操作在 VSCode 里手动添加 Pi 的 API 与编码 Skill命令行里跑通了接下来就是大多数人真正想要的部分——把 Pi 接进 VSCode并且给它配好自己的编码 skill。这部分也是热搜里出现频率最高的几个点。4.1 在 VSCode 里接入 Pi装插件还是手动配置Pi 官方提供 VSCode 插件搜索 “pi coding agent” 就能找到。装插件本身不算手动添加但插件只是壳它内部还是要去读你~/.pi下的配置。换句话说你在命令行手动配好的 API Key、模型参数插件会自动复用。不过有一个坑必须提醒你VSCode 插件不一定继承你 shell 里的环境变量。VSCode 的图形界面进程不是从你的终端启动的所以如果你把 API Key export 在了 shell 配置文件里终端里 Pi 好好的插件却报鉴权失败。解决办法有两个一是把 Key 写到 Pi 自己的.env文件里让插件启动时主动加载二是在 VSCode 的settings.json里手动声明。我实际用下来觉得第一种更干净因为配置只此一份终端和插件都会读它。4.2 手动添加编码 Skill 的完整流程Skill 是 Pi 最值得折腾的部分。所谓“手动添加 skill”其实就是在指定目录下创建一个符合格式的规则文件告诉 Pi在什么场景下按什么步骤处理问题。具体操作分三步第一步建目录。Pi 的 skill 目录一般在~/.pi/skills下每个 skill 一个子目录名字要语义清晰比如code-review、pytest-fix、react-component。第二步写 skill 定义文件。每个 skill 目录下一般有一个SKILL.md文件里面是 Markdown 格式包含两部分信息头部是元数据名称、描述、适用场景正文是具体的指令。这里给一个我实际在用的 code review skill 示例--- name: code-review description: 对代码变更进行严格审查发现问题并给出修改建议 when: 用户要求 review 代码、检查 PR、或说“帮我看看这段代码” --- 按照以下步骤执行 1. 先获取变更文件列表逐个阅读变更内容。 2. 重点关注逻辑错误、边界条件、安全问题、性能隐患、命名和代码规范。 3. 按严重程度分级输出致命问题/建议改进/风格建议。 4. 每个问题必须指出文件位置和行号并给出修改示例。 5. 不要只夸代码也不要为了批评而批评只输出有价值的问题。第三步验证 skill 是否被加载。在项目里启动 Pi然后输入“帮我 review 一下当前的改动”如果 Pi 开始按你定义的步骤执行说明 skill 已经生效。如果一点反应都没有先检查文件名是不是SKILL.md大小写敏感再检查when字段里描述的场景是否覆盖了你的触发词。4.3 Skill 的设计心得少而精别贪多Skill 这东西特别容易让人上头一写就是十几个结果真正用得上的没几个。我的建议是先给编码流程里最痛的点写 skill写一个打磨一个。以我自己的项目为例我最先写的是“测试修复” skill因为我发现 Pi 最擅长写新代码但面对一个跑挂的测试时它经常会东改一下西改一下把测试改“绿”了但把代码改坏了。这个 skill 的规则很简单先读测试报错信息定位到具体断言再分析被测代码的逻辑最后改动最小化地修复并且必须解释为什么这么修。写完这个 skill 之后Pi 修测试的成功率提升非常明显。这个例子说明一件事skill 本质上是在给 Agent “立规矩”你越清楚自己在协作中的痛点写出来的 skill 越有价值。另外skill 文件和代码一样需要版本管理我强烈建议把~/.pi/skills目录做成一个 git 仓库换新机器或同事入职时直接 clone 一份一个指令集就同步过去了。5. 实操过程中最容易踩的坑问题排查与修正建议手动添加这个过程我前前后后折腾了不止一次换机器也重新部署过。下面这些坑都是我实际遇到的不是理论推演。5.1 常见问题速查表症状大概率原因处理方式pi: command not foundnpm 全局 bin 目录不在 PATH 里执行npm prefix -g把输出的路径下bin目录加入 PATH启动报SyntaxErrorNode 版本过低升级到 Node 18 及以上请求 API 报鉴权失败Key 复制错误或没写进环境变量先用 curl 直接测 Key 是否可用能回答但读不到项目文件工作目录不是项目根目录或权限不足确认在项目根目录运行检查目录读权限VSCode 插件能打开但请求失败插件进程没拿到 shell 环境变量把 Key 放到 Pi 的.env文件不用 shell export模型总是答非所问model.name和 API 实际模型名不一致去 API 文档核对精确的模型标识任务执行到一半停下来maxIterations设太小适当调大或改为手动确认模式5.2 配置文件写错的典型症状配置文件的错误非常隐蔽因为它经常不直接报“配置文件错”这句话。举几个我碰过的例子JSON 格式错了比如多了一个逗号、少了一个引号Pi 会直接启动失败报错信息里是指向某个位置的Unexpected token。这个还好定位。更隐蔽的是字段名拼写错误。比如把maxIterations写成max_interationsPi 不会报错它会默默忽略这个字段用默认值。症状就是你认为自己设了 50 次迭代实际它跑了 20 次就停了。排查这类问题没有捷径就是把配置逐字段和文档对照。还有一个容易忽略的点配置文件里路径的写法。如果你的工作区是相对路径Pi 会以它启动时所在的目录为基准来解析。我一开始用workspace: ./没问题但换了个目录启动之后发现 Pi 跑到了别的项目里。后来统一改成绝对路径再也没有这种困惑。5.3 我觉得最有用的三点经验第一手动添加时的每一条命令、每一个改动建议记个笔记。不是让你写论文而是简单记一下“今天改了哪个文件、为什么改”。这看起来笨办法但换环境、升级版本、或者电脑重装的时候这份笔记比任何官方文档都顶用。第二学会看日志。Pi 运行过程中会在~/.pi/logs下记录日志很多人报错只会看终端那几行红字忽略了完整日志里的堆栈信息。有一次我排查一个 skill 不生效问题就是打开日志看到它加载 skill 目录时路径不对一改就好。日志文件的路径可能因版本而异用pi --verbose跑一次任务输出的信息量足够定位大多数问题。第三每次升级版本后把配置备份一份。有些版本升级会迁移配置目录还有少数版本会改配置格式。我吃过一次亏升级后旧配置没自动迁移全部手工重建。从那以后我的习惯是升级前把~/.pi整个目录压缩备份升级后如果一切正常再删掉。6. 顺手聊几句手动添加完选 Agent 时该怎么想6.1 几个常见编码 Agent 的实际对比参考网上关于“opencode、codex、Pi 哪个好用”的讨论很多手动添加完 Pi 之后我也认真对比过这几个工具。这里的对比基于我个人使用体验不代表绝对优劣参数和功能以各项目最新版本为准。opencode 的优势在于插件生态丰富社区活跃适合喜欢折腾的人codex 作为 OpenAI 出品和 GPT 系列模型的配合比较顺滑开箱即用但自定义空间相对有限Pi 的特点则是目录和配置非常清晰手动添加之后一切都透明可控适合愿意花一点时间把工具调到完全顺手的人。我的感受是这三个工具没有绝对的强弱只有适不适合你的工作方式。如果你想要“装完就跑”codex 可能最省心如果你想要“什么都能改”那手动添加完的 Pi 会很对味如果你大量依赖社区的现成方案那 opencode 的生态能帮你省不少时间。6.2 我最终留下 Pi 的几个实际感受真正让我长期用 Pi 的不是它某一个炫酷功能而是这种“手动添加”带来的掌控感。我知道我的 Key 在哪里我知道我的 skill 放在哪个目录我知道任务跑到第几步会卡住。这些东西在纯自动化安装里是感受不到的。说得直白一点手动添加 Pi 的过程本质上是在和这个工具建立信任。装完以后出了问题你能自己修改了配置能预测结果这种感觉是任何一键脚本都给不了的。所以就算官方以后把安装脚本做得再完美我大概率还是会维护一套自己的手动配置这不是情怀是省事。如果你也想尝试我的建议是别一上来就配全套先跑通最基础的“能问问题、能改文件”然后按需加 skill最后再去折腾模型参数和插件联动。一步一步来不着急工具这东西永远是为人服务的你觉得怎么用着舒服那就是最好的配置。