Remotion WebCodecs Bug 追踪工作流：基于 add-webcodecs-bug 技能维护 Mediabunny 浏览器缺陷档案

本文讲解 Remotion 仓库中 add-webcodecs-bug 这个 Agent 技能的完整工作流：如何从 Chromium、WebKit、Firefox 三大浏览器缺陷追踪系统获取 issue 信息，按统一字段规范登记到 packages/docs/docs/mediabunny/webcodecs-bugs.mdx 缺陷跟踪表中，并理解其背后的产品背景、字段映射规则与校验方法。

背景：为什么 Remotion 要维护一个 WebCodecs 缺陷清单

要理解这个技能的价值，先要理解它服务的对象。WebCodecs 是浏览器提供的底层音视频编解码 API（VideoEncoder、VideoDecoder、AudioEncoder、AudioDecoder、VideoFrame 等），Remotion 的浏览器端渲染与转码能力（如 @remotion/webcodecs 及后续方案）直接构建在这些 API 之上，因此浏览器的 WebCodecs 缺陷会直接表现为渲染错误、编码失败或性能退化。

从 Mediabunny 文档入口 可以看到，Remotion 与独立多媒体库 Mediabunny（作者 Vanilagy）已合并研发力量，并计划逐步用 Mediabunny 替代 @remotion/media-parser 与 @remotion/webcodecs。Mediabunny 底层同样依赖浏览器 WebCodecs，因此“哪些浏览器 WebCodecs 缺陷已被上报、修复到什么程度”对选型与排障具有直接参考价值。

webcodecs-bugs 页面正是为此设立的官方追踪页，其文档定位可以从三处仓库文件交叉印证：

• webcodecs-bugs.mdx 的 frontmatter 中 crumb: 'Issue Tracker'、sidebar_label: WebCodecs Bugs，正文开头即声明：“This page is a list of known WebCodecs issues in browsers that our community has filed. It serves as a tracker for overall progress and known issues.”
• sidebars.ts 将其排入 mediabunny 文档栏目的侧边导航；
• articles.ts 将其注册为站点文章条目，relativePath 指向该 mdx 文件。

缺陷档案的录入不是随意的手动操作，而是由 SKILL.md 定义的标准化技能流程驱动：当维护者给出一个 Chromium、WebKit 或 Firefox 的 issue 链接并要求登记时，Agent 按照该技能逐条核实标题、上报日期、上报人与解决状态，再向表格追加一行。

目标文档的表格结构

技能的第一步要求 Agent 先读取 webcodecs-bugs.mdx “理解当前表格格式”。该文件的实际结构为：

---
image: /generated/articles-docs-mediabunny-webcodecs-bugs.png
title: WebCodecs Bugs
crumb: 'Issue Tracker'
sidebar_label: WebCodecs Bugs
---

This page is a list of known WebCodecs issues in browsers that our community has filed.
It serves as a tracker for overall progress and known issues.

| Issue | Product | Filed by | Status |
| ----- | ------- | -------- | ------ |
| ...   | ...     | ...      | ...    |

关键结构特征（对应 表格头两行）：

1. 固定四列：Issue、Product、Filed by、Status。
2. Issue 列是链接：单元格文本为 issue 的完整标题，链接指向上游追踪系统页面——Chrome 缺陷指向 Chromium issue tracker（issues.chromium.org 域），Safari 缺陷指向 WebKit Bugzilla（bugs.webkit.org 域），Firefox 缺陷指向 Mozilla Bugzilla（bugzilla.mozilla.org 域）。
3. Product 列只取三个值：Chrome、Safari、Firefox。
4. Filed by 列：社区成员的 GitHub 风格句柄（如 @Vanilagy、@JonnyBurger）或具名个人（如表尾的 Jozef Chúťka）。
5. Status 列：取 Open、Fixed、Won't fix 等值。

