generic-migration

通用插件迁移方法

一套严谨的流程，用于将插件迁移到可能包含破坏性变更的上游版本。以下内容与框架无关：不涉及产品名称、版本号或 API 标识符。只要上游项目提供了变更日志和发行说明，就应配合阅读。

0. 基本原则

• 切勿盲目迁移。 如果没有阅读迁移区间内每个版本的上游变更日志（起始版本 → 目标版本，含首尾），就只能靠猜。
• 先盘点，再修改。 先列出插件涉及的内容，胜过逐次崩溃后才发现问题。
• 每次只改一层，并确保旧安装在新安装经过验证前仍可运行（并行安装、使用不同的数据目录）。

1. 盘点耦合面

修改代码前，以只读方式扫描插件，并记录所有与宿主耦合的位置。通用耦合检查清单：

1. 清单 / 元数据 — 声明的兼容范围、入口点、权限、插件请求的功能。
2. 宿主 API 导入 — 从宿主或其 SDK 导入的所有模块、符号或类型；注明哪些在加载时使用，哪些在调用时使用。
3. 生命周期与事件 — 激活钩子、事件订阅、资源释放。
4. 服务与 RPC — 插件使用或提供的服务；进程间或请求／响应通道及其负载结构。
5. UI 扩展 — 命令、视图、面板、菜单、主题、键绑定。
6. 持久化 — 插件读取或写入的文件、数据库或键值存储，包括架构版本和迁移代码。
7. 进程与 I/O 接缝 — 启动的子进程、套接字、管道、宿主生成内容（日志、CLI 文本、序列化状态）的解析器。
8. 配置 — 读取／写入的设置键、插件依赖的默认值，以及这些键面向用户的文档。
9. 依赖项 — 与宿主共用的包（存在重复实例的风险）、对等依赖范围、运行时版本下限。

对于每个项目，记录：文件／行号、具体耦合内容，以及你的确信程度。只有在说明扫描了什么以及无法排除什么之后，“未发现”才有意义。

2. 阅读整个迁移区间，而不只是起止版本

迁移区间内的变更会相互影响。阅读每个中间版本的发行说明和差异，并建立一份净状态表：

• 某字段在中间版本中被移除、随后又恢复，净变化为零——不要将其“迁移”掉。
• 某重命名分两步发生（A → B → C），直接从 A 迁移到 C。
• 行为变更（默认值、顺序、时序）与 API 移除同样具有破坏性；请明确列出。

将每项上游变更分类为：破坏性（必须修改）、行为性（必须重新验证）、增补性（可选）或信息性。

3. 先映射，再修改

将每个盘点项（§1）映射到迁移区间内的变更（§2）。然后按依赖顺序修改：

1. 首先修改清单和兼容范围——宿主可能会拒绝加载其他所有你修复的内容。
2. 宿主 API 表面：重命名、移除、签名变更。
3. 生命周期／事件／服务。
4. 持久化迁移（绝不修改用户唯一的副本；首次运行时备份后再迁移，或安全失败）。
5. UI 和配置。
6. 依赖项对齐：共用包必须解析到宿主的实例；检查已安装目录树中是否存在重复副本。

4. 分层验证

先进行成本低的验证；每一层都必须通过，下一层的结果才有意义：

1. 静态检查：类型检查、lint，以及插件自身的单元测试。
2. 安装时检查：宿主接受清单并加载插件，且没有警告。
3. 冷启动检查：启用插件后，实际宿主进程能够启动；检查日志中的弃用和回退警告，而不只是确认没有崩溃。
4. 功能探测：每项主要功能至少验证一条真实的端到端路径，包括未迁移的功能（行为悄然偏移的情况往往藏在这里）。
5. 数据检查：迁移一份真实持久化数据的副本；验证往返转换和降级行为。
6. 回滚演练：证明可以回退——针对迁移后的数据重新安装旧版本，并确认其仍能正常工作，或确认已有恢复路径。

5. 规范与陷阱

• 优先采用宿主文档中说明的替代方案，而不是自行重新实现已移除的行为。
• 把“类型检查通过”视为验证的起点，而非终点。
• 已弃用但仍能工作的功能迟早会出问题：即使超出范围，也要记录下来。
• 如果变更的语义不明确，请阅读目标标签对应的上游源代码；不要根据一行变更日志猜测数据结构。
• 保留书面迁移日志：记录更改内容、原因和验证结果。这份记录能让他人信任此次迁移。