Pi 编码代理使用教程：从交互界面到 CLI 实战
Pi 编码代理使用教程：从交互界面到 CLI 实战
本教程基于 Pi 官方文档 Using Pi 整理，覆盖日常使用的全部细节：交互界面、斜杠命令、消息队列、会话管理、上下文文件、项目信任机制，以及完整的 CLI 参考。
Pi 是一个刻意做小的编码代理（coding agent）：核心只提供读写文件、执行命令、会话管理等基础能力，把 MCP、子代理、权限弹窗、计划模式这些"大代理"功能全部留给扩展和技能生态。这篇教程按"先上手、再进阶、后进阶"的顺序，帮你把它的日常用法一次讲透。
1. 交互界面速览
直接运行 pi 即进入交互模式。界面分为四个区域：
| 区域 | 内容 |
|---|---|
| 启动头部 | 快捷键、已加载的上下文文件、提示词模板、技能与扩展 |
| 消息区 | 用户消息、模型回复、工具调用与结果、通知与错误 |
| 编辑器 | 你输入内容的地方；边框颜色表示当前思考等级（thinking level） |
| 底部状态栏 | 工作目录、会话名、token/缓存用量、花费、上下文占用、当前模型 |
编辑器还可以被内置 UI（如 /settings）或自定义扩展 UI 临时替换。
编辑器高频技巧
| 功能 | 操作 |
|---|---|
| 引用文件 | 输入 @ 模糊搜索项目文件 |
| 路径补全 | 按 Tab |
| 多行输入 | Shift+Enter（Windows Terminal 用 Ctrl+Enter） |
| 复制回复 | Ctrl+X：在 /tree 中复制选中消息；否则复制最后一条助手回复 |
| 粘贴图片 | Ctrl+V（Windows 用 Alt+V）或直接拖入终端 |
| 执行 shell 命令 | !command —— 执行并把输出发给模型 |
| 静默执行 shell 命令 | !!command —— 执行但不发给模型 |
| 外部编辑器 | Ctrl+G 打开 externalEditor / $VISUAL / $EDITOR |
一个非常实用的组合是 ! 前缀：比如 !git status，模型能直接"看到"命令输出并接着分析，省去复制粘贴。
2. 斜杠命令
输入 / 打开命令补全。扩展可以注册自定义命令，技能以 /skill:name 形式调用，提示词模板通过 /templatename 展开。常用命令如下：
会话类
| 命令 | 说明 |
|---|---|
/resume | 从历史会话中选择恢复 |
/new | 开新会话 |
/name <name> | 设置会话显示名 |
/session | 查看会话文件、ID、消息数、token 与花费 |
/tree | 跳转会话中任意节点，从那里继续 |
/fork | 从之前某条用户消息分叉出新会话 |
/clone | 把当前活跃分支复制为新会话 |
/compact [prompt] | 手动压缩上下文，可附自定义指令 |
模型与配置类
| 命令 | 说明 |
|---|---|
/login / /logout | 管理 OAuth 或 API key 凭据 |
/model | 切换模型；在选择器里按 Ctrl+S 保存为启动默认值 |
/thinking | 切换思考等级；同样支持 Ctrl+S 保存默认 |
/scoped-models | 配置 Ctrl+P 循环切换的模型集合 |
/llama | 下载/加载/卸载 llama.cpp 路由模型（本地模型） |
/settings | 主题、消息投递、传输等偏好 |
/trust | 保存当前项目的信任决定 |
/reload | 重载按键绑定、扩展、技能、模板、主题、上下文文件 |
导出与反馈类
| 命令 | 说明 |
|---|---|
/copy | 复制最后一条助手回复到剪贴板 |
/export [file] | 导出为 HTML 或 JSONL |
/share | 上传为私有 GitHub gist，得到可分享的 HTML 链接 |
/bug [描述] | 向 Pi 开发者报告 bug |
/hotkeys / /changelog / /quit | 快捷键总览 / 版本历史 / 退出 |
其中 /tree 是 Pi 的特色：会话在文件里是一棵消息树，你可以回到任何一个历史节点继续对话，还能对放弃的分支做摘要总结。
3. 消息队列：边跑边说
Pi 允许在代理还在干活时继续提交消息：
- Enter —— 发送"转向消息"（steering），在当前这轮助手工具调用执行完后立即投递；
- Alt+Enter —— 发送"追加消息"（follow-up），等代理完成全部工作后再投递；
- Escape —— 中止并把排队中的消息退回编辑器；
- Alt+Up —— 把排队消息取回编辑器。
投递行为可在 /settings 里通过 steeringMode 和 followUpMode 配置。注意 Windows Terminal 默认把 Alt+Enter 绑定为全屏，需要按官方 terminal-setup 文档重新映射。
实际体验：代理在跑长任务时，你发现方向偏了，直接 Enter 敲一句"注意别动测试文件"，它会在当前工具调用结束后收到并调整——这就是 steering 的价值。
4. 会话管理
会话自动保存到 ~/.pi/agent/sessions/，按工作目录归档。
pi -c # 继续最近的会话
pi -r # 浏览并选择历史会话
pi --no-session # 临时模式，不保存
pi --name "my task" # 启动时设置会话显示名
pi --session <path|id> # 使用指定会话文件或 ID
pi --fork <path|id> # 把某会话分叉为新会话文件配合 /session、/tree、/fork、/clone、/compact，可以完整掌控会话生命周期：
- 上下文快满了？
/compact把旧消息摘要压缩，腾出窗口； - 想试另一条思路？
/fork从早期某条消息分叉，主线不受影响； - 想把成果留档？
/export导出 HTML，或/share生成可分享链接（开源研究还可以用badlogic/pi-share-hf发布到 Hugging Face datasets）。
5. 上下文文件（AGENTS.md）
Pi 启动时按以下层级加载 AGENTS.md 或 CLAUDE.md：
- 全局：
~/.pi/agent/AGENTS.md - 父目录：从当前目录逐级向上查找
- 当前目录
若某目录中存在 AGENTS.override.md，该目录只加载它（取代 AGENTS.md/CLAUDE.md），其他目录仍正常分层。
用途：项目约定、常用命令、安全规则、个人偏好都写在这里。用 --no-context-files（或 -nc）可以禁用加载。
自定义系统提示词
- 项目级：
.pi/SYSTEM.md - 全局：
~/.pi/agent/SYSTEM.md
不想整体替换、只想追加？在任一位置放 APPEND_SYSTEM.md 即可。
6. 项目信任机制
首次进入一个包含项目级配置/资源/.agents/skills 且没有信任记录的目录时，Pi 会询问是否信任该项目。信任后才允许：
- 加载
.pi/settings.json与.pi资源； - 安装缺失的项目包；
- 执行项目扩展。
信任前的启动只加载上下文文件、用户/全局扩展和 CLI -e 扩展（以便它们能处理 project_trust 事件）。这条规则在切换到不同 cwd 的会话时同样生效。
几个要点：
- 非交互模式（
-p、--mode json、--mode rpc）不会弹窗询问，按~/.pi/agent/settings.json里的defaultProjectTrust（ask/always/never，默认ask）处理；也可用--approve/-a或--no-approve/-na单次覆盖。 pi config与包命令走同样的信任流程；pi update从不询问。/trust写入~/.pi/agent/trust.json，但当前会话不会重载，需要重启 pi 生效。
7. CLI 完整参考
pi [options] [--] [@files...] [messages...]包管理
pi install <source> [-l] # 安装包，-l 为项目级
pi remove <source> [-l] # 移除
pi update [source|self|pi] # 更新 pi 或某个包
pi update --all # 更新 pi + 全部包
pi list # 列出已安装包
pi config # 启用/禁用包资源运行模式
| 参数 | 说明 |
|---|---|
| 默认 | 交互模式 |
-p, --print | 打印回复后退出 |
--mode json | 所有事件以 JSON lines 输出（适合脚本对接） |
--mode rpc | 基于 stdin/stdout 的 RPC 模式 |
--export <in> [out] | 导出会话为 HTML |
打印模式还会读取管道 stdin 并合并进初始提示词：
cat README.md | pi -p "Summarize this text"模型选项
| 选项 | 说明 |
|---|---|
--provider <name> | 供应商，如 anthropic、openai、google |
--model <pattern> | 模型名或 ID，支持 provider/id 和 :thinking 后缀 |
--api-key <key> | 覆盖环境变量的 API key |
--thinking <level> | off/minimal/low/medium/high/xhigh/max |
--models <patterns> | Ctrl+P 循环切换的模型模式串 |
--list-models [search] | 列出可用模型 |
工具选项
| 选项 | 说明 |
|---|---|
--tools <list> / -t | 只允许指定工具 |
--exclude-tools <list> / -xt | 禁用指定工具 |
--no-builtin-tools / -nbt | 禁用内置工具，保留扩展工具 |
--no-tools / -nt | 全部禁用 |
内置工具：read、bash、powershell（Windows）、edit、write、grep、find、ls。
资源选项
| 选项 | 说明 |
|---|---|
-e, --extension <source> | 加载扩展（路径/npm/git），可重复 |
--no-extensions | 禁用扩展发现 |
--skill <path> | 加载技能，可重复 |
--no-skills | 禁用技能发现 |
--prompt-template <path> | 加载提示词模板，可重复 |
--theme <path> | 加载主题，可重复 |
--no-context-files, -nc | 禁用 AGENTS.md/CLAUDE.md 发现 |
组合 --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"
# 以破折号开头的提示词
pi -p -- "- Summarize these points"
# 管道输入
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"
pi --model openai/gpt-4o "Help me refactor"
# 模型 + 思考等级简写
pi --model sonnet:high "Solve this complex problem"
# 限制 Ctrl+P 切换范围
pi --models "claude-*,gpt-4o"
# 只读模式（代码审查很合适）
pi --tools read,grep,find,ls -p "Review the code"
# 只禁用某一个工具
pi --exclude-tools ask_question其他常用参数：--system-prompt 替换默认系统提示词（上下文文件和技能仍会追加）、--append-system-prompt 追加、--tui-mode regular|fullscreen 切换 TUI 模式、--use-theme 单次指定主题、-a/-na 单次控制项目信任、-h/-v 查看帮助与版本。
关于 fullscreen 模式：消息流在终端视口内滚动，队列消息、工作状态、编辑器、底部栏固定在底部；支持 Kitty 图形协议的终端（Kitty、Ghostty）可显示内联图片，iTerm2 会退化为文本占位符。regular 模式则使用终端自带回滚。
8. 设计哲学
Pi 的原则是核心做小，把工作流行为推给扩展、技能、提示词模板和包。它刻意不内置：
- MCP
- 子代理（sub-agents）
- 权限弹窗
- 计划模式（plan mode）
- 待办列表（to-dos）
- background bash
这些都可以作为扩展/包自己装，或者干脆用容器、tmux 等外部工具解决。完整的设计动机见作者 Mario Zechner 的博客文章。
小结
一句话上手路径：
pi进交互模式，用@引用文件、!跑命令；- 用
/model、/thinking选好模型和思考等级，Ctrl+S 存默认； - 项目根放
AGENTS.md写约定，首次进入时信任项目； - 长任务用消息队列（Enter 转向、Alt+Enter 追加）；
- 会话自动保存，
pi -c续上，/tree回溯，/compact压缩； - 脚本化用
pi -p+ 管道，或--mode json； - 不够用的能力，装扩展或技能，而不是等官方内置。