Common Agent
Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。
当前项目已经完成基础工程、公共模块、RAG 元数据管理、文档上传、文档解析入口、前端知识库与知识文档管理页面。 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, Apache Tika 3.2.3 |
| 构建 | 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
│ │ │ ├── document/parse/ # 文档解析抽象与 Tika 实现
│ │ │ ├── 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, RagChunk, RagChunkEmbedding
│ │ ├── enums/ # RagParseStatusEnum, RagIndexStatusEnum, RagChunkStrategyEnum
│ │ ├── 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 状态码
RAG 当前能力边界
当前 RAG 已经从元数据管理推进到"上传 + 解析入口"阶段：
- 知识库：支持列表、条件查询、详情、总览、单库文档概览、新增、编辑、删除。
- 知识文档：支持列表、条件查询、详情、新增/编辑、删除、批量上传。
- 文档解析：基于 Apache Tika 支持 TXT/Markdown/LOG、PDF、Word、Excel 文本抽取，解析时更新
parseStatus。 - 切片与向量表：
rag_chunk、rag_chunk_embedding实体、Mapper、Service 已有结构，但尚未实现切片生成、向量写入和检索召回。 - 前端：知识库页和知识文档页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。
规划模块
agent-core：Agent 执行模型、工具注册、记忆和编排能力。rag-core：文档导入、解析、切片、Embedding、检索和引用元数据。model-provider：基于 Spring AI 的聊天模型、Embedding、重排序和模型配置层。platform-api：面向前端和外部系统的 REST API。platform-admin：平台管理前端。common-infra：持久化、审计日志、安全、租户隔离和可观测性。