最近我在给新电脑配置开发环境时会先把 Pi Agent 装好因为它差不多已经成了我打开终端后的第一件事。Pi Agent 是一个开源的 AI 编程助手它不只是一个聊天框而是能直接读取项目文件、执行命令、修改代码并把改动后的 diff 交给我确认的编码智能体。上一篇聊了它的定位和整体架构这篇是系列第二篇目标很明确让你在五分钟内把它装好、配好模型然后跑通第一条指令。无论你是第一次听说这个工具还是在 GitHub 上看到项目后卡在了安装那一步这篇都给你一条可以直接照抄的路径。1. 我为什么把 Pi Agent 列入新电脑必装清单1.1 它解决的是终端里的工作流断点不是又一个聊天框很多 AI 编程工具给我的感觉是“问答很流畅落地很遥远”。你在网页里问它一段代码问题它给你一段答案然后你还是要自己切回编辑器手动把代码贴进去再手动跑测试。一天里这种切换如果超过十次效率其实是在下降的。Pi Agent 不一样的地方在于它默认就跑在终端里跟你的项目在同一个上下文中。它可以自己列目录、读文件、看 git 状态甚至执行测试命令。你只需要给它一个相对明确的任务比如“把登录接口的超时时间改成可配置项”它会自己完成从查找代码到修改代码的闭环最后把 diff 给到你看。我刚开始用的时候也有点不习惯觉得把改代码的权限交给一个命令行工具不太放心。但后来我发现它每一步都有确认机制关键操作需要你点头才会继续。这个“人在环上”的设计让我愿意在真实项目里逐步放开权限。1.2 安装前先分清三个词CLI、TUI、桌面端Pi Agent 的安装和使用绕不开三个词CLI、TUI、桌面端。搞懂它们的区别五分钟安装就不会走弯路。CLI 是指pi这个命令行程序。你装完包之后在终端里敲pi就会进入一个全屏的交互界面这个界面叫做 TUIText User Interface。它占用整个终端窗口左边是会话列表右边是对话和任务日志操作方式类似 Vim可以用快捷键切换。桌面端则是一个独立的应用窗口适合你不开终端、单独看任务进度的时候用。它跟 CLI 共用同一套配置和项目数据所以你可以早上在终端里启动任务下午打开桌面端看结果不需要重新初始化。换句话说你只需要记住核心引擎只有一套CLI 是入口TUI 是交互界面桌面端是辅助监控面板。2. CLI 版安装五分钟里的前三分钟2.1 前置检查Node 和 npmPi Agent 目前通过 npm 分发所以在安装之前先确认你机器上有 Node.js 环境。在终端里执行两条命令node -v npm -v如果都能正常输出版本号说明环境没问题。比如我前几天在新电脑上看到的是v20.11.0和10.2.4。如果你还没有 Node.js去官方站点下载 LTS 版本也就是长期支持版装完再回来继续。这块不用追求最新版LTS 最稳。这里有一个容易忽略的小点不要用系统自带的旧版 Node尤其是有些电脑上预装的 Node 版本停在 16 以下。Pi Agent 的依赖生态比较新很多库要求 Node 18 以上。所以我会建议你直接装 Node 20 或更高版本省得后面报一堆奇奇怪怪的兼容性错误。2.2 设置 npm 镜像源然后装包Pi Agent 的安装命令本身很简单npm install -g pi-agent/cli但在国内网络环境下如果你直接用默认源很可能会遇到超时或者下载到一半失败。这不是项目本身的问题而是 npm 官方的下载源在部分地区访问不稳定。常规做法是把源切换到国内镜像我用的是淘宝的 npmmirror一直挺稳。先查看当前使用的源npm config get registry如果输出不是https://registry.npmmirror.com就手动切过去npm config set registry https://registry.npmmirror.com设置完成后再执行安装命令。全局安装的意思是安装完成后你在任何目录下都能直接使用pi命令不需要进入某个项目文件夹才能启动。这里补充一句pi-agent/cli是 CLI 包的完整名称。你在网上搜的时候可能看到有人写pi-agent或者pi那通常是别名安装方式。为避免版本不一致我还是建议装带完整 scope 的包。2.3 检查安装结果安装通常会在一分钟内结束结束后做两件事。第一看版本号是否显示正常pi --version如果输出了0.x.x之类的版本号说明核心程序已经可用。第二确认一下命令所在路径which pi在 macOS 和 Linux 上通常输出/usr/local/bin/pi或者用户目录下的 npm 全局路径。在 Windows 上则是在 npm 全局目录下。做完这一步你就完成了“五分钟方案”里的前三分钟。剩下两分钟分给密钥配置和第一次实际调用。3. 第一次对话密钥配置比安装更值得花时间3.1 最保险的最小配置方法Pi Agent 本身不内置模型它需要对接一个支持 OpenAI 接口协议的大模型服务。也就是说你还需要准备一个 API Key。我第一次安装的时候就踩了坑装完直接在终端里敲pi结果界面起来了但问它什么问题都返回错误。后来看提示才知道它根本没读到模型配置。所以这里我建议你安装完成后第一件事不是急着对话而是先把模型信息写进配置。执行下面这条命令进入配置向导pi config set model.provider openai然后依次配置模型名称、接口地址、API Key。以我个人常用的配置为例pi config set model.name deepseek-chat pi config set model.baseURL https://api.deepseek.com/v1 pi config set model.apiKey sk-你的密钥注意model.provider不一定叫openai它代表的是“兼容 OpenAI 协议的服务商”。Pi Agent 内部会按 OpenAI 的接口格式去调用所以只要你的模型服务商提供/v1/chat/completions接口都可以这样填。3.2 使用 OpenAI 兼容服务时别忽略 baseURL很多人在配置时只填了 model 名称和 API Key没填 baseURL结果模型名称填对了也连不上。这是因为像国产模型厂商的产品虽然兼容 OpenAI 协议但接口地址并不是 OpenAI 官方的地址。这种情况下你要把接口地址改成这个服务商自己的 baseURL。官网上一般都会写。配置完成后可以用一条非常简单的指令验证pi run 用一句话介绍你自己如果它能正常回复就说明密钥、模型名、接口地址这三样都配对了。如果仍然报错大概率是接口地址末尾少了/v1或者模型名跟服务商文档里的名称不一致。3.3 环境变量覆盖团队协作时的好习惯除了写入配置文件Pi Agent 还支持用环境变量注入模型配置。这么做的好处是你的密钥不用留在磁盘上的配置文件里也方便在 CI 环境里使用。常用环境变量有三个环境变量作用PI_MODEL指定模型名称PI_BASE_URL指定接口地址PI_API_KEY指定 API Key我平时在本机直接用pi config set写入配置因为它最省事。但在帮别人排查问题时我会先看环境变量是否覆盖了本地配置。因为 Pi Agent 的优先级是“环境变量 配置文件”如果环境变量里有一个旧的密钥你配置文件填得再正确它也会读到那个旧的。有一条铁律想单独强调永远不要把 API Key 写进项目代码或者提交到 Git 仓库里。配置文件你自己用可以但如果项目是多人协作的最好用.env文件配合环境变量并把.env加进.gitignore。4. 桌面端从 Releases 下载到双端打通4.1 桌面端安装包去哪里拿CLI 安装完之后如果你想用桌面端可以直接到 Pi Agent 项目的 GitHub Releases 页面下载对应系统的安装包。Windows、macOS、Linux 三个平台都有。我这里不放具体链接是因为项目更新比较频繁每次 Release 的下载入口都在同一个页面你进去选最新版本就行。下载的时候注意区分平台架构Intel 芯片的 Mac 选x64Apple Silicon 选arm64Windows 一般是x64版本。下载完成后直接安装和安装普通软件没有区别。不需要额外配置路径也不需要手动关联命令。4.2 桌面端和 CLI 为什么会“认识”彼此我第一次用桌面端的时候有个困惑它怎么知道我在终端里启动过哪些会话后来我看了配置目录才明白CLI 和桌面端共用同一个用户目录下的配置文件。在 macOS 和 Linux 上这个目录是~/.pi在 Windows 上是用户目录下的.pi文件夹。你通过 CLI 写入的模型配置、密钥、会话记录桌面端会自动读取。这意味着两件事。第一桌面端安装完成后不需要重新填一遍 API Key。第二你在终端里跑了一半的任务可以切到桌面端继续看日志和进度。4.3 什么时候我只会用桌面端虽然我大部分时间在终端里操作但在两种场景下我必定打开桌面端。一种是跑长时间任务的时候。比如让 Pi Agent 批量重构几十个文件终端开着怕误触关掉又怕中断。桌面端挂在后台随时能看进度也不用担心终端窗口被其他输出刷屏。另一种是历史记录回溯。桌面端的任务列表展示得比 TUI 更直观我可以按日期翻看之前做过的改动甚至搜索某次任务的关键词。如果你平时需要写日报这个功能会很省事。5. 跑通一条最小工作流从描述到改动落地5.1 先用pi plan确认方向不急着改代码很多刚接触 coding agent 的人上来直接跑一句“帮我重构一下”然后就等着它动手。这往往得不到理想结果因为任务描述越模糊模型的自由发挥空间越大最后产生的 diff 你越不敢接受。我的习惯是先让 Pi Agent 给方案而不是给改动。比如我会说pi plan 把项目里的所有 fetch 请求统一改成使用 utils/request.ts 封装它不会直接改文件而是会分析当前项目里有多少处 fetch 调用涉及哪些文件给出一个改造计划甚至估算风险点。这个计划会保存在本地方便你确认。这一步最大的价值是让你在代码还没被修改的时候低成本地纠偏。如果它理解的方向不对直接终止或者重新描述即可不用处理垃圾代码。5.2 确认计划后再让 Pi Agent 执行计划确认没问题之后再给执行指令pi run 按照刚才的 plan 执行改动保持原有逻辑不变执行过程中Pi Agent 会列出它读过的文件、执行的命令和修改的点。最终产生一个完整的 diff 供你审查。你可以逐行查看也可以直接让它跳过某些文件。这里有个小技巧在pi run的指令里把前置约束写得越具体越好。比如“不要改测试文件”“不要动第三方库的代码”“保留所有注释”。模型对这类约束的遵守能力通常比对模糊目标的理解能力强很多。5.3 工作流的三个习惯能让 agent 好用到另一个量级我连续用了几周之后总结出三个值得坚持的习惯这里直接分享给你。第一个习惯是“小步跑”。不要一次性给它一个覆盖全项目的大任务而是拆成“每个任务改动三五文件、能在十分钟内完成”的小块。每一块单独plan、单独run、单独 review。这能让每次改动的可审查性大幅提升。第二个习惯是“先喂上下文”。如果你的项目里有一个模块它不知道存在那么它很可能自己造一个相似模块。这时候你可以在描述里直接给出关键路径比如“先看src/services/api.ts再改src/components/Login.tsx”。这比让模型自己翻整个目录树快得多。第三个习惯是忙完后就留下记录。Pi Agent 会把任务会话保存在本地我养成了一个习惯每隔几天翻一次会话列表看看当时的思路和改动记录。这有点像代码 review 的辅助笔记对后续维护帮助很大。6. 安装和使用里最常遇到的四个坑以及我的处理方式6.1 npm 全局安装时提示 EACCES 权限错误这个问题在 macOS 和 Linux 上很常见说白了就是系统不允许 npm 往全局目录写入文件。我在一台旧电脑上遇到过安装指令执行到一半报了一串EACCES: permission denied。最简单的处理办法是不要用 sudo 强行装而是把 npm 的全局目录改到用户自己的目录下。执行mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把这个目录加到 PATH 里。在~/.zshrc或~/.bashrc末尾加一行export PATH~/.npm-global/bin:$PATH保存后重新打开终端再执行一次安装命令。这样既绕开了权限问题也能避免 sudo 安装带来的文件归属混乱。6.2 安装成功了却提示 command not found如果你已经看到npm install成功但在终端里敲pi却提示命令找不到那基本可以断定是 PATH 环境变量里没有包含 npm 全局目录。不同系统对应的全局目录不同可以用一条命令查出来npm prefix -g比如在 macOS 上输出可能是/usr/local那么实际的可执行文件就在/usr/local/bin/pi。你把这个 bin 目录加到 PATH 里就行。Windows 上则常见于没有重启终端。npm 安装新包后环境变量不会自动刷新重新开一个终端窗口往往就能解决。6.3 桌面端启动后一直显示“未连接”桌面端打开后如果状态一直是未连接先别急着重装。你只需要确认本地服务有没有跑起来。这里有个底层逻辑桌面端本身不是一个独立引擎它要连接一个本地服务来读写任务数据。CLI 安装时这个服务已经作为依赖装好了。如果桌面端连不上最简单的办法是把 Pi Agent 的 CLI 先启动一次比如运行pi --version后再重新打开桌面端。如果在团队里用了自定义配置目录还需要检查桌面端启动时是否加载了正确的环境变量。我遇到过的情况是.env文件里的配置写得太随意导致桌面端读取失败调整后就好。6.4 模型上下文超限当你让 Pi Agent 处理一个大型项目时偶尔会看到“context length exceeded”这类错误。这不是安装问题也不是 Pi Agent 坏了而是你喂给模型的上下文太大了。解决办法有两个方向。一个是在指令里限制任务范围比如明确说“只分析src/modules/下的代码不递归进入node_modules”。另一个是开启项目索引的文件忽略功能把node_modules、dist、build这类大目录排除在扫描范围外。我在实际项目里会同时做这两件事。说句实在话多数“agent 越跑越笨”的情况并不是工具退化了而是上下文里塞进了太多无关文件把真正有用的信息挤掉了。Pi Agent 的安装和基础使用到这里就全部跑通了。我个人这几周用下来的最大感受是安装其实是最简单的一步真正的门槛在于你能不能把一个模糊想法变成一条让 agent 能理解、能执行、能审查的清晰指令。如果你照这个流程走完五分钟内应该能听到它的首次响应。下一步建议你找一件手头真实存在的小任务试试比如清理一段重复代码、补充一个缺失的错误处理逻辑而不是造一个 hello world。真实项目里踩出来的经验比任何演示都有用。