pi coding-agent 日常使用详解：交互模式、斜杠命令、会话管理、项目信任与完整 CLI 参考

本文基于 pi 仓库中的官方使用文档 usage.md 撰写，覆盖交互模式界面与编辑器能力、全部内置斜杠命令、消息队列、会话管理、上下文文件与项目信任机制、会话导出/共享，以及 pi CLI 的完整选项参考。读完后你可以掌握 pi coding-agent 的日常操作全貌，并能结合仓库源码理解每个参数在实现层是如何被解析和生效的。

交互模式

pi 的交互式 TUI 由四个主要区域构成：

• 启动头部（Startup header）：显示快捷键、已加载的上下文文件、prompt 模板、skills 与扩展；
• 消息区（Messages）：用户消息、助手回复、工具调用与工具结果、通知、错误信息以及扩展的自定义 UI；
• 编辑器（Editor）：输入区，边框颜色指示当前 thinking 级别；
• 页脚（Footer）：显示工作目录、会话名称、token/缓存用量、成本、上下文占用与当前模型。累计值包含助手回复、工具上报的用量以及摘要生成的消耗。

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

编辑器能力

功能	触发方式
文件引用	输入 @ 模糊搜索项目文件
路径补全	按 Tab 补全路径
多行输入	Shift+Enter，Windows Terminal 下为 Ctrl+Enter
复制回复	Ctrl+X 复制 /tree 中选中的消息；否则复制最后一条助手消息；fullscreenCopyOnSelect 禁用时复制当前全屏文本选区
图片	Ctrl+V 粘贴，Windows 下 Alt+V，或拖拽进终端
Shell 命令	!command 执行并把输出发送给模型
隐藏 Shell 命令	!!command 执行但不把输出发给模型
外部编辑器	Ctrl+G 打开 externalEditor、$VISUAL、$EDITOR，Windows 下为 Notepad，其他系统为 nano

完整快捷键与自定义方式见 Keybindings 文档。

斜杠命令

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

内置命令定义在 slash-commands.ts 的 BUILTIN_SLASH_COMMANDS 常量中，与文档命令表一一对应：

命令	说明
/login、/logout	管理 OAuth 或 API key 凭据
/llama	下载、加载、卸载 llama.cpp 路由模型（见 llama.cpp 文档）
/model	切换模型；选择器中按 Ctrl+S 保存为启动默认值
/thinking	切换 thinking 级别；选择器中按 Ctrl+S 保存为启动默认值
/scoped-models	启用/禁用参与 Ctrl+P 循环切换的模型
/settings	主题、消息投递、传输方式等偏好设置
/resume	从历史会话中选择恢复
/new	开始新会话
/name <name>	设置会话显示名
/session	显示会话文件、ID、消息数、token 与成本
/tree	跳转到会话树中任意节点并从该处继续
/trust	为未来会话保存项目信任决定
/fork	从之前的某条用户消息创建新会话
/clone	将当前活动分支复制到新会话
/compact [prompt]	手动压缩上下文，可选自定义指令
/copy	复制最后一条助手消息到剪贴板
/export [file]	导出会话为 HTML 或 JSONL
/import <file>	从 JSONL 文件导入并恢复会话
/share	上传为私有 GitHub gist 并生成可共享的 HTML 链接
/reload	重新加载键位、扩展、skills、prompts、主题与上下文文件
/hotkeys	显示全部键盘快捷键
/changelog	显示版本历史
/quit	退出 pi

消息队列

Agent 工作期间可以继续提交消息：

• Enter：加入一条 steering 消息，在当前助手回合执行完工具调用后投递；
• Alt+Enter：加入一条 follow-up 消息，在 agent 完成全部工作后投递；
• Escape：中止当前处理，把已排队的消息还原回编辑器；
• Alt+Up：把已排队的消息取回编辑器。

Windows Terminal 中 Alt+Enter 默认是全屏切换，若希望 pi 能接收该快捷键，需要按 终端设置文档 做重映射。

