Files
streamline/docs/evidmon-daily-analyst.md
2026-11-16 17:26:44 -08:00

6.4 KiB
Raw Permalink Blame History

证据采集监控 · 每日分析任务

这是每日分析跑批的作业书。控制面的定时任务(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. 看什么

按这个顺序过,先看尺子准不准,再看量出来的数:

  1. L1-E 判定精度 — 它低,上面所有指标都是用弯尺量的。先修它。
  2. 指标树里发生了变化的项 — 对照上一篇的 deltas,只关注变化 ≥1% 且样本足够的。
  3. 昨日新增的 fail / warn 样本 — 逐个看 probe:是真坏,还是判据误伤?
  4. skip 理由 — 这是最富信息的字段。新出现的阻塞类型往往指向一条能力型策略。
  5. 已生效策略的实测效果 — 有没有出现"批准了但指标没动",或者更糟,"动反了"。

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 时标记为不可靠
  • 判据类策略额外有回放对照,那个是即时且无风险的

边界

  • 分析任务不批准任何东西。它只提出。
  • 分析任务不改代码。策略里写清楚改什么,由人执行。
  • 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。 其他抓手都要走正常的发版流程。