# agent-platfrom

**Repository Path**: DLLLL/agent-platfrom

## Basic Information

- **Project Name**: agent-platfrom
- **Description**: 开源的ai平台，使用Java agentscope2.0开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 灵枢 Agent Platform

> 开源企业级智能体平台：覆盖智能体开发、运行、集成与治理的全生命周期，开箱即用的前后端完整实现。

**Agent Platform** 是一个面向企业和中小团队的智能体平台，支持智能体的创建、配置、发布、调试与对话，内置多模型接入、工具（Tool）、技能（Skill）、MCP 服务集成、运行时权限控制、沙箱隔离执行与文件产物管理等能力。后端基于 Spring Boot 3 + DDD 四层架构，前端基于 Vue 3 + Element Plus，另附产品需求文档与高保真静态原型作为演进参考。

## 核心特性

### 智能体全生命周期

- **智能体管理**：草稿创建、版本管理、主/备用模型配置、生成参数调优、一键发布与调试
- **实时对话**：NDJSON 流式事件协议，打字机式正文渲染、思考面板、工具调用轨迹、会话历史回显
- **多模态消息**：支持文本、图片、视频、音频与数据文件内容块
- **会话状态存储**：可选 `IN_MEMORY`、`JSON_FILE`、`REDIS`、`MONGO` 四种策略，支持跨存储迁移续聊

### 能力资产中心

- **模型管理**：OpenAI、Ollama、DashScope、Gemini、Anthropic 多供应商接入，凭证 AES 加密存储，连通性测试，主备模型与重试超时配置
- **Tool 管理**：平台自定义工具注册与发布，按 `executorKey` 路由到受控执行适配器，运行时权限策略约束
- **Skill 管理**：ZIP 包上传与多仓库来源（Git 等），依赖声明，运行时按版本白名单绑定并同步到工作区
- **MCP 服务集成**：HTTP/SSE 真实连通性测试，Tool/Resource/Prompt 能力发现与同步；运行时由子智能体基于 **pgvector + 本地 BGE-small-zh-v1.5 Embedding 模型**做三路混合检索，仅将 Top-K 能力交给大模型，规避工具数量限制

### 安全与运行隔离

- **RBAC**：用户、角色、菜单权限管理，JWT + Redis 会话，支持即时会话撤销与服务端方法级鉴权，前端路由/侧栏/按钮级权限过滤
- **Agent 运行时权限**：资源授权、权限策略与规则、运行时评估、能力快照与工具决策审计
- **三种工作区模式**：`LOCAL` 本机目录、`REMOTE` 基于 Redis 的共享文件、`SANDBOX` Docker 沙箱隔离执行（Node.js 20 + Python 3 双运行时），按用户隔离
- **文件产物管理**：Agent 输出文件自动增量归档，支持 Local/MinIO/Amazon S3/阿里云 OSS 多存储后端（X File Storage），下载经用户与 Agent 归属校验

### 通知系统

- 智能体可通过内置通知工具发送实时/延时通知；Redis Stream 延时派发、消费组重试与死信队列，跨节点 Pub/Sub 广播，前端 Fetch-SSE 实时推送与收件箱管理

## 界面预览

以下截图来自当前运行的 `agent-platform-web` 管理端（本地开发环境），展示真实 Vue 页面中的工作台、智能体管理和调试流程。截图使用项目当前开发配置加载的数据，便于快速了解实际交互；产品原型仍可通过 [`prd/index.html`](prd/index.html) 单独体验。

### 工作台

集中查看运行量、成功率、响应时延、预算用量和待处理事项，并快速进入常用智能体。

![灵枢 Agent Platform 工作台](docs/screenshots/dashboard.png)

### 智能体列表

按发布状态筛选智能体，查看今日运行、成功率、版本和最近更新等关键信息。

![灵枢 Agent Platform 智能体列表](docs/screenshots/agents.png)

### 工作流编排与调试

通过节点编排智能体流程，在右侧配置模型、提示词和输入变量，并在同一页面调试草稿版本。

![Agent Platform 智能体配置](docs/screenshots/agent-builder.png)

