LQConstPlanWriterAgent/docs/文档编辑AI对话接口文档.md

文档编辑 AI 对话接口对接文档

1. 接口用途

/sgbx/document_chat 用于文档编辑页中，围绕“当前选中章节”发起 AI 对话。当前支持两类能力：

• 章节问答：总结、解释、分析、判断当前章节是否合理或完整。
• 章节修改：润色、扩写、改写、补充、压缩、优化当前章节正文，并返回修改草案。

注意：

• 本接口只处理文档编辑 AI 对话，不影响方案编写、大纲生成、章节续写等 construction_write 接口。
• 修改类请求只返回草案，不直接保存或替换章节。
• 当前版本不生成 diff；返回体中的 diff、old_content_hash、new_content_hash、diff_granularity 是保留字段，默认为空。
• references 只返回通过质量门控、实际提交给大模型的知识库参考。
• SSE 中的 reasoning 是可展示的处理过程，不是模型原始思维链；原始 <think>...</think> 内容不会透出。
• 当前 SSE 会流式推送流程事件，但 chunk 仍是在模型生成完成后一次性推送完整回答或完整草案，不是 token 级逐字输出。

2. 意图判定

接口不是根据最终文本判断“问答”或“修改”，而是在工作流前置阶段先执行意图识别。

2.1 判定入口

• 工作流节点：recognize_intent
• 模型功能名：document_chat_intent
• 可调用技能白名单：document-answer、document-modify

意图识别模型的核心输入：

字段	说明
message	用户本轮输入
selected_section.index/title/code/content_preview	当前选中章节信息和正文预览
project_info	项目信息
document_context	前后文、同级章节、检索范围
available_skills	后端允许调用的技能列表

意图识别模型返回 JSON，示例：

{
  "intent": "document_modify",
  "confidence": 0.88,
  "skill_name": "document-modify",
  "operation": "expand",
  "target_scope": "selected_section",
  "normalized_instruction": "补充当前章节施工准备、现场条件和工程特点",
  "needs_clarification": false,
  "clarification_question": "",
  "reason": "",
  "warnings": []
}

2.2 路由规则

判定结果	条件	后续执行	最终 response_type
章节问答	skill_name=document-answer	执行 DocumentAnswerSkill	answer
章节修改	skill_name=document-modify	执行 DocumentModifySkill	proposal
需要澄清	needs_clarification=true、intent=clarify 或 confidence < 0.65	返回澄清问题	clarify
不支持	intent=unsupported 或 skill 不在白名单	返回不支持说明	unsupported
异常	工作流或模型调用异常	返回错误信息	error

后端会做白名单归一化：如果模型返回的 intent 与 skill_name 不一致，但 skill_name 命中白名单且不需要澄清，则优先信任白名单 skill 并修正 intent。

2.3 意图识别失败兜底

如果意图识别模型异常或返回非 JSON，后端使用关键词兜底：

用户输入包含	兜底意图
怎么完善、如何完善、怎样完善、完善建议、修改建议、优化建议、补充建议、怎么改、如何改	document_answer
润色、扩写、改写、修改、补充、完善、压缩、简化、优化、替换、重写	document_modify
解释、说明、总结、分析、是否、为什么、哪里、问题、合理、缺少	document_answer
空消息	clarify
其他	默认 document_answer

3. 接口地址

3.1 普通 JSON

POST /sgbx/document_chat

3.2 SSE

POST /sgbx/document_chat?stream=true

也可以在请求体中传：

{
  "response_mode": "sse"
}

当 query 参数 stream=true 或请求体 response_mode=sse 任一成立时，接口返回 text/event-stream。

3.3 健康检查

GET /sgbx/document_chat/health

返回示例：

{
  "status": "healthy",
  "module": "document_chat",
  "workflow": "langgraph",
  "skills": ["document-answer", "document-modify"]
}

4. 请求参数

请求体不允许传入未定义字段。

