在整站迁移前需要准备页面清单、模块目录与设计规范时…

当用户决定把一个现有站点整体迁移（重设计流程）时，按顺序跑 extract --prep、direct --prep、prototype --prep、assets prep 和 dynamics 门禁，每阶段确认后再进入下一阶段，产出 migrate 所需的类型化页面清单、已确认模块目录与 canon。

适用场景

解决思路

1. 先跑主技能的 setup（impeccable 依赖检查、上下文加载、状态读取），并做流程守卫：若 state.json.flow 为 replica 则拒绝执行并提示 `$stardust prepare-migration --switch-flow`；若 flow 缺失，先判定——用户说“1:1”“exact replica”“same design”“faithful”“re-platform”则本技能不适用，交给 replica；普通迁移请求则问一次保留还是重设计（hands-off 模式默认 redesign 并记入 direction.md），然后写入 flow: "redesign"。
2. 校验 stardust/state.json 存在且至少有一个已抽取页面，否则建议 `$stardust extract <url>` 并停止。
3. 校验 stardust/direction.md 存在且有生效方向，否则建议 `$stardust direct` 并停止。
4. 检查各阶段完成情况以决定起点：extract 完成 = state.json 中每页 type 非空且 current/pages/<slug>.json 含 slots 块；direct 完成 = DESIGN.json.extensions.modules[] 全部 status: confirmed 且存在 colorReservations 与 metadata 块；prototype 完成 = 每个页面类型至少有一个已批准原型、stardust/canon/ 已填充、DESIGN.json.extensions.canon 已填充；assets 完成 = stardust/migrated/assets/ 有 favicon 变体且字体已下载；dynamics 完成 = stardust/dynamic-features.md 存在且每行都有处置结论，有索引型列表时 helix-query.yaml 存在（否则 Phase 4.5 记录为 none）。默认从最早未完成阶段恢复，除非 --from 覆盖。
5. 支持输入参数：--from <phase>（extract | direct | prototype | assets | dynamics，从指定阶段恢复）、--skip-confirm（跳过每阶段确认门，hands-off 模式隐含此行为）、--canon-from <slug>（转发给 prototype --prep，覆盖默认 canon 作者 home）、--refine-module <module-id>（重进 Phase 2 的模块目录步骤，把反复出现的 bespoke slot 提升进该模块的 slot schema 即 DESIGN.json.extensions.modules[]，展示变更待确认后停止，不重跑整个级联）。
6. Phase 1：调用 stardust extract 技能并传参 --prep（Claude Code 形式：`Skill { skill: "stardust:extract", args: "--prep" }`），它会带五个 --prep 覆盖项跑标准抽取流程（提升上限、页面类型化、模块候选、类型化 slots、prep 摘要）。完成后原样展示摘要、标明流程并设门禁：`Flow: redesign — the design changes while migrating. Say \`switch to replica\` now if it is to be kept. Confirm and continue? (yes / refine "<phrase>" / switch to replica)`。用户选 yes 进入 Phase 2；选 switch to replica 则停止本流程并运行 `$stardust replica <url> --switch-flow`（刚产出的 extract 可被 replica Phase 1 复用，其余不复用）；选 refine "<phrase>" 则带细化要求重跑 extract --prep 并重新展示摘要循环。
7. Phase 1 与 Phase 2 之间执行来源守卫：按 state-machine.md § Provenance validation 对清单中每页调用 validateProvenance(page)，若有页面缺少实时渲染证据则带错误中止级联。成功时输出 `Provenance OK on 127 pages.`；失败时输出失败页数与中止提示，并列出需重跑的 slug 命令 `$stardust extract --refresh <slug>`。
8. Phase 2：调用 stardust direct 技能并传参 --prep（`Skill { skill: "stardust:direct", args: "--prep" }`），它会跑五个 --prep 覆盖项（类型目录确认、模块目录定稿、颜色预留、方向重评估、品牌元数据默认值）。展示摘要并设门禁，用户选项同 Phase 1（yes / refine "<phrase>"）。
9. Phase 3：调用 stardust prototype 技能并传参 --prep，已知 canon slug 时附加 --canon-from <slug>（`Skill { skill: "stardust:prototype", args: "--prep --canon-from <slug>" }`）。它会为每个页面类型补齐一个已批准原型，并按 canon-extraction.md 写回 canon：首次批准建立 canon，后续批准扩展 canon（冲突默认记为 deviation）。此阶段通常最耗时，每个原型走完整循环（shape brief、craft、浏览器打开、迭代、批准），每个原型落地时向用户流式汇报进度。展示摘要并设门禁。
10. Phase 4（assets prep，无底层 SKILL，跑一段图像处理 + 下载例程）：从 stardust/current/assets/favicon.<ext> 生成 favicon 变体到 stardust/migrated/assets/：favicon-512.png、apple-touch-icon.png（180×180）、icon-192.png、icon-512.png。
11. Phase 4 字体下载：扫描 stardust/canon/canon.css（及 header.html / footer.html）中含外部 URL 的 @font-face 规则，逐个下载到 stardust/migrated/assets/fonts/<basename-with-hash>.<ext>，把 canon 文件中的 @font-face url(...) 改写为本地路径；已下载（sha 比对）则跳过；下载失败记警告（字体保留外部 URL，migrate 会按页记 metadata-override 警告）。
12. Phase 4 品牌资产审计：核对 logo、favicon 及 canon 模块渲染引用的媒体文件是否都在 stardust/current/assets/，把缺失资产报给用户。展示摘要并设门禁。
13. Phase 4.5（动态表面，导入前门禁，即 dynamics 的 Phase 1–3，在 assets prep 之后、任何批量导入之前运行）：委托给 skills/dynamics/SKILL.md——先 Detect：若 Phase 1 未跑 --dynamics 则重跑 `extract --dynamics`（reach），再跑 `dynamics-detect.mjs --from-state stardust/state.json --reach stardust/current`（depth 作用于原型）；再 Classify + triage：跑 `dynamics-plan.mjs [--target-origin <host>]` 为每行起草四个轴，整理进 stardust/dynamic-features.md（§ Listings contract 含 helix-query.yaml、§ Features、§ Decision batch、§ Register）与 stardust/dynamic-features-plan.md；最后 Gate：每行都有处置结论即通过，两节都写 "none" 也算通过；门禁不阻塞静态路径，只阻塞静默回归。摘要行：`dynamic surface: N findings · self K · owner batch M · host-bound H · listings L dynamic / S static`。
14. 输出最终报告：列出各阶段结果（Phase 1 页数/类型数/模块候选数，Phase 2 类型与模块已确认及元数据已设，Phase 3 已批准原型数与 canon 已写，Phase 4 favicon 变体 + 字体 + 品牌资产就绪，Phase 4.5 动态表面统计），并提示下一步 `$stardust migrate`。
15. 失败处理：无 state.json 或无可抽取页面时建议 `$stardust extract <url>` 并停止；无生效方向时建议 `$stardust direct` 并停止；用户拒绝某阶段则干净停止，状态保持一致的中间态，可用 `$stardust prepare-migration --from <phase>` 恢复；底层技能失败则原样上报不推进；Phase 3 非 canon 作者的批准出现 canon 冲突时默认记为 deviation，若要逐冲突覆盖（提升为 canon / 拒绝并重迭代 / 记为 deviation）在该阶段确认门禁时提出；Phase 4 资产下载失败则继续运行并在摘要中记录，migrate 后续按页给警告。
16. 并发与幂等：state.json 写入按 slug 合并，可与其他并行通道共存，但同一项目上不要同时跑两个 prepare-migration（会在 canon、模块目录等顶层产物上竞争，last-write-wins 且可能损坏 canon），也不要为此加锁；重跑时从最早未完成阶段（或 --from 指定阶段）恢复，各底层技能自身幂等（已类型化页面不重打、已确认模块不重提、已批准原型不重做、已生成 favicon 变体不重生成、已有 dynamic-features.md 只细化不重写）；全部完成后再跑为 no-op，除非输入变化（extract 发现新页面、方向被编辑、canon 作者原型被重迭代等）。

适用边界 · 注意事项

• 同设计迁移（保留原设计的 1:1 / exact replica / same design / faithful / re-platform）不适用——replica 会跑自己的 preserve 模式 prep 级联，绝不要把 prepare-migration 与 replica 串联。
• 不用于执行迁移本身（用 `$stardust migrate`），也不用于转换单个页面（用 `deploy`）。
• 依赖 Node 22+、可从项目解析的 Playwright with Chromium、PATH 上的 playwright-cli 以及并排安装的 impeccable 技能，缺少这些环境时无法运行。