302 lines
11 KiB
Markdown
302 lines
11 KiB
Markdown
# xdfx 分步技能使用说明
|
||
|
||
## 适用场景
|
||
|
||
使用分步技能时，总控技能 `xdfx-split-controller` 负责告诉智能体按顺序调用 6 个步骤技能。适合弱模型、长流程不稳定、需要断点续跑或单独重跑某一步的场景。
|
||
|
||
## 技能目录
|
||
|
||
```text
|
||
skills-data/xdfx-split-controller/
|
||
skills-data/xdfx-step1-audience/
|
||
skills-data/xdfx-step2-pathway/
|
||
skills-data/xdfx-step3-audience-vulns/
|
||
skills-data/xdfx-step4-pathway-vulns/
|
||
skills-data/xdfx-step5-audience-strategy/
|
||
skills-data/xdfx-step6-pathway-strategy/
|
||
```
|
||
|
||
每个技能目录下都有同一份执行器：
|
||
|
||
```text
|
||
scripts/xdfx_flow.py
|
||
```
|
||
|
||
使用时不要让智能体手写接口调用，必须直接执行脚本。
|
||
|
||
## 输入文件
|
||
|
||
准备统一的 `xdfx-input.json`：
|
||
|
||
```json
|
||
{
|
||
"api_base": "https://ch1.b.uat.4.cn",
|
||
"taskId": "真实任务id",
|
||
"actionId": "真实xdfx行动id",
|
||
"mubiao": "完整行动目标",
|
||
"direction": "U方向",
|
||
"platform": "fb"
|
||
}
|
||
```
|
||
|
||
所有步骤共用同一个状态文件：
|
||
|
||
```text
|
||
xdfx-flow-state.json
|
||
```
|
||
|
||
默认会自动处理登录态：脚本启动时先 `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 并重试原接口一次。
|
||
|
||
每一步命令结束都会输出一行：
|
||
|
||
```text
|
||
步骤反馈 {...}
|
||
```
|
||
|
||
总控智能体必须在每一步结束后立即把这行反馈转述给用户，再执行下一步。
|
||
|
||
每次执行具体操作或调用接口前，脚本会输出：
|
||
|
||
```text
|
||
操作反馈 {...}
|
||
```
|
||
|
||
总控智能体必须把 `操作`、`请求方式` 和 `接口地址` 转述给用户。
|
||
|
||
每次保存接口成功拿到 `id` 后，脚本会输出：
|
||
|
||
```text
|
||
入库反馈 {...}
|
||
```
|
||
|
||
总控智能体必须把 `入库对象类型`、`入库对象名称` 和 `返回ID` 转述给用户，例如“已入库受众目标：xxx，designId=123”或“已入库策略：xxx，id=456”。
|
||
|
||
如果报错，脚本会立即输出：
|
||
|
||
```text
|
||
错误反馈 {...}
|
||
```
|
||
|
||
总控智能体必须立刻告诉用户失败阶段、接口 URL、状态码、请求摘要和响应摘要。
|
||
|
||
如果模型 JSON 经过自动提取和修复仍无法解析，脚本会输出：
|
||
|
||
```text
|
||
JSON解析复核 {...}
|
||
```
|
||
|
||
总控智能体必须查看 `响应片段`，判断是否能识别真正 JSON；无法确认时重跑当前步骤或重新调用对应模型接口。
|
||
|
||
每一步中的流式模型接口第一次返回空响应、`y模型没有响应`、`模型没有响应` 或超时类字符串时，脚本会自动再调用一次；如果第二次仍失败，才写入 `errors` 并在该步骤反馈里体现为 `部分完成`。
|
||
|
||
## 推荐执行顺序
|
||
|
||
总控技能按下面顺序执行：
|
||
|
||
```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
|
||
```
|
||
|
||
如果某一步失败，修复接口、鉴权或输入后，只重跑对应 `stepN` 即可。
|
||
|
||
如果需要一条命令完成分步编排，可以在 `xdfx-split-controller` 目录使用包装脚本；它内部仍按 step1-step6 调用执行器，并逐行转发反馈：
|
||
|
||
```bash
|
||
python scripts/xdfx_run_full_steps.py --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
|
||
```
|
||
|
||
## 每步反馈格式
|
||
|
||
脚本会输出六类反馈行：
|
||
|
||
- `操作反馈`：当前正在做什么、调用哪个接口。
|
||
- `入库反馈`：当前已入库对象的类型、名称和返回 ID。
|
||
- `错误反馈`：当前错误的阶段、接口、状态码、请求摘要和响应摘要。
|
||
- `JSON解析复核`：模型返回内容无法稳定解析为 JSON，需要执行智能体复核是否重试。
|
||
- `用户协助`：当前步骤需要用户选择候选；总控必须暂停后续步骤，展示选项，等待用户选择后重跑同一个 step。
|
||
- `步骤反馈`：当前步骤最终状态和累计入库数量。
|
||
|
||
`步骤反馈` 中包含：
|
||
|
||
- `步骤`：步骤编号。
|
||
- `步骤名称`：步骤名称。
|
||
- `状态`：`成功`、`部分完成`、`等待用户选择` 或 `已跳过`。
|
||
- `执行状态`：中文执行状态。
|
||
- `累计入库数量`：当前累计入库数量。
|
||
- `本步骤新增错误数`：本步骤新增错误数。
|
||
- `累计错误数`：累计错误数。
|
||
|
||
默认数量规则：
|
||
|
||
- Step1 入库最优 3 个受众。
|
||
- Step2 入库最优 3 个传播节点。
|
||
- 默认开启用户协助选择：Step1 选择受众；Step2 选择关键传播节点；Step3/Step4 选择要入库的脆弱点；Step5 只能选择多个受众生成策略；Step6 只能选择多个关键传播节点生成策略。受众和关键传播节点不能在同一步交叉生成策略。
|
||
- 用户选择后重跑当前 step：`--select-audiences`、`--select-pathways`、`--select-audience-vulns`、`--select-pathway-vulns`、`--select-strategy-audiences`、`--select-strategy-pathways`。
|
||
- Step3/Step5 的受众下游分析只能从“已在 Step2 分析出并关联关键传播节点”的受众中选择，默认取前 2 个；没有产生传播节点的受众不得继续分析脆弱点和策略。
|
||
- Step4/Step6 的传播节点下游分析默认从已入库传播节点中选择前 2 个继续；可用 `--downstream-audiences` / `--downstream-pathways` 调成 1 或 2。
|
||
- Step3-Step6 对上述选中的每个受众/传播节点默认生成最多 3 个脆弱点或策略。
|
||
- Step5/Step6 的策略模态必须按前端 `modelType` 字典保存为 value 逗号串；脚本会自动把“图片,视频/文本,图片”等文字转成 `task-action-message.modelType` 需要的值。
|
||
- Step5/Step6 的策略归属由步骤强制决定：Step5 固定写“目标受众账号”和 `designId + strategyId` 关系，Step6 固定写“关键传播节点账号”和 `pathwayId + strategyId` 关系，不用模型返回的 `accountType` 判断归属。
|
||
|
||
总控反馈用户时建议使用这种格式：
|
||
|
||
```text
|
||
Step2 关键传播节点分析完成：当前已入库传播节点 X 个，本步骤新增错误 Y 个。
|
||
```
|
||
|
||
如果 `状态` 为 `部分完成`，说明该步骤部分完成，并继续执行后续可执行步骤。
|
||
|
||
如果 `状态` 为 `已跳过`，说明跳过原因。
|
||
|
||
## 各步骤职责
|
||
|
||
### Step1：受众目标分析
|
||
|
||
技能：`xdfx-step1-audience`
|
||
|
||
动作：
|
||
|
||
- 调用受众分析模型。
|
||
- 抽取结构化受众。
|
||
- 输出 `用户协助`，等待用户选择受众；带 `--select-audiences` 重跑后才保存选中的受众。
|
||
- 保存受众与受众账号。
|
||
- 同步前端 `step-analysis-audience`、`step-analysis-keypoint` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
topAudiences
|
||
```
|
||
|
||
### Step2：关键传播节点分析
|
||
|
||
技能：`xdfx-step2-pathway`
|
||
|
||
动作：
|
||
|
||
- 基于 Step1 的受众逐个分析关键传播节点。
|
||
- 跨受众去重。
|
||
- 输出 `用户协助`，等待用户选择关键传播节点；带 `--select-pathways` 重跑后才保存选中的节点。
|
||
- 保存传播节点。
|
||
- 保存受众与传播节点关系。
|
||
- 同步前端 `step-analysis-keypoint`、`step-analysis-weakpoint` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
topPathways
|
||
```
|
||
|
||
### Step3：受众脆弱点分析
|
||
|
||
技能：`xdfx-step3-audience-vulns`
|
||
|
||
动作：
|
||
|
||
- 只基于已关联关键传播节点的受众分析脆弱点候选。
|
||
- 输出 `用户协助`，等待用户选择受众脆弱点；带 `--select-audience-vulns` 重跑后才保存选中的脆弱点。
|
||
- 同步前端 `step-analysis-weakpoint` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
audienceVulns
|
||
```
|
||
|
||
### Step4：传播节点脆弱点分析
|
||
|
||
技能：`xdfx-step4-pathway-vulns`
|
||
|
||
动作：
|
||
|
||
- 基于 `topPathways` 分析传播节点脆弱点。
|
||
- 输出 `用户协助`，等待用户选择传播节点脆弱点；带 `--select-pathway-vulns` 重跑后才保存选中的脆弱点。
|
||
- 同步前端 `step-analysis-weakpoint` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
pathwayVulns
|
||
```
|
||
|
||
### Step5：受众策略分析
|
||
|
||
技能：`xdfx-step5-audience-strategy`
|
||
|
||
动作：
|
||
|
||
- 基于已关联关键传播节点的受众与 `audienceVulns` 生成策略候选。
|
||
- 输出 `用户协助`，等待用户选择一个或多个受众；带 `--select-strategy-audiences` 重跑后才生成并保存这些受众的策略。
|
||
- 本步骤只能选择受众，不能选择或混入关键传播节点。
|
||
- 保存策略主表。
|
||
- 同步写入策略 channel、narrate、message 和策略-受众关系；只写 `designId + strategyId`，即使模型返回关键传播节点账号类型也要按受众策略保存。
|
||
- 同步前端 `step-analysis-strategy`、`step-analysis-strategy-gantt` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
audienceStrategies
|
||
```
|
||
|
||
### Step6：传播节点策略分析
|
||
|
||
技能：`xdfx-step6-pathway-strategy`
|
||
|
||
动作：
|
||
|
||
- 基于 `topPathways` 与 `pathwayVulns` 生成策略候选。
|
||
- 输出 `用户协助`，等待用户选择一个或多个关键传播节点；带 `--select-strategy-pathways` 重跑后才生成并保存这些传播节点的策略。
|
||
- 本步骤只能选择关键传播节点，不能选择或混入受众。
|
||
- 保存策略主表。
|
||
- 同步写入策略 channel、narrate、message 和策略-传播节点关系；只写 `pathwayId + strategyId`，即使模型返回受众账号类型也要按传播节点策略保存。
|
||
- 同步前端 `step-analysis-strategy`、`step-analysis-strategy-gantt` 状态。
|
||
|
||
输出写入：
|
||
|
||
```text
|
||
pathwayStrategies
|
||
```
|
||
|
||
## 断点续跑
|
||
|
||
每一步都会读写 `xdfx-flow-state.json`。
|
||
|
||
如果 Step3 失败，只需要重新执行：
|
||
|
||
```bash
|
||
python scripts/xdfx_flow.py --mode step3 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
|
||
```
|
||
|
||
如果想重新生成某一步，需要先清理 `xdfx-flow-state.json` 中对应字段，例如：
|
||
|
||
- 重新跑受众：清理 `topAudiences` 和后续所有字段。
|
||
- 重新跑传播节点：清理 `topPathways`、`pathwayVulns`、`pathwayStrategies`。
|
||
- 重新跑策略：清理 `audienceStrategies` 或 `pathwayStrategies`。
|
||
|
||
## 错误汇报
|
||
|
||
每一步执行结束后都要查看：
|
||
|
||
```text
|
||
xdfx-flow-summary.md
|
||
xdfx-flow-state.json
|
||
```
|
||
|
||
优先依据本步骤的 `步骤反馈` 给即时反馈；最终汇总时再读取完整 summary 和 errors。
|
||
|
||
如果 `errors` 非空，必须告诉用户：
|
||
|
||
- 失败阶段。
|
||
- 接口 URL。
|
||
- HTTP 状态码。
|
||
- 请求摘要。
|
||
- 响应正文摘要。
|
||
- 哪些数据已成功入库，哪些数据未完成。
|
||
|
||
只要存在错误，就说“部分完成”，不要说“全部完成”。
|