PI 这个 Agent 运行时我前后装过七八次从 macOS 的 M 芯片笔记本到 WSL2 里的 Ubuntu再到团队那台常年不关的开发机踩过的坑基本能凑成一份完整的排错手册。趁着这个系列写到第六十二篇我把 LLM 之 Agent 这条线里最容易被低估的一环——PI 的安装指南——从头到尾捋一遍。安装这件事看似只是敲几行命令实际上它决定了你后面几个月的使用体验路径没配对你的智能体每次启动都会找不到技能目录权限没设好它会对着你的主目录乱翻模型参数没算清跑半个任务就上下文溢出。所以我把这篇定位成一份“装完之后能立刻干活”的指南而不是一份复制粘贴的 README。这篇内容适合三类人刚接触 LLM Agent、想找个终端里的编码智能体练手的初学者已经用过别的 Agent 工具、想横向对比 PI 差异的中级开发者以及需要在团队里批量部署、统一配置的工程负责人。全文按“认知—准备—安装—配置—自检—排错—升级”的顺序推进每一步我都写清了为什么这么做以及不做会出什么问题。你不需要提前懂太多但需要一台能连公网的机器和一点点命令行耐心。1. 先搞清楚 PI 到底是什么再决定怎么装1.1 从 LLM 到 AgentPI 落在整个链条的哪一层很多人第一次接触这类工具时会把“大模型”“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 系统环境清单哪些是硬要求哪些是锦上添花我把依赖分成三档你可以对着自查。项目硬性要求说明常见踩坑操作系统macOS 13 / Ubuntu 22.04 / WSL2Windows 原生不推荐cmd 下 TTY 行为异常Node20 以上推荐 22 LTS运行时底座18 及以下报语法错误Git2.30 以上源码安装、diff 查看、worktree 隔离老版本缺 worktree 支持包管理器npm 10 / pnpm 9安装与依赖解析pnpm 未装时源码构建失败终端支持真彩色输出可读性老终端出现乱码磁盘预留 2G 以上依赖与缓存缓存目录写满导致安装中断关于磁盘有一点容易被忽略包管理器的全局缓存在多次安装和升级后会膨胀得很快。我见过一台开发机的缓存目录堆到 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 pingnpm 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 加进 PATHzsh 用户改 ~/.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 --installUbuntu 上装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 --helppi 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_KEYsk-你的密钥 export PI_MODELyour-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_LEVELdebug pi # 或者把日志定向到文件方便事后翻 PI_LOG_LEVELdebug pi 21 | tee ~/.pi/logs/session-$(date %s).log日志里我最关注三类信息每次请求的 token 消耗、工具调用的入参出参、上下文压缩的触发时机。第一类帮你判断预算设置是否合理第二类在结果不符合预期时能直接看出它到底读了哪个文件第三类能解释“为什么它突然忘了前面说过的话”——多半是压缩把关键信息压掉了这时候你就该调整压缩策略比如把项目约定文件设为永不压缩。6. 常见问题与排查实录6.1 安装阶段的问题速查表症状大概率原因处理动作command not foundPATH 未生效或改错 shell 配置文件确认 shell 类型重开终端窗口EACCES权限错误曾用 sudo 装过全局包改用户级 prefix清掉旧目录依赖拉取超时源不可达或超时太短换就近公共镜像调大 fetch-timeout原生模块编译失败缺构建工具链macOS 装命令行工具Linux 装 build-essentialNode 版本报语法错版本低于 20用版本管理器升到 22 LTS数字签名/哈希校验失败缓存损坏npm cache verify必要时清缓存重装启动即退出无输出配置 JSON 语法错用node -e或在线工具校验 JSON6.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/clilatest # 需要锁版本时 npm install -g pi-agent/cli1.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 的技能体系从文件结构、元信息写法到调优策略把这块讲透。
PI Agent 安装指南：从 LLM 到终端智能体执行环境
PI 这个 Agent 运行时我前后装过七八次从 macOS 的 M 芯片笔记本到 WSL2 里的 Ubuntu再到团队那台常年不关的开发机踩过的坑基本能凑成一份完整的排错手册。趁着这个系列写到第六十二篇我把 LLM 之 Agent 这条线里最容易被低估的一环——PI 的安装指南——从头到尾捋一遍。安装这件事看似只是敲几行命令实际上它决定了你后面几个月的使用体验路径没配对你的智能体每次启动都会找不到技能目录权限没设好它会对着你的主目录乱翻模型参数没算清跑半个任务就上下文溢出。所以我把这篇定位成一份“装完之后能立刻干活”的指南而不是一份复制粘贴的 README。这篇内容适合三类人刚接触 LLM Agent、想找个终端里的编码智能体练手的初学者已经用过别的 Agent 工具、想横向对比 PI 差异的中级开发者以及需要在团队里批量部署、统一配置的工程负责人。全文按“认知—准备—安装—配置—自检—排错—升级”的顺序推进每一步我都写清了为什么这么做以及不做会出什么问题。你不需要提前懂太多但需要一台能连公网的机器和一点点命令行耐心。1. 先搞清楚 PI 到底是什么再决定怎么装1.1 从 LLM 到 AgentPI 落在整个链条的哪一层很多人第一次接触这类工具时会把“大模型”“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 系统环境清单哪些是硬要求哪些是锦上添花我把依赖分成三档你可以对着自查。项目硬性要求说明常见踩坑操作系统macOS 13 / Ubuntu 22.04 / WSL2Windows 原生不推荐cmd 下 TTY 行为异常Node20 以上推荐 22 LTS运行时底座18 及以下报语法错误Git2.30 以上源码安装、diff 查看、worktree 隔离老版本缺 worktree 支持包管理器npm 10 / pnpm 9安装与依赖解析pnpm 未装时源码构建失败终端支持真彩色输出可读性老终端出现乱码磁盘预留 2G 以上依赖与缓存缓存目录写满导致安装中断关于磁盘有一点容易被忽略包管理器的全局缓存在多次安装和升级后会膨胀得很快。我见过一台开发机的缓存目录堆到 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 pingnpm 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 加进 PATHzsh 用户改 ~/.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 --installUbuntu 上装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 --helppi 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_KEYsk-你的密钥 export PI_MODELyour-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_LEVELdebug pi # 或者把日志定向到文件方便事后翻 PI_LOG_LEVELdebug pi 21 | tee ~/.pi/logs/session-$(date %s).log日志里我最关注三类信息每次请求的 token 消耗、工具调用的入参出参、上下文压缩的触发时机。第一类帮你判断预算设置是否合理第二类在结果不符合预期时能直接看出它到底读了哪个文件第三类能解释“为什么它突然忘了前面说过的话”——多半是压缩把关键信息压掉了这时候你就该调整压缩策略比如把项目约定文件设为永不压缩。6. 常见问题与排查实录6.1 安装阶段的问题速查表症状大概率原因处理动作command not foundPATH 未生效或改错 shell 配置文件确认 shell 类型重开终端窗口EACCES权限错误曾用 sudo 装过全局包改用户级 prefix清掉旧目录依赖拉取超时源不可达或超时太短换就近公共镜像调大 fetch-timeout原生模块编译失败缺构建工具链macOS 装命令行工具Linux 装 build-essentialNode 版本报语法错版本低于 20用版本管理器升到 22 LTS数字签名/哈希校验失败缓存损坏npm cache verify必要时清缓存重装启动即退出无输出配置 JSON 语法错用node -e或在线工具校验 JSON6.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/clilatest # 需要锁版本时 npm install -g pi-agent/cli1.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 的技能体系从文件结构、元信息写法到调优策略把这块讲透。