第三章：快速入门：首次交互

本章从零开始，手把手带你完成 Pi 的第一次交互——从最简单的命令行提问，到掌握交互式 TUI 的日常操作、会话管理、模式切换等核心技能。读完本章，你就能把 Pi 真正用起来。

前置要求：已完成第二章：安装与环境配置中的安装与认证步骤。如果你还没有配好 API Key 或订阅，现在去做，三分钟后回来。

3.1 两种基本运行方式

Pi 有两种最核心的运行方式，理解它们的区别是所有高级用法的起点。

3.1.1 交互式模式（默认）

不带任何特殊参数，直接在项目目录下运行：

pi "列出当前目录的所有 .ts 文件"

Pi 会进入全屏交互界面（TUI）。界面从上到下分为四个区域：

运行 pi "列出当前目录的所有 .ts 文件" 后，你可以看到模型如何一步一步调用工具完成任务：

1. 模型收到你的指令，判断需要列出 .ts 文件
2. 模型调用 bash 工具，执行 find . -name "*.ts" 或类似命令
3. 终端显示工具调用结果（文件列表）
4. 模型读取结果并整理回复

整个过程透明可见——Pi 不会假装知道，它会真的去执行命令、读取文件、编辑代码。

继续尝试更多交互式命令：

pi "解释这个函数的逻辑"

模型会读取目标文件，分析函数结构，并用自然语言解释其工作方式。

pi "帮我重构这段代码，拆成两个函数"

模型会读取代码、规划重构方案、执行编辑操作，并逐一展示每一步的修改。

3.1.2 Print 模式（-p 参数）

如果你只需要一次性的答案，不需要交互界面，用 -p：

pi -p "总结这段代码"

Pi 处理完毕后直接输出结果并退出——不进入 TUI，不回环追问，不等待你确认。这个模式专为以下场景设计：

• 脚本 / 流水线：在 Shell 脚本中嵌入 Pi，自动化分析、格式化、解释代码
• CI/CD：在构建流水线中做代码审查、变更摘要、依赖分析
• 管道组合：把 Pi 的输出作为其他命令的输入

Print 模式还支持管道（pipe）输入：

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

Pi 会自动把管道传入的 stdin 拼接到初始提示中，然后给出回复。

更完整的例子：

# 审查一个 commit 的 diff
git diff HEAD~1 | pi -p "Review this diff for bugs and security issues"

# 给一次性的命名
pi --name "CI audit" -p "Review this build failure log" < ci.log

# 带图片的分析
pi -p @screenshot.png "这张截图里有什么异常？"

Print 模式下，Project Trust（项目信任）的行为与交互模式不同：非交互模式不会弹出信任提示，而是根据全局设置 defaultProjectTrust 来决定是否加载项目本地资源。需要时可以通过 --approve 或 --no-approve 手动指定。

3.2 编辑器（Editor）进阶操作

编辑器不仅是输入框，它集成了很多便利功能。

3.2.1 文件引用：@ 模糊搜索

在交互模式下，输入 @ 就会触发模糊文件搜索——一个覆盖当前项目的文件选择器弹出，你可以边打字边筛选，按回车确认。

你: @code.ts
你: @code.ts @test.ts "审查这些文件的差异"

这个功能极大减少了手动输入路径的痛苦。切换到哪个文件？直接 @ 加几个字符就够了。

3.2.2 图片支持

Pi 支持多模态模型（如 Claude Sonnet / Opus、GPT-4o 等），可以直接分析图片。放入图片的方式有两种：

• 粘贴：在编辑器中按 Ctrl+V（Linux/macOS）或 Alt+V（Windows），将剪贴板中的图片粘贴进去
• 拖拽：直接从文件管理器中把图片拖到终端窗口

图片会作为多模态消息的一部分发送给模型。在 Print 模式下也一样：

pi -p @screenshot.png "这张图片里有什么？"

