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

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

@@ -46,7 +46,12 @@ DSH_TUI_THEME
 ## Switching themes
 
 - `/theme` opens the picker, with `auto` and the built-ins before static JSON
-  and plugin themes.
+  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 static or runtime plugin theme.
 - `/theme status` shows the current theme and persistence location.
 
@@ -140,7 +145,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

@@ -41,7 +41,10 @@ DSH_TUI_THEME
 ## 切换主题
 
 - `/theme`：打开主题选择器。`auto` 与内置主题在前，
-  静态 JSON 主题和插件主题在后。
+  静态 JSON 主题和插件主题在后。宽终端（≥76 列）在列表右侧并排一列实时预览：
+  用**焦点行**主题的调色板实渲染代码块、代码操作工具卡与 diff——移动光标即可
+  比较语法色、diff 色与工具卡底色，Enter 才真正应用；窄终端预览堆叠在列表
+  下方，浮层高度不够时整块让位，列表与焦点行始终完整。
 - `/theme <name>`：直接切换静态或运行时插件主题。
 - `/theme status`：显示当前主题与持久化位置。
 
@@ -141,7 +144,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)。
 
 ## 颜色格式
 

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

@@ -36,21 +36,41 @@ dsh-tui
 
 ### 1.2 What you see on first launch
 