字段	类型	必填	说明
user_id	string	是	用户 ID
message	string	是	用户问题或修改要求，不能为空
selected_section	object	是	当前选中章节
conversation_id	string/null	否	会话 ID
task_id	string/null	否	业务任务 ID
project_info	object	否	项目信息
document_context	object	否	章节上下文和检索范围
conversation_history	array	否	历史对话
response_mode	string	否	json 或 sse，默认 json

selected_section：

字段	类型	必填	说明
index	string	是	章节编号，例如 2.1
title	string	是	章节标题
content	string	否	当前章节正文
code	string	否	章节编码
chapter_level_1	string	否	一级章节分类，用于相似章节检索
chapter_level_2	string	否	二级章节分类，用于相似章节检索

document_context：

字段	类型	说明
before	string	当前章节前文
after	string	当前章节后文
siblings	array	同级章节摘要
references	array	入参允许传入，但生成阶段会被后端质量门控后的知识库参考覆盖
retrieval_filters	object	RAG 检索范围

retrieval_filters 常用字段：

{
  "tenant_id": "tenant-001",
  "project_id": "project-001",
  "knowledge_base_id": "kb-bridge-001",
  "engineering_type": "桥梁工程"
}

检索范围还可以从 selected_section.chapter_level_1、selected_section.chapter_level_2 或 project_info 中补齐。

5. 请求示例

5.1 章节问答

{
  "user_id": "user-001",
  "conversation_id": "conv-001",
  "task_id": "task-001",
  "message": "总结一下这一节主要讲了什么，并判断内容是否完整。",
  "selected_section": {
    "index": "2.1",
    "code": "overview_DesignSummary_ProjectIntroduction",
    "title": "工程简介",
    "content": "本工程为某桥梁施工项目，主要包括桩基、承台、墩柱及上部结构施工。",
    "chapter_level_1": "technology",
    "chapter_level_2": "MethodsOverview"
  },
  "project_info": {
    "project_name": "某桥梁施工方案",
    "engineering_type": "桥梁工程"
  },
  "document_context": {
    "before": "",
    "after": "后续章节为施工总体部署和施工工艺。",
    "retrieval_filters": {
      "knowledge_base_id": "kb-bridge-001",
      "engineering_type": "桥梁工程"
    }
  },
  "response_mode": "json"
}

5.2 章节修改

{
  "user_id": "user-001",
  "conversation_id": "conv-001",
  "task_id": "task-001",
  "message": "把这一节补充完整，增加施工准备、现场条件和工程特点描述。",
  "selected_section": {
    "index": "2.1",
    "code": "overview_DesignSummary_ProjectIntroduction",
    "title": "工程简介",
    "content": "本工程为某桥梁施工项目，主要包括桩基、承台、墩柱及上部结构施工。",
    "chapter_level_1": "technology",
    "chapter_level_2": "MethodsOverview"
  },
  "project_info": {
    "project_name": "某桥梁施工方案",
    "engineering_type": "桥梁工程"
  },
  "document_context": {
    "retrieval_filters": {
      "knowledge_base_id": "kb-bridge-001",
      "engineering_type": "桥梁工程"
    }
  },
  "response_mode": "sse"
}

6. 普通 JSON 返回

6.1 问答成功

{
  "code": 200,
  "message": "success",
  "data": {
    "callback_task_id": "doc_chat_abc123",
    "response_type": "answer",
    "intent_result": {
      "intent": "document_answer",
      "confidence": 0.86,
      "skill_name": "document-answer",
      "operation": "answer",
      "target_scope": "selected_section",
      "normalized_instruction": "总结当前章节并判断是否完整",
      "needs_clarification": false,
      "clarification_question": "",
      "reason": "",
      "warnings": []
    },
    "answer": "本节主要介绍工程概况、施工对象和主要施工内容。当前内容覆盖了主要结构类型，但现场条件、施工准备和关键工程特点仍可补充。",
    "proposed_content": null,
    "old_content_hash": null,
    "new_content_hash": null,
    "diff": [],
    "diff_granularity": null,
    "change_summary": [],
    "references": [],
    "retrieval_status": "low_confidence",
    "retrieval_metrics": {
      "approved_count": 0,
      "retrieval_method": "chapter_similarity"
    },
    "warnings": ["未找到可信度足够的知识库片段，本次未引用向量库内容。"],
    "selected_section": {
      "index": "2.1",
      "code": "overview_DesignSummary_ProjectIntroduction",
      "title": "工程简介"
    },
    "error_message": null
  }
}

