第二章：安装与环境配置

在第一章中我们建立了对 Pi 的整体认知：它是一个极简但高度可扩展的终端编码 Agent 工具集。本章将带你完成从零到”Pi 能跑起来干活”的全过程，覆盖环境要求、四种安装方式、首次启动配置、更新与卸载、以及常见安装问题的排查。

2.1 环境要求

Pi 的设计哲学之一是”低依赖、低资源占用”，核心运行时只依赖 Node.js。但在安装之前，你需要确认以下环境条件是否满足。

2.1.1 Node.js 版本要求

Pi 基于 TypeScript 构建，运行在 Node.js 运行时之上。版本要求如下：

几条关键说明：

• node >= 22.19.0 是硬性要求。Pi 内部使用了 Node.js 22 引入的多项新特性（如原生 TypeScript 支持、新版 Fetch API 等），低于此版本将无法启动，会直接报错退出。
• 推荐使用 LTS 版本。当前 Node.js 22.x 是 Active LTS，Node.js 24.x 也已进入 LTS 通道。你可以使用 nvm、fnm、volta 等版本管理器来安装和切换 Node.js 版本。
• npm 不需要单独安装，Node.js 自带。

验证你的 Node.js 版本：

node --version
# 应输出 v22.19.0 或更高，例如 v22.20.0、v24.5.0

如果版本过低，使用 nvm 快速升级：

nvm install 22
nvm use 22
node --version  # 确认已切换

2.1.2 操作系统支持

Pi 对操作系统的支持情况如下：

关于 Windows 的特别说明：

Pi 不支持 Windows 原生环境（包括 PowerShell、CMD、Git Bash）。这不是”体验差一点”的问题，而是 Windows 的文件系统权限模型、进程管理、信号处理、pty 终端模拟等与 Unix 差异过大，Pi 的核心终端交互（pi-tui）和工具执行（pi-agent-core）在 Windows 原生环境下存在根本性不兼容。

如果你使用 Windows 作为主机系统，请通过 WSL2 运行 Pi。安装 WSL2 只需一条命令：

wsl --install -d Ubuntu-24.04

安装完成后在 WSL2 终端内按照本文档的 Linux 指引操作即可。WSL2 内的文件系统性能（尤其是 ext4 on vhdx）足以胜任日常编码工作；如果需要在 Windows 文件系统中操作代码，可以通过 WSL2 的 /mnt/c/ 路径访问，但建议将项目放在 WSL2 原生文件系统中以获得最佳 IO 性能。

2.1.3 Bun 可选支持

Bun 是一个兼容 Node.js 的 JavaScript 运行时，以其极快的安装速度和执行性能著称。Pi 对 Bun 的态度是：

• Bun 不是必需。标准的 Node.js + npm 组合完全可以运行 Pi，且是唯一经过全面测试的运行时。
• Pi 包本身兼容 Bun。如果你已经在项目中使用 Bun 作为包管理器和运行时，可以用 bun 替代 node 来运行 Pi 命令，但需注意以下几点：
  • 使用 Bun 安装依赖时速度更快（bun install 替代 npm install）。
  • 部分边缘场景下 Node.js 原生模块行为可能与 Bun 有细微差异，如遇到问题请先切回 Node.js 排查。
• 官方推荐以 npm 为主。本教程的所有示例均以 npm 为准；如果你选择使用 Bun，将 npm/npx 替换为 bun/bunx 即可。

2.1.4 包管理器选择

安装 Pi 本身需要使用以下任一包管理器：

四者任选其一即可，效果相同。本教程后续章节中如无特别说明，均以 npm 作为包管理器的示例。

2.1.5 硬件要求

Pi 自身的硬件开销极低：

• CPU：任何现代 x86_64 或 ARM64 处理器均可。Pi 本身不执行模型推理，所有 AI 计算都在远程 API 端完成。
• 内存：空闲内存 128 MB 即可稳定运行。实际占用通常在 50–100 MB 范围内（取决于当前会话的上下文长度和加载的 Extensions 数量）。
• 磁盘：Pi 本体约 50 MB（含依赖）。会话历史、Skills、配置等持久化数据通常不超过 100 MB。
• 网络：需要稳定的互联网连接以访问模型 API。离线状态下 Pi 可以启动（CLI 界面），但无法与 LLM 交互。

