socaichat/gpthd.md

# SOC 项目后端功能方案（基于 LangChain，按功能拆解）

> 约束：在未获得明确允许前，不修改前端交互，只补后端能力、编排链路和数据层。
> 目标：严格围绕当前 `~/go/soc` 这个 Gemini 风格前端，按“每个功能用什么技术完成什么功能”来写，核心框架改为 **LangChain / LangGraph**，不再以 FastAPI 作为方案重点。

---

## 1. 对话流式回复

### 要完成什么功能
- 用户在当前聊天输入框发送消息
- 后端实时返回回答内容
- 支持“思考中 / 检索中 / 生成中”的状态
- 不改变现有前端交互，只替换当前前端 `simulateAIResponse()`

### 用什么技术
- **LangChain**：负责组织提示词、消息上下文、模型调用
- **LangGraph**：负责整个对话节点编排与状态流转
- **Azure OpenAI**：生成最终回答
- **SSE**：把 LangChain/LangGraph 执行过程和回答流式推给前端
- **PostgreSQL**：保存会话和消息记录

### 怎么落地
- 以 `LangGraph StateGraph` 建立一个对话图：
  - `receive_message`
  - `load_history`
  - `route_tools`
  - `call_llm`
  - `persist_message`
- 前端发送消息后，后端触发 graph 执行
- Azure OpenAI 通过 LangChain chat model 调用
- 生成的 token 和中间状态通过 SSE 返回给前端

### 输出结果
- 前端仍然保持当前 Gemini 风格聊天交互
- 从 mock 回复升级为真实流式 AI 回复
- 后续所有工具调用都能接到同一个 graph 里

---

## 2. 会话管理

### 要完成什么功能
- 左侧历史会话列表从真实数据读取
- 支持新建、切换、删除会话
- 支持自动生成标题
- 会话上下文可在 LangChain 中继续使用

### 用什么技术
- **PostgreSQL**：保存 conversation 和 message
- **LangChain Memory / Message History 抽象**：管理历史消息上下文
- **SQLAlchemy / SQLModel**：管理数据表

### 怎么落地
- conversations/messages 数据存入 PostgreSQL
- 在 LangChain 层使用 `BaseChatMessageHistory` 风格封装数据库消息
- 每次进入 graph 时先加载历史消息
- 标题生成可以由 LLM 在首轮消息后自动归纳

### 输出结果
- 当前左侧 mock 会话可以替换为真实会话记录
- 后端真正具备多轮上下文记忆能力

---

## 3. 内部知识库检索

### 要完成什么功能
- 当用户问产品、方案、配置、内部文档时
- 自动检索内部知识库
- 再让模型基于检索结果生成回答
- 回答中附带引用来源

### 用什么技术
- **LangChain Tool**：把 KB_AGENT 封装成知识库工具
- **KB_AGENT 接口**：作为实际搜索源
- **Azure OpenAI**：总结检索结果并生成回答
- **LangGraph**：决定何时调用知识库节点

### 怎么落地
- 编写 `kb_search_tool`
- 工具内部调用 `KB_AGENT_URL + KB_AGENT_SEARCH_PATH`
- 返回统一的文档列表结构
- graph 中当识别为内部知识类问题时，先进入 `kb_search` 节点，再进入 `llm_answer`

### 输出结果
- 产品知识问答不再靠模型空想
- 回答可基于真实内部资料
- 更适合售前、售后、研发支持

---

## 4. 外部 AI 搜索

### 要完成什么功能
- 处理实时互联网问题、行业动态、外部资料调研
- 支持搜索、网页读取、重排
- 支持 fast / deep / auto 三种搜索质量
- 后续支持图片和视频检索结果

### 用什么技术
- **LangChain Tool**：封装外部搜索工具链
- **Jina Search API**：外部搜索
- **Jina Reader**：网页正文读取
- **Rerank 模型**：重排结果
- **LangGraph**：编排 Search -> Read -> Rerank -> Answer
- **Azure OpenAI**：生成最终总结回答

