2 使用 Pi

本页面收录了不适合放在快速开始页面中的日常使用细节。

交互模式

界面分为四个主要区域：

• 启动头部——快捷方式、已加载的上下文文件、提示词模板、技能和扩展
• 消息区——用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器——你输入内容的地方；边框颜色指示当前的思考级别
• 底部栏——工作目录、会话名称、token/缓存用量、费用、上下文用量和当前模型。总计包含助手回复、工具报告的用量以及摘要生成。

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

编辑器功能

所有快捷键及自定义方式参见快捷键。

斜杠命令

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

消息队列

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

• Enter 将一条转向消息加入队列，在当前助手回合执行完其工具调用后送达。
• Alt+Enter 将一条后续消息加入队列，在智能体完成所有工作后送达。
• 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 用于全局指令
• 从当前工作目录向上遍历的父目录
• 当前目录

如果某个目录包含 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]     # 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、powershell（Windows）、edit、write、grep、find、ls。

资源选项

将 --no-* 与显式标志组合使用，可以忽略设置、精确加载所需资源。示例：

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

其他选项

在 fullscreen 模式下，对话记录在终端视口内滚动，而排队消息、工作状态、扩展小部件、编辑器和底部栏固定在底部。鼠标/触控板输入会滚动指针所在区域；键盘视口操作始终可用。行内图片在支持 Kitty 图形协议的终端（包括 Kitty 和 Ghostty）中可以正常显示。在 iTerm2 中，它们会渲染为文本占位符，因为 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"

示例

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

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

# Prompt beginning with a dash
pi -p -- "- Summarize these points"

# 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 等外部工具。

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