Initial import of streamline
This commit is contained in:
+359
@@ -0,0 +1,359 @@
|
||||
# 「验证」线
|
||||
|
||||
跑真机、收证据、出报告。**只测试,不产生代码改动** —— 没有分支,没有 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` 取不回控制面**(证据代理不透出子目录),所以只有节点能算框;控制面没法复算,人也没法手工校正一个画歪的框。
|
||||
- **历史任务不会被追溯重写**,要回填(且回填是生产写操作)。
|
||||
- **没有跨任务聚合**:单个任务内能看可达性、覆盖和通过率,但看不到「这几轮验证在变好还是变差」。
|
||||
Reference in New Issue
Block a user