使用 Pi

本页收集了不适合放在快速入门页面上的日常使用细节。

交互模式

界面有四个主要区域：

• 启动头 - 快捷方式、已加载的上下文文件、提示词模板、技能和扩展
• 消息 - 用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器 - 输入区域；边框颜色指示当前的思考级别
• 页脚 - 工作目录、会话名称、令牌/缓存使用量、成本、上下文使用情况和当前模型。总计包括助手回复、工具报告的使用量以及摘要生成。

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

编辑器功能

参见 键绑定 了解所有快捷键和自定义设置。

斜杠命令

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

消息队列

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

• 输入 将一条引导消息加入队列，在当前助手回合执行完工具调用后投递。
• Alt+Enter 将一条后续消息加入队列，在智能体完成所有工作后投递。
• “转义” 中止并将已排队的消息恢复到编辑器。
• Alt+向上键 将已排队的消息取回编辑器。

在 Windows 终端中，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 用于全局指令
• 父目录，从当前工作目录向上遍历
• 当前目录

如果某个目录包含 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/settings.json 和 .pi 资源，安装缺失的项目包，并执行项目扩展。

在做出信任决定之前，pi 仅加载上下文文件、用户/全局扩展和 CLI -e 扩展，以便它们能够处理 project_trust 事件。项目本地扩展、项目包管理的扩展和项目设置仅在项目受信任后加载。当切换到来自不同 cwd 的会话且该 cwd 的信任在当前进程中尚未解决时，此分离也适用。

非交互模式（-p, --mode json和 --mode rpc）不显示信任提示。如果没有适用的已保存信任决定，它们会使用全局设置中的 defaultProjectTrust 从全局设置： ask （默认）和 never 忽略这些项目资源，而 always 信任它们。传递 --approve/-a 或 --no-approve/-na 可覆盖单次运行的项目信任。

如果没有扩展或已保存的决定适用， defaultProjectTrust 控制回退行为。将其设置为 "ask", "always"或 "never" ，在 ~/.pi/agent/settings.json中，或使用 /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]     # 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 本身，请参阅 快速入门. pi config 和项目包命令接受 --approve/--no-approve 以信任或忽略单条命令的项目本地设置。 pi update 从不提示项目信任。

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

模式

在打印模式下，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

其他选项

在 fullscreen 模式下，转录内容在终端视口内滚动，而排队消息、工作状态、扩展小部件、编辑器和页脚保持固定在底部。鼠标/触控板输入滚动指针下的区域；键盘视口操作始终可用。内联图像在支持 Kitty 图形协议的终端（包括 Kitty 和 Ghostty）中工作。在 iTerm2 中，它们呈现为文本占位符，因为其内联图像协议无法在应用程序控制的滚动期间删除或裁剪放置。在 regular 模式下，pi 使用主屏幕和终端拥有的回滚，iTerm2 内联图像继续正常渲染。请参阅 终端设置 了解终端特定的设置和解决方法。

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

文件参数

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

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 保持核心小巧，并将特定工作流的行为推送到扩展、技能、提示词模板和包中。

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

有关完整理由，请阅读 博客文章.