# loser-agent

**Repository Path**: fly_elephant_sa/loser-agent

## Basic Information

- **Project Name**: loser-agent
- **Description**: 基于 AgentScope 2.0.1 的多 Agent 编排平台，提供 Agent 全生命周期管理、LLM 模型配置、灰度发布、技能/MCP 插件化、子 Agent 协同等能力。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Loser Agent

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)

基于 [AgentScope](https://github.com/modelscope/agentscope) 2.0.1 的多 Agent 编排平台，提供 Agent 全生命周期管理、LLM 模型配置、灰度发布、技能/MCP 插件化、HITL 人机协同、子 Agent 协同等能力。

## 演示视频

[![Loser Agent 平台入门演示](docs/assets/tutorial-cover.jpg)](docs/assets/loser-agent-tutorial.mp4)

> 约 5 分钟语音讲解走查：对话工作台 · 管理后台 · 模型 / Skill / MCP 市场。点击封面跳转到仓库内视频文件页即可在线播放（Gitee / GitHub 均支持）。

## 架构概览

```
loser-agent
├── loser-common/                    # 通用基础库
│   ├── loser-common-core            # 核心工具类、通用异常
│   ├── loser-common-mybatis         # MyBatis-Plus 封装
│   ├── loser-common-swagger         # Knife4j/OpenAPI 配置
│   └── loser-common-util            # 工具集
├── loser-modules-repository/        # 数据访问层
│   └── loser-agent-repository       # 实体、Mapper、DO
├── loser-modules/                   # 业务模块
│   └── loser-agent-app              # 主应用（Spring Boot 启动入口）
└── loser-agent-web/                 # Vue 3 前端（独立 README）
```

## 技术栈

| 类别       | 选型                                     |
|------------|------------------------------------------|
| 框架       | Spring Boot 4.1 + JDK 21（编译目标 17）  |
| Agent 引擎 | AgentScope 2.0.1 (HarnessAgent)         |
| ORM        | MyBatis-Plus 3.5.16 (Spring Boot 4 starter) |
| 数据库     | MySQL 8.0（单文件 SQL 初始化）          |
| 向量库     | Milvus 2.4.11（RAG 知识库）              |
| 离线 TTS   | sherpa-onnx 1.13.8（纯 Java JNI，数字人语音） |
| API 文档   | Knife4j 4.5 / OpenAPI 3 (Jakarta)       |
| 对象映射   | MapStruct-Plus 1.5.2                    |
| 监控       | Micrometer → Prometheus (/actuator/prometheus) |
| 加密       | AES-256-GCM (LLM API Key KMS)           |
| 构建       | Maven (flatten-maven-plugin 多模块版本管理) |

## 核心功能

### Agent 管理
- Agent 配置 CRUD（草稿 / 已发布状态机）
- 发布与真实回滚（PublishSnapshot 快照 + 状态追溯）
- 子 Agent CRUD + 会话委托（Delegation）
- 子 Agent 工作区同步广播

### LLM 模型管理
- 模型实体 + Agent 绑定（多模型绑定同一 Agent）
- LlmConfigRegistry 注册表 + `ModelKey(binding, model, apiKey)` 路由
- API Key AES-256-GCM 加密存储（KMS），数据库仅存 cipher
- 熔断器（CircuitState：CLOSED / OPEN / HALF_OPEN）
- 本地 Provider（Ollama 等）免 API Key 创建
- 模型指标（LlmMetrics：延迟、成功率、Token 统计）

### 灰度发布
- 按 Agent 维度灰度配置（权重 / 百分比策略）
- 请求环境解析 + 灰度路由（GrayRoutingService）
- 灰度指标采集（GrayMetrics）
- 前端灰度规则管理 UI

### 技能系统（Skill）
- 3 源技能加载：classpath / filesystem / MySQL
- 技能文件上传（staging → baseDir 两阶段提交 + 启动崩溃恢复）
- Frontmatter 校验 + 跨文件系统数据安全
- Agent-Skill 绑定管理（运行时 SkillBindingResolver + SkillFilter 白名单）
- SkillRequest.parameters 持久化

### MCP 配置域
- MCP Server 定义 CRUD
- Agent-MCP Binding 绑定管理
- 前端 MCP Market 管理 UI
- MCP ssoToken 最小透传 + fail-closed 身份校验（IdentityMcpToolWrapper）

### HITL 人机协同
- 5 级规则 scope：GLOBAL / AGENT / TOOL_GROUP / TOOL / MCP
- TOOL_GROUP scope 从 Toolkit.getToolGroup 运行时展开
- PermissionMode 5 档切换（DEFAULT / EXPLORE / ACCEPT_EDITS / BYPASS / DONT_ASK）
- 前端 HITL 确认弹窗 + ConfirmResult 恢复
- 复用 AgentScope 原生 PermissionContextState + PermissionEngine

### 会话与对话
- AGUI 协议 SSE 流式对话 + 实时渲染
- 会话状态持久化（DbAgentStateStore）
- 上下文压缩归档（Block archived + 压缩任务）
- 聊天历史后端查询（localStorage → DB 迁移）
- 身份头注入（X-Emp-Id / X-SSO-Token / X-Thread-Id）
- Plan Mode（AGUI Plan/Task 事件 + 前端执行计划抽屉）
- 多模态聊天（图片/文本附件上传落盘，10MB 上限）
- 会话历史后端唯一事实源（替代前端 localStorage）

### 知识库（RAG）
- 自研轻量向量层 + Milvus 持久化，无 langchain4j / Spring AI 依赖
- 文档上传 / 切片 / DashScope 嵌入（EMBEDDING 模型类型独立管理）
- Agent-知识库绑定 + KnowledgeSearchTool 按 Agent 动态实例化

### 工具注册表
- Spring Bean 运行时自动扫描注册（loser.tool-registry 开关）
- 工具 CRUD + Agent 绑定 + 角色级权限
- 远程子 Agent（SubagentDeclaration url 声明式接入）

### 数据分析域
- 数据源管理 + SQL 只读工具（SqlSafetyGuard 白名单防护）
- 定时任务（Spring CronExpression 调度 + CAS 防重 + 运行日志）
- 通知渠道（Webhook / 飞书 / 钉钉，secret AES-256-GCM 加密，EMAIL 预留）
- 预置 data_analyst 数据分析师 Agent

### 可观测与审计
- 调用审计日志（ac_audit_call_log）+ Reactor Context 链路追踪
- 资源可见性 PUBLIC/PRIVATE（Agent / 工具 / MCP / 技能级）

### 数字人（离线 TTS）
- sherpa-onnx 1.13.8 纯 Java JNI 进程内合成，无云端/Python 依赖（`POST /tts/synthesize` 返回 WAV base64）
- 模型可配置（默认 vits-piper-zh_CN-xiao_ya-medium 63MB 中文女声，完全离线；melo/kokoro 中英混读模型切换零代码）
- 懒加载引擎（首次合成约 1s），dll 绝对路径加载 + 相对路径自动回退模块目录
- TtsService 内存 LRU 缓存（32 条 / TTL 10min）+ synchronized 串行合成
- emoji 剔除（防 JNI modified-UTF8 警告）+ Markdown 语法清洗（防 OOV 朗读杂音）
- 前端 Live2D shizuku 形象 + RMS 口型同步（详见 loser-agent-web README）

### 安全
- RBAC 权限控制（用户/角色/菜单）
- AdminAuthFilter 泛化鉴权
- HITL 规则防篡改（agent 级优先）
- 会话归属 + 租户隔离
- MCP ssoToken 最小透传
- Prod 关闭 Swagger

### 评测系统
- Benchmark CRUD + 评测执行
- 评分维度自定义
- cost_tokens 真实采集（streamEvents 含工具轮次）

### 集群与运维
- AgentConfigBroadcaster 事件广播（in-process MVP，预留 MetaQ 扩展）
- 12+ 项 Micrometer 指标 → Prometheus
- 运维 Runbook（发布回滚 / 会话清理 / 监控告警）
- 配置审计日志（ac_agent_config_audit_log）

## 数据库初始化

数据库 schema 已定型，**不使用版本化迁移工具（Flyway 等）**，采用单文件初始化：

- 文件：`loser-modules/loser-agent-app/src/main/resources/sql/init.sql`（45 张业务表全量 DDL + 种子数据：内置模型/Agent/工具注册表/RBAC/技能 + `admin / admin123` 账号）
- **仅限全新安装**：脚本含 `DROP TABLE IF EXISTS`，会清空同名表
- Docker Compose 部署：mysql 容器空数据卷首次启动时自动执行，无需手动操作
- 手动部署/开发环境：`mysql -u root -p loser_agent < loser-modules/loser-agent-app/src/main/resources/sql/init.sql`

后续表结构变更请在库上自行 ALTER，并同步维护 `init.sql`。

## 快速开始

### Docker 一键部署（推荐）

```bash
cp .env.example .env   # 填入 LOSER_AGENT_API_KEY_MASTER_KEY（openssl rand -base64 32）
docker compose up -d --build
```

完整说明见 [DEPLOY.md](DEPLOY.md)（含 Milvus RAG 组件、TTS 模型、数据持久化与常见问题）。

### 环境要求
- JDK 21（勿用 JDK 24，Lombok 不兼容；pom 编译目标 17）
- Maven 3.9+
- MySQL 8.0+
- Milvus 2.4+（启用知识库功能时）

### 配置
修改 `loser-modules/loser-agent-app/src/main/resources/application.yaml` 中的数据库连接信息。

### 初始化数据库
```bash
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS loser_agent DEFAULT CHARSET utf8mb4"
mysql -u root -p loser_agent < loser-modules/loser-agent-app/src/main/resources/sql/init.sql
```

### 启动
```bash
mvn -pl loser-modules/loser-agent-app spring-boot:run
```

### 验证
```bash
# 健康检查
curl http://localhost:8080/actuator/health

# Prometheus 指标
curl http://localhost:8080/actuator/prometheus

# API 文档
open http://localhost:8080/doc.html
```

## API 端点

按域分组的 Controller（完整 REST 路径以 Knife4j 文档 `/doc.html` 为准）：

| 域 | Controller |
|----|-----------|
| Agent 管理 | AgentConfigController / PublishController / AcAgentGrayConfigController / AgentPlanController |
| 对话与语音 | AguiChatController（SSE）/ ChatHistoryController / ChatUploadController / TtsController |
| 模型与绑定 | ModelEntityController / AgentModelBindingController / AgentSkillBindingController / AgentToolBindingController / AgentMcpBindingController / AgentKnowledgeBindingController |
| 技能 / MCP | SkillController / SkillUploadController / McpController |
| 子 Agent | AcSubagentController |
| HITL | HitlRuleController |
| 知识库 | KnowledgeBaseController / KnowledgeDocumentController |
| 数据源 | DataSourceController |
| 调度 / 通知 | ScheduledTaskController / NotifyChannelController |
| 可观测 | EvalController / AuditController |
| 工具 | ToolInfoController |
| 安全 | AuthController / SysUserController / SysRoleController / RolePermissionRuleController |

## 测试

```bash
# 全量测试
mvn test

# 仅单元测试
mvn test -pl loser-modules/loser-agent-app -Dtest="*Test"

# 仅集成测试
mvn test -pl loser-modules/loser-agent-app -Dtest="*IT"
```

> 注意：`-am test` 受 loser-common-util surefire 历史配置影响会失败；刷新仓库 JAR 用 `mvn -pl loser-modules/loser-agent-app -am install -DskipTests`。

## 路线图

- [x] RBAC 权限控制
- [x] HITL 前端确认交互
- [x] Thinking / ToolCall 事件渲染
- [x] SSE 流式渲染
- [x] RAG 知识库
- [x] 工具注册表 + 远程子 Agent
- [x] 数据源 + 定时任务 + 通知推送
- [x] 多模态聊天
- [x] 数字人（离线 TTS + Live2D 口型同步）
- [ ] MetaQ / RocketMQ 集群广播替换 in-process bus
- [ ] Master Key 轮换（KMS 架构级）
- [ ] MCP stdio 协议支持
- [ ] 跨服务分布式追踪（W3C header 透传）
- [ ] EMAIL 通知渠道
- [ ] 移动端适配

## 许可证

本项目采用**双许可**模式：

- **开源版**：[GNU Affero General Public License v3.0](LICENSE) —— 自用、学习、内部系统免费；若以本软件对外提供网络服务，须按 AGPL-3.0 开源修改代码
- **商业版**：[商业授权条款](COMMERCIAL-LICENSE.md) —— 付费购买后免除 AGPL 义务，允许闭源商用与客户交付，适合不想开源自身业务改造的企业

> 数字人模块依赖的 Live2D 运行时与官方样例模型为 Live2D Inc. 受限许可资产，**不随本仓库分发**，获取方式见 [loser-agent-web/public/live2d/README.md](loser-agent-web/public/live2d/README.md)；商业使用请替换为已获授权的形象。