---
name: add-audience
description: 添加受众目标入库：校验受众JSON载荷，登录任务系统后按完整链路（查重→删除同名受众及其关系表→创建受众目标→创建账号关联）调用接口，并如实回报每个接口的入参与调用结果。
allowed-tools:
  - read_file
  - bash
---

# 添加受众目标（完整链路入库）

当且仅当需要把分析产出的受众目标（含关联账号）写入任务系统时使用本 Skill。脚本会自动完成：登录鉴权 → 查重 → 删除同名受众（连带删除 `task-action-pathway-account` 关系表与脆弱点关联）→ 创建受众目标 → 创建账号关联。

## 前置条件

先用 `write_file` 把载荷写到 `/mnt/user-data/outputs/add-audience-payload.json`，结构如下（`targetAudience` 也可写作 `groupName`）：

```json
{
  "taskId": 101,
  "actionId": 201,
  "audienceList": [
    {
      "targetAudience": "18-30岁智能穿戴尝鲜用户",
      "recReason": "对新形态设备接受度高……",
      "userList": [
        {
          "id": "mock_fa_0001",
          "name": "极客评测室GeekBench",
          "platformType": 1,
          "platform": "facebook",
          "dataSource": "target",
          "score": 0.93,
          "metadata": { "...": "完整user对象会整体存入 frofileInfo" }
        }
      ]
    }
  ]
}
```

- `taskId` / `actionId` 必须是整数，等于当前任务与行动 ID。
- `userList` 每项是完整 user 对象：`id`、`name` 必填；`platformType` 写入 accountPlat——缺失时可只给 `platform` 平台名（如 `facebook`、`instagram`），脚本登录后自动查平台字典表（sys-dict-data，dictType=platform）按前端 platformTypeChange 同款规则映射为编码（未识别回退 1，两者都缺则置空）；`accountSource` 优先取 `dataSource`，缺失时回退 `score`；整个对象 JSON 序列化后存入 `frofileInfo`。
- `recReason` 中的 `<n>` 引用标记会被自动清洗，无需预处理。

完整字段定义、账号对象字段表与生成规则，见：

```text
/mnt/skills/public/add-audience/docs/受众JSON生成规范.md
```

（custom 安装时把路径中的 `public` 换成 `custom`；需要生成载荷时，先读该规范再写 JSON。）

## 接口地址与鉴权配置

部署时编辑以下文件（安装到 custom 时把路径中的 `public` 换成 `custom`）：

```text
/mnt/skills/public/add-audience/config/audience_api.json
```

| 配置项 | 说明 |
| --- | --- |
| `base_url` | 任务系统地址（到端口，不带 `/api`），如 `http://192.168.1.11:3912` |
| `username` / `password` | 登录账号（环境变量 `AUDIENCE_API_USERNAME` / `AUDIENCE_API_PASSWORD` 可覆盖） |
| `request.verify_ssl` | **默认 false，已关闭 HTTPS 证书校验**，适配自签名证书内网环境；公网环境建议改回 true |
| `request.timeout_seconds` | 每个请求的超时秒数，默认 30 |

鉴权流程（脚本自动完成）：`POST {base_url}/api/auth/login`（body `{username, password}`）取 `access_token`，后续所有请求附加请求头 `Authorization: Bearer {access_token}`。

## 执行方式

```bash
python /mnt/skills/public/add-audience/scripts/add_audiences.py \
  --json /mnt/user-data/outputs/add-audience-payload.json
```

可加 `--dry-run` 只校验载荷并打印调用计划，不实际发送。环境变量覆盖地址：`AUDIENCE_API_BASE_URL`。

## 结果处理（必须如实转述）

脚本 stdout 是一段 JSON，其中：

- `入参摘要`：本次传入的 taskId/actionId 与每个受众组（名称、清洗后理由、账号数）——**必须告知用户**。
- `calls`：每个接口的 method、url、请求体（密码与 token 已脱敏）、HTTP 状态与响应——**必须汇总告知用户**，特别是删除了哪些同名旧受众及其关系表记录、新建的 designId。
- `groups` / `summary` / `人读摘要`：分组结果与统计。

规则：

- `success: true`：按 `人读摘要` + `groups` 如实汇报新增/删除数量。
- `success: false`：如实说明失败步骤与错误（如登录 401 → 提示检查 config 账号密码），**不要假装调用成功**，也不要静默吞掉失败。
- 不要自己用 curl / requests 逐条调接口替代本 Skill；不要在未执行脚本的情况下宣称"已添加"。

## 同名受众处理策略

与前端行为一致：同名（`targetAudience` 相同）受众已存在时**先删后建**，删除链为：关系表 `task-action-pathway-account`（按 pathwayId 逐条）→ `task-action-design/deleteDesignVulns?designId=` → `task-action-design/{id}`。如用户只想要"跳过已存在"而非覆盖，需在执行前明确说明并由用户决策。