zsjz-ai/.qoder/repowiki/zh/content/技术栈与依赖.md

技术栈与依赖

本文引用的文件

• pom.xml
• ai-server/pom.xml
• ai-gateway/pom.xml
• ai-electron/package.json
• ai-electron/frontend/package.json

目录

1. 简介
2. 项目结构
3. 核心依赖矩阵
4. 后端架构与依赖
5. 前端架构与依赖
6. 桌面层架构与依赖
7. 依赖管理方式
8. 兼容性注意事项
9. 升级依赖的风险点
10. 结论

简介

本仓库是清鉴 AI 调查工具的多模块工程，包含后端服务、网关、前端应用和 Electron 桌面封装。后端基于 Spring Boot 3.5.16，使用 WebFlux 网关、MyBatis-Plus、Dynamic Datasource、Sa-Token、Redis、PostgreSQL/pgvector、DJL HuggingFace Tokenizers + ONNX Runtime、DuckDB JDBC、Spring AI Tika 与 AgentScope；前端基于 Vue 3 生态，使用 Ant Design Vue、Pinia、Vue Router、Vue I18n、Monaco Editor、CodeMirror、VDitor、Markdown-it、ECharts、AntV G6/X6、Relation Graph、MapLibre GL、PMTiles、Dexie、xlsx、crypto-js、dayjs、lodash-es；桌面层基于 Electron 37、electron-builder、ee-core 与 electron-updater。

项目结构

工程根目录是一个 Maven 多模块聚合工程，同时包含前端和桌面子工程：

• pom.xml：Maven 父工程，声明 Spring Boot 父版本、模块列表。
• ai-server：业务后端，承载数据库访问、认证授权、Agent、向量检索、文档解析等能力。
• ai-gateway：Spring Cloud Gateway WebFlux 网关，负责按用户粘性路由转发、SSE/流式响应与共享 Redis 中的 Sa-Token 校验。
• ai-electron：Electron 桌面工程，通过 ee-core 组织前端构建、打包与更新流程。

• ai-electron/frontend：Vue 3 前端源码，由 Vite + pnpm 构建。

  graph TB
  subgraph "后端"
      A["ai-server<br/>Spring Boot 3.5.16"]
      B["ai-gateway<br/>Spring Cloud Gateway WebFlux"]
  end
  
  subgraph "前端"
      C["ai-electron/frontend<br/>Vue 3 + Vite + pnpm"]
  end
  
  subgraph "桌面层"
      D["ai-electron<br/>Electron 37 + ee-core"]
  end
  
  C --> D
  B --> A
  

图示来源

• pom.xml:1-23
• ai-gateway/pom.xml:1-25
• ai-electron/package.json:1-42
• ai-electron/frontend/package.json:1-20

章节来源

• pom.xml:1-23
• ai-gateway/pom.xml:1-25
• ai-electron/package.json:1-15
• ai-electron/frontend/package.json:1-20

核心依赖矩阵

