使用 Pi

本页介绍 Pi 的日常使用方式，以及 Quickstart 中未展开说明的功能。

该界面有四个主要区域：

• 启动头部 - 快捷键、已加载的 context files、Prompt Templates、Skills 和扩展
• 消息 - 用户消息、助手响应、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器 - 输入内容的位置；边框颜色表示当前 thinking level
• 页脚 - 工作目录、会话名称、令牌/缓存使用情况、成本、上下文使用情况和当前模型。总计包括助理响应、工具报告的使用情况以及摘要生成。

编辑器可以暂时替换为内置 UI（例如 /settings）或自定义扩展 UI。

功能	用法
文件引用	输入 @ 模糊搜索项目文件
路径补全	按 Tab 补全路径
多行输入	Shift+Enter，或 Windows 终端上的 Ctrl+Enter
复制回复	Ctrl+X 复制最后一条助手消息；在 /tree 中复制选中的消息
图片	使用 Ctrl+V 粘贴，Windows 上使用 Alt+V，或拖入终端
Shell 命令	!command 运行命令并将输出发送给模型
隐藏 Shell 命令	!!command 运行命令，但不将输出发送给模型
外部编辑器	Ctrl+G 打开 externalEditor、$VISUAL、$EDITOR、Windows 上的 Notepad，或其他平台上的 nano

有关所有快捷方式和自定义，请参阅 Keybindings。

在编辑器中输入 / 可打开命令补全。扩展可以注册自定义命令，Skills 可通过 /skill:name 使用，Prompt Templates 会通过 /templatename 展开。

命令	描述
/login, /logout	管理 OAuth 或 API Key 凭据
/llama	下载、加载和卸载 llama.cpp 路由器模型
/model	切换模型
/scoped-models	启用/禁用 Ctrl+P 循环模型
/settings	thinking level、主题、消息投递和传输设置
/resume	从之前的会话中选择
/new	开始新会话
/name <name>	设置会话显示名称
/session	显示会话文件、ID、消息、令牌和成本
/tree	跳转到会话中的任意一点并从那里继续
/trust	保存项目信任决策，供后续会话使用
/fork	根据先前的用户消息创建新会话
/clone	将当前分支复制到新会话中
/compact [prompt]	手动压缩上下文，可选择使用自定义指令
/copy	将最后一条助理消息复制到剪贴板
/export [file]	将会话导出为 HTML 或 JSONL
/import <file>	从 JSONL 文件导入并恢复会话
/share	上传为私有 GitHub Gist，并生成可分享的 HTML 链接
/reload	重新加载按键绑定、扩展、技能、提示、主题和 context files
/hotkeys	显示所有键盘快捷键
/changelog	显示版本历史记录
/quit	退出 pi

Agent 仍在工作时也可以提交消息：

• Enter 将 steering message 加入队列，在当前助手轮次完成工具调用后投递。
• Alt+Enter 将 follow-up message 加入队列，在 Agent 完成全部工作后投递。
• Escape 中止并将排队消息恢复到编辑器。
• Alt+Up 将排队的消息检索回编辑器。

在 Windows Terminal 中，Alt+Enter 默认是全屏快捷键。若希望 pi 接收该快捷键，请按 Terminal setup 中的说明重新映射。

可在 Settings 中通过 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 导航文件内的 session tree，并可以总结已放弃的分支。
• /fork 根据较早的用户消息创建新会话。
• /clone 将当前分支复制到新的会话文件中。
• /compact 总结较早消息以释放上下文。

详情请参阅Sessions和Compaction。

Pi 在启动时加载 AGENTS.md 或 CLAUDE.md：

• ~/.pi/agent/AGENTS.md 用于全局指令
• 父目录，从当前工作目录向上走
• 当前目录

如果目录包含 AGENTS.override.md，Pi 会从该目录加载它，而不是 AGENTS.md 或 CLAUDE.md。其他目录中的上下文文件仍然正常分层。

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

将默认的系统提示替换为：

• .pi/SYSTEM.md 用于项目
• ~/.pi/agent/SYSTEM.md 用于全局

附加到默认提示，而不在任一位置将其替换为 APPEND_SYSTEM.md。

在交互式启动时，pi 在信任包含项目本地设置、资源或项目 .agents/skills 的项目文件夹之前会询问，并且在 ~/.pi/agent/trust.json 中没有保存该文件夹或父文件夹的决定。信任项目允许 pi 加载 .pi/settings.json 和 .pi 资源、安装缺少的项目包以及执行项目扩展。

在做出信任决定之前，pi 只加载 context files、用户/全局扩展和 CLI -e 扩展，以便它们可以处理 project_trust 事件。项目本地扩展、由项目包管理的扩展以及项目设置只会在项目受信任后加载。当切换到来自另一个 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 数据集。

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

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 本身，请参阅 Quickstart。 pi config 和项目包命令接受 --approve/--no-approve 以信任或忽略一个命令的项目本地设置。 pi update 从不提示项目信任。

有关软件包来源和安全说明，请参阅Pi Packages。

标志	描述
默认	交互模式
-p, --print	打印响应并退出
--mode json	将所有事件输出为 JSON 行；见 JSON mode
--mode rpc	通过 stdin/stdout 使用 RPC 模式；见 RPC mode
--export <in> [out]	将会话导出为 HTML

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

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

选项	描述
--provider <name>	Provider，例如 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]	列出可用模型

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

选项	描述
--tools <list>, -t <list>	将特定内置、扩展和自定义工具列入白名单
--exclude-tools <list>, -xt <list>	禁用特定的内置、扩展和自定义工具
--no-builtin-tools, -nbt	禁用内置工具但保持扩展/自定义工具启用
--no-tools, -nt	禁用所有工具

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

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

将 --no-* 与显式标志结合，可以只加载需要的资源并忽略设置。例如：

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

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

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

在 /settings 中设置 TUI mode，可以立即在 regular 和 fullscreen 之间切换，并为后续会话选择默认值。Fullscreen exit output 控制退出全屏时是打印最终转录记录，还是恢复上一屏并只打印会话恢复提示。

使用 @ 为文件添加前缀以将其包含在消息中：

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 保持核心精简，并将工作流相关行为放到扩展、Skills、Prompt Templates 和 packages 中。

它有意不内置 MCP、子 Agent、权限弹窗、plan mode、to-do 或后台 Bash。可以将这些工作流构建或安装为扩展/包，也可以使用容器、tmux 等外部工具。

完整设计动机见 blog post。