$ pi –install

TL;DR。 Pi 在 npm 上以 @earendil-works/pi-coding-agent 发布。推荐路径是 npm install -g --ignore-scripts @earendil-works/pi-coding-agent；Bun、pnpm、Yarn 同样可用。v0.84.3 新增了 Windows 上的可选 powershell 工具——它通过 pwsh.exe 运行（参数为 -NoProfile -NonInteractive -ExecutionPolicy Bypass），并引入了一种实验性的「installer-managed」更新流程：分阶段下载、校验，再原子地激活新版本。更新命令包括 pi update（升级 CLI 本体）、pi update --extensions（升级已安装的包）、pi update --all（升级一切）。用 pi install npm:pkg@x.y.z 或 pi install git:host/user/repo@ref 固定版本，并通过 settings.json 中的 npmCommand 字段固定包管理器包装器。

本文汇集所有受支持的安装方式、更新矩阵，以及 v0.84.3 新引入的表面（PowerShell 工具、managed 更新、Windows 默认键位）。参考来源：Quickstart、Packages 文档、Windows Setup 页面，以及 v0.84.3 release notes。

用 npm 安装

Pi 是单一的 npm 包。--ignore-scripts 用于关闭 npm 的安装脚本钩子——pi 不需要它们，而钩子会让安装变慢：

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

这条命令会把 pi 放进全局 PATH。pnpm 与 Yarn 用法完全一致：

pnpm add -g @earendil-works/pi-coding-agent
yarn global add @earendil-works/pi-coding-agent

在 Windows 上，npm 装出来的不是可以直接执行的 pi 二进制，而是 pi.cmd shim——下文 Windows 一节会讨论这对扩展与子进程的影响。

用同一种包管理器卸载：

npm uninstall -g @earendil-works/pi-coding-agent
pnpm remove -g @earendil-works/pi-coding-agent
yarn global remove @earendil-works/pi-coding-agent

卸载 pi 不会删除 ~/.pi/agent/（Windows 下为 %USERPROFILE%\.pi\agent\）下的设置、凭证、会话与已安装的 pi 包，因此重装不会丢状态。

用 Bun 安装

Bun 直接替代 npm 完成安装与卸载：

bun install -g @earendil-works/pi-coding-agent
bun uninstall -g @earendil-works/pi-coding-agent

v0.84.3 修复了一个 Bun 专属的小坑：Bun 的 release 归档只在「wrapper 包」内部附带原生剪贴板二进制，而不再放到顶层。如果你在 Bun 装的版本上排查剪贴板丢失，要去找 wrapper 包的 bin/，而不是去 pi 二进制旁边找。

在 Windows 上安装

Windows 用户走与 macOS / Linux 相同的 npm 路线：

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

npm 在 PATH 上放置的是 pi.cmd shim，而不是可直接执行的 pi 二进制——这符合 npm 全局布局，但对试图通过绝对路径直接启动 pi 的扩展有影响：它们需要的是 pi.cmd shim，而不是底层的二进制。

Git 在 Windows 上的安装，按 pi 默认的 bash 工具查找 bash.exe 的顺序：

~/.pi/agent/settings.json 中自定义的路径（shellPath 字段）。
C:\Program Files\Git\bin\bash.exe（Git for Windows）。
PATH 上的 bash.exe（Cygwin、MSYS2、WSL）。

对绝大多数 Windows 用户来说，「Git for Windows」就够了，官方文档也明确把它列为推荐选项。

PowerShell 工具（v0.84.3）

v0.84.3 在 Windows 上额外提供了一个可选、原生的 powershell 工具。它在 pwsh.exe 可用时优先用 PowerShell 7，否则回落到 Windows PowerShell。每次调用都附带：

-NoProfile -NonInteractive -ExecutionPolicy Bypass

由管理员强制设定的执行策略仍然优先生效，因此在高安全策略的主机上，工具可能复现 PowerShell 自身的报错。! 与 !! 编辑器 shell 转义命令依旧走 Bash，不会被这个新工具接管——变动的只是模型能看到的那一面。

在 ~/.pi/agent/settings.json（Windows 下为 %USERPROFILE%\.pi\agent\settings.json）里改 defaultTools 即可启用：

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

如果想在对比期同时保留两个 shell：

{
  "defaultTools": ["read", "bash", "powershell", "edit", "write"]
}

不改 defaultTools 也不影响 Bash 的默认行为；defaultTools 只决定模型看到的工具集。

更新 pi 本体与扩展包