投递行为由设置项 steeringMode 与 followUpMode 控制（见 Settings 文档）。从源码看，两者都取值为 "all" | "one-at-a-time"，且默认值为 "one-at-a-time"——在 settings-manager.ts 中，getSteeringMode() 返回 this.settings.steeringMode || "one-at-a-time"，getFollowUpMode() 同理；旧设置 queueMode 还会被自动迁移为 steeringMode。这两个值最终通过 sdk.ts 传入 agent 运行时（agent.steeringMode / agent.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：全局指令；
• 从当前工作目录向上遍历的各级父目录；
• 当前目录。

如果某个目录包含 AGENTS.override.md，pi 会加载它而不加载该目录中的 AGENTS.md 或 CLAUDE.md；其他目录的上下文文件仍按正常顺序叠加。上下文文件适合存放项目约定、命令、安全规则与偏好设置。可用 --no-context-files 或 -nc 关闭加载。

从源码看，resource-loader.ts 中的候选文件列表为 ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]——也就是说大小写变体（AGENTS.MD、CLAUDE.MD）同样被识别，且 AGENTS.override.md 排在最前面，优先命中。

系统提示文件

用以下方式替换默认系统提示：

• 项目级：.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 事件；项目本地扩展、项目包管理的扩展与项目设置要等项目被信任后才加载。切换到不同 cwd 的会话且当前进程尚未解析其信任状态时，同样适用这一拆分。

非交互模式（-p、--mode json、--mode rpc）不显示信任提示。在没有适用的已保存信任决定时，它们采用全局设置中的 defaultProjectTrust：ask（默认）与 never 会忽略这些项目资源，always 则信任它们。也可以用 --approve/-a 或 --no-approve/-na 在单次运行中覆盖项目信任。

从实现看，完整流程集中在 project-trust.ts 的 resolveProjectTrusted() 中，优先级依次为：

1. 命令行覆盖（trustOverride）直接返回；
2. 目录中不存在需要信任的项目资源（hasTrustRequiringProjectResources）时直接返回信任；
3. 发射 project_trust 扩展事件，扩展可返回 trusted 与 remember 决定（remember=true 时写入信任存储）;
4. 查询 trust.json 中已保存的决定；
5. 否则按 defaultProjectTrust ?? "ask" 分支：always 返回 true，never 返回 false，ask 进入交互选择；
6. 非交互环境（hasUI 为 false）最终回退为不信任。

信任存储路径由 trust-manager.ts 定义：join(resolvePath(agentDir), "trust.json")，即 ~/.pi/agent/trust.json。

/trust 命令在交互模式下保存项目信任决定（包括对直接父目录的信任），它只写 ~/.pi/agent/trust.json，不会重载当前会话，需要重启 pi 才生效。defaultProjectTrust 可设为 "ask"、"always"、"never"，写在 ~/.pi/agent/settings.json 或通过 /settings 修改。pi config 与包管理命令使用相同的项目信任流程，但 pi update 从不提示；可用 --approve 在单条命令中信任项目本地设置，或用 --no-approve 忽略它们。

会话导出与共享

• /export [file]：把会话写为 HTML 文件；
• /share：上传为私有 GitHub gist，返回可共享的 HTML 链接。

如果你用 pi 做开源工作并希望发布会话用于模型、提示词、工具与评测研究，pi 仓库提供了发布到 Hugging Face 数据集的配套工具 badlogic/pi-share-hf（文档中提及的外部项目）。

CLI 参考

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

所有选项由 args.ts 中的 parseArgs() 解析。值得注意的两个实现细节：

• --thinking 的合法值在 VALID_THINKING_LEVELS 中硬编码为 off, minimal, low, medium, high, xhigh, max，非法值会产生 warning 而非直接报错；
• 以 -- 开头的未知 flag 不会丢弃，而是存入 unknownFlags，供扩展注册的 CLI flag（如 plan-mode 扩展的 --plan）使用——这也是扩展可以扩展 CLI 的底层机制。

包管理命令

pi install <source> [-l]     # 安装包，-l 表示项目本地
pi remove <source> [-l]      # 移除包
pi uninstall <source> [-l]   # remove 的别名
pi update [source|self|pi]   # 只更新 pi，或更新某个包来源
pi update --all              # 更新 pi 与包；协调 pinned git 引用
pi update --extensions       # 只更新包；协调 pinned git 引用
pi update --models           # 只刷新模型目录
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 文档。

运行模式

