5 日常使用
5.1 交互模式界面
Pi 的交互模式界面由四个主要区域组成：
- 启动头（Startup Header）：显示快捷键、已加载的上下文文件、提示词模板、技能和扩展信息
- 消息区（Messages）：显示用户消息、助手响应、工具调用、工具结果、通知、错误和扩展 UI
- 编辑器（Editor）：你输入文字的区域；边框颜色指示当前思考级别
- 页脚（Footer）：显示工作目录、会话名称、Token/缓存使用量、费用、上下文使用率和当前模型
页脚中的费用总计包括助手响应、工具报告的使用量以及摘要生成。这是整个会话的累计费用。
编辑器可以被内置 UI（如 /settings）或自定义扩展 UI 临时替换。
5.1.1 编辑器功能
| 功能 | 操作方式 |
|---|---|
| 文件引用 | 输入 @ 模糊搜索项目文件 |
| 路径补全 | 按 Tab 补全路径 |
| 多行输入 | Shift+Enter，Windows Terminal 上为 Ctrl+Enter |
| 复制响应 | Ctrl+X 复制最后的助手消息；在 /tree 中复制选中消息 |
| 图片粘贴 | Ctrl+V，Windows 上为 Alt+V，或拖入终端 |
| Shell 命令 | !command 执行并将输出发送给模型 |
| 隐藏 Shell 命令 | !!command 执行但不发送输出给模型 |
| 外部编辑器 | Ctrl+G 打开 externalEditor、$VISUAL、$EDITOR、Windows 记事本或 nano |
在 VS Code 中使用外部编辑器时，建议在设置中配置 "externalEditor": "code --wait"，这样 Pi 会在编辑器关闭后恢复。
5.2 斜杠命令
在编辑器中输入 / 即可打开命令补全。扩展可以注册自定义命令，技能以 /skill:name 形式出现，提示词模板通过 /templatename 展开。
5.2.1 完整命令列表
| 命令 | 描述 |
|---|---|
/login、/logout |
管理 OAuth 或 API Key 凭证 |
/llama |
下载、加载和卸载 llama.cpp 路由器模型 |
/model |
切换模型 |
/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 |
5.3 消息队列
你可以在 Agent 仍在工作时提交消息：
- Enter：排队一条引导消息（steering message），在当前助手轮次执行完工具调用后发送
- Alt+Enter：排队一条后续消息（follow-up message），在 Agent 完成所有工作后发送
- Escape：中止并恢复排队的消息到编辑器
- Alt+Up：将排队的消息取回编辑器
在 Windows Terminal 中，Alt+Enter 默认是全屏切换。如果你想让 Pi 接收这个快捷键，请参考终端设置文档进行重新映射。
消息的传递方式可通过设置中的 steeringMode 和 followUpMode 配置：
"one-at-a-time"（默认）：逐条发送"all"：一次性发送所有排队消息
5.4 会话管理
Pi 自动将会话保存到 ~/.pi/agent/sessions/ 目录，按工作目录组织。
5.4.1 命令行会话选项
pi -c # 继续最近的会话
pi -r # 浏览并选择历史会话
pi --no-session # 临时模式，不保存
pi --name "my task" # 启动时设置会话名称
pi --session <path|id> # 使用特定会话文件或部分 UUID
pi --fork <path|id> # 将会话分叉为新文件
pi --session-dir <dir> # 自定义会话存储目录5.4.2 常用会话命令
/session：显示当前会话文件和 ID/tree：导航会话内树结构，可对废弃分支生成摘要/fork：从早期用户消息创建新会话/clone：复制当前活跃分支到新会话文件/compact：压缩旧消息以释放上下文空间
5.5 上下文文件
Pi 在启动时自动加载上下文文件来为模型提供项目信息。
5.5.1 加载顺序
~/.pi/agent/AGENTS.md：全局指令- 从当前目录的父目录开始逐级向上查找，直到根目录
- 当前目录中的
AGENTS.md或CLAUDE.md
Pi 同时支持 AGENTS.md 和 CLAUDE.md 文件名。如果一个目录中两者都存在，优先加载 AGENTS.md。
使用 --no-context-files 或 -nc 标志可以禁用上下文文件加载。
5.5.2 系统提示词文件
你可以完全替换默认系统提示词：
.pi/SYSTEM.md：项目级替换~/.pi/agent/SYSTEM.md：全局替换
如果只想追加内容而不替换，使用 APPEND_SYSTEM.md：
.pi/APPEND_SYSTEM.md：项目级追加~/.pi/agent/APPEND_SYSTEM.md：全局追加
5.6 项目信任机制
Pi 在启动时会检查项目目录是否包含需要信任的资源。
5.6.1 需要信任的资源
以下资源的存在会触发信任提示：
.pi/settings.json.pi/extensions、.pi/skills、.pi/prompts、.pi/themes.pi/SYSTEM.md或.pi/APPEND_SYSTEM.md- 当前目录或祖先目录中的
.agents/skills
单纯的 .pi 目录不会触发信任提示。只有包含上述特定资源时才会。
5.6.2 信任决策流程
- 交互模式：如果项目包含需要信任的资源且无已保存的决策，Pi 会询问是否信任
- 非交互模式（
-p、--mode json、--mode rpc）：不显示信任提示，根据defaultProjectTrust设置决定行为 - 保存的决策：存储在
~/.pi/agent/trust.json中，按规范目录路径索引
信任决策选项：
"ask"（默认）：询问用户"always"：总是信任"never"：从不信任
使用 /trust 命令可以保存当前项目的信任决策。CLI 标志 -a/--approve 和 -na/--no-approve 可为单次运行覆盖信任决策。
5.6.3 信任前后的加载行为
信任决策前，Pi 仅加载：
- 上下文文件（AGENTS.md、CLAUDE.md）
- 用户/全局扩展
- CLI
-e指定的扩展
信任决策后（如果被信任），Pi 额外加载：
.pi/settings.json.pi资源（扩展、技能、提示词模板、主题、系统提示词文件）- 缺失的项目包
- 项目本地扩展和项目包管理的扩展
5.7 导出和分享会话
/export [file] # 导出会话为 HTML
/share # 上传为私有 GitHub Gist/share 会生成一个可分享的 HTML 链接。如果你从事开源工作并希望发布会话用于模型、提示词、工具和评估研究，可以参考 badlogic/pi-share-hf，它将会话发布到 Hugging Face 数据集。
5.8 CLI 完整参考
pi [options] [@files...] [messages...]5.8.1 模式选项
| 标志 | 描述 |
|---|---|
| 默认 | 交互模式 |
-p、--print |
输出响应并退出 |
--mode json |
以 JSON 行输出所有事件 |
--mode rpc |
通过 stdin/stdout 的 RPC 模式 |
--export <in> [out] |
导出会话为 HTML |
5.8.2 模型选项
| 选项 | 描述 |
|---|---|
--provider <name> |
提供商名称，如 anthropic、openai、google |
--model <pattern> |
模型模式或 ID，支持 provider/id 和可选的 :thinking |
--api-key <key> |
API Key，覆盖环境变量 |
--thinking <level> |
思考级别：off、minimal、low、medium、high、xhigh、max |
--models <patterns> |
逗号分隔的模型模式，用于 Ctrl+P 循环 |
--list-models [search] |
列出可用模型 |
5.8.3 会话选项
| 选项 | 描述 |
|---|---|
-c、--continue |
继续最近的会话 |
-r、--resume |
浏览并选择会话 |
--session <path\|id> |
使用特定会话文件或部分 UUID |
--fork <path\|id> |
分叉会话文件或部分 UUID |
--session-dir <dir> |
自定义会话存储目录 |
--no-session |
临时模式，不保存 |
--name <name>、-n <name> |
启动时设置会话名称 |
5.8.4 工具选项
| 选项 | 描述 |
|---|---|
--tools <list>、-t <list> |
允许列表：指定可用的内置、扩展和自定义工具 |
--exclude-tools <list>、-xt <list> |
禁用特定工具 |
--no-builtin-tools、-nbt |
禁用内置工具但保留扩展/自定义工具 |
--no-tools、-nt |
禁用所有工具 |
内置工具列表：read、bash、edit、write、grep、find、ls。
5.8.5 资源选项
| 选项 | 描述 |
|---|---|
-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-* 标志与显式加载标志组合使用，精确控制加载哪些资源：
pi --no-extensions -e ./my-extension.ts5.8.6 其他选项
| 选项 | 描述 |
|---|---|
--system-prompt <text> |
替换默认提示词；上下文文件和技能仍会追加 |
--append-system-prompt <text> |
追加到系统提示词 |
--alt |
使用备用屏幕 TUI，带可滚动对话记录和固定编辑器/状态栏 |
--verbose |
强制显示详细启动信息 |
-a、--approve |
本次运行信任项目本地文件 |
-na、--no-approve |
本次运行忽略项目本地文件 |
-h、--help |
显示帮助 |
-v、--version |
显示版本 |
5.8.7 文件参数
使用 @ 前缀引用文件：
pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"5.9 包管理命令
pi install <source> [-l] # 安装包，-l 为项目本地
pi remove <source> [-l] # 移除包
pi uninstall <source> [-l] # remove 的别名
pi update [source|self|pi] # 更新 Pi 或单个包
pi update --all # 更新 Pi 和所有包
pi update --extensions # 仅更新包
pi update --models # 仅刷新模型目录
pi update --self # 仅更新 Pi
pi update --extension <src> # 更新单个包
pi list # 列出已安装的包
pi config # 启用/禁用包资源pi config 和项目包命令接受 --approve/--no-approve 来为单次命令信任或忽略项目本地设置。pi update 从不提示项目信任。
5.10 设计原则
Pi 保持核心精简，将工作流特定的行为推送到扩展、技能、提示词模板和包中。
Pi 有意不包含以下内置功能：
- MCP 协议支持
- 子代理（sub-agents）
- 权限弹窗
- 计划模式
- 待办事项列表
- 后台 bash
这些工作流都可以通过扩展或包来实现，或者使用容器和 tmux 等外部工具来完成。
要了解完整的设计理念，请阅读作者的博客文章。