tihao-ai/claude-code-tihao-sourcing/docs/live-provider-integration-runbook.md

Tihao SOP 真实 Provider 联调 Runbook

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

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 示例：

$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 兼容模型网关：

$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 候选检索时：

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

4. 本地合同自测

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

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 后，先跑不扣费预检：

npm run live:preflight

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

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 后运行：

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 候选检索验收

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

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

通过标准：

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

8. 参考视频 A/B 验收

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

$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 命中；
• 需要人工复核的问题。