# Agent Management

> 智能体管理和编排平台 —— Skill 文件管理、标签分类、可视化工作流编排、DAG 调度执行、知识库与知识图谱一站式平台。

基于 Spring Boot + Vue 3 的全栈应用，前后端合并打包为单一 JAR 同端口部署。支持拖拽式工作流画布、多种节点类型、节点流式输出、运行历史回放，并集成知识库向量化检索、结构化数据源 SQL 控制台与 Neo4j 知识图谱。

## ✨ 核心功能

- **智能体（Skill）管理** — 上传、在线编辑（Monaco Editor）、删除 Skill；元数据表单 + Markdown 正文双轨编辑；目录级文件树浏览与多语言高亮；`SKILL.md` 智能保存自动合并 frontmatter。
- **技能版本管理** — 版本列表查看、内容对比、备注编辑、一键回滚。
- **标签系统** — 树形标签分类（标签组 / 子标签 / 移动 / 删除）；技能与工作流实体多标签关联；标签选择器与导入导出。
- **分类管理** — 技能分类与工作流分类两套独立树形体系，支持增删改查与拖拽移动。
- **可视化工作流编排** — 拖拽式画布编辑器，支持 9 种节点：用户输入、LLM、智能体、技能、条件分支、输出、智能动作（SmartAction）、HermesAgent、HermesSmartAction；节点 IO 变量智能推断与连线类型匹配。
- **DAG 调度引擎** — 拓扑排序执行、循环依赖检测、模板变量渲染、上下文透传与快照、节点结构化输出（三级降级解析）、流式输出（SSE）、节点失败策略（abort/skip）、变量覆盖检测。
- **运行历史与回放** — 每次运行持久化节点状态、输出、日志与上下文快照；前端节点级展开查看；思考过程折叠展示。
- **工作流版本管理** — 版本快照、版本对比、一键回滚。
- **知识库** — 文档上传与解析（Tika 支持 PDF/Word/Excel/PPT/HTML/TXT）；三级层次化分块（L1/L2/L3）；语义分块器自适应识别话题边界；Milvus 向量存储 + 本地 bge-m3 稠密向量 + 原生 BM25 稀疏检索；Leaf-only 向量化策略。
- **SQL Console（结构化数据源）** — 动态 JDBC 数据源管理（MySQL / PostgreSQL / 达梦 / SQLite）；表结构与数据浏览；SQL 守卫；Jasypt 凭据加密入库。
- **知识图谱** — Neo4j 图源管理；Cypher 守卫；标签与关系查询。
- **AI 模型管理** — 多模型配置、连接测试、可用模型列表拉取、默认模型切换与优先级。
- **智能体模板** — 创建智能体时选择工作流编辑 / 自然语言 / 空白等模式；TemplatePicker 组件。
- **自动翻译** — Skill 描述英文→中文，SSE 实时推送进度；长文本按段落自动分段翻译。
- **外部 API** — 第三方系统通过 `X-API-Key` 鉴权调用工作流，支持工作流 ID 白名单。
- **`.agentignore` 过滤** — 仿 `.gitignore` 的工作目录过滤机制，输出节点与运行目录 zip 下载按规则过滤。

## 🏗️ 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Java 17 + Spring Boot 3.3.6 + Spring AI 1.0.0 |
| 数据访问 | Spring Data JPA + H2（嵌入式文件模式，存储运行日志） |
| WebSocket | spring-boot-starter-websocket |
| 文档解析 | Apache Tika 2.9.2（PDF/Word/Excel/PPT/HTML/TXT） |
| 向量库 | Spring AI Milvus Starter（Milvus 2.5+） |
| 知识图谱 | Neo4j Java Driver 5.27 |
| 数据库驱动 | MySQL 8.4 / PostgreSQL 42.7 / 达梦 8.1 / SQLite 3.45 |
| 安全 | Jasypt 3.0.5（凭据加密）+ Bean Validation |
| 工具库 | Lombok、commons-io 2.18、commons-compress 1.26 |
| 前端框架 | Vue 3.5 + Vue Router 4.6 + Pinia 3.0 |
| 前端 UI | Naive UI 2.44 + @vicons/ionicons5 |
| 画布编辑 | @vue-flow/core 1.48 + @vue-flow/background |
| 代码编辑 | Monaco Editor 0.55 |
| 图谱可视化 | Cytoscape 3.34 + cytoscape-cose-bilkent |
| HTTP / 构建 | Axios + Vite 8 |
| AI 服务 | Spring AI OpenAI 兼容接口（默认智谱 GLM） |
| 本地嵌入 | Embedding Bridge（Python 子进程，BAAI/bge-m3） |
| 智能体引擎 | Hermes Bridge（Python AIAgent 子进程，40+ 工具） |
| 构建 | Maven + Vite，前端产物嵌入 Spring Boot，单一 JAR |

