技能使用指南

qa-quarto（Quarto与BeamerQA审计工作流程）Skill 能解决什么问题？

qa-quarto 是一套对抗式 Quarto 与 Beamer 质检工作流：审计员挑问题、修复员动手改，循环至多 5 轮，六道硬门把关溢出、图表质量、内容对等、视觉回归、居中与公式保真，并把过程与最终报告写入 quality_reports。本文讲清安装启用、调用方式、竞品对比与典型场景，帮你在课件迁移中守住质量底线。

Quarto与BeamerQA审计工作流程Skillqa-quarto
8 个章节 约 13 分钟阅读 AI 智能生成

Quarto与BeamerQA审计工作流程Skill：让 Quarto 幻灯片在每个维度上都不输 Beamer

  • 一句话定位：这是一个把「Beamer PDF 视为黄金标准」的对抗式质检工作流，用审计员与修复员的循环迭代，把 Quarto HTML 幻灯片的质量逼到与 Beamer 基准持平甚至更好。
  • 核心机制：阶段 0 预检 → 阶段 1 审计 → 阶段 2 修复 → 阶段 3 重新审计，循环直到批准，最多 5 轮，超出则向用户上报剩余问题。
  • 六道硬门不可协商：溢出、图表质量、内容对等、视觉回归、幻灯片居中、符号保真度，任一门不通过即不得批准。
  • 产物可追溯：过程报告写入 quality_reports/[Lecture]_qa_critic_round1.md，最终报告写入 quality_reports/[Lecture]_qa_final.md。
  • 最适合谁：把课程讲义、学术报告从 Beamer 迁移到 Quarto 的教师、研究者与教学团队，以及需要批量维护幻灯片质量的内容工程师。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：Quarto与BeamerQA审计工作流程Skill 技能英文名：qa-quarto 技能ID：13615

它解决的是一个非常具体、却极其耗神的痛点：把 LaTeX Beamer 做成的 PDF 讲义翻译成 Quarto 的 HTML 幻灯片之后，质量到底有没有退化。传统做法是人眼逐页比对，几十上百页的课件比到第三十页就开始眼花，公式符号被悄悄改掉、图表从静态变交互后退化、长代码块被截断溢出、幻灯片内容左右跳动……这些细节问题往往在讲课现场或报告当天才暴露。qa-quarto 把这个比对过程变成一套可重复、有硬性验收标准、带迭代上限的自动化审计流程。

一键安装的思路与步骤（以下为通用流程，具体命令与入口以官方说明为准）：

  1. 确认安装前提：你的 AI 助手环境需支持技能（Skill）机制，并能授予 Read、Grep、Glob、Write、Edit、Bash、Task 这些工具权限——因为审计要读文件、修复要写文件、重新渲染要通过 Bash 调用渲染命令、并行分析要派发子任务。同时本地应存在待比对的 Quarto 源文件与产物（.qmd / .html）以及 Beamer 基准文件（.tex / .pdf）。
  2. 在技能市场或技能库中检索：使用技能英文名 qa-quarto 或技能 ID 13615 搜索，找到条目后点击安装/启用，通常为一键完成，无需手工配置依赖。
  3. 确认运行上下文：该技能声明了 context: fork，意味着它在被调用时会以独立的上下文分支运行，不污染主对话的上下文，适合长时间、多轮次的审计任务。
  4. 验证是否生效：安装后列出当前可用技能，确认 qa-quarto 出现在列表中；随后在对话中直接说出技能名并给出讲义编号（技能的参数提示为 [LectureN]，即指定某一讲），观察它是否按「预检 → 审计 → 修复 → 重新审计」的顺序推进，并在 quality_reports/ 下生成对应的报告文件。若未生成报告，通常说明权限未授予或文件路径不匹配。

