知识库智能体

本项目面向企业知识管理与智能问答场景，旨在解决传统知识库检索精度低、无法处理复杂多步问题等痛点，引入 AI Agent 编排能力实现从问题理解到答案生成的全链路自动化。系统核心包含四大功能模块：RAG 检索增强生成模块实现知识的语义召回；LangGraph4j 状态图引擎负责任务规划、并行执行、结果评估与答案汇总的流水线编排；CheckPoint 断点恢复与人机协同审批模块保障关键操作的可控性；SSE 实时推送模块提供图执行轨迹的可视化观测。业务流程以"用户提问→知识检索→任务规划→人工审批→并行执行→结果评估→答案汇总"为主线，功能路径遵循"前端交互→Controller 接入→Service 编排→图引擎调度→LLM 调用→流式响应"的技术链路，形成端到端闭环。

1. 整体架构与设计思路

系统采用前后端分离架构。后端基于 Spring Boot 3 + Spring MVC 构建，核心引入 LangGraph4j 状态图引擎实现 AI Agent 的多步编排（检索→规划→执行→评估→汇总），通过 PostgreSQL 持久化 Checkpoint 支持断点恢复与人机协同审批；AI 层基于 Spring AI 对接 DashScope 大模型，使用 ToolCallingAdvisor 链实现工具调用与流式推送；并行执行模块采用 Java 21 虚拟线程 + Kahn 拓扑排序实现依赖感知的波次调度。前端基于 React + Vite + TypeScript + Tailwind CSS，通过 SSE 实时消费图执行事件，渲染状态图轨迹与审批交互界面。

2. 负责模块与成果

独立负责状态图引擎全链路开发，包括：LangGraph4j 图定义与编译（5 个节点、条件边路由）、CheckpointSaver Bean 化封装与 PostgreSQL 持久化、Human-in-the-Loop 中断/恢复机制（interruptBefore + resume 端点）、Executor 节点的并行分支执行（虚拟线程 + CountDownLatch 超时控制）、前端 SSE 事件处理与状态图可视化。实现复杂多步问题从单轮回答到多步编排的升级，支持最多 5 个并行子任务同时执行，单轮端到端响应时间降低约 40%。

3. 难点与解决方案

interrupt 事件被 done 覆盖：后端图暂停后 finally 块仍发送 done 事件，导致前端审批 UI 一闪而过。通过将 runGraph 改为返回 boolean 标识中断状态，finally 中按标志决定是否发送 done，前端 done 处理器增加 interrupted 状态保护，双端修复。

虚拟线程工厂与 CompletableFuture 类型不兼容：`ThreadFactory` 无法直接传给 `runAsync` 的 `Executor` 参数，改用 `Executors.newThreadPerTaskExecutor(factory)` 包装，后进一步简化为 `Thread.ofVirtual().start()` + `CountDownLatch` 方案。

Checkpoint 状态序列化失败：AgentState 中的自定义 record 类型未实现 Serializable，导致 PostgresSaver 序列化异常，通过为所有状态值 record 添加 `implements Serializable` 解决。