dsh-workbench

dsh-workbench

给 DeepSeek Harness Web 端加一个「工作台」面板： 迭代（AI 改 md → 生成 Word → 你审这一版，一条时间轴看全）、 技能库（看机器上所有技能、读全文）、 文档（md 源与 docx/pdf 产物配对，把「产物比源旧」挑到最前面）。 可以停在右栏，于是对话留在中间、时间轴在右手边；左栏图标上还有「待我审」角标。 另带一个记录器（bin/record.mjs）：AI 每产出一版就顺手记一条，不用面板开着。

DSH Web 插件 · 零依赖 · 只读为主（插件本体写文件的只有三处：记审批、记录一版、打开文件； 记录器 CLI 写的是同一对记录文件）· 左栏一个图标 + 右栏一个页签，主区域一个面板。

---

它解决什么

一、AI 把文档迭代得像代码，但你看不见这条线。 AI 改 30 次 .md，每次生成一份 Word 给你 —— 中间那些版本全部同名覆盖，消失了； 你看到永远只有最新一版，也不知道这版跟前一版差在哪。

二、技能散在好几个地方，看不见也搜不到。 一个 DSH 技能可能来自项目层（.agents/skills）、用户层（~/.agents/skills）、内置层……想知道 「我到底装了哪些技能、那个技能到底写了什么」，得挨个目录翻。

三、用 AI 改文档时，源和产物会脱节。 Markdown 是源，docx/pdf 是产物。改完 md 忘了重新生成 → 交出去的 Word 里是旧内容。

这个插件把这三件事放进同一个面板。

界面

点左栏的「工作台」图标，主区域出现面板，三个页签。标题行两端各有一组按钮：

• 左上 ← → —— 面板里的浏览历史：切页签、换目录、打开技能、点开某一轮、改筛选，每一步都能退回来再进回去 （悬停显示还剩几步；只有「用户做的一步」入栈，连续打字不算）。
• 右上 ← 返回对话 —— 把中央区域切回当前会话，不改变当前会话。
• 右上 ⇥ 搬到右栏 —— 把工作台停到右侧栏（DSH 官方的右栏），于是对话留在中间、时间轴在右手边， 一边让 AI 改、一边扫这一版。它同时是右栏的一种页签类型，右栏「+」的引导页里也能找到它； 已经在右栏那一份里时这枚按钮自己收起来。
• 左栏图标上的数字 —— 「待我审」还有几轮，不用点开就知道有没有活干（0 时不显示）。

⌘ 右栏与主区域是同一份面板：位置不同，状态是同一个（目录、筛选、选中轮次都跟着走）。

迭代（默认）

把「AI 改文档」这件事变成一条看得见的时间轴：

• 按产线分组（毕业论文 / Aspen 流程模拟 / 经济分析…），产线内按天分小节，一轮一行；
• 目录不用手打：点 浏览… 开宿主的目录选择——挂原生选择器就弹系统对话框， 挂 browse 后端（远程/SSH 部署）就开插件自绘的应用内浏览器（面包屑 + 子目录 + 手输路径）；选中即读取；
• 每轮显示：时间、产物类型（Word / PDF / Excel）、这一版干了什么（记录里的摘要；没有就显示收编时补的那句 note）、改自哪几个 md、审批状态；
• 鼠标悬停任一版 → 浮出摘要卡：摘要、备注（收编时写的那句）、产出时间与体积、生成方式（哪条命令）、改动来源、快照路径、你的历史意见；
• 点开一轮 → 【通过】【要改】【重置为待审】；旁边有个理由输入框，写下的那句话会跟着审批一起进 decisions.jsonl，悬停卡里的「你的意见」以后就是它——下次打开还在；
• 产线头上摆着两条「会变坏的事」：.versions/ 里快照一共多少个、占多少空间（删快照不影响记录与源）； 记录文件里读不懂几行（坏行 / 缺 id 会被跳过，但这里会明说，不装作没发生）；
• 看完能直接打开：同一行上还有【打开这一版】（那一版的快照）、【打开成品】（产线目录里那个随时被覆盖的最新成品）、 【在文件夹里】（打开文件管理器并选中它）；
• 和上一版比：点开任意一轮，底部多一枚【和上一版比】——把这一版和上一版的正文摆到一块， 多出来的段标绿、删掉的段标红、改动的段里那个变了的词再单独描出来；
• 目录里多了内容会自动发现：目录行的档位按钮默认 自动：10 秒（可切 30 秒 / 1 分钟 / 关）， 探到变化时顶栏给一条提示「多了 N 轮」+【现在刷新】【稍后】——不擅自改你正在看的那一屏；
• 顶部按状态（待我审 / 已通过 / 要改）、产线、类型筛选。

