Operit PR Check Android 构建与单测拆分:验证流程与 fork 测试实战

原创2026-09-27 20:59:281,833 阅读
文章标签:人工智能AI AgentAI 应用移动开发工具调用GUI 自动化本地部署插件系统Agent 工作流

Operit PR Check Android 构建与单测拆分:验证流程与 fork 测试实战

本文以 Operit 仓库中 pr_check_android_build_split_20260815 改造的验证记录为骨架,完整还原「Android build 与 Android JVM tests 独立 job」改造从静态检查、fork 线上验证到问题修复的完整闭环。读者将掌握如何为拆分后的 CI 设计可复现的验证矩阵、如何用 fork PR 观察 job 独立性,以及如何定位并修复拆分后暴露的既有测试源码问题。

一、背景:为什么要把构建与单测拆成两个 job

在拆分之前,PR Check 的 Candidate checks 单个 job 同时承担作用域规划、快速检查、JavaScript 专项检查、Android 资源编译、依赖准备和完整 Android Gradle 检查;完整 Android lane 在同一个 job 中依次执行 assembleDebug 和 :app:testDebugUnitTest。Android Build workflow 也在编译后继续执行 JVM 单测。

这带来三个直接问题:

  • 共享失败边界:单测失败会连带判定构建失败,APK 编译结果无法独立呈现;
  • 共享 runner 时间:测试与构建串行排队,拉长整个 CI 反馈周期;
  • 共享产物上传条件:构建产物(APK/AAB)的上传被测试结果牵连。

改造目标(详见 1_JobBoundaries.md 与 index.md)是把职责拆开:

  • Fast checks 只负责规划、快速门禁、资源 lane、WebChat 与 ToolPkg 专项检查;
  • Android build 仅在 android_full 作用域下运行 assembleDebug;
  • Android JVM tests 在 android_jvm 或 android_full 作用域下运行 JVM 单测;
  • 两个 Android job 基于同一个 merge candidate,但各自拥有干净 workspace;
  • 新增 job 的结果由最终的 Candidate checks 聚合。

同时保留约束:仅有快速门禁的 PR 不能因不存在 Android job 而失败;Android build 必须自行生成 WebChat 和 ToolPkg 的 Gradle 输入;JVM test job 必须自行准备 Gradle 依赖和 native ripgrep;不在 job 之间传递未审计的 workspace,只复用既有缓存和 candidate checkout。

拆分完成后,3_Verification.md 记录了这套改造的验证设计、执行过程与问题修复,正是本文的主体。

二、静态验证:先在本地把规则钉死

任何线上验证之前,先做不依赖 runner 的静态验证,确保 workflow 语法、门禁逻辑和聚合语义本身正确。

2.1 检查 workflow YAML 与 actionlint

第一步是对 .github/workflows/ 下的 YAML 做双重校验:

  • YAML 语法:用 Ruby Psych 的 Psych.parse_file 做 AST 级解析(而非直接加载成 Ruby 对象),确认语法合法;
  • actionlint:对变更的 workflow 文件运行 actionlint(仓库使用 v1.7.12,并先通过 sha256 校验下载归档再解压执行),检查 on、jobs、needs、if 条件等结构的正确性。

这一步骤的实际命令实现可在 pr-check.yml 的 Check changed YAML and Actions workflows step 中查看:它先 git diff --name-only 收集 base..candidate 之间变更的 *.yml/*.yaml 文件,再按路径筛选出 .github/workflows/*.yml 交给 actionlint。

2.2 运行 CI Python 单元测试

门禁逻辑本身是用标准库 unittest 写的,命令为:

python3 -B -m unittest discover -s ci/test -p 'test_*.py'

仓库 ci/test/ 下共有 6 个测试文件,实测合计 46 个 test_* 用例,与验证记录中「46 个 CI 门禁单元测试」一致:

测试文件 用例数 覆盖对象
test_pr_check.py 13 candidate 契约、scope 分类
test_localizations.py 11 本地化检查器
test_android_dependencies.py 10 Android 依赖下载/准备
test_markdown_links.py 7 Markdown 链接检查
test_toolpkg_sync.py 4 ToolPkg 示例同步
test_repo_hygiene.py 1 仓库卫生检查

这些用例由 pr-check.yml 的 Check gate implementation step 执行(continue-on-error: true,收集诊断后由后续 step 统一裁决)。

2.3 检查 scope 分类、job 条件与聚合逻辑

这是静态验证中最关键的一环:确认改动路径被分到正确的 lane。分类实现集中在 ci/script/pr_check.py:

  • ANDROID_FULL_PATTERNS 定义哪些路径会触发完整 Android lane(如 cmake/**、gradle.properties、tools/native_ripgrep/**、.github/workflows/android-*.yml 等);
  • ANDROID_MODULE_ROOTS 列出独立原生模块根(avator/dragonbones、avator/fbx、avator/mmd、llm/llama、llm/mnn、quickjs、showerclient、terminal),命中任一即 android_full;
  • 对 app/ 下的普通改动,除翻译资源外默认归入 android_jvm;纯翻译资源(values-*/strings.xml、locales_config.xml)走资源 lane(android_resources,只用 aapt2 compile 校验资源语法,不触发完整构建);
  • android_instrumentation 在命中 app/src/androidTest/ 时置真,测试 job 会额外编译 AndroidTest 源码。

