# 证据采集监控 · 每日分析任务 这是每日分析跑批的作业书。控制面的定时任务(`scripts/evidmon-daily.sh`)负责把 指标算出来;这份文档负责把「指标变了 → 为什么 → 该做什么」这一步写清楚,产出一篇 研究日志条目和若干条待批准策略。 面板位置:证据采集监控 Portal → **研究日志** tab。 --- ## 分工 | 环节 | 由谁做 | 何时 | |---|---|---| | 拉取节点 manifest、算指标快照、刷新已生效策略的前后对比 | `scripts/evidmon-daily.sh`(系统 cron) | 每日 09:00 北京时间 | | 读快照 → 写发现 → 提策略 | 每日分析任务(本文档) | 每日 09:30 北京时间 | | 批准 / 驳回策略 | owner,在面板上 | 人工 | | 判据类策略生效 | 批准即时生效(无需发版) | 自动 | | 其余策略执行 | 转为待办,人工推进后在面板标记「已上线」 | 人工 | 指标快照必须由机器定时写,不能依赖分析任务是否跑成功——否则前后对比的基线会因为 某天没做分析而出现空洞。 --- ## 每日流程 ### 1. 取数 ```bash # 若快照当天还没生成(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 时标记为不可靠 - 判据类策略额外有回放对照,那个是即时且无风险的 --- ## 边界 - 分析任务**不批准任何东西**。它只提出。 - 分析任务**不改代码**。策略里写清楚改什么,由人执行。 - 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。 其他抓手都要走正常的发版流程。