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

xdfx 单技能全流程使用说明

适用场景

使用 xdfx-single-agent-full-flow 技能，让单智能体一次性完成 xdfx 深链接模式下的完整分析与入库流程：

1. 受众目标分析，输出 用户协助 让用户选择受众，入库选中的受众。
2. 关键传播节点分析，跨受众去重后输出 用户协助 让用户选择节点，入库选中的节点。
3. 从已关联关键传播节点的受众中生成脆弱点候选，输出 用户协助 让用户选择后入库。
4. 从已入库关键传播节点中生成脆弱点候选，输出 用户协助 让用户选择后入库。
5. 让用户选择一个或多个受众生成策略并入库。
6. 让用户选择一个或多个关键传播节点生成策略并入库；受众和节点不能在同一步交叉。
7. 同步前端步骤状态，保证原 item-aiceh 页面步骤条可继续识别。

策略入库归属由步骤强制决定：Step5 固定写“目标受众账号”和 designId + strategyId 关系，Step6 固定写“关键传播节点账号”和 pathwayId + strategyId 关系，不用模型返回的 accountType 判断归属。

技能位置

skills-data/xdfx-single-agent-full-flow/

核心逻辑在：

skills-data/xdfx-single-agent-full-flow/scripts/xdfx_flow.py

后续使用时不要让智能体照着说明手写接口调用，必须让它直接执行这个 Python 脚本。

输入文件

在技能目录下准备 xdfx-input.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 长命令；为了保证用户能看到实时反馈，智能体要一条命令跑一步，每步结束后先反馈给用户，再继续下一步：

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

python scripts/xdfx_run_full_steps.py --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md

每完成一步都会输出一行：

步骤反馈 {...}

调用技能的智能体必须在每个 step 命令结束后读取 步骤反馈，给用户一次反馈，再执行下一条 step 命令。

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

操作反馈 {...}

调用技能的智能体必须把 操作、请求方式 和 接口地址 转述给用户，例如：

正在保存受众目标，调用 POST https://.../api/task/task-action-design。

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

入库反馈 {...}

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

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

错误反馈 {...}

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

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

JSON解析复核 {...}

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

只检查脚本与参数、不调用真实接口：

python scripts/xdfx_flow.py --mode full --input xdfx-input.json --dry-run

如果只想入库数据，不更新前端步骤条：

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 生成反了，脚本也会按当前步骤强制纠正，避免受众策略和传播节点策略串写。

输出文件

执行后查看：

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

xdfx-flow-state.json 保存断点状态、接口返回 ID、模型解析结果与错误明细。

xdfx-flow-summary.md 是给用户看的执行摘要。

每步反馈

脚本会输出六类反馈行：

• 操作反馈：当前正在做什么、调用哪个接口。
• 用户协助：当前步骤需要用户选择候选；智能体必须暂停后续步骤，展示选项，等待用户选择后重跑同一个 step。
• 入库反馈：当前已入库的对象类型、名称和返回 ID。
• 错误反馈：当前错误的阶段、接口、状态码、请求摘要和响应摘要。
• JSON解析复核：模型返回内容无法稳定解析为 JSON，需要执行智能体复核是否重试。
• 步骤反馈：当前步骤最终状态和累计入库数量。

步骤反馈 中包含：

• 步骤：步骤编号。
• 步骤名称：步骤名称。
• 状态：成功、部分完成、等待用户选择 或 已跳过。
• 执行状态：中文执行状态。
• 累计入库数量：当前累计入库数量。
• 本步骤新增错误数：本步骤新增错误数。
• 累计错误数：累计错误数。

智能体反馈用户时建议使用这种格式：

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、状态码和响应摘要。