-1. **Pixel whale header** (~3.4 s intro animation, then frozen): `✦ dsh-TUI` version,
-   `DEEPSEEK / HARNESS` big text, current model and effort, working directory, and a
-   **startup hint** (`/model` · `/help` · `Tab`). Narrow terminals climb down a ladder (see 5.1).
-   When the dsh engine is out of the verified range, a **⚠ version-drift warning**
-   appears with the align command.
-2. **Bottom status bar**: working-status row, context bar, TPS gauge, and other live
+1. **First-run guide** (whenever the guide has not been completed yet — a fresh install, or a
+   guide that bumped its own version): a four-step wizard — **API key & connectivity → language &
+   theme → model & workspace → shortcuts & moves**. `←/→` change step, `Tab` switches between the
+   two panes, `↑/↓` move the selection, `Enter` runs the step, `Esc` skips. **Skipping is not
+   recorded** (you are asked again next launch); the last step only counts as finished — and writes
+   the marker — when `Enter` lands on a **shortcut card** (on a command card `Enter` tries the command).
+   Re-run it any time with `/setup`.
+2. **Launchpad** (the first screen of an **ordinary launch** — no `--resume`, no workspace target,
+   no prompt; `DSH_TUI_NO_LAUNCHPAD=1` skips it entirely): the pixel-whale header (`✦ dsh-TUI`
+   version, `DEEPSEEK / HARNESS` big text, current model and effort, working directory, and a
+   **startup hint**; the header here is **frozen from the first frame** — the intro animation is
+   left to the transcript header once you are in the chat), a **real input box** underneath
+   (type your first sentence here; Enter carries it into the chat screen), and a row of
+   **quick actions** (v7 four slots: `Continue "…"` — shortcut `Alt+R`, the slot is simply absent
+   when there is nothing to continue · `Sessions & workspaces` — history and workspaces are the
+   same `/home` screen, merged into one entry · `Settings` · a **conditional slot** — `Background
+   jobs` while jobs are running, `Update available` when a newer release is detected, `Feed us a
+   star` once usage milestones are reached and you never starred, falling back to `Help`).
+   Move with `↑/↓` or `Tab`, activate with `Enter`, or just click;
+   short terminals drop whole blocks (quick actions → hint line → input only) and narrow ones
+   climb down the ladder in 5.1. Full screens opened from this screen (sessions & workspaces /
+   settings / background jobs / the first-run guide) render **above the launchpad** — `Esc` closes
+   them back onto the launchpad (draft, params and focus intact); the only way off the launchpad
+   into the chat is submitting a non-command line with Enter. When the dsh engine is out of the verified range, a
+   **⚠ version-drift warning** appears with the align command.
+3. **Bottom status bar**: working-status row, context bar, TPS gauge, and other live
    indicators (see [5. UI and status bar](#5-ui-and-status-bar)).
-3. **Startup hint line**: one fixed line under the logo:
+4. **Startup hint line**: one fixed line under the logo:
    `提示：<随机小技巧> · /tips 更多技巧` — changes each launch.
    `/tips` opens the full tips panel (`↑/↓` scroll, `Esc` close).
-4. **First normal launch** (no `--resume`, no workspace, no prompt) enters the
-   **session manager** to pick a workspace. `~/.dsh-tui/home.json` records "seen"
-   so later launches go straight to chat. Open it any time with `/resume`, `/home`,
-   `/agentview`, `/bg`, or `⌸` at the start of the input line.
-5. Type `/` for the command menu, `?` for the shortcut help.
+5. **First normal launch** (no `--resume`, no workspace, no prompt) reaches the
+   **session manager** after the launchpad to pick a workspace. `~/.dsh-tui/home.json`
+   records "seen" so later launches go straight to chat. Open it any time with `/resume`,
+   `/home`, `/agentview`, `/bg`, or `⌸` at the start of the input line.
+6. Type `/` for the command menu, `?` for the shortcut help.
 
 ### 1.3 Core mental model
 
@@ -92,7 +112,7 @@ dsh-tui
 
 | Key | Action |
 |---|---|
-| `Ctrl+R` (⌘R) | history search; press again or `↓` for next match; `Enter` fills the input |
+| `Ctrl+R` (⌘R) | history search (current project only); press again or `↓` for next match; `Enter` fills the input |
 | `/` (transcript) | full-transcript search; `n` / `N` jump (only in Ctrl+O expanded state) |
 
 ### 2.4 Input editing
@@ -104,8 +124,9 @@ dsh-tui
 | `Home` / `End`, `Ctrl+E` | logical line start / end (`Ctrl+A` now opens the subagent panel, see §2.7) |
 | `Ctrl+U` / `Ctrl+K` | delete before the cursor (to line start) / after the cursor (to line end) |
 | `Ctrl+W` | delete the previous word |
+| `Ctrl+Z` | undo the draft's last word-level edit (caret and images included); draft-only — a submit or a history recall (`Ctrl+R`/`↑`) ends it, and it is unrelated to the `Esc Esc` conversation/message rewind; remappable via `/settings` |
 | `Backspace` / `Delete` | delete previous / next character; **with a selection, delete the whole selection** |
-| `↑` / `↓` | move between lines when multi-line; browse input history when single-line (last 200 entries, kept across restarts) |
+| `↑` / `↓` | move between lines when multi-line; browse input history when single-line (scoped per project, last 200 entries each, kept across restarts; history from before the upgrade shows in every project) |
 | `Ctrl+V` (⌘V) / `Alt+V` | paste: text / file path (images auto `@`-referenced) / clipboard bitmap (`[Image #N]` attachment); use `Alt+V` when the terminal swallows `Ctrl+V` |
 | `Ctrl+G` | edit the input in the `$VISUAL`/`$EDITOR` external editor (`:cq` keeps the draft; prompts you to configure when unset) |
 | `Ctrl+Shift+E` (⌘⇧E) | open the **full-screen draft editor** (or click `⛶` at the end of the input line): line numbers, current line highlighted, `Enter` newline, `Ctrl+Enter` send, `Esc` collapse (draft kept); off at `/settings → 全屏草稿编辑` |
@@ -127,6 +148,7 @@ Unrecognized keys are ignored, `Esc` does nothing, clear with `Ctrl+C`/`dd`.
 | `Shift+Tab` | cycle session mode (default → plan → full access); mounted third-party permission presets follow in registry order at the end of the cycle |
 | `Shift+↑` | message selection mode (`↑/↓` move, `Enter` expand one, `Esc` exit) |
 | `Ctrl+T` (⌘T) | open the trace scene (same as `/trace`) |
+| `Alt+R` | on the launchpad, **continue the most recent session** (same as the `Continue "…"` entry; bound only while the launchpad is up, no-op when there is nothing to continue). Remappable in `/settings` |
 | `Alt+S` | one-key star (same as `/star`; the splash's star line is clickable too). Remappable in `/settings`; a short "the whale girl catches the star" celebration plays on success. Replay it any time with `DSH_TUI_STAR_MODAL=1 dsh-tui`; preview the splash star line with `DSH_TUI_STAR_LINE=1 dsh-tui` (preview env vars, ledger untouched) |
 
 ### 2.6 Mouse (fullscreen mode; drag/double-click/triple-click select-and-copy)
@@ -173,6 +195,8 @@ A session taken by another terminal shows red with `占用 pid <pid>`
 and can't be entered; it recovers after that terminal exits.
 Fixed items live in `~/.dsh-tui/session-pins.json`.
 The workspace menu has four items: edit / new here / rename / remove from list (**removes the entry only**, directory and session log stay).
+After removal, a directory with past sessions remains in the rail as "History only"; the heading counts registrations and history directories separately, and a success notice confirms the removal.
+A "History only" row offers edit and new here; rename and remove apply only to registered workspaces.
 
 **Image preview** (open by clicking `[Image #N]` in the input or a thumbnail in the transcript)
 
@@ -189,6 +213,7 @@ The workspace menu has four items: edit / new here / rename / remove from list (
 - No IDE installed/connected → skipped automatically, nothing else affected (see [vscode.md](vscode.md)).
 
 **History search (Ctrl+R)**
+Lists only inputs from the current project (the session's working directory), plus unscoped history from before the upgrade.
 `↑/↓` select · press `Ctrl+R` again or `↓` for next · `Enter` fill · `Esc`/`Ctrl+C`/`Ctrl+D` cancel
 
 **Trace scene (Ctrl+T / /trace)**
@@ -219,9 +244,78 @@ changes save automatically, `Esc` exits
 **Double-press Esc time-travel (rewind)**
 List `↑/↓` + `Enter` to confirm · confirm page `Enter` rewind / `Esc` back · only `Esc` responds while a plugin decision is pending
 
+### 2.8 Side panel
+
+`Ctrl+B` (remappable under `/settings` → `Shortcuts`) expands a panel column to the right of the
+chat: a capsule tab bar on top, the active panel in the middle, a key-hint row at the bottom, and a
+one-column seam between the two surfaces.
+
+- **Three states**: **split** (chat ≈ 68% plus the panel; `+`/`-` resize by 4 columns), **collapsed**
+  (the layout is byte-identical to before), **zoom** (the panel takes over and the chat column keeps
+  its minimum width).
+- **When it splits**: `fullscreen` plus a content width of ≥93 columns (≈97 terminal columns at the
+  default page margin); narrow terminals, inline mode and the expanded draft editor fall back —
+  `/jobs` and friends keep their full-screen panels there, while `Ctrl+B` and `/panel` do not split at all.
+- **Focus model**: one keyboard focus at a time; while the panel holds it, its frame and the seam
+  brighten together. `Ctrl+B` is three-state: closed → open and focus the panel; open but
+  chat-focused → focus the panel; panel-focused → close and return to the chat.
+- **Panel keys**: `Esc` steps back to the input (the panel stays open) · `←`/`→` or `[`/`]` switch
+  panels · `1`-`9` jump to the Nth · `z` or `Alt+Z` zoom · `+`/`-` resize (`+` widens the panel by 4 columns) · `↑`/`↓`/`PgUp`/`PgDn`
+  go to the active panel (jobs selects and scrolls with them). Keys the panel does not take never
+  reach the chat, while `Ctrl+C`/`Ctrl+D`/`Ctrl+L` and the other Ctrl combos still do.
+- **Mouse**: click the chat column to focus the chat, click the panel column to focus the panel;
+  clicking a tab on the bar switches to that panel (hover highlights it), and the `⤢` on its right
+  edge blows the active panel up to the full screen. The panel column is excluded from
+  drag-selection.
+- **Panels**: `todo` (Goals/Todos — with a split it moves here from above the input), `jobs`
+  (background jobs; clicking a job card in the transcript focuses that job here), `agents`
+  (subagent dashboard and detail: Enter opens the detail, Esc steps back), `companion`
+  (the pet — off by default; add `companion` to `sidePanel.panels` to enable: its mood follows
+  the session, click for a heart, Enter to poke; the `dsh-tui.companion.skin` setting offers
+  deepy (default, the fan-made deepy whale kit) or whale), `info` (model, effort, mode,
+  permissions, context usage, cache hit, tokens, TPS, spend, working dir, session title and id),
+  `trajectory` (the session's wake band + ledger + inspector: ↑/↓ select, Enter expands, Tab
+  switches to the hotspot view — ←/→ always stay the host's panel-cycling keys), `workspace`
+  (working-directory overview; Enter opens the full workspace home).
+- **Pet (companion) details**: the pet sits at the BOTTOM of the panel with a status area above
+  it (mood · subagent/session counts · current animation). Interactions: clicking its left/right
+  half pokes it (poke-left/right), three rapid clicks tickle it, **holding and dragging walks it
+  around the whole panel with the pointer (release springs it back home)**, hovering makes it look
+  toward the pointer; Enter also pokes. Job-done / interrupted notices are spoken by a speech
+  bubble above its head — while the pet panel is the ACTIVE panel the toast above the input box
+  does NOT repeat it (toasts return on any other panel; error-colored notices always toast). Moods
+  are debounced: fast tool calls no longer flicker the animation (leaving the working state takes
+  ~1.5s to settle; approvals and errors still preempt instantly). Subagent/session counts switch
+  the music / conducting / building ensemble animations. When the column is too narrow even for
+  the compact form the pet hides, leaving one line: "So cramped! {{name}} is hiding for now~".
+  The `dsh-tui.companion.skin` setting picks one of three: `deepy` (default, the fan-made whale
+  kit), `whaleGirl` (the whale-girl sticker pack — 22 animations that react to pokes, tickles and
+  drags, plus its own hearts and thumbs-up) or `whale` (the splash's pixel whale). **On terminals
+  with an image protocol (kitty/sixel) whaleGirl renders at native 240px with all 267 frames**
+  (transparent float, decoded on demand); without one it falls back to the character-art form.
+
+| Subcommand | Effect |
+|---|---|
+| `/panel` | Open the panel picker (↑↓ to choose, Enter opens and focuses) |
+| `/panel toggle` | Really open / really close (closing returns focus to the chat) |
+| `/panel focus` | Open and focus the panel |
+| `/panel zoom` | Open and zoom the active panel |
+| `/panel <id>` | Open a panel by id: `todo` / `info` / `trajectory` / `jobs` / `agents` / `workspace` / `companion` (completion lists the enabled ids) |
+
+- Views that used to be full-screen-only now also live in the sidebar: with the split up and the
+  matching panel enabled, `Ctrl+T` / `/trace` open the trajectory panel and `/home` opens the
+  workspace panel; the `⤢` on the panel bar puts them back on the whole screen (`⤢` is the mouse
+  path — the keyboard equivalents are each view's own full-screen shortcut: `Ctrl+T` trajectory,
+  `Ctrl+A` agents, `/jobs` jobs, `/home` the workspace home).
+- Settings: the **Side panel** group in `/settings`, or
+  `dsh-tui.sidePanel.{splitEnabled,open,ratio,panels}` (see the
+  [configuration reference](configuration.en.md#tui-configuration)).
+- **tmux users**: `Ctrl+B` is tmux's default prefix, so tmux swallows it before the TUI sees it —
+  remap `sidePanel` to another combo (for example `alt+b`) under `/settings` → `Shortcuts`.
+
 ## 3. Command reference
 
-The command menu = built-in commands (50) + DSH registry commands (`/plan` `/goal` etc.) + the skill catalog
+The command menu = built-in commands (58, aliases included) + DSH registry commands (`/plan` `/goal` etc.) + the skill catalog
 (completion only, hidden from the `/help` menu). `/lang` switches the UI and command descriptions between English and Chinese.
 
 ### 3.1 Session
@@ -260,6 +354,7 @@ The command menu = built-in commands (50) + DSH registry commands (`/plan` `/goa
 | `/agents` | none | subagent list for this session |
 | `/jobs` | none | background-task panel: status/runtime/exit-code tracking, `↑/↓` select, `k` stop; while open, `Esc` **closes only the panel** and won't interrupt the turn (close the panel first, then `Ctrl+C`) |
 | `/settings` | none | open the plugin settings editor (namespace read/edit) |
+| `/setup` | none | re-run the first-run guide (API key / language+theme / model+workspace / shortcuts) — same screen as the very first launch |
 | `/help` | none | shortcut + command help menu (`?` entry) |
 
 ### 3.3 Model / display
@@ -269,13 +364,14 @@ The command menu = built-in commands (50) + DSH registry commands (`/plan` `/goa
 | `/model` | none | model selector; **switching = fork the session** (history kept, only routing changes; a session nobody has typed into records no branch, keeping automatic titles for its first prompt), choice persisted to `~/.dsh-tui/model.json` |
 | `/effort` | `status` / `<id>` | reasoning effort: no-arg slider (`←/→` adjust); `status` current level; `<id>` set directly. Persisted to `~/.dsh-tui/effort.json`; new-session start level follows /settings `effortDefault` (§5.3) |
 | `/thinking` | none | extended-thinking display toggle (thinking expands item by item while streaming) |
-| `/tokens` | none | token usage + context percentage |
+| `/tokens` | none | three separate figures, never two different quantities side by side: **this request**'s upload (input + cache read + cache write — the harness's four buckets are disjoint), the **session totals** (uncached input / output / cache read / cache write), and **context occupancy** |
 | `/activity` | `frames <名>` / `status` | working-status animation: no-arg selector, `frames <名>` sets directly (includes `random`), default `moon8`. Persisted to `~/.dsh-tui/working-activity.json` |
 | `/preset` | `<id>` / `status` | agent preset: `standard` / `ptc` (old 0.1.1 name `code`) / `minimal` / `cordis` / **Liangshen mode `liangshen`**; **cannot switch an already-started session**. Persisted to `~/.dsh-tui/agent-preset.json` |
 | `/theme` | `<名字>` / `status` | theme: no-arg selector; `<名字>` switch directly; `status` current theme (auto appends the OSC 11 result). Persisted to `~/.dsh-tui/theme.json` |
 | `/color` | no-arg / `<名>` / `status` / `reset` | session accent color: no-arg opens the palette (`↑/↓` pick, `Enter` apply); `<名>` set directly; `reset` back to default. Colors `red/orange/yellow/green/blue/purple/pink/cyan`, saved per session |
 | `/lang` | `en` / `zh` / `status` | hot-switch UI language. Priority: `DSH_TUI_LANG` > profile config (legacy: settings.yaml user layer > cordis.yml) > persisted |
 | `/vim` | none | **vim editing mode toggle** (see §2.4): input switches to vim keys, per-session, not persisted |
+| `/panel` | `toggle` / `focus` / `zoom` / `<panel id>` | side panel: toggle / focus / zoom / switch panels; states and subcommands in §2.8 |
 
 ### 3.4 Account / policy / extensions
 
@@ -367,7 +463,7 @@ Full-screen view of the whole session timeline (doesn't pollute scrollback); key
 - `/model`: selector. **Switching = fork the session** (history kept, only routing changes, the old session stays in `/resume`);
   persisted to `~/.dsh-tui/model.json`.
 - Switching is rejected mid-turn.
-- `/preset` options: `standard` (default full features), `ptc`, `minimal` (the kernel's Minimal preset: one persistent-shell tool only, no compaction, no plan mode),
+- `/preset` options: `standard` (default full features), `ptc`, `minimal` (the kernel's Minimal preset: one persistent-shell tool only, no compaction, no plan mode — and therefore no compaction and no tool-result pruning, so a long session can hit the context limit and `/compact` plus questions are unavailable; Help and `/` completion mark the command, and entering the preset says so once),
   `cordis`, `liangshen` (Liangshen mode).
   **A session that already has messages can't switch** (blank-only): the choice only becomes the default for the next `/new`.
   This is a **kernel agent preset** deciding which tools the model can use; `/settings → Minimal UI` (极简界面) on the display side is unrelated.
@@ -389,7 +485,7 @@ Keys are in §2.7. Key points:
 - `/skills` browses the skill catalog; a direct-call skill joins the command menu as `/name` (dsh-TUI ships no generic skills).
 - `/plan` `/goal` `/feedback` `/permission` come from the DSH registry, merged into the `/` menu.
 - **Goals/Todos panel appears automatically**: when the model writes a goal/todo, it renders above the input
-  (🎯 goal + phase badge + tree todo), no action needed.
+  (🎯 goal + phase badge + tree todo), no action needed; with a split it moves to the `todo` panel on the right (see §2.8).
 
 ### 4.9 MCP / Workspace / other
 
@@ -445,12 +541,18 @@ An empty session shows the whale logo area at the top (scrolls away with the con
 **Row 1 — context segment bar** (`/settings → statusBar.contextBar`, default on)
 
 - Colored by content type (system / prompt / assistant / thinking / tools).
+- Segment token counts are a **local estimate** (CJK/full-width ≈1.4 chars/token, ASCII ≈4, other scripts ≈2): they describe what the bar is made of and **never** feed the occupancy total — that comes from the ctx reading below.
 - The only text on the bar is the right-edge reading `13k/64k 19.5%` (narrow screens show only `19.5%`).
 - The reading colors by usage: <80% gray-blue, **≥80% amber, ≥95% red**.
 - Hover the whole bar for the legend: color block + name + token count (narrow screens shorten the names).
 
 **Row 2 — status field row** (each field toggled separately, see `/settings`)
-- left group: model → TPS → thinking → mode → ctx → cache hit rate → tokens (`1.2k→340` input→output) →
+- left group: model → TPS → thinking → mode → ctx (**context occupancy** `19.5% (13k/64k)`: the SAME
+  value the segmented bar, the working line's pressure prefix, `/tokens`, `/status` and the context-low
+  warning read, sourced from the harness's own `contextPressure` projection — `projectedTokens ??
+  pressureTokens`, i.e. what the NEXT request would occupy, so a compaction or a rejected request shows
+  up immediately instead of waiting for one successful request; a bare `cordis.yml` composition without
+  the meter falls back to the last request's billed usage) → cache hit rate → tokens (`1.2k→340` input→output) →
   cost (`≈¥0.05 谷`, **a session estimate** that includes subagent usage, priced per
   each agent's model × peak/idle × cache components; hover splits main ¥ / subagent ¥ / unpriced N tok;
   unofficial or unlisted models show tokens only and are marked unpriced;
@@ -462,7 +564,7 @@ An empty session shows the whale logo area at the top (scrolls away with the con
 
 **Row 3 — hints / working activity + mini trace bar**
 - Idle shows `? for shortcuts`, running `esc to interrupt`, selecting `esc to return to input`.
-- Idle also shows the working-activity animation (`statusBar.activity` on), context ≥80% amber, ≥95% red.
+- Idle also shows the working-activity animation (`statusBar.activity` on), context ≥80% amber, ≥95% red (the same occupancy reading as the ctx field).
 - Right-side **mini trace bar MiniWake** (`statusBar.trajectory`, default off): session projected as density glyphs, color per channel, failures red;
   degrades/hides on narrow screens.
 
@@ -473,7 +575,7 @@ speed **≥50 green / ≥20 yellow / <20 red**.
 
 `/settings` opens the plugin settings editor; **changes save automatically**, `Esc` exits directly.
 On 0.1.7 the dsh-tui block writes to the active profile's `cordis.patch.yml`; older hosts use the settings.yaml user layer. Most settings apply live; fullscreen and image-preview need `/restart`.
-Common items below, full list on the /settings screen. Most topics (**Appearance**, **Splash**, **Conversation**, **Rendering**) lay their fields right on the root page under small headers — no subpage round-trip to tweak them; only the genuinely block-like domains — **Formula**, **Status bar**, **Shortcuts** — keep a subpage behind one root-page row:
+Common items below, full list on the /settings screen. Most topics (**Appearance**, **Splash**, **Conversation**, **Rendering**) lay their fields right on the root page under small headers — no subpage round-trip to tweak them; only the genuinely block-like domains — **Formula**, **Status bar**, **Side panel**, **Shortcuts** — keep a subpage behind one root-page row:
 
 | Field | Notes |
 |---|---|
@@ -488,6 +590,7 @@ Common items below, full list on the /settings screen. Most topics (**Appearance
 | whaleGirl | maid portrait (default off): swaps the header's pixel whale for the author-drawn maid as a **real raster** (Kitty/Sixel); falls back to the pixel whale without graphics support |
 | diffLayout | Edit/Write diff layout: auto (two columns ≥110 cols) / split / unified |
 | thinkingFold | thinking block: preview (2-3 line preview + folded when settled) / full (expanded to end of turn) |
+| jobGroupFold | consecutive background-job cards: auto (default — runs of 2+ group, a settled run of 3+ folds into its summary line) / always (any run of 2+ folds right away, live jobs included) / never (never folds on its own, every card stays). The group header summarizes status and total time; click it or press Ctrl+O to expand |
 | effortDefault | default reasoning effort: auto / off / low / high / max. Start level for new sessions (details below) |
 | smoothStreaming | smooth streaming output (default on): replies/thinking/tool-card text reveal at ~30fps; replay/history always direct |
 | toolBackground | tool-card background emphasis: none / subtle / strong |

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

@@ -35,17 +35,35 @@ 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、工作目录，及一行**启动提示**；
+   这一屏的头部**直接定格**——开场动画留给进入对话后的转录区顶部），
+   下面是一个**真输入框**（第一句话在这里打，**回车直接发送**）与框下一行**参数行**
+   （模型 · 思考深度 · 模式 · 权限——四段都可点，点开对话页同款选择器就地换值），
+   隔一行留白再一行**快捷入口**（第七版四格：`继续「…」`（快捷键 `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 核心心智模型
 
@@ -86,7 +104,7 @@ dsh-tui
 
 | 键 | 功能 |
 |---|---|
-| `Ctrl+R`（⌘R） | 历史消息搜索；重复按或 `↓` 到下一匹配；`Enter` 回填输入框 |
+| `Ctrl+R`（⌘R） | 历史消息搜索（只搜当前项目）；重复按或 `↓` 到下一匹配；`Enter` 回填输入框 |
 | `/`（转录态） | 会话全文搜索；`n` / `N` 跳转（仅 Ctrl+O 展开态） |
 
 ### 2.4 输入编辑
@@ -98,8 +116,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 +140,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 +185,8 @@ dsh-tui
 切换会话只是**停放**——正在跑的回合继续跑；被其他终端占用的会话标红写 `占用 pid <pid>`、点不动，对方退出后恢复。
 固定项存到 `~/.dsh-tui/session-pins.json`。
 工作区菜单四项：编辑 / 在此新建 / 重命名 / 从列表移除（**只删登记**，目录与会话日志都保留）。
+移除后，仍有历史会话的目录会以「仅历史」行留在侧栏；栏头分别统计已登记工作区与历史目录，移除成功也会显示提示。
+「仅历史」行的菜单只有编辑与在此新建；重命名、移除只适用于已登记工作区。
 
 **大图预览**（点输入框里的 `[Image #N]` 或转录缩略图打开）
 
@@ -178,6 +200,7 @@ dsh-tui
 - 没装/没连 IDE 时自动跳过、不影响其他功能（详见 [vscode.md](vscode.md)）。
 
 **历史搜索（Ctrl+R）**
+只列出当前项目（会话工作目录）的输入，外加升级前未分项目的旧历史。
 `↑/↓` 选择 · 重复 `Ctrl+R` 或 `↓` 下一项 · `Enter` 回填 · `Esc`/`Ctrl+C`/`Ctrl+D` 取消
 
 **轨迹场景（Ctrl+T / /trace）**
@@ -208,9 +231,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 组合照旧作用于聊天。
+- **鼠标**：点聊天栏把焦点给聊天，点右栏把焦点给面板；点标签栏上的标签直接切到那个面板（悬停会高亮），
+  点右端的 `⤢` 把当前面板放大成整屏；右栏不参与拖拽选字。
+- **面板**：`todo`（Goals/Todos，分栏时从输入框上方迁到这里）、`jobs`（后台任务，点转录里的任务卡
+  会直接定位到该任务）、`agents`（子代理 Dashboard 与详情：Enter 进详情、Esc 逐级返回）、`companion`
+   （宠物，默认不启用——在 `sidePanel.panels` 加入 `companion` 开启：跟随会话状态换心情动画，点击
+   比爱心、Enter 戳一戳；皮肤 `dsh-tui.companion.skin` 可选 deepy（默认，非官方粉丝作品 deepy
+   小鲸鱼）或 whale）、`info`（信息栏：模型 / 思考深度 / 工作模式 / 权限 / 上下文占用 / 缓存命中 /
+  Token / TPS / 消耗 / 工作目录 / 会话标题与 ID）、`trajectory`（会话轨迹：唤醒带 + 账本 + 检视器，
+  ↑/↓ 选择、Enter 展开、Tab 切热点视图；←/→ 恒归侧栏切面板，Tab 才是切视图）、`workspace`
+  （工作目录/工作区总览，Enter 打开整屏工作区主页）。
+- **宠物（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` / `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 会话
@@ -249,6 +324,7 @@ dsh-tui
 | `/agents` | 无 | 本会话子代理列表 |
 | `/jobs` | 无 | 后台任务面板：状态/运行时长/退出码实时跟踪，`↑/↓` 选择、`k` 停止；面板打开时 `Esc` **只关面板**不打断回合（想中断先关面板再 `Ctrl+C`） |
 | `/settings` | 无 | 打开插件设置编辑器（命名空间读取/编辑） |
+| `/setup` | 无 | 重跑首次引导向导（API Key / 语言主题 / 模型工作区 / 快捷键），与首次启动是同一个界面 |
 | `/help` | 无 | 快捷键 + 命令帮助菜单（`?` 入口） |
 
 ### 3.3 模型 / 显示
@@ -258,13 +334,14 @@ dsh-tui
 | `/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 账号 / 策略 / 扩展
 
@@ -355,7 +432,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 +453,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 / 其他
 
@@ -426,12 +503,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 +521,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 +532,7 @@ dsh-TUI 不预装通用技能；`/skills` 浏览 DSH 发现的技能，可直调
 
 `/settings` 打开插件设置编辑器；**改动自动保存**，`Esc` 直接退出。
 dsh-tui 自身区块在 0.1.7 写入当前 profile 的 `cordis.patch.yml`，旧版写入 settings.yaml 用户层。多数设置实时生效；全屏和图片预览开关需 `/restart`。
-下表为常用项，完整列表见 /settings 屏。多数主题（**外观与布局** / **开屏与吉祥物** / **对话与输入** / **图表与图片**）的字段直接平铺在根页的小标题下，改起来不用进出子页；只有真正成块的域——**公式设置** / **底栏设置** / **快捷键**——保留子页，根页一行入口点进去：
+下表为常用项，完整列表见 /settings 屏。多数主题（**外观与布局** / **开屏与吉祥物** / **对话与输入** / **图表与图片**）的字段直接平铺在根页的小标题下，改起来不用进出子页；只有真正成块的域——**公式设置** / **底栏设置** / **侧栏** / **快捷键**——保留子页，根页一行入口点进去：
 
 | 字段 | 说明 |
 |---|---|
@@ -468,6 +547,7 @@ dsh-tui 自身区块在 0.1.7 写入当前 profile 的 `cordis.patch.yml`，旧
 | whaleGirl | 女仆娘立绘（默认关）：标题像素鲸鱼换成作者绘制的女仆娘**真图**（Kitty/Sixel 图像协议）；不支持时回落像素鲸鱼 |
 | diffLayout | Edit/Write diff 布局：auto（≥110 列双栏）/ split / unified |
 | thinkingFold | 思考块：preview（流式 2-3 行预览 + 落定折叠）/ full（展开到轮末） |
+| jobGroupFold | 连续的后台任务卡：auto（默认，≥2 张成组；整组落定且 ≥3 张时折叠成汇总行）/ always（≥2 张立即折叠，含在跑的任务）/ never（从不自动折叠，每张卡都留着）。组头一行汇总状态与合计时长，点组头或 Ctrl+O 展开 |
 | effortDefault | 默认推理强度：auto / off / low / high / max。新会话的起始档位（细节见下） |
 | smoothStreaming | 流式平滑输出（默认开）：回复/思考/工具卡正文按 ~30fps 匀速揭示；回放/历史完整直出 |
 | toolBackground | 工具卡背景强调：none / subtle / strong |