初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

@@ -0,0 +1,95 @@
---
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}`。如用户只想要"跳过已存在"而非覆盖,需在执行前明确说明并由用户决策。
@@ -0,0 +1,32 @@
{
"_note": "添加受众技能接口配置。base_url 填任务系统完整服务地址(到端口即可,不带 /api);username/password 为登录账号(默认取登录页写死的 admin/ch@user);verify_ssl=false 时关闭 HTTPS 证书校验(自签名证书内网环境用)。环境变量可覆盖:AUDIENCE_API_BASE_URL / AUDIENCE_API_USERNAME / AUDIENCE_API_PASSWORD / AUDIENCE_API_VERIFY_SSL。",
"base_url": "http://127.0.0.1:4913",
"username": "admin",
"password": "ch@user",
"auth": {
"login_path": "/api/auth/login",
"token_field": "access_token",
"header_name": "Authorization",
"header_template": "Bearer {token}"
},
"endpoints": {
"login": "/api/auth/login",
"platform_dict": "/api/sys/sys-dict-data",
"design_list": "/api/task/task-action-design",
"design_create": "/api/task/task-action-design",
"design_delete": "/api/task/task-action-design",
"delete_design_vulns": "/api/task/task-action-design/deleteDesignVulns",
"pathway_relation_list": "/api/task/task-action-design-pathway-relation",
"pathway_account_delete": "/api/task/task-action-pathway-account",
"design_vulns_list": "/api/task/task-action-design-vulns",
"design_account_create": "/api/task/task-action-design-account"
},
"request": {
"timeout_seconds": 30,
"verify_ssl": false,
"extra_headers": {}
}
}
@@ -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。
@@ -0,0 +1,401 @@
# -*- coding: utf-8 -*-
"""
添加受众目标入库脚本(完整链路)。
链路(与前端 block-chat-audience.taskAddActionDesign / audience-content.taskActionDesignDel 一致):
1. POST {login} 登录换取 access_token(Authorization: Bearer)
2. GET {design_list}?filter=taskId&filter=actionId 查询当前行动下已有受众(查重)
3. 同名受众存在时执行删除链:
GET {pathway_relation_list}?filter=actionId 找出该受众的 pathwayId(关系表)
DELETE {pathway_account_delete}/{pathwayId} 删关系表 task-action-pathway-account
DELETE {delete_design_vulns}?designId={id} 删受众关联脆弱点
DELETE {design_delete}/{id} 删受众目标本身
4. POST {design_create} 创建受众目标(parentTargetAudience=大模型生成)
5. POST {design_account_create} ×N 逐个创建受众-账号关联
用法:
python add_audiences.py --json payload.json [--dry-run] [--config ../config/audience_api.json]
payload.json 结构:
{
"taskId": 101,
"actionId": 201,
"audienceList": [
{ "targetAudience": "群体名", // 也可用 groupName
"recReason": "推荐理由", // 会自动清洗 <n> 引用标记
"userList": [ {完整user对象} ] } // 取 id/name/platformType/dataSource/score,整个对象进 frofileInfo
]
}
输出:一段 JSON(stdout),包含每个接口的入参与调用结果(密码与 token 已脱敏),
以及分组结果与汇总,供模型如实转述给用户。
"""
import argparse
import copy
import json
import os
import re
import ssl
import sys
import urllib.error
import urllib.parse
import urllib.request
DEFAULT_CONFIG = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "config", "audience_api.json")
# 环境变量覆盖名
ENV_OVERRIDES = {
"base_url": "AUDIENCE_API_BASE_URL",
"username": "AUDIENCE_API_USERNAME",
"password": "AUDIENCE_API_PASSWORD",
"verify_ssl": "AUDIENCE_API_VERIFY_SSL",
}
def load_config(path: str) -> dict:
cfg = json.loads(open(path, encoding="utf-8").read())
for key, env in ENV_OVERRIDES.items():
if os.environ.get(env):
raw = os.environ[env]
if key == "verify_ssl":
cfg.setdefault("request", {})
cfg["request"]["verify_ssl"] = raw.lower() in ("1", "true", "yes")
else:
cfg[key] = raw
# 兼容 "$ENV_VAR" 占位值写法
def resolve(v):
if isinstance(v, str) and v.startswith("$") and re.fullmatch(r"\$[A-Z0-9_]+", v):
return os.environ.get(v[1:], "")
return v
def walk(o):
if isinstance(o, dict):
return {k: walk(v) for k, v in o.items()}
if isinstance(o, list):
return [walk(v) for v in o]
return resolve(o)
return walk(cfg)
def clean_reason(text) -> str:
"""复刻前端 recReason 清洗:<n> 引用标记、顿号、「引用」、空括号。"""
if not isinstance(text, str):
return ""
text = re.sub(r"<(\d+)>", "", text)
return text.replace("、", "").replace("引用", "").replace("()", "")
def platform_type_change(platform, options):
"""
平台名/别名 → 平台字典编码(写入 task-action-design-account.accountPlat)。
移植自前端 chat-data.utils.platformTypeChange:子串匹配 fb / x|witter / in / re / th → 字典 label
命中取 value;否则 label 全量小写精确匹配;仍匹配不到回退 1(facebook,与前端一致)。
options 形如 [{"label": "facebook", "value": 1}, ...],来自 sys-dict-data 的 platform 字典。
技能侧扩展:入参已是编码(int 或纯数字字符串)时原样透传;完全缺失(None/空)返回 None(不臆造)。
"""
if platform is None or (isinstance(platform, str) and not platform.strip()):
return None
if isinstance(platform, bool):
return None
if isinstance(platform, int):
return platform
if isinstance(platform, str) and platform.strip().isdigit():
return int(platform.strip())
low = str(platform).strip().lower()
def val(*labels):
for lab in labels:
for o in options:
if str(o.get("label", "")).strip().lower() == lab and o.get("value") is not None:
return o.get("value")
return None
if "fb" in low:
return val("facebook") or 1
if "x" in low or "witter" in low:
return val("x(twitter)", "x") or 1
if "in" in low:
return val("instagram") or 1
if "re" in low:
return val("reddit") or 1
if "th" in low:
return val("threads") or 1
for o in options:
if str(o.get("label", "")).strip().lower() == low and o.get("value") is not None:
return o.get("value")
return 1
class ApiClient:
def __init__(self, cfg: dict, dry_run: bool = False):
self.base = cfg["base_url"].rstrip("/")
self.cfg = cfg
self.dry_run = dry_run
self.headers = {"Content-Type": "application/json"}
self.headers.update(cfg.get("request", {}).get("extra_headers") or {})
self.timeout = cfg.get("request", {}).get("timeout_seconds", 30)
verify = cfg.get("request", {}).get("verify_ssl", True)
self.ctx = ssl.create_default_context() if verify else ssl._create_unverified_context()
self.calls = []
def _log(self, step, method, url, request, status, response):
self.calls.append({
"step": step, "method": method, "url": url,
"request": request, "response": {"status": status, "body": response},
})
def request(self, step, method, path, query=None, body=None, auth=True):
"""执行一次 HTTP 请求并记录。返回 (status, 解析后的响应)。"""
url = self.base + path
if query:
url += "?" + urllib.parse.urlencode(query, doseq=True)
payload = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
display_body = self._redact(copy.deepcopy(body))
req_headers = dict(self.headers)
if auth:
req_headers[self.cfg["auth"]["header_name"]] = "***已附带鉴权头***"
if self.dry_run:
self._log(step, method, url, {"query": query, "body": display_body}, 0, "[dry-run] 未实际发送")
return 0, None
req = urllib.request.Request(url, data=payload, method=method)
for k, v in req_headers.items():
if v == "***已附带鉴权头***":
req.add_header(k, self._auth_header_value())
else:
req.add_header(k, v)
try:
with urllib.request.urlopen(req, timeout=self.timeout, context=self.ctx) as resp:
status, text = resp.status, resp.read().decode("utf-8", "replace")
except urllib.error.HTTPError as e:
status, text = e.code, e.read().decode("utf-8", "replace")
except Exception as e: # 网络层错误
self._log(step, method, url, {"query": query, "body": display_body}, -1, str(e))
raise
try:
parsed = json.loads(text) if text else None
except ValueError:
parsed = text[:300]
self._log(step, method, url, {"query": query, "body": display_body}, status, parsed if not isinstance(parsed, str) else parsed)
return status, parsed
def _auth_header_value(self) -> str:
return self.cfg["auth"]["header_template"].format(token=getattr(self, "token", ""))
@staticmethod
def _redact(body):
if isinstance(body, dict):
for k in list(body.keys()):
if k in ("password",):
body[k] = "***"
return body
def ep(cfg, key) -> str:
return cfg["endpoints"][key]
def main():
parser = argparse.ArgumentParser(description="添加受众目标(完整链路:登录→查重→删同名及关系表→建受众→建账号关联)")
parser.add_argument("--json", required=True, help="载荷 JSON 文件路径")
parser.add_argument("--config", default=DEFAULT_CONFIG, help="接口配置文件路径")
parser.add_argument("--dry-run", action="store_true", help="只校验与打印调用计划,不实际发送")
args = parser.parse_args()
result = {
"success": False, "dry_run": args.dry_run,
"配置": {}, "入参摘要": {}, "登录": None, "groups": [], "summary": {}, "error": None,
}
try:
cfg = load_config(args.config)
except Exception as e:
result["error"] = f"配置加载失败:{e}"
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
# ---- 载荷校验 ----
try:
payload = json.loads(open(args.json, encoding="utf-8").read())
except Exception as e:
result["error"] = f"载荷 JSON 读取失败:{e}"
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
task_id = payload.get("taskId")
action_id = payload.get("actionId")
groups_in = payload.get("audienceList") or []
errors = []
if not isinstance(task_id, int) or not isinstance(action_id, int):
errors.append("taskId / actionId 必须为整数")
if not groups_in:
errors.append("audienceList 不能为空")
for i, g in enumerate(groups_in):
name = (g.get("targetAudience") or g.get("groupName") or "").strip()
if not name:
errors.append(f"audienceList[{i}] 缺少群体名(targetAudience/groupName)")
if not isinstance(g.get("userList"), list):
errors.append(f"audienceList[{i}] 缺少 userList 数组")
if errors:
result["error"] = "载荷校验失败:" + ";".join(errors)
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
result["配置"] = {
"base_url": cfg["base_url"], "username": cfg["username"],
"verify_ssl": cfg.get("request", {}).get("verify_ssl", True),
"timeout_seconds": cfg.get("request", {}).get("timeout_seconds", 30),
}
result["入参摘要"] = {
"taskId": task_id, "actionId": action_id,
"audienceList": [
{"targetAudience": (g.get("targetAudience") or g.get("groupName", "")).strip(),
"recReason清洗后": clean_reason(g.get("recReason", "")),
"账号数": len(g.get("userList") or [])}
for g in groups_in
],
}
client = ApiClient(cfg, dry_run=args.dry_run)
# ---- 1. 登录 ----
login_status, login_resp = client.request("登录", "POST", ep(cfg, "login"),
body={"username": cfg["username"], "password": cfg["password"]}, auth=False)
if login_status not in (200, 201):
result["登录"] = f"失败(HTTP {login_status})"
result["error"] = f"登录失败:HTTP {login_status},请检查 config/audience_api.json 的 base_url 与账号密码"
result["calls"] = client.calls
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
token = (login_resp or {}).get(cfg["auth"]["token_field"]) if isinstance(login_resp, dict) else None
if not token:
result["登录"] = "失败(响应中无 " + cfg["auth"]["token_field"] + ")"
result["error"] = f"登录响应缺少 {cfg['auth']['token_field']} 字段:{login_resp}"
result["calls"] = client.calls
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
client.token = token
result["登录"] = f"成功(已获取 {cfg['auth']['token_field']},后续请求头 {cfg['auth']['header_name']}: {cfg['auth']['header_template']})"
# ---- 1.5 平台字典(platform 名称/别名 → 字典编码,写入 accountPlat 前映射;与前端 platformTypeChange 同款) ----
platform_options = []
dict_status, dict_resp = client.request("查询平台字典", "GET", ep(cfg, "platform_dict"),
query={"filter": ["dictType||$eq||platform"], "limit": 99999})
dict_rows = (dict_resp or {}).get("data") or [] if isinstance(dict_resp, dict) else []
if dict_status == 200:
platform_options = [
{"label": r.get("dictLabel"), "value": int(str(r["dictValue"]).strip())}
for r in dict_rows
if r.get("dictValue") is not None and str(r.get("dictValue")).strip().lstrip("-").isdigit()
]
result["平台字典"] = (
f"已加载 {len(platform_options)} 项:"
+ "、".join(f"{o['label']}={o['value']}" for o in platform_options)
)
else:
result["平台字典"] = f"查询失败(HTTP {dict_status}),平台名只能按子串规则映射且未命中回退 1,建议检查字典表"
# ---- 2. 查询已有受众(查重) ----
q = {"filter": [f"taskId||$eq||{task_id}", f"actionId||$eq||{action_id}"], "limit": 99999}
status, designs_resp = client.request("查询已有受众", "GET", ep(cfg, "design_list"), query=q)
designs = (designs_resp or {}).get("data") or [] if isinstance(designs_resp, dict) else []
if status != 200:
result["error"] = f"查询已有受众失败:HTTP {status}"
result["calls"] = client.calls
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(1)
# 关系表(一次查出整个行动的 pathway 关联)
rel_status, rel_resp = client.request("查询受众-传播节点关系表", "GET", ep(cfg, "pathway_relation_list"),
query={"filter": [f"actionId||$eq||{action_id}"], "limit": 99999})
relations = (rel_resp or {}).get("data") or [] if isinstance(rel_resp, dict) else []
summary = {"新增受众": 0, "新增账号关联": 0, "删除同名旧受众": 0, "删除关系表记录": 0, "删除脆弱点关联": 0}
all_ok = True
for g in groups_in:
name = (g.get("targetAudience") or g.get("groupName")).strip()
group = {"targetAudience": name, "designId": None, "新增账号": 0, "deletedOld": [], "ok": False, "error": None}
# ---- 3. 同名删除链 ----
for old in [d for d in designs if str(d.get("targetAudience", "")).strip() == name]:
old_id = old.get("id")
pathway_ids = [r.get("pathwayId") for r in relations if r.get("designId") == old_id and r.get("pathwayId") is not None]
for pid in pathway_ids:
s, _ = client.request("删除关系表记录", "DELETE", f"{ep(cfg, 'pathway_account_delete')}/{pid}")
if s in (200, 204):
summary["删除关系表记录"] += 1
s, _ = client.request("删除受众关联脆弱点", "DELETE", ep(cfg, "delete_design_vulns"),
query={"designId": old_id})
if s in (200, 204):
summary["删除脆弱点关联"] += 1
s, _ = client.request("删除同名旧受众", "DELETE", f"{ep(cfg, 'design_delete')}/{old_id}")
if s in (200, 204):
summary["删除同名旧受众"] += 1
group["deletedOld"].append({"id": old_id, "删除关系表记录数": len(pathway_ids)})
# ---- 4. 创建受众目标 ----
design_body = {
"taskId": task_id, "actionId": action_id,
"parentTargetAudience": "大模型生成",
"targetAudience": name,
"recReason": clean_reason(g.get("recReason", "")),
}
s, created = client.request("创建受众目标", "POST", ep(cfg, "design_create"), body=design_body)
if s not in (200, 201) or not isinstance(created, dict) or "id" not in created:
group["error"] = f"创建受众目标失败:HTTP {s},响应:{created}"
result["groups"].append(group)
all_ok = False
continue
design_id = created["id"]
group["designId"] = design_id
summary["新增受众"] += 1
# ---- 5. 创建账号关联 ----
for user in g.get("userList") or []:
account_source = user.get("dataSource") if user.get("dataSource") is not None else user.get("score")
# 平台编码:user.platformType(编码)缺失时回退 user.platform(名称),统一经平台字典映射为编码
raw_platform = user.get("platformType") if user.get("platformType") is not None else user.get("platform")
account_plat = platform_type_change(raw_platform, platform_options)
group.setdefault("账号平台映射", []).append(
{"accountName": user.get("name"), "原始值": raw_platform, "accountPlat": account_plat}
)
account_body = {
"taskId": task_id, "actionId": action_id,
"accountId": user.get("id"),
"accountName": user.get("name"),
"accountPlat": account_plat,
"accountSource": account_source,
"frofileInfo": json.dumps(user, ensure_ascii=False),
"designId": design_id,
}
s, resp = client.request("创建受众-账号关联", "POST", ep(cfg, "design_account_create"), body=account_body)
if s in (200, 201):
group["新增账号"] += 1
summary["新增账号关联"] += 1
else:
group.setdefault("账号失败", []).append({"accountName": user.get("name"), "status": s, "response": resp})
all_ok = False
group["ok"] = "账号失败" not in group
result["groups"].append(group)
result["summary"] = summary
result["success"] = all_ok
result["calls"] = client.calls
result["人读摘要"] = (
f"{'[演练]' if args.dry_run else ''}共处理 {len(groups_in)} 个受众组:"
f"新增受众 {summary['新增受众']} 个、账号关联 {summary['新增账号关联']} 条;"
f"删除同名旧受众 {summary['删除同名旧受众']} 个(连带关系表记录 {summary['删除关系表记录']} 条、脆弱点关联 {summary['删除脆弱点关联']} 处)。"
+ ("全部成功。" if all_ok else "存在失败项,详见 groups/error 字段。")
)
print(json.dumps(result, ensure_ascii=False, indent=2))
sys.exit(0 if all_ok else 2)
if __name__ == "__main__":
main()
@@ -0,0 +1,40 @@
---
name: sentiment-analysis
description: 调用外部舆情分析 AG-UI 网关,实时解析思考与正文流,并输出统一 NDJSON 或 Markdown 结果。
license: Proprietary
version: 1.0.0
allowed-tools:
- bash
---
# 舆情分析
当用户需要研判新闻事件、社会热点、品牌声誉、风险传播或某一主题的舆情态势时,使用本技能调用已配置的外部舆情分析服务。
## 执行规则
1. 必须实际执行本技能目录中的 `scripts/sentiment_stream.py`,不要根据常识虚构分析结果。
2. 默认使用 `--format markdown`,将脚本最终输出原样或经简短整理后回复用户。
3. 当调用方需要消费实时增量时,使用 `--format ndjson`。每行都是一个 JSON 事件,可直接按 `type` 渲染:
- `thinking_delta`:思考文本增量;
- `answer_delta`:正文文本增量;
- `done`:完整结果;
- `error`:调用失败。
4. 只有在用户明确需要结合上一轮结果时,才通过 `--messages-file` 传入历史消息。历史文件必须是 JSON 数组,元素为 `{role, id, content}`。
5. 不得在回答、日志或产物中输出接口配置中的用户名、密码或 Authorization 请求头。
## 调用命令
在技能运行目录执行:
```bash
python scripts/sentiment_stream.py --question "请分析某主题近期的舆情态势" --format markdown
```
需要给调用方提供可实时消费的标准化流时:
```bash
python scripts/sentiment_stream.py --question "请分析某主题近期的舆情态势" --format ndjson
```
完整安装、鉴权配置、历史消息和事件格式见 `docs/调用与安装说明.md`。
@@ -0,0 +1,11 @@
{
"api_url": "https://gw.y.sit.4.cn/alg/stream/report-agent",
"timeout_seconds": 300,
"verify_tls": true,
"auth": {
"username": "",
"password": "",
"username_env": "SENTIMENT_AGENT_AUTH_USERNAME",
"password_env": "SENTIMENT_AGENT_AUTH_PASSWORD"
}
}
@@ -0,0 +1,101 @@
# 舆情分析技能:安装与调用说明
## 1. 包内容
安装包 `sentiment-analysis.skill` 是 ZIP 格式,解压后包含以下文件:
```text
sentiment-analysis/
├── SKILL.md
├── config/
│ └── sentiment-agent.json # 接口地址与鉴权配置(独立文件)
└── scripts/
└── sentiment_stream.py # AG-UI SSE 调用与流式转换脚本
```
脚本只使用 Python 标准库,不需要额外执行 `pip install`。
## 2. 安装到技能管理
1. 打开系统的「技能管理」。
2. 选择「导入/安装技能」,上传 `sentiment-analysis.skill`。
3. 在安装预览中确认技能名称为 `sentiment-analysis`,安装到「我的技能」。
4. 在技能列表启用该技能;如需让某个智能体使用,再在该智能体的技能配置中勾选「舆情分析」。
安装后,技能目录通常是 `/mnt/skills/custom/sentiment-analysis/`。实际容器挂载目录以部署配置为准。
## 3. 配置接口与鉴权
接口地址单独保存在:
```text
config/sentiment-agent.json
```
默认已填入当前舆情网关地址。鉴权不写入安装包,推荐在运行技能的环境中设置:
```bash
export SENTIMENT_AGENT_AUTH_USERNAME='你的用户名'
export SENTIMENT_AGENT_AUTH_PASSWORD='你的密码'
```
脚本优先读取这两个环境变量。仅在受控的内网测试环境,也可以将 `auth.username` 和 `auth.password` 填入 `config/sentiment-agent.json`;不要将带有真实密码的配置提交到代码仓库或上传到公共技能广场。
如需切换环境,只改 `config/sentiment-agent.json` 中的 `api_url`,不需要修改脚本或重新打包。`timeout_seconds` 为一次请求的连接与读取超时上限,`verify_tls` 生产环境应保持 `true`。
## 4. 调用方法
进入技能目录后运行:
```bash
python scripts/sentiment_stream.py \
--question "请分析某主题近一周的舆情态势、风险点和建议" \
--format markdown
```
`markdown` 适用于普通智能体对话:脚本在上游完成后输出可直接回复给用户的 Markdown。
若调用端能够持续读取标准输出,改用 `ndjson` 可获得实时标准化事件:
```bash
python scripts/sentiment_stream.py \
--question "请实时分析某主题的舆情" \
--format ndjson
```
每行是一个完整 JSON,不需要再解析上游 AG-UI 的字段差异:
| `type` | 含义 | 关键字段 |
| --- | --- | --- |
| `run_started` | 上游开始运行 | `threadId`, `runId` |
| `thinking_delta` | 思考文本增量 | `messageId`, `delta` |
| `answer_delta` | 正文文本增量 | `messageId`, `delta` |
| `run_finished` | 上游运行结束 | `threadId`, `runId` |
| `done` | 本次完整结果汇总 | `reasoning`, `answer` |
| `error` | 安全的错误说明 | `message` |
## 5. 传入多轮历史
先准备一个 JSON 数组,例如 `history.json`:
```json
[
{"role": "user", "id": "u-1", "content": "请先分析某主题的总体舆情"},
{"role": "assistant", "id": "a-1", "content": "此前分析结论……"}
]
```
再调用:
```bash
python scripts/sentiment_stream.py \
--messages-file history.json \
--question "请补充近三天的风险变化" \
--format markdown
```
脚本会把历史与本轮问题转换为上游所需的 `messages`,并自动生成缺省的 `threadId`、`runId` 和本轮消息 `id`。也可通过 `--thread-id`、`--run-id` 显式传入,方便调用方关联日志。
## 6. 与当前前端的关系
该包是独立的技能调用方式,不修改现有舆情分析前端页面。脚本本身已经实时输出规范化 NDJSON;若未来有新的调用端需要逐字展示,只需消费这些 NDJSON 行,而不用再次对接或解析外部 AG-UI SSE。
@@ -0,0 +1,295 @@
#!/usr/bin/env python3
"""Invoke the configured AG-UI sentiment gateway and normalize its SSE stream.
This script intentionally uses only Python's standard library, so an installed
skill does not need to install an extra dependency. It accepts the external
AG-UI stream and prints one normalized JSON object per line (NDJSON) as soon as
each event arrives, which makes it suitable for a caller that renders a live
stream. ``--format markdown`` is a convenience mode for ordinary agent calls.
"""
from __future__ import annotations
import argparse
import base64
import json
import os
import ssl
import sys
import uuid
from collections.abc import Iterable, Iterator
from pathlib import Path
from typing import Any
from urllib.error import HTTPError, URLError
from urllib.request import HTTPSHandler, Request, build_opener
DEFAULT_CONFIG_PATH = Path(__file__).resolve().parents[1] / "config" / "sentiment-agent.json"
VALID_ROLES = {"user", "assistant"}
class SentimentAgentError(RuntimeError):
"""A safe, user-facing error from the external sentiment gateway."""
def load_config(path: Path) -> dict[str, Any]:
"""Read and validate the skill's separate gateway configuration file."""
try:
raw = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise SentimentAgentError(f"未找到技能配置文件:{path}") from exc
except json.JSONDecodeError as exc:
raise SentimentAgentError(f"技能配置文件不是合法 JSON:{path}") from exc
if not isinstance(raw, dict):
raise SentimentAgentError("技能配置文件根节点必须是 JSON 对象。")
api_url = str(raw.get("api_url") or "").strip()
if not api_url.startswith(("https://", "http://")):
raise SentimentAgentError("请先在 config/sentiment-agent.json 配置有效的 api_url。")
return raw
def _read_auth_value(auth: dict[str, Any], key: str) -> str:
"""Read a credential, allowing the deployment environment to override JSON."""
env_name = str(auth.get(f"{key}_env") or "").strip()
if env_name:
env_value = os.getenv(env_name)
if env_value:
return env_value
return str(auth.get(key) or "")
def build_headers(config: dict[str, Any]) -> dict[str, str]:
"""Create upstream request headers without ever printing credentials."""
headers = {
"Content-Type": "application/json",
"Accept": "text/event-stream",
}
auth = config.get("auth")
if not isinstance(auth, dict):
return headers
username = _read_auth_value(auth, "username")
password = _read_auth_value(auth, "password")
if username and password:
token = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
headers["Authorization"] = f"Basic {token}"
return headers
def load_history(path: Path | None) -> list[dict[str, str]]:
"""Read a caller-supplied AG-UI history file and validate its safe subset."""
if path is None:
return []
try:
raw = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise SentimentAgentError(f"未找到历史消息文件:{path}") from exc
except json.JSONDecodeError as exc:
raise SentimentAgentError(f"历史消息文件不是合法 JSON:{path}") from exc
if not isinstance(raw, list):
raise SentimentAgentError("历史消息文件必须是 JSON 数组。")
messages: list[dict[str, str]] = []
for index, item in enumerate(raw, start=1):
if not isinstance(item, dict):
raise SentimentAgentError(f"历史消息第 {index} 项必须是对象。")
role = str(item.get("role") or "")
content = str(item.get("content") or "").strip()
if role not in VALID_ROLES or not content:
raise SentimentAgentError(f"历史消息第 {index} 项需要非空 role(user/assistant) 和 content。")
message_id = str(item.get("id") or f"history-{index}-{uuid.uuid4()}")
messages.append({"role": role, "id": message_id, "content": content})
return messages
def build_payload(
*,
thread_id: str,
run_id: str,
question: str,
history: list[dict[str, str]],
) -> dict[str, Any]:
"""Build the AG-UI request body documented by the external gateway."""
text = question.strip()
if not text:
raise SentimentAgentError("问题不能为空。")
return {
"threadId": thread_id,
"runId": run_id,
"state": {},
"tools": [],
"context": [],
"forwardedProps": {},
"messages": [
*history,
{"role": "user", "id": f"message-{uuid.uuid4()}", "content": text},
],
}
def parse_sse_payloads(lines: Iterable[bytes]) -> Iterator[dict[str, Any]]:
"""Yield JSON payloads from an SSE byte stream, including an unterminated last frame."""
data_lines: list[str] = []
def flush() -> dict[str, Any] | None:
if not data_lines:
return None
joined = "\n".join(data_lines)
data_lines.clear()
try:
parsed = json.loads(joined)
except json.JSONDecodeError:
return None
return parsed if isinstance(parsed, dict) else None
for raw_line in lines:
line = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
if not line:
payload = flush()
if payload is not None:
yield payload
continue
if line.startswith("data:"):
data_lines.append(line[5:].lstrip(" "))
payload = flush()
if payload is not None:
yield payload
def normalize_agui_event(payload: dict[str, Any], *, thread_id: str, run_id: str) -> dict[str, Any] | None:
"""Convert an upstream AG-UI event to the stable, UI-friendly event contract."""
event_type = str(payload.get("type") or "")
message_id = str(payload.get("message_id") or payload.get("messageId") or "")
delta = payload.get("delta")
text_delta = delta if isinstance(delta, str) else ""
if event_type == "RUN_STARTED":
return {"type": "run_started", "threadId": thread_id, "runId": run_id}
if event_type == "THINKING_TEXT_MESSAGE_START":
return {"type": "thinking_start", "messageId": message_id}
if event_type == "THINKING_TEXT_MESSAGE_CONTENT":
return {"type": "thinking_delta", "messageId": message_id, "delta": text_delta}
if event_type == "THINKING_TEXT_MESSAGE_END":
return {"type": "thinking_end", "messageId": message_id}
if event_type == "TEXT_MESSAGE_START":
return {"type": "answer_start", "messageId": message_id}
if event_type == "TEXT_MESSAGE_CONTENT":
return {"type": "answer_delta", "messageId": message_id, "delta": text_delta}
if event_type == "TEXT_MESSAGE_END":
return {"type": "answer_end", "messageId": message_id}
if event_type == "RUN_FINISHED":
return {"type": "run_finished", "threadId": thread_id, "runId": run_id}
if event_type == "RUN_ERROR":
message = str(payload.get("message") or "舆情分析服务返回错误。")
raise SentimentAgentError(message)
return None
def stream_events(config: dict[str, Any], payload: dict[str, Any]) -> Iterator[dict[str, Any]]:
"""Call the configured gateway and yield normalized events as soon as they arrive."""
verify_tls = bool(config.get("verify_tls", True))
timeout_seconds = float(config.get("timeout_seconds", 300))
if timeout_seconds <= 0:
raise SentimentAgentError("timeout_seconds 必须大于 0。")
request = Request(
str(config["api_url"]),
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers=build_headers(config),
method="POST",
)
ssl_context = ssl.create_default_context() if verify_tls else ssl._create_unverified_context()
opener = build_opener(HTTPSHandler(context=ssl_context))
try:
with opener.open(request, timeout=timeout_seconds) as response:
for upstream in parse_sse_payloads(response):
normalized = normalize_agui_event(
upstream,
thread_id=str(payload["threadId"]),
run_id=str(payload["runId"]),
)
if normalized is not None:
yield normalized
except HTTPError as exc:
raise SentimentAgentError(f"舆情分析服务请求失败(HTTP {exc.code})。") from exc
except URLError as exc:
raise SentimentAgentError("无法连接舆情分析服务,请检查接口地址和网络。") from exc
except TimeoutError as exc:
raise SentimentAgentError("舆情分析服务响应超时。") from exc
def write_ndjson(events: Iterable[dict[str, Any]]) -> None:
"""Write every normalized event immediately for real-time consumers."""
reasoning = ""
answer = ""
for event in events:
if event["type"] == "thinking_delta":
reasoning += str(event.get("delta") or "")
elif event["type"] == "answer_delta":
answer += str(event.get("delta") or "")
print(json.dumps(event, ensure_ascii=False), flush=True)
print(json.dumps({"type": "done", "reasoning": reasoning, "answer": answer}, ensure_ascii=False), flush=True)
def write_markdown(events: Iterable[dict[str, Any]]) -> None:
"""Collect the stream for a normal chat-friendly Markdown result."""
reasoning = ""
answer = ""
for event in events:
if event["type"] == "thinking_delta":
reasoning += str(event.get("delta") or "")
elif event["type"] == "answer_delta":
answer += str(event.get("delta") or "")
if reasoning:
print("<details><summary>分析过程</summary>\n\n" + reasoning + "\n\n</details>\n")
print(answer or "舆情分析服务未返回正文。")
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="调用舆情分析 AG-UI 流式网关。")
parser.add_argument("--question", required=True, help="本轮需要分析的问题。")
parser.add_argument("--thread-id", default=f"sentiment-{uuid.uuid4()}", help="会话标识,默认自动生成。")
parser.add_argument("--run-id", default=f"run-{uuid.uuid4()}", help="运行标识,默认自动生成。")
parser.add_argument("--messages-file", type=Path, help="可选的历史消息 JSON 文件。")
parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG_PATH, help="网关配置 JSON 文件。")
parser.add_argument("--format", choices=("ndjson", "markdown"), default="ndjson", help="输出格式,默认 ndjson。")
return parser.parse_args()
def main() -> int:
args = parse_args()
try:
config = load_config(args.config)
payload = build_payload(
thread_id=args.thread_id,
run_id=args.run_id,
question=args.question,
history=load_history(args.messages_file),
)
events = stream_events(config, payload)
if args.format == "markdown":
write_markdown(events)
else:
write_ndjson(events)
return 0
except SentimentAgentError as exc:
if args.format == "ndjson":
print(json.dumps({"type": "error", "message": str(exc)}, ensure_ascii=False), flush=True)
else:
print(f"舆情分析调用失败:{exc}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())