Chapter 4 · Interactive Mode: Editor / Commands / Keybindings
Chapter goals: Familiarize yourself with the TUI界面分区 and editor capabilities; master常用 slash commands and keybindings; learn to "queue interrupt" the model while it works via the message queue; and complete terminal compatibility配置.
4.1 TUI Layout Overview
The interactive mode界面自上而下分四个区域:
┌─────────────────────────────────────────────┐
│ Startup header Keybinding hints / loaded AGENTS.md │
│ /templates/skills/extensions清单 │
├─────────────────────────────────────────────┤
│ Messages User messages / replies / tool calls and results │
├─────────────────────────────────────────────┤
│ Editor Input area (border color indicates thinking level) │
├─────────────────────────────────────────────┤
│ Footer Dir / session name / tokens & cost / current model │
└─────────────────────────────────────────────┘The Footer stats值得专门认识: ↑ input tokens, ↓ output tokens, R cache read, W cache write, CH recent cache hit rate — this is the第一仪表盘 for cost control. The editor may临时 be replaced (e.g.内置 /settings panel, or an extension-provided structured Q&A UI).
4.2 Six Core Editor Capabilities
| Function | Action |
|---|---|
| File reference | Type @ to fuzzy-search project files |
| Path completion | Tab |
| Multi-line input | Shift+Enter (Windows Terminal uses Ctrl+Enter) |
| External editor | Ctrl+G opens $VISUAL/$EDITOR (Windows defaults to Notepad, fallback nano) |
| Paste images/text | Ctrl+V (Windows uses Alt+V); or直接拖图进终端 |
| Execute shell commands | !command sends output to the model; !!command does not |
# Typical flow: external editor writes a long prompt → reference files → submit
# Ctrl+G opens vim to写 a complex refactor request; auto-return to the editor after saving/closingHand long prompts to a comfortable editor
For需求 descriptions超过三四行,建议 Ctrl+G into an external editor: has syntax highlighting,可反复修改; far more efficient than cramming into a small editor框.
4.3 Common Slash Commands Checklist
Type / totrigger command completion (extensions可注册新 commands; skills appear as /skill:name; templates expand as /templateName). Most常用 daily:
/model switch model /resume select a historical session
/new new session /name <name> name the session
/session view current session info /tree session tree navigation
/fork fork from a historical message /clone clone当前分支 into a新 session
/compact [instructions] manually compress context /copy copy the last reply
/export [file] export HTML/JSONL /share upload as a private GitHub gist
/hotkeys show all keybindings /quit exit管理类还有 /login, /logout (credentials), /settings (thinking level/theme/message delivery/transport), /trust (save project trust), /reload (reload keybindings/extensions/skills/templates/themes/context files).
💡 Thinking Level Picker (0.84.3+): type
/thinkingto open a searchable thinking level picker (off/minimal/low/medium/high/xhigh/max); Enter applies仅会话内生效;Ctrl+Ssaves as全局默认;快捷键shift+tab直接循环切换 thinking level;ctrl+t折叠/展开 thinking blocks.
4.4 High-Frequency Keybindings
| Key | Action |
|---|---|
| Ctrl+C | Clear the editor; double-tap to exit |
| Escape | Cancel/abort current generation |
| Escape×2 | Open /tree session tree |
| Ctrl+L | Model picker |
| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
| Shift+Tab | Cycle thinking levels |
| Ctrl+O | Fold/expand tool output |
| Ctrl+T | Fold/expand thinking blocks |
| Ctrl+X | Copy the last assistant message |
All keybindings可重映射 via ~/.pi/agent/keybindings.json; format is modifier+key (e.g. ctrl+shift+x); the authoritative清单 is /hotkeys:
{
"tui.editor.historyPrevious": "ctrl+p",
"tui.input.submit": "enter"
}Note the official提醒: after binding tui.editor.historyPrevious to ctrl+p, Ctrl+P will no longer用于 model cycling in that editor context.
4.5 The Message Queue: How to Interrupt While the Model Works
You can still提交 messages while the model is executing; two排队 semantics:
- Enter = steering message: delivered immediately after the当前轮 tool calls结束; suitable for中途纠偏;
- Alt+Enter = follow-up message: delivered only after the agent fully stops; suitable for追加下一步任务;
- Escape aborts and退回 the queued messages to the editor; Alt+Up取回排队消息.
Delivery节奏可在 /settings or settings.json配置: steeringMode and followUpMode default to "one-at-a-time" (wait响应 per条); change to "all" to deliver一次性全部送达. transport可指定 a provider supporting多传输方式 to use "sse" / "websocket" / "auto".
4.6 Terminal Compatibility Configuration
pi relies on the Kitty keyboard protocol for reliable modifier key识别:
- Kitty / iTerm2 regular mode: works out of the box;
- iTerm2 fullscreen mode trackpad scroll too slow: Settings → Advanced → search "Trackpad scrolls fast?" set to No;
- Apple Terminal: local fallback机制可把普通 Return当 Shift+Enter处理;无效 in SSH remote场景;
- Windows Terminal Alt+Enter defaults to fullscreen; need to重映射 per the terminal-setup doc before it can serve as the follow-up快捷键.
Chapter Summary
- TUI四分区: header/messages/editor/footer; footer is the cost仪表盘;
- Six editor capabilities: @ refs, Tab completion, Shift+Enter multi-line, Ctrl+G external editor, Ctrl+V paste images, ! execute commands;
- The message queue distinguishes steering (Enter,即时纠偏) and follow-up (Alt+Enter,完工后执行);
- All keybindings可重映射 in keybindings.json;
/hotkeysis the authoritative清单; - The terminal needs to支持 the Kitty keyboard protocol; Windows Terminal要手动处理 the Alt+Enter冲突.
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. Pressing Enter to提交 a message while the model is executing results in?
2. To paste a screenshot for the model to analyze a UI, the correct操作 is?
3. Regarding the difference between !!command and !command, which is correct?
4. What does double-tap Escape trigger?
🛠️ Hands-on Practice
- Use Ctrl+G to write a重构 request不少于 10 lines in an external editor and submit to pi;对比 the体验 difference with the small editor框.
- Have pi执行 a long task;分别用 Enter and Alt+Enter queue一条 message each; observe the delivery timing difference.
- Remap
/treeto your preferred key combo; verify生效 with/hotkeys.
Proceed to Chapter 5: Session Management to make every work session追溯able and rollbackable.