层次	框架或库	主要版本	用途	兼容性注意事项
后端	Spring Boot	3.5.16	统一后端启动、自动配置与依赖托管	Java 25；升级需检查 Spring Boot 3.x 到 4.x 的破坏性变更
后端	Spring Cloud	2025.0.1	网关及 WebFlux 生态版本协调	与 Spring Boot 3.5 配套，不可随意改为其他发布线
后端	Spring Cloud Gateway WebFlux	由 Spring Cloud BOM 管理	非阻塞网关、SSE、分片下载、流式转发	避免混用 Servlet 容器与 WebFlux
后端	MyBatis-Plus	3.5.17	ORM、分页、代码生成、通用 CRUD	必须配合 Spring Boot 3 Starter
后端	Dynamic Datasource	4.5.0	多数据源切换，连接 PostgreSQL、DuckDB 等	与 Spring Boot 3 Starter 版本对齐
后端	Sa-Token	1.46.0	会话与权限控制，前后端共享 Redis	网关与服务端 Sa-Token 配置必须一致
后端	Redis	由 Spring Data Redis 引入	缓存、会话存储、Agent 扩展缓存	注意 reactive 与非 reactive 客户端差异
后端	PostgreSQL / pgvector	pgvector 0.1.6	关系数据与向量检索	需要 PostgreSQL 启用 pgvector 扩展
后端	DJL HuggingFace Tokenizers	0.38.0	本地加载 tokenizer.json，Rust 原生依赖	需匹配运行平台 native 库
后端	ONNX Runtime	1.30.0	本地嵌入模型推理	与 CPU/native 包匹配，注意平台分发体积
后端	DuckDB JDBC	1.5.5.1	嵌入式分析查询（测试/数据源）	适合单机分析，不适合高并发写入
后端	Spring AI Tika	Spring AI BOM 1.1.8	文档解析、附件读取	与 Spring AI BOM 管理版本
后端	AgentScope	2.0.1	Agent 编排、DashScope/Ollama/OpenAI/Mem0/RAG/Redis 扩展	已排除 MCP SDK，不引入外部 MCP 客户端
前端	Vue	3.5.25	组件化 UI 框架	与 @vue/compiler-sfc、@vue/runtime-core、@vue/shared 同版本
前端	Vite	7.2.7	前端构建与开发服务器	Node 要求见 engines 字段
前端	pnpm	10.25.0	包管理器	脚本强制只允许 pnpm
前端	Ant Design Vue	4.2.6	企业级 UI 组件库	与 Vue 3 兼容，升级需关注 Breaking Changes
前端	Pinia	2.3.1	状态管理	替代 Vuex，与 Vue 3 生态匹配
前端	Vue Router	4.6.3	单页路由	与 Vue 3 对应主版本
前端	Vue I18n	11.2.2	国际化	与 Vue 3 生态匹配
前端	Monaco Editor	0.55.1	代码编辑器	体积较大，按需动态加载
前端	CodeMirror	5.65.16	文本编辑与语法支持	仍为 v5，不是 v6 API
前端	VDitor	3.11.2	Markdown 编辑器	与 Markdown-it 协同渲染
前端	Markdown-it	14.1.1+	Markdown 解析	插件生态需注意版本兼容
前端	ECharts	6.0.0	图表可视化	与浏览器 WebGL/Canvas 能力相关
前端	AntV G6	5.1.0	关系图与拓扑图	与 @antv/g 6.3.1 配套
前端	AntV X6	2.19.2+	流程图/绘图引擎	与 selection 插件版本配套
前端	Relation Graph	3.0.13	关系图组件	作为上层封装，仍需底层图布局兼容
前端	MapLibre GL	5.22.0+	矢量地图	与 PMTiles 协议配合展示瓦片
前端	PMTiles	4.4.0+	PMTiles 瓦片加载	需服务端或代理正确返回内容类型
前端	Dexie	4.3.0+	IndexedDB 封装	用于浏览器端轻量缓存
前端	xlsx	0.18.5	Excel 读写	大表可能影响内存，建议分页处理
前端	crypto-js	4.2.0	加密算法工具	仅做辅助加密，敏感场景需结合后端安全策略
前端	dayjs	1.11.19	时间格式化与计算	轻量替代 Moment.js
前端	lodash-es	4.17.21	工具函数库	Tree-shaking 友好，优先使用 esm 版本
桌面层	Electron	37.8.0+	桌面应用运行时	需匹配 Chromium 与 Node 版本
桌面层	electron-builder	26.3.5+	跨平台打包	与 Electron 主版本配套
桌面层	ee-core	5.0.1+	工程脚手架与构建流程	提供 dev/build/start/encrypt 等命令
桌面层	electron-updater	6.7.3+	桌面端自动更新	需配置更新源与签名

章节来源

• pom.xml:1-23
• ai-server/pom.xml:1-405
• ai-gateway/pom.xml:1-148
• ai-electron/package.json:1-42
• ai-electron/frontend/package.json:1-162

后端架构与依赖

后端整体定位

后端由两个 Spring Boot 模块组成：

• ai-server：业务主体，负责登录认证、账号校验、案件数据源管理、Agent 调用、文档解析、向量检索、全文检索、Excel/CSV 处理、文件系统与部署产物输出。

