# 使用 Pi

> pi 的日常使用细节：交互模式、斜杠命令、会话管理、CLI 参考与设计原则。

---

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

---

本页面收录了不适合放在快速开始页面中的日常使用细节。

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

<p align="center"><img src="/book/images/interactive-mode.png" alt="交互模式" width="600"></p>

界面分为四个主要区域：

- **启动头部**——快捷方式、已加载的上下文文件、提示词模板、技能和扩展
- **消息区**——用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
- **编辑器**——你输入内容的地方；边框颜色指示当前的思考级别
- **底部栏**——工作目录、会话名称、token/缓存用量、费用、上下文用量和当前模型。总计包含助手回复、工具报告的用量以及摘要生成。

编辑器可以被内置 UI（如 `/settings`）或自定义扩展 UI 临时替换。

### 编辑器功能 {#editor-features}

| 功能 | 用法 |
|---------|-----|
| 文件引用 | 输入 `@` 对项目文件进行模糊搜索 |
| 路径补全 | 按 Tab 补全路径 |
| 多行输入 | Shift+Enter，Windows Terminal 上为 Ctrl+Enter |
| 复制回复 | 在 `/tree` 中 Ctrl+X 复制选中的消息；否则复制上一条助手消息；当 `fullscreenCopyOnSelect` 禁用时，复制全屏模式下活动的文本选区 |
| 图片 | 使用 Ctrl+V 粘贴（Windows 上为 Alt+V），或拖拽到终端中 |
| Shell 命令 | `!command` 运行命令并将输出发送给模型 |
| 隐藏 Shell 命令 | `!!command` 运行命令但不将输出发送给模型 |
| 外部编辑器 | Ctrl+G 打开 `externalEditor`、`$VISUAL`、`$EDITOR`、Windows 上的记事本或其他平台上的 `nano` |

所有快捷键及自定义方式参见[快捷键](/book/pi/keybindings/)。

## 斜杠命令 {#slash-commands}

在编辑器中输入 `/` 打开命令补全。扩展可以注册自定义命令，技能以 `/skill:name` 的形式提供，提示词模板通过 `/templatename` 展开。

| 命令 | 说明 |
|---------|-------------|
| `/login`、`/logout` | 管理 OAuth 或 API 密钥凭证 |
| [`/llama`](/book/pi/llama-cpp/) | 下载、加载和卸载 llama.cpp 路由器模型 |
| `/model` | 切换模型；在选择器中按 Ctrl+S 保存为启动默认值 |
| `/thinking` | 切换思考级别；在选择器中按 Ctrl+S 保存为启动默认值 |
| `/scoped-models` | 启用/禁用用于 Ctrl+P 循环切换的模型 |
| `/settings` | 主题、消息送达、传输方式等偏好设置 |
| `/resume` | 从之前的会话中选择 |
| `/new` | 开始新会话 |
| `/name <name>` | 设置会话显示名称 |
| `/session` | 显示会话文件、ID、消息、token 和费用 |
| `/tree` | 跳转到会话中的任意位置并从那里继续 |
| `/trust` | 保存项目信任决定，供未来会话使用 |
| `/fork` | 从之前的用户消息创建新会话 |
| `/clone` | 将当前活动分支复制为一个新会话 |
| `/compact [prompt]` | 手动压缩上下文，可选附带自定义指令 |
| `/copy` | 将上一条助手消息复制到剪贴板 |
| `/export [file]` | 将会话导出为 HTML 或 JSONL |
| `/import <file>` | 从 JSONL 文件导入并恢复会话 |
| `/share` | 上传为私有 GitHub gist，并生成可分享的 HTML 链接 |
| `/reload` | 重新加载快捷键、扩展、技能、提示词、主题和上下文文件 |
| `/hotkeys` | 显示所有键盘快捷键 |
| `/changelog` | 显示版本历史 |
| `/quit` | 退出 pi |

## 消息队列 {#message-queue}

你可以在智能体仍在工作时提交消息：

