dsh-plugin-workspace-archive

DSH（DeepSeek Harness）插件：工作区文件夹被删除或移走时，把它名下的会话归档；同一个文件夹放回来时，把这些会话带回该工作区 —— 只走官方 API。

English: README.en.md

它补的是哪条缝

DSH 有意把"目录缺失"和"归档"分开：

• 目录无法校验的工作区（被移动、被删除、从未记录）无法加入新会话，其中的会话会散成「无项目」；
• 「移除项目」保留文件夹与会话历史，但重新添加同一目录会从空项目开始：旧会话不会自动回来。

本插件补上这条缺失的联动。它不改 app.asar、不写官方 storages/ 与 sessions/ 文件，自己的记账放在 DSH 主目录下的 sidecar 里。

它做什么

触发	结果
已登记的工作区目录被删除或移走	把该路径下由本插件登记过的会话归档（侧栏默认视图不再显示，在"全部对话"里仍可见）
工作区登记被移除（菜单里的「删除工作区」，文件夹还在）	同样视为消失并归档 —— 否则那些对话会散成「无项目」。这一条不等确认窗口：官方删除登记是即时的，等窗口就是让你盯着那批对话散在侧栏里看几秒
目录或登记回来	本插件归档过的那批会话取消归档；并且台账里记过的全部成员都会被挂回该路径的工作区 —— 包括在消失之前就已经归档的会话（典型是你自己手动归档的）
一条会话待在「无项目」里，但它的工作目录就是某个已登记工作区的路径	启动后自动挂回该工作区（判据：不在任何工作区的成员表 + 目录精确相等；可用 adoptUngrouped: false 关闭）

两条永不违反的规则：

• 你自己归档的会话永远不会被取消归档：它们只是回到自己的分组里，仍然隐藏，直到你手动取消归档；
• 归档 / 恢复只处理它记过账的会话：台账是插件运行期间、工作区健康时写下的；这条路径绝不按工作目录反查。唯一的例外是启动后那一次归位：只把工作目录精确等于某已登记工作区路径、且不属于任何工作区的会话挂回去，可用 adoptUngrouped: false 关闭。

它为什么做得成（关键机制）

因为这条能力不需要改任何文件：DSH 里"会话属于哪个组"存在工作区记录的一份成员表里，而官方恰好提供了往这份表里补一笔的 API（Workspace.attachSession）。

1. 分组是"名册"，不是"档案"里的字段。 会话日志里写的是它自己的工作目录；"它显示在哪个工作区下"是工作区记录里的成员表 —— 改分组 = 改名册，官方允许。
2. 官方挂载只校验一个条件，而这个条件天然成立。 attachSession 会读会话 header 的 cwd，要求它规范化后精确等于该工作区路径，否则拒绝；而"无项目"里的孤会话，cwd 本来就等于那个路径 —— 官方自己会放行（它也顺手代我们复核了一遍，塞错组在机制上不可能）。
3. "没在名册上"是官方自己留下的空洞。 官方只在第一次启动时按 cwd 把已有会话归组一次（bootstrap 一次性，写完 initialized 标记就不再跑），此后新增的工作区不会再回头认领旧会话 —— 这正是本插件补的那一步。

而"把会话从一个工作区迁到另一个工作区"做不到（在只走官方 API 的前提下）：那要求改 cwd 本身，可它是写死在会话日志里的，官方没有任何改 cwd 的 API。详见 docs/recon/05-migration-and-multi-folder.md 与 docs/plan-session-migration.md。

环境要求

• DSH（DeepSeek Harness）桌面版或 CLI；开发与验证基线是 0.2.0-rc.2。
• Node.js 22.5+（由宿主提供）。
• 零运行时依赖：插件不 import 标准库以外的任何东西 —— 这是刻意的：通过目录联接装载的插件按真实路径解析嵌套 import，够不到宿主自带的包。

安装

三种方式，推荐第一种：

1. 从 npm 安装（推荐，2026-10-08 已发布 0.1.0）

   dsh plugin add dsh-plugin-workspace-archive
   

   插件管理器走 npm registry（官方源，回退 registry.npmmirror.com；两侧实测都已同步）。想钉版本就写 dsh-plugin-workspace-archive@<version>。

2. 从本地检出安装（本仓库真机验证用的就是这条）：把目录联接进 profile 的 node_modules，并把包名写进 profile 清单。本机用 .verify/install-desktop.mjs 一次完成这四步，--uninstall 可回滚。

3. 从本仓库按提交安装：官方插件管理器也接受 GitHub 规格，例如 dsh plugin add github:WindFromKadath/dsh-plugin-workspace-archive#<commit>。

必须重启宿主/应用：插件行与 bundle 在启动时固定，HMR 从不热装载。配置默认值在 src/index.js 的 resolveConfig；profile 的 patch 行可以覆盖 dryRun、confirmDelayMs、pollIntervalMs、watch、adoptUngrouped、adoptDelayMs。

验证

• npm test —— 52 项离线断言（工具行为、决策层、台账、真 Cordis 装载、"无项目归位"的选择逻辑、消失判据的分档确认，以及"插件源码不得 import 宿主包"的回归）。
• npm run rm-test —— 27 项针对真 DSH 运行时（一次性 DSH_HOME）的断言：建工作区 → 建两个真会话 → 删目录 → 断言只归档该归档的那个 → 放回目录 → 断言它被恢复并挂回工作区，而"用户手动归档"的那个保持归档 → 删除登记再重新添加 → 断言都回到分组 → 未分组的孤会话被自动归位。
• npm run check —— 语法。

两套都可在本仓库一键重跑，且不碰真实 profile、不碰真实工作区目录。设计约束、已采纳决策与证据线索见 MAINTAINER.md。

已知限制

• 「删除工作区」立即归档，「目录缺失」要等几秒，这不是不一致：目录缺失是一次 stat 的观测，可能抖（网络盘、改名中途），所以要等确认窗口（默认 3 秒）；而「删除工作区」是官方注册表的权威变更，且本次运行中见过这条登记，所以立即动手。插件刚启动、注册表还没铺完时不会走这条快路（那时"不在清单里"和"被删了"分不清），会退回确认窗口。
• 归档 / 恢复只认它记过账的会话：若"删除 → 重新添加"发生在插件没运行的时候，它只认得台账里最后一次快照 —— 快照里有的成员会被挂回，更早散掉的不会（这类可以由启动时的归位补上，前提是 cwd 仍等于该工作区路径）。
• 挂回分组 ≠ 取消归档：attach 只动工作区成员表，从不碰归档集合。
• 归位只跑一次（启动后延迟 5 秒）：之后新出现的孤会话要等下次重启。
• 跨工作区迁移不在本插件范围内：需要离线改写会话日志，官方无此通道。
• 不做会话删除、不删文件夹、不做跨机器同步。
• 目录被改名等于换了一个路径：挂回时官方会校验 cwd，对不上时插件只记日志、不改数据。

许可证

MIT —— 见 LICENSE。