# 「验证」线 跑真机、收证据、出报告。**只测试,不产生代码改动** —— 没有分支,没有 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//manualTask/`),表单当场拉出用例、按模块勾选。 **用例树怎么拆**(`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` 注进面板的 `