安装与第一条命令

装之前看一眼 Node 版本

pi 是基于 Node.js 的 CLI 工具，用 npm 分发。安装前先确认你机器上的 Node 版本：

node --version

当前 pi npm 仓库提供两条版本线：

版本线	npm tag	最低 Node 要求	适用情况
最新稳定线	latest（0.84.1）	Node ≥ 22.19.0（<26）	大多数用户的首选
旧版兼容线	legacy-node20（0.74.2）	Node 20	暂时不能升级 Node 22 的过渡方案

如果你的 Node 是 v22 或更新，直接用 latest 线。如果还在 v20，用 legacy-node20 线也能正常工作，只是少了一些新版特性。

安装 pi：npm 一行搞定

最通用的安装方式是通过 npm 全局安装。打开终端，执行这一条命令：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 这个参数是干什么的？它让 npm 跳过依赖包里的生命周期脚本，提高安装安全性。pi 的正常功能不依赖这些脚本，所以放心加上。

装完之后验证一下：

pi --version

输出类似 0.84.1，说明安装成功。再试一个更完整的自检：

pi --help

这会打印出所有可用参数和命令。知道怎么查帮助，比记住所有参数更重要。

不想全局安装？用 npx

如果你只是临时用一下 pi，或者不想往全局塞东西，npx 也能跑：

npx @earendil-works/pi-coding-agent --version

npx 会自动下载、执行，用完就清理。不过频繁使用的话全局安装体验更好——每次省掉下载等待。

其他包管理器也行

如果你团队统一用 pnpm、Yarn 或 Bun，对应的安装命令如下：

# pnpm
pnpm add -g @earendil-works/pi-coding-agent

# Yarn
yarn global add @earendil-works/pi-coding-agent

# Bun
bun install -g @earendil-works/pi-coding-agent

用哪个装就用哪个卸载，别混着来。卸载命令镜像一下就行：

npm uninstall -g @earendil-works/pi-coding-agent

终端选对了体验更好

pi 的界面用 24 位 RGB 色彩渲染。大部分现代终端都支持 True Color，但如果你还在用老旧的终端模拟器，颜色可能会显得寡淡。

• macOS：iTerm2、Kitty、Warp
• Windows：Windows Terminal（强烈推荐）、WezTerm
• Linux：Kitty、WezTerm、Alacritty

不确定你当前终端支持不支持？运行这行：

echo $COLORTERM

输出 truecolor 或 24bit 就说明支持完整色彩。

第一次启动 pi

安装完成，该让它动起来了。挑一个你正在做的项目目录：

cd /path/to/your-project
pi

首次启动会看到 pi 的欢迎界面。此时你还没配 AI 提供商，所以 pi 暂时不能帮你干活——这个我们在下一章解决。

更新 pi 到最新版

pi 迭代很快，隔段时间跑一下更新是个好习惯：

# 只更新 pi 本身
pi update --self

# 更新 pi 和所有已安装的扩展包
pi update --all

# 更新内置模型目录
pi update --models

加 --force 可以强制重装，即使已经是最新版。