- **Enter** 将一条转向消息加入队列，在当前助手回合执行完其工具调用后送达。
- **Alt+Enter** 将一条后续消息加入队列，在智能体完成所有工作后送达。
- **Escape** 中止操作，并将排队的消息恢复到编辑器中。
- **Alt+Up** 将排队的消息取回编辑器。

在 Windows Terminal 中，Alt+Enter 默认是全屏快捷键。如果希望 pi 接收到该快捷键，请按[终端设置](/book/pi/terminal-setup/)中的说明重新映射。

可在[设置](/book/pi/settings/)中通过 `steeringMode` 和 `followUpMode` 配置送达方式。

## 会话 {#sessions}

会话会自动保存到 `~/.pi/agent/sessions/`，按工作目录组织。

```bash
pi -c                  # Continue most recent session
pi -r                  # Browse and select a session
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or session ID
pi --fork <path|id>    # Fork a session into a new session file
```

常用的会话命令：

- `/session` 显示当前会话文件和 ID。
- `/tree` 导航会话文件内的会话树，并可以总结被放弃的分支。
- `/fork` 从更早的用户消息创建新会话。
- `/clone` 将当前活动分支复制到一个新的会话文件。
- `/compact` 总结较旧的消息以释放上下文。

详情参见[会话](/book/pi/sessions/)和[上下文压缩](/book/pi/compaction/)。

## 上下文文件 {#context-files}

Pi 启动时会从以下位置加载 `AGENTS.md` 或 `CLAUDE.md`：

- `~/.pi/agent/AGENTS.md` 用于全局指令
- 从当前工作目录向上遍历的父目录
- 当前目录

如果某个目录包含 `AGENTS.override.md`，Pi 会改为加载它，而不再加载该目录中的 `AGENTS.md` 或 `CLAUDE.md`。来自其他目录的上下文文件仍照常分层叠加。

可以用上下文文件记录项目约定、命令、安全规则和偏好。使用 `--no-context-files` 或 `-nc` 禁用加载。

### 系统提示词文件 {#system-prompt-files}

替换默认系统提示词：

- 项目级：`.pi/SYSTEM.md`
- 全局：`~/.pi/agent/SYSTEM.md`

在上述任一位置放置 `APPEND_SYSTEM.md`，可以在默认提示词后追加内容而不替换它。

### 项目信任 {#project-trust}

在交互式启动时，如果项目文件夹包含项目本地设置、资源或项目级 `.agents/skills`，且在 `~/.pi/agent/trust.json` 中没有针对该文件夹或其父文件夹的已保存决定，pi 会先询问是否信任该项目。信任项目后，pi 才能加载 `.pi/settings.json` 和 `.pi` 资源、安装缺失的项目包，并执行项目扩展。

在做出信任决定之前，pi 只加载上下文文件、用户/全局扩展以及 CLI `-e` 扩展，以便它们能够处理 `project_trust` 事件。项目本地扩展、项目包管理的扩展和项目设置只有在项目被信任后才会加载。当切换到来自其他 cwd、且信任尚未在当前进程中确定的会话时，同样适用这一划分。

非交互模式（`-p`、`--mode json` 和 `--mode rpc`）不显示信任提示。在没有适用的已保存信任决定时，它们使用全局设置中的 `defaultProjectTrust`：`ask`（默认）和 `never` 会忽略这些项目资源，而 `always` 则信任它们。传入 `--approve`/`-a` 或 `--no-approve`/`-na` 可为单次运行覆盖项目信任。

如果没有扩展或已保存决定适用，则由 `defaultProjectTrust` 控制回退行为。在 `~/.pi/agent/settings.json` 中将其设为 `"ask"`、`"always"` 或 `"never"`，或通过 `/settings` 修改。

`pi config` 和包管理命令使用相同的项目信任流程，但 `pi update` 从不弹出提示。传入 `--approve` 可为单条命令信任项目本地设置，传入 `--no-approve` 则忽略它们。

在交互模式下使用 `/trust` 可以为未来会话保存项目信任决定，包括对直接父文件夹的信任。它只写入 `~/.pi/agent/trust.json`；当前会话不会重新加载，因此需重启 pi 才能生效。