### 怎么落地
- 分成三个 tool：
  - `web_search_tool`
  - `web_read_tool`
  - `rerank_tool`
- 在 graph 中建立外部搜索链路：
  - 搜索候选
  - 读取正文
  - 重排结果
  - 将高质量上下文交给 LLM
- `fast/deep/auto` 可作为 graph state 中的参数

### 输出结果
- 外部信息回答准确度显著提升
- 满足文档要求里的企业级外部搜索能力
- 为后续图片、视频结果展示预留结构

---

## 5. 工单系统只读接入

### 要完成什么功能
- 查询工单列表
- 查询工单详情
- 汇总 P0/P1 工单
- 支持聊天中分析工单趋势、共性问题、故障重点
- 替换当前前端 mock 工单摘要

### 用什么技术
- **LangChain Tool**：把 gongdan API 封装为工单工具
- **Gongdan HTTP API**：工单实际数据源
- **Azure OpenAI**：对工单结果做总结和归纳
- **PostgreSQL（可选缓存）**：保存查询结果和摘要缓存

### 怎么落地
- 编写工具：
  - `ticket_list_tool`
  - `ticket_detail_tool`
  - `ticket_summary_tool`
- 当用户问题涉及工单时，graph 路由到 ticket 节点
- 工具取回结果后，再由 LLM 进行总结
- 当前前端的 TicketSummary 数据以后改成读取真实接口结果，但不改交互样式

### 输出结果
- 工单分析能力可直接在聊天里使用
- 首页/聊天区的工单摘要可从 mock 变成真实数据

---

## 6. 文档生成

### 要完成什么功能
- 用户要求生成方案、汇报、纪要、总结文档时
- 后端自动进入文档生成流程
- 返回任务状态和结果
- 生成正式文档链接或结果卡片

### 用什么技术
- **LangChain Tool / Runnable**：封装文档生成能力
- **Doc Creator Agent HTTP API**：实际生成正式文档
- **LangGraph**：把“文档生成”作为 graph 的分支节点
- **PostgreSQL**：保存文档任务记录
- **Azure OpenAI**：先整理文档结构或提纲

### 怎么落地
- graph 中识别“生成文档”类意图
- 先用 LLM 生成结构化文档提纲
- 再调用 doc creator agent
- 把任务状态写入数据库
- 前端依旧保持聊天式入口，只在消息中显示结果卡片

### 输出结果
- 销售、售前、汇报场景可以直接从聊天进入正式文档输出
- 文档生成成为对话系统中的标准能力节点

---

## 7. 沙盒代码执行

### 要完成什么功能
- 分析 CSV、JSON、日志、结构化数据
- 在安全环境中执行代码
- 返回分析结果、图表和文件
- 不改变前端交互，只把结果塞回当前聊天流里

### 用什么技术
- **LangChain Tool**：把沙盒能力封装为可调用工具
- **Daytona Sandbox**：安全执行环境
- **Python 数据工具链**：pandas、matplotlib、json、csv
- **LangGraph**：按意图路由到 sandbox 节点
- **PostgreSQL**：保存执行记录

### 怎么落地
- 第一阶段不开放任意代码执行
- 只先封装几个固定工具：
  - `csv_summary_tool`
  - `json_transform_tool`
  - `data_analysis_tool`
  - `chart_generate_tool`
- graph 根据问题和附件类型决定是否调用 sandbox

### 输出结果
- 后端不仅能“回答”，还能“执行”和“计算”
- 数据类问题能返回真正算出来的结果

---

## 8. 附件上传与解析

### 要完成什么功能
- 接收用户上传的附件
- 保存附件元数据
- 提取文本内容进入上下文
- 为知识问答、文档生成、沙盒分析提供输入

### 用什么技术
- **对象存储/本地存储**：保存附件
- **LangChain Document Loader**：解析 PDF、DOCX、TXT、CSV 等文件
- **PostgreSQL**：保存附件元数据
- **LangGraph**：把附件解析结果接入 graph state

