4 快速开始
4.1 安装步骤
4.1.1 通过 npm 安装
Pi 以 npm 包的形式分发。在终端中运行以下命令进行全局安装：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent--ignore-scripts 参数会禁用安装过程中的依赖生命周期脚本。Pi 在正常 npm 安装时不需要这些脚本。
如果你使用 pnpm、Yarn 或 Bun，请使用对应的包管理器命令进行安装。Pi 支持所有主流 Node.js 包管理器。
4.1.2 通过 curl 安装
在 Linux 或 macOS 上，也可以使用官方安装脚本：
curl -fsSL https://pi.dev/install.sh | shcurl 安装器底层同样使用 npm 进行全局安装，因此后续的卸载方式与 npm 安装完全相同。
4.1.3 卸载
使用安装 Pi 时所用的包管理器进行卸载：
# npm 安装或 curl 安装
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 不会删除用户数据。设置、凭证、会话和已安装的 Pi 包会保留在 ~/.pi/agent/ 目录中。如果需要完全清除，请手动删除该目录。
4.2 认证方式
Pi 支持两种身份认证方式：订阅登录和 API Key。
4.2.1 方式一：订阅登录
如果你拥有以下任一订阅，可以直接通过 OAuth 登录：
- ChatGPT Plus/Pro（Codex）
- Claude Pro/Max
- GitHub Copilot
- xAI（Grok/X 订阅）
- OpenRouter
- Radius
启动 Pi 后，在交互模式中运行：
/login然后从列表中选择你的订阅提供商。OAuth 令牌会存储在 ~/.pi/agent/auth.json 中，过期时自动刷新。
OpenRouter 的登录方式略有不同——它会创建一个用户可控的 API Key，该 Key 从你的 OpenRouter 余额中扣费，不会自动过期。
4.2.2 方式二：API Key
如果你使用 API Key（如 Anthropic、OpenAI、Google 等），可以在启动 Pi 之前设置环境变量：
export ANTHROPIC_API_KEY=sk-ant-...
pi你也可以在 Pi 中运行 /login，选择 API Key 提供商，将 Key 存储到 ~/.pi/agent/auth.json 中：
# 也可以通过 auth.json 文件存储
# ~/.pi/agent/auth.json
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." }
}auth.json 文件创建时使用 0600 权限（仅用户可读写）。Auth 文件中的凭证优先于环境变量。
关于所有支持的提供商和环境变量名称，请参阅模型提供商章节。
4.3 首次会话
安装和认证完成后，进入你想要工作的项目目录并启动 Pi：
cd /path/to/project
pi启动后，输入你的需求并按 Enter：
Summarize this repository and tell me how to run its checks.Pi 会自动为模型提供四个内置工具：
| 工具 | 功能 |
|---|---|
read |
读取文件 |
write |
创建或覆盖文件 |
edit |
修补文件 |
bash |
执行 Shell 命令 |
Pi 在你的当前工作目录中运行，可以修改该目录中的文件。建议使用 Git 或其他检查点工作流，以便在需要时轻松回滚。
4.4 AGENTS.md 项目指令
Pi 在启动时会加载上下文文件来了解项目约定。在项目根目录创建 AGENTS.md 文件：
# Project Instructions
- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.Pi 会按以下顺序加载上下文文件：
~/.pi/agent/AGENTS.md：全局指令（适用于所有项目）- 从当前目录的父目录开始，逐级向上查找
AGENTS.md或CLAUDE.md - 当前目录中的
AGENTS.md或CLAUDE.md
修改上下文文件后，重启 Pi 或运行 /reload 命令即可重新加载。
4.5 常用操作
4.5.1 引用文件
在编辑器中输入 @ 可以模糊搜索项目文件：
# 在命令行中引用文件
pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"在交互模式中，直接输入 @ 即可触发文件搜索。支持粘贴图片（Ctrl+V，Windows 上为 Alt+V），也可将图片拖入支持的终端。
4.5.2 运行 Shell 命令
在交互模式中，以 ! 开头的输入会被当作 Shell 命令执行：
!npm run lint命令输出会发送给模型。如果你不想让输出进入模型上下文，使用 !! 前缀：
!!git status4.5.3 切换模型
/model # 打开模型选择器快捷键：
- Ctrl+L：打开模型选择器
- Shift+Tab：切换思考级别
- Ctrl+P / Shift+Ctrl+P：在已启用的模型间循环切换
4.5.4 会话恢复
Pi 自动保存所有会话：
pi -c # 继续最近的会话
pi -r # 浏览并选择历史会话
pi --name "my task" # 启动时设置会话名称
pi --session <path|id> # 打开特定会话在 Pi 内部，可以使用 /resume、/new、/tree、/fork 和 /clone 命令管理会话。
4.6 非交互模式
对于一次性提示（prompt），使用 -p / --print 模式：
# 直接输出结果并退出
pi -p "Summarize this codebase"
# 通过管道输入
cat README.md | pi -p "Summarize this text"
# 引用图片文件
pi -p @screenshot.png "What's in this image?"非交互模式非常适合在 Shell 脚本中集成 Pi。你还可以使用 --mode json 获取 JSON 事件流输出，或使用 --mode rpc 进行进程间通信。
4.7 完整示例
# 交互模式，带初始提示
pi "List all .ts files in src/"
# 非交互模式
pi -p "Summarize this codebase"
# 非交互模式，带管道输入
cat README.md | pi -p "Summarize this text"
# 带名称的一次性会话
pi --name "release audit" -p "Audit this repository"
# 指定模型
pi --provider openai --model gpt-4o "Help me refactor"
# 使用 provider 前缀
pi --model openai/gpt-4o "Help me refactor"
# 指定思考级别
pi --model sonnet:high "Solve this complex problem"
# 限制模型循环范围
pi --models "claude-*,gpt-4o"
# 只读模式
pi --tools read,grep,find,ls -p "Review the code"
# 禁用特定工具
pi --exclude-tools ask_question