dsh-neotui 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.3.0 — 2026-08-17
+
+### Added
+
+- tmux 风格 pane 焦点：`Ctrl+←/→` 在工作区栏、对话和轨迹间循环。
+- 正文块 `=>` 游标、只读 NORMAL / VISUAL 导航、原子代码块与 `y` / `Ctrl+Shift+C` 复制。
+- 全屏跨会话全文搜索：工作区→会话→匹配块树、附近内容预览和按 seq 精确跳转；Host 索引不可用时降级为有界本地扫描。
+- Host 供应商目录选项预览，模型选择器默认定位当前会话模型。
+- 可编辑快捷键改为真正的动态 dispatch：定义独立于 `src/keybindings.js`，每个功能主/备两个槽位，修改后立即生效。
+- `Ctrl+K` 用默认编辑器打开 `tui-config.json`，关闭编辑器后快捷键自动重载；Skills 移至 `Ctrl+H`。
+- 控制面板快捷键页升级为 `MODE / KEY1 / KEY2 / FUNCTION` 四列，JSON 编辑同时校验两个槽位。
+- 模型选择器改为供应商文件夹 → 具体模型的层级结构：`Space` 展开/折叠、`Enter` 确认、当前模型默认展开并选中；`/` 进入筛选、`Ctrl+/` 退出筛选，与其它 buffer 一致。
+- 代码块标题行重排：语言标签移入框内、按钮字段按固定宽度预留，`[按y复制]` 切换不再推动右边框；整框每行严格等宽。
+- 旧版单槽位快捷键配置自动迁移（`sessionFilter "/"`、`homeSwitch "Ctrl+Left/Right"`、`skills "Ctrl+K"`），避免旧配置让 `Ctrl+F`、`Ctrl+←/→`、`Ctrl+H` 失效。
+
+### Changed
+
+- 所有有限选项列表统一首尾循环；文本光标和纯滚动位置保持有界。
+- 侧栏、轨迹和欢迎页改为 keyboard-first 导航；全局 Tab/Shift+Tab 切换由 `Ctrl+←/→` / F8 取代。
+- 轨迹展开直接呈现全部事件，移除重复且未实现完整的“查看详情”入口。
+- 鼠标正文拖选固定为自由字符选择，不再由 `v` 切换整行模式。
+- 工作区、设置、模型供应商、子代理和技能从“标签页模式”改为全屏模态 Buffer（`Esc` 关闭），与 `Ctrl+←/→` pane 聚焦不再冲突；轨迹仍是 pane 序列成员。
+- 正文块游标改为两端停留（`j`/`k`、`↑`/`↓` 不环绕）；`Shift+G` 选中最新块并让块头落在视口底部。
+- 清除未使用的 `List` 导入与死字段 `expandedTools`。
+
 ## 0.2.2 — 2026-08-16
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # dsh-neotui
 
-`dsh-neotui` 是 DeepSeek Harness 的终端客户端：以 Vim/Nvim 风格的 NORMAL / INSERT 模式、Yazi 风格文件选择器和鼠标交互，访问与 WebUI 相同的 Host 会话、工具、审批、任务和设置能力。
+`dsh-neotui` 是 DeepSeek Harness 的 keyboard-first 终端客户端：以 Vim/Nvim 风格的 NORMAL / INSERT / VISUAL 只读导航、tmux 风格 pane 焦点和 Yazi 风格文件选择器为主，鼠标作为辅助，访问与 WebUI 相同的 Host 会话、工具、审批、任务和设置能力。
 
 本仓库发布两个 npm 包：
 
@@ -13,8 +13,8 @@
 
 - 三栏 Yazi 风格文件与工作区选择器：路径编辑、模糊筛选、隐藏项、Nerd Font 图标和 Kitty 图片预览；
 - 图片附件栏、附件管理器、`dd` 删除和等比例 Kitty 预览；
-- 会话树筛选、跨会话模糊定位和稳定的历史分页；
-- NORMAL / INSERT 模式与可编辑的快捷键目录；
+- 全屏跨会话全文搜索：工作区→会话→匹配块树、附近内容预览和精确跳转；
+- NORMAL / INSERT / VISUAL 只读模式、正文块选择与可编辑的快捷键目录；
 - 独立的命令、设置和插件目录，插件支持即时筛选；
 - Queue / Steering、Goal、TODO、Plan Review、后台任务和 Subagent 状态；
 - grapheme-aware framebuffer、CJK/组合字符、Kitty keyboard、SGR mouse、OSC 8/52。
