prepare-migration

stardust:prepare-migration

编排 migrate-prep 级联流程。当用户决定迁移现有站点时，此技能会按顺序运行上游阶段（extract、direct、prototype）的 --prep 模式，并在各阶段设置确认关卡，让用户确认或调整推断出的目录。

prepare-migration 是一个轻量级编排器——它不会重复底层技能的逻辑，而是调用这些技能并汇总各阶段的结果。实质性工作由以下内容完成：

• skills/extract/SKILL.md § Prep mode
• skills/direct/SKILL.md § Prep mode
• skills/prototype/SKILL.md § Prep mode + reference/canon-extraction.md

准备工作完成后，用户需另行运行 $stardust migrate。将流程分为两步（先运行 prepare-migration，再运行 migrate）是有意为之：这让“我决定迁移此站点”成为一个经过慎重考虑的操作，也使幂等性一目了然。

输入

• --from <phase> — 可选。从指定阶段恢复级联流程。取值：extract | direct | prototype | assets | dynamics。默认从最早的未完成阶段开始。
• --skip-confirm — 可选。跳过各阶段的确认关卡。适用于目录已确定后的重新运行。默认在每个阶段边界设置关卡。无人值守模式（skills/stardust/SKILL.md § Hands-off mode，即 state.json.handsOff: true）会启用 --skip-confirm。
• --canon-from <slug> — 可选。在运行 prototype --prep --canon-from <slug> 阶段时将此参数传递给该命令。覆盖默认的规范作者（即 home）。
• --refine-module <module-id> — 可选。重新进入阶段 2 的模块目录步骤，针对一个模块操作——该参数对应 migrate 提示的“定制插槽达到晋升阈值”。将重复出现的定制插槽提升到该模块的插槽架构（DESIGN.json.extensions.modules[]），展示变更以供确认，然后停止；不会重新运行完整级联流程。受影响的页面会根据 skills/stardust/reference/state-machine.md 标记为过期，并考虑内容。

设置

1. 运行主技能的设置（skills/stardust/SKILL.md § 设置）——严格检查依赖项、加载上下文、读取状态。 流程守卫。 这是 redesign 流程的编排器。如果 state.json.flow 为 replica，则拒绝执行：打印“绝不要在 replica 之前或之后运行 prepare-migration”，以及切换 命令（$stardust prepare-migration --switch-flow，该命令会将 replica 产物标记为过时——主技能 § 两种迁移流程）。 如果缺少 flow，则先确定其值：只有明确提到 redesign 的 说法（“redesign”、“modernise”、“refresh”、“new look”）才会选择此 技能——设置 flow: "redesign" （skills/stardust/reference/state-machine.md § 流程键）。任何其他 迁移请求、保留设计的说法或单纯的“migrate”，都表示此技能 不适用——说明这一点并交给 replica。

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：每种页面类型至少有一个已批准的 archetype；stardust/canon/ 已填充； DESIGN.json.extensions.canon 已填充。
   • assets：stardust/migrated/assets/ 中有 favicon 变体； 字体已下载。
   • dynamics：stardust/dynamic-features.md 存在，且每行都有 disposition；任何 listing 都由索引提供支持时，helix-query.yaml 必须 存在（否则，Phase 4.5 会记录“none”）。

   从最早一个未完成的阶段恢复，除非 --from 覆盖该设置。

流程

此级联按顺序运行五个阶段。每个阶段都通过 harness 的技能调用工具 调用底层技能（关于如何寻址子技能，请参阅主技能 § 路由），显示该阶段的准备 摘要，然后等待用户确认后再继续（除非使用 --skip-confirm 或处于无人值守模式）。

阶段 1 — extract --prep

调用 stardust extract 技能，并传入参数 --prep。 Claude Code 格式：Skill { skill: "stardust:extract", args: "--prep" }。

底层技能会运行标准提取流程，并应用五项 --prep 扩展 （提升上限、页面类型判定、模块候选项、类型化插槽、准备摘要）。

