PI Agent 安装指南：从 LLM 到终端智能体执行环境

PI 这个 Agent 运行时我前后装过七八次，从 macOS 的 M 芯片笔记本到 WSL2 里的 Ubuntu，再到团队那台常年不关的开发机，踩过的坑基本能凑成一份完整的排错手册。趁着这个系列写到第六十二篇，我把 LLM 之 Agent 这条线里最容易被低估的一环——PI 的安装指南——从头到尾捋一遍。安装这件事看似只是敲几行命令，实际上它决定了你后面几个月的使用体验：路径没配对，你的智能体每次启动都会找不到技能目录；权限没设好，它会对着你的主目录乱翻；模型参数没算清，跑半个任务就上下文溢出。所以我把这篇定位成一份“装完之后能立刻干活”的指南，而不是一份复制粘贴的 README。

这篇内容适合三类人：刚接触 LLM Agent、想找个终端里的编码智能体练手的初学者；已经用过别的 Agent 工具、想横向对比 PI 差异的中级开发者；以及需要在团队里批量部署、统一配置的工程负责人。全文按“认知—准备—安装—配置—自检—排错—升级”的顺序推进，每一步我都写清了为什么这么做，以及不做会出什么问题。你不需要提前懂太多，但需要一台能连公网的机器和一点点命令行耐心。

1. 先搞清楚 PI 到底是什么，再决定怎么装

1.1 从 LLM 到 Agent：PI 落在整个链条的哪一层

很多人第一次接触这类工具时，会把“大模型”“Agent”“框架”三个词混着用，结果装到一半就迷失了。我用一个生活化的类比拆开讲：LLM 是一个博览群书但只会在纸上写字的人，你递给他一段话，他续写下一段，仅此而已——他看不见你的文件系统，也敲不了键盘。Agent 则是给这个人配了手、眼和记事本：手是工具调用（读写文件、执行命令），眼是上下文检索（把相关文件塞进提示），记事本是记忆与状态管理。

那 PI 是什么？PI 是承载这个“人”的那具身体，也就是常说的 harness（执行外壳）。它负责把用户的输入、模型输出、工具结果编排成一个循环：想 → 做 → 看结果 → 再想。热词里常有人问 harness 和 agent 的区别，我的回答一贯是：harness 是驱动器和协议层，agent 是跑在里面的策略。同一套策略换个 harness，行为会明显不同，因为工具集、权限模型、上下文压缩策略全变了。理解这一层，你就明白安装 PI 装的不是“一个模型”，而是一整套执行环境，这决定了后面所有配置项的优先级。

1.2 PI 的几个设计取向，直接影响安装方式

我在对比过若干同类工具后，认为 PI 有三个明显取向，值得在安装前先知道。

第一是终端原生。它没有强绑定的图形界面，默认以 CLI 形态工作，这意味着它对终端环境有要求：需要真实的 TTY，需要正常的行尾处理，需要能处理 ANSI 转义序列。Windows 原生 cmd 和 PowerShell 在这些点上历史包袱很重，这也是为什么后面我会强烈建议走 WSL2。

第二是技能可插拔，也就是 PI Skills 这套机制。技能不是硬编码在程序里的功能，而是一份份带元信息描述的说明文件，程序启动时扫描目录、读取描述、按需注入上下文。好处是你可以自己写技能，坏处是安装时必须把技能目录的位置配对，否则它会静默地什么技能都不加载——这个坑我后面会单独讲。

第三是审批优先。PI 默认对写操作和命令执行持谨慎态度，倾向于先给你看一眼再放行。这个设计对新手友好，但如果你在容器或 CI 里跑，就必须显式关掉交互式审批，否则任务会卡在等待输入上，看起来像“卡死”。

1.3 三类人适合现在就装，三类人建议先等等

先说适合的。第一类是日常要读别人代码、做小规模重构的后端或全栈开发者，PI 在“理解一个陌生模块”这件事上省下的时间非常可观。第二类是写脚本、做数据处理的分析岗，把重复的目录遍历、格式转换交给它做，边际收益很高。第三类是正在学习 Agent 原理的学生或转行者，亲手装一遍、改一次配置，比看十篇概念文章都管用。

再说建议先等等的。第一类是完全没有命令行经验的用户，配置文件和路径问题会消耗掉你大部分耐心，建议先花两小时熟悉基本命令。第二类是机器配置吃紧的情况，Agent 本身不重，但要同时跑编辑器、模型请求和构建过程，8G 内存的机器会很难受。第三类是对数据出境有硬性要求的场景，这一点必须提前和你的合规同事确认清楚，不要装完才想起来。

