Files
2026-11-16 17:26:44 -08:00

54 KiB
Raw Permalink Blame History

「验证」线

跑真机、收证据、出报告。只测试,不产生代码改动 —— 没有分支,没有 MR,终态产物是一份可交互的报告加一个证据包。

报告有四种格式:

  • 用例验证(case-run,基础格式,新建单的默认值):拿一份测试用例,在真机上逐条执行,每个检查点给一个结论,附截图和录像。用例从 Bits 测试计划拉取。
  • UI 走查(ui-audit,定制格式):同一批页面在多种语言下各截一遍,逐条记 UI 问题,并把问题标回截图上。建单时在「更多选项」里选,默认不选。
  • CI 包覆盖率验证(ci-coverage,定制格式,实验,仅管理员):从一张已经跑完的 bug / feature 单一键建。平台把它 MR 流水线打出的覆盖率插桩包装上,按这张单第一次执行验证过的路径重走,把改动代码尽量都执行到,让覆盖率记到 MR 上;报告把截图、录像和「执行到的改动代码」按时间轴对在一起。见下文「CI 包覆盖率验证」。
  • 改动验证(change-run,定制格式,2026-10-26 起暂停新建:Skill 不再引导,命令行建单 / 复验由 routes_cli.ts 的 CHANGE_RUN_OPEN 挡住,已建的照常执行。等机器数量、按需独占实例、热编译唤起就绪再打开):提交人在本地分支改完、推送后,用命令行 streamline verify(Skill)建。节点在 agent 起来之前把代码仓检出到被测提交(satellite/src/change_run.ts,提交不在远端就直接 verify_failed,提示先推送),agent 从这个提交编译出包、装上,按提交人用自己的 coding agent 写、本人确认过的用例逐条执行。报告是用例验证的骨架,报告头多「被测提交」、末尾多第 3 节「建议」。它是验证线里唯一会编译的格式,但同样不改代码、不提交 —— 想法只能写进「建议」。报告就绪后 streamline verify get 把逐条结论和建议带回提交人的会话。

后面还想放回归核验(改动前后同路径对拍)、埋点核对(操作序列 ↔ 上报事件)、竞品对照 —— 它们和 UI 走查一样,是建在「用例验证」这个基础之上的定制格式。

为什么要单独一条线

这件事在有这条线之前就已经在跑了,只是被塞进 Feature 里。e5e4c65c-23a8-4f8d-a63d-637086a22cf3(TikTok iOS 社交场景走查,61 页面 × 11 语言 / 657 张截图 / 106 条问题)跑完之后:

  • 分支 feature/social-ui-audit-report 0 commit,ImplReport 的「Remote delivery」写着 Skipped — 规约排除 MR,且没有代码改动。Feature 那一整套分支 / MR / 代码覆盖检查全是空转。
  • 真正的交付物(报告、对照图、657 张截图)只能藏在 evidence/ 里,最后靠一个手工建的飞书文档送出去。面板上看到的可读性报告,是模型把一篇 ImplReport 转述成的图文 —— 106 条问题里它只提了几条。

所以分歧不在「要不要多一个入口」,而在字段和终态语义对不上。

它是第五条 track,不是 Feature 的变体

库里是自己的一张表 verifications(见 drizzle/0036_verifications.sql),有自己的 id、状态机、执行模板、runner、接口和统计口径。和另外四条一样,字段是平行定义,不是共享的。

最早它是 features.deliverable = 'report' 的 feature,理由是「派发、认领、路由、复核都能复用,差别只在交付物和报告格式两处」。跑了一段之后发现,共用一张表的代价不在这两处分叉,而在它把 Feature 的一切口径都污染了:

  • 服务端的每日创建 / 完成数、周报、KB 效果、证据指标全都按 features 表算,走查被计成 Feature 交付,前端再靠 displayKindOf() 事后剔一遍 —— 只剔得掉看板,剔不掉服务端统计。
  • 执行 prompt 是 Feature 的 feature.run.* 模板,再在末尾追加一段「前面那套交付代码的规矩这一轮不适用」。TestSpec、EffectiveSpec、TTKB、拉产品代码仓全照跑,Feature 模板每次改版都顺带改了验证线的行为,而验证线的 prompt 没法独立做版本实验。
  • 收尾时 feature runner 仍会走推分支那段逻辑,e5e4c65c 因此挂着一个 0 commit 的 feature/social-ui-audit-report。

所以拆开。它和 prototype 一样不改代码仓(没有 eval、没有确认闸、没有分支 / MR),认领时排在 prototype 之后、其它三类之前。面板上它本来就独立成一档,现在后端也是。改动验证要检出、编译,却仍然插队:提交人正等着结果接着改,不该排在修复单两小时的构建后面。老卫星会把不认识的格式当 UI 走查跑,所以卫星认领时声明自己能跑的格式(verifyFormats),没声明 change-run 的拿不到改动验证。

同样的道理也用在格式上:两种格式的执行模板、报告契约、面板视图各是一套,不是一份模板里的两个开关。出现下一种交付物时,先加一种格式,别往现有模板里塞「只有某种验证才用」的段落。

一条任务的全生命周期

阶段 status 面板读法 这一步产出什么
建单 awaiting_verify 待采集 verifications.verify_spec(规约 JSON;用例验证连同用例清单一起落库)
执行 verifying 采集中 evidence/:截图、录像、manifest.jsonl;报告 evidence/Case-Run-Report.md 或 evidence/UI-Audit-Report.md(UI 走查另有同名 .ui.txt / .navfail.png;CI 包覆盖率验证另有 ci-*.json(l) 四个平台文件)
收尾 report_ready 报告就绪 verifications.audit_report(面板渲染用的结构化数据)+ readable_report_html(几 KB 降级摘要)
复核期 report_ready — verification_notes:复核人写的期望、以及问题转成了哪张单
补采 report_ready → awaiting_verify 待采集 复核意见追加进 review_history,下一轮用第二轮模板在原工作区上补
终态 accepted / verify_failed / archived 已验收 / 采集失败 / 已归档 无分支、无 MR、代码零改动

UI 走查的「执行」可以是多段会话:一段结束后,报告第 3 节还有「待走」场景、预算没用完、这一段确实有进展,节点就起下一段从报告接着走(见下文「长时间走查:预算与接力」)。下面说的终态判定发生在最后一段之后。

执行结束的判据是 Agent 自己打的哨兵:STATUS: VERIFY_DONE 且本格式的报告已落盘 → report_ready,STATUS: VERIFY_FAILED / 没有哨兵 → verify_failed。超时但报告已落盘也判 report_ready:报告是边走边写的,已落盘的部分照样能复核 —— 用例验证里没写到的检查点显示「未报告」,UI 走查里没走到的页面在覆盖矩阵里是「—」,都不会被当成通过;超时且没有报告才是 verify_failed;claude CLI 鉴权失败或 API 基础设施错误退回 awaiting_verify 自动重排,和 prototype 同一套处理。report_ready 时控制面自动触发一次报告生成。

