distill

stardust:distill

读取用户提供的设计样例目录——用户放在 samples/static/ 下的静态 HTML 文件，以及包含待抓取实时 URL 的 samples/live/urls.json 清单——并生成两个用于锚定 stardust 后续流程的产物：

1. samples/trait-matrix.json — 按样例整理的结构化特征数据，以及跨样例 特征数据（类型系统、颜色、间距、动效、组件 模式、语调、资源）。
2. samples/SAMPLES.md — 叙述式词汇概要文件，stardust:direct 在模式 B 下 会将其读取为已确定的锚点集合。

此技能是描述性且预提取的。它不会爬取源站（这是 extract 的工作）。它不会臆造设计观点（这是 direct 的工作）。它会生成一份概要，供用户在希望 stardust 遵循某种特定视觉语言时，作为模式 B 锚点参考交给 direct——这种视觉语言取自样例，而不是冷启动生成偏差种子。

Distill 是可选的。没有样例的用户可直接跳过，使用 extract。当品牌团队、设计师或艺术指导要求用户遵循特定参考材料，且这些材料并非现有网站时，Distill 就会成为流程中的关键环节（常见情况：视觉方向已由设计负责人预先确定的改版项目，相关材料以 HTML 文件和截图组成的文件夹形式提供）。

输入

• <samples-dir> — 可选的位置参数。默认为 samples/。
• --from-static — 仅处理静态样例；跳过实时抓取。 没有列出实时 URL，或用户想延后实时处理时使用。
• --from-live — 仅处理实时样例；跳过静态解析。 静态处理已完成、只需刷新实时快照时使用。
• --cap <N> — 限制待抓取的实时 URL 数量（默认值为 8）。遵循 extract 的 小样本理念：8 个参考 URL 足以推断出一种视觉语言， 无需为近似重复项消耗预算。
• --refresh — 重新抓取并解析每个样例，即使 samples/live/snapshots/ 下 已有缓存快照。默认行为是复用缓存快照，仅抓取缺失的 URL。

设置

先运行主技能的设置流程 （skills/stardust/SKILL.md § Setup）：检查依赖是否完备、加载上下文、 读取状态。

此子命令还需进行以下检查：

1. Playwright 可用性 — 与 extract 使用相同的依赖检查。实时处理 需要真实浏览器。按以下顺序检测 Playwright：先检查 Playwright MCP 服务， 再检查 npx playwright。若两者都不可用且未传入 --from-static，则停止并告知用户如何安装 Playwright。
2. 样例目录结构 — 确认输入目录存在，且至少包含以下其中一项：static/<sample>/、 live/urls.json。如果两者都没有，则停止并说明预期的目录布局：

   samples/
     static/
       <sample-1>/
         index.html         (or any .html file)
         assets/            (optional; reused if present)
       <sample-2>/
         ...
     live/
       urls.json            (array of { url, slug?, role? } objects)
   

3. 状态优先级 — 如果 stardust/state.json 已记录 samples.distilledAt 时间戳，且未传入 --refresh， 则询问用户是要重新提炼（覆盖现有内容）还是跳过。 Distill 具有幂等性；重新运行会覆盖先前的概要 和特征矩阵。

流程

阶段 1 — 清点静态样例

针对 samples/static/ 下的每个子目录：

1. 确定入口 HTML 文件（若存在 index.html，则使用该文件；否则 使用文件大小最大的 .html 文件）。
2. 读取该文件及其引用的样式表（内联 <style> + 链接的 <link rel="stylesheet">，相对于样例 目录解析，也包括 samples/static/<sample>/... 和任意同级 assets/ 目录）。
3. 如果样例目录中有截图或 PDF，则记录其路径—— 审阅者可能会希望将其与解析出的特征进行比较。
4. 在内存清单中记录一项： { slug, kind: "static", entryHtml, stylesheets[], screenshot?, role? }。角色（如果有）根据目录名称推断 （bizpro-hub-prototype → business；plan-page → pricing；等等）——保存推断结果，并展示给用户以便修正。

阶段 2 — 获取实时样本

如果 live/urls.json 存在，且未传入 --from-static：

1. 读取清单。每个条目：{ url, slug?, role? }。如果缺少 slug，则根据 URL 主机名和路径自动生成。
2. 对每个 URL（数量上限由 --cap 指定）：
   • 检查缓存：如果 live/snapshots/<slug>.html 和 .png 存在，且未传入 --refresh，则跳过获取，使用缓存文件。
   • 否则，按照 extract 的 playwright-recipe.md，使用 Playwright 渲染：视口为 1440 × 900 @ 2× DPR，等待模式为 medium，减少动态效果，滚动到底部，然后捕获完整 DOM 和整页截图。
   • 保存：
     • live/snapshots/<slug>.html（渲染后的 DOM）
     • live/snapshots/<slug>.png（整页截图）
     • live/snapshots/<slug>.log（单行来源记录： { url, fetchedAt, waitMs, status }）
