# 参考博主证据链优化路线图

本文档用于 Tihao SOP 技能包后续优化和验收。目标是把 Brief 里的参考博主链接，升级成可解释、可复核、能影响排序的证据链，而不是只把链接贴进报告。

真实 provider 联调请按 `docs/live-provider-integration-runbook.md` 执行。没有真实 gate 证据前，只能称为合同验证、mock 验证或待联调能力。

## 1. 当前已落地能力

### Brief 解析

已支持从 Brief 中解析：

```json
{
  "referenceLinks": [],
  "referenceAccounts": [],
  "referenceStyleAnchors": [],
  "referenceSignals": []
}
```

字段含义：

- `referenceLinks`：Brief 里的参考链接，例如小红书、抖音、B 站链接；
- `referenceAccounts`：用户直接给出的参考账号名、redId、userId 或账号描述；
- `referenceStyleAnchors`：把参考链接归类为干货科普、618 合集、图文、视频等上下文；
- `referenceSignals`：从参考区提取风格词，例如育婴师、营养师、真实测评、清单推荐、成分党。

### 排序与报告

已接入：

- `referenceSignals` 参与候选内容和风格匹配；
- 候选结果带 `referenceMatchedSignals`；
- 传入 `referenceBaselines` 或 `referenceBaselinePath` 后，候选带 `referenceSimilarity`、`referenceFitLevel`、`referenceHitPoints`；
- Markdown 报告包含“参考视频风格指纹”“多模态证据卡”“商务可用名单”“剔除/降级原因”等章节；
- CSV/JSON 保留证据字段，方便人工复核。

### 偏好记忆

已支持：

- `preferredReferenceAccounts`；
- `blockedCreators`；
- 客户反馈中的“像某某账号”“不要某类账号”可以沉淀为下一轮提号偏好。

## 2. VOC social 参考账号补证

目标：把 Brief 中的参考链接升级为参考账号基线，而不是只看链接文本。

建议处理链路：

1. 解析短链，得到最终笔记或视频 URL；
2. 提取 noteId / awemeId / userId 等平台标识；
3. 查询笔记或视频详情，得到作者、标题、内容类型和视频资源；
4. 查询作者主页，得到粉丝、简介、地区、认证等信息；
5. 查询作者近作，得到标题、描述、互动、发布时间；
6. 生成 `referenceBaselines`；
7. 将基线写入排序、报告和复核 CSV。

Provider 输入建议：

```json
{
  "referenceEnrichmentBaseUrl": "https://<provider>",
  "referenceEnrichmentPath": "reference-baselines",
  "socialAnalysisToken": "<runtime optional token>",
  "referencePostsLimit": 20
}
```

约定：

- provider 接收 `referenceLinks`、`referenceAccounts`、`referenceStyleAnchors`；
- provider 返回 `referenceBaselines` 数组；
- provider 失败、401、403、网络错误或空结果都不能中断提号，只能写 warning，并保留原参考链接。

## 3. 视频证据链

当参考账号或候选账号的关键样本是视频时，不能只看标题和简介，需要补充画面、口播、字幕和产品露出证据。

推荐链路：

```text
视频/笔记详情
-> 读取视频 URL、封面、字幕或可下载资源
-> 抽帧
-> ASR 转写
-> 豆包视觉/多模态分析
-> evidenceCards
-> 排序、重排、报告复核
```

证据卡至少包含：

- 命中的 Brief 需求；
- 命中的参考风格；
- 画面或口播依据；
- 风险提示；
- 对候选排序的影响；
- 缺失证据时的人工复核提示。

真实性保护：

- 模型返回的风格结论不能冒充 ASR 或帧图证据；
- 没有 transcript 时标注“待补口播证据”；
- 没有 frame/resource 时标注“待补帧图证据”；
- 证据卡不得写入 token 或 Authorization。

## 4. 对命中率的提升路径

优先优化顺序：

1. Brief 关键词召回：从品类、人设、场景、内容形态、节点词扩展，但过滤跑偏事件词。
2. 参考风格召回：用参考视频指纹补充“DHA 专业科普”“清单推荐”“真实测评”等与 Brief 绑定的关键词。
3. 预排序：先用数据质量、Brief 匹配、预算、风险筛出高潜候选。
4. 证据分析：优先分析预排序前列候选，结果优先服务重排。
5. 重排与降级：证据命中可升级；混类、竞品、预算、合规风险必须降级。
6. 人工复核：把不确定项写进 CSV，让商务能标注“命中/跑偏/待复核/不可投”。

## 5. 验收标准

技术验收：

- `npm run acceptance` 通过；
- `npm run acceptance:providers:mock` 通过；
- 有真实权限时 `npm run acceptance:providers` 通过；
- 有真实 token 和模型 token 时 `npm run acceptance:video-ab` 通过；
- 输出文件 token leak scan 为 0。

质量验收：

- 每个 Brief 至少有一个发布策略通过；
- 强推荐数量不低于基线；
- top 10 平均分不低于基线；
- 证据覆盖率达到目标；
- 负样本风险率为 0 或可解释并降级；
- top 博主能用 Brief 匹配和参考风格证据解释给客户。

业务验收：

- 商务打开 Markdown 能直接看到推荐名单、推荐原因、风险和复核建议；
- Excel 直接打开 CSV 不乱码；
- 人工复核 CSV 有中文列名和“人工复核标签”列；
- 首轮输出明确是“初步判断/机会假设/待校准名单”。