使用 Pi

本页汇总的是日常使用细节。它们不太适合放在快速上手页里。

交互模式

<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>

界面分为四个主要区域：

• 启动头部 - 快捷方式、已加载的上下文文件、提示词模板、Skill 和扩展
• 消息区 - 用户消息、助手回复、tool call、tool result、通知、错误和扩展 UI
• 编辑器 - 你输入内容的地方；边框颜色表示当前思考级别
• 底部栏 - 工作目录、会话名称、token/cache 使用情况、费用、上下文使用量和当前模型

编辑器可以被内置 UI 临时替换，比如 /settings，也可以被自定义扩展 UI 替换。

编辑器功能

所有快捷键和自定义方式见 键位绑定。

斜杠命令

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

消息队列

你可以在 agent 仍在工作时继续提交消息：

• Enter 会把一条 steering 消息加入队列，在当前助手轮次执行完它的 tool call 后发送。
• Alt+Enter 会把一条后续消息加入队列，在 agent 完成全部工作后发送。
• Escape 会中止，并把队列里的消息恢复到编辑器中。
• Alt+Up 会把队列里的消息取回编辑器。

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

可在 设置 中通过 steeringMode 和 followUpMode 配置消息传递方式。

会话

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

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 对较早的消息做上下文压缩，以释放上下文。

详情见 会话 和 上下文压缩。

上下文文件

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

• ~/.pi/agent/AGENTS.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 资源、安装缺失的项目 Package，并执行项目扩展。

在做出信任决定之前，pi 只会加载上下文文件、用户/全局扩展和 CLI -e 扩展，这样它们就能处理 project_trust 事件。项目本地扩展、由项目 Package 管理的扩展和项目设置，只有在项目被信任后才会加载。切换到来自其他 cwd 的会话时，如果该 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 和 package 命令使用同样的项目信任流程，但 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 datasets。

CLI 参考

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

Package 命令

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 --self             # Update pi only
pi update --extension <src>  # Update one package
pi list                      # List installed packages
pi config                    # Enable/disable package resources

这些命令用于管理 pi packages，而 pi update 可以更新 pi CLI 的安装。要卸载 pi 本身，请参见 快速开始。pi config 和项目 package 命令都支持 --approve/--no-approve，可在单次命令中信任或忽略项目本地设置。pi update 从不会提示项目信任。

参见 Pi Packages，了解 package 来源和安全说明。

模式

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

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

模型选项

会话选项

工具选项

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

资源选项

将 --no-* 与显式标志组合使用，可以只加载你需要的内容，并忽略设置。示例：

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

其他选项

文件参数

在文件名前加 @，即可把它们包含到消息中：

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

示例

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

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

# 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

环境变量

---

设计原则

Pi 会把核心保持得很小，并把与工作流相关的行为放到扩展、Skill、提示词模板和 Package 里。

它刻意不内置 MCP、子 agent、权限弹窗、计划模式、待办事项或后台 bash。你可以把这些工作流做成扩展或 Package 安装进来，也可以使用容器、tmux 之类的外部工具。

如果想看完整的设计理由，请阅读这篇 blog post。