@@ -23,6 +23,8 @@
 
 ## 安装与启动
 
+需要 **Node.js 22 或更高版本**（客户端使用 Node 内置 `fetch`、`WebSocket`、`crypto.randomUUID` 和 `Intl.Segmenter`）。
+
 ### 独立 DSH profile
 
 ```bash
@@ -131,39 +133,49 @@ Kitty graphics 可用时，图片在文件选择器和附件预览中等比例
 - `queue`：加入下一回合队列；
 - `steer`：追加到当前回合。
 
-`Ctrl+Y` 切换策略，`Ctrl+N` 打开排队命令详情。队列面板每条命令一行，使用 `↑/↓` 选择、`dd` 删除、`Esc` 关闭。
+`Ctrl+Y` 切换策略，`Ctrl+N` 打开排队命令详情。队列面板每条命令一行，使用 `↑/↓` 循环选择、`Enter` 展开详情、`Ctrl+↑/↓` 独立滚动详情、`dd` 删除、`Esc` 关闭。
 
 ## 快捷键
 
-以下是默认绑定。控制面板中的快捷键页以 `MODE / KEY / FUNCTION` 三列显示，并允许编辑用户覆盖；配置写入 `$DSH_HOME/tui-config.json`。
+以下是默认绑定。控制面板中的快捷键页以 `MODE / KEY1 / KEY2 / FUNCTION` 四列显示，每个功能拥有主/备两个槽位，并允许编辑用户覆盖；配置写入 `$DSH_HOME/tui-config.json`。这些绑定是运行时的唯一来源：修改后立即生效（无需重启），全部定义集中在 `src/keybindings.js`。
 
 | 模式 | 按键 | 功能 |
 |---|---|---|
 | ALL | `Ctrl+Space` / `F7` | 控制面板 |
-| NORMAL | `/` | 筛选会话树；`Ctrl+/` 退出 |
-| NORMAL | `Ctrl+F` | 跨会话模糊定位 |
+| NORMAL | `Ctrl+F` / `/` | 打开全屏跨会话全文搜索；Enter 执行，`/` 重新编辑 |
 | NORMAL | `Ctrl+B` | 显示/隐藏侧栏 |
 | NORMAL | `Ctrl+M` | 模型与思考强度 |
-| NORMAL | `Shift+Tab` / `F8` | 权限模式轮换 |
+| NORMAL | `F8` | 权限模式轮换 |
 | NORMAL | `F9` | Agent 模式 |
 | NORMAL | `Ctrl+W` | 工作区 |
 | NORMAL | `Ctrl+Shift+W` | 添加工作区 |
 | NORMAL | `Ctrl+T` | 轨迹视图 |
-| NORMAL | `Tab` | 对话/轨迹切换 |
+| NORMAL | `Ctrl+←` / `Ctrl+→` | 工作区栏 / 对话 / 轨迹 pane 循环聚焦 |
 | NORMAL | `Ctrl+E` | 按 step 快速跳转 |
 | NORMAL | `Ctrl+J` | 后台任务与 Subagent |
 | NORMAL | `Ctrl+N` | 排队命令详情 |
+| NORMAL | `Ctrl+Y` | 运行中 Enter 策略（追加 / 排队） |
+| NORMAL | `Ctrl+O` | 附件管理 |
 | NORMAL | `Ctrl+G` | Goal / TODO |
 | NORMAL | `Ctrl+S` | Settings |
 | NORMAL | `Ctrl+A` | Subagent |
-| NORMAL | `Ctrl+K` | Skills |
+| NORMAL | `Ctrl+H` | Skills |
+| NORMAL | `Ctrl+K` | 用默认编辑器（`$EDITOR` / `$VISUAL` / `vi`）打开 `tui-config.json`；编辑完成后快捷键立即重载 |
 | ALL | `Ctrl+Q` | 退出 |
-| NORMAL | `t` / `b` | 展开/折叠思考块 / 工具块 |
-| NORMAL | `g g` / `G` | 对话顶部 / 底部 |
+| 正文块 | `↑` / `↓`、`j` / `k` | 上下选择正文块，两端停留不环绕；`Ctrl+↑/↓` 只滚动视口 |
+| 正文块 | `Space` / `Enter` / `Ctrl+R` | 折叠块 / 进入只读光标 / 打开上下文菜单 |
+| NORMAL 光标 | `h l w b e 0 $`、`v` / `V` | Vim 式只读移动与字符/整行 VISUAL（无 `x` / `d`） |
+| NORMAL / VISUAL | `y` / `Ctrl+Shift+C` | 复制当前代码块/正文块或选区 |
+| 正文块 | `t` / `b` | 全局展开/折叠思考块 / 工具块 |
+| 正文块 | `g g` / `G` | 首个 / 最新正文块；`G` 选中最新块并让块头落在视口底部 |
 | NORMAL | `[` / `]` | 上一个 / 下一个提问终点 |
 | NORMAL | `PgUp` / `PgDn` | 翻页；到顶时加载更早历史 |
 
-快捷键目录中：`Enter` 编辑当前 JSON 配置项，`Shift+Tab` 在 NORMAL / INSERT / ALL 间轮换，`Alt+Enter` 恢复默认。保存前会校验 JSON、模式和按键字段；错误文本会保留以便继续修改。
+侧栏聚焦后，`↑/↓` 循环选择工作区或会话，`Space` 展开/折叠工作区，`Enter` 打开会话且保持侧栏焦点，`n` 新建会话，`i` 进入输入，`Ctrl+R` 打开当前项菜单。轨迹聚焦后，`↑/↓` 循环选择 step，`Space` 展开完整事件，`Enter` 跳回对话，`Ctrl+R` 打开 step 菜单。
+
+搜索 buffer 中，Enter 执行查询或跳转结果，`/` 返回查询编辑，`Space` 折叠工作区/会话，`t` / `b` 折叠思考/工具匹配，`Ctrl+↑/↓` 独立滚动右侧预览。若 Host 未挂载搜索索引（`session.search` 不可用），会自动降级为对最近 20 个会话近期历史的有界本地扫描，并在 buffer 顶部提示。
+
+快捷键目录中：`Enter` 编辑当前 JSON 配置项（`{"mode":"normal|insert|all","key":"…","key2":"…"}`，`key2` 可为空），`Shift+Tab` 在 NORMAL / INSERT / ALL 间轮换，`Alt+Enter` 恢复默认。保存前会校验 JSON、模式和两个按键槽位；错误文本会保留以便继续修改。两按组合键（如 `g g`）以空格分隔书写。
 
 ## Slash 命令
 
@@ -192,6 +204,10 @@ TUI 支持：
 - 独立插件清单及 `/` 筛选；
 - dark、light、gruvbox 主题。
 
+工作区（`Ctrl+W`）、设置（`Ctrl+S`）、模型供应商（模型选择器里的 `⚙ 管理供应商…`）、子代理（`Ctrl+A`）和技能（`Ctrl+H`）都是**全屏模态 Buffer**：打开后覆盖整个界面，`Esc` 逐级返回并最终关闭。它们不再占用“标签页模式”，因此关闭后 `Ctrl+←/→` 的 pane 聚焦立即恢复，两者互不冲突。轨迹仍是 pane 序列的一部分，由 `Ctrl+T` 或 `Ctrl+←/→` 进入。
+
+模型选择器（`Ctrl+M` / `/model`）是供应商文件夹 → 具体模型的层级结构：`Space` 展开/折叠文件夹，`↑/↓` 移动，`Enter` 确认具体模型（带思考强度时再选一档），当前模型以 `●` 标记并默认展开、默认选中。筛选与其他 buffer 一致：`/` 进入筛选、`Ctrl+/` 退出筛选，普通字符在浏览模式下不会误触发筛选。
+
 所有 Buffer 都是模态的：点击外部只会吞掉事件，不会关闭 Buffer。退出必须使用界面明确提示的按键或操作。
 
 ## 鼠标与终端能力
@@ -255,6 +271,7 @@ src/term.js         raw mode、鼠标、paste、Kitty keyboard
 src/screen.js       cell framebuffer 与 ANSI diff
 src/text.js         grapheme、显示宽度和截断
 src/md.js           Markdown、代码块和 OSC 8
+src/keybindings.js  可编辑快捷键注册表（每个功能主/备两个槽位）
 src/widgets.js      Input、Popup、ScrollView、Menu、StatusBar
 src/views.js        App、ChatView、会话树和主路由
 src/panels.js       Workspace、Trajectory、Queue、Jobs、Settings

package/bin/dsh-tui.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// dsh-tui — mouse-driven terminal client for DeepSeek Harness.
+// dsh-tui — keyboard-first terminal client for DeepSeek Harness.
 // Usage:
 //   dsh-tui                        interactive mode (needs a real terminal)
 //   dsh-tui --base http://host:port

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "dsh-neotui",
-  "version": "0.2.3",
-  "description": "Neo-TUI: mouse-driven terminal UI client for DeepSeek Harness (B-tier per dsh-tui-design.md)",
+  "version": "0.3.0",
+  "description": "Keyboard-first Vim/tmux-style terminal client for DeepSeek Harness",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "bin": {
     "dsh-neotui": "bin/dsh-tui.js"
   },

package/src/config.js

@@ -3,6 +3,9 @@
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { userInfo } from "node:os";
+import { DEFAULT_KEYBINDINGS, normalizeKeyBinding, validateKeySpec } from "./keybindings.js";
+
+export { DEFAULT_KEYBINDINGS };
 
 export function tuiConfigFile() {
   const base = process.env.DSH_HOME ?? (process.env.XDG_CONFIG_HOME ?? join(process.env.HOME ?? ".", ".config"));
@@ -69,21 +72,52 @@ export function busyEnter() {
   return loadTuiConfig().busyEnter === "steer" ? "steer" : "queue";
 }
 
-export const DEFAULT_KEYBINDINGS = {
-  think: { mode: "normal", key: "t" }, tools: { mode: "normal", key: "b" }, insert: { mode: "normal", key: "i" },
-  leaveInsert: { mode: "insert", key: "Esc" }, sessionFilter: { mode: "normal", key: "/" }, newSession: { mode: "normal", key: "n" },
-  top: { mode: "normal", key: "g g" }, bottom: { mode: "normal", key: "G" }, prevQuestion: { mode: "normal", key: "[" }, nextQuestion: { mode: "normal", key: "]" },
-  expandInput: { mode: "insert", key: "Ctrl+L" }, copyInput: { mode: "insert", key: "Ctrl+Shift+C" }, panel: { mode: "all", key: "Ctrl+Space" },
-  model: { mode: "normal", key: "Ctrl+M" }, trajectory: { mode: "normal", key: "Ctrl+T" }, homeSwitch: { mode: "normal", key: "Tab" },
-  permissionRotate: { mode: "normal", key: "Shift+Tab" },
-  workspace: { mode: "normal", key: "Ctrl+W" }, settings: { mode: "normal", key: "Ctrl+S" }, subagent: { mode: "normal", key: "Ctrl+A" },
-  skills: { mode: "normal", key: "Ctrl+K" }, goal: { mode: "normal", key: "Ctrl+G" }, jobs: { mode: "normal", key: "Ctrl+J" },
-  stepJump: { mode: "normal", key: "Ctrl+E" }, sidebar: { mode: "normal", key: "Ctrl+B" }, quit: { mode: "all", key: "Ctrl+Q" },
+/** Pre-registry one-slot defaults that would silently kill the new two-slot
+ *  bindings (e.g. an old sessionFilter "/" override removes Ctrl+F). */
+const LEGACY_KEY_VALUES = {
+  sessionFilter: { mode: "normal", key: "/" },
+  homeSwitch: { mode: "normal", key: "Ctrl+Left/Right" },
+  skills: { mode: "normal", key: "Ctrl+K" },
 };
-export function keyBindings() { return { ...DEFAULT_KEYBINDINGS, ...(loadTuiConfig().keyBindings ?? {}) }; }
-export function setKeyBinding(id, value) { const all = { ...(loadTuiConfig().keyBindings ?? {}) }; all[id] = value; return saveTuiConfig({ keyBindings: all }); }
+
+/** Effective two-slot keybindings: defaults merged per id with user overrides. */
+export function keyBindings() {
+  const overrides = loadTuiConfig().keyBindings ?? {};
+  const merged = {};
+  for (const id of Object.keys(DEFAULT_KEYBINDINGS)) {
+    const def = DEFAULT_KEYBINDINGS[id];
+    const raw = overrides[id];
+    if (!raw) { merged[id] = { ...def }; continue; }
+    const normalized = normalizeKeyBinding(raw);
+    // A saved legacy default value maps back onto the current defaults so
+    // remapped chords (Ctrl+F, Ctrl+Left/Right, Ctrl+H) keep working.
+    const legacy = LEGACY_KEY_VALUES[id];
+    if (legacy && !Object.hasOwn(raw, "key2") && normalized.mode === legacy.mode && normalized.key === legacy.key) {
+      merged[id] = { ...def };
+      continue;
+    }
+    if (!normalized.key || !validateKeySpec(normalized.key).ok) { merged[id] = { ...def }; continue; }
+    const key2 = Object.hasOwn(raw, "key2")
+      ? (normalized.key2 && validateKeySpec(normalized.key2).ok ? normalized.key2 : "")
+      : def.key2;
+    merged[id] = { mode: normalized.mode, key: normalized.key, key2 };
+  }
+  return merged;
+}
+export function setKeyBinding(id, value) {
+  if (!Object.hasOwn(DEFAULT_KEYBINDINGS, id)) return false;
+  const normalized = normalizeKeyBinding(value);
+  if (!normalized.key || !validateKeySpec(normalized.key).ok) return false;
+  if (normalized.key2 && !validateKeySpec(normalized.key2).ok) return false;
+  const all = { ...(loadTuiConfig().keyBindings ?? {}) };
+  all[id] = normalized;
+  return saveTuiConfig({ keyBindings: all });
+}
 export function resetKeyBinding(id) { const all = { ...(loadTuiConfig().keyBindings ?? {}) }; delete all[id]; return saveTuiConfig({ keyBindings: all }); }
 
+/** Drop the 1s read cache so an external editor's changes apply immediately. */
+export function reloadTuiConfig() { cache = { file: null, data: null, at: 0 }; }
+
 export function foldDefaults() {
   const fd = loadTuiConfig().foldDefaults ?? {};
   return {

package/src/file-picker.js

@@ -1,4 +1,4 @@
-import { Widget, Input, Popup } from './widgets.js';
+import { Widget, Input, Popup, wrapIndex } from './widgets.js';
 import { truncate } from './text.js';
 import { T } from './theme.js';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
@@ -183,8 +183,8 @@ export class UploadPicker extends Widget {
     if (ev.ctrl && ev.key === '.') { const name=this.current()?.name; this.showHidden=!this.showHidden; this.load(name); this.app.toast(this.showHidden?'已显示隐藏文件':'已隐藏隐藏文件'); return true; }
     if (ev.ctrl && (ev.key === '/' || ev.key === '_')) { this.filter = ''; this.load(); return true; }
     if (ev.name === 'escape') { this.clearKitty(); this.onCancel?.(); return true; }
-    if (ev.name === 'up') { this.clearKitty(); this.sel = Math.max(0, this.sel - 1); return true; }
-    if (ev.name === 'down') { this.clearKitty(); this.sel = Math.min(this.items().length - 1, this.sel + 1); return true; }
+    if (ev.name === 'up') { this.clearKitty(); this.sel = wrapIndex(this.sel - 1, this.items().length); return true; }
+    if (ev.name === 'down') { this.clearKitty(); this.sel = wrapIndex(this.sel + 1, this.items().length); return true; }
     if (ev.name === 'left') { this.goParent(); return true; }
     if (ev.name === 'right') { this.enterDir(); return true; }
     if (ev.name === 'enter') { this.confirmUpload(); return true; }
@@ -192,5 +192,5 @@ export class UploadPicker extends Widget {
     if (ev.name === 'char' && ev.key === '/') { this.startFilter(); return true; }
     return false;
   }
-  onMouse(ev) { if (ev.kind === 'wheel-up') { this.sel = Math.max(0, this.sel - 1); return true; } if (ev.kind === 'wheel-down') { this.sel = Math.min(this.items().length - 1, this.sel + 1); return true; } return true; }
+  onMouse(ev) { if (ev.kind === 'wheel-up') { this.sel = wrapIndex(this.sel - 1, this.items().length); return true; } if (ev.kind === 'wheel-down') { this.sel = wrapIndex(this.sel + 1, this.items().length); return true; } return true; }
 }

package/src/keybindings.js

@@ -0,0 +1,172 @@
+// keybindings.js — the single source of truth for editable shortcuts.
+//
+// Every function owns TWO slots: `key` (primary) and `key2` (alternate).
+// User overrides live in tui-config.json under
+//   keyBindings.<id> = { "mode": "normal"|"insert"|"all", "key": "...", "key2": "..." }
+// and the dispatchers in views.js consult this registry instead of hardcoded
+// key checks. A spec is either one press ("Ctrl+F"), or a two-press chord
+// ("g g"). Modifier prefixes are Ctrl / Shift / Alt; named keys are
+// Up/Down/Left/Right/Enter/Escape(Esc)/Tab/Backtab/PgUp/PgDn/Home/End/
+// Insert/Delete/Space and F1–F12; anything else must be a single character.
+
+export const KEYBINDING_MODES = ["normal", "insert", "all"];
+
+export const DEFAULT_KEYBINDINGS = {
+  think: { mode: "normal", key: "t", key2: "" },
+  tools: { mode: "normal", key: "b", key2: "" },
+  insert: { mode: "normal", key: "i", key2: "" },
+  leaveInsert: { mode: "insert", key: "Esc", key2: "" },
+  sessionFilter: { mode: "normal", key: "Ctrl+F", key2: "/" },
+  newSession: { mode: "normal", key: "n", key2: "" },
+  top: { mode: "normal", key: "g g", key2: "" },
+  bottom: { mode: "normal", key: "G", key2: "" },
+  prevQuestion: { mode: "normal", key: "[", key2: "" },
+  nextQuestion: { mode: "normal", key: "]", key2: "" },
+  expandInput: { mode: "insert", key: "Ctrl+L", key2: "" },
+  copyInput: { mode: "insert", key: "Ctrl+Shift+C", key2: "" },
+  panel: { mode: "all", key: "Ctrl+Space", key2: "F7" },
+  model: { mode: "normal", key: "Ctrl+M", key2: "" },
+  trajectory: { mode: "normal", key: "Ctrl+T", key2: "" },
+  homeSwitch: { mode: "normal", key: "Ctrl+Left", key2: "Ctrl+Right" },
+  permissionRotate: { mode: "normal", key: "F8", key2: "" },
+  workspace: { mode: "normal", key: "Ctrl+W", key2: "" },
+  settings: { mode: "normal", key: "Ctrl+S", key2: "" },
+  subagent: { mode: "normal", key: "Ctrl+A", key2: "" },
+  skills: { mode: "normal", key: "Ctrl+H", key2: "" },
+  goal: { mode: "normal", key: "Ctrl+G", key2: "" },
+  jobs: { mode: "normal", key: "Ctrl+J", key2: "" },
+  queue: { mode: "normal", key: "Ctrl+N", key2: "" },
+  busyEnter: { mode: "normal", key: "Ctrl+Y", key2: "" },
+  attachments: { mode: "normal", key: "Ctrl+O", key2: "" },
+  stepJump: { mode: "normal", key: "Ctrl+E", key2: "" },
+  sidebar: { mode: "normal", key: "Ctrl+B", key2: "" },
+  editConfig: { mode: "normal", key: "Ctrl+K", key2: "" },
+  quit: { mode: "all", key: "Ctrl+Q", key2: "" },
+};
+
+/** App-level dispatch precedence: the first matching binding wins. */
+export const KEYBINDING_ORDER = [
+  "sessionFilter", "panel", "homeSwitch", "permissionRotate", "editConfig", "quit",
+  "model", "trajectory", "workspace", "settings", "subagent", "skills", "goal",
+  "jobs", "queue", "busyEnter", "attachments", "stepJump", "sidebar",
+];
+
+/** Transcript-level bindings evaluated inside ChatView.onKey. */
+export const CHAT_BINDING_ORDER = ["think", "tools", "insert", "top", "bottom", "prevQuestion", "nextQuestion", "sessionFilter"];
+
+/** Sidebar-level bindings evaluated inside SidebarTree.onKey. */
+export const SIDEBAR_BINDING_ORDER = ["insert", "newSession"];
+
+const NAMED_KEYS = {
+  up: "up", down: "down", left: "left", right: "right", enter: "enter",
+  escape: "escape", esc: "escape", tab: "tab", backtab: "backtab",
+  pgup: "pgup", pgdn: "pgdn", home: "home", end: "end",
+  insert: "insert", delete: "delete",
+};
+
+/** Parse one key press spec ("Ctrl+Shift+C", "F8", "g"). Null when malformed. */
+function parseKeyPart(part) {
+  if (typeof part !== "string") return null;
+  const pieces = part.split("+");
+  const base = pieces.pop() ?? "";
+  if (!base) return null;
+  const mods = { ctrl: false, shift: false, alt: false };
+  for (const piece of pieces) {
+    if (piece === "Ctrl") mods.ctrl = true;
+    else if (piece === "Shift") mods.shift = true;
+    else if (piece === "Alt") mods.alt = true;
+    else return null;
+  }
+  const named = NAMED_KEYS[base.toLowerCase()];
+  if (named) return { ...mods, named };
+  if (base === " " || base.toLowerCase() === "space") return { ...mods, space: true };
+  if (/^f\d{1,2}$/i.test(base)) return { ...mods, fkey: base.toLowerCase() };
+  if (base.length === 1) {
+    const lower = base.toLowerCase();
+    // An uppercase letter implies Shift only for unmodified letters ("G"):
+    // "Ctrl+F" denotes the Ctrl chord, not Ctrl+Shift+F.
+    const wantsShift = base !== lower && !mods.ctrl && !mods.alt;
+    return { ...mods, shift: mods.shift || wantsShift, char: lower };
+  }
+  return null;
+}
+
+/** Split a full spec into its presses ("g g" → ["g", "g"]). */
+export function specParts(spec) {
+  return String(spec ?? "").split(/\s+/).filter(Boolean);
+}
+
+/** Whether one key event satisfies one press spec. */
+export function matchKeyPart(ev, part) {
+  if (!ev || ev.type !== "key") return false;
+  const parsed = parseKeyPart(part);
+  if (!parsed) return false;
+  const ctrl = ev.ctrl === true, shift = ev.shift === true, alt = ev.alt === true;
+  if (ctrl !== parsed.ctrl || alt !== parsed.alt) return false;
+  if (parsed.space) return ev.name === "char" && ev.key === " " && shift === parsed.shift;
+  if (parsed.named) return ev.name === parsed.named && shift === parsed.shift;
+  if (parsed.fkey) return ev.name === parsed.fkey && shift === parsed.shift;
+  return ev.name === "char" && ev.key === parsed.char && shift === parsed.shift;
+}
+
+/**
+ * Match an event against one binding's two slots. Returns
+ * { kind:"full", slot } | { kind:"pending", slot, part } | null.
+ * `pending` carries an in-progress two-press chord across events.
+ */
+export function matchKeyBinding(ev, spec, pending = null) {
+  if (!spec) return null;
+  for (const slot of ["key", "key2"]) {
+    const parts = specParts(spec[slot]);
+    if (parts.length === 0) continue;
+    if (pending && pending.slot === slot) {
+      const part = parts[pending.part];
+      if (!part || !matchKeyPart(ev, part)) continue;
+      return pending.part + 1 >= parts.length ? { kind: "full", slot } : { kind: "pending", slot, part: pending.part + 1 };
+    }
+    if (parts.length === 1 && matchKeyPart(ev, parts[0])) return { kind: "full", slot };
+    if (parts.length === 2 && matchKeyPart(ev, parts[0])) return { kind: "pending", slot, part: 1 };
+  }
+  return null;
+}
+
+/** First matching binding across an ordered id list. `editing` = INSERT mode. */
+export function bindingMatchFor(ev, bindings, editing, order = KEYBINDING_ORDER) {
+  for (const id of order) {
+    const spec = bindings?.[id];
+    if (!spec) continue;
+    if (spec.mode === "normal" && editing) continue;
+    if (spec.mode === "insert" && !editing) continue;
+    const hit = matchKeyBinding(ev, spec);
+    if (hit?.kind === "full") return { id, slot: hit.slot };
+  }
+  return null;
+}
+
+/** Human-readable spec ("Ctrl+Left", "g, g"); "—" when empty. */
+export function describeSpec(spec) {
+  const parts = specParts(spec);
+  return parts.length ? parts.join(", ") : "—";
+}
+
+/** Validate a user-supplied key spec. */
+export function validateKeySpec(spec) {
+  const parts = specParts(spec);
+  if (parts.length === 0 || parts.length > 2) {
+    return { ok: false, reason: `需要 1–2 次按键（如 "Ctrl+F" 或 "g g"），得到 ${parts.length || 0} 次` };
+  }
+  for (const part of parts) {
+    if (!parseKeyPart(part)) {
+      return { ok: false, reason: `无法解析按键 "${part}"（支持 Ctrl/Shift/Alt 修饰、方向/功能键、单字符，如 Ctrl+Left、F8、g g）` };
+    }
+  }
+  return { ok: true };
+}
+
+/** Normalize a raw user override into { mode, key, key2 } (backwards compatible). */
+export function normalizeKeyBinding(value) {
+  const mode = KEYBINDING_MODES.includes(value?.mode) ? value.mode : "normal";
+  const key = typeof value?.key === "string" ? value.key.trim() : "";
+  const key2 = typeof value?.key2 === "string" ? value.key2.trim() : "";
+  return { mode, key, key2 };
+}

package/src/md.js

@@ -2,7 +2,7 @@
 // Segments: { t: string, fg?, bg?, bold, italic, underline, strike, code, link? }
 // Links use OSC 8 (clickable in most terminals, emitted by Screen.render).
 
-import { hexRgb, strWidth, truncate } from "./text.js";
+import { hexRgb, strWidth, truncate, graphemes } from "./text.js";
 
 import { T } from "./theme.js";
 
@@ -255,31 +255,39 @@ export function renderMd(text, width, sink = null, opts = {}) {
         const lang = inCode || "text";
         const hw = Math.max(2, width - 4);
         const codeLines = codeBuf.length === 0 ? [""] : codeBuf;
-        if (sink?.codeBlocks) sink.codeBlocks.push({ text: codeBuf.join("\n"), lineIdx: lines.length, lang });
+        const codeMeta = { text: codeBuf.join("\n"), lineIdx: lines.length, lang };
+        if (sink?.codeBlocks) sink.codeBlocks.push(codeMeta);
         // Fixed-width box: EVERY row is exactly (hw + 4) columns wide —
-        // top `┌…[复制]…┐`, content `│ … │`, bottom `└…┘` — so the corners
-        // always sit above the vertical bars, never above the code text.
+        // top `┌─ [tag] [复制…] ───┐`, content `│ … │`, bottom `└…┘` — so the
+        // corners always sit above the vertical bars, never above the code.
         const btn = "[复制]";
+        const activeBtn = "[按y复制]";
         const btnW = strWidth(btn);
+        // The tag sits INSIDE the box, before the button: the button field is
+        // padded to a fixed reserve width so the NORMAL-mode [按y复制] swap
+        // never shifts the right corner. Nothing extends past the box.
+        const tagPart = lang && lang !== "text" ? lang + " " : "";
+        const tagW = strWidth(tagPart);
+        const reserveW = Math.max(btnW, Math.min(strWidth(activeBtn), Math.max(0, hw - tagW)));
+        const btnField = btn + " ".repeat(Math.max(0, reserveW - btnW));
+        const tailPad = Math.max(1, hw + 1 - tagW - reserveW);
         const inner = hw + 2;                       // columns between the corners
-        const leftLen = Math.max(1, inner - btnW - 2);
-        const tag = lang && lang !== "text" ? " " + lang : "";
         lines.push([
-          SEG("┌" + "─".repeat(leftLen) + " ", { fg: C.hr }),
-          SEG(btn, { fg: C.link, bold: true, copyCode: codeBuf.join("\n") }),
-          SEG(" ┐" + tag, { fg: C.hr }),
+          SEG("┌─" + tagPart, { fg: C.hr, codeBlock: codeMeta }),
+          SEG(btnField, { fg: C.link, bold: true, copyCode: codeBuf.join("\n"), codeBlock: codeMeta }),
+          SEG("─".repeat(tailPad) + "┐", { fg: C.hr, codeBlock: codeMeta }),
         ]);
         for (const cl of codeLines) {
           const hls = highlightLine(cl, lang);
           for (const row of wrapSegs(hls, hw)) {
             const rowW = strWidth(row.map((g) => g.t ?? "").join(""));
-            const segs = [SEG("│ ", { fg: C.hr }), ...row];
+            const segs = [SEG("│ ", { fg: C.hr, codeBlock: codeMeta }), ...row.map((seg) => ({ ...seg, codeBlock: codeMeta }))];
             if (rowW < hw) segs.push(SEG(" ".repeat(hw - rowW)));
-            segs.push(SEG(" │", { fg: C.hr }));
+            segs.push(SEG(" │", { fg: C.hr, codeBlock: codeMeta }));
             lines.push(segs);
           }
         }
-        lines.push([SEG("└" + "─".repeat(inner) + "┘", { fg: C.hr })]);
+        lines.push([SEG("└" + "─".repeat(inner) + "┘", { fg: C.hr, codeBlock: codeMeta })]);
         inCode = null;
       }
       i++;
@@ -368,13 +376,12 @@ export function wrapSegs(segs, width, { pad: padLines = false } = {}) {
       while (strWidth(rest) > width) {
         let cut = "";
         let cw = 0;
-        for (const ch of rest) {
-          const c = ch.codePointAt(0);
-          const cwc = wcwidthFor(c);
+        for (const ch of graphemes(rest)) {
+          const cwc = strWidth(ch);
           if (cw + cwc > width) break;
           cut += ch; cw += cwc;
         }
-        if (!cut) cut = rest[0];
+        if (!cut) cut = graphemes(rest)[0] ?? "";
         if (curW > 0) { lines.push(cur); cur = []; curW = 0; }
         lines.push([{ ...seg, t: cut }]);
         rest = rest.slice(cut.length);
@@ -395,8 +402,3 @@ export function wrapSegs(segs, width, { pad: padLines = false } = {}) {
   if (lines.length === 0) lines.push([SEG("")]);
   return lines;
 }
-
-function wcwidthFor(cp) {
-  // local import to avoid cycles
-  return strWidth(String.fromCodePoint(cp));
-}