lanscer/dsh-workspace-drag

---

DSH Web UI 插件 — 在侧边栏（分组视图）里，把一个历史对话直接拖到另一个工作区的标题（或该组内任意会话行）上松开， 就能把这个对话归到目标工作区，实现跨工作区的对话分类整理。无感拖拽：没有弹窗、没有中间面板，拖到哪就归到哪。

安装

从本 GitHub 仓库用 DSH 官方插件命令安装：

dsh plugin --profile web add github:lanscer/dsh-workspace-drag

本地 checkout 则可一键安装进 DSH web profile。请先在插件目录内运行（包含 package.json 的那个文件夹——克隆 dsh-workspace-drag 后先 cd 进去）：

npm run install:plugin

或直接执行（跨平台，基于 Node.js）：

node install-plugin.mjs

支持 Windows（PowerShell）、macOS、Linux——安装器是纯 Node.js 脚本，不依赖 bash 或 PowerShell 专属语法。

脚本会把插件注册进 ~/.dsh/profiles/web（Windows 上为 %USERPROFILE%\.dsh\profiles\web）：在 profile 的 package.json 添加 link: 依赖，并在 node_modules 下建立符号链接。 不触发 pnpm install，从而绕过 pnpm 的 minimumReleaseAge 策略（该策略会拦截发布不足 24 小时的依赖）。幂等——已安装时重复执行会直接跳过。

⚠️ Windows 注意事项

• 必须在克隆下来的插件文件夹内运行，不要在用户主目录运行——npm run 需要当前目录有 package.json（报错 ENOENT ... C:\Users\<你>\package.json 就是因为在错误目录运行）。
• 建符号链接使用 junction 类型，Windows 无需开启开发者模式或管理员权限。
• 若符号链接被策略拦截，link: 依赖仍会写入 profile，此时再用 dsh plugin --profile web add link:<插件路径> 补完即可。

安装后生效方式：

• 纯客户端改动：刷新浏览器页面
• 宿主端改动：重启 dsh web

注意：插件依赖 zstd CLI（见依赖）。

功能

• 无感跨工作区拖拽：侧边栏分组视图中，拖起会话行 → 悬停在另一个工作区组（标题或组内任意会话行）上高亮 → 松开即迁移。
  • 无浮动面板、无确认弹窗；同工作区内的拖放仍走 DSH 原生排序，互不干扰。
  • 成功后短暂提示，会话立即出现在目标工作区。
• 开关：在 设置 → 拖拽归类对话 页面一键启用/关闭；关闭后拖拽不生效（高亮/迁移都被禁用）。
• 安全：
  • Agent 正在运行中的会话不能移动（基于 agent 状态精确判断，不再用粗暴的 30 秒 mtime 窗口）。
  • 刚聊完的会话：拖拽后宿主端自动等待写入静止（最长 15 秒）再迁移，一次拖拽即完成，无需"等一会再拖一次"。
  • 迁移在宿主端先复制 + 校验新文件，确认无误后才删除旧目录，失败不丢数据。
  • 移动的是会话日志文件的物理位置 + 头部 cwd 字段，并同步工作区注册表归属账本与内存状态 （live header / 持久化写入句柄 / 注册表索引），移动后可继续在该会话中对话。
  • 写入句柄重定向（ENOENT 修复）：DSH 的 jsonl 后端把每次追加的落盘路径取自打开中的写入句柄的 header.cwd（JsonlSessionHandle.persistContiguous → appendLines → logPath(root, meta.cwd, id)）， 并按 id 通过同一句柄路由实时事件（tracker.writers）。旧版只重写文件与 session 对象、没动该句柄， 句柄仍指向旧目录，于是下一次对话失败于 ENOENT: no such file or directory, open '<旧路径>/session.v3.jsonl.zstd'。现在插件会在删除旧目录之前 重写该句柄的 header；若句柄无法重定向则放弃移动（原目录不动、已发布的副本回滚）。

原理（数据层）

