Skip to content

3.0.0

Choose a tag to compare

View all tags
@ly1836 ly1836 released this 01 Aug 07:31
· 11 commits to main since this release
3.0.0
d0615a2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

3.0.0 更新说明

3.0.0 为主要功能版本，新增业务 Tool 查询结果图表可视化能力，并增强知识文档导入、知识问答、流式响应和历史会话回放。

✨ 核心功能

Tool 结果图表可视化

业务 Tool 查询到结构化数据后，可在返回文字答案的同时生成图表：

  • LLM 只负责选择图表类型和标题。
  • 后端根据真实 Tool 数据自动完成来源选择、字段绑定、数据转换和安全校验。
  • 前端通过本地 ECharts 直接渲染图表。
  • 每次问答最多返回一个图表，同一会话中的后续问答仍可继续生成图表。
  • 图表生成失败时自动降级为纯文本，不影响业务回答。
  • 图表随助手消息保存，支持历史记录和续聊回放。
  • 不重新查询业务数据库，不允许 LLM 直接提交业务数值或任意 ECharts 配置。

支持以下 23 种图表：

  • 环形图
  • 旭日图
  • 条形图
  • 瀑布图
  • 子弹图
  • 面积图
  • 阶梯图
  • 雷达图
  • 散点图
  • 气泡图
  • 直方图
  • 箱线图
  • 热力图
  • 桑基图
  • 矩形树图
  • 甘特图
  • 漏斗图
  • 词云图
  • 仪表盘图
  • 水位图
  • 平行坐标图
  • 折线图
  • 饼图

知识库能力增强

  • knowledge 模式使用独立的知识问答提示词，不再受 ERP 业务范围提示限制。
  • 支持回答用户导入的 Java、JVM、RabbitMQ 等非 ERP 技术文档。
  • 增加知识库召回数量并调整相似度阈值，改善中文技术文档召回效果。
  • knowledge 模式不装配业务 Tool，继续保持租户隔离。
  • 同租户、同来源文档重新导入时自动覆盖旧向量。

大文档受控导入

上传限制调整为：

  • 单文件最大 500MB
  • 单次请求最大 550MB

同时增加多层资源保护：

  • 限制文档提取后的最大字符数。
  • 限制单文档最终分片数量。
  • 使用实际 ONNX WordPiece 分词器进行二次切分。
  • 保证每个向量分片不超过 128 Token。
  • 向量数据按 100 条分批写入。
  • 写入失败时清理当前来源的残留数据，避免留下半成品向量。

🚀 流式响应优化

  • 流式接口统一使用类型化 SSE。
  • 支持 delta、chart、done、error 四类事件。
  • 恢复正文实时逐段输出效果。
  • 图表在正文完成后发送并渲染。
  • 异常和用户取消只执行一次消息、计费及 Tool 流水收口。
  • 修复查询、重试和图表规划等内部英文旁白泄漏问题。
  • 修复最终答案边界跨网络分片时可能泄漏协议残片的问题。
  • SSE 错误复用当前助手消息，避免生成空白或重复气泡。

Important

GET /api/ask/stream 已从历史纯文本 SSE 升级为类型化 SSE，属于协议变更。项目内置前端已同步升级；独立接入该接口的客户端需要适配新的事件结构。

🧩 会话历史与数据安全

  • 助手消息增加可空 chart_spec 字段。
  • 历史详情和续聊可直接回放已保存图表。
  • 历史回放不会重新调用 LLM 或业务 Tool。
  • 旧消息没有图表字段时继续正常展示文本。
  • 非法或不兼容的历史图表自动降级为 chart = null。
  • 会话读取、归档和状态查询增加租户及当前用户所有权校验。
  • 原始业务 Tool 数据只在当前请求生命周期内使用，请求结束后自动清理。
  • Tool 结果按 trace、租户和会话隔离，禁止跨请求或跨租户复用。

🏗️ 架构调整

