# Overnight 质量验证运行手册

本文档用于长时间运行提号质量矩阵，验证“上传 Brief 后生成商务可用博主名单”的稳定性、去重质量、主页证据覆盖和策略效果。

## 快速 Smoke

不需要 live token，只验证 fixture、聚合报告、软件端表格、人工复核抽样、门禁和泄密扫描。

```powershell
$env:TIHAO_OVERNIGHT_LIVE="false"
npm run overnight:quality
```

限制运行次数：

```powershell
$env:TIHAO_OVERNIGHT_LIVE="false"
$env:TIHAO_OVERNIGHT_MAX_RUNS="5"
npm run overnight:quality
```

## 受控 Live 子集

正式长跑前先跑一个小子集。会消耗真实额度，范围要小。

启动前先跑长跑就绪度审计，确认 live 预检和历史数据审计都满足当前目标：

```powershell
npm run longrun:readiness -- --mode live-subset --preflight <live-preflight-summary.json> --strict
```

```powershell
$env:TIHAO_SESSION_TOKEN="<Parse sessionToken>"
$env:TIHAO_COMPANY="<Company objectId>"
$env:VOC_SOCIAL_TOKEN="<Parse sessionToken>"
$env:VIDEO_ANALYSIS_BASE_URL="https://api.fmode.cn"
$env:VIDEO_ANALYSIS_MODEL="doubao-seed-2-0-pro"
$env:VIDEO_ANALYSIS_TOKEN="<runtime model token>"
$env:TIHAO_OVERNIGHT_LIVE="true"
$env:TIHAO_OVERNIGHT_FIXTURES="dha-mom-baby"
$env:TIHAO_OVERNIGHT_VARIANTS="baseline-live,result-first"
$env:TIHAO_OVERNIGHT_MAX_RUNS="2"
$env:TIHAO_OVERNIGHT_FAIL_ON_GATES="true"
npm run overnight:quality
```

## 完整 Live 矩阵

受控子集通过后再跑完整矩阵。

```powershell
$env:TIHAO_OVERNIGHT_FIXTURES="dha-mom-baby,sensitive-skin-repair,healthy-snack,home-cleaning,618-list-seeding"
$env:TIHAO_OVERNIGHT_VARIANTS="baseline-live,reference-account,homepage-evidence,video-enhanced,result-first,result-first-risk,result-first-broad"
$env:TIHAO_OVERNIGHT_DELAY_MS="1500"
$env:TIHAO_OVERNIGHT_RUN_RETRIES="1"
$env:TIHAO_OVERNIGHT_RESUME="true"
$env:TIHAO_OVERNIGHT_FAIL_ON_GATES="true"
npm run overnight:quality
```

## 常用参数

- `TIHAO_OVERNIGHT_FIXTURES`：指定要跑的 fixture id，用逗号分隔。
- `TIHAO_OVERNIGHT_VARIANTS`：指定策略变体，用逗号分隔。
- `TIHAO_OVERNIGHT_MAX_RUNS`：最多新增执行多少个 run。
- `TIHAO_OVERNIGHT_DELAY_MS`：live run 之间的等待时间。
- `TIHAO_OVERNIGHT_RUN_RETRIES`：live 网络错误时整轮重试次数。
- `TIHAO_OVERNIGHT_RESUME=true`：复用同一输出目录下已有 `quality-summary.json`。
- `TIHAO_OVERNIGHT_FAIL_ON_GATES=true`：发布门禁失败时返回非 0 exit code。
- `TIHAO_GATE_MIN_EVIDENCE_COVERAGE`：有视频证据时的最低证据覆盖率。
- `TIHAO_GATE_MAX_NEGATIVE_RISK_RATE`：最高负样本风险率，默认 10%。兼容旧环境变量 `TIHAO_GATE_MAX_OFF_TOPIC_RATE`。
- `TIHAO_GATE_MAX_SCORE_DROP`：live 模式 top-10 均分相对 baseline 允许下降的最大分数。
- `TIHAO_GATE_REQUIRE_REFERENCE_PROVIDER=true`：`reference-account` 策略必须拿到真实参考补证 provider `ok`，否则门禁失败。
- `TIHAO_GATE_REQUIRE_HOMEPAGE_PROVIDER=true`：`homepage-evidence` 策略必须拿到真实主页最近内容 provider `ok`，否则门禁失败。

严格 provider 门禁只在真实 provider 联调或 live 长跑验收时打开。sample/fallback 环境打开后失败是正常结果，表示不能把 fallback 证据当成真实 provider 证据。

## 输出目录

```text
outputs/overnight-quality-<timestamp>/
  manifest.json
  runs/<brief-id>/<variant>/
  aggregate-summary.json
  aggregate-report.md
  failures.json
  manual-review-sample.csv
```

