dsh-code 1.0.7 → 1.2.0

package/README.en.md

@@ -7,7 +7,7 @@ English | [中文](README.md)
 <p align="center"><img alt="Typing SVG" src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&amp;weight=500&amp;size=22&amp;duration=4000&amp;pause=700&amp;color=4176E6&amp;center=true&amp;vCenter=true&amp;width=680&amp;lines=DeepSeek+Harness+Code;Terminal+Coding+Interface+for+the+DSH+Core"></p>
 <p align="center">
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek-Harness-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh"><img alt="dsh version" src="https://img.shields.io/badge/dsh-0.1.5--rc.1-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh"><img alt="dsh version" src="https://img.shields.io/badge/dsh-0.1.5--rc.2-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
   <a href="https://github.com/UNLINEARITY/dsh-code/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/UNLINEARITY/dsh-code?label=Stars&amp;style=for-the-badge&amp;logo=github&amp;logoColor=white&amp;color=4176E6&amp;labelColor=1c1917"></a>
   <a href="https://www.npmjs.com/package/dsh-code"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-code?label=npm&amp;style=for-the-badge&amp;logo=npm&amp;color=cb3837&amp;labelColor=1c1917"></a>
   <a href="https://github.com/UNLINEARITY/dsh-code/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/UNLINEARITY/dsh-code?label=License&amp;style=for-the-badge&amp;logo=opensourceinitiative&amp;color=4176E6&amp;labelColor=1c1917"></a>
