# 更新与数据迁移

0.4.2 将公开名称统一为 `dsh-cuigengji-plugin`。旧名 `dsh-cuigengji` 安装的用户需要由升级 Agent 完成一次[安装名称迁移](package-name-migration.md)，转接启用项和配置，避免两个包同时加载。小说目录、内部 ID、工具名与数据格式保持兼容。

0.4.0 是第一次把“可维护升级”作为正式能力发布的版本。用户仍然通过 DSH 桌面版的原生插件管理安装，插件加载后会自动处理已有催更姬数据。用户不需要 Git、Node.js、pnpm，也不需要手工移动文件。

0.4.1 修复 GitHub 地址直接安装：在 DSH“添加插件”的“包名或地址”中填仓库地址即可。成品包安装继续可用；数据布局与 0.4.0 相同，插件启动会为新版本建立升级前快照并核对已有工作库。

已有用户更新推荐使用新版本的 Release `.tgz` URL。当前宿主重复安装同一个无 ref 仓库地址时，可能沿用锁定旧提交并报“无法从依赖变更中确定安装了哪一个包”；安装或重启成功都要以实际加载版本与文件为准。详细诊断见 [Agent 安装指南](agent-installation.md)。

## 更新时发生什么

负责更新的 Agent 先安装发布包并让 DSH 完整重启。催更姬启动阶段会依次完成：

1. 读取当前配置的数据根。优先使用宿主传入的 `dataRoot`，其次是 `CUIGENGJI_DATA_ROOT`，最后才使用系统默认目录。
2. 在数据根旁建立一次完整的原始快照。快照包括作品、章节正文和历史、回收站、规划页面与批注、人物和世界设定、关系、预设、导入原件、绑定、请求记录和作者放在数据根中的额外文件。
3. 恢复上一次未完成的文件事务，再执行 v1/v2/v3 到当前物理布局的迁移。迁移由存储层完成，保持内部 ID、历史版本、来源引用和作者内容。
4. 在迁移前后重建完整工作库，比较逻辑摘要并检查章节正文哈希、设定关系、规划页面和绑定引用。校验通过才标记可用。

状态写入数据根的 `runtime/upgrade.json`。重复重启是幂等的：已经完成的同版本更新会复用原始备份，不重新制造备份，也不会重写作品内容。迁移期间不会把正文或工作数据拼进系统提示词。

## 给 Agent 的验收步骤

安装结果不能只看插件管理器显示“安装成功”。重启后调用维护工具：

```json
{"action":"status","args":{}}
```

然后使用真实加载版本和数据根进行校验：

```json
{"action":"verify","args":{"expectedVersion":"0.4.2","expectedDataRoot":"C:\\Users\\用户\\AppData\\Local\\cuigengji"}}
```

只有 `status.status` 为 `ready` 且 `verify.verified` 为 `true`，才能向用户报告更新完成。校验结果包含作品、章节、历史、设定、规划和绑定数量，不返回正文内容。

如果状态是 `failed`，保留 `failedStage`、错误代码、备份路径和数据根，先不要打开空库或重新导入。中断的迁移可让 DSH 再完整重启一次继续；若仍失败，再把这些元数据提供给维护者。升级前快照位于数据根旁的 `.cuigengji-upgrade-backups/<数据根摘要>/<本次升级>/data`，旁边的 `manifest.json` 记录逐文件 SHA-256 和目录清单，它是恢复依据。

## 恢复与回滚

先区分两类恢复：

- **升级中断**：保留 `runtime/upgrade.json`、`transaction.pending.json` 和事务暂存文件，重启新版即可在同一个锁下恢复并继续，不手工改 JSON。
- **确需回到旧版**：先完整停止 DSH，保留升级后所有新写入，再使用本次升级前的原始快照和对应旧插件包。先校验 `manifest.json`，把快照的 `data` 复制到新的恢复目录，确认旧包可读取、作品与历史完整，再切换配置到恢复目录。原数据根和完整快照继续保留，不把它们覆盖或删除。

只把新包换成旧包并不等于回滚。旧 0.3.13 使用单文件工作库，无法读取布局 4；旧的 `store.json` 也是升级时的历史快照。已有新正文时先通过新版导出保留，回滚需明确核对会损失或暂时不可见的内容，并获得作者对恢复范围的确认。

数据根如果是链接目录，或复制权限/空间不足，自动升级会停止并保留错误，不把不完整快照当成可恢复备份。普通文件和目录都纳入原始快照；DSH 的浏览器草稿与偏好保留在原 profile 中，不由此快照移动。

## 这次更新包含什么

- 正文、目录、回收站、章节排序、字数统计和编辑草稿继续使用原有版本记录。
- 规划升级为多页共享画布：节点是情节单元，可以分组、连线、写便签和讨论框，Agent Skill 明确了多线推演和页面工作台的用法。
- 设定、角色卡、世界书和关系图支持分组、筛选、批量管理和可读文件名；酒馆世界书、角色卡和写作预设导入保留原始文件。
- 工作数据支持按作品、正文、设定、规划、预设和完整工作库导入导出，导入先预览和校验，再原子写入。
- 写作预设在启用后随插件的稳定写作要求提供给 Agent；正文、规划和设定仍按需读取。
- 新增 Windows 无 Git 的预构建 `.tgz` 发布资产和面向安装 Agent 的维护 Skill。

DSH 自己的聊天记录、附件、API 密钥和桌面偏好由 DSH 管理，不属于催更姬工作数据导出；不要把它们当成插件迁移失败的证据。