![preview](docs/img/social-preview.jpg)

DeepSeek Harness Web UI 工作台插件。在「对话」视图中打开工作台后，对话保留在左侧；右侧两栏分别是编辑器（含 **Agent Control Plane**、语法高亮与**智能终端**），以及文件、Git、**用量**面板和**插件命令**面板。

请先认这些特色能力：

- **用量**：官方接口余额、本机观察消耗、本会话 Token 与上下文。可钉到左侧 **Settings** 上方，边聊边看花费。
- **Agent Control Plane（智能体控制面）**：编辑器区域默认首标签。分 **执行轨迹** 与 **能力配置** 两页：前者用时间轴鱼骨图串起用户 → LLM → 工具 → Agent 回复（可展开看完整输入/输出）；后者列出当前会话 Agent 的模型、工具、Prompt 段落等，并支持会话级旋钮微调。可在设置里开关显示。
- **插件命令（Ultra Slash）**：斜杠命令，把内容注入模型下一步，**不会打断当前对话**。在右侧栏管理；在输入框输入 `/`，从最下面「插件命令」分组发送。
- **Canvas 可视化**：在工作区 `.canvas/` 目录用 React 交付产品原型、看板、分析页等独立可视化。Agent 写入 `.canvas/*.canvas.tsx` 后工作台会**自动打开**并默认进入**预览**（可像 Markdown 一样切换编辑 / 分栏 / 预览）。发送 `/canvas <主题>` 可引导模型创建，同样不打断当前对话。
- **智能终端**：编辑器里的本机伪终端。真正的 shell 行（含粘贴的 `$ ls`）直接执行；自然语言用 **AI 命令助手**（<kbd>Alt</kbd>+<kbd>I</kbd> 或工具栏 ✨）翻译后打进**当前**终端。说明语句不会执行；危险命令有黑名单，只拦助手代敲。<kbd>Alt</kbd>+<kbd>J</kbd> 可再开一个终端标签。
- **添加到会话**：不用复制粘贴，把内容直接交给模型。文件树里的文件、DevTools 里的网络请求可直接拖进对话输入框；终端里右键可把**选中内容**或**最近输出**加进会话（带上 pwd / shell 上下文）；内置浏览器里点「点选页面元素」按钮、再在页面上点一下，就能把元素快照放进会话。它们都会以引用胶囊的形式插入输入框，随下一条消息一起发给模型。
- **AI 提交说明**：右侧栏 **源代码管理** 里，按已暂存改动流式生成提交信息，写入提交框。生成模板可改。

- **提示音**：会话在后台完成、或正等你处理（审批、方案确认、提问）时，工作台会播放提示音。内置 5 种 Web Audio 合成的提示音，也可上传自己的音频（mp3、ogg、wav、webm、m4a、flac，最大 50 MB）；循环提醒会每隔 N 秒（默认 10 秒）重播一次，直到处理完或关闭。总开关、铃声选择与循环间隔都在工作台「设置」面板里。

## 目录