3. 在清单中记录一个条目： { slug, kind: "live", url, snapshotHtml, snapshotPng, snapshotLog, role? }。

阶段 3 — 提取每个样本的特征

对清单中的每个条目，解析 HTML 和计算样式（使用无头浏览器，通过 getComputedStyle() 检查代表性元素——采用与 extract 的分区样式摘要相同的技术）。 提取每个样本的以下信息：

• 字体系统 — 所有匹配 --*font-*、--*type-* 的命名 CSS 变量，以及每个标题、正文段落、按钮、眉题、链接的计算样式。汇总为 { headingFamily, bodyFamily, labelFamily, weights[], scale: { title-1, title-2, ..., body-lg, body-sm, eyebrow, label }, rules[] }。按照 extract/reference/brand-surface.md § Modular-scale audit 检测模块化比例。
• 颜色 — 所有匹配 --*color-*、--*bg-*、--*surface-*、--*text-* 的命名 CSS 变量，以及代表性元素的计算背景颜色和文字颜色。汇总为 { palette: { neutrals[], brand: {}, surfaces: {} }, reservations: [{ color, reservedFor[] }], rules[] }。根据类名和 CSS 选择器推断 reservedFor 列表（例如，.brand-mnemonic ⇒ reservedFor: ["brand-mnemonic"]）。
• 间距 — 所有匹配 --*space-*、--*spacing-*、--*pad-*、--*gap-* 的命名 CSS 变量。按照 intent-dimensions.md § 4，对分区内边距值进行聚类，以检测密度等级（紧凑 / 均衡 / 密集）。
• 圆角 / 阴影 / 动态效果令牌 — 所有匹配 --*radius-*、--*shadow-*、--*ease-*、--*duration-*、--*motion-* 的命名 CSS 变量。
• 动态效果技术栈 — 检查 <script src=>，检测已加载的库：GSAP、ScrollTrigger、Lenis、Locomotive、Three.js、Splide、Swiper。若 URL 中可读出版本，则固定记录版本。扫描 animation-timeline:、@keyframes、transition:，检测仅使用 CSS 的动态效果模式。记录：

  {
    libraries: [{ name, version?, role }],
    cssOnlyPatterns: ["animation-timeline: view(block)", ...],
    choreographies: [{ name, surface, mechanism, capturedFrom }]
  }
  

• 组件模式 — 检测重复出现的 DOM 特征：卡片网格、横幅、导航结构、主视觉区域构成。参照 extract/reference/brand-surface.md § System components。对每种模式，记录 { kind, shape, instanceCount, examples[] }——示例需包含足够的标记片段，以便 direct 理解捕获到的结构。
• 语气样本 — 主视觉标题、第一段正文、三个有代表性的 CTA、三个导航标签、页脚文案。字段与 extract 的语气区块相同；区别在于此处的语气按样本分别记录（不跨样本汇总，因为不同样本可能代表不同语域）。
• 资源清单 — 字体（@font-face 声明及其 src URL）、图片（含固有尺寸）、内联 SVG。按样本记录；若可访问，则在本地缓存。

将每个样本的数据保存到特征矩阵的 samples[] 数组中。

阶段 4 — 跨样本聚合

遍历各样本的数据并生成 sharedTokens 块。如果至少有 ceil(N/2) 个样本具有相同的值（颜色需先经过近似重复聚类），该令牌即为“共享”令牌。否则，将其放入 divergentTraits，并按样本列出明细。

聚合：

• sharedTokens.type — 重复出现的字体系列、字重和字号比例。
• sharedTokens.color — 重复出现的中性色、品牌色和表面色令牌；预留项取并集（任一样本有预留项，就足以保留该项）。
• sharedTokens.spacing — 重复出现的区块内边距和网格。
• sharedTokens.radius / shadow / easing / duration — 众数值。
• sharedTokens.motionStack — 至少一个样本加载的库（动效为可选项，不遵循多数规则）。
• divergentTraits — 未达到多数阈值的所有内容。direct 会读取此项，以了解在 B/C/... 变体中应强化哪些特征（即“放大所捕捉特征”的作用）。

阶段 5 — 编写 SAMPLES.md（叙述性简报）

SAMPLES.md 是 direct 在 Mode B 下读取的核心产物。格式参见 reference/samples-brief-format.md：

