deerflow-code/skills-data/xdfx-split-flow-skill-guide.md

xdfx 分步技能使用说明

适用场景

使用分步技能时，总控技能 xdfx-split-controller 负责告诉智能体按顺序调用 6 个步骤技能。适合弱模型、长流程不稳定、需要断点续跑或单独重跑某一步的场景。

技能目录

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/

每个技能目录下都有同一份执行器：

scripts/xdfx_flow.py

使用时不要让智能体手写接口调用，必须直接执行脚本。

输入文件

准备统一的 xdfx-input.json：

{
  "api_base": "https://ch1.b.uat.4.cn",
  "taskId": "真实任务id",
  "actionId": "真实xdfx行动id",
  "mubiao": "完整行动目标",
  "direction": "U方向",
  "platform": "fb"
}

所有步骤共用同一个状态文件：

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 并重试原接口一次。

每一步命令结束都会输出一行：

步骤反馈 {...}

总控智能体必须在每一步结束后立即把这行反馈转述给用户，再执行下一步。

每次执行具体操作或调用接口前，脚本会输出：

操作反馈 {...}

总控智能体必须把 操作、请求方式 和 接口地址 转述给用户。

每次保存接口成功拿到 id 后，脚本会输出：

入库反馈 {...}

总控智能体必须把 入库对象类型、入库对象名称 和 返回ID 转述给用户，例如“已入库受众目标：xxx，designId=123”或“已入库策略：xxx，id=456”。

如果报错，脚本会立即输出：

错误反馈 {...}

总控智能体必须立刻告诉用户失败阶段、接口 URL、状态码、请求摘要和响应摘要。

如果模型 JSON 经过自动提取和修复仍无法解析，脚本会输出：

JSON解析复核 {...}

总控智能体必须查看 响应片段，判断是否能识别真正 JSON；无法确认时重跑当前步骤或重新调用对应模型接口。

每一步中的流式模型接口第一次返回空响应、y模型没有响应、模型没有响应 或超时类字符串时，脚本会自动再调用一次；如果第二次仍失败，才写入 errors 并在该步骤反馈里体现为 部分完成。

推荐执行顺序

总控技能按下面顺序执行：

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 调用执行器，并逐行转发反馈：

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 判断归属。

总控反馈用户时建议使用这种格式：

Step2 关键传播节点分析完成：当前已入库传播节点 X 个，本步骤新增错误 Y 个。

如果 状态 为 部分完成，说明该步骤部分完成，并继续执行后续可执行步骤。

如果 状态 为 已跳过，说明跳过原因。

各步骤职责

Step1：受众目标分析

技能：xdfx-step1-audience

动作：

• 调用受众分析模型。
• 抽取结构化受众。
• 输出 用户协助，等待用户选择受众；带 --select-audiences 重跑后才保存选中的受众。
• 保存受众与受众账号。
• 同步前端 step-analysis-audience、step-analysis-keypoint 状态。

输出写入：

topAudiences

Step2：关键传播节点分析

技能：xdfx-step2-pathway

动作：

• 基于 Step1 的受众逐个分析关键传播节点。
• 跨受众去重。
• 输出 用户协助，等待用户选择关键传播节点；带 --select-pathways 重跑后才保存选中的节点。
• 保存传播节点。
• 保存受众与传播节点关系。
• 同步前端 step-analysis-keypoint、step-analysis-weakpoint 状态。

输出写入：

topPathways

Step3：受众脆弱点分析

技能：xdfx-step3-audience-vulns

动作：

• 只基于已关联关键传播节点的受众分析脆弱点候选。
• 输出 用户协助，等待用户选择受众脆弱点；带 --select-audience-vulns 重跑后才保存选中的脆弱点。
• 同步前端 step-analysis-weakpoint 状态。

输出写入：

audienceVulns

Step4：传播节点脆弱点分析

技能：xdfx-step4-pathway-vulns

动作：

• 基于 topPathways 分析传播节点脆弱点。
• 输出 用户协助，等待用户选择传播节点脆弱点；带 --select-pathway-vulns 重跑后才保存选中的脆弱点。
• 同步前端 step-analysis-weakpoint 状态。

输出写入：

pathwayVulns

Step5：受众策略分析

技能：xdfx-step5-audience-strategy

动作：

• 基于已关联关键传播节点的受众与 audienceVulns 生成策略候选。
• 输出 用户协助，等待用户选择一个或多个受众；带 --select-strategy-audiences 重跑后才生成并保存这些受众的策略。
• 本步骤只能选择受众，不能选择或混入关键传播节点。
• 保存策略主表。
• 同步写入策略 channel、narrate、message 和策略-受众关系；只写 designId + strategyId，即使模型返回关键传播节点账号类型也要按受众策略保存。
• 同步前端 step-analysis-strategy、step-analysis-strategy-gantt 状态。

输出写入：

audienceStrategies

Step6：传播节点策略分析

技能：xdfx-step6-pathway-strategy

动作：

• 基于 topPathways 与 pathwayVulns 生成策略候选。
• 输出 用户协助，等待用户选择一个或多个关键传播节点；带 --select-strategy-pathways 重跑后才生成并保存这些传播节点的策略。
• 本步骤只能选择关键传播节点，不能选择或混入受众。
• 保存策略主表。
• 同步写入策略 channel、narrate、message 和策略-传播节点关系；只写 pathwayId + strategyId，即使模型返回受众账号类型也要按传播节点策略保存。
• 同步前端 step-analysis-strategy、step-analysis-strategy-gantt 状态。

输出写入：

pathwayStrategies

断点续跑

每一步都会读写 xdfx-flow-state.json。

如果 Step3 失败，只需要重新执行：

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。

错误汇报

每一步执行结束后都要查看：

xdfx-flow-summary.md
xdfx-flow-state.json

优先依据本步骤的 步骤反馈 给即时反馈；最终汇总时再读取完整 summary 和 errors。

如果 errors 非空，必须告诉用户：

• 失败阶段。
• 接口 URL。
• HTTP 状态码。
• 请求摘要。
• 响应正文摘要。
• 哪些数据已成功入库，哪些数据未完成。

只要存在错误，就说“部分完成”，不要说“全部完成”。