Pi 快速上手

这份教程会带你从空白环境走到一次可验证的 Pi 会话。正常情况下需要约 10 分钟。

本教程适用版本 Pi 0.83.0 源码 c13ffe1877c32026-07-30

运行环境要求 Node.js >=22.19.0，推荐使用当前 LTS 版本。

你的上手进度

0 / 5 已完成

1. 确认运行环境Node.js 版本不低于 22.19.0。
2. 安装并验证 Pipi --version 能输出版本号。
3. 完成供应商认证通过 /login 或环境变量提供凭据。
4. 完成首个只读任务Pi 能概览项目并说明检查命令。
5. 加入项目约束用 AGENTS.md 记录命令、边界和偏好。

你需要准备什么

项目	要求
Node.js	>=22.19.0，推荐当前 LTS
npm	随 Node.js 安装，用于安装 Pi
Git	强烈推荐，用来查看和回滚修改
模型账号	支持的订阅账号，或供应商 API Key

Windows 用户还需要可用的 Bash。最省事的选择通常是安装 Git for Windows，并使用其中的 Git Bash。完整平台说明见 Pi Windows 文档。

第 1 步：安装并验证 Pi

先确认 Node.js 版本：

node --version

输出应为 v22.19.0 或更高。然后安装 Pi：

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

--ignore-scripts 会关闭依赖的生命周期脚本。Pi 的正常 npm 安装不需要运行这些脚本，这是上游推荐的安装方式。

确认命令可用：

pi --version
pi --help

如果终端提示 pi: command not found，关闭并重新打开终端，再检查 npm 的全局安装目录是否已经加入 PATH。

第 2 步：在项目目录启动

进入一个你熟悉、最好已经由 Git 管理的项目：

cd /path/to/your/project
git status --short
pi

Pi 会在当前目录工作。它能读取、创建、编辑文件并运行 shell 命令，因此启动目录就是最重要的作用域。

如果 Pi 询问是否信任项目，只对你自己创建或已经检查过的仓库选择信任。项目信任控制 .pi 配置、扩展和技能是否加载，不限制 Pi 对文件和 shell 的系统权限。

第 3 步：认证并完成首个任务

方式 A：订阅账号

在 Pi 的输入框中执行：

/login

然后选择供应商。内置订阅登录包括 ChatGPT Plus/Pro（Codex）、Claude Pro/Max 和 GitHub Copilot。完成浏览器或设备登录后，回到终端。

方式 B：API Key

也可以在启动 Pi 前设置供应商环境变量：

export ANTHROPIC_API_KEY="<your-api-key>"
pi

PowerShell 中使用：

$env:ANTHROPIC_API_KEY="<your-api-key>"
pi

不要把真实密钥提交到仓库，也不要把密钥粘贴到对话内容中。其他供应商的变量名见 Providers。

不确定订阅登录、环境变量和 CI 应该怎么选？查看认证与模型。

发出第一个请求

先用一个只读任务确认模型、文件读取和项目理解都正常：

先不要修改任何文件。阅读 README、包管理文件和项目入口，
概览这个项目，并告诉我应该运行哪些检查命令。

你应该看到 Pi 读取少量文件，然后返回项目结构和可执行命令。再开一个终端确认没有意外修改：

git status --short

这就是第一个可见结果。安装、认证、工具调用和模型回复链路已经打通。

第 4 步：加入项目说明

在项目根目录添加 AGENTS.md，把团队已经确定的规则写清楚：

# Project Instructions

- 使用仓库现有的包管理器，不要生成第二种 lockfile。
- 修改代码后运行 `pnpm check`。
- 不执行生产部署、数据迁移或发布命令。
- 开始修改前先说明计划；完成后列出验证结果。

Pi 会从父目录到当前目录加载 AGENTS.md 或 CLAUDE.md。修改说明文件后，在 Pi 中执行：

/reload

项目说明应该记录真实命令和稳定约束，不要堆放一次性任务。

第 5 步：完成一次安全修改

先创建可回滚的 Git 分支：

git switch -c chore/pi-first-task

然后把任务写成“范围 + 结果 + 验证”：

修复 README 中失效的本地链接，只修改 Markdown 文件。
完成后检查所有相对链接，并给我看修改摘要。

Pi 完成后，在另一个终端检查：

git status --short
git diff --check
git diff --cached --check
git diff
git diff --cached

状态为 ?? 的未跟踪文件不会出现在普通 diff 中，需要单独检查。再运行项目自己的检查命令。确认结果后，才由你决定是否提交。

日常协作循环

一个可靠的 Pi 工作循环通常只有五步：

1. 建立检查点：确认工作树状态，必要时创建分支或提交。
2. 缩小范围：说明允许修改的文件、完成标准和禁止动作。
3. 让 Pi 执行：工作中可以发送补充或纠偏消息。
4. 独立验证：查看 git diff，运行测试、类型检查或构建。
5. 保留或回滚：你决定提交、继续修改或撤销。

Pi 不会替你建立权限边界。详细原因见权限与安全边界。

常用操作

引用文件

在编辑器中输入 @ 搜索文件，或从命令行直接传入：

pi @README.md "概览这份文档"
pi @src/app.ts @src/app.test.ts "一起审查实现和测试"

执行 shell 命令

在交互模式中：

!pnpm test

单个 ! 会把命令输出加入模型上下文。使用 !!command 时，命令仍会执行，但输出不会发送给模型。

继续之前的会话

pi -c
pi -r
pi --name "修复登录流程"

-c 继续最近会话，-r 打开会话选择器。Pi 默认自动保存会话。

一次性任务

pi -p "概览这个代码库"
cat README.md | pi -p "提炼安装步骤"

需要结构化事件时使用 --mode json；需要从其他程序控制 Pi 时使用 --mode rpc。

完整列表见命令速查。

如何确认已经上手

完成下面四项就算通过：

• pi --version 能输出版本。
• /login 或 API Key 能提供可用模型。
• 只读首任务能返回项目概览，工作树保持不变。
• 一个小修改能通过 git diff 和项目检查命令验证。

故障排查

Node.js 版本不满足要求

症状通常是安装警告、语法错误或启动失败。运行：

node --version

升级到 Node.js 22.19 或更高，推荐 Node.js 24 LTS，然后重新安装 Pi。

没有可用模型或找不到凭据

在 Pi 中重新执行：

/login
/model

如果使用环境变量，确认它已在启动 Pi 的同一个 shell 中设置。可以用下面的命令检查模型目录：

pi --list-models

项目扩展或设置没有加载

你可能拒绝了项目信任，或在非交互模式中没有已保存的信任决策。先审查 .pi/ 和 .agents/skills/，再在交互模式使用 /trust 并重启 Pi。一次性覆盖可使用 --approve 或 --no-approve。

Windows 无法运行 shell 工具

确认 Git Bash、Cygwin、MSYS2 或 WSL 中至少一个可用。优先从 Git for Windows 提供的 Bash 开始。

快捷键不工作

不同终端对 Shift+Enter、Alt+Enter 等组合键的处理不同。查看 Terminal setup 并按所用终端配置。

你已经完成了什么

你现在拥有一个可运行的 Pi 环境、可用的模型认证、第一场经过验证的会话，以及一套不会把模型回复直接当成完成结果的协作流程。

下一步先读日常使用与会话，学习运行中纠偏、恢复和分支。把命令速查作为参考；在增加项目扩展前阅读权限与安全边界。