每一步都落库:规约(verify_spec)→ 过程(round_digests,kind verify)→ 产物(audit_report)→ 人的判断(verification_notes)。唯一还在盘上的是证据文件本身,它有自己的 TOS 镜像(owner kind verify)。

规约与执行模板

e5e4c65c 那次能跑成,靠的是有人把整份走查规约手写进了任务描述、agent 恰好读懂 —— 那是运气不是机制。要测什么、语言矩阵、用户形态、报告格式都是创建时就已知的事实,应该由控制面下发。

所以建单时收的是结构化规约(shared/src/verify_prompt.ts::VerifySpec):

// 用例验证
{ "format": "case-run", "scope": "<补充说明,可空>", "cases": { "source": {…}, "title": "…", "cases": [ … ] } }
// UI 走查
{ "format": "ui-audit", "scope": "社交场景全链路 …", "langs": ["en","de",…], "personas": ["新用户",…],
  "scopeTemplate": "tiktok-social-main", "checks": ["【热区】…", …], "budgetHours": 8 }

没写 format 的是用例验证出现之前的老规约,按 UI 走查处理。

执行模板各自是 shared/src/verify_prompt.ts 里的一个常量、各有自己的派发 stage(控制面随任务下发正文),改它不影响 Feature:

格式 首轮 补采轮 报告文件
用例验证 verify.case.first verify.case.second Case-Run-Report.md
UI 走查 verify.run.first verify.run.second UI-Audit-Report.md
CI 包覆盖率验证 verify.cicov.first verify.cicov.second Case-Run-Report.md(多一节「覆盖补测」)
改动验证 verify.change.first verify.change.second Case-Run-Report.md(报告头多「被测提交」,多一节「建议」)

控制面派发时六份一起下发,节点按规约的 format 和「本格式的报告在不在」挑一份(verify_runner.ts::verificationPromptStage)—— 不让控制面去猜格式和轮次。规约由 runner 渲染成 {{verifySpecBlock}};规约缺失时退回用标题 + 描述当 UI 走查的 scope。

分支。 建单「更多选项」里和 Feature / Bugfix 一样有产品和自定义分支(verifications.base_ref),两种格式里含义不同:UI 走查里它是查「代码位置」的只读基线;用例验证里它是测试分支 —— 平台不替它出包,执行前让 agent 核对设备上装的包是不是这个分支出的,写进报告头「被测包」,对不上照常执行并标明。

用例从哪来:Bits 测试计划与按人授权

建单时贴 Bits 测试计划的执行页链接(…/quality/plan/scenarios/planDetail/<plan>/manualTask/<id>),表单当场拉出用例、按模块勾选。

用例树怎么拆(shared/src/test_cases.ts)。数据来自 bytedcli -j test-plan mind get,它自带的 Markdown 导出只列叶子(预期结果),前置条件、步骤、模块层级全丢,不能用。脑图 JSON 里结构是完整的,每个节点带 nodeType:0 模块 / 标题,3 前置条件,6 操作步骤,13 预期结果。要拆对的一点:Bits 的叶子不是用例,是检查点 —— 多个预期常挂在同一步骤下。所以一条用例 = 前置条件 + 操作步骤,下面挂若干检查点(Share to story 那份计划:18 条用例、31 个检查点)。编号 C01… / #1… 在解析时按先序遍历定死,取消勾选不重排,这样编号能对回 Bits 那一行,补采轮也和上一轮对得上。用例清单在建单那一刻随规约落库,派发时不再回 Bits 拉。

授权。 读计划用的是建单人自己的 Bits 权限:

  1. 表单调 POST /api/bits-cases/fetch。控制面只认 SSO 解析出的邮箱 —— 前端传的一概不收,否则谁都能借别人的授权读计划。
  2. 控制面在本机执行 bytedcli --profile sl-<邮箱>(control-server/src/bits_cli.ts),每人一个 profile,凭据互不相干,都存在控制面这台机器上。
  3. 没授权 → 表单直接给一个授权链接(ByteCloud 设备码流程,auth login --begin),人点开批准,表单每 3 秒轮询 --complete,批准后接着拉。refresh token 约 30 天有效,过期了表单会再给链接。
  4. 批准的人不一定是建单的人(授权页上登着的可能是另一个账号)。--complete 成功后核对 bytedcli 报出的身份,和建单人不一致就清掉这份凭据、报 mismatch,让他用自己的账号重来。

为什么放控制面、不放卫星:凭据要固定存在一台机器上,控制面本来就只有一台;而且这样卫星根本不碰 Bits —— 读到的用例随规约(verify_spec,一段 JSON 字符串)落库,认领时整行下发给卫星,runner 从里面渲染 prompt,报告组装也从它还原用例清单。卫星上没有任何能以别人身份读 Bits 的接口,也就不依赖集群密钥。

报告文件是一份双向契约

prompt 里写死报告的章节骨架,而解析它的是平台的解析器。两者是同一份契约的两端,改一边必须改另一边。漂了不会有人报错 —— 解析不出来时面板静默退回普通报告,证据还在但交互式视图消失。

格式 骨架 解析器 盯着它的测试
用例验证 case_run_report.ts::CASE_RUN_REPORT_SKELETON parseCaseRunReport satellite/test/case_run.test.ts
CI 包覆盖率验证 ci_coverage.ts::CI_COVERAGE_REPORT_SKELETON(用例验证骨架 + 第 3 节) parseCaseRunReport(第 3 节当附加章节) satellite/test/ci_coverage.test.ts
UI 走查 verify_prompt.ts::UI_AUDIT_REPORT_SKELETON audit_report.ts::parseAuditReport satellite/test/verify_prompt.test.ts

证据文件名也是契约的一部分:平台靠文件名把截图 / 录像对到检查点或页面上,名字错一个字就「没有证据」。用例验证的示例名由 caseShotName / caseVideoName 生成,测试断言 prompt 里写的就是这两个函数的输出。

报告是一份数据,不是一段 HTML

另外几条线在可读性报告那个位置放的是模型写好的一段 HTML,读完就完了。这条线不行 —— 报告的价值在看得准、选得动、回得去,静态 HTML 做不到(dangerouslySetInnerHTML 注进面板的 <script> 根本不会执行,第一版就是这么丢掉交互的)。

所以节点交付的是结构化数据,存在 verifications.audit_report,各格式存同一列、靠 format 字段区分:用例验证和改动验证都是 CaseRunData(format: "case-run"),CI 包覆盖率验证是 CiCoverageData(format: "ci-coverage",用例验证的数据 + 覆盖块),UI 走查是 AuditData。面板入口 AuditReportView.tsx 按它选 CiCoverageReportPanel、CaseRunReportPanel 或 AuditReportPanel。readable_report_html 仍然写,里面是几 KB 的降级摘要(结论 + 要看的条目 + 体检),给飞书卡片、导出这类不吃 JSON 的消费者用 —— 它是附属品,不是主视图。