从源码结构可以推断,scope 判定顺序是「先 full、再资源、再 jvm」:android_jvm = android_jvm_change and not android_full,android_resources = resource_change and not android_jvm and not android_full(见 pr_check.py)。

对应的 job 条件写在各 workflow 中:

  • Android build 只当 needs.fast.result == 'success' && needs.fast.outputs.android_full == 'true' 时运行(pr-check.yml);
  • Android JVM tests 当 android_jvm == 'true' || android_full == 'true' 时运行(pr-check.yml);
  • Candidate checks 聚合三个 job,用同一套 check_stage 函数按 Required 列决定是否阻断,并在 step summary 输出表格(pr-check.yml)。

值得注意的边界用例在 test_pr_check.py 中有明确覆盖:

  • 纯翻译改动只走资源 lane,不触发 JVM/完整 lane(test_translation_only_uses_resource_lane);
  • 默认 values/strings.xml 走 JVM lane(test_default_strings_use_jvm_lane);
  • CMake 或 Android workflow 改动走 full lane(test_native_change_uses_full_lane、test_android_workflow_changes_use_full_lane);
  • AndroidTest 源码同时触发 JVM 与 instrumentation 编译(test_android_test_source_uses_instrumentation_compile);
  • candidate 必须恰好有两个父提交且与事件中的 base/head 一致,否则拒绝(test_stale_branch_uses_candidate_first_parent_diff、test_non_merge_candidate_is_rejected)。

三、线上验证:用 fork 分支观察 job 独立性

静态验证通过后,进入线上验证。由于不能直接在 upstream 仓库提交,验证流程采用 fork 隔离:

  1. 把改动推送到 fork 的 ci/split-android-pr-check 分支;
  2. 在 fork 中创建指向 fork main 的测试 PR;
  3. 观察 Android build 与 Android JVM tests 两个 job 是否各自独立启动、独立呈现结果;
  4. 人为构造「构建失败但单测通过」「单测失败但构建通过」两种场景,确认一方失败时另一方仍保留自己的结果;
  5. 确认无 Android 改动的 PR 不会被错误阻断(即不触发 Android job 的 PR 必须正常通过);
  6. 全部通过后再由用户决定是否提交 upstream。

这套流程的意义在于:fork PR 触发的是与 upstream 完全相同的 Actions 流水线,但不会污染正式仓库的合并历史与门禁状态。ci/README.md 的「PR check lanes」一节也说明了同样的安全边界——PR workflow 只有 contents: read 权限,不读取仓库 secret,也不上传 APK/AAB,因此可以在 fork 环境安全复现。

3.1 fork 验证中需要盯住的观察点

根据 pr-check.yml 的实际结构,验证时应重点确认:

  • needs.fast 是否只被 fast job 触发,两个 Android job 之间没有 needs 依赖(并行关系);
  • Android build job 是否包含 test step(拆分后已删除 JVM test 输入和 test step,只保留依赖、assets 生成、Gradle build 和产物上传);
  • Android JVM tests job 是否运行 :app:testDebugUnitTest,并在 android_instrumentation 时追加 :app:compileDebugAndroidTestKotlin 与 :app:compileDebugAndroidTestJavaWithJavac(pr-check.yml);
  • Android build 是否自行完成 WebChat assets 构建(npm run build:webchat)与 ToolPkg 示例同步(sync_example_packages.py --no-hot-reload),即「必须自行生成 Gradle 输入」的约束是否落实(pr-check.yml)。

四、验证结果:两轮 fork PR 与问题修复

4.1 Fork PR #15:验证 job 独立性并暴露既有测试缺陷