• ai-gateway：WebFlux 网关，负责将请求按用户粘性转发到后端，复用 Redis 中 Sa-Token 的用户标识进行路由决策，并处理流式响应、SSE 和多部分传输。

  graph LR
  Client["客户端"] --> Gateway["ai-gateway<br/>Spring Cloud Gateway WebFlux"]
  Gateway --> Server["ai-server<br/>Spring Boot 业务服务"]
  Server --> Redis["Redis"]
  Server --> Postgres["PostgreSQL + pgvector"]
  Server --> DuckDB["DuckDB JDBC"]
  Server --> ES["Elasticsearch"]
  

图示来源

• ai-gateway/pom.xml:26-90
• ai-server/pom.xml:1-200
• ai-server/pom.xml:201-405

关键后端依赖说明

依赖	作用	风险点
Spring Boot 3.5.16	所有后端模块的统一父版本	升级时注意 Java 25、Jakarta EE、Actuator、配置文件语义变化
Spring Cloud 2025.0.1	管理 Gateway、WebFlux、Reactive 生态版本	不要与旧版 Spring Cloud 混合
MyBatis-Plus 3.5.17	持久层基础能力	升级时需验证 SQL 生成、分页与 Lambda 表达式行为
Dynamic Datasource 4.5.0	多数据源路由	升级后注解、默认数据源、事务传播可能变化
Sa-Token 1.46.0	登录态、权限、Redis 会话	网关和服务端 token key、序列化方式必须一致
Spring Data Redis	缓存与会话	注意 Reactor Redis 与 Blocking Redis 的差异
pgvector 0.1.6	PostgreSQL 向量扩展 Java SDK	需要数据库端也安装 pgvector
DJL HuggingFace Tokenizers 0.38.0	本地 tokenizer.json 解析	Rust native 依赖在 Windows/macOS/Linux 上行为不同
ONNX Runtime 1.30.0	本地模型推理	大模型会显著增加内存和安装包体积
DuckDB JDBC 1.5.5.1	嵌入式数据分析	不适合高并发写入库场景
Spring AI Tika	文档解析	依赖 Tika 生态，大型文档解析耗时较长
AgentScope 2.0.4	Agent 框架与模型扩展	已排除 MCP，外部 MCP 客户端不会随包引入
Elasticsearch Starter	全文检索	注释明确服务端须与 Spring Boot 托管客户端 8.18.x 匹配

章节来源

• ai-server/pom.xml:1-405
• ai-gateway/pom.xml:1-148

前端架构与依赖

前端整体定位

前端位于 ai-electron/frontend，是一个 Vue 3 + TypeScript + Vite + pnpm 的单页应用。它被 Electron 工程 ai-electron 作为静态资源加载，并通过 ee-core 提供的脚本统一开发、构建、加密和打包。

graph TB
    Dev["开发者"] --> Pnpm["pnpm 10.25.0"]
    Pnpm --> Vite["Vite 7.2.7"]
    Vite --> Vue["Vue 3.5.25"]
    Vue --> Antd["Ant Design Vue 4.2.6"]
    Vue --> Pinia["Pinia 2.3.1"]
    Vue --> Router["Vue Router 4.6.3"]
    Vue --> I18n["Vue I18n 11.2.2"]
    Vue --> Editors["Monaco / CodeMirror / VDitor"]
    Vue --> Charts["ECharts / AntV G6 / X6 / Relation Graph"]
    Vue --> Maps["MapLibre GL / PMTiles"]
    Vue --> Storage["Dexie / xlsx / crypto-js / dayjs / lodash-es"]

图示来源

• ai-electron/frontend/package.json:1-162

关键前端依赖说明