2. 安装前的环境盘点与依赖选型

2.1 运行时到底选 Node 还是 Bun

这是安装环节第一个真正的决策点。我的结论是：主力环境选 Node 22 LTS，追求启动速度可以另开一个 Bun 环境试，但不要把生产环境建在 Bun 上。理由很实在。

Node 22 进入 LTS 之后，原生 fetch、内置测试运行器、AbortSignal 的超时语义都已经齐备，绝大多数 Agent 类的包在它上面是“装了就能跑”。而 Bun 虽然冷启动快得离谱，但在原生模块编译、N-API 兼容、子进程 PTY 行为这几块，遇到边角问题的概率明显更高。Agent 这类程序的特点是重度依赖子进程和伪终端，恰恰踩在 Bun 兼容性最薄的区域。我实测过同一套配置在两边的表现：日常问答没差别，一旦涉及多轮命令行执行，Bun 偶尔会出现子进程句柄没回收、输出截断的情况。

如果你确实想两头都留着，建议用版本管理器隔离，不要全局乱装。

# macOS / Linux 下用 fnm，启动快、切换干净 curl -fsSL https://fnm.vercel.app/install | bash fnm install 22 fnm use 22 node -v # 应输出 v22.x.x

装完确认版本号。低于 20 的版本请果断升级，很多 Agent 包在 18 上会报语法错误，因为用到了较新的顶层 await 和结构化克隆。

2.2 系统环境清单：哪些是硬要求，哪些是锦上添花

我把依赖分成三档，你可以对着自查。

关于磁盘，有一点容易被忽略：包管理器的全局缓存在多次安装和升级后会膨胀得很快。我见过一台开发机的缓存目录堆到 6G 以上，最后是磁盘写满报错，而不是网络问题。所以预留空间这件事别抠。

2.3 镜像源与超时参数：让安装过程少一次中断

安装过程中断十有八九出在依赖拉取阶段。这里最有效的动作是配置一个就近的公共镜像源，并适当放宽超时。注意，改的是包管理器的 registry 配置，而不是别的什么东西，操作本身非常干净。

# 查看当前源 npm config get registry # 切换到就近的公共镜像 npm config set registry https://registry.npmmirror.com # 放宽超时与重试，弱网环境很有用 npm config set fetch-timeout 120000 npm config set fetch-retries 5 npm config set fetch-retry-maxtimeout 120000

改完立刻验证一次：

npm config get registry npm ping

npm ping返回 PONG 就说明链路通了。这一步别省，我遇到过配置文件写错、命令继续往下跑、最后在编译阶段才报错的案例，排查时间被拉长了好几倍。如果你在组织内网，请把源换成内部镜像地址，具体地址问你们的运维，别硬套公开地址。

3. 三种安装路径的实操全过程

3.1 路径一：全局包管理器安装，最省事也最容易出权限问题

这是绝大多数人的选择，一条命令的事。

npm install -g @pi-agent/cli

但这里有三个必须知道的前提。

第一，先核对包名和来源。生态里同名的仿冒包并不少见，名字差一个字符、少一个连字符的情况真实存在。我的习惯是先npm view <包名>看一眼维护者、最近发布时间、周下载量，三项都对得上再装。这一步花三十秒，能省掉后面清理恶意包的麻烦。

第二，绝对不要用 sudo 装全局包。sudo npm install -g会把包装到系统目录，后续升级、卸载都会遇到权限纠缠，更麻烦的是它可能让某些安装脚本以高权限执行。正确做法是给 npm 换一个用户级前缀：

# 创建用户级全局目录 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 把它的 bin 加进 PATH（zsh 用户改 ~/.zshrc） echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc # 现在再装，不需要 sudo npm install -g @pi-agent/cli

第三，如果装完提示command not found，九成是 PATH 没生效。先echo $PATH看有没有那个 bin 目录，再确认你是不是改了~/.bashrc却在 zsh 里测试。这种低级错我自己犯过不止一次。

3.2 路径二：源码安装，需要改代码或跟进特性时走这条

当你发现某个行为不符合预期、想读一眼源码，或者需要跟进尚未发版的功能时，源码安装是唯一路径。

git clone https://github.com/<org>/<repo>.git cd <repo> # 用 pnpm，这类项目通常是 monorepo 结构 corepack enable pnpm install # 构建产物 pnpm build # 链接到全局，方便在任意目录调用 npm link

