使用 Pi

本页汇总了不适合放在快速入门页面中的日常使用细节。

交互模式

界面包含四个主要区域：

• 启动标题栏 - 快捷键、已加载的上下文文件、提示模板、技能和扩展
• 消息 - 用户消息、助手响应、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器 - 你输入内容的地方；边框颜色表示当前思考级别
• 页脚 - 工作目录、会话名称、token/缓存使用量、成本、上下文使用量和当前模型

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

编辑器功能

查看 快捷键 了解所有快捷键和自定义方式。

斜杠命令

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

消息队列

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

• Enter 将引导消息加入队列，在当前助手回合完成工具调用后投递。
• 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 资源、安装缺失的项目包，并执行项目扩展。

在做出信任决定之前，pi 只加载上下文文件、用户/全局扩展以及 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 和包命令使用相同的项目信任流程，但 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...]

包命令

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 包，且 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

其他选项

文件参数

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

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、sub-agents、权限弹窗、计划模式、待办事项或后台 bash。你可以将这些工作流构建或安装为扩展或包，或使用容器和 tmux 等外部工具。

完整理由请阅读这篇 blog post。