@ 文件引用在 Print 和交互模式下均有效。对于图片文件，Pi 会自动识别并转为多模态输入。

3.2.3 多行编辑与外部编辑器

如果你需要写一个长 prompt、编辑一个 Skill 草稿或调试一段代码，用 Ctrl+G 唤起你最习惯的编辑器，编辑完保存退出后内容自动回填到 Pi 中。

3.2.4 消息队列：边聊边排队

Pi 的一个精妙设计是消息队列——当模型正在执行工具调用（比如正在跑一个长脚本），你不需要干等。你可以继续打字，把下一条消息排进队列，模型会在合适的时机接收并处理：

你还可以在 Settings 中精细化控制消息交付策略：steeringMode 和 followUpMode 可以设为 "one-at-a-time"（默认，等一次回复后再发下一条）或 "all"（全部排队消息一次性交付）。

3.3 斜杠命令（Slash Commands）

在编辑器中输入 / 即可打开命令补全菜单。下面是核心命令的快速检索表：

常用键盘快捷键一览：

3.4 使用 ! 执行 Shell 命令（交互式）

在交互模式的编辑器中，你可以用 ! 前缀让 Pi 执行 Shell 命令，并把输出或结果一并交给模型。这是最方便的动态上下文注入方式。

3.4.1 !command：输出发送给模型

你: 我的代码有什么风格问题？先看看 eslint 的结果：
你: !npx eslint src/ --format compact

上面的例子中，npx eslint src/ --format compact 由 Pi 执行，其标准输出会直接拼接在你的消息后面一起发给模型。模型会同时看到你的问题和 eslint 的报告，然后针对性地给出建议。

更多典型用法：

你: 查一下最近 5 个 commit，解释每个做了什么：
你: !git log --oneline -5

你: 帮我分析测试失败的原因：
你: !npm test 2>&1

3.4.2 !!command：静默执行

双叹号 !!command 执行命令，但不把输出发给模型——适用于你只想做前置准备，不希望输出污染模型上下文的情况：

你: !!npm install
你: 依赖装好了，帮我分析 package.json 中是否有过时的版本

模型不会看到 npm install 的输出，只收到了你的问题。这在做环境准备工作时十分有用。

3.5 会话管理：记住每一次对话

Pi 的会话管理是其区别于”一次性问答工具”的关键能力之一。所有对话完整记录，随时可以继续、分支、回顾。

3.5.1 会话存储位置

Pi 自动把所有会话保存为 JSONL 文件，默认路径为：

~/.pi/agent/sessions/

文件以工作目录为单位组织——不同项目的会话互不干扰。

3.5.2 会话的树结构：id 与 parentId

Pi 的会话不是线性的聊天记录，而是一棵树。每条消息（entry）都有自己的 id 和 parentId。每当你在 /tree 中回跳到历史节点重新提问，就创建了一个新分支——所有历史都保留在同一个 JSONL 文件中，没有任何东西被覆盖。

一个典型的会话树形结构如下：

├─ user: "你好，帮我……"
│  └─ assistant: "当然！我可以……"
│     ├─ user: "试试方案 A……"
│     │  └─ assistant: "关于方案 A……"
│     │     └─ user: "这可行……"  ← 当前活跃
│     └─ user: "其实，试试方案 B……"
│        └─ assistant: "关于方案 B……"

这种设计让你可以无成本地在同一个会话文件中探索多条路径、对比不同方案的效果，而不会丢失任何记录。它也是 Pi 的 /tree、/fork、/clone 等高级会话操作的基础。

3.5.3 新建会话

pi                        # 启动新会话（默认行为）

交互模式下也可以用命令：

/new    # 开始新会话

新会话的初始提示可以从命令行参数带入：

pi "帮我审查 src/ 目录下的所有 TypeScript 文件"

3.5.4 继续最近会话

pi -c                     # 继续最近一次会话

