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

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

@@ -0,0 +1,301 @@
+# Using dsh-TUI in VS Code
+
+[Documentation index](README.md) · [中文](vscode.md)
+
+dsh-TUI is a terminal program: it writes ANSI into a PTY and reads keys
+back from the PTY. So any compatible terminal can host it — including the
+**VS Code integrated terminal** (xterm.js). This page covers two ways to
+use it:
+
+**The `dsh-tui-vscode` companion extension (recommended)**
+
+- sessions run in a real VS Code integrated terminal (a new column beside
+  the editor);
+- multiple concurrent sessions, a sidebar session history, one-click start;
+- resume-last and specific-session resume;
+- published on the VS Code Marketplace.
+
+**Run directly in the built-in terminal**
+
+- zero install, seconds to start;
+- for when you do not want the extension.
+
+> Version note: `dsh-tui` here means this repository (the TUI plugin);
+> `dsh-tui-vscode` means the companion extension; the two are versioned
+> and released independently. Full docs:
+> [baobaolaodie/dsh-tui-vscode](https://github.com/baobaolaodie/dsh-tui-vscode)
+>
+> **The selection channel requires an extension that speaks protocol v2**
+> (**dsh-tui-vscode >= 0.7.0**); with an older extension the feature stays
+> silently disabled and everything else is unaffected.
+
+## Option 1: the dsh-tui-vscode companion extension (recommended)
+
+[`baobaolaodie/dsh-tui-vscode`](https://github.com/baobaolaodie/dsh-tui-vscode)
+runs dsh-tui inside a real VS Code integrated terminal (`createTerminal`
+plus the CLI running inside it), with no webview and no xterm emulation.
+It does not touch the TUI's rendering core — it only **hosts** it and adds
+editor integration.
+
+### Extension features
+
+- Editor-title button, activity-bar whale icon, and command-palette entries;
+- a `DeepSeek` integrated terminal in a column beside the editor;
+- one independent terminal and process per session, with existing sessions
+  continuing in their own terminals;
+- a sidebar session history grouped by project, with refresh and
+  specific-session resume;
+- environment injection for `DSH_TUI_LANG`, `$VISUAL`, `$DSH_HOME`, and a
+  target session id;
+- per-session termination when its terminal closes, or when `Ctrl+C` is
+  pressed twice inside the TUI.
+
+| Capability | Official Claude Code extension | dsh-tui-vscode |
+| --- | --- | --- |
+| Entry points | Activity-bar icon + editor-title button + command palette | Same (DeepSeek whale icon) |
+| Session position | NEW column beside the active one (`ViewColumn.Beside`) | Same — never takes the current column |
+| Terminal tab | `Claude Code` + logo icon | `DeepSeek` + whale icon |
+| Session host | Real integrated terminal (default shell — PowerShell on Windows) | Same |
+| Multiple sessions | Every click opens a new session terminal | Same; old sessions keep running |
+| Sidebar | Sessions list | Session history (grouped by project — stronger) |
+| Auto start/stop | Open = start; closing the terminal = end | Same |
+| Env injection | — | `DSH_TUI_LANG` / `$VISUAL` / `$DSH_HOME` / session id / `DSH_TUI_IDE_PORT/TOKEN` (selection channel) |
+| Editor selection sync | Selection enters context automatically; `⧉ N lines selected` under the prompt | Same (IDE selection channel, below) |
+
+### IDE selection channel
+
+With a dsh-tui build that includes the IDE selection channel, the extension
+runs a loopback WebSocket server and writes a lock file (directory 0700,
+file 0600).
+
+- Extension-launched sessions connect via injected env vars at startup;
+- manually launched sessions discover it by scanning the lock — only windows
+  whose workspace covers the session directory are ever dialed. With no
+  match the integration stays silently disabled and a foreign project is
+  never connected.
+
+Afterwards:
+
+- Selecting code in the editor instantly shows a `⧉ N lines selected` badge
+  under the TUI prompt (it disappears when the selection clears);
+- Submitting a message attaches only the selected lines to the model
+  context, with a `⧉ Selected N lines from <relative path>` indicator above
+  the user bubble (resuming after a restart still rebuilds that indicator);
+- Selection pushes carry the editor buffer's OWN text — unsaved edits are
+  attached exactly as you see them on screen; oversized selections are
+  capped and marked with the same policy as @-mentions;
+- Without an IDE or on disconnect everything degrades silently with zero
+  impact on the rest of the TUI.
+
+![IDE selection channel: live footer badge and transcript indicator](../screenshots/ide-selection-badge.png)
+
+**Protocol & versions**:
+
+- After connecting, the TUI sends `ide/hello` (token + protocolVersion);
+- the extension answers `ide/hello_ack` (protocolVersion + workspaceFolders)
+  only when the token validates — the link counts as established only after
+  a valid v2 ack; a wrong token is silently dropped;
+- `selection_changed` then carries absolute 0-based inclusive line numbers
+  plus the editor buffer's own selection text;
+- lock discovery only ever dials windows whose workspace covers the session
+  directory and stays silently disabled without a match;
+- both ends of the protocol must ship at the same version.
+
+### Prerequisites
+
+- VS Code >= 1.90;
+- Global `dsh` CLI and `dsh-tui` (**dsh-tui 0.7.0+ recommended**, see
+  [Getting started](getting-started.en.md)):
+
+  ```sh
+  npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
+  ```
+
+- `DEEPSEEK_API_KEY` for running models (in the terminal environment or the
+  dsh configuration).
+
+### Install
+
+**From the VS Code extension panel (recommended)**: press `Ctrl+Shift+X`,
+search for **`dsh-tui`** and install with one click (publisher
+`baobaolaodie`), or open the
+[Marketplace page](https://marketplace.visualstudio.com/items?itemName=baobaolaodie.dsh-tui-vscode)
+directly.
+
+Or build from source:
+
+```sh
+git clone https://github.com/baobaolaodie/dsh-tui-vscode.git
+cd dsh-tui-vscode
+npm install
+npm run package && code --install-extension dsh-tui-vscode-<version>.vsix --force
+# or: npm run install:local
+```
+
+### Quick start
+
+1. Click the **editor-title whale button** (or the command-palette entry
+   `dsh-tui: Start new session / 启动新会话`) — a **DeepSeek** terminal
+   opens on the Beside column and runs dsh-tui automatically.
+2. The **activity-bar whale icon** opens the sidebar session history; its
+   welcome view offers start/resume buttons.
+3. Click again = **another concurrent session**; older sessions keep
+   running in their own terminals.
+4. **Resume the last session**: `dsh-tui: Resume last session / 恢复上次会话`.
+5. **Resume a specific session**: expand a project group in the sidebar
+   "会话历史" and click the session entry.
+6. **Terminate**: close the terminal tab (ends only that session), or
+   double `Ctrl+C` inside the TUI; the command
+   `dsh-tui: Terminate session / 终止会话` sends Ctrl+C to the most recent
+   terminal.
+
+While sessions are running, a **status-bar** item (`dsh-tui`, bottom-left)
+appears; clicking it starts a new session (`dsh-tui-vscode.open`).
+
+### Command reference
+
+| Command ID | Title | Action |
+| --- | --- | --- |
+| `dsh-tui-vscode.open` | Open panel / 打开会话面板 | Start a new session (the editor-title button uses this entry point too) |
+| `dsh-tui-vscode.start` | Start new session / 启动新会话 | Start a new session |
+| `dsh-tui-vscode.resume` | Resume last session / 恢复上次会话 | Resume via `--resume` |
+| `dsh-tui-vscode.focus` | Focus session panel / 聚焦会话面板 | Focus the most recent terminal, else start one |
+| `dsh-tui-vscode.kill` | Terminate session / 终止会话 | Send Ctrl+C to the most recent terminal |
+| `dsh-tui-vscode.refreshSessions` | Refresh sessions / 刷新会话列表 | Manually refresh the sidebar |
+| `dsh-tui-vscode.resumeSession` | Resume session / 恢复会话 | Resume a specific session (sidebar click) |
+| `dsh-tui-vscode.insertAtMention` | Insert @-mention / 插入 @文件引用 | With editor focus press `Ctrl+Alt+K` (macOS `Cmd+Alt+K`) or the editor context menu: inserts the current file / selection as `@absolute/path Lstart-end` into the dsh-tui input box (the absolute path is independent of the dsh-tui session cwd; whole file when nothing is selected; falls back to the clipboard with no running session) |
+
+### Architecture
+
+- The extension runs a loopback WebSocket server and writes a lock file
+  (directory 0700, file 0600).
+- Extension-launched sessions connect via injected env vars at startup.
+- Manually launched sessions (e.g. tmux / SSH) discover it by scanning the
+  lock — only windows whose workspace covers the session directory are ever
+  dialed; with no match it stays silently disabled and a foreign project is
+  never connected.
+- The connection speaks protocol v2: the TUI sends `ide/hello`, the
+  extension answers `ide/hello_ack`, then `selection_changed` pushes
+  selections.
+- Without an IDE or on disconnect, everything degrades silently with zero
+  impact on the rest of the TUI.
+
+### Configuration
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `dsh-tui-vscode.command` | `dsh-tui` | Launch command (resolved to an absolute path against the host PATH) |
+| `dsh-tui-vscode.extraArgs` | `[]` | Extra CLI args, e.g. `["--lang","en"]` |
+| `dsh-tui-vscode.lang` | `""` | `""`/`zh`/`en`, exported as `DSH_TUI_LANG` |
+| `dsh-tui-vscode.injectEditor` | `true` | Export `$VISUAL` when unset |
+| `dsh-tui-vscode.editorCommand` | `code -w` | Value exported as `$VISUAL` |
+| `dsh-tui-vscode.dshHome` | `""` | `$DSH_HOME` override (empty = inherit) |
+
+### Development and verification
+
+Entry-level commands in the extension repository:
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # compile + node --test (data-layer unit tests)
+npm run test:e2e    # real extension-host tests (xvfb-run -a on Linux)
+npm run package     # compile + build the .vsix
+```
+
+`npm run install:local` installs locally in one step; the CI job matrix and
+commit hooks live in the extension repository's own docs.
+
+### Known limitations
+
+- Session content is terminal content: scrollback is managed by the VS Code
+  integrated terminal;
+- Specific-session resume requires this profile's `cordis.patch.yml`
+  (dsh-tui 0.7.0+);
+- For logs without a `session` header, the project name comes from decoding
+  the cwd-encoded group dir, which is lossy for hyphenated project names
+  (e.g. `flow-comet` → `flow\comet`); the real cwd is still available in
+  the item tooltip.
+
+## Option 2: run directly in the VS Code integrated terminal
+
+When you do not want the extension, run dsh-tui directly in the integrated
+terminal. Prerequisites match [Getting started](getting-started.en.md):
+global `dsh` CLI and `dsh-tui` (the first run bootstraps the profile; pnpm
+is required).
+
+1. Open the VS Code integrated terminal (`` Ctrl+` ``) and run:
+
+   ```sh
+   dsh-tui
+   ```
+
+2. Resume the last session:
+
+   ```sh
+   dsh-tui --resume
+   ```
+
+   > `-c` / `--continue` is equivalent to `--resume`; `dsh-tui --resume <id>`
+   > (or `--resume=<id>`, since 0.7.0) resumes a specific session.
+
+dsh-TUI has dedicated compatibility paths for xterm.js (VS Code / Cursor /
+code-server):
+
+- truecolor;
+- OSC 8 links (rendered clickable by VS Code itself);
+- OSC 52 clipboard (VS Code prompts for permission on first use);
+- synchronized output and smooth draining.
+
+These are handled in `src/ink/` under the `TERM_PROGRAM=vscode` detection
+branches. Streaming Markdown, tool cards, scrolling, and double-Esc time
+travel behave the same as in a standalone terminal.
+
+### Make `Ctrl+G` edit the current input in VS Code
+
+The TUI's `Ctrl+G` uses `$VISUAL`/`$EDITOR`. To edit in VS Code, export
+`code -w` in the terminal environment (`settings.json`, key
+`terminal.integrated.env.<platform>`):
+
+```jsonc
+{
+  "terminal.integrated.env.windows": { "VISUAL": "code -w" },
+  "terminal.integrated.env.linux":   { "VISUAL": "code -w" },
+  "terminal.integrated.env.osx":     { "VISUAL": "code -w" }
+}
+```
+
+(The companion extension exports `code -w` automatically when neither
+`$VISUAL` nor `$EDITOR` is set — see Option 1.)
+
+### UI language
+
+`DSH_TUI_LANG` defaults to Chinese; for the English UI, add
+`"DSH_TUI_LANG": "en"` to the env block above.
+
+### Known differences (built-in terminal)
+
+| Capability | Behavior in the integrated terminal |
+| --- | --- |
+| 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 |
+
+For the full protocol behavior of a standalone terminal (e.g. complex mouse
+semantics), use an external terminal window (Windows Terminal / kitty /
+WezTerm / iTerm2 / tmux).
+
+## Which option to choose
+
+| Scenario | Choice |
+| --- | --- |
+| Need multiple sessions, session history, and specific-session resume | Option 1: companion extension |
+| Occasional use, no extension wanted | Option 2: built-in terminal |
+| Need a standalone terminal's full protocol behavior (complex mouse semantics, etc.) | External terminal window |
+
+## Acceptance baseline
+
+Per [Contributing](contributing.en.md), VS Code is a supported terminal
+platform. Any rendering change should be walked through inside the VS Code
+integrated terminal in both inline and fullscreen modes at narrow widths —
+startup, resize, scroll, input, cancel, and clean exit.

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

@@ -0,0 +1,272 @@
+# 在 VS Code 中使用 dsh-TUI
+
+[文档索引](README.md) · [English](vscode.en.md)
+
+dsh-TUI 是终端程序：它把 ANSI 写进 PTY，再从 PTY 读按键。
+所以任何兼容终端都能运行它，包括 **VS Code 集成终端**
+（xterm.js）。本页介绍两种用法：
+
+**companion 扩展 `dsh-tui-vscode`（推荐）**
+
+- 会话跑在 VS Code **真实的集成终端**里（编辑器区另一侧新开一列）；
+- 支持多会话并存、侧边栏会话历史、一键启动；
+- 支持恢复上次会话、恢复指定会话；
+- 扩展已上架 VS Code Marketplace。
+
+**内置集成终端直接运行**
+
+- 零安装、秒级可用；
+- 适合不想装扩展的场景。
+
+> 版本说明：本页的 `dsh-tui` 指本仓库（TUI 插件），
+> `dsh-tui-vscode` 指 companion 扩展，两者版本独立、各自发布。
+> 扩展完整说明见其仓库 README：
+> [baobaolaodie/dsh-tui-vscode](https://github.com/baobaolaodie/dsh-tui-vscode)
+>
+> **选区通道要求扩展支持协议 v2**（**dsh-tui-vscode ≥ 0.7.0**）——
+> 更旧的扩展下该功能静默不启用，其余功能不受影响。
+
+## 方式一：companion 扩展 dsh-tui-vscode（推荐）
+
+[`baobaolaodie/dsh-tui-vscode`](https://github.com/baobaolaodie/dsh-tui-vscode)
+把 dsh-tui 跑进 VS Code **真实的集成终端**（用 `createTerminal`
+在终端内运行 CLI），没有 webview、没有 xterm 模拟层。它不改动
+TUI 核心渲染链路，只负责**运行 TUI、做编辑器集成**。
+
+### 扩展提供的功能
+
+- 编辑器标签栏按钮、活动栏鲸鱼图标、命令面板入口；
+- 在编辑器区旁边创建名为 `DeepSeek` 的集成终端；
+- 每次启动创建独立会话，已有会话继续在各自终端运行；
+- 侧边栏按项目分组显示会话历史，支持刷新、恢复指定会话；
+- 注入 `DSH_TUI_LANG`、`$VISUAL`、`$DSH_HOME`、指定会话 id 等环境变量；
+- 关闭终端结束对应会话，TUI 内双击 `Ctrl+C` 也可退出。
+
+| 能力 | Claude Code 官方扩展 | dsh-tui-vscode |
+| --- | --- | --- |
+| 入口 | 活动栏图标 + 编辑器标签栏按钮 + 命令面板 | 同（DeepSeek 鲸鱼图标） |
+| 会话位置 | 编辑器区**另一侧**新开一列（`ViewColumn.Beside`） | 同，不占当前列 |
+| 终端标签 | `Claude Code` + logo 图标 | `DeepSeek` + 鲸鱼图标 |
+| 会话运行终端 | 真实集成终端（默认 shell：Windows = PowerShell） | 同 |
+| 多会话 | 每次点击新开一个会话终端 | 同，旧会话继续运行 |
+| 侧边栏 | sessions 会话列表 | 会话历史（按项目分组树，更强） |
+| 自动启停 | 打开 = 启动；关闭终端 = 结束 | 同 |
+| 环境注入 | — | `DSH_TUI_LANG` / `$VISUAL` / `$DSH_HOME` / 指定会话 id / `DSH_TUI_IDE_PORT/TOKEN`（选区通道） |
+| 编辑器选区联动 | 选区自动进上下文，prompt 下方 `⧉ N lines selected` | 同（IDE 选区通道，见下） |
+
+### IDE 选区通道
+
+搭配含 IDE 选区通道的 dsh-tui 版本，扩展会在本机起一个
+loopback WebSocket 服务，并写入 lock 文件（目录 0700、文件 0600）。
+
+- 扩展启动的会话：dsh-tui 启动时通过环境变量直连；
+- 手动启动的会话：扫描 lock 自动发现——只连 workspace 覆盖
+  当前会话目录的窗口；没有匹配就静默禁用，绝不连别的项目。
+
+此后：
+
+- 编辑器选中代码 → TUI prompt 下方**实时**出现 `⧉ N lines selected`
+  徽标（清空选区即消失）；
+- 提交消息 → 选中行自动附加进模型上下文，transcript 用户消息上方
+  渲染「⧉ Selected N lines from <相对路径>」指示行（重启后 resume
+  仍能重建该指示行）；
+- 选区推送携带**编辑器缓冲区自己的文本**——未保存的修改也如实附加
+  （附加的就是你屏幕上看到的）；超大选区按与 @-引用相同的上限截断
+  并标记；
+- 无 IDE / 断连时静默降级，TUI 其余功能零影响。
+
+![IDE 选区通道：footer 实时徽标与 transcript 指示行](../screenshots/ide-selection-badge.png)
+
+**协议与版本**：
+
+- 连接后 TUI 先发 `ide/hello`（token + protocolVersion）；
+- 扩展验证通过才回 `ide/hello_ack`（protocolVersion + workspaceFolders）——
+  只有收到合法 v2 ACK 才算连接建立，token 不对会被静默断开；
+- 此后 `selection_changed` 携带绝对行号（0-based 含端）与编辑器
+  缓冲区自身的选区文本；
+- lock 发现只连 workspace 覆盖会话目录的窗口，无匹配即静默禁用；
+- 协议两端需同版本发布。
+
+### 前置条件
+
+- VS Code ≥ 1.90；
+- 全局安装 `dsh` CLI 与 `dsh-tui`
+  （**建议 dsh-tui 0.7.0+**，见[快速开始](getting-started.md)）：
+
+  ```sh
+  npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
+  ```
+
+- 运行模型需要 `DEEPSEEK_API_KEY`（放在终端环境或 dsh 配置里）。
+
+### 安装
+
+**从 VS Code 扩展面板安装（推荐）**：`Ctrl+Shift+X` 搜索
+**`dsh-tui`** 一键安装（发布者 `baobaolaodie`），或直接打开
+[Marketplace 页面](https://marketplace.visualstudio.com/items?itemName=baobaolaodie.dsh-tui-vscode)。
+
+或从源码构建：
+
+```sh
+git clone https://github.com/baobaolaodie/dsh-tui-vscode.git
+cd dsh-tui-vscode
+npm install
+npm run package && code --install-extension dsh-tui-vscode-<version>.vsix --force
+# 或一步到位：npm run install:local
+```
+
+### 快速上手
+
+1. 点**编辑器标签栏右侧鲸鱼按钮**，或跑命令面板
+   `dsh-tui: Start new session / 启动新会话`——编辑器区**另一侧**
+   新开 **DeepSeek** 终端并自动运行 dsh-tui。
+2. 点**活动栏鲸鱼图标**打开侧边栏「会话历史」，欢迎页提供
+   「启动新会话」「恢复上次会话」按钮。
+3. 再次点击 = **再开一个会话**，多会话并行，旧会话在自己的
+   终端里继续运行。
+4. **恢复上次会话**：`dsh-tui: Resume last session / 恢复上次会话`。
+5. **恢复指定会话**：侧边栏「会话历史」展开项目组 → 点击会话条目。
+6. **终止**：关闭终端标签（只结束该会话），或 TUI 内双击
+   `Ctrl+C`；命令 `dsh-tui: Terminate session / 终止会话` 向最近
+   终端发送 Ctrl+C。
+
+有会话运行时，**状态栏**（左下）显示 `dsh-tui` 项，
+点击启动新会话（对应 `dsh-tui-vscode.open`）。
+
+### 命令清单
+
+| 命令 ID | 标题 | 作用 |
+| --- | --- | --- |
+| `dsh-tui-vscode.open` | Open panel / 打开会话面板 | 启动新会话（编辑器标签栏按钮的同一入口） |
+| `dsh-tui-vscode.start` | Start new session / 启动新会话 | 启动新会话 |
+| `dsh-tui-vscode.resume` | Resume last session / 恢复上次会话 | `--resume` 恢复最近会话 |
+| `dsh-tui-vscode.focus` | Focus session panel / 聚焦会话面板 | 聚焦最近终端，无则新开 |
+| `dsh-tui-vscode.kill` | Terminate session / 终止会话 | 向最近终端发送 Ctrl+C |
+| `dsh-tui-vscode.refreshSessions` | Refresh sessions / 刷新会话列表 | 手动刷新侧边栏 |
+| `dsh-tui-vscode.resumeSession` | Resume session / 恢复会话 | 恢复指定会话（侧边栏点击） |
+| `dsh-tui-vscode.insertAtMention` | Insert @-mention / 插入 @文件引用 | 编辑器聚焦时按 `Ctrl+Alt+K`（macOS `Cmd+Alt+K`）或编辑器右键：把当前文件/选中代码以 `@绝对路径 L起-止` 插入 dsh-tui 输入框（绝对路径与 dsh-tui 会话 cwd 无关；未选中引用整个文件；无运行会话回退为复制到剪贴板） |
+
+### 架构与机制
+
+- 扩展在本机起一个 loopback WebSocket 服务，并把连接信息写进 lock
+  文件（目录 0700、文件 0600）。
+- 从扩展启动：dsh-tui 用注入的环境变量直连该服务。
+- 手动启动（如 tmux / SSH）：扫描 lock 自动发现，只连 workspace
+  覆盖当前会话目录的窗口；没有匹配就静默禁用，绝不连别的项目。
+- 连接走协议 v2：TUI 先发 `ide/hello`，扩展回 `ide/hello_ack`，
+  之后用 `selection_changed` 推送选区。
+- 无 IDE / 断连时静默降级，TUI 其余功能零影响。
+
+### 配置
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `dsh-tui-vscode.command` | `dsh-tui` | 启动命令（按宿主 PATH 解析为绝对路径） |
+| `dsh-tui-vscode.extraArgs` | `[]` | 每次启动追加的 CLI 参数，如 `["--lang","en"]` |
+| `dsh-tui-vscode.lang` | `""` | `""`/`zh`/`en`，写入 `DSH_TUI_LANG` |
+| `dsh-tui-vscode.injectEditor` | `true` | 未设 `$VISUAL`/`$EDITOR` 时导出 `$VISUAL` |
+| `dsh-tui-vscode.editorCommand` | `code -w` | 导出为 `$VISUAL` 的命令 |
+| `dsh-tui-vscode.dshHome` | `""` | 覆盖会话的 `$DSH_HOME`（空 = 继承） |
+
+### 开发与验证
+
+扩展仓库跑测试、打包与本地安装的入口命令：
+
+```sh
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # 编译 + node --test（数据层单测）
+npm run test:e2e    # 真实扩展宿主测试（Linux 用 xvfb-run -a）
+npm run package     # 编译 + 生成 .vsix
+```
+
+`npm run install:local` 一步本地安装；CI 任务矩阵与提交钩子等扩展仓库细节，此处从略。
+
+### 已知限制
+
+- 会话内容即终端内容：滚动历史由 VS Code 集成终端管理；
+- 指定会话恢复依赖 dsh-tui profile 的 `cordis.patch.yml`
+  （dsh-tui 0.7.0+）；
+- 无 `session` 头日志的项目名来自组目录解码，含连字符的项目名
+  解码有损（如 `flow-comet` → `flow\comet`）——此类会话的 cwd
+  仍可在悬浮提示中查看。
+
+## 方式二：VS Code 集成终端直接运行
+
+不想装扩展时，直接在集成终端里跑 dsh-tui。前置条件与
+[快速开始](getting-started.md) 一致：全局安装 `dsh` CLI 与 `dsh-tui`
+（首次启动会自举 profile，需要 pnpm）。
+
+1. 打开 VS Code 集成终端（`` Ctrl+` ``）：
+
+   ```sh
+   dsh-tui
+   ```
+
+2. 恢复上次会话：
+
+   ```sh
+   dsh-tui --resume
+   ```
+
+   > `-c` / `--continue` 与 `--resume` 等价；`dsh-tui --resume <id>`（或
+   > `--resume=<id>`，0.7.0 起）恢复指定会话。
+
+dsh-TUI 对 xterm.js（VS Code / Cursor / code-server）有专门的兼容路径：
+
+- truecolor 配色；
+- OSC 8 链接（由 VS Code 直接渲染为可点击）；
+- OSC 52 剪贴板（首次使用 VS Code 会弹授权提示）；
+- 同步输出、平滑刷屏。
+
+这些在 `src/ink/` 中按 `TERM_PROGRAM=vscode` 探测分支处理。
+流式 Markdown、工具卡、滚动、双击 Esc 时间回溯等行为
+与独立终端一致。
+
+### 让 `Ctrl+G` 用 VS Code 编辑当前输入
+
+TUI 的 `Ctrl+G` 走 `$VISUAL`/`$EDITOR`。想让它在 VS Code 里编辑，
+把 `code -w` 写进终端环境（`settings.json` 中按平台设置，键名
+`terminal.integrated.env.<platform>`）：
+
+```jsonc
+{
+  "terminal.integrated.env.windows": { "VISUAL": "code -w" },
+  "terminal.integrated.env.linux":   { "VISUAL": "code -w" },
+  "terminal.integrated.env.osx":     { "VISUAL": "code -w" }
+}
+```
+
+（若 `$VISUAL`/`$EDITOR` 都未设置，companion 扩展会自动导出
+`code -w`，见方式一。）
+
+### 界面语言
+
+`DSH_TUI_LANG` 默认中文；要英文界面，在上述 env 里加
+`"DSH_TUI_LANG": "en"`。
+
+### 已知差异（内置终端）
+
+| 能力 | 内置终端表现 |
+| --- | --- |
+| 鼠标滚轮/拖选 | 由集成终端处理；“松开即复制”表现为 OS 级复制行为 |
+| 扩展键盘协议 | modifyOtherKeys / win32-input-mode 由 xterm.js 决定，可能与 kitty / WezTerm 不完全一致 |
+| OSC 52 剪贴板 | 首次使用弹出权限提示（VS Code 自身的安全设计） |
+
+需要完全对齐独立终端行为时，请使用独立终端窗口
+（Windows Terminal / kitty / WezTerm / iTerm2 / tmux）。
+
+## 选型建议
+
+| 场景 | 选择 |
+| --- | --- |
+| 需要多会话、会话历史和指定会话恢复 | 方式一：companion 扩展 |
+| 偶尔用、不想装扩展 | 方式二：内置终端 |
+| 需要完全独立终端的协议行为（复杂鼠标行为等） | 独立终端窗口 |
+
+## 验收基线
+
+按[贡献指南](contributing.md)的约定，VS Code 属于受支持的终端平台。
+任何渲染改动请在 inline / fullscreen 两种模式、窄终端宽度下，
+在 VS Code 集成终端内走一遍：启动、resize、滚动、输入、取消、
+干净退出。