deerflow-code/NEW_CHAT_STREAM_FORMAT.md

New Chat 接口流式返回格式说明

接口概览

• 路径：POST /new_chat
• 传输协议：Server-Sent Events (SSE)
• Content-Type：text/event-stream
• 协议基础：Vercel AI SDK Data Stream Protocol

---

请求格式

{
  "chat_id": 123,
  "search_space_id": 456,
  "user_query": "用户问题",
  "pic_query": [{"image_url": "/tmp/xxx.png"}],
  "model_name": "gpt-4o",
  "enable_citations": true,
}

字段	类型	必填	说明
chat_id	int	✅	会话 ID，同时作为 LangGraph 的 thread_id
search_space_id	int	✅	搜索空间 ID
user_query	string	✅	用户问题
pic_query	list|null	❌	图片路径列表，格式 [{"image_url": "..."}]
model_name	string|null	❌	指定模型名称（插件场景使用）
enable_citations	bool	❌	是否启用引用（默认 true）
messages	list|null	❌	历史消息列表
attachments	list|null	❌	上传附件（已解析为 Markdown）
mentioned_document_ids	list|null	❌	前端 @ 引用的文档 ID 列表

---

响应 Headers

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

---

SSE 数据帧格式

每条消息均为标准 SSE 格式：

data: {JSON 对象}\n\n

流结束时发送：

data: [DONE]\n\n

---

事件类型详解

1. 消息生命周期

start — 消息开始

{"type": "start", "messageId": "msg_abc123"}

字段	说明
messageId	本次消息的唯一 ID

---

finish — 消息结束

{"type": "finish"}

---

[DONE] — 流终止标记

data: [DONE]

这是流中最后一帧，为纯字符串，不是 JSON。

---

2. 步骤控制（多轮工具调用）

start-step — 步骤开始

{"type": "start-step"}

finish-step — 步骤结束

{"type": "finish-step"}

每次 LLM 调用算一个 step。工具调用期间会有多个 step 交替出现。

---

3. 文本块（start / delta / end 模式）

text-start — 文本块开始

{"type": "text-start", "id": "text_abc123"}

text-delta — 文本增量内容

{"type": "text-delta", "id": "text_abc123", "delta": "Hello, "}

text-end — 文本块结束

{"type": "text-end", "id": "text_abc123"}

---

4. 推理块（Reasoning，适用于 DeepSeek R1 等思维链模型）

reasoning-start — 推理块开始

{"type": "reasoning-start", "id": "reasoning_abc123"}

reasoning-delta — 推理增量内容

{"type": "reasoning-delta", "id": "reasoning_abc123", "delta": "让我先思考..."}

reasoning-end — 推理块结束

{"type": "reasoning-end", "id": "reasoning_abc123"}

触发时机：

• 模型返回 additional_kwargs.reasoning_content（DeepSeek R1 原生）
• 模型输出中包含 <think>...</think> 标签（自动剥离）

---

5. 工具调用

tool-input-start — 工具调用开始

{"type": "tool-input-start", "toolCallId": "call_abc123", "toolName": "search_knowledge_base"}

tool-input-delta — 工具输入流式内容（增量）

{"type": "tool-input-delta", "toolCallId": "call_abc123", "inputTextDelta": "San Fra"}

tool-input-available — 工具输入完整参数

{
  "type": "tool-input-available",
  "toolCallId": "call_abc123",
  "toolName": "search_knowledge_base",
  "input": {"query": "机器学习入门"}
}

tool-output-available — 工具执行结果

{
  "type": "tool-output-available",
  "toolCallId": "call_abc123",
  "output": {"status": "completed", "result_length": 1234}
}

注意：search_knowledge_base 只返回摘要（不含全文），write_todos、link_preview、display_image、scrape_webpage、generate_podcast 会返回完整 output 供前端渲染组件。

---

6. 来源引用

source-url — URL 来源

{
  "type": "source-url",
  "sourceId": "https://example.com",
  "url": "https://example.com",
  "title": "示例页面"
}

source-document — 文档来源

{
  "type": "source-document",
  "sourceId": "doc_123",
  "mediaType": "file",
  "title": "报告.pdf",
  "description": "第三季度报告"
}

---

7. 文件

{"type": "file", "url": "https://example.com/image.png", "mediaType": "image/png"}

---

8. 自定义数据（data-* 类型）

data-terminal-info — 终端信息提示

{
  "type": "data-terminal-info",
  "data": {
    "text": "知识库搜索已完成",
    "type": "success"
  }
}

type 枚举值：info | error | success | warning

---

data-further-questions — 推荐追问问题

{
  "type": "data-further-questions",
  "data": {
    "questions": ["问题1", "问题2", "问题3"]
  }
}

---

data-thinking-step — 思考步骤（思维链 UI 展示）

{
  "type": "data-thinking-step",
  "data": {
    "id": "thinking-1",
    "title": "正在搜索知识库",
    "status": "in_progress",
    "items": ["Query: 机器学习入门"]
  }
}

字段	说明
id	步骤唯一 ID（格式 thinking-N）
title	步骤标题
status	pending | in_progress | completed
items	步骤详情列表（可选）