6.2 修改成功

{
  "code": 200,
  "message": "success",
  "data": {
    "callback_task_id": "doc_chat_def456",
    "response_type": "proposal",
    "intent_result": {
      "intent": "document_modify",
      "confidence": 0.88,
      "skill_name": "document-modify",
      "operation": "modify",
      "target_scope": "selected_section",
      "normalized_instruction": "补充当前章节施工准备、现场条件和工程特点描述",
      "needs_clarification": false,
      "clarification_question": "",
      "reason": "",
      "warnings": []
    },
    "answer": null,
    "proposed_content": "本工程为某桥梁施工项目，主要包括桩基、承台、墩柱及上部结构施工。施工前应完成图纸会审、测量复核、技术交底和临时设施布置...",
    "old_content_hash": null,
    "new_content_hash": null,
    "diff": [],
    "diff_granularity": null,
    "change_summary": ["补充施工准备", "增加现场条件描述"],
    "references": [],
    "retrieval_status": "low_confidence",
    "retrieval_metrics": {
      "approved_count": 0,
      "retrieval_method": "chapter_similarity"
    },
    "warnings": [],
    "selected_section": {
      "index": "2.1",
      "code": "overview_DesignSummary_ProjectIntroduction",
      "title": "工程简介"
    },
    "error_message": null
  }
}

6.3 字段说明

字段	类型	说明
callback_task_id	string	本次请求 ID
response_type	string	返回类型，见下表
intent_result	object/null	意图识别结果
answer	string/null	问答结果、澄清问题或不支持说明
proposed_content	string/null	修改后的完整章节正文草案
old_content_hash	string/null	保留字段，当前为 null
new_content_hash	string/null	保留字段，当前为 null
diff	array	保留字段，当前为空数组
diff_granularity	string/null	保留字段，当前为 null
change_summary	array	修改摘要，仅 proposal 常见
references	array	通过质量门控并提交给大模型的知识库参考
retrieval_status	string/null	RAG 状态
retrieval_metrics	object	RAG 指标
warnings	array	提示信息
selected_section	object	当前章节摘要，只返回 index/code/title
error_message	string/null	错误信息

response_type 取值：

值	说明
answer	普通问答
proposal	内容修改草案
clarify	需要用户补充说明
unsupported	当前能力不支持
error	执行异常

普通 JSON 模式下，工作流内错误通常返回 code=500 且 data.response_type=error；请求处理层未捕获的异常会返回 HTTP 500。

7. RAG 状态

retrieval_status	出现场景	最终 references
usable	有高质量参考，已提交给大模型	非空
low_confidence	召回或重排内容质量不足，未通过质量门控	空数组
no_scope	缺少可靠检索范围，且不允许无范围检索	空数组
no_recall	没有召回内容	空数组
rerank_failed	重排失败	空数组
disabled	RAG 配置关闭	空数组
recalled	已召回，通常只在中间状态出现	以最终结果为准
reranked	已重排，通常只在中间状态出现	以最终结果为准
null	未进入 RAG，例如澄清、不支持或早期异常	空数组

说明：

• 最终 references 只取质量门控后的 approved_references。
• 召回但未通过质量门控的内容不会进入最终 references。
• SSE 的 retrieval_result 是重排阶段的过程预览，不等同于最终 references。

retrieval_method 常见取值：

