使用 Pi

本页面收集不适用于快速入门页面的日常使用细节。

交互模式 Interactive Mode

界面包含四个主要区域：

• 启动头部（Startup header） — 快捷键、已加载的上下文文件、提示模板、技能和扩展
• 消息区（Messages） — 用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器（Editor） — 输入区域；边框颜色表示当前的思考级别
• 底部栏（Footer） — 工作目录、会话名称、令牌/缓存用量、费用、上下文使用情况和当前模型

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

编辑器功能 Editor Features

快捷键和自定义配置请参见键盘快捷键。

斜杠命令 Slash Commands

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

消息队列 Message Queue

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

• Enter 将引导消息（steering message）加入队列，在当前助手回合的工具调用完成后投递。
• Alt+Enter 将后续消息（follow-up message）加入队列，在 agent 完成所有工作后投递。
• Escape 中止操作并将队列中的消息恢复到编辑器中。
• Alt+Up 将队列中的消息取回到编辑器中。

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

在设置中使用 steeringMode 和 followUpMode 配置投递行为。

会话 Sessions

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

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择会话
pi --no-session        # 临时模式；不保存
pi --name "my task"    # 启动时设置会话显示名称
pi --session <path|id> # 使用特定的会话文件或会话 ID
pi --fork <path|id>    # 将会话分支到新的会话文件

有用的会话命令：

• /session 显示当前会话文件和 ID。
• /tree 导航文件内的会话树，并可汇总已废弃的分支。
• /fork 从较早的用户消息创建新会话。
• /clone 将当前活动分支复制到新的会话文件中。
• /compact 汇总较早的消息以释放上下文空间。

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

上下文文件 Context Files

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

• ~/.pi/agent/AGENTS.md — 全局指令
• 从当前工作目录向上逐级查找的父目录
• 当前目录

使用上下文文件来定义项目约定、命令、安全规则和偏好。使用 --no-context-files 或 -nc 禁用加载。

系统提示文件 System Prompt Files

替换默认系统提示：

• 项目级：.pi/SYSTEM.md
• 全局级：~/.pi/agent/SYSTEM.md

在以上任一位置使用 APPEND_SYSTEM.md 可在不替换默认提示的情况下追加内容。

项目信任 Project Trust

交互式启动时，如果项目目录包含本地设置、资源或 .agents/skills，且 ~/.pi/agent/trust.json 中对该目录或其父目录无已保存的信任决策，pi 会询问是否信任该项目。信任后，pi 可加载 .pi/settings.json 和 .pi 资源、安装缺失的包以及执行项目扩展。

信任决策做出前，pi 仅加载上下文文件、用户/全局扩展和 CLI -e 扩展，以便它们处理 project_trust 事件。项目本地扩展、包管理的扩展和项目设置仅在信任后才加载。此规则同样适用于切换到来自不同工作目录且当前进程尚未解决信任的会话。

非交互模式（-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 以使更改生效。

导出与分享会话 Exporting and Sharing Sessions

使用 /export [file] 将会话写入 HTML。

使用 /share 上传为私有 GitHub Gist，附带可分享的 HTML 链接。

如果你在开源项目中使用 pi，并希望发布会话以供模型、提示、工具和评估研究使用，请参见 badlogic/pi-share-hf。该工具将会话发布到 Hugging Face 数据集。

CLI 参考 CLI Reference

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

包命令 Package Commands

pi install <source> [-l]     # 安装包，-l 表示项目本地安装
pi remove <source> [-l]      # 移除包
pi uninstall <source> [-l]   # remove 的别名
pi update [source|self|pi]   # 仅更新 pi，或更新一个包源
pi update --all              # 更新 pi 和所有包；协调锁定的 git 引用
pi update --extensions       # 仅更新包；协调锁定的 git 引用
pi update --self             # 仅更新 pi
pi update --extension <src>  # 更新单个包
pi list                      # 列出已安装的包
pi config                    # 启用/禁用包资源

这些命令管理 pi 包，pi update 可以更新 pi CLI 安装本身。卸载 pi 请参见快速入门。pi config 和项目包命令接受 --approve/--no-approve 以信任或忽略单条命令的项目本地设置。pi update 从不提示项目信任。

包源和安全说明请参见Pi 包。

模式 Modes

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

cat README.md | pi -p "总结这段文本"

模型选项 Model Options

会话选项 Session Options

工具选项 Tool Options

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

资源选项 Resource Options

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

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

其他选项 Other Options

文件参数 File Arguments

使用 @ 前缀将文件包含到消息中：

pi @prompt.md "回答这个问题"
pi -p @screenshot.png "这张图片里有什么？"
pi @code.ts @test.ts "审查这些文件"

示例 Examples

# 交互模式，附带初始提示
pi "列出 src/ 中所有 .ts 文件"

# 非交互模式
pi -p "总结这个代码库"

# 非交互模式，通过管道传入 stdin
cat README.md | pi -p "总结这段文本"

# 命名的一次性会话
pi --name "发布审核" -p "审核此仓库"

# 使用不同模型
pi --provider openai --model gpt-4o "帮我重构代码"

# 带提供商前缀的模型
pi --model openai/gpt-4o "帮我重构代码"

# 带思考级别简写的模型
pi --model sonnet:high "解决这个复杂问题"

# 限制模型循环切换范围
pi --models "claude-*,gpt-4o"

# 只读模式
pi --tools read,grep,find,ls -p "审查代码"

# 禁用某个扩展或内置工具，同时保留其他可用工具
pi --exclude-tools ask_question

环境变量 Environment Variables

设计原则 Design Principles

Pi 保持核心小巧，将工作流特定行为推送到扩展、技能、提示模板和包中。

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

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