# 真实历史提号数据集准备指南

本文档用于准备长期优化所需的真实历史样本。只有具备真实 Brief、人工最终名单、客户最终选择和拒绝原因，才能验证客户选中率和人工补号量是否真的改善。

## 目录结构

建议放在一个独立目录，不要把 token 或客户敏感报价写入文件：

```text
history-dataset/
  dha-2026-05.json
  skincare-2026-05.json
  home-cleaning-2026-05.json
```

验收命令：

```powershell
npm run history:audit -- --input <history-dataset目录> --output <输出目录> --strict
```

默认要求至少 5 个真实 Brief。小范围试跑可以加：

```powershell
npm run history:audit -- --input <history-dataset目录> --min-briefs 3
```

## 从 CSV 生成 JSON 数据集

商务可以先用 CSV/Excel 整理历史样本，再转换成 `history:audit` 可读取的 JSON 数据集。

如果需要先生成可直接填写的收集包，运行：

```powershell
npm run data:intake-template -- --output outputs\data-intake-pack-latest
```

会生成：

```text
outputs/data-intake-pack-latest/history-data-template.csv
outputs/data-intake-pack-latest/manual-review-template.csv
outputs/data-intake-pack-latest/README.md
```

其中 `history-data-template.csv` 用于整理历史 Brief，`manual-review-template.csv` 用于整理本轮 AI 名单、商务复核、客户选择和本轮人工补号量。

CSV 表头建议：

```text
brief编号,项目名称,类目,客户原始Brief,历史人工补号量基线,参考账号或视频,平台,博主名称,主页链接,人工复核标签,客户选择,拒绝原因
```

一行代表一个历史提报账号；同一个 `brief编号` 的多行会自动合并成一个历史 Brief。

转换命令：

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

字段说明：

- `brief编号`：必填，同一项目多行保持一致。
- `客户原始Brief`：必填，写客户原始需求，不要写 token 或敏感报价。
- `历史人工补号量基线`：如需证明人工补号减少 50%，必须填写。
- `参考账号或视频`：多个链接可用中文或英文分号分隔。
- `客户选择`：填写 `客户选中`、`客户拒绝`、`通过`、`未选` 等。
- `拒绝原因`：客户拒绝或跑偏时必须填写。

## JSON 模板

```json
{
  "id": "dha-2026-05",
  "name": "某客户 DHA 五月提号",
  "category": "母婴",
  "briefText": "客户原始 Brief 文本，包含平台、预算、粉丝、人群、参考账号、排除项等。",
  "manualSupplementBaseline": 6,
  "referenceLinks": [
    {
      "url": "https://example.com/reference-video",
      "platform": "xiaohongshu",
      "contentType": "video"
    }
  ],
  "manualFinalList": [
    {
      "platform": "小红书",
      "creatorName": "营养师妈妈",
      "profileUrl": "https://example.com/creator-a",
      "manualReviewLabel": "可直接发客户",
      "customerDecision": "客户选中"
    },
    {
      "platform": "小红书",
      "creatorName": "泛生活方式号",
      "profileUrl": "https://example.com/creator-b",
      "manualReviewLabel": "跑偏",
      "customerDecision": "客户拒绝",
      "rejectReason": "客户认为账号人设太泛，不能承接母婴 DHA"
    }
  ],
  "customerFeedback": [
    {
      "creatorName": "营养师妈妈",
      "finalDecision": "客户选中",
      "reason": "客户认可营养师人设和清单结构"
    },
    {
      "creatorName": "泛生活方式号",
      "finalDecision": "客户拒绝",
      "rejectReason": "账号内容方向跑偏"
    }
  ]
}
```

## 必填要求

- 每个样本必须有 `id` 或 `name`。
- 每个样本必须有客户原始 `briefText`。
- 每个样本必须有 `manualFinalList`，即人工最终提报名单。
- 每个样本必须有客户最终选中/拒绝记录，可以写在 `manualFinalList.customerDecision` 或 `customerFeedback.finalDecision`。
- 有拒绝或跑偏时，必须提供 `rejectReason`、`feedbackReason` 或 `reason`。
- 如需证明“人工补号量减少 50%”，必须提供 `manualSupplementBaseline`、`manualSupplementCount` 或 `manualAddedCount` 任一字段，表示该历史 Brief 人工补号量基线。
- 推荐覆盖至少 3 个类目；完整长期验证建议 5-10 个真实 Brief。

## 验收口径

`history:audit` 输出：

- `historical-dataset-audit.json`
- `historical-dataset-audit.md`

只有报告里显示“可用于长期优化长跑=是”，才适合拿来验证：

- 客户选中率 30%/50%；
- 有参考账号 Brief 的通过率；
- 参考账号链路相对关键词召回是否更好；
- 每轮反馈是否让下一轮负样本率下降；
- 人工补号量是否减少。

没有客户最终选择字段时，只能验证商务复核通过率，不能宣称客户选中率达标。
没有人工补号量基线时，可以做长期优化长跑，但不能宣称人工补号量减少 50% 达标。

## 客户效果证明命令

当 `history:audit` 输出的 `historical-dataset-audit.json` 显示 `readyForCustomerEffectProof=true` 后，再用商务标注后的 CSV 做客户效果审计：

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

输出文件：

```text
customer-effect-summary.json
customer-effect-report.md
```

验收标准：

- 客户选中率 >= 30%。
- 长期客户选中率 >= 50%。
- 参考链路客户选中率 >= 40%。
- 历史人工补号量基线存在。
- 本轮人工补号量存在。
- 人工补号量减少率 >= 50%。

如果本轮人工补号量已经写在 CSV 中，可以使用 `本轮人工补号量`、`当前人工补号量`、`人工补号量` 或 `manualSupplementCount` 列，不必再传 `--current-manual-supplement-count`。