---
name: xdfx-step1-audience
description: xdfx 拆分流程 step1，分析受众目标，发起用户协助选择受众，并保存选中的受众与受众账号。
---

# Step1 受众分析与入库

不要手写接口调用，直接运行：

```bash
python scripts/xdfx_flow.py --mode step1 --input xdfx-input.json --state xdfx-flow-state.json --summary xdfx-flow-summary.md
```

`xdfx-input.json` 必须包含：

```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` 获取 `access_token`，并在第一次业务接口调用前写入内部 Authorization；不要通过命令行传 token。接口返回 401 时仍由 `xdfx_auth.py` 刷新 token 并重试原接口一次；HTTPS 默认不校验证书，需校验证书时追加 `--verify-ssl`。

本步骤由脚本完成：

- 调用受众分析模型接口。
- 自动解析流式 answer 与候选账号。
- 流式模型接口首次空响应、模型无响应或超时类返回会自动再调用一次。
- 抽取结构化受众。
- 抽取结果中的 `用户编号列表` / `编号id` / `id` 必须对应上一轮 `zhanghao` 账号数组的索引值；脚本按索引依次找到账号并保存。
- 输出 `用户协助`，等待用户选择受众；用户选择后带 `--select-audiences 1,2,3` 重跑 Step1，才保存选中的受众。
- 保存受众目标。
- 保存受众目标账号。
- 同步前端步骤状态 `step-analysis-audience` 与 `step-analysis-keypoint`。
- 把 `designId`、账号、错误明细写入 `xdfx-flow-state.json`。

执行后检查 `xdfx-flow-summary.md`。如果 `errors` 非空，向用户报告失败接口、状态码、响应正文摘要。

## 失败重试规则

- 出现 `错误反馈`、`JSON解析复核`，或 `步骤反馈` 中 `状态` 为 `部分完成` / `已跳过` / `本步骤新增错误数` 大于 0 时，必须先重跑当前 Step1 命令。
- 重试前必须告诉用户失败阶段、接口 URL、状态码、响应摘要和“正在重试 Step1”，不能静默重试。
- Step1 未重试成功前，不允许继续 Step2；不要因为 Step1 失败就跳过受众分析。
- Step1 重试后仍失败时，停止自动推进，读取 `xdfx-flow-state.json.errors` 汇报失败细节，并等待用户处理或确认。

## 步骤反馈

命令结束会输出 `步骤反馈 {...}`。必须先根据这行反馈告诉用户 Step1 的完成状态、当前受众入库数量和新增错误数，再决定是否继续下一步。

如果输出 `用户协助 {...}`，必须暂停流程，把受众选项发给用户；用户选择后重跑 Step1 并追加 `--select-audiences ...`。

执行过程中会输出 `操作反馈 {...}`。每出现一次都要告诉用户当前操作和接口 URL。

保存成功会输出 `入库反馈 {...}`。每出现一次都要告诉用户已入库的受众、受众账号和返回 ID。

如果出现 `错误反馈 {...}`，必须立即告诉用户失败阶段、接口 URL、状态码、请求摘要和响应摘要。

如果出现 `JSON解析复核 {...}`，必须查看 `响应片段`，判断是否能识别受众 JSON；无法确认时重跑 Step1。