SkiaSharp 的 Skia 上游合并 PR 审查全流程:从 orchestrator 到可审计报告
SkiaSharp 的 Skia 上游合并 PR 审查全流程:从 orchestrator 到可审计报告
导读
本篇文章讲解 SkiaSharp 项目中 review-skia-update 技能定义的完整方法论:当 mono/skia 仓库发起一次 Skia 上游合并(milestone bump)PR 时,如何通过四个阶段的流水线,将 10 万~50 万行的巨型 diff 收敛为一份聚焦、可人工审查、schema 校验通过的结构化 JSON 报告。读完本文,你将掌握 orchestrator 的调用方式、四类机械检查(生成文件、上游完整性、interop 完整性、DEPS 审计)各自的职责、报告 JSON 的字段结构与风险评级规则,以及验证(validate)与持久化(persist)两道阶段门禁的执行细节。
背景:为什么一次 Skia 更新需要专门的审查流程
SkiaSharp 是基于 Google Skia 图形库的跨平台 2D 绘图 API(其原生依赖位于仓库的 externals/skia 子模块)。当上游 Skia 推进到新里程碑时,合并过程会产生两类必须一起审查的 PR:
- mono/skia PR:Skia 子模块的版本提升,涉及 C 头文件、DEPS 依赖描述和上游合并;
- SkiaSharp PR:配套的 C# 改动,包括重新生成的 P/Invoke 绑定和手写包装类。
两类 PR 的 diff 叠加起来动辄 10 万到 50 万行,靠人工逐行阅读既不现实也不可靠。因此仓库在 .agents/skills/review-skia-update/SKILL.md 中定义了一套"机械检查 + AI 摘要 + schema 校验 + 人工复核"的审查方法论,目标是产出可安全审计(security-auditable)的报告:由脚本完成所有机械工作,AI 只提供事实性摘要,最终所有条目仍交由人类审查。
整个流程分为四个阶段:
Phase 1: Run orchestrator → Phase 2: Write summaries & build report
Phase 3: Review C# PR → Phase 4: Validate & persist
Phase 1:运行 Orchestrator(一次性机械检查)
所有机械工作被收敛到单个脚本中:拉取 PR 元数据、检出两个 PR、独立重生成绑定、检查源码完整性、审计 DEPS、分析 companion PR 文件。
python3 .agents/skills/review-skia-update/scripts/run_review.py \
--skia-pr {skia_pr_number} \
--skiasharp-pr {skiasharp_pr_number} \
--milestone {milestone_number}
三个参数缺一不可(对应脚本 run_review.py 中的 required=True 定义):
| 参数 | 含义 | 来源 |
|---|---|---|
--skia-pr |
mono/skia 的 PR 编号 |
待审查对象 |
--skiasharp-pr |
SkiaSharp 配套 PR 编号 | 一次 Skia 更新必有配套 PR |
--milestone |
目标 Chrome 里程碑号(如 147) | 从 PR 标题/正文/分支名提取,例如 "Bump skia to milestone 147" 或 "Dev/update skia 147" |
orchestrator 会用 cgmanifest.json 和 PR 标题交叉校验里程碑一致性。从脚本实现看(run_review.py),它从 cgmanifest.json 的 registrations 中读取 skia 组件的 upstream_ref(形如 chrome/m156)、chrome_milestone 与 upstream_merge_commit,作为权威依据。当前仓库的 cgmanifest 记录为 chrome/m156。
orchestrator 内部做了什么
按脚本执行顺序,orchestrator 会依次完成:
- Pre-flight:若
externals/skia子模块尚未初始化则执行git submodule update --init;校验子模块 remote 指向mono/skia;预取pull/{skia_pr}/headref;确认两个工作树干净(dirty 直接报错中止)。 - 拉取元数据:读取两个 PR 的标题、描述、分支与 SHA。
- 独立重生成绑定:调用生成器产出
*.generated.cs,与仓库已检入的版本比对(详见下方"生成文件检查")。 - 源码完整性检查:对 upstream 层与 interop 层分别做 diff-of-diffs。
- DEPS 审计:解析 DEPS 文件中的依赖变化。
- companion PR 文件分析:对 C# PR 的增删改文件产出过滤后的 diff。
输出:输出目录中的 raw-results.json,包含上述所有检查结果、机械生成的文件列表与 diff(upstream 完整性、interop 完整性、DEPS、companion PR 文件四部分)。运行结束后工作树被检出到 PR 状态,可直接在本地浏览文件。
两条铁律
- orchestrator 失败即停止:失败时直接上报,绝不手动逐个运行子脚本;
- NO-RETRY 策略:orchestrator 恰好运行一次。若生成环节报告 FAIL,那就是最终结果,不得重跑以期获得不同结论。
生成文件检查:绝不信任已检入的 generated.cs
生成文件检查由 check_generated_files.py 完成,核心原则是"独立重生成、逐文件比对"。脚本覆盖五个绑定项目,每个项目由一份 *.json 配置驱动,生成器项目位于 utils/SkiaSharpGenerator/SkiaSharpGenerator.csproj:
| 配置 | 原生源码根 | 绑定项目 | 产物 |
|---|---|---|---|
libSkiaSharp.json |
externals/skia |
SkiaSharp |
SkiaApi.generated.cs(按头文件拆分) |
libSkiaSharp.Skottie.json |
externals/skia |
SkiaSharp.Skottie |
SkottieApi.generated.cs |
libSkiaSharp.SceneGraph.json |
externals/skia |
SkiaSharp.SceneGraph |
SceneGraphApi.generated.cs |
libSkiaSharp.Resources.json |
externals/skia |
SkiaSharp.Resources |
ResourcesApi.generated.cs |
libHarfBuzzSharp.json |
externals/skia/third_party/externals/harfbuzz |
HarfBuzzSharp |
HarfBuzzApi.generated.cs |
实际比对逻辑是:先 dotnet build 生成器,再在隔离输出目录中重生成绑定树,然后用 filecmp.dircmp 与仓库已检入的 binding/{项目}/Generated 目录逐文件比对,报告 deleted / added / modified 差异。当前仓库中可见产物形如 binding/SkiaSharp/Generated/SkiaApi_include_c_sk_bitmap_h.generated.cs、SkiaApi_include_xamarin_sk_managedstream_h.generated.cs(interop 头文件 include/c/、include/xamarin/ 均有对应生成文件)。这一节的结果状态只有 PASS 或 FAIL,FAIL 直接将整体风险推到 HIGH。
Phase 2:撰写摘要并构建报告
机械检查完成后,进入人工/AI 协作阶段。首先阅读 writing-summaries.md 获取详细指导:
- 从 orchestrator 打印的输出目录加载
raw-results.json; - 对 所有 四个 section(upstream、interop、DEPS、companion PR)中
added/removed/changed的每一项,阅读 diff 并撰写事实性摘要; - 逐条验证被移除的补丁(见下节);
- 组装符合
skia-review-schema.jsonv1.0 的最终 JSON 报告; - 报告中的
diff字段必须是真实的 diff 文本,不能只给文件路径引用——仪表盘(HTML viewer)直接渲染这些 diff; - 保存到
{output_dir}/{pr_number}.json,与raw-results.json同目录。
摘要撰写规则
- 只写事实:描述变更做了什么,不评判好坏;
- 不逐文件给 PASS/FAIL:所有条目都需要人工复核;
- 必须读真实 diff:仅凭文件名写摘要毫无价值。
各 section 的摘要各有侧重点:
- Upstream 完整性:说明文件为何被修改,常见原因包括 API 变更(函数签名、返回类型、命名空间迁移)、构建修复(GN 配置、include、平台守卫)、安全补丁(溢出修复、边界检查)、合并残留(空白、注释,无功能变化)。
- Interop 完整性:描述哪个 C API 函数/类型变了——新增函数(如
sk_surface_draw_with_sampling)、移除函数(如 typeface 工厂方法)、签名变化(增删参数、重设类型)、类型/枚举变化(新值、成员改名)。 - DEPS 审计:说明依赖是什么、改了什么——版本提升(安全修复还是功能更新?)、新增依赖(为什么加?)、URL 变化(镜像迁移还是 fork 切换?)。
验证被移除的补丁(Verifying Removed Patches)
对 upstream 完整性中每个 removed 条目,必须查明补丁被丢弃的原因,禁止凭空猜测。标准流程:
- 读
raw-results.json中的旧 fork diff,理解补丁做了什么; - 定位关键变更点(新增函数、常量修改、新增 ifdef 等);
- 在
externals/skia中用git show upstream/{new_upstream_branch}:{file_path}查看新上游版本,对超大文件用grep/head过滤,搜索旧补丁中的特定函数、常量或模式; - 在摘要中给出证据。
结论分四类:Upstream resolved(上游已解决,需给出具体行/值)、Replaced by interop(由新 interop 文件处理)、API removed upstream(被补丁的 API 在上游已不存在)、Unverified(无法确认,标记交人工复核)。changed 补丁同理:若补丁内容变化,需确认是被上游 API 变更所迫,还是 fork 的主动修改。
报告 JSON 的结构:schema-cheatsheet 详解
最终报告必须符合 skia-review-schema.json v1.0(可用 schema-cheatsheet.md 快速查阅)。顶层结构:
{
"meta": { ... },
"summary": "Executive summary of the PR review...",
"recommendations": ["Action item 1", "Action item 2"],
"generatedFiles": { "status": "...", "summary": "...", "recommendations": [...], ... },
"upstreamIntegrity": { "status": "...", "summary": "...", "recommendations": [...], ... },
"interopIntegrity": { "status": "...", "summary": "...", "recommendations": [...], ... },
"depsAudit": { "status": "...", "summary": "...", "recommendations": [...], ... },
"riskAssessment": "HIGH",
"companionPr": { "prNumber": N, "status": "...", "summary": "...", "recommendations": [...], "added": [...], "changed": [...], "unchanged": N }
}
companionPr 为必填——一次 Skia 更新必然伴随 SkiaSharp PR。meta 中 repo 恒为 mono/skia,shas.upstream 是被合并的新上游 SHA,且全报告禁止出现绝对路径(/Users/... 必须脱敏为相对路径)。
状态值与风险评级
| 字段 | 取值 |
|---|---|
generatedFiles.status |
PASS、FAIL |
upstreamIntegrity.status |
PASS、REVIEW_REQUIRED |
interopIntegrity.status |
PASS、REVIEW_REQUIRED |
depsAudit.status |
PASS、REVIEW_REQUIRED |
riskAssessment |
LOW、MEDIUM、HIGH |
源码/依赖层没有 WARN 或 FAIL——所有变化都需人工复核,故只有 PASS 与 REVIEW_REQUIRED。风险取最高者:
| 条件 | 风险 |
|---|---|
generatedFiles.status == FAIL |
HIGH |
upstreamIntegrity.status == REVIEW_REQUIRED |
HIGH |
interopIntegrity.status == REVIEW_REQUIRED |
MEDIUM |
depsAudit.status == REVIEW_REQUIRED |
MEDIUM |
| 全部 PASS | LOW |
例如 upstream 与 deps 同时 REVIEW_REQUIRED,取 HIGH。
源码完整性:diff-of-diffs 模型
upstream 与 interop 两个 section 共用同一结构(均由 check_source.py 产出)。interop 目录由脚本硬编码为 include/c/、include/xamarin/、src/c/、src/xamarin/ 四个;位于其内的文件归 interopIntegrity(Skia 更新时预期会变,仍需审查),其余归 upstreamIntegrity(变更即红旗,需格外小心)。
| 类别 | 含义 |
|---|---|
added |
新 fork 打了补丁但旧 fork 没有——新增修改 |
removed |
旧 fork 打了补丁但新 fork 没有——补丁被丢弃 |
changed |
两个 fork 都打了补丁但内容不同 |
unchanged |
完全相同的补丁被带过来的数量 |
每个条目的 diff 视图(viewer 中可切换):
diff:分支直连 diff(base→PR head),展示 fork 实际改了什么,是 HTML viewer 的默认视图;patchDiff:diff-of-diffs(旧补丁 vs 新补丁),展示 fork 相对上游的"修改"如何演变,用于理解变更原因;oldDiff/newDiff:旧/新分支分别相对上游的完整补丁。
注意:没有逐文件状态——AI 只提供事实摘要,所有条目都需人工审查。
relatedFiles 交叉链接
每个源码条目可带 relatedFiles 数组,将报告中相互关联的文件串起来(viewer 渲染为可点击的 pill,点击可滚动跳转或打开对应文件):
{
"path": "include/core/SkFontMgr.h",
"summary": "Fork patch added MakeDefault()...",
"relatedFiles": [
{ "path": "src/c/sk_default_fontmgr.cpp", "relationship": "replaced by" },
{ "path": "src/c/sk_typeface.cpp", "relationship": "consumer" }
]
}
常用 relationship 取值:replaced by、moved to、moved from、depends on、consumer、header、implementation、C# wrapper。典型场景:上游移除补丁 → 新增 interop 文件(用 replaced by/replaces 成对标注)、头文件与实现文件同时变更、interop 文件对应 companion PR 中的 C# 包装。
DEPS 审计结构
与源码完整性同为 added/removed/changed/unchanged 结构。脚本 check_deps.py 用 Python ast 解析 DEPS 文件,处理 Var() 调用、字符串拼接与注释,比较 base 与 head 的依赖。条目字段:
{ "name": "libpng", "summary": "...", "oldUrl": "...", "oldRevision": "...", "newUrl": "...", "newRevision": "..." }
Phase 3:审查配套 C# PR
orchestrator 已在 raw-results.json 的 companionPr 部分产出文件列表与 diff,本阶段补充人工导向的审查上下文(详细指南见 csharp-review.md)。由于工作树已检出到 companion PR 状态,可直接阅读文件。
忽略什么
*.generated.cs中由生成器拥有的声明与 interop 改动(脚本 check_companion.py 通过SKIP_PATTERNS跳过);但 orchestrator 报告的源码控制的///文档注释变更仍需审查;- 纯空白改动;
- 纯注释改动(除非注释记录了行为变化)。
审查什么
- 新增/修改的 C# 包装类(
binding/SkiaSharp/下非生成文件):- 空值处理:工厂方法失败返回
null,构造函数抛异常; - 参数校验:P/Invoke 调用前抛
ArgumentNullException; - 释放模式:拥有对象用
SKObject.GetObject(),借用对象用owns: false; - 同实例返回:
Subset()、ToRasterImage()这类方法可能返回this,必须遵循:// ✅ 同实例返回的必需模式 var result = source.Subset(bounds); if (result != source) source.Dispose();
- 空值处理:工厂方法失败返回
- ABI 兼容性:SkiaSharp 维持稳定 ABI。任何修改现有方法签名(参数、返回类型)、移除公共 API(应改用
[Obsolete])、在公共 API 使用默认参数(应改用重载)都必须标记。 - 新增 API 重载:新重载安全且预期存在,但需确认它们委托给既有方法(不复制逻辑)、参数名遵循
camelCase惯例、新类型/枚举带SK前缀。 - 平台相关改动:Skia 更新常改变平台行为——字体管理器(平台单例)、GPU 上下文工厂(命名空间迁移、新参数)、构建配置(
*.targets、*.props)。 - 测试覆盖:检查 tests/Tests 是否有覆盖新 API 的测试、反映行为变化的更新测试、以及不得新增跳过测试——GPU 覆盖由现有 host/platform 的
GpuPolicy定义,因缺硬件或后端 bring-up 失败而新增/扩大 skip 即视为失败。
companionPr 的输出格式与其他 section 共用 sourceFile 结构,类别含义:added(新增 C# 文件/测试)、changed(修改的包装、新重载、签名变化)、unchanged(已审查且无需关注的文件数,不含生成的)。同样要利用 relatedFiles 把 C# 包装与其 C API 实现互链(如 binding/SkiaSharp/SKFoo.cs → src/c/sk_foo.cpp,relationship 标 C API implementation)。
Phase 4:验证与持久化
1. Validate——硬性阶段门禁
未通过验证不得进入 persist,跳过验证 = 无效审查。
python3 .agents/skills/review-skia-update/scripts/validate-skia-review.py {output_dir}/{pr_number}.json
退出码语义(脚本 validate-skia-review.py 实现):
- Exit 0 = ✅ 有效 → 进入 persist;
- Exit 1 = ❌ 按输出修复错误后重跑,最多重复 3 次;
- Exit 2 = 致命错误,停止并上报。
绝不手写自己的校验逻辑,绝不假设通过——必须运行脚本。 校验器用 jsonschema(Draft 2020-12)做 schema 校验,并额外做业务规则检查:顶层 summary 至少 50 字符、recommendations 非空、五个 section 的 summary/recommendations 齐全、REVIEW_REQUIRED 的 section 至少含一个 added/removed/changed 条目、meta.skiasharpPrNumber 为整数非空、companionPr 五项必填字段齐备、schema 版本恒为 "1.0"、无绝对路径等。
2. Persist——只有看到 ✅ 才能执行
python3 .agents/skills/review-skia-update/scripts/persist-skia-review.py {output_dir}/{pr_number}.json
脚本 persist-skia-review.py 会:
- 从文件名提取 PR 编号(必须为纯数字);
- 再次内部调用验证脚本,验证未通过则中止;
- 将 JSON 复制到
output/ai/repos/mono-skia/ai-review/; - 调用 render-skia-review.py 在同一目录生成 HTML 报告。
该 HTML 是自包含文件(viewer 模板 viewer.html 内联了 Bootstrap 5 与 diff2html 的 CDN 资源),适合直接挂到 PR/issue 上或作为 gist 上传。如需单独推送到 data-cache 分支,则使用 persist-aw-data GitHub Actions 工作流。
3. 汇报总结
向用户呈现标准化的审查结论摘要:
✅ Review: ai-review/{pr_number}.json
Generated Files: PASS/FAIL
Upstream Integrity: PASS/REVIEW_REQUIRED (Na/Nr/Nc)
Interop Integrity: PASS/REVIEW_REQUIRED (Na/Nc)
DEPS Audit: PASS/REVIEW_REQUIRED (Na/Nc)
Companion PR: PASS/REVIEW_REQUIRED (Na/Nc)
Risk: HIGH/MEDIUM/LOW
汇报后询问用户是否在浏览器中打开 HTML 报告查看完整内容(diff、建议、依赖表等),如需打开可执行:
open output/ai/repos/mono-skia/ai-review/{pr_number}.html # macOS
# 或: xdg-open ... (Linux) / start ... (Windows)
七条规则:流程红线一览
- 先跑 orchestrator——不得手动逐个运行检查脚本;
- 不重试——运行一次,如实报告结果;
- 绝不信任生成文件——orchestrator 独立重生成并比对;
- 不逐文件 PASS/FAIL——AI 只提供事实摘要,所有条目需人工复核;
- JSON 中必须含真实 diff——仪表盘直接渲染;
- 先验证再持久化——必须看到
✅ valid; - 报告中无绝对路径——一律脱敏为相对路径。
仓库中的支撑实现与自测
本技能的所有机械环节都有对应脚本,并配有单元测试用于自检:check_generated_files.py、check_source.py、check_deps.py、check_companion.py 之外,还有 regenerate_bindings.py(独立重生成入口)与配套测试 check_generated_files_test.py、check_companion_test.py、run_review_test.py(见 scripts 目录)。与它配套的还有 merge-skia-update 技能(负责准备发布分支与更新提交)和 update-skia 技能(覆盖研究、分支合并、绑定与测试、发布等阶段),共同构成 Skia 版本升级的完整工具体系。
结语
review-skia-update 方法论的核心理念可以概括为三句话:机械工作交给脚本(且只跑一次)、AI 只写事实摘要(不给结论)、所有变化必须人工复核(且先验证再持久化)。它把 Skia 更新这种超大 diff 的审查从"不可能完成"变成"可审计、可追溯、可复核"的标准化流程——理解这套流程,无论是维护 SkiaSharp 还是面对其他大型上游同步场景,都能获得一套可复用的审查骨架。