droboticflow/.scratch/workflow-perf-audit-report.md
d-robotics 58e0e50570 🧪 Retro 2026-10-12: CI gate, known-failure baselines, devboot regression test, workbench smoke, review standards
Six follow-ups from the round8-12 hotfix retrospective:

- web-ci.yml: lint + Go/frontend tests on every push and PR (nothing ran
  app checks before; the round10 dev-mode regression shipped green)
- tests/known-failures.json + check-test-baseline.mjs: gate by exact
  failing-test id instead of hand-counted failure totals (14 frontend,
  70 Go upstream debts recorded from the dev tip)
- devboot.test.mjs: boots the real Vite dev server and pins the movi
  loader contract that broke round10 (query-less DEV url, /vendor stays
  off the module pipeline)
- scripts/local/smoke-workbench.mjs: pre-release smoke covering the
  seven recurring acceptance points (login/pool/claim/play-while-loading/
  captions/4x/playhead), 3x green against the local replica
- docs/CODING_STANDARDS.md + AGENTS pointer: eligibility flags are
  server-shipped, the UI renders them (rounds 9+12 lesson)
- vendor README host-element quirks section, HANDOFF gate pointers and
  movi-path verification rule, perf-audit report pinned with the
  post-round12 production 500 observation
- husky pre-commit: lint-staged (repo prettier scope) + tsc + gofmt
- gofmt: restore lint:go green on the dev tip (drift shipped silently
  in the perf merge and round12 because nothing gated it)
2026-10-12 18:07:02 +05:30

11 KiB
Raw Permalink Blame History

工作流全链路性能与数据 footprint 审计汇总报告

汇总自四份只读审计笔记(2026-10-09):

  • A1 API 热路径:.scratch/audit-notes/api-hotpaths.md(P1–P9)
  • A2 DB 足迹与清洗候选:.scratch/audit-notes/db-footprint.md(C1–C8)
  • A3 Worker/交付管道 + part-index 激活:.scratch/audit-notes/worker-delivery.md(W1–W6)
  • A4 前端工作流页面:.scratch/audit-notes/frontend-workflow.md(F1–F11)

本报告不新增任何未验证结论,仅做合并、排序与交叉印证。已排除 slow-page-fix 已修复项(认证缓存、human-items 分页/投影、S4 点查等)。

1. 合并后的根因:视频强制服务端转码(F1 × A1/P5 × 部署线)

三线交叉印证的同一根因:前端 src/lib/video-preview.js:120-148 无条件加 transcode=browser,CaptureAnnotationWorkbench 的 browserReadyMedia 默认 false 且页面未传 → 所有标注/审核/验收视频走 API 进程 ffmpeg 实时转码(internal/api/human_loop.go:538-552 → serveRunArtifactContent),叠加全局 Compress(5) 再 gzip 视频流。

  • 影响:打开任务首帧分钟级等待;API CPU 被转码占用并与 JSON 热路径争抢;多标注员并行打满。
  • 修复方向(A4 建议):先直连(去 transcode,307 跳 BOS 预签名)失败再回退转码;中期在切片物化时产出 browser-ready 副本。收益:首帧分钟级→秒级 + 消除 API 最大 CPU 消耗点。风险:个别编码不可播,保留回退并埋点统计。
  • 置信度:高(代码路径三线互证;线上实际回退率需验证后确认中期方案收益)。

2. 按收益 × 置信度排序的优化清单