第一轮验证(Fork PR #15)得到以下结果:

  • Fast checks 通过:包含 46 个 CI 门禁单元测试和 actionlint 检查;
  • Android build job 通过:assembleDebug 完成,构建报告生成;
  • Android JVM tests job 独立启动,并执行到 Gradle 测试编译阶段;
  • Candidate checks 正确记录 Android build=success、Android JVM tests=failure——这正是拆分想要的效果:单测失败不再拖垮构建判定。

拆分同时也放大了此前被「同 job 顺序执行」掩盖的问题:首轮 JVM 测试暴露了 upstream 既有的测试源码错误,包括:

  • ProviderUsageCancellationTest.kt(provider 取消传播测试);
  • RecordingSQLiteDriver.kt(SQLite 记录驱动测试夹具);
  • TokenCanonicalTotalsTest.kt 与 TokenCostCalculatorTest.kt(token 统计相关测试)。

修复方式为:补齐导入和参数、删除过期测试夹具,并修正日志与 Gemini usage 测试夹具。其中 TokenCostCalculatorTest.kt 目前仍存于 app/src/test/java/com/ai/assistance/operit/data/stats/TokenCostCalculatorTest.kt,可继续作为理解 token 统计逻辑的测试入口;RecordingSQLiteDriver.kt 与 TokenCanonicalTotalsTest.kt 因属过期夹具/过期用例已被删除,故当前仓库中不再存在。

4.2 run 31835091374:只剩 cancellation 身份断言问题

修复后重新运行(run 31835091374),Android build 通过,JVM 测试仅剩 ProviderUsageCancellationTest.kt 中 3 个跨 IO dispatcher 的 cancellation 对象身份断言。

问题本质:provider 的 sendMessage 会通过其内部 IO context 派发,协程取消时抛出的 CancellationException 实例可能被重新创建,因此断言「抛出的异常对象与原异常是同一个对象(object identity)」是不可靠的——对象身份并非 provider 接口契约。

修复方式:改为验证取消消息语义,即只断言 expected.message 与捕获到的异常消息一致。当前实现可在 ProviderUsageCancellationTest.kt 中看到:

val expected = CancellationException("usage observer cancelled")
// ...
try {
    response.collect { }
    fail("usage callback cancellation must propagate")
} catch (actual: CancellationException) {
    // Dispatching through the provider's IO context may recreate the cancellation instance;
    // the callback contract is cancellation propagation, not object identity.
    assertEquals(expected.message, actual.message)
}

这段注释(the callback contract is cancellation propagation, not object identity)正是对本次修复原则的源码级记录:契约是取消必须传播,而不是协程实例必须原样抵达。

4.3 Fork PR #14(run 31839888120):全绿

第二轮验证(Fork PR #14,run 31839888120)全部通过:Fast checks、Android JVM tests、Android build、Candidate checks 均为 success。同时,可信的 Android Build 手动运行也通过,并上传了 Android 报告和成功产物。

4.4 可信 workflow 的纯构建化验证

除了 PR workflow,改造还涉及两条可信 workflow:

  • android-build.yml:push 到 main 或 workflow_dispatch 触发,只做「准备打包输入 → 执行 Gradle 构建 → 上传报告与产物」,不再包含 JVM 单测;支持 assembleDebug、:app:assembleNightly、:app:assembleClone、:app:bundleRelease 四种可选任务;
  • android-tests.yml:push 到 main 或 workflow_dispatch 触发,只运行 :app:testDebugUnitTest 并上传测试报告,不生成 APK/AAB。

两条 workflow 都复用「terminal 子模块初始化 → JDK/SDK/NDK → 依赖缓存恢复 → native ripgrep 编译 → local.properties 配置」这套准备步骤,与 PR workflow 中的对应 step 保持一致,保证可信构建与 PR 构建行为等价。

五、验证结论与交付判定

综合静态与线上验证,可以确认以下事实:

  1. Android 编译已在单测失败时独立完成——run 31835091374 中 Android build 通过而 JVM 测试仅剩 cancellation 断言问题时即为证据;
  2. JVM 测试与 Candidate checks 聚合状态已通过最新 run 验证——run 31839888120 四项全绿;
  3. 拆分后的 scope 分类与 job 条件有单元测试钉底——46 个门禁用例覆盖 candidate 契约与全部 lane 边界;
  4. fork 安全边界保留——PR workflow 无 secret、无 APK 上传,可信构建只在 main push / 手动触发时产出产物。

验证通过后,这套拆分方案才被允许提交 upstream。对任何想要复刻此改造的团队,可参照 1_JobBoundaries.md(边界契约)、2_WorkflowImplementation.md(实现要点)与本文(验证闭环)三份文档组合使用;本地提交前也可按 ci/README.md 的「Local checks」一节先跑一遍门禁单元测试与各检查器,把大部分问题拦截在推送之前。

登录后查看全文
Operit