一个极端的参考数据：一台 5 美元/月的 VPS（1 vCPU、1 GB RAM、25 GB SSD）可以同时运行 Pi 和你的项目代码。这意味着你可以把 Pi 部署在云端，通过 SSH 远程使用，甚至配合 tmux/screen 保持长时运行。

2.2 安装方式

Pi 提供四种安装方式，从最简单到最灵活依次排列。本节按推荐程度从高到低逐一介绍。

2.2.1 方式一：npm 全局安装（推荐）

这是最推荐、最通用的安装方式。只需一条命令：

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

安装完成后，pi 命令即全局可用：

pi --version

关于 --ignore-scripts 参数

注意命令中有一个 --ignore-scripts 参数，它的作用是跳过 npm 包的 postinstall 脚本。

正常情况下 npm 全局安装一个包时，如果包的 package.json 中定义了 postinstall 钩子，npm 会自动执行它。Pi 的 postinstall 脚本会尝试做一些初始化操作（如创建目录结构、下载可选依赖等）。然而：

• 如果遇到网络问题（尤其是国内环境访问 npm registry 不稳定），postinstall 脚本可能超时或失败，导致整个安装过程报错。
• 有些企业环境或受限网络中，postinstall 脚本触发的额外网络请求会被防火墙拦截。

--ignore-scripts 让安装过程只下载并放置文件，不执行任何生命周期脚本，从而避免了上述问题。Pi 的首次启动时（执行 pi 命令）会自动检测并完成未完成的初始化，因此跳过 postinstall 不会影响最终使用。

提示：如果你在稳定的网络环境中安装，去掉 --ignore-scripts 也可以；如果遇到安装失败，加上它通常就能解决。

npm 安装验证

安装完成后，检查全局 npm 包列表中是否出现了 Pi：

npm list -g --depth=0 @earendil-works/pi-coding-agent
# 应输出类似：@earendil-works/pi-coding-agent@X.Y.Z

2.2.2 方式二：curl 安装脚本

Pi 提供了一行 curl 安装脚本，适合快速部署或 CI/CD 环境中使用：

curl -fsSL https://pi.dev/install.sh | sh

这条命令会：

1. 自动检测当前系统的操作系统和架构。
2. 检查 Node.js 版本是否满足要求，若不满足则提示安装/升级。
3. 下载并执行安装脚本，完成 npm 全局安装和基础配置。
4. 如果系统中没有 Node.js，部分平台的安装脚本会自动通过 nvm 或系统包管理器安装 Node.js（需要 sudo 权限）。

安全提醒：不要盲目使用 curl … | sh 方式安装（管道到 sh 存在安全风险）

行业惯例是以 curl ... | sh 方式安装，但请务必理解其中的安全风险：你正在将远程脚本直接交给 shell 执行。建议：

• 先下载脚本查看内容：curl -fsSL https://pi.dev/install.sh -o install.sh && cat install.sh
• 确认无异常后再执行：sh install.sh
• 或者直接使用 2.2.1 节的 npm 安装方式，更安全可控。

2.2.3 方式三：pnpm / yarn / bun 安装

如果你已经在项目中或全局使用 pnpm、yarn 或 bun，可以直接用对应的包管理器安装：

pnpm：

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

yarn：

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

bun：

bun add -g @earendil-works/pi-coding-agent

这三种方式和 npm 安装的效果完全一致，pi 命令会被注册到全局 PATH 中。不同之处仅在于：

• pnpm 使用硬链接节省磁盘空间，适合在一个机器上管理多个 Node.js 项目。
• yarn 如果你已经在项目中用 yarn，保持统一的包管理器可以减少心智负担。
• bun 安装速度最快，但如前所述，非官方主要测试目标。

2.2.4 方式四：从源码构建

如果你想参与 Pi 的开发、调试或自定义修改，可以从 GitHub 克隆源码并本地构建：

# 1. 克隆仓库
git clone https://github.com/earendil-works/pi.git
cd pi

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 链接到全局（可选，让 pi 命令全局可用）
npm link

构建完成后：

• 如果执行了 npm link，直接在终端输入 pi 即可使用。
• 如果没有 link，可以通过 npx pi 在项目目录中运行，或使用完整路径 node /path/to/pi/dist/cli.js。

源码目录结构速览