• 来源信息标题（首行须为 HTML 注释）——与其他 stardust 产物的来源信息块格式相同：writtenBy、writtenAt、readArtifacts、samples、stardustRole。
• 开篇段落——用一段话将样本集描述为一个参考系列。说明共享的设计语言、各样本的风格基调，以及这份简报的使用者（direct，阶段 2 Mode B）。
• § 1 字体系统——共享字号比例表；规则块；如检测到流式字号，则列出 clamp() 公式。
• § 2 颜色——带色样的调色板表格；预留项列表；符合品牌风格的反转候选项（参见 direct/reference/direction-format.md § 品牌风格反转）。
• § 3 间距 + 网格 + 密度等级。
• § 4 动效栈 + 编排——列出库及其版本；列出命名编排（hero scroll-grow、garage-door 等），并注明实现机制和捕捉来源样本。
• § 5 组件模式——卡片、横幅、导航、主视觉构图；每种模式各写一份形状简报。
• § 6 各风格基调的语气——按样本分别撰写语气内容（不聚合）；direct 在 B/C 变体中会使用各样本的语气来匹配风格基调。
• § 7 资源清单——字体（注明许可证标记）、摄影与插画的比例、标志性图案。
• § 8 差异特征——direct 用来挑选要在 B/C 变体中强化的特征列表。

直接编写即可——提炼过程不需要遵循 impeccable 的编写流程。direct 将 SAMPLES.md 作为事实输入，而非设计观点。

阶段 6 — 更新状态并报告

所有阶段成功后：

1. 更新 stardust/state.json（如果没有 samples 块，则添加）：

   "samples": {
     "distilledAt": "<ISO-8601>",
     "samplesDir": "samples/",
     "brief": "samples/SAMPLES.md",
     "traitMatrix": "samples/trait-matrix.json",
     "inventory": [
       { "slug": "bizpro-hub", "kind": "static", "role": "business" },
       { "slug": "sr-homepage", "kind": "live", "url": "...", "role": "consumer-creative" },
       ...
     ]
   }
   

2. 输出一屏摘要：

   Distilled 3 samples (2 static, 1 live)
   
   samples/
     SAMPLES.md             (8 sections, 4 motion choreographies named)
     trait-matrix.json      (12 shared tokens, 4 divergent traits)
     live/snapshots/        (1 file)
   
   Per-sample evidence:
     slug          kind     role                 typeFam               motion-libs
     bizpro-hub    static   business             adobe-clean-display   Lenis 1.x, GSAP 3
     plan-page     static   pricing              adobe-clean-display   Lenis 1.x
     sr-homepage   live     consumer-creative    adobe-clean-display   Lenis 1.x, GSAP 3
   
   Shared tokens: type (12), color (8), spacing (10), motion (2 libs)
   Divergent traits (amplification candidates):
     - scroll-driven choreography (bizpro-hub strongest)
     - photography-led tile vocabulary (sr-homepage strongest)
     - pricing-tier card density (plan-page strongest)
   
   Next: $stardust direct "<phrase referencing SAMPLES.md>" --variants 3
   

distill 运行与不运行的情况

distill 是可选的。常见场景有三种：

1. 没有样例，只需刷新。 用户直接运行 $stardust extract → $stardust direct。模式 A（忠于品牌）可处理常见情况——调色板和字体固定为从目标网站捕获的内容，变体则在捕获到的设计范围内探索表现力、密度和动效维度。不会调用 distill。
2. 有样例 + 忠于品牌的刷新。 用户先运行 distill，再运行 extract，然后运行 direct "<phrase referencing SAMPLES.md>"。 模式 B 的锚点引用优先级（参见 direct/SKILL.md § 模式 B）会将 SAMPLES.md 读取为已解析的锚点集合；由于捕获到的品牌在这些维度上优先，模式 A 仍会继承其调色板和字体。蒸馏提供的是非品牌维度：动效技术栈、组件形状、密度等级和编排名称。
3. 基于样例集重新打造品牌。 用户运行 distill + direct --rebrand "<phrase>"。蒸馏会提供完整的调色板、字体和动效语言；extract 捕获到的设计范围仅用于 IA + 内容。这是最少见的情况，但也是最初编写 distill 的目的。

用户准备的输入（不属于此技能的范围）

Distill 会读取用户手动整理的目录。样例的常见来源：

• 设计师制作的静态 HTML 模型（在浏览器中打开并保存完整页面）。
• 品牌团队提供的实时 URL——将其列入 samples/live/urls.json；distill 会获取这些 URL。
• 转换为 HTML 的打印版 PDF / Figma 导出文件（尽力而为）。

Distill 不会替用户筛选样例；不会编造样例来源；也不会获取用户未列出的任意 URL。如果样例有误，设计简报也会有误；这是有意为之——distill 是忠实的描述工具，而不是筛选工具。

来源信息

distill 写入的每个产物都带有来源信息块，至少包含：writtenBy: stardust:distill、writtenAt: <ISO-8601>、 readArtifacts: [...]（读取的每个样例文件）、 consumedBy: "stardust:direct — Mode B anchor resolution"。

参考资料

• reference/samples-brief-format.md — SAMPLES.md 输出所遵循的叙述式设计简报格式。
• reference/trait-matrix-schema.md — trait-matrix.json 输出所遵循的单样例及跨样例架构。