# 提号经验长期优化计划（中文执行版）

本文用于把商务、投放同事的真实提号经验沉淀到 `@vocmarket/tihao` 技能包中，形成可长期复用的工作流、测试方法和验收标准。当前目标不是宣称“已经提升命中率”，而是持续把每一轮真实证据转成可执行规则，并用自动化审计区分真实业务证明、smoke/local 证明和未证明项。

## 核心判断

提号最难的不是粉丝数、预算、地域、互动量这些硬指标，而是：

- 产品理解：识别 Brief 没写明但商务默认知道的隐性规则。
- 参考账号拆解：客户给参考博主时，真正有价值的是账号类型、调性、内容结构、场景和表达方式。
- 主页近期内容判断：人工通常先看主页最近 10-20 篇封面、标题、内容类型和互动，再决定是否深看视频。
- 视频和图文证据：只有拿到视频 URL、封面、字幕、帧图、正文或 ASR，才能声明完成真实分析。
- 商务可解释性：输出必须能让商务向客户解释“为什么推荐”和“哪里需要复核”。

## 当前已具备能力

- Brief 解析和 sample/live 两种模式。
- VOC 电商数据中台 live 调用入口。
- 参考账号、参考链接识别。
- 参考风格指纹和多模态证据卡结构。
- 主页近期内容轻量证据分。
- 美护、母婴 DHA、敏感肌、食品饮料、家清家居、生活方式等品类隐性规则。
- Markdown、JSON、CSV 输出。
- 偏好记忆和反馈导入。
- no-token、额度不足等友好提示。
- 软件端 CSV 固定表头、严格去重、连续排名和 Markdown 表格导出。
- 证据台账：区分 `real_evidence`、`smoke_or_local`、`not_business_proof`。

## 关键差距

| 优先级 | 差距 | 目标 |
| --- | --- | --- |
| P0 | 真实主页近期内容 provider 仍需稳定 | 接入最近 10/20 篇内容、封面、标题、互动、发布时间和风险信号。 |
| P0 | 反馈导入后缺少二轮闭环证明 | 商务标注的拉黑、跑偏、调性不符账号，第二轮必须自动剔除或降权。 |
| P0 | 视频分析对命中率的提升需要真实 A/B 验证 | 对比无视频证据与有视频证据名单质量，不能只看接口 200。 |
| P1 | 参考账号相似链路需要更强 | 小红书优先走相似账号链路；抖音单独走星图、关键词和招募策略。 |
| P1 | 团队规则升级机制不足 | 同类反馈连续出现 3 次以上，才建议升级为团队规则。 |
| P1 | 软件端表格需要持续稳定 | 表头固定、中文不乱码、重复键为 0、排名连续。 |

## 长跑优化任务

### 数据准备

准备 5-10 个真实历史 Brief，覆盖：

- 美容仪、脱毛仪。
- 母婴 DHA。
- 敏感肌、护肤修护。
- 食品饮料、健康零食。
- 家清家居。
- 生活方式、高质感女性场景。

每个 Brief 需要包含：

- 客户原始 Brief。
- 参考账号或参考视频。
- 人工最终提报名单。
- 客户最终选中、拒绝或待反馈记录。
- 拒绝原因或商务复核标签。
- 历史人工补号量基线；如果缺失，只能做流程验证，不能证明人工补号减少。

历史数据可先按 CSV 整理，再转成 JSON 数据集：

```powershell
npm run history:from-csv -- --input <历史数据CSV> --output <history-dataset目录>
npm run history:audit -- --input <history-dataset目录> --output <审计输出目录> --strict
```

### 策略矩阵

每个 Brief 跑以下策略：

| 策略 | 说明 |
| --- | --- |
| baseline-live | 只用基础 live 召回和硬性规则。 |
| reference-account | 增加参考账号拆解和相似度判断。 |
| homepage-evidence | 增加主页最近内容证据。 |
| video-enhanced | 增加参考视频和候选视频证据。 |
| result-first | 先生成结果，再用证据和规则重排。 |
| result-first-broad | 扩大召回池后再重排。 |

