qa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

stardust:qa — read-only site QA sweep

stardust:qa — 只读站点QA扫描

One live URL in. One evidence-bound findings report out. This skill never edits anything — not site content, not DA documents, not repo code. Its only writes are report artifacts under

stardust/qa/

. If the user wants findings fixed, that is a separate, explicit follow-up outside this skill.

qa

is the post-deploy counterpart of

rollout

's delivery verification: where rollout asks "did every page ship?", qa asks "is everything that shipped actually correct?" — at all three layers a deploy can silently break:

delivery — what the pipeline serves (
```
.plain.html
```
, full HTML, sheets, sitemap)
rendered — what a browser shows after block decoration
regression — what changed since the last approved state (visual baselines)

A green upper layer never implies the lower one: a publish 200 ≠ delivered, delivered HTML ≠ rendered correctly.

输入一个线上URL，输出一份附带证据的检测报告。该技能绝不修改任何内容——不修改站点内容、DA文档或仓库代码。仅会在

stardust/qa/

目录下生成报告产物。若用户希望修复检测到的问题，需在本技能之外单独发起明确的后续请求。

qa

是

rollout

交付验证的部署后配套工具：

rollout

关注“所有页面是否都已部署？”，而

qa

关注“已部署的所有内容是否真的正确？”——覆盖部署可能静默出错的三个层面：

交付层——管道提供的内容（
```
.plain.html
```
、完整HTML、样式表、站点地图）
渲染层——浏览器完成区块装饰后展示的内容
回归层——与上次已批准状态（视觉基准）相比发生的变化

上层检测通过绝不代表下层无问题：发布返回200状态码≠内容已正确交付，交付的HTML≠渲染正确。

Setup

设置步骤

