# one-agent

**Repository Path**: it_yaochao/one-agent

## Basic Information

- **Project Name**: one-agent
- **Description**: one to many,一个智能体创建平台
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# One-Agent

[![Java 17](https://img.shields.io/badge/Java-17-007396?logo=openjdk&logoColor=white)](https://openjdk.org/projects/jdk/17/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.5-6DB33F?logo=springboot&logoColor=white)](https://spring.io/projects/spring-boot)
[![Vue 3](https://img.shields.io/badge/Vue-3.x-42b883?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.x-4479A1?logo=mysql&logoColor=white)](https://www.mysql.com/)

简体中文 | [English](README.en.md)

One-Agent 是一个面向 AI Agent 应用开发的开源控制台与运行时平台。项目以 Spring Boot、Vue 3、MySQL、Redis 和 AgentScope Harness 为核心，提供模型管理、Agent 配置、Prompt 管理、工具编排、运行调试、Playground 会话和 Knowledge/RAG 基础能力。

项目当前处于积极开发阶段，适合作为 Agent 平台、LLM 应用后台、工具调用网关或企业内部 AI 工作台的二次开发基础。项目已接入 IAM 账号、Tenant 隔离、RBAC 和多端 Session；生产环境仍需完成真实联调、密钥托管、部署运维、审批与审计治理。

## 功能特性

- 模型中心：管理 OpenAI Compatible 模型供应商、模型信息、调用参数和模型连通性测试。
- Agent 中心：维护 Agent 基础信息、分类、标签、模型配置、Prompt 引用和运行参数。
- Prompt 中心：支持 Prompt 分类、模板、版本、变量、标签和版本发布管理，并提供渲染接口。
- Tool 中心：支持 HTTP Tool 配置、OpenAPI/cURL Schema 生成、版本管理、权限检查、调试记录和调用日志。
- MCP 管理：支持 MCP Server 配置管理和平台 Tool 映射数据结构；MCP 工具执行仍是占位能力。
- Agent Runtime：基于 AgentScope Harness 组织会话、运行、消息、模型调用、工具调用、Trace、错误和流式事件。
- Playground：提供 Agent 会话调试、流式运行、运行详情、消息、日志、Trace、工具调用和测试用例能力。
- Knowledge/RAG：提供知识库、文档上传、切片、Embedding、检索日志和 Agent 知识库绑定等后端基础能力。
- AgentOps 基础：提供统一 Trace、Span、Event、Token 成本、指标与治理策略的数据模型；采集和治理执行将在后续阶段接入。
- IAM 多端接入：Console 与 Electron Desktop Client 共用统一账号、Tenant、RBAC 和可撤销多端 Session。
- 开发规范：沉淀后端、前端、数据库、接口、模块和 Codex 提示词规范，方便持续协作。

## 架构概览

```mermaid
flowchart LR
  Web["one-agent-web<br/>Vue 3 + Vite"] --> API["one-agent-server<br/>Spring Boot API"]
  Client["one-agent-client<br/>Electron + Vue 3"] --> API
  API --> MySQL[("MySQL 8<br/>业务数据")]
  API --> Redis[("Redis<br/>缓存与运行状态")]
  API --> Harness["AgentScope Harness<br/>Agent 执行适配"]
  Harness --> Models["OpenAI Compatible<br/>LLM Providers"]
  Harness --> Tools["Tool Runtime<br/>HTTP Tool / MCP Placeholder"]
  API --> Storage["Local Storage<br/>Knowledge Documents"]
```

## 技术栈

| 层级 | 技术 |
| --- | --- |
| 后端 | Java 17, Spring Boot 3.3.5, Maven, MyBatis Plus, Spring Validation, Lombok, Knife4j |
| 运行时 | AgentScope Harness, SSE, Tool Runtime Adapter |
| 数据 | MySQL 8, Redis, JSON columns, logical delete |
| 前端 | Vue 3, Vite, TypeScript, Element Plus, Pinia, Vue Router, Axios |
| 桌面端 | Electron, contextBridge, safeStorage, Vue 3 |
| 文档 | Markdown, OpenAPI 3, Knife4j |

## 目录结构

```text
one-agent
├── one-agent-server/          # Spring Boot 后端服务
│   └── src/main/java/com/oneagent
├── one-agent-web/             # Vue 3 + Vite 前端控制台
│   └── src
├── one-agent-client/          # Electron + Vue 3 Agent 使用端
│   ├── electron
│   └── src
├── db/                        # MySQL 初始化脚本与增量迁移
├── docs/                      # 设计文档与开发规范
├── AGENTS.md                  # Codex/Agent 协作约定
├── README.md
└── README.en.md
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- Node.js 18+
- MySQL 8+
- Redis 6+

### 1. 克隆项目

```bash
git clone <repo-url> one-agent
cd one-agent
```

### 2. 初始化数据库

新环境建议按脚本版本顺序执行：

```bash
mysql -uroot -p < db/init.sql
mysql -uroot -p < db/v2_add_model_info_support_vision.sql
mysql -uroot -p < db/v4_prompt_center.sql
mysql -uroot -p < db/v5_tool_center.sql
mysql -uroot -p < db/v5_tool_runtime_migration.sql
mysql -uroot -p < db/v5_tool_permission_version_log_migration.sql
mysql -uroot -p < db/v6_agent_runtime_harness.sql
mysql -uroot -p < db/v7_playground_debug_center.sql
mysql -uroot -p < db/v8_knowledge_rag.sql
mysql -uroot -p < db/v9_mcp_center.sql
mysql -uroot -p < db/v10_workflow.sql
mysql -uroot -p < db/v11_agent_ops.sql
```

默认开发配置位于 [one-agent-server/src/main/resources/application-dev.yml](one-agent-server/src/main/resources/application-dev.yml)，当前数据库连接为：

- Database: `one_agent`
- URL: `jdbc:mysql://localhost:3306/one_agent`
- Username: `root`
- Password: `123456`

如果本机账号、密码或端口不同，请同步修改 `application-dev.yml`。

### 3. 启动 Redis

后端默认连接 `localhost:6379`：

```bash
redis-server
```

### 4. 启动后端

```bash
cd one-agent-server
mvn spring-boot:run
```

后端默认运行在 `http://localhost:8080`。

常用入口：

- 健康检查：`http://localhost:8080/api/health`
- Knife4j：`http://localhost:8080/doc.html`
- OpenAPI JSON：`http://localhost:8080/v3/api-docs`

### 5. 启动前端

```bash
cd one-agent-web
npm install
npm run dev
```

前端默认运行在 `http://localhost:5173`，Vite 会将 `/api` 代理到 `http://localhost:8080`。

### 6. 构建 Desktop Client

```bash
cd one-agent-client
npm install
npm run build
```

Client 默认连接 `http://localhost:8080`。生产环境通过
`ONE_AGENT_API_ORIGIN` 配置主进程认证地址，并通过 `VITE_API_BASE_URL`
配置渲染进程 API 地址。Refresh Token 由 Electron 主进程使用
`safeStorage` 加密保存。

## 使用路径

1. 在模型中心创建模型供应商和模型，例如 DeepSeek、OpenAI Compatible、智谱等兼容 Chat Completions 的服务。
2. 在 Prompt 中心创建模板、版本和变量，并发布可用版本。
3. 在 Agent 中心创建 Agent，绑定模型、Prompt、分类和标签。
4. 在 Tool 中心创建 HTTP Tool，生成或维护 Schema，配置版本、权限和调试参数。
5. 在 Playground 中选择 Agent，创建会话并进行流式调试，查看运行详情、Trace、日志和工具调用。

## 开发命令

### 后端

```bash
cd one-agent-server
mvn test
mvn clean package
mvn spring-boot:run
```

### 前端

```bash
cd one-agent-web
npm install
npm run dev
npm run build
```

## 开发规范

开始开发新模块、接口、数据库表或前端页面前，请先阅读 `docs` 下的规范文档：

- [通用编码规范](docs/coding-standard.md)
- [后端开发规范](docs/backend-standard.md)
- [前端开发规范](docs/frontend-standard.md)
- [数据库设计规范](docs/database-standard.md)
- [接口设计规范](docs/api-standard.md)
- [模块开发规范](docs/module-standard.md)
- [Codex 提示词规范](docs/codex-prompt-standard.md)

相关设计文档：

- [Agent Runtime 数据库设计](docs/agent-runtime-database-design.md)
- [Playground 数据库设计](docs/playground-database-design.md)
- [Knowledge/RAG 数据库设计](docs/knowledge-rag-database-design.md)
- [V11 AgentOps 数据库设计](docs/v11-agentops-database-design.md)
- [Playground 验收报告](docs/playground-acceptance-report.md)
- [HTTP Tool 自测说明](docs/v5-http-tool-self-test.md)

## 当前限制

- 暂未内置登录、RBAC、租户隔离和生产级审计。
- API Key 当前以开发验证为主，生产环境需要接入加密存储、权限隔离和密钥轮换。
- MCP Server 管理已具备配置能力，但 MCP Tool 执行仍未实现。
- Knowledge/RAG 处于基础能力阶段，真实向量索引、生产检索链路和前端知识库页面仍需补齐。
- 当前默认本地文件存储知识库文档，生产环境建议接入对象存储。

## 路线图

- 登录认证、用户体系、RBAC 和租户组织模型。
- MCP Tool 执行器、同步机制和运行时权限策略。
- Knowledge/RAG 检索链路、Embedding 任务、向量库适配和前端页面。
- Workflow 编排、多 Agent 协作和发布中心。
- 可观测性、审计、部署文档、Docker Compose 和 CI。
- 贡献指南、示例数据集和更完整的部署示例。

## 贡献

欢迎提交 Issue、改进文档和贡献代码。建议流程：

1. Fork 仓库并创建特性分支，例如 `feat/agent-runtime-trace`。
2. 阅读 `docs` 下的开发规范，保持后端、前端和数据库风格一致。
3. 提交前运行相关测试或构建命令。
4. 发起 Pull Request，并说明变更范围、影响模块、验证方式和截图。

## 许可证

本项目基于 [MIT License](LICENSE) 开源。