@@ -27,17 +27,27 @@ Requires Node `^22.19 || >=24` and the preview `dsh` CLI (current release line:
 
 ### 1. Install and update
 
-Use the same commands for the initial installation and subsequent updates:
+Install from npm (recommended). `/update` and `deepseek update --apply` both work afterwards: they check npm for a newer version and walk you through the upgrade.
 
 ```sh
-npm install -g @deepseek-ai/dsh@0.1.5-rc.2 dsh-code@1.0.7
-npm install -g pnpm
-dsh plugin --profile cli add dsh-code@1.0.7
+npm install -g @deepseek-ai/dsh@0.1.5-rc.2 pnpm
+npm install -g dsh-code@1.2.0
+dsh plugin --profile cli add dsh-code@1.2.0
 ```
 
-> Note: pnpm ignores packages published less than 24 hours ago, so use the exact version `dsh-code@1.0.7` on release day; the version may be omitted after 24 hours. npm installation is not affected.
+When npm is unreachable (restricted network, a mirror outage), install the GitHub Release tarball instead. CI builds it on every tag and attaches it to the release; lib is prebuilt, so the installing machine needs no toolchain:
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.5-rc.2 pnpm
+npm install -g https://github.com/unlinearity/dsh-code/releases/download/1.2.0/dsh-code-1.2.0.tgz
+dsh plugin --profile cli add https://github.com/unlinearity/dsh-code/releases/download/1.2.0/dsh-code-1.2.0.tgz
+```
+
+> npm script prompts: npm 11.6+ may print `npm warn install-scripts` during a global install (unapproved build scripts for node-pty, koffi, and friends). The host ships prebuilt artifacts, so common platforms can ignore the warning; if a native-module error appears after installing, follow npm's own hint and rerun with `npm install -g --allow-scripts=<package list>`.
 >
-> Version alignment: dsh-code targets dsh `0.1.5-rc.2`, with every Harness dependency pinned exactly to `0.1.5-rc.2`. Keep the global dsh CLI and dsh-code aligned instead of mixing release candidates; the legacy `code` preset id maps to its renamed `ptc` automatically.
+> Version alignment: dsh-code targets dsh `0.1.5-rc.2`, with every Harness dependency pinned exactly to `0.1.5-rc.2`. A local `link:` mount should be rebuilt with `git pull && pnpm install && pnpm build`; do not run the updater against a checkout.
+>
+> A GitHub tarball install can lead npm by one release (until the registry carries the same version). The updater only reads npm, so it reports that this install is newer and refuses to downgrade, instead of claiming everything is up to date; use `/update` once npm catches up.
 
 ### 2. Launch commands
 
@@ -53,7 +63,7 @@ dsh-code
 
 > DeepSeek Harness is still a developer preview and may introduce compatibility-breaking changes. DSH-Code will continue to track the evolution of its plugin interfaces.
 
-For installation, native-module, and plugin-loading issues, see [Troubleshooting](docs/problems.md).
+For installation, native-module, and plugin-loading issues, run `deepseek doctor` first, then see [Troubleshooting](docs/problems.md).
 
 ## 3. Core features and usage
 
@@ -65,8 +75,9 @@ DSH-Code brings DSH Agents, models, tools, and durable sessions directly into th
 - Create a new work branch from a historical point with `/fork` while preserving the original session
 - Search history by current directory, update time, and session scope
 - Recall input history with Up/Down (typed slash commands included), or search previous prompts and commands with `/history`
-- Use persistent titles, Markdown export, context occupancy, token, cache, TTFT, and elapsed-time metrics
-- Restore the session's Agent Preset and model selection when resuming it
+- Use persistent titles, Markdown export, context occupancy, token, cache, TTFT, and elapsed-time metrics; `/usage` reports the harness token meter's four disjoint buckets, the totals merged by model, and a per-turn breakdown
+- The status bar's `in` counts only uncached input, and `cache` shows both the cache-read volume and the hit share — together they are the billed prompt side
+- Restore the session's Agent Preset, model selection, and subagent list when resuming it; the welcome header shows both the dsh and dsh-code versions
 
 <p align="center"><img src="docs/pictures/dsh-3.png" width="95%" alt="Searchable session resume picker"></p>
 
@@ -104,18 +115,41 @@ Levels above `high` include `xhigh`, `x-high`, `very-high`, `max`, `maximum`, an
 
 - Use `@` to reference workspace files or existing sessions; selecting PNG, JPEG, WebP, or GIF files attaches the real image automatically
 - Attach images through the initial prompt, repeated `--image` arguments, or by dragging one or more images into the terminal
-- Inspect changes by file with `/diff`, and start a read-only code review with `/review`
+- Inspect changes by file with `/diff`, and start a read-only code review with `/review` (a range picker; diffs use full-row green/red)
+- `run_code` lists nested tool calls as they run; workflow runs list their member agents until they finish
 - Copy the latest complete response with `/copy`, and inspect full history and tool details with Ctrl+O
 - Handle tool approvals, structured questions, plan reviews, multiple selections, and custom answers
 - Control what the Agent may do with permission Presets and sandboxes; add instructions or interrupt while a task is running
 
-### 5. Commands and key bindings
+### 5. Queued and steered messages
+
+While a turn is running you can keep typing. There are two ways to send what you type:
+
+- **Queue** — it waits until the turn finishes and then runs as a new turn. Use it for "do this once you are done with that".
+- **Steer** — it reaches the model before the next step of the running turn, as part of that request. Use it when the work has gone the wrong way and you want it corrected now.
+
+The difference is **when the model sees it**: a queued message is read once the turn has finished, a steered one before the turn makes its next move.
+
+How to send each way:
+
+- Press `Tab` on an empty composer to switch between them. The prompt glyph (`❯` / `↳`), the placeholder text, and the notice shown on switching all say which one is selected. With text in the box, `Tab` still completes commands and references.
+- `/queue` opens the queue panel: press `Enter` on a message to send it as steering instead, `e` to edit its text (attachments are kept as they are), or `d` to remove it.
+- Press `Delete` on an empty composer to cancel the newest queued message.
+- Pressing `Esc` to cancel the turn keeps **queued messages and sends them next**, while steered messages are dropped with the turn.
+
+Every prompt in the transcript is a full-width coloured row, and the colour says how it was sent: the theme's bright brand colour for an ordinary message, its warning colour for a queued one, and its third accent for a steered one, each labelled with "queued" or "steered". The colour is computed from the theme, so switching themes or rerolling rainbow changes it too.
+
+A message counts as queued or steered only when a turn was **already running** at the moment you sent it. A message sent while idle is an ordinary one even if the composer is set to steer, because it starts a new turn straight away.
+
+See [Queued and steered messages](docs/message-queue.md) for the queue behaviour, the order the upstream queues are read in, and the colour values per theme.
+
+### 6. Commands and key bindings
 
 Start the TUI:
 
 ```sh
 dsh --profile cli                    # create a standard session
-dsh --profile cli --mode code        # start with the specified Agent Preset
+dsh --profile cli --mode ptc         # start with the specified Agent Preset (standard/minimal/cordis/ptc)
 dsh --profile cli --continue         # resume the latest session for the current directory
 dsh --profile cli --resume abc123    # resume by id or unique prefix
 dsh --profile cli --session my-id    # create a session with an explicit id
@@ -129,6 +163,7 @@ The following built-in commands are available inside the TUI. Additional Harness
 | --- | --- |
 | `/new [preset]` | Create a session, optionally selecting an Agent Preset |
 | `/resume [id\|prefix]` | Search for or restore an existing session |
+| `/search [query]` | Full-text search across persisted sessions (Enter resumes the hit) |
 | `/resume cancel` | Cancel a pending session switch |
 | `/fork [event-seq]` | Create a session branch from the latest completed turn or a specified event position |
 | `/delete [id\|prefix]` | Delete a session and its subagent sessions |
@@ -152,8 +187,10 @@ The following built-in commands are available inside the TUI. Additional Harness
 | Command | Purpose |
 | --- | --- |
 | `/diff [--staged\|ref]` | Inspect the working-tree, staged, or specified-ref Git diff by file |
-| `/review [--staged\|ref]` | Review Git changes with read-only permissions |
+| `/review [note]` | Bare /review opens a candidate picker (uncommitted changes / pick a branch / pick a commit / custom focus); any argument becomes a review note over the uncommitted diff (`/review in Chinese`). The diff is pasted into the current session under read-only permissions, and findings arrive with P0-P3 priorities and file anchors |
 | `/todos` | View the complete todo list for the current session |
+| `/queue` | See the messages waiting for the next turn: enter sends one as steering instead, `e` edits its text, `d` removes it; `↑↓`/`PageUp`/`PageDown`/`g`/`G` move |
+| `/usage` | See this session's token usage: the four disjoint buckets (uncached input, cache write, cache read, output), the totals merged by model, and the per-turn breakdown |
 | `/agents` | View subagent sessions created by the current session |
 | `/jobs` | View background jobs and their runtime status |
 | `/schedule` | Inspect active reminders (created through the model's schedule tools; read-only, overdue first) |
@@ -164,10 +201,12 @@ The following built-in commands are available inside the TUI. Additional Harness
 | Command | Purpose |
 | --- | --- |
 | `/plugin [query]` | Inspect loaded extensions and their status |
-| `/update` | One aligned upgrade: pins the global Harness host to the line the target release declares in its peers, moves dsh-code, the host, and profile companion plugins together, shows the full plan and refusal reasons before confirming, and prompts a restart when done |
+| `/update` | Checks npm for a newer version and confirms the upgrade. A GitHub tarball install can lead npm, in which case it says so and refuses to downgrade |
 | `/statusline` | Select the items displayed in the status bar |
 | `/vscode-keys` | Pass Ctrl+R through VS Code-family terminals (idempotent user-level keybindings.json write) |
-| `/theme` | Switch the terminal color theme |
+| `/theme` | Switch colors: `dark` / `light` / `prismatic` / `rainbow` / `auto` |
+| `/rainbow [seed]` | Reroll or pin the rainbow theme seed; a bare `/rainbow` rolls a new seed and switches to rainbow |
+| `/language [en\|zh]` | Switch the interface language, default English; model prompts and factual status values stay in English |
 | `/animation` | Toggle timed animations (shimmer/chase/blink/switch wave), `/animation [on\|off]` |
 | `/help` | View key bindings, built-in commands, Harness commands, and user skills |
 | `/quit` | Exit DSH-Code |
@@ -177,17 +216,18 @@ The following built-in commands are available inside the TUI. Additional Harness
 | Action | Purpose |
 | --- | --- |
 | `Enter` | Submit the current input |
+| `Ctrl+J` / `Alt+Enter` | Insert a newline in the composer (with the enhanced keyboard protocol, `Shift+Enter` / `Ctrl+Enter` work too) |
 | `Up` / `Down` | Recall the previous or next input-history entry |
-| `Tab` | Complete commands, skills, or `@` references |
+| `Tab` | Complete commands, skills, or `@` references; on an empty composer, switch the next message between queue and steer |
 | `@` | Reference workspace files or existing sessions; image files are sent as attachments |
-| `Ctrl+O` | Inspect full history and tool details |
+| `Ctrl+O` | Inspect full history and tool details, with a kind label on each entry (user prompt / reply / tool call, and so on) |
 | `Ctrl/Alt+R` | Fold or expand model reasoning; run /vscode-keys first in VS Code-family terminals to pass Ctrl+R through |
-| `Shift+Tab` | Cycle through permission Presets |
-| `Delete` | Cancel the newest queued message when the composer is empty |
+| `Shift+Tab` | Cycle permission Presets, and the plan station when `/plan` is available |
+| `Delete` | Cancel the newest queued message when the composer is empty (steering is not in the queue; press `Esc` to end the turn instead) |
 | `Ctrl+K` | Delete from the cursor to the end of the line |
 | `Ctrl+U` | Clear the current input line |
 | `Ctrl+A` / `Ctrl+E` | Move to the beginning or end of the current line |
-| `Esc` | Close the current menu or interrupt the running turn |
+| `Esc` | Close the current menu or interrupt the running turn; queued messages are kept and sent next, steered ones are dropped with the turn |
 | `Ctrl+C` | Cancel a task, clear the input, or exit, depending on the current state |
 | `Ctrl+D` | Exit DSH-Code |
 
@@ -238,8 +278,8 @@ The following official plugins are installed but opt-in (append rows in the user
         config:
           configPath: C:/Users/you/.claude/hooks.json
   ```
-- **LSP navigation**: the composition carries `lsp` / `lsp-stdio` / `tool-lsp` rows in a disabled state — language-server binaries resolve at mount, and a missing binary would fail the whole composition boot. Flip the three rows to `disabled: false` in the user layer and configure `lsp-stdio` `servers` (extension to language to server command); the model then gets the `lsp` tool (goToDefinition / findReferences / goToImplementation / hover).
-- **Persistent terminals**: the PTY service and platform backends (pwsh dialect on Windows, bash on POSIX) mount by default, but the six model tools `terminal_open` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` / `terminal_list` ship DISABLED — enabling them grants shell capability to every session, which the preset layer is supposed to gate, so deployments opt in explicitly. Enable in the user layer:
+- **LSP navigation**: the composition carries `lsp` / `lsp-stdio` / `tool-lsp` rows in a disabled state — language-server binaries resolve at mount, and a missing binary would fail the whole composition boot. The host CLI does not bundle the three packages: install them into the profile first (`dsh plugin --profile cli add @deepseek-ai/dsh-lsp @deepseek-ai/dsh-lsp-stdio @deepseek-ai/dsh-tool-lsp`), then flip the three rows to `disabled: false` in the user layer and configure `lsp-stdio` `servers` (extension to language to server command); the model then gets the `lsp` tool (goToDefinition / findReferences / goToImplementation / hover).
+- **Persistent terminals**: the PTY service and platform backends (pwsh dialect on Windows, bash on POSIX) mount by default, but the six model tools `terminal_open` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` / `terminal_list` ship DISABLED — enabling them grants shell capability to every session, which the preset layer is supposed to gate, so deployments opt in explicitly. `@deepseek-ai/dsh-tool-terminal` is likewise not bundled by the host: run `dsh plugin --profile cli add @deepseek-ai/dsh-tool-terminal` first, then enable in the user layer:
   ```yaml
   - id: tool-terminal
     disabled: false
@@ -287,12 +327,18 @@ dsh profile
 
 ```sh
 pnpm install
+pnpm lint            # type-aware ESLint over src, tests, scripts, and the root configs
+pnpm typecheck       # the build project (src)
+pnpm typecheck:tests # the spec suite and scripts
 pnpm test
-pnpm typecheck
+pnpm test:coverage   # coverage report (reporting only, no threshold)
 pnpm build
+pnpm verify          # lint + both typechecks + tests in one pass
 pnpm run gen:whale   # regenerate src/whale-glyph.ts from the vendored logo path
 ```
 
+`tsconfig.test.json` puts the specs inside a TypeScript project, so a fixture that drifts from the interface it fakes fails `pnpm typecheck:tests` instead of surfacing (or not) at runtime.
+
 The whale glyph is generated from the DeepSeek FishLogo geometry vendored in `scripts/fish-logo.ts` (source: DeepSeek Harness, MIT).
 
 ### 1. Source development installation

package/README.md

@@ -7,7 +7,7 @@
 <p align="center"><img alt="Typing SVG" src="https://readme-typing-svg.herokuapp.com?font=JetBrains+Mono&amp;weight=500&amp;size=22&amp;duration=4000&amp;pause=700&amp;color=4176E6&amp;center=true&amp;vCenter=true&amp;width=680&amp;lines=DeepSeek+Harness+Code;DSH+%E5%86%85%E6%A0%B8%E7%9A%84%E7%BB%88%E7%AB%AF%E7%BC%96%E7%A0%81%E7%95%8C%E9%9D%A2"></p>
 <p align="center">
   <a href="https://github.com/deepseek-ai/deepseek-harness"><img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek-Harness-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
-  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh"><img alt="dsh version" src="https://img.shields.io/badge/dsh-0.1.5--rc.1-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh"><img alt="dsh version" src="https://img.shields.io/badge/dsh-0.1.5--rc.2-4176E6?style=for-the-badge&amp;logo=deepseek&amp;logoColor=white&amp;labelColor=1c1917"></a>
   <a href="https://github.com/UNLINEARITY/dsh-code/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/UNLINEARITY/dsh-code?label=Stars&amp;style=for-the-badge&amp;logo=github&amp;logoColor=white&amp;color=4176E6&amp;labelColor=1c1917"></a>
   <a href="https://www.npmjs.com/package/dsh-code"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-code?label=npm&amp;style=for-the-badge&amp;logo=npm&amp;color=cb3837&amp;labelColor=1c1917"></a>
   <a href="https://github.com/UNLINEARITY/dsh-code/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/UNLINEARITY/dsh-code?label=License&amp;style=for-the-badge&amp;logo=opensourceinitiative&amp;color=4176E6&amp;labelColor=1c1917"></a>
@@ -29,19 +29,29 @@ DeepSeek Harness 将模型、工具、存储、策略和界面作为插件，通
 
 ### 1. 安装与更新
 
-初次安装和更新使用同一组指令：
+从 npm 安装（推荐）。装好后 `/update` 和 `deepseek update --apply` 都能用：它们查询 npm 上的新版本，确认后按提示升级。
 
 ```sh
-npm install -g @deepseek-ai/dsh@0.1.5-rc.2 dsh-code@1.0.7
-npm install -g pnpm
-dsh plugin --profile cli add dsh-code@1.0.7
+npm install -g @deepseek-ai/dsh@0.1.5-rc.2 pnpm
+npm install -g dsh-code@1.2.0
+dsh plugin --profile cli add dsh-code@1.2.0
 ```
 
-> 提示：pnpm 会忽略发布不足 24 小时的包，因此发布首日请使用精确版本 `dsh-code@1.0.7`；24 小时后可省略版本号。npm 安装不受此限制。
+npm 不可达时（网络受限、镜像临时故障），改用 GitHub Release tarball。每次打 tag 由 CI 构建并挂到 Release，lib 已预构建，安装机不需要工具链：
+
+```sh
+npm install -g @deepseek-ai/dsh@0.1.5-rc.2 pnpm
+npm install -g https://github.com/unlinearity/dsh-code/releases/download/1.2.0/dsh-code-1.2.0.tgz
+dsh plugin --profile cli add https://github.com/unlinearity/dsh-code/releases/download/1.2.0/dsh-code-1.2.0.tgz
+```
+
+> npm 脚本提示：npm 11.6+ 可能在全局安装时提示 `npm warn install-scripts`（node-pty、koffi 等原生依赖的构建脚本未获批准）。宿主随包自带预编译产物，常规平台可直接忽略；若安装后出现原生模块报错，按 npm 提示执行 `npm install -g --allow-scripts=<包名列表>` 后重装。
 >
-> 版本对齐：dsh-code 面向 dsh `0.1.5-rc.2` 构建，全部 Harness 依赖均精确锁定为 `0.1.5-rc.2`。已安装的用户运行 `deepseek update --apply` 即可按同一条版本线一起升级全局宿主与 cli profile 中的插件，本地开发挂载（`link:`）不受影响。
+> 版本对齐：dsh-code 面向 dsh `0.1.5-rc.2` 构建，全部 Harness 依赖均精确锁定为 `0.1.5-rc.2`。本地 `link:` 挂载请先 `git pull && pnpm install && pnpm build`，不要对开发挂载跑更新器。
 >
 > 升级说明：旧会话与旧参数中记录的 `code` 预设会自动映射到上游已改名的 `ptc`，无需手动迁移。会话日志读取端随上游升级到格式 v3：旧格式日志在读取时由内核自动迁移，磁盘上的原始文件保持不变。
+>
+> 从 GitHub tarball 装的版本可能领先 npm 一步（npm 上还没同步这个版本时）。更新器只认 npm，这种情况会写明「新于 npm，不降级」而不是「已是最新」；等 npm 同步后再用 `/update`。
 
 ### 2. 启动指令
 
@@ -57,7 +67,7 @@ dsh-code
 
 > DeepSeek Harness 目前仍处于 developer preview，可能出现破坏兼容性的变化；DSH-Code 会持续跟随其插件接口演进。
 
-安装、原生模块和插件加载问题，请查看[常见问题与排障](docs/problems.md)。
+安装、原生模块和插件加载问题，请先运行 `deepseek doctor` 自检，更多排查见[常见问题与排障](docs/problems.md)。
 
 ## 三、核心功能与使用方式
 
@@ -69,8 +79,9 @@ DSH-Code 的重点是让 DSH 的 Agent、模型、工具和持久会话可以直
 - 使用 `/fork` 从历史节点创建新的工作分支，同时保留原会话
 - 按当前目录、更新时间和会话范围搜索历史记录
 - 使用 Up/Down 召回输入历史（含 / 指令），或通过 `/history` 搜索过去的提示词与指令
-- 支持持久标题、Markdown 导出、上下文占用、token、缓存、TTFT 和耗时统计
-- 恢复会话时同步恢复该会话使用的 Agent Preset 和模型选择
+- 支持持久标题、Markdown 导出、上下文占用、token、缓存、TTFT 和耗时统计；`/usage` 面板按上游 token 统计给出四个互不重叠的桶、按模型合并的总量和按回合明细
+- 状态栏的 `入` 只算未命中缓存的输入，`缓存` 同时给出缓存读取量与命中率——两者相加才是真正计费的输入侧
+- 恢复会话时同步恢复该会话使用的 Agent Preset、模型选择和子代理列表；欢迎页同时显示 dsh 与 dsh-code 版本
 
 <p align="center"><img src="docs/pictures/dsh-3.png" width="95%" alt="可搜索的会话恢复选择器"></p>
 
@@ -112,12 +123,35 @@ DSH-Code 的重点是让 DSH 的 Agent、模型、工具和持久会话可以直
 
 - 使用 `@` 引用工作区文件或已有会话；选择 PNG、JPEG、WebP、GIF 时会自动作为真实图片附件
 - 支持启动 prompt、多个 `--image` 参数，以及从终端拖入或粘贴附件：图片按图片附件发送，其他文件按原样文件附件发送（单文件 8 MiB、每条消息 8 个以内）
-- 使用 `/diff` 按文件检查改动，使用 `/review` 发起只读代码审查
+- 使用 `/diff` 按文件检查改动，使用 `/review` 发起只读代码审查（弹出范围选择，diff 整行红绿着色）
+- `run_code` 会列出正在执行的子工具调用；workflow 会列出各成员直到结束
 - 使用 `/copy` 复制最近一条完整回复，使用 Ctrl+O 查看完整历史和工具详情
 - 支持工具审批、结构化提问、plan review、多选和自定义答案
 - 使用权限 Preset 和 sandbox 控制 Agent 可以执行的操作；任务运行中仍可补充指令或中断
 
-### 5. 命令与快捷键
+### 5. 排队与插队
+
+回合运行中你还可以继续输入消息，有两种发送方式：
+
+- **排队**：等这一回合全部结束后，作为新的一回合处理。适合「做完这件再做下一件」。
+- **插队**：在这一回合的下一个步骤开始之前交给模型，和当前这次请求一起处理。适合发现它做偏了、要立刻纠正或补充要求。
+
+两者的区别是**模型什么时候能看到它**：排队是等它做完再说，插队是在它下一步动手之前就告诉它。
+
+怎么用：
+
+- 输入框空着按 `Tab` 在两种方式之间切换。提示符（`❯` / `↳`）、空输入框的提示文字和切换时的通知都会写明当前是哪一种；输入框有内容时 `Tab` 仍是补全。
+- `/queue` 打开队列面板：对某条按回车即可改为插队，按 `e` 改文字（附件原样保留），按 `d` 删除。
+- 输入框空着按 `Delete`，直接取消最新一条排队消息。
+- 按 `Esc` 取消当前回合时，**排队的消息保留并接着发出**，插队的消息随这一回合一起丢掉。
+
+会话区里每条提问都是一整行带底色的消息，颜色说明它是怎么发出的：普通消息用主题的亮品牌色，排队用警示色，插队用主题的第三种强调色，并分别带「排队」「插队」字样。底色由主题色算出，所以换主题或重新随机 rainbow 之后会跟着变。
+
+只有**提交那一刻已经有回合在运行**，才记为排队或插队；空闲时提交的消息（哪怕当时选的是插队）都算普通消息，因为它本来就会立刻开始新的一回合。
+
+队列的具体行为、上游两条队列的取出顺序和各主题的色值见 [排队与插队](docs/message-queue.md)。
+
+### 6. 命令与快捷键
 
 启动 TUI：
 
@@ -137,6 +171,7 @@ dsh --profile cli --session my-id    # 使用指定 id 新建会话
 | --- | --- |
 | `/new [preset]` | 创建新会话，可同时指定 Agent Preset |
 | `/resume [id\|前缀]` | 搜索或恢复已有会话 |
+| `/search [query]` | 跨会话全文检索（复用 session-query 引擎，回车恢复命中的会话） |
 | `/resume cancel` | 取消正在等待的会话切换 |
 | `/fork [event-seq]` | 从最近完成的 turn 或指定事件位置创建分支会话 |
 | `/delete [id\|前缀]` | 删除指定会话及其 subagent 会话 |
@@ -160,8 +195,10 @@ dsh --profile cli --session my-id    # 使用指定 id 新建会话
 | 命令 | 用途 |
 | --- | --- |
 | `/diff [--staged\|ref]` | 按文件查看工作区、暂存区或指定 ref 的 Git diff |
-| `/review [--staged\|ref]` | 使用只读权限审查 Git 改动；新会话中可直接使用，审查提示词作为首条消息建立会话 |
+| `/review [说明]` | 直接回车弹出候选面板（未提交改动 / 选择分支 / 选择提交 / 自定义关注点）；带任意文字则作为审查说明搭配未提交 diff（如 `/review 使用中文`）。diff 直接附在当前会话的审查提示里，自动切换只读权限，结论按 P0–P3 分级带文件行号 |
 | `/todos` | 查看当前会话的完整 todo 列表 |
+| `/queue` | 查看等待下一回合的消息：按回车改为插队、`e` 改文字、`d` 删除；`↑↓`/`PageUp`/`PageDown`/`g`/`G` 移动 |
+| `/usage` | 查看本会话的 token 用量：四个互不重叠的桶（未命中输入、缓存写入、缓存读取、输出）、按模型合并的总量、以及按回合的明细 |
 | `/agents` | 查看当前会话创建的 subagent 会话 |
 | `/jobs` | 查看后台任务及其运行状态 |
 | `/schedule` | 查看活动提醒(模型经 schedule 工具创建/取消,面板只读展示,逾期优先) |
@@ -172,10 +209,12 @@ dsh --profile cli --session my-id    # 使用指定 id 新建会话
 | 命令 | 用途 |
 | --- | --- |
 | `/plugin [query]` | 查看已加载扩展及其状态 |
-| `/update` | 一键对齐升级：按目标版本的 peers 锁定宿主 Harness 线，同步升级 dsh-code、全局宿主与 profile 内伴生插件，升级前展示完整计划与拒绝条件，完成后提示重启生效 |
+| `/update` | 查询 npm 上的新版本并确认升级。从 GitHub tarball 装的版本可能领先 npm，此时会写明不降级 |
 | `/statusline` | 选择状态栏显示的项目 |
 | `/vscode-keys` | 将 Ctrl+R 放行进 VS Code 系终端（幂等写入用户级 keybindings.json） |
-| `/theme` | 切换终端配色主题 |
+| `/theme` | 切换配色：`dark` / `light` / `prismatic` / `rainbow` / `auto` |
+| `/rainbow [seed]` | 重掷或指定 rainbow 主题的配色种子；无参数换一颗并切到 rainbow |
+| `/language [en\|zh]` | 切换界面语言，默认英文；模型提示词和状态栏事实数据仍为英文 |
 | `/animation` | 开关计时动画（shimmer/追逐/闪烁/切换波浪），`/animation [on\|off]` |
 | `/help` | 查看快捷键、内置命令、Harness 命令和用户技能 |
 | `/quit` | 退出 DSH-Code |
@@ -185,17 +224,18 @@ dsh --profile cli --session my-id    # 使用指定 id 新建会话
 | 操作 | 用途 |
 | --- | --- |
 | `Enter` | 提交当前输入 |
+| `Ctrl+J` / `Alt+Enter` | 在输入中插入换行（增强键盘协议下 `Shift+Enter` / `Ctrl+Enter` 同效） |
 | `Up` / `Down` | 召回上一条或下一条输入记录 |
-| `Tab` | 补全命令、技能或 `@` 引用 |
+| `Tab` | 补全命令、技能或 `@` 引用；输入框为空时切换下一条消息是排队还是插队 |
 | `@` | 引用工作区文件或已有会话；图片文件自动作为附件发送 |
-| `Ctrl+O` | 查看完整历史与工具详情 |
+| `Ctrl+O` | 查看完整历史与工具详情，每条带种类标签（user prompt / reply / tool call 等） |
 | `Ctrl/Alt+R` | 折叠或展开思考过程；VS Code 系终端先运行 /vscode-keys 放行 Ctrl+R |
-| `Shift+Tab` | 循环切换权限 Preset |
-| `Delete` | 输入框为空时，取消最新一条排队消息 |
+| `Shift+Tab` | 循环权限 Preset，并在提供 `/plan` 时经过 plan 档 |
+| `Delete` | 输入框为空时取消最新一条排队消息（插队不在队列里，要取消请按 `Esc` 结束回合） |
 | `Ctrl+K` | 删除光标到行尾的内容 |
 | `Ctrl+U` | 清空当前输入行 |
 | `Ctrl+A` / `Ctrl+E` | 移动到当前行开头或结尾 |
-| `Esc` | 关闭当前菜单或中断正在运行的 turn |
+| `Esc` | 关闭当前菜单或中断正在运行的回合；排队的消息保留并接着发出，插队的随回合丢掉 |
 | `Ctrl+C` | 依次用于取消任务、清空输入或退出 |
 | `Ctrl+D` | 退出 DSH-Code |
 
@@ -246,8 +286,8 @@ DSH-Code 读取 Harness 的实时注册表，不在本地维护另一套副本
         config:
           configPath: C:/Users/you/.claude/hooks.json
   ```
-- **LSP 导航**：组合里预置了 `lsp` / `lsp-stdio` / `tool-lsp` 三行（禁用状态——语言服务器二进制在挂载期解析，缺失会让整个组合启动失败）。在用户层将三行 `disabled: false` 并为 `lsp-stdio` 配置 `servers`（扩展名到语言再到服务器命令），模型即获得 `lsp` 工具（goToDefinition / findReferences / goToImplementation / hover）。
-- **持久终端**：PTY 服务与平台后端（Windows 走 pwsh 方言、POSIX 走 bash）已默认挂载，但六个模型工具 `terminal_open` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` / `terminal_list` 出厂禁用——启用等于向所有会话放开 shell 能力，与 preset 把关原则一致，由部署显式决定。在用户层开启：
+- **LSP 导航**：组合里预置了 `lsp` / `lsp-stdio` / `tool-lsp` 三行（禁用状态——语言服务器二进制在挂载期解析，缺失会让整个组合启动失败）。这三个包宿主 CLI 未捆绑：先装入 profile（`dsh plugin --profile cli add @deepseek-ai/dsh-lsp @deepseek-ai/dsh-lsp-stdio @deepseek-ai/dsh-tool-lsp`），再在用户层将三行 `disabled: false` 并为 `lsp-stdio` 配置 `servers`（扩展名到语言再到服务器命令），模型即获得 `lsp` 工具（goToDefinition / findReferences / goToImplementation / hover）。
+- **持久终端**：PTY 服务与平台后端（Windows 走 pwsh 方言、POSIX 走 bash）已默认挂载，但六个模型工具 `terminal_open` / `terminal_send` / `terminal_read` / `terminal_signal` / `terminal_close` / `terminal_list` 出厂禁用——启用等于向所有会话放开 shell 能力，与 preset 把关原则一致，由部署显式决定。`@deepseek-ai/dsh-tool-terminal` 同样不在宿主捆绑内：先 `dsh plugin --profile cli add @deepseek-ai/dsh-tool-terminal`，再在用户层开启：
   ```yaml
   - id: tool-terminal
     disabled: false
@@ -277,7 +317,7 @@ Host 持有共享基础设施——注册表、持久化、会话查询、权限
 
 ### 4. 会话记录与恢复
 
-提示词、工具调用与结果、模型选择、plan 状态、权限、标题和 preset 选择都由持久 Session 事件投影得到；会话恢复、导出、历史检查、上下文统计和终端重放使用同一份记录。实时流式文本经进程内流帧呈现，落盘日志只保留装配完成的回复（内嵌计时流），两者在重放时得到同一视图。
+提示词、工具调用与结果、模型选择、plan 状态、权限、标题和 preset 选择都从持久的 Session 事件记录推导而来；会话恢复、导出、历史检查、上下文统计和终端回放使用同一份记录。实时流式文本经进程内流帧呈现，落盘日志只保留装配完成的回复（内嵌计时流），两者在回放时得到同一视图。
 
 React state 只保存输入草稿、光标、当前面板、选中项和滚动位置等临时界面状态。
 
@@ -288,19 +328,25 @@ dsh profile
    ├─ Agent 会话 B + preset minimal
    └─ DSH-Code TUI
       持久事件 → 纯投影 → 只追加的历史转录
-                         └→ 有界面板 → 输入框 → 状态栏
+                         └→ 受限面板 → 输入框 → 状态栏
 ```
 
 ## 五、开发
 
 ```sh
 pnpm install
+pnpm lint            # ESLint（类型敏感）：src、tests、scripts、根配置
+pnpm typecheck       # 构建项目的类型检查（src）
+pnpm typecheck:tests # 测试套件与 scripts 的类型检查
 pnpm test
-pnpm typecheck
+pnpm test:coverage   # 覆盖率报告（只报告，不设门槛）
 pnpm build
+pnpm verify          # lint + 两个类型检查 + 测试，一次跑完
 pnpm run gen:whale   # 从 vendored Logo 路径重新生成 src/whale-glyph.ts
 ```
 
+测试文件由 `tsconfig.test.json` 纳入类型检查：spec 里的假实现若与真实接口脱节，会在 `pnpm typecheck:tests` 直接报错，而不是留到运行时。
+
 鲸鱼字形由 `scripts/fish-logo.ts` 中 vendored 的 DeepSeek FishLogo 几何数据生成（来源：DeepSeek Harness，MIT）。
 
 ### 1. 源码开发安装