430 lines
17 KiB
Markdown
430 lines
17 KiB
Markdown
# 任务分析定时 · 对外接口对接文档
|
||
|
||
> 面向外部任务系统（下称「对方系统」）的开发者。覆盖任务接入、时间线详情拉取、
|
||
> 总控问答、**定时数据交付**（任务 6 块 JSON）四组接口。智能体编排配置
|
||
> （选业务链 / 执行频率）在 DeerFlow 任务分析页操作，对方系统无需开发。
|
||
>
|
||
> 相关实现：`app/gateway/routers/task_analysis.py`（任务/绑定/运行记录）、
|
||
> `app/gateway/routers/task_analysis_qa.py`（问答）。
|
||
|
||
## 0. 通用约定
|
||
|
||
- **Base URL**：DeerFlow Gateway 地址（如 `http://<host>:8001`）。
|
||
- **鉴权**：所有接口需带 `Authorization: Bearer <token>` 请求头（token 获取方式见登录对接，本文不重复）。
|
||
- **Content-Type**：`application/json`（SSE 接口除外，响应为 `text/event-stream`）。
|
||
- **时间格式**：ISO 8601 字符串（含时区，如 `2026-09-10T10:14:55+08:00`）。
|
||
- **两类任务标识**：
|
||
- `source_task_id`：对方系统的任务号（创建时由你们传入）；
|
||
- `task_id`：DeerFlow 内部任务 id（**创建接口的响应里返回**，问答接口使用它）。
|
||
创建任务后请保存响应中的 `task_id`；也可随时通过时间线详情接口重新取到。
|
||
|
||
## 1. 任务接入
|
||
|
||
### 1.1 创建任务
|
||
|
||
对方系统创建任务完成后调用，DeerFlow 落一条任务记录（初始未绑定分析方案）。
|
||
|
||
```
|
||
POST /api/task-analysis/external/tasks
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"source_task_id": "TS-2026-0147",
|
||
"name": "东南亚舆论环境监测",
|
||
"description": "持续跟踪东南亚重点渠道舆论动向，输出结构化分析详情。"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| source_task_id | string(≤128) | 是 | 对方任务号，全局唯一 |
|
||
| name | string(≤512) | 是 | 任务名称 |
|
||
| description | string(≤8192) | 否 | 任务简介。**定时执行时注入各智能体的任务上下文以此为准**（存量快照，执行时不会回拉） |
|
||
|
||
响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"task_id": "ta-TS-2026-0147",
|
||
"default_chain_id": "ta-demo-chain"
|
||
}
|
||
```
|
||
|
||
- `task_id`：DeerFlow 内部任务 id，**问答接口需要它**，请保存。
|
||
- `default_chain_id`：DeerFlow 侧最近一次绑定使用的业务链 id，可作为你们界面上绑定流程的默认选项；无绑定为 `null`。
|
||
|
||
错误：`409` —— `source_task_id` 已存在。
|
||
|
||
### 1.2 删除任务
|
||
|
||
对方系统删除任务时同步调用，**彻底删除**：任务、绑定、全部执行记录、过程消息与时间线版本一并清除（不可恢复）。
|
||
|
||
```
|
||
DELETE /api/task-analysis/external/tasks/{source_task_id}
|
||
```
|
||
|
||
响应 `200`：`{"deleted": true, "task_id": "..."}`。错误：`404` —— 任务不存在。
|
||
|
||
## 2. 任务详情（时间线）
|
||
|
||
对方系统详情页的数据源。每次定时执行成功会落一期**时间线版本**（含各智能体产出），按时间倒序返回。
|
||
|
||
```
|
||
GET /api/task-analysis/external/tasks/{source_task_id}/detail?limit=20&offset=0
|
||
```
|
||
|
||
响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"task": {
|
||
"task_id": "ta-TS-2026-0147",
|
||
"source_task_id": "TS-2026-0147",
|
||
"name": "东南亚舆论环境监测"
|
||
},
|
||
"binding": {
|
||
"chain_id": "ta-demo-chain",
|
||
"cron_expr": "0 9 * * *",
|
||
"schedule_type": "cron",
|
||
"enabled": true
|
||
},
|
||
"timeline": [
|
||
{
|
||
"id": "…",
|
||
"external_task_id": "ta-TS-2026-0147",
|
||
"run_id": "tar-…",
|
||
"blocks": {
|
||
"eightbf-roundtable-intent": {
|
||
"name": "8BF 任务理解",
|
||
"seat_agent_id": "eightbf-roundtable-intent",
|
||
"content": "（该智能体本次产出的 Markdown 正文）",
|
||
"format": "markdown"
|
||
},
|
||
"c0a8799da8724e179e086ea9ca723967": { "name": "策略分析师", "…": "…" }
|
||
},
|
||
"created_at": "2026-09-10T10:15:13+08:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `binding`：当前绑定信息（未绑定为 `null`，此时 `timeline` 不会有新版本）。
|
||
`schedule_type` 为执行方式：`cron` = 按 `cron_expr` 频率定时执行；
|
||
`once` = 只执行一次（创建后立即执行，之后不再自动执行，`cron_expr` 不生效）。
|
||
- `timeline[].blocks`：**每个参与执行的智能体一块**，key 为该智能体的 agent_id，
|
||
`name` 为执行时的名称快照，`content` 为其交付正文（Markdown）。
|
||
按你们的详情分区规则渲染即可（如按 block 顺序分栏）。
|
||
- 分页：`limit`（默认 20）/ `offset`，按 `created_at` 倒序。
|
||
|
||
## 3. 总控问答（详情页对话）
|
||
|
||
详情页的对话入口：用户提问 → DeerFlow 总控按任务绑定的编排给对应智能体派活 →
|
||
智能体执行 → 总控汇总结论。一次问答会话记为一条「手动执行」记录，过程消息可查。
|
||
|
||
### 3.1 发起问答会话（init）
|
||
|
||
```
|
||
POST /api/task-analysis/tasks/{task_id}/qa/init
|
||
```
|
||
|
||
> 注意：此处 `{task_id}` 为 **DeerFlow 内部任务 id**（创建接口响应里的 `task_id`）。
|
||
|
||
请求体：空（无需参数）。
|
||
|
||
响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"run_id": "tar-0743654e-…",
|
||
"coordinator": "roundtable-coordinator",
|
||
"thread_ids": {
|
||
"eightbf-roundtable-intent": "ta-seat-…-…",
|
||
"c0a8799da8724e179e086ea9ca723967": "ta-seat-…-…",
|
||
"roundtable-coordinator": "ta-seat-…-…"
|
||
},
|
||
"seats": [
|
||
{ "agent_id": "eightbf-roundtable-intent", "name": "8BF 任务理解" },
|
||
{ "agent_id": "c0a8799da8724e179e086ea9ca723967", "name": "策略分析师" }
|
||
]
|
||
}
|
||
```
|
||
|
||
- `run_id`：本次问答会话的运行记录 id（查历史 / 应用方向都用它）。
|
||
- `thread_ids`：**会话线程映射，请保存并在后续每轮 stream 原样传回**（会话不跨请求保存在服务端）。
|
||
- init 时已自动把任务上下文（名称/简介/编排/历次方向备注）注入总控，之后每轮消息传用户原话即可。
|
||
|
||
错误：`400` —— 任务未绑定分析方案 / 绑定链没有可调度席位。
|
||
|
||
### 3.2 发送消息（stream，SSE）
|
||
|
||
```
|
||
POST /api/task-analysis/tasks/{task_id}/qa/stream
|
||
Content-Type: application/json
|
||
Accept: text/event-stream
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"run_id": "tar-0743654e-…",
|
||
"message": "请让两个席位各自分析当前的主要风险点，然后给我综合结论。",
|
||
"thread_ids": { "…init 返回的映射原样传回…" }
|
||
}
|
||
```
|
||
|
||
响应为 SSE 流，每帧 `data: {JSON}\n\n`。**帧类型**：
|
||
|
||
| 帧 | 触发时机 | 关键字段 |
|
||
|---|---|---|
|
||
| LangGraph 上游事件（无 `event` 字段的多种帧） | 总控正在生成（token 流） | 透传自运行时，可用于打字机效果 |
|
||
| `{"event": "leader", "status": [[seat_id, task], …], …}` | 总控一轮结束 | `status` 为派活表（二维数组）时表示已派活 |
|
||
| `{"event": "leader", "status": "clarification", …}` | 总控需要澄清 | `question` / `options`，前端展示追问，等用户补充后发下一轮 |
|
||
| `{"event": "leader", "status": [], "content": …}` | 总控给出结论（共识） | `content` 为结论正文 |
|
||
| `{"event": "seat", "agent": id, "name": …, "content": …}` | 某智能体执行完成 | `content` 为该智能体交付正文 |
|
||
| `{"event": "round_done", "consensus": true/false}` | 本轮结束 | `consensus=true` 会话已收口（run 置 succeeded）；`false`（如澄清）可继续发下一轮 |
|
||
|
||
一轮完整时序：`leader（派活）→ 若干 seat（交付）→ leader（综合结论）→ round_done`。
|
||
|
||
约定：
|
||
- 澄清（`consensus=false, kind=clarification`）：继续对**同一 run_id** 发下一轮 stream；
|
||
- 共识（`consensus=true`）：run 已自动收口，如需再问请新开一次 `qa/init`；
|
||
- 客户端中断流不影响服务端继续执行（消息仍会落库，可从历史接口补读）。
|
||
|
||
错误：`404` 会话不存在；`409` 会话已收口（需重新 init）或 `thread_ids` 缺失（重新 init）。
|
||
|
||
### 3.3 应用调整方向（可选）
|
||
|
||
问答结束后，若用户确认「把本次调整应用到后续执行」，调用本接口把结论沉淀为
|
||
**执行方向备注**——该备注会注入此任务后续**每次定时执行**各智能体的任务上下文。
|
||
|
||
```
|
||
POST /api/task-analysis/qa/{run_id}/apply-direction
|
||
```
|
||
|
||
请求体：`{"note": "后续执行请重点关注台湾海峡北段动态，风险输出按高/中/低分级。"}`
|
||
|
||
响应 `200`：`{"applied": true, "direction_notes": ["…", "…"]}`（全部累计备注）。
|
||
|
||
### 3.4 对话历史查询
|
||
|
||
按运行记录查询完整过程消息（总控 + 各智能体），供会话回放或补读。
|
||
|
||
```
|
||
GET /api/task-analysis/external/runs/{run_id}/messages?seat=&limit=500
|
||
```
|
||
|
||
- `seat` 可选：传智能体 agent_id 只看该席位；传 `__coordinator__` 只看总控；不传看全部。
|
||
- 响应：`{"run": {"id", "trigger", "status", "started_at", "finished_at"}, "messages": […]}`
|
||
- 消息字段：`seq`（顺序）、`seat_agent_id`、`stage_index`、`event_type`
|
||
（`input` 输入 / `llm.ai` 智能体输出 / `artifact` 产物备注）、`content`。
|
||
|
||
## 4. 定时数据交付（任务 6 块数据）
|
||
|
||
按任务展示 **6 块结构化数据**（相当于 6 个页面分区，每块含多个部分），每块一个
|
||
JSON 对象。DeerFlow 只负责数据管道与调度：智能体在定时执行过程中把成果提交进
|
||
数据块，归配智能体 / 业务链的配置由管理方维护。
|
||
|
||
**口径要点**：
|
||
|
||
- 块 key 定死 `block_1`~`block_6`，标题默认「数据块一~六」，可经 4.4 修改；
|
||
存量 5 块任务在读接口 / 首次提交时懒补 `block_6`，已改过的标题不覆盖；
|
||
- payload 不做 schema 校验（结构会变），只要求是 **JSON 对象**；
|
||
- 不定席位↔块映射：多个智能体可各写一个块的不同部分，一个智能体也可写多个块；
|
||
- 同一块多次提交按「**顶层 key 合并、同 key 后写覆盖**」合并——某个部分一提交，
|
||
立刻体现在任务的当前数据里（实时更新）；
|
||
- **不挂时间轴**：一个任务的数据只有一份「当前状态」，所有提交（定时轮次、
|
||
手动触发、对话修复）都合并进它，越提交越新；
|
||
- 调度不管上一轮跑没跑完：到期照常触发，**同任务允许多轮并行**，不跳过不顺延；
|
||
多轮提交按流水顺序收敛到同一份数据；
|
||
- 首次提交时若任务还没有数据承载记录，自动创建一条（`trigger=external`），
|
||
保证写入永远成功。
|
||
|
||
### 4.1 数据块定义列表
|
||
|
||
```
|
||
GET /api/task-analysis/external/tasks/{source_task_id}/blocks
|
||
```
|
||
|
||
响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"task": {"task_id": "ta-TS-2026-0147", "source_task_id": "TS-2026-0147", "name": "东南亚舆论环境监测"},
|
||
"blocks": [
|
||
{"block_key": "block_1", "title": "数据块一", "sort_order": 1},
|
||
{"block_key": "block_2", "title": "数据块二", "sort_order": 2},
|
||
{"block_key": "block_3", "title": "舆情热点", "sort_order": 3},
|
||
{"block_key": "block_4", "title": "数据块四", "sort_order": 4},
|
||
{"block_key": "block_5", "title": "数据块五", "sort_order": 5},
|
||
{"block_key": "block_6", "title": "数据块六", "sort_order": 6}
|
||
]
|
||
}
|
||
```
|
||
|
||
固定 6 条，按 `sort_order` 升序返回；`title` 为修改后的标题（见 4.4）。
|
||
|
||
### 4.2 当前数据状态（兼容旧路径 periods）
|
||
|
||
```
|
||
GET /api/task-analysis/external/tasks/{source_task_id}/periods
|
||
```
|
||
|
||
时间轴已去掉：任务的数据只有一份当前状态，本接口固定返回**唯一一条**当前数据
|
||
承载记录（`periods` 数组长度恒为 1，`is_current` 恒为 `true`），供消费方感知
|
||
数据更新时间。响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"task": {"task_id": "…", "source_task_id": "…", "name": "…"},
|
||
"current_period_index": 3,
|
||
"total": 1,
|
||
"periods": [
|
||
{
|
||
"period_index": 3,
|
||
"opened_at": "2026-09-14T15:00:00+08:00",
|
||
"trigger": "cron",
|
||
"run_id": "tar-…",
|
||
"is_current": true,
|
||
"blocks": {
|
||
"block_1": {"updated_at": "2026-09-14T15:03:12+08:00"},
|
||
"block_2": {"updated_at": null},
|
||
"block_3": {"updated_at": null},
|
||
"block_4": {"updated_at": null},
|
||
"block_5": {"updated_at": null},
|
||
"block_6": {"updated_at": null}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- 各块 `updated_at` 为 `null` 表示该块尚无数据；
|
||
- 首条承载记录由首次数据提交自动创建（`trigger=external`）；存量任务沿用
|
||
历史期号（`period_index` 数值仅作标识，无时间轴含义）。
|
||
|
||
### 4.3 单期数据详情
|
||
|
||
```
|
||
GET /api/task-analysis/external/tasks/{source_task_id}/periods/{period}
|
||
```
|
||
|
||
`{period}` 传期号数字（如 `2`）或 `latest`（当前最新一期）。响应 `200`：
|
||
|
||
```json
|
||
{
|
||
"task": {"task_id": "…", "source_task_id": "…", "name": "…"},
|
||
"period": {
|
||
"period_index": 2,
|
||
"opened_at": "2026-09-14T12:00:00+08:00",
|
||
"trigger": "cron",
|
||
"run_id": "tar-…",
|
||
"is_current": false
|
||
},
|
||
"blocks": [
|
||
{
|
||
"block_key": "block_1",
|
||
"title": "数据块一",
|
||
"sort_order": 1,
|
||
"payload": {"热点列表": ["…"], "统计": {"提及量": 128}},
|
||
"updated_at": "2026-09-14T12:04:55+08:00"
|
||
},
|
||
{"block_key": "block_2", "title": "数据块二", "sort_order": 2, "payload": null, "updated_at": null}
|
||
]
|
||
}
|
||
```
|
||
|
||
- `blocks` 固定 6 条、按 `sort_order` 升序；尚未提交的块 `payload` / `updated_at`
|
||
为 `null`；
|
||
- `payload` 即该块的**合并结果**（多次提交按顶层 key 合并、同 key 后写覆盖），
|
||
结构由智能体产出决定，请按 JSON 对象渲染；
|
||
- `{period}` 推荐传 `latest`（当前数据）；传数字期号可访问存量任务的历史
|
||
遗留数据（时间轴去掉前的旧期，仅供排查）。
|
||
|
||
错误：`404` —— 期不存在；`400` —— `period` 既不是数字也不是 `latest`。
|
||
|
||
### 4.4 修改块标题 / 排序（管理端）
|
||
|
||
块标题支持后续修改（页面 + API）。`{task_id}` 为 **DeerFlow 内部任务 id**（创建
|
||
接口响应里保存的那个）。
|
||
|
||
```
|
||
PUT /api/task-analysis/tasks/{task_id}/blocks
|
||
```
|
||
|
||
请求体（只传要改的块；块集合固定 6 条，不能增删）：
|
||
|
||
```json
|
||
{
|
||
"blocks": [
|
||
{"block_key": "block_3", "title": "舆情热点"},
|
||
{"block_key": "block_1", "sort_order": 9}
|
||
]
|
||
}
|
||
```
|
||
|
||
响应 `200`：`{"blocks": […]}`（修改后的完整定义列表，形状同 4.1）。
|
||
错误：`400` —— `block_key` 不在 `block_1`~`block_6` 内。
|
||
|
||
### 4.5 演示数据（已预存）
|
||
|
||
开发环境已预存一个演示任务，可直接用于联调：
|
||
|
||
- 任务号 `source_task_id = BUSINESS-OVERVIEW-DEMO`；`block_1` 标题「商业态势总览」；
|
||
- 预存时按 13 期小时刻度写入（时间轴去掉前的演示口径）；当前对外仅暴露最新一期
|
||
的 `block_1` payload = 页面整卡数据（`pageTitle` / `briefs` / `objectives` /
|
||
`events` / `businessNarratives` / `insights` / `chart` / `snapshotName` 等，
|
||
与页面 mock 快照同构）；`block_2`~`block_6` 暂无数据；
|
||
- 预存脚本：`scripts/seed_business_overview_demo.py`（可重复运行，幂等重建）。
|
||
|
||
### 4.6 智能体数据提交（内部，供参考）
|
||
|
||
智能体侧由内置技能 `task-data-submit`（`skills/public/task-data-submit/`）调以下
|
||
接口完成入库，**对方系统无需调用**，此处仅供联调排查参考：
|
||
|
||
```
|
||
POST /api/task-analysis/data/submit
|
||
```
|
||
|
||
请求体：`{"task_id": "<source_task_id>", "block_key": "block_2", "data": {…JSON 对象…}}`。
|
||
响应 `200`：`{"source_task_id", "task_id", "block_key", "period_index", "updated_at", "keys"}`。
|
||
错误：`400` —— 块 key 非法 / payload 不是对象；`404` —— 任务不存在；`422` ——
|
||
请求体不是合法 JSON 对象。
|
||
|
||
## 5. 典型对接流程
|
||
|
||
```
|
||
对方系统创建任务
|
||
└─ POST /external/tasks ──► 保存 task_id（+ default_chain_id）
|
||
│
|
||
│ （DeerFlow 管理页配置：选业务链 + 执行频率 —— 无需开发）
|
||
▼
|
||
按 cron 自动执行（多轮并行，产出时间线版本）
|
||
├─ 详情页定期/手动 GET /external/tasks/{source_task_id}/detail ──► 渲染 blocks
|
||
└─ 数据交付（任务 6 块 JSON，见第 4 章）
|
||
├─ GET /external/tasks/{source_task_id}/periods ──► 当前数据状态（兼容路径）
|
||
└─ GET /external/tasks/{source_task_id}/periods/latest ──► 6 块完整 JSON
|
||
│
|
||
▼
|
||
详情页问答（可选）
|
||
├─ POST /tasks/{task_id}/qa/init ──► 保存 run_id + thread_ids
|
||
├─ POST /tasks/{task_id}/qa/stream（每轮，SSE 渲染对话与席位交付）
|
||
├─ （可选）POST /qa/{run_id}/apply-direction ──► 调整注入后续执行
|
||
└─ GET /external/runs/{run_id}/messages ──► 历史回放
|
||
|
||
对方系统删除任务
|
||
└─ DELETE /external/tasks/{source_task_id} ──► DeerFlow 侧级联清除
|
||
```
|
||
|
||
## 6. 错误码汇总
|
||
|
||
| 状态 | 场景 |
|
||
|---|---|
|
||
| 400 | 任务未绑定分析方案 / 链无席位 / 请求参数非法 / 数据块 key 非法 |
|
||
| 401 | 未带 token 或 token 失效 |
|
||
| 404 | 任务 / 会话 / 运行记录 / 期不存在 |
|
||
| 409 | `source_task_id` 重复创建；会话已收口或线程映射缺失；执行被跳过（业务链已删除/停用） |
|