几个实操要点。一是pnpm install阶段如果出现原生模块编译报错，先确认 Python 和构建工具链在不在，macOS 上xcode-select --install，Ubuntu 上装build-essential python3。二是pnpm build失败时不要急着删目录重来，先看错误出现在哪个子包，很多情况下只是某个子包的依赖没装上，单独进那个目录再 install 一次就行。三是npm link之后，如果你又改了源码，记得重新 build，否则跑的还是旧产物——我在这上面浪费过整个下午。

源码安装还有一个隐性好处：你可以把~/.pi之外的配置全部放进项目目录，做到每个项目一套独立配置，互不干扰。

3.3 路径三：容器化安装，团队批量复用的正解

如果要给团队统一环境，或者要在 CI 里跑，容器是最省心的。核心原则有三条：基础镜像选官方 Node 镜像、以非 root 用户运行、绝不把密钥烤进镜像。

FROM node:22-bookworm-slim # 构建期依赖，装完就删，控制镜像体积 RUN apt-get update \ && apt-get install -y --no-install-recommends git ca-certificates \ && rm -rf /var/lib/apt/lists/* # 非 root 用户 RUN useradd -m -u 1001 pi USER pi WORKDIR /home/pi/workspace # 全局包装到用户目录 ENV NPM_CONFIG_PREFIX=/home/pi/.npm-global ENV PATH=/home/pi/.npm-global/bin:$PATH RUN npm install -g @pi-agent/cli # 配置通过挂载或环境变量注入，不写进镜像 CMD ["pi", "--help"]

构建与运行：

docker build -t pi-agent:local . docker run --rm -it \ -v "$PWD":/home/pi/workspace \ -e PI_API_KEY \ -e PI_MODEL \ pi-agent:local pi init

密钥用-e PI_API_KEY从当前 shell 环境透传，而不是写死在 docker run 命令或 Dockerfile 里。这样镜像可以推到内部仓库复用，也不会因为镜像泄露导致凭证外流。还有一点，挂载工作目录时尽量只挂项目目录，不要图省事挂整个家目录，Agent 的文件操作范围会被无限放大。

3.4 安装结果验证：三条命令确认装对了

装完别急着进配置，先跑这三条。

# 1. 版本与二进制位置 which pi && pi --version # 2. 环境自检（很多 CLI 都有这个子命令） pi doctor # 3. 帮助信息，确认子命令列表符合预期 pi --help

pi doctor是最值得跑的一条。它会检查运行时版本、配置目录可写性、技能目录是否存在、网络连通性等。输出里如果有黄色或红色项，先解决再往下走。我自己的经验是，凡是跳过 doctor 直接进配置的，后面都会在某个莫名其妙的地方卡住。

4. 首次初始化与核心配置项逐条拆解

4.1 初始化向导：它会生成什么

pi init

这个命令通常会在你的家目录生成配置目录，典型结构是这样：

~/.pi/ ├── config.json # 主配置：模型、权限、上下文策略 ├── skills/ # 技能目录，启动时扫描 ├── sessions/ # 会话历史与状态 └── logs/ # 运行日志

同时它可能在当前项目下生成一个项目级配置（如.pi/config.json）。理解这两层配置的关系是后面所有配置工作的基础：用户级配置是默认值，项目级配置覆盖它，命令行参数覆盖项目级。我见过有人改了用户级配置却发现不生效，折腾半天才发现项目目录里躺着一个旧的覆盖项。

初始化向导最后通常会问你要不要写入 API 凭证。我的建议是选“否”，凭证用环境变量管理，原因后面讲。

4.2 模型接入：参数怎么填，上下文预算怎么算

模型接入这块，需要填的通常是四项：接口地址、凭证、模型标识、最大上下文。前两项按你的模型服务说明填，注意地址末尾不要多加斜杠，也不要少写版本前缀，这两处是最常见的 404 来源。

重点是第四项，也是最多人忽略的：上下文长度不是越大越好，你要给它留出预算。我给个实际的算法。

假设你接的模型窗口是 128K token。预算分配大致这样：系统提示与工具定义占 3K；技能说明与项目约定占 2K；对话历史占 15K；剩下的留给文件内容和命令输出。也就是说，真正给“看文件”的额度大约是 108K。但这里有个隐藏成本：每次工具返回的内容都会累加进历史，一次读取一个 500 行的文件大概消耗 6K token，跑十几次就吃掉大半。

所以我在配置里通常做两件事：一是把历史压缩阈值设在窗口的 60% 到 70%，到阈值就触发摘要压缩，而不是等撑满；二是给工具输出设上限，超长输出自动截断成头尾两段，中间用省略标记。后者看着粗暴，实际效果很好——Agent 需要的是定位信息，不是逐行通读。

