使用 Pi

本页汇集日常使用的操作细节，这些内容不适合放在快速开始页面。

交互模式

界面有四个主要区域：

启动头部（Startup header） - 快捷键、已加载的上下文文件、提示词模板、技能和扩展
消息区（Messages） - 用户消息、智能体回复、工具调用、工具结果、通知、错误和扩展界面
编辑器（Editor） - 输入区域；边框颜色表示当前思考级别
底部状态栏（Footer） - 工作目录、会话名称、token/缓存用量、费用、上下文占用和当前模型。总计包含智能体回复、工具上报的用量以及摘要生成

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

编辑器功能

功能	操作方法
文件引用	输入 `@` 模糊搜索项目文件
路径补全	按 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`）

所有快捷键及自定义方法见快捷键绑定。

斜杠命令

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

命令	描述
`/login`, `/logout`	管理 OAuth 或 API 密钥凭据
`/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

消息队列

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

Enter 排队一条引导消息（steering message），在当前智能体回合执行完工具调用后投递。
Alt+Enter 排队一条追问消息（follow-up message），在智能体完成全部工作后投递。
Escape 中止并将排队消息恢复到编辑器。
Alt+Up 把排队消息取回编辑器。

在 Windows Terminal 中，Alt+Enter 默认为全屏快捷键。如果你希望 pi 收到该快捷键，请按终端设置中的说明重新映射。

在设置中通过 steeringMode 和 followUpMode 配置投递方式。

会话

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

pi -c                  # 继续最近一次的会话
pi -r                  # 浏览并选择一个会话
pi --no-session        # 临时模式；不保存
pi --name "my task"    # 启动时设置会话显示名称
pi --session <path|id> # 使用指定的会话文件或会话 ID
pi --fork <path|id>    # 把会话分叉到新的会话文件

常用的会话命令：

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

详见会话和上下文压缩。

上下文文件

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

~/.pi/agent/AGENTS.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 可在单次运行中覆盖项目信任。

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

pi config 和包命令使用相同的项目信任流程，只有 pi update 从不询问。传入 --approve 可在单条命令中信任项目本地设置，传入 --no-approve 则忽略它们。

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

导出和分享会话

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

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

如果你用 pi 做开源工作，并希望为模型、提示词、工具和评测研究发布会话，请查看 badlogic/pi-share-hf。它将会话发布到 Hugging Face 数据集。

CLI 参考

pi [options] [@files...] [messages...]

包命令

pi install <source> [-l]     # 安装包，-l 表示安装到项目本地
pi remove <source> [-l]      # 移除包
pi uninstall <source> [-l]   # remove 的别名
pi update [source|self|pi]   # 只更新 pi，或更新某个包源
pi update --all              # 更新 pi 和所有包；核对锁定的 git 引用
pi update --extensions       # 只更新包；核对锁定的 git 引用
pi update --models           # 只刷新模型目录
pi update --self             # 只更新 pi
pi update --extension <src>  # 更新单个包
pi list                      # 列出已安装的包
pi config                    # 启用/禁用包资源

这些命令管理 Pi 包，pi update 可以更新 pi CLI 安装。要卸载 pi 本身，请参阅快速开始。pi config 和项目包命令接受 --approve/--no-approve，用于在单条命令中信任或忽略项目本地设置。pi update 从不询问项目信任。

包源和安全说明请参阅Pi 包。

模式

Flag	描述
default	交互模式
`-p`, `--print`	打印响应后退出
`--mode json`	将所有事件输出为 JSON 行；见 JSON 模式
`--mode rpc`	通过 stdin/stdout 的 RPC 模式；见 RPC 模式
`--export <in> [out]`	将会话导出为 HTML

在打印模式下，pi 还会读取管道输入并合并到初始提示词：

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

模型选项

Option	描述
`--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]`	列出可用的模型

会话选项

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

工具选项

Option	描述
`--tools <list>`, `-t <list>`	白名单指定内置、扩展和自定义工具
`--exclude-tools <list>`, `-xt <list>`	禁用指定的内置、扩展和自定义工具
`--no-builtin-tools`, `-nbt`	禁用内置工具但保留扩展/自定义工具
`--no-tools`, `-nt`	禁用所有工具

内置工具：read、bash、edit、write、grep、find、ls。

资源选项

Option	描述
`-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.ts

其他选项

Option	描述
`--system-prompt <text>`	替换默认提示词；上下文文件和技能仍会追加
`--append-system-prompt <text>`	追加到系统提示词
`--tui-mode <mode>`	TUI 模式：`regular`（默认）或实验性的 `fullscreen`
`--verbose`	强制详细启动输出
`-a`, `--approve`	本次运行信任项目本地文件
`-na`, `--no-approve`	本次运行忽略项目本地文件
`-h`, `--help`	显示帮助
`-v`, `--version`	显示版本

在 fullscreen 模式下，对话记录在终端视口内滚动，而排队消息、工作状态、扩展小组件、编辑器和底部状态栏固定在底部。鼠标/触控板输入滚动指针下方的区域；键盘视口操作始终可用。内联图片在支持 Kitty 图形协议的终端中可用，包括 Kitty 和 Ghostty。在 iTerm2 中它们渲染为文本占位符，因为其内联图片协议无法在应用控制的滚动过程中删除或裁剪图片。在 regular 模式下，pi 使用主屏幕和终端自有的回滚缓冲区，iTerm2 的内联图片仍可正常渲染。

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

文件参数

在文件前加 @ 可将其包含在消息中：

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

示例

# 交互式，带初始提示词
pi "List all .ts files in src/"

# 非交互式
pi -p "Summarize this codebase"

# 非交互式，通过管道输入 stdin
cat README.md | pi -p "Summarize this text"

# 命名的一次性会话
pi --name "release audit" -p "Audit this repository"

# 使用不同的模型
pi --provider openai --model gpt-4o "Help me refactor"

# 带模型提供方前缀的模型
pi --model openai/gpt-4o "Help me refactor"

# 带思考级别简写的模型
pi --model sonnet:high "Solve this complex problem"

# 限制模型循环切换
pi --models "claude-*,gpt-4o"

# 只读模式
pi --tools read,grep,find,ls -p "Review the code"

# 禁用某个扩展或内置工具，同时保留其余工具可用
pi --exclude-tools ask_question

设计原则

Pi 保持核心小巧，把工作流相关的行为放进扩展、技能、提示词模板和包中。

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

完整的理由请阅读博客文章。