Lumina 是一个企业级 AI Agent 开发框架，基于 AgentScope Java 和 Spring Cloud 构建，提供开箱即用的 Agent 能力、微服务架构和企业级特性。

• AgentScope 集成 - 原生集成 AgentScope 框架，支持 ReAct、工具调用、流式输出
• 工作流编排引擎 - DAG 引擎支持 Agent/条件/循环/并行/数据转换/人工审批 6 种节点 + 5 种协作模板
• Prompt 版本管理 - DB 持久化、版本发布/激活、Agent 执行链路运行时动态生效
• Agent 评估框架 - YAML 数据集 + 4 种评分器（精确/包含/语义相似度/LLM Judge）+ A/B 对比 + CSV 导出
• RAG 知识库 - 文档上传 → 切片 → 向量化 → 检索增强（Qdrant REST + 多 Embedding 提供商）+ 来源可视化
• 微服务架构 - 基于 Spring Cloud Alibaba，支持服务注册、配置管理、负载均衡
• 简化分层架构 - 清晰的 API、Service、Domain、Infrastructure 四层架构
• 多轮对话与记忆 - 会话维度上下文持久化（Redis 热记忆 + DB 冷存储）、历史回放、Token 用量统计
• 异步任务执行 - 提交后立即返回 taskId，后台线程池执行，状态查询与独立列表页管理
• 成本管理 - 模型价格表 + Token 用量计费 + 消费汇总仪表盘 + 趋势图表
• 安全防护 - Prompt 注入检测 + 输出 PII 脱敏（手机号/身份证/银行卡/邮箱）+ 频率限制 + 内容审核
• 全链路可观测 - MDC 结构化日志 + 审计日志 + Micrometer 指标(Prometheus/Grafana) + OpenTelemetry 分布式追踪(Jaeger)
• 工程化 - 统一错误码、Flyway 版本迁移(V1-V14)、网关限流、API 版本策略、工具调用熔断器
• 响应式编程 - 基于 Project Reactor + Context Propagation，支持跨线程租户上下文传递
• 多 LLM 支持 - 支持 DashScope、OpenAI/DeepSeek、Claude、Ollama 等主流模型
• 前端增强 - 动态菜单（后端权限下发）、Agent 调试面板、暗色主题、i18n 中英文切换

lumina/
├── lumina-common/              # 公共模块（统一响应、异常体系、工具类）
├── lumina-framework/           # 框架模块（配置类、全局异常处理、Web 配置）
├── lumina-agent-core/          # Agent 核心模块（执行引擎、配置加载、工具管理）
├── lumina-gateway/             # API 网关模块（统一入口、路由、限流）
└── lumina-modules/             # 业务模块聚合器
    ├── lumina-business-base/   # 基础业务模块（用户、角色、权限、租户管理）
    ├── lumina-business-agent/  # Agent 业务模块（Agent 配置、工具绑定等）
    └── lumina-business-*/      # 其他领域业务模块

lumina-frontend/
├── src/
│   ├── api/                    # API 接口定义
│   ├── components/             # 公共组件
│   ├── composables/            # 组合式函数
│   ├── layouts/                # 布局组件
│   ├── router/                 # 路由配置
│   ├── stores/                 # 状态管理 (Pinia)
│   ├── types/                  # TypeScript 类型定义
│   ├── utils/                  # 工具函数
│   └── views/                  # 页面组件
└── package.json

• JDK 21+ - 下载
• Maven 3.9+ - 下载
• MySQL 8.0+ - 下载
• Redis 7.0+ - 下载
• Nacos 3.1.1+ - 下载

• Node.js 18+ - 下载
• pnpm 8+ (推荐) 或 npm 9+ / yarn 1.22+ - 下载

git clone https://github.com/zwl467135974/lumina.git
cd lumina

启动 MySQL

# 创建数据库
mysql -u root -p
CREATE DATABASE lumina_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

启动 Redis

redis-server

启动 Nacos

# 下载 Nacos
wget https://github.com/alibaba/nacos/releases/download/3.1.1/nacos-server-3.1.1.zip

# 解压并启动
unzip nacos-server-3.1.1.zip
cd nacos/bin
./startup.sh -m standalone

访问 Nacos 控制台：http://localhost:8848/nacos（默认账号密码：nacos/nacos）

# Linux/Mac
export DASHSCOPE_API_KEY=your_api_key_here

# Windows (PowerShell)
$env:DASHSCOPE_API_KEY="your_api_key_here"

启动 base 服务时 Flyway 自动执行建表与初始化数据（V1-V14），无需手动执行 SQL：

cd lumina-modules/lumina-business-base
mvn spring-boot:run
# 首次启动自动创建表 + 初始 admin 数据

迁移脚本位于 lumina-modules/lumina-business-base/src/main/resources/db/migration/。

默认管理员账号：

• 用户名：admin
• 密码：admin123
• 租户：SYSTEM（系统租户，tenant_id=0）
• 角色：SUPER_ADMIN（超级管理员）

启动 Gateway

cd lumina-gateway
mvn spring-boot:run

访问 Gateway：http://localhost:8080