-c 等价于 --continue。它会找到当前项目下最近使用的会话文件，从上次中断的地方继续。适合”稍微休息一下，回来继续干活”的场景。

3.5.5 从历史会话列表恢复

pi -r                     # 打开历史会话选择器

-r 等价于 --resume，打开一个交互式的会话选择器，列出当前项目的全部历史会话。在交互模式下你也可以随时用 /resume 进入同一个选择器。

在会话选择器中你可以：

3.5.6 /resume 命令

在交互模式中随时按 Esc → 输入 /resume 就能调出会话选择器并切换到另一段历史对话。结合 /tree，Pi 的会话能力远不止”加载/保存”——它让你在任何时间点审视历史、重做选择。

3.5.7 指定会话与 Fork

pi --session <path|id>    # 使用特定的会话文件或部分 UUID
pi --fork <path|id>       # 从特定会话 Fork 出一个新会话

在交互模式下可以用 /session 查看当前会话的文件路径和 ID，方便以后用 --session 精确指定。

3.6 分支与会话树操作：/tree、/fork、/clone

3.6.1 /tree：在同一个会话中自由穿梭

按下 Esc 两次或输入 /tree，打开可视化的会话树导航界面。你可以在会话树中上下浏览、折叠展开分支、跳转到任意历史节点并在原地重新开始——所有变更都保存在同一个会话文件中，不会创建新文件。

过滤模式有五种：默认、隐藏工具调用、仅用户消息、仅带标签的消息、全部显示。可以通过 treeFilterMode 在 Settings 中配置默认过滤模式。

选择用户消息或自定义消息时：Pi 会把当前叶子节点移动到该消息的父节点位置，并将该消息文本填入编辑器等待你修改后重新发送——这会产生一个新分支。

选择助手消息、工具调用结果、compaction 记录或其他非用户条目时：Pi 把叶子节点移到该条目，编辑器留空，让你直接从该点继续对话。

3.6.2 /fork：从历史消息创建新会话

想从一个早期提示开始全新的探索？用 /fork——它会打开一个用户消息选择器，从当前活跃分支中选取一个历史提示，复制该路径的完整历史到独立的新会话文件，并把选中的原始提示放进编辑器等你调整。

3.6.3 /clone：复制当前分支到新会话

/clone 把当前活跃分支的完整路径复制到一个新会话文件中，停在当前位置，编辑器为空——适合”我希望把当前进展存档，然后在这个基础上继续探索”的场景。

3.6.4 三者的对比

3.6.5 分支摘要

当你在 /tree 中从一个分支切换到另一个时，Pi 会询问是否要对被放弃的分支生成摘要。摘要会附加在新位置的消息中，这样你不需要重放整个被放弃分支，就能了解那里发生了什么关键进展。

你有三种选择：

1. 不生成摘要
2. 使用默认提示生成摘要
3. 使用自定义焦点指令生成摘要

3.7 指定模型

Pi 支持 30+ 供应商、200+ 模型，一行命令切换。

3.7.1 在交互模式中切换

最方便的方式是交互模式的 /model 命令——弹出模型列表，选择目标模型即可。你也可以按 Ctrl+L 直接打开模型选择器。

3.7.2 从命令行指定

pi --provider openai --model gpt-4o "重构这个函数"

你也可以把供应商和模型写在一起，省去 --provider：

pi --model openai/gpt-4o "重构这个函数"

Pi 支持为模型名附加思考等级简写：

pi --model sonnet:high "解决这个复杂问题"

sonnet:high 会被解析为 “使用 Sonnet 模型并启用高思考等级（high thinking）”。等价的写法：

pi --model claude-sonnet-4-20250514 --thinking high "解决这个复杂问题"

3.7.3 限制模型切换范围

用 --models 指定 Ctrl+P 循环切换的模型列表，这在需要控制成本或锁定模型时非常实用：

pi --models "claude-*,gpt-4o" "帮我开发"