如果你是普通用户，不需要从源码构建；直接通过 2.2.1 的 npm 全局安装即可。源码构建主要面向希望定制 Pi 或向 Pi 贡献代码的开发者。

2.3 验证安装

无论采用哪种安装方式，安装完成后都应该验证 Pi 是否正确安装和可用。

2.3.1 版本检查

pi --version

正常输出示例：

pi v1.2.3
# 或
1.2.3

如果输出 command not found 或类似的未找到命令错误，说明 pi 未正确加入 PATH。请检查：

• npm 全局安装路径是否在 PATH 中。运行 npm config get prefix 查看全局安装路径，确认其 bin 子目录在 $PATH 中。
• 如果使用了 nvm，确认已执行 nvm use 切换到正确的 Node.js 版本。
• 重新打开终端或执行 hash -r（bash/zsh）刷新命令缓存。

2.3.2 帮助信息检查

pi --help

正常输出应包含 Pi 的用法概览、可用命令列表和全局选项。示例输出结构如下：

Usage: pi [options] [command]

Pi Coding Agent - A minimal terminal coding agent toolkit

Options:
  -v, --version        output the version number
  -h, --help           display help for command
  ...

Commands:
  chat [options]        Start an interactive chat session
  run [options] <task>  Run a single task non-interactively
  update [options]      Update Pi and installed packages
  ...

如果你能看到类似上述内容，说明 Pi 已正确安装并可执行。

2.3.3 首次试运行（不连接模型）

在不配置任何 API Key 的情况下，可以先进行一次”干跑”以验证 CLI 框架工作正常：

pi --help

这个命令不需要任何模型认证，纯粹测试命令行解析和基础模块加载。如果它能正常输出帮助信息，Pi 的核心运行时就是健康的。

2.4 首次启动与认证配置

Pi 安装好后，要让它真正干活——也就是和 LLM 交互——还需要配置模型认证。本节介绍首次启动的完整流程。

2.4.1 在项目目录运行 Pi

进入你的项目目录，运行：

cd /path/to/your-project
pi

首次运行 pi 时，由于尚未配置任何模型认证，Pi 会检测到这一状态并引导你完成设置。引导流程通常分为以下几个步骤：

1. Pi 检查是否存在有效的配置文件（~/.pi/config.yaml 或 ~/.pi/agent/config.yaml）。
2. 如果配置文件不存在或未包含认证信息，Pi 会提示选择认证方式。
3. 根据你的选择，Pi 引导你完成对应方式的设置。

2.4.2 认证方式一：API Key（推荐）

API Key 方式是最通用、最灵活的认证方式。具体操作：

步骤 1：获取对应供应商的 API Key

根据你想使用的模型供应商，前往其官方网站获取 API Key：

步骤 2：设置环境变量

将 API Key 写入 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.zprofile）：

# Anthropic (Claude)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# OpenAI (GPT)
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Google (Gemini)
export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxx"

# DeepSeek
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 多个供应商可以同时设置，Pi 会根据你的模型选择自动使用对应的 Key

保存后执行 source ~/.zshrc（或 source ~/.bashrc）使环境变量生效。

步骤 3：验证认证

重新启动 Pi 并发送一条简单消息：

pi run "say hello in chinese"

如果 Pi 能正常回复（例如”你好”），说明 API Key 认证已配置成功。

安全提醒

• 不要将 API Key 硬编码在代码仓库中。使用环境变量或 .env 文件（记得将 .env 加入 .gitignore）。
• 不要将 API Key 分享给他人。泄露后请立即在供应商网站上 revoke 旧 Key 并生成新 Key。
• 不同供应商的 Key 格式不同：Anthropic 以 sk-ant-api03- 开头，OpenAI 以 sk- 开头，Google 以 AIza 开头。

2.4.3 认证方式二：OAuth 登录

部分模型供应商支持 OAuth 登录，Pi 提供了内置的 /login 命令来简化此流程。

在 Pi 的交互会话中执行：

/login

Pi 会：

1. 列出支持 OAuth 登录的供应商（如 Anthropic、GitHub Copilot 等）。
2. 让你选择一个供应商。
3. 打开浏览器（或显示一个 URL 让你手动访问），引导你在供应商的网页中授权。
4. 获取授权后的 access token 并加密存储到本地。

