# 技术栈与依赖 **本文引用的文件** - [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.4 | 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.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](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.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](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 进行专项回归测试。