157 lines
6.4 KiB
Markdown
157 lines
6.4 KiB
Markdown
# 证据采集监控 · 每日分析任务
|
||
|
||
这是每日分析跑批的作业书。控制面的定时任务(`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 时标记为不可靠
|
||
- 判据类策略额外有回放对照,那个是即时且无风险的
|
||
|
||
---
|
||
|
||
## 边界
|
||
|
||
- 分析任务**不批准任何东西**。它只提出。
|
||
- 分析任务**不改代码**。策略里写清楚改什么,由人执行。
|
||
- 判据是唯一可以「批准即生效」的抓手,因为它可版本化、可回放、可一键回滚。
|
||
其他抓手都要走正常的发版流程。
|