retrieval_method	说明
chapter_similarity	根据 chapter_level_1 和 chapter_level_2 走相似章节片段检索
milvus_hybrid_vector	走 Milvus hybrid search 检索
disabled	RAG 配置关闭
empty_query	未构建出有效检索 query
no_scope	缺少可靠检索范围，且不允许无范围检索
unknown	检索异常或未能识别方式

8. SSE 事件

SSE 响应头：

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

SSE 数据格式：

event: event_name
data: {"callback_task_id":"doc_chat_abc123"}

8.1 典型事件顺序

问答或修改流程：

connected
processing
reasoning          # recognize_intent
intent
reasoning          # rerank_context
retrieval_result
skill_started
reasoning          # run_answer_skill 或 run_modify_skill
chunk              # 完整回答或完整草案，一次性推送
answer_completed   # answer
proposal_completed # proposal
completed

澄清或不支持流程：

connected
processing
reasoning          # recognize_intent
intent
answer_completed   # response_type=clarify 或 unsupported
completed

错误流程：

connected
processing
reasoning          # error_handler，视错误发生位置而定
error

实际事件会根据流程分支变化。当前不会发送 retrieval_query、retrieval_recalled、retrieval_reranked、retrieval_approved、retrieval、diff_ready 等事件。

8.2 事件清单

event	说明
connected	SSE 连接成功
processing	工作流启动
reasoning	可展示处理过程
intent	意图识别结果
retrieval_result	重排阶段的参考片段预览
skill_started	技能开始执行
chunk	完整回答或完整草案文本
answer_completed	问答、澄清或不支持流程完成
proposal_completed	修改草案完成
completed	SSE 流程结束
error	错误

8.3 事件 payload

connected

{
  "callback_task_id": "doc_chat_abc123",
  "status": "connected",
  "timestamp": 1779696000
}

processing

{
  "callback_task_id": "doc_chat_abc123",
  "stage_name": "workflow_started",
  "status": "processing",
  "message": "文档 AI 对话工作流已启动"
}

reasoning

{
  "callback_task_id": "doc_chat_abc123",
  "stage_name": "recognize_intent",
  "status": "processing",
  "message": "已完成用户意图识别"
}

当前会主动转成 reasoning 的阶段：

stage_name	message
recognize_intent	已完成用户意图识别
rerank_context	知识库内容检索重排完成
run_answer_skill	已生成章节问答结果
run_modify_skill	已生成章节修改草案
error_handler	流程异常，已进入错误处理

intent

{
  "callback_task_id": "doc_chat_abc123",
  "intent_result": {
    "intent": "document_answer",
    "confidence": 0.86,
    "skill_name": "document-answer",
    "operation": "answer",
    "target_scope": "selected_section",
    "normalized_instruction": "总结当前章节并判断是否完整",
    "needs_clarification": false,
    "clarification_question": "",
    "reason": "",
    "warnings": []
  }
}

retrieval_result

references 最多 8 条，每条 content 最多约 600 字。该事件用于过程展示或调试，最终引用以完成事件中的 references 为准。

{
  "callback_task_id": "doc_chat_abc123",
  "retrieval_status": "reranked",
  "retrieval_method": "chapter_similarity",
  "retrieval_metrics": {
    "recall_count": 18,
    "max_vector_similarity": 0.78,
    "rerank_count": 8,
    "max_rerank_score": 0.86
  },
  "rerank_count": 8,
  "references": [
    {
      "source": "相似施工方案A",
      "content": "施工准备包括图纸会审、测量复核、临时设施布置...",
      "vector_similarity": 0.78,
      "rerank_score": 0.86,
      "metadata": {
        "knowledge_base_id": "kb-bridge-001",
        "file_name": "相似施工方案A",
        "chapter_level_1": "technology",
        "chapter_level_2": "MethodsOverview",
        "source_scope_valid": true
      }
    }
  ],
  "warnings": []
}

skill_started

{
  "callback_task_id": "doc_chat_abc123",
  "skill_name": "document-answer",
  "response_type": "answer"
}

chunk