从当前 表格数据行 可以统计出：档案已收录 28 条缺陷，其中 Chrome 15 条、Safari 5 条、Firefox 1 条（含 WebKit 追踪系统中的 Safari 相关缺陷），状态以 Fixed 和 Open 为主，另有一条 Won't fix。缺陷主题高度聚焦 WebCodecs 的核心痛点：关键帧检测过严（如非 IDR AVC 关键帧被拒）、encodeQueueSize 行为不可预测、高刷新率显示器上 VideoDecoder 被限流、visibleRect 裁剪错误、色彩空间（colorSpace）被硬件解码路径忽略、AudioData.copyTo() 崩溃等。这类清单本身就是给下游开发者“先查已知缺陷、再怀疑自己代码”的排障索引。

add-webcodecs-bug 的五步工作流

SKILL.md 的 frontmatter 定义了技能名（name: add-webcodecs-bug）与触发条件：当用户给出一个应登记到 webcodecs-bugs.mdx 的 Chromium / WebKit / Firefox issue URL 时使用，且强调编辑 MDX 表格前必须先行查清 issue 标题、上报日期、上报人与解决状态。正文 Workflow 共五步：

第 1 步：读取目标文件，理解现有格式。 Agent 必须先打开 packages/docs/docs/mediabunny/webcodecs-bugs.mdx，确认表格的列顺序、列名与措辞。这是为了保证新增行与既有行格式完全一致——技能后文“Preserve the existing table columns and wording”（保留既有表格列与措辞）的规则以这一步的观察结果为准。

第 2 步：打开 issue URL 核实信息。 技能指定使用 browser:control-in-app-browser 技能打开提供的链接。这一步的意义在于：登记表的每一项都必须以追踪系统的实时页面为准，而不是凭用户口头描述照抄。

第 3 步：在 issue 页面核实四项关键事实。

• issue 标题（将直接作为 Issue 列的链接文本）；
• 创建/上报日期（created or filed date）；
• 上报人身份（reporter / filed-by）；
• 当前状态与解决状态（current status and resolution state）。

值得注意的是，虽然要求核实日期，但表格本身并没有日期列——这一点与后文“不要主动添加日期列”的约束相呼应。

第 4 步：把追踪系统字段映射到表格字段。 这是整个技能中最精细的一步，包含三条映射规则（详见下节）。

第 5 步：向 MDX 文件追加一行 Markdown 表格行。 只追加一行，不做任何额外整理、重排或格式美化。

三条核心映射规则

SKILL.md 第 17–21 行 定义了从“浏览器缺陷追踪系统”到“Remotion 文档表格”的字段翻译规则，这是保证档案数据一致性的关键。

规则一：追踪系统 → Product

缺陷来源	表格 Product 值
Chromium issues（issues.chromium.org）	Chrome
WebKit Bugzilla（bugs.webkit.org）	Safari
Mozilla Bugzilla（bugzilla.mozilla.org）	Firefox

这条规则隐含一个事实：WebKit 的 Bugzilla 是 Safari 上游 WebKit 引擎共用的追踪系统，因此登记时统一归入 Safari 产品名，与 现有表中 Safari 条目（全部指向 bugs.webkit.org 域链接）的实际写法一致。

规则二：已知名句柄 → Filed by

某些追踪系统（如 Chromium issue tracker）出于隐私考虑会隐去上报人邮箱，页面只暴露 dp@***@musica-viva.de 这类打码地址。技能为此维护了一张“已知上报人映射表”：

• musica-viva.de 或 dp@***@musica-viva.de → @Vanilagy

这解释了为什么当前档案中 Chrome 条目绝大多数由 @Vanilagy 上报——该映射让 Agent 在邮箱被打码时仍能正确归名，而不是留空或写成匿名。从 现有表格 看，除 Chromium 外，Firefox 与 Safari 条目由 @JonnyBurger（Remotion 作者）等社区成员上报，体现了“community has filed”这一档案定位。