这样 Ctrl+P 只会在这两个模型间切换，不会意外切到其他模型。

3.7.4 列出可用模型

pi --list-models            # 列出所有已配置的模型
pi --list-models "claude"   # 按名称搜索

3.7.5 单独控制思考等级

pi --thinking high "解决这个复杂问题"

思考等级从低到高：off → minimal → low → medium → high → xhigh。可在交互模式下用 Shift+Tab 循环切换，或通过 /settings 面板设置。

3.8 只读模式：限制工具范围

你是想让模型审查代码，不希望它修改任何文件？Pi 内置了精确的工具控制机制。

3.8.1 白名单模式

pi --tools read,grep,find,ls -p "审查代码安全性"

--tools（或 -t）接受一个逗号分隔的工具名列表，仅启用列出的工具。上面的命令只允许模型 read（读取文件）、grep（文本搜索）、find（文件查找）、ls（目录列表）——没有 write、edit、bash，模型不可能修改文件或执行命令。这是代码审查中最安全的做法。

3.8.2 黑名单模式

pi --exclude-tools bash

--exclude-tools（或 -xt）禁用指定的工具，其他工具保持可用。上面这个例子中，模型可以读取、编辑、写文件，但不能执行 Shell 命令。

3.8.3 全部禁用

pi --no-builtin-tools       # 仅禁用七个内置工具，Extensions 注册的工具仍然可用
pi --no-tools               # 禁用所有工具，仅做纯对话

3.8.4 Pi 的七个内置工具

Pi 的极简哲学在工具数量上体现得很直观——就七个：

七个工具覆盖了编码工作的全部底层操作——读、写、改、搜、查、跑命令。Pi 不内置 Git、LSP、MCP 等高级工具，这些可以通过 Extensions 或 Skills 按需加载（参见第八章、第九章）。

3.9 四种运行模式概览

Pi 支持的四种运行模式各有使用场景：

3.9.1 交互式（默认）

你已经在前面的章节中充分体验了。TUI 界面、文件引用、消息队列、! 命令——所有特性在交互模式中可用。

3.9.2 Print 模式（-p）

详见 3.1.2 节。核心特征：一次输入、一次输出、立即退出。

3.9.3 JSON 模式（--mode json）

pi --mode json -p "列出当前目录的所有 .ts 文件"

每行输出一条结构化的 JSON 事件（消息增量、工具调用、工具结果等）。适合构建自定义前端、日志采集系统或需要精确解析输出的自动化工具。详细协议参见 JSON 模式文档。

3.9.4 RPC 模式（--mode rpc）

pi --mode rpc

启动后 Pi 进入一个持久的 stdin/stdout RPC 服务，通过换行符 \n 分隔的 JSONL 帧进行通信。适用于非 Node.js 环境或需要长驻进程的场景。协议细节参见 RPC 模式文档。

注意：RPC 模式要求客户端确切地按 \n 分割帧，不要使用通用行阅读器（如 Node.js 的 readline），因为它会在 JSON 内容中的 Unicode 分隔符处也进行分割，导致帧边界错乱。

3.10 上下文文件：让 Pi 自动了解项目

启动 Pi 后，如果你在启动头看到 “AGENTS.md loaded” 之类的提示，那是因为 Pi 自动从以下位置加载了上下文文件：

1. ~/.pi/agent/AGENTS.md — 全局通用指令
2. 从当前目录向上遍历父目录，加载路径上所有的 AGENTS.md 或 CLAUDE.md
3. 当前目录的 AGENTS.md 或 CLAUDE.md

所有匹配的文件内容会被拼接并注入系统提示。这是给 Pi 提供项目约定的最佳方式——你可以告诉 Pi 项目的构建命令、代码风格偏好、常见陷阱：

# AGENTS.md
- 本项目使用 pnpm，不要使用 npm 或 yarn
- 所有公开 API 必须先写 TSDoc
- 单元测试文件与源文件放在同一个目录，后缀 .test.ts
- 不要直接修改 dist/ 目录

