@deepseek-harness-tui/dsh-tui 0.11.2 → 0.13.0

package/guide/dsh-tui-guide/interaction.md

@@ -0,0 +1,793 @@
+# 交互与命令
+
+[文档索引](README.md) · [English](interaction.en.md)
+
+## 输入与全局快捷键
+
+| 按键 | 行为 |
+| --- | --- |
+| `Enter` | 空闲时发送；模型工作时把文本 steer 到当前回合的下一步边界；菜单打开时确认选项 |
+| `Tab` | 补全 `/` 命令或 `@` 文件；模型工作且输入非空时排入当前回合之后的 follow-up |
+| `Ctrl+Enter` | 打断当前回合并立即处理输入消息 |
+| `Shift+Enter` / `Ctrl+J` | 在光标处插入换行；终端无法上报 Shift 修饰键时可用 `Ctrl+J`（LF）兜底，macOS Terminal.app 用 `Option+Enter` |
+| `Shift+Tab` | 在配置的会话模式间循环（默认：默认 → 计划模式 → 完全访问）；运行时可用的第三方 permission preset 按 registry 顺序追加到循环末尾，`custom`/`status`、canonical 预设、重复 identity 和不安全 token 不加入 |
+| `Alt/Option+Up` | 把最后一条尚未处理的消息取回输入框编辑 |
+| `Up/Down` | 菜单选择；普通输入中浏览历史或在多行文本间移动 |
+| `Ctrl+V` / `Alt+V` | 从系统剪贴板插入文本或文件；图片作为持久附件发送。终端拦截 `Ctrl+V` 时用 `Alt+V` |
+| `Ctrl+G` | 用外部编辑器（`$VISUAL` → `$EDITOR`）编辑当前输入，保存退出后回填；`:cq` 或非零退出保留原稿；未设置变量时提示配置，无 `vi` 兜底 |
+| `Ctrl+Shift+E` | 展开全屏草稿编辑器（也可点输入行尾 `⛶`）：行号 + 当前行高亮 + 行/字统计，`Enter` 换行、`Ctrl+Enter` 或「发送」按钮发送、`Esc` 或「收起」按钮收起（草稿保留）；滚轮自由滚动、点击定位/拖选/双击选词与输入框一致；可经 `/settings` 重映射 |
+| `Ctrl+Z` | 撤销输入框草稿的上一步「词级」编辑（文本、光标、图片一起回退）。只作用于草稿：提交、历史召回（`Ctrl+R`/`↑`）或换会话后即结束；`Esc Esc` 的会话/消息回溯与它不是一回事。可经 `/settings` 重映射 |
+| `Esc` | 层级：关帮助 → 关图片预览 → 关命令菜单 → 关文件菜单（仅当前 `@` token）→ **输入框内有选区时仅清选区（文本不动）** → 中断回合并重投 pending 消息 → 有输入时清空 → 空输入连续两次 = 时间回溯 rewind；fullscreen 下有鼠标选区时优先取消选区（不复制） |
+| 图片预览打开时 `Esc` / `Ctrl+C` / `Enter` | 关闭预览，恢复下层界面；其余按键不透传 |
+| 图片弹窗中的 `←` / `→` | 上一张 / 下一张；首尾不循环，临时光标预览不抢输入框方向键 |
+| `Ctrl+C` | 工作时中断；中断迟迟不收敛时再按一次强制退出；空闲且有输入时清空；**空闲且输入框内有选区时复制选区到剪贴板（保留选区继续编辑）**；空输入时连续两次退出 |
+| `Ctrl+D` | 与 `Ctrl+C` 同阶梯：工作中=中断（未收敛时再按=强制退出）；空闲时连续两次退出 |
+| `Ctrl+O` | 切换 transcript/verbose 详情，展开思考与完整工具参数/输出；也是**超长单行折叠**（单行 > 1000 字符裁到 1000 + `… 已折叠 N 字符` 标记，见 user guide §5）的展开逃生门——鼠标点被折叠的那一行（或工具卡卡面）同样能展开/收起 |
+| `Ctrl+P` | 切换启动时加载的 loaded-context 面板（面板在屏时有效） |
+| `Ctrl+B` | 侧栏三态：未开 → 打开并聚焦右栏；已开且焦点在聊天 → 聚焦右栏；焦点在右栏 → 关闭并回聊天。仅 fullscreen 且内容区 ≥93 列可分栏，窄屏与 inline 下此键不生效（`/jobs` 等仍走整屏面板，见用户指南 §2.8） |
+| `Alt+Z` | 缩放当前侧栏面板（聊天列保留最小宽度），再按恢复 |
+| `Ctrl+T` | 打开轨迹场景（等同 `/trace`）；场景内 `q`/`Esc` 返回对话 |
+| `Ctrl+R` | 打开输入历史搜索；重复按或 `Down` 移到下一项 |
+| `Ctrl+L` | 强制清理并重绘物理终端 |
+| `?` | 输入框为空时打开快捷键和命令帮助 |
+| Help 内 `↑/↓`、`PgUp/PgDn`、`Home/End` | 逐行滚动、翻页或跳到命令列表首尾；`Esc` 关闭 |
+| 转录内 `PgUp` / `PgDn` | 全屏模式按页翻动消息列表（每页一屏减一行）；Help 或浮层打开时让位（各滚各的）；inline 模式不接管——历史在终端原生 scrollback 里，翻页归终端 |
+| `Shift+Up` | 进入消息选择模式；方向键移动，`Enter` 展开单条，`Esc` 退出 |
+
+动作型快捷键支持在 `/settings` → `dsh-tui` → `Shortcuts` 自定义。
+
+- 覆盖：粘贴、历史搜索、外部编辑器、`Ctrl+O/T/P/R/L`、侧栏（`Ctrl+B`、`Alt+Z`）、子代理面板、显示全部、待办折叠。
+- 填 `alt+v` 这类组合，多个用逗号分隔；留空恢复默认，保存即生效。
+- 与固定编辑键或其它动作冲突的组合会被拒绝。
+- cordis.yml 可用 `shortcuts.<action>` 静态指定。
+
+`/` 有两种用途：普通输入模式打开 slash command 补全；`Ctrl+O` 的 transcript 模式打开会话全文搜索。
+
+- 全文搜索用 `n`/`N` 在结果间前后跳转。
+
+插件可经 `tuiShortcuts` 接缝注册额外组合键。
+
+- 组合键必须带 Ctrl 或 Alt；内建绑定永远优先。
+- 冲突的组合在注册时就会被拒绝。
+
+插件弹出的托管对话框（select/confirm/input）打开期间独占键盘：
+
+- `↑`/`↓` 移动，`Enter` 确认，`Esc` 取消。
+
+插件还能加一行纯文本，或经 `tuiStatus.registerView` 显示紧凑富状态：
+
+- 富状态最多三行，只能用宿主的 `Box`、`Text`、`Image` 与终端尺寸。
+- 点击/悬停/拖动只在 fullscreen 下生效，不会取得键盘。
+- `Image` 接收已解码 RGBA，另有同尺寸字符回退。
+- 探测到 Kitty graphics 时，按终端报告的单元格像素比例等比居中。
+- 像素比例不可用时用保守默认值；必要时透明留边并降采样。
+- 否则自动显示回退内容（inline、辅助功能、多路复用器同样如此）。
+
+同一动作的键盘路径由插件另提供 slash 命令，或注册 `tuiShortcuts`。
+
+- 富状态注册被拒绝时返回 `undefined`。
+- 注册成功时返回 disposer，会同时撤下视图和对应 Cordis effect。
+
+### 落地页与首次引导
+
+启动**落地页**与**首次引导向导**各自独占键盘；两者都只把结果交回对话页，不新增行为。
+
+- **落地页**：可打印字符接进输入框（行首 `/` 时前缀由 `❯` 变 `⌘`），`Backspace`/`Delete`/`←`/`→`/`Home`/`End` 编辑；
+- **落地页**：可打印字符接进输入框（行首 `/` 时前缀由 `❯` 变 `⌘`），`Backspace`/`Delete`/`←`/`→`/`Home`/`End` 编辑；
+  输入光标是**压在当前字符身上的反显块**（对那一个字符 inverse，行尾是反显空格），闪烁是纯样式切换
+  （inverse ↔ 常规，约 550ms 一相位），绝不另起一格、绝不吃掉字符；`Alt+R` 继续最近一条会话
+  （= 入口行第一格「继续「…」」，仅此屏生效，无可继续会话时无动作，键位可在 `/settings` 改）；
+  **执行**选中命令，`Esc` 只收面板、草稿不动）；面板没收时 `Enter` 直接**发送**这一行（行首 `/` 的命令——含
+  插件/registry 命令——按对话页同一条合并命令表判定，是命令就不发模型）；
+  `↑`/`↓`/`Tab` 沿焦点环走（输入框 → 框下参数行四段 → 快捷入口行 → Tips 行），`Enter` 激活焦点上的那一条
+  （焦点在 Tips 行上 `Enter` = 切下一条 Tip），在入口/参数段上敲字会把焦点收回输入框；有字时 `Esc` 只清空，
+  空输入 `Esc` 去看会话，空输入 `Ctrl+C` 走退出漏斗。
+- **落地页参数行**（框下一行：模型 · 思考深度 · 模式 · 权限；模型段只显示模型名，模式段显示 agent preset
+  的显示名——Standard/PTC/极简…）：四段**各自可点**，点开的就是对话页同一套选择器
+  （`/model` · `/effort` · `/preset` · `/permission`），选择器**盖在落地页之上**、吃走键盘
+  （`Esc` 关掉它回到落地页），选中的值就地更新参数行、已输入的草稿不动；选择器开着时点它内部是选择，
+  **点别处会关掉它、点另一段会直接切换**成那个选择器。
+- **入口行（第七版四格）**：`继续「…」`（Alt+R；无可继续会话时整格不画）· `会话与工作区`（`/home`，
+  历史会话与工作区合并成一个入口）· `设置`（`/settings`）· **条件位**（优先级：有后台任务在跑 →
+  `后台任务`；检测到新版本 → `有新版本`；用量到档且从未 star → `投喂一颗 Star`；兜底 `帮助`）。
+  从落地页打开的整屏界面（会话与工作区 / 设置 / 后台任务 / 家谱 / 引导向导）都**盖在落地页之上**，
+  `Esc` 退出回到落地页（草稿/参数/焦点原样保留）；**离开落地页进对话页的唯一方式是回车提交一条
+  非命令消息**。落地页这一侧的浮层（选择器/命令面板）是**干净的镂空**——矩形内空格占位
+  遮掉宿主屏的字形（绝不重影）、不发背景色（无白底；Kitty 立绘图像仍从终端默认背景透出；
+  聊天页同款选择器不受影响）。
+- **Tips 行**：可点击轮换（三条 Tips 循环；首启那一句优先级最高、不参与轮换），键盘路径 = 焦点环 + `Enter`；
+  第七版起还**自动轮换**（约 10s 一换，手动切换后计时重置），切换只改文本、行高与居中位置不变。
+- **双角铭牌（第七版）**：左下角工作目录**可点**——点开既有的 `/workspace` 菜单
+  （盖在落地页之上、`Esc` 回落地页），键盘路径 = 焦点环末格 + `Enter`，悬停/焦点 =
+  文字高亮；右下角是**双版本竖排两行**：第一行 `dsh-tui v<TUI>`、第二行
+  `dsh-core v<内核>`（内核版本读宿主/内核线包的 manifest，读不到只画 TUI 一行），
+  两行都右对齐、左下目录铭牌与第一行顶对齐，窄屏按既有 truncate-middle 截断。
+- **引导向导**：`←`/`→` 换步骤（例外：第三步的强度区、以及已钻进去的模型列表，横向键归子控件，不换步骤）、
+  `Tab` 在「语言 / 主题」与「模型 / 强度 / 工作区」两组面板间切、`↑`/`↓` 移动选择；
+  `Enter` 执行这一步（第一步 = 重新检查连通性，第三步 = 钻进 provider / 换模型 / 打开工作区选择器——**强度不走 Enter**，只用 `←`/`→` 调且移动即生效）；
+  主题面板移动光标即预览，**语言面板要 `Enter` 才生效**；最后一步的 `Enter` 在**键位卡**上「完成」并记账，
+  在命令卡上则是「试一下」；`Esc` 跳过（**不记账**，下次启动再问）。
+- **鼠标**（fullscreen）：落地页的快捷入口（悬停 = 文字变主题蓝加粗，移开复原）、参数行四段、命令补全面板、
+  Tips 行、引导招式卡的「试一下」与工作区选择器都可点，点击与键盘落到同一条命令路径。
+
+## 输入编辑
+
+| 按键 | 行为 |
+| --- | --- |
+| `Left/Right` | 按字符移动光标；**有选区时坍缩到选区对应边缘** |
+| `Ctrl+Left/Right` | 按单词移动 |
+| `Home/End` | 移到当前逻辑行首/行尾 |
+| `Ctrl+A` / `Ctrl+E` | `Ctrl+A` 打开子代理面板（编辑器内 `Mod+A` 仍移到行首）；`Ctrl+E` 移到行尾，还会展开或折叠长会话中隐藏的旧消息 |
+| `Ctrl+U` | 删除光标前内容 |
+| `Ctrl+K` | 删除光标后内容 |
+| `Ctrl+W` | 删除前一个单词 |
+| `Backspace` / `Delete` | 删前一 / 后一字符；**有选区时删除整个选区** |
+| 打字 | **有选区时替换整个选区**，光标落在插入文本之后 |
+
+### vim 编辑模式（`/vim`）
+
+`/vim` 切换输入框的 vim 编辑模式（会话级、不持久化）。
+
+- 开启后输入框左侧出现 `INSERT` 徽标，打字照常。
+- `Esc` 切到 `NORMAL` 徽标，裸键按 vim 规则处理。
+
+| NORMAL 键 | 行为 |
+| --- | --- |
+| `h` / `l` | 左 / 右移一个字符 |
+| `j` / `k` | 下 / 上一行（多行输入） |
+| `0` / `^` / `$` | 行首 / 行首首个非空白 / 行尾 |
+| `w` / `b` | 下一个 / 上一个词首（空白分词） |
+| `x` / `X` | 删除光标处 / 光标前字符（行尾时 `x` 删最后一个字符） |
+| `d` + 第二键 | `dd` 删整行（含换行）· `d$` 删至行尾 · `d0`/`d^` 删至行首 · `dw` 删至词尾 |
+| `u` | 撤销最近一次 vim 编辑（栈上限 100） |
+| `i` / `I` / `a` / `A` | 光标处 / 行首首个非空白 / 光标后 / 行尾进入 INSERT |
+| `o` / `O` | 下方 / 上方新建一行并进入 INSERT |
+| `/` | 插入 `/` 并切回 INSERT（打开命令菜单） |
+| `Esc` | 取消待决 `d`；其余无操作（不触发现有清空 / 双击 rewind 行为） |
+| `Enter` / `Tab` / 方向键 / `Ctrl+*` 组合 | 照常放行（发送、补全、历史、编辑快捷键等） |
+| 其他裸键 | 忽略，不插入 |
+
+注意：vim 开启时 `Esc` 归 vim 管。
+
+- 时间回溯：退出 vim 模式后双击 `Esc`，或用 `/rewind`。
+- 回合运行中 insert 模式按 `Esc` 只回 normal；打断回合用 `Ctrl+C` / `Ctrl+Enter`。
+- NORMAL 下清空输入用 `Ctrl+C` 或 `dd`。
+
+Bracketed paste（右键或终端原生粘贴）保留普通文本与换行。
+
+- 不会把粘贴内容误当成 `Enter` 提交。
+- 为保显示、点击与选区几何一致，剥离终端 ANSI 控制序列。
+- 多行粘贴不再留下 `_`：Windows 终端以 win32-input-mode 逐条记录投递时，残留的键记录（`ESC[Vk;Sc;Uc;Kd;Cs;Rc_` 完整形态，或记录拆散后无 ESC 的尾部）在入口整体剥离；只匹配 5 段分号的记录语法，普通文本里的真实 `_` 与形似记录的方括号文本不受影响。
+- CRLF 折叠：粘贴内容里的 CR+LF 只产生一个换行，不再多出空行；LF-only 与单独 CR 行为不变。
+- `Tab` 进入编辑缓冲区时展开为空格。
+
+### 全屏草稿编辑（`Ctrl+Shift+E` / `⛶`）
+
+长草稿不再挤 5 行小窗。
+
+- `Ctrl+Shift+E`（可重映射）或输入行尾的 `⛶` 按钮，把草稿展开成整屏编辑器。
+- 编辑状态（光标/选区/折叠/vim 模式）与输入框是同一份。
+- 可在 `/settings` → `dsh-tui` 关闭（`expandEditor`，默认开）。
+- 关闭后 `⛶` 与快捷键两个入口都不再出现。
+
+- **外观**：
+  - 圆角边框随会话强调色/plan 色联动。
+  - 左侧行号槽，宽度随行数伸缩，光标行号提亮。
+  - 光标行整行浅底色。
+  - 标题行实时显示行数/字数。
+  - 状态行显示 `行 L · 列 C` 与 vim 徽标（`/vim` 开启时）。
+- **键位**：
+  - `Enter` 换行（绝不误发送）。
+  - `Ctrl+Enter` 或「⏎ 发送」按钮发送并收起。
+  - `Esc` 分层：先清选区，再收起编辑器，草稿保留。
+  - `Tab` 插入 4 空格缩进。
+  - 其余编辑键与输入框一致：方向/词跳/Home/End/`Ctrl+U/K/W`、vim NORMAL 键位。
+- **折叠块互斥**：
+  - 收起态粘贴大文本照旧折叠成 chip。
+  - 编辑器展开块即散开（与点击 chip 展开同一行为）。
+  - 展开期间粘贴一律是纯文本、直接可编辑。
+  - 收起后也不会再变回块。
+- **鼠标**：
+  - 点击定位光标、拖拽建选区、双击选词、`Ctrl+C` 复制选区。
+  - 几何按行号槽宽度校正。
+  - 滚轮自由滚动；浏览时不强制跳回光标。
+  - 任何光标移动后恢复跟随。
+  - 「发送」「收起」按钮可点击且 hover 提亮。
+- 与 `Ctrl+G` 外部编辑器互补：不依赖 `$VISUAL/$EDITOR`，不离开终端。
+
+## @ 文件引用
+
+在消息**任意位置**输入 `@` 打开文件补全菜单。
+
+- 输入即过滤，`Tab`/`Enter` 选择，目录可继续深入。
+- 普通片段走**模糊匹配**（`@ment` 命中 `src/utils/mentions.ts`；前缀/边界命中优先，短路径优先）。
+- 路径形态（`@src/`、`@./`、`@../`、`@~/`、`@D:\` 或含分隔符）只读**该目录**，不全仓扫描。
+- `Esc` 只关当前 `@` token 的菜单。
+- 异步候选刷新时按候选身份保持当前选中项。
+
+发送消息时：
+
+- 文本文件内容或目录列表会自动附加到消息。
+- PNG、JPEG、WebP、GIF 经 Harness 附件库作为真正的图片块发送。
+- 文件读取走当前 workspace 的 FS 服务；提供者管理的 workspace 同样适用。
+
+### 粘贴与 `[Image #N]`
+
+`Ctrl+V` 粘贴时：
+
+- 文件管理器（Finder、Windows Explorer、GNOME Files、KDE Dolphin 等）复制的普通文件插入路径。
+- 复制的图片文件与剪贴板位图一样，直接保存到附件库。
+- 输入框显示 `[Image #N]`；暂存失败退回 `@` 引用。
+- 发送时变成真正的图片块；输入文本不含 base64。
+
+终端把拖放转发为粘贴文本时（如 Ghostty 经 PTY 发送转义路径）：
+
+- 只有整段粘贴恰为一个存在的本地图片路径才暂存。
+- 任何歧义都原样保留文本。
+
+暂存的 `[Image #N]` 在输入框里是一个整体。
+
+- 光标不会停在它内部，`←`/`→` 整体跳过。
+- 光标在其末尾按 `Backspace`、在其起点按 `Delete`、或按 `Ctrl+W`，都整体删除。
+- 选区边缘落在其中会扩到整个 token。
+
+它的显示与预览：
+
+- 以主题强调色显示；光标位于起点时整块反显。
+- 点击它把光标放到起点，并打开预览。
+- 整块反显（光标在起点）时预览自动打开，光标离开自动关闭。
+- 停在 token 后面一格不算在其上。
+- 预览打开期间键盘仍归输入框；方向键可在多张图片间移动，预览跟着切换。
+- `Esc` 或点击卡片外只关当前 token 的预览。
+- 光标离开再回来会重新打开；点击 token 总是打开。
+- 手动输入或从历史恢复、没有附件能力的同形文本仍是普通文字。
+
+### 全屏大图预览
+
+- 打开：点击输入框里的 `[Image #N]` 或 transcript 缩略图，在对话区内打开同一个居中大图预览。
+- 输入栏、状态行与置顶提示保持可见；`Esc` 或点击卡片外关闭，窄终端显示纯元数据卡。
+- 标题格式 `Image #N — 格式 · 宽×高 · 体积 · 文件名`。
+- 底行：本次暂存的图片显示来源路径（`打开原图: …`，过长保留首尾、省略中间）；历史图片显示文件名。
+- 「打开原图」用系统看图程序打开附件库原始字节，不依赖可能已删除或被修改的来源路径，也不重新编码。
+- 原图仅在点击时导出到私有的 `dsh-tui-original-*` 系统临时目录，退出 TUI 后保留供外部程序读取，可随后通过系统临时文件清理删除。
+- 失效的 `[Image #N]`（超过 128 个暂存或会话切换后）在点击、发送、作为斜杠命令参数时都会给出明确警告。
+
+### 缩略图与回退
+
+- 发送后，用户图片从持久化会话事件重新投影到 transcript；助手/工具结果含图片块也走同一预览路径。
+- 有 Kitty graphics 或 Sixel 时显示缩略图；否则（inline、辅助功能、多路复用器或读取失败）显示文字回退。
+- 切换或恢复会话不依赖原始本地路径。
+
+### 缩放、平移与翻页
+
+- 缩放：适应（整图）/ 100%（原图局部）；`+`/`-` 在 100%、200%、400%、800% 间切换，标题显示比例。
+- 100% 需要终端报告有效字符格像素尺寸才启用。
+- 平移：拖动图片、滚轮、四个方向按钮；键盘归属与 `Esc` 关闭行为不变。
+- 换图：`←`/`→` 和底部 `‹`/`›` 上一张、下一张，显示 `当前张/总张数`，首尾不循环。
+- 从 transcript 打开按当前会话消息顺序浏览，未访问图片不预读；输入框预览按有附件能力的 token 顺序浏览。
+- 点击切图按钮进入大图弹窗，不改动草稿；仅光标触发的临时预览仍把方向键留给输入框。
+- 切图回到适应窗口，旧图异步任务会取消；会话切换或阻塞对话框出现时关闭弹窗。
+- 需要原始色彩或动画时用「打开原图」。
+
+## 界面语言
+
+`/lang` 在简体中文与英文界面之间切换（影响所有 UI 文案）。
+
+- 选择持久化，重启后沿用（0.3.7+）。
+- `/settings` 的 **dsh-tui → 界面语言** 下拉项同样可以切换。
+- 立即生效并保存到当前 profile 配置的 `dsh-tui.lang`（旧版为 `~/.dsh/settings.yaml`）。
+- `DSH_TUI_LANG` 环境变量始终优先。
+
+## 消息投递语义
+
+模型正在工作时有三种不同路径：
+
+| 操作 | 放置位置 |
+| --- | --- |
+| `Enter` | steer：送入正在运行的回合，在下一步边界被 Agent 领取 |
+| `Tab` | follow-up：等待当前回合结束后再处理 |
+| `Ctrl+Enter` | interrupt：中断当前回合并立即投递 |
+
+输入框上方会显示尚未领取的消息。
+
+- `Alt/Option+Up` 取回最后一条。
+- 模型工作时按 `Esc` 会中断，并立即重投当前 pending 消息。
+
+## 会话工作流
+
+### 会话管理（`/resume`、`/home`、`/agentview`、`/bg`、输入框 `⌸`）
+
+四条命令和输入框行首的 `⌸` 按钮打开的是**同一个界面**。
+
+- 左边是工作区（durable registry）栏，右边是所选工作区里的会话列表。
+- 每行带该会话的实时状态。
+- 原来是三个各自演化的实现（会话浏览器 / 会话总览 / 工作区首页）。
+- 同一个会话会被三个界面各自列出、各自定义"打开"的含义。
+- 所以现在只剩一个界面、一套选择模型。
+
+界面描述运行时的真实模型：**一个 TUI 进程同时托管多个会话**。
+
+- 被切走的会话是**停放**，不是结束。
+- 正在跑的回合继续跑，切回来照旧。
+- 离开一个会话不需要任何确认，也没有"停止"这一操作。
+
+打开这个界面**不会丢掉没发出去的草稿**。
+
+- 输入框随界面卸载，草稿由 Chat 保存。
+- 草稿含：文字、光标位置、已暂存的图片引用、折叠块、全屏草稿编辑器的展开态和 vim 模式。
+- `Esc` 回来时原样还给你。
+- 草稿跟着**会话**走；换了会话，上一段对话的草稿不会跟过来。
+- `/rewind` 回填的历史消息属于回退后的新会话，照常留在输入框里。
+
+| 按键 | 作用 |
+| --- | --- |
+| `←` `→` | 切换键盘所在栏（工作区栏 / 会话栏），屏幕上永远只有一个 `❯` |
+| `↑` `↓` / `PgUp` `PgDn` / 滚轮 | 在工作区栏移动工作区；在会话栏移动会话（第 0 行是"新建会话"卡片） |
+| 直接输入 | 实时筛选当前工作区下的会话（标题、目录、分支、模型） |
+| `Enter` | 会话栏：进入光标所在行（第 0 行 = 在该工作区新建会话）；工作区栏：打开该工作区的操作菜单 |
+| `Ctrl+Enter` | 在光标所在工作区新建会话（两栏都可用） |
+| `Ctrl+N` | 在光标所在工作区新建会话 |
+| `Ctrl+X` | 停止光标所在的**后台**会话（当前会话不可停止） |
+| `Ctrl+L` | 重新读取工作区登记与会话列表 |
+| `Tab` / `Shift+Tab` | 切换到下一个 / 上一个来源标签（有外部来源时） |
+| `Esc` | 先关提示 → 再清空筛选 → 再离开界面 |
+
+标题栏右侧是**来源标签条**：`DSH │ Claude Code  Codex …`。
+
+- 本机其他编程代理（Claude Code、Codex、Grok Build、zcode）有会话时才出现对应标签，按固定顺序排列；一个都没有时不显示标签条。打开界面只探测各来源是否有会话，不读取会话内容，列表在点进标签时才读取。
+- 每次打开界面都在 `DSH` 标签；点击标签或按 `Tab` / `Shift+Tab` 切换，切换时清空筛选词。
+- 终端不够宽时先隐藏副标题，再把末尾的标签折叠成 `+N`，点击 `+N` 弹出其余标签；当前标签永不折叠。
+- 外部来源标签也是两栏：左栏按会话的工作目录分组（已登记的目录沿用工作区名，没有记录目录的归「未知目录」），右栏是该目录下的会话，按标题和目录实时筛选。
+- 右栏没有"新建会话"卡片；`Enter` 或单击 = **导入并打开**：只导入这一条，写进 DSH 会话库后直接进入。已经导入过的会话直接打开，不会重复写入。
+- 会话原来的工作目录已不存在时不导入，状态行给出提示。
+- 外部标签下 `Ctrl+N`、`Ctrl+X`、固定不生效；`Ctrl+L` 改为重新扫描该来源。
+- 导入与 `/migrate` 用同一套解析和确定性 id，两个入口导入同一条会话得到的是同一个 DSH 会话。
+
+工作区栏的菜单有四项：
+
+- **编辑**：选中该工作区，右侧列出它的会话。
+- **新建会话**。
+- **重命名**。
+- **从列表移除**：只删登记，目录与会话日志都保留。
+
+工作区加入方式是"用这个目录启动 dsh-tui"（启动时自动登记）。
+
+- 界面里没有"添加工作区"入口。
+
+会话行的实时状态来自通道自己的 agent-view 投影（与状态栏的"等待输入"提示同源）。
+
+- 状态：运行中 / 等待输入 / 空闲 / 已完成 / 失败 / 已停止。
+- 当前终端所附着的那一行标 `当前`。
+
+点击行为：
+
+- 点击会话行 = 进入该会话（同 `Enter`）。
+- 点击行内的 `★`/`☆` 只切换固定状态。
+- 固定项持久化到 `~/.dsh-tui/session-pins.json`，**不会**进入会话。
+
+被**其他** TUI 终端占用的会话照常列出：
+
+- 但整行标红、行尾写 `占用 pid <pid>`，并且**点不动**。
+- 原因：两个进程驱动同一条 append-only 日志会交错写入、破坏转录。
+- 占用状态按界面自有的 2 秒间隔重读账本。
+- 对方退出后会自动恢复可进入。
+- 本进程停放中的会话不算占用。
+
+判定与文档见 [session-mount-runtime.md](session-mount-runtime.md)。
+
+当工作区服务缺失（bare composition）或有会话目录**没有登记**时：
+
+- 栏里会出现「未登记的工作区」分组。
+- 这些会话照常列出并可恢复——"没有登记"不等于"没有历史"。
+- 该分组只在本界面内存活，不会写回登记。
+
+**旧界面相较之下的行为变更**（有意移除，不再回归）：
+
+- 会话级右键菜单（重命名/删除单个会话）。
+- `Ctrl+P` 固定快捷键、`Ctrl+S` 展开委托运行。
+- `Ctrl+A`「仅本项目/全部项目」、`Ctrl+B` 分支筛选。
+- `Tab` 预览、`Ctrl+R` 重命名、`Ctrl+D` 删除、`Ctrl+X` 清理空会话。
+
+仍然保留与未回归的部分：
+
+- 会话固定仍可通过行内 `★` 点击完成。
+- 后台会话的**派发与回复**、`Space` 预览面板、`Shift+Enter` 派发并切换，目前**没有**回到新界面。
+- `/bg` 之后要进入某个后台会话，请在工作区列表里 `Enter` 它。
+
+Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的会话 ID。
+
+### Rewind
+
+输入框为空时连续按两次 `Esc` 打开用户消息列表。选择并确认后：
+
+1. 找到该消息所属 turn 的开始事件。
+2. 通过 DSH session fork 创建分支会话。
+3. 回放该边界前的历史。
+4. 把原消息放回输入框供修改和重发。
+
+- 边界取该消息所属回合**开始之前**；**不能回退到第一条消息**。
+- 若模型正在工作：先取消回合并等落定（最长 30s）。
+- 回退后的分支不算子 agent（只写 `parentSession`，无 origin 标记）。
+- 继续用当前模型路由 + 会话自己的 preset。
+
+插件可介入这一步（`tui/rewind-prompt` 决策事件）：
+
+- 否决此次回退（给出原因）。
+- 或在确认页提供额外的回退模式，例如"回退会话 + 恢复此间修改的文件"。
+- 确认页第一项恒为"仅回退会话"。
+- 选择插件模式后，回退完成时插件收到 `tui/rewind-done` 通知。
+- 通知带所选模式 id 与新旧会话 id，插件可回执一条摘要。
+
+鼠标：
+
+- 列表页点击行只选中；进入确认必须键盘 `Enter`。
+- 确认页的消息行 / 模式行点击 = 直接执行该回退。
+
+### 侧问 /btw
+
+`/btw <问题>` 发起一次不打扰主任务的快速侧问。
+
+- 复用当前会话上下文（system prompt + 已有历史）。
+- 做一次**无工具、单轮**的模型调用，答案显示在可滚动的浮层面板里。
+- **不进会话历史**：问答不写入 session log，也不会出现在主上下文与 token 计数里（关闭面板即消失）。
+- **不打断主回合**：模型正在流式输出时也可以触发，主任务继续运行。
+- 面板内 `↑`/`↓` 滚动，`Space`/`Enter`/`Esc` 关闭，`c` 复制答案；等待答案时 `Esc` 取消。
+- 再次触发 `/btw` 会中止上一个侧问。
+
+### 轨迹场景（/trace / Ctrl+T）
+
+整屏场景（不污染 scrollback），查看会话全程的时间线：
+
+| 按键 | 作用 |
+| --- | --- |
+| `←`/`→`（或 `h`） | 切换 时间线 / 热点 视图 |
+| `↑` `↓` / `PgUp` `PgDn` | 移动、翻页 |
+| `[` / `]` | 跳上 / 下一个失败点 |
+| `{` / `}` | 跳上一轮 / 下一轮 |
+| `/` | 查询行：`tool:` `kind:` `turn:` `err:` `run:` `>10s` `tok>1k` 前缀，多条 AND，命中列原位高亮 |
+| `m` | 循环投影模式（等分 / 墙钟 / 压缩空闲） |
+| `g` / `G` | 跳到顶部 / 底部 |
+| `Enter` | 展开详情；`j`/`k` 在详情内翻页 |
+| `t`（热点视图） | 循环排序（耗时 / 次数 / token） |
+| `q` / `Esc` | 退出；Esc 三层：收详情 → 清查询 → 关闭 |
+
+以上全部有鼠标等价（inline 模式的整屏场景同样启用鼠标跟踪）：
+
+- 时间线/热点行点击跳光标。
+- 页签与右上标签点击切换/循环。
+- 查询行与页签空白区点击打开 `/` 搜索。
+- 波形带（含标尺）点击列跳最近事件。
+- 滚轮移动光标。
+
+### /settings 设置编辑器
+
+`/settings` 打开插件设置编辑器，按命名空间读取/编辑。
+
+**改动自动保存**：
+
+- `↑`/`↓` 移动、`Enter` 展开/切换/编辑。
+- 布尔/选项即时写入，文本草稿回车确认。
+- `Esc` 直接退出。
+
+鼠标：
+
+- 字段/组行点击 = 设焦点并执行该行 `Enter` 动作。
+- 悬停即移动焦点，滚轮走焦点（焦点跟随窗口下即滚动）。
+
+命名空间写入：
+
+- dsh-tui 自身命名空间的字段写入当前 profile 配置（旧版为 settings.yaml 用户层）并**实时生效**（`lang`、`statusBar.*` 等）。
+- 未声明 TUI 区块的命名空间以只读形式列出。
+- 需手工编辑 profile 配置（旧版为 `~/.dsh/settings.yaml`）。
+
+### Model 与 preset
+
+`/model` 通过在当前历史末尾 fork 会话来切换模型，因为 DSH 没有原位换模型 API。
+
+- 旧会话仍保留在 `/resume` 中。
+- 还没有人说过话的会话不记分支：此时换模型得到的是一个不写 `parentSession` 的独立会话（继承同一份会话脚手架前缀），这样你随后打的第一个真实 prompt 仍能触发自动生成会话标题；已经对话过的会话照旧记血缘。
+
+`/preset` 只允许空白会话原地切换。
+
+- 已经开始的会话会把选择保存为下一次 `/new` 或启动时的默认值。
+- 详细规则见[配置参考](configuration.md#agent-preset)。
+
+### 工作区
+
+`/workspace` 子命令：
+
+- `/workspace resume` 打开工作区选择器。
+- `/workspace rename <名称>` 重命名当前工作区。
+- `/workspace open <目标>` 直接打开工作区并创建一个全新会话。
+
+`/resume` 和 `/rename` 仍分别用于：
+
+- 当前工作区内的会话切换。
+- 当前会话重命名。
+
+本地目标：
+
+- 可以是绝对路径、相对当前本地工作区的路径，或标准 `file://` URI。
+- 其他 URI scheme 和 `/workspace` 子命令可由可选插件注册。
+- TUI 本身不认识任何具体外部协议。
+- 当前工作区属于插件时，相对路径也由该插件在自己的路径空间内解析。
+
+输入 `/workspace ` 后：
+
+- 列出内建及插件注册的子命令。
+- 继续输入前缀并按 `Tab` 即可补全，例如 `/workspace rem`。
+- 插件别名同样参与匹配。
+
+启动器同样接受工作区目标，例如：
+
+- `dsh-tui .`
+- `dsh-tui ../project`
+- `dsh-tui file:///path/to/project`
+
+未安装任何工作区插件时：
+
+- 本地路径、`!command` 和全部普通 TUI 会话流程保持可用。
+
+## Fullscreen 与鼠标
+
+`fullscreen: false` 恢复 inline 模式（0.9.0 起出厂默认为 fullscreen）。
+
+- 此时终端模拟器拥有原生 scrollback 和选区。
+
+`fullscreen: true` 使用 alternate screen，并启用应用内鼠标处理：
+
+- **滚轮**：按位置路由。
+  - 补全/命令菜单悬停处，移动菜单选中行。
+  - 最上层滚动容器（转录 / 帮助 / 子代理面板）滚它。
+  - 其余位置滚动会话消息列表。
+  - 浮层打开时不穿透滚动背后转录。
+  - 轨迹场景移动光标（时间线一格 ±3 行、热点 ±1 行、详情展开时滚详情）。
+  - 设置屏移动焦点行。
+- **拖拽**：选择文本，松开后立即复制并清除选区，弹出「已复制 N 字符」提示。
+  - `dsh-tui.scrollGutter: scrollbar` 时，右缘滚动条是拖拽目标。
+  - 未修饰左键按住拖动，按轨道位置连续滚动（与点击轨道同一映射：拖到哪滚到哪）。
+  - `Shift`/`Alt`/`Ctrl`+拖动仍是选字（拖拽协议只对无修饰左键开启）。
+- **双击/三击**：选择单词/整行并复制。
+  - `scrollGutter: scrollbar` 的轨道例外：轨道是拖拽目标，其上多击不再选行。
+- **`Esc`**：取消正在进行的拖拽（或现有选区），不复制。
+- **单击消息行**：纯文本行（用户/assistant）无操作——转录是阅读区，鼠标职责是选字。
+- **单击工具卡 / thinking / compact 摘要**：展开 / 收起（hover 时标题提亮指示，行右侧空白不触发）。
+- **单击子代理卡**：打开该子代理的详情场景（hover 时状态符号提亮）。
+- **单击输入框**：定位文本光标到点击处（多行/换行/CJK 均按显示宽度对齐）。
+- **单击输入框中的 `[Image #N]` / transcript 缩略图**：打开居中大图预览（Kitty/Sixel 不可用时显示图片元数据）。
+- 预览打开时点击预览外部关闭。
+- **输入框内拖拽**：建立输入框选区并高亮渲染（caret 跟随拖拽末端）。
+  - `Backspace`/`Delete` 删选区、打字替换选区、`←/→` 坍缩到对应边缘、`Esc` 仅清选区。
+  - 拖拽只映射可见行（暂不做边缘自动滚动）。
+  - 折叠块存在时选区钳制在 head 或 tail 一侧、不跨 chip 行。
+- **输入框 Shift+click**：从选区头（无选区时为光标）扩展到点击处。
+- **输入框双击**：选词（组件内自检测，500ms / 1 格；路径与标点连串整选）。
+- **输入框 `Ctrl+C`（有选区）**：复制选区到剪贴板（OSC 52 + 原生工具兜底）并保留选区继续编辑。
+- **全屏编辑器**（`Ctrl+Shift+E` 展开）：
+  - 点击定位/拖选/双击选词与输入框同路径（坐标按行号槽校正）。
+  - 滚轮滚编辑窗口（位置路由，光标移动后恢复跟随）。
+  - 「发送」「收起」按钮点击执行、hover 提亮。
+  - 输入行尾 `⛶` 点击展开。
+- **单击「加载更早消息」/「ctrl+e 显示前 N 条」**：加载更早消息 / 展开全部。
+- **单击 StickyHeader / 「↓ N new messages」**：跳回固定消息处 / 滚动到底部。
+- **单击超链接**：打开浏览器。
+- **单击 picker / 菜单条目行**：选中并立即应用，与键盘 `Enter` 同路径。
+  - 覆盖：模型 / 技能 / 活动帧 / 预设 / 权限 / plan / 语言 / 主题 / effort 档位 / 命令与文件补全 /
+    历史命令 / 会话行 / thinking 显示模式 / 工作区目标与子菜单 / 工作区命令分支。
+  - busy 或输入态中的浮层行禁点。
+- **单击 rewind 候选行 / 确认页**：
+  - 列表页点击只选中（确认保留键盘 `Enter`——高危操作显式触发）。
+  - 确认页消息行 / 模式行点击 = 直接执行（确认页本身即显式确认层）。
+- **单击审批 / 问卷 / 计划评审 / 插件对话框决定行**：直接提交该决定（agent 阻塞等待时可鼠标放行）。
+- **单击轨迹场景**：
+  - 时间线/热点行点击 = 光标跳该行（热点行跳回时间线定位该组，同 `Enter`；hover 亮 dim ▸ 轻指示不刷背景）。
+  - 页签点击切视图；右上排序/投影标签点击循环。
+  - 查询行与页签空白区点击打开 `/` 搜索。
+  - 波形带（含标尺行）点击列 = 跳最近事件。
+- **单击 /settings 字段 / 组行**：设焦点并执行该行的 `Enter` 动作（boolean/select 循环值、文本进编辑态、组进组页）。
+- 悬停即移动焦点（lazygit 规则），编辑态整屏不响应防误触。
+- **单击会话浏览器确认行**：删除/清理确认行点击 = 确认执行（同 `Enter`）；取消保留键盘 `Esc`。
+- **单击帮助菜单命令行**：填入 `/name ` 并关闭帮助（`Tab` 补全的鼠标等价）。
+- **点击时间轴刻度**：跳到该回合——轨道覆盖全部回合（含折叠的）；折叠刻度先展开该回合再滚到位。
+- **键盘扩展选区**：有选区时 `Shift+←/→/↑/↓/Home/End` 扩展 / 收缩（跨行环绕）。
+
+以上鼠标行为只在 `fullscreen: true` 的 alternate screen 生效。
+
+- inline 模式不开启鼠标上报。
+- 滚动条拖动不适用（沿用终端原生 scrollback 与选区）。
+
+复制优先使用 OSC 52。
+
+- 本地终端可回退到 `wl-copy`、`xclip` 或 `xsel`。
+- tmux 使用 `load-buffer -w`。
+- 设置 `DSH_TUI_DISABLE_MOUSE=1` 可临时关闭 fullscreen 鼠标。
+
+## `ask_user_question` 问卷
+
+模型调用问卷工具时，问卷面板暂时拥有键盘：
+
+| 按键 | 行为 |
+| --- | --- |
+| `Up/Down` | 移动选项 |
+| `Space` | 多选题勾选或取消 |
+| `Tab` | 切换到自定义文本回答 |
+| `Enter` | 提交当前题 |
+| `Left` / `Right` | 在题目之间切换并保留当前草稿（不提交）。自由输入行里方向键仍移动光标，只有光标已在行首/行尾时才换题 |
+| `Esc`（第 2 题起） | 返回上一题并保留当前草稿 |
+| `Esc`（第 1 题） | 取消整批提问，模型收到 `ASK_CANCELLED` |
+| `Ctrl+C` | 从任意题取消整批提问，模型收到 `ASK_CANCELLED`（harness 侧中止仍报 `ASK_ABORTED`） |
+| `Ctrl+K` | 折叠/展开 ask_user_question 问卷面板 |
+
+**最后一行是自由输入行**：
+
+- 直接在选项行打字 = 附加该选项标签 + 自定义文本一起提交（不必先 `Tab`）。
+- `Tab` 直达输入行。
+
+- 一批多题以及并发子代理提问按 FIFO 逐题显示。
+- 完成后，问答摘要折叠进本地 transcript。
+
+## 计划评审（plan review）
+
+计划模式下模型调用 `exit_plan_mode` 时，计划全文以 markdown 渲染在评审面板中
+（`intent: plan-review` 的专用决策布局）：
+
+| 按键 | 行为 |
+| --- | --- |
+| `Up/Down` | 在选项与底部反馈输入行之间移动 |
+| 鼠标滚轮 | 滚动计划正文；批准 / 继续规划 / 反馈行保持钉在视口内 |
+| `1`/`2` | 直接提交对应选项（反馈缓冲为空时；非空则数字视为反馈字符） |
+| 打字 | 进入反馈输入行 |
+| `Enter`（选项行） | 提交该选项；批准行有反馈时会报错——批准必须不带反馈，否则协议视为"继续规划" |
+| `Enter`（输入行） | 提交"继续规划"并附上反馈文本 |
+| `Esc` | 打断评审去说话（`ASK_CANCELLED`），模型停留在计划模式 |
+
+批准计划或执行 `/plan off` 后：
+
+- 会话恢复进入计划前的实际沙箱与审批策略。
+- `Shift+Tab` 切走则保留用户选择的目标模式，包括运行中延迟生效的切换。
+
+恢复已有会话时：
+
+- 从事件历史还原进入前权限。
+- 历史不足以确定的权限保持不变。
+- 不会因无法匹配配置模式而自动回落到 full access。
+
+## 工具审批（approval）
+
+权限层发起 `approval/request` 时，审批面板暂时拥有键盘（同时挂起问卷时审批优先）。
+
+- 显示工具名、从配对 tool call 提取的完整命令与原因。
+
+| 按键 | 行为 |
+| --- | --- |
+| `Up/Down` | 移动选项 |
+| `1` / `2` | 允许（仅本次）/ 拒绝 |
+| `Enter` | 提交当前焦点项 |
+| `Esc` / `Ctrl+C` | 拒绝（fail closed） |
+
+协议只有「允许一次 / 拒绝」两种结果，**没有「总是允许」**。
+
+## Slash Commands
+
+命令菜单由本地命令与 DSH 命令注册表合并而成。
+
+- 输入 `/` 查看当前组合真正可用的全集。
+- 命令描述随界面语言（`/lang`）中英切换。
+- 内置命令与已收录的注册表命令（`/plan`、`/goal`、`/feedback`）显示中文翻译。
+- 其余注册表命令回退注册表原文。
+
+**会话**
+
+- `/new`。
+- `/resume`、`/home`、`/agentview`：三者打开同一个会话管理界面。
+- `/bg`（别名 `/background`）：会话转入后台并打开该界面。
+- `/rename`。
+- `/recap`：最近活动摘要 + 建议标题一键应用。
+- 设置 `recapOnOpen` 开启时打开会话自动出分隔线 + `回顾：` 摘要行，发送新消息后消失，默认开。
+- `/workspace resume|rename|open`。
+- `/clear`、`/compact`、`/export`、`/btw`。
+- `/trace`：轨迹场景，亦可 `Ctrl+T`。
+- `/rewind`：时间回溯，同空输入双击 `Esc`。
+
+**状态**
+
+- `/context`、`/status`、`/cost`。
+- `/balance`：DeepSeek 官方余额，摘要行 + hover 明细，点击刷新。
+- `/config`、`/doctor`、`/init`、`/agents`。
+- `/jobs`：后台任务面板，状态/时长/退出码，`k` 停止；分栏开启且宽度足够时改为打开右栏面板，窄屏 / inline 回退整屏。
+- `/settings`。
+
+**模型与显示**
+
+- `/model`、`/effort`、`/thinking`、`/tokens`、`/activity`、`/preset`、`/theme`。
+- `/color`：会话强调色。
+  - 无参打开调色板选择器，`<名>` 直接设置，`status`/`reset`。
+  - 输入框边框 + 右上角会话名标签，按会话保存。
+  - 标签默认关闭，`/settings` 可开。
+- `/panel`：侧栏面板——开关 / 聚焦 / 缩放 / 切换（子命令见用户指南 §2.8）。
+- `/lang`。
+
+**账号与策略**
+
+- `/provider`、`/login`、`/logout`、`/permission`、`/add-dir`、`/hooks`、`/mcp`。
+- `/auth login deepseek-account` 或 `/provider` 完成 DeepSeek 登录后，若 Platform 返回尚未展示的登录赠金，鲸鱼女仆娘弹窗会显示“鲸鱼券”的金额与到期时间；按 Enter/Esc 关闭。
+- `/plugins`：`check <路径>` 校验插件清单。
+
+**Skills**
+
+- `/skills` 浏览 DSH 从当前 profile、用户与项目发现的技能。
+- 可直调技能以 `/name` 加入菜单。
+
+**其他**
+
+- `/update`、`/vim`（vim 编辑模式开关，见「输入编辑」）、`/terminal-setup`、`/connect`、`/help`。
+- `/exit`（别名 `/quit`、`/q`）。
+
+**注册表**
+
+- `/plan`、`/goal`，以及当前 DSH 组合注册的其他命令。
+
+dsh-TUI 不预装通用技能；技能内容与发现规则由 DSH 及当前组合负责。
+
+补充语法：
+
+- `/activity` 打开动画选择器；`/activity frames <name>` 直接设置（当前可选
+  `random`、`star2`、`sand`、`triangle`、`box`、`box2`、`corners`、`point`、
+  `layer`、`flip`、`aesthetic`、`hamburger`、`moon`、`moon8`、`whale-spout`、
+  `whale-spin`、`whale-bubbles`、`clock`、`traffic_lights`、`comet`、`breathe`、
+  `dots`、`arrow`、`spark`、`bar`、`braille`、`arc`、`circle`、`grow`、`noise`、
+  `bounce`、`rainbow`、`bar2`、`dqpb`、`toggle`，默认 `moon8`）。旧本地配置值
+  `claude` 读取时映射为 `moon8`，选择器不显示该旧预设；
+  `/activity status` 查看当前选择。
+- `/preset <id>` 与 `/preset status` 见配置文档。
+- `/effort` 打开推理强度滑杆（←/→ 实时调整）；`/effort <id>` 直接设定，
+  `/effort status` 查看当前档位。
+- `/theme <name>` 与 `/theme status` 见主题文档。
+- `/permission` 的名册来自 DSH `permissionPresets` registry。
+  - 按声明顺序显示，参与补全与 `Shift+Tab` 循环。
+  - 第三方预设无需 TUI 硬编码。
+  - 服务可用时以本地命令常驻菜单：裸命令打开 picker、参数直接切换、`status` 打印当前预设与策略说明。
+  - 切换优先调用官方 `/permission <preset>` 命令。
+  - 命令未暴露给本 agent 时，回退到服务自身的官方写路径（同一 handler、真实事件），并以事件/读回确认。
+  - 两者都不可用时显式报错，不会把输入当普通消息发给模型。
+  - registry 服务缺失时 TUI 使用三项 legacy 兼容名册。
+  - 服务已挂载但损坏、为空或不一致时标记 unavailable 并 fail closed。
+  - 退出计划模式先恢复进入前的 sandbox/approval，再还原进入前所在的权限预设（registry 仍提供时）。
+- `/lang` 切换中英界面语言（见「界面语言」）。
+- `/compact` 压缩会话历史；内核「极简模式」预设（Agent preset `minimal`，只有一个持久 shell 工具）既不挂载压缩服务也不剪枝工具结果，长会话可能撞上下文上限、超长工具输出整段留在上下文里，`/compact` 因此不可用（Help 与 `/` 补全标注「不可用」，进入该预设时提示一次）——与界面设置的「极简界面」无关。
+- `/thinking` 扩展思考显示开关，仅本次界面状态、**不持久化**。
+- 启动后后台检查 npm 新版本，发现更新时提示。
+  - 检测遵循 npm registry 配置（`NPM_CONFIG_REGISTRY` 或 `~/.npmrc`）。
+  - 镜像源用户看到的就是安装源的最新版。
+  - `/update` 更新已安装的 `@deepseek-harness-tui/dsh-tui`。
+  - 更新后自动重启并恢复当前会话；当前回合运行时需等待完成。
+  - 仅在 `dsh --profile <name>` 启动时可用（源码运行等场景提示不可用）。
+  - 已是最新版时直接提示，不会重启。
+- `/plan [off|message]` 与 `/goal ...` 由 DSH 命令插件处理并写入会话事件。
+- Skill 命令由 host 注入对应 `SKILL.md` 的技能正文后执行，参数原样随行；
+  技能内容与发现规则由 DSH 及当前组合负责。
+
+`/connect`、`/hooks` 当前是兼容占位命令。
+
+- 当 DSH 组合没有对应能力时，会给出明确说明，而不是静默执行。
+
+## 外部注入通道（编辑器集成）
+
+运行中的会话会开一个**本会话独占的本地注入通道**，供编辑器插件（如 `dsh.nvim`）把上下文推进输入框。
+
+- 它是 OpenCode `POST /tui/publish` 的对应物。
+- 但走本地 socket 而非 HTTP 端口：无端口分配、无鉴权面。
+- 端点随会话退出自动清理。
+
+- **传输**：Unix domain socket `~/.dsh-tui/inject/<sessionId>.sock`
+  （Windows 为命名管道 `\\.\pipe\dsh-tui-inject-<sessionId>`）。
+- **发现**：`~/.dsh-tui/inject/servers.json` 列出每个存活会话
+  （`pid`、`sessionId`、`cwd`、`socketPath`），客户端据此按 `cwd` 匹配项目并
+  选择目标会话；会话退出时该记录被移除。
+- **协议**：换行分隔的 JSON，每行一条：
+  `{"type":"prompt.append","text":"@src/foo.ts "}` 把文本追加到输入框；
+  `{"type":"command.execute","command":"prompt.submit"}` 提交当前输入。追加文本以
+  空格结尾（OpenCode 惯例）时保持不提交，便于继续编辑。
+- **接线**：追加复用输入框的 `PromptController.append`，提交走
+  `channel.submit`（工作态下自动进 inbox，回合结束后处理）。实现见
+  `src/dsh-adapter/inject-channel.ts`，回归门禁 `scripts/verify-inject-channel.mjs`。