同一个 id 的步骤事件会被重复发送以更新状态（先 in_progress 后 completed）。

常见步骤标题对照：

工具 / 场景	标题
初始分析	正在理解您的请求 / 正在分析您的内容
search_knowledge_base	查询个人知识库中
search_web	网查搜索中
link_preview	正在获取链接预览
display_image	正在分析图片
scrape_webpage	正在抓取网页
write_todos（首次）	正在创建计划
write_todos（更新）	正在更新进度
generate_podcast	正在生成播客

---

9. 错误

{
  "type": "error",
  "errorText": "API rate limit exceeded",
  "errorType": "llm",
  "errorCode": "rate_limit"
}

字段	说明
errorText	错误描述文本
errorType	错误类型（见下表）
errorCode	具体错误代码（可选）

errorType 枚举：

值	含义
llm	LLM / API 错误（模型不存在、限流、密钥错误等）
network	网络连通性错误
timeout	请求超时
authentication	鉴权 / 权限错误
rate_limit	速率限制
validation	输入验证错误
internal	内部服务器错误
unknown	未知错误

---

10. 中断（Human-in-the-loop）

{
  "type": "interrupt",
  "messageId": "msg_abc123",
  "interrupt": {
    "action_requests": [...],
    "review_configs": [...]
  },
  "payload": {"expertAgentId": 42}
}

---

完整流示例（普通问答）

data: {"type":"start","messageId":"msg_abc123"}

data: {"type":"start-step"}

data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"in_progress","items":["Processing: 什么是向量数据库？"]}}

data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"completed","items":["Processing: 什么是向量数据库？"]}}

data: {"type":"text-start","id":"text_xyz789"}

data: {"type":"text-delta","id":"text_xyz789","delta":"向量数据库是"}

data: {"type":"text-delta","id":"text_xyz789","delta":"一种专为存储和检索"}

data: {"type":"text-delta","id":"text_xyz789","delta":"高维向量而设计的数据库..."}

data: {"type":"text-end","id":"text_xyz789"}

data: {"type":"finish-step"}

data: {"type":"finish"}

data: [DONE]

---

完整流示例（含工具调用）

data: {"type":"start","messageId":"msg_abc123"}

data: {"type":"start-step"}

data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"in_progress","items":["Processing: 搜索最新 AI 论文"]}}

data: {"type":"data-thinking-step","data":{"id":"thinking-1","title":"正在理解您的请求","status":"completed","items":["Processing: 搜索最新 AI 论文"]}}

data: {"type":"data-thinking-step","data":{"id":"thinking-2","title":"查询个人知识库中","status":"in_progress","items":["Query: 最新 AI 论文"]}}

data: {"type":"tool-input-start","toolCallId":"call_xxx","toolName":"search_knowledge_base"}

data: {"type":"tool-input-available","toolCallId":"call_xxx","toolName":"search_knowledge_base","input":{"query":"最新 AI 论文"}}

data: {"type":"data-thinking-step","data":{"id":"thinking-2","title":"Searching knowledge base","status":"completed","items":["Query: 最新 AI 论文","Found relevant information (2048 chars)"]}}

data: {"type":"tool-output-available","toolCallId":"call_xxx","output":{"status":"completed","result_length":2048}}

data: {"type":"data-terminal-info","data":{"text":"知识库搜索已完成","type":"success"}}

data: {"type":"text-start","id":"text_xyz789"}

data: {"type":"text-delta","id":"text_xyz789","delta":"根据知识库中的内容..."}

data: {"type":"text-end","id":"text_xyz789"}

data: {"type":"finish-step"}

data: {"type":"finish"}

data: [DONE]

---

完整流示例（含推理过程）

data: {"type":"start","messageId":"msg_abc123"}

data: {"type":"start-step"}

data: {"type":"reasoning-start","id":"reasoning_r01"}

data: {"type":"reasoning-delta","id":"reasoning_r01","delta":"让我先分析这个问题..."}

data: {"type":"reasoning-delta","id":"reasoning_r01","delta":"需要考虑以下几个方面..."}

data: {"type":"reasoning-end","id":"reasoning_r01"}

data: {"type":"text-start","id":"text_xyz789"}

data: {"type":"text-delta","id":"text_xyz789","delta":"综合分析后，结论是..."}

data: {"type":"text-end","id":"text_xyz789"}

data: {"type":"finish-step"}

data: {"type":"finish"}

data: [DONE]

---

标准消息流顺序

start
  └─ start-step
       ├─ [data-thinking-step × N]   思考步骤（可多次）
       ├─ [reasoning-start/delta/end] 推理过程（可选）
       ├─ [tool-input-start]          工具调用开始（可多次）
       ├─ [tool-input-available]      工具参数确认
       ├─ [tool-output-available]     工具结果
       ├─ [data-terminal-info]        终端提示（可多次）
       ├─ [source-url / source-document] 来源引用（可选）
       ├─ text-start
       │    └─ text-delta × N         流式文本
       └─ text-end
     finish-step
finish
[DONE]