数据 100+ KB,所以不跟着条目下发:列表和详情都把它剥掉、只留一个 hasAuditReport 布尔,面板真要渲染时走 GET /api/verifications/:id/audit-report 取一次。

报告本身不是模型写的。 源文件已经是结构化的,再让模型转述一遍只会丢精度,而且每漏一行都是静默的。用例验证完全不调模型;UI 走查只问模型一件事(见下文「标注框」)。

人写的东西单独落一张表(verification_notes):复核人填的「期望怎么改」、以及这条问题最后转成了哪张单。不能塞进 audit_report —— 那一列是机器产出,每次重新生成整体覆盖,人边看边写的判断会在下一次 regen 时静默消失。

踩过的坑:生成结果是从异步回调回来的。 节点对报告生成返回 202,真正的结果随后 POST 回 /api/internal/readable-result。第一版只在同步分支里落 audit 数据,于是线上生成完一切正常、readableReportGeneratedAt 也更新了,但 audit_report 始终是空的,面板静默退回普通报告。加字段时记得两条路径都要过。

生成链路

节点上 readable_report.ts 收到 kind audit 的生成请求后:Case-Run-Report.md 在就走用例验证,否则走 UI 走查,两者都认不出才退回模型生成。一个工作区只跑一种格式,两份报告不会同时出现。这段跑在节点而不是控制面,因为要的东西只在节点盘上:证据目录的完整文件清单、manifest.jsonl、UI 走查的 .ui.txt 结构树和截图像素(证据代理只透出扁平文件,带 / 的路径直接 400)。

用例验证的报告

按用例组织,检查点是最小单位。每个检查点四种结论之一,外加平台补的一种:

  • 通过:走到了,实际与预期一致,有证据。
  • 不通过:走到了,实际与预期不符。prompt 要求先复现一次、复现那一遍录像。
  • 阻塞:前置条件造不出来 / 进不去 / 设备或账号不够,没走到。不怪被测功能,不计入通过率分母,但要写进报告第 2 节:卡在哪、试了什么、还差什么。
  • 需人工:走到了、证据齐,但预期本身没法客观判定(「符合设计稿」却没给设计稿)。
  • 未报告:用例清单里有、报告里没写 —— 平台补的,不计为通过。分母只认建单时定下的那份清单,agent 自己加的行丢掉。

汇总数字(通过率、各结论条数)不让 agent 写,平台从逐条结论算;agent 写的数字和它自己的表对不上是常态,两份并存只会让读者不知道信哪个。

面板自上而下:汇总 → 需要你看的(不通过 → 未报告 → 需人工 → 阻塞,每条带预期 / 实际 / 细节,录像停在出问题的那一刻)→ 全部用例(按模块折叠,有问题的模块默认展开)→ 复核处理记录 → 证据体检。

证据体检(全部只看文件,不问模型;判的是「结论有没有东西撑着」,不判结论对错):每个检查点有结论、走到了的检查点有截图、不通过的用例有复现录像、截图落在录制区间内能打点、录像本身过了 record-evidence 的校验。

录像与打点

一条用例录一段:从执行「操作步骤」开始,到最后一个检查点截完图结束;前置条件的搭建不录。检查点预期是动态的(出现 / 消失 / 跳转 / 动画 / 键盘 / toast)必须录,判了不通过的必须录,静态画面只截图,阻塞的不录。单段目标 60 秒以内,检查点太多就拆段(case-C05-r1-p2.mp4)。

打点不要 agent 多做任何事。 录制期间 agent 照常在检查点那一刻截图(case-C05-r1-cp27.png),平台从 manifest.jsonl 里读:截图的拍摄时刻落在某段录像的 start / stop 之间,就换算成录像里的秒数(case_run_report.ts::caseVideosFromManifest)。两处校准:

  • 截图时刻用 record-evidence shot 在按快门前记的 takenAt。ts 是截完、探测完、跑完校验才写的,会晚好几秒。老 manifest 没有 takenAt 时退回 ts。
  • 录制器起来要时间:挂钟时长比文件真实时长(ffprobe)多出来的那一截,基本花在开头,从偏移里扣掉。

面板上每段录像下面一条时间轴,打点按结论着色;点检查点从打点前 1.5 秒开始播,播到哪、对应的检查点就高亮;链接带 ?case=C05&t=18.2 打开时滚到那条用例、从那一秒播。模型不看视频判结论 —— 真值只认执行,录像是给人复核用的。

CI 包覆盖率验证(实验)

为什么有这种格式

Streamline 的 bug / feature 交付物是 Bits 上的一条 MR,MR 的卡点之一是代码覆盖率。覆盖率只认流水线打出的插桩包在真机上跑出的数据:包里的 SDK 每 60s 把执行过的代码报给 coverage-data-center,按 commit 记到 MR 上。平台第一次执行时测的是节点本地构建的包,覆盖率同步不过去,人还得拿 CI 包再手测一遍。这种格式把「第二遍」交给平台,而且接力第一遍:第一次执行时验证过的路径(TestSpec 的条件 / 步骤、报告里的验证小节)原样带过来,不用重新摸索。

2026-09-24 用 MR 8439663 在 fei-android-01 上手工走过一遍全链路,结论全部成立:CI 包与节点本地包签名相同,adb install -r -d 覆盖装、登录态保留;channel local_test ⇒ 离线包,TTMock 生效;R8 混淆后 Frida 按 mapping 翻译的名字能 hook;打开任意草稿后等 180s,Bits 行覆盖率 0% → 66.67%。

建单:只能从单子上一键建,事实在建单时查定

入口在 bug / feature 抽屉头部的烧瓶按钮,只对管理员显示(Android、已有 MR、复核中 / 已完成才出现);建出来的验证任务和报告对所有人照常可见。表单 POST /api/verifications 不接受 ci-coverage 规约 —— 手写的包信息平台核实不了,装错包白跑一轮还污染 MR 的覆盖率。

POST /api/verifications/from-source(control-server/src/ci_verify.ts)以建单人自己的 Bits 授权(和读测试计划同一份 bytedcli profile,没授权时抽屉走同一套设备码流程)查定:

  1. bits mr status → project / iid / 最新 commit / merge base / 流水线 job 与产物;
  2. bits mr packages → 最新 commit 那一组里的 *-local_test-release.apk(ci_package.ts::pickCiPackage)。只有旧 commit 的包 = 流水线还没出新包,返回 409 让人稍后再点 —— 拿旧包等于验证一份已经改掉的代码;
  3. 打包 job 的 jenkins_build_result.json(公开地址)→ md5、大小、mapping 地址;
  4. 来源单 TestSpec → 用例(ci_coverage.ts::casesFromSourceSpec):C01 的检查点是 bug「修复后验证」/ feature「验收标准」的每一条,前置 / 步骤原文带上;C02 是「改动代码覆盖补测」。

同一张单同一个 commit 已有未归档的,直接打开那一个。