排名 条目 来源 位置 收益 置信度 风险
1 视频直连 + 回退(根因合并项,见 §1) F1 video-preview.js:120-148 等 首帧分钟级→秒级;释放 API CPU 高 低(保留回退)
2 annotation-tasks 列表全组织 revision 扫描:ListSliceRevisions/ListAnnotationRevisions(org,"") 无 limit 无投影,列表请求拉全组织历史并内存过滤 P1 annotation_operations.go:692-693 消除数百 MB 级 BSON 解码/请求,随历史线性恶化被止住 高 低($in+投影不改契约)
3 loadProject 全量重载(9–11 请求 × 22 调用点,含 listTasks 无分页与 4 池各 500 条) F2/F8/F7 AnnotationOperations.tsx:953-1138 每次操作请求数 ~10→1–2,后端读放大同步大降 高 中(局部更新需核对旁路状态)
4 验收池 listAcceptancePools 放大:非管理员 6 次全量分页扫描/次刷新 F3 human-loop.ts:62-97 全集合游标扫描→单次聚合接口 高 低
5 human-batches 非管理员 batch×item 双重 N+1 全量记录 P2 human_loop.go:244-261 B 次全量 item 查询→存在性判断 高 中(可见性需等价,留 fallback)
6 reviewed 池无界 ID $in + canClaimHumanItem 每条 2 次绕过缓存的 GetHumanBatch(500 条页 → 500–1000 次串行往返) P3 human_loop.go:851/856 纯冗余往返清除,行为不变 高 极低
7 验收决策写路径:整批串行重写(3N+ 写)+ v5.8 聚合 payload 全量重建(MB 级单文档,16MB 风险) P4 human_loop.go:1907-1953、2410-2605 决策延迟大降 + 消除文档膨胀 高 中(acceptance-package/v2 前端契约需同步)
8 workBuffer 3s 常驻轮询(20 req/min/人,无可见性暂停) F4 AnnotationOperations.tsx:4477 空闲期该端点流量降 80%+ 高 低
9 交付管道:逐片 7 文件复制 + 同字节读 3 遍 + 每切片 2 次 ffprobe;上传每文件 4–6 次 BOS API + staging 中转 W1/W2 operator.py:1558-1602、capture_delivery.go:45-77 打包节点读 IO/子进程开销 −50%+(估) 高 中(staging 直传受"不覆盖他人交付"契约约束)
10 prepareDeliveryTarget 每次全量 ListCaptureRecords 重叠检查 W3 capture_delivery.go:109 消除每次交付的全表扫描 高 低
11 最终验收打开即全切片全量翻页拉证据目录 F5 FinalAcceptanceWorkspace.tsx:170-181 打开请求数 O(N×页)→O(页) 中高 低(服务端提交校验兜底)
12 task 详情全历史响应体 + GET 读路径写恢复/转码预热 P5 annotation_operations.go:833-911 响应体 MB 级→当前 generation 中高 中(前端依赖 revisions 形状需核对)
13 交付下载 manifest 逐文件串行预签名(最多 5 万文件,分钟级) P7 delivery_downloads.go:457-464 manifest 生成分钟级→秒级 中高 中(下载器需配合)
14 part.json 全量读+解析 2 遍再读第 3 遍上传 W4 capture_delivery.go:317-356 消除重复多 MB JSON 解析 中 低
15 任务池无虚拟化 + taskContextById O(n²) F6 AnnotationOperations.tsx:5351、2001-2024 低配机点选卡顿消除 高 低
16 rejects 无分页 N+1;随机领取逐候选全量 GetHumanItem P6/P8 human_loop.go:1956-1980;annotation_random_claim.go:226-306 中等冗余往返清除 高 低
17 ProjectDetail 15s 轮询级联扇出;GET 4 次重试×轮询叠加;普通池 500 条静默截断(正确性问题) F10/F11/F9 ProjectDetail.tsx:435;client.ts:99-134;human-loop.ts:36-40 常态流量与雪崩放大收敛;截断正确性修复 高 低
18 完成后 ListPrefix 全量核对、小文件 marker 走完整 staging W5/W6 capture_delivery.go:282-290、156-167 小 中 低

排位说明:1–8 直接作用于标注/审查/验收日常操作路径(人感最强);9–10 是交付管道结构性开销(part-index 激活后 W1 全免,见 §4);11–18 次之。

3. 数据清洗候选(全部需用户逐项拍板,均未执行任何写操作)

体量基于 2026-10 快照库(127.0.0.1:27018/drobodata-fanyu,约 6 周数据),线上需按增长系数外推并复核。