规则三：解决状态 → 状态列

状态判定采用三值口径：

• Fixed / 已验证修复 → Yes 类（表中写作 Fixed）；
• Open / New / Assigned / 未解决 → No 类（表中写作 Open）；
• 明确被拒绝 / wontfix → Won't fix。

技能原文使用 Yes / No / Won't fix 的语义表述，而 现行表格 的列名是 Status、取值是 Fixed / Open / Won't fix——这正是第 1 步“先读现有格式”存在的意义：以文档现状为准，保持措辞与既有行一致。

两条硬性约束

技能在工作流之后给出了两条边界规则（第 24 行）：

1. 保留既有表格列与措辞（Preserve the existing table columns and wording）——不得借机改列名、加空格、重排列序；
2. 除非文档已有日期列，或用户明确要求，否则不得添加日期列。

第二条约束解释了为什么第 3 步要求核实“上报日期”：日期用于人工判断与交叉验证（例如区分同一缺陷的不同阶段、辅助定位回归时间线），但不落入持久化的表格结构。这类“信息核实与持久化字段分离”的设计，避免了表格在无人决策的情况下悄悄膨胀出新列。

编辑后校验

技能末尾的 Verification 小节 规定：编辑完成后检查 diff，逐字段确认新行的四要素——

• URL 是否指向正确的 issue 页面；
• Product 是否与追踪系统归属一致；
• Filed by 是否按映射规则正确归名（含打码邮箱场景）;
• 状态是否反映最新的解决状态。

四列全部核对通过才算完成。这套“先核实、后写入、再回看 diff”的闭环，本质上是把人工维护缺陷清单时最容易犯的错误（抄错链接、归错产品、状态过期）压缩到最小。

与相邻技能的对照：add-bug 与 add-webcodecs-bug

仓库中另有一个名字相近的技能 add-bug，两者职责完全不同，容易混淆，值得区分：

维度	add-bug	add-webcodecs-bug
维护对象	packages/bugs/api/[v].ts（Remotion 自身已知缺陷的 API 数据）	packages/docs/docs/mediabunny/webcodecs-bugs.mdx（浏览器 WebCodecs 缺陷档案）
缺陷归属	Remotion 框架自身	Chrome / Safari / Firefox 浏览器实现
输出格式	TypeScript 对象（title / description / link / versions），插入数组顶部	Markdown 表格行
信息来源	用户口述缺陷描述与受影响版本	必须打开上游 issue 页面核实

从 add-bug 技能正文 看，它要求描述中包含升级指引（description should tell users which version to upgrade to），而 add-webcodecs-bug 不产生任何版本信息——浏览器缺陷不在 Remotion 的修复范围内，Remotion 只能跟踪其状态。两者分别对应“向上游报障”（Mediabunny 文档的 Reporting bugs 一节说明了向 Mediabunny 或 Remotion 仓库上报的方式）与“向社区公示进度”两种诉求。

小结：可复用的缺陷登记模式

add-webcodecs-bug 技能体量虽小，却完整示范了“把外部事实源登记进仓库内文档”这一类工作流的可靠做法：

1. 先读目标文件，让格式基准来自现状而非记忆；
2. 强制回源核实标题、时间、作者、状态四要素，拒绝二手转述；
3. 显式写出字段映射表（追踪系统 → Product、打码邮箱 → 句柄、解决状态 → 状态列），把易错点固化成规则；
4. 用约束划定边界（不改列、不加日期列），防止数据文件在自动化维护中漂移；
5. 以 diff 复核收尾，四字段逐一对齐才算完成。

对于维护 webcodecs-bugs.mdx 的读者，直接查阅 档案本体 即可获取当前全部缺陷与状态；对于希望在自己项目中沉淀类似“外部 issue 追踪表”的读者，SKILL.md 的“读格式 → 回源核实 → 映射字段 → 单行追加 → diff 校验”五步骨架可以直接套用。