Pi Agent 第一次对话
完成了安装和认证配置后，本章带你进行第一次完整的对话体验，熟悉界面和基本操作。
启动 Pi Agent
进入你的项目目录，启动 Pi Agent：
$ cd /path/to/my-project $ pi
你会看到终端中出现 Pi Agent 的交互界面。
界面分为四个主要区域：
| 区域 | 位置 | 显示内容 |
|---|---|---|
| 启动头部 | 顶部 | 快捷键提示、已加载的上下文文件、提示词模板、Skills、扩展 |
| 消息区域 | 中部 | 用户消息、AI 回复、工具调用详情、通知和错误 |
| 编辑区 | 底部输入行 | 你的输入位置，边框颜色表示当前推理等级 |
| 底部状态栏 | 最下方 | 工作目录、会话名、token/缓存用量、上下文用量、费用、当前模型名（总额包含 AI 回复、工具上报用量和摘要生成消耗） |
如果你觉得启动时显示的头部信息太多，可以在设置中启用 quietStartup 选项来隐藏它。
第一个任务
进入界面后，输入你的第一个需求并回车：
帮我总结一下这个项目的结构和主要功能
Pi Agent 会使用内置工具读取你的项目文件，分析代码结构，然后返回总结。
你可以在消息区域看到 AI 正在执行的操作——包括它调用了哪些工具、读取了哪些文件。
以下是 Pi Agent 在对话中默认可用的工具：
| 工具 | 说明 | 典型用法 |
|---|---|---|
| read | 读取文件内容 | 读取 README.md 了解项目说明 |
| write | 创建或覆盖文件 | 创建新的源代码文件 |
| edit | 精确替换文件内容 | 修改函数中的某几行 |
| bash | 执行 shell 命令 | 运行 ls 查看目录结构 |
引用文件
你可以在对话中引用特定文件，有两种方式：
方式一：@ 语法（编辑器内搜索）
在编辑区输入 @，会自动弹出项目文件的模糊搜索：
@src/app.ts 解释这个文件的功能
方式二：命令行参数
启动时直接传入文件引用：
$ pi @README.md "总结一下这个文档" $ pi @src/app.ts @src/app.test.ts "对比这两个文件"
也可以引用图片文件：
$ pi -p @screenshot.png "这张截图里显示了什么"
粘贴图片
Pi Agent 支持在对话中发送图片：
- macOS/Linux：按 Ctrl+V 粘贴剪贴板中的图片
- Windows：按 Alt+V 粘贴
- 支持的终端还可以直接拖拽图片到终端窗口
在对话中执行命令
你可以直接从编辑区执行 shell 命令，无需退出 Pi Agent：
!npm run lint !git diff
以 ! 开头的命令会被执行，且输出结果会自动发送给 AI 查看。
以 !! 开头的命令也会执行，但 不会 将输出发送给 AI：
!!echo "这只在本地显示"
使用 !! 前缀执行不需要 AI 查看的命令（如打开文件、查看环境变量），可以避免浪费上下文窗口。
多行输入与外部编辑器
| 操作 | 快捷键 |
|---|---|
| 插入换行 | Shift+Enter（Windows Terminal 用 Ctrl+Enter） |
| 打开外部编辑器 | Ctrl+G |
| 复制 AI 最后一条回复 | Ctrl+X |
| 路径自动补全 | Tab |
当你需要输入大段文本时，按 Ctrl+G 会打开系统默认编辑器（如 nano、vim 或 VS Code），编辑完成保存后内容会自动填入 Pi Agent 的编辑区。
消息队列
Pi Agent 允许在 AI 正在工作时发送消息，而不需要等待它完成：
| 快捷键 | 行为 | 说明 |
|---|---|---|
| Enter | 发送 steering 消息 | 在当前工具执行完毕后立即发送给 AI |
| Alt+Enter | 发送 follow-up 消息 | 等 AI 完成所有工作后再发送 |
| Escape | 取消已排队消息 | 将排队中的消息恢复到编辑区 |
| Alt+Up | 取回排队消息 | 将已排队的消息取回编辑区修改 |
在 Windows Terminal 中，Alt+Enter 默认是全屏快捷键。如果想让 Pi Agent 接收这个快捷键，需要参考终端设置中的说明进行重映射。
非交互模式
除了交互对话，你也可以用以下方式快速使用 Pi Agent：
实例
pi -p "总结一下这个代码库"
# 管道输入：将文件内容传给 AI
cat README.md | pi -p "总结这段文字"
# 带图片的一次性问答
pi -p @screenshot.png "这张图里有什么"
# 命名会话（方便之后继续）
pi --name "代码审查" -p "审查 src/ 目录下的代码"
# 只读模式（不允许修改文件）
pi --tools read,grep,find,ls -p "审查代码不修改"
Print 模式（-p）非常适合集成到脚本和 CI 流程中。
创建项目指令文件
为了让 AI 更好地理解你的项目，建议创建 AGENTS.md 文件：
实例
- 代码修改后运行 `npm run check`
- 不要直接在本地执行生产环境迁移
- 回复保持简洁，不要过多解释
- 使用 TypeScript 严格模式编写代码
- 遵循项目现有的代码风格
Pi Agent 会在启动时自动加载这个文件。
同时也会加载来自 ~/.pi/agent/AGENTS.md 的全局指令和父目录中的指令文件。
更新 AGENTS.md 后，使用 /reload 命令即可热重载，无需重启。
如果你之前使用 Claude Code，已有的 CLAUDE.md 文件可以直接被 Pi Agent 识别使用，无需重命名。
界面一览
以下是 Pi Agent 交互模式的主要快捷键速查：
| 操作 | 快捷键 | 说明 |
|---|---|---|
| 提交输入 | Enter | 发送当前编辑区内容 |
| 模型选择 | Ctrl+L | 打开模型选择器 |
| 切换模型 | Ctrl+P / Shift+Ctrl+P | 向前/向后循环切换模型 |
| 推理等级 | Shift+Tab | 循环切换推理等级 |
| 展开/折叠工具输出 | Ctrl+O | 切换工具调用结果的显示 |
| 展开/折叠推理过程 | Ctrl+T | 切换 AI 推理过程的显示 |
| 中断操作 | Escape | 取消当前 AI 操作 |
| 清空编辑区 | Ctrl+C | 清空当前编辑区内容 |
| 退出程序 | Ctrl+D | 编辑区为空时退出程序 |
| 退出程序（直接） | /quit | 立即退出 |