# Tihao SOP 真实 Provider 联调 Runbook

本文档用于拿到真实参考账号补证、VOC social、视频分析或多模态 evidence provider 权限后的联调验收。它不替代默认发布门禁；默认发布门禁仍然是：

```powershell
npm run acceptance
```

真实 provider gate 只有在具备安全测试账号、余额和样本时才运行。

发布红线：不能宣称未验证的 provider 已完成真实接入。没有跑通 `acceptance:providers`，不能说参考补证 provider 已接通；没有跑通 `acceptance:video-ab`，不能说参考视频分析已经证明能提升提号结果。

## 1. 联调目标

真实联调要证明：

- Brief 里的参考链接可以转成可复核的 `referenceBaselines`；
- 候选博主可以获得 `referenceSimilarity`、`referenceFitLevel`、`referenceHitPoints`；
- 视频/图文证据可以写入统一的 `evidenceCards`；
- 报告、JSON、CSV 不泄露 token、Authorization header、上游原始错误或未确认定价；
- 视频分析结果确实能影响召回、评分或重排，而不是只出现在报告里做展示。

## 2. 最小输入清单

运行前准备：

- 一份安全测试 Brief，推荐使用 DHA、敏感肌、清洁、零食等已有 fixture；
- 至少 1 条可访问的参考博主链接，优先选择带视频资源的链接；
- 参考账号补证 provider URL；
- 多模态 evidence provider URL，或 OpenAI 兼容豆包视频分析 URL；
- 如 provider 需要鉴权，准备运行时 token；
- 如要跑 live 候选检索，准备 Tihao `sessionToken` 和 `Company objectId`。

不要把真实 token 写进仓库、Brief、报告或聊天记录。

## 3. 环境变量

PowerShell 示例：

```powershell
$env:SOCIAL_ANALYSIS_BASE_URL="<reference-enrichment-provider-url>"
$env:VOC_SOCIAL_TOKEN="<optional-reference-provider-token>"
$env:TIHAO_EVIDENCE_BASE_URL="<multimodal-evidence-provider-url>"
$env:TIHAO_EVIDENCE_TOKEN="<optional-evidence-provider-token>"
$env:DOUBAO_VISION_BASE_URL="<user-filled-video-analysis-url>"
$env:DOUBAO_VISION_TOKEN="<optional-doubao-vision-token>"
$env:DOUBAO_VISION_MODEL="doubao-seed-2-0-pro"
```

如果使用 Fmode OpenAI 兼容模型网关：

```powershell
$env:DOUBAO_VISION_BASE_URL="https://api.fmode.cn"
$env:DOUBAO_VISION_MODEL="doubao-seed-2-0-pro"
```

该 base URL 会自动请求 `/v1/chat/completions`。token 只能通过运行时环境变量或工具入参提供。

同时验证 live 候选检索时：

```powershell
$env:TIHAO_SESSION_TOKEN="<parse-session-token>"
$env:TIHAO_COMPANY="<company-object-id>"
```

## 4. 本地合同自测

没有真实 provider 时，先跑 mock 合同测试：

```powershell
npm run acceptance:providers:mock
```

通过标准：

- mock reference provider 返回 `referenceBaselines`；
- mock evidence provider 返回 `evidenceCards`；
- 候选结果出现 `referenceSimilarity` 和 `evidenceSignals`；
- mock 豆包请求包含模型 `doubao-seed-2-0-pro`、Authorization、视觉能力和 OpenAI 风格响应解析。

## 5. Live 预检

配置真实 token 或 provider 后，先跑不扣费预检：

```powershell
npm run live:preflight
```

需要阻断长跑时使用严格模式：

```powershell
npm run live:preflight -- --strict
```

预检会输出 `live-preflight-summary.json`，只记录是否配置齐全，不写入 token 明文。

通过标准：

- `session-token-present=pass`；
- `parse-user-resolved=pass`；
- `company-resolved=pass`；
- `video-model-doubao-seed-2-0-pro=pass`；
- 如果要验证视频提升，必须同时有视频分析 base URL 和运行时 token；
- 如果要验证主页最近内容，必须配置真实 homepage provider。

预检通过只说明“可以开始真实测试”，不说明 live 提号或视频分析已经有效。

## 6. 真实 Provider 验收

配置真实 provider 后运行：

```powershell
npm run acceptance:providers
```

通过标准：

- `referenceBaselines.length >= 1`；
- 至少一个候选的 `referenceSimilarity > 0`；
- `evidenceCards.length >= 1`；
- 至少一个候选存在 `evidenceSignals`；
- 结果中不包含 `Authorization: Bearer ...`；
- 结果中不包含任何环境变量 token 明文；
- provider 收到的请求体包含 `contractVersion: "tihao-provider-v1"`；
- reference provider 收到 `referenceLinks`、`referenceStyleAnchors`、`criteria.keywords`；
- evidence provider 收到 `requestedCapabilities`、`criteria.referenceBaselines`、`creators`。

如果没有配置 provider URL，该命令会安全跳过并输出 skip 提示。skip 不是通过真实联调。

## 7. Live 候选检索验收

只有测试账号有额度时运行：

```powershell
npm run live:preflight -- --strict
npm run live:acceptance
```

通过标准：

- 线上 `voc-e-commerce` 返回 200；
- 至少返回一个候选博主；
- Markdown、JSON、CSV 写出成功；
- APIGAuth 扣费链路正常；
- 输出不包含 Parse sessionToken 或 Authorization。

## 8. 参考视频 A/B 验收

用于证明视频分析对提号命中率有帮助：

```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>"
npm run acceptance:video-ab
```

核心判断：

- A 组只跑 live 提号；
- B 组在同一 Brief 上增加 VOC social 视频详情和豆包分析；
- B 组能拿到真实视频 URL、封面、标题、作者、字幕或其他资源；
- B 组必须拿到视频 URL；
- B 组必须拿到封面、ASR/字幕、帧图资源中的至少一类；
- B 组能产出证据卡；
- B 组证据卡不能只是 `pending`、`fallback` 或“待补证据”占位；
- B 组证据卡必须包含 text/ASR/visual/frame 中至少一类可解释信号；
- B 组 top 10 中证据命中候选增加；
- B 组强推荐数量、平均参考风格分、平均总分不得下降；
- 输出不泄露 token。

## 9. 失败处理

- 网络抖动：允许带重试重新跑，不要把一次 TLS 或上游短暂失败当成质量失败。
- 参考链接无法解析：保留原参考链接并写 warning，不能中断整个提号流程。
- 视频资源缺失：证据卡必须标注“待补口播证据”或“待补帧图证据”，不能假装已经分析过帧图/ASR。
- 召回跑偏：禁止把婚礼、宴会、布景、仪式等与 Brief 无关的场景词扩展成 live 召回关键词。

## 10. 交付记录

真实联调完成后，需要沉淀：

- `live-preflight-summary.json`；
- 本次运行目录；
- `aggregate-summary.json` 或对应 summary；
- 是否 `liveEnabled=true`；
- 候选数量、强推荐数量、证据卡数量；
- 是否有 token leak scan 命中；
- 需要人工复核的问题。