Add XDFX skill data artifacts

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

@@ -0,0 +1,268 @@
+# 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
+```
+
+默认会自动处理登录态：缺少 `Authorization` 或接口返回 401 时，脚本会用固定账号 `admin`、口令 `ch@user` 调用 `POST /api/v1/auth/login/username?password=ch%40user`，请求体为 `{"username":"admin"}`，拿到 `access_token` 后写入 `Authorization: Bearer ...` 并重试原接口一次。默认关闭 HTTPS 证书校验，用于兼容 UAT/内网自签证书；需要严格校验证书时追加 `--verify-ssl`。已有 token 时可追加 `--auth-token TOKEN` 或 `--header "Authorization: Bearer TOKEN"`。
+
+每一步命令结束都会输出一行：
+
+```text
+STEP_FEEDBACK {...}
+```
+
+总控智能体必须在每一步结束后立即把这行反馈转述给用户，再执行下一步。
+
+每次执行具体操作或调用接口前，脚本会输出：
+
+```text
+OP_FEEDBACK {...}
+```
+
+总控智能体必须把 `operation`、`method` 和 `url` 转述给用户。
+
+如果报错，脚本会立即输出：
+
+```text
+ERROR_FEEDBACK {...}
+```
+
+总控智能体必须立刻告诉用户失败阶段、接口 URL、状态码、请求摘要和响应摘要。
+
+如果模型 JSON 经过自动提取和修复仍无法解析，脚本会输出：
+
+```text
+JSON_PARSE_REVIEW {...}
+```
+
+总控智能体必须查看 `responseExcerpt`，判断是否能识别真正 JSON；无法确认时重跑当前 step 或重新调用对应模型接口。
+
+每一步中的流式模型接口第一次返回空响应、`y模型没有响应`、`模型没有响应` 或超时类字符串时，脚本会自动再调用一次；如果第二次仍失败，才写入 `errors` 并在该步骤反馈里体现为 `partial`。
+
+## 推荐执行顺序
+
+总控技能按下面顺序执行：
+
+```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` 即可。
+
+## 每步反馈格式
+
+脚本会输出三类反馈行：
+
+- `OP_FEEDBACK`：当前正在做什么、调用哪个接口。
+- `ERROR_FEEDBACK`：当前错误的阶段、接口、状态码、请求摘要和响应摘要。
+- `JSON_PARSE_REVIEW`：模型返回内容无法稳定解析为 JSON，需要执行智能体复核是否重试。
+- `STEP_FEEDBACK`：当前步骤最终状态和累计入库数量。
+
+`STEP_FEEDBACK` 中包含：
+
+- `step`：步骤编号。
+- `label`：步骤名称。
+- `status`：`ok`、`partial` 或 `skipped`。
+- `counts`：当前累计入库数量。
+- `newErrors`：本步骤新增错误数。
+- `totalErrors`：累计错误数。
+
+总控反馈用户时建议使用这种格式：
+
+```text
+Step2 关键传播节点分析完成：当前已入库传播节点 X 个，本步骤新增错误 Y 个。
+```
+
+如果 `status=partial`，说明该步骤部分完成，并继续执行后续可执行步骤。
+
+如果 `status=skipped`，说明跳过原因。
+
+## 各步骤职责
+
+### Step1：受众目标分析
+
+技能：`xdfx-step1-audience`
+
+动作：
+
+- 调用受众分析模型。
+- 抽取结构化受众。
+- 选择最优 3 个受众。
+- 保存受众与受众账号。
+- 同步前端 `step-analysis-audience`、`step-analysis-keypoint` 状态。
+
+输出写入：
+
+```text
+topAudiences
+```
+
+### Step2：关键传播节点分析
+
+技能：`xdfx-step2-pathway`
+
+动作：
+
+- 基于 Step1 的受众逐个分析关键传播节点。
+- 跨受众去重。
+- 选择全局最优 3 个节点。
+- 保存传播节点。
+- 保存受众与传播节点关系。
+- 同步前端 `step-analysis-keypoint`、`step-analysis-weakpoint` 状态。
+
+输出写入：
+
+```text
+topPathways
+```
+
+### Step3：受众脆弱点分析
+
+技能：`xdfx-step3-audience-vulns`
+
+动作：
+
+- 基于 `topAudiences` 分析受众脆弱点。
+- 每个受众最多保存 3 个脆弱点。
+- 同步前端 `step-analysis-weakpoint` 状态。
+
+输出写入：
+
+```text
+audienceVulns
+```
+
+### Step4：传播节点脆弱点分析
+
+技能：`xdfx-step4-pathway-vulns`
+
+动作：
+
+- 基于 `topPathways` 分析传播节点脆弱点。
+- 每个节点最多保存 3 个脆弱点。
+- 同步前端 `step-analysis-weakpoint` 状态。
+
+输出写入：
+
+```text
+pathwayVulns
+```
+
+### Step5：受众策略分析
+
+技能：`xdfx-step5-audience-strategy`
+
+动作：
+
+- 基于 `topAudiences` 与 `audienceVulns` 生成策略。
+- 保存策略主表。
+- 同步写入策略 channel、narrate、message 和策略-受众关系。
+- 同步前端 `step-analysis-strategy`、`step-analysis-strategy-gantt` 状态。
+
+输出写入：
+
+```text
+audienceStrategies
+```
+
+### Step6：传播节点策略分析
+
+技能：`xdfx-step6-pathway-strategy`
+
+动作：
+
+- 基于 `topPathways` 与 `pathwayVulns` 生成策略。
+- 保存策略主表。
+- 同步写入策略 channel、narrate、message 和策略-传播节点关系。
+- 同步前端 `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
+```
+
+优先依据本步骤的 `STEP_FEEDBACK` 给即时反馈；最终汇总时再读取完整 summary 和 errors。
+
+如果 `errors` 非空，必须告诉用户：
+
+- 失败阶段。
+- 接口 URL。
+- HTTP 状态码。
+- 请求摘要。
+- 响应正文摘要。
+- 哪些数据已成功入库，哪些数据未完成。
+
+只要存在错误，就说“部分完成”，不要说“全部完成”。