# 使用 Pi 完整指南

作者：吉祥法师

## 交互模式

Pi 的交互界面由四个主要区域构成，每个区域承担特定的功能角色。启动头部区域显示快捷键、已加载的上下文文件、提示模板、技能和扩展程序；消息区域展示用户消息、助手回复、工具调用及其结果、通知、错误信息和扩展界面；编辑器是输入文本的区域，其边框颜色会反映当前的思考级别；底部区域则显示工作目录、会话名称、令牌与缓存使用量、成本、上下文使用情况以及当前模型信息。统计总量涵盖了助手回复、工具报告的使用量以及摘要生成所消耗的资源。编辑器可以被内置界面（如 `/settings` 设置）或自定义扩展界面临时替换。

### 编辑器核心功能

编辑器提供了一系列提升效率的功能特性。文件引用通过输入 `@` 符号触发模糊搜索项目文件；路径补全使用 Tab 键完成；多行输入通过 Shift+Enter（Windows Terminal 使用 Ctrl+Enter）实现；复制助手回复使用 Ctrl+X，在 `/tree` 视图中可复制选中消息；图片支持通过 Ctrl+V（Windows 使用 Alt+V）粘贴或直接拖拽到终端；Shell 命令通过 `!command` 执行并将输出发送给模型，而 `!!command` 则执行命令但不发送输出；外部编辑器通过 Ctrl+G 启动，依次调用 `externalEditor`、`$VISUAL`、`$EDITOR`（Windows 使用记事本，其他系统使用 nano）。

### 斜杠命令体系

在编辑器中输入 `/` 即可打开命令补全菜单，扩展程序可注册自定义命令，技能以 `/skill:name` 形式调用，提示模板通过 `/templatename` 展开。核心命令包括：`/login` 和 `/logout` 用于管理 OAuth 或 API 密钥凭证；`/llama` 管理 llama.cpp 路由器模型的下载、加载和卸载；`/model` 切换当前模型；`/scoped-models` 启用或禁用 Ctrl+P 循环切换的模型；`/settings` 调整思考级别、主题、消息投递和传输方式；`/resume` 浏览并恢复历史会话；`/new` 开启新会话；`/name` 设置会话显示名称；`/session` 展示会话文件、ID、消息数、令牌数和成本；`/tree` 支持跳转到会话任意节点继续对话；`/trust` 保存项目信任决策；`/fork` 从历史用户消息创建新会话；`/clone` 复制当前活动分支到新会话；`/compact` 手动压缩上下文（可附加自定义指令）；`/copy` 复制最后一条助手消息；`/export` 导出会话为 HTML 或 JSONL 格式；`/import` 从 JSONL 文件导入并恢复会话；`/share` 上传为私有 GitHub gist 并生成可分享的 HTML 链接；`/reload` 重新加载键位绑定、扩展、技能、提示、主题和上下文文件；`/hotkeys` 显示全部快捷键；`/changelog` 展示版本历史；`/quit` 退出程序。

## 消息队列机制

Pi 支持在代理工作期间提交消息。按 Enter 键会将引导消息排入队列，在当前助手回合完成工具调用后投递；Alt+Enter 排入后续消息，在代理完成所有工作后投递；Escape 键中止当前操作并将排队的消息恢复到编辑器；Alt+Up 将排队消息取回编辑器。在 Windows Terminal 中，Alt+Enter 默认为全屏功能，需在终端设置中重新映射以让 Pi 接收此快捷键。消息投递可通过设置中的 `steeringMode` 和 `followUpMode` 配置。

## 会话管理

会话自动保存至 `~/.pi/agent/sessions/` 目录，按工作目录组织。关键命令参数：`pi -c` 继续最近会话；`pi -r` 浏览选择会话；`pi --no-session` 进入临时模式（不保存）；`pi --name "任务名"` 启动时设置会话名称；`pi --session <路径|ID>` 使用指定会话文件或 ID；`pi --fork <路径|ID>` 分叉会话到新文件。有用的会话命令包括 `/session`（显示文件与 ID）、`/tree`（导航会话树并可总结废弃分支）、`/fork`（从早期消息创建会话）、`/clone`（复制当前活动分支）、`/compact`（总结旧消息释放上下文）。

## 上下文文件与系统提示

Pi 启动时从 `~/.pi/agent/AGENTS.md`（全局指令）、父目录（从当前工作目录向上遍历）和当前目录加载 AGENTS.md 或 CLAUDE.md 文件。特定目录存在 `AGENTS.override.md` 时，Pi 将优先加载该文件替代同目录的 AGENTS.md 或 CLAUDE.md，其他目录的上下文文件保持正常分层加载。上下文文件用于定义项目约定、命令、安全规则和偏好设置，可通过 `--no-context-files` 或 `-nc` 参数禁用加载。

系统提示文件方面，项目可通过 `.pi/SYSTEM.md`，全局通过 `~/.pi/agent/SYSTEM.md` 替换默认系统提示；在任一位置放置 `APPEND_SYSTEM.md` 可追加内容而不替换默认提示。

## 项目信任机制

交互启动时，如果项目文件夹包含项目本地设置、资源或项目 `.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` 可在单次运行中覆盖信任决策；`/trust` 命令保存信任决策供后续会话使用（仅写入 `~/.pi/agent/trust.json`，当前会话需重启后生效）。

## 会话导出与共享

`/export [file]` 将会话导出为 HTML 格式，`/share` 上传为私有 GitHub gist 并生成分享链接。开源项目用户可参考 `badlogic/pi-share-hf` 将会话发布到 Hugging Face 数据集，用于模型、提示词、工具和评估研究。

