SkiaSharp C 伴生 PR 审查指南:从 diff 到 companionPr 报告的可执行清单
SkiaSharp C# 伴生 PR 审查指南:从 diff 到 companionPr 报告的可执行清单
导读
SkiaSharp 每次升级 Skia 上游(mono/skia 子模块 bump)都会同时产生一个 C# 伴生 PR(companion PR),其中包含重新生成的 P/Invoke 绑定与手写包装器(wrapper)的增删改。本文基于仓库中 csharp-review.md 定义的审查规范,系统讲解在 review-skia-update 流水线中如何对伴生 PR 逐文件撰写摘要、按五类检查清单审查 diff、并通过 relatedFiles 建立与 C 层 interop 的交叉引用,最终产出符合 skia-review-schema.json 的 companionPr JSON 报告。读完本文,你将掌握 SkiaSharp 包装器的 null 处理、释放模式、ABI 兼容、重载约定与测试覆盖等核心审查要点,并能在实际评审 Skia 升级 PR 时直接套用。
一、伴生 PR 审查在整体流水线中的位置
review-skia-update 技能将一次 Skia 升级拆成四个阶段(见 SKILL.md):
- 运行编排器:
python3 .agents/skills/review-skia-update/scripts/run_review.py --skia-pr {skia_pr_number} --skiasharp-pr {skiasharp_pr_number} --milestone {milestone_number},三个参数缺一不可,其中 milestone 从 PR 标题/正文/分支名提取(如 "Bump skia to milestone 147" 中的 147),编排器会与cgmanifest.json交叉校验;执行后工作树被检出到 PR 状态,便于直接浏览文件。 - 撰写摘要并组装报告:加载编排器产出的
raw-results.json,对 upstream/interop/DEPS/companion 四个 section 的每一项写事实性 summary(详细规则见 writing-summaries.md)。 - 审查 C# 伴生 PR:即本文主题,对应参考文档 csharp-review.md。
- 校验并持久化:
validate-skia-review.py校验通过(Exit 0)后由persist-skia-review.py复制到output/ai/并生成可附到 PR 的自包含 HTML 报告。
编排器在阶段 1 已通过 check_companion.py 机械地完成了伴生 PR 的文件分类与 diff 提取——它会计算 PR base 与 head 的 merge-base,用 git diff --name-status 解析新增(A)、修改(M)、重命名(R)、复制(C)记录,并把 per-file diff 落盘到 companion-pr/ 目录。审查者的职责不是重新跑 diff,而是在此基础上做三件事:
- 为每个文件条目补充
summary(与 upstream/interop 摘要同风格); - 按下方清单审查 diff 的正确性;
- 在适用处为条目添加指向 interop 文件的
relatedFiles交叉链接。
二、先划清边界:明确“忽略清单”
文档开篇就强调,不是所有 diff 都值得人工逐行看。以下三类变更应直接跳过,避免把审查精力浪费在噪音上:
| 忽略类型 | 说明 |
|---|---|
生成器自有的声明与 interop 变更(*.generated.cs) |
除非 diff 修改了受版本控制的 /// 文档注释 trivia——check_companion.py 会单独把这些注释变更保留下来供审查 |
| 纯空白变更(whitespace-only) | 不值得审查 |
| 纯注释变更(comment-only) | 除非注释记录了行为变更 |
这一“跳过”逻辑在脚本层有明确实现:check_companion.py 的 SKIP_PATTERNS = <a href="https://link.gitcode.com/i/89994059e69453209165b0a7b28de832" target="_blank">"*.generated.cs"] 直接命中生成文件;has_generated_documentation_changes()([L47-L52)逐行检查 diff 中是否有 +/- 开头且内容以 /// 开头的文档注释行——有则保留给人工,无则计入 unchanged 计数并跳过。配套单测 check_companion_test.py 用 M/A/R100/C100 四种状态分别验证“带文档注释的生成文件必须被纳入审查”和“无文档注释的纯生成代码变更必须被跳过”两条规则。
仓库内 binding/SkiaSharp/Generated/ 与 binding/HarfBuzzSharp/Generated/ 下的 240+ 个 *.generated.cs 文件即属于此类:它们的声明与 interop 代码由生成器全量重写,人工审查价值集中在手写的 binding/SkiaSharp/*.cs 包装层。
三、审查清单核心一:新增或变更的 C# 包装器
审查范围是 binding/SkiaSharp/(排除生成文件)下手写包装器的正确性,重点检查四个方面。
3.1 Null 处理:工厂方法返回 null,构造函数抛异常
SkiaSharp 的包装约定是:工厂方法(factory)在原生调用失败时返回 null,而构造函数则抛出异常。审查时要确认新代码没有在这两种语义之间混淆——例如一个本应“失败返回 null”的静态工厂却被写成了抛异常,会破坏调用方的 null 检查契约。
3.2 参数校验:P/Invoke 调用前先抛 ArgumentNullException
在进入 P/Invoke 之前必须完成参数校验。仓库中有大量现成范本,例如 SKImage.cs 的 FromEncodedData(SKData, SKRectI) 与 FromEncodedData(SKData) 都以 if (data == null) throw new ArgumentNullException (nameof (data)); 开头,之后才触碰 data.Handle 发起原生调用。这一顺序保证了托管层参数错误不会以难以诊断的原生层崩溃形式暴露。
3.3 释放模式:GetObject() 与 owns 参数
每个包装类型内部都有 internal static GetObject (IntPtr handle, ...) 工厂,负责把原生句柄包装成托管对象并登记到全局 HandleDictionary.cs。审查要点是区分两种所有权:
- 自有对象(owned):包装器通过
GetObject(...)默认参数owns: true接管句柄,Dispose时会释放原生对象; - 借用对象(borrowed):必须显式传
owns: false,例如 SKCanvas.cs 中sk_get_surface(Handle)/sk_get_recording_context(Handle)返回的是 Skia 内部持有的对象,包装时必须SKSurface.GetObject (SkiaApi.sk_get_surface (Handle), owns: false, unrefExisting: false),否则会重复释放导致崩溃。
owns: false 的典型场景是 Skia 返回的“不朽单例”(immortal singleton):SKColorFilter.cs 的注释明确说明 srgb↔linear gamma 单例以 owns: false 包装,因为 Skia 返回的是永不销毁的对象;SKBlender.cs、SKData.cs、SKTypeface.cs、SKColorSpace.cs 中的缓存单例同样如此——owns: false 会让 Dispose(bool) 跳过 DisposeNative(它由 OwnsHandle 门控),从而不释放 Skia 持有的对象。
3.4 同实例返回(same-instance returns):必须使用的释放模式
部分方法(如 Subset()、ToRasterImage())的语义是“可能返回 this 本身”——当结果就是源对象时,调用方绝不能顺手释放它。文档给出了强制模式:
// ✅ Required pattern for same-instance returns
var result = source.Subset(bounds);
if (result != source)
source.Dispose();
仓库中的真实实现与测试完整印证了这一规则:
- SKImage.Subset(SKRectI) 调用
sk_image_make_subset_raster后经GetObject包装返回,其文档注释写明“The underlying implementation may share the pixels, or it may make a copy”——即可能返回新图,也可能直接返回原图; - SKImage.ToRasterImage(bool) 的注释更直白:“If the image is already raster-backed, it may return the same image”;
- 最经典的落地案例是 SKImage.FromEncodedData(SKData, SKRectI):它先解出整幅中间图
image,再image.Subset(subset),随后if (result != image) image.Dispose();——只有确实分配了新图时才释放中间对象; - 回归测试 Pr3997ResourceLeakTest.cs 专门锁定这一行为:
FromEncodedDataWithSubsetDoesNotLeakIntermediateImage在不触发 GC 的情况下对比HandleDictionary中存活的SKImage数量,修复前中间图泄漏导致 delta 为 2,修复后仅剩返回图、delta 精确为 1;FromEncodedDataWithFullBoundsSubsetReturnsFullImage则验证“全尺寸子集返回同一实例”分支不误释放源图。
因此审查新包装器时,只要看到“可能返回自身”语义的方法,就要核对是否遵循了上述 if (result != source) source.Dispose(); 模式,缺了它就会复现 PR #3997 式的资源泄漏。
四、审查清单核心二:ABI 兼容性
SkiaSharp 对外维持稳定的 ABI,任何破坏性变更都是红灯。审查时重点标记:
- 修改既有方法签名(参数、返回类型变化);
- 删除公共 API——正确做法是标记
[Obsolete]而非移除; - 在公共 API 中使用默认参数——正确做法是用重载(overload)表达可选性。
仓库内 <a href="https://link.gitcode.com/i/325091e403d4315eed21c4db8d09d6d5" target="_blank">Obsolete] 的用法可以佐证“不删除、只标记”的约定:[SKImage.cs 中 ScalePixels(SKPixmap dst, SKImageCachingHint) 等旧签名被标记为 <a href="https://link.gitcode.com/i/0a38bfe529e0a1765de15e68cb6066f4" target="_blank">Obsolete("Use ScalePixels(SKPixmap dst, SKSamplingOptions sampling) instead.", error: true)],error: true 表示编译期即阻断旧调用,但 API 本身依然保留,ABI 不被破坏;[L923/L944 的 ToShader(...) 旧重载同理。
五、审查清单核心三:新增 API 重载
新增重载是安全且被预期的,但要验证三点:
- 委托给既有方法,而不是复制实现逻辑(duplicate logic)——例如
ToRasterImage()无参版本就只是ToRasterImage(false)的薄封装(SKImage.cs); - 参数命名遵循既有约定(
camelCase); - 新类型/枚举使用
SK前缀。
若发现新重载内部重新实现了一遍原生调用而没有复用旧方法,通常意味着未来维护会出现双份逻辑漂移,应要求收敛为委托式实现。
六、审查清单核心四:平台特定变更
Skia 升级经常改变平台行为,尤其是以下三类:
- 字体管理器变更(平台相关的单例)——对应
SKFontManager及其平台实现,font manager 常以平台单例形式暴露,改动会影响各 OS 的字体回退链; - GPU 上下文工厂变更(命名空间迁移、新参数)——
GRContext、GRRecordingContext、GRGlInterface等 GPU 入口的签名变动需要跨平台核对; - 构建配置变更(
*.targets、*.props)——仓库中binding/IncludeNativeAssets.*.targets、各SkiaSharp.NativeAssets.*/buildTransitive/*.targets以及source/SkiaSharp.Build.props/SkiaSharp.Build.targets都在此列,改动会影响原生资产(native assets)的传递引用与平台条件。
七、审查清单核心五:测试覆盖
检查 tests/Tests/(对应测试工程 SkiaSharp.Tests)需确认:
- 新 API 有新测试:如 SKImageTest.cs 的
ToRasterImageReturnsSameRaster验证光栅图ToRasterImage()返回同一实例(Assert.Equal(image, image.ToRasterImage())),正是对“同实例返回”语义的测试锚点; - 变更行为有更新测试:如
Pr3997ResourceLeakTest对FromEncodedData(data, subset)的重构同时锁定了行为一致性与泄漏修复; - 不得新增跳过(skip)的测试。
关于第三条,仓库有严格的 GPU 测试策略作为依据(gpu-test-policy.md):只要宿主平台在 GpuPolicy.RequiredOn 名单中声明了某后端(如 ganesh-gl 之于 Windows/macOS/Linux/Nano Server,ganesh-metal/graphite-metal 之于 Apple,ganesh-vulkan 之于 Windows/Linux/Android),该后端就是必需的——没有设备、驱动、ICD、空 context 或绑定损坏都属于测试失败,而不是跳过的理由。只有两种情形允许跳过:当前平台不在该后端的 RequiredOn 集合中,或通过 SKIASHARP_TEST_SKIP_GPU 环境变量对某个 agent 显式豁免(如 SKIASHARP_TEST_SKIP_GPU=ganesh-gl,graphite-dawn 或 all)。因此审查时要标记任何“新增或扩大 skip 而非修复环境/后端”的 PR——正确的修法是补上测试宿主能力,而不是用 skip 掩盖 bring-up 失败。
八、输出格式:构建 companionPr JSON 段
审查结论以 JSON 形式写入最终报告,与 upstream/interop 段共用同一 sourceFile 结构。文档给出的完整模板如下(可直接套用):
{
"companionPr": {
"prNumber": 3560,
"status": "REVIEW_REQUIRED",
"summary": "Brief overview of C# changes...",
"recommendations": ["Action item 1", "..."],
"added": [
{
"path": "binding/SkiaSharp/SKFoo.cs",
"summary": "New wrapper for sk_foo_bar API — creates SKFoo with factory method",
"diff": "--- a/dev/null\n+++ b/binding/SkiaSharp/SKFoo.cs\n...",
"relatedFiles": [
{ "path": "src/c/sk_foo.cpp", "relationship": "C API implementation" }
]
}
],
"changed": [
{
"path": "binding/SkiaSharp/SKSurface.cs",
"summary": "New DrawSurface overload with SKSamplingOptions parameter",
"diff": "...",
"oldDiff": "...",
"newDiff": "...",
"patchDiff": "..."
}
],
"unchanged": 4
}
}
字段含义与分类规则:
added——新增的 C# 文件(新包装器、新测试文件);changed——被修改的 C# 文件(更新的包装器、新重载、签名变更);其中oldDiff/newDiff/patchDiff分别承载旧补丁、新补丁与两者的差异,供查看器以 Direct/Patch/Old/New 四种视角渲染(见 writing-summaries.md);unchanged——经审查无需关注的已审文件计数(被跳过的生成文件计入此处)。
注意 schema 约束(skia-review-schema.json):companionPr 必填 prNumber、status、summary、recommendations、unchanged;每个文件条目必填 path 与 summary,且 additionalProperties: false——任何多余字段都会导致校验失败。status 只能取 PASS 或 REVIEW_REQUIRED,必须沿用 raw results 中的原始值,不要自行改写。diff 等字段必须内嵌真实 diff 文本而非文件路径引用,保证 JSON 自包含、可直接被 dashboard 渲染。
九、用 relatedFiles 建立 C# ↔ interop 交叉链接
relatedFiles 的价值在于让审查者能在 HTML 查看器中一键跳转上下游文件,例如把 C# 包装器链到其 C API 实现。常用关系词:
- 被移除的上游补丁 → 新的 interop 文件:被移除项用
"replaced by",新增项用"replaces"; - 头文件 + 实现文件配对:用
"header"/"implementation"; - interop 文件 → 伴生 PR 的 C# 包装器:关系写
"C# wrapper"。
典型示例:binding/SkiaSharp/SKImage.cs 的 Subset 重载可以 relatedFiles 到 sk_image_make_subset_raster 对应的 C 层实现;新包装器 SKFoo.cs 链到 src/c/sk_foo.cpp(关系 "C API implementation")。
十、与其他阶段衔接:校验与持久化
伴生 PR 审查不是终点。组装完整个报告后必须经过校验门槛:
python3 .agents/skills/review-skia-update/scripts/validate-skia-review.py {output_dir}/{pr_number}.json
- Exit 0 = ✅ 有效,可进入持久化;
- Exit 1 = ❌ 按输出修复后重跑(最多 3 次);
- Exit 2 = 致命错误,停止并上报。
校验通过后再执行 persist-skia-review.py 把 JSON 复制到 output/ai/repos/mono-skia/ai-review/ 并生成自包含 HTML(Bootstrap 5 + diff2html),最后以固定模板向用户汇报四段状态与整体风险等级(generatedFiles/upstreamIntegrity 为 REVIEW_REQUIRED 或 FAIL 时风险为 HIGH,interopIntegrity/depsAudit 为 REVIEW_REQUIRED 时 MEDIUM,全部 PASS 为 LOW,取最高者)。
结语
一次 Skia 升级的 C# 伴生 PR 审查可以浓缩为一句流程:跳过生成文件与纯格式变更 → 按“null 处理 / 参数校验 / 释放模式 / 同实例返回”审查新包装器 → 守住 ABI(不删 API、不签默认参数)→ 确认重载是委托而非复制 → 核对平台相关改动 → 用测试覆盖兜底(尤其不得新增 skip)→ 输出 schema 合规的 companionPr JSON 并交叉链接 interop。这套清单把 10 万~50 万行的升级 diff 收敛成可聚焦、可引用、可审计的评审产物,正是 SkiaSharp 维护者面对高频 Skia 里程碑 bump 时保持质量的核心手段。