# add-audience 技能 · 安装与调用说明

把「添加受众目标」的完整接口链路封装给大模型调用：模型写好受众 JSON → 脚本登录任务系统 → 自动执行查重、删除同名（含关系表）、创建受众与账号关联 → 把每个接口的入参与调用结果如实回报给用户。

## 一、安装

**方式 A（推荐）**：在技能管理界面上传 `add-audience.skill`（本质是 zip，内含 `add-audience/` 目录：SKILL.md + config + scripts）。

**方式 B（手工）**：把 `add-audience/` 目录解压到 DeerFlow 后端的 `skills/custom/` 下，然后调用一次 `POST /skills/reconcile-custom` 收编注册。

安装后技能名：`add-audience`。若安装到 public，文档中的 `/mnt/skills/custom/...` 路径对应换成 `/mnt/skills/public/...`。

## 二、配置（config/audience_api.json）

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `base_url` | `http://127.0.0.1:4913` | 任务系统地址（到端口，不带 `/api`）；按实际环境修改，如 `http://192.168.1.11:3912` |
| `username` / `password` | `admin` / `ch@user` | 登录账号，取自前端登录页写死的默认值，可自行修改 |
| `auth.*` | `/api/auth/login` + `Authorization: Bearer {token}` | 登录路径、token 字段与请求头拼装规则，一般不用动 |
| `endpoints.*` | `/api/task/task-action-design` 等 | 完整链路涉及的全部接口路径 |
| `request.verify_ssl` | `false` | **已关闭 HTTPS 证书校验**，适配自签证书内网；公网环境建议改 `true` |
| `request.timeout_seconds` | `30` | 单请求超时 |

环境变量覆盖：`AUDIENCE_API_BASE_URL`、`AUDIENCE_API_USERNAME`、`AUDIENCE_API_PASSWORD`、`AUDIENCE_API_VERIFY_SSL`。

## 三、鉴权与请求头

1. 脚本先 `POST {base_url}/api/auth/login`，请求体 `{"username": "...", "password": "..."}`；
2. 从响应取 `access_token`；
3. 后续所有业务请求附加请求头 `Authorization: Bearer {access_token}`（即 `auth.header_name` + `auth.header_template`）。

证书校验通过 Python ssl 上下文关闭（`verify_ssl=false` 时），HTTPS 自签名证书可直接访问。

## 四、完整调用链

对载荷中的每个受众组依次执行：

| 步骤 | 接口 | 说明 |
| --- | --- | --- |
| 1 | `POST /api/auth/login` | 登录换 token |
| 2 | `GET /api/task/task-action-design?filter=taskId&filter=actionId` | 查当前行动下已有受众（查重） |
| 3a | `GET /api/task/task-action-design-pathway-relation?filter=actionId` | 查关系表，找同名受众的 pathwayId |
| 3b | `DELETE /api/task/task-action-pathway-account/{pathwayId}` | **逐条删除关系表记录**（同名时） |
| 3c | `DELETE /api/task/task-action-design/deleteDesignVulns?designId={id}` | 删除受众关联脆弱点（同名时） |
| 3d | `DELETE /api/task/task-action-design/{id}` | 删除同名旧受众本身 |
| 4 | `POST /api/task/task-action-design` | 创建受众目标，`parentTargetAudience` 固定 `大模型生成`，`recReason` 自动清洗 `<n>` 引用标记 |
| 5 | `POST /api/task/task-action-design-account`（每账号一次） | 字段映射：`accountId←user.id`、`accountName←user.name`、`accountPlat←user.platformType`、`accountSource←user.dataSource`（缺失回退 `user.score`）、`frofileInfo←整个user对象JSON`、`designId←步骤4返回id` |

## 五、载荷格式

```json
{
  "taskId": 101,
  "actionId": 201,
  "audienceList": [
    {
      "targetAudience": "18-30岁智能穿戴尝鲜用户",
      "recReason": "对新形态设备接受度高……",
      "userList": [ { "id": "...", "name": "...", "platformType": 1, "dataSource": "target", "...": "完整user对象" } ]
    }
  ]
}
```

`targetAudience` 也可写作 `groupName`（对齐前端对话链路字段名）。

## 六、输出与验证

脚本 stdout 输出单段 JSON：

- `入参摘要`：taskId/actionId 与各受众组（名称、清洗后理由、账号数）
- `calls`：每个接口的 method/url/请求体（密码、token 脱敏）/HTTP 状态/响应
- `groups`：每组结果（designId、新增账号数、删除的旧受众及关系表记录数）
- `summary` / `人读摘要`：统计与人读结论

验证是否真正入库：`GET {base_url}/api/task/task-action-design?filter=taskId||$eq||{taskId}` 与 `.../task-action-design-account?...` 应能看到新建记录。

## 七、注意事项

- 密码明文存于 config，部署环境请控制文件访问权限，或改用环境变量注入。
- 同名受众默认「先删后建」（与前端对话链路一致）；需要跳过语义时应先改造脚本再加策略参数。
- 业务失败（如创建受众返回非 201）时脚本继续处理其余受众组，整体 `success=false`，退出码 2；登录失败立即退出，退出码 1。