### 每轮输出

每轮必须输出：

- `tihao-sourcing-report.md`
- `tihao-sourcing-result.json`
- `tihao-sourcing-client-list.csv`
- 软件端去重表。
- 最新提号表单索引：集中指向补证表单、软件端候选名单和负责人行动文件。
- 重复键统计。
- 人工复核标签统计。
- 失败样本归因。
- 如果汇总多个策略或多个 Brief，必须输出软件端去重表；同一 Brief 内排名从 1 连续。

## 软件端表格验收

固定表头见 `docs/software-client-table-format.md`。

硬性要求：

- CSV 使用 UTF-8 BOM，Excel 打开中文不乱码。
- 表头固定为软件端格式。
- 软件端交付表按“全局博主唯一”去重，同一 `平台 + 规范化主页链接` 不重复。
- 没有主页链接时，同一 `平台 + 规范化博主名称` 不重复。
- 同一博主如被多个 Brief 或多个策略召回，只保留证据更完整、综合分更高的一条进入交付表。
- 已剔除账号不进入软件端交付表。
- 去重和剔除后，排名从 1 开始连续。
- 推荐理由能解释 Brief 匹配、参考风格或主页证据。
- 风险提示能说明具体待复核事项。
- Markdown 表格和 CSV 字段一致，适合软件端或商务文档引用。

## 质量验收标准

### 基础链路

- `npm run acceptance` 通过。
- `npm run acceptance:providers:mock` 通过。
- `npm run smoke:package` 通过。
- 输出不泄露 Parse sessionToken、模型 token、Authorization、npm token。
- live/no-token/403/401 返回友好状态，不暴露原始错误、堆栈或密钥。

### 硬性规则

- 硬性约束违规率 = 0。
- 明确剔除账号不得进入软件端交付表。
- 粉丝、地域、预算、平台不符的账号不得标为强推荐。
- 美容仪、脱毛仪默认偏女性使用场景，男性泛账号不得标为强推荐，除非 Brief 明确允许。
- 多参考账号风格冲突时，不得强行合成一个统一参考标准。

### 风格调性

- 每个强推荐账号至少有 2 条 Brief 命中点。
- 每个强推荐账号至少有 1 条参考风格或主页证据命中点，并在 JSON 中结构化保留 `referenceStyleHitPoints` 或 `homepageEvidenceHitPoints`。
- `需补相似账号证据`、`待补参考风格证据` 等占位提示只能进入 `referenceFallbackHitPoints`，不得写入 `referenceStyleHitPoints`，也不得单独支撑强推荐。
- 候选 JSON 必须保留 `referenceEvidenceConcrete`；强推荐必须有真实参考信号或主页证据，不能只依赖 fallback reference hint。
- 有参考账号时，强推荐必须说明“类型相似”或“调性相似”的依据。
- Top 10 负样本风险率低于 10%。
- 明显下沉、封面混乱、质感不符账号不得标为强推荐；候选 JSON 应保留 `homepageQualityRisks`，风险提示应说明主页质感问题。

### 视频和多模态

- 有参考视频时，必须尝试 VOC social 视频详情和豆包视频分析。
- 拿到视频 URL、封面、字幕、ASR、帧图或正文后，才能声明视频分析完成。
- 没有真实资源时，只能写“待补视频证据”或“待补帧图证据”。
- A/B 测试中，`video-enhanced` 不得低于 baseline：
  - 强推荐数量不下降。
  - Top 10 平均综合分不下降。
  - Top 10 平均参考风格分不下降。
  - 证据命中候选数量增加。
  - 输出 token 泄露为 0。

### 业务效果

短期目标：

