类别	技术
后端	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。

当前已有页面：

页面	状态
RAG 工作台	文档解析与切片概览
系统枚举	完整 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 已有结构，向量写入、检索召回和重排序仍待接入。
模型配置：已补充模型服务商配置与路由需求/设计文档，后续用于统一接入 Ollama、硅基流动、百炼等来源。
前端：知识库页、知识文档页、RAG 工作台和切片任务页已经接入当前接口，检索配置、最近任务、重建索引仍是后续能力。

规划模块

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

README.md Unescape Escape

Common Agent

项目愿景

当前技术栈