# loser-agent

**Repository Path**: yimeng812/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**: 1
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: agentscope, springboot4, Harness

## 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
├── 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 + Java 17               |
| Agent 引擎 | AgentScope 2.0.1 (HarnessAgent)         |
| ORM        | MyBatis-Plus 3.5.16 (Spring Boot 4 starter) |
| 数据库     | MySQL + Flyway (V1–V29)                 |
| 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）

### 安全
- RBAC 权限控制（用户/角色/菜单，V27 DDL）
- 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）

## 数据库版本（Flyway）

| 版本 | 内容 |
|------|------|
| V1 | 初始 5 表（agent_config / session / block / memory / publish_record） |
| V2 | agent_model 扩展 |
| V3 | 默认模型种子数据 |
| V8 | workspace_dir 字段 |
| V9 | session extra_state |
| V10 | 清理 V1 harness tier1 旧表 |
| V11 | skill markdown |
| V12 | subagent |
| V13 | api_key nullable（本地 provider） |
| V14 | publish_record 列对齐 |
| V15 | api_key cipher（KMS 加密） |
| V17 | gray_config 灰度配置 |
| V18 | model_entity + binding |
| V19 | skill 表重构 |
| V20 | model partial unique primary |
| V21 | skill enabled 字段 |
| V22 | mcp_server + binding |
| V23 | hitl_rule 升级（5 级 scope + permission_mode + tool_group_name） |
| V24 | eval 评测表 |
| V25 | eval scoring_dimensions text |
| V26 | block archived + 对齐 |
| V27 | sys_rbac 权限 |
| V28 | prompt + audit_log |
| V29 | drop legacy ac_skill |

## 快速开始

### 环境要求
- JDK 17+
- Maven 3.9+
- MySQL 8.0+

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

### 启动
```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 | 说明 |
|------|-----------|------|
| `/api/agent-configs` | AgentConfigController | Agent 配置 CRUD |
| `/api/publish` | PublishController | 发布 / 回滚 |
| `/api/chat` | AguiChatController | SSE 流式对话 |
| `/api/models` | ModelEntityController | 模型实体管理 |
| `/api/model-bindings` | AgentModelBindingController | Agent-Model 绑定 |
| `/api/skill-bindings` | AgentSkillBindingController | Agent-Skill 绑定 |
| `/api/mcp-bindings` | AgentMcpBindingController | Agent-MCP 绑定 |
| `/api/mcp` | McpController | MCP Server CRUD |
| `/api/subagents` | AcSubagentController | 子 Agent CRUD |
| `/api/agents/{code}/gray` | AcAgentGrayConfigController | 灰度配置 |
| `/agui/agents/{code}/hitl-rules` | HitlRuleController | HITL 规则 CRUD |
| `/agui/agents/{code}/permission-mode` | HitlRuleController | PermissionMode 管理 |
| `/admin/hitl-rules` | HitlRuleController | 全局 HITL 规则 |

## 测试

```bash
# 全量测试
mvn test

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

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

## 路线图

- [x] RBAC 权限控制
- [x] HITL 前端确认交互
- [x] Thinking / ToolCall 事件渲染
- [x] SSE 流式渲染
- [ ] MetaQ / RocketMQ 集群广播替换 in-process bus
- [ ] Master Key 轮换（KMS 架构级）
- [ ] MCP stdio 协议支持
- [ ] TOOL_GROUP 前端管理 UI
- [ ] 移动端适配

## 许可证

本项目基于 [GNU Affero General Public License v3.0](LICENSE) 开源。