依赖	用途	兼容性注意事项
Vue 3.5.25	核心 UI 框架	与编译器和运行时包保持相同主版本
Vite 7.2.7	构建与开发服务器	Node 版本受 engines 约束
pnpm 10.25.0	包管理器	脚本预安装钩子强制使用 pnpm
Ant Design Vue 4.2.6	企业级组件库	升级前需确认与 Vue 3 和样式主题兼容
Pinia 2.3.1	状态管理	不再支持 Vuex API，迁移需谨慎
Vue Router 4.6.3	路由系统	与 Vue 3 对应版本
Vue I18n 11.2.2	国际化	Composition API 为主，旧 API 可能弃用
Monaco Editor 0.55.1	代码编辑	包体大，建议按需加载语言支持
CodeMirror 5.65.16	编辑器内核	v5 API 与 v6 不兼容
VDitor 3.11.2	Markdown 编辑器	与 Markdown-it 插件生态需一起验证
Markdown-it 14.1.1+	Markdown 解析	插件升级可能改变渲染结果
ECharts 6.0.0	图表	大数据集应开启虚拟化或采样
AntV G6 5.1.0	关系图	与 @antv/g 6.3.1 配套
AntV X6 2.19.2+	流程图与绘图	与 selection 插件版本一致
Relation Graph 3.0.13	关系图封装	若替换底层图引擎需重新验证交互
MapLibre GL 5.22.0+	矢量地图	注意 CORS、瓦片格式与缩放层级
PMTiles 4.4.0+	PMTiles 瓦片	需要正确的 MIME 类型和范围请求
Dexie 4.3.0+	IndexedDB 封装	升级 Schema 需考虑已有索引和数据
xlsx 0.18.5	Excel 读写	超大表格需限制行数与列数
crypto-js 4.2.0	加密工具	不能替代后端安全机制
dayjs 1.11.19	时间处理	升级时注意 locale 和插件行为
lodash-es 4.17.21	工具函数	优先导入具体函数以减小体积

章节来源

• ai-electron/frontend/package.json:1-162

桌面层架构与依赖

桌面层整体定位

桌面层位于 ai-electron，主入口指向 public/electron/main.js，通过 ee-core 提供统一的开发、构建、启动、图标处理和加密流程。electron-updater 负责桌面应用的自动更新逻辑。

flowchart TD
    Start["桌面进程启动"] --> EECore["ee-core 构建流程"]
    EECore --> Frontend["前端静态资源"]
    EECore --> ElectronRuntime["Electron 37.8.0 运行时"]
    ElectronRuntime --> Updater["electron-updater 6.7.3+"]
    Updater --> UpdateServer["更新服务器"]

图示来源

• ai-electron/package.json:1-42

关键桌面依赖说明

依赖	用途	兼容性注意事项
Electron 37.8.0+	桌面运行时	升级需验证 Chromium、Node、原生模块 ABI
electron-builder 26.3.5+	跨平台打包	与 Electron 主版本配套，签名和 notarize 可能变化
ee-core 5.0.1+	工程脚手架	覆盖 dev/build/start/encrypt 等行为，升级需核对脚本契约
electron-updater 6.7.3+	自动更新	需配置更新地址、签名、增量更新和回滚策略
@electron/rebuild ^3.7.1	重建原生模块	如使用 better-sqlite3 等原生依赖时需要

章节来源

• ai-electron/package.json:1-42

依赖管理方式

Maven 父工程 pom.xml

根 pom.xml 继承 Spring Boot 官方父工程 spring-boot-starter-parent 3.5.16，将工程定义为打包类型为 pom 的多模块聚合工程，并声明两个子模块：

• ai-server
• ai-gateway

这意味着：

• 所有 Spring Boot 相关依赖版本默认由 Spring Boot 3.5.16 管理。
• 子模块可以显式覆盖某些依赖版本。
• 新增后端模块时应添加到 <modules> 列表中。

章节来源

• pom.xml:1-23

ai-server/pom.xml

该模块定义 Java 25、Spring AI BOM、AgentScope、pgvector、DJL、ONNX Runtime、DuckDB JDBC、MyBatis-Plus、Dynamic Datasource、Sa-Token、Spring Security Crypto、Guava、Hutool、MapStruct、Elasticsearch Starter 等依赖，并配置了：

• Spring Boot 瘦包与肥包构建。
• MapStruct 注解处理器。
• Lombok 注解处理器。
• 工作目录指向仓库根，保证附件路径与历史产物一致。

章节来源

• ai-server/pom.xml:1-405

ai-gateway/pom.xml

网关模块继承同一 Maven 父工程，并单独引入 Spring Cloud BOM 2025.0.1。它依赖：

• Spring Cloud Gateway WebFlux。
• Spring WebFlux。
• Spring JDBC 与 PostgreSQL。
• Reactor Redis。
• Sa-Token Reactor Starter 与 Redis Jackson 集成。
• Lombok、Spring Boot Test、Reactor Test。

