快速开始

本页将带你从安装到完成第一次有用的 pi 会话。

安装

Pi 以 npm 包的形式分发：

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

--ignore-scripts 会在安装时禁用依赖的生命周期脚本。Pi 在正常 npm 安装中不需要 install 脚本。

卸载

使用安装 pi 时所用的包管理器。curl 安装器使用 npm 全局安装，因此 curl 和 npm 安装都通过 npm 卸载：

# curl 安装器或 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 工作的项目目录中启动 pi：

cd /path/to/project
pi

身份验证

Pi 可通过 /login 使用订阅提供商，或通过环境变量或 auth 文件使用 API 密钥提供商。

方式 1：订阅登录

启动 pi 并运行：

/login

然后选择提供商。内置订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro (Codex) 和 GitHub Copilot。

方式 2：API 密钥

在启动 pi 前设置 API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以运行 /login 并选择 API 密钥提供商，将密钥存储在 ~/.pi/agent/auth.json 中。

有关所有支持的提供商、环境变量和云提供商设置，请参阅 Providers。

第一次会话

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                  # 继续最近的会话
pi -r                  # 浏览之前的会话
pi --name "my task"    # 启动时设置会话显示名称
pi --session <path|id> # 打开特定会话

在 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 进行进程集成。

下一步

• Using Pi - 交互模式、斜杠命令、会话、上下文文件和 CLI 参考。
• Providers - 身份验证和模型设置。
• Settings - 全局和项目配置。
• Keybindings - 快捷键和自定义。
• Pi Packages - 安装共享扩展、技能、提示词和主题。

平台说明：Windows、Termux、tmux、Terminal setup、Shell aliases。