#使用 Pi

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

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

#交互模式

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

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

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

#编辑器功能

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

#斜杠命令（Slash Commands）

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

#消息队列

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

• Enter 将 steering 消息加入队列，在当前助手回合完成 tool call 后送达。
• 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 --name "my task"    # 启动时设置会话显示名称
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 之后，而不替换它。

#项目信任

在交互式启动时，如果项目目录包含项目本地设置、资源或项目 .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 用于开源工作，并希望发布用于模型、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 --all              # 更新 Pi 和包；协调固定的 git ref
pi update --extensions       # 仅更新包；协调固定的 git ref
pi update --self             # 仅更新 Pi
pi update --extension <src>  # 更新单个包
pi list                      # 列出已安装的包
pi config                    # 启用/禁用包资源

这些命令管理 Pi 包，且 pi update 可以更新 Pi CLI 安装本身。要卸载 Pi 本身，请参阅 Quickstart。pi config 与项目包命令接受 --approve/--no-approve，以便在单次命令中信任或忽略项目本地设置。pi update 从不提示项目信任。

包来源和安全说明请参阅 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 --name "release audit" -p "Audit this repository"

# 不同模型
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 --exclude-tools ask_question

#环境变量

#设计原则

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

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

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

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