# 快速开始

> 从安装、登录认证到完成第一个 pi 会话的完整入门流程。

---

LLMS 索引： [llms.txt](/llms.txt)

---

本页带你从安装一路走到完成第一个实用的 pi 会话。

## 安装 {#install}

Pi 以 npm 包的形式分发：

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

`--ignore-scripts` 会在安装过程中禁用依赖的生命周期脚本。在常规 npm 安装下，Pi 不需要安装脚本。

### 卸载 {#uninstall}

使用安装 pi 时所用的包管理器来卸载。curl 安装器底层使用全局 npm，因此 curl 和 npm 安装的版本都用 npm 卸载：

```bash
# 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 包会保留在 `~/.pi/agent/` 中。

然后在想让 pi 处理的项目目录中启动它：

```bash
cd /path/to/project
pi
```

## 认证 {#authenticate}

Pi 可以通过 `/login` 使用订阅型提供商，也可以通过环境变量或认证文件使用 API 密钥型提供商。

### 方式一：订阅登录 {#option-1-subscription-login}

启动 pi 并运行：

```text
/login
```

然后选择一个提供商。内置的订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）以及 GitHub Copilot。

### 方式二：API 密钥 {#option-2-api-key}

在启动 pi 之前设置 API 密钥：

```bash
export ANTHROPIC_API_KEY=sk-ant-...
pi
```

也可以运行 `/login` 并选择一个 API 密钥型提供商，把密钥存入 `~/.pi/agent/auth.json`。

所有受支持的提供商、环境变量以及云端提供商的配置，请参阅[提供商](/book/pi/providers/)。

## 第一个会话 {#first-session}

pi 启动后，输入一个请求并按回车：

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

默认情况下，pi 会为模型提供四个工具：

- `read` - 读取文件
- `write` - 创建或覆盖文件
- `edit` - 修补文件
- `bash` - 运行 shell 命令

更多内置只读工具（`grep`、`find`、`ls`）可通过工具选项启用。Pi 在你当前的工作目录中运行，并且可以修改其中的文件。如果想要方便地回滚，请使用 git 或其他检查点工作流。

## 为 pi 提供项目指令 {#give-pi-project-instructions}

Pi 启动时会加载上下文文件。添加一个 `AGENTS.md` 文件，告诉它在这个项目中如何工作：

```markdown
# 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.override.md`，Pi 会加载它来取代该目录中的 `AGENTS.md` 或 `CLAUDE.md`。

修改上下文文件后，请重启 pi 或运行 `/reload`。

## 常用操作 {#common-things-to-try}

### 引用文件 {#reference-files}

在编辑器中输入 `@` 可以模糊搜索文件，也可以在命令行上直接传入文件：

```bash
pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"
```

图片或文本可以用 Ctrl+V 粘贴（Windows 上是 Alt+V）；图片也可以直接拖入支持的终端。

### 运行 shell 命令 {#run-shell-commands}

在交互模式下：

```text
!npm run lint
```

命令输出会发送给模型。使用 `!!command` 可以运行命令而不把输出加入模型上下文。

### 切换模型 {#switch-models}

使用 `/model` 或 Ctrl+L 为当前会话选择模型。在模型选择器中按 Ctrl+S，可以把高亮的模型保存为启动默认值。使用 `/thinking` 为当前会话选择思考级别；在该选择器中按 Ctrl+S 可保存启动默认的思考级别。使用 Shift+Tab 可以循环切换思考级别。使用 Ctrl+P / Shift+Ctrl+P 可以在限定范围（scoped）的模型之间循环切换。

### 稍后继续 {#continue-later}

会话会自动保存：

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

### 非交互模式 {#non-interactive-mode}

一次性提示可以这样运行：

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

## 后续步骤 {#next-steps}

- [使用 Pi](/book/pi/usage/)——交互模式、slash 命令、会话、上下文文件与 CLI 参考。
- [提供商](/book/pi/providers/)——认证与模型配置。
- [设置](/book/pi/settings/)——全局与项目配置。
- [快捷键](/book/pi/keybindings/)——快捷键与自定义。
- [Pi 包](/book/pi/packages/)——安装共享的扩展、技能、提示词模板和主题。

平台说明：[Windows](/book/pi/windows/)、[Termux](/book/pi/termux/)、[tmux](/book/pi/tmux/)、[终端配置](/book/pi/terminal-setup/)、[Shell 别名](/book/pi/shell-aliases/)。

---

反链：

- [Pi 用户手册](/book/pi/)
- [Pi 包](/book/pi/packages/)
- [使用 Pi](/book/pi/usage/)