本章介绍如何在不同平台上安装 Pi Agent并完成基础环境配置。环境要求在安装 Pi Agent 之前请确保你的系统满足以下要求依赖项最低版本说明Node.js建议 18 LTS 或更高Pi Agent 基于 Node.js 运行需要支持现代 JavaScript 特性的运行环境npm随 Node.js 自带用于安装 Pi Agent 和扩展包终端支持 True Color推荐 iTerm2macOS、Windows Terminal、Kitty、WezTerm检查 Node.js 是否已安装node --version输出类似v20.11.0查看 npm 是否同步安装安装 Node.js 会自带npm --version输出类似10.2.4如果你的 Node.js 版本低于 18请先升级。可以使用 nvmNode Version Manager来管理多个 Node.js 版本。安装方式一npm 全局安装这是最通用、最简单的安装方式适用于 macOS、Linux 和 Windows# 全局安装 Pi Agent # --ignore-scripts 禁用依赖包的生命周期脚本提高安装安全性 npm install -g --ignore-scripts earendil-works/pi-coding-agent安装完成后验证版本:pi --version安装完成后pi 命令就可以在终端中直接使用了。方式二curl 一键脚本在 Linux 或 macOS 上也可以使用官方安装脚本# 使用 curl 下载并执行安装脚本 curl -fsSL https://pi.dev/install.sh | sh这个脚本会自动检测你的系统并完成安装本质也是通过 npm 全局安装。方式三其他包管理器如果你使用 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卸载方法卸载 Pi Agent 时请使用与你安装时相同的包管理器# npm 或 curl 安装的用 npm 卸载 npm uninstall -g earendil-works/pi-coding-agent # pnpm 安装的 pnpm remove -g earendil-works/pi-coding-agent # Yarn 安装的 yarn global remove earendil-works/pi-coding-agent # Bun 安装的 bun uninstall -g earendil-works/pi-coding-agent卸载 Pi Agent 不会删除你的配置、凭证和会话记录。这些数据保存在 ~/.pi/agent/ 目录中。如需彻底清除可以手动删除该目录。终端建议Pi Agent 使用 24 位 RGB 色彩渲染终端界面推荐使用以下终端以获得最佳体验平台推荐终端说明macOSiTerm2、Kitty、Warp原生支持 True Color内嵌图片显示效果好WindowsWindows Terminal、WezTermWindows Terminal 是官方推荐的现代终端LinuxKitty、WezTerm、Alacritty都支持 True Color 和 GPU 加速检查你的终端是否支持 True Color$ echo $COLORTERM truecolor如果输出是 truecolor 或 24bit说明你的终端支持完整的色彩渲染。首次运行安装完成后进入一个项目目录并启动 Pi Agent$ cd /path/to/your-project $ pi首次启动时你会看到 Pi Agent 的欢迎界面。此时还没有配置 AI 提供商你需要先完成认证——这将在下一章详细说明。Pi Agent 在启动时会以当前工作目录cwd作为项目根目录。它对目录中的文件拥有读写权限建议在 git 版本控制下使用方便随时回滚修改。更新 Pi Agent保持 Pi Agent 更新到最新版本# 仅更新 Pi Agent 本身 pi update --self # 更新 Pi Agent 和所有已安装的扩展包 pi update --all # 更新模型目录获取最新的可用模型列表 pi update --models使用 --self --force 可以强制重装 Pi Agent即使当前已是最新版本$ pi update --self --force