通过 stardust 技能对现有网站进行可恢复的多页重设计…

当你有一个可通过 URL 指向的现有网站，想重设计、翻新、现代化或重设风格，或需要恢复多页重设计/迁移流程时使用。

适用场景

解决思路

1. 运行前先验证 impeccable 是否已安装：在 harness 暴露的技能列表、项目技能目录（`.claude/skills/`、`.agents/skills/`、`.cursor/skills/`、`.github/skills/`）或 harness 插件缓存（Claude Code：`~/.claude/plugins/cache/`；GitHub Copilot：`~/.copilot/installed-plugins/*/impeccable/skills/impeccable`）中查找。若未安装，停止并告诉用户从 <https://github.com/pbakaus/impeccable> 安装后重跑命令。
2. 每会话运行一次版本提示检查：执行 `node <plugin>/skills/stardust/scripts/impeccable-version-check.mjs`；当 impeccable 位于 harness skills 目录而非插件注册表时加 `--local <impeccable-dir>`。仅当输出报告有更新版本时，原样展示那一行输出；当前、未知、离线等结果都视为噪音，不提及，也绝不因此停止或降级运行。
3. 检查项目根目录的 `PRODUCT.md` 和 `DESIGN.md` 是否存在，它们是 stardust 的目标状态；用目录列表确认即可。不要在此运行 impeccable 的 context loader `scripts/impeccable context`。
4. 读取 `stardust/state.json`（若存在），按 `reference/state-machine.md` 的 schema 记录各页状态：`extracted`、`directed`、`prototyped`、`approved`、`migrated`。
5. 解析 `<harness>/skills/impeccable/scripts/command-metadata.json` 读取 impeccable 的命令注册表，把它作为 24 个 impeccable 命令的唯一来源，绝不在推理中硬编码命令列表。
6. 每个 stardust 技能在阶段开始和结束时，按 `reference/run-status.md` 向 `stardust/status.jsonl` 追加一条阶段转换行。
7. 执行项目卫生（幂等）：若 `stardust/.gitignore` 不存在，从 `reference/stardust.gitignore` 写入；绝不编辑项目自己的副本。在 git 仓库中：根 `.gitignore` 覆盖 `.env` / `.env.*`（托管在 `# >>> stardust` 块），若存在 `.hlxignore` 则列出 `stardust/`，并且 `git check-ignore -q stardust/state.json` 必须失败——若通过，停止并指出规则名。若 `stardust/` 下跟踪的二进制超过 50 MB，只提供 LFS 建议，不直接写入；细节见 `reference/artifact-map.md` § Versioning。
8. 路由无参数或恢复请求：按 `reference/state-machine.md` 渲染状态报告，包含项目状态、每页状态表、推荐下一命令及理由，不写任何文件。恢复也包括新会话、继续、询问进度或由记忆文件驱动的恢复；先从状态报告开始，它应指出流程和最后门编号，然后通过对应阶段的技能进入下一阶段，不凭记忆执行。
9. 路由第一词为子技能时：委托给匹配的子技能并传递剩余参数。按 harness 命名方式处理：Claude Code 插件技能为 `stardust:<name>`（Skill tool）；GitHub Copilot 等展平插件技能的 harness 暴露裸 `<name>`；若 harness 没有技能调用工具，读取子技能的 `SKILL.md` 并内联执行。不要把 stardust 的 `extract` 和 `audit` 技能与 impeccable 的 `extract` 和 `audit` 命令混淆，后者始终写作 `$impeccable <command>`。
10. 主管技能路由所有兄弟子技能：`extract` 爬取并捕获当前站点；`direct` 解析视觉方向；`prototype` 生成每页重设计原型；`migrate` 生成全站平台无关静态 HTML；`prepare-migration` 执行迁移准备级联（准备阶段、资产、动态门），仅用于重设计流；`replica` 执行同设计迁移（换平台、保留当前设计），运行自己的 preserve 模式准备后交给 migrate/deploy/rollout；`reskin` 将字节保真内容重排到单独定义的捐赠设计系统上；`deploy` 将一页转为 EDS blocks + DA delivery；`rollout` 将整个迁移站点转为 EDS，带覆盖和交付门；`dynamics` 处理迁移的动态表面——检测、分类、分诊、实现、验证（APIs、search、forms、modals、media、tags、client-rendered、sheet data），迁移绑定，由 prepare-migration / replica / migrate / rollout 调用，或对已迁移站点独立运行；`diff` 执行原型↔构建保真探针（像素和结构）；`audit` 执行三视角站点审计——设计张力、SEO/技术、LLM 可见性——输出评分报告和发现账本；`qa` 执行只读部署后 QA 扫描实时站点——路由、保真、模板一致性、渲染、视觉回归、SEO、链接、a11y、性能——仅出发现报告，从不修复；`uplift` 是一次性售前编排器（3 个变体）。
11. 对 `prototype` 使用 `--cinematic`（或 `--cinematic=<register>`）在静态原型上叠加品牌保真运动寄存器，规则见 `skills/prototype/reference/motion-registers.md`。对 `uplift`，用 `$stardust uplift <URL>` 从 URL 产生三个差异化变体（其中一个全电影感），无需进一步用户协调；当用户想跳过 extract/direct/prototype 链时使用，见 `skills/uplift/SKILL.md`。
12. 迁移到 EDS 时只选两种流之一，绝不混合。先问设计是保留还是改变，该答案选择流程。重设计边迁移：`extract` → `direct` → `prototype`，或一步 `prepare-migration`（带确认门的准备级联）→ `migrate` → `deploy`（单页试点）/ `rollout`（整站）。保留当前设计（换平台）：`replica` → `migrate` → `deploy` / `rollout`；`replica` 在 preserve 模式包含准备级联——`extract --prep` 是其 Phase 1，机械方向保留步骤替代 `direct --prep`，带门原型重建（每断点测量源保真门）替代 `prototype --prep`；永远不要在 `replica` 前后运行 `prepare-migration`。新设计来自捐赠者、相同内容：`reskin`——内容字节门，设计来自另一个实时站点或本地原型。
13. 两种迁移流默认携带动态表面：预导入门（`prepare-migration` 4.5 / `replica` Phase 2，`migrate` 作为安全网）运行 stardust `dynamics` 技能 Phases 1–3，使每个 API、搜索框、表单、模态、播放器、标签和客户端渲染表面在导入前有处置；`rollout` D2 实现可复现行，`qa` 重放一致性。绝不要用于纯重设计工作（`uplift`、裸 `extract`）。
14. 选择并记录迁移流：在任何子技能加载前读取用户请求。保留设计短语无需提问即选择 `replica`：`exact replica`、`1:1`、`pixel-perfect`、`faithful`、`same design`、`keep the current design`、`as is`、`re-platform only`、`migrate keeping the design`，或固定所有轴不变的方向短语（`ia-fidelity: verbatim` 且 palette、type、density 都 pinned）。重设计短语选择重设计流：`redesign`、`modernise`、`refresh`、`new look`、`rethink`、`reimagine`，以及任何移动设计轴的短语。其他情况（`migrate X to EDS`、`build a migration plan for X`）只问一个保持-vs-重设计问题；hands-off 下不问：保留设计短语选 `replica`，否则选 `redesign`，并记录为 `direction.md` 中的命名假设。委托前在 `state.json` 标记 `flow` / `flowChosenAt` / `flowSource`，见 `reference/state-machine.md` § Flow keys。
15. 子技能强制流程：`migrate`、`deploy`、`rollout` 和迁移意图的 `extract` 拒绝在项目有 `state.json` 但无 `flow` 时开始迁移；`prepare-migration` 在 `flow: replica` 下拒绝；`replica` 在 `flow: redesign` 下拒绝。切换必须显式执行：`$stardust replica --switch-flow` 或 `$stardust prepare-migration --switch-flow`，并标记旧流中已原型或已迁移的页面为 stale，见 § Per-page state。
16. 规划辅助只属于一种流。重设计使用 `prepare-migration` 计划及其阶段门、canon、模块目录、模板计划（例如「学习模板，然后编译」类）。保留设计使用 `replica` 的不一致寄存器、`progress.json`、原型门账本、`rollout` waves。若在 replica 运行中出现重设计过程或计划模板，或反之，则视为路由缺陷：拒绝，或在 `direction.md` 中标记并交回本节。
17. 激活 hands-off 模式：在任意 stardust 调用上使用 `--hands-off`，或用户明确说 `fully hands-off`、`no approval gates`、`run autonomously`。激活后，在 `state.json.handsOff: true` 标记，并向 `stardust/direction.md` 追加激活行。该模式移除等待，不移除验证：管道中每个质量门仍全强度运行，变化的是谁解决交互暂停。
18. Hands-off 下自动解析所有交互门：`direct` 澄清问题从捕获证据 `stardust/current/` 推导，并在 `direction.md` 中作为命名假设陈述；`prototype` 简报确认等待跳过，按 authored brief 继续；原型批准仅在所有质量门通过后由 agent 自己判断授予（craft bar、validation loop、motion gates），并在 `state.json` 页面的 `approved` 历史记录中记为 `approvedBy: "hands-off"`；`prepare-migration` 阶段门行为如 `--skip-confirm`；`rollout` 全自动端到端运行；`dynamics` 所有者决策（backend、tags on the new host、datasource ownership、locale scope）发布临时层，逐名记录在 `dynamic-features.md` 和 parity report，继续；regulated-pii 表单保持阻塞。
19. Hands-off 默认值：一个规范方向，无变体扇出——承诺单一方向并在 `direction.md` 记录理由；体量上限作为有理由的提议，默认总共 100 页、每模板 20 页；名册优先级为 (1) 页眉和页脚链接的每个页面，(2) 分区着陆/概览页，(3) 跨所有模板的代表性详情页分布；在 `direction.md` 说明所选上限；委托按文件指针、按章节读取——给委托 agent 的简报命名其需要的文件和章节（`state.json`、页面 schema、阶段 `SKILL.md` 章节），绝不内联参考文档；参考文档按标题和行范围读取，不端到端读取；可能卡住的仪器在其附带的 deadline 下运行（replica `gate.sh`、`pixel-compare --timeout`），绝不放在 agent 编写的 `sleep N; kill` 循环下；长步骤写进度文件供协调者轮询，而非阻塞 agent。
20. 等待纪律：绝不把对话停在 prompt-cache 窗口之后。任何预计运行超过约 2 分钟的任务（多页门轮、爬取、批量推送、捕获集、委托 agent）都在后台运行并写进度或摘要文件；协调者绝不前台运行，也绝不用一个长 `sleep` 覆盖它。运行期间做独立工作；没有独立工作时，最多每 4 分钟一次短读进度文件，绝不固定 `sleep` 5 分钟或更多，也绝不用长超时阻塞「等待 agent 输出」调用。结束回合等待完成通知对用户有帮助但对缓存无帮助：超过 5 分钟到达的通知也会错过；因此约 45 分钟以下等待优先短检查，只有等待更长或需要用户决定时才结束回合。Claude Code 中，shell 调用用 `run_in_background: true`，harness 在退出时发布任务通知；`promptCacheTtl: "1h"` 在 settings.json 将窗口延长到一小时，写价格 1.6×，属于所有者设置，对多小时会话值得。
21. 在 git 仓库中每个阶段结束时提交。第一次此类提交前重新运行 Setup 步骤 6——第一次提交落在 audit 阶段结束时，远在 deploy 的 `SKILL.md` 被读取之前，而跟踪的 `.env` 会毒害之后每次推送（GH013 加部署时历史重写）。
22. 硬阻塞仍停止：不可达源站点、无法恢复的过期 `DA_TOKEN`、信号缺失的品牌表面（extract 即使重跑也未捕获可用品牌信号）不是判断调用——精确陈述阻塞，向 `stardust/status.jsonl` 追加 `event: "blocked"`，并停止。绝不在硬阻塞上猜测。质量门在 hands-off 下绝不减弱：Provenance validation、validation loop、fidelity gates、delivery gates、rollout 的 optimize gate 都原样运行。Hands-off 改变谁回答，不改变什么必须通过。
23. 遵循「开放和推理」原则：不发布封闭的 `intent → commands` 查找。每个自由形式短语都公开推理。必须：1) 用 stardust 维度词汇（`reference/intent-dimensions.md`）重述短语；2) 识别短语移动哪些轴及方向；3) 识别未充分说明的内容，向用户最多问两个澄清问题；4) 将解决的方向映射到一系列 impeccable 命令，引用每个命令在 `reference/impeccable-command-map.md` 中的参考；5) 执行前向用户展示提议计划；6) 执行后，将解决的方向、轴、命令和推理记录在 `stardust/direction.md` 中，带 stardust provenance 块。工作示例在 `reference/intent-examples.md`。
24. 处理每页状态和方向变化时的 stale：页面生命周期状态为 `extracted | directed | prototyped | approved | migrated`。当用户方向在部分页面已原型或已迁移后变化时，标记这些页面 stale，不自动重跑。用户显式选择重新原型或重新迁移。细节在 `reference/state-machine.md`。
25. 读写 artifacts：stardust 状态在 `stardust/` 下；impeccable 的 `PRODUCT.md` / `DESIGN.md` / `DESIGN.json` 在项目根目录，代表目标状态；当前提取状态在 `stardust/current/` 下；完整布局在 `reference/artifact-map.md`。写边界：stardust 写入 `stardust/`、项目根的 impeccable 目标文件、EDS 项目（仅通过 `deploy`、`rollout`、`dynamics`）。仅运行文件——日志、harness page、预渲染、脚本副本、草稿——放在 `stardust/.work/<skill>/` 下；根 `scripts/` 和 `qa/` 不是 stardust 的。写到其他地方是该技能的 bug。
26. 版本管理：`stardust/` 下一切提交，除了 `reference/stardust.gitignore` 列出的内容：截图、四个重文件夹（`current/assets/`、`replica/gates/`、`migrated/assets/`、`rollout/qa/`）、`.work/`、运行残留、会话状态。每目录表、没有 `current/assets/` 的克隆能做什么和不能做什么，见 `reference/artifact-map.md` § Versioning。
27. 每个 stardust 写的 artifact 都携带 provenance 块作为第一行或第一个键，声明：哪个子命令写的、针对哪个用户输入、什么被合成 vs 创作、读了哪些其他 artifact。格式约定在 `reference/artifact-map.md`。
28. 维护 journal：多会话 stardust 项目应维护按时间顺序的 `stardust/journal.md`，记录跨轮提示历史、决策和开放问题，与状态机和每 artifact provenance 分开。按 `reference/journal-format.md` 格式，在每次导致非平凡写入的提示执行后（任何 `direct`、`prototype`、`migrate` 或大量迭代），结束回合前追加条目。任何 agent 编写的爬虫、编译器、导入器、wave 驱动器或门若取代技能阶段，必须作为命名偏差记录在 `stardust/direction.md`——取代什么、为什么发布仪器不适用、替代品在哪里——并在 journal 条目中注明。未记录的并行管道是缺陷，不是主动性。Journal 仅追加：若先前条目错误，写新条目纠正，不编辑历史。Journal 项目范围且面向人，位于与 impeccable `PRODUCT.md` 同级，不在 `stardust/current/` 或 `stardust/canon/` 下。新会话开始时，先读 journal（连同 `state.json`），最后 3-5 条目携带「我们停在哪里」的上下文。
29. 执行验证规则：每个 stardust 写的、人将肉眼看 的 artifact——提议 HTML、`brand-review.html`、迁移站点——在标记完成前运行递归 validate-and-fix 循环。原则：类型检查和测试套件验证代码正确性；只有浏览器渲染验证功能正确性。对用户将看到的 HTML（原型、迁移页面、brand-review HTML）：1) 在 Playwright 中渲染（静态用 file:// 或本地 dev server）；2) 在三个视口捕获——桌面 1440×900、平板 768×1024、移动 390×844：全页截图；浏览器控制台消息（错误和警告）；网络失败（4xx / 5xx / 中止请求、缺失资产）；未捕获 JS 异常和未处理 promise 拒绝；布局健全：无水平溢出，关键地标存在且非空；a11y 快速通过：alt text、输入标签、标题顺序、文字覆盖图像上的对比度；交互冒烟：悬停交互卡片、滚动触发触发、导航打开/关闭、主要 CTA 可通过键盘到达；3) 若发现任何问题，修复并重跑循环，递归迭代直到 (a) 无问题剩留或 (b) 修复需要用户输入——此时提出问题并停止。不要在有已知未解决问题时报告任务完成；4) 将最终干净通过截图保存到 `stardust/validation/<artifact>/<viewport>.png`，让审查者无需重跑即可比较。每个子技能验证细节在各技能参考文档——尤其 `extract/reference/playwright-recipe.md`（规范配方）、`prototype/reference/motion-validation.md`（运动特定门）、`prototype/SKILL.md` Phases 2.5–2.8（critique / audit / adapt / motion gate 级联）。
30. Stardust 绝不做：发明与 impeccable 硬规则矛盾的设计意见——遵从 impeccable；执行重设计计划前不先展示（hands-off 模式将计划记录在 `stardust/direction.md` 而非等待）；未经用户显式选择强制重跑 stale 页面；爬取现有站点超出用户确认的页面上限（显式 `--pages` 列表本身即确认范围——列出的页面永不丢弃；列表超过 `--max` 时爬虫警告而非截断）；从 `migrate` 发出平台特定输出。`migrate` 发出平台无关静态 HTML；EDS 转换和交付由 stardust `deploy`（一页）和 `rollout`（整站）技能子技能拥有，按上文路由。
31. 按需读取并参考以下文档：`reference/intent-dimensions.md`（重设计移动的轴）；`reference/intent-reasoning.md`（处理自由形式短语的程序）；`reference/intent-examples.md`（8-12 个工作示例）；`reference/impeccable-command-map.md`（何时使用 24 个 impeccable 命令）；`reference/state-machine.md`（页面生命周期、stale 规则、状态报告格式）；`reference/artifact-map.md`（stardust 读写每个文件、所有权、provenance 形状和 § Versioning）；`reference/stardust.gitignore`（由 Setup 步骤 6 安装为 `stardust/.gitignore`）；`reference/divergence-toolkit.md`（反平庸设备：默认移动列表、确定性种子、字体 decks、角色命名规则，由 `direct` 编写目标 tokens 和 `prototype` 生成变体时消费）；`reference/token-contract.md`（每个原型和迁移页面必须暴露的 `:root` CSS 自定义属性契约）；`reference/data-attributes.md`（应用于每个原型和迁移页面 section 的结构 `data-*` 词汇）；`reference/journal-format.md`（`stardust/journal.md` 条目格式）；`reference/run-status.md`（`stardust/status.jsonl` 阶段转换契约）；`reference/learnings.md`（每轮 learnings 账本契约 `stardust/learnings.md`，rollout 报告阶段写入，插件维护者收获 pending 条目到技能 diffs）。
32. 按需读取电影功能参考：`../prototype/reference/motion-registers.md`（五个品牌保真运动个性 `arrival`、`kinetic-display`、`live-systems`、`editorial`、`kinetic-grid`，以及映射 `PRODUCT.md` Brand Personality 特征到 register 的选择启发式）；`../prototype/reference/motion-stack.md`（技术选择：Lenis + CSS keyframes + rAF + IntersectionObserver，为什么不用 GSAP，bundle policy）；`../prototype/reference/motion-attributes.md`（运行时消费的 `data-*` 词汇：`[data-anim]`、`[data-tile-anim]`、`[data-countup]`、`[data-flip]`、`[data-fill]`、`[data-split]`、`[data-parallax]`）；`../prototype/reference/motion-runtime.md`（规范内联运行时脚本）；`../prototype/reference/motion-validation.md` § Pass 6（电影模式验证门：Lenis boot、reduced-motion fallback、scroll-jack、三位置截图、register-match、motion C-cliff detector）。
33. 按需读取 uplift 功能参考：`../uplift/SKILL.md`（一次性售前编排器：extract → tension/trait identification → 3-variant direction → prototype × 3 → open + summarize）；`../uplift/reference/what-if-candidates.md`（8 个工作捕获特征放大候选，B 和 C 在 Phase 2b 选择，及其 § Extension rule 接纳 evidence-shaped `derived` 候选）。

适用边界 · 注意事项

• 不要用于从零设计全新站点，或一次性单组件编辑。
• 未安装 impeccable，或缺少 Node 22+、Playwright with Chromium、`playwright-cli` 时不要使用；Stardust 无回退。
• 不要混合两种迁移流；`replica` 前后不要运行 `prepare-migration`，`prepare-migration` 在 `flow: replica` 下拒绝，`replica` 在 `flow: redesign` 下拒绝。