# xdfx 单技能全流程使用说明

## 适用场景

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

1. 受众目标分析，选出最优 3 个受众并入库。
2. 关键传播节点分析，跨受众去重后选出最优 3 个节点并入库。
3. 受众脆弱点分析并入库。
4. 关键传播节点脆弱点分析并入库。
5. 受众策略分析并入库。
6. 关键传播节点策略分析并入库。
7. 同步前端步骤状态，保证原 `item-aiceh` 页面步骤条可继续识别。

## 技能位置

```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"
}
```

默认会自动处理登录态：当命令没有传 `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"`，脚本会优先使用传入 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 传递、断点续跑和最终入库。

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

```text
STEP_FEEDBACK {...}
```

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

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

```text
OP_FEEDBACK {...}
```

调用技能的智能体必须把 `operation`、`method` 和 `url` 转述给用户，例如：

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

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

```text
ERROR_FEEDBACK {...}
```

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

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

```text
JSON_PARSE_REVIEW {...}
```

调用技能的智能体必须查看 `responseExcerpt`，判断是否能识别真正 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` 字段

## 输出文件

执行后查看：

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

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

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

## 每步反馈

脚本会输出三类反馈行：

- `OP_FEEDBACK`：当前正在做什么、调用哪个接口。
- `ERROR_FEEDBACK`：当前错误的阶段、接口、状态码、请求摘要和响应摘要。
- `JSON_PARSE_REVIEW`：模型返回内容无法稳定解析为 JSON，需要执行智能体复核是否重试。
- `STEP_FEEDBACK`：当前步骤最终状态和累计入库数量。

`STEP_FEEDBACK` 中包含：

- `step`：步骤编号。
- `label`：步骤名称。
- `status`：`ok`、`partial` 或 `skipped`。
- `counts`：当前累计入库数量。
- `newErrors`：本步骤新增错误数。
- `totalErrors`：累计错误数。

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

```text
Step1 受众目标分析完成：当前已入库受众 X 个，本步骤新增错误 Y 个。
```

如果 `status=partial`，要补一句“该步骤部分完成”，并说明稍后最终汇总会列出错误明细。

如果 `status=skipped`，要说明跳过原因。

## 容错规则

- 单个受众、账号、传播节点、脆弱点或策略失败，不中断整个流程。
- 保存接口必须返回 `id`，否则不会进入下游步骤。
- 模型流式 `answer` 会自动拼接。
- 流式模型接口第一次返回空响应、`y模型没有响应`、`模型没有响应` 或超时类字符串时，会自动再调用一次；仍失败才写入 `errors`。
- 模型输出会自动去掉 `<think>`，从前后混杂文本、多个 JSON 代码块、无换行流式文本、连续 JSON 对象、非工整 JSON 中提取多个候选，并按当前步骤所需字段选择最像的 JSON。
- 模型 JSON 会尝试修复中文引号、全角冒号/逗号、尾随逗号、未加引号的键、Python 风格 `True/False/None`。
- 模型 JSON 解析失败会自动重试 1 次。
- 每一步完成都会写入 state/summary 并输出 `STEP_FEEDBACK`。
- 接口失败会写入 `errors`，包含阶段、URL、状态码、请求摘要、响应正文和异常类型。

## 回复用户规则

执行结束后，智能体必须读取 `xdfx-flow-summary.md` 和 `xdfx-flow-state.json.errors` 再回复用户。

如果 `errors` 为空，可以说明“全流程完成”。

如果 `errors` 非空，只能说明“部分完成”，并列出失败阶段、接口 URL、状态码和响应摘要。