# 第 1 章：交互模式——终端里的驾驶舱
> 好工具如自来水：拧开即来，关上即停。
## 设计思想
交互模式（TUI）是 Pi 的默认形态：不追求花哨的图形界面，而是把终端文本界面做到信息密度与操作效率的极致。所有日常操作——输入、纠偏、切模型、看消耗——都能在键盘上完成，让手不离开主键区。
## 原理
### 界面四块布局（自上而下）
| 区域 | 内容 |
|------|------|
| **Startup header** | 快捷键提示（`/hotkeys` 看全部）、已加载的 AGENTS.md、prompt 模板、skills、extensions |
| **Messages** | 用户消息、助手回复、工具调用与结果、通知、错误、扩展 UI |
| **Editor** | 输入区；**边框颜色指示当前思考级别**；可被 `/settings` 或扩展 UI 临时替换 |
| **Footer** | 工作目录、会话名、token/缓存用量（`↑` 输入 `↓` 输出 `R` 缓存读 `W` 缓存写 `CH` 缓存命中率）、成本、上下文占用、当前模型 |
### 编辑器技巧
| 操作 | 用法 |
|------|------|
| 引用文件 | `@` 触发项目文件模糊搜索 |
| 路径补全 | Tab |
| 多行输入 | Shift+Enter（Windows Terminal 用 Ctrl+Enter） |
| 外部编辑器 | Ctrl+G（按 `externalEditor` → `$VISUAL` → `$EDITOR` → nano/Notepad 顺序回退） |
| 剪贴板贴图 | Ctrl+V（Windows 用 Alt+V），或直接把图片拖进终端 |
| Shell 命令 | `!command` 执行并把输出喂给模型；`!!command` 执行但不喂 |
### 斜杠命令
输入 `/` 触发。常用分组：
| 分组 | 命令 |
|------|------|
| 凭据/模型 | `/login` `/logout` `/model` `/thinking` `/scoped-models` `/llama` |
| 会话 | `/new` `/resume` `/name` `/session` `/tree` `/fork` `/clone` |
| 上下文 | `/compact [prompt]`（手动压缩） |
| 导出分享 | `/copy` `/export` `/import` `/share` |
| 配置 | `/settings` `/trust` `/reload` |
| 信息 | `/hotkeys` `/changelog` `/quit` |
扩展可注册自定义命令，skills 以 `/skill:name` 出现，提示模板以 `/模板名` 展开。
### 快捷键
| 键 | 作用 |
|----|------|
| Ctrl+C | 清空编辑器；**连按两次退出 pi** |
| Escape | 取消/中止当前操作 |
| Escape ×2 | 打开 `/tree` |
| Ctrl+L | 模型选择器 |
| Ctrl+P / Shift+Ctrl+P | 在 scoped 模型列表中前进/后退循环 |
| Shift+Tab | 循环思考级别 |
| Ctrl+O | 折叠/展开工具输出 |
| Ctrl+T | 折叠/展开思考块 |
| Ctrl+X | 复制最近一条助手消息 |
完整列表 `/hotkeys`；可用 `~/.pi/agent/keybindings.json` 自定义（见 `docs/keybindings.md`）。
### 消息队列（agent 工作时继续输入）
| 键 | 语义 |
|----|------|
| **Enter** | 排入 **steering** 消息：当前助手 turn 的工具调用执行完就送达 |
| **Alt+Enter** | 排入 **follow-up** 消息：所有工作全部结束后才送达 |
| **Escape** | 中止运行，队列消息撤回编辑器 |
| **Alt+Up** | 把队列中的消息取回编辑器修改 |
投递模式可在 settings 配置：`steeringMode` / `followUpMode` = `"one-at-a-time"`（默认，逐条等回复）或 `"all"`（一次性全部送达）。Windows Terminal 的 Alt+Enter 默认被全屏占用，需按 `docs/terminal-setup.md` 重映射。
## 用法
- **日常节奏**：正常对话 → 发现方向跑偏时按 Enter 排一条 steering 纠偏（不用等它停下来）→ 需要追加独立任务时 Alt+Enter 排 follow-up。
- **观察消耗**：瞟一眼 Footer 的 token/缓存/成本/上下文占用，判断何时该 `/compact`。
- **长输出管理**：工具输出太长用 Ctrl+O 折叠，思考块用 Ctrl+T 折叠。
- **快速换模型**：Ctrl+L 选择（Ctrl+S 存为默认），或 Ctrl+P 在常用模型间轮换。
- **配置速调**：`/settings` 里改主题、消息投递、传输方式（`transport`: `sse` / `websocket` / `auto`）等偏好。