快速开始

本页会带你从安装开始，直到跑通第一次有用的 Pi 会话。

安装

Pi 通过 npm Package 分发：

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

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

卸载

使用安装 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 packages 仍会保留在 ~/.pi/agent/ 中。

然后在你希望 Pi 处理的项目目录中启动它：

cd /path/to/project
pi

认证

Pi 可以通过 /login 使用订阅型 Provider，也可以通过环境变量或 auth 文件使用 API key 型 Provider。

选项 1：订阅登录

启动 Pi，然后运行：

/login

然后选择一个 Provider。内置的订阅登录包括 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 Provider，把 key 保存到 ~/.pi/agent/auth.json。

有关所有支持的 Provider、环境变量和云 Provider 配置，请参阅 Providers。

第一次会话

Pi 启动后，输入请求并按 Enter：

Summarize this repository and tell me how to run its checks.

默认情况下，Pi 会给模型 4 个工具：

• 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 管理会话。

非交互模式

对于一次性 prompt：

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

下一步

• 使用 Pi - 交互模式、slash 命令、会话、上下文文件和 CLI 参考。
• Providers - 认证和模型配置。
• Settings - 全局和项目配置。
• Keybindings - 快捷键和自定义。
• Pi Packages - 安装共享的扩展、Skill、提示词和主题。

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