# 受众群体 JSON 生成规范（add-audience 载荷）

本规范规定大模型生成「受众群体入库载荷」时的 JSON 格式。生成后写入文件，交由 `scripts/add_audiences.py --json <文件>` 执行入库。

## 一、整体结构

```json
{
  "taskId": 101,
  "actionId": 201,
  "audienceList": [
    {
      "targetAudience": "18-30岁智能穿戴尝鲜用户",
      "recReason": "对新形态设备接受度高<2>，预热期讨论参与意愿强，是首发销量的核心贡献人群",
      "userList": [
        {
          "id": "mock_fa_0001",
          "name": "极客评测室GeekBench",
          "platformType": 1,
          "platform": "facebook",
          "followers_count": 285200,
          "interactions": 12713,
          "issue": "真无线耳机;手机周边;数码开箱;",
          "dataSource": "target",
          "score": 0.9276,
          "page_content": "数码科技领域创作者「极客评测室GeekBench」……",
          "metadata": {
            "screen_name": "极客评测室GeekBench",
            "user_id": "mock_fa_0001",
            "平台": "facebook",
            "发文": [],
            "用户画像": { "粉丝数": 285200, "内容垂类": "数码科技" }
          }
        }
      ]
    }
  ]
}
```

## 二、字段定义

### 顶层

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `taskId` | integer | ✅ | 当前任务 ID。**必须取自用户上下文/前端传入，禁止编造**；未知时先向用户询问 |
| `actionId` | integer | ✅ | 当前行动 ID。同上 |
| `audienceList` | array | ✅ | 受众组数组，**至少 1 项**；按推荐优先级排序（S 级在前） |

### audienceList 每项

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetAudience` | string | ✅ | 受众群体名称。去掉首尾空格后非空；**同一载荷内不得重名**；简洁（建议 ≤ 20 字），如「中高端降噪耳机通勤党」。不要写 `groupName`，统一用本字段 |
| `recReason` | string | 推荐 | 入选理由，一两句话。文本中的 `<数字>` 引用标记、顿号、「引用」、空括号会被脚本自动清洗，无需预处理；但也不要故意堆这些符号 |
| `userList` | array | ✅ | 该群体关联的账号数组，**必须为数组**（允许空数组 `[]`，表示只建群体不挂账号） |

### userList 每项（账号对象）

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string\|number | ✅ | 账号唯一标识 → 写入接口字段 `accountId` |
| `name` | string | ✅ | 账号名 → 写入 `accountName` |
| `platformType` | integer | 建议 | 平台编码 → 写入 `accountPlat`（facebook=1、x=2、instagram=3、threads=5、youtube=6、tiktok=7） |
| `platform` | string | 建议 | 平台名（供人读） |
| `followers_count` | integer | 建议 | 粉丝数 |
| `interactions` | integer | 可选 | 近 30 天均篇互动 |
| `issue` | string | 可选 | 关注话题串，如 `"真无线耳机;数码评测;"` |
| `dataSource` | string | 建议 | 数据来源（`target` / `social` / `AI_LLM`）→ 优先写入 `accountSource` |
| `score` | number 0-1 | 可选 | 相关度分数；**仅当无 `dataSource` 时**作为 `accountSource` 的回退值 |
| `page_content` | string | 建议 | 账号描述正文 |
| `metadata` | object | 强烈建议 | 完整画像对象（`用户画像`、`发文` 等）。**整个 user 对象会原样 JSON 序列化存入 `frofileInfo`**，字段越全，后续页面回显与二次分析越完整 |

## 三、生成规则（生成侧模型必须遵守）

1. **账号必须来自真实数据源**：`userList` 的账号对象必须从账号池（如 `product-account-matching` 技能的 `accounts.json`，用 `query_accounts.py --full` 取完整档案）或对话引用中**原样复制**，禁止虚构 id/name/粉丝数等任何字段。
2. **ID 不编造**：`taskId` / `actionId` 只能取自当前对话上下文；用户没给就先问，不要猜。
3. **同名覆盖语义要告知**：目标系统里已存在同名 `targetAudience` 时，执行脚本会**先删除旧受众（连带其传播节点关系表与脆弱点关联）再新建**。生成前如已知会覆盖，需在回复中向用户说明。
4. **群体划分有依据**：`targetAudience` 的划分角度（垂类/场景/人群）与 `recReason` 的理由需与账号池数据（内容垂类、关注话题、发文、受众画像）对得上，理由中可引用具体账号名。
5. **输出为纯 JSON**：写入 `.json` 文件时最外层就是对象，不要包裹 markdown 代码块、注释或多余文本。
6. **数量适中**：单次建议 2-6 个受众组，每组 3-15 个账号；超出时按 `score` 与推荐优先级裁剪。

## 四、校验失败常见原因

脚本会前置校验载荷，以下错误会直接退出（不做任何写入）：

- `taskId` / `actionId` 不是整数（如传了 `"101"` 字符串）
- `audienceList` 为空或缺失
- 某组 `targetAudience`（或 `groupName`）为空/纯空格
- 某组 `userList` 不是数组（如传了对象或字符串）