目录只有两个来源：顶栏那个「最近用过…」下拉（最近打开过的目录 + DSH 已登记的工作区）， 或者自己填、点「浏览…」选。没有演示数据，也没有预置路径——看的就是你自己的项目。

产线按「最近动过」排：最上面那条就是你上一轮在改的线；产线头上写着它一共多少轮、 最近一次是什么时候（悬停看具体时间）、还有几轮待你审。

干活时的那套规程就在手边：本机装了 doc-iteration-control 这类迭代流程技能时， 顶栏会多出一枚【迭代流程】，点开就是技能库里的全文——不用先想起「技能库里好像有这么个技能」。

和上一版比

这是时间轴一直没回答的那一问：这一版到底比上一版改了什么。点开一轮 → 【和上一版比】：

• 默认跟上一轮比；顶上下拉可以换成同一条产线里更早的任意一轮；
• 读的是两边的快照（.versions/ 里那一份）。这一轮没留快照时退回读工作副本， 标题行会把两个文件名都摆出来，不遮着；
• 段落级 diff：新增标绿、删掉标红；一删一添配成一对时，段内再按词高亮—— 0.62 → 0.58 这种改动自己跳出来，不用整段读完再自己找；
• 连续没动的地方折成一行「…… 中间 N 段没有变化 ……」，屏幕不会被没改的内容撑满；
• 两版一字不差时明说「两版正文完全一致」——脚本跑了但没改，和「改了但你看不出来」是两件事；
• 统计一行：新增 N 段 · 删掉 M 段 · 相同 K 段。

读不出来的时候也直说，不编：pdf / pptx / 老的 .xls 现在解不出正文（那一轮连【和上一版比】都是灰的）， docx 被加密或根本不是 zip 时给一句「找不到 word/document.xml」。差异是在浏览器里算的， 宿主只负责把两段文本交出来（GET /text），不猜、不比、不写文件。

Word 与 Excel 是两种比法

• docx：单位是段落，标题、列表、表格行各占一块；
• xlsx / xlsm：单位是行。每个工作表先落一个标记块，然后一行一块， 格子之间用竖线连起来（乙苯 | 1.2 | 0.44）。于是「改了哪个格子」在词级高亮里自己跳出来， 和 Word 用的是同一套 diff——表格不用另做一套。

数字原样取，不当成日期猜（判日期要看 styles.xml 的数字格式，那一步容易猜错）；公式只取算出来的值， 公式本身不当正文；没算完的缓存如实留空。

只比产物，不比 md 源：磁盘上 md 只有一份、随时被改写，「这一轮记的源」和「那一轮记的源」 读到的往往是同一个文件，比出来永远是「完全相同」——那是骗人的。

记录格式

时间轴不是猜出来的，是产出那一刻记下来的。每个产线目录下：

产线/
├── *.md                        ← 源（AI 改的就是这些）
├── 论文全文.docx                ← 工作副本，名字永远不变（每次覆盖）
└── .versions/
    ├── produced.jsonl          ← 产出记录：追加一行一条
    ├── decisions.jsonl         ← 你的审批：追加一行一次
    └── 20260911T2210-毕业论文-论文全文.docx   ← 快照（这才叫版本存在）

produced.jsonl 一行：