启动 Base 服务（可选，用于用户管理）

cd lumina-modules/lumina-business-base
mvn spring-boot:run

Base 服务访问：http://localhost:8082

# 进入前端目录
cd lumina-frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

访问前端：http://localhost:3000

注意: 前端开发服务器已配置代理，API 请求会自动转发到后端 Gateway (http://localhost:8080)

Lumina 提供完整的多租户用户管理功能，基于 lumina-business-base 模块实现。

核心特性：

• 多租户隔离：每个租户的用户数据严格隔离（ToB 场景）
• RBAC 权限模型：用户 → 角色 → 权限三级权限体系
• 角色管理：角色作为权限集合，可配置给用户使用
• 分级管理：
  • 超级管理员（SUPER_ADMIN）：可管理所有租户，拥有所有权限
  • 租户管理员（TENANT_ADMIN）：只能管理本租户用户和角色
  • 普通用户（TENANT_USER）：基本权限

使用方式：

1. 用户登录：

curl -X POST http://localhost:8080/api/v1/base/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "tenantId": 0
  }'

2. Gateway 传递用户信息： Gateway 自动将用户信息通过 HTTP Header 传递给下游服务：

• X-User-Id: 用户 ID
• X-Username: 用户名
• X-Tenant-Id: 租户 ID
• X-Roles: 角色列表（逗号分隔）
• X-Permissions: 权限列表（逗号分隔）

3. 在业务代码中获取用户信息：

// 从 HttpServletRequest 中获取
String userId = request.getHeader("X-User-Id");
String tenantId = request.getHeader("X-Tenant-Id");
String[] roles = request.getHeader("X-Roles").split(",");

# 在 lumina-modules 下创建模块
mkdir -p lumina-modules/lumina-business-order/src/main/java/io/lumina/order

创建 pom.xml：

<parent>
    <groupId>io.lumina</groupId>
    <artifactId>lumina</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../../pom.xml</relativePath>
</parent>

<artifactId>lumina-business-order</artifactId>

<dependencies>
    <dependency>
        <groupId>io.lumina</groupId>
        <artifactId>lumina-common</artifactId>
    </dependency>
    <dependency>
        <groupId>io.lumina</groupId>
        <artifactId>lumina-framework</artifactId>
    </dependency>
</dependencies>

# 在 lumina-modules 下创建模块
mkdir -p lumina-modules/lumina-agent-customer/src/main/java/io/lumina/agent/customer

创建 pom.xml：

<parent>
    <groupId>io.lumina</groupId>
    <artifactId>lumina</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../../pom.xml</relativePath>
</parent>

<artifactId>lumina-agent-customer</artifactId>

<dependencies>
    <dependency>
        <groupId>io.lumina</groupId>
        <artifactId>lumina-common</artifactId>
    </dependency>
    <dependency>
        <groupId>io.lumina</groupId>
        <artifactId>lumina-agent-core</artifactId>
    </dependency>
    <dependency>
        <groupId>io.lumina</groupId>
        <artifactId>lumina-framework</artifactId>
    </dependency>
</dependencies>

Lumina 采用简化分层架构：

lumina-modules/lumina-{domain}/
└── src/main/java/io/lumina/{domain}/
    ├── api/                    # 接口层
    │   ├── controller/         # REST 控制器
    │   └── dto/                # 数据传输对象
    │
    ├── service/                # 业务服务层（核心）
    │   ├── {业务}Service.java
    │   └── impl/
    │
    ├── domain/                 # 领域模型层
    │   ├── model/              # 领域实体
    │   └── enums/              # 领域枚举
    │
    └── infrastructure/         # 基础设施层
        ├── mapper/             # MyBatis Mapper
        └── entity/             # 数据库实体 (DO)

详细规范参考：Lumina开发规范与编码标准.md

@Autowired
private AgentExecutionEngine agentExecutionEngine;

public String executeAgent(String task) {
    AgentConfig config = new AgentConfig();
    config.setAgentName("customer-service");
    config.setAgentType("ReAct");

    AgentConfig.LLMConfig llmConfig = new AgentConfig.LLMConfig();
    llmConfig.setModelType("dashscope");
    llmConfig.setModelName("qwen-max");
    config.setLlmConfig(llmConfig);

    ExecuteResult result = agentExecutionEngine.executeSync("customer-service", task, config);
    return result.getResult();
}

• 项目 README - 项目介绍和快速开始
• 快速开始 - 5 分钟跑起来
• 部署指南 - Docker Compose 一键部署 + 本地开发 + K8s 参考
• 配置说明 - JWT、白名单、租户隔离等完整配置
• 测试指南 - 测试验证步骤和场景

• 开发规范与编码标准 - 开发规范
• Agent 开发指南 - Agent 开发、执行、安全管线
• 工作流设计指南 - 多 Agent 编排
• 业务模块开发指南 - 业务模块开发
• 前端开发指南 - 前端开发指南
• 工具开发指南 - Agent 工具开发
• 配置管理规范 - 配置管理规范
• 数据库配置指南 - 数据库配置