{ "model": { "id": "your-model-id", "baseUrl": "https://your-endpoint/v1", "maxContextTokens": 128000, "compactThreshold": 0.65, "maxToolOutputTokens": 8000 } }

凭证不要写进这个文件，用环境变量：

# 写进 ~/.bashrc 或 ~/.zshrc export PI_API_KEY="sk-你的密钥" export PI_MODEL="your-model-id" # 让配置文件读取环境变量占位

如果你机器上会跑多个工具，建议把密钥统一存到一个只有自己可读的文件里再 source，权限设成 600。多工具共用一份明文密钥散落在各处，哪天要轮换就知道痛苦了。

4.3 权限与沙箱配置：这一节比模型配置更重要

模型配错了顶多答得差，权限配错了可能直接把你的项目改乱。PI 的权限配置我建议按“最小可用”原则来。

第一，工作目录白名单。把可读写范围限制在项目根目录，明确排除.ssh、.aws、.env这类敏感路径。第二，写操作默认审批。至少在熟悉它行为之前保持这个设置，等你能预判它要做什么了再考虑放宽。第三，命令执行白名单。把rm -rf、git push --force、涉及远程仓库改写的命令放进需二次确认的名单。第四，用 git worktree 做物理隔离，这是我最推荐的技巧：

git worktree add ../myproject-agent -b agent/refactor cd ../myproject-agent pi

这样 Agent 在独立的工作副本里折腾，你的主工作区完全不受影响。任务结束后你只需要 review 那个分支的 diff，满意就合并，不满意直接删掉整个 worktree。这个习惯养起来之后，我对 Agent 的信任度反而提高了，因为风险被物理隔离掉了。

4.4 配置优先级与团队统一配置

层级顺序再强调一次：命令行参数 > 项目级配置 > 用户级配置 > 内置默认。团队场景下，把模型标识、上下文预算、审批策略这些写进项目级配置并提交到仓库，每个人 clone 下来就是一致的行为。凭证、个人偏好这类不能共享的，留在用户级配置或环境变量里。

必须提交的：模型能力相关的预算参数、审批策略、技能目录约定。 绝对不能提交的：任何凭证、任何指向个人机器的绝对路径。

5. 安装后必做的连通性与能力自检

5.1 冒烟测试：三个动作验证端到端通了

装完配置好，别急着上真实任务，先做三个低成本验证。

第一个，纯对话。问一个不涉及文件的问题，比如让它解释一段你贴进去的正则。这一步验证的是凭证和接口后缀是否正确，失败通常报 401 或 404。

第二个，只读操作。让它读项目根目录的 README 并给出三句话总结。这一步验证的是文件读取权限、路径解析和上下文注入链路。如果它说找不到文件，检查你启动 PI 时所在的目录是不是项目根。

第三个，受控写操作。让它在一个新建的测试分支里创建一个说明文件。这一步验证审批流程和写权限。三步都过，说明安装环节彻底结束了。

提示：冒烟测试一定放在临时目录或 worktree 里做。我早期图快，直接在主分支根目录跑第一个测试，结果它顺手把某个配置文件格式化了一遍，diff 里混进一堆无关改动，review 的时候非常难受。

5.2 技能挂载：装完不等于能用

PI Skills 是这套工具最有价值的部分，也是安装后最容易哑火的部分。技能的工作原理是：启动时扫描技能目录，读取每个技能的元信息描述，按当前任务相关性决定注入哪些。所以如果你的技能目录路径配错了，它不会报错，只是技能列表为空，你完全察觉不到。

验证方法很简单，让它列出当前可用技能。如果列表为空，按这个顺序查：配置里的技能目录路径是不是绝对路径且存在；技能文件的元信息格式对不对（通常是文件头部一段带分隔符的键值描述，格式错一个冒号就解析不出来）；技能名有没有重名冲突，同名时后者可能被静默丢弃。

我自己写技能有个习惯：每个技能只解决一件事，描述里写清“什么时候用”和“什么时候不要用”。后者比前者重要，很多技能误触发都是因为没写排除条件。

5.3 日志与用量观测：出问题时你唯一的朋友

# 提高日志级别再启动 PI_LOG_LEVEL=debug pi # 或者把日志定向到文件，方便事后翻 PI_LOG_LEVEL=debug pi 2>&1 | tee ~/.pi/logs/session-$(date +%s).log

