vent_deep_agent/API_DOCUMENTATION.md

通风数据解读 API 接口文档

服务器地址: http://39.97.59.228:8070

文档版本: v1.0

---

目录

• 接口概览
• SSE 流式响应格式
• 点选巷道解读接口
• 点选设备解读接口
• 对话式解读接口
• 聊天历史查询接口
• 会话列表接口
• 删除会话接口
• 工具清单

---

接口概览

方法	路径	描述	类型
POST	/api/interpret/click/tun	点选/悬浮巷道数据解读	SSE 流式
POST	/api/interpret/click/device	点选/悬浮设备数据解读	SSE 流式
POST	/api/chat	对话式数据解读 / 需风量计算	SSE 流式
POST	/api/vent/review/pdf	配风计划审查（PDF 上传）	SSE 流式
GET	/api/chat/history/{session_id}	查询聊天历史	常规
GET	/api/sessions	查询会话列表	常规
DELETE	/api/sessions/{session_id}	删除会话	常规

---

SSE 流式响应格式

所有流式接口均采用 Server-Sent Events (SSE) 协议，返回 text/event-stream 类型。

通用响应头

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Session-Id: {session_id}

事件类型 (type 字段)

流式返回数据以 data: 开头，JSON 格式，核心字段定义如下：

type	描述	核心字段
thinking	AI 正在思考/推理	source, node, message
executing	AI 正在执行工具调用	source, tools, message
tool_call	检测到工具调用	source, tool, message
tool_result	工具执行结果返回	source, tool, message
updated_todo_list	Todo 列表更新	source, todos, message
token	AI 生成的文本内容	source, content
done	流式响应结束	thread_id, session_id, message
generating	Fast 模式：LLM 开始生成报告	source
progress	Fast 模式：等待心跳进度	message
reasoning	Fast 模式：推理模型思考过程（如 DeepSeek-R1）	content
error	发生错误	message

message 字段（v1.3+）：所有事件均包含中文 message 字段，描述当前正在执行的操作，如 "正在分析您的问题..."、"查询巷道监测数据 完成"。前端可据此展示进度提示。

配风计划审查专属事件

配风计划 PDF 审查接口还会产生以下额外事件类型：

type	描述	核心字段
progress	审查进度更新	message, agent, hash_id, download_url
agent_start	子智能体开始审查	agent, message
agent_thinking	子智能体正在分析	agent, message
agent_executing	子智能体执行工具	agent, message, tools
agent_todos	子智能体任务进度更新	agent, message, todos
agent_tool_result	子智能体工具执行完成	agent, message, tool
agent_done	子智能体审查完成	agent, message, preview, progress
agent_error	子智能体审查出错	agent, message, error
generating	LLM 正在生成报告	source

source 字段说明

值	含义
main	主代理（当前对话）
subagent	子代理（被调用的工具代理）
fast	Fast 模式直连（跳过 Agent）

---

点选巷道解读接口

POST /api/interpret/click/tun

解读模式

接口支持两种模式，通过 mode 参数控制：

模式	值	行为	适用场景
Plan（默认）	"plan"	走完整智能体流程：加载技能 → 调用工具 → 逐项比对规程 → 生成结构化报告	需要深度分析、规程溯源
Fast	"fast"	跳过智能体和技能，直接查询数据后发给 LLM 按模板生成报告	快速预览、延迟敏感场景

区别：Plan 模式会调用多个工具逐项核查（知识库检索、规程比对等），输出更严谨完整；Fast 模式仅一次数据查询 + 一次 LLM 调用，响应更快但分析深度较浅。

数据库：点选解读接口不写数据库，不创建会话、不保存消息记录。

请求示例

Plan 模式（默认）：

{
  "tun_id": "15216",
  "tun_name": "15216 辅运起坡段"
}

Fast 模式：

{
  "tun_id": "15216",
  "tun_name": "15216 辅运起坡段",
  "mode": "fast"
}

请求参数

参数	类型	必填	描述
tun_id	string	是	巷道 ID
tun_name	string	是	巷道名称
mode	string	否	解读模式："plan"（智能体全流程，默认）或 "fast"（直接生成报告）

响应示例

Plan 模式（智能体全流程）：

data: {"type": "thinking", "source": "main", "node": "model"}

data: {"type": "executing", "source": "main", "tools": ["query_knowledge_base"]}

data: {"type": "tool_call", "source": "main", "tool": "query_knowledge_base"}

data: {"type": "tool_result", "source": "main", "tool": "query_knowledge_base"}

data: {"type": "token", "source": "main", "content": "根据监测数据，该巷道当前风速为"}

data: {"type": "done", "thread_id": "xxx", "session_id": "xxx"}

Fast 模式（直连 LLM）：

data: {"type": "thinking", "source": "fast", "node": "fetching_data"}