### 怎么落地
- 上传后先保存附件和元数据
- 再用 LangChain loader 抽取文本
- 将解析结果挂到当前会话 state 中
- 当用户继续提问时，graph 可以把附件内容作为上下文输入 LLM 或工具

### 输出结果
- 未来可以真正支持“基于附件提问”和“基于附件分析”
- 为文档生成和沙盒执行提供输入材料

---

## 9. 工具编排层

### 要完成什么功能
- 判断用户当前问题到底需要哪种能力
- 决定先查 KB、先查工单、还是先查外部搜索
- 决定是否触发文档生成或沙盒分析
- 把多个工具结果统一整理给模型

### 用什么技术
- **LangGraph**：整个系统的核心编排框架
- **LangChain Tools**：封装 KB、Search、Tickets、Docs、Sandbox
- **Azure OpenAI**：辅助做意图判断、结果总结

### 怎么落地
- graph 中至少有这些节点：
  - `router`
  - `kb_search`
  - `web_search`
  - `ticket_query`
  - `doc_generate`
  - `sandbox_run`
  - `llm_answer`
  - `persist`
- 第一阶段可以先“规则路由 + LLM总结”
- 第二阶段再升级为“LLM路由 + 工具调用决策”

### 输出结果
- 后端不再是散乱接口集合，而是统一 Agent 编排系统
- 前端只保留一个 Gemini 风格聊天入口即可

---

## 10. 数据持久化与基础设施

### 要完成什么功能
- 保存历史会话
- 保存消息记录
- 保存工具调用记录
- 保存附件记录
- 保存文档任务记录
- 保存 graph 执行状态和日志
- 提升缓存能力、异步任务能力和文件持久化能力

### 用什么技术
- **PostgreSQL**：主数据库，保存会话、消息、任务、工具记录
- **LangGraph Checkpointer / State Persistence**：保存 graph 执行状态
- **Redis**：缓存热点结果、会话临时状态、短期上下文、速率控制
- **Azure Storage Account**：保存附件、图表、导出文件、文档产物
- **Azure Service Bus**：承载异步任务与解耦长链路处理

### 怎么落地
- PostgreSQL 中至少建立以下表：
  - `conversations`
  - `messages`
  - `tool_runs`
  - `attachments`
  - `document_tasks`
  - `graph_runs`
- Redis 用于：
  - 外部搜索结果缓存
  - KB 搜索缓存
  - 工单摘要缓存
  - 正在运行的 graph/session 临时状态
  - SSE 会话短状态同步
- Azure Storage Account 用于：
  - 用户上传附件原始文件
  - Sandbox 输出文件
  - 图表与中间产物
  - 文档生成结果文件
- Azure Service Bus 用于：
  - 文档生成异步任务派发
  - Sandbox 长任务调度
  - 外部搜索深度模式异步并发编排
  - 后续告警/通知类事件扩展

### 输出结果
- 对话、工具、任务都有追踪记录
- graph 执行链路具备可恢复能力
- 系统具备缓存、异步任务和文件持久化基础设施

---

## 11. Redis 缓存层

### 要完成什么功能
- 降低外部接口重复调用成本
- 提升对话链路响应速度
- 处理短期状态、热点数据和限流控制

### 用什么技术
- **Azure Redis**：缓存层
- **LangChain / LangGraph 外围状态管理**：结合缓存保存中间态

### 怎么落地
- 缓存这些内容：
  - 相同 query 的 KB 搜索结果
  - 相同 query 的外部搜索与重排结果
  - 工单摘要结果
  - 文档生成任务短状态
  - 会话级短期上下文摘要
- 为外部搜索和知识库增加 TTL
- 为 Service Bus 异步任务增加状态缓存

### 输出结果
- 系统速度更稳定
- 外部服务成本更低
- 可支撑更高并发下的会话请求

---

## 12. 存储账户（文件与产物存储）

### 要完成什么功能
- 持久化用户上传附件
- 保存文档生成结果
- 保存 Sandbox 执行生成的图表/文件
- 为前端提供附件与结果文件访问地址

