# Agent Management

> 智能体管理和编排平台 —— 基于 Spring Boot + Spring AI 的可视化工作流编排与智能体执行平台。

通过拖拽式的节点编排构建 AI 工作流，支持 LLM 调用、智能体执行、条件分支、用户输入等多种节点类型，并通过内置的 **Hermes Bridge** 委托执行引擎，获得终端、浏览器、搜索等 40+ 工具与 Skill 系统的真实执行能力。

---

## ✨ 核心功能

- **可视化工作流编排** — 基于 DAG（有向无环图）的节点式编排引擎，支持多种节点类型与依赖解析
- **节点执行器** — 内置 LLM、Agent、SmartAction、Condition、UserInput、Output 等节点执行器
- **AI 模型管理** — 多模型配置、默认模型、优先级排序、连通性测试、远程模型列表拉取
- **技能（Skill）管理** — Skill 的上传、编辑、版本管理、回滚、文件级操作，基于 Markdown（SKILL.md）描述
- **标签系统** — 标签组 / 标签的多级管理、跨对象打标、批量导入导出
- **分类体系** — 技能分类、工作流分类的树形管理与拖拽排序
- **工作流版本管理** — 版本快照、历史回滚、版本说明编辑
- **运行历史与产物** — 每次运行的节点日志、运行产物打包下载
- **实时推送** — 基于 SSE（Server-Sent Events）的工作流执行进度与流式翻译推送
- **Hermes 执行引擎集成** — 通过 Python 桥接调用 Hermes Agent，获得真实工具执行能力

---

## 🏗️ 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 语言 / 运行时 | Java 17 | — |
| 框架 | Spring Boot 3.3.6 | 主框架 |
| AI 集成 | Spring AI 1.0.0 | OpenAI 兼容接口，可对接智谱 GLM 等 |
| Web | Spring Web + WebSocket | REST API 与实时通信 |
| 数据持久化 | Spring Data JPA + H2 | H2 文件库存储运行日志 |
| 配置数据存储 | JSON 文件（自定义） | 工作流 / 模型 / 标签等配置类数据 |
| 文件处理 | Commons IO 2.18.0 / Commons Compress 1.26.2 | 文件操作与产物打包 |
| 工具库 | Lombok | 样板代码消除 |
| 前端 | Vue 3 + Vite | SPA 单页应用，打包后由后端静态资源服务托管 |
| 执行引擎 | Python + Hermes Agent | 通过 HTTP 桥接，提供 40+ 工具与 Skill 系统 |

---

## 📁 项目结构

```
backend/
├── src/main/java/com/agent/management/
│   ├── AgentManagementApplication.java        # Spring Boot 启动类
│   ├── common/                                # 统一响应 Result、全局异常处理
│   ├── config/                                # 配置类（Hermes / Skill / JsonStore / WebMvc / SPA 等）
│   ├── controller/                            # REST API 控制器
│   ├── engine/                                # ⭐ 工作流执行引擎
│   │   ├── WorkflowEngine.java                #   引擎主流程
│   │   ├── DagResolver.java                   #   DAG 依赖解析
│   │   ├── TemplateRenderer.java              #   模板变量渲染
│   │   ├── executor/                          #   节点执行器
│   │   │   ├── LlmExecutor                    #     LLM 调用节点
│   │   │   ├── AgentExecutor / HermesAgentExecutor      #  智能体节点
│   │   │   ├── SmartActionExecutor / HermesSmartActionExecutor  # 智能动作节点
│   │   │   ├── ConditionExecutor              #     条件分支节点
│   │   │   ├── UserInputExecutor              #     用户输入节点
│   │   │   └── OutputExecutor                 #     输出节点
│   │   └── hermes/                            #   Hermes 桥接
│   │       ├── HermesBridgeClient             #     HTTP 桥接客户端
│   │       └── HermesProcessManager           #     Python 进程生命周期管理
│   ├── model/                                 # 数据模型（entity / dto / vo）
│   ├── parser/                                # SkillMarkdownParser（技能描述解析）
│   ├── repository/                            # JPA 仓库 + JSON 文件仓库
│   └── service/                               # 业务服务层
├── src/main/resources/
│   ├── application.yml                        # 主配置文件
│   ├── application.yml.example                # 配置模板（脱敏）
│   ├── logback-spring.xml                     # 日志配置
│   └── static/                                # 前端打包产物（SPA）
├── hermes-bridge/                             # Python 桥接脚本
│   ├── hermes_bridge.py                       #   桥接主程序
│   └── requirements.txt                       #   Python 依赖
├── hermes-agent/                              # Hermes Agent 执行引擎源码（独立项目）
├── data/                                      # 运行数据
│   ├── agent-runs.mv.db                       #   H2 数据库（运行日志）
│   ├── json/                                  #   JSON 配置存储（模型/标签/工作流等）
│   ├── workflow-runs/                         #   每次工作流运行的文件与产物
│   └── workflow-versions/                     #   工作流版本快照
├── uploads/                                   # 技能文件上传目录
├── logs/                                      # 应用日志
├── pom.xml                                    # Maven 构建文件
└── README.md
```

---

## 🚀 快速开始

### 环境要求

- **JDK 17+**
- **Maven 3.8+**
- **Python 3**（仅在启用 Hermes 执行引擎时需要，用于运行桥接脚本）

### 构建与运行

