PianoPrince/dsh-workspace-mover

dsh-workspace-mover

当前版本：2.4.1。Desktop 验收记录。

v2.4.0 会将运行中或仍驻留内存的会话加入持久化等待队列。DSH 暂无安全的写入句柄重绑定接口，因此需等会话卸载或重启后才会迁移，单纯变为空闲不足以释放句柄。迁移会把会话当前工作目录同步到目标工作区，保留已有目录变更历史，并在需要时追加目标目录记录。详见Desktop 验收记录和验证记录与检验方法。

[!IMPORTANT]

非官方项目，由社区成员独立开发和维护。

在侧边栏把会话拖到另一个工作区——真迁移原始档案，而不是复制

🌏 中文 · English

📑 目录

• ✨ 功能
• 🚀 安装
• 🖼️ 特性巡礼
• ⌨️ 使用
• 🔌 如何接入 DSH
• 🤝 与其他插件共存
• 🧩 兼容性与卸载
• 🔐 安全台账
• ⚠️ 已知限制（含 可调策略）
• 🆕 最近版本

✨ 功能

DeepSeek Harness 侧边栏可以拖拽排序同一工作区内的会话，但拖到另一个工作区上会被静默忽略。本插件补上跨工作区迁移：

• 🖱️ 拖拽迁移：把空闲会话行拖到目标工作区标题行，确认后完成移动
• 📦 批量迁移 / 分组合并：Ctrl/Shift 多选后整批拖移，或用组标题「⋯」菜单「整组迁移…」；源分组清空后可一键删除，两条命令完成合并（单批至多 50 个，失败互不牵连）
• 🚚 真迁移 · 零 token：会话 ID 与完整历史原样保留，不复制第二条会话、不重新注入上下文
• 🏠 工作区搬家向导：项目文件夹被移动/改名后，一键把失效分组原地重定向到新位置；id、标题、排序、归档位保持，名下会话连同旧路径散件一起迁移
• 🛟 会话救援（设置 → 会话救援）：一键找回「失联」「未记账」「挂错分组」的会话；已归档会话可恢复；支持一键修复与筛选
• 🗑️ 回收站与备份：删除先进回收站，可还原到原位置或任意分组；迁移自动生成恢复快照，可按会话恢复或清理
• 🛡️ 数据保护：相同会话内容只保留一份物理快照，往返迁移不会无限增长；每次迁移仍写入历史，备份列表显示快照份数与占用
• ⏪ 移动历史与撤回：记录最近 100 次跨工作区移动，批量聚合为一条，整批可一键撤回
• 🧾 迁移任务中心：批量迁移逐项持久化记录（完成/失败、最后错误与尝试时间），失败项一键重试——按会话当前位置重新迁移，不用陈旧路径
• ⏳ 忙碌会话自动排队：运行中或写入句柄未释放的会话不会触碰文件，卸载或重启后自动重试；队列持久化，支持单项取消、单项重试和批量重试失败项
• 🔎 迁移预览：确认前展示来源、目标路径、冲突、运行状态、适配器和本次预计新增备份大小；已有内容快照会明确显示复用
• 📂 空分组清理 / 打开文件夹：只列出真正零成员的工作区；组菜单可直达系统文件管理器
• 🤖 Agent 工具：mover_list_sessions / mover_move_session / mover_repair_sessions / mover_doctor / mover_create_workspace / mover_rename_workspace 六个模型可调用工具——在对话里说「把这个会话挪到某组」即可触发与面板完全相同的备份回滚管线，也能新建、改名工作区；迁移、修复与改名执行前经宿主审批弹窗确认（改名在完全访问模式下免确认），未装 dsh-tools 的宿主自动停用

🚀 安装

dsh plugin --profile web add "github:PianoPrince/dsh-workspace-mover"
# 重启 dsh web 一次

零构建授权：纯 JavaScript 源码即产物（无 TypeScript、无构建步骤）。从 GitHub 安装时不需要 allowBuilds 构建授权。

npm 渠道

dsh plugin --profile web add dsh-workspace-mover

本地开发安装

dsh plugin --profile web add "link:C:/path/to/dsh-workspace-mover"