OAuth 方式的好处是不需要手动复制粘贴 API Key，且部分供应商（如 Anthropic）通过 OAuth 可以获得与 Claude Pro/Max 订阅关联的配额，无需额外购买 API 额度。但 OAuth 的可用性取决于供应商是否开放了这一通道。

2.4.4 使用订阅服务

如果你已经订阅了以下服务，Pi 可以直接利用这些订阅中附带的 API 配额：

需要注意的计费区别：

• Claude Pro / ChatGPT Plus 是月付订阅制，适合高频使用；其 API 配额通常有速率限制但无额外按量费用。
• Anthropic / OpenAI 直连 API 是按量计费（pay-as-you-go），每次 API 调用都会产生费用。
• GitHub Copilot 的月付订阅包含一定的模型调用额度，但速率限制可能比直连 API 更紧。

建议首次使用时选择按量计费的 API Key 方式来测试和熟悉 Pi，后续再根据自己的使用频率决定是否需要升级到订阅服务。

2.4.5 认证验证与诊断

如果首次运行 Pi 时遇到认证相关错误，可以使用以下命令诊断：

# 检查当前配置中哪些供应商已配置
pi config list

# 检查环境变量是否设置
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

在 Pi 的交互会话中，还可以查看当前使用的模型和供应商：

/model

输出会显示当前激活的模型、供应商以及认证状态。

2.5 更新

Pi 和它的生态系统（Extensions、Skills、Skillsets 等）会持续更新。Pi 提供了内置的更新命令来保持所有组件处于最新状态。

2.5.1 更新 Pi 本身

pi update

这个命令会：

1. 检查 npm registry 上 @earendil-works/pi-coding-agent 的最新版本。
2. 与当前安装的版本对比。
3. 如果有新版本，自动执行 npm install -g @earendil-works/pi-coding-agent@latest 完成更新。
4. 输出更新日志或 changelog 链接。

2.5.2 更新 Pi 和所有已安装包

pi update --all

--all 参数会在更新 Pi 本身的基础上，同时检查并更新所有已安装的 Extensions、Skills 和 Themes 等包到最新版本。推荐定期（例如每周）执行一次 pi update --all 以保持整个 Pi 生态处于最新状态。

2.5.3 查看当前版本

pi --version       # Pi 本身版本
pi list            # 列出所有已安装的包及其版本

2.5.4 版本锁定

如果你希望 Pi 固定在某个特定版本（例如为了稳定性或兼容性），可以在安装时指定版本号：

npm install -g @earendil-works/pi-coding-agent@1.0.0

之后执行 pi update 时 Pi 会提示有新版本但不会自动升级（取决于 pi update 的具体实现逻辑；部分版本中 pi update 会直接升级到最新版）。如需完全锁定，可以使用 npm 的原生机制：

# 查看当前安装的精确版本
npm list -g @earendil-works/pi-coding-agent

# 如果要锁定版本不自动升级，可记录版本号并避免执行 pi update

2.6 卸载

2.6.1 标准卸载

要完全移除 Pi 的 npm 全局安装，执行：

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

这个命令会删除：

• pi 全局命令和所有相关 npm 包文件。
• npm 全局 node_modules 中的 Pi 本体及其依赖。

2.6.2 持久化数据目录

执行 npm uninstall -g 不会删除 Pi 在用户目录下的持久化数据。这些数据位于：

~/.pi/agent/

该目录包含以下内容：

设计决策说明：持久化数据与应用本体分离存放（而非放在 npm 的全局 node_modules 内），是为了确保卸载和更新 Pi 时不会意外丢失你的会话历史、自定义 Skills 和配置文件。如果你希望彻底清除 Pi 的所有痕迹，在卸载 npm 包后手动删除 ~/.pi/ 目录：

rm -rf ~/.pi

⚠️ 警告：此操作不可逆。删除 ~/.pi/ 将永久丢失所有会话历史和自定义配置。如果不确定将来是否还会使用 Pi，建议保留该目录或先备份。

2.7 常见安装问题排障

本节收集了安装和初次使用过程中最常见的问题及其解决方案。

2.7.1 Node.js 版本过低

现象：安装成功但运行 pi 时报错：

Error: Pi requires Node.js >= 22.19.0. Current version: v20.11.0.
# 或
SyntaxError: Unexpected token ...