```bash
# 1. 安装 Hermes Bridge Python 依赖（如需启用执行引擎）
pip install -r hermes-bridge/requirements.txt

# 2. 编译打包（跳过测试）
mvn clean package -DskipTests

# 3. 运行
java -jar target/agent-management-1.0.0.jar
# 或开发模式
mvn spring-boot:run
```

启动后访问：`http://localhost:2438`

---

## ⚙️ 配置

配置位于 `src/main/resources/application.yml`，关键配置项均可通过环境变量覆盖。
项目同时提供 `application.yml.example` 作为脱敏模板。

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| 服务端口 | — | `2438` | 后端 HTTP 端口 |
| 技能基础路径 | `SKILL_BASE_PATH` | `./uploads/skills` | 技能文件存储目录 |
| JSON 存储目录 | `JSON_STORE_DIR` | `./data/json` | 配置类数据（模型/标签/工作流等） |
| 工作流运行目录 | `WORKFLOW_RUN_DIR` | `./data/workflow-runs` | 每次运行的文件与产物 |
| 启用 Hermes | `HERMES_ENABLED` | `true` | 是否启用 Hermes 执行引擎 |
| 桥接端口 | `HERMES_BRIDGE_PORT` | `18731` | Python 桥接服务本地端口 |
| Python 路径 | `HERMES_PYTHON_PATH` | `python` | Python 可执行文件路径 |
| 桥接脚本路径 | `HERMES_SCRIPT_PATH` | `hermes-bridge/hermes_bridge.py` | 桥接脚本位置 |
| OpenAI 兼容 Base URL | — | `https://open.bigmodel.cn/api/coding/paas/v4` | AI 服务接口地址 |
| API Key | `OPENAI_API_KEY` | ⚠️ 请务必通过环境变量设置 | AI 服务密钥（**切勿提交明文**） |
| 默认模型 | — | `glm-5.2` | 默认调用的大语言模型 |
| 上传大小上限 | — | `50MB` | 文件上传最大体积 |

> **安全提示**：生产环境务必通过 `OPENAI_API_KEY` 环境变量注入密钥，不要在 `application.yml` 中硬编码。

---

## 📡 API 概览

所有接口统一前缀 `/api`，响应体使用 `common.Result` 统一封装。

| 模块 | 基础路径 | 主要能力 |
|------|---------|---------|
| AI 模型管理 | `/api/models` | 模型 CRUD、设为默认、优先级排序、连通性测试、拉取远程模型列表 |
| 工作流管理 | `/api/workflows` | 工作流 CRUD、分类、**运行（SSE 流式）**、版本管理、回滚、运行产物下载、自动关联 |
| 技能管理 | `/api/skills` | 技能上传/编辑/删除、SKILL.md 编辑、文件级 CRUD、版本管理与回滚 |
| 工作流分类 | `/api/wf-categories` | 分类树 CRUD、移动排序 |
| 技能分类 | `/api/categories` | 分类树 CRUD、移动排序 |
| 标签系统 | `/api/tags` | 标签组/标签 CRUD、移动、**导入/导出**、跨对象打标 |
| 运行历史 | `/api/run-history` | 工作流运行历史列表、运行详情、删除 |
| 翻译（SSE） | `/api/translations` | `/stream` 流式订阅、`/translate` 触发翻译 |

---

## 🧩 架构说明

### 工作流执行引擎

`engine/WorkflowEngine` 是核心调度器，配合 `DagResolver` 解析节点依赖拓扑，依次驱动各节点执行器（`NodeExecutor` 实现）：

```
工作流 JSON 定义
      │
      ▼
 DagResolver（依赖拓扑排序）
      │
      ▼
 WorkflowEngine（逐节点调度）
      │
      ├──► LlmExecutor            直接调用 Spring AI / OpenAI 兼容接口
      ├──► ConditionExecutor       条件分支判定
      ├──► UserInputExecutor       等待用户输入
      ├──► OutputExecutor          输出汇总
      ├──► AgentExecutor ──────┐
      └──► SmartActionExecutor ┤  委托
                               ▼
                       Hermes Bridge Client（HTTP）
                               │
                               ▼
                    Hermes Agent（Python，40+ 工具）
```

### Hermes 桥接

当工作流中包含 `agent` / `smartAction` 节点时，引擎通过 `HermesProcessManager` 拉起一个常驻的 Python 进程（`hermes-bridge/hermes_bridge.py`），并经 `HermesBridgeClient` 通过本地 HTTP 端口（默认 `18731`）与之通信。该桥接将节点执行委托给 Hermes Agent，从而获得终端、浏览器、搜索等真实工具调用能力及 Skill 系统。

- 使用前需安装依赖：`pip install -r hermes-bridge/requirements.txt`
- 关闭时设置 `HERMES_ENABLED=false`，相关节点将回退为本地执行（仅文本对话，无工具能力）

---

## 📦 部署

- **构建产物**：`mvn clean package -DskipTests` 生成可执行单包 `target/agent-management-1.0.0.jar`
- **前端托管**：项目通过 `SpaController` 提供前端单页应用（SPA）托管，前端打包产物（`src/main/resources/static/`）由后端静态资源服务直接提供，可单包一体化部署
- **运行数据**：`data/` 与 `uploads/` 为运行态目录，部署时需保证可写；H2 数据库以文件形式存储于 `./data/agent-runs`

---

## 📄 许可证

TODO（暂未声明开源许可证，默认保留所有权利）