桌面版安装（DSH v0.2 桌面客户端）

1. 安装并打开官方桌面版，左侧进入「插件」页；
2. 点右上角「添加插件」，搜索 dsh-workspace-mover 安装并启用；
3. 完成——桌面 profile 与 web profile 相互独立，需要各自安装一次。

桌面 profile 由 Electron 应用专属管理（独立 CLI 不接受 --profile desktop），请以应用内插件页为准。

常见问题

现象 · 原因与解决 拖了但没反应 · 请在分组视图把会话行拖到工作区标题行；「扁平列表」视图没有标题行，本插件在该视图不激活 提示会话正在运行中 · 等该会话回合结束再拖即可 移动失败的 toast · 操作前有自动备份、失败会回滚；按提示处理后重试。详细原因见宿主日志中的 MOVE FAILED 移动成功但侧边栏没归位 · 刷新页面即可 有些会话从侧边栏不见了 · 打开 设置 → 会话救援 自动扫描并找回 升级 DSH 0.2 后，旧会话切换模型报 Unknown agent preset · 0.2 不再读取 0.1.x 旧格式的自定义预设目录，需迁移为声明行——与插件无关，完整步骤见 docs/dsh-0.2-preset-migration.md

🖼️ 特性巡礼

以下均为真实界面实拍（点击可放大）。

拖拽跨工作区迁移

· 把空闲会话行拖到目标工作区标题行，出现虚线高亮 · 确认框亮出目标工作区路径，一键移动 · 设置 → 会话救援：一键找回失联与未记账的会话 · ·

批量迁移 · 多选拖拽

Ctrl+点击选中多个会话（当前打开的会话自动带上），左下角亮出计数徽章；拖到目标工作区标题行即整批移动，Esc 清空 组标题「⋯」菜单里的「整组迁移…」：整组搬移，迁入后可删除已空的源分组（分组合并）

工作区搬家向导 · 实测全程

以下为一次真实搬家的完整记录：把 Test1 文件夹改名为 Test2 后，用向导原地修复工作区。

· 改名前：`Test1` 分组正常工作 · 改名后侧边栏仍显示旧分组（磁盘上文件夹已不在） · 打开设置 → 会话修复：「工作区体检」把分组标为「路径失效」，填入新路径 · 确认框亮出起讫路径与将要迁移的会话数 · 搬家完成：分组原地更名为 Test2，会话与历史原样保留 · ·

⌨️ 使用

拖拽跨工作区迁移

1. 重启后在侧边栏分组视图里，按住任意空闲会话行；
2. 拖到目标工作区的标题行（出现虚线高亮）松手；
3. 确认框显示目标工作区路径 → 点「移动」；
4. 完成 toast 提示；若侧边栏未自动刷新，手动刷新页面即可。

运行中的会话会被拒绝；移动失败会自动回滚并在 toast 中说明原因。

会话救援面板

1. 重启后打开 设置 → 会话救援，面板自动完成首次扫描；
2. 失联行：选目标工作区 → 点「迁移过去」；
3. 未记账行：点「补挂账」原地挂到路径匹配的工作区；
4. 挂错分组行：点「归位」或「全部归位」；
5. 一键修复：自动跑完可修复项，失败项隔离；
6. 支持按标题 / 会话 ID / 路径 / 分组筛选；
7. 已归档 / 回收站 / 备份：归档可恢复；删除进回收站，可还原或确认后彻底删除；迁移备份可恢复或清理。

对话里迁移（Agent 工具）

需要审批的工具在审批服务缺失时会拒绝执行，可改用设置中的会话修复面板。