data: {"type": "executing", "source": "fast", "tools": ["query_tun_data_by_id"]}

data: {"type": "generating", "source": "fast"}

data: {"type": "token", "source": "fast", "content": "**15216 辅运起坡段**\n- 当前风速："}

data: {"type": "done", "thread_id": "xxx", "session_id": "xxx"}

Fast 模式下 source 为 "fast"，不会出现 tool_call/tool_result/updated_todo_list 等 Agent 独有事件；LLM 生成阶段可能出现 progress（心跳）和 reasoning（推理过程）事件。

---

点选设备解读接口

POST /api/interpret/click/device

解读模式

与巷道解读接口相同，支持 mode 参数：

模式	值	行为
Plan（默认）	"plan"	走完整智能体流程：加载技能 → 调用工具 → 逐项比对 → 生成报告
Fast	"fast"	跳过智能体，直接查数据 + LLM 生成报告

点选设备解读同样不写数据库。

请求示例

Plan 模式（默认）：

{
  "device_id": "FAN-001",
  "device_name": "主通风机",
  "device_type": "fan"
}

Fast 模式：

{
  "device_id": "FAN-001",
  "device_name": "主通风机",
  "device_type": "fan",
  "mode": "fast"
}

请求参数

参数	类型	必填	描述
device_id	string	是	设备 ID
device_name	string	是	设备名称
device_type	string	是	设备类型
mode	string	否	解读模式："plan"（默认）或 "fast"

响应格式

与巷道解读接口相同，返回该设备的数据解读报告。

---

对话式解读接口

POST /api/chat

请求示例

{
  "message": "15216 辅运起坡段当前风速风量情况如何？",
  "session_id": "可选，已有会话ID",
  "thread_id": "可选，LangGraph线程ID"
}

请求参数

参数	类型	必填	描述
message	string	是	用户消息（自然语言）
session_id	string	否	会话 ID，新会话可不传
thread_id	string	否	LangGraph 线程 ID，用于恢复多轮对话状态

流式响应详解

thinking 事件

{
  "type": "thinking",
  "source": "main",
  "node": "model"
}

字段	描述
type	固定为 thinking
source	事件来源：main 或 subagent
node	当前执行节点名称

executing 事件

{
  "type": "executing",
  "source": "main",
  "tools": ["write_todos", "query_knowledge_base"]
}

字段	描述
type	固定为 executing
source	事件来源
tools	即将执行的工具名称列表

tool_call 事件

{
  "type": "tool_call",
  "source": "main",
  "tool": "query_knowledge_base"
}

字段	描述
type	固定为 tool_call
source	事件来源
tool	被调用的工具名称

tool_result 事件

{
  "type": "tool_result",
  "source": "main",
  "tool": "query_knowledge_base"
}

字段	描述
type	固定为 tool_result
source	事件来源
tool	执行完成的工具名称

updated_todo_list 事件

{
  "type": "updated_todo_list",
  "source": "main",
  "todos": [
    {"content": "查询巷道监测数据", "status": "in_progress"},
    {"content": "分析风速风量异常", "status": "pending"}
  ]
}

字段	描述
type	固定为 updated_todo_list
source	事件来源
todos	Todo 列表数组

token 事件

{
  "type": "token",
  "source": "main",
  "content": "根据监测数据，"
}

字段	描述
type	固定为 token
source	事件来源
content	AI 生成的文本片段（逐步累积）

done 事件

{
  "type": "done",
  "thread_id": "a1b2c3d4-...",
  "session_id": "e5f6g7h8-..."
}

字段	描述
type	固定为 done
thread_id	LangGraph 线程 ID
session_id	会话 ID

error 事件

{
  "type": "error",
  "message": "查询超时，请重试"
}

字段	描述
type	固定为 error
message	错误信息描述

---

配风计划审查接口（PDF 上传）

POST /api/vent/review/pdf

功能说明

上传配风计划 PDF 文件，系统自动进行三方面审查：

1. 基本形式审查 — 版本、签字、编制时间、计算过程完整性、语病逻辑
2. 数据一致性审查 — 用风地点完整性、瓦斯/CO₂数据、工作面参数、风速温度匹配
3. 计算核验 — 逐地点调用计算工具核验需风量

三个子智能体并行审查，汇总后流式返回结果，同时生成可下载的 Word 审查报告。

请求参数（multipart/form-data）

参数	类型	必填	描述
file	file	是	配风计划 PDF 文件
session_id	string	否	会话 ID，新会话可不传
message	string	否	附加消息/审查指令
force_refresh	bool	否	是否强制重新 OCR 提取（忽略缓存），默认 false

流式响应示例

data: {"type":"progress","message":"正在保存上传的 PDF 文件...","agent":"system"}

