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

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

@@ -35,17 +35,38 @@ dsh-tui
 
 ### 1.2 首次启动你会看到
 
-1. **像素鲸鱼顶栏**（约 3.4 秒开场动画，之后定格）：`✦ dsh-TUI` 版本号、`DEEPSEEK / HARNESS` 大字、
-   当前模型与 effort、工作目录，及一行**启动提示**（`/model` · `/help` · `Tab` 补全）；终端变窄时按阶梯降级（见 5.1）。
+1. **首次引导**（在"还没完成过引导"时出现：首次安装，或引导本身升级过版本）：四步向导 ——
+   **API Key 与连通性 → 语言与主题 → 模型与工作区 → 快捷键与招式**。
+   `←/→` 换步骤、`Tab` 在两组面板间切、`↑/↓` 移动选择、`Enter` 执行这一步、`Esc` 跳过；
+   **跳过不记账**（下次启动还会问），最后一步要在**键位卡**上按 `Enter` 才算"完成"并写入记账文件
+   （焦点落在命令卡上时 `Enter` 是"试一下"）。之后随时可用 `/setup` 重跑。
+2. **落地页**（**普通启动**的第一屏：没带 `--resume`、没指定工作区、也没带首句提示词；
+   `DSH_TUI_NO_LAUNCHPAD=1` 可整体跳过）：像素鲸鱼顶栏（`✦ dsh-TUI` 版本号、
+   `DEEPSEEK / HARNESS` 大字、当前模型与 effort、工作目录，及一行**启动提示**；
+   这一屏的头部**直接定格**——开场动画留给进入对话后的转录区顶部），
+   下面是一个**真输入框**（第一句话在这里打，**回车直接发送**）与框下一行**参数行**
+   （模型 · 思考深度 · 模式 · 权限——四段都可点，点开对话页同款选择器就地换值；四段常在，
+   一行装不下时只把超长的段截尾成 `前缀…`（权限段不截断），悬停被截断的段可看**完整名**
+   （落地页这一屏恒启用鼠标跟踪，inline 模式下也是）；其余各段压到下限后**完整权限名放不进预算**时
+   （终端 ≥76 列后，再宽也不改变结果；更窄的终端或更长的权限名都会更早触发）才回落到按显示顺序从尾部整段省掉），
+   隔一行留白再一行**快捷入口**（第七版四格：`继续「…」`（快捷键 `Alt+R`，没有可继续会话时整格不画）·
+   `会话与工作区`（历史会话与工作区本就是 `/home` 同一个界面，合并成一个入口）· `设置` ·
+   **条件位**——有后台任务在跑显 `后台任务`、检测到新版本显 `有新版本`、用量到档且没 star 过显
+   `投喂一颗 Star`，都不成立兜底 `帮助`）。
+   入口与参数段用 `↑/↓` 或 `Tab` 移焦点、`Enter` 激活，也可以直接点；终端变矮时按"整块撤"的顺序降级
+   （快捷入口 → 提示行 → 只留输入框），变窄时按 5.1 的阶梯降级。
+   从这一屏打开的整屏界面（会话与工作区 / 设置 / 后台任务 / 引导向导）都**盖在落地页之上**，
+   `Esc` 退出即回到落地页（草稿、参数、焦点原样保留）；**离开落地页进对话页的唯一方式是
+   回车提交一条非命令消息**。
    dsh 引擎版本不在验证范围时会出现 **⚠ 版本漂移警告** 及对齐命令。