• Agent 执行引擎设计 - Agent 核心设计
• 项目结构设计 - 项目结构说明
• Lumina 模块设计 - 模块设计文档
• Lumina 技术选型方案 - 技术选型说明
• 前端架构设计 - 前端架构设计
• 架构模式分析与建议 - 架构模式分析

• Quick Start | Architecture | Agent Dev | Workflow

AgentScope Java 使用 Java 17 编译，但 Lumina 使用 Java 21。由于 Java 21 向下兼容，可以直接使用。

在 ~/.m2/settings.xml 中配置阿里云镜像：

<mirrors>
    <mirror>
        <id>aliyun-maven</id>
        <mirrorOf>*</mirrorOf>
        <name>Aliyun Maven</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

检查 Nacos 是否启动，访问 http://localhost:8848/nacos 确认。

如果使用 pnpm 安装依赖失败，可以尝试：

# 清除缓存
pnpm store prune

# 重新安装
pnpm install

或者使用 npm：

npm install

前端开发服务器已配置代理，API 请求会自动转发到后端。如需修改代理地址，编辑 lumina-frontend/vite.config.ts 中的 proxy 配置。

开发环境下，前端已配置代理，不会出现跨域问题。生产环境需要在 Gateway 中配置 CORS。

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

本项目采用 Apache License 2.0 许可证。详见 LICENSE 文件。

• 项目主页：https://github.com/zwl467135974/lumina
• 问题反馈：Issues

Agent 编排引擎（P1）

• ✅ DAG 工作流引擎：Agent / Condition / Loop / Parallel / Transform / Human 6 种节点类型
• ✅ 5 种协作模式 YAML 模板：Supervisor-Worker / Debate / Pipeline / Router / Human-in-the-Loop
• ✅ 工作流持久化：定义表 + 实例表 + 执行日志表（Flyway V8）
• ✅ 管理 API：创建/发布/执行/查询 + 模板列表
• ✅ 前端工作流管理页

Prompt 管理（V9）

• ✅ DB 持久化 + 版本管理 + 发布/激活
• ✅ Agent 执行链路运行时接入：优先读 DB 激活 Prompt（租户优先 + 全局回退），未命中回退 classpath 内置
• ✅ 前端管理页 + Agent 列表/表单/详情页运行时 Prompt 可见性

流式增强 + 调试（P2）

• ✅ 多模态流式：图片 + 文本混合输入，LLM 流式回复
• ✅ Agent 调试面板：工具调用记录 + 推理过程展示

生产可用性（P3）

• ✅ 异步任务执行：提交即返回 taskId，后台线程池执行，状态查询 + 独立任务列表页（Flyway V10）
• ✅ 成本管理：模型价格表 + Token 计费 + 消费汇总仪表盘 + 趋势图表（Flyway V11）
• ✅ 安全防护：Prompt 注入检测（11 种模式）+ 输出 PII 脱敏 + 频率限制（Redis 滑动窗口）+ 内容审核

Agent 评估框架（E1）

• ✅ YAML 数据集管理 + 文件上传导入
• ✅ 4 种评分器：精确匹配 / 关键词包含 / 语义相似度（Embedding 余弦） / LLM Judge（1-5 分制）
• ✅ 评估报告：分类统计 + ECharts 柱状图 + 历史趋势折线图
• ✅ 异步评估（大数据集）+ A/B 两次评估对比 + CSV 导出（Flyway V13-V14）

部署 + 文档（P4-P5）

• ✅ Helm Chart 全量模板（Gateway / Business-Base / Agent-Service / Frontend / Ingress + HPA）
• ✅ 英文 README（README_EN.md）
• ✅ Apache 2.0 License + CHANGELOG.md

测试

• ✅ 后端 355 单元测试（全 8 模块 mvn verify 通过）
• ✅ 前端 80 测试（66 工具/Store + 14 组件）
• ✅ CI/CD 双流水线（GitHub Actions：后端 mvn verify + 前端 pnpm build + pnpm test）

继承 v1.3.0 核心能力

• ✅ 响应式上下文传递 + 敏感配置环境变量化
• ✅ 统一错误码 + Flyway V1-V14 + 网关限流 + API 版本策略
• ✅ 流式输出（SSE）+ 多轮对话/记忆管理 + Token 用量统计
• ✅ 多模型适配（DashScope/OpenAI/DeepSeek/Claude/Ollama + 硅基流动/智谱/Kimi/豆包/Minimax）
• ✅ RAG 知识库（多 Embedding + Qdrant 向量存储 + 文档管线）
• ✅ 工具调用可观测（记录/统计/熔断器）+ 审计日志（@Audit AOP + 异步）
• ✅ 可观测性：MDC 结构化日志 + Micrometer 指标 + OpenTelemetry 全链路追踪
• ✅ 前端：动态菜单 + Agent 对话（SSE 流式）+ 暗色主题 + i18n 国际化

相关文档：

• v2.0.0 路线图 - 完整需求文档与完成状态
• Prompt 运行时规则 - Prompt 生效规则说明
• 部署指南 - Docker Compose 一键部署 + 本地开发 + K8s 参考

Lumina Framework - 让 AI Agent 开发更简单 🚀