data: {"type":"progress","message":"PDF 文件已保存，HashID: a1b2c3d4...，正在提取文本内容...","agent":"system","hash_id":"a1b2c3d4..."}

data: {"type":"progress","message":"PaddleOCR 正在扫描第 1/12 页...","agent":"system","ocr_progress":{"page":1,"total":12}}

data: {"type":"progress","message":"PDF 文本提取完成，共 45230 字符。正在初始化审查智能体...","agent":"system"}

data: {"type":"progress","message":"3个审查智能体已就绪，正在并行执行审查...","agent":"system"}

data: {"type":"agent_start","agent":"form-reviewer","message":"「基本形式审查」开始审查..."}
data: {"type":"agent_start","agent":"data-checker","message":"「数据一致性审查」开始审查..."}
data: {"type":"agent_start","agent":"calc-verifier","message":"「计算核验审查」开始审查..."}

data: {"type":"agent_thinking","agent":"form-reviewer","message":"「基本形式审查」正在分析..."}
data: {"type":"agent_executing","agent":"calc-verifier","message":"「计算核验审查」正在采煤面综合需风量计算...","tools":["calc_face_air_volume_max"]}
data: {"type":"agent_tool_result","agent":"calc-verifier","message":"「计算核验审查」采煤面综合需风量计算 完成","tool":"calc_face_air_volume_max"}

data: {"type":"agent_todos","agent":"data-checker","message":"「数据一致性审查」已更新任务进度","todos":[{"content":"查询采掘计划","status":"completed"},{"content":"对比用风地点","status":"in_progress"}]}

data: {"type":"agent_done","agent":"form-reviewer","message":"「基本形式审查」审查完成","preview":"## 基本形式审查结果...","progress":"1/3"}
data: {"type":"agent_done","agent":"data-checker","message":"「数据一致性审查」审查完成","preview":"## 数据一致性审查结果...","progress":"2/3"}
data: {"type":"agent_done","agent":"calc-verifier","message":"「计算核验审查」审查完成","preview":"## 计算核验结果...","progress":"3/3"}

data: {"type":"progress","message":"3个子智能体均已审查完成，正在汇总审查结果...","agent":"system"}

data: {"type":"progress","message":"正在生成最终审查报告...","agent":"system"}

data: {"type":"token","content":"# 最终审查报告\n\n## 审查概况..."}

data: {"type":"progress","message":"正在生成 Word 审查报告...","agent":"system"}

data: {"type":"progress","message":"Word 报告已生成，点击下载","agent":"system","download_url":"http://localhost:8000/static/reports/vent_review_abc123_20260713.docx"}

data: {"type":"done","session_id":"xxx","download_url":"http://localhost:8000/static/reports/vent_review_abc123_20260713.docx"}

subagent 字段说明

值	含义
form-reviewer	基本形式审查子智能体
data-checker	数据一致性审查子智能体
calc-verifier	计算核验审查子智能体

审查进度事件详解

progress 事件

{
  "type": "progress",
  "message": "正在提取 PDF 文本...",
  "agent": "system",
  "hash_id": "a1b2c3d4...",
  "ocr_progress": {"page": 3, "total": 12},
  "download_url": "http://..."
}

字段	描述
message	进度描述
agent	"system" 表示系统级进度
hash_id	PDF 文件哈希，用于缓存标识
ocr_progress	OCR 扫描进度（仅 OCR 阶段出现）
download_url	Word 报告下载链接（报告生成完成时出现）

agent_start / agent_done / agent_error 事件

{
  "type": "agent_done",
  "agent": "form-reviewer",
  "message": "「基本形式审查」审查完成",
  "preview": "## 基本形式审查结果\n### 1. 版本审查...",
  "progress": "1/3"
}

字段	描述
agent	子智能体标识
message	状态描述
preview	审查结果预览（前 300 字，仅 agent_done）
progress	完成进度，格式 已完成/总数
error	错误详情（仅 agent_error）

agent_thinking / agent_executing / agent_tool_result 事件

{
  "type": "agent_executing",
  "agent": "calc-verifier",
  "message": "「计算核验审查」正在采煤面综合需风量计算...",
  "tools": ["calc_face_air_volume_max"]
}

字段	描述
agent	子智能体标识
message	操作描述
tools	正在执行的工具名称列表（仅 agent_executing）
tool	完成的工具名称（仅 agent_tool_result）

agent_todos 事件

{
  "type": "agent_todos",
  "agent": "data-checker",
  "message": "「数据一致性审查」已更新任务进度",
  "todos": [
    {"content": "查询采掘计划", "status": "completed"},
    {"content": "对比用风地点完整性", "status": "in_progress"},
    {"content": "校验瓦斯数据", "status": "pending"}
  ]
}

---

聊天历史查询接口

GET /api/chat/history/{session_id}

请求参数（Query）