构建阶段还会把根目录下的 sql/gateway.sql 复制到 classpath，供启动时初始化网关表。

章节来源

• ai-gateway/pom.xml:1-148

前端 package.json

前端工程位于 ai-electron/frontend，使用 pnpm，并通过 scripts 暴露 bootstrap、dev、build、preview、lint、typecheck、update 等命令。dependencies 中声明了 Vue、Ant Design Vue、Pinia、Vue Router、Vue I18n、Monaco Editor、CodeMirror、VDitor、Markdown-it、ECharts、AntV G6/X6、Relation Graph、MapLibre GL、PMTiles、Dexie、xlsx、crypto-js、dayjs、lodash-es 等运行时依赖；devDependencies 中声明 Vite、TypeScript、ESLint、Prettier、UnoCSS、vue-tsc 等构建与质量工具。

章节来源

• ai-electron/frontend/package.json:1-162

桌面层 package.json

桌面工程位于 ai-electron，主入口为 public/electron/main.js，scripts 通过 ee-bin 调用 ee-core 提供的命令，包括前端构建、Electron 构建、加密、图标处理和多平台打包。dependencies 中声明 ee-core 和 electron-updater，devDependencies 中声明 Electron、electron-builder、@electron/rebuild、TypeScript、Vitest 等。

章节来源

• ai-electron/package.json:1-42

兼容性注意事项

后端兼容性

• Java 25：当前后端模块声明 Java 25，构建环境和 CI 必须支持该版本。
• Spring Boot 3.5.16 与 Spring Cloud 2025.0.1：两者属于同一 Spring 生态发布线，不应混入旧版 Spring Cloud 或新版 Spring Boot 4。
• Sa-Token 1.46.0：网关与服务端必须使用相同版本，且 Redis 地址、token key、序列化方式保持一致，否则 token 解析会失败。
• pgvector 0.1.6：仅引入 Java SDK，实际向量检索还需要 PostgreSQL 数据库安装并启用 pgvector 扩展。
• DJL HuggingFace Tokenizers 0.38.0 与 ONNX Runtime 1.30.0：两者都涉及 native 库，Windows、macOS、Linux 平台的二进制包和行为需要分别验证。
• DuckDB JDBC 1.5.5.1：适合嵌入式分析，但不应视为通用高并发数据库。
• Spring AI Tika：文档解析依赖 Tika 生态，升级 Spring AI BOM 时需同步验证解析器兼容性。
• AgentScope 2.0.4：已排除 MCP SDK，如果未来引入外部 MCP 客户端，需要显式添加依赖。
• Elasticsearch Starter：注释明确指出服务端版本应与 Spring Boot 托管的客户端 8.18.x 匹配，不能随意升级服务端 Elasticsearch。

前端兼容性

• Vue 3.5.25 与编译器/运行时包：应保持主版本一致，避免运行时与模板编译期不匹配。
• Vite 7.2.7 与 Node 版本：engines 要求 Node >=20.19 或 >=22.12，低版本 Node 可能无法构建。
• pnpm 10.25.0：preinstall 钩子强制使用 pnpm，使用 npm/yarn 可能触发警告或错误。
• Ant Design Vue 4.2.6：升级时需关注主题变量、组件 API 和 Vue 3 兼容性。
• CodeMirror 5.65.16：仍为 v5，不是 v6，API 不兼容，不能直接按 v6 文档升级。
• ECharts 6.0.0：大数据量图表应考虑数据降采样、虚拟化和按需引入模块。
• MapLibre GL 与 PMTiles：需要服务端正确设置 CORS、Content-Type 和 Range 请求支持。
• Dexie 4.3.0+：IndexedDB schema 升级需考虑已有数据迁移。

桌面层兼容性

• Electron 37.8.0+：升级需验证 Chromium、Node、原生模块 ABI 是否兼容。
• electron-builder 26.3.5+：与 Electron 主版本配套，签名、公证、增量更新策略可能变化。
• ee-core 5.0.1+：作为脚手架覆盖构建和启动流程，升级时需核对脚本契约。
• electron-updater 6.7.3+：需确保更新服务器返回正确的 latest.yml 或等效元数据，并配置签名校验。

章节来源