# 对象 估计体量 建议 风险
C1 BOS:已 accepted 分区的源目录 + 中间 pose/undistort/blur 产物 ~50–60GiB(39.1GiB 源 + ~22GiB 中间,需按 manifest 去重) 删除(客户已拿 finalExport) 高:不可逆;必须以 deliveryPackages.acceptanceReviews + finalExportArtifactIds 白名单为准,failed/未验收除外;先导出 manifest 备份
C2 runs.nodeExecutions 的 inputArtifacts/inputLineage/inputBindings 三重重复(占全库 99.8%) 终态 run 30–40MB,全量 ~60MB 归档/收缩为引用(>N 天终态 run);保留 status/时间/artifacts 摘要 中:重放调试需完整输入;同时使 /api/runs 列表传输降 ~90%
C3 poseSummary 在 humanItems 与 annotationTasks 双份冗余 ~200KB,随任务线性 保留 annotationTasks 权威,另一处迁移后 unset 低
C4 humanEvents 历史事件(651 条,无 TTL/归档) 现 0.4MB,无上限 TTL 或 180 天归档 中:合规/审计要求需先确认合同
C5 annotationTimelineIndexes.body 内嵌 gzip 3.9MB(22 条),随 part 增长 改 BOS 引用或大小阈值 低–中:查询延迟可能回退,与 P1 修复需权衡
C6 runs 15 个快照期 0 访问索引(前缀重叠) ~0.3MB + 写放大 线上 $indexStats 复核后 drop 中:快照≠线上,必须线上复核
C7 legacyAssignment 残留、终态 annotationDraft、一次性迁移/备份集合 <100KB 确认无读方后 unset/drop 低
C8 快照实例 9 个测试库 仅本地 ~130MB 本地 drop 无

4. part-index worker 激活执行方案(合并 t3 结论)

变更性质:05f2dc14 → da446d13 属向后兼容(hyperparam PART_INDEX_DELIVERY 默认 false,定义于 builtin_operators_catalog.json:7848;唯一读取点 operator.py:1531;worker 按产物特征自动路由(artifact_storage.go:357-366),对旧目录形态零行为变化;backend 与 operator-repos 镜像同步;有 capture_part_index_test.go 契约测试)。

执行步骤:

  1. 镜像滚动更新(先 1 副本观察再全量),可与 API 同镜像。
  2. 灰度:仅对新增交付任务的打包节点设 PART_INDEX_DELIVERY=true(节点级覆盖,不改 catalog 默认)。
  3. 验证点:首个灰度 part 的 final part.json owner marker/sha256/manifest kind=="part-index";打包节点耗时与 BOS API 次数应显著下降(W1 全免:不再复制媒体字节)。
  4. 回滚:开关关回 false 即回到旧形态,无需回滚镜像;已发布 part.json 为冻结交付物不回滚。
  5. 存量迁移(需专项评审 + 用户批准):scripts/part_index_migration.py dry-run 只读(拒绝写对象存储、拒绝覆盖不同 part.json、复用算子源码保证同构);关键约束:存量已交付目录会被 worker "拒绝覆盖无主/已有文件目录"保护挡住,正常交付通道无法追加 part.json——需专项通道或随下一 revision 交付携带。v2 清单、calibration 为空、discard 无 reason 的 part 需人工确认。

5. 客户确认材料清单索引

需要用户逐项拍板/另行批准的事项及证据出处:

  1. 优化清单 §2 各条的实施顺序与范围(证据:api-hotpaths.md / frontend-workflow.md / worker-delivery.md 对应条目)。
  2. 清洗候选 C1–C7(§3;C8 本地即可)。C1 涉及删除线上 BOS 对象、C4 涉及审计保留期限,须明确授权。
  3. part-index 激活的镜像发布与灰度节点选择(§4);存量迁移正式发布属对已交付目录的写入,需专项评审与批准。
  4. 待线上验证项(快照证据局限):runs 冗余索引线上访问统计(C6)、C1 的 BOS 实际对象体量与 manifest 去重、Mongo RTT 与线上增长系数(db-footprint.md §5)。
  5. 契约影响项:P4/F7 验收 payload 改引用需前端 acceptance-package/v2 同步改造;P7 下载器配合改造;P5 详情 history 分页需核对 workbench 调用方。
  6. 线上观察(2026-10-12,round12 上线后 12h 只读日志):/api/projects/*/workflows、/api/human-items 等出现 4 次零星 500,无 panic、无慢请求级联——与 F10(ProjectDetail 15s 轮询级联扇出 + GET 4 次重试叠加)、P2/P3(human-batches/reviewed 池扫描压力)特征一致。同事性能分支(codex/slow-page-performance-20261009)覆盖多项后应复测销项;未复测前不算新增回归。

6. 正面项(已确认无需改,避免重复投入)

  • human-items 列表分页 + ListProjection + 请求级 humanListReads 缓存。
  • delivery 下载媒体走 BOS 预签名直链;claim 幂等 receipt + 乐观版本控制;候选查询投影干净。
  • 目录发布 BOS 并行度 4;packages-manifest 最后串行发布保证可见性顺序;共享目录文件引用去重。
  • 会话心跳/续期为设计成本非热点;DataOperations 轮询有 hidden 感知可作 F4 范式;验收元数据按需加载。