跳转到内容

10 分钟快速上手

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

本教程以 Pi 1.5.0 为参考。旧版 OpenAI 订阅入口与新版不同,见接入 OpenAI GPT;从旧版升级请查看1.5 新功能与升级。

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

你的上手进度

0 / 5 已完成

你需要准备什么

项目要求
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 使用当前目录发现项目资源、组织会话并作为工具默认工作位置。它还能以启动用户的权限访问其他路径;当前目录不是文件系统隔离边界。

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

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

方式 A:ChatGPT 订阅账号

OpenAI 已将 Pi 列为 Sign in with ChatGPT 的开源集成。符合条件的 ChatGPT Plus / Pro 用户,在新版 Pi 的输入框中执行:

/login openai

选择 Sign in with ChatGPT,在浏览器中登录并允许 Pi Use your ChatGPT plan。回到终端确认成功后,执行 /model 并选择 provider 为 openai 的 GPT 模型。这会使用已有计划额度,账户资格与可用模型以授权页面和 Pi 当前目录为准。

如果使用 0.83.0,订阅登录仍是 /login 中的 ChatGPT Plus/Pro (Codex)(openai-codex);从 0.99.0 起可使用新版 openai 登录。Claude、GitHub Copilot 等其他账号可以通过 /login 查看各自的登录方式。

方式 B:OpenAI API Key

在 OpenAI Platform创建 Key,并确认项目有可用 API 额度。可以在 Pi 中执行 /login openai、选择 Sign in with an API key 保存凭据,也可以在启动 Pi 前注入环境变量:

终端窗口
export OPENAI_API_KEY="<your-openai-api-key>"
pi

PowerShell 中使用:

终端窗口
$env:OPENAI_API_KEY="<your-openai-api-key>"
pi

启动后执行 /model 并选择 openai 下的 GPT 模型。API Key 按 API 用量计费,详见认证与模型。如果此前已用 ChatGPT 登录 openai,先执行 /logout 并选择 OpenAI,再重启 Pi,环境变量中的 Key 才会生效。

不要把真实密钥提交到仓库,也不要把密钥粘贴到对话内容中。其他供应商的变量名见 Providers。模型选择、默认值与远程登录步骤见接入 OpenAI GPT。

发出第一个请求

先用一个只读任务确认模型、文件读取和项目理解都正常。下面的文字要求不是权限隔离;如需限制工具,还要检查 MCP 和扩展,见安全边界:

先不要修改任何文件。阅读 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 是 continue:不挑,直接继续当前目录最近一次会话;-r 是 resume:先打开列表再挑。记不住就想:接着干用 c,挑着续用 r。Pi 默认自动保存会话;换过目录时 -c 找不到旧会话,改用 -r。

一次性任务

终端窗口
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 环境、可用的模型认证、第一场经过验证的会话,以及一套不会把模型回复直接当成完成结果的协作流程。

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