qa-quarto

Quarto 对比 Beamer 的对抗式 QA 工作流

通过迭代式审查者/修复者循环，将 Quarto HTML 幻灯片与 Beamer PDF 基准进行比较。

理念： Beamer PDF 是黄金标准。Quarto 译稿在每个维度上都必须至少与之相当。

---

工作流

Phase 0: Pre-flight → Phase 1: Critic audit → Phase 2: Fixer → Phase 3: Re-audit → Loop until APPROVED or dry (2 consecutive dry rounds; fallback cap 5)

硬性门槛（不可妥协）

门槛	条件
溢出	内容不得被截断
图表质量	交互式图表 >= 静态图表
内容一致性	不得缺少幻灯片/公式/文本
视觉回归	Quarto 在所有维度上 >= Beamer
幻灯片居中	内容居中，不得跳动
符号忠实度	所有数学内容必须与 Beamer 完全一致

阶段 0：预检

1. 定位 Beamer（.tex/.pdf）和 Quarto（.qmd/.html）文件
2. 检查文件是否为最新版本（如果 QMD 比 HTML 新，则重新渲染）
3. 如适用，验证 TikZ SVG
4. 测量渲染结果："${SLIDE_QA_PYTHON:-python3}" scripts/slide-qa.py Quarto/[Lecture].html。该脚本会在无头 Chrome 中加载幻灯片，并将报告写入 quality_reports/audits/slide-qa/[Lecture]/report.md，其中包含每张幻灯片的溢出像素数，以及每张幻灯片的一张截图。退出码 1 表示发现问题——溢出、内容被裁剪、图像损坏，或文件缺失/大小写错误；退出码 2 表示无法运行（通常是缺少 Playwright——脚本会打印一次性 venv 安装命令以及需要设置的 SLIDE_QA_PYTHON 行）——请说明此情况，审查者将改为阅读源文件。

阶段 1：初始审查

启动 quarto-critic Agent，全面比较 Beamer 与 Quarto，并传入阶段 0 中的 slide-qa 报告路径，用于检查溢出门槛。将报告保存到 quality_reports/[Lecture]_qa_critic_round1.md。

阶段 2：修复循环

如果结果不是 APPROVED，则启动 quarto-fixer Agent，按 Critical → Major → Minor 的顺序应用修复、重新渲染并验证。

阶段 3：重新审查

对修复者重新渲染的结果再次运行 scripts/slide-qa.py，然后使用最新报告重新启动审查者，以验证修复效果。必要时返回阶段 2。

迭代限制 — 持续循环直至无新增问题

这是 orchestrator-protocol.md 中的 持续循环直至无新增问题 原语：审查者会返回 FINDING（硬性门槛表是 CRITICAL 问题的汇总，参见 orchestration-schemas.md）；循环会在 连续 2 轮无新增问题后收敛——即没有新增 CRITICAL/MAJOR 问题的轮次（按 id = sha1(file:line:locus) 去重），而不是在固定轮数后结束。

• 兜底上限： 最多 5 轮，以限制无法收敛的循环；之后将剩余问题升级给用户。
• 两次失败规则： 同一门槛在第 N 轮和第 N+2 轮均未通过时，将标记给用户，而不再尝试修复（summary-parity.md）。
• 仅当所有硬性门槛均通过且不再有 CRITICAL 或 MAJOR 问题时，才判定为 APPROVED（Minor 问题会列出供用户查看）。

最终报告

将报告保存到 quality_reports/[Lecture]_qa_final.md，其中包括硬性门槛状态、迭代摘要和剩余问题。

发现经过验证，而非仅仅写下（v2.5）

此技能的审阅者会按照 finding-schema.json 中经过机器检查的契约提交发现。报告为 JSON 数组。

投入审阅工作前，先对测试框架进行冒烟测试——如果一次运行分发了多个审阅者，却无法写出有效报告，那么整个审阅轮次就白费了：

echo '[]' | python3 scripts/validate-findings.py

审阅者 Agent 仅可读取，因此由此技能写入文件。对于每位审阅者的最终回复：将文字报告保存到此技能中该审阅者对应的报告路径，将其末尾的 fenced json 代码块复制到临时文件，并在验证时填写 ID：

python3 scripts/validate-findings.py --fill-ids block.json > <report>.json.tmp \
  && mv <report>.json.tmp <report>.json || rm -f <report>.json.tmp   # exit 0 required; a failed run keeps no file
python3 scripts/validate-findings.py --check-quotes <report>.json   # each quote must be the file's own text (orchestration-schemas.md §1)

如果审阅者没有返回 json 代码块，或代码块未通过验证，则视为尚未完成审阅：将验证器的错误文本一并发送给它，再重新派发一次；之后应将该审阅视角报告为缺失，而不是在缺少它的情况下进行归并。

契约的约束及其原因：

• rule — 被违反的文档规则或标准。未引用规则的发现只是意见，而意见不能阻止提交。
• failing_case — 会导致该主张不成立的具体配置，或确切缺失的假设。*“这里可以写得更清楚”*无法通过验证。
• id = sha1("<file>:<line>:<locus>") — 具有确定性，因此不同轮次间可以精确去重，也能核查两次警告规则，而不是凭目测判断。
• mechanical — 仅当修复不会改变结果时设为 true（拼写错误、交叉引用、格式、标签）。对于估计目标、假设、规格、推断程序、样本定义或报告措辞，绝不可设为 true：这些问题应交由研究人员处理。

在验证前，先应用 orchestration-schemas.md §7 中的各审阅视角证据要求和**“不计入”筛选条件**，以免已知的误报到达裁决环节。验证阶段倾向于驳斥，并为每条发现设置 verdict（审阅者不设置此字段）：只有 verdict: "confirmed" 的发现才会保留；无法找到依据的内容会被删除，而非降级为警告。