## 📁 项目结构

```
├── backend/                              # Spring Boot 后端
│   ├── embedding-bridge/                 # 本地 Embedding Bridge（Python，bge-m3 向量与分块）
│   ├── src/main/java/com/agent/management/
│   │   ├── controller/                  # REST API 控制器（15 个）
│   │   ├── service/                     # 业务逻辑层
│   │   ├── engine/                      # 工作流 DAG 调度引擎
│   │   │   └── executor/                # 节点执行器（9 种节点类型）
│   │   ├── model/                       # 实体、DTO、VO
│   │   ├── repository/                  # JPA 数据访问层
│   │   ├── parser/                      # SKILL.md 解析器
│   │   ├── external/                    # 外部 API（/api/v1/**）
│   │   ├── config/                      # 配置类（CORS、SPA Fallback、Milvus 等）
│   │   └── common/                      # 通用工具（统一响应、异常处理）
│   └── src/main/resources/
│       ├── application.yml              # 后端配置（需从 .example 复制）
│       ├── application.yml.example      # 配置示例（已脱敏）
│       └── static/                      # 前端构建产物（Vite 直出）
├── frontend/                             # Vue 3 前端
│   └── src/
│       ├── views/                       # 页面（knowledge/skill/workflow/模型/标签/编排）
│       ├── components/                  # 组件（knowledge/skill/tag/workflow/layout）
│       ├── composables/                 # 组合式函数（工作流运行/版本/字段）
│       ├── api/                         # API 请求封装
│       ├── stores/                      # Pinia 状态管理
│       ├── router/                      # 路由配置
│       └── utils/                       # 工具函数（request、SSE）
├── hermes-bridge/                        # Hermes Agent 执行桥（Python 子进程）
├── docs/                                 # 设计文档
├── run.sh / run.bat                      # 前后端合并构建部署脚本
└── pom.xml
```

## 🚀 快速开始

### 环境要求

- **Java** 17+
- **Maven** 3.6+
- **Node.js** 18+（仅构建前端时需要）
- **Python** 3.10+（启用 Embedding Bridge / Hermes Bridge 时需要）

### 配置

复制示例配置文件并填入真实值：

```bash
cp backend/src/main/resources/application.yml.example backend/src/main/resources/application.yml
```

编辑 `application.yml`，按需填入 AI 服务 API Key、Milvus / Neo4j / 数据库连接信息（参见文件内注释）。敏感配置建议通过环境变量注入。

### 构建 & 运行

**Windows：**
```bash
run.bat
```

**Linux / macOS：**
```bash
chmod +x run.sh
./run.sh
```

**仅构建（不启动）：**
```bash
run.bat build    # Windows
./run.sh build   # Linux/macOS
```

**单独运行已构建的 JAR：**
```bash
java -jar backend/target/agent-management-1.0.0.jar
```

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

### 可选依赖（按功能启用）

```bash
# Embedding Bridge（知识库向量化，首次运行自动下载 bge-m3 约 2GB）
pip install -r backend/embedding-bridge/requirements.txt

# Hermes Bridge（智能体节点工具执行能力）
pip install -r hermes-bridge/requirements.txt
```

