qa

stardust:qa — 只读网站 QA 巡检

输入一个线上 URL，输出一份基于证据的发现报告。此技能绝不会编辑任何内容——包括网站内容、DA 文档和仓库代码。它唯一会写入的文件是 stardust/qa/ 下的报告产物。如果用户想修复发现的问题，这属于此技能之外单独进行的明确后续操作。

qa 是 rollout 部署验证的部署后对应流程：rollout 检查“每个页面都上线了吗？”，qa 则检查“所有已上线内容实际上都正确吗？”——涵盖部署可能悄然出错的三个层面：

1. 交付——流水线实际提供的内容（.plain.html、完整 HTML、样式表、站点地图）
2. 渲染——浏览器在区块装饰后显示的内容（以及实际运行效果：自动播放的视频若只显示封面图，就属于渲染缺陷）
3. 回归——自上次获批状态以来发生的变化（视觉基线）

上层检查通过，绝不代表下层也通过：发布返回 200 ≠ 已交付；已交付的 HTML ≠ 渲染正确。

设置

1. 如果本次会话尚未完成，请运行主技能的设置步骤（skills/stardust/SKILL.md § 设置）。qa 也可独立运行——只需要一个线上基础 URL。
2. 确定基础 URL（*.aem.live 主机或生产域名）。如果用户未提供，请查看 stardust/rollout/rollout.json（site.liveHost），或询问用户。
3. 确定清单来源——本次巡检覆盖哪些页面。合并以下任意来源：stardust/template-map.json（也提供模板分配信息，供一致性检查使用；scripts/from-knowledge.mjs 会根据规范写入此文件，并包含源站已有的 404 允许列表条目）、路径文件和线上 sitemap.xml（始终会获取；站点地图不匹配会成为发现项，因此错误的站点地图无法悄然缩小覆盖范围）。
4. 可选输入，可启用更深入的检查：
   • --scrape stardust/scrape——与提取时的原始内容进行逐字保真度比较
   • --expected-blocks <json>——按模板指定区块预期
   • --parity <json>——要重放的动态一致性文件（默认值为 stardust/dynamics/parity.json；若文件不存在，dynamics 检查会报告 parity-missing）
   • --auth-header "token …" / --token-env SITE_TOKEN——用于受保护的源站；密钥只会发送到基础源站 （否则会通过站群共识推导）
   • --blocks-dir <dir>——网站的 blocks/ 检出目录，使 editability 检查能够遵循 @ew-exempt JSDoc 标签（否则请对由索引驱动的区块传入 --ew-exempt a,b）
5. 浏览器检查需要项目能够解析到 playwright（node_modules/playwright）。 若缺少该依赖，只运行交付层检查（--checks routing,content,templates,metadata,links），并告知用户跳过了哪些检查。
6. 在巡检开始和结束时，根据主技能的 reference/run-status.md，向 stardust/status.jsonl 追加阶段转换记录。

流程

阶段 1 — 确定性扫描

node <plugin>/skills/qa/scripts/qa.mjs \
  --base https://main--<site>--<org>.aem.live \
  --template-map stardust/template-map.json \
  --scrape stardust/scrape

写入 stardust/qa/inventory.json、report.json、report.html、位于 stardust/qa/shots/ 下的截图，以及（首次运行时）位于 stardust/qa/baselines/ 下的视觉基线。退出码 0 = 没有活动错误，1 = 有活动错误， 2 = 基础设施故障。reference/checks.md 记录了每项检查、其发现项 ID 以及严重性判定理由。实用的变体：--checks <subset>、 --max-pages <n>（冒烟运行）、--fail-on warn（严格门禁）。ai-readability 检查 会按页面复现 Adobe 的 AI Content Visibility Checker（已提供的字数 ÷ 已渲染的字数），并 按区块归因差异（deploy/reference/ai-readability.md）。

editability 检查是部署后的 Experience Workspace 可编辑性门禁（deploy SKILL.md § 8，EW1–EW10）：对每个页面，它会在已提供的文档上 重新创建 da.live 画布的检测机制，让实时页面完成装饰，然后统计哪些创作文本仍带有其编辑器 索引。editability/dead-text（错误）= 某个区块重建了创作文本，作者无法在画布中点击该文本；editability/duplicated-index （警告）= 展示性克隆保留了索引。位于标记为 @ew-exempt 的区块内（或列在 --ew-exempt 中）的 失效文本属于信息项，不是错误。

首次扫描网站时：预计会出现一波 visual/baseline-created 信息项—— 这表示正在建立基线，并非缺陷。基线是截图，因此保存在本地（stardust/.gitignore 排除了 qa/baselines/ 和 qa/shots/，master skill § Artifacts）：在同一台机器上后续运行会与基线进行差异比较；新克隆的项目会在首次扫描时重新建立基线。qa/allowlist.json 是已跟踪的判定记录。

阶段 2 — 分类含糊的标记（由大模型判定，仍为只读）

确定性扫描会将两类发现标记为需要分类；读取 report.json，只判定这些项：

• content/verbatim-below-threshold — 将 evidence.missingNodes 与 实时页面及抓取结果进行检查：内容是否确实丢失或损坏（缺陷），还是经过了可接受的转换（可加入允许列表）？
• visual/visual-diff — 并排打开 evidence.baseline 和 evidence.current （它们是 PNG 文件；请查看）：是真实的布局／样式回归，还是无害的动态变化（轮播帧、已加载的字体、实时嵌入内容）？使用 bands 证据定位变化区域。

在给用户的摘要中为每项发现添加注释，记录每项判定（缺陷或非缺陷及原因）。不要编辑 report.json 中的分数，也不要修复任何内容。

阶段 3 — 向用户报告

汇总：按严重性统计总数，首先列出已确认的缺陷（附页面路径和一句证据），然后列出 已分类排除的标记及其理由，最后列出值得注意的警告。指出 stardust/qa/report.html。 提出修复建议，但不要实施。

允许列表工作流（记录在案的非缺陷）

stardust/qa/allowlist.json（架构见 schemas/qa-allowlist.schema.json） 用于记录已知的非缺陷，避免它们淹没之后的每次运行结果——例如，源页面本身就提供了占位文案，或表单端点有意等待 客户端凭据。条目依据 check/id/path/messagePattern 匹配，且必须 附带原因。允许列表中的发现仍会保留在报告中，只是显示为灰色，确保不会删除证据。

只有在用户确认某标记属于非缺陷（或项目记录中已将其记为非缺陷）时，才添加条目。切勿为了让运行结果显示为绿色而加入允许列表。

只读约定

• 只在 stardust/qa/ 下写入（另加一行 status.jsonl 记录）。
• 绝不调用部署／发布 API，绝不向 DA 发送 PUT 请求，绝不编辑区块、 样式或内容——即使扫描本身发现了“简单”的修复，也不例外。
• 如实报告失败：崩溃的检查会以 <check>/check-crashed（错误）出现在报告中，绝不会被静默忽略。

调度 / CI

运行器是纯 Node，不依赖插件运行时，因此同一条命令可用于 GitHub Action 或 cron 进行漂移监控；--fail-on 用于设置门槛。在没有 playwright 的 CI 中，将 --checks 固定为交付层子集。