原因：当前系统 Node.js 版本不满足 22.19.0 的最低要求。Pi 使用了 Node.js 22 才引入的语法特性，旧版 Node.js 无法解析。

解决方案：

# 使用 nvm 升级（推荐）
nvm install 22
nvm use 22
nvm alias default 22   # 设为默认版本

# 或使用 fnm
fnm install 22
fnm use 22
fnm default 22

# 或使用 volta
volta install node@22

# 验证
node --version
# 应输出 v22.x.x

如果未安装任何版本管理器，可以直接从 nodejs.org 下载安装最新的 LTS 版本。

2.7.2 Windows 原生环境限制

现象：在 Windows PowerShell、CMD 或 Git Bash 中运行 pi 时出现各种异常：

• 终端渲染乱码、光标位置错乱
• 工具执行（尤其是 bash 工具）报错或挂起
• 文件路径处理异常（\ vs / 分隔符问题）
• pty 终端模拟功能不可用

原因：如 2.1.2 节所述，Pi 不支持 Windows 原生环境。

解决方案：

唯一推荐的方案是使用 WSL2：

# 在 PowerShell（管理员）中执行
wsl --install -d Ubuntu-24.04

安装完成并重启后，在开始菜单中找到 “Ubuntu 24.04 LTS”，打开 WSL2 终端。在 WSL2 内部执行本文档的 Linux 安装指引即可。

如果你不希望或无法安装 WSL2，替代方案包括：

• 在 Windows 上安装 Linux 虚拟机（VirtualBox、VMware），在虚拟机内使用 Pi。
• 在便宜的 VPS 上安装 Pi，通过 SSH 远程使用。
• 使用 GitHub Codespaces 或其他云端开发环境。

2.7.3 网络连接与代理问题

现象：npm 安装过程中报网络相关错误：

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! FetchError: request to https://registry.npmjs.org/... failed
# 或
npm ERR! code ETIMEDOUT

原因：

1. 直接网络到 npm registry（registry.npmjs.org）不通（常见于国内网络环境）。
2. 系统代理设置不正确。
3. 企业防火墙拦截了 npm 的网络请求。

解决方案：

方案 A：配置 npm 镜像（国内用户首选）

# 使用 npmmirror 国内镜像（阿里云维护）
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 应输出 https://registry.npmmirror.com

设置镜像后重新执行安装命令。如果你想要更精细的控制（例如只对特定包使用镜像），可以使用 .npmrc 文件。

方案 B：配置代理

如果你在需要代理才能访问外网的环境中：

# 设置 npm 代理
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# 如果代理需要认证
npm config set proxy http://username:password@proxy.example.com:8080

# 取消代理设置
npm config delete proxy
npm config delete https-proxy

方案 C：配置 Pi 自身的 httpProxy

Pi 在配置文件中也支持设置 HTTP 代理，用于 Pi 在运行时访问模型 API（独立于 npm 的代理设置）。在 ~/.pi/agent/config.yaml 中配置：

httpProxy: "http://127.0.0.1:7890"   # 示例：Clash/Clash Verge 的默认端口

这样 Pi 发往模型供应商的 API 请求会经过代理，而 npm 安装过程不受影响。

方案 D：配置环境变量

某些情况下，设置系统级代理环境变量即可：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

将此配置写入 ~/.zshrc 或 ~/.bashrc 以持久化。

2.7.4 权限问题（EACCES / Permission Denied）

现象：全局安装时报权限错误：

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/@earendil-works
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '...'

原因：当前用户对 npm 全局安装目录没有写权限。常见于 Linux/macOS 上使用系统自带的 Node.js（通过 apt 或 Homebrew 安装），其全局安装路径为 /usr/local/lib/node_modules/，需要 sudo 权限。

解决方案（按推荐顺序）：

方案 A：使用 nvm 管理 Node.js（推荐）

nvm 将 Node.js 安装在用户目录下（~/.nvm/），全局 npm 包也安装在用户目录内，无需 sudo：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 重新打开终端或执行
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js
nvm install 22
nvm use 22

# 现在 npm install -g 不需要 sudo
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

方案 B：修改 npm 全局安装目录

将 npm 的全局安装目录改为用户目录下的路径：

# 创建用户级全局目录
mkdir -p ~/.npm-global