标志	说明
默认	交互模式
-p、--print	打印响应后退出
--mode json	以 JSON Lines 输出所有事件，见 JSON 模式
--mode rpc	通过 stdin/stdout 的 RPC 模式，见 RPC 模式
--export <in> [out]	将会话导出为 HTML

print 模式下，pi 还会读取管道 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]	列出可用模型

会话选项

选项	说明
-c、--continue	继续最近一次会话
-r、--resume	浏览并选择会话
--session <path|id>	使用指定会话文件或 partial UUID
--fork <path|id>	将会话文件或 partial UUID 分叉到新会话
--session-dir <dir>	自定义会话存储目录
--no-session	临时模式，不保存
--name <name>、-n <name>	启动时设置会话显示名

工具选项

选项	说明
--tools <list>、-t <list>	白名单指定内置、扩展与自定义工具
--exclude-tools <list>、-xt <list>	禁用指定内置、扩展与自定义工具
--no-builtin-tools、-nbt	禁用内置工具，但保留扩展/自定义工具
--no-tools、-nt	禁用全部工具

内置工具为：read、bash、powershell（Windows）、edit、write、grep、find、ls。这些工具的实现位于 core/tools 目录。

资源选项

选项	说明
-e、--extension <source>	从路径、npm 或 git 加载扩展，可重复
--no-extensions	禁用扩展发现
--skill <path>	加载一个 skill，可重复
--no-skills	禁用 skill 发现
--prompt-template <path>	加载 prompt 模板，可重复
--no-prompt-templates	禁用 prompt 模板发现
--theme <path>	加载主题，可重复
--no-themes	禁用主题发现
--no-context-files、-nc	禁用 AGENTS.md 与 CLAUDE.md 发现

把 --no-* 与显式 flag 组合，可以在忽略设置的前提下精确加载所需资源。例如：

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

其他选项

选项	说明
--system-prompt <text>	替换默认提示；上下文文件与 skills 仍会附加
--append-system-prompt <text>	追加到系统提示
--tui-mode <mode>	TUI 模式：regular（默认）或实验性的 fullscreen
--use-theme <name[/name]>	设置本次运行的初始交互主题，不修改设置
--verbose	强制 verbose 启动
-a、--approve	本次运行信任项目本地文件
-na、--no-approve	本次运行忽略项目本地文件
--	停止选项解析，其余参数视为提示或 @file 输入
-h、--help	显示帮助
-v、--version	显示版本

fullscreen 模式下，transcript 在终端视口内滚动，而排队消息、工作状态、扩展 widget、编辑器与页脚固定在底部；鼠标/触控板可滚动指针所在区域，键盘视口操作始终可用。内联图片在支持 Kitty 图形协议的终端（Kitty、Ghostty）中可正常渲染；iTerm2 因其内联图片协议无法在应用自管滚动时删除或裁剪图片位置，只能渲染为文本占位符。regular 模式下 pi 使用主屏幕与终端自管的 scrollback，iTerm2 的内联图片可正常渲染。终端专属设置与变通方案见 Terminal setup 文档。

也可在 /settings 中设置 TUI mode，在 regular 与 fullscreen 之间立即切换并选择默认值。Fullscreen exit output 控制退出全屏时是打印最终 transcript，还是恢复上一屏幕并只打印会话恢复提示。

文件参数

用 @ 前缀把文件包含进消息：

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

在 args.ts 中，以 @ 开头的参数会去掉前缀后进入 fileArgs；而 -- 之后的所有参数无论是否带 @ 前缀，也都会分别归入 fileArgs 或 messages——这解释了为什么 pi -p -- "- Summarize these points" 这类以连字符开头的提示能正常工作。

实战示例

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

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

# 以连字符开头的提示
pi -p -- "- Summarize these points"

# 非交互模式 + 管道 stdin
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 级别简写的模型
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 mode、to-do 列表或后台 bash——这些工作流可以通过扩展或包自行构建安装，也可以使用容器、tmux 等外部工具实现。完整的设计理由见 pi 官方 blog（文档中引用的作者博文）。

---

扩展阅读（均在当前仓库内）：

• Quickstart、Sessions、Compaction、Settings
• JSON 模式、RPC 模式、Keybindings
• Pi Packages、Skills、Prompt 模板、扩展
• 测试与实现：args 解析、args 测试、信任管理 及其 测试