1. 装有 dsh-tools 的宿主（web 与桌面版默认）自动注册六个模型工具：会话清单（只读）、迁移、一键修复、自检（只读）、新建工作区、工作区改名；
2. 在对话里说「列出我的会话」「把会话 X 挪到 Y 组」「跑一次修复」「自检一下」「用文件夹 /路径 新建一个叫 Z 的工作区」「把 Y 组改名为 Z」——模型先用清单工具把名字解析成精确 id，再执行动作；
3. 迁移与修复在动手前经宿主审批弹窗请你确认（与面板确认同级）；拒绝或关闭弹窗则不执行；两个只读工具（清单 / 自检）不弹确认；
4. 新建工作区：把一个已存在的文件夹登记为新分组；该文件夹（含指向它的符号链接）或该名称已被其他工作区使用时拒绝，不会在磁盘上创建文件夹，不弹确认；
5. 工作区改名：只改显示名，执行前弹窗确认；会话处于完全访问（danger-full-access）时免确认；与其他工作区重名时拒绝；
6. 宿主没有 dsh-tools 时自动停用，不影响面板与拖拽。

批量迁移

1. Ctrl/Cmd+点击加入多选，Shift+点击组内范围选择，Esc 清空；
2. 拖任一选中行到目标工作区标题行 →「全部移动」；
3. 或用 「⋯」菜单 →「整组迁移…」；源分组清空时可确认后删除（分组合并）。

工作区搬家向导

1. 文件夹被移动/改名后，工作区体检会把对应分组标为「路径失效」；
2. 填入文件夹现在的完整路径，点「搬家」；
3. 确认起讫路径与会话数量后执行；运行中的会话本次跳过，结束后可续跑剩余部分。

🔌 如何接入 DSH

本插件面向使用者只承诺以下接入原则（实现细节见 docs/ARCHITECTURE.md）：

1. 使用 DSH 官方扩展点挂载，不修改 DSH 或 dsh-market 的安装文件；
2. 会话归属变更走宿主提供的正式接口，不伪造持久化数据；
3. 插件自有数据（历史、备份、回收站）写在独立数据目录，与会话档案分开；
4. 与官方侧边栏同组排序互不干扰，只处理跨工作区场景。

🤝 与其他插件共存

设计上按「与生态共生」标准实现，冲突面很小：通信与样式使用独立命名空间；不改写官方安装文件；会话归属写入使用宿主正式接口。

同装插件类目 · 兼容性 · 说明 官方内置插件（0.2 起的 8 个：终端 / 网页搜索 / 子智能体等） · ✅ 无冲突 · 功能面不相交；Agent 工具经官方 dsh-tools 注册表共存，本插件工具名以 mover_ 前缀隔离 侧边栏增强 / better-sidebar / 终端 / 费用统计 / 记忆 / 导出分享 · ✅ 无冲突 · 面板与数据面完全不同 归档管理类插件 · ✅ 兼容 · 双方都使用官方归档数据，数据层一致（面板功能可能有些重复） 回收站 / 会话删除类插件 · ✅ 数据隔离 · 各插件维护独立的回收站目录，互不读写；建议只启用一家的删除入口，避免操作混淆 排序 / 置顶类插件 · ⚠️ 基本兼容 · 移动后会精确重排「最近更新」；与置顶/排序插件并存通常无碍，仅各自面板展示顺序可能不完全一致 重画侧边栏的插件（自绘工作区树） · ⚠️ 降级共存 · 对方若替换官方侧边栏结构，本插件可能暂时无法识别会话行——表现为功能不触发，不会损坏数据 其他会话移动器 · ❌ 建议二选一 · 同类插件可能重复处理同一次拖拽；本插件已覆盖移动 / 批量 / 合并 / 归位 / 归档恢复

🧩 兼容性与卸载

为什么自检显示“存储适配器”警告？

当前 DSH 未公开原始档案路径或原始字节迁移接口，插件使用宿主存储根目录和经过检查的 JSONL 文件布局进行迁移，因此显示 filesystem-fallback 警告。它表示兼容性降级，不代表迁移失败；请同时查看“存储布局”检查结果。宿主升级后应重新自检，布局未知或损坏时不要继续迁移。仅提供官方会话 handle、没有物理路径的宿主不支持物理迁移。

恢复快照独立于主会话档案；复用的快照保留首次保存时的路径，默认恢复到该路径，也可明确选择其他工作区。历史记录不意味着对应快照会永久保留，超出保留上限或手动清理后，该快照可能不存在。

版本兼容矩阵

