# Common Agent

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

当前项目处于基础工程阶段。后端骨架、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成；
Agent 运行时、RAG 索引和更多管理功能会在后续阶段逐步实现。

## 项目愿景

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

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

## 当前技术栈

- Java 21
- Spring Boot 4.0.6
- Spring AI，规划接入
- MyBatis-Plus 3.5.16
- PostgreSQL JDBC Driver
- Lombok
- Maven Wrapper
- PostgreSQL 数据库：`common_agent`

## 项目结构

```text
common_agent
├── frontend
│   ├── src/layouts
│   ├── src/pages
│   ├── src/router
│   └── src/styles
├── src/main/java/com/bruce
│   └── CommonAgentApplication.java
├── src/main/resources
│   ├── application.yaml
│   ├── application-dev.yaml
│   └── application-template.yaml
├── docs
│   ├── ARCHITECTURE.md
│   └── ROADMAP.md
├── pom.xml
└── README.md
```

## 配置说明

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

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

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

```yaml
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` 等其他环境配置文件。

## 运行方式

运行测试：

```powershell
.\mvnw.cmd test
```

启动应用：

```powershell
.\mvnw.cmd spring-boot:run
```

当前阶段还没有加入 Web 服务依赖或常驻任务，所以应用可能启动成功后立即退出。

启动前端：

```powershell
cd frontend
npm install
npm run dev
```

前端检查：

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

## 前端控制台

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

当前已有页面：

- 工作台
- 系统枚举
- 附件管理
- 知识库
- 知识文档

当前 UI 规范：

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

## 规划模块

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

## 文档

- [架构说明](docs/ARCHITECTURE.md)
- [开发路线图](docs/ROADMAP.md)

## 参考资料

- [Spring AI Reference](https://docs.spring.io/spring-ai/reference/)
- [Spring AI RAG Reference](https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html)
- [MyBatis-Plus](https://baomidou.com/)