6.4 KiB
6.4 KiB
证据采集监控 · 每日分析任务
这是每日分析跑批的作业书。控制面的定时任务(scripts/evidmon-daily.sh)负责把
指标算出来;这份文档负责把「指标变了 → 为什么 → 该做什么」这一步写清楚,产出一篇
研究日志条目和若干条待批准策略。
面板位置:证据采集监控 Portal → 研究日志 tab。
分工
| 环节 | 由谁做 | 何时 |
|---|---|---|
| 拉取节点 manifest、算指标快照、刷新已生效策略的前后对比 | scripts/evidmon-daily.sh(系统 cron) |
每日 09:00 北京时间 |
| 读快照 → 写发现 → 提策略 | 每日分析任务(本文档) | 每日 09:30 北京时间 |
| 批准 / 驳回策略 | owner,在面板上 | 人工 |
| 判据类策略生效 | 批准即时生效(无需发版) | 自动 |
| 其余策略执行 | 转为待办,人工推进后在面板标记「已上线」 | 人工 |
指标快照必须由机器定时写,不能依赖分析任务是否跑成功——否则前后对比的基线会因为 某天没做分析而出现空洞。
每日流程
1. 取数
# 若快照当天还没生成(cron 未跑或失败),先补一次
bun run control-server/src/evidmon_daily.ts
然后读取:
GET /api/evidmon/metrics?days=30— 指标树当前值 + 历史快照GET /api/evidmon/findings— 既有研究日志、全部策略、已生效策略的实测效果GET /api/evidmon/events?sinceDays=2— 近两日原始事件(用于定位具体样本)
分析任务用 x-cluster-secret 头认证。它能写发现、不能批准策略——批准路由要求
SSO 登录身份,这是刻意的:提出和批准必须分开。
2. 看什么
按这个顺序过,先看尺子准不准,再看量出来的数:
- L1-E 判定精度 — 它低,上面所有指标都是用弯尺量的。先修它。
- 指标树里发生了变化的项 — 对照上一篇的 deltas,只关注变化 ≥1% 且样本足够的。
- 昨日新增的 fail / warn 样本 — 逐个看 probe:是真坏,还是判据误伤?
- skip 理由 — 这是最富信息的字段。新出现的阻塞类型往往指向一条能力型策略。
- 已生效策略的实测效果 — 有没有出现"批准了但指标没动",或者更糟,"动反了"。
3. 写发现的标准
一条发现必须包含:
- evidence — 引用真实数字和具体产物名。写「12 条 static 打在了 25–108fps 的真实 录制上」,不要写「静态检测不太准」。
- rootCause — 定位到代码或机制。写不出根因说明还没查透,那就先标记为待查,不要 用形容词补位。
- metricKey — 这条发现对应指标树里的哪一项。对不上任何指标,通常意味着指标树缺了 一维,这本身就是一条发现。
样本量纪律:每天只有约 20–40 次采集,视频只有 ~5 次。所以:
- 视频类指标用 14 天窗口,不看单日
- 分母 <8 的比率不下结论,面板会自动标「样本不足」
- 宁可写「样本尚不足以判断,继续观察」,也不要把噪声讲成趋势
4. 提策略的标准
每条策略必须能回答四个问题:
| 问题 | 落在哪个字段 |
|---|---|
| 改什么 | title + payload |
| 为什么(证据是什么) | rationale |
| 用哪个指标验收 | metricKey + baselineValue + targetValue |
| 怎么生效、怎么回滚 | knob |
四类 knob:
- criteria — 阈值与规则。批准即生效,可一键回滚到任一历史版本。 必须附回放结果(见下)。
- collector — record-evidence 的行为。需发版到节点。
- prompt — 采集引导话术。
- capability — 能力/环境工程项(采集后端、账号池、构建健康)。
5. 判据类策略必须先回放
判据变更不需要等新数据来验证——历史采集的完整 ffprobe 结果都在库里,而
evaluateCapture 是纯函数,所以新判据可以对全部历史样本重跑:
POST /api/evidmon/criteria/replay
{ "criteria": { ...CaptureCriteria 的差异字段... }, "days": 30 }
返回收紧/放松了多少条、每个 issue code 的增减、以及每一条判定翻转的样本(带时长、
有效帧率、码率,便于人工抽查)。把整个 ReplayResult 放进策略的 replay 字段,面板
会渲染成生效前后对照。
这意味着判据类策略的效果在批准前就是已知的,不是预期。 提这类策略时不要写 "预计能降低误报",直接写回放跑出来的确定结果。
回放时要留意的陷阱:
- 拼接产物(
compose)是重编码的,码率天然低一个数量级,不能套原生录屏的码率下限 r_frame_rate不可用(大量样本返回 90000 时基),活性要用nb_frames / duration- 一个判据同时收紧和放松是正常的;要分别检查两侧的样本是否都合理
6. 写入
POST /api/evidmon/findings
{
"id": "YYYY-MM-DD", "day": "YYYY-MM-DD",
"title": "...", "summary": "...",
"highlights": ["..."],
"findings": [{ "code": "P1", "title": "...", "severity": "critical",
"evidence": "...", "rootCause": "...", "metricKey": "..." }],
"strategies": [{ "id": "YYYY-MM-DD-S1", "code": "S1", "title": "...",
"rationale": "...", "knob": "criteria", "metricKey": "...",
"baselineValue": 0.538, "targetValue": 0.9,
"payload": { "criteria": {...}, "label": "v3-..." },
"replay": { ...ReplayResult... } }]
}
同 id 重复写入是覆盖(便于当天修订),但已决策的策略不会被重新提案覆盖—— 批准/驳回是终态。
7. 没有新发现的日子
不要为了填日志而写。指标平稳、无新样本时,写一条短条目说明「本日无显著变化, 样本量 N」即可,不提策略。虚构的发现会污染日志作为决策依据的价值。
前后对比是怎么算的
effectiveAt在批准的那一刻盖章,不能事后挑窗口- 对比取生效前 7 个快照 vs 生效后 7 个快照的均值,不是单日读数——避免一个安静的 日子主导结论
- 样本量随结论一起显示;任一侧天数 <2 或样本 <20 时标记为不可靠
- 判据类策略额外有回放对照,那个是即时且无风险的
边界
- 分析任务不批准任何东西。它只提出。
- 分析任务不改代码。策略里写清楚改什么,由人执行。
- 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。 其他抓手都要走正常的发版流程。