# 配置 npm 使用该目录
npm config set prefix ~/.npm-global

# 将 ~/.npm-global/bin 加入 PATH（写入 ~/.zshrc 或 ~/.bashrc）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 现在可以无 sudo 安装了
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

方案 C：使用 sudo（不推荐）

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

不推荐的原因：以 root 权限运行的 npm 脚本存在安全风险，且可能在未来引发更多权限问题。

2.7.5 macOS 上的额外安全提示

在 macOS 上首次运行 Pi 时，可能会遇到 Gatekeeper 的拦截：

"pi" cannot be opened because the developer cannot be verified.

这是因为 Pi 的二进制（如果是独立打包）或通过 npm 链接的命令未经过 Apple 的代码签名。解决方法：

1. 打开 系统设置 → 隐私与安全性。
2. 在页面底部找到关于 pi 的拦截信息，点击 仍要打开（Allow Anyway）。
3. 或在终端中执行：xattr -d com.apple.quarantine $(which pi)。

如果 Pi 是通过 npm 全局安装的（纯 Node.js 脚本），通常不会触发此问题；触发此提示的情况多见于通过独立 .pkg 或 .app 分发的安装方式。

2.7.6 安装后 pi 命令找不到

现象：安装没有报错，但终端中输入 pi 显示 command not found。

排查步骤：

1. 确认 npm 全局 bin 目录在 PATH 中：

   npm config get prefix
   # 输出例如 /usr/local 或 ~/.npm-global
   # bin 目录是 {prefix}/bin
   ls $(npm config get prefix)/bin/pi
   # 确认 pi 文件存在
   

2. 检查 PATH：

   echo $PATH | tr ':' '\n' | grep "$(npm config get prefix)/bin"
   # 如果没有输出，说明该 bin 目录未在 PATH 中
   

3. 如果不在 PATH 中，添加它：

   # zsh 用户
   echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   
   # bash 用户
   echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

4. 刷新命令缓存：

   hash -r   # bash/zsh
   rehash    # 如果使用 zsh
   

5. 如果使用了 nvm/fnm：确认当前 shell 中已激活 Node.js 版本：

   nvm current   # 或 fnm current
   which node
   which npm
   

2.7.7 通用排查策略

如果你遇到的问题不在上述列表中，按以下顺序排查：

1. 查看 Pi 自身的调试信息：

   # 以调试模式启动，输出详细日志
   pi --debug
   
   # 或设置环境变量
   PI_LOG_LEVEL=debug pi
   

2. 检查系统基础条件：

   node --version      # >= 22.19.0?
   npm --version       # 能正常输出?
   uname -a            # 操作系统和架构信息
   

3. 检查安装完整性：

   npm list -g @earendil-works/pi-coding-agent
   # 确认包状态正常（没有 extraneous、missing 等标记）
   

4. 重新安装：

   npm uninstall -g @earendil-works/pi-coding-agent
   npm cache clean --force
   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
   

5. 查阅官方资源：

   • Pi GitHub Issues — 搜索是否有相同问题的报告和解决方案。
   • 官方文档站点（如果有）获取最新的安装指引。

2.8 本章小结

本章覆盖了从零搭建 Pi 运行环境的完整过程：

• 环境要求：Node.js >= 22.19.0，macOS / Linux / WSL2，128 MB 内存即可，不支持 Windows 原生。
• 四种安装方式：npm 全局安装（推荐）、curl 脚本、pnpm/yarn/bun 安装、从源码构建。npm 安装时带上 --ignore-scripts 可避免网络问题。
• 验证安装：pi --version 和 pi --help 确认安装成功。
• 首次启动：在项目目录运行 pi，选择认证方式 — API Key（推荐）或 OAuth。支持直接使用 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 的订阅配额。
• 更新与卸载：pi update 和 pi update --all 保持最新；npm uninstall -g 卸载应用但保留 ~/.pi/agent/ 目录。
• 排障指南：覆盖了 Node.js 版本、Windows 限制、网络代理、权限问题等常见安装障碍及解决方案。

完成本章后，你的 Pi 应该已经安装完毕并能和 LLM 正常交互。下一章：第三章：快速入门：首次交互 将带你进行第一次真正的 Pi 会话——从发送第一条消息到理解 Pi 的交互模型和基本工作流。