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

157 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 证据采集监控 · 每日分析任务
这是每日分析跑批的作业书。控制面的定时任务(`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 时标记为不可靠
- 判据类策略额外有回放对照,那个是即时且无风险的
---
## 边界
- 分析任务**不批准任何东西**。它只提出。
- 分析任务**不改代码**。策略里写清楚改什么,由人执行。
- 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。
其他抓手都要走正常的发版流程。