-2. **底部状态栏**：工作状态行、上下文进度条、TPS 仪表与各类实时指标（见
+3. **底部状态栏**：工作状态行、上下文进度条、TPS 仪表与各类实时指标（见
    [5. 界面与状态栏](#5-界面与状态栏)）。
-3. **启动提示行**：Logo 下方固定一行 `提示：<随机小技巧> · /tips 更多技巧`，每次启动随机换一条；
+4. **启动提示行**：Logo 下方固定一行 `提示：<随机小技巧> · /tips 更多技巧`，每次启动随机换一条；
    `/tips` 打开完整技巧面板（`↑/↓` 滚动、`Esc` 关闭）。
-4. **第一次普通启动**（没带 `--resume`、没指定工作区、也没带首条提示词）进入**会话管理界面**先挑工作区，
-   离开后 `~/.dsh-tui/home.json` 记下"已看过"，以后启动直接进对话；
+5. **第一次普通启动**（没带 `--resume`、没指定工作区、也没带首条提示词）在落地页之后进入
+   **会话管理界面**先挑工作区，离开后 `~/.dsh-tui/home.json` 记下"已看过"，以后启动直接进对话；
    界面随时可用 `/resume`、`/home`、`/agentview`、`/bg` 或输入框行首 `⌸` 打开。
-5. 输入 `/` 看命令菜单，按 `?` 看快捷键帮助。
+6. 输入 `/` 看命令菜单，按 `?` 看快捷键帮助。
 
 ### 1.3 核心心智模型
 
@@ -62,7 +83,7 @@ dsh-tui
 
 | 键 | 功能 |
 |---|---|
-| `Enter` | 空闲=发送；**模型工作时=steer**（注入下一步边界，不中断）；菜单打开=确认选中项 |
+| `Enter` | 空闲=发送；**已知 `/` 命令（可带参数）=执行该命令**（回合运行中由命令自己的门禁裁决）；模型工作时=steer（注入下一步边界，不中断）；菜单打开=确认选中项 |
 | `Tab` | 补全 `/` 命令或 `@` 文件；**模型工作时=follow-up**（排入当前回合之后） |
 | `Ctrl+Enter`（⌘Enter） | 打断当前回合并立即发送输入 |
 | `Shift+Enter` / `Ctrl+J` | 换行（`Option+Enter` 是 mac Terminal.app 的兜底） |
@@ -70,6 +91,8 @@ dsh-tui
 | `Esc`（工作 + 有 pending） | 中断回合并立即重投 pending 消息 |
 | 工作中的 `/btw …` | Enter 直接执行（侧问永不打断主回合） |
 
+回合运行中的 `/` 浮窗按「对当前对话的影响」分区：不影响的命令在上（原样式），会被门禁拦下 / 会打断或替换对话 / 会 steer 的沉到下方、整行变灰（`subtle`，不额外插标题行）。灰区不阻止使用：选中执行后该门禁的门禁、该 steer 的 steer。回合运行中只有两种输入会加塞：不构成命令的普通文本，以及**直接调用技能**的手势（`/技能名 …`，浮窗里同样按「会 steer」沉到灰区）。
+
 ### 2.2 中断 / 退出 / 系统
 
 | 键 | 功能 |
@@ -86,7 +109,7 @@ dsh-tui
 
 | 键 | 功能 |
 |---|---|
-| `Ctrl+R`（⌘R） | 历史消息搜索；重复按或 `↓` 到下一匹配；`Enter` 回填输入框 |
+| `Ctrl+R`（⌘R） | 历史消息搜索（只搜当前项目）；重复按或 `↓` 到下一匹配；`Enter` 回填输入框 |
 | `/`（转录态） | 会话全文搜索；`n` / `N` 跳转（仅 Ctrl+O 展开态） |
 
 ### 2.4 输入编辑
@@ -98,8 +121,9 @@ dsh-tui
 | `Home` / `End`，`Ctrl+E` | 逻辑行首 / 行尾（`Ctrl+A` 已改用于子代理面板，见 §2.7） |
 | `Ctrl+U` / `Ctrl+K` | 删除光标前（至行首）/ 光标后（至行尾） |
 | `Ctrl+W` | 删除前一个单词 |
+| `Ctrl+Z` | 撤销草稿上一步「词级」编辑（含光标与图片）；只作用于草稿，提交或用历史召回（`Ctrl+R`/`↑`）后不再可撤销，与 `Esc Esc` 的会话/消息回溯无关；可经 `/settings` 重映射 |
 | `Backspace` / `Delete` | 删前一 / 后一字符；**有选区时删除整个选区** |
-| `↑` / `↓` | 多行时行间移动；单行时浏览输入历史（最近 200 条，跨重启保留） |
+| `↑` / `↓` | 多行时行间移动；单行时浏览输入历史（按项目隔离，每个项目最近 200 条，跨重启保留；升级前的旧历史各项目都可见） |
 | `Ctrl+V`（⌘V）/ `Alt+V` | 粘贴：文本 / 文件路径（图片自动 `@` 引用）/ 剪贴板位图（`[Image #N]` 附件）；终端拦截 `Ctrl+V` 时用 `Alt+V` |
 | `Ctrl+G` | 用 `$VISUAL`/`$EDITOR` 外部编辑器编辑输入（`:cq` 保留原稿；未设置变量时提示配置） |
 | `Ctrl+Shift+E`（⌘⇧E） | 展开**全屏草稿编辑器**（也可点输入行尾 `⛶`）：带行号、高亮当前行，`Enter` 换行、`Ctrl+Enter` 发送、`Esc` 收起（草稿还在）；`/settings → 全屏草稿编辑` 可关 |
@@ -121,6 +145,7 @@ dsh-tui
 | `Shift+Tab` | 循环会话模式（默认 → plan 计划 → full 完全访问）；挂载了第三方权限预设时，它们按 registry 顺序排在循环末尾 |
 | `Shift+↑` | 消息选择模式（`↑/↓` 移动，`Enter` 展开单条，`Esc` 退出） |
 | `Ctrl+T`（⌘T） | 打开轨迹场景（同 `/trace`） |
+| `Alt+R` | 落地页上**继续最近一条会话**（同入口行的「继续「…」」；仅启动页生效，无可继续会话时无动作）。键位可在 `/settings` 改 |
 | `Alt+S` | 一键 star（同 `/star`；开屏那句求 star 标语整行也可点）。键位可在 `/settings` 改；成功后会演一小段「鲸鱼娘接住星星」的庆祝。想随时看这段庆祝：`DSH_TUI_STAR_MODAL=1 dsh-tui`；想随时看开屏那句求 star 标语：`DSH_TUI_STAR_LINE=1 dsh-tui`（都是预览用环境变量，不动账本） |
 
 ### 2.6 鼠标（fullscreen 全屏模式；拖拽/双击/三击即选即复制）
@@ -165,6 +190,8 @@ dsh-tui
 切换会话只是**停放**——正在跑的回合继续跑；被其他终端占用的会话标红写 `占用 pid <pid>`、点不动，对方退出后恢复。
 固定项存到 `~/.dsh-tui/session-pins.json`。
 工作区菜单四项：编辑 / 在此新建 / 重命名 / 从列表移除（**只删登记**，目录与会话日志都保留）。
+移除后，仍有历史会话的目录会以「仅历史」行留在侧栏；栏头分别统计已登记工作区与历史目录，移除成功也会显示提示。
+「仅历史」行的菜单只有编辑与在此新建；重命名、移除只适用于已登记工作区。
 
 **大图预览**（点输入框里的 `[Image #N]` 或转录缩略图打开）
 
@@ -178,6 +205,7 @@ dsh-tui
 - 没装/没连 IDE 时自动跳过、不影响其他功能（详见 [vscode.md](vscode.md)）。
 
 **历史搜索（Ctrl+R）**
+只列出当前项目（会话工作目录）的输入，外加升级前未分项目的旧历史。
 `↑/↓` 选择 · 重复 `Ctrl+R` 或 `↓` 下一项 · `Enter` 回填 · `Esc`/`Ctrl+C`/`Ctrl+D` 取消
 
 **轨迹场景（Ctrl+T / /trace）**
@@ -208,9 +236,61 @@ dsh-tui
 **双击 Esc 时间回溯（rewind）**
 列表 `↑/↓` + `Enter` 进入确认 · 确认页 `Enter` 回退 / `Esc` 返回 · 插件决策等待中只响应 `Esc`
 
+### 2.8 侧栏（Side panel）
+
+`Ctrl+B`（可在 `/settings` → `Shortcuts` 重映射）在聊天右侧展开一条侧栏：顶部胶囊标签栏、
+中间活动面板、底部按键提示行，与聊天之间隔一列中缝。
+
+- **三种形态**：**分栏**（split，聊天约 68% + 侧栏，`+`/`-` 每次调 4 列）、**收起**（collapsed，
+  布局与以前逐字节相同）、**缩放**（zoom，面板占满，聊天列保留最小宽度）。
+- **分栏条件**：fullscreen 且内容区 ≥93 列（默认页边距下约合终端 97 列）；窄屏、inline 模式、
+  展开全屏草稿编辑器时自动回退——`/jobs` 等命令仍走整屏面板，`Ctrl+B` 与 `/panel` 则不分栏。
+- **焦点模型**：同一时刻只有一处键盘焦点，焦点在右栏时面板边框与中缝一起提亮。`Ctrl+B` 三态：
+  未开 → 打开并聚焦右栏；已开但焦点在聊天 → 聚焦右栏；焦点已在右栏 → 关闭并回聊天。
+- **右栏按键**：`Esc` 一步回到输入框（不关面板）· `←`/`→` 或 `[`/`]` 切换面板 · `1`-`9` 直达第 N 个 ·
+  `z` 或 `Alt+Z` 缩放 · `+`/`-` 调宽（`+` 加宽面板，步长 4 列） · `↑`/`↓`/`PgUp`/`PgDn` 交给活动面板（jobs 用它选择与滚动）；
+  面板没吃下的键不会再落到聊天，但 `Ctrl+C`/`Ctrl+D`/`Ctrl+L` 等 Ctrl 组合照旧作用于聊天。
+- **鼠标**：点聊天栏把焦点给聊天，点右栏把焦点给面板；点标签栏上的标签直接切到那个面板（悬停会高亮），
+  点右端的 `⤢` 把当前面板放大成整屏；右栏不参与拖拽选字。
+- **面板**：全部 8 个内置面板默认启用，可在 `sidePanel.panels` 调整。`todo`（Goals/Todos，分栏时从输入框上方迁到这里）、`jobs`（后台任务，点转录里的任务卡
+  会直接定位到该任务）、`agents`（子代理 Dashboard 与详情：Enter 进详情、Esc 逐级返回）、`companion`
+   （宠物：跟随会话状态换心情动画，点击
+   比爱心、Enter 戳一戳；皮肤 `dsh-tui.companion.skin` 可选 deepy（默认，非官方粉丝作品 deepy
+   小鲸鱼）或 whale）、`info`（信息栏：模型 / 思考深度 / 工作模式 / 权限 / 上下文占用 / 缓存命中 /
+  Token / TPS / 消耗 / 工作目录 / 会话标题与 ID）、`trajectory`（会话轨迹：唤醒带 + 账本 + 检视器，
+  ↑/↓ 选择、Enter 展开、Tab 切热点视图；←/→ 恒归侧栏切面板，Tab 才是切视图）、`workspace`
+  （工作目录/工作区总览，Enter 打开整屏工作区主页）、`btw`（追问线程，可从 `/btw` 进入）。
+- **宠物（companion）细节**：宠物锚在面板**底部**，上方是状态区（心情 · 子代理/会话计数 · 当前动作）。
+  互动：点它左半/右半会被戳（poke-left/right）、短窗口连点三次是挠痒（tickle）、**按住拖动它就跟着
+  指针在整个面板里走（松手弹回底部）**、鼠标悬停它会看向指针；Enter 也算戳一戳。后台任务完成、已打断
+  这类提示会由它头顶的对话气泡说出——此时输入框上方**不再重复弹**同一条（宠物面板不是活动面板时
+  toast 照旧；错误类通知永远走 toast）。情绪带防抖平滑：快速的工具调用不会让动画来回闪烁（离开工作
+  状态约 1.5s 才切换；审批/出错仍立即抢占）。子代理/会话数会切换配乐/指挥/施工等群像动画。面板窄到
+  连紧凑形态都放不下时它会「躲起来」，只留一行 `好挤呀！{{name}}暂时躲起来了~`。
+  皮肤 `dsh-tui.companion.skin` 三选一：`deepy`（默认，非官方粉丝作品小鲸鱼）、`whaleGirl`（鲸娘
+  表情包，22 个动画，被戳/被挠/被拎起来都有对应反应，独有「冒爱心」「举大拇指」）、`whale`（开屏
+  同款像素鲸）。**鲸娘在有图像协议（kitty/sixel）的终端里按原帧数 240px 像素级渲染**（267 帧全保留、
+  透明悬浮、按需解码），无图像协议自动回退字符画版。
+
+| 子命令 | 作用 |
+|---|---|
+| `/panel` | 打开面板选择器（↑↓ 选择、Enter 打开并聚焦） |
+| `/panel toggle` | 真开 / 真关（关闭时焦点回聊天） |
+| `/panel focus` | 打开并聚焦右栏 |
+| `/panel zoom` | 打开并缩放当前面板 |
+| `/panel <id>` | 打开指定面板：`todo` / `info` / `trajectory` / `jobs` / `agents` / `workspace` / `btw` / `companion`（补全列出已启用的 id） |
+
+- 原本只能整屏的视图现在也能进侧栏：分屏开着且对应面板已启用时，`Ctrl+T` / `/trace` 打开轨迹面板、
+  `/home` 打开工作区面板；面板栏右端的 `⤢` 再把它们放回整屏（`⤢` 是鼠标入口，键盘等价物就是各自的
+  整屏快捷键：`Ctrl+T` 轨迹、`Ctrl+A` 子代理、`/jobs` 任务、`/home` 工作区主页）。
+- 设置：`/settings` → `侧栏` 分组，或 `dsh-tui.sidePanel.{splitEnabled,open,ratio,panels}`
+  （见[配置参考](configuration.md#tui-配置)）。
+- **tmux 用户注意**：`Ctrl+B` 是 tmux 的默认前缀键，会被 tmux 截走、送不到 TUI——到
+  `/settings` → `Shortcuts` 把 `sidePanel` 换成别的组合（例如 `alt+b`）。
+
 ## 3. 命令全集
 
-命令菜单 = 内置命令（50 条） + DSH 注册表命令（`/plan` `/goal` 等） + 技能目录
+命令菜单 = 内置命令（58 条，含别名） + DSH 注册表命令（`/plan` `/goal` 等） + 技能目录
 （仅补全，`/help` 菜单隐藏）。`/lang` 可切换中英文界面与命令描述。
 
 ### 3.1 会话
@@ -218,11 +298,12 @@ dsh-tui
 | 命令 | 参数 | 作用 |
 |---|---|---|
 | `/new` | 无 | 新开会话（无二次确认；旧会话可 `/resume` 恢复） |
-| `/resume` | 无 | 打开**会话管理界面**（工作区栏 + 会话栏、实时筛选、固定常用、跨工作区）：切换会话只是**停放**，正在跑的回合不中断 |
+| `/resume` | 无 | 打开**会话管理界面**（工作区栏 + 会话栏、实时筛选、固定常用、跨工作区）：切换会话只是**停放**，旧会话转后台继续跑，正在跑的回合不中断（与 `/tree` 同类：浏览与切换都不打断当前回合；仅 Claude 后端例外，回合运行中切换会被拒绝） |
 | `/home` / `/agentview` / `/bg` | 无 | 同一个会话管理界面（`/home`=工作区视角 · `/agentview`=托管会话状态 · `/bg`=转后台并打开，别名 `/background`） |
 | `/tree` | 无 | 会话分叉树：悬停预览、点击回退 / 分叉 / 切换分支 |
 | `/fork` | 无 | 把当前会话复制成可恢复的副本（原会话不受影响） |
 | `/restart` | 无 | 重启进程并恢复本会话（回合运行中会被拒绝，先 `Ctrl+C`） |
+| `/kernel` | 无 | 内核选择器：在 DSH 与实验性的 Claude 后端之间切换，记住选择并重启进入新会话（回合运行中会被拒绝）；见 [Claude 后端](claude-backend.md) |
 | `/rename` | `<新名称>` | 重命名当前会话（无参时显示当前标题与用法） |
 | `/recap` | 无 | 最近活动摘要（一行）+ 建议标题；面板内 `a` 键或点击一键应用标题。设置 `dsh-tui.recapOnOpen`（默认开）开启时，打开/恢复会话自动在底部显示一条分隔线 + `回顾：` 摘要行，悬停可查看操作、点击展开，发送新消息后自动消失 |
 | `/workspace` | `resume` / `rename <名称>` / `open <路径或URI>` | 管理工作区；`open` 支持绝对路径、file URI、插件 scheme |
@@ -231,7 +312,7 @@ dsh-tui
 | `/export` | 无 | 导出会话为 Markdown 到工作目录 |
 | `/btw` | `<问题>` | 侧问：单轮、无工具、不打断主回合、不写历史 |
 | `/trace` | 无 | 打开轨迹场景（同 `Ctrl+T`） |
-| `/rewind` | 无 | 回退选择器（同空输入双击 Esc 的时间回溯） |
+| `/rewind` | 无 | 回退选择器（同空输入双击 Esc 的时间回溯）；**回合运行中会先取消当前回合**再回溯 |
 | `/exit`（别名 `/quit` `/q`） | 无 | 退出 dsh-tui |
 
 ### 3.2 状态与诊断
@@ -249,22 +330,25 @@ dsh-tui
 | `/agents` | 无 | 本会话子代理列表 |
 | `/jobs` | 无 | 后台任务面板：状态/运行时长/退出码实时跟踪，`↑/↓` 选择、`k` 停止；面板打开时 `Esc` **只关面板**不打断回合（想中断先关面板再 `Ctrl+C`） |
 | `/settings` | 无 | 打开插件设置编辑器（命名空间读取/编辑） |
+| `/setup` | 无 | 重跑首次引导向导（API Key / 语言主题 / 模型工作区 / 快捷键），与首次启动是同一个界面 |
 | `/help` | 无 | 快捷键 + 命令帮助菜单（`?` 入口） |
 
 ### 3.3 模型 / 显示
 
 | 命令 | 参数 | 作用 |
 |---|---|---|
+| `/channel` | 无 | 中转渠道档案（仅 Claude 后端）；**回合运行中导入 / 新建 / 管理，以及需要重启进程的切换会被拒绝**（选择器本身仍可打开），见 [交互与命令](interaction.md#渠道档案channel仅-claude) |
 | `/model` | 无 | 模型选择器；**切换 = fork 会话续聊**（历史保留、仅换路由；还没有人说过话的会话不记分支，保留首个 prompt 的自动标题），选择持久化到 `~/.dsh-tui/model.json` |
 | `/effort` | `status` / `<id>` | 推理强度：无参滑杆（`←/→` 实时调整）；`status` 当前档位；`<id>` 直接设定。持久化 `~/.dsh-tui/effort.json`；新会话起始档看 /settings 的 `effortDefault`（§5.3） |
 | `/thinking` | 无 | 扩展思考显示开关（流式时思考逐条展开） |
-| `/tokens` | 无 | token 用量 + 上下文百分比 |
+| `/tokens` | 无 | 分三段报数，不再并列两个不同量：**本次请求**上传量（input + 缓存读 + 缓存写，harness 的四个桶互斥）、**会话累计**（未缓存输入 / 输出 / 缓存读 / 缓存写）、**上下文占用** |
 | `/activity` | `frames <名>` / `status` | 工作状态行动画：无参选择器浏览，`frames <名>` 直接设置（含 `random`），默认 `moon8`。持久化 `~/.dsh-tui/working-activity.json` |
 | `/preset` | `<id>` / `status` | Agent 预设切换：`standard` / `ptc`（旧 0.1.1 名 `code`）/ `minimal` / `cordis` / **梁神模式 `liangshen`**；**已开始的会话不可切换**。持久化 `~/.dsh-tui/agent-preset.json` |
 | `/theme` | `<名字>` / `status` | 主题：无参选择器；`<名字>` 直接切换；`status` 当前主题（auto 时附 OSC 11 解析结果）。持久化 `~/.dsh-tui/theme.json` |
 | `/color` | 无参 / `<名>` / `status` / `reset` | 会话强调色：无参打开调色板（`↑/↓` 选、`Enter` 应用）；`<名>` 直设；`reset` 恢复默认。颜色 `red/orange/yellow/green/blue/purple/pink/cyan`，按会话保存 |
 | `/lang` | `en` / `zh` / `status` | 界面语言热切换。优先级：`DSH_TUI_LANG` > profile 配置（旧版 settings.yaml 用户层 > cordis.yml）> 持久化 |
 | `/vim` | 无 | **vim 编辑模式开关**（见 §2.4）：输入框切到 vim 键位编辑，会话级、不持久化 |
+| `/panel` | `toggle` / `focus` / `zoom` / `<面板 id>` | 侧栏面板：开关 / 聚焦 / 缩放 / 切换；三态与子命令见 §2.8 |
 
 ### 3.4 账号 / 策略 / 扩展
 
@@ -333,7 +417,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 ### 4.3 消息投递语义（模型工作中）
 
 键位见 §2.1：
-- `Enter` = **steer**（注入下一步边界，不中断）
+- `Enter` = 已知 `/` 命令（可带参数）按命令执行（回合运行中由该命令自己的门禁裁决）；其余文本 **steer**（注入下一步边界，不中断）
 - `Tab` = **follow-up**（排到回合后）
 - `Ctrl+Enter` = **interrupt**（打断并发送）
 - `Alt+Up` 取回最后一条未处理消息
@@ -355,7 +439,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 - `/model`：选择器。**切换 = fork 会话续聊**（历史保留、仅换路由，旧会话留在 `/resume`）；
   持久化 `~/.dsh-tui/model.json`。
 - 回合运行中切换会被拒绝。
-- `/preset` 可选：`standard`（默认全功能）、`ptc`、`minimal`（内核「极简模式」：只暴露一个持久 shell 工具，无 compaction、无计划模式）、
+- `/preset` 可选：`standard`（默认全功能）、`ptc`、`minimal`（内核「极简模式」：只暴露一个持久 shell 工具，无 compaction、无计划模式；也因此没有压缩、工具结果不剪枝——长会话可能撞上下文上限，`/compact` 与问卷不可用，Help 与 `/` 补全会标注，进入该预设时提示一次）、
   `cordis`、`liangshen`（梁神模式）。
   **已产生对话的会话不能切换**（blank-only）：选择只保存为下次 `/new` 的默认。
   这里的 preset 是**内核 Agent 预设**，决定模型能用哪些工具；界面上的 `/settings → 极简界面`（Minimal UI）与它无关。
@@ -376,7 +460,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 - `/skills` 浏览技能目录，可直调技能以 `/name` 加入命令菜单（dsh-TUI 不自带通用技能）。
 - `/plan` `/goal` `/feedback` `/permission` 来自 DSH 注册表，随组合并入 `/` 菜单。
 - **Goals/Todos 面板自动出现**：模型写入 goal/todo 时在输入框上方实时渲染（🎯 目标 + phase 徽章 + 树形 todo），
-  无需操作。
+  无需操作；分栏开启时它迁到右栏的 `todo` 面板（见 §2.8）。
 
 ### 4.9 MCP / Workspace / 其他
 
@@ -384,7 +468,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 - `/workspace`：`resume` / `rename <名>` / `open <路径|file:// URI>`（打开并新建会话）。
 - `dsh-tui <路径>` 同样接受工作区目标。
 - `/doctor` 自检：Node/平台、API key、模型路由、cwd、上下文窗口、会话存储、插件宿主。
-- `/provider` 交互向导管理模型提供方：添加 / 编辑 / 删除。
+- `/provider` 交互向导管理模型提供方：添加 / 编辑 / 删除。在模型列表聚焦一项后按 `Tab`，可编辑其上下文窗口、最大输出 token、推理档位和图片输入能力；`Enter` 保存到本次 provider 草稿，取消外层向导不会写入。
   - 标准 profile 的内置 OAuth 模块提供 **订阅账号登录**（ChatGPT/Codex / Claude / Grok；较新 pi-ai 另有 OpenAI 直连 / Meta Muse，免 API key）；也可用 `/auth login <provider>`，`/auth logout <provider>` 删除保存的 OAuth 凭据。
   - DSH 0.2.0-rc.1+ 的 DeepSeek 账号经宿主浏览器授权：`/auth login deepseek-account`，随后用 `/model` 选独立的 `deepseek-account` 路由；`/auth logout deepseek-account` 由宿主退登。它不修改 `deepseek-official` 的 API key。
 - 非环境变量 API key 写入 `~/.dsh/.credentials.yaml`（0600），界面只显示 `••••••`；pi-ai 订阅 OAuth 凭据另存于 `$DSH_HOME/dsh-auth/credentials.json`（未设置 DSH_HOME 时为 `~/.dsh/dsh-auth/credentials.json`）。DeepSeek 账号授权记录由宿主凭据服务持有，不写入此 OAuth 文件。
@@ -426,12 +510,14 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 **Row 1 — 上下文分段进度条**（`/settings → statusBar.contextBar`，默认开）
 
 - 按内容类型分段着色（system / prompt / assistant / thinking / tools）。
+- 分段 token 数是**本地估算**（CJK/全角按 ~1.4 字符/token、ASCII 按 ~4 字符/token、其它脚本按 ~2），
+  只描述这条由什么构成，**不参与占用总量**——占用以 ctx 字段/读数为准（见下）。
 - 条上唯一文字是最右缘读数 `13k/64k 19.5%`（窄屏只显示 `19.5%`）。
 - 读数按占用率变色：<80% 灰蓝，**≥80% 琥珀、≥95% 红**。
 - 悬停整条弹出图例：色块 + 名称 + token 数（窄屏自动改用短名）。
 
 **Row 2 — 状态字段行**（每个字段独立开关，见 `/settings`）
-- 左组：模型 → TPS → thinking → mode → ctx → cache 缓存命中率 → tokens（`1.2k→340` 输入→输出）→
+- 左组：模型 → TPS → thinking → mode → ctx（**上下文占用** `19.5% (13k/64k)`：与分段条、工作线压力前缀、`/tokens`、`/status` 和上下文告警**同读一个值**，来源是 harness 自带的 `contextPressure` 投影——`projectedTokens ?? pressureTokens`，即「下一次请求」的占用，压缩与被拒请求都会立刻反映，不再等一次成功请求；投影缺席的裸 `cordis.yml` 组合回退到上次请求的计费用量）→ cache 缓存命中率 → tokens（`1.2k→340` 输入→输出）→
   cost（`≈¥0.05 谷`，**本会话估算**：包含子代理用量，按各自模型 × 峰值/空闲 × 缓存分项计价；
   hover 拆「主会话 ¥ / 子代理 ¥ / 未计价 N tok」；非官方/未收录模型只显示 token 并标注未计价；
   **估算是参考，以平台账单为准**）
@@ -442,7 +528,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 
 **Row 3 — 提示 / 工作活动 + 迷你轨迹条**
 - 空闲显示 `? for shortcuts`、运行中 `esc to interrupt`、选择中 `esc to return to input`。
-- 空闲还显示 working-activity 动画帧（`statusBar.activity` 开），上下文 ≥80% 琥珀、≥95% 红。
+- 空闲还显示 working-activity 动画帧（`statusBar.activity` 开），上下文 ≥80% 琥珀、≥95% 红（与 ctx 字段同一占用读数）。
 - 右侧**迷你轨迹条 MiniWake**（`statusBar.trajectory`，默认关）：会话投影为密度字形，颜色区分通道，失败列染红；
   窄屏降格/隐藏。
 
@@ -453,7 +539,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 
 `/settings` 打开插件设置编辑器；**改动自动保存**，`Esc` 直接退出。
 dsh-tui 自身区块在 0.1.7 写入当前 profile 的 `cordis.patch.yml`，旧版写入 settings.yaml 用户层。多数设置实时生效；全屏和图片预览开关需 `/restart`。
-下表为常用项，完整列表见 /settings 屏。多数主题（**外观与布局** / **开屏与吉祥物** / **对话与输入** / **图表与图片**）的字段直接平铺在根页的小标题下，改起来不用进出子页；只有真正成块的域——**公式设置** / **底栏设置** / **快捷键**——保留子页，根页一行入口点进去：
+下表为常用项，完整列表见 /settings 屏。多数主题（**外观与布局** / **开屏与吉祥物** / **对话与输入** / **图表与图片**）的字段直接平铺在根页的小标题下，改起来不用进出子页；只有真正成块的域——**公式设置** / **底栏设置** / **侧栏** / **快捷键**——保留子页，根页一行入口点进去：
 
 | 字段 | 说明 |
 |---|---|
@@ -462,15 +548,20 @@ dsh-tui 自身区块在 0.1.7 写入当前 profile 的 `cordis.patch.yml`，旧
 | minimal | 极简界面 Minimal UI（默认关）：隐藏开屏头部、emoji 状态符与装饰性配色，底栏只留模型与目录；代码高亮与工具配色保留。**这是界面开关**，对模型能力没有任何影响——别和 `/preset` 的内核「极简模式」预设搞混 |
 | terminalImages | 终端图片预览（默认开，需终端支持）；保存后用 `/restart` 生效。关闭后只显示文字信息并跳过预览解码，不影响向模型发送图片 |
 | imageBacking | 图片底色（默认 `transparent`，与上一条同在**图表与图片**主题下）：聊天照片/插图背后垫什么。透明：只画图片自己的像素，抗锯齿边缘和透明圆角透出终端底色或壁纸；终端底色：先合成到终端背景色，柔和边缘更平滑。立即生效 |
+| codeFrameStyle | 代码框样式（默认 `light`）：`light` 左侧开放栏杆；`full` 带连续右边框和底边的封闭边框。终端太窄时显示纯代码围栏。立即生效 |
 | whale | 开屏头部像素鲸鱼娘（默认开）；每次启动随机三选一开场动画（经典/爱心/睡觉），`/deepseek` 彩蛋重掷 |
 | whaleIdle | 鲸鱼娘欢迎期闲置动画（默认开）：定格后摆鱼鳍/拍尾巴/眨眼，空闲 10 秒入睡冒 Z；点击冒爱心。开始第一个任务后定格 |
 | splashFont | 开屏大字字体：按天轮换（默认，随本地日期换款）/ 加粗 / 方角实心 / 半立体 / 宽体 / 点阵灰度 / 镂空模板 / 细笔 / 方板。选某一款即固定那一款，选回「按天轮换」恢复。立即生效 |
 | whaleGirl | 女仆娘立绘（默认关）：标题像素鲸鱼换成作者绘制的女仆娘**真图**（Kitty/Sixel 图像协议）；不支持时回落像素鲸鱼 |
 | diffLayout | Edit/Write diff 布局：auto（≥110 列双栏）/ split / unified |
 | thinkingFold | 思考块：preview（流式 2-3 行预览 + 落定折叠）/ full（展开到轮末） |
+| btw.contextBudget | `/btw` 追问携带的最近问答总字符预算（默认 24000，范围 1000-200000）；超出时从最旧的整组开始裁剪。立即生效 |
+| btw.contextTurns | `/btw` 追问显式携带的最近完成问答组数（默认 4，范围 1-8）；窗口外的问答不进入请求，线程与面板仍保留全文。立即生效 |
+| jobGroupFold | 连续的后台任务卡：auto（默认，≥2 张成组；整组落定且 ≥3 张时折叠成汇总行）/ always（≥2 张立即折叠，含在跑的任务）/ never（从不自动折叠，每张卡都留着）。组头一行汇总状态与合计时长，点组头或 Ctrl+O 展开 |
 | effortDefault | 默认推理强度：auto / off / low / high / max。新会话的起始档位（细节见下） |
 | smoothStreaming | 流式平滑输出（默认开）：回复/思考/工具卡正文按 ~30fps 匀速揭示；回放/历史完整直出 |
 | toolBackground | 工具卡背景强调：none / subtle / strong |
+| turnUsageRow | 回合用量行（默认关闭）：在每回合末显示 token、缓存、耗时与重试摘要；`/tokens`、`/status` 和底栏 token 悬停不受此开关影响 |
 | mermaidDiagrams | Mermaid 图表（默认开）：回复中的 ```` ```mermaid ```` 代码块画成字符图，流式期间逐步成形；比终端宽或类型不支持的图保留源码并注明所需列数。立即生效 |
 | mathRendering | LaTeX 公式（默认 `auto`，在 `/settings` 的**公式设置**子页里）：回复中的 `$…$`、`\(…\)` 行内公式，`$$…$$`、`\[…\]` 与单独成行的 `\begin{align}` 等显示环境块级公式的显示方式。`auto` 用当前最好的渲染方式（目前是 Unicode 文本，块级公式里的分数与上下限竖排），`image` 在支持图形的终端里用 MathJax 把公式排版成图片——Kitty 图形协议（Kitty、Ghostty、WezTerm、iTerm2 等）或 Sixel（Windows Terminal 1.22+、xterm、foot、WezTerm）（颜色跟随主题文字色；块级公式最多 16 行，行内公式在能压成一行且不糊时也显示为一行高的图片；流式中的公式、暗色的思考区、不支持图形的终端、压成一行太小以及任何渲染失败都退回 Unicode），`unicode` 固定用 Unicode 文本，`source` 保留原始 TeX。不支持、仍在流式输出或比终端宽的公式保留源码（过宽的块级公式先退成单行）。价格（`$5`）、shell 变量（`$HOME`）与代码里的 `$` 不受影响。旧的 `latexMath: false` 仍等同 `source`。**点击公式图片**打开预览卡：按 2 倍单元格尺寸重排，可 100%–800% 缩放、拖拽平移，`Esc` 或点击卡片外关闭，标题即该公式的 TeX。Sixel 下公式**不带衬底**（只画笔画），终端底色或壁纸会透出来。标题立绘这类自带透明留白的插图同样不带衬底（`whaleGirl` 的真图就是这个行为）；照片、截图与卡片内的图像仍合成到底色上，因为 Sixel 表达不了软 alpha。立即生效 |
 | mathImageScale | 公式图片大小（默认 `auto`，与上一条同在**公式设置**子页）：配合 LaTeX 公式的「图片」使用——`auto` 与正文同尺寸，`large` / `xlarge` 把**块级**公式排得更大；终端图片是按设备像素 1:1 画的，所以"更大"就等于"每个笔画更多像素"，是唯一的清晰度杠杆。行内公式不受影响（只能占一行）。立即生效 |
@@ -562,7 +653,7 @@ dsh 意外退出时，安全模式给出**只读**的环境诊断、profile 插
 
 **效率**
 
-4. 模型工作中三种投递：`Enter` 注入下一步、`Tab` 排队、`Ctrl+Enter` 打断并发送。
+4. 模型工作中三种投递：`Enter` 注入下一步（已知 `/` 命令除外，按命令执行）、`Tab` 排队、`Ctrl+Enter` 打断并发送。
 5. `Alt+Up` 取回最后一条未处理消息改完重发，不用重打。
 6. 想快速问又不打断主回合、不留历史：`/btw <问题>`。
 7. 打错了想重来：**空输入双击 `Esc` 时间回溯**（或 `/rewind`），改完重发。

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

@@ -280,6 +280,7 @@ The TUI's `Ctrl+G` uses `$VISUAL`/`$EDITOR`. To edit in VS Code, export
 | Mouse wheel / drag selection | Handled by the integrated terminal; "copy on release" surfaces as OS-level copy behavior |
 | Extended keyboard protocol | modifyOtherKeys / win32-input-mode behavior is decided by xterm.js and may differ from kitty / WezTerm |
 | OSC 52 clipboard | First use triggers VS Code's own permission prompt |
+| Image protocol | Portraits/images can stay **permanently blank**: dsh-tui prefers the Kitty graphics protocol over Sixel, while VS Code's `@xterm/addon-image` answers the Kitty query with an `OK` that was never verified against an actual draw, so the image is erased and never redrawn. Fix: turn on `terminal.integrated.enableImages` (off by default) in VS Code settings and **reload the window** (the image addon only loads on the WebGL renderer, so it does nothing when `terminal.integrated.gpuAcceleration` is `off` or the legacy `canvas`); if needed, set `DSH_TUI_IMAGE_PROTOCOL=sixel` (needs dsh-tui ≥ 0.10.0) — the companion extension `dsh-tui-vscode` ≥ 0.7.5 injects that variable automatically, so no manual setup is required |
 
 For the full protocol behavior of a standalone terminal (e.g. complex mouse
 semantics), use an external terminal window (Windows Terminal / kitty /

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

@@ -252,6 +252,7 @@ TUI 的 `Ctrl+G` 走 `$VISUAL`/`$EDITOR`。想让它在 VS Code 里编辑，
 | 鼠标滚轮/拖选 | 由集成终端处理；“松开即复制”表现为 OS 级复制行为 |
 | 扩展键盘协议 | modifyOtherKeys / win32-input-mode 由 xterm.js 决定，可能与 kitty / WezTerm 不完全一致 |
 | OSC 52 剪贴板 | 首次使用弹出权限提示（VS Code 自身的安全设计） |
+| 图像协议 | 立绘/图片可能**永久空白**：dsh-tui 让 Kitty 图形协议优先于 Sixel，而 VS Code 的 `@xterm/addon-image` 对 Kitty 查询回一个从未经真实绘制验证的 `OK`，图片被擦掉后不再重绘。解决：在 VS Code 设置里打开 `terminal.integrated.enableImages`（默认关闭）并**重载窗口**（图像 addon 只挂在 WebGL 渲染器上，`terminal.integrated.gpuAcceleration` 为 `off` 或旧 `canvas` 时开了也不生效）；必要时设 `DSH_TUI_IMAGE_PROTOCOL=sixel`（需 dsh-tui ≥ 0.10.0）——用 companion 扩展 `dsh-tui-vscode` ≥ 0.7.5 时该变量自动注入，无需手动设置 |
 
 需要完全对齐独立终端行为时，请使用独立终端窗口
 （Windows Terminal / kitty / WezTerm / iTerm2 / tmux）。