agent-management

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 时需要）

配置

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

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

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

构建 & 运行

Windows：

run.bat

Linux / macOS：

chmod +x run.sh
./run.sh

仅构建（不启动）：

run.bat build    # Windows
./run.sh build   # Linux/macOS

单独运行已构建的 JAR：

java -jar backend/target/agent-management-1.0.0.jar

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

可选依赖（按功能启用）

# 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_1	—	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 数据库，部署时注意持久化。

📄 许可证

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