使用 Pi

本页面收集了日常使用细节，这些内容不适合放在快速入门页面中。

交互模式

界面有四个主要区域：

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

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

编辑器功能

功能	方法
文件引用	输入 @ 进行项目文件的模糊搜索
路径补全	按 Tab 补全路径
多行输入	Shift+Enter，或在 Windows Terminal 中按 Ctrl+Enter
图片	Ctrl+V 粘贴，或在 Windows 中按 Alt+V，或拖入终端
Shell 命令	!命令 执行并将输出发送给模型
隐藏 Shell 命令	!!命令 执行但不将输出发送给模型
外部编辑器	Ctrl+G 打开 externalEditor、$VISUAL、$EDITOR，Windows 上是记事本，其他系统是 nano

参见 快捷键 了解所有快捷键和自定义选项。

斜杠命令

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

命令	描述
/login, /logout	管理 OAuth 或 API 密钥凭据
/model	切换模型
/scoped-models	启用/禁用 Ctrl+P 循环中的模型
/settings	思考级别、主题、消息交付、传输方式
/resume	从之前的会话中选择一个
/new	启动新会话
/name 名称	设置会话显示名称
/session	显示会话文件、ID、消息、令牌和费用
/tree	跳转到会话的任意位置并从那里继续
/trust	保存项目信任决策以供未来会话使用
/fork	从前面的用户消息创建新会话
/clone	将当前活动分支复制为新会话
/compact [提示]	手动压缩上下文，可选择带自定义指令
/copy	复制最后一条助手消息到剪贴板
/export [文件]	导出会话为 HTML 或 JSONL
/import 文件	从 JSONL 文件导入并恢复会话
/share	上传为带可共享 HTML 链接的私有 GitHub gist
/reload	重新加载快捷键、扩展、技能、提示、主题和上下文文件
/hotkeys	显示所有键盘快捷键
/changelog	显示版本历史
/quit	退出 pi

消息队列

当代理仍在工作时，您可以提交消息：

• Enter 队列一条转向消息，在当前助手轮次执行完工具调用后交付
• Alt+Enter 队列一条跟进消息，在代理完成所有工作后交付
• Escape 中止并将队列消息恢复至编辑器
• Alt+Up 将队列消息取回编辑器

在 Windows Terminal 中，Alt+Enter 默认为全屏。如需让 pi 接收该快捷键，请按 终端设置 说明重新映射。

在 设置 中通过 steeringMode 和 followUpMode 配置交付方式。

会话

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

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择会话
pi --no-session        # 临时模式；不保存
pi --name "我的任务"    # 启动时设置会话显示名称
pi --session 路径或 id  # 使用特定会话文件或会话 ID
pi --fork 路径或 id     # 将会话复制为新会话文件

有用的会话命令：

• /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 切换到会话（其信任在当前进程中尚未解析）时，此分离同样适用。

非交互模式（-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 [文件] 将会话写入 HTML。

使用 /share 上传带可共享 HTML 链接的私有 GitHub gist。

如用 Pi 进行开源工作并希望公开会话以供模型、提示、工具和评估研究，请查看 badlogic/pi-share-hf。它将会话发布到 Hugging Face 数据集。

CLI 参考

pi [选项] [@文件...] [消息...]

包命令

pi install 源 [-l]     # 安装包，-l 为项目本地
pi remove 源 [-l]      # 移除包
pi uninstall 源 [-l]   # remove 的别名
pi update [源|self|pi] # 仅更新 pi 或一个包源
pi update --all        # 更新 pi 和包；解析固定 git 引用
pi update --extensions # 仅更新包；解析固定 git 引用
pi update --self       # 仅更新 pi
pi update --extension 源 # 更新单个包
pi list                # 列出已安装包
pi config              # 启用/禁用包资源

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

参见 Pi 包 了解包源和安全说明。

模式

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

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

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

模型选项

选项	描述
--provider 名称	提供商，如 anthropic、openai 或 google
--model 模式	模型模式或 ID；支持 provider/id 和可选的 :<thinking>
--api-key 密钥	API 密钥，覆盖环境变量
--thinking 级别	off, minimal, low, medium, high, xhigh, max
--models 模式	Ctrl+P 循环的逗号分隔模式
--list-models [搜索]	列出可用模型

会话选项

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

工具选项

选项	描述
--tools 列表, -t 列表	允许特定内置、扩展和自定义工具
--exclude-tools 列表, -xt 列表	禁用特定内置、扩展和自定义工具
--no-builtin-tools, -nbt	禁用内置工具但保留扩展/自定义工具
--no-tools, -nt	禁用所有工具

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

资源选项

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

组合 --no-* 与显式标志仅加载所需内容，忽略设置。例如：

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

其他选项

选项	描述
--system-prompt 文本	替换默认提示；上下文文件和技能仍会追加
--append-system-prompt 文本	追加到系统提示
--verbose	强制详细启动
-a, --approve	本次运行信任项目本地文件
-na, --no-approve	本次运行忽略项目本地文件
-h, --help	显示帮助
-v, --version	显示版本

文件参数

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

pi @提示.md "回答这个问题"
pi -p @截图.png "这张图片里有什么？"
pi @代码.ts @测试.ts "审查这些文件"

示例

# 交互模式带初始提示
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

环境变量

变量	描述
PI_CODING_AGENT_DIR	覆盖配置目录；默认 ~/.pi/agent
PI_CODING_AGENT_SESSION_DIR	覆盖会话存储目录；被 --session-dir 覆盖
PI_PACKAGE_DIR	覆盖包目录，对 Nix/Guix 存储路径很有用
PI_OFFLINE	禁用启动网络操作，包括更新检查和包安装/更新遥测
PI_SKIP_VERSION_CHECK	跳过启动时的 Pi 版本更新检查，防止向 pi.dev 发送最新版本请求
PI_TELEMETRY	覆盖安装/更新遥测和提供商归属标头：1/true/yes 或 0/false/no。不会禁用更新检查
PI_CACHE_RETENTION	在支持的地方设为 long 以扩展提示缓存
VISUAL, EDITOR	当 externalEditor 未设时作为 Ctrl+G 的外部编辑器回退；Windows 默认记事本，其他系统 nano

设计原则

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

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

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