- “可直接发客户 + 商务复核”占比达到 60% 以上。
- 负样本率低于 10%。
- 负样本归因覆盖率达到 100%。
- 每个 Brief 至少产出目标数量 1.5 倍的可复核候选。

中期目标：

- 客户选中率达到 30% 以上。
- 有参考账号的 Brief，客户选中率达到 40% 以上。
- 参考账号链路召回的候选，通过率高于纯关键词召回。
- `review:metrics` 必须输出分策略指标和参考链路对照；缺少对照组时，只能标记为待补对照组。

长期目标：

- 客户选中率稳定达到 50% 以上。
- 同等客户需求下，人工补号量减少 50%。
- 每轮客户反馈都能沉淀为规则或偏好，下一轮负样本率下降。

客户效果证明必须使用独立审计：

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

只有 `customer-effect-report.md` 中客户选中率、参考链路客户选中率、历史人工补号基线、本轮人工补号量和人工补号减少率全部通过，才可以声明业务效果达标。

## 给下一轮 AI 的任务

目标：优化 `@vocmarket/tihao` 的提号命中率和商务可用率，让上传 Brief 后能稳定输出商务可复核、可解释、可沉淀的博主名单。

输入：

1. 5-10 个真实历史 Brief。
2. 每个 Brief 的参考账号或参考视频。
3. 人工最终名单和客户最终选中/拒绝记录。
4. 拒绝原因或商务复核标签。
5. 历史人工补号量基线。

任务：

1. 跑 `baseline-live`、`reference-account`、`homepage-evidence`、`video-enhanced`、`result-first`、`result-first-broad` 策略矩阵。
2. 每轮输出 Markdown、JSON、软件端 CSV。
3. 检查重复键、乱码、token 泄露和排名连续性。
4. 对比每个策略的强推荐数量、Top 10 平均分、参考风格分、主页证据覆盖率、人工复核通过率、负样本率。
5. 把失败样本归因为：需求解析错、隐性规则漏、召回关键词错、主页证据不足、视频证据误判、排序权重错、输出解释错、软件端表重复或排名不连续。
6. 每轮只优化一个主要失败原因，重跑矩阵并记录提升。

通过标准：

1. `failureCount=0`。
2. 每个 Brief 至少一个策略通过。
3. leak scan=0。
4. 软件端表重复键为 0。
5. 每个 Brief 排名连续。
6. Top 10 负样本率低于 10%。
7. 负样本归因覆盖率=100%。
8. 人工复核通过率相对 baseline 提升 20% 以上。
9. 有参考账号的 Brief，`reference-account` 或 `homepage-evidence` 策略优于 brief-only。
10. 优化结论能沉淀为明确规则、权重或工作流变更。
11. `customer-effect:audit` 通过；缺少客户选择、历史人工补号基线或本轮人工补号量时，不得宣称客户效果完成。

## 每轮沉淀

每轮结束优先运行：

```powershell
npm run round:refresh -- --output-root outputs --strict
```

刷新后检查 `outputs/latest-form-index-latest/latest-form-index.md`。它只用于定位最新表单和行动文件，不证明客户效果完成。

真实历史数据和客户复核表都到位后，可用 pipeline 串起本地审计闭环：

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

如果商务/投放直接填写的是统一收集包，优先使用 data-pack/video-pack 入口：

```powershell
npm run optimization:pipeline -- --data-pack outputs\data-intake-pack-latest --video-pack outputs\video-intake-pack-latest --current-manual-supplement-count <本轮人工补号量> --output <输出目录> --strict
```

必须记录：

- 运行命令。
- 输出目录。
- 是否 live。
- 是否打开严格 provider 门槛。
- 是否真实视频资源。
- `failureCount`、`failedGateCount`、`overallPass`。
- 软件端重复键和排名连续性。
- 人工复核指标或客户选中率。
- 仍未证明的边界。

如果状态里仍有 `ready_not_proven` 或 `blocked_by_external_data`，不得宣布长期优化目标完成。