Phase 11: Telescope 风格命令面板

[pionxe]

Phase 11: Telescope 风格命令面板

• Phase: 11
• 优先级: P1
• 依赖: Phase 10（键位系统可用）、Phase 6（主题可用）

---

What — 要做什么

实现 Telescope 风格的命令面板 — 浮动搜索 + 命令列表弹窗，通过确定性子串搜索快速定位和执行命令。

触发方式

• Normal Mode 下 Space p（Leader Key）

面板外观

┌─ ⚡ Commands ───────────────────────────────────────────────┐
│ › ses                                                        │
│─────────────────────────────────────────────────────────────│
│  ▎ /new     新建会话                              Space n  │
│    /session 切换会话                              Space s  │
│    /delete  删除当前会话                                    │
│    /model   切换模型                               Space m  │
│    /retry   重试上次运行                           Space r  │
│─────────────────────────────────────────────────────────────│
│  5 项匹配 · ↑↓ 选择 · Enter 执行 · Esc 关闭                 │
└─────────────────────────────────────────────────────────────┘

渲染说明：铺平展示（无 Session:/Model: 分组 header），选中项用 ▎ 前缀 + 高亮；快捷键列右侧右对齐。› 为搜索输入提示。

功能特性

• 确定性匹配：输入子串匹配命令名或描述，按优先级分桶排序（精确匹配 > 前缀匹配 > 子串匹配 > 描述子串匹配）。不引入模糊子序列匹配（fuzzy subsequence）——在 10-20 个命令的小集合上 fuzzy 边际收益为零，且会重新引入 mode 误命中 model 的问题；同桶内保持定义顺序，不引入评分函数。
• 实时过滤：每输入一个字符即时更新匹配列表
• 快捷键预览：右侧右对齐显示已有快捷键绑定的命令（如 Space n）
• 铺平展示：命令列表铺平展示（不做 Category 分组 header），靠快捷键列提供视觉结构；Category 字段保留仅用于空查询时排序（Session 类优先于 System 类）
• 键盘导航：↑↓ 选择、Enter 执行、Esc 关闭、Ctrl+J/K 同 ↑↓

设计决策（经 3 轮审查争辩裁定）：不引入 fuzzy/评分是刻意设计——现有 matchedItems() 已用确定性分桶并注释说明"不使用模糊匹配，避免 mode 评分排序命中 /model"。铺平优于分组是因为 10 条命令不值得分组渲染带来的 Selected→item 映射复杂度与鼠标偏移问题。

命令列表

初始命令注册表（后续 Phase 扩展）。/checkpoint、/skills 暂未实现，保留在列表中并在 Description 标注 [未实现]，选中后走默认提示分支。

命令(Name)	Action(常量)	快捷键	描述
/new	new_session	Space n	新建会话
/session	switch_session	Space s	打开会话选择器
/delete	delete_session	—	删除当前会话
/model	model	Space m	打开模型选择器
/retry	retry	Space r	重试上次运行
/cancel	cancel	Space c	取消当前运行
/help	help	Space h	打开帮助面板
/clear	clear	—	清空当前会话消息
/debug	debug	:debug	切换调试模式
/info	session_info	—	查看会话信息（token 等）
/compact	compact	—	手动 compact
/mode	mode	—	切换 Agent 模式
/exit	exit	—	退出
/checkpoint	checkpoint	—	管理检查点 [未实现]
/skills	skills	—	管理会话技能 [未实现]

命令 Name 保留 / 前缀作为用户可见标识，Action 用具名常量（PaletteAction）做内部路由，消除硬编码业务字符串（AGENTS.md 第 7 节）。快捷键 Shortcut 直接在注册表中硬编码并标注 // keep in sync with keymap，不强行从 keymap 反推（开销不值得）。

弹窗规则

命令面板是弹窗（有 ┌─┐│└┘ 边框），显示在终端中央，覆盖在 Agent Stream 之上。这是少数允许使用边框的场景之一：

• 命令面板（搜索 + 命令列表）
• 帮助面板（分组信息多）
• 会话选择器（列表搜索）
• 危险操作确认（防误操作）

---

Why — 为什么不复用 v1 的命令方式

1. v1 命令靠记忆：v1 没有命令面板，用户需要记住快捷键组合。v2 的命令面板支持搜索定位，降低记忆负担
2. Telescope 模式验证成熟：Neovim 生态中 Telescope/fzf 的"搜索 + 选择"交互模式已被广泛验证，终端用户熟悉
3. 可扩展：后续新增命令只需注册到命令列表，自动出现在面板中，无需修改 UI 代码
4. 发现性：新用户通过 Space p 可以浏览所有可用命令，降低上手成本

---

How — 怎么做

1. 改造 internal/tuiv2/components/palette.go 现有 Palette 组件（Phase 10 已有基础）
2. 新建 internal/tuiv2/components/commands.go：定义 PaletteAction 常量、Category（带 iota 优先级）、CommandDef{Name,Description,Category,Shortcut,Action}、PaletteCommands()（返回铺平命令列表，按 Category 优先级 sort.SliceStable）
3. 匹配算法保持确定性分桶（精确名 > 前缀 > 子串 > 描述子串），不引入 fuzzy、不引入评分；空查询返回全部按 Category 优先级排序
4. PaletteCommandMsg 增 Action PaletteAction 字段；选中时 emit {Name, Action}
5. 实时过滤：Overlay.Query 变化 → 重新计算匹配列表（Selected 重置为 0）
6. 弹窗尺寸：宽度 = min(终端宽度 - 4, 60)；高度 = min(匹配数 + 4, 20)；铺平渲染，快捷键列右对齐
7. 在 App.Update() 中：收到 Space p → openOverlay(state.OverlayPalette)（沿用 Phase 10 Overlay 机制，不用 ShowPalette）
8. app.handlePaletteCommand 改为 switch msg.Action 常量分发，复用现有 handler（openOverlay/handleSessionDelete/toggleAgentMode/triggerCompact 等）
9. Ex 命令（:mode/:compact/:debug）与 Palette 两份独立列表，共享 handler 函数，不强行统一为单注册表

---

验收标准

• Space p 打开命令面板，Esc 关闭
• 输入文字实时过滤命令列表（确定性分桶：精确>前缀>子串>描述子串）
• 不引入 fuzzy/评分（mode 不会误命中 model）
• ↑↓/Ctrl+J/K 选择、Enter 执行
• 有快捷键的命令在右侧右对齐显示快捷键
• 命令铺平展示（无分组 header），空查询按 Category 优先级排序
• PaletteCommandMsg 携带 Action 常量，handlePaletteCommand switch Action
• 未实现命令（/checkpoint /skills）标注 [未实现]，选中走默认提示
• 弹窗边框使用主题 Border 色
• 面板关闭后焦点回到原区域（Overlay 关闭）
• 命令注册表在 commands.go，palette.go 保持 < 400 行
• go test ./internal/tuiv2/components/ 覆盖匹配/排序/选中/快捷键列，增量覆盖率 ≥80%