• DSH 每个会话的工作区身份 = 其头部 cwd（绝对目录路径）。
• 会话存储于 ~/.dsh/sessions/<projectKey(cwd)>/<会话id>/session.v<格式版本>.jsonl[.zstd]。 格式版本随 dsh 升级推进：0.1.5 起为 v3（session.v3.jsonl[.zstd]），0.1.7-rc.1 起为 v4 （session.v4.jsonl[.zstd]）；最初版本的 session.jsonl[.zstd]（无 vN 段，即版本 0） 仍会保留在磁盘上。
• 迁移 = 把会话目录移动到目标工作区的 projectKey 目录下 + 重写第一行（header）的 cwd + 用 ctx.workspaceRegistry 的 detach/attach 更新工作区归属账本。
• 格式版本是"发现"出来的，不是写死的：插件按规范文件名 ^session(?:\.v([1-9][0-9]*))?\.jsonl(\.zstd)?$ 扫描会话目录，取版本号最大的一代，并重写 目录内全部世代（当前代 + 旧代 + 遗留 session.jsonl[.zstd]）的 header cwd。这样 dsh 再升到 v5/v6 也无需改插件代码；备份文件（*.bak-*、*.pre-fix-*、*.corrupt-*）因不符合规范 命名而被忽略。dsh 持久化层会按 (cwd, id) 计算期望路径，若磁盘实际位置不符即报 corrupt session log: header id ... and cwd identify ...——所以每一代都必须重写。
• sessionPersistence.list() 返回契约：dsh 0.1.7-rc.1 起返回 SessionPersistenceSnapshot 记录 { header, revision, sizeBytes? }（header 嵌在 .header 下）；更早版本直接返回 header 本身。 插件两种形状都接受。list() 是"尽力而为"的：它遍历整棵会话树，任何一个不可用产物（未来格式、 中断迁移残留的重复 id、编码不匹配）都会让它抛错——此时插件回退到自己的文件系统扫描，只影响 该会话，不会让整个功能失效。
• zstd 日志是拼接多帧容器：帧 1 = 恰好一行 header（以换行结尾），帧 2..N = 每次追加的事件批次； DSH 读取器要求第一帧独立解码后恰好是这一行 header。
• 迁移时对 zstd 日志做帧保留手术：只解码帧 1 → 改写 header 的 cwd → 重编码为单帧（带 checksum， 与 DSH 后端一致）→ 与其余原始帧（逐字节不变）拼接。绝不能把整个日志压成单帧（会破坏 DSH 读取器的"第一帧=仅 header"不变量）。

文件

dsh-workspace-drag/
├── package.json          # dsh.bundle.patch + client inject
├── cordis.patch.yml      # 向 web profile 注册插件行
├── lib/
│   ├── index.js          # 宿主端：config/move 两个 HTTP 路由 + 迁移逻辑
│   └── client.js         # 浏览器端：设置页(开关) + document 级拖拽引擎
├── test/
│   ├── fixtures/multiframe-session.jsonl.zstd  # 多帧 zstd 会话样本（7 帧）
│   ├── verify-core.mjs              # zstd 往返 + DSH 帧扫描器兼容校验
│   └── integration-move.mjs         # moveSessionToWorkspace 端到端集成测试（含帧数保持断言）
└── README.md

宿主端 HTTP 接口

方法	路径	说明
GET	/api/dsh-workspace-drag/config	读开关 { "enabled": true }
POST	/api/dsh-workspace-drag/config	写开关 { "enabled": false }
POST	/api/dsh-workspace-drag/move	{ "sessionId", "targetWorkspaceId", "waitMs" } 迁移对话；waitMs（0–30000，可选）让宿主端等待 agent 结束/日志静止后自动完成，失败响应带 code（agent-running / writing / move-failed）

配置持久化在 ~/.dsh/dsh-workspace-drag.json。

依赖

• 宿主端需要 zstd CLI。插件自动通过 PATH 查找，找不到再 fallback 到常见路径（/opt/homebrew/bin/zstd、/usr/local/bin/zstd、/usr/bin/zstd）。macOS 通过 brew install zstd 安装，Linux 通过 apt install zstd 安装。
• 需要 DSH 内置服务：webServer / sessions / sessionPersistence / workspaceRegistry （@deepseek-ai/dsh-web-app 已全部加载）。
• DSH 版本兼容：peerDependencies 声明为 >=0.0.1-rc.1 <0.2.0-0，即覆盖整个 0.1.x（含预发布版， 如 0.1.7-rc.1），排除未验证的 0.2.x。会话日志格式版本与 list() 返回形状都是运行时探测的， 因此 dsh 在 0.1.x 内的升级不需要改插件。

测试

cd test
node verify-core.mjs      # 校验 zstd 往返 + DSH 帧扫描兼容
node integration-move.mjs # 端到端集成测试（临时目录，不碰真实数据）；覆盖 v3/v4 与 SessionPersistenceSnapshot 回归

使用限制

• Agent 正在运行中的对话不能移动（会提示等待回复完成）；刚结束的对话由宿主端自动等待日志静止后迁移。
• 迁移会改变会话的 cwd，也就是它所属的工作区与磁盘存储位置；这是"归到某工作区"的本质。
• 需要 zstd CLI 已安装（自动 PATH 检测，无硬编码路径）。

License

MIT

---