{
  "callback_task_id": "doc_chat_abc123",
  "chunk": "本节主要介绍工程概况、施工对象和主要施工内容..."
}

answer_completed

answer、clarify、unsupported 都使用该事件完成。payload 为完整 DocumentChatData。

{
  "callback_task_id": "doc_chat_abc123",
  "response_type": "answer",
  "intent_result": {},
  "answer": "本节主要介绍工程概况...",
  "proposed_content": null,
  "change_summary": [],
  "references": [],
  "retrieval_status": "low_confidence",
  "retrieval_metrics": {},
  "warnings": [],
  "selected_section": {
    "index": "2.1",
    "code": "overview_DesignSummary_ProjectIntroduction",
    "title": "工程简介"
  },
  "error_message": null
}

proposal_completed

payload 为完整 DocumentChatData。

{
  "callback_task_id": "doc_chat_def456",
  "response_type": "proposal",
  "intent_result": {},
  "answer": null,
  "proposed_content": "本工程为某桥梁施工项目，主要包括桩基...",
  "change_summary": ["补充施工准备", "增加现场条件描述"],
  "references": [],
  "retrieval_status": "low_confidence",
  "retrieval_metrics": {},
  "warnings": [],
  "selected_section": {
    "index": "2.1",
    "code": "overview_DesignSummary_ProjectIntroduction",
    "title": "工程简介"
  },
  "error_message": null
}

completed

{
  "callback_task_id": "doc_chat_abc123",
  "status": "completed",
  "duration": 3.218
}

error

{
  "callback_task_id": "doc_chat_abc123",
  "response_type": "error",
  "error_message": "错误信息"
}

如果 SSE 生成器外层捕获到异常，error payload 可能是：

{
  "callback_task_id": "doc_chat_abc123",
  "status": "error",
  "message": "错误信息"
}

9. 前端处理建议

• 按 callback_task_id 归并同一次请求的 SSE 事件。
• intent 只用于展示本轮识别为“问答”或“修改”，不要把 intent_result.reason 当成最终 assistant 消息。
• reasoning 展示为处理进度，例如“已完成用户意图识别”“知识库内容检索重排完成”。
• retrieval_result 建议放在“检索详情”或折叠面板；正式引用资料以完成事件和普通 JSON 返回中的 references 为准。
• response_type=answer 时展示 answer。
• response_type=proposal 时展示 proposed_content 和 change_summary；用户确认后由前端或业务后端替换当前章节。
• response_type=clarify 时展示 answer，引导用户补充说明。
• response_type=unsupported 时展示 answer 或不支持说明。
• response_type=error 时展示 error_message 或 message。
• 不要依赖当前保留的 diff 字段；当前服务端不生成 diff。

10. 对接边界

• 本文档只适用于 /sgbx/document_chat。
• 方案编写接口，例如 /sgbx/generating_outline、/sgbx/content_completion，不复用本文档的事件语义。
• 如果前端同时对接方案编写和文档编辑 AI 对话，应按接口路径区分事件处理逻辑。
• AI 服务不保存文档，也不直接替换章节；保存和版本管理由前端或业务后端完成。

11. 服务端日志

文档编辑 AI 对话会写入独立模块日志：

logs/document_chat/

日志按 callback_task_id 串联一次请求，日志消息体为 JSON 字符串。核心事件：

event	记录内容
request_received	请求参数、stream、response_mode
rag_query_built	RAG 查询文本、意图、章节、项目和上下文
rag_recall_completed	RAG 检索方式、召回状态、召回指标、召回结果
rag_rerank_completed	重排指标、召回结果、重排结果
rag_rerank_skipped	未进入重排时的 RAG 状态和原因
rag_quality_gate_completed	质量门控状态、重排结果、最终可引用结果
rag_quality_gate_skipped	未进入质量门控时的 RAG 状态和原因
response_completed	最终输出结果
request_failed	异常信息和请求参数

response_completed 当前不包含服务端生成的 diff；如需前端展示新旧内容对比，需要由前端或后续专门接口生成。