该技能的主要功能和特点

  • 对抗式双角色循环：不是「检查一遍给个建议」的软性审查，而是审计员（quarto-critic）负责挑问题、修复员（quarto-fixer）负责改问题，改完重新审计，直到审计员批准为止。角色分离避免了「自己写自己评」的宽容偏差。
  • 六道硬门作为验收标准：溢出（无内容被截断）、图表质量（交互式图表需不弱于静态图表）、内容对等（无缺失幻灯片、方程、文本）、视觉回归（Quarto 在所有维度不低于 Beamer）、幻灯片居中（内容居中且无跳动）、符号保真度（所有数学公式从 Beamer 逐字复制）。硬门不可协商，任一项不达标就继续循环。
  • 修复按优先级排序：修复员按「关键 → 主要 → 次要」的顺序处理问题，先堵致命伤，避免把预算耗在排版小瑕疵上。
  • 新鲜度检查：预检阶段会比较源文件与产物的时间戳，如果 .qmd 比 .html 新，先重新渲染再审计，杜绝「审的是旧版本」这种低级但常见的误判。
  • TikZ SVG 校验：对使用 TikZ 绘图的讲义，预检会额外验证 SVG 产物是否正常，避免图形丢失或渲染残缺。
  • 迭代有上限、结论有落盘：最多 5 轮修复，防止无限打磨；最终报告包含硬门状态、迭代摘要与剩余问题，形成可交接的质量凭证。
  • 和普通工具的差别：语法检查器只关心「代码能不能跑」，视觉回归工具只关心「像素像不像」，而 qa-quarto 关心的是教学内容的语义与呈现是否等价——公式是不是逐字复制、内容有没有整块缺失、课堂投影时会不会有内容被切掉。

如何使用该技能？

  1. 准备文件：把同一讲的 Beamer 基准文件（.tex 或 .pdf）与 Quarto 文件（.qmd 或渲染产物 .html）放在技能可访问的路径下，命名尽量对应，便于它定位配对。
  2. 调用技能并指定讲次：在对话中提及技能 qa-quarto，并按参数提示传入讲次标识，例如「用 qa-quarto 审计 Lecture3」。参数提示形式为 [LectureN]，具体调用写法以官方说明为准。
  3. 等待阶段 0 预检结果：技能会先定位两套文件、检查新鲜度（必要时重新渲染）、校验 TikZ SVG。这一步的输出会告诉你「即将比对的是哪两个版本」。
  4. 阅读第一轮审计报告：审计员会全面比对各维度，报告写入 quality_reports/[Lecture]_qa_critic_round1.md。报告中的问题会按硬门归类，并标注严重程度。
  5. 让修复员动手（或人工确认后再动手）：未获批准时，修复员会按关键 → 主要 → 次要的顺序应用修复、重新渲染并自行验证。若你希望保留人工把关，可在这一步介入确认改动范围。
  6. 跟踪重新审计与循环：每轮修复后重新启动审计员验证，直到批准或达到 5 轮上限；达到上限时技能会把剩余问题上报给你。
  7. 领取最终报告：quality_reports/[Lecture]_qa_final.md 中包含硬门状态总表、迭代摘要与遗留问题清单，可直接作为交付或复查依据。

输入输出示例（说明性示意）：

  • 输入：qa-quarto Lecture5（并确保 Lecture5 的 .tex/.pdf 与 .qmd/.html 就位）
  • 输出：quality_reports/Lecture5_qa_critic_round1.md（首轮问题清单）→ 修复与重新审计 → quality_reports/Lecture5_qa_final.md（硬门全绿或列出剩余问题）

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
qa-quarto（本技能） 对抗式 Quarto vs Beamer 质量审计工作流 审计员/修复员循环、六道硬门、最多 5 轮迭代、报告落盘 需支持技能机制的 AI 助手环境，授予文件读写与命令执行权限；需自备 Beamer 基准与 Quarto 文件 课程讲义迁移、学术报告幻灯片质检、批量课件维护 优势：验收标准明确、修复闭环、结论可追溯；不足：依赖 Beamer 基准存在，纯 Quarto 原创项目无对应基准则价值下降
人工逐页比对 传统人工复核 人眼对照 PDF 与网页幻灯片 零门槛 页数少、一次性交付 优势：能理解教学意图；不足：极易疲劳漏检、无记录、不可复现，几十页以上成本陡增
通用视觉回归/截图对比工具 像素级差异检测 截图 diff、阈值告警 需搭建截图流水线与基线管理 UI 回归测试 优势：像素差异客观；不足：不理解语义，公式被改写但字形相近时难以发现，也无法自动修复
通用代码审查型 AI 助手 泛化的文件审阅与改写 读取文件、给出修改建议 通用对话即可，门槛低 零散文件修正 优势：灵活；不足：无固定硬门、无多轮对抗验证、无标准化报告，容易「看过就算改过」

该技能的典型应用场景与实际体验情况

