初始化
This commit is contained in:
1 parent
34474bd5fc
commit
b638b541d0
3008 files changed
+837699
No files matched your search
@@ -0,0 +1,91 @@
|
||||
# 受众群体 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` 不是数组(如传了对象或字符串)
|
||||
@@ -0,0 +1,82 @@
|
||||
# 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。
|
||||
Reference in new issue
Block a user