如果你需要替换默认系统提示（而不是追加），可以创建 .pi/SYSTEM.md（项目级）或 ~/.pi/agent/SYSTEM.md（全局）。如果你只想追加内容而不替换，使用 APPEND_SYSTEM.md。

用 --no-context-files 或 -nc 可以暂时禁用上下文文件加载。

3.11 一个完整的首次交互示例

让我们走一遍完整的”入职”流程，从安装后第一次启动到一个典型任务完成。

Step 1：启动

cd ~/projects/my-app
pi

Pi 启动，显示启动头，然后停在编辑器等待你的第一条消息。

Step 2：第一次提问

你: 这是什么项目？阅读 README.md 和 package.json 给我概述一下

模型依次调用 read 工具读取这两个文件，然后组织回答：

●⏺  read README.md
●⏺  read package.json

Pi: 这是一个基于 React + Vite 的前端项目，主要……

Step 3：让 Pi 改代码

你: 给 src/utils/format.ts 的 formatDate 函数加上 JSDoc

模型调用 read 读取文件，然后用 edit 工具精确插入 JSDoc 注释，最后请你确认。

Step 4：审查修改

你: 审查你刚才的修改是否正确，以及是否有遗漏

模型会再次读取修改后的文件，逐行分析逻辑和边界情况，给出审查结论。

Step 5：用 ! 执行测试

你: 跑一下单元测试，看看我们的修改有没有破坏什么：
你: !npm test

Pi 执行 npm test，把输出拼进消息，模型根据测试结果判断是否一切正常。

Step 6：命名并退出

你: /name 添加 formatDate JSDoc
你: /quit

下次再用 pi -c 启动时，就会自动回到这个已命名的会话，继续之前的工作。

3.12 项目信任（Project Trust）

首次在一个包含 .pi/settings.json、.pi/ 资源文件或 .agents/skills/ 的目录中启动交互式 Pi 时，你会看到一个项目信任提示。这是因为本地项目配置、Extensions 或 Skills 可能执行代码——Pi 需要你明确授权后才加载。

交互模式中，选择信任后用 /trust 保存决策到 ~/.pi/agent/trust.json，以后进入相同（或上级）目录就不会再次提示。/trust 写入后需重启 Pi 才能生效。

非交互模式（-p、--mode json、--mode rpc）不会弹出提示，而是根据 settings.json 中的 defaultProjectTrust 决定行为：

• "ask"（默认）或 "never"：忽略项目本地资源
• "always"：自动信任

你可以用 --approve / -a 或 --no-approve / -na 临时覆盖。

3.13 本章小结

本章覆盖了 Pi 日常使用的核心技能：

• 两种基本运行方式：交互式 TUI（pi）和 Print 模式（pi -p）
• 编辑器功能：@ 模糊文件搜索、图片粘贴/拖拽、多行编辑、外部编辑器、消息队列
• 斜杠命令：/model、/resume、/tree、/new、/settings 等 20+ 条内置命令
• ! Shell 命令：!command 将输出发给模型，!!command 静默执行
• 会话管理：JSONL 树结构（id / parentId）、pi -c 继续、pi -r 恢复、/tree 分支、/fork 独立分支、/clone 复制归档
• 模型切换：--provider + --model、模型简写、思考等级控制
• 工具控制：白名单（--tools read,grep,find,ls）、黑名单（--exclude-tools）、全部禁用
• 四种运行模式：交互式、Print、JSON、RPC
• 上下文文件：AGENTS.md / CLAUDE.md 自动加载
• 项目信任：理解及管理项目信任决策

现在你已经可以用 Pi 完成绝大多数的日常编码任务了。下一章：第四章：模型供应商与认证体系 将深入模型供应商体系——如何配置 API Key、如何选择最优模型组合、如何设置 fallback 链路。