初始化

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

+221
View File
@@ -0,0 +1,221 @@
# xdfx 单技能全流程使用说明
## 适用场景
使用 `xdfx-single-agent-full-flow` 技能,让单智能体一次性完成 xdfx 深链接模式下的完整分析与入库流程:
1. 受众目标分析,输出 `用户协助` 让用户选择受众,入库选中的受众。
2. 关键传播节点分析,跨受众去重后输出 `用户协助` 让用户选择节点,入库选中的节点。
3. 从已关联关键传播节点的受众中生成脆弱点候选,输出 `用户协助` 让用户选择后入库。
4. 从已入库关键传播节点中生成脆弱点候选,输出 `用户协助` 让用户选择后入库。
5. 让用户选择一个或多个受众生成策略并入库。
6. 让用户选择一个或多个关键传播节点生成策略并入库;受众和节点不能在同一步交叉。
7. 同步前端步骤状态,保证原 `item-aiceh` 页面步骤条可继续识别。
策略入库归属由步骤强制决定:Step5 固定写“目标受众账号”和 `designId + strategyId` 关系,Step6 固定写“关键传播节点账号”和 `pathwayId + strategyId` 关系,不用模型返回的 `accountType` 判断归属。
## 技能位置
```text
skills-data/xdfx-single-agent-full-flow/
```
核心逻辑在:
```text
skills-data/xdfx-single-agent-full-flow/scripts/xdfx_flow.py
```
后续使用时不要让智能体照着说明手写接口调用,必须让它直接执行这个 Python 脚本。
## 输入文件
在技能目录下准备 `xdfx-input.json`:
```json
{
"api_base": "https://ch1.b.uat.4.cn",
"taskId": "真实任务id",
"actionId": "真实xdfx行动id",
"mubiao": "完整行动目标,例如:传播某叙事,驱动某行为体产生某预期行为,实现某作战目的。",
"direction": "U方向",
"platform": "fb"
}
```
默认会自动处理登录态:脚本启动时先 `import scripts/xdfx_auth.py`,用固定账号 `admin`、口令 `ch@user` 调用 `POST /api/auth/login`,请求体为 `{"username":"admin","password":"ch@user"}`。拿到 `access_token` 后写入内部 `Authorization: Bearer ...`,再调用第一步业务接口;不要通过任何命令行参数传 token。
默认关闭 HTTPS 证书校验,用于兼容 UAT/内网自签证书;如果部署环境证书链正常,可以追加 `--verify-ssl`。接口返回 401 时仍由 `xdfx_auth.py` 刷新 token 并重试原接口一次。
## 执行命令
进入技能目录后按步骤执行。这个版本仍然是 `xdfx-single-agent-full-flow` 一个技能负责完整流程,但不要默认使用一个 `--mode full` 长命令;为了保证用户能看到实时反馈,智能体要一条命令跑一步,每步结束后先反馈给用户,再继续下一步:
```bash
python scripts/xdfx_flow.py --mode step1 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
python scripts/xdfx_flow.py --mode step2 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
python scripts/xdfx_flow.py --mode step3 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
python scripts/xdfx_flow.py --mode step4 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
python scripts/xdfx_flow.py --mode step5 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
python scripts/xdfx_flow.py --mode step6 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
```
`--mode full` 只作为无人值守或排障兜底,不作为默认执行方式;外层工具通常会等长命令结束后才返回输出,无法保证真实逐步反馈。逐步命令共享同一个 `xdfx-flow-state.json`,不会影响 id 传递、断点续跑和最终入库。
如果需要一条命令完成逐步编排,可以使用包装脚本。它内部仍按 step1-step6 调用 `xdfx_flow.py`,并逐行转发反馈:
```bash
python scripts/xdfx_run_full_steps.py --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
```
每完成一步都会输出一行:
```text
步骤反馈 {...}
```
调用技能的智能体必须在每个 step 命令结束后读取 `步骤反馈`,给用户一次反馈,再执行下一条 step 命令。
每次执行具体操作或调用接口前,脚本会输出:
```text
操作反馈 {...}
```
调用技能的智能体必须把 `操作`、`请求方式` 和 `接口地址` 转述给用户,例如:
```text
正在保存受众目标,调用 POST https://.../api/task/task-action-design。
```
每次保存接口成功拿到 `id` 后,脚本会输出:
```text
入库反馈 {...}
```
调用技能的智能体必须把 `入库对象类型`、`入库对象名称` 和 `返回ID` 转述给用户,例如“已入库受众目标:xxx,designId=123”或“已入库受众脆弱点:xxx,id=456”。
如果报错,脚本会立即输出:
```text
错误反馈 {...}
```
调用技能的智能体必须立刻告诉用户失败阶段、接口 URL、状态码、请求摘要和响应摘要。
如果模型 JSON 经过自动提取和修复仍无法解析,脚本会输出:
```text
JSON解析复核 {...}
```
调用技能的智能体必须查看 `响应片段`,判断是否能识别真正 JSON;无法确认时重跑当前步骤或重新调用对应模型接口。
只检查脚本与参数、不调用真实接口:
```bash
python scripts/xdfx_flow.py --mode full --input xdfx-input.json --dry-run
```
如果只想入库数据,不更新前端步骤条:
```bash
python scripts/xdfx_flow.py --mode step1 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
python scripts/xdfx_flow.py --mode step2 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
python scripts/xdfx_flow.py --mode step3 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
python scripts/xdfx_flow.py --mode step4 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
python scripts/xdfx_flow.py --mode step5 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
python scripts/xdfx_flow.py --mode step6 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md --no-step-status
```
## 入库内容
脚本会写入以下接口对应的数据:
- `task-action-design`
- `task-action-design-account`
- `task-action-pathway-account`
- `task-action-design-pathway-relation/saveRelation`
- `task-action-design-vulns`
- `task-action-pathway-account-vulns`
- `task-action-strategy`
- `task-action-channel`
- `base-narrate`
- `task-action-message`
- `task-action-design-strategy-relation`
- `task/task-action/{actionId}` 的 `step` 字段
策略信息形式/模态会按前端 `modelType` 字典保存为 value 逗号串,例如模型输出“图片,视频”时,脚本先查 `sys/sys-dict-data` 再写入 `task-action-message.modelType`,不会直接保存中文文字。
策略关系表写入时,Step5 只写受众 `designId`,Step6 只写传播节点 `pathwayId`;即使模型把 `账号类型/accountType` 生成反了,脚本也会按当前步骤强制纠正,避免受众策略和传播节点策略串写。
## 输出文件
执行后查看:
```text
xdfx-flow-state.json
xdfx-flow-summary.md
```
`xdfx-flow-state.json` 保存断点状态、接口返回 ID、模型解析结果与错误明细。
`xdfx-flow-summary.md` 是给用户看的执行摘要。
## 每步反馈
脚本会输出六类反馈行:
- `操作反馈`:当前正在做什么、调用哪个接口。
- `用户协助`:当前步骤需要用户选择候选;智能体必须暂停后续步骤,展示选项,等待用户选择后重跑同一个 step。
- `入库反馈`:当前已入库的对象类型、名称和返回 ID。
- `错误反馈`:当前错误的阶段、接口、状态码、请求摘要和响应摘要。
- `JSON解析复核`:模型返回内容无法稳定解析为 JSON,需要执行智能体复核是否重试。
- `步骤反馈`:当前步骤最终状态和累计入库数量。
`步骤反馈` 中包含:
- `步骤`:步骤编号。
- `步骤名称`:步骤名称。
- `状态`:`成功`、`部分完成`、`等待用户选择` 或 `已跳过`。
- `执行状态`:中文执行状态。
- `累计入库数量`:当前累计入库数量。
- `本步骤新增错误数`:本步骤新增错误数。
- `累计错误数`:累计错误数。
智能体反馈用户时建议使用这种格式:
```text
Step1 受众目标分析完成:当前已入库受众 X 个,本步骤新增错误 Y 个。
```
如果 `状态` 为 `部分完成`,要补一句“该步骤部分完成”,并说明稍后最终汇总会列出错误明细。
如果 `状态` 为 `已跳过`,要说明跳过原因。
## 容错规则
- 单个受众、账号、传播节点、脆弱点或策略失败,不中断整个流程。
- 保存接口必须返回 `id`,否则不会进入下游步骤。
- 受众目标默认入库 3 个,关键传播节点默认入库 3 个。
- 默认开启用户协助选择:Step1 选择受众;Step2 选择关键传播节点;Step3/Step4 选择要入库的脆弱点;Step5 只能选择多个受众生成策略;Step6 只能选择多个关键传播节点生成策略。受众和关键传播节点不能在同一步交叉生成策略。
- 用户选择后重跑当前 step:`--select-audiences`、`--select-pathways`、`--select-audience-vulns`、`--select-pathway-vulns`、`--select-strategy-audiences`、`--select-strategy-pathways`。
- 下游受众脆弱点/策略只能从“已在 Step2 分析出并关联关键传播节点”的受众中选择,默认取前 2 个;没有产生传播节点的受众不得继续分析脆弱点和策略。
- 下游传播节点脆弱点/策略默认只选择前 2 个已入库传播节点继续,可用 `--downstream-audiences` / `--downstream-pathways` 调成 1 或 2。
- 每个被选中的对象默认最多生成 3 个脆弱点、3 个策略。
- 模型流式 `answer` 会自动拼接。
- 流式模型接口第一次返回空响应、`y模型没有响应`、`模型没有响应` 或超时类字符串时,会自动再调用一次;仍失败才写入 `errors`。
- 模型输出会自动去掉 `<think>`,从前后混杂文本、多个 JSON 代码块、无换行流式文本、连续 JSON 对象、非工整 JSON 中提取多个候选,并按当前步骤所需字段选择最像的 JSON。
- 模型 JSON 会尝试修复中文引号、全角冒号/逗号、尾随逗号、未加引号的键、Python 风格 `True/False/None`。
- 模型 JSON 解析失败会自动重试 1 次。
- 每一步完成都会写入 state/summary 并输出 `步骤反馈`。
- 接口失败会写入 `errors`,包含阶段、URL、状态码、请求摘要、响应正文和异常类型。
## 回复用户规则
执行结束后,智能体必须读取 `xdfx-flow-summary.md` 和 `xdfx-flow-state.json.errors` 再回复用户。
如果 `errors` 为空,可以说明“全流程完成”。
如果 `errors` 非空,只能说明“部分完成”,并列出失败阶段、接口 URL、状态码和响应摘要。