@deepseek-harness-tui/dsh-tui 0.12.0 → 0.14.0

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

@@ -6,7 +6,7 @@
 
 | 按键 | 行为 |
 | --- | --- |
-| `Enter` | 空闲时发送；模型工作时把文本 steer 到当前回合的下一步边界；菜单打开时确认选项 |
+| `Enter` | 空闲时发送；输入构成已知 `/` 命令时执行该命令（可带参数，回合运行中由该命令自己的门禁裁决）；模型工作时把其余文本 steer 到当前回合的下一步边界；菜单打开时确认选项 |
 | `Tab` | 补全 `/` 命令或 `@` 文件；模型工作且输入非空时排入当前回合之后的 follow-up |
 | `Ctrl+Enter` | 打断当前回合并立即处理输入消息 |
 | `Shift+Enter` / `Ctrl+J` | 在光标处插入换行；终端无法上报 Shift 修饰键时可用 `Ctrl+J`（LF）兜底，macOS Terminal.app 用 `Option+Enter` |
@@ -16,13 +16,17 @@
 | `Ctrl+V` / `Alt+V` | 从系统剪贴板插入文本或文件；图片作为持久附件发送。终端拦截 `Ctrl+V` 时用 `Alt+V` |
 | `Ctrl+G` | 用外部编辑器（`$VISUAL` → `$EDITOR`）编辑当前输入，保存退出后回填；`:cq` 或非零退出保留原稿；未设置变量时提示配置，无 `vi` 兜底 |
 | `Ctrl+Shift+E` | 展开全屏草稿编辑器（也可点输入行尾 `⛶`）：行号 + 当前行高亮 + 行/字统计，`Enter` 换行、`Ctrl+Enter` 或「发送」按钮发送、`Esc` 或「收起」按钮收起（草稿保留）；滚轮自由滚动、点击定位/拖选/双击选词与输入框一致；可经 `/settings` 重映射 |
-| `Esc` | 层级：关帮助 → 关图片预览 → 关命令菜单 → 关文件菜单（仅当前 `@` token）→ **输入框内有选区时仅清选区（文本不动）** → 中断回合并重投 pending 消息 → 有输入时清空 → 空输入连续两次 = 时间回溯 rewind；fullscreen 下有鼠标选区时优先取消选区（不复制） |
+| `Ctrl+Z` | 撤销输入框草稿的上一步「词级」编辑（文本、光标、图片一起回退）。只作用于草稿：提交、历史召回（`Ctrl+R`/`↑`）或换会话后即结束；`Esc Esc` 的会话/消息回溯与它不是一回事。可经 `/settings` 重映射 |
+| `Esc` | 层级：关帮助 → 关图片预览 → 关命令菜单 → 关文件菜单（仅当前 `@` token）→ **输入框内有选区时仅清选区（文本不动）** → 排队选择器开着时仅退出选择器 → 中断回合并暂存排队消息（不自动重发，见「消息投递语义」）→ 有输入时清空 → 空输入连续两次 = 时间回溯 rewind；fullscreen 下有鼠标选区时优先取消选区（不复制） |
 | 图片预览打开时 `Esc` / `Ctrl+C` / `Enter` | 关闭预览，恢复下层界面；其余按键不透传 |
 | 图片弹窗中的 `←` / `→` | 上一张 / 下一张；首尾不循环，临时光标预览不抢输入框方向键 |
+| `←`（输入框为空） | 打开会话管理界面；DSH 内核会先把当前会话转入后台，Claude/Codex 内核保持当前会话运行 |
 | `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` | 强制清理并重绘物理终端 |
@@ -33,7 +37,7 @@
 
 动作型快捷键支持在 `/settings` → `dsh-tui` → `Shortcuts` 自定义。
 
-- 覆盖：粘贴、历史搜索、外部编辑器、`Ctrl+O/T/P/R/L`、子代理面板、显示全部、待办折叠。
+- 覆盖：粘贴、历史搜索、外部编辑器、`Ctrl+O/T/P/R/L`、侧栏（`Ctrl+B`、`Alt+Z`）、子代理面板、显示全部、待办折叠。
 - 填 `alt+v` 这类组合，多个用逗号分隔；留空恢复默认，保存即生效。
 - 与固定编辑键或其它动作冲突的组合会被拒绝。
 - cordis.yml 可用 `shortcuts.<action>` 静态指定。
@@ -65,6 +69,56 @@
 - 富状态注册被拒绝时返回 `undefined`。
 - 注册成功时返回 disposer，会同时撤下视图和对应 Cordis effect。
 