> 想直接体验交互效果，可先按[快速开始](#快速开始)启动前后端，再访问 `http://127.0.0.1:5173`；无需后端时也可打开 [`prd/index.html`](prd/index.html) 查看静态原型。

## 特色设计

### MCP 大规模工具接入：检索式调用，破解工具爆炸与注意力稀释

传统做法把每个 MCP 能力注册为一个独立 function 交给大模型：工具一多，提示词膨胀、模型注意力被稀释、调用准确率下降，部分模型（如 DeepSeek）还存在工具数量与函数名限制。本平台改为 **“先检索、后调用”** 的通用架构，MCP 服务接入的能力数量几乎不受限：

- **只注册两个通用工具**：运行时仅注册 `mcp_capability_search`（能力检索）与 `mcp_invoke`（统一调用），不再按能力逐个注册函数，从机制上绕开模型工具数量限制
- **子智能体委派**：主 Agent 只保留 `agent_spawn`，能力检索与调用由 `mcp-executor` 子 Agent 完成，检索噪音不进入主对话上下文
- **三路混合检索**：子 Agent 对授权 MCP 服务的全量能力执行 pgvector 向量余弦扫描、全文关键词、字段匹配三路混合检索，仅将 Top-K 候选 Schema 交给模型，把注意力集中在最相关的能力上
- **本地 Embedding，数据不出域**：语义向量由 Java 进程内的 BGE-small-zh-v1.5 ONNX 模型生成（512 维），不调用任何远程 Embedding API，能力描述等语义数据不离开部署环境
- **连接复用**：MCP 客户端按服务缓存会话，首次调用才握手初始化且并发共享，避免每次工具调用重复建连

### 流式事件工程化

- **三层事件转换链路**：运行时原始事件 → 领域事件值对象 → 应用层 DTO，事件类型由枚举唯一约束，前后端零魔法值
- **replyId 统一对齐**：将多轮推理的轮次级消息 ID 对齐为 Agent 级标识，前端凭单一 replyId 即可关联正文、思考面板与工具轨迹
- **生产级保活**：NDJSON 响应携带 `X-Accel-Buffering: no`，并以 15s 心跳事件防止代理与网关断流

### 会话历史投影

历史回显按用户轮次投影：每轮只展示用户消息与最终回答，工具链中间消息不形成空白气泡；多模态消息自动生成文件摘要；切换状态存储策略后首次续聊自动迁移旧会话，上下文不丢失。

### 受控工具执行与安全边界

- 自定义 Tool 按 `executorKey` 路由到部署时已审核的执行适配器，**数据库中的类名永远不会被反射执行**，缺少适配器时运行构建立即失败
- 模型密钥、MCP 凭证 AES 加密存储；OAuth 等无令牌刷新能力的凭证类型在领域层明确拒绝
- 平台状态消息以结构化标记注入模型上下文（运行环境、工具计数、Todo 等），帮助模型感知运行时状态，且工具结果与凭证不进入状态

## 设计理念

- **COLA 5 Light 单体分层**：不引入多模块与微服务治理，通过严格的包边界实现 DDD 四层职责——`adapter` 只做协议适配，`application` 编排用例与事务，`domain` 承载业务规则且不依赖任何基础设施技术，`infrastructure` 实现领域端口
- **轻量 CQRS**：写操作由 Command Service 编排，查询由 Query Service 处理，职责清晰、易于演进
- **约定优于配置**：统一响应与异常体系、枚举驱动（禁止魔法值）、MapStruct 对象转换、Flyway 数据库版本迁移、参数化日志与 TraceId
- **文档即入口**：仓库维护[项目知识图谱](docs/project-knowledge-graph.md)，记录工程结构、业务域、核心链路与数据地图，可作为二次开发的导航
- **可演进的边界**：领域端口 + 适配器模式预留扩展点（Skill 仓库来源、工具执行适配器、状态存储、产物存储），业务扩展不侵入核心

## 技术栈

| 端 | 技术 | 用途 |
|---|---|---|
| 后端 | Java 17、Spring Boot 3.5 | 应用框架 |
| 后端 | Spring Security、Nimbus JOSE + JWT | 认证授权 |
| 后端 | PostgreSQL 17、MyBatis-Plus、Flyway、pgvector | 关系数据与向量检索 |
| 后端 | MongoDB、Spring Data MongoDB | 会话状态等文档数据 |
| 后端 | Redis | 登录会话、权限缓存、通知队列、可选状态存储 |
| 后端 | AgentScope Harness | 智能体运行时（ReAct、工具、技能、沙箱） |
| 后端 | DJL + ONNX Runtime | 本地中文 Embedding（BGE-small-zh-v1.5） |
| 后端 | X File Storage 2.3.0 | Local/MinIO/S3/OSS 统一产物存储 |
| 前端 | Vue 3、TypeScript、Vite | 管理端应用 |
| 前端 | Element Plus、Pinia、Vue Router、Axios | UI 组件、状态与路由 |
| 前端 | markdown-it、highlight.js、ECharts | 对话渲染与图表 |
| 部署 | Docker Compose | 基础环境与应用容器模板 |

## 仓库结构

```
.
├── agent-platform-backend/     # 后端服务（Java 17 / Spring Boot 3）
│   ├── src/main/java/io/github/agent/platform/
│   │   ├── adapter/            # 适配层：Web 控制器、请求/响应处理
│   │   ├── application/        # 应用层：用例编排、Command / Query
│   │   ├── domain/             # 领域层：实体、值对象、规则与端口
│   │   ├── infrastructure/     # 基础设施：持久化、网关、外部服务
│   │   └── common/             # 公共模块：统一响应、异常、工具
│   └── docs/                   # 环境模板、部署配置、沙箱镜像与专项文档
├── agent-platform-web/         # 前端管理端（Vue 3 / TypeScript / Vite）
│   └── src/
│       ├── api/                # 领域 API 模块与类型契约
│       ├── router/             # 路由与权限守卫
│       ├── stores/             # Pinia 状态
│       └── views/              # 页面（智能体、资产中心、系统管理、聊天窗口等）
├── prd/                        # 产品需求文档与高保真静态原型（浏览器直接打开）
├── docs/                       # 仓库级文档（知识图谱、设计方案）
│   └── screenshots/             # README 使用的界面预览截图
└── scripts/                    # 辅助脚本（本地 Embedding 模型下载等）
```

### 请求链路

```text
Web 页面 → Axios / Fetch(NDJSON) → Vite 代理 → Spring Boot
    adapter(Controller) → application(Command/Query) → domain
        ↑ infrastructure 实现 domain 定义的 Repository / Gateway 端口
```

## 快速开始

### 环境要求

| 工具 | 版本 | 说明 |
|---|---|---|
| JDK | 17+ | 后端编译运行 |
| Maven | 3.9+ | 后端构建（未提供 Wrapper） |
| Node.js | 20+ | 前端开发与构建 |
| Docker Compose | 近期版本 | 一键启动 PostgreSQL 17 / MongoDB 8.0 / Redis 7.4 |

### 1. 启动基础环境

```bash
cd agent-platform-backend/docs/environment
cp .env.example .env
# 将 .env 中的 change-this-* 占位符替换为本地使用的密码
docker compose -f docker-compose-environment.yml up -d
```

首次创建 PostgreSQL 数据卷时会自动执行 `postgresql/init.sql` 创建表结构（Flyway 管理后续版本迁移）。

### 2. 启动后端

在与 `.env` 一致的环境变量下使用 `dev` profile 启动：

```bash
cd agent-platform-backend
export DB_HOST=localhost DB_PORT=5432 DB_NAME=ddd_rbac_scaffold_lite
export DB_USERNAME=ddd_rbac_user DB_PASSWORD='<同 POSTGRES_PASSWORD>'
export MONGO_HOST=localhost MONGO_PORT=27017 MONGO_DATABASE=agent_platform
export MONGO_USERNAME=agent_platform_user MONGO_PASSWORD='<同 MONGO_PASSWORD>' MONGO_AUTH_DATABASE=admin
export REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD='<同 REDIS_PASSWORD>'
export JWT_SECRET='<一段长随机字符串>'

mvn clean package -DskipTests
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

也可在 IDE 中运行 `io.github.agent.platform.Application`（Active Profiles 设为 `dev`）。默认端口 `8080`。

> **首次登录**：初始化脚本只创建表结构，不含默认管理员。请自行创建用户、角色、菜单及关联数据，密码必须使用 BCrypt 编码；或通过接口/SQL 初始化后再登录。

### 3. 启动前端

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

访问 `http://127.0.0.1:5173`，开发代理已配置转发 `/api` 到 `http://127.0.0.1:8080`。

### 4.（可选）下载本地 Embedding 模型

启用 MCP 能力语义检索需要本地 Embedding 模型（约 91MB，不入 git）：

```bash
bash scripts/download-mcp-embedding-model.sh
```

### 5.（可选）沙箱模式

若智能体版本使用 `SANDBOX` 工作区模式，需预装 Docker 并构建沙箱镜像，说明见 [`agent-platform-backend/docs/sandbox`](agent-platform-backend/docs/sandbox)。

### Docker 部署应用

```bash
cd agent-platform-backend
mvn clean package -DskipTests
cp target/agent-platform-backend.jar docs/app/app.jar
cd docs/app
docker compose -f docker-compose-app.yml up --build -d
```

部署模板默认使用 `dev` profile，生产环境请通过 Compose 环境变量或密钥管理服务注入真实配置，切勿复用开发默认凭证。产物存储可通过 `ARTIFACT_STORAGE_PLATFORM` 切换 Local/MinIO/Amazon S3/阿里云 OSS。

## API 文档

启动后端后访问：

- Swagger UI：`http://localhost:8080/swagger-ui.html`
- OpenAPI JSON：`http://localhost:8080/v3/api-docs`

除登录与文档地址外，`/api/v1/**` 接口均需 Bearer Token。

## 功能状态

| 能力域 | 状态 |
|---|---|
| RBAC 与认证（用户/角色/菜单、JWT、会话撤销） | ✅ 完整闭环 |
| 智能体管理（版本、发布、调试） | ✅ 核心闭环（知识库、模板规划中） |
| 实时对话与会话历史（NDJSON 流、四种状态存储） | ✅ 基础闭环 |
| 模型管理（多供应商、凭证加密、连通性测试） | ✅ 核心闭环 |
| Tool / Skill / MCP 资产与运行时装配 | ✅ 核心闭环 |
| 运行时权限策略与审计 | ✅ 部分（审批流规划中） |
| 通知中心（延时派发、死信、实时推送） | ✅ 基础闭环 |
| 工作区隔离（LOCAL / REMOTE / SANDBOX）与文件产物 | ✅ 完整闭环 |
| 工作流编排、知识中心/RAG、评测与灰度发布 | 🚧 见 PRD 与静态原型 |

完整能力覆盖度与演进规划见 [PRD](prd/PRD.md) 与[项目知识图谱](docs/project-knowledge-graph.md)。静态原型可直接用浏览器打开 `prd/index.html` 体验。

## 文档索引

| 文档 | 说明 |
|---|---|
| [项目知识图谱](docs/project-knowledge-graph.md) | 工程结构、业务域、核心链路与数据地图 |
| [Quick Start](agent-platform-backend/docs/quick-start.md) | 后端环境配置、启动与验证 |
| [Project Structure](agent-platform-backend/docs/project-structure.md) | DDD 四层职责与依赖方向 |
| [MCP 本地 Embedding](agent-platform-backend/docs/mcp-local-embedding.md) | BGE-small-zh-v1.5 本地模型与 pgvector 配置 |
| [腾讯文档 MCP 接入](docs/tencent-docs-mcp.md) | 一键预置接入指南 |
| [通知系统设计](docs/notification-design.md) | Redis Stream 延时派发与投递语义 |
| [能力组合设计](docs/capability-composition-design.md) | Tool/Skill/MCP 组合与治理方案 |
| [沙箱镜像说明](agent-platform-backend/docs/sandbox) | SANDBOX 模式镜像定义与构建 |
| [PRD](prd/PRD.md) | 产品需求与原型说明 |

## 参与贡献

欢迎提交 Issue 与 Pull Request：

1. Fork 本仓库并创建特性分支；
2. 遵守仓库 [AGENTS.md](AGENTS.md) 中的开发规范（命名、中文注释、分层约束、禁止魔法值）；
3. 提交前至少保证项目可编译，并运行与改动相关的测试（后端 `mvn test`，前端 `npm run type-check`）；
4. 涉及目录结构、接口或核心链路变化时，请同步更新[项目知识图谱](docs/project-knowledge-graph.md)。

## 安全

如发现安全漏洞，请勿公开 Issue，按照 [SECURITY.md](agent-platform-backend/SECURITY.md) 私下报告。

## 许可证

本项目采用 [Apache License 2.0](LICENSE) 开源。