好工具如自来水：拧开即来，关上即停。
设计思想
交互模式（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）等偏好。