+### 落地页与首次引导
+
+启动**落地页**与**首次引导向导**各自独占键盘；两者都只把结果交回对话页，不新增行为。
+
+- **落地页**：可打印字符接进输入框（行首 `/` 时前缀由 `❯` 变 `⌘`），`Backspace`/`Delete`/`←`/`→`/`Home`/`End` 编辑；
+- **落地页**：可打印字符接进输入框（行首 `/` 时前缀由 `❯` 变 `⌘`），`Backspace`/`Delete`/`←`/`→`/`Home`/`End` 编辑；
+  输入光标是**压在当前字符身上的反显块**（对那一个字符 inverse，行尾是反显空格；主题声明了 `cursor`
+  键时改用该填充色的实色块配对比字形，见[主题系统](themes.md)），闪烁是纯样式切换
+  （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` 关掉它回到落地页），选中的值就地更新参数行、已输入的草稿不动；选择器开着时点它内部是选择，
+  **点别处会关掉它、点另一段会直接切换**成那个选择器。四段**常在**：这一行装得下就原样画；
+  装不下时只把**超长的段**按显示宽度截尾成 `前缀…`（权限段**不被截断**），悬停被截断的段约 600ms
+  弹出卡片显示**完整名**（落地页这一屏恒启用鼠标跟踪，inline 模式下也是）；其余各段压到下限后
+  **完整权限名放不进预算**时（终端 ≥76 列后，再宽也不改变结果；更窄的终端或更长的权限名都会更早触发）
+  才回落到按显示顺序**从尾部整段省掉**（权限 → 模式 → 思考深度 → 模型），省掉的段同时退出焦点环。
+- **入口行**：`继续「…」`（Alt+R；无可继续会话时整格不画）· `会话与工作区`（`/home`，
+  历史会话与工作区合并成一个入口）· `设置`（`/settings`）· `内核 · <当前内核>`（`/kernel`，打开内核选择器，见「命令」一节）· **条件位**（优先级：有后台任务在跑 →
+  `后台任务`；检测到新版本 → `有新版本`；用量到档且从未 star → `投喂一颗 Star`；兜底 `帮助`）。
+  从落地页打开的整屏界面（会话与工作区 / 设置 / 后台任务 / 家谱 / 引导向导）都**盖在落地页之上**，
+  `Esc` 退出回到落地页（草稿/参数/焦点原样保留）；**离开落地页进对话页的唯一方式是回车提交一条
+  非命令消息**。落地页这一侧的浮层（选择器/命令面板）是**干净的镂空**——矩形内空格占位
+  遮掉宿主屏的字形（绝不重影）、不发背景色（无白底；Kitty 立绘图像仍从终端默认背景透出；
+  聊天页同款选择器不受影响）。
+- **Tips 行**：可点击轮换（三条 Tips 循环；首启那一句优先级最高、不参与轮换），键盘路径 = 焦点环 + `Enter`；
+  还会**自动轮换**（约 10s 一换，手动切换后计时重置），切换只改文本、行高与居中位置不变。
+- **双角铭牌**：左下角工作目录**可点**——点开既有的 `/workspace` 菜单
+  （盖在落地页之上、`Esc` 回落地页），键盘路径 = 焦点环末格 + `Enter`，悬停/焦点 =
+  文字高亮；右下角第一行是 `dsh-tui v<TUI>`，其下两个内核各占一行：
+  `▸ DSH · dsh-core v<内核>` / `Claude · claude-code v<CLI>`。`▸` 标出当前内核，其余行暗色；
+  不可用的内核在版本后写原因（如「未安装」「未登录」），读不到版本时只写名字，检测期间显示
+  「检测中…」。整块可点，打开同一个内核选择器（键盘路径 = 焦点环 + `Enter`）。
+  各行右对齐，左下目录铭牌与第一行顶对齐，窄屏按既有 truncate-middle 截断。
+- **引导向导**：`←`/`→` 换步骤（例外：第三步的强度区、以及已钻进去的模型列表，横向键归子控件，不换步骤）、
+  `Tab` 在「语言 / 主题」与「模型 / 强度 / 工作区」两组面板间切、`↑`/`↓` 移动选择；
+  `Enter` 执行这一步（第一步 = 重新检查连通性，第三步 = 钻进 provider / 换模型 / 打开工作区选择器——**强度不走 Enter**，只用 `←`/`→` 调且移动即生效）；
+  主题面板移动光标即预览，**语言面板要 `Enter` 才生效**；最后一步的 `Enter` 在**键位卡**上「完成」并记账，
+  在命令卡上则是「试一下」；`Esc` 跳过（**不记账**，下次启动再问）。
+- **鼠标**（落地页这一屏恒启用鼠标跟踪）：落地页的快捷入口（悬停 = 文字变主题蓝加粗，移开复原）、
+  参数行四段、命令补全面板、Tips 行、引导招式卡的「试一下」与工作区选择器都可点，
+  点击与键盘落到同一条命令路径。
+
 ## 输入编辑
 
 | 按键 | 行为 |
@@ -112,7 +166,8 @@ Bracketed paste（右键或终端原生粘贴）保留普通文本与换行。
 
 - 不会把粘贴内容误当成 `Enter` 提交。
 - 为保显示、点击与选区几何一致，剥离终端 ANSI 控制序列。
-- 多行粘贴不再留下 `_`：Windows 终端以 win32-input-mode 逐条记录投递时，残留的键记录（`ESC[Vk;Sc;Uc;Kd;Cs;Rc_` 完整形态，或记录拆散后无 ESC 的尾部）在入口整体剥离；只匹配 5 段分号的记录语法，普通文本里的真实 `_` 与形似记录的方括号文本不受影响。
+- 多行粘贴不再留下 `_`，也不再丢字符：Windows 终端以 win32-input-mode 逐条记录投递时，泄漏进载荷的键记录（`ESC[Vk;Sc;Uc;Kd;Cs;Rc_` 完整形态，或记录拆散后无 ESC 的尾部）按 `Uc` 字段**还原成它编码的字符**（含换行，走同一条 CR+LF 折叠规则），所以 chip 报出的行数等于粘贴内容的真实行数。**还原要有证据**：只有构成**成对转移**（同一 `Uc` 的按下+抬起）的记录才还原成字符；**单条**记录（拿不到成对证据、无法与载荷里的字面文本区分）仍按协议记号整体剥离，它的 `Uc` **不还原**；没有字符语义的记录（`Uc=0` 的合成记录、无文本的按键记录）同样整体剥离。本屏的承诺因此是「**在能证明这些字节是记录流时**不静默删除字符」，而不是"任何记录形状都还原成字符"。
+- 剥离与还原都要证据：完整记录先于尾部剥离（不会把一条记录从中间切开、留下孤立 ESC 再连带吃掉紧随的一个载荷字符）；无 ESC 的尾部必须自成记号，焊在载荷自身词内的记录形态逐字节保留（宁可见残留）。只匹配 5 段分号的记录语法，普通文本里的真实 `_` 与形似记录的方括号文本不受影响。
 - CRLF 折叠：粘贴内容里的 CR+LF 只产生一个换行，不再多出空行；LF-only 与单独 CR 行为不变。
 - `Tab` 进入编辑缓冲区时展开为空格。
 
@@ -239,14 +294,26 @@ Bracketed paste（右键或终端原生粘贴）保留普通文本与换行。
 
 | 操作 | 放置位置 |
 | --- | --- |
-| `Enter` | steer：送入正在运行的回合，在下一步边界被 Agent 领取 |
+| `Enter` | 输入构成已知 `/` 命令（可带参数）→ 按命令执行，由该命令自己的门禁裁决；其余文本 → steer：送入正在运行的回合，在下一步边界被 Agent 领取 |
 | `Tab` | follow-up：等待当前回合结束后再处理 |
 | `Ctrl+Enter` | interrupt：中断当前回合并立即投递 |
 
+**回合运行中，命令永远是命令；只有两类输入才 steer：不构成命令的普通文本，以及直接调用技能的手势（`/技能名 …`）。** 补全浮窗据此把命令按对当前对话的影响分区：不影响的在上（原样式），会被门禁拦下 / 会打断或替换对话 / 会 steer 的沉到下方、整行变灰（`subtle`，不插标题行），灰区命令仍可选中执行。
+
 输入框上方会显示尚未领取的消息。
 
 - `Alt/Option+Up` 取回最后一条。
-- 模型工作时按 `Esc` 会中断，并立即重投当前 pending 消息。
+- 模型工作时按 `Esc` 会中断回合，排队消息暂存在输入框上方，不自动重发；提示行显示
+  `按 ↑ 编辑排队消息，⏎ 立即发送`。DSH 与 Claude 后端行为相同。
+  - 有暂存消息且空闲时，在空输入框按 `↑` 打开排队消息选择器：`↑`/`↓` 移动，`⏎` 把选中的消息
+    取回输入框编辑，`Esc` 退出选择器。也可以直接点暂存的消息（取回编辑；输入框里已有草稿
+    时两者互换，`Ctrl+Z` 换回）或点提示行（全部发送）。
+  - 空输入框按 `⏎` 按顺序发送全部暂存消息，只发一次；输入框有草稿时 `⏎` 只发送草稿，暂存的
+    消息继续暂存，不会和草稿合并发出。
+  - `Ctrl+Enter`（有草稿时）中断当前回合，连同暂存消息一起立即发送。
+  - 回合正常结束时，排队消息照常进入下一回合；`Ctrl+C` 中断时保留队列。
+  - 只有后端确认已撤回的消息才会暂存。旧版 Claude CLI 不支持撤回，或撤回请求失败时，这些
+    消息仍由后端在下一回合执行，dsh-TUI 不再暂存它们并给出提示，不会重复发送。
 
 ## 会话工作流
 
@@ -447,6 +514,60 @@ Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的
 - 已经开始的会话会把选择保存为下一次 `/new` 或启动时的默认值。
 - 详细规则见[配置参考](configuration.md#agent-preset)。
 
+### 渠道档案（/channel，仅 Claude）
+
+中转渠道常把请求路由到别的模型，却沿用 Claude 的档位名（例如 Opus 5.5 (1M)）。渠道档案
+记录每个渠道的模型映射和连接方式，存在 `~/.dsh-tui/backends/claude/channels.json`：
+
+```json
+{
+  "active": "zhipu",
+  "channels": [
+    {
+      "id": "zhipu",
+      "name": "智谱",
+      "baseUrl": "https://open.bigmodel.cn/api/anthropic",
+      "tokenRef": "CHANNEL_ZHIPU_TOKEN",
+      "models": { "claude-opus-5-5[1m]": "glm-5.3[1M]" },
+      "tiers": { "opus": "glm-5.3[1M]", "haiku": "glm-5.3-flash" }
+    }
+  ]
+}
+```
+
+- `models` 是精确映射：先精确匹配，再去掉 `[1m]` 后缀、忽略大小写匹配。`tiers` 按档位关键字
+  （`haiku`/`opus`/`sonnet`/`fable`）匹配，保留字 `default` 匹配其余所有模型（对应
+  `ANTHROPIC_MODEL`）。两个字段都可省略。
+- `id` 由 `name` 生成（小写，非字母数字折叠成 `-`）；重复导入会更新同 id 的渠道。
+- 显示的模型名按以下顺序取：激活渠道的 `models` > 激活渠道的 `tiers` > 旧的
+  `model-names.json` > Claude 设置 `env` 里的档位变量 > 原始 id。没有激活渠道时与没有这个
+  文件一样。
+- `baseUrl`、`tokenRef` 与渠道私有的 `env` 是连接信息，都可省略。激活的渠道决定本会话连到
+  哪里，并优先于 dsh-auth 订阅登录。令牌存在 `~/.dsh/.credentials.yaml`（0600，与 `/provider`
+  的密钥同一个凭据库，引用名默认 `CHANNEL_<ID>_TOKEN`），`channels.json` 只存引用，不存明文。
+- 连接经两处下发给 CLI：子进程环境，以及 SDK 的 `settings` 选项（CLI 的 `--settings` 层，
+  优先级高于 `~/.claude/settings.json` 的 `env`，所以 cc-switch 之类工具写进设置文件的值
+  不会盖过渠道）。环境里为其他端点签发的 `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN` 不会
+  带到新主机。
+
+`/channel` 打开选择器，依次是：
+
+- 各渠道（当前渠道打勾，副行是映射条数）。`Enter` 切换激活渠道。连接信息相同的渠道之间就地
+  切换，页脚和 `/model` 的模型名立即刷新；连接不同则重启进入新会话（运行中的 CLI 换不了连接）。
+- 「从 settings.json 导入」：用 `ANTHROPIC_BASE_URL` 的主机名作渠道名，把
+  `ANTHROPIC_DEFAULT_{HAIKU,OPUS,SONNET,FABLE}_MODEL` 与 `ANTHROPIC_MODEL` 收进 `tiers`
+  （不猜 `models`），同时收下 `baseUrl` 和 `ANTHROPIC_AUTH_TOKEN`（按上面的规则入凭据库）。
+  重复导入更新同 id 的渠道，手写的 `models` 保留。
+- 「新增渠道」与「管理渠道」：打开与 `/provider` 相同的问答面板。新增依次问名字、baseUrl、
+  令牌（输入不回显）、映射来源（从设置吸收档位或跳过）、是否立即切换；管理可以改 baseUrl、
+  令牌，从设置刷新映射，或删除渠道（连同保存的令牌）。
+- 「查看映射」：把当前渠道的 `models` 和 `tiers` 打印成本地转录块。逐条编辑请直接改
+  `channels.json`，模型名按上面的顺序实时生效。
+
+文件损坏时读作空，写入失败只记调试日志，写入经同目录临时文件 + rename 原子替换。
+dsh-tui 不修改 `~/.claude/settings.json`；会话启动时若其中的 `ANTHROPIC_BASE_URL` 或凭据与
+激活渠道冲突，会提示一次本会话按渠道档案连接。该命令只在 Claude 会话中出现。
+
 ### 工作区
 
 `/workspace` 子命令：
@@ -622,11 +743,15 @@ Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的
 
 协议只有「允许一次 / 拒绝」两种结果，**没有「总是允许」**。
 
+Claude 后端的审批来自 CLI：CLI 给出建议时多一个「始终允许」，焦点在「拒绝」行时还可以输入
+拒绝理由，见[Claude 后端](claude-backend.md#审批与提问)。
+
 ## Slash Commands
 
 命令菜单由本地命令与 DSH 命令注册表合并而成。
 
 - 输入 `/` 查看当前组合真正可用的全集。
+- **回合运行中**，浮窗按「对当前对话的影响」分区：不影响的在上（原样式），会被门禁拦下 / 会打断或替换对话 / 会 steer 的沉到下方、整行变灰（`subtle`，不插标题行），灰区命令仍可选中执行。
 - 命令描述随界面语言（`/lang`）中英切换。
 - 内置命令与已收录的注册表命令（`/plan`、`/goal`、`/feedback`）显示中文翻译。
 - 其余注册表命令回退注册表原文。
@@ -635,7 +760,7 @@ Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的
 
 - `/new`。
 - `/resume`、`/home`、`/agentview`：三者打开同一个会话管理界面。
-- `/bg`（别名 `/background`）：会话转入后台并打开该界面。
+- `/bg`（别名 `/background`）：打开会话管理界面；DSH 内核先将当前会话转入后台，Claude/Codex 内核保持当前会话运行。
 - `/rename`。
 - `/recap`：最近活动摘要 + 建议标题一键应用。
 - 设置 `recapOnOpen` 开启时打开会话自动出分隔线 + `回顾：` 摘要行，发送新消息后消失，默认开。
@@ -649,16 +774,18 @@ Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的
 - `/context`、`/status`、`/cost`。
 - `/balance`：DeepSeek 官方余额，摘要行 + hover 明细，点击刷新。
 - `/config`、`/doctor`、`/init`、`/agents`。
-- `/jobs`：后台任务面板，状态/时长/退出码，`k` 停止。
+- `/jobs`：后台任务面板，状态/时长/退出码，`k` 停止；分栏开启且宽度足够时改为打开右栏面板，窄屏 / inline 回退整屏。
 - `/settings`。
 
 **模型与显示**
 
 - `/model`、`/effort`、`/thinking`、`/tokens`、`/activity`、`/preset`、`/theme`。
+- `/channel`：渠道档案选择器（仅 Claude 后端，见「渠道档案」小节）。
 - `/color`：会话强调色。
   - 无参打开调色板选择器，`<名>` 直接设置，`status`/`reset`。
   - 输入框边框 + 右上角会话名标签，按会话保存。
   - 标签默认关闭，`/settings` 可开。
+- `/panel`：侧栏面板——开关 / 聚焦 / 缩放 / 切换（子命令见用户指南 §2.8）。
 - `/lang`。
 
 **账号与策略**
@@ -675,6 +802,11 @@ Windows `dsh-tui.cmd --resume` 使用 `~/.dsh-tui/resume.txt` 中最后选择的
 **其他**
 
 - `/update`、`/vim`（vim 编辑模式开关，见「输入编辑」）、`/terminal-setup`、`/connect`、`/help`。
+- `/kernel`：打开内核选择器（当前内核打勾，每行带版本与一句说明），在 DSH 与 Claude 会话里都可用。
+  选中另一个内核会记住选择并重启进入它，在新内核里开新会话；原会话仍可在 `/resume` 找到，新会话
+  启动失败时回到原会话。回合进行中不能切换。启动页的「内核」入口与右下角内核区打开的是同一个
+  选择器。用 `--backend` 或配置行指定了内核时，本次按选择重启，之后直接启动仍按参数。全新启动
+  不论记住的是哪个内核都先到启动页，带恢复目标的启动直接进入会话。
 - `/exit`（别名 `/quit`、`/q`）。
 
 **注册表**
@@ -707,8 +839,20 @@ dsh-TUI 不预装通用技能；技能内容与发现规则由 DSH 及当前组
   - registry 服务缺失时 TUI 使用三项 legacy 兼容名册。
   - 服务已挂载但损坏、为空或不一致时标记 unavailable 并 fail closed。
   - 退出计划模式先恢复进入前的 sandbox/approval，再还原进入前所在的权限预设（registry 仍提供时）。
+  - 非 DSH 后端（如 Claude）声明原生权限模式时，`/permission` 列的是该后端的模式：
+    `default`（逐个询问）、`acceptEdits`（自动接受编辑）、`plan`（只读规划）、
+    `bypassPermissions`（跳过全部权限确认），模型支持时还有 `auto`，每行带一句解释。
+    `bypassPermissions` 只能在这个选择器里明确选择，`Shift+Tab` 的循环
+    default → acceptEdits → plan（→ auto）到不了它。状态栏总是显示当前模式
+    （`bypassPermissions`/`dontAsk` 用警告色），只有「极简界面」例外。Claude 设置里的
+    `defaultMode: bypassPermissions` 会降为 `default` 并在转录里提示，克隆来的仓库不能
+    悄悄关掉所有确认。
+  - `/permission` 的选择会存进 `~/.dsh-tui/backends/claude/prefs.json`（与模型、effort
+    同一个文件），之后的会话按它启动。优先级：`DSH_TUI_CLAUDE_PERMISSION_MODE` 环境变量 >
+    记住的选择 > Claude 设置 > `default`。按记住的选择以 `bypassPermissions` 启动时，转录里
+    会提示一句。
 - `/lang` 切换中英界面语言（见「界面语言」）。
-- `/compact` 压缩会话历史；内核「极简模式」预设（Agent preset `minimal`，只有一个持久 shell 工具）下不可用——与界面设置的「极简界面」无关。
+- `/compact` 压缩会话历史；内核「极简模式」预设（Agent preset `minimal`，只有一个持久 shell 工具）既不挂载压缩服务也不剪枝工具结果，长会话可能撞上下文上限、超长工具输出整段留在上下文里，`/compact` 因此不可用（Help 与 `/` 补全标注「不可用」，进入该预设时提示一次）——与界面设置的「极简界面」无关。
 - `/thinking` 扩展思考显示开关，仅本次界面状态、**不持久化**。
 - 启动后后台检查 npm 新版本，发现更新时提示。
   - 检测遵循 npm registry 配置（`NPM_CONFIG_REGISTRY` 或 `~/.npmrc`）。

package/guide/dsh-tui-guide/plugins.en.md

@@ -1,9 +1,9 @@
-# Plugin Development Guide (merged into spec)
+# Plugin Development Guide (authoritative text: the TUI Profile)
 
 [Documentation index](README.md) · [简体中文](plugins.md)
 
-> This document has been merged with the ecosystem admission specification:
-> [Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+> This document has been merged with the in-repo TUI Profile (`tui-profile/`):
+> [Plugin Admission and Development Guide](../tui-profile/docs/plugin-admission-and-development.md)
 
 The ecosystem entry points and seam stability reference below are kept here
 for quick reference; the authoritative status and compatibility agreement
@@ -12,7 +12,7 @@ live in the admission & development guide.
 ## Ecosystem entry points
 
 - **Interface & compatibility agreement / Plugin development guide**:
-  [Terminal Interactive Ecosystem Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+  [Terminal Interactive Ecosystem Plugin Admission and Development Guide](../tui-profile/docs/plugin-admission-and-development.md)
   (admission spec, seams, contracts, verification checklist).
 - **Organization**:
   [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)
@@ -28,17 +28,27 @@ live in the admission & development guide.
 
 An **informal** maturity grading to help plugin authors gauge investment;
 the authoritative status and compatibility agreement live in the
-[admission & development guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md):
+[admission & development guide](../tui-profile/docs/plugin-admission-and-development.md):
 
 | Tier | Seams |
 | --- | --- |
 | Stable candidate (shape frozen; breaking changes go through a minor-version deprecation warning before removal) | VI settings sections · VIII full-screen scenes · X managed dialogs · XI status line · XII keyboard shortcuts · XIII entry renderers |
-| Experimental (may still shift with dsh-std / admission-spec evolution) | IX decision events · toast notifications (`ctx.tuiToast`, new) |
+| Experimental (may still shift with dsh-std / the TUI Profile) | IX decision events · toast notifications (`ctx.tuiToast`, new) · **Side panels (`ctx.tuiPanels`, full panel + compact row, experimental)** |
 | Upstream-tracked (stability owned by the cordis / dsh mechanisms underneath) | I session events · II official prompt slots · III bundled skills · IV themes · V system-prompt sections · VII profile composition |
 
 Also an experimental public surface:
 
 - `@deepseek-harness-tui/dsh-tui/api` (types-only entry).
+- **Side panels (experimental, §18)**: `ctx.tuiPanels.register({ apiVersion:
+  1, id, title, icon?, component | compact })` registers a right-sidebar
+  panel (the host prefixes `<pluginId>:`; ≤4 panels per plugin, ≤32 globally;
+  `open()` is rate-limited to once per 5s; 3 consecutive crashes disable the
+  panel for the session). Of the two render slots — the full panel
+  (`component`) and the compact row (`compact`, 1–3 lines) — **compact is
+  descriptor-validated only this phase and not mounted yet**; `sendToChat`
+  requires the `panels.chat.attach` grant (a later version) and currently
+  always returns `false` with a one-time hint. Types live at
+  `@deepseek-harness-tui/dsh-tui/panels` and `./api`.
 - The `@deepseek-harness-tui/dsh-tui/test-utils` subpath and
   `ctx.tuiPluginHost.grants.corrupt` were removed in the adapter layering
   refactor (#705).

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

@@ -1,9 +1,9 @@
-# 插件开发指南（已并入 spec）
+# 插件开发指南（口径见 TUI Profile）
 
 [文档索引](README.md) · [English](plugins.en.md)
 
-> 本文档已与 dsh-ecosystem-spec 的准入规范整合，请阅读：
-> [终端交互生态插件准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+> 本文档已与仓内 TUI Profile（`tui-profile/`）的准入规范整合，请阅读：
+> [终端交互生态插件准入与开发指南](../tui-profile/docs/plugin-admission-and-development.md)
 
 以下生态入口与接缝稳定性分级仅为速览保留；正式状态与兼容性协定
 以准入与开发指南为准。
@@ -11,7 +11,7 @@
 ## 生态入口
 
 - **接口与兼容性协定 / 插件开发指南**：
-  [终端交互生态插件准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+  [终端交互生态插件准入与开发指南](../tui-profile/docs/plugin-admission-and-development.md)
   （准入规范、接缝、契约、验证清单）。
 - **生态组织**：
   [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)
@@ -25,17 +25,25 @@
 ## 接缝稳定性参考
 
 按当前实现成熟度给出的**非正式**分级，帮助插件作者评估投入；正式
-状态与兼容性协定以[准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)为准：
+状态与兼容性协定以[准入与开发指南](../tui-profile/docs/plugin-admission-and-development.md)为准：
 
 | 分级 | 接缝 |
 | --- | --- |
 | 稳定候选（形态冻结；如有破坏性变更，先在次版本弃用告警再移除） | 六 设置区块 · 八 全屏场景 · 十 托管对话框 · 十一 状态行 · 十二 键盘快捷键 · 十三 条目渲染器 |
-| 实验性（仍可能随 dsh-std / 准入规范演进调整） | 九 决策事件 · toast 通知（`ctx.tuiToast`，新增） |
+| 实验性（仍可能随 dsh-std / TUI Profile 演进调整） | 九 决策事件 · toast 通知（`ctx.tuiToast`，新增） · **侧栏 Panel（`ctx.tuiPanels`，full 面板与 compact 行，实验性）** |
 | 跟随上游（稳定性由 cordis / dsh 官方机制决定） | 一 会话事件 · 二 官方 prompt 槽位 · 三 技能打包 · 四 主题 · 五 system prompt 段 · 七 profile 组合 |
 
 另：
 
 - `@deepseek-harness-tui/dsh-tui/api`（纯类型入口）为实验性公开面。
+- **侧栏 Panel（实验性，§18）**：`ctx.tuiPanels.register({ apiVersion: 1,
+  id, title, icon?, component | compact })` 向右侧栏注册面板（宿主自动加
+  `<pluginId>:` 前缀；每插件 ≤4 个、全局 ≤32 个；`open()` 限速每 5s 一次；
+  连续崩溃 3 次本会话禁用）。full 面板（`component`）与 compact 行
+  （`compact`，1–3 行紧凑呈现）两个渲染槽中，**本阶段 compact 仅校验
+  descriptor、尚不挂载渲染**；`sendToChat` 需要 `panels.chat.attach`
+  授权（后续版本），当前恒返回 `false` 并提示一次。类型见
+  `@deepseek-harness-tui/dsh-tui/panels` 与 `./api`。
 - `@deepseek-harness-tui/dsh-tui/test-utils` 子路径与
   `ctx.tuiPluginHost.grants.corrupt` 已随 adapter 分层重构（#705）移除。
 - `grants` 收窄为 `HostGrantFacade`，迁移细节见该 PR。

package/guide/dsh-tui-guide/themes.en.md

@@ -11,7 +11,7 @@ dsh-TUI provides three Gentle Mist Blue palettes, plus an `auto` pseudo-theme:
 | `auto` | Pseudo-theme: follows the system/terminal background, resolving to `light` or `dark` |
 | `light` | White panels, ink body text, and mist-blue interaction color |
 | `dark` | Dark-terminal adaptation with warm-gray text and soft blue accents |
-| `dark-ansi` | Compatibility fallback using only the 16 ANSI colors |
+| `dark-ansi` | Compatibility fallback using only the 16 ANSI colors (except the ignition pair) |
 
 Without an explicit choice, the TUI queries the terminal background with OSC
 11 and selects `light` or `dark`. It falls back to `dark` when the terminal
@@ -46,8 +46,13 @@ DSH_TUI_THEME
 ## Switching themes
 
 - `/theme` opens the picker, with `auto` and the built-ins before static JSON
-  and plugin themes.
-- `/theme <name>` switches directly to a static or runtime plugin theme.
+  and plugin themes. On terminals at least 76 columns wide a live preview sits
+  beside the list: the **focused row's** palette renders a code block, a
+  code-operation tool card and a diff, so moving the cursor compares syntax,
+  diff and tool-card colors before Enter applies anything. Narrower terminals
+  stack the preview under the list, and it yields entirely when the height
+  budget is short — the list and its focused row always stay visible.
+- `/theme <name>` switches directly to a built-in, static JSON, or runtime plugin theme.
 - `/theme status` shows the current theme and persistence location.
 
 Confirming a choice hot-switches immediately and writes it to
@@ -105,6 +110,8 @@ Available color keys by purpose:
 - Diff syntax highlighting: `syntaxKeyword`, `syntaxString`, `syntaxComment`, `syntaxNumber`, `syntaxFunction`, `syntaxType`
 - Diff syntax highlighting (cont.): `syntaxVariable`, `syntaxOperator`, `syntaxPunctuation`, `syntaxConstant`
 - Badges/accents: `mascotBody`, `inputBackground`, `professionalBlue`, `chromeYellow`
+- Animated chrome & caret: `contextBarSystem`, `contextBarPrompt`, `contextBarAssistant`
+- Animated chrome & caret (cont.): `contextBarThinking`, `contextBarTools`, `ignition`, `ignitionDim`, `cursor`
 - Messages & input: `userMessageBackground`, `userMessageBackgroundHover`, `messageActionsBackground`, `selectionBg`, `bashMessageBackgroundColor`
 - Messages & input (cont.): `memoryBackgroundColor`, `rate_limit_fill`, `rate_limit_empty`, `fastMode`, `fastModeShimmer`, `userPromptLabel`
 - Subagent messages: `subagentBullet`, `subagentDescription`, `subagentModel`, `subagentElapsed`, `subagentToolName`, `subagentStatusRunning`
@@ -113,6 +120,26 @@ Available color keys by purpose:
 When the file declares `name`, its filename remains a loading alias. See the
 `Theme` type in [`src/theme.ts`](../src/theme.ts) for every color key.
 
+A few keys carry behavior worth knowing:
+
+- `contextBarSystem` … `contextBarTools`: the context progress bar's five segment fills, in bar
+  order (system → prompt → assistant → thinking → tools). Static JSON and plugin themes inherit
+  all five from the `base` they pick; only a legacy resolver's key-less palette keeps the old ramp.
+- `ignition` / `ignitionDim`: the top reasoning tier's ignition colors — the sweep waveform, the
+  `❯` prefix and the tier badge all read the same pair, and `ignitionDim` is the substrate the
+  wave fades into. The wave emits per-column truecolor SGR, so these two want a form with fixed
+  channels (`#rgb`, `#rrggbb`, `#rrggbbaa` with the alpha ignored, or `rgb(r,g,b)`); `ansi:*` /
+  `ansi256(n)` — or a missing key — falls back **per key** to the built-in pair selected by the
+  palette's lightness, so the other key is unaffected.
+- `cursor`: the caret fill in the main prompt, launchpad input and picker search boxes.
+  The glyph on it is whichever of `text` / `inverseText`
+  contrasts better with that fill (a 16-color `ansi:*` fill, or a palette whose `text`/`inverseText`
+  has no parseable channels, cannot be measured and keeps `inverseText`), so a light caret can still
+  carry dark ink. The built-ins leave it empty — empty
+  keeps the inverse-video caret for backwards compatibility; declare it only when the caret must
+  stop following the body text color.
+- Transcript link text follows `accent`; an empty or unparseable accent keeps the old fixed blue.
+
 ## npm plugin themes
 
 An npm plugin registers a runtime theme through the `tuiThemes` service,
@@ -140,7 +167,7 @@ export function apply(ctx: Context): void {
 - On an older profile without `tuiThemes`, the plugin degrades silently and
   static themes remain unaffected.
 
-See the [Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+See the [Plugin Admission and Development Guide](../tui-profile/docs/plugin-admission-and-development.md)
 for the full key list, legacy-key mapping, and registration contract.
 
 ## Color formats

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

@@ -11,7 +11,7 @@ dsh-TUI 提供三套 Gentle Mist Blue 色板，外加一个 `auto` 伪主题：
 | `auto` | 伪主题：跟随系统/终端背景，自动解析为 `light` 或 `dark` |
 | `light` | 白色面板、墨色正文、雾蓝交互色 |
 | `dark` | 深色终端适配，暖灰正文与柔雾蓝强调色 |
-| `dark-ansi` | 只依赖 16 色 ANSI 的兼容回退 |
+| `dark-ansi` | 只依赖 16 色 ANSI 的兼容回退（点火色对除外） |
 
 未明确指定主题时，TUI 通过 OSC 11 查询终端背景，
 在 `light` 与 `dark` 之间选择；终端不响应时回退到 `dark`。
@@ -41,8 +41,11 @@ DSH_TUI_THEME
 ## 切换主题
 
 - `/theme`：打开主题选择器。`auto` 与内置主题在前，
-  静态 JSON 主题和插件主题在后。
-- `/theme <name>`：直接切换静态或运行时插件主题。
+  静态 JSON 主题和插件主题在后。宽终端（≥76 列）在列表右侧并排一列实时预览：
+  用**焦点行**主题的调色板实渲染代码块、代码操作工具卡与 diff——移动光标即可
+  比较语法色、diff 色与工具卡底色，Enter 才真正应用；窄终端预览堆叠在列表
+  下方，浮层高度不够时整块让位，列表与焦点行始终完整。
+- `/theme <name>`：直接切换内置、静态 JSON 或运行时插件主题。
 - `/theme status`：显示当前主题与持久化位置。
 
 选择器确认后立即热切换，并把选择写入 `~/.dsh-tui/theme.json`。
@@ -104,6 +107,8 @@ DSH_TUI_THEME
 - diff 语法高亮（续）：`syntaxFunction`、`syntaxType`、`syntaxVariable`、`syntaxOperator`
 - diff 语法高亮（续）：`syntaxPunctuation`、`syntaxConstant`
 - 徽标/强调：`mascotBody`、`inputBackground`、`professionalBlue`、`chromeYellow`
+- 界面动画与光标：`contextBarSystem`、`contextBarPrompt`、`contextBarAssistant`
+- 界面动画与光标（续）：`contextBarThinking`、`contextBarTools`、`ignition`、`ignitionDim`、`cursor`
 - 消息/输入：`userMessageBackground`、`userMessageBackgroundHover`
 - 消息/输入（续）：`messageActionsBackground`、`selectionBg`、`bashMessageBackgroundColor`
 - 消息/输入（续）：`memoryBackgroundColor`、`rate_limit_fill`、`rate_limit_empty`
@@ -115,6 +120,23 @@ DSH_TUI_THEME
 如果文件声明了 `name`，文件名仍可作为加载别名。完整颜色键见
 [`src/theme.ts`](../src/theme.ts) 中的 `Theme` 类型。
 
+几条键的语义与默认行为：
+
+- `contextBarSystem` … `contextBarTools`：上下文进度条的五个分段填充色，按条上顺序
+  （system → prompt → assistant → thinking → tools）。静态 JSON 与插件主题都从所选
+  `base` 继承这五个键；只有旧运行时解析器直接返回、缺键的色板才沿用写死的深蓝坡道。
+- `ignition` / `ignitionDim`：最高思考强度档的点火动画用色——扫光波形、`❯` 前缀与档位徽标
+  同源，`ignitionDim` 是波形淡出的本底色。波形逐列输出真彩色 SGR，所以这两个键要写成能解析
+  出固定通道的形式（`#rgb`、`#rrggbb`、`#rrggbbaa`（alpha 会被忽略）或 `rgb(r,g,b)`）；
+  写成 `ansi:*` / `ansi256(n)`（或整键缺失）时**逐键**回退到按主题明暗选定的内置点火色对，
+  另一个键不受牵连。
+- `cursor`：主输入框、落地页输入框及选择器搜索框光标的填充色。
+  块上的字形取 `text` 与 `inverseText` 中对该填充对比度更高
+  的一个（16 色的 `ansi:*` 填充，或 `text`/`inverseText` 解析不出通道的调色板，
+  都量不出对比度，仍用 `inverseText`），所以浅色光标也能配深墨字形。
+  内置主题留空——空值表示沿用原来的反色块光标（向后兼容）；只有需要光标独立于正文色时才声明。
+- 正文链接的文字色跟随 `accent`；accent 为空或解析不出时回落到原来的固定蓝。
+
 ## npm 插件主题
 
 npm 插件通过 `tuiThemes` 服务注册运行时主题，不必写入
@@ -141,7 +163,7 @@ export function apply(ctx: Context): void {
 - 旧 profile 没有 `tuiThemes` 时插件静默降级，静态主题不受影响。
 
 完整的可覆盖键、旧键映射与注册契约见
-[终端交互生态插件准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)。
+[终端交互生态插件准入与开发指南](../tui-profile/docs/plugin-admission-and-development.md)。
 
 ## 颜色格式