audit

stardust:audit

输入一个 URL，输出一份带评分、以证据为依据的审计报告。

audit 从三个角度审视现有网站：设计（品牌张力 + 具体改进机会）、SEO/技术，以及 LLM/AI 搜索可见性；同时测量 Core Web Vitals，并将所有内容综合为七个维度的评分卡和一份按优先级排列的发现清单，告诉所有者该改进什么，才能取得更好的业务成果。该报告也是重新设计的自然起点：其中的发现会为 stardust uplift 技能的改进列表和 stardust direct 技能的 Phase 2.5 提供依据，并以符合 uplift 方向的重新设计方案收尾，让“运行 $stardust uplift”成为显而易见的下一步。

有主见的默认设置

• 默认多页面 — $stardust extract <url> --cap 8 （首页 + 七个 IA 支柱），除非使用 --single 或 --pages 覆盖。
• 非交互式 — 审计绝不会提问。它所做的每项假设都会记录在 audit.json#assumptions 中，并在报告的执行摘要里说明。
• 以证据为依据 — 每项结论都引用一项测量结果、一个 T-* 张力 ID、一项检查结果或一条截图观察。没有引用的结论不会进入报告。
• 不编造数据 — 无法进行的测量会报告为 not measured (<reason>)，绝不会悄悄估算。 如有依据充分的估算，会标明这是估算并说明依据。
• 平稳降级，而非失败 — 可选能力 （refero、marketing-skills、modern-web-guidance、PageSpeed Insights）只会探测一次；缺少这些能力会被记录下来，不会导致失败。请参阅 § 降级梯级。

输入

• <url> — 必需。要审计的网站。指定路径会将爬取范围限定为该子树（遵循 extract 的语义）。
• --pages <n> — 可选。覆盖默认的 8 页提取上限（会传递为 --cap <n>）。
• --single — 可选。仅审计给定 URL 的单个页面。此时跨页面检查（重复标题、站点地图覆盖情况、跨页面 CTA 分散情况）会针对单个页面运行，并对此作出说明。
• --deploy — 可选。报告渲染完成后，通过 DA 传输方式将 report.html 发布为一个独立页面 （../deploy/da-deploy-protocol.md：源文件 PUT → 预览 → 上线）， 并输出发布后的 URL。仅传输文件——报告不会经过 deploy 的章节→区块转换，因为该转换会拆解这个独立文件。
• --benchmark — 可选。强制运行 Phase 5 参考基准测试： 即使较早的能力探测缓慢或结果不明确，也会探测 refero MCP。若不使用此标志，只有探测快速成功时才会运行 Phase 5。

没有其他标志。其他所有内容都源自已采集的网站信息，或受底层技能的约定约束。

阶段 0 — 设置

1. 执行主技能的设置流程（../stardust/SKILL.md § Setup）——但有一项仅适用于审计的例外：**这里，缺少 impeccable 属于降级，而不是主设置中的硬性停止条件。**依赖检查失败时，在 audit.json#degradations 中记录 impeccable: unavailable，然后继续——阶段 2 不运行批评／审计环节（VISION 检查 + 无障碍整合仍会执行），阶段 6 跳过报告渲染；写入 audit.json 后，运行会因停止条件 (b) 而结束。
2. 检查提取结果是否新鲜。如果 stardust/current/ 中保存着相同来源且不到 7 天的提取结果——来源取自 stardust/state.json（站点记录提取时间戳），新鲜度取自最新的 pages/<slug>.json#_provenance.fetchedAt——则复用它，并记录 site.extraction.reused: true。否则，调用 $stardust extract <url> --cap 8（或根据输入使用 --single / --pages <n>）。提取流程负责爬取、截图、_brand-extraction.json、pages/<slug>.json、PRODUCT.md / DESIGN.md，以及包含 Tensions 部分的 brand-review.html。
3. 探测可选能力，每项只探测一次，并在降级记录（audit.json#degradations）中记录结果：
   • marketing-skills 插件（是否包含 seo-audit、ai-seo 技能？）
   • modern-web-guidance（npx -y modern-web-guidance@latest search "<query>" 是否有响应？）
   • refero MCP（尝试调用 mcp__refero__refero_search_styles；若工具不存在或超时，则视为不可用）
   • PageSpeed Insights API（是否无需密钥即可连接网络？）
   • rollout 项目（是否存在 stardust/rollout/rollout.json？）