## CLI 参考

### 包管理命令

`pi install <源>` 安装包（`-l` 为项目本地安装）；`pi remove` 和 `pi uninstall` 移除包；`pi update [源|self|pi]` 仅更新 Pi 或指定包源；`pi update --all` 更新 Pi 和包并协调固定 git 引用；`pi update --extensions` 仅更新包并协调固定 git 引用；`pi update --models` 刷新模型目录；`pi update --self` 仅更新 Pi；`pi update --extension <源>` 更新单个包；`pi list` 列出已安装包；`pi config` 启用/禁用包资源。`pi config` 和项目包命令支持 `--approve`/`--no-approve` 参数。

### 运行模式

默认进入交互模式；`-p`、`--print` 打印响应后退出；`--mode json` 以 JSON 行格式输出所有事件；`--mode rpc` 通过标准输入输出运行 RPC 模式；`--export <输入> [输出]` 将会话导出为 HTML。打印模式下支持管道输入：`cat README.md | pi -p "总结这段文本"`。

### 模型选项

`--provider <名称>` 指定提供商（如 `anthropic`、`openai` 或 `google`）；`--model <模式>` 设定模型模式或 ID，支持 `提供商/ID` 及可选 `:思考级别` 后缀；`--api-key <密钥>` 覆盖环境变量中的 API 密钥；`--thinking <级别>` 设置思考级别（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`）；`--models <模式>` 为 Ctrl+P 循环指定逗号分隔的模式；`--list-models [搜索]` 列出可用模型。

### 会话选项

`-c`、`--continue` 继续最近会话；`-r`、`--resume` 浏览选择会话；`--session <路径|ID>` 使用特定会话文件或部分 UUID；`--fork <路径|ID>` 分叉会话到新文件；`--session-dir <目录>` 自定义会话存储目录；`--no-session` 临时模式不保存；`--name <名称>`、`-n <名称>` 启动时设置会话名称。

### 工具选项

`--tools <列表>`、`-t <列表>` 白名单特定内置、扩展和自定义工具；`--exclude-tools <列表>`、`-xt <列表>` 禁用特定工具；`--no-builtin-tools`、`-nbt` 禁用内置工具但保留扩展/自定义工具；`--no-tools`、`-nt` 禁用所有工具。内置工具包括：`read`、`bash`、`edit`、`write`、`grep`、`find`、`ls`。

### 资源选项

`-e`、`--extension <源>` 从路径、npm 或 git 加载扩展（可重复）；`--no-extensions` 禁用扩展发现；`--skill <路径>` 加载技能（可重复）；`--no-skills` 禁用技能发现；`--prompt-template <路径>` 加载提示模板（可重复）；`--no-prompt-templates` 禁用提示模板发现；`--theme <路径>` 加载主题（可重复）；`--no-themes` 禁用主题发现；`--no-context-files`、`-nc` 禁用 AGENTS.md 和 CLAUDE.md 发现。组合使用 `--no-*` 与显式标记可精确加载所需内容。

### 其他选项

`--system-prompt <文本>` 替换默认提示（上下文文件和技能仍会附加）；`--append-system-prompt <文本>` 追加到系统提示；`--tui-mode <模式>` 设置 TUI 模式（`regular` 常规或 `experimental fullscreen` 实验全屏）；`--use-theme <名称[/名称]>` 为本次运行设置初始交互主题；`--verbose` 强制详细启动；`-a`、`--approve` 本次运行信任项目本地文件；`-na`、`--no-approve` 忽略项目本地文件；`-h`、`--help` 显示帮助；`-v`、`--version` 显示版本。

全屏模式下，转录内容在终端视口内滚动，排队消息、工作状态、扩展组件、编辑器和底部栏保持固定。鼠标/触控板输入滚动指针所在区域，键盘视口操作始终可用。支持 Kitty 图形协议的内联图片在 Kitty 和 Ghostty 终端可用；iTerm2 中图像渲染为文本占位符（因其内联图像协议无法在应用程序控制的滚动中删除或裁剪）。常规模式使用主屏幕和终端拥有的回滚缓冲区，iTerm2 内联图像可正常渲染。可通过 `/settings` 切换 TUI 模式并设置默认值。

### 文件参数与实用示例

使用 `@` 前缀将文件包含到消息中：`pi @prompt.md "回答这个"`、`pi -p @截图.png "图片中是什么？"`、`pi @code.ts @test.ts "审查这些文件"`。

常用示例：`pi "列出 src/ 中所有 .ts 文件"` 交互式初始提示；`pi -p "总结此代码库"` 非交互式；`cat README.md | pi -p "总结此文本"` 管道输入；`pi --name "发布审计" -p "审计此仓库"` 命名一次性会话；`pi --provider openai --model gpt-4o "帮我重构"` 指定模型；`pi --model openai/gpt-4o "帮我重构"` 提供商前缀；`pi --model sonnet:high "解决这个复杂问题"` 思考级别简写；`pi --models "claude-*,gpt-4o"` 限制模型循环；`pi --tools read,grep,find,ls -p "审查代码"` 只读模式；`pi --exclude-tools ask_question` 禁用特定工具。

## 设计原则

Pi 保持核心轻量，将工作流特定行为推入扩展、技能、提示模板和包中实现。它有意不内置 MCP、子代理、权限弹窗、计划模式、待办事项或后台 bash 等功能，这些工作流可通过扩展或包构建安装，或使用容器、tmux 等外部工具实现。