- [界面](#界面)
- [核心能力](#核心能力)
- [功能一览](#功能一览)
- [Agent Control Plane](#agent-control-plane)
- [用量面板](#用量面板)
- [插件命令](#插件命令)
- [Canvas 可视化](#canvas-可视化)
- [智能终端](#智能终端)
- [工作区终端](#工作区终端)
- [AI 命令助手](#ai-命令助手)
- [能力矩阵](#能力矩阵)
- [发行信息](#发行信息)
- [安装](#安装)
- [升级](#升级)
- [许可证](#许可证)

## 界面

工作台为三栏布局。左侧为系统对话；右侧两栏为能力区：中央为编辑器（含 **Agent Control Plane**、语法高亮与智能终端），最右侧为文件树、Git、用量与插件命令。右侧栏标签依次是 **文件**、**源代码管理**、**用量**、**插件命令**。编辑器默认首标签为 **控制面**。

![screen_0](docs/img/screen_shot_0.png)
![screen_1](docs/img/screen_shot_1.png)
![screen_2](docs/img/screen_shot_2.png)
![screen_3](docs/img/screen_shot_3.png)
![screen_4](docs/img/screen_shot_4.png)
![screen_5](docs/img/screen_shot_5.png)
![screen_6](docs/img/screen_shot_6.png)
![screen_7](docs/img/screen_shot_7.png)


## 核心能力

1. **工作台布局**：三栏——左侧对话，中间编辑器与终端，右侧文件 / Git / 用量 / 插件命令。新建会话即打开工作台。默认编辑区收起、右侧栏打开、用量钉在左侧设置上方。各栏可拖拽调宽、收成图标条、再展开；折叠与钉住会全局记住。
2. **智能终端**：本机伪终端（PTY）。真正的 shell 行（含粘贴的 `$ ls`）直接执行；自然语言会翻译后打进**当前** shell。说明语句不可执行。可配置黑名单拦助手代敲的危险命令。
3. **Agent Control Plane**：编辑器首标签（默认开启，设置里可关）。**执行轨迹**以话题流 + 左侧导轨展示每轮 LLM、工具调用与 Agent 回复，支持折叠展开与输入/输出详情；**能力配置**展示当前会话 Agent 的能力树（模型、工具、Prompt 段落、子 Agent 等），可在线调节旋钮并清除策略。
4. **工作区编辑器**：CodeMirror 6 语法高亮；普通 / Emacs / Vim 快捷键；Markdown 编辑 / 预览 / 分栏；**Canvas 编辑 / 预览 / 分栏**（`.canvas/*.canvas.tsx` 的 React 渲染）；图片与表格预览；Git 差异；多标签、面包屑、保存与未保存关闭确认。
5. **文件树**：浏览、筛选、隐藏文件、`.gitignore` 标记、新建 / 重命名 / 删除，以及用本机 Cursor、VS Code 等打开。
6. **Git**：状态、暂存、提交（含 AI 流式说明）、fetch / pull / push 安全拦截、分支、合并、撤销、提交图、`git init`，以及对话里的 `git_*` 工具。
7. **用量面板**：官方余额、本机观察消耗、本会话 Token 与上下文。从右侧栏 **用量** 打开；也可钉到左侧 **Settings** 上方（含收起后的缩略条）。状态栏在「反馈」左侧常驻余额。
8. **插件命令面板**：斜杠命令，把固定内容注入模型下一步，**不会打断当前对话**。右侧栏点 **插件命令** 管理；对话输入框输入 `/`，从最下面「插件命令」分组发送。内置 `/steer`、`/new`、`/skill`、`/docs`、`/canvas`。可自定义短命令，保存在本机，所有会话共用。
9. **状态栏**：已打开文件、余额、反馈、版本 / 升级、工作区路径、分支、改动数、编辑模式。
10. **维护与隐私**：界面内升级检查、中 / 英界面、路径和报错里的 token 脱敏。

## 功能一览

### 工作台

- 三栏布局：对话 | 编辑器 + 终端 | 文件 / Git / 用量 / 插件命令
- 右侧栏标签：**文件**、**源代码管理**、**用量**、**插件命令**
- 新建会话立刻打开，不必先提问
- 标题栏 **工作台** 按钮可整体开关
- 拖拽调栏宽，双击分隔条恢复默认，宽度会记住
- 对话、编辑器、右侧栏都可收成窄图标条。默认：编辑区收起、右侧栏打开、用量钉在左侧设置上方。收起状态、侧栏标签、用量钉住位置会全局记住（刷新和新建会话都保持）

### 编辑器

- 多文件标签；保存；未保存标记；有改动关闭前会确认
- 关闭全部 / 其他 / 左侧 / 右侧
- 路径面包屑
- 语法高亮：JavaScript、TypeScript、JSX、TSX、JSON、HTML、CSS、Markdown、Python、XML、YAML；其余按纯文本
- 快捷键：普通 / Emacs / Vim，选择会保存；**默认 Emacs**（打字即输入，不会卡在 Vim 普通模式）
- Vim 模式：视觉模式选中区域正常高亮（`v` / `V` / `<C-v>`）；`:w` 保存、`:q` 关闭标签、`:qa` 全部关闭、`:x` / `:wq` 保存并关闭、`:vs` / `:sp` 左右 / 上下分栏、`:only` 取消分栏；`!` 强制（跳过未保存确认）
- 编辑器分栏：`:vs` / `:sp` 只把编辑区正文拆成两个文件视图——顶部工具栏、标签栏保持单一，不重复；分栏对应的标签带下划线标记，点标签切换焦点栏的文件；拖动分隔条调整大小，`:only` 或工具栏「合并分栏」按钮合并
- 编辑器内容 → 会话：选中代码出现「添加到chat」浮动按钮；工具栏与标签右键菜单可把整个文件加入会话（与终端、网络请求同一官方胶囊机制，附文件路径）
- Markdown：编辑、预览、分栏；GFM；`http(s)` 与工作区相对路径图片；Mermaid 代码块（流程图、时序图、状态图、类图、ER 图、XY 图，基于 [beautiful-mermaid](https://www.npmjs.com/package/beautiful-mermaid)）；工作区文件链接可点开；不安全链接会拦截
- **Canvas**：工作区根目录 `.canvas/<名称>.canvas.tsx`；编辑 / 预览 / 分栏（与 Markdown 相同）；Host 编译 TSX，浏览器挂载自包含 React 组件；Agent 写入或修改后**自动打开并默认预览**；从文件树手动打开也默认进预览
- 工作区 diff 与提交 diff 在编辑器标签中打开
- 图片预览：png、jpg、jpeg、gif、webp、avif、bmp、ico
- 表格预览：csv、tsv、xlsx（UTF-8，乱码时再试 GB18030）。`.xls` 请用本机应用打开
- 新建空白文件；新建终端标签（<kbd>Alt</kbd>+<kbd>J</kbd>）

### Agent Control Plane

- 编辑器区域**首个标签**（标签名 **控制面** / **Agent Control Plane**）。在设置 → **智能体控制面** 可开关；默认开启
- **执行轨迹**（默认页）：按时间顺序展示用户、每轮 LLM（可展开看工具与 Agent 回复）、Context 注入等；左侧导轨用蓝 / 紫 / 橙鱼骨线标示层级；工具与回复可折叠，展开可看完整参数与输出
- **能力配置**：当前会话 Agent 的能力清单——模型、工具、Prompt 段落、子 Agent、环境插件等；顶部概览统计，下方轨迹式列表可逐项展开调节旋钮（如模型、工具开关、Prompt 段落内容）
- 自动刷新（约每 4 秒）；可手动 **刷新**；**清除全部旋钮** 恢复默认策略
- 需先在左侧打开会话；无数据时会提示等待 Agent 就绪。详见 [Agent Control Plane](#agent-control-plane)

### 文件树

- 浏览、展开、打开、新建、重命名、删除（删除前确认）
- 显示/隐藏隐藏文件；`.gitignore` 忽略项有标记
- 按文件名筛选
- 用本机 Cursor、VS Code、VS Code Insiders、VSCodium、Windsurf、Zed 或系统默认应用打开文件或整个工作区（只启动已安装的软件）
- 目录过大时截断并提示

### Git

- 还不是仓库时：`git init`，并填写 `user.name` / `user.email`
- 已暂存 / 更改 / 未跟踪
- 暂存、取消暂存、整栏操作
- 撤销未提交修改、删除未跟踪文件（确认后才执行）
- 点文件在编辑器看 diff
- 提交、提交全部更改、<kbd>Ctrl</kbd>+<kbd>Enter</kbd>
- AI 流式生成提交说明，模板可改
- fetch / pull / push。有未提交改动、落后远端、分离 HEAD、没有上游时会拦住，避免点错。没有 `--force`
- 拉取方式：合并 / 仅快进 / 变基。推送方式：普通 / 带租约强制推送
- 切换分支、新建并切换、合并（有冲突会自动取消，不留半成品）
- 超前 / 落后、远程探测
- GRAPH：提交图、**默认紧凑**（只看说明；可切回完整）、复制哈希、展开文件、打开提交差异、拖高度；紧凑/展开与 Git 设置会记住
- 对话工具：`git_status`、`git_diff`、`git_log`、`git_branch`、`git_commit`（提交需你确认；没有 delete / `reset --hard` / `clean`）

### 用量

- 右侧栏 **用量** 标签（仪表盘图标）。点钉住，面板会移到左侧 **Settings** 上方，边聊边看花费
- 官方接口余额；币种符号跟接口走（人民币 `¥`，美元 `$`）
- 本机观察消耗（充值不会冲掉）。官方 API Key 接口不返回累计消费——这是本机自己记的下降累计，不是官网页上的总数
- 本会话 Token：输入 / 输出 / 缓存命中 / 缓存写入 / 命中率（只统计当前这轮对话）
- 上下文占用
- **官网用量** 打开 DeepSeek 用量页
- 再点一次钉住，会收回右侧栏。左侧栏收起时也能钉进缩略条（余额 / 消耗 / Token）
- 拖高度，不会盖住上面的会话列表；双击拖动手柄恢复默认
- 底部状态栏在「反馈」左侧常驻余额；读不到时显示 `—`（或 `¥—` / `$—`）
- 点哪里、数字是什么意思，见[用量面板](#用量面板)

### 插件命令一览

- 右侧栏 **插件命令** 标签（`/` 图标）。英文界面写 **Ultra Slash**
- 在对话输入框输入 `/`：插件命令在**最下面**一组，上面有一条分隔线，分组名是「插件命令」
- 内置五条，不能改名或删除：`/steer`（注入引导）、`/new`（空白会话；`/new <内容>` 会用该内容作为第一句话发起新会话）、`/skill`（完成后存到工作区 `.dsh/skills/`）、`/docs`（完成后把原因和方案写成 `docs/` 下的 md）、`/canvas`（完成后在工作区 `.canvas/` 创建或更新 Canvas 可视化）
- 自定义短命令等于发送一段固定的 `/steer` 内容。面板里填 `review`（不用写斜杠），之后输入 `/review` 就会出现在菜单里
- **不会打断**当前对话。模型正在跑时，内容会排到下一次访问大模型；不必点「停止」
- 保存在本机 `~/.dsh/ultra-slash/commands.json`，所有会话共用（最多 40 条自定义）
- 命令表和添加步骤见[插件命令](#插件命令)

### 状态栏

- 可左右滑动的已打开文件标签
- 余额、反馈（GitHub Issues）、版本（GitHub 仓库）、升级入口（npm）
- 工作区路径（token 已脱敏）、当前分支、改动文件数
- 编辑模式菜单

### 智能终端

- 工作区目录下的本机 xterm.js 伪终端
- 自动区分命令和自然语言；粘贴的 `$ ls` 仍按命令执行
- 多标签（<kbd>Alt</kbd>+<kbd>J</kbd>）；每个标签独立 PTY 和 AI 助手；第一个终端标签会钉住
- AI 命令助手（<kbd>Alt</kbd>+<kbd>I</kbd> 或工具栏 ✨）
- 问候 / 警告 / 说明写成不可执行语句
- 可配置危险命令黑名单（只拦助手代敲，你在终端里手打的不受影响）
- 助手设置：分割线、执行前一句话说明、识别到真命令是否直接执行、自定义翻译提示词
- 中断（<kbd>Ctrl</kbd>+<kbd>C</kbd>）、重连、复制输出
- POSIX：bash / zsh / sh / dash。Windows：先 Git Bash，再 Windows PowerShell。详见[工作区终端](#工作区终端)

### 维护

- 中 / 英界面
- 可关闭的升级提示；安装命令以 `#` 注释写入终端
- 界面和报错里的 token、密码、Bearer 会脱敏；URL 仍保留主机和路径

## 用量面板

打开右侧栏 **用量** 标签（仪表盘图标）。要边聊天边看花费，点钉住：面板会移到左侧 **Settings** 上方。再点一次钉住，会收回右侧栏。左侧栏收成图标条时也能钉住——会变成一行缩略条，显示余额、消耗、Token。

| 你看到的 | 是什么意思 |
| --- | --- |
| 余额 | 官方接口当前余额。币种跟接口走（人民币 `¥`，美元 `$`） |
| 观察消耗 | 从本机开始记之后，余额**下降**的累计。充值不会冲掉。**不是**官网页上的累计消费——官方 API Key 接口不返回那个数字 |
| 本会话 Token | 输入 / 输出 / 缓存命中 / 缓存写入 / 命中率，只统计**当前这轮对话**，不是整个账号 |
| 上下文 | 当前上下文窗口已经用了多少 |
| 官网用量 | 打开 [platform.deepseek.com/usage](https://platform.deepseek.com/usage) |

拖顶部手柄改高度，双击恢复默认。上面的会话列表不会被盖住。底部状态栏（「反馈」左侧）常驻同一份余额；读不到时显示 `—`。

余额读不出来时，面板会直接说明原因：

- **还没有读到 API Key** — 到设置里填好密钥环境变量
- **API Key 被拒绝** — 核对有没有多空格、是不是填错
- **余额接口暂时失败** — 点刷新再试；网络或供应商抽风时也会出现
- **当前供应商没有可用的余额接口** — 这个供应商读不到余额，用量面板其它部分仍可看本会话 Token

**清零观察**只清掉本机自己记的累计，不会改官方账户。

## Agent Control Plane

打开编辑器区域首个标签 **控制面**（英文界面为 **Agent Control Plane**）。若未看到，到设置 → **智能体控制面** → **在编辑器显示控制面** 打开（默认已开启）。

面板顶部可在两个子页之间切换，选中项会记住：

| 子页 | 做什么 |
| --- | --- |
| **执行轨迹** | 以话题流查看当前会话的执行过程：用户消息 → 每轮 LLM（展开后可见工具调用与 Agent 回复）→ Context 注入等。左侧导轨标示时间主轴与分支；点击 LLM 行可展开/收起节内详情，工具与回复支持查看完整输入/输出。运行中会高亮流式状态。 |
| **能力配置** | 查看并调节**当前会话** Agent 的能力边界：顶部为 Agent 概览与统计，下方按轨迹式列表列出 LLM、Tools、Prompt 段落、子 Agent 等；环境插件单独列在底部。带 **可调** 标记的项可在线改旋钮（如切换模型、开关工具、编辑 Prompt 段落）；改动作用于本会话策略。 |

常用操作：

- **刷新** — 重新拉取控制面快照与轨迹
- **清除全部旋钮** — 去掉本会话已保存的旋钮覆盖，恢复默认
- 能力配置里点某一能力行 — 在右侧或抽屉中查看详情并调节

使用注意：

- 必须先打开左侧会话；空状态表示尚无轨迹或 Agent 未就绪
- 隐藏控制面标签**不会**撤销已生效的旋钮，只是不再显示面板
- 加载失败时，请确认工作台 Host 已更新并重启 `dsh web`

## 插件命令

打开右侧栏 **插件命令** 标签（`/` 图标；英文界面写 **Ultra Slash**）。在对话输入框输入 `/`，这些命令会出现在**最下面**一组，上面有一条分隔线，分组名是「插件命令」。

这些命令把文字注入模型的**下一步**。当前对话**不会被停止**，也不必点「停止」。模型正在跑时，内容会排队，等到下一次访问大模型；模型空闲时，会立刻开始下一步。

### 内置命令

这五条不能改名或删除。

| 命令 | 做什么 |
| --- | --- |
| `/steer <引导内容>` | 把引导注入下一步，不打断当前对话。例如：`/steer 先不要改代码，只列出将要改的文件` |
| `/new [内容]` | 切到空白会话；命令后面跟的内容会作为第一句话直接发出。正在跑的对话不会被停止，可在左侧列表点回去 |
| `/skill` | 完成当前任务后，把刚才的方案写成 `.dsh/skills/<name>/SKILL.md`，供 DeepSeek Harness 加载。同样不打断对话 |
| `/docs` | 完成当前任务后，把问题原因和解决方案写成 md，放到 `docs/`。同样不打断对话 |
| `/canvas [主题]` | 完成当前任务后，在工作区 `.canvas/` 创建或更新 Canvas（产品原型、看板、分析页等）。命令后可追加主题以指定文件名与布局重点。同样不打断对话 |

`/steer` 如果没写内容就发送，界面会提示先写明引导，并给出用法示例，不会注入空内容。

### 默认内容

面板的 **默认内容** 区可以给 `/new`、`/skill`、`/docs`、`/canvas` 各设置一段默认文字（`/steer` 必须手动输入，不能设置）。留空则使用内置文案：

- `/new` 的默认文字会作为**新会话的第一句话**发出；`/new <内容>` 仍然以输入内容为准。
- `/skill`、`/docs`、`/canvas` 的默认文字会注入模型下一步；使用时在命令后追加的文字会接在默认文字后面，例如 `/canvas 订单管理后台原型`。

默认内容保存在本机 `commands.json`（和自定义命令同一个文件），所有会话共用；刷新页面不丢失。

输入 `/new`、`/skill`、`/docs`、`/canvas` 或自定义命令名时，名字会在输入框里以引用样式高亮（与 DSH 内置命令、skill 名一致），会话无论是否正在执行都会显示。

### 自定义命令

给常用的 `/steer` 内容起一个短名字。例如填 `review` 和一段固定说明，之后在对话里输入 `/review` 就等于发送那段文字。

1. 打开右侧栏 **插件命令**。
2. 在「自定义命令」里填写 **命令名**（不用写斜杠：填 `review` 就会变成 `/review`）、可选的 **菜单说明**、以及 **注入内容**。
3. 点 **添加命令**。成功后立刻可以在输入框用这个命令。
4. 同一列表里可以编辑或删除。删除前会再确认一次。

面板会拦住不合规的填写，并在字段下方用中文说明原因：

- 命令名：小写英文字母开头，后面只能是字母、数字、连字符或下划线。中文请写在「注入内容」里，不要写在命令名上。
- 不能占用 `/steer`、`/new`、`/skill`、`/docs`、`/canvas`，也不能占用 DeepSeek Harness 自带的 `/help`、`/plan` 等。
- 最多 40 条自定义命令。说明最多 80 字，注入内容最多 8000 字。
- 名单保存在本机 `~/.dsh/ultra-slash/commands.json`（若设置了 `$DSH_HOME`，则在该目录下的 `ultra-slash/commands.json`），所有会话共用。配置文件损坏时**不会覆盖保存**——修好或删掉后再试。

## Canvas 可视化

Canvas 用于把**独立可视化交付物**（产品原型、数据看板、架构审查、时间线、交互探索等）放在编辑器里预览，而不是全部堆在聊天 markdown 里。

### 文件放在哪

与 Cursor 把 Canvas 放在用户配置目录不同，本插件把 Canvas **放在当前工作区**：

| 项目 | 规则 |
| --- | --- |
| 目录 | 工作区根目录下的 **`.canvas/`** |
| 文件名 | `<描述性-kebab名>.canvas.tsx`（例如 `.canvas/order-dashboard.canvas.tsx`） |
| 格式 | 每个 Canvas 恰好一个文件：default export 一个 React 组件；只用内联 `style`；数据内嵌在文件中（不要 `fetch`、不要额外模块） |

只有 `.canvas/` 下以 `.canvas.tsx` 结尾的路径走 Canvas 预览；其它 `.tsx` 仍按普通文本编辑。

### 怎么创建

1. **斜杠命令** — 发送 `/canvas` 或 `/canvas <主题>`，把内置引导注入模型下一步，**不打断当前对话**；模型会把文件写到 `.canvas/`。
2. **手动** — 自己在 `.canvas/` 下新建 `.canvas.tsx`，从文件树打开即可。

可在插件命令面板的 **默认内容** 里自定义 `/canvas` 的默认引导词。

### 预览与自动打开

当 Agent **写入或修改** `.canvas/*.canvas.tsx` 时，工作台会：

1. **自动打开**该文件
2. 默认进入 **预览**，**渲染 React 组件**（工具栏可切换编辑 / 分栏 / 预览，与 Markdown 相同）

从文件树手动打开 Canvas 也默认进预览；需要改源码时点「编辑 Canvas 源码」，或开「分栏」对照源码与预览。

TSX 在 Host 端编译为 JS，浏览器注入 React 钩子后挂载。编译失败时预览区会显示中文错误说明。

## 能力矩阵

| 能力领域 | 能力点 | 说明 | 状态 |
| --- | --- | --- | --- |
| 工作台 | 三栏布局 | 对话 \| 编辑器 + 终端 \| 文件 / Git / 用量 / 插件命令 | 已支持 |
| 工作台 | 自动打开 | 新建会话即打开工作台，不必先提问 | 已支持 |
| 工作台 | 调宽 / 收起 | 拖分隔条（双击恢复）；收成图标条；宽度记忆 | 已支持 |
| 编辑器 | 语法高亮 | JS / TS / JSX / TSX / JSON / HTML / CSS / Markdown / Python / XML / YAML | 已支持 |
| 编辑器 | 快捷键 | 普通 / Emacs / Vim；持久保存；默认 Emacs | 已支持 |
| 编辑器 | 标签与保存 | 多标签、未保存关闭确认、关闭全部 / 其他 / 左 / 右 | 已支持 |
| 编辑器 | Markdown | 编辑 / 预览 / 分栏；图片；Mermaid；安全文件链接 | 已支持 |
| 编辑器 | Canvas | `.canvas/*.canvas.tsx`；编辑 / 预览 / 分栏；React 渲染；Agent 写入后自动打开 | 已支持 |
| 编辑器 | 图片预览 | png / jpg / jpeg / gif / webp / avif / bmp / ico | 已支持 |
| 编辑器 | 表格预览 | csv / tsv / xlsx；`.xls` 请用本机打开 | 已支持 |
| 编辑器 | 差异 | 工作区 diff 与提交 diff 以标签打开 | 已支持 |
| 文件 | 文件树 | 浏览 / 筛选 / 隐藏文件 / 忽略标记 / 新建 / 重命名 / 删除 | 已支持 |
| 文件 | 外部打开 | Cursor / VS Code / Insiders / VSCodium / Windsurf / Zed / 系统默认 | 已支持 |
| Git | 状态与提交 | 暂存 / 撤销 / 提交 / AI 说明 / 模板 | 已支持 |
| Git | 同步 | fetch / pull / push，脏工作区 / 落后 / 分离 HEAD 会拦住；无 `--force` | 已支持 |
| Git | 分支 | 切换 / 新建 / 合并；`git init` 与身份 | 已支持 |
| Git | GRAPH | 提交图、紧凑模式、复制哈希、提交文件 diff | 已支持 |
| Git | 模型工具 | `git_status` / `git_diff` / `git_log` / `git_branch` / `git_commit` | 已支持 |
| 用量 | 余额与 Token | 官方余额、本机观察消耗、本会话 Token、上下文 | 已支持 |
| 用量 | 钉住 | 钉到左侧 Settings 上方（含收起态）；状态栏 ¥ / $ | 已支持 |
| 插件命令 | 内置命令 | `/steer` / `/new` / `/skill` / `/docs` / `/canvas`；不打断当前对话 | 已支持 |
| 插件命令 | `/` 菜单分组 | 输入框 `/` 菜单最下面「插件命令」组，上方有分隔线 | 已支持 |
| 插件命令 | 自定义命令 | 给 `/steer` 内容起短名字；本机 `commands.json`；最多 40 条 | 已支持 |
| 状态栏 | 底栏 | 文件标签、反馈、版本、路径、分支、改动、编辑模式 | 已支持 |
| 智能终端 | 本地 PTY | xterm.js；POSIX bash / zsh / sh / dash 及路径约束 | 已支持 |
| 智能终端 | 命令与自然语言 | 真实 argv 直接写入；请求交给模型翻译 | 已支持 |
| 智能终端 | 多终端标签 | <kbd>Alt</kbd>+<kbd>J</kbd>；每标签独立 PTY | 已支持 |
| 智能终端 | 自然语言翻译 | <kbd>Alt</kbd>+<kbd>I</kbd>，写入当前会话 shell | 已支持 |
| 智能终端 | 说明语句隔离 | 问候 / 警告永不执行 | 已支持 |
| 智能终端 | 危险命令黑名单 | 只拦助手代敲；规则可配置 | 已支持 |
| 智能终端 | Windows — Git Bash | 标准 Git for Windows 路径 | 已支持 |
| 智能终端 | Windows — PowerShell | 无 Git Bash 时用系统 PowerShell | 已支持 |
| 维护 | 版本升级检查 | 界面提示 + 终端 `#` 安装命令 | 已支持 |
| 维护 | 语言包 | 中 / 英 | 已支持 |
| 隐私 | 密钥脱敏 | 界面 / 报错 / 路径中的 token | 已支持 |
| 兼容性 | 测试覆盖以外的 shell | fish / tcsh / csh / ksh / mksh / cmd / 以 `ash` 为名的 BusyBox；`$SHELL` 指向它们时回退到已覆盖的 shell | 未测试覆盖 |
| 兼容性 | 远程 SSH 跳板会话 | 尚未纳入测试覆盖 | 未测试覆盖 |

## 发行信息

| 项目 | 说明 |
| --- | --- |
| 包名 | [`dsh-workbench-plugin`](https://www.npmjs.com/package/dsh-workbench-plugin) |
| 当前版本 | **0.1.32**（npm 标签 `latest`） |
| 软件源 | https://registry.npmjs.org |

```
+ dsh-workbench-plugin@0.1.32
```

维护者发布 npm 请执行 `bash devops/release.sh`。该脚本使用本机已有的 `npm login` 会话；不得将账号或凭据写入仓库。

应用市场走 GitHub 安装（`github:loadingvx/deepseek-harness-workbench-plugin`），**不会在用户机器上编译**。每次推 GitHub 之前先执行 `bash devops/build.sh`，把 `lib/index.js` 和 `lib/client.js` 与源码一起提交。

## 安装

### 前置条件

已安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)，并且能够启动 `dsh web`。

### 步骤

1. 安装插件（必须带版本号，不要省略 `@0.1.32`）：

```bash
dsh plugin --profile web add dsh-workbench-plugin@0.1.32
```

`dsh plugin add` 底层是 pnpm。pnpm 11 默认要等一个版本**发布满 24 小时**才会把它当成 `latest`。只写 `dsh-workbench-plugin`、不带 `@版本号` 时，可能静默装上 **0.1.0**，而且命令仍然成功退出。写上 `@0.1.32` 才会明确要这一版。

若指定版本后仍提示太新、装不上，在 `~/.dsh/profiles/web/pnpm-workspace.yaml` 加上下面两行，再执行一次安装命令：

```yaml
minimumReleaseAgeExclude:
  - dsh-workbench-plugin
```

2. 重启 `dsh web`。
3. 访问 http://127.0.0.1:3080 ，进入「对话」并新建会话。工作台会立刻在右侧打开，不必先提问。发出第一轮对话后，标题栏的 **工作台** 按钮可以随时开关。

### 应用市场 / GitHub

市场分配的安装命令装的是 GitHub 仓库，不是 npm 包：

```bash
dsh plugin --profile web add github:loadingvx/deepseek-harness-workbench-plugin
```

默认分支里必须已经有构建好的 `lib/index.js` 和 `lib/client.js`。只提交源码会装不上：pnpm 默认拦截 git 包的 `prepare` 构建脚本，用户会看到 `allowBuilds` 报错。装完后同样重启 `dsh web`，再打开工作台。

## 升级

### 自动提示

若当前环境已安装较低版本，文件与 Git 侧栏顶部将显示可关闭的升级提示。升级说明及安装命令会写入工作区终端，并以 `#` 开头（作为注释，不会被执行）。去掉行首 `#` 后按回车即可安装；安装完成后须重启 `dsh web`。

```bash
# dsh plugin --profile web add dsh-workbench-plugin@<最新版本号>
```

查询软件源失败时不显示提示。关闭提示仅忽略当前这一次最新版本；此后若出现更新的版本，仍会再次提示。

### 从 0.1.1 升级

**0.1.1 未包含升级检查逻辑，因此不会显示上述提示。** 请按安装命令手动升级至 0.1.32；此后版本将通过界面提示。

## 工作区终端

工作区终端基于本机伪终端（PTY）。AI 命令助手将自然语言转换为 shell 命令，写入**当前会话**所用的 shell；问候与说明以不可执行语句写入，不会被执行。已测试与尚未测试的 shell 覆盖情况见[能力矩阵](#能力矩阵)。

### 允许的 shell（POSIX）

| 名称 | 选用条件 | 命令助手验证情况 |
| --- | --- | --- |
| **bash** | `$SHELL` 为 bash；或 `$SHELL` 不在本表其余行时的默认首选 | 已验证（含 `failglob` 与交互式历史展开） |
| **zsh** | `$SHELL` 为 zsh | 已验证（含默认 `nomatch`）。交互式 zsh **默认不将 `#` 视为注释**，因此说明行不以裸 `#` 写入 |
| **sh** | `$SHELL` 为 sh；或 bash、zsh 均不可用时的兜底 | 已验证。`/bin/sh` 可能为 bash 或 dash 的符号链接，以本机实际指向为准 |
| **dash** | 仅当 `$SHELL` 明确为 dash（`/bin/dash`、`/usr/bin/dash` 或 `/usr/local/bin/dash`） | 与 sh 相同，采用 POSIX `:` 空操作。默认候选列表**不会**主动选择 dash |

### 允许的 shell（Windows）

| 名称 | 选用条件 | 命令助手验证情况 |
| --- | --- | --- |
| **Git Bash** | 探测 `C:/Program Files/Git/bin/bash.exe` 与 `C:/Program Files/Git/usr/bin/bash.exe`，存在即选用 | 尚未测试覆盖 |
| **Windows PowerShell** | 探测 `%SystemRoot%/System32/WindowsPowerShell/v1.0/powershell.exe`，Git Bash 不可用时选用 | 尚未测试覆盖 |

### 路径约束

仅接受位于 `/bin`、`/usr/bin`、`/usr/local/bin` 下、且文件名为上表四种 POSIX 名称之一的绝对路径，例如 `/bin/bash`、`/usr/bin/zsh`。Windows 下接受指向 Git Bash 与 PowerShell 可执行文件的绝对路径。其余路径（包括用户目录下的自定义安装路径）一律忽略，以免执行未知程序。

### 选择顺序

Windows 下依次探测 Git Bash、系统 PowerShell，随后才轮及下方的 POSIX 候选。POSIX 选择顺序：

1. `$SHELL`（须在白名单内）
2. `/bin/bash`
3. `/usr/bin/bash`
4. `/bin/zsh`
5. `/usr/bin/zsh`
6. `/bin/sh`
7. `/usr/bin/sh`

若上述路径均不可用，则无法启动终端。尚未测试覆盖的 shell（fish、tcsh、csh、ksh、mksh、cmd 及以 `ash` 为名的 BusyBox）见[能力矩阵](#能力矩阵)：当 `$SHELL` 指向其中之一时，该值会被忽略，并在可用时回退至已覆盖的 shell。BusyBox 仅在系统将其提供为 `/bin/sh` 时按 **sh** 处理，名称 `ash` 尚未纳入测试覆盖。

## AI 命令助手

<kbd>Alt</kbd>+<kbd>J</kbd> 新建一个终端标签；每个标签各自持有独立的 PTY 会话与 AI 助手状态，互不串扰。

按 <kbd>Alt</kbd>+<kbd>I</kbd>（或终端工具栏的 ✨ 按钮）打开当前终端底部的 AI 命令助手，将自然语言请求转换为 shell 命令，写入该终端所用的 shell，不启动独立 shell。问候、风险说明与命令前的一行解释以不可执行语句写入，不会被执行。

## 许可证

MIT