场景一：高校教师的课程讲义从 Beamer 迁移到 Quarto 一位长期用 Beamer 写讲义的教师，把整门课迁到 Quarto 以获得更好的网页与交互图表体验。痛点是：迁移后总担心某几页公式符号被悄悄改动，或长推导被截断。使用 qa-quarto 后，符号保真度与溢出这两道硬门直接兜底，每讲的最终报告成为迁移验收单。实际体验：上手极简单，只需指定讲次；真正的成本在于准备一份可信的 Beamer 基准，基准质量差会连带审计结论失真。

场景二：学术会议报告的幻灯片复刻 研究者把会议报告从 Beamer 复刻成 Quarto，需要保证投影现场不出现内容被切、图表在投影分辨率下糊掉的情况。技能的「溢出」与「图表质量」硬门正好对应这两类事故。实际体验：多轮循环确实会反复几轮，尤其首轮问题较多时，按关键问题优先修复的策略让第二轮开始问题量明显收敛；建议预留出完整一轮的时间预算。

场景三：教学团队多人协作维护同一套课件 多人接手同一门课，风格与完整性容易走样。qa-quarto 的输出目录 quality_reports/ 天然形成版本化的质检记录，谁改的、改到第几轮、还剩什么问题一目了然。实际体验：报告可追溯是最大惊喜；注意事项是团队应约定统一的文件命名与讲次编号，否则技能定位文件时容易配错对。

场景四：含大量 TikZ 图形的技术讲义 图形复杂、依赖 TikZ 渲染的讲义，最容易出现「图没了但没人发现」。预检阶段的 SVG 校验能提前暴露图形问题。实际体验：这一步显著减少了「审完才发现图没渲染」的返工；但图形本身的语义是否正确仍需人工最终确认，技能保证的是「不丢、不退化」，不是「画得好看」。

该技能能为用户带来的价值

  • 把主观的「看起来差不多」变成客观的「六道硬门全过」：质检从感觉判断升级为可勾选的验收清单，减少讲课现场翻车的概率。
  • 把逐页人工比对的时间压缩为一次调用加若干轮自动循环：几十页幻灯片的比对从数小时级降到可由流程托管的等待时间，人只负责在关键节点确认。
  • 修复闭环，不停留在「提建议」：审计员发现问题、修复员真正动手改并重新渲染验证，避免「报告写了一堆、问题一个没改」。
  • 质量凭证长期可复用：quality_reports/ 下的报告构成课程资产的一部分，学期更替、人员交接时可直接调阅历史质检结论。
  • 降低 Quarto 迁移的心理门槛：有 Beamer 基准作黄金标准兜底，教师可以放心尝试更现代的呈现方式，而不必承担质量退化的风险。

常见问题 FAQ

Q1：怎么安装这个技能？需要自己配环境吗？ 在支持技能机制的 AI 助手中，用英文名 qa-quarto 或技能 ID 13615 在技能库中检索并一键启用即可，通常无需手工安装依赖。关键是要授予 Read、Grep、Glob、Write、Edit、Bash、Task 权限，否则它既读不到文件也无法重新渲染。具体命令与入口以官方说明为准。

Q2：它是收费的吗？ 技能本身的定价与获取方式取决于你使用的技能平台，本文不掌握其价格信息，请以官方说明为准。需要提醒的是，运行时它会读取文件、执行渲染命令并可能派发子任务，这部分消耗与你所用模型/平台的计费规则相关。

Q3：没有 Beamer 版本，纯 Quarto 项目能用吗？ 不太适合。该技能的设计前提是「Beamer PDF 是黄金标准」，所有硬门都是相对于 Beamer 基准来判定的。若项目从一开始就只有 Quarto，缺少对照基准，审计将失去判定依据，此时应改用常规的排版检查或视觉回归方案。

Q4：最多 5 轮是什么意思？5 轮还没修好怎么办？ 指修复循环最多进行 5 轮，避免无限打磨。达到上限后，技能会把剩余未解决的问题整理上报给用户，由你决定是接受现状、人工处理还是调整基准后重跑。

Q5：它和通用的代码审查 AI 助手怎么选？ 如果你的任务只是零星改几个文件，通用助手更轻便；如果你要保证一整讲幻灯片在内容、公式、图表、排版上全面不弱于既有 Beamer 版本，并且需要留下质检记录，qa-quarto 的硬门与对抗循环才是有意义的投入。