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

360 lines
54 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 「验证」线
跑真机、收证据、出报告。**只测试,不产生代码改动** —— 没有分支,没有 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`):
```jsonc
// 用例验证
{ "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` 取不回控制面**(证据代理不透出子目录),所以只有节点能算框;控制面没法复算,人也没法手工校正一个画歪的框。
- **历史任务不会被追溯重写**,要回填(且回填是生产写操作)。
- **没有跨任务聚合**:单个任务内能看可达性、覆盖和通过率,但看不到「这几轮验证在变好还是变差」。