`manual-review-sample.csv` 已加 UTF-8 BOM，Windows Excel 直接打开应显示中文。

## 证据台账

长跑或复核结束后运行：

```powershell
npm run evidence:index
```

它会扫描 `outputs`，生成 `evidence-index-summary.json` 和 `evidence-index-report.md`，用于区分：

- `real_evidence`：包含 live、客户选择、历史数据或视频 A/B 的真实证明入口；
- `smoke_or_local`：只证明结构、门禁或启动前置条件，例如 `live-preflight` 已就绪；
- `not_business_proof`：明确显示仍缺真实数据或状态未完成。

`live-preflight-summary.json` 会作为 `live-preflight` 类型进入证据台账。它只能证明 sessionToken、company、provider 和视频模型等启动前置条件，不等同于 live 长跑结果或客户效果证明。

## 自动化门禁

必须满足：

- `acceptance.overallPass=true`
- `acceptance.releaseCoveragePass=true`
- `failureCount=0`
- `failedGateCount=0`
- 软件端表重复键为 0。
- 软件端表排名从 1 开始连续。
- 每个 run 都输出主页证据状态。
- 开启严格 provider 门禁时，`reference-account` 的参考补证状态必须为 `ok`。
- 开启严格 provider 门禁时，`homepage-evidence` 的主页证据状态必须为 `ok`。
- live 发布策略有真实召回。
- 发布策略强推荐数不低于 baseline。
- 有视频证据时 top-10 证据覆盖达到门槛。
- 负样本风险率不高于 10%。
- live 模式 top-10 均分相对 baseline 下降不超过门槛。
- token 泄密扫描为 0。

## 策略角色

- `baseline-live`：基线策略，只用于对比。
- `reference-account`：发布候选策略，用于验证参考账号/参考链接补证和相似度链路。
- `homepage-evidence`：发布候选策略，用于验证主页最近内容、封面质感和调性一致性链路。
- `result-first`：发布候选策略，参与发布门禁。
- `result-first-broad`：发布候选策略，参与发布门禁。
- `video-enhanced`：诊断策略，用于观察视频证据影响。
- `result-first-risk`：诊断策略，用于观察风险提示和证据批处理。

诊断策略 warning 需要复盘，但只要每个 Brief 都有通过的发布策略，就不阻断发布验收。

## 人工复核

先打开 `aggregate-report.md` 看整体结果，再打开 `manual-review-sample.csv` 标注“人工复核标签”。夜跑表已预置 `客户选择`、`归因类型`、`反馈原因` 三列，商务不用手动加列。

- 可直接发客户
- 商务复核
- 跑偏
- 硬性规则违规
- 调性不符
- 主页质感不符
- 参考账号不像
- 可投但需补证

如果是负样本，必须填写 `归因类型`：

- 需求解析错
- 隐性规则漏
- 召回关键词错
- 主页证据不足
- 视频证据误判
- 排序权重错
- 输出解释错
- 软件端表重复或排名不连续

如果已经拿到客户最终反馈，在 `客户选择` 列填写：

- 客户选中
- 客户拒绝
- 待客户反馈

人工复核重点：

- top 博主是否真的能给客户解释清楚推荐理由。
- 视频/参考证据是否真的提升了风格调性判断。
- 是否有活动词、明星词、无关品类词污染召回。
- 是否有重复、低质量账号、报价或合规风险。

自动化门禁只证明结构和方向，不能替代最终合规、报价、主页有效性和客户选中率验证。

## 客户效果收口

拿到客户最终反馈和本轮人工补号量后，先跑复核指标，再跑客户效果证明：

```powershell
npm run review:metrics -- --input <已标注CSV> --output <输出目录> --strict
npm run customer-effect:audit -- --review-csv <已标注CSV> --history-audit <historical-dataset-audit.json> --current-manual-supplement-count <本轮人工补号量> --output <输出目录> --strict
npm run evidence:index -- --output outputs\evidence-index-latest
```

如果历史数据是 CSV，可以使用 pipeline 串起历史导入、历史审计、复核指标、客户效果审计和证据台账：

```powershell
npm run optimization:pipeline -- --history-csv <历史数据CSV> --review-csv <已标注CSV> --current-manual-supplement-count <本轮人工补号量> --output <输出目录> --strict
```

客户效果证明必须同时满足：

- 客户选中率 >= 30%。
- 有参考账号/视频时，参考链路客户选中率 >= 40%。
- 长期客户选中率目标 >= 50%。
- 历史人工补号基线存在。
- 本轮人工补号量存在。
- 人工补号量减少率 >= 50%。

缺少任一项时，`customer-effect-summary.json` 会被证据台账标记为 `not_business_proof`，不能宣称客户效果已经达标。