插件版本 · 已验证 DeepSeek Harness · Node · 备注 2.4.0 · 0.2.1-rc.2 Desktop · ≥22 · 用户确认排队、迁移前后继续发送、两次重启、目标工作目录和工作区工具审批；自动滚动仅自动检查 2.3.0 · 0.2.0-rc.2 Desktop（用户验证部分场景） · ≥22 · 空闲会话迁移与快照复用已反馈通过；Web、队列进程重启和完整 runtime smoke 待验证 2.2.0 · 0.1.5-rc.1、0.1.5-rc.2、`0.2.0 桌面版`（0.2.0-rc.2 内核） · ≥22 · 存储布局自检、Agent 工具与桌面版实测；宿主缺 dsh-tools 时工具自动停用 2.0.3 · 0.1.5-rc.1、0.1.5-rc.2 · ≥22 · 真迁移 / 批量 / 救援 / 回收站 / 备份；首次发布 npm — · 0.2.0 web（0.2.0-rc.2） · ≥22 · 与桌面版同内核，已按同一代码路径适配；web 启动场景待回归

会话档案格式验证

以下“本地通过”指仓库沙盒 fixture，不代表官方 DSH runtime 逐格式实测。2.4.0 已在 Desktop 0.2.1-rc.2 完成排队、重启迁移、继续发送和工作区工具审批验收；下表逐格式的官方 runtime 状态仍待单独验收。自动滚动通过自动 DOM 检查，人工验收已豁免。详见Desktop 验收记录和格式兼容报告。

档案布局 · 本地沙盒 · 官方 DSH runtime v3 / v4 Zstd · 迁移与撤回通过；同目录选择最高代际并保留旧文件 · 待验收 legacy / v3 plain JSONL · 迁移与撤回通过，不升级代际 · 待验收 混合压缩编码 · 明确拒绝 · 待验收 文件名与 header 代际不符 · header 声明代际时，迁移前拒绝且字节不变 · 待验收

• engines 声明：package.json → engines.dsh ≥ 0.1.5-rc.1，engines.node ≥ 22（与 CI 矩阵 Node 22/24 一致）。
• 其他已知组合：dsh-market 1.45.1。不修改 DSH 源码，仅通过官方扩展点接入。
• 质量门禁：提交前运行 npm run check（语法检查 + 测试 + npm pack --dry-run）；CI 在 ubuntu / windows / macos × Node 22/24 上执行同等步骤。
• 市场卡片的「宿主要求未知」：GitHub-only 插件没有 npm 发布清单时，dsh-market 可能无法从远端元数据推导宿主版本；显示「未知」不代表运行时不兼容。
• 升级到 DSH 0.2 的预设迁移：0.2 不再读取 0.1.x 旧格式的自定义预设目录（$DSH_HOME.agent-presets），旧会话恢复会报 Unknown agent preset（与本插件无关，属宿主变更）。迁移步骤与实测记录见 docs/dsh-0.2-preset-migration.md。
• 卸载可逆：移除插件不会删除会话档案、工作区或官方记账。插件自己的历史、任务、备份和回收站数据仍保留在插件数据目录（见 docs/ARCHITECTURE.md）；移除后刷新或重启 DSH 即可清理注入的界面。
• 共存建议：不要与另一个跨工作区拖拽移动器同时启用；其他类型插件可按上表共存。

部分高级操作依赖较新的 DSH 能力；不支持时界面会明确提示，而不是静默失败。

🔐 安全台账（Safety Ledger）

每一次迁移都走同一条带安全边界的管线：字节级备份先行 → 逐步回滚 → 迁移后校验 → 恢复账本兜底。任何一步失败都会回到移动前的状态；连回滚都失败的极端情况会写入持久化恢复记录并在救援面板标红，等待人工确认——数据永不消失。

Never-does（绝不）：

• 绝不执行任何 git 写操作（commit / stash / reset / checkout 都不碰）；
• 绝不在字节级备份落盘之前改动任何文件；
• 绝不静默丢弃会话数据——恢复不了的极端情况会明确标红并保留现场；
• 绝不绕过确认执行破坏性操作（对话内的迁移 / 修复还须经宿主审批弹窗）；
• 绝不上传任何本地数据——插件无网络请求，全部工作在本机完成。

具体承诺：

