dependency_management.md 4.0 KB
总体方案
仓库是一个混合技术栈的聚合工程，涉及三种依赖管理体系：
| 语言/模块 | 包管理器 | 清单文件 | 锁定文件 |
|---|---|---|---|
| Java (ai-server, ai-gateway) | Maven | pom.xml |
无（未启用 BOM lock） |
Electron 主进程 (ai-electron) |
npm | ai-electron/package.json |
package-lock.json |
Vue 前端 (ai-electron/frontend) |
pnpm | ai-electron/frontend/package.json |
pnpm-lock.yaml |
根目录 pom.xml 是 Spring Boot 3.5 聚合父工程，仅声明两个 Maven 子模块，不直接引入业务依赖。
Java 层（Maven）
- 父 POM 继承
org.springframework.boot:spring-boot-starter-parent:3.5.16，统一 Java 25、编码等属性。 ai-server/pom.xml通过<dependencyManagement>引入spring-ai-bom:1.1.8集中管理 Spring AI 子组件版本；其他第三方库（Guava、Druid、Commons、pgvector、DJL、ONNX Runtime 等）在<properties>中集中声明，再由<dependencies>引用${xxx.version}。ai-gateway/pom.xml通过<dependencyManagement>引入spring-cloud-dependencies:${spring-cloud.version}（2025.0.1），并显式与ai-server共享sa-token:1.46.0，注释明确要求“版本必须与 ai-server 完全一致”。- 未发现 Maven
settings.xml或pom.xml中的自定义<repository>/<mirror>配置，Java 依赖默认从中央仓库解析。 ai-server对传递依赖做选择性排除：例如agentscope-harness排除了io.modelcontextprotocol.sdk:mcp，注释说明“本项目不接外部 MCP 客户端”。
Node.js 层（Electron + Vue 前端）
Electron 主进程
- 位于
ai-electron/package.json，使用 npm（由package-lock.json锁定）。 - 构建工具链基于自研
ee-bin@^5.0.0和ee-core@^5.0.1，打包用electron-builder，更新用electron-updater。
Vue 前端
- 位于
ai-electron/frontend/package.json，使用 pnpm（packageManager: "pnpm@10.25.0"，通过engines.node >=20.19 || >=22.12约束运行时）。 preinstall: npx only-allow pnpm强制安装器必须是 pnpm。- 依赖版本大多采用精确版本号（如
vue: 3.5.25、ant-design-vue: 4.2.6、vite: 7.2.7），而非范围符，便于锁定可复现构建。 resolutions.bin-wrapper: npm:bin-wrapper-china用于替换bin-wrapper以适配国内网络。.npmrc配置了两个镜像源：registry=https://registry.npmmirror.com（全局 npm 镜像）@jeesite:registry=https://maven.jeesite.net/repository/npm-package/（私有 npm 仓库，用于@jeesite/*scope）
pnpm.onlyBuiltDependencies白名单限定core-js、es5-ext、esbuild、vue-demi允许编译原生依赖，减少不必要的 native rebuild。- 提供
ncu -u && pnpm reinstall（pnpm update）脚本用于升级依赖。
约定与约束
- Java 依赖版本统一管理：所有第三方库版本集中在
ai-server/pom.xml的<properties>与<dependencyManagement>中声明，子模块不得硬编码版本（依据 pom 结构推断的约定）。 - 跨模块版本一致性：
ai-gateway与ai-server共用相同版本的 Sa-Token，并在源码注释中要求二者保持一致（ai-gateway/pom.xml明确注释）。[来源：ai-gateway/pom.xml 注释] - Node 环境约束：前端要求 Node ≥20.19 或 ≥22.12，安装时必须使用 pnpm（
preinstall钩子 +engines字段）。[来源：ai-electron/frontend/package.json] - Electron 主进程与前端分离：主进程使用 npm，前端使用 pnpm，两套锁文件独立维护。
- 私有 npm 仓库：
@jeesite/*包走https://maven.jeesite.net/repository/npm-package/，其余包走npmmirror。[来源：ai-electron/frontend/.npmrc] - 无 Maven 私有仓库配置：当前 POM 中未发现自定义
<repositories>或<mirrors>，Java 依赖全部来自中央仓库。 - 构建产物不含 MCP SDK：
ai-server通过<exclusions>移除 agentscope 传递引入的io.modelcontextprotocol.sdk:mcp，避免产物冗余。[来源：ai-server/pom.xml]