#使用 Pi

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

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

#交互模式

交互界面分为四个主要区域：

• 启动头部（Startup header） —— 显示快捷键、已加载的上下文文件、Prompt 模板、Skills 和扩展
• 消息区域（Messages） —— 用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器（Editor） —— 输入区域，边框颜色反映当前 thinking level
• 底部栏（Footer） —— 显示工作目录、会话名称、Token/缓存使用、成本、上下文使用量和当前模型

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

#编辑器功能

有关所有快捷键和自定义设置，请参阅 Keybindings。

#斜杠命令（Slash Commands）

在编辑器中输入 / 会打开命令补全。扩展可以注册自定义命令，Skills 以 /skill:name 形式出现，Prompt 模板以 /templatename 展开。

#消息队列

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

• Enter 将 steering 消息加入队列，在当前助手回合完成工具调用后投递。
• Alt+Enter 将 follow-up 消息加入队列，在 Agent 完成所有工作后投递。
• Escape 中断并将队列消息恢复到编辑器。
• Alt+Up 将队列消息取回编辑器。

在 Windows Terminal 上，Alt+Enter 默认为全屏。如要使 Pi 接收到该快捷键，请按照 Terminal 设置 中的描述重新映射。

投递行为可通过 Settings 中的 steeringMode 和 followUpMode 配置。

#会话（Sessions）

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

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择会话
pi --no-session        # 临时模式，不保存
pi --session <path|id> # 使用特定会话文件或会话 ID
pi --fork <path|id>    # 从会话分叉到新会话文件

有用的会话命令：

• /session 显示当前会话文件和 ID。
• /tree 导航会话内文件树，可以摘要被放弃的分支。
• /fork 从之前的用户消息创建新会话。
• /clone 将当前活跃分支复制到新会话文件。
• /compact 总结旧消息以释放上下文。

详见 Sessions 和 Compaction。

#上下文文件

Pi 在启动时加载 AGENTS.md 或 CLAUDE.md：

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

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

#系统 Prompt 文件

使用 .pi/SYSTEM.md 替换项目默认系统 Prompt，或 ~/.pi/agent/SYSTEM.md 全局替换。使用 APPEND_SYSTEM.md 在相同位置追加到默认 Prompt 之后，而不替换它。

#导出和分享会话

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

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

如果你将 Pi 用于开源工作，并希望发布用于模型、Prompt、工具和评估研究的会话，请参考 badlogic/pi-share-hf。它将会话发布到 Hugging Face 数据集。

#CLI 参考

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

#包管理命令

pi install <source> [-l]     # 安装包，-l 为项目本地安装
pi remove <source> [-l]      # 移除包
pi uninstall <source> [-l]   # remove 的别名
pi update [source|self|pi]   # 更新 Pi 和包；跳过固定的包
pi update --extensions       # 仅更新包
pi update --self             # 仅更新 Pi
pi update --extension <src>  # 更新单个包
pi list                      # 列出已安装的包
pi config                    # 启用/禁用包资源

这些命令管理 Pi 包，而非 Pi CLI 安装本身。要卸载 Pi 本身，请参阅 Quickstart。

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

#模式

在 print 模式下，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"

#示例

# 交互式初始提示
pi "List all .ts files in src/"

# 非交互式
pi -p "Summarize this codebase"

# 非交互式带管道传入
cat README.md | pi -p "Summarize this text"

# 不同模型
pi --provider openai --model gpt-4o "Help me refactor"

# 带 Provider 前缀的模型
pi --model openai/gpt-4o "Help me refactor"

# 带 thinking level 简写的模型
pi --model sonnet:high "Solve this complex problem"

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

# 只读模式
pi --tools read,grep,find,ls -p "Review the code"

#环境变量

#设计原则

Pi 将核心保持小巧，将工作流特定的行为推到扩展、Skills、Prompt 模板和包中。

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

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

法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。