## 导出与分享会话 {#exporting-and-sharing-sessions}

使用 `/export [file]` 将会话写入 HTML 文件。

使用 `/share` 上传一个私有 GitHub gist，并附带可分享的 HTML 链接。

如果你将 pi 用于开源工作，并希望发布会话以供模型、提示词、工具和评估研究使用，请参见 [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf)。它可以将会话发布到 Hugging Face 数据集。

## CLI 参考 {#cli-reference}

```bash
pi [options] [--] [@files...] [messages...]
```

### 包管理命令 {#package-commands}

```bash
pi install <source> [-l]     # Install package, -l for project-local
pi remove <source> [-l]      # Remove package
pi uninstall <source> [-l]   # Alias for remove
pi update [source|self|pi]   # Update pi only, or one package source
pi update --all              # Update pi and packages; reconcile pinned git refs
pi update --extensions       # Update packages only; reconcile pinned git refs
pi update --models           # Refresh model catalogs only
pi update --self             # Update pi only
pi update --extension <src>  # Update one package
pi list                      # List installed packages
pi config                    # Enable/disable package resources
```

这些命令用于管理 pi 包，`pi update` 还可以更新 pi CLI 本体。要卸载 pi 本体，请参见[快速开始](/book/pi/quickstart/#uninstall)。`pi config` 和项目包命令接受 `--approve`/`--no-approve`，用于为单条命令信任或忽略项目本地设置。`pi update` 从不因项目信任而弹出提示。

包来源与安全说明参见 [Pi 包](/book/pi/packages/)。

### 模式 {#modes}

| 标志 | 说明 |
|------|-------------|
| default | 交互模式 |
| `-p`、`--print` | 打印回复后退出 |
| `--mode json` | 以 JSON 行输出所有事件；参见 [JSON 模式](/book/pi/json/) |
| `--mode rpc` | 通过 stdin/stdout 的 RPC 模式；参见 [RPC 模式](/book/pi/rpc/) |
| `--export <in> [out]` | 将会话导出为 HTML |

在打印模式下，pi 还会读取管道传入的 stdin 并将其合并到初始提示词中：

```bash
cat README.md | pi -p "Summarize this text"
```

### 模型选项 {#model-options}

| 选项 | 说明 |
|--------|-------------|
| `--provider <name>` | 提供商，例如 `anthropic`、`openai` 或 `google` |
| `--model <pattern>` | 模型模式或 ID；支持 `provider/id` 以及可选的 `:<thinking>` |
| `--api-key <key>` | API 密钥，覆盖环境变量 |
| `--thinking <level>` | `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max` |
| `--models <patterns>` | 用于 Ctrl+P 循环切换的逗号分隔模式 |
| `--list-models [search]` | 列出可用模型 |

### 会话选项 {#session-options}

| 选项 | 说明 |
|--------|-------------|
| `-c`、`--continue` | 继续最近的会话 |
| `-r`、`--resume` | 浏览并选择一个会话 |
| `--session <path\|id>` | 使用指定的会话文件或部分 UUID |
| `--fork <path\|id>` | 将会话文件或部分 UUID 分叉为一个新会话 |
| `--session-dir <dir>` | 自定义会话存储目录 |
| `--no-session` | 临时模式；不保存 |
| `--name <name>`、`-n <name>` | 启动时设置会话显示名称 |

### 工具选项 {#tool-options}

| 选项 | 说明 |
|--------|-------------|
| `--tools <list>`、`-t <list>` | 以白名单方式指定可用的内置、扩展和自定义工具 |
| `--exclude-tools <list>`、`-xt <list>` | 禁用指定的内置、扩展和自定义工具 |
| `--no-builtin-tools`、`-nbt` | 禁用内置工具，但保留扩展/自定义工具 |
| `--no-tools`、`-nt` | 禁用所有工具 |

内置工具包括：`read`、`bash`、`powershell`（Windows）、`edit`、`write`、`grep`、`find`、`ls`。

### 资源选项 {#resource-options}

| 选项 | 说明 |
|--------|-------------|
| `-e`、`--extension <source>` | 从路径、npm 或 git 加载扩展；可重复使用 |
| `--no-extensions` | 禁用扩展发现 |
| `--skill <path>` | 加载技能；可重复使用 |
| `--no-skills` | 禁用技能发现 |
| `--prompt-template <path>` | 加载提示词模板；可重复使用 |
| `--no-prompt-templates` | 禁用提示词模板发现 |
| `--theme <path>` | 加载主题；可重复使用 |
| `--no-themes` | 禁用主题发现 |
| `--no-context-files`、`-nc` | 禁用 `AGENTS.md` 和 `CLAUDE.md` 发现 |

将 `--no-*` 与显式标志组合使用，可以忽略设置、精确加载所需资源。示例：

```bash
pi --no-extensions -e ./my-extension.ts
```

### 其他选项 {#other-options}

| 选项 | 说明 |
|--------|-------------|
| `--system-prompt <text>` | 替换默认提示词；上下文文件和技能仍会追加 |
| `--append-system-prompt <text>` | 在系统提示词后追加内容 |
| `--tui-mode <mode>` | TUI 模式：`regular`（默认）或实验性 `fullscreen` |
| `--use-theme <name[/name]>` | 为本次运行设置初始交互主题，不修改设置 |
| `--verbose` | 强制显示详细启动信息 |
| `-a`、`--approve` | 本次运行信任项目本地文件 |
| `-na`、`--no-approve` | 本次运行忽略项目本地文件 |
| `--` | 停止解析选项；其余参数作为提示词或 `@file` 输入 |
| `-h`、`--help` | 显示帮助 |
| `-v`、`--version` | 显示版本 |

在 `fullscreen` 模式下，对话记录在终端视口内滚动，而排队消息、工作状态、扩展小部件、编辑器和底部栏固定在底部。鼠标/触控板输入会滚动指针所在区域；键盘视口操作始终可用。行内图片在支持 Kitty 图形协议的终端（包括 Kitty 和 Ghostty）中可以正常显示。在 iTerm2 中，它们会渲染为文本占位符，因为 iTerm2 的行内图片协议无法在应用接管滚动期间删除或裁剪已放置的图片。在 `regular` 模式下，pi 使用主屏幕和终端自带的回滚缓冲区，iTerm2 中的行内图片可继续正常渲染。各终端的专属设置与变通方案参见[终端设置](/book/pi/terminal-setup/)。

在 `/settings` 中设置 **TUI 模式**，可以立即在 `regular` 和 `fullscreen` 之间切换，并为未来会话选择默认值。**全屏退出输出**控制退出全屏时是打印最终对话记录，还是恢复之前的屏幕并只打印会话恢复提示。

### 文件参数 {#file-arguments}

为文件名加上 `@` 前缀可将其包含在消息中：

```bash
pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"
```

### 示例 {#examples}

```bash
# Interactive with initial prompt
pi "List all .ts files in src/"

# Non-interactive
pi -p "Summarize this codebase"

# Prompt beginning with a dash
pi -p -- "- Summarize these points"

# Non-interactive with piped stdin
cat README.md | pi -p "Summarize this text"

# Named one-shot session
pi --name "release audit" -p "Audit this repository"

# Different model
pi --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
pi --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
pi --model sonnet:high "Solve this complex problem"

# Limit model cycling
pi --models "claude-*,gpt-4o"

# Read-only mode
pi --tools read,grep,find,ls -p "Review the code"

# Disable one extension or built-in tool while keeping the rest available
pi --exclude-tools ask_question
```

## 设计原则 {#design-principles}

Pi 保持核心小巧，将特定工作流的行为推送到扩展、技能、提示词模板和包中。

它有意不内置 MCP、子智能体、权限弹窗、计划模式、待办事项或后台 bash。你可以将这些工作流构建或安装为扩展或包，也可以使用容器和 tmux 等外部工具。

完整的设计理由请阅读[博客文章](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)。

---

反链：

- [快速开始](/book/pi/quickstart/)