用途：这是面向 Motoko 迁移链（mops 管理的 migrations/ 目录）故障的深度排查参考。日常编写迁移、决定隐式还是显式、给新文件命名，应由 migrating-motoko-actors 覆盖；本技能只在迁移诊断与源码不符、迁移文件写入失败、链中第一个文件 OldActor 非空、或任务要求移除迁移、恢复内联初始化器、回到 (with migration = ...) 时查阅。
运行时机制：整条链编译进后端 wasm，没有独立迁移产物，改任一迁移文件都会改变 wasm。已应用迁移按模块名（去掉 .mo 的文件名）记录在 canister 持久元数据中；升级时只重放尚未应用的迁移，跨多版本部署可在一次升级中补齐。全新安装按字典序重放链中每个文件，因此历史上添加过的每个迁移都会在所有全新安装中永久执行。由此得出：重命名迁移会改变其身份，文件名永久有效；编辑已应用的迁移对已运行过的 canister 不可见，运行时会按名跳过。
检查器对比对象：mops check 将链与已部署 canister 的稳定签名（.most 快照）比对，而非本地 git 历史；因此诊断可能指出源码中已不存在的字段；一待处理迁移上限只统计尚未部署的文件；.most 头部稳定签名主版本标识持久化模型（1 经典、3 旧式内联、4 增强迁移链），达到 4 后不可回退。
常见诊断：M0250 稳定字段带内联初始化器，应改为类型声明并把初始化表达式移入待处理迁移的 NewActor；M0254/M0267 初始 actor 缺少字段，需在待处理迁移 NewActor 中补上；M0170 兼容性错误，应新增或扩展待处理迁移显式转换；M0255 稳定签名降级，通常因链或 mops 迁移配置被删，不支持降级，应恢复；链起点与基线不符，首个迁移 OldActor 未描述实际状态，勿改写为 {}；M0268 迁移目录与已部署历史不一致，已应用迁移被编辑、删除或重排，需恢复原样并以新迁移表达变更，只有最旧的迁移可裁剪；M0014 有副作用的 actor 体（旧工具链）；IC0503 缺失迁移变量，运行时出现，应新增迁移供给字段，不可编辑旧文件；IC0505 无效自定义段，仅安装失败，构建与检查可通过，源于链的稳定类型历史超出平台自定义段限制，本地无法修复。
冻结的迁移文件：冻结编码运行时不变式，不要 chmod、删除、重命名或绕过；仍待处理的迁移未冻结，可直接编辑，不必为同一变更另加文件。
转换项目：从旧式内联迁移转换而来的项目，链首通常是恒等迁移，OldActor 是转换前稳定形态、NewActor 原样传递，这是正确的，不要简化为 {} 或重新播种字段，否则会丢弃活跃状态；转换前历史是承重的，全新安装会从最后一个旧式 schema 重放。分叉或复用转换项目同样继承该链。
受保护配置与单向性：平台拥有的 [canisters.<name>.migrations] 段、链路径与 check-limit 不可增删改；不要为提高 check-limit 消除待处理迁移过多错误，应合并进单个待处理迁移；链目录由 chain = ... 决定，默认 src/backend/migrations。增强迁移链是单向的，无支持路径回到旧式持久化：模型按项目固定，编译器拒绝签名降级（M0255），已应用迁移按模块名识别，冻结平台无法改写历史。若任务要求删除 migrations/、恢复内联初始化器或重新引入 (with migration = ...)，应说明不可行，并提供前向等价方案：新增迁移把状态重塑为用户所需形态。
保持链短的原因：每部署版本一个迁移并非形式要求。wasm 自定义段编码整个稳定类型历史，随迁移数量和稳定类型规模增长，直至超过平台约 1 MiB 限制，此时 mops build 与 mops check 仍成功，仅安装被拒（IC0505），重试无法恢复；每次全新安装要在一个消息内重放所有文件，GC 只在消息边界运行，中间状态全程存活，可能更早耗尽内存；重放递归深度与链长成正比；wasm 体积与编译时间随每步增长，.most 签名序列化整条链。因此要合并变更、保持稳定类型精简，绝不添加内容只是旧逻辑的迁移。
静态 actor 体：actor 体不得做事，稳定字段是类型声明，取值来自链。初始化只能放在迁移函数（每次安装/升级运行一次）或正常操作中惰性调用的幂等逻辑里；顶层播种会在每次升级重跑并覆盖活跃状态。
无法解决时：不要通过放宽受保护配置、删除或重命名历史、改写冻结文件来开路，那会把构建失败变成数据丢失。若链与已部署签名确实不一致且上述诊断无法解释，应停止并报告不一致：检查器指出的字段、最新迁移 NewActor 声明的内容、main.mo 声明的内容。
相关技能：migrating-motoko-actors（如何编写迁移，正常路径）、writing-motoko（语言参考、actor 与 mixin 规则、核心库）。