完成后，逐字显示摘要，说明流程并等待确认——级联中的第一个交互式确认点会询问保留设计还是 redesign （曾有一次迁移运行了 3.5 小时后，用户才提出保留设计流程，导致已完成的工作被丢弃）：

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 — 进入阶段 2。
• switch to replica — 保留设计：停止此级联流程并运行 $stardust replica <url> --switch-flow（主技能 § 两种 迁移流程）。replica 阶段 1 会复用刚刚生成的提取结果；此流程的其他内容均不会复用。
• refine "<phrase>" — 使用优化要求重新调用 extract --prep（例如，“将 news/* slug 设为 listing 而非 article”， “将 /search 和 /404 排除在清单之外”）。再次显示摘要； 循环执行。

来源验证防护（Phase 1 与 Phase 2 之间）

在调用 direct --prep 之前，根据 skills/stardust/reference/state-machine.md § Provenance validation，通过 validateProvenance(page) 验证清单中的每个页面。如果任何页面缺少实时渲染证据，则使用该 helper 的错误中止级联流程。这是级联级别的防护，用于应对以下故障模式：extract --prep（或其委派的子 Agent）静默合成了一条或多条页面记录——extract 自身的写入时拒绝是主要防护，但级联流程会在阶段之间增加第二次检查，这样即使合成错误因其他原因再次出现，也不会悄然污染后续运行。

Phase 2、3 和 4 内部也会隐式运行相同的防护（每个底层技能的设置流程都会根据自身的 SKILL.md 调用 validateProvenance()）——但将其作为明确的级联步骤列在这里，可确保在用户看到 Phase 2 的准备摘要之前中止；否则该摘要看起来会像是运行成功了。

在级联输出中显示：

Provenance OK on 127 pages.

检查失败时：

Provenance check failed on 20 of 127 pages — see error above.
Cascade aborted between Phase 1 and Phase 2.
   → Re-run extract for the affected slugs:
       $stardust extract --refresh <slug-1>
       $stardust extract --refresh <slug-2>
       ...

Phase 2 — direct --prep

使用参数 --prep 调用 stardust direct 技能。 Claude Code 格式：Skill { skill: "stardust:direct", args: "--prep" }。

底层技能会运行五个 --prep 覆盖项（类型目录确认、模块目录定稿、颜色预留、方向重新评估、品牌元数据默认值）。

显示摘要和确认环节。用户选项与 Phase 1 相同（yes / refine "<phrase>"）。

Phase 3 — prototype --prep

使用参数 --prep 调用 stardust prototype 技能；如果已知规范 slug，还要加上 --canon-from <slug>。 Claude Code 格式：Skill { skill: "stardust:prototype", args: "--prep --canon-from <slug>" }。

底层技能会填补页面类型缺口（每种类型一个经批准的原型），并根据 skills/prototype/reference/canon-extraction.md 将规范写回。

首次批准会确立规范；后续批准会扩展规范（默认将冲突记录为偏差）。

此阶段通常耗时最长——每个原型类型都要经过完整的原型循环（结构简介、制作、在浏览器中打开、迭代、批准）。每个原型完成时，向用户持续报告进度。

显示摘要和确认环节。

Phase 4 — 资源准备

生成或下载迁移后的网站所需的资源变体。 此阶段没有对应的 SKILL——它通过一个小型图像处理和下载流程完成。

1. 网站图标变体。 根据规范网站图标 stardust/current/assets/favicon.<ext>，生成：

   • stardust/migrated/assets/favicon-512.png
   • stardust/migrated/assets/apple-touch-icon.png（180×180）
   • stardust/migrated/assets/icon-192.png、 icon-512.png（清单尺寸）

2. 字体下载。 扫描 stardust/canon/canon.css（以及 stardust/canon/header.html / footer.html）中的 @font-face 规则，查找带有外部 URL 的规则。对每条规则：

   • 将文件下载到 stardust/migrated/assets/fonts/<basename-with-hash>.<ext>。
   • 将规范文件中 @font-face 的 url(...) 引用改写为本地路径。
   • 如果文件已下载，则跳过（通过 sha 比较）。
   • 如果下载失败，则记录警告（字体保留外部 URL； migrate 会为每个页面记录一条 metadata-override 警告）。

3. 品牌资源审查。 验证徽标、网站图标以及规范模块渲染所引用的任何媒体文件是否 存在于 stardust/current/assets/ 中。向用户显示缺失的资源。

显示摘要和确认环节：

assets prep complete
====================

Favicon variants:    favicon-512.png, apple-touch-icon.png, icon-192.png, icon-512.png
Font downloads:      4 files (HarmoniaSans 4 weights)
Brand assets:        all present

Phase 4.5 — 动态表面（导入前门禁：dynamics Phases 1–3）

在资源准备完成后、任何批量导入之前运行。与迁移绑定： 此步骤可防止动态网站被当作静态网站导入。委派给 skills/dynamics/SKILL.md：

1. 检测 — 如果 Phase 1 运行时未启用此选项，则重新运行 extract --dynamics （覆盖范围），然后运行 dynamics-detect.mjs --from-state stardust/state.json --reach stardust/current（针对 archetypes 的深度）。
2. 分类 + 分流 — dynamics-plan.mjs [--target-origin <host>] 为每一行拟定四个维度；整理并写入 stardust/dynamic-features.md（§ Listings contract with helix-query.yaml、§ Features、§ Decision batch、§ Register）以及 stardust/dynamic-features-plan.md。
3. 门禁 — 每一行都有处置结果即为通过。两个部分中的 "none" 都是有效的通过结果。门禁不会阻止静态路径；它会阻止未被察觉的回归。

摘要行：dynamic surface: N findings · self K · owner batch M · host-bound H · listings L dynamic / S static。规范： skills/dynamics/reference/triage.md。

最终报告

prepare-migration complete
==========================

Phase 1 (extract --prep):      127 pages, 7 types, 8 module candidates
Phase 2 (direct --prep):       types & modules confirmed; metadata set
Phase 3 (prototype --prep):    6 archetypes approved; canon written
Phase 4 (assets prep):         favicon variants + fonts + brand assets ready
Phase 4.5 (dynamic surface):   14 findings · self 6 · owner batch 7 · host-bound 1 · listings 3 index-backed / 1 static

Next: $stardust migrate

输出

prepare-migration 不会直接写入任何内容——每个产物都由底层技能或 Phase 4 / 4.5 流程写入。 级联流程运行后，项目状态包含：

产物	写入它的 Phase
state.json.pages[].type	extract --prep
current/pages/<slug>.json § slots	extract --prep
DESIGN.json.extensions.modules[] (status: confirmed)	extract --prep + direct --prep
DESIGN.json.extensions.colorReservations[]	direct --prep
DESIGN.json.extensions.metadata	direct --prep
stardust/canon/ (header, footer, css, modules/)	prototype --prep
DESIGN.json.extensions.canon	prototype --prep
stardust/migrated/assets/favicon-*	资源准备
stardust/migrated/assets/fonts/	资源准备
stardust/dynamic-features.md + -plan.md (清单、四个维度、决策批次)	dynamics 门禁（Phase 4.5）
helix-query.yaml (限定范围的索引、EDS 项目根目录)	dynamics 门禁（Phase 4.5）
stardust/state.json (逐页状态更新)	各底层 Phase

失败情况

• 没有 state.json 或没有提取的页面。 建议运行 $stardust extract <url> 并停止。
• 没有生效的方向。 建议运行 $stardust direct 并停止。
• 用户拒绝某个 Phase。 正常停止级联流程。状态 将保留在一致的中间状态（底层技能的写入已完成）；用户可以通过 $stardust prepare-migration --from <phase> 继续。
• 底层技能失败。 原样呈现失败信息；不要继续。由用户修复后重新运行。
• 非规范作者审批期间发生 Phase 3 规范冲突。 默认情况下，根据 reference/canon-extraction.md 将冲突记录为偏差。如果用户希望逐项覆盖 （提升为规范 / 拒绝并重新迭代 / 记录为偏差），应在该 Phase 的确认门禁期间提出， 而不是等到运行时。未来的 --strict-canon 标志可以拒绝 与规范冲突的审批；v0.2 中尚未提供。
• Phase 4 资源下载失败。 继续运行；在资源准备摘要中记录 失败情况。Migrate 之后会针对每个受影响的页面发出警告。

并发

根据 skills/stardust/reference/state-machine.md § 并发： state.json 的写入会按 slug 合并，因此级联流程按页面进行的写入 可以与其他并行通道共存。但是，同一项目上并发运行两次 prepare-migration 会争用相同的顶层产物（规范、模块目录）——这仍会 遵循最后写入者生效，并给出警告，而且很可能会损坏规范。 不要同时运行两次级联流程；也不要为此设计锁。

幂等性

在部分完成后重新运行 prepare-migration，会从最早的未完成阶段（或显式指定的 --from 阶段）继续。每项底层技能本身都具有幂等性——已完成类型标注的页面不会再次标注，已确认的模块不会再次提议，已批准的原型不会再次进行原型设计，已生成的 favicon 变体不会再次生成，现有的 dynamic-features.md 会得到完善，而不是被重写。

在全部完成后重新运行不会产生任何操作，除非输入发生变化（extract 找到了新页面、方向已编辑、canon-author 原型已重新迭代等）。

参考

• skills/extract/SKILL.md § 准备模式
• skills/direct/SKILL.md § 准备模式
• skills/prototype/SKILL.md § 准备模式
• skills/prototype/reference/canon-extraction.md — prototype --prep 在获批后执行的 五步提取流程
• skills/dynamics/SKILL.md + reference/triage.md、 reference/listings.md — 第 4.5 阶段对应其第 1–3 阶段
• skills/migrate/SKILL.md — 使用此级联流程准备的每种数据 结构
• skills/stardust/reference/state-machine.md — 页面类型标注、 过时标记级联流程
• skills/stardust/reference/artifact-map.md — 文件结构、 DESIGN.json.extensions 形状