为降低核心问答服务复杂度，本版本拆分了 ErpAssistantService 的部分职责：

  • AssistantClientProvider

    • 负责模型 Provider、模式路由、RAG 和 Tool 装配。

  • AssistantLifecycleService

    • 负责消息持久化、计费、Tool 流水和终止收口。

  • BusinessDataTurnGuard

    • 保证业务数据问题使用当前轮查询结果。

  • AssistantAnswerSanitizer

    • 负责最终答案边界处理和内部旁白净化。

图表能力按职责拆分至：

  • chat/chart/model
  • chat/chart/capture
  • chat/chart/compile
  • chat/chart/protocol
  • chat/chart/selection
  • chat/chart/tool

同时增加 Spring Bean 构造器依赖图测试，防止后续重构引入循环依赖。

🎨 前端更新

  • 本地引入 Apache ECharts。
  • 本地引入词云图和水位图扩展。
  • 新增统一的 chart-adapter.js 图表适配器。
  • 不依赖 CDN，不增加前端构建工具。
  • 支持实时问答、非流式回答、历史记录和续聊图表展示。
  • 支持图表实例释放和消息重新渲染。
  • 甘特图使用项目内固定水平时间范围实现。
  • 图表渲染异常时保留 Markdown 文本答案。
  • 中英文 README 增加图表能力介绍、测试话术和实际效果截图。

🔐 图表安全与可靠性

  • LLM 不能提交来源 Tool、字段绑定、转换规则、业务数据或任意 ECharts option。
  • 图表类型由统一枚举约束。
  • Tool 结果、规划输入和最终图表协议均设置大小、深度、宽度、节点数、行数和维度限制。
  • 自动排除订单号、工单号等数值型业务标识，避免被误选为业务指标。
  • 支持纯分类业务数据按真实记录数生成统计图表。
  • 多个业务 Tool 返回结果时只选择一个可信来源，不自动合并不同 Tool 数据。
  • 内部图表规划 Tool 不计入业务 Tool 命中次数、调用流水或动态 Tool 管理列表。
  • 图表失败、空结果和不可图表化数据均安全降级为文本回答。

🗄️ 数据库变更

ERP MySQL 的 a_chat_message 表增加可空字段：

  • chart_spec JSON NULL

数据库初始化逻辑支持：

  • 新数据库自动创建字段。
  • 已有数据库幂等增加字段。
  • 重复启动不会重复修改表结构。
  • 历史消息无需迁移，原有文本数据继续兼容。

⚠️ 升级注意事项

从 2.1.1 升级到 3.0.0 时请注意：

  1. 使用项目数据库初始化逻辑或手工确认 a_chat_message.chart_spec 字段已创建。
  2. 独立调用 /api/ask/stream 的客户端需要适配类型化 SSE。
  3. 项目内前后端必须作为同一版本一起部署。
  4. 如需让已导入文档使用新的真实 Token 切分和覆盖导入逻辑，可重新导入对应文档。
  5. 本版本不迁移历史向量数据，也不要求迁移历史纯文本消息。
  6. ECharts 及扩展已经内置在静态资源中，部署环境不需要访问外部 CDN。

✅ 验证结果

  • Java 测试：194 项通过
  • 测试失败：0
  • 测试错误：0
  • 前端图表 fixture：33 项通过
  • Spring Bean 依赖图检查：通过，未发现循环依赖
  • OpenSpec 主规范严格校验：8 项通过，0 项失败
  • 图表类型、流式事件、历史回放和异常降级均有自动化测试覆盖
  • 中英文 README 图表话术和本地图片引用检查通过

📚 文档

  • 更新中文 README
  • 更新英文 README
  • 新增 20 条可直接复制的图表测试话术
  • 新增环形图、条形图、瀑布图、子弹图、面积图、阶梯图和甘特图等效果截图
  • 完成 tool-result-chart-visualization OpenSpec change 归档
  • OpenSpec 任务完成度：169/169

📦 变更规模

  • 修改文件：102 个
  • 新增代码及文档：约 16,430 行
  • 删除或调整：约 765 行

Full Changelog

2.1.1...3.0.0

Assets 2
Loading