# 技术栈与依赖
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [ai-server/pom.xml](file://ai-server/pom.xml)
- [ai-gateway/pom.xml](file://ai-gateway/pom.xml)
- [ai-electron/package.json](file://ai-electron/package.json)
- [ai-electron/frontend/package.json](file://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 构建。
```mermaid
graph TB
subgraph "后端"
A["ai-server
Spring Boot 3.5.16"]
B["ai-gateway
Spring Cloud Gateway WebFlux"]
end
subgraph "前端"
C["ai-electron/frontend
Vue 3 + Vite + pnpm"]
end
subgraph "桌面层"
D["ai-electron
Electron 37 + ee-core"]
end
C --> D
B --> A
```
**图示来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
- [ai-gateway/pom.xml:1-25](file://ai-gateway/pom.xml#L1-L25)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/frontend/package.json:1-20](file://ai-electron/frontend/package.json#L1-L20)
**章节来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
- [ai-gateway/pom.xml:1-25](file://ai-gateway/pom.xml#L1-L25)
- [ai-electron/package.json:1-15](file://ai-electron/package.json#L1-L15)
- [ai-electron/frontend/package.json:1-20](file://ai-electron/frontend/package.json#L1-L20)
## 核心依赖矩阵
| 层次 | 框架或库 | 主要版本 | 用途 | 兼容性注意事项 |
|---|---|---:|---|---|
| 后端 | 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](file://pom.xml#L1-L23)
- [ai-server/pom.xml:1-405](file://ai-server/pom.xml#L1-L405)
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
- [ai-electron/frontend/package.json:1-162](file://ai-electron/frontend/package.json#L1-L162)
## 后端架构与依赖
### 后端整体定位
后端由两个 Spring Boot 模块组成:
- `ai-server`:业务主体,负责登录认证、账号校验、案件数据源管理、Agent 调用、文档解析、向量检索、全文检索、Excel/CSV 处理、文件系统与部署产物输出。
- `ai-gateway`:WebFlux 网关,负责将请求按用户粘性转发到后端,复用 Redis 中 Sa-Token 的用户标识进行路由决策,并处理流式响应、SSE 和多部分传输。
```mermaid
graph LR
Client["客户端"] --> Gateway["ai-gateway
Spring Cloud Gateway WebFlux"]
Gateway --> Server["ai-server
Spring Boot 业务服务"]
Server --> Redis["Redis"]
Server --> Postgres["PostgreSQL + pgvector"]
Server --> DuckDB["DuckDB JDBC"]
Server --> ES["Elasticsearch"]
```
**图示来源**
- [ai-gateway/pom.xml:26-90](file://ai-gateway/pom.xml#L26-L90)
- [ai-server/pom.xml:1-200](file://ai-server/pom.xml#L1-L200)
- [ai-server/pom.xml:201-405](file://ai-server/pom.xml#L201-L405)
### 关键后端依赖说明
| 依赖 | 作用 | 风险点 |
|---|---|---|
| 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.1 | Agent 框架与模型扩展 | 已排除 MCP,外部 MCP 客户端不会随包引入 |
| Elasticsearch Starter | 全文检索 | 注释明确服务端须与 Spring Boot 托管客户端 8.18.x 匹配 |
**章节来源**
- [ai-server/pom.xml:1-405](file://ai-server/pom.xml#L1-L405)
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
## 前端架构与依赖
### 前端整体定位
前端位于 `ai-electron/frontend`,是一个 Vue 3 + TypeScript + Vite + pnpm 的单页应用。它被 Electron 工程 `ai-electron` 作为静态资源加载,并通过 `ee-core` 提供的脚本统一开发、构建、加密和打包。
```mermaid
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](file://ai-electron/frontend/package.json#L1-L162)
### 关键前端依赖说明
| 依赖 | 用途 | 兼容性注意事项 |
|---|---|---|
| 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](file://ai-electron/frontend/package.json#L1-L162)
## 桌面层架构与依赖
### 桌面层整体定位
桌面层位于 `ai-electron`,主入口指向 `public/electron/main.js`,通过 `ee-core` 提供统一的开发、构建、启动、图标处理和加密流程。`electron-updater` 负责桌面应用的自动更新逻辑。
```mermaid
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](file://ai-electron/package.json#L1-L42)
### 关键桌面依赖说明
| 依赖 | 用途 | 兼容性注意事项 |
|---|---|---|
| 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](file://ai-electron/package.json#L1-L42)
## 依赖管理方式
### 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 管理。
- 子模块可以显式覆盖某些依赖版本。
- 新增后端模块时应添加到 `` 列表中。
**章节来源**
- [pom.xml:1-23](file://pom.xml#L1-L23)
### 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](file://ai-server/pom.xml#L1-L405)
### 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](file://ai-gateway/pom.xml#L1-L148)
### 前端 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](file://ai-electron/frontend/package.json#L1-L162)
### 桌面层 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](file://ai-electron/package.json#L1-L42)
## 兼容性注意事项
### 后端兼容性
- **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.1**:已排除 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](file://ai-server/pom.xml#L1-L405)
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
- [ai-electron/frontend/package.json:1-162](file://ai-electron/frontend/package.json#L1-L162)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
## 升级依赖的风险点
### 后端风险点
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.1**
如果未来引入 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](file://pom.xml#L1-L23)
- [ai-server/pom.xml:1-405](file://ai-server/pom.xml#L1-L405)
- [ai-gateway/pom.xml:1-148](file://ai-gateway/pom.xml#L1-L148)
- [ai-electron/frontend/package.json:1-162](file://ai-electron/frontend/package.json#L1-L162)
- [ai-electron/package.json:1-42](file://ai-electron/package.json#L1-L42)
## 结论
清鉴 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 进行专项回归测试。