Common Agent

Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。

当前项目处于基础工程阶段。后端骨架（含 DTO、统一返回体、全局异常处理、审计自动填充）、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成； Agent 运行时、RAG 文档解析与向量化和更多管理功能会在后续阶段逐步实现。

项目愿景

Common Agent 希望成为一个可复用的企业级 AI 应用基础平台：

• Agent 运行时：支持对话、工具调用、记忆、任务执行和流程编排。
• RAG 知识库：支持文档导入、解析、切片、向量化、检索和基于上下文的回答生成。
• 模型抽象：通过 Spring AI 统一接入聊天模型、Embedding 模型和重排序模型。
• 管理控制台：提供会话、Agent、知识库、文档、提示词和系统配置的 Web 管理界面。
• 多环境部署：支持本地开发、测试环境和生产环境的配置隔离。

当前技术栈

类别	技术
后端	Java 21, Spring Boot 4.0.6, MyBatis-Plus 3.5.16
数据库	PostgreSQL
工具库	Lombok, Springdoc OpenAPI 2.8.13, Jackson
构建	Maven Wrapper
前端	Vue 3, TypeScript 5.9, Vite, Element Plus, Pinia, Vue Router 4
前端测试	Vitest, @vue/test-utils
后端测试	Spring Boot Test

项目结构

common_agent
├── frontend/                          # Vue 3 前端控制台
│   ├── src/
│   │   ├── api/                       # Axios 封装与各模块 API
│   │   ├── layouts/                   # AdminLayout 管理后台布局
│   │   ├── pages/                     # 业务页面（工作台、枚举、附件、知识库、文档）
│   │   ├── router/                    # Vue Router 配置
│   │   ├── stores/                    # Pinia 状态管理
│   │   ├── styles/                    # 全局样式
│   │   └── types/                     # TypeScript 类型声明
│   └── package.json
├── src/
│   ├── main/java/com/bruce/
│   │   ├── CommonAgentApplication.java
│   │   ├── common/                    # 公共模块
│   │   │   ├── config/                # AttachmentProperties, EntityAuditMetaObjectHandler
│   │   │   ├── controller/            # SysAttachmentController, SysEnumController
│   │   │   ├── domain/
│   │   │   │   ├── entity/            # SysAttachment, SysEnum
│   │   │   │   └── model/             # BaseEntity, RequestResult
│   │   │   ├── dto/
│   │   │   │   ├── request/           # 各模块请求 DTO
│   │   │   │   └── response/          # 各模块响应 DTO
│   │   │   ├── enums/                 # CommonStatusEnum, EnableStatusEnum
│   │   │   ├── handler/               # GlobalExceptionHandler
│   │   │   ├── mapper/                # SysAttachmentMapper, SysEnumMapper
│   │   │   └── service/               # 接口与实现
│   │   └── rag/                       # RAG 知识库模块
│   │       ├── constant/              # RagSystemConstants
│   │       ├── controller/            # RagStoreController, RagDocumentController
│   │       ├── dto/                   # 请求/响应 DTO
│   │       ├── entity/                # RagStore, RagDocument
│   │       ├── enums/                 # RagParseStatusEnum, RagIndexStatusEnum
│   │       ├── mapper/                # RagDocumentMapper, RagStoreMapper
│   │       └── service/               # 接口与实现
│   ├── main/resources/
│   │   ├── application.yaml           # 环境选择
│   │   ├── application-dev.yaml       # 开发环境配置
│   │   └── application-template.yaml  # 配置模板
│   └── test/java/                     # 单元测试（结构稳定性测试 + 前端 API 测试）
├── docs/
│   ├── ARCHITECTURE.md                # 架构说明
│   └── ROADMAP.md                     # 开发路线图
├── AGENT.md                           # 平台设计草案
├── pom.xml
└── README.md

配置说明

主配置文件只负责选择当前环境：

spring:
  application:
    name: common_agent
  profiles:
    active: dev

本地开发环境配置位于 src/main/resources/application-dev.yaml。 当前开发环境数据库指向 PostgreSQL：

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://110.42.106.130:5431/common_agent?currentSchema=common_agent
    username: common_agent
    password: common_agent

src/main/resources/application-template.yaml 是配置模板，可用于复制生成 application-test.yaml、application-prod.yaml 等其他环境配置文件。

运行方式

运行测试：

./mvnw test

启动应用：

./mvnw spring-boot:run

启动前端：

cd frontend
npm install
npm run dev

前端检查：

cd frontend
npm run test:unit
npm run type-check
npm run build

前端控制台

前端控制台位于 frontend 目录，当前使用 Vue 3、Vite、Pinia、Vue Router 和 Element Plus。

当前已有页面：

页面	状态
工作台	占位
系统枚举	完整 CRUD + 批量新增
附件管理	占位
知识库	完整 CRUD + 双栏详情
知识文档	占位

当前 UI 规范：

• 左侧为固定管理导航，右侧为主内容区。
• 主内容区不再额外渲染外层页面标题，标题由各业务页面面板自行展示。
• 全局样式集中在 frontend/src/styles/global.css，页面专属样式优先放在对应 .vue 文件的 scoped style 中。
• 后台页面以清晰、克制、便于扫描为优先目标，避免营销式大面积装饰。

接口规范

• 统一返回体：RequestResult<T>（resultcode, message, data）
• 所有接口通过 DTO 交互，不直接暴露实体
• 查询条件封装为 XxxQueryRequest
• 响应 DTO 提供 fromEntity() 静态转换
• 大整数 ID 通过 @JsonSerialize(ToStringSerializer.class) 防止前端精度丢失
• 全局异常处理返回 HTTP 400/500 状态码

规划模块

• agent-core：Agent 执行模型、工具注册、记忆和编排能力。
• rag-core：文档导入、切片、Embedding、检索和引用元数据。
• model-provider：基于 Spring AI 的聊天模型、Embedding、重排序和模型配置层。
• platform-api：面向前端和外部系统的 REST API。
• platform-admin：平台管理前端。
• common-infra：持久化、审计日志、安全、租户隔离和可观测性。

文档

• 架构说明
• 开发路线图
• 平台设计草案

参考资料

• Spring AI Reference
• Spring AI RAG Reference
• MyBatis-Plus