# dsh-workspace-mover
当前版本：**2.4.3**。已通过 DSH Desktop `0.2.1-rc.5` 删除、还原、即时显示、继续发送及语言切换验收，详见[2.4.3 验收与 PR 审查记录](docs/compatibility/issue-11-pr-12-review-2026-11-02.md)。
支持即时迁移的会话：空闲时释放写入句柄、实际搬移并重新加载；运行中可取消，或明确选择「停止任务并迁移」。迁移保留标题和历史。安装或热更新后请彻底重启 DSH 一次，以接入会话生命周期；无法安全释放的会话会明确阻止拖动迁移。旧队列仍保留恢复与取消入口。后端验证与实际验收结果见 [即时迁移记录](docs/compatibility/immediate-migration-2026-10-26.md)。
> [!IMPORTANT]
> 非官方项目，由社区成员独立开发和维护。
## 📑 目录
- [✨ 功能](#-功能)
- [🚀 安装](#-安装)
- [🖼️ 特性巡礼](#️-特性巡礼)
- [⌨️ 使用](#️-使用)
- [🔌 如何接入 DSH](#-如何接入-dsh)
- [🤝 与其他插件共存](#-与其他插件共存)
- [🧩 兼容性与卸载](#-兼容性与卸载)
- [🔐 安全台账](#-安全台账safety-ledger)
- [⚠️ 已知限制](#️-已知限制)（含 [可调策略](#-可调策略环境变量)）
- [🆕 最近版本](#-最近版本)
---
## ✨ 功能
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 的宿主自动停用
## 🚀 安装
```bash
dsh plugin --profile web add "github:PianoPrince/dsh-workspace-mover"
# 重启 dsh web 一次
```
> **零构建授权**：纯 JavaScript 源码即产物（无 TypeScript、无构建步骤）。从 GitHub 安装时**不需要** `allowBuilds` 构建授权。
npm 渠道
```bash
dsh plugin --profile web add dsh-workspace-mover
```
本地开发安装
```bash
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](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](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.3 | `0.2.1-rc.5` Desktop | `≥22` | 用户确认驻留会话删除、回收站还原、即时显示、继续发送、语言切换及迁移；运行中拒绝删除由自动测试覆盖 |
| 2.4.2 | `0.2.1-rc.2` Desktop | `≥22` | 用户确认即时迁移、当前界面继续发送、运行中取消/停止迁移、标题保留及重启恢复 |
| 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 验收记录](docs/compatibility/issue-5-desktop-acceptance-2026-10-22.md)和[格式兼容报告](docs/compatibility/dsh-0.2.0-rc.2-2026-10-13.md)。
| 档案布局 | 本地沙盒 | 官方 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/dsh-0.2-preset-migration.md)。
- **卸载可逆**：移除插件不会删除会话档案、工作区或官方记账。插件自己的历史、任务、备份和回收站数据仍保留在插件数据目录（见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)）；移除后刷新或重启 DSH 即可清理注入的界面。
- **共存建议**：不要与另一个跨工作区拖拽移动器同时启用；其他类型插件可按上表共存。
部分高级操作依赖较新的 DSH 能力；不支持时界面会明确提示，而不是静默失败。
## 🔐 安全台账（Safety Ledger）
每一次迁移都走同一条带安全边界的管线：**字节级备份先行 → 逐步回滚 → 迁移后校验 → 恢复账本兜底**。任何一步失败都会回到移动前的状态；连回滚都失败的极端情况会写入持久化恢复记录并在救援面板标红，等待人工确认——数据永不消失。
**Never-does（绝不）：**
- 绝不执行任何 git 写操作（commit / stash / reset / checkout 都不碰）；
- 绝不在字节级备份落盘之前改动任何文件；
- 绝不静默丢弃会话数据——恢复不了的极端情况会明确标红并保留现场；
- 绝不绕过确认执行破坏性操作（对话内的迁移 / 修复还须经宿主审批弹窗）；
- 绝不上传任何本地数据——插件无网络请求，全部工作在本机完成。
**具体承诺：**
- **移动前自动生成恢复快照**；相同内容（忽略迁移产生的 `cwd` 变化）复用既有快照，搬运落地后再核对会话身份与路径，不符则整体回退；
- **每次移动都记入历史**；历史记录保存来源、目标和所使用的快照，因此快照去重不会隐藏操作轨迹；
- **失败时恢复到移动前状态**（文件与记账一并恢复）；
- **删除先进回收站**，可还原到原位置或任意分组；彻底删除需二次确认；
- **无法自动恢复时**，会在救援面板明确标出，需要人工确认；会话文件与备份始终保留；
- **空闲且已被插件跟踪的驻留会话**可安全释放后删除；运行中的会话仍拒绝删除。插件加载前打开、未捕获生命周期句柄的驻留会话，需要彻底退出并重启 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.3 · 2026-11-03
- 空闲且已跟踪的驻留会话可安全删除，无需先重启；运行中或未跟踪的会话仍受保护。
- 回收站还原、备份恢复和取消归档后刷新会话列表。归档后删除的会话还原时仍保留归档状态，按提示取消归档即可回到侧栏。
- 界面跟随 DSH 中英文设置（感谢 PR #12 的 EzraRT），旧宿主保留浏览器语言回退；幽灵记录区分档案位于别处或位置未知，不自动清除归属。
- Desktop `0.2.1-rc.5` 已验收；完整说明见 [CHANGELOG](CHANGELOG.md) 和[验收记录](docs/compatibility/issue-11-pr-12-review-2026-11-02.md)。
### v2.4.2 · 2026-10-26
- **即时迁移**：已接入生命周期的空闲会话直接释放句柄、搬移并重新加载；运行中可取消或明确选择“停止任务并迁移”。
- **标题修复（#10）**：对齐标题缓存归属，兼容新版单记录缓存，避免迁移及归档列表误显示“未命名会话”。
- **迁移后继续对话**：等待旧界面引用释放后重新打开，修复“会话不可用”；桌面提示改为必要时彻底退出并重启。
- **验收**：Desktop `0.2.1-rc.2` 上述流程及重启后继续发送均通过。更新后请彻底重启 DSH 一次。见[验收记录](docs/compatibility/immediate-migration-2026-10-26.md)和[CHANGELOG](CHANGELOG.md)。Web 与旧版宿主的完整验收仍待补齐。
### 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 验收记录](docs/compatibility/issue-5-desktop-acceptance-2026-10-22.md)和[CHANGELOG](CHANGELOG.md)。
### v2.3.0 · 2026-10-13
- **恢复快照复用**：会话内容相同时复用已有快照，忽略迁移产生的 `cwd` 变化；内容发生变化才新增备份。每次迁移仍记录来源、目标及快照引用，默认保留最多 20 个物理快照，兼容旧备份。
- **预览更清晰**：确认前显示实际来源、目标路径、冲突、运行状态及本次新增备份大小；复用时明确显示“复用已有快照”。单会话确认框支持显式选择目标工作区，修复往返迁移时目标识别错误。
- **忙碌会话队列**：运行中的会话不触碰文件，进入持久化队列，空闲后自动尝试；支持取消、单项及批量重试。真实 DSH 进程重启恢复仍待实测。
- **存储适配器与格式诊断**：显示当前适配模式及降级原因；支持 v3/v4 和 plain/Zstd 的沙盒验证，区分不支持的格式、未知布局和损坏数据，不强制升级旧格式。
- **分支与便携包接口**：可明确选择包含后代分支；Portable Bundle 提供导出、校验和及默认 dry-run 导入接口，冲突与已知空间不足会阻断。当前只有沙盒验证，尚未完成真实 runtime 验收。
- **恢复修正**：未指定文件时选择最新备份；导入空间估算包含附件。新增 npm 周下载量徽章。
### v2.2.0 · 2026-10-09
- **批量移动不再"猜"会话身份**：权威 id 通道不可用时，旧兜底会按顺序顶替一个 id；现在无法确认的行一律跳过并在确认框里如实说明（全部无法识别则整体中止，不动任何文件）
- **目标分组解析必须自证**：标题/路径都不匹配时不再按 DOM 序号回退——官方侧边栏会隐藏目录已失效的分组，按序号回退会把会话搬进相邻分组
- **客户端热重载不再叠加实例**：7 个监听器与菜单 observer 全部经宿主 effect 释放，并加防重复装载；此前重载会叠加第二份，出现双确认框与双请求
- **存储布局自检**：反推一个真实会话的目录并验证，结果进入 `mover.status` 与自检面板（`data-layout`），把"某天突然全都找不到"提前变成可见的降级提示
- **孤儿备份可见可清**：会话彻底删除后其迁移备份会永久残留；现在会标记孤儿组并支持一键清理，「彻底删除」时也可顺带勾选清理
- **归档列表说明截断**：扫描只解析最新 400 条，较旧的归档会话可能不在列表中——UI 现在会说明
- **策略可调**：物理快照数 / 历史条数 / 单批上限 / 搬家上限 / 扫描上限 / 清理天数支持环境变量覆盖（`DSH_WORKSPACE_MOVER_*`）
- **官方接口替代私有耦合**：取消归档改走官方 `registry.unarchiveSession`（保留回退通道）；标题同步改用官方 `entity.setTitle` 并与路径重定向解耦；`record.sessionIds` 的读取收敛为单一访问器
- **可达性与文案**：弹窗补 `aria-labelledby`、打开即聚焦、Tab 循环；Esc 尊重"输入框聚焦时不清空"；清理死文案与两处漏出的英文硬编码，新增中英词条对账告警
- **生态元数据**：新增 `screenshots.json`（自主控制市场卡片截图）；声明宿主包 `peerDependencies`（全部 `*` 且标 optional——它们只是元数据，真正的版本下限是 `engines.dsh`，运行时不匹配由能力位如实上报）；修正 README/ARCHITECTURE 中长期存在的工具数量与兼容性描述漂移
- **修正**：上述 peer 范围最初按生态惯例写成"显式预发布分支"，结果宿主把本插件判为**与 `0.2.0-rc.2` 不兼容**——`<0.2.0-0` 这个上界会排除**所有** 0.2.0 预发布版（npm 的预发布规则按 `||` 集合逐条判定，且 `0.2.0-rc.2 > 0.2.0-0`）。现全部改为 `*`，并加了回归测试覆盖 0.1.5-rc.1 ~ 1.0.0
- 测试 108 → 144（新增客户端 DOM 用例 10 个、策略/Config 与 peer 范围回归用例 13 个，以及能力位/自检/备份 GC 等宿主侧用例）
### v2.1.1 · 2026-10-05
- `mover.doctor` 自检：面板新增「自检」按钮 + `mover_doctor` 模型工具——服务、数据目录、恢复记录、工作区路径约 13 项检查，pass/warn/fail 三态汇报，DSH 升级后先自检再动手
- 信任资产：tagline 下突出 npm 一行安装命令（`dsh://` 深链按钮因 GitHub 剥离自定义协议而移除）、dsh.so 风险徽章（已收录且 L5 实测 / risk low）、dsh-plugin-registry 收录徽章、"DSH tested 0.2.0-rc.2" 徽章
- 兼容性报告：`docs/compatibility/` 落地桌面版实测记录，此后每适配一个 DSH 版本新增带日期报告
- 安全承诺章节品牌化为「安全台账（Safety Ledger）」+ never-does 清单
### v2.1.0 · 2026-10-04
- Agent 工具：`mover_list_sessions`（只读清单）/ `mover_move_session`（迁移单个会话）/ `mover_repair_sessions`（一键修复）注册进官方 `dsh-tools`，在对话里即可调用
- 变更类工具执行前经宿主审批接缝请用户确认：拒绝 / 关闭 / 无应答一律不执行（fail-closed）
- 与面板共用同一条加锁、先备份、迁移后校验的管线；无 `dsh-tools` 宿主自动跳过注册
- 桌面版（0.2）实测通过：修复热重载后「inactive context」移动报错；确认框改为不透明，不再与底层文字重叠
- `mover.status` 新增 `agentTools` 能力位
### v2.0.3 · 2026-09-21
- 首次发布到 npm：`dsh plugin --profile web add dsh-workspace-mover`
- 本地质量门禁 `npm run check`；CI 与之对齐
- README 增加 npm / DSH 徽章与宿主兼容矩阵
完整变更记录见 [CHANGELOG.md](CHANGELOG.md)。
实现与架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## License
MIT