• ai-server/pom.xml:1-405
• ai-gateway/pom.xml:1-148
• ai-electron/frontend/package.json:1-162
• ai-electron/package.json:1-42

升级依赖的风险点

后端风险点

1. Spring Boot 3.5.16 → 更高版本
   可能带来 Jakarta EE 命名空间、Actuator、配置绑定、日志、测试框架等破坏性变更。应先升级到 Spring Boot 3.x 最新稳定版，再评估 4.x。
2. Spring Cloud 2025.0.1 → 其他发布线
   必须与 Spring Boot 主版本匹配，否则 WebFlux、Gateway、Reactor 可能出现类缺失或行为异常。
3. MyBatis-Plus 与 Dynamic Datasource
   升级前应验证分页、Lambda 查询、SQL 生成、事务传播和多数据源切换行为。
4. Sa-Token 1.46.0
   网关与服务端必须同步升级，且 Redis 配置、token key、序列化实现要保持一致。
5. pgvector、DJL、ONNX Runtime
   这些依赖涉及 native 库和平台二进制，升级时必须逐平台验证安装、加载、内存占用和推理结果。
6. AgentScope 2.0.4
   如果未来引入 MCP 客户端，需要显式引入依赖，因为当前已排除 MCP SDK。
7. Elasticsearch Starter
   升级服务端 Elasticsearch 时，必须与 Spring Boot 托管的客户端 8.18.x 匹配，不能只看版本号。

前端风险点

1. Vue 3 内部包版本不一致
   vue、@vue/compiler-sfc、@vue/runtime-core、@vue/shared 都应保持在相同主版本，避免运行时与编译期不一致。
2. Vite 与 Node 版本
   升级 Vite 或 Node 前应验证 pnpm、TypeScript、ESLint、Prettier、UnoCSS、vue-tsc 是否兼容。
3. Ant Design Vue 4.2.6
   升级可能影响样式、组件 API、主题变量和 SSR 行为。
4. CodeMirror 5 → 6
   API 不兼容，不能简单替换，需要重构编辑器集成。
5. ECharts、AntV G6/X6、Relation Graph
   升级图引擎或图表库时，需重新验证交互、布局、性能和大图渲染。
6. MapLibre GL 与 PMTiles
   升级后需验证瓦片协议、CORS、Range 请求和移动端兼容性。
7. Dexie 与 IndexedDB
   升级 schema 时需编写迁移逻辑，防止用户本地数据损坏。

桌面层风险点

1. Electron 37 → 更高版本
   需要验证 Chromium、Node、原生模块 ABI、GPU 加速、打印、窗口行为和权限模型。
2. electron-builder
   升级后可能需要调整签名、公证、增量更新、NSIS/MSI/Dmg/AppImage 配置。
3. ee-core
   作为脚手架，升级可能改变 dev/build/start/encrypt 的行为，需回归测试完整构建流程。
4. electron-updater
   升级后需验证更新元数据、签名校验、增量更新、失败回退和网络重试策略。

章节来源

• pom.xml:1-23
• ai-server/pom.xml:1-405
• ai-gateway/pom.xml:1-148
• ai-electron/frontend/package.json:1-162
• ai-electron/package.json:1-42

结论

清鉴 AI 调查工具的技术栈围绕 Spring Boot 3.5.16 后端、Vue 3 前端和 Electron 37 桌面层展开。后端通过 Spring Cloud Gateway WebFlux 接入，使用 MyBatis-Plus、Dynamic Datasource、Sa-Token、Redis、PostgreSQL/pgvector、DJL HuggingFace Tokenizers、ONNX Runtime、DuckDB JDBC、Spring AI Tika 和 AgentScope 形成“关系数据 + 向量检索 + 文档解析 + Agent”的能力组合；前端以 Vue 3 为核心，整合 Ant Design Vue、Pinia、Vue Router、Vue I18n、编辑器、图表、图和地图生态；桌面层通过 ee-core 统一构建和打包，并由 electron-updater 提供更新能力。

升级依赖时应优先保证 Spring Boot 与 Spring Cloud 的主版本一致性、Sa-Token 前后端一致性、Vue 内部包一致性、Electron 与 electron-builder 的主版本一致性，并对 native 依赖、图引擎、地图协议和 IndexedDB schema 进行专项回归测试。