### 用什么技术
- **Azure Blob Storage**：统一文件对象存储
- **LangChain Document Loader**：结合存储文件做解析

### 怎么落地
- 上传文件后先保存到 Blob Storage
- 数据库中记录 blob URL、文件类型、所属消息/会话
- 文档生成与 Sandbox 产物统一落到 Blob Storage
- 前端保持现有交互，仅在消息中附带文件结果卡片或链接

### 输出结果
- 所有附件和中间产物有统一落盘位置
- 后续分析、下载、追踪都更方便

---

## 13. Service Bus 异步任务层

### 要完成什么功能
- 处理长耗时任务
- 解耦即时对话链路和后台异步处理链路
- 支持重试、失败恢复、延后处理

### 用什么技术
- **Azure Service Bus**：消息队列 / 异步任务总线
- **LangGraph**：消费任务后继续执行长链路节点

### 怎么落地
- 把这些任务异步化：
  - 文档生成
  - Sandbox 长任务
  - 深度外部搜索
  - 未来的大批量分析任务
- 聊天主链路先返回“任务已受理”状态
- Worker 从 Service Bus 拉取任务继续执行
- 执行结果写数据库和存储账户，再回推前端

### 输出结果
- 避免主对话链路阻塞
- 长任务处理更稳定
- 适合企业级系统扩展

---

## 14. MCP 方式接入外部搜索

### 要完成什么功能
- 利用 `https://mcp.jina.ai/sse` 这一类能力，以 MCP 方式接入外部搜索
- 让外部搜索不只是普通 HTTP API，而是可作为标准工具节点接入 LangChain / LangGraph

### 用什么技术
- **MCP（Model Context Protocol）**：统一工具协议
- **Jina MCP SSE / v1**：外部搜索与读取能力来源
- **LangChain Tool 封装层**：把 MCP 调用转换成 graph 可调用工具

### 怎么落地
- 优先测试 Jina 提供的 `/sse` 和 `/v1` 两种入口
- 将 Search 和 Read 分别封装成两个 tool
- 在外部搜索节点中统一走 MCP 接入层，保留将来替换搜索供应商的可能
- 重排仍保留单独节点，以便保障搜索质量控制

### 输出结果
- 外部搜索链路更标准化
- 更容易扩展到更多 MCP 服务
- 对 LangChain / LangGraph 编排更友好

---

## 15. 基于当前前端代码补充的后端缺口与完善方案

> 这一章专门对应当前前端已经存在、但此前后端方案没有完整覆盖的功能点。不含认证和权限，只补业务后端能力。

### 15.1 消息反馈（赞 / 踩）

#### 要完成什么
- 用户对 assistant 消息进行点赞或点踩
- 后端记录反馈结果
- 后续可用于回答质量分析、提示词优化和问题回溯

#### 用什么技术
- **PostgreSQL**：保存反馈记录
- **LangGraph 旁路记录**：反馈不进入主对话 graph
- **Redis（可选）**：做短期统计缓存

#### 怎么落地
- 新增表：`message_feedback`
  - `id`
  - `message_id`
  - `conversation_id`
  - `feedback_type` (`up` / `down`)
  - `reason`（可空，后续扩展）
  - `created_at`
- 新增接口：
  - `POST /api/messages/{id}/feedback`
- 前端点击赞/踩后直接调用该接口
- 第一阶段先只记录 `up/down`，不做复杂原因分类

---

### 15.2 模型切换映射

#### 要完成什么
- 前端已有 Flash / Pro 与顶部模型选择入口
- 第一阶段后端先统一固定使用 **GPT-5.4**
- 但保留字段和映射结构，后续再扩展多模型、多链路

#### 用什么技术
- **LangChain model wrapper**：模型封装
- **LangGraph state**：保存 `model_profile`
- **PostgreSQL conversation metadata**：记录选择结果

#### 怎么落地
- 前端若传模型字段，第一阶段统一映射为：
  - `model_provider = azure_openai`
  - `model_name = gpt-5.4`
- 保留 metadata 字段：
  - `selected_model`
  - `selected_mode`