{"id":"20260911T2210-毕业论文-000000-a3k9","at":1789000200000,"line":"毕业论文",
 "artifact":"论文全文.docx","snapshot":".versions/20260911T2210-毕业论文-论文全文.docx",
 "kind":"docx","bytes":38000,"tool":"python thesis_docx.py","by":"dsh",
 "sources":[{"path":"03-第三章-物料衡算.md"}],
 "summary":"第3章：修正乙苯转化率 0.62→0.58，重算全表",
 "note":"这一版就按 0.58 定稿","adopted":false}

几个字段的规矩（记录器会自动写对，手写才需要看）：

• id 是「时间戳-产线-at 尾 6 位-随机后缀」，审批按 id 归档，所以别自己编；
• at 是产物 mtime，不是「什么时候记的」——补记旧版本不会被排到时间轴最前，也不会让 【未入记录】把它再报一次；
• summary 是这一版干了什么，note 是额外备注（两个都显示，互不覆盖：时间轴一行显示 summary， 没有就退回 note；都有又不是同一句时 note 另起一行写成「备注：…」）；
• 快照是复制出来的，不是硬链接——下一版脚本若原地覆盖工作副本，硬链接会让旧快照跟着变， 那就不叫版本了；
• 日常这条记录由记录器（node bin/record.mjs）或面板的【记一版】写，不要手写 JSONL： 手写少一个字段不会报错，只会在时间轴上静默错位。

decisions.jsonl 一行：

{"id":"20260911T2210-毕业论文-3","at":1789007400000,"state":"rejected","by":"human","note":"热量衡算和物料衡算对不上"}

state ∈ approved / rejected / pending；同一个 id 以最后一条为准（追加式，不改历史）。

工作模式就是这条循环：

AI 改 .md  →  跑脚本生成 docx/pdf/xlsx  →  写 produced.jsonl + 存快照
   ↑                                                    ↓
   └────── 你给反馈 ←── 你在插件里审 Word ←──────────────┘

还没进记录的产物：把漏掉的版本捡回来

记录由产出那一刻写（日常用下面的记录器，或面板的【记一版】）。可真实项目里往往 记录器还没装上、或者某几版是别的工具生成的，.versions/produced.jsonl 里就缺了几行—— 这个按钮是补漏用的，不是日常主路径。

所以迭代页顶栏有一个 未入记录 按钮，点开它做两件事：

1. 找（宿主 POST /scan）：扫产线目录，列出「文件躺在那里、记录里却没有」的产物。 判据只有一条：记录里有同名产物、且记录时间不早于文件时间（留 3 秒时钟差）。 同时去 DSH 会话日志里翻「最近一次产出它的命令」和「那前后改过哪几个 md」—— 只认本项目 cwd 的会话，且说得保守：soffice --convert-to pdf 论文.docx 里那个 docx 是读入的一方， 不算生成；删除命令也不算。找不到就如实写「没找到生成命令」。
2. 收编（宿主 POST /adopt）：你补一句话、点【记一版】，它才真的收编成一版 —— 复制一份快照到 .versions/，并往 produced.jsonl 追加一行。 那句话写进记录的 note，时间轴上看得见（有摘要时排在下面一行「备注」）。 同一版已经被记录引用过会明确告诉你（409，不会覆盖）；如果记录文件被写坏/删了、只剩快照， 再收编会复用那份快照补记录（自愈）——这正是「记录坏了」之后该走的那条恢复路。

这一步不会自动跑：展开才扫，因为扫一次要读目录、还可能翻会话日志。

记录器：AI 产出一版就记一条

面板看的是 .versions/produced.jsonl，这个文件由产出方写。为了不让人 / AI 手写 JSON， 仓库里带了一个零依赖的命令行记录器——和面板的【记一版】走同一份实现（lib/record.js）：