用哪条 MR,建单时可以改。 单子上记的 MR 不一定是修复最终落地的那条:0ed54d79 记着的 8188853 已关闭,真正在用的 8439663 是后来在另一条分支上手工开的,平台不知道。所以抽屉的确认框里 MR 链接默认填单子上那条、可以改;已关闭的 MR 直接拒绝(409 mr-closed)—— 它最新 commit 的包往往还在,不拦就会成功建单、认真跑完一整轮,测的却是被放弃的代码。入口除了头部的烧瓶图标,复核清单 / 「修复完成」清单里也有一行「用 CI 包验证 · 跑覆盖率」:执行成功不等于不需要这一步,覆盖率卡点只认 CI 包的数据。

只有 release 变体插桩:gradle/global/buildcontext.gradle 里 isOpenJacoco = (jacoco || precise_test) && !isDebug。CI-Check 那个 *-local_test-debug.apk 虽然也带 jacoco=true,dex 里没有 $jacocoInit,不能用。

节点:agent 起来之前装包、之后恢复

satellite/src/ci_coverage_run.ts,不交给 agent —— 一半是真值来源(装的到底是不是 CI 包、改了哪些方法、执行到没有),一半是会弄坏节点的操作。

  • 准备:备份设备上的包 → 下载 CI 包(md5 校验,按 URL 缓存在 ~/.streamline/ci-cache,留最近 2 个)→ adb install -r -d → 从 merge base..commit 的 diff 算改动方法(git show <commit>:<path> 只读,不碰工作区)→ 流式扫 mapping(400+ MB 不进内存)把类名、方法名、参数类型翻译成混淆名 → 生成 Frida 脚本 → 起采集守护。这一段十几分钟(下载 ~1 GB 是大头),期间状态已是 verifying,进度在运行日志 [ci] 行。装包失败直接 verify_failed 并恢复原包,不让 agent 在错的包上跑。
  • 采集守护:每 2s 看一次 App 的 pid,换了就重新 attach(agent 冷启动 App 是常事);attach 连续很快失败时指数退避。事件写进 evidence/ci-events.jsonl,已执行 / 未执行的清单实时刷新到 evidence/ci-coverage-status.md —— agent 靠它知道 C02 还要去触发哪些方法。
  • 收尾(写终态之前):App 必须活着再等 190s,让 SDK 报完最后一个周期(被 agent 杀了就拉起来,落盘没报的会在启动后补报)→ 停采集 → 装回原包。顺序不能反:终态一落,控制面就让本节点组装报告,报告要读到这一步的记录(evidence/ci-run.json)。

时间轴:谁的时钟、怎么对齐

Frida 脚本(ci_coverage.ts::buildCiFridaScript)只观察、不改行为,挂三类 hook:

  • 改动方法:按翻译后的名字和参数类型选重载(R8 会让不同签名的方法共用一个混淆名);mapping 里找不到的方法 = 被内联或裁掉,标「包里没有」、不计入分母,绝不猜(带行号的 mapping 里,同区间同混淆名一串中前面的是内联帧,也不 hook)。
  • 点击:View.performClick —— 控件在屏幕上的矩形、文案、resource id。agent 用 adb input tap 注入的点击不经过 /dev/input,getevent 看不到,但一定走到 App 里的 performClick。报告里的「UI 区域高亮」就是这个矩形。
  • 触摸:Activity.dispatchTouchEvent 的按下 / 抬起(滑动这类没有 click 的操作)。

事件带设备时间;frida CLI 走管道有缓冲,到达宿主的时间不可信。所以每 5s 发一次心跳,报告组装时按 offset = min(recv - dt) 把设备时间换到宿主时钟上,再和 manifest(录像起止、截图 takenAt,宿主时间)对齐。残余误差 = 最快那条事件的传输延迟,USB 上是几十毫秒。

报告