- 当前只做字段记录与透传，不做真正多模型切换
- 第二阶段再扩为 flash/pro 对应不同 graph 策略

---

### 15.3 工具显式开关控制

#### 要完成什么
- 前端工具 chips：
  - 搜索
  - 内部知识库
  - 沙盒
  - 文档生成
- 用户手动启用哪些工具，后端就只允许调用这些工具
- 用户未选择时，后端才走自动路由

#### 用什么技术
- **LangGraph state**：保存当前消息工具选择
- **LangChain tools registry**：统一工具注册
- **tool allowlist / denylist**：工具调用控制

#### 怎么落地
- 前端发消息时附带：
```json
{
  "enabled_tools": ["search", "knowledge"]
}
```
- graph state 增加：
  - `enabled_tools`
  - `tool_selection_mode` (`auto` / `manual`)
- router 节点规则：
  - `manual` 模式：只能从 allowlist 中路由
  - `auto` 模式：按规则或模型自由决策
- 工具执行前统一做可用性校验

---

### 15.4 多文件上传与消息绑定

#### 要完成什么
- 一次上传多个文件
- 每个文件单独保存
- 文件和某条消息绑定
- 文件可参与知识问答、搜索、Sandbox 分析和文档生成

#### 用什么技术
- **Azure Blob Storage**：存储文件
- **PostgreSQL**：存储附件元数据
- **LangChain Document Loaders**：解析附件内容
- **消息-附件关联机制**：支撑多文件场景

#### 怎么落地
- 新增表：`attachments`
  - `id`
  - `conversation_id`
  - `message_id`（允许先空，待消息发送后再绑定）
  - `file_name`
  - `content_type`
  - `storage_url`
  - `parse_status`
  - `parsed_text`
  - `created_at`
- 新增接口：
  - `POST /api/attachments`
  - `POST /api/messages/{id}/attachments/bind`
- 推荐流程：
  1. 前端先上传多个文件
  2. 后端返回 attachment ids
  3. 前端发消息时附带 attachment ids
  4. 后端完成消息与附件绑定
- 解析流程异步化，避免阻塞主聊天链路

---

### 15.5 扩展程序连接管理

#### 要完成什么
- 支持扩展程序的连接、断开、修改 key、查看状态
- 页面刷新后仍保留扩展连接状态
- 扩展状态可被后端 graph 感知

#### 用什么技术
- **PostgreSQL**：保存扩展配置与状态
- **加密存储机制**：保存敏感配置
- **extension registry**：统一扩展管理
- **LangChain tool 注册机制**：根据扩展状态暴露工具

#### 怎么落地
- 新增表：`extensions`
  - `id`
  - `extension_type` (`ticket` / `sales` / `cloud`)
  - `display_name`
  - `status`
  - `config_encrypted`
  - `last_check_at`
  - `last_check_status`
- 新增接口：
  - `GET /api/extensions`
  - `POST /api/extensions/{type}/connect`
  - `POST /api/extensions/{type}/disconnect`
  - `POST /api/extensions/{type}/validate`
- 第一阶段先完成工单系统全链路，销售和云管先保留扩展框架

---

### 15.6 销售系统 / 云管系统预留

#### 要完成什么
- 虽然当前两套系统还在开发，但后端要预留统一扩展接入结构
- 避免未来工单、销售、云管三套系统接入方式不一致

#### 用什么技术
- **统一 extension schema**
- **summary provider 接口**
- **tool provider 接口**
- **connection config schema**

#### 怎么落地
- 一期不要求真实接入销售/云管 API
- 但必须预留：
  - 扩展类型定义
  - tool 注册入口
  - summary 注册入口
  - 状态位和配置结构
- 后续新增业务系统时不需要推翻现有后端结构

---

### 15.7 通用扩展摘要机制

#### 要完成什么
- 不只是工单系统，未来销售、云管系统接入后，也能输出首页/对话页摘要卡片
- 后端统一提供摘要机制