参数	类型	默认值	描述
limit	int	100	返回条数上限
offset	int	0	偏移量

响应示例

{
  "session_id": "abc123",
  "messages": [
    {
      "role": "user",
      "content": "15216 辅运起坡段当前风速风量情况如何？"
    },
    {
      "role": "assistant",
      "content": "根据监测数据，该巷道当前..."
    }
  ],
  "total": 10
}

响应字段

字段	描述
session_id	会话 ID
messages	消息列表，每条包含 role 和 content
total	消息总条数

---

会话列表接口

GET /api/sessions

请求参数（Query）

参数	类型	默认值	描述
limit	int	20	返回条数上限
offset	int	0	偏移量

响应示例

{
  "sessions": [
    {
      "session_id": "xxx",
      "title": "15216 辅运起坡段...",
      "message_count": 5,
      "created_at": "2024-01-15T10:30:00"
    }
  ],
  "total": 15
}

---

删除会话接口

DELETE /api/sessions/{session_id}

路径参数

参数	类型	描述
session_id	string	要删除的会话 ID

响应示例

{
  "status": "ok",
  "message": "会话 xxx 已删除"
}

---

工具清单

系统工具分为数据查询、知识库检索、需风量计算、MCP 远程查询四类。

数据查询工具（对话解读 / 点选解读）

工具名称	描述
query_tun_data_by_id	根据巷道 ID 查询巷道监测数据（风速、风量、瓦斯、温度等）
query_device_data_by_id	根据设备 ID 查询设备实时数据和报警信息
query_devices_by_tunnel	根据巷道名称查询关联设备列表
query_devices_by_tunnel_id	根据巷道 ID 查询已绑定设备
get_tun_list_by_modelid	根据模型 ID 获取巷道列表
query_knowledge_base	检索煤矿安全知识库（《煤矿安全规程》条款）
write_todos	任务清单管理工具

需风量计算工具（需风量计算 / 配风计划审查）

工具名称	描述
calc_face_by_gas	按瓦斯涌出量计算采煤面需风量
calc_face_by_workers	按人数计算采煤面需风量
calc_face_by_wind_speed	按风速验算采煤面需风量
calc_face_air_volume_max	采煤面需风量综合计算（取各方法最大值）
calc_tunnel_by_gas	按瓦斯涌出量计算掘进面需风量
calc_tunnel_by_explosives	按炸药量计算掘进面需风量
calc_tunnel_by_workers	按人数计算掘进面需风量
calc_tunnel_by_wind_speed	按风速验算掘进面需风量
calc_tunnel_air_volume_max	掘进面需风量综合计算（取各方法最大值）
calc_chamber_by_equipment	按设备发热量计算机电硐室需风量
calc_chamber_by_wind_speed	按风速验算硐室需风量
calc_other_by_wind_speed	按风速计算其他巷道需风量
calc_effective_area	计算工作面有效断面积
calc_total_air_volume	汇总矿井总需风量
get_needq_all_data	获取通防管控平台全部需风量数据（MCP）

MCP 配风计划审查工具（仅 PDF 审查）

工具名称	MCP 服务端工具名	描述
query_mining_plan	query_monthly_mining_plan	查询煤矿月度采掘计划
query_face_procedure	query_working_face_procedure	查询工作面作业规程参数
query_gas_report	query_gas_identification_report	查询瓦斯等级鉴定报告
query_wind_report	query_ventilation_report	查询测风报表数据

write_todos 工具响应

当调用 write_todos 时，会触发 updated_todo_list 事件：

{
  "type": "updated_todo_list",
  "source": "main",
  "message": "任务进度已更新",
  "todos": [
    {"content": "查询巷道监测数据", "status": "pending"},
    {"content": "分析风速风量异常", "status": "in_progress"},
    {"content": "生成解读报告", "status": "pending"}
  ]
}

Todo 状态枚举：

• pending: 待执行
• in_progress: 执行中
• completed: 已完成

---

前端接入示例

SSE 连接示例 (JavaScript)

async function connectChat(message, sessionId = null) {
  const response = await fetch('http://39.97.59.228:8070/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, session_id: sessionId })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split('\n\n');

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        handleSSEMessage(data);
      }
    }
  }
}

function handleSSEMessage(data) {
  switch (data.type) {
    case 'thinking':
      console.log('AI思考中...', data.node);
      break;
    case 'executing':
      console.log('执行工具:', data.tools);
      break;
    case 'token':
      appendContent(data.content);
      break;
    case 'done':
      console.log('完成', data.session_id);
      break;
  }
}

---

错误处理

常见错误码

HTTP 状态码	含义
400	请求参数错误
404	会话不存在
500	服务器内部错误

错误响应格式

{
  "type": "error",
  "message": "详细错误信息"
}

---

文档生成时间: 2024年