日志里我最关注三类信息：每次请求的 token 消耗、工具调用的入参出参、上下文压缩的触发时机。第一类帮你判断预算设置是否合理；第二类在结果不符合预期时能直接看出它到底读了哪个文件；第三类能解释“为什么它突然忘了前面说过的话”——多半是压缩把关键信息压掉了，这时候你就该调整压缩策略，比如把项目约定文件设为永不压缩。

6. 常见问题与排查实录

6.1 安装阶段的问题速查表

6.2 运行阶段的典型故障

报 401 未授权。九成是环境变量没被读到。先确认你是在同一个终端里 export 的，还是写进了配置文件但没 source。子进程和图形界面启动的程序经常读不到你交互式 shell 里的变量，这类问题优先怀疑环境。

报 404。接口地址少了或多了路径片段。多数服务需要保留版本前缀，末尾不要重复斜杠。把地址贴进配置文件前，先单独用 curl 验一次，能通再往里写，别让 Agent 帮你调接口地址。

任务进行到一半上下文溢出。说明预算分配太激进。把压缩阈值往下调，把工具输出上限压小，把历史保留轮数减少。这三招按顺序试，通常第一招就够。

请求频率被限制。表现为任务中途频繁停顿重试。适当降低并发、增加重试间隔，如果是在跑批量任务，考虑把任务拆成更小的批次串行执行，别一次性全推上去。

任务卡住不动，CPU 占用很低。大概率在等交互式审批，而当前环境没有可交互终端。容器和 CI 场景一定要显式关闭交互审批，或者把审批策略改为“仅高危命令确认”。

输出乱码或界面错位。终端对彩色输出支持不好。换个现代终端，或把输出模式调成纯文本。远程会话里尤其常见。

6.3 三个只有踩过才知道的经验

第一，不要在同一个目录同时跑两个实例。会话状态文件会互相覆盖，表现是两个任务的结果交叉污染，排查起来极其折磨。要用并行，就开两个 worktree。

第二，升级前先备份配置目录。配置格式在小版本之间也可能变，升级脚本未必能完美迁移。我现在的习惯是升级前cp -r ~/.pi ~/.pi.bak，一分钟的事。

第三，技能目录不要放在同步盘里。云盘客户端在后台改文件时间戳会触发反复重新扫描，启动变慢，偶尔还会读到写了一半的文件。技能目录放本地磁盘。

7. 升级、回滚与彻底卸载

7.1 升级与回滚

# 看当前版本和最新版本 npm outdated -g # 升级到最新 npm install -g @pi-agent/cli@latest # 需要锁版本时 npm install -g @pi-agent/cli@1.4.2

我的做法是主力机跟最新，团队环境锁一个验证过的版本号。锁版本这件事在团队协作里价值很大，能避免“我这能跑你那不行”的扯皮。升级后第一件事还是跑pi doctor，配置项有变化它会提示。

回滚很简单，装回旧版本号即可。但如果新版本已经改写了配置结构，回滚前记得把备份的配置恢复回去，否则旧版本读不懂新格式。

7.2 彻底卸载

npm uninstall -g @pi-agent/cli # 清理数据目录（确认不需要历史会话再删） rm -rf ~/.pi rm -rf ~/.npm-global/lib/node_modules/@pi-agent

数据目录里存着会话历史和日志，如果你平时靠它回溯工作过程，删之前先把需要的会话导出或备份。我一般保留sessions目录，只清缓存和日志。

8. 我的实际部署节奏与一点个人体会

这套东西我在三种环境里都落地过，最后稳定下来的节奏是这样的：开发笔记本上跟最新版，用来试新功能和写技能；团队开发机上锁一个已验收版本，所有人共用项目级配置；容器镜像按季度重建一次，构建的时候顺手把基础镜像的安全更新带上。三套环境互不干扰，出问题也容易定位是哪一层的事。

我个人最想分享的一条体会是：安装这件事的收益曲线不在“装上”，而在“配对”。我见过太多人十分钟装完，然后用两周时间跟各种奇怪行为较劲，最后得出结论说这东西不好用。实际上问题往往出在三个地方——技能目录没挂上、上下文预算没算、权限范围没收敛。这三个都是一次性投入，配好之后体验差异是断层的。

另外提一句，如果你打算长期用，建议从第一天就开始记录自己的技能库。每解决一个重复性问题，就把它固化成一个技能文件，写上适用场景和排除条件。半年后你会发现，这个技能库比工具本身更值钱。下一篇我会专门拆 PI 的技能体系，从文件结构、元信息写法到调优策略，把这块讲透。