如果提取彻底失败（站点无法访问，或在使用有头 Chrome 回退方案后仍被机器人管理机制拦截），则停止并原样显示提取错误——没有可供审计的内容。这是合成前唯一的硬性停止条件；参见 § 停止条件。

流程

阶段 1 — 品牌表现与张力分析

阅读 stardust/current/_brand-extraction.json 和 stardust/current/brand-review.html § Tensions surfaced（规则目录见 ../extract/reference/brand-review-template.md § Tensions）。每个触发的 T-* 张力都可作为问题证据的候选项——保留其 ID，不要重新推导检测结果。

计算报告所需的四项品牌表现指标。每项都应写入 audit.json#measurements，并按照 reference/report-format.md 填写 status + method：

• brandColorShare — 品牌色在首页截图已绘制像素中的占比。首选方法：使用 Playwright 进行像素采样（method: "pixel-sample"）——加载截图，按网格采样（例如每隔 8 个像素采样一次），将每个样本归类为容差范围内最接近的调色板条目，并用品牌色相样本数除以已绘制的（非白色／近白色）样本数。若当前会话无法进行采样，则可根据已捕获的界面作出有依据的估算，但必须使用 method: "surface-estimate" 并说明依据——绝不可将估算说成测量结果。
• ctaFragmentation — 按等价类别统计不同 CTA 标签，数据汇总自 pages/*.json#ctas[].label（与 T-cta-vocab 使用相同类别）。
• typeScale — 不同的标题字号及比例类型／比率，数据来自 _brand-extraction.json#type.scaleAudit。
• radiusSprawl — 不同的边框圆角值及其出现次数，数据来自 _brand-extraction.json#motifs.borderRadius。

阶段 2 — 设计与体验评审

对捕获的主页（截图 + 实时 URL）进行三轮检查， 整合为一组设计发现：

1. impeccable 评审 + 审计。 使用委派机制，通过 harness 的技能调用工具调用 impeccable，参见 ../prototype/SKILL.md § 调用 impeccable（Claude Code 形式： Skill { skill: "impeccable:impeccable", args: "critique <target>" }，然后针对可访问性 / 响应式 / 性能检查执行 "audit <target>"）。将其发现规范化为审计的发现格式。
2. VISION 检查。 直接研究捕获的截图 （stardust/current/assets/screenshots/<slug>.png），指出设计总监会关注的问题：业界已淘汰的过时模式、层级结构缺陷、捕获界面未能充分利用的机会。必须绝对严谨地提出主张——每条观察都要引用测量值、张力 id 或截图区域（"home.png，主视觉：三个权重相同的 CTA 争夺注意力"）。 没有证据的形容词不能作为发现。
3. 纳入可访问性检查。 计算对比度（捕获调色板中各色彩组合在实际使用角色下的 WCAG 比率），从 pages/*.json#media.images 检查替代文本覆盖情况，从 pages/*.json#landmarks 检查地标存在情况和标题顺序，以及检查缺少内容的链接标签（触发时复用 T-link-content-free）。

阶段 3 — SEO 与技术检查

安装了 marketing-skills 插件时，遵循 marketing-skills:seo-audit 的方法，并将其问题 / 影响 / 证据 / 修复项规范化为发现。未安装时，直接运行检查——这些都可以通过 curl/Playwright 获取：

范围	检查项	方法
可爬取性	robots.txt 是否存在且合理；是否声明 sitemap，且是否为有效 XML	curl
索引	canonical 是否存在且指向自身；meta robots 是否意外设为 noindex；http→https 是否单跳重定向；是否存在重定向链	curl -I
语义	main/nav/footer 地标；单个 <h1>；标题层级是否有跳级	pages/*.json + Playwright
元数据	每页标题 / 描述是否存在且质量合格；页面之间是否重复；Open Graph 是否完整	pages/*.json#metadata
结构化数据	是否存在 JSON-LD、解析是否有效、实体类型是否与页面类型匹配	Playwright / curl

如果某项失败与 rollout:baseline 检查 id 匹配 （../rollout/reference/checks.md：single-h1、title-missing、 meta-description、canonical、sitemap、jsonld、img-alt、 landmark-main、duplicate-title），请复用该 id 作为 发现的 evidence.ref（check:<id>）——记录到 rollout 台账中的已知 id 下的发现会自动由 AEM 自动修复注册表处理。

Core Web Vitals。 通过 Playwright 性能 API 测量 LCP / CLS / TBT（对 largest-contentful-paint 和 layout-shift 使用 PerformanceObserver，对 TBT 使用 longtask 条目），并测试两个视口：移动端（375×667，在会话支持时限制 CPU）和桌面端（1440×900）。如果无需密钥即可通过网络访问 PageSpeed Insights API，优先使用并记录 method: "psi-api"（它还会提供字段 INP）；否则记录 method: "playwright-lab"，并在测量说明中指出实验室 TBT 是 INP 的代理指标。根据 reference/scoring.md § 性能中的 Google 阈值表对每项指标进行分类。

修复指导。 安装了 modern-web-guidance 时，对每种不同的失败类型运行 npx -y modern-web-guidance@latest search "<specific failure>" 并在发现的 guides[] 中引用返回的指南 id。未安装时，写出通用修复建议，并将 guides: [] 留空。

阶段 4 — LLM 可见性

安装了 marketing-skills:ai-seo 时，请遵循其方法论。 未安装时，请直接评估：

• llms.txt — 是否存在于源站根目录？
• 可回答性 — 每个审计页面是否都以易于提取、结构清晰的文案回答用户可能提出的问题（“这要多少钱”“这是什么”）？答案在页面中的位置是否足够靠前？
• schema.org 覆盖范围 — JSON-LD 实体是否涵盖组织，以及答案引擎进行实体理解所需的页面类型实体？
• 以问题为标题的覆盖率 — 有多少 h2/h3 对应可提问的问题或便于浏览的主题，而非标语？
• 内容深度 — 关键页面中可提取文案的字数；具体、可引用的说法与单薄的营销文案之间的对比。
• 关键事实是否位于可抓取文本中 — 价格、产品介绍和目标用户是否以可抓取文本呈现，还是被锁在图片和 JS 渲染的小组件中？
• 可引用性可读性指标 — 运行 skills/deploy/scripts/ai-readability.mjs --origin <site> <sampled paths>，并报告每个页面的严格评分，以及增加渲染专属文字的主要区块；该指标采用 Adobe 的 AI Content Visibility Checker 的精确公式（deploy/reference/ai-readability.md）。

阶段 4 的每项发现都要指出具体的修复措施（“在定价表中以文本列出三个价格档位；目前它们只显示在套餐卡片图片中”），不能只写类别（“改进内容”）。

阶段 5 — 参考基准对比（可选）

当 refero MCP 工具可用时触发 — 阶段 0 的探测曾尝试使用 mcp__refero__refero_search_styles；--benchmark 会强制重新探测。工具不可用时妥善跳过 （benchmarks: { status: "skipped", reason: … }）。

工具可用时：检索 2–3 个相同垂直领域的参考风格，将审计网站的品牌表现（阶段 1 的测量结果）与该类别中最佳实践进行比较，并在相关设计发现和 audit.json#benchmarks.references 中列出每个参考案例 — 标题、URL，以及一行说明其做得更好的地方。

阶段 6 — 综合与报告

1. 评分卡。 按照 reference/scoring.md 对七个维度评分——先使用锚点，落实证据门槛，将未测量的维度设为 null 并重新归一化。计算加权总分。

2. 发现项。 将阶段 1–5 的结果整合到按优先级排序的台账中：P1（正在流失业务或排斥用户）／P2（造成实质性阻碍）／P3（润色）。每项发现包括：dimension、evidence（测量／矛盾点／截图／检查／基准引用）、businessImpact（一句话说明）、具体的 fix、guides[]。

3. 提升方向。 最后提出 2–3 个重新设计方向，严格按照 uplift 的变体角色约定撰写（../uplift/SKILL.md § The three-variant role contract）：A 忠于原设计并修复问题（指出解决哪些发现项）；B 放大一个已捕获但利用不足的特质；C 电影感（以动效作为身份特征，并依据 ../prototype/reference/motion-registers.md § Selection heuristic 建议风格）。如果当前页面无法支撑有差异化的中间方案，则省略 B——两个有力的方向胜过三个薄弱的方向。

4. 编写 stardust/audit/<domain-slug>/audit.json——遵循 reference/report-format.md 第 1 部分中的架构、slug 规则和测量规则。_provenance 必须是第一个键。

5. 通过将任务委派给 $impeccable craft 来生成 stardust/audit/<domain-slug>/report.html，使用 reference/report-format.md 第 2 部分中的任务说明——采用与 prototype 相同的技能调用机制，并遵守相同规则：绝不手动套模板生成报告。运行渲染后的验证清单；若失败，则针对具体违规项重新调用 craft。使用 open stardust/audit/<domain-slug>/report.html 打开结果。

6. 记录台账（仅限 rollout 项目）。 当 stardust/rollout/rollout.json 存在时，通过 node skills/rollout/scripts/findings.mjs record 将每项发现记录到交付台账，来源命名空间为 audit:——使用 --source audit:<dimension>，根据下方映射设置 --layer，保留严重程度，并按照 ../rollout/reference/audit-sources.md § Recording an external finding 规范化 --fixability。将返回的每个 ID 写入对应发现项的 ledgerId。

   audit 维度	台账层级
   brand-expression	brand-tensions
   visual-hierarchy-craft	design-ux
   conversion-focus	content-conversion
   accessibility	accessibility
   technical-seo	seo（全站：cross-page）
   content-llm-visibility	ai-search
   performance	seo

7. --deploy。 若传入此参数，则按照 ../deploy/da-deploy-protocol.md 中的 DA 传输流程发布 report.html——将文件作为单个来源 PUT，POST 预览，POST 正式发布，并验证交付 URL 返回 200——然后输出交付 URL。仅进行传输；绝不对报告运行 deploy 的 section→block 转换。

8. 聊天摘要。 简短说明——成果已写入磁盘，可打开查看：

   audit complete — <url>
   
   Site health: <overall>/100
     <dimension>: <score>   × 7 (not-measured dimensions listed with reasons)
   
   Findings: <n> P1 · <n> P2 · <n> P3
   Top lever: <the single highest-impact P1, one line>
   
   Report: stardust/audit/<domain-slug>/report.html
   Data:   stardust/audit/<domain-slug>/audit.json
   
   Next: run `$stardust uplift <url>` — the report's closing directions
   are its variant briefs.
   

降级处理

在阶段 0 探测一次；所有降级情况都记录在 audit.json#degradations 中，并呈现在报告的方法附录中。这些情况均不会中止审计。

缺少的能力	处理方式
refero MCP	跳过阶段 5；benchmarks.status: "skipped" 并附上原因
marketing-skills	直接运行阶段 3／阶段 4 的检查（见上表）
modern-web-guidance	使用通用修复建议文本；guides: []
PageSpeed Insights	仅使用 Playwright 实验室指标；测量说明指出实验室 TBT 仅作为 INP 的代理指标
Playwright 像素采样不可行	brandColorShare 以 method: "surface-estimate" 和依据一并提供
rollout 项目	不记录台账；每项发现的 ledgerId: null

严格约束

• 不得编造数据。 无法获取的测量值，在两个产物中都写为 not measured (<reason>)。估算值须标明方法和依据。extract 通过同样的纪律防止综合编造（../extract/SKILL.md § 失败模式）—— 编造的审计数字比缺失的数据更糟，因为它们看似可用于采取行动，实际却是错误的。
• 遵循证据规范。 每项发现都须引用可观察的证据： 测量键、T-* 张力 ID、截图区域、 检查 ID 或基准测试 URL。综合时会删去没有引用的主张。
• 报告以精工方式呈现。 report.html 由 $impeccable craft 根据 reference/report-format.md 中的简介编写，之后再验证——绝不 使用手工模板，也绝不手工修补。
• 两个产物都必须包含来源信息，具体形态见 ../stardust/reference/artifact-map.md § 来源信息形态。
• 非交互式。 正常流程中不提问；假设会在报告中说明。只有以下两种情况会停止。
• 审计不负责修复。 修复应由 uplift（页面重设计）、 direct 第 2.5 阶段（改进清单）和 rollout 的优化 循环（平台自动修复）完成。审计会指出修复方案，但绝不编辑 网站。

停止条件

仅在以下情况下停止并报告：

(a) Extract 完全失败——网站无法访问、结构 无法解析，或在启用 Chrome 回退方案后仍遭遇机器人管理拦截。原样报告 extract 的错误；无需进行审计。 (b) impeccable 不可用——第 2 阶段的评议／审计环节和 第 6 阶段的报告呈现都需要它。根据第 0 阶段的例外条款， 运行会以降级模式继续（VISION 检查、SEO／技术检查、 大模型可见性、基准测试仍会执行），并写入 audit.json；随后停止并告知用户，经过设计的报告需要 impeccable 插件——交付数据，不提供 手工套用模板的替代品。

其他情况均按降级阶梯处理；正常流程中，审计绝不会为等待确认而停止。

输出

stardust/
├── current/                             ← from extract (reused when <7 days old)
│   ├── _brand-extraction.json
│   ├── brand-review.html                ← Tensions section = Phase 1 input
│   ├── pages/<slug>.json
│   └── assets/screenshots/<slug>.png    ← VISION-pass + report evidence figures
└── audit/
    └── <domain-slug>/                   ← hostname, www-stripped, dots → dashes
        ├── audit.json                   ← scorecard, measurements, findings[], provenance
        └── report.html                  ← craft-rendered, self-contained

stardust/rollout/optimize/findings.json  ← appended via findings.mjs (rollout projects only)

审计不会写入任何 state.json 条目——提取状态归 extract 所有；审计自身的产物通过来源信息自我描述。 针对全新提取结果重新运行审计会覆盖 stardust/audit/<domain-slug>/；台账记录则按台账自身的 ID 哈希去重。

范围

• 执行审计并提出建议；绝不修改网站或其重设计产物。
• 每次运行仅审计一个源站。审计一组竞争对手需要运行 N 次。
• 自然的后续操作：$stardust uplift <url>（结尾处的 指引是其变体简介）、stardust 的 direct 技能（发现会 纳入第 2.5 阶段的改进清单），rollout 的优化循环 （台账中包含已知检查 ID 的发现会在 AEM 上自动修复）。

参考资料

• reference/scoring.md — 七个维度、权重、40/70/90 分的可观察锚点、评分流程。
• reference/report-format.md — audit.json 架构（第 1 部分）以及 report.html 制作说明和渲染后验证（第 2 部分）。
• ../extract/SKILL.md — 爬取、捕获、品牌表面提取；反综合原则的 § Failure modes。
• ../extract/reference/brand-review-template.md § Tensions — Phase 1 延续使用的 T-* 检测器目录。
• ../prototype/SKILL.md § Invoking impeccable — 用于批评（Phase 2）和报告渲染（Phase 6）的技能调用委派机制。
• ../rollout/reference/audit-sources.md — Phase 6 应用的发现台账规范化规则（严重程度、可修复性）。
• ../rollout/reference/checks.md — 可复用的基线检查 ID，以便 AEM 自动修复能识别这些发现。
• ../rollout/scripts/findings.mjs — 台账写入器（record）。
• ../uplift/SKILL.md § The three-variant role contract — 用于结尾提升方向的框架。
• ../prototype/reference/motion-registers.md § Selection heuristic — 方向 C 的寄存器建议。
• ../direct/SKILL.md § Phase 2.5 — 后续重新设计时，改进清单所依据的审计发现。
• ../deploy/da-deploy-protocol.md — --deploy 背后的 DA 传输机制（源 PUT → 预览 → 正式环境；不转换区块）。
• ../stardust/SKILL.md § Setup — Phase 0 中运行的主技能设置。
• ../stardust/reference/artifact-map.md — 溯源数据结构。