Run the master skill's setup (
```
skills/stardust/SKILL.md
```
§ Setup) if not already done this session.
```
qa
```
works standalone too — it only needs a live base URL.
Resolve the base URL (the
```
*.aem.live
```
host or production domain). If the user didn't give one, look in
```
stardust/rollout/rollout.json
```
(
```
site.liveHost
```
) or ask.
Resolve the inventory source — what pages the sweep covers, merged from any of:
```
stardust/template-map.json
```
(also supplies template assignments for conformance), a paths file, and the live
```
sitemap.xml
```
(always fetched; parity mismatches become findings, so a wrong sitemap can't silently shrink coverage).
Optional inputs that unlock deeper checks:
- ```
--scrape stardust/scrape
```
  — verbatim fidelity vs the extraction capture
- ```
--expected-blocks <json>
```
  — explicit per-template block expectations (otherwise derived by fleet consensus)
Browser checks need playwright resolvable from the project (
```
node_modules/playwright
```
). If missing, run the delivery-layer checks only (
```
--checks routing,content,templates,metadata,links
```
) and tell the user what was skipped.
Append a phase-transition line to
```
stardust/status.jsonl
```
per
```
reference/run-status.md
```
(master skill) at sweep start/end.

若本次会话尚未完成主技能的设置，请执行主技能设置（
```
skills/stardust/SKILL.md
```
§ Setup）。
```
qa
```
也可独立运行——仅需一个线上基础URL即可。
确定基础URL（
```
*.aem.live
```
主机或生产域名）。若用户未提供，可查看
```
stardust/rollout/rollout.json
```
中的
```
site.liveHost
```
字段，或向用户询问。
确定清单源——扫描覆盖的页面范围，合并自以下任意来源：
```
stardust/template-map.json
```
（同时提供合规性检查所需的模板分配信息）、路径文件，以及线上
```
site.xml
```
（始终会获取；若存在匹配差异会被列为检测结果，因此错误的站点地图不会静默缩小覆盖范围）。
可选输入项，用于解锁更深入的检查：
- ```
--scrape stardust/scrape
```
  ——与提取捕获内容的完全一致性检查
- ```
--expected-blocks <json>
```
  ——明确的模板预期区块配置（否则通过集群共识推导）
浏览器检查需要项目中可解析的playwright（
```
node_modules/playwright
```
）。若缺失，仅运行交付层检查（
```
--checks routing,content,templates,metadata,links
```
），并告知用户跳过的检查项。
在扫描开始/结束时，按照主技能的
```
reference/run-status.md
```
要求，向
```
stardust/status.jsonl
```
追加阶段转换记录。

Procedure

执行流程

Phase 1 — deterministic sweep

阶段1 — 确定性扫描

bash

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

Writes

stardust/qa/inventory.json

report.json

report.html

, screenshots under

stardust/qa/shots/

, and (first run) visual baselines under

stardust/qa/baselines/

. Exit 0 = no active errors, 1 = active errors, 2 = infra failure.

reference/checks.md

documents every check, its finding ids, and severity rationale. Useful variants:

--checks <subset>

--max-pages <n>

(smoke run),

--fail-on warn

(strict gate).

First run on a site: expect a wave of

visual/baseline-created

info findings — that is the baseline being established, not a defect. Baselines should be committed to the workspace repo so later runs diff against an approved state.

bash

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 <子集>

、

--max-pages <n>

（快速冒烟测试）、

--fail-on warn

（严格校验）。

首次在站点运行时：会出现大量

visual/baseline-created

信息类检测结果——这是基准正在建立的正常现象，而非缺陷。基准应提交至工作区仓库，以便后续运行时与已批准状态进行对比。

Phase 2 — triage the ambiguous flags (LLM judgment, still read-only)

阶段2 — 模糊标记分类（LLM判断，仍为只读）

The deterministic sweep marks two finding classes as needs triage; read

report.json

and judge only those:

```
content/verbatim-below-threshold
```
— inspect
```
evidence.missingNodes
```
against the live page and the scrape capture: is copy actually lost/corrupted (defect) or acceptably transformed (candidate for the allowlist)?
```
visual/visual-diff
```
— open
```
evidence.baseline
```
and
```
evidence.current
```
side by side (they are PNGs; view them): real layout/style regression, or benign dynamism (carousel frame, loaded font, live embed)? Use the
```
bands
```
evidence to locate the changed region.

Record each verdict by annotating the finding in your summary to the user (defect vs non-defect + why). Do not edit

report.json

scores and do not fix anything.

确定性扫描会将两类检测结果标记为需分类；读取

report.json

并仅对这些结果进行判断：

```
content/verbatim-below-threshold
```
——对照线上页面和捕获内容检查
```
evidence.missingNodes
```
：内容确实丢失/损坏（缺陷），还是可接受的转换（可加入白名单的候选项）？
```
visual/visual-diff
```
——并排打开
```
evidence.baseline
```
和
```
evidence.current
```
（均为PNG文件）：是真实的布局/样式回归，还是良性动态变化（轮播帧、加载的字体、线上嵌入内容）？使用
```
bands
```
证据定位变化区域。

通过在给用户的总结中标注检测结果来记录每个判断（缺陷vs非缺陷+原因）。请勿修改

report.json

的评分，也不要修复任何问题。

Phase 3 — report to the user

阶段3 — 向用户汇报

Summarize: totals by severity, the confirmed defects first (with page paths and one-line evidence), then triaged-away flags with their rationale, then notable warns. Point at

stardust/qa/report.html

. Recommend — but do not apply — fixes.

汇总内容：按严重程度分类的总数，先列出确认的缺陷（含页面路径和一行证据），再列出已分类排除的标记及理由，最后列出值得关注的警告。引导用户查看

stardust/qa/report.html

。给出修复建议，但不要直接执行修复操作。

Allowlist workflow (documented non-defects)

白名单流程（已记录的非缺陷）

stardust/qa/allowlist.json

(schema in

schemas/qa-allowlist.schema.json

) keeps known non-defects from drowning every future run — e.g. a source page that itself ships placeholder copy, or a form endpoint deliberately awaiting a client credential. Entries match on check/id/path/messagePattern and must carry a reason. Allowlisted findings stay in the report, greyed out, so the evidence is never deleted.

Only add an entry when the user confirms the flag is a non-defect (or it is already documented as one in the project's records). Never allowlist to make a run green.

stardust/qa/allowlist.json

（ schema见

schemas/qa-allowlist.schema.json

）用于避免已知非缺陷淹没后续每次运行的结果——例如源页面本身包含占位文本，或表单端点故意等待客户端凭证。条目通过检查项/ID/路径/消息模式匹配，必须附带理由。已加入白名单的检测结果仍会保留在报告中，仅会灰度显示，因此证据不会被删除。

仅当用户确认标记为非缺陷（或项目记录中已明确标注为非缺陷）时，才可添加白名单条目。绝不能为了让扫描结果显示“通过”而添加白名单。

Read-only contract

只读协议

Writes only under
```
stardust/qa/
```
(plus the
```
status.jsonl
```
ledger line).
Never invokes deploy/publish APIs, never PUTs to DA, never edits blocks, styles, or content — even for "trivial" fixes the sweep itself surfaced.
Reports failure honestly: a crashed check appears in the report as
```
<check>/check-crashed
```
(error), never silently dropped.

仅在
```
stardust/qa/
```
目录下写入内容（以及
```
status.jsonl
```
中的记录行）。
绝不调用部署/发布API，绝不向DA发送PUT请求，绝不修改区块、样式或内容——即使是扫描本身发现的“微小”修复也不行。
如实报告失败：崩溃的检查项会在报告中显示为
```
<check>/check-crashed
```
（错误），绝不会被静默忽略。

Scheduling / CI

调度 / CI集成

The runner is plain node with no plugin-runtime dependency, so the same command works from a GitHub Action or cron for drift monitoring;

--fail-on

sets the gate. In CI without playwright, pin

--checks

to the delivery-layer subset.

运行器是纯Node.js程序，无插件运行时依赖，因此相同命令可在GitHub Action或cron中用于漂移监控；

--fail-on

参数可设置校验门限。在无playwright的CI环境中，需将

--checks

固定为交付层检查子集。