快速开始
本页会带你从安装走到一次有用的 pi 初始会话。
安装
Pi 以 npm 包形式发布：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
--ignore-scripts 会在安装期间禁用依赖生命周期脚本。普通 npm 安装不需要 Pi 运行安装脚本。
卸载
使用当初安装 pi 的包管理器。curl 安装器会使用全局 npm，因此 curl 和 npm 安装都用 npm 移除：
# curl installer or npm install -g
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/agent/ 中的设置、凭据、会话和已安装的 pi 包。
然后在你希望 pi 处理的项目目录中启动它：
cd /path/to/project
pi
身份验证
Pi 可以通过 /login 使用订阅提供商，也可以通过环境变量或 auth 文件使用 API-key 提供商。
选项 1：订阅登录
启动 pi 并运行：
/login
然后选择一个提供商。内置订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro (Codex) 和 GitHub Copilot。
选项 2：API key
在启动 pi 前设置 API key：
export ANTHROPIC_API_KEY=sk-ant-...
pi
你也可以运行 /login 并选择 API-key 提供商，将 key 存储在 ~/.pi/agent/auth.json 中。
所有支持的提供商、环境变量和云提供商设置请参阅提供商。
第一次会话
pi 启动后，输入一个请求并按 Enter：
Summarize this repository and tell me how to run its checks.
默认情况下，pi 会给模型四个工具：
read- 读取文件write- 创建或覆盖文件edit- 修补文件bash- 运行 shell 命令
额外的内置只读工具（grep、find、ls）可通过工具选项启用。Pi 在当前工作目录中运行，并可以修改其中的文件。如果希望轻松回滚，请使用 git 或其他检查点工作流。
给 pi 项目说明
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
修改上下文文件后，请重启 pi，或运行 /reload。
常见尝试
引用文件
在编辑器中输入 @ 可以模糊搜索文件，也可以在命令行上传入文件：
pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"
图片可以用 Ctrl+V（Windows 上为 Alt+V）粘贴，或拖入受支持的终端。
运行 shell 命令
在交互模式中：
!npm run lint
命令输出会发送给模型。使用 !!command 可以运行命令但不把输出加入模型上下文。
切换模型
使用 /model 或 Ctrl+L 选择模型。使用 Shift+Tab 循环切换思考级别。使用 Ctrl+P / Shift+Ctrl+P 在限定范围的模型间循环切换。
稍后继续
会话会自动保存：
pi -c # Continue most recent session
pi -r # Browse previous sessions
pi --name "my task" # Set session display name at startup
pi --session <path|id> # Open a specific session
在 pi 内部，使用 /resume、/new、/tree、/fork 和 /clone 管理会话。
非交互模式
用于一次性提示：
pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"
使用 --mode json 输出 JSON 事件，或使用 --mode rpc 进行进程集成。