#### 用什么技术
- **summary provider registry**：每个扩展实现自己的摘要提供者
- **Redis**：缓存摘要结果
- **PostgreSQL**：记录摘要生成时间与状态
- **LangChain summarizer（可选）**：对原始数据做摘要

#### 怎么落地
- 新增统一摘要接口：
  - `GET /api/extensions/summaries`
- 返回结构示例：
```json
[
  {
    "extension_type": "ticket",
    "status": "connected",
    "summary_type": "ticket_summary",
    "data": {}
  }
]
```
- 第一阶段先实现 ticket summary provider
- 但接口设计按多扩展统一返回

---

### 15.8 结构化消息块协议

#### 要完成什么
- 后端不能只返回纯文本
- 需要支持：
  - 文本
  - 引用来源
  - 摘要卡片
  - 文件结果
  - 工具状态
  - 错误块

#### 用什么技术
- **LangGraph 标准化事件输出**
- **message block schema**
- **前后端统一 JSON 协议**

#### 怎么落地
- 定义统一 block 结构：
```json
{
  "type": "text | citation | summary_card | artifact | tool_status | error",
  "payload": {}
}
```
- assistant message 最终存储结构：
```json
{
  "id": "...",
  "blocks": []
}
```
- SSE 中间态也复用 block/event 体系
- 第一阶段前端至少支持：
  - `text`
  - `tool_status`
  - `citation`
  - `summary_card`

---

### 15.9 长任务状态回传

#### 要完成什么
- 文档生成、Sandbox 数据分析、深度搜索等任务可能耗时较长
- 前端需要看到任务状态，而不是一直假 loading

#### 用什么技术
- **Azure Service Bus**：异步任务投递
- **PostgreSQL**：任务状态持久化
- **Redis**：缓存短状态
- **SSE / 轮询**：状态回传给前端

#### 怎么落地
- 新增表：`async_tasks`
  - `id`
  - `task_type`
  - `conversation_id`
  - `message_id`
  - `status`
  - `progress_text`
  - `result_payload`
  - `created_at`
  - `updated_at`
- 新增接口：
  - `GET /api/tasks/{id}`
- 第一阶段先采用“数据库状态 + 前端轮询”
- 后续再增强为 SSE 任务事件推送

---

### 15.10 扩展连接状态注入 graph

#### 要完成什么
- 某个扩展是否已连接，必须直接决定 graph 中哪些工具可用
- 未连接扩展不能被调用
- 已连接扩展才能参与 agent 路由

#### 用什么技术
- **extension registry**
- **LangGraph state injection**
- **tool availability resolver**

#### 怎么落地
- graph 执行前先加载当前扩展连接状态
- 注入 state：
```json
{
  "available_extensions": ["ticket"]
}
```
- router 节点判断：
  - 工单问题 + ticket 已连接 -> 允许调用
  - 工单问题 + ticket 未连接 -> 返回“扩展未连接”
- 销售 / 云管未来直接复用该机制

---

### 15.11 会话重命名 / 置顶等预留

#### 要完成什么
- 为左侧会话更多操作菜单预留后端能力
- 支持未来扩展：
  - 重命名
  - 置顶
  - 自定义排序

#### 用什么技术
- **PostgreSQL conversation metadata**
- **排序字段 / pinned 字段**

#### 怎么落地
- conversations 表补充字段：
  - `custom_title`
  - `pinned`
  - `sort_order`
- 接口统一走：
  - `PATCH /api/conversations/{id}`
- 即使前端暂未开放置顶，也建议先预留字段

---

### 15.12 会话级偏好元数据

#### 要完成什么
- 记录会话偏好信息，例如：
  - 当前选中的模型
  - 当前启用工具
  - 默认搜索模式
  - 当前关联扩展
- 会话恢复时自动延续这些设置

#### 用什么技术
- **PostgreSQL JSON metadata**
- **LangGraph state hydration**

#### 怎么落地
- conversations 表增加：
  - `metadata_json`
- 典型结构示例：
```json
{
  "selected_model": "gpt-5.4",
  "selected_mode": "pro",
  "enabled_tools": ["knowledge", "search"],
  "preferred_search_mode": "deep"
}
```
- 会话恢复时把 metadata 注入 graph 初始 state