## ⚙️ 配置项

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| 服务端口 | — | `2438` | Spring Boot 监听端口 |
| Skill 存储目录 | `SKILL_BASE_PATH` | `./uploads/skills` | Skill 文件根目录 |
| JSON 存储目录 | `JSON_STORE_DIR` | `./data/json` | 配置类数据存储 |
| 工作流运行目录 | `WORKFLOW_RUN_DIR` | `./data/workflow-runs` | 每次运行的文件永久保留 |
| LLM API Key | `OPENAI_API_KEY` | — | 智谱 AI Key，同时供 Hermes Bridge 回退使用 |
| LLM 服务地址 | — | 智谱 OpenAI 兼容地址 | 可改为 DeepSeek / Moonshot 等 |
| 知识库开关 | `KB_ENABLED` | `true` | false 时所有 kb 接口返回 503 |
| Milvus 地址 | `MILVUS_HOST` / `MILVUS_PORT` | `127.0.0.1` / `19530` | gRPC 连接地址 |
| Milvus 开关 | `MILVUS_ENABLED` | `true` | 文档向量化总开关 |
| Embedding Bridge | `EMBEDDING_BRIDGE_ENABLED` | `true` | 本地 bge-m3 嵌入服务 |
| Embedding Bridge 端口 | `EMBEDDING_BRIDGE_PORT` | `18732` | Python 子进程端口 |
| 嵌入模型 | `EMBEDDING_MODEL` | `BAAI/bge-m3` | HuggingFace 模型 |
| Hermes Bridge | `HERMES_ENABLED` | `true` | 关闭后 agent 节点退化为纯 LLM 对话 |
| Hermes Bridge 端口 | `HERMES_BRIDGE_PORT` | `18731` | Python 子进程端口 |
| Hermes LLM Key | `HERMES_BRIDGE_LLM_API_KEY` | — | 为空时回退到 `OPENAI_API_KEY` |
| Neo4j 连接 | `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` | 本地默认 | 实际凭据存 GraphSource 表（Jasypt 加密） |
| Jasypt 密钥 | `JASYPT_KEY` | `dev-only-key-...` | ⚠️ 生产环境务必设置强随机密钥 |
| 外部 API 开关 | `EXTERNAL_API_ENABLED` | `true` | 第三方调用工作流接口 |
| 外部 API Key | `EXTERNAL_API_KEY` | — | X-API-Key 鉴权 |

## 📡 API 概览

| 模块 | 前缀 | 主要功能 |
|------|------|---------|
| Skill 管理 | `/api/skills` | 上传、编辑、删除、详情、文件树、版本管理、回滚 |
| 标签 | `/api/tags` | 标签组与标签的增删改查 |
| 技能分类 | `/api/categories` | 树形分类管理、移动 |
| 工作流分类 | `/api/wf-categories` | 工作流独立树形分类 |
| 智能体模板 | `/api/agent-templates` | 模板 CRUD |
| AI 模型 | `/api/models` | 多模型配置、测试、拉取、默认切换、优先级 |
| 工作流 | `/api/workflows` | 工作流编排、保存、执行（SSE） |
| 运行历史 | `/api/run-history` | 工作流与单次运行记录查看 / 删除 |
| 知识库文档 | `/api/kb/documents` | 上传、分块、向量化、移动、依赖检查 |
| 知识库分类 | `/api/kb/categories` | 知识库树形分类 |
| 知识库搜索 | `/api/kb/search` | 向量 + BM25 混合检索 |
| 数据源 | `/api/kb/datasources` | 动态数据源管理、连接测试 |
| SQL 查询 | `/api/kb/datasources/{id}` | 表结构、列、数据、查询、历史 |
| 知识图谱 | `/api/kb/graphs` | Neo4j 图源管理、查询、标签 |
| 翻译 SSE | `/api/translation` | 实时翻译进度推送 |
| 外部 API | `/api/v1/**` | 第三方 X-API-Key 鉴权调用工作流 |

## 📦 部署

- **打包方式**：前端 Vite 构建产物直接输出到 `backend/src/main/resources/static/`，后端 Maven 打包为单一 JAR。
- **单端口部署**：Spring Boot 同时托管前端静态资源与后端 API，同端口（2438）访问。
- **SPA Fallback**：后端配置将非 API 路由回退到 `index.html`，支持前端路由刷新。
- **运行时数据**：`data/` 目录保存 JSON 配置、工作流运行文件与 H2 数据库，部署时注意持久化。

## 📄 许可证

私有项目，未指定开源许可证。