CiCoverageReportPanel:头部三个数 —— 检查点结论、改动方法执行到几个(平台记录)、行覆盖率(链到 Bits,只有 Bits 能解析插桩数据,报告不自己估);然后是回放:录像上叠被点控件的高亮框和触摸涟漪,改动方法一执行,右侧卡片浮现那个方法的 diff、几秒后淡出,旁白(开始录制 / 点击「…」/ 执行到改动代码 … / 检查点 #n → 结论)随播放滚动、点击跳转,下面三条轨道(检查点 / 改动代码 / 操作)可点;再往下是改动方法清单(点开看 diff、跳到第一次执行)和逐条检查点(每条挂着「拍这张截图之前执行到的改动代码」)。旁白、打点、对应关系全是平台从文件算的,不调模型。

体检比用例验证多六项:装的是 CI 插桩包(不可调试、md5 对)、改动方法能在包里定位、代码执行记录、改动方法执行到、覆盖率上报等待、恢复原包。

这一版的边界

  • 只支持 Android。 iOS 的 CI 包是 iphoneos 的 InhouseRelease IPA(带 BDTestCoverage),deploy.sh 理论上能转成 macCatalyst,但没验证过;而且 iOS MR 面板上「总插桩行」是 0,流水线是否接了覆盖率要先问覆盖率平台。
  • 行覆盖率不自动取。 Bits 的覆盖率接口(ospApi/codeCoverage/...)走浏览器会话,控制面能不能以 bytedcli 的授权调用没验证;bytedcli 也没有客户端覆盖率命令。
  • 节点要有 frida CLI:fei-android-01 有;evaluator-android-01 只有 frida-server 没有 CLI,在那里跑时代码执行记录为空(体检 FAIL,用例照常)。
  • 补采轮的状态清单是本轮重新记的:上一轮执行到的方法这一轮没再跑到会显示「未执行」;Bits 上的覆盖率按 commit 累计,不受影响。
  • 上线要控制面 + 卫星一起发,卫星先到。 老卫星的 parseVerifySpec 不认识 ci-coverage,会把它当 UI 走查跑(不装包、不采集)。入口只对管理员开放,在卫星全部更新之前不要建单。
  • 本地插桩构建(不下载 CI 包,节点自己 -Pjacoco=true -PpredefinedChannel=local_test 打 release)在调研中:插件对 TASK_ID 为空的本地构建有专门分支(uuid -1、TOS 前缀 local_android),但这样上报的数据会不会计入 MR 报告还没验证。

UI 走查的报告

生成链路

evidence/UI-Audit-Report.md ──parseAuditReport──> AuditReport(覆盖矩阵/逐页问题/BLOCKED)
evidence/screens/<lang>/<page>.ui.txt ──parseUiTree──> UiElement[](含 frame)
                    │
                    ├── 模型:这条问题指的是哪个控件?只能回 @序号
                    │
                    └── boxOf() ──> 百分比框 ──> buildAuditData() ──> verifications.audit_report
  • shared/src/audit_report.ts —— 解析、坐标换算、数据组装、降级摘要。零运行时依赖(要打进卫星 bundle)。
  • satellite/src/audit_report.ts —— 扫证据目录、收结构树、跑定位、做证据体检。

模型只被问一件事,而且是封闭选择题:候选控件连同 @序号 一起给出,它只能回序号。最坏情况是选错控件(框画在邻居身上,人一眼看得出),而不是编一个看起来合理、实际不存在的坐标。任何一批定位失败就丢掉那一批,报告照出 —— 没有框比框错好,面板上那条问题会标「未标框」。

坐标换算有一个坑

截图是 macCatalyst 的窗口截图,比 App 窗口本身高出一条标题栏。先用宽度定缩放(窗口宽 = 图宽),再用高度差反推标题栏占了多少像素:

scale  = imgW / winW                 // 606 / 394 = 1.538
chrome = imgH - winH * scale         // 1418 - 854*1.538 = 104px

不扣这 104px,所有框整体偏上约 7 个百分点 —— 在 chip 这种 16pt 高的目标上就是完全错位。

面板

默认按问题读(AuditIssueReport.tsx,对照用户期望的交付报告样子做的):批量走查是后续修复计划的入口,所以顶上是「后续执行」—— 已处置进度(转修复 / 无需修复 / 未处置)、修复单各档(待确认执行 → 修复中 → 待复核 → 修复完成 → MR 合入 → 未修好)、按规则挑的「下一步」(最多三条,不调模型)、按严重度 / 按面 / 报告完整度的入口,每个数点了就是把下面的列表筛到那一撮。类别页签(功能 / 热区 / 文案与多语言 / 颜色 / 布局 / 组件规范,老报告的自由类别按关键词归进来)+ 优先级筛选;问题卡里看截图上的标注框、现象、复现条件与原因(直接展示不折叠:读者靠它判断是不是真 bug,修的人靠它复现;报告第 4 节问题表的两列,人可以在卡上补充 / 修正,落在 verification_notes.repro / cause(drizzle/0056),人写的优先,转单时原样写进修复单)、证据与检查说明、修复期望,上一个 / 下一个(按列表的显示顺序);「分享」复制 /verify?id=…&issue=<页面 id>:<序号>,对方打开直接全屏定位到那一条(多语言这类转不成修复单、要交给别的团队的问题用它)。下面是按「类别 → 功能区(报告里的面)」分组的问题列表,每行「开始修复」或「无需修复」,处置后留在原地显示新状态;勾选后底部结算条「修复所选问题」(同一个面上的合并成一张,见下文「建单」)或「重新检查」(带上所选问题和补充要求,走补采意见那条路,回到采集中)。一条问题在多语言里出现算一条。「无需修复」落在 verification_notes.dismissed_at(drizzle/0055),可撤销。可全屏(和修复报告同一个外壳):详情在左吸顶、列表在右,选中行高亮。演示页 control-web/demo-audit-fix.html。

原来的按页面看仍在,外层切换:三栏:页面列表(按面分组,带该语言下的采集状态与问题数)· 截图与标注框 · 检查项与问题。顶上是语言条 —— 切的是截图和命中的问题,不是界面翻译。

勾选是跨页跨语言累积的,所以结算条一直吸在底部。每条勾中的问题下面会长出一个选填的「期望怎么改」输入框 —— 捕获点必须在看着那张截图的时候,隔两屏再回忆就变成空话了。

建单:同一个面合并,复现已确认,直接修(POST /api/verifications/:id/fix-batch,逻辑在 control-server/src/audit_fix.ts,分组和正文在 shared/src/audit_fix_plan.ts,面板拿同一份代码预览)。原来一条一单:2026-10 的六份走查转出 161 张,每张各自 clean 构建、装包、走到那一页、复现、拍修复前证据 —— 修复一轮中位 59 分钟、构建加设备操作占一半,建单到开跑中位 53 小时,还有 50 张停在「待确认执行」等人点。现在:

  • 分组:同一份走查、同一个面(### 面 N · …)的问题合成一张,一张最多 6 条,同一页面的问题不拆开(某一页本身超过 6 条才切开)。161 条 → 39 张。P0 / P1 和「功能」类单独成单、照常评估 —— 它们是行为缺陷,要真复现。勾了多条时先弹预览,说清会建几张、每张挂哪几条;只勾一条直接建。
  • 不复现:走查截图是真机上的执行结果,按 docs/rsi.md 的底线可以当真值。合并单不过评估器:控制面直接写好 TestSpec,以「待确认执行」带方案落库后立刻走 startTaskExecution 进修复队列(勾选、写期望的那一下就是确认)。TestSpec 第一段是「复现已确认」声明,bug.run 步骤 3 认这几个字(TRUSTED_REPRO_MARK,测试钉住两端):不单独复现、不判 UNREPRODUCIBLE,走查截图复制进 evidence/ 当 before-*,修复后逐条回到现场拍 after-*,FixReport 加一节「逐条结论」(已修复 / 未修复 / 不成立 / 不在本仓)。修好几条就交几条:至少一条已修复就推送、以 FIXED 收尾,其余各条的结论留给复核人;一条都没修好才 FIX_FAILED。原来要求「全部已修复或不在本仓」才算成功,2026-10 的 5 张 FIX_FAILED 合并单里 4 张其实已修好 1–5 条,commit 卡在节点本地;被判「未修复」的多半是走查量错(所以加了「不成立」)或改了没环境验证。走查写的「原因」「代码位置」是走查 agent 的推断,在 TestSpec 里标成线索 —— 线上有走查判成 Lynx 页面、其实是原生 Fragment 的单。建单时勾的检查项里和本单问题同类的那几条,原文写进 TestSpec「走查用的判定规则」:修复侧动手前按同一条规则、同一个参照系复算,不命中的不改代码、记「不成立」,规则套不上的写「规则不适用」,不另定标准;记「不成立」时并排写出双方量的控件、参照和数值。以前修复侧只拿到「按 TUX 规范 / 同类页面的做法改」,各自定标准 —— 2026-10 的合并单里被修复侧推翻的 F-62 / F-18 / F-98 复算下来都是走查量错(参照系取了屏幕边、取了含 padding 的 cell 边界、量了被盖住收不到点击的控件),而 F-39 / F-60 按走查规则修复前并不命中,修复侧却改了代码。间距和热区两条检查项的原文同时改了(到所在容器左边缘、只认可见内容、热区写出来源并对叠放控件做 hitTest);已建的走查规约是快照,不追溯。
  • 现场随单走:每条问题的走查截图、同名 .ui.txt 结构树和 .controls.txt 控件清单,建单时转存成 plan 图(img_upload/plan-<uuid>.<ext>),卫星认领时 materializePlanImages 拉进修复单的 images/,走查节点的工作区被清掉也不丢;标注框坐标、人补的复现条件 / 原因 / 期望、第 5 节的构造方式、第 6 节的路由一并写进正文。以前只写证据文件名,修复 agent 拿不到图;正文里「进入方式见第 5 节」也是一句悬空的引用。
  • 母单与并发:一份走查转出的单都挂在批次 audit-<验证 id 前 8 位> 下(批次中心里就是那张母单,建单人是负责人);同一批同时最多 2 张在修(AUDIT_BATCH_MAX_RUNNING,claimAnyFixForNode 认领时检查,软上限),免得一份走查占满整个舰队。
  • 停泊合并:合并单建好后先停 15 分钟才让节点领(AUDIT_PARK_MS,记在控制面内存里 audit_park.ts,重启丢了只是提前开跑);停泊期内、以及之后在队列里还没开跑的时候,同一个面上再转的问题先并进这张单(并满 6 条为止,同页面的优先去已有这一页的单;planAuditFixMerge),整张单的描述和 TestSpec 按全部问题重写,用条件更新防和认领撞车(撞了就新建)。只对走查转出的合并单,普通 Bug 单没有停泊。
  • 面板引导一起修:建单前先以 dryRun 问服务端会并进哪张、会新建几张,预览里写「并入现有单 +N 条,共 M 条」;单条点「修复」时,同一个面上还有能合并的问题就提示「再加 N 条能凑满这一张、共用一次编译」(只建议凑满一张的那几条,同页面优先);列表每个面的标题上有「选中这一面」。
  • 修复单抽屉:「原始问题与截图」按合并单正文(auditFiledIssues 认新旧两种格式)一条一行 —— 缩略图、等级、一句现象、编号 · 页面 · 语言,和走查报告的列表一个样子;点开看带标注框的截图和期望、复现条件、原因(线索)。正文里的 images/plan-… 换成 TOS 地址显示。
  • 回写:每条问题的 verification_notes.filed_task_id 指向它所在的那张单,几条问题指向同一张;已经转过单、标了无需修复的跳过;某一组建失败不影响别的组。同一份走查同一时刻只跑一个建单请求。

修复进度。 走查报告是总表,修复单各自一张。总表不另记进度,只读每张单自己的状态(verification_notes.filed_task_id → GET /api/tasks/:id,开着报告时每分钟刷新):问题卡上的「已转」变成带状态的链接(修复中 / 待复核 / 修复完成 / MR 已合入 / 未修好 / 已关闭),报告顶部多一节「修复进度」,一单一行、链到单子和 MR、列出它挂着的问题编号。合并单修好几条就交几条,单子状态说明不了每一条,所以单子跑完后(待复核 / 修复完成 / 未修好)再按它最近一批 FixReport 的「逐条结论」逐条显示(GET /api/verifications/:id/audit-verdicts,解析器 parseAuditVerdicts 和 TestSpec 里规定的结论词是同一份契约,测试钉住两端):「已修复」照旧跟单子状态走;「未修复」显示「这条没修好」、「不成立」显示「复查未见」(和走查结论对不上,附修复 agent 的实测依据),这两种重新算待处置,可以「再转一张」(新单 TestSpec 带上上一张的结论当线索,不成立 的先核对两边量的是不是同一个东西)或确认无需修复;「不在本仓」提示用「分享」交给对应团队。编号按问题当前挂着的那张单对,报告重新生成、问题挪了位时会对错,目前不校验。本地演示 control-web/demo-audit-fix.html(报告数据读线上只读接口,单子状态是假的)。

构造态。 报告第 5 节「状态构造记录」里登记过的页面,在页面列表和截图头上标「构造态」,截图上方写怎么造的 —— 看图的人得知道这一帧不是自然走到的。

场景可达性。 覆盖率只统计进得去的页面,进不去的场景根本不在分母里。e5e4c65c 的「单元可达率 97.9%」看着很好,但 Story 创作、新用户弹窗顺序、Streak 主页这些整类场景从未进入那 61 个页面。所以 BLOCKED 清单是结构化字段(场景 / 原因分类 / 已做到哪一步 / 解封需要什么),不是正文里的一段话。可达性判断本身会出错:那次复核推翻了首轮的一条 —— 首轮判「Creator 消息套件缺账号做不了」,复核发现设置里换个套件就能进,多覆盖了 6 个页面。做成字段才追得着改。

证据完备性。 截图与结构树是否配套、字节重复检测、导航失败是否留痕(*.navfail.png)、未采集单元、问题是否落到代码行、有没有端到端录像。字节重复那一项是有来历的:那次走查有 10 张截图内容完全相同(隐私弹窗压根没拍到,却按「已采集」计入 279 张),另有 3 起误拍(阿语好友列表拍成粉丝列表、贴纸面板和表情面板同一帧、Streak Pet 拍成贺卡面板)。全是人工复核才发现的,而它们在落盘那一刻就能机械查出来。

范围模板与关注问题

建单表单(UI 走查)有三样起草辅助,都在 shared/src/verify_scope_templates.ts:

  • 范围模板:选了就把一段起草好的范围正文填进输入框,人照样能改、能追加「这次重点看空态」。落库的仍是文字,模板 id 只记来源;模板改版不追溯已建的单。第一份是「TikTok 社交主场景」(Story 创作 / Story 消费 / DM / Profile / Friends tab)。
  • 关注问题:勾几条注入几条(spec.checks),不勾 = 只按范围正文查,系统 prompt 里没有缺省检查项(以前不勾会补一份写死的六类,含热区 <44pt,范围只写了多语言的 e1e28a58 因此报出 23 条热区);原来的六类是表单上的「常规走查」一组。热区的规范只有 hit-area-spec 一份。表单上「添加更多」可以加共享的自定义专项(名称 + 六类之一 + 检查内容),存在 settings 表 verify_check_presets_v1 一行 JSON,目前所有人都能读写删(/api/verify-check-presets);建单时和内置专项一样把全文快照进 spec.checks,改了删了不影响已建的单。范围正文的快捷填充叫「常用场景」,仍存在各人浏览器本地。每条带类别(热区 / 布局 / 组件规范 / 文案与多语言),prompt 要求报告「类别」列照填,面板按类别筛得动。量法写在条目里:热区、间距从结构树的 frame 算(安卓像素要按 density 换成 dp),字重、组件类名从运行时读(Frida),截图目测判不准这几类。
  • 时间预算:2–12 小时,缺省 6(= 引入预算前的单会话上限)。
  • 测试账号(spec.accounts,可选):按用户形态给号(空账号 / 新用户 …)。给了就取真实空态 —— 比 Frida 造的可信,也省掉 agent 自己去账号池里试号(e3c30b3d 试了两个号,都有大量数据,还在设备上留下了账号)。prompt 同时禁止登录规约之外的账号。

状态构造:进不去的状态可以造出来

走查不是修 bug,目标只是让页面以某种状态(空态、加载失败、断网、无好友…)出现在屏幕上好检查 UI,不需要「真实复现」。所以 prompt 给了一个从低到高的阶梯,三档都试过才允许写「BLOCKED(缺数据)」:真实操作 → 环境手段(断网、TTMock)→ Frida 改数据(把列表数据源 / ViewModel / 解析后的回包改成空或失败,再刷新)。规矩:脚本存 evidence/hooks/、报告第 5 节登记;hook 不许跨页泄漏,但脚本自带 dispose()、复原能确认的就不冷启(e3c30b3d 一轮冷启了 29 次,每次连带重新导航),只有动过缓存 / 单例 / 全局开关才冷启;只因构造本身才出现的异常不记成问题。平台相关的 attach 方式由 runner 按探测到的基线渲染进 {{fridaBlock}}。

Frida 报错不等于阻塞。 2026-10-14 扫了 6 个用过 Frida 的会话(5 个原型 + 4c3b7d32):10 次 Frida 报错里 8 次 agent 在后续序列里自己恢复了(重启设备上的 frida-server、清残留 helper、修脚本、补 PATH、冷启 App),剩下 2 次都有已知解法、只是放弃得太早 —— 4c3b7d32 遇到 unable to intercept function 重试一次就转去抓包、把 Frida 记成「环境」;766f1074 第 1 轮 iOS attach 一直超时判了失败,第 2 轮先清 helper,普通用户就挂上了(所以「iOS 必须 root、sudo -n true 要密码就不可用」这条是错的)。prompt 因此带一张「现象 → 解法」自救表,表里的解法没试完不许写 BLOCKED,并要求在「已做到哪一步」逐条写试过什么。复核可达性时同样按这个口径:**看后续序列有没有自己恢复,恢复过的或有已知解法的都不是 hard block。**节点兜底:每段会话结束都清掉命令行带工作区路径的 frida 进程、安卓 svc wifi enable。

长时间走查:预算与接力

一段 claude -p 会话越拉越长,上下文就越来越糊;4c3b7d32 那种一小时就自认「走完了」收工的情形也常见。所以长走查交给多段会话:

  • prompt 要求开工先把规约范围拆成场景清单,全部写进报告第 3 节、状态「待走」,走完一个移走一个。「待走」行是段与段之间唯一的交接物 —— 它在报告里,不在模型上下文里。
  • 一段结束后(verify_runner.ts 的循环),满足全部条件就起下一段:报告里还有「待走」、剩余预算 ≥ 15 分钟、段数 < 8、这一段证据目录或报告有变化(防空转)、这一段没打 VERIFY_FAILED、不是鉴权 / API 错误。接力段的 prompt = 一段开场白(第几段、已用 / 剩余、还剩几个待走)+ 本轮完整 prompt。
  • 日志追加到同一个 session-r<n>.log(面板只认一个 logPath);哨兵和卡死看门狗只看本段新增的部分,否则上一段的 VERIFY_DONE 会让下一段一起来就被掐掉。
  • 预算用完时仍是「待走」的场景,在可达性表里显示「未走到」,不计为通过。
  • 按上下文体量交棒。 e3c30b3d 两段会话的上下文都从 68k 线性涨到 550k+、一次没压缩(模型有 1M 窗口),每一步都把整段重读一遍 —— 那一单约 $78 里八成是读缓存。而接力段开场只要几分钟、68k 起步,所以更早交棒更划算:节点每次轮询从日志尾部读主会话最近一次调用的上下文大小(子 Agent 的不算),超过 200k(VERIFY_HANDOFF_CTX)建 logs/HANDOFF,prompt 要求 agent 每走完一个面检查它、存在就落盘交棒;超过 360k(VERIFY_HANDOFF_HARD_CTX)直接截断本段照常接力(报告边走边写,最多丢正在做的那一页)。
  • 看图节制。 同一单读了 143 张全分辨率截图,占工具输出的 48%。热区、间距、字重、类名、文案是否带「…」从结构树 / Frida 控件清单读数判断;要用眼睛看的先 sips -Z 480 缩略,成批核对交给子 Agent、只回文字。
  • 改报告走 audit-report 命令,一次改一处。 00889383 写了 122 次报告、其前的思考共 34 分钟 —— 每次把整份 Markdown 读出来拼字符串整段写回,越往后越贵,还把表格改坏过。bin/audit-report.ts(打进卫星 bundle 的子命令,核心在 shared/src/audit_report_edit.ts)提供 init / page / issue / cov / scene / done / construct / route / recipe / summary,格式由它保证、和解析器同一份契约,写入先落临时文件再改名(会话被截断也不会留下半份报告)。命令全名由节点渲染进 {{auditReportCmd}}。
  • 等界面用 wait-for --ui-text,不写死 sleep。 两张走查单每轮 16–21 分钟耗在 sleep 上。--ui-text '<正则>' 每秒读一次结构树,出现即返回;--ui-gone 等加载提示消失;默认 30 秒、上限 3 分钟,等不到时打印当前屏幕上的文案(这正是早先禁止拿 --until 等 UI 的理由 —— 只知道没等到、不知道在哪一页)。这一条写在所有任务共用的等待块里,修 bug / Feature 同样受益。
  • Android 别拿 actl_screenshot 看屏幕:它把整张图返回进上下文,00889383 调了 168 次、占工具输出 39%。
  • 长语言对照放最后。 主语言把所有场景走完后一次切换、逐页补拍、一次复原,在第 3 节是最后一行「待走:长语言对照」。e3c30b3d 切了 4 次德语,每次都要冷启并复原切语言带出的两项翻译设置。
  • 代价:验证插队在修复单前面,12 小时的走查就是占住一台节点半天。

已知路由与做法:跨任务积累

每次走查都在重新摸同样的入口(Story 归档要从精选进、Followers 要从 Following 里切 tab)和同样的坑(Story 创作入口卡在相册授权框、切德语带出翻译设置副作用),而这些只写进了那台节点本机的记忆。所以:

  • 报告新增第 6 节「路由与经验」:两张表,页面 | 中文名 | 怎么进 和 场景 | 管用的做法,写给下一个 agent 看。解析进 AuditData.report.routes / recipes,随报告数据落库。
  • 派单时控制面取同平台最近 6 份 UI 走查报告的第 6 节,按「新的覆盖旧的」合并(mergeAuditKnowledge,上限 150 条路由 / 40 条做法),作为 runPromptTemplates["verify.knowledge"] 随模板一起下发;节点渲染进 {{knowledgeBlock}},前面再拼上写在代码里的平台配方(verify_prompt.ts 的 IOS_RECIPES / ANDROID_RECIPES,从 e3c30b3d / 4c3b7d32 / a614077e 的日志里沉淀:MTLJSONAdapter 清空列表、Reachability + TTNet 改写断网、相册授权打通 Story 创作、各类权限被拒的真正读取点、App 内切语言及复原、SCK 截图守护重启、DeviceSim 假相机等)。prompt 要求先照着走、走不通再探索,并把新路由写回第 6 节。
  • 只给 UI 走查。 用例验证 / 改动验证 / CI 包覆盖率验证不经过页面,修 bug / Feature 要的是真实复现 —— 它们的 prompt 都不带这一块(测试里断言了)。其中的环境坑(截图守护、假相机)对所有 iOS 任务都有用,但那属于节点自己维护的 DeviceSim skill,应该写在那里,不往别的线的 prompt 里塞。

解析器对契约漂移的兜底

agent 写报告不会百分之百照骨架来,每处漂移在面板上都是静默的失真,所以解析器对见过的几种都兜住了(00889383 一次撞上四种):

  • .ui.txt 前面拼了说明 / Frida 视图树、uiautomator 的 XML 在文件中段 → 从 <hierarchy 截起解析(那一单原先 122 张里只有 8 张画得出框)。prompt 同时要求 .ui.txt 只放原始结构树,Frida 的另存 .controls.txt。
  • 走完的场景写成「已覆盖」留在第 3 节 → 不算阻塞(原先在可达性表里显示成 13 行「未覆盖」)。
  • 第 5 节多加了别的说明表 → 只认表头第一格是「页面」的那张。
  • 覆盖矩阵补进来的全绿页只能按 id 猜出「面 3」→ 并到同序号的全名面上,按功能区分组不再裂成两组。

取证与基线的两处修补

  • record-evidence 不许同名覆盖已通过的证据,而文件名是平台契约(页面 id / 检查点编号)—— 拍错一帧就只能空着(e3c30b3d 丢了 2 张德语帧)。现在可以显式 --replace "<作废原因>":旧文件(连同 .ui.txt / .controls.txt)改名为 <名>.replaced-<n>.<ext> 保留,manifest 记一条 void(原因、去向),之后同名可重拍。不带这个参数时行为不变 —— 所有任务类型共用这个工具,只多了一个显式开关。
  • iOS 基线探测只认 ~/iosapp/TikTokM.app,而 DeviceSim 节点上 App 跑在 cat-supervisor 实例里,报告头的「被测包」一直是空的。现在找不到时退到 cat-supervisor list(正在跑的实例优先)读实例包的 Info.plist,bundle id 去掉 .dsim.<实例> 后缀。包里没有源码 commit(AWEBuildInfo.json 为空),代码位置仍按 develop 查,prompt 要求在「代码索引基线」写明;大仓 git grep 先缩目录、攒一批后台查(那一单撞过两次 120 秒超时)。

迁移

drizzle/0036_verifications.sql 建表并把存量搬过去:features.deliverable = 'report' 的行连同 audit_report / verify_spec / audit_notes 一起进 verifications / verification_notes,id 不变(节点工作区 ~/taskLog/<id>/ 和证据路径都按 id 找),辅表(readable_report_runs、readable_sources、task_transitions、round_digests、evidence_capture_events、evidence_media)里挂在这些 id 上的 kind 一并改挂,然后从 features 删掉这些行。它只建表、搬行、删行,不删列,所以在旧进程还跑着时执行是无害的。

drizzle/0037_drop_feature_verify_columns.sql 删掉 features 上的三列和 audit_notes 表,只能在 0036 执行且新代码已上线之后跑。

上线顺序(每一步迁移都是生产写操作,由人执行):

  1. bun scripts/apply-migration.ts drizzle/0036_verifications.sql(预演)→ --commit。
  2. 部署新代码(控制面 + 卫星)。
  3. 再跑一次 0036。它是幂等的;第 1 步到控制面重启之间,旧进程仍接受 POST /features {deliverable:'report'},这段窗口里新建的验证会留在 features 里,不搬就会被新代码当普通 Feature 派发、跑出代码。
  4. SELECT count(*) FROM features WHERE deliverable = 'report' 为 0 后,跑 0037。

卫星热部署在等空档、或有推不上去的节点时,旧卫星还在认领。控制面按认领请求里有没有 excludeVerificationIds 字段判断卫星是否认识验证线,老卫星不会被派到验证任务 —— 否则它会把验证当 feature 处理、崩在认领里,任务卡死在 verifying。

老的 feature 深链(?feature=<id>)指向已迁走的 id 时,面板回退去查 /api/verifications/:id。

用例验证不需要迁移:规约和报告数据都复用原来的列,只多了 format 字段。

上线用例验证要做的

  • 在控制面那台机器上、以运行服务的账号装 bytedcli(NPM_CONFIG_REGISTRY=http://bnpm.byted.org npm install -g @bytedance-dev/bytedcli)。服务的 PATH 里找不到时,在控制面的环境里设 BYTEDCLI_BIN 指向它;bytedcli 是 node 脚本,它所在目录会被放到 PATH 最前,同目录的 node 才找得到。没装时表单会显示「控制面这台机器没有安装 bytedcli」(503)。
  • 控制面 + 卫星一起发。 用例验证的模板、record-evidence 的 takenAt、报告组装都在卫星上;老卫星会把 case-run 规约当 UI 走查跑。

还没做的

  • 执行结果回写 Bits(第二期):把每个检查点的结论和证据链接填回测试计划,QA 在 Bits 里直接看进度。bytedcli 没有封装(bits autocase run report 只写本地 report.json);后端有 ExecuteTestPlan,要直接调,而且是写 QA 的计划,需要单独确认。叶子节点 id 已经随用例存下(TestCheckpoint.leafId)。
  • UI 走查还不能叠加在用例验证上。现在两种格式二选一;「按用例走、顺带在经过的每一屏上做 UI 检查」要等 UI 走查改造成附加检查。
  • 打点帧与截图的一致性校验:在打点时刻从录像抽一帧和同名截图比对,对不上说明打点或截图有问题。现在只校验打点落在录像时长内。
  • 只认测试计划执行页(manualTask),单条用例链接(caseDetail)和 scenario plan 本身还不认。
  • 不碰代码仓只靠 prompt 约束,代码层没有硬闸门(和 prototype 一样)。
  • 合并单的「逐条结论」还没解析回来:FixReport 里已经按声明写了每条问题的结论,但报告页上一条问题的状态仍然读整张单的状态。要加 verification_notes.fix_outcome 和解析器(prompt 骨架和解析器是同一份契约)。
  • 第 5 节的构造脚本没有随单下发:脚本在走查工作区的 hooks/ 子目录里,证据代理不透出子目录;现在只带「怎么造的」那段说明,修复 agent 照说明重写。
  • UI 走查建单去重口径:同一条问题在不同语言下算不同的单。要改成一单多语言,把 key 从 page#n@lang 改成 page#n 即可 —— 但 verification_notes 的主键也要跟着改。
  • UI 走查的定位占着节点的可读性报告信号量:12 批跑完之前,这台机器上别的报告排队。要么把批次上限压到 4–6,要么给定位单开一个并发档。
  • .ui.txt 取不回控制面(证据代理不透出子目录),所以只有节点能算框;控制面没法复算,人也没法手工校正一个画歪的框。
  • 历史任务不会被追溯重写,要回填(且回填是生产写操作)。
  • 没有跨任务聚合:单个任务内能看可达性、覆盖和通过率,但看不到「这几轮验证在变好还是变差」。