---

## 16. 接口层总表

> 虽然本方案不以 FastAPI 为重点，但前端要接入，仍然需要有 HTTP/SSE 出口。这里把它视为“接入层”，不是方案核心。

### 第一阶段建议建设的接口

#### 基础接口
- `GET /health`

#### 会话接口
- `GET /api/conversations`
- `POST /api/conversations`
- `GET /api/conversations/{id}`
- `PATCH /api/conversations/{id}`
- `DELETE /api/conversations/{id}`

#### 聊天接口
- `POST /api/chat/stream`

#### 工单接口
- `GET /api/tickets/summary`
- `GET /api/tickets`
- `GET /api/tickets/{id}`

#### 搜索接口
- `POST /api/search/internal`
- `POST /api/search/external`

#### 文档接口
- `POST /api/documents/generate`
- `GET /api/documents/{task_id}`

#### 附件接口
- `POST /api/attachments`
- `GET /api/attachments/{id}`

#### 沙盒接口
- `POST /api/sandbox/run`

---

## 16. 推荐技术组合总结

### 核心框架
- **LangChain**：模型调用、Prompt 组织、Tool 封装、Memory 适配
- **LangGraph**：对话状态机、工具路由、任务编排、长链路执行

### 数据层
- **PostgreSQL**：会话/消息/工具调用/任务持久化
- **Redis**：缓存、短状态、限流
- **Azure Blob Storage**：附件、产物、文档存储
- **Azure Service Bus**：异步任务编排
- **SQLAlchemy / SQLModel**：ORM
- **Alembic**：迁移管理

### AI 与搜索
- **Azure OpenAI**：LLM 生成与总结
- **KB_AGENT**：内部知识库检索
- **Jina MCP SSE / v1 + Search / Reader / Rerank**：外部搜索链路

### 外部业务系统
- **Gongdan API**：工单只读
- **Doc Creator Agent**：文档生成
- **Daytona Sandbox**：受控代码执行

### 协议与接入
- **SSE**：流式输出到前端
- **HTTP API**：前端接入层

---

## 17. 第一阶段开发顺序

### 第一步
先完成：
- LangChain + LangGraph 基础工程
- PostgreSQL 接入
- conversations/messages 表
- 基础聊天 graph
- `/api/chat/stream`
- `/api/conversations`

### 第二步
接入：
- Azure OpenAI
- KB_AGENT tool
- 工单 tools

### 第三步
接入：
- Jina MCP SSE / v1 搜索链路
- Search / Reader / Rerank tool chain
- 来源引用
- graph 中间状态流式事件
- Redis 缓存

### 第四步
接入：
- 文档生成 tool
- 附件解析 loader
- sandbox tools
- Azure Blob Storage
- Azure Service Bus
- graph 持久化和恢复

---

## 18. 最终结论

这个项目当前最合适的后端方案，如果明确要求基于 LangChain 框架来做，那就应该是：

- 用 **LangChain + LangGraph** 做整个后端核心
- 用 **Azure OpenAI** 做模型生成和总结
- 用 **KB_AGENT** 做内部知识检索工具
- 用 **Jina Search/Reader/Rerank** 做外部搜索工具链
- 用 **Gongdan API** 做工单查询工具
- 用 **Doc Creator Agent** 做正式文档生成工具
- 用 **Daytona Sandbox** 做受控执行工具
- 用 **PostgreSQL** 做会话、消息、任务和 graph 状态持久化
- 用 **Redis** 做缓存和短状态管理
- 用 **Azure Blob Storage** 做附件与产物存储
- 用 **Azure Service Bus** 做长任务异步编排
- 用 **MCP 方式** 标准化接入 Jina 外部搜索

整个系统本质上是：
**一个基于 LangGraph 编排、具备缓存/存储/异步任务能力的企业级对话 Agent 后端。**

而且整个过程中：
**前端交互不改，只替换数据来源和后端能力。**