• 移动前自动生成恢复快照；相同内容（忽略迁移产生的 cwd 变化）复用既有快照，搬运落地后再核对会话身份与路径，不符则整体回退；
• 每次移动都记入历史；历史记录保存来源、目标和所使用的快照，因此快照去重不会隐藏操作轨迹；
• 失败时恢复到移动前状态（文件与记账一并恢复）；
• 删除先进回收站，可还原到原位置或任意分组；彻底删除需二次确认；
• 无法自动恢复时，会在救援面板明确标出，需要人工确认；会话文件与备份始终保留；
• 近期打开过、仍驻留在 Harness 内存中的会话不能直接删除，需重启 Harness 后再删（界面会给出明确提示）。

失败路径优先保数据，不静默丢会话。

并非「任何错误都能自动恢复」：极端情况下会要求人工处理，但数据会留在原处。

⚠️ 已知限制

• 不支持把会话移入「Ungrouped」桶；
• 常驻内存的会话（近期打开过）不能直接删除，请重启 Harness 后再删；
• 若第三方插件整页重绘侧边栏，本插件可能暂时无法识别会话行（功能触发不了，不损坏数据）；批量拖拽时无法确认身份的行会被跳过并明确告知，不会猜一个 id 去移动；
• 「扁平列表」视图无工作区标题行，本插件在该视图不激活；
• 宿主大版本升级若改变内部结构，相关能力可能降级或需重启后生效；搬家向导在无法安全写入时会在改动任何文件之前中止并提示；
• 没有图形化设置页：官方设置页需要宿主提供 schemastery（插件目录下不可解析，静态引入会打断启动）。策略改用环境变量配置，见下表；mover_doctor 会报告宿主服务与存储布局的降级情况；
• 降级是可观测的：插件优先使用官方接口（取消归档 registry.unarchiveSession、改名 entity.setTitle），宿主没有时自动回退到等价实现。回退是静默的（功能不变），所以 mover.status.capabilities 会同时给出 unarchiveApi / setTitleApi 能力位，degradedFeatures 里也会列出 unarchive-official-api / set-title-official-api——真机上一眼能看出走的是哪条路。
• 存储适配器也会明确报告降级：公开 persistence 句柄可用但没有物理路径时，storageAdapter 为 official-handle，诊断与预览仍可用，物理移动会明确提示不支持；有物理根目录时标记为 filesystem-fallback，并由 mover_doctor 解释原因。

🔧 可调策略（环境变量）

策略 · 默认 · 环境变量 每个会话保留的物理快照数 · 20 · DSH_WORKSPACE_MOVER_BACKUP_KEEP 移动历史保留条数 · 100 · DSH_WORKSPACE_MOVER_HISTORY_LIMIT 单批移动 / 修复上限 · 50 · DSH_WORKSPACE_MOVER_BATCH_LIMIT 单个工作区搬家上限 · 200 · DSH_WORKSPACE_MOVER_REPOINT_LIMIT 救援扫描解析上限 · 400 · DSH_WORKSPACE_MOVER_SCAN_LIMIT 「清理 N 天前数据」默认天数 · 30 · DSH_WORKSPACE_MOVER_CLEANUP_DAYS

取值非法或越界时回退默认值——配置写错不会让功能失效。

🆕 最近版本

v2.4.0 · 2026-10-22

• Issue #5 安全迁移：运行中或仍驻留内存的会话进入持久化队列；等会话卸载或 DSH 重启、写入句柄关闭后再迁移，并保留工作目录变更历史。
• 工作区工具：mover_create_workspace 登记已有目录；mover_rename_workspace 只修改显示名称，并按宿主权限请求审批。
• 故障处理与界面清理：缺失存储根目录视为空列表，权限和 I/O 错误继续明确报告；指针离开侧栏或到达边界、拖动结束或取消、插件卸载时都会停止自动滚动。
• 验收：DSH Desktop 0.2.1-rc.2 的排队、继续发送、两次重启、目标工作目录及工作区工具审批通过；自动滚动仅完成人工豁免后的自动 DOM 检查。详见Desktop 验收记录和CHANGELOG。

v2.3.0 · 2026-10-13