node bin/record.mjs "D:\论文\毕业论文" 论文全文.docx `
  --summary "第3章：修正乙苯转化率 0.62→0.58，重算全表" `
  --sources "03-第三章-物料衡算.md" `
  --tool "python thesis_docx.py"

• 它会把这个产物复制一份快照到 .versions/，再往 produced.jsonl 追加一行；
• --summary 一句话（时间轴那行），--note 额外备注；--sources、--tool 可选；--by 默认 dsh；
• --json 输出一行 JSON 给程序 / Agent 解析，--help 看全部选项；
• 不需要 DSH 跑着、不需要面板开着；同一分钟里生成了两版（mtime 不同）会另起一个不重名的快照， 同一版重复记会被拒绝（不产生重复轮次）；快照在记录里已经被引用时不会覆盖， 记录被删 / 写坏、只剩快照时会复用那份快照补记录（自愈）；
• 写错（文件不在、类型不对、带路径）非零退出并说明原因，不会静默写坏记录。

装了 doc-iteration-control 这类迭代技能时，技能里「每轮结束顺手记一条」那一节就是调它。

技能库

• 先问核心 ctx.skills 注册表，再拿本机技能目录补缺：注册表里有谁就用谁的元数据； 它给不出来的，直接扫 ~/.agents/skills、~/.dsh/skills 和项目里的 .agents/skills（只扫一层、只认 SKILL.md）。 为什么要补这一手：snapshot() 跑在没有会话上下文的 HTTP 路由里，只给得出随包发布的那几个技能， 用户自己装的一个都看不到——那份「模型实际会加载的目录」于是反而是残缺的；
• 按技能名 / 描述 / 触发词搜索，按来源过滤（用户 · .agents、用户 · .dsh、内置、项目层…）
• 点任意一条，右侧显示它的 SKILL.md 全文与来源路径（注册表问不到全文时，直接读文件）

文档

• 填一个目录、点 浏览… 选一个，或用下拉里的已登记工作区，然后扫描
• 同样的自动档位按钮：源或产物变了会提示「多了 N 份文档」，点【现在刷新】才重扫
• 按主干名把 md/tex/qmd 等源与 docx/pdf/xlsx 等产物配对
• 状态从「该先处理」往下排：

安装

# 从本仓库源码安装（link: 方式，改源码只需重启宿主）
dsh plugin --profile web add link:/绝对路径/dsh-workbench

# 或从 GitHub 源码入口安装
dsh plugin --profile web add github:liiydong/dsh-workbench

装完必须重启 dsh web：客户端 bundle 在组合阶段被快照进内存，刷新页面不够。

工作台出现在哪里

三条路互不影响，注册都挂在插件 fiber 上，卸载即消失。右栏与 dsh-better-sidebar 都是按存在性接的： 宿主没有右栏服务（ctx.get('sidebarRight') 返回 undefined）、或没装 dsh-better-sidebar， 就只是少一个入口，不报错、也不会让插件挂起。

和「文件变动」的关系：做的过程中发现侧栏里已经有一个「文件变动」，它看的是 「这次会话里 AI 碰过哪些文件」；「迭代」页想要的比这多一层 —— 跨会话、跨天、跨产线的版本线， 每一版带着摘要、快照路径和你审批的状态。所以这块是在它旁边做的派生，工作台同时也注册成了 dsh-better-sidebar 的一个页签，两者在同一个入口里并存。

卸载：

dsh plugin --profile web remove dsh-workbench

它怎么拿到数据

宿主半侧只有 10 条 JSON 路由，全部在 /api/dsh-workbench/ 下：

/decide 的写路径做了越界检查（只允许写根目录的直接子目录，拒绝 ..、分隔符与非法状态）。 除此之外不写任何文件，不发任何模型调用，不采集遥测。

/adopt 的边界同样收死：产线名只能是根目录的直接子目录名、文件名只能是产线目录里的文件名 （拒绝路径穿越与 ..）、文件必须真的存在且是允许的产物类型、快照同名时只新建不覆盖。 它只往 <产线>/.versions/ 里写，不会碰你的 Word 本身。

/scan 是只读的，但会去读 DSH 的会话日志（ctx.sessionQuery）：只挑 cwd 等于该项目目录 的会话， 最多读最近 40 个会话、20000 条事件，找不到就读不到（面板上如实写「没找到生成命令」）。

/reveal 会启动外部程序，所以边界收得很紧——它只认白名单里的文档类型 （docx / pdf / xlsx / pptx / md / txt / csv / html / png / jpg…）、只认项目根目录里的文件、 文件必须真的存在。放行任意路径等于给网页一个「执行任意程序」的接口（.exe / .bat / .lnk）， 所以这不是偏好而是安全边界。三个平台各一套启动方式，且都不经过 shell（参数以数组传给 spawn）， 路径里的空格或 & 不会被当成命令解析。

四个 POST 写接口在入口还有两道闸：只收 application/json（浏览器对跨站的「简单请求」不发预检， 这条直接把 text/plain 表单挡掉），带 Origin 时必须与站点同源。宿主 web server 这层目前不拦这些， 所以插件自己兜住——没有这两道，任意网页都能盲打 /decide、/adopt、/reveal（读不到响应，但能写）。

另外两件事不经过本插件，走的是 DSH 自己的客户端服务：

• 选目录（迭代页/文档页的「浏览…」）→ uiWorkspace：原生选择器还是应用内浏览由部署决定，插件只接一个绝对路径字符串；
• 返回对话 → layout.selectPanel(null)：把中央区域切回当前会话，不改变当前会话。
• 自动检测新内容 → 就是把已有的 /history（或 /docs）再读一遍、算个指纹比一比，没有新增路由、没有文件监听； 探到变化只给一条提示，点【现在刷新】才真正重读并换掉屏幕上的内容。
• 「哪条命令生成的」 → 走 DSH 自己的会话查询服务 ctx.sessionQuery（listSessions + readSession）， 只看 cwd 等于该项目目录的会话，把 tool/call 事件折出来做归因；读不到就降级成「没找到生成命令」。

开发

dsh-workbench/
├── package.json          # dsh.bundle.patch + dsh.client.platform + dsh.engines.dsh + scripts.test
├── cordis.patch.yml      # 把宿主行插进 profile 名册
├── lib/
│   ├── index.js          # 宿主半侧：10 条路由（ESM，零依赖）
│   ├── record.js         # 记录一版的公共实现（/adopt 与 bin/record.mjs 共用）
│   └── client.js         # 浏览器半侧：侧栏图标 + 三个页签（手写 __ModuleLoader__ bundle，无构建步骤）
├── bin/
│   └── record.mjs        # 命令行记录器：AI 产出一版就调一次
├── test/
│   ├── smoke.mjs         # 组件树自检：桩 __ModuleLoader__ + 迷你 React，263 项
│   ├── host-routes.mjs   # 路由自检：假 req/res + 真实文件系统 + 真写审批与快照，204 项
│   └── record-cli.mjs    # 记录器自检：真起子进程、真写临时目录，并用 /history 读回来，44 项
└── .github/workflows/
    └── test.yml          # CI：windows-latest × Node 22/24 上跑三套自检

npm test                      # = 下面三套，按顺序跑
node test/host-routes.mjs     # 路由；可选参数：/docs 要扫描的目录
node test/smoke.mjs           # 组件树
node test/record-cli.mjs      # 记录器 CLI

三套自检都不需要浏览器：客户端 bundle 的 factory 与组件都是普通函数，在 Node 里可直接跑 （迷你 React 运行时按组件实例分配 hook 槽、按「组件类型 + hook 序号」去重 effect、在渲染循环里展开整棵树）。 host-routes.mjs 还会在系统临时目录里真写审批、真记录一版产物（快照 + 记录）， 并用桩会话服务验证 /scan 的归因反例（读入方、删除命令、别的项目）。 record-cli.mjs 真起 node bin/record.mjs 子进程，再把同一份目录交给宿主 /history 读回来—— 两条写入路径必须读得出同一份结果，这是这套自检存在的理由。抓得到崩溃与状态流转错误，抓不到布局观感。 自检里大量 Windows 路径（C:\ 盘符、.versions\ 分隔符），所以 CI 固定 windows-latest； Linux / macOS 上直接跑会挂，要跨平台得先把这些路径断言改掉。

已知限制

• 界面观感只过了组件树自检，未做人工视觉验证；浅色/深色都做了适配但与真实主题的贴合度可能还要调。
• 记录要靠产出方写。 面板不会替你写记录 —— 它只做两件事：显示 .versions/produced.jsonl 里已有的， 以及把「目录里有、记录里没有」的那些列出来（【未入记录】），由你点一下才收编成一版。 日常要让 AI 或脚本产出即记录，用 node bin/record.mjs（和面板的【记一版】同一份实现）； 收编只补漏，不猜内容。记录器需要本机有 Node（面板本身不需要）。
• 「还没进记录」的生成命令是靠会话日志反推的，只在两种情况下给得出：那次产出发生在 DSH 会话里、 且命令里带着输出路径（--out / -o / 重定向 / 构建脚本 + 文件名）。别的工具改的（WordBuddy、手动另存） 一律显示「没找到生成命令」——宁可不给，也不编。
• 历史上已经同名覆盖掉的版本，找不回来（快照是从设了记录器之后才开始存的）； 但【未入记录】至少能把「现在这一版」先收编下来，从这一刻起它就有了快照。
• 「产物过期」按文件修改时间判定，不看内容。生成脚本若先 touch 产物再写内容，判定会偏乐观。
• 「和上一版比」只解 docx / xlsx（含 xlsm） 与纯文本（md/tex/qmd/txt/csv/html）。 pdf / pptx / 老的 .xls 读不出正文，那一轮的按钮是灰的；超长文档只比前面 4000 段（面板上会说明被截断了）。 段落级 diff 用 LCS，序列过大时退化成「整段全删 + 全增」——宁可粗，也不把浏览器卡住。 表格里的日期按数字显示：判它是不是日期要看 styles.xml 的数字格式，那一步容易猜错，不如不猜。
• 目录扫描不递归，只扫一层；一次最多返回 1000 轮。
• 自动检测是定时重读记录文件（默认 10 秒一次，可在档位按钮里放慢或关掉），不是操作系统的文件监听； 浏览器标签页在后台时那一拍会跳过，所以切回来可能要等一拍才提示。
• 审批写的是记录文件，不会真的去改动或回滚你的 Word。
• 写接口的同源闸按 Origin 与请求的 Host 比。如果以后启用反向代理、且代理把 Host 改写成 127.0.0.1:端口（浏览器 Origin 还是公网域名），所有写接口会 403——本机 reverse-proxy.json 现在是关的，这条未实测；真要用代理，得让代理保留原始 Host（或给插件加白名单）。
• 「上一步/下一步」的历史只在面板活着的时候有效：刷新页面、或工作台被切走再切回来，那条历史就空了 （但位置会记住——目录落在 localStorage 里，技能库打开的技能、筛选、选中轮次也随面板状态保留）。

关于这个仓库：作者与 AI 披露

• 本仓库的代码由 DeepSeek Harness 中的 AI Agent 生成，由仓库所有者审阅、验证并发布； 每次提交的验证方式记录在 CHANGELOG.md（不需要浏览器的三套自检，共 511 项；测试全部自建临时目录， 不依赖仓库里的任何示例数据；CI 在 windows-latest × Node 22/24 上跑这三套）。
• 仓库里没有示例项目：曾经的演示数据（3 条产线 27 轮假记录）已经删掉——它是给「先看看长什么样」用的， 真实用法一上来就是自己的目录。仓库里也不含本机路径、姓名或邮箱，提交作者统一使用 GitHub 的 noreply 邮箱。
• 以 MIT 发布（见 LICENSE）。
• 第三方接口说明：与 dsh-better-sidebar 的集成使用它公开的客户端服务契约 （ctx.betterSidebar.registerTab），未复制其代码。该契约按其文档是版本化的（SIDEBAR_FEATURES）， 所以本插件把它当作可选依赖：读不到就只走官方座位。

License

MIT