pi update 是统一的更新命令族，同时承担 CLI 与包的更新。不带任何参数的 pi update 升级 pi 本体；想更新包或调和 git ref 必须显式加 flag：

pi update              # 升级 pi 本体
pi update --all        # 升级 pi + 包 + 调和固定到 git ref 的包
pi update --extensions # 仅升级包并调和固定到 git ref 的包
pi update --models     # 仅刷新模型目录
pi update --self       # 升级 pi 本体（与裸命令等价）
pi update --self --force # 即便已是最新版也强制重装
pi update npm:@foo/bar  # 升级单个包
pi update --extension npm:@foo/bar

pi update 不会再次询问项目信任——更新流程在你的用户账户下直接进行，不会再弹 prompt。

Managed 更新（v0.84.3，实验性）

对于实验性的 installer-managed 安装，pi update 不再就地覆盖运行中的二进制，而是：

把目标 release 下载到一个「分阶段 + lockfile 托管」的位置。
校验这个分阶段 release。
原子地激活分阶段 release；如果激活失败，当前的 release 仍然完整保留在磁盘上。

这与 Nix、Cargo 等包管理器沿用的「staged-then-activate」模式一致，只是被移植到了 Node 运行时上。由于校验在激活之前发生，一个破损或不完整的更新不会替换掉能跑的二进制。Managed 安装 不支持 pi update --self --force；要修复一个 managed 安装，请重新跑一遍当初创建它的安装器。

Packages 文档提到了 managed 安装的存在，但截至本文写作时并未给出创建它所用的安装命令；当前唯一有官方文档的安装方式是 npm install -g。如果你已经有一个 managed 安装，那么每次跑 pi update 都会自动走「分阶段 + 校验 + 激活」流程。

固定版本与 git ref

两种固定方式都很常见：

固定到已发布的版本。 pi install npm:pkg@1.2.3 会把版本写进 settings.json。pi update --extensions 跳过被固定的包；若想执行只对账、不动固定值的操作，可以传 --all。
固定到 git ref。 pi install git:host/user/repo@ref 会把仓库克隆到 ~/.pi/agent/git/<host>/<path>（全局）或 .pi/git/<host>/<path>（项目）。pi update --extensions 与 pi update --all 会在不移动 ref 的前提下，对克隆进行调和；若想换到一个更新的 ref，重新跑 pi install git:host/user/repo@new-ref。

--all 的调和模式在「固定到的 commit 被 force-push 或 rebase 改写」时尤其有用——pi 会重置并清理克隆，如果存在 package.json 还会跑一次 npm install。

固定包管理器包装器

如果你的团队统一使用非 npm 的包管理器（mise、asdf、volta），可以在 settings.json 里把 pi 调用的包装命令写死：

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

不写 npmCommand 时，pi 在更新时会去 PATH 里找当时那个 npm——绝大多数情况没问题，但在某些机器上，它可能与最初安装 pi 的那个 npm 不是同一个二进制。

状态都放在哪

安装完成后，所有用户态数据都在 ~/.pi/agent/ 下：

路径	内容
`~/.pi/agent/settings.json`	用户级设置（默认工具、provider、信任、npmCommand）
`~/.pi/agent/auth.json`	已解析的 provider 凭证
`~/.pi/agent/sessions/`	每个会话的 JSONL 历史
`~/.pi/agent/extensions/`	用户范围的扩展包
`~/.pi/agent/skills/`、`~/.pi/agent/prompts/`、`~/.pi/agent/themes/`	其他用户范围的包
`~/.pi/agent/npm/`、`~/.pi/agent/git/`	安装缓存
`~/.pi/agent/trust.json`	已保存的项目信任决策

项目本地状态则落在 .pi/，位置在项目的 package.json 旁边（也就是 pi 启动时所在的项目根）。项目范围的安装受项目信任控制，由 defaultProjectTrust 以及 --approve / --no-approve 一次性开关把关。

部署前的小清单

确认 pi --version 是你打算安装的版本。
决定走 managed（实验性的 installer-managed 安装）还是 unmanaged（npm / Bun）——只有 managed 路径支持阶段式更新。
在 Windows 上，决定是否通过 defaultTools 启用 powershell 工具；把这个决定写进团队 onboarding 文档。
在 CI 里固定运行时版本（pi install npm:@earendil-works/pi-coding-agent@x.y.z），并通过 npmCommand 固定包管理器包装器。
对手动下载的二进制，校验其 SHA-256 与 GitHub release 中的 SHA256SUMS 文件一致。

Pi 的安装与更新