# Hermes-Java

**Repository Path**: lc8026/hermes-java

## Basic Information

- **Project Name**: Hermes-Java
- **Description**: Hermes的Java版本
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-07-09
- **Last Updated**: 2026-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Agent Java

<p align="center">
  <img src="https://img.shields.io/badge/Java-17+-orange?style=for-the-badge" alt="Java 17+" />
  <img src="https://img.shields.io/badge/Spring%20Boot-3.3.6-brightgreen?style=for-the-badge" alt="Spring Boot 3.3.6" />
  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="MIT License" />
  <img src="https://img.shields.io/badge/功能完成度-95%25-green?style=for-the-badge" alt="95% Complete" />
</p>

<p align="center">
  <a href="https://gitee.com/lc8026/hermes-java">Gitee 仓库</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#部署手册">部署手册</a> •
  <a href="#功能特性">功能特性</a>
</p>

---

## 📖 项目简介

**Hermes Agent Java** 是 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 的 Java 实现版本，基于 Spring Boot 3.x + Spring AI 构建，具备 ReAct 执行循环、分层记忆体系、技能自进化能力。

这是一个**自我改进的 AI Agent**，具有以下核心特性：
- 🔄 **闭环学习** - 从经验中创建技能，在使用中改进，跨会话持久化
- 🧠 **五层记忆模型** - L1 短期工作记忆 → L2 Redis 缓存 → L3 ES 情景记忆 → L4 MySQL 持久化 → L5 程序性技能记忆
- 🎭 **人格系统** - 支持 SOUL.md 自定义人格，多人格切换
- 🌐 **跨平台连续性** - 用户在不同消息网关间切换不丢失上下文
- 🔌 **插件化架构** - Java SPI + 热加载外部 JAR
- 🚀 **Spring Boot 原生** - 提供 Starter 一键集成到业务项目

---

## ✨ 功能特性

### 核心引擎
- ✅ ReAct 事件驱动编排引擎
- ✅ 五层记忆模型（短期工作/Redis/ES/MySQL/技能）
- ✅ 技能自进化系统（任务完成后反思生成技能）
- ✅ 工具注册/调度/安全守卫
- ✅ MCP 协议支持

### LLM Provider（7 个）
| Provider | 说明 |
|---|---|
| DashScope | 阿里通义千问 |
| OpenAI Compatible | OpenAI 兼容端点 |
| ZhiPu | 智谱 AI |
| Ollama | 本地模型 |
| **OpenRouter** | 200+ 模型聚合 |
| **HuggingFace** | 开源模型推理 |
| **Moonshot** | Kimi 全系列 |

### 消息网关（14 个）
| 类别 | 支持平台 |
|---|---|
| 国际 IM | Telegram, Discord, Slack, **WhatsApp, Signal** |
| 国内 IM | 钉钉, 飞书, 企业微信, 微信公众号 |
| 其他 | Webhook, Email, **Home Assistant**, **ACP 协议** |

### 执行后端（5 个）
| 类型 | 后端 |
|---|---|
| 本地 | Local 命令执行 |
| 容器 | Docker 沙箱执行 |
| 远程 | SSH 远程执行 |
| **Serverless** | Modal, Daytona |

### 工具生态（26+ 个）
- 📁 文件操作: ReadFile, WriteFile, SearchFiles, Grep
- 🌐 网络工具: WebSearch, WebExtract, BrowserNavigate/Click/Screenshot
- 💻 代码执行: Python, JavaScript, **Java**
- 🖥️ 桌面控制: **Computer Use**（截图/点击/键盘/滚动）
- 🎨 多媒体: ImageGeneration, **TTS, STT**
- 🔧 系统工具: Terminal, Git, SqlQuery, Clipboard
- 📊 知识管理: KnowledgeBase, Todo, DelegateTask, SessionSearch

### Agent 特性
- ✅ 人格系统（SOUL.md + personality 命令）
- ✅ 上下文文件（AGENTS.md/MEMORY.md/USER.md）
- ✅ RAG 知识库（ES + MySQL + 三级切分）
- ✅ 跨平台对话连续性
- ✅ ACP 多 Agent 协作协议
- ✅ 轨迹压缩与训练数据导出

### 可观测性
- ✅ Micrometer 指标监控
- ✅ AOP 自动拦截
- ✅ Actuator 健康检查
- ✅ Admin REST API

### UI 界面
- ✅ Web Dashboard（Vue 3 + Vite + Tailwind CSS）
- ✅ CLI TUI（Spring Shell + 打字指示器 + 格式化输出）

---

## 🏗️ 技术架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        Hermes Agent Java                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │ Web UI   │  │ CLI TUI  │  │ Gateway  │  │ Admin REST API   │ │
│  │ (Vue 3)  │  │ (Shell)  │  │ (14个)   │  │ (Knife4j)        │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬─────────┘ │
│       │             │             │                  │           │
│       └─────────────┴──────┬──────┴──────────────────┘           │
│                            ▼                                     │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                   AgentOrchestrator                          ││
│  │  (ReAct 编排引擎: Thought → Action → Observation 循环)      ││
│  └──────────────────────────┬──────────────────────────────────┘│
│                             ▼                                    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ LLM Service  │ │ Tool System  │ │ Memory Svc   │            │
│  │ (7 Provider) │ │ (26+ Tools)  │ │ (五层记忆)    │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
│                             ▼                                    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │ RAG Service  │ │ Skill System │ │ ACP Protocol │            │
│  │ (ES+MySQL)   │ │ (自进化)      │ │ (多Agent)    │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
├─────────────────────────────────────────────────────────────────┤
│                        基础设施层                                 │
│  ┌────────┐ ┌────────┐ ┌──────────────┐ ┌────────────────────┐  │
│  │ MySQL  │ │ Redis  │ │ Elasticsearch│ │ Docker/Modal/SSH   │  │
│  └────────┘ └────────┘ └──────────────┘ └────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 📦 模块结构

```
hermes-agent-java/
├── agent-common/          # 公共模块：实体、枚举、工具类
├── agent-core/            # 核心模块：编排器、记忆、技能、工具、RAG
├── agent-executor/        # 执行模块：Local/Docker/SSH/Modal/Daytona
├── agent-gateway/         # 网关模块：14 个消息适配器
├── agent-boot/            # 启动模块：Web 应用入口
├── agent-cli/             # CLI 模块：命令行交互
├── agent-web/             # 前端模块：Vue Dashboard
└── hermes-agent-spring-boot-starter/  # Starter：一键集成
```

---

## 🚀 快速开始

### 环境要求

| 依赖 | 版本 |
|---|---|
| JDK | 17+ |
| Maven | 3.9+ |
| MySQL | 8.0+ |
| Redis | 7.0+ |
| Elasticsearch | 8.x |
| Node.js | 18+ (前端开发) |

### 1. 克隆项目

```bash
git clone https://gitee.com/lc8026/hermes-java.git
cd hermes-java
```

### 2. 编译项目

```bash
mvn clean install -DskipTests
```

### 3. 启动后端

```bash
cd agent-boot
mvn spring-boot:run
```

### 4. 启动前端（可选）

```bash
cd agent-web
npm install
npm run dev
```

访问 `http://localhost:3000` 即可使用 Web Dashboard。

---

## 📚 部署手册

### 一、本地开发部署

#### 1. 数据库准备

```sql
-- 创建数据库
CREATE DATABASE hermes_agent CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户
CREATE USER 'hermes'@'localhost' IDENTIFIED BY 'hermes2024';
GRANT ALL PRIVILEGES ON hermes_agent.* TO 'hermes'@'localhost';
FLUSH PRIVILEGES;
```

执行建表脚本：
```bash
mysql -u hermes -p hermes_agent < agent-boot/src/main/resources/db/schema.sql
```

#### 2. Redis 配置

```bash
# 启动 Redis
redis-server --requirepass hermes2024 --appendonly yes --maxmemory 256mb
```

#### 3. Elasticsearch 配置

```bash
# Docker 启动 ES
docker run -d --name hermes-es \
  -p 9200:9200 -p 9300:9300 \
  -e "discovery.type=single-node" \
  -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
  -e "xpack.security.enabled=false" \
  docker.elastic.co/elasticsearch/elasticsearch:8.13.4
```

#### 4. 配置文件

编辑 `agent-boot/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/hermes_agent
    username: hermes
    password: hermes2024
  data:
    redis:
      host: localhost
      port: 6379
      password: hermes2024
  elasticsearch:
    uris: http://localhost:9200
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}

hermes:
  admin:
    enabled: true
```

#### 5. 启动服务

```bash
# 方式一：Maven 启动
cd agent-boot
mvn spring-boot:run

# 方式二：JAR 启动
java -jar agent-boot/target/agent-boot-1.0.0-SNAPSHOT.jar

# 方式三：CLI 模式
cd agent-cli
mvn spring-boot:run
```

#### 6. 验证服务

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

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

---

### 二、Docker 部署

#### 1. 环境准备

```bash
# 克隆项目
git clone https://gitee.com/lc8026/hermes-java.git
cd hermes-java

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 填入 API Key
vim .env
```

#### 2. 配置环境变量

`.env` 文件内容：

```bash
# 数据库
MYSQL_ROOT_PASSWORD=hermes2024
MYSQL_DATABASE=hermes_agent
MYSQL_USER=hermes
MYSQL_PASSWORD=hermes2024

# Redis
REDIS_PASSWORD=hermes2024

# LLM Provider（按需启用）
DASHSCOPE_API_KEY=sk-xxx
OPENROUTER_API_KEY=sk-or-xxx
HUGGINGFACE_API_KEY=hf_xxx
MOONSHOT_API_KEY=sk-xxx

# 语音能力（可选）
TTS_ENABLED=false
TTS_API_URL=https://api.openai.com/v1/audio/speech
TTS_API_KEY=sk-xxx

STT_ENABLED=false
STT_API_URL=https://api.openai.com/v1/audio/transcriptions
STTS_API_KEY=sk-xxx

# Serverless（可选）
MODAL_ENABLED=false
MODAL_API_KEY=ak-xxx

DAYTONA_ENABLED=false
DAYTONA_API_KEY=dp-xxx
DAYTONA_WORKSPACE_ID=xxx

# Admin
ADMIN_API_KEY=hermes-admin-key-2024
```

#### 3. 一键启动

```bash
# 构建并启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f app

# 查看服务状态
docker compose ps
```

#### 4. 服务访问

| 服务 | 地址 |
|---|---|
| Agent API | http://localhost:8080 |
| Admin API | http://localhost:8080/api/admin |
| API 文档 | http://localhost:8080/doc.html |
| MySQL | localhost:3306 |
| Redis | localhost:6379 |
| Elasticsearch | localhost:9200 |

#### 5. 常用命令

```bash
# 停止服务
docker compose down

# 重新构建
docker compose up -d --build

# 查看特定服务日志
docker compose logs -f mysql
docker compose logs -f redis

# 进入容器
docker exec -it hermes-agent bash

# 清理数据卷（慎用）
docker compose down -v
```

---

### 三、云端部署（生产环境）

#### 方案一：云服务器部署

**推荐配置**：

| 配置项 | 最低配置 | 推荐配置 |
|---|---|---|
| CPU | 2 核 | 4 核+ |
| 内存 | 4 GB | 8 GB+ |
| 磁盘 | 40 GB SSD | 100 GB SSD |
| 带宽 | 2 Mbps | 5 Mbps+ |

**部署步骤**：

```bash
# 1. 安装 Docker
curl -fsSL https://get.docker.com | sh
systemctl enable docker --now

# 2. 安装 Docker Compose
curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# 3. 克隆项目
git clone https://gitee.com/lc8026/hermes-java.git
cd hermes-java

# 4. 配置环境变量
cp .env.example .env
vim .env  # 填入真实配置

# 5. 启动服务
docker compose up -d

# 6. 配置防火墙（开放端口）
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
```

#### 方案二：Kubernetes 部署

**1. 创建命名空间**

```yaml
# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: hermes-agent
```

**2. 创建 Secret**

```yaml
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: hermes-secret
  namespace: hermes-agent
type: Opaque
stringData:
  MYSQL_PASSWORD: "hermes2024"
  REDIS_PASSWORD: "hermes2024"
  DASHSCOPE_API_KEY: "sk-xxx"
  ADMIN_API_KEY: "hermes-admin-key-2024"
```

**3. 部署 MySQL**

```yaml
# mysql.yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
  namespace: hermes-agent
spec:
  serviceName: mysql
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - name: mysql
        image: mysql:8.0
        env:
        - name: MYSQL_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: hermes-secret
              key: MYSQL_PASSWORD
        - name: MYSQL_DATABASE
          value: "hermes_agent"
        ports:
        - containerPort: 3306
        volumeMounts:
        - name: mysql-data
          mountPath: /var/lib/mysql
  volumeClaimTemplates:
  - metadata:
      name: mysql-data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
  name: mysql
  namespace: hermes-agent
spec:
  ports:
  - port: 3306
  selector:
    app: mysql
```

**4. 部署应用**

```yaml
# app.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hermes-agent
  namespace: hermes-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hermes-agent
  template:
    metadata:
      labels:
        app: hermes-agent
    spec:
      containers:
      - name: app
        image: hermes-agent:latest
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_DATASOURCE_URL
          value: "jdbc:mysql://mysql:3306/hermes_agent"
        - name: SPRING_DATASOURCE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: hermes-secret
              key: MYSQL_PASSWORD
        - name: DASHSCOPE_API_KEY
          valueFrom:
            secretKeyRef:
              name: hermes-secret
              key: DASHSCOPE_API_KEY
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
---
apiVersion: v1
kind: Service
metadata:
  name: hermes-agent
  namespace: hermes-agent
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 8080
  selector:
    app: hermes-agent
```

**5. 部署命令**

```bash
kubectl apply -f namespace.yaml
kubectl apply -f secret.yaml
kubectl apply -f mysql.yaml
kubectl apply -f app.yaml

# 查看状态
kubectl get pods -n hermes-agent
kubectl get svc -n hermes-agent
```

#### 方案三：云平台托管

**阿里云 ECS 部署**：

1. 购买 ECS 实例（推荐：2 核 4G，CentOS 7.9）
2. 安全组开放 8080 端口
3. SSH 登录实例
4. 执行 Docker 部署流程

**腾讯云轻量应用服务器**：

```bash
# 使用 Docker 应用镜像
# 直接在控制台配置环境变量
```

---

## ⚙️ 配置说明

### 核心配置项

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `spring.ai.dashscope.api-key` | 通义千问 API Key | - |
| `spring.ai.openrouter.api-key` | OpenRouter API Key | - |
| `hermes.admin.enabled` | 启用 Admin API | true |
| `hermes.admin.api-key` | Admin API 密钥 | - |
| `hermes.personality.enabled` | 启用人格系统 | true |
| `hermes.executor.type` | 执行后端类型 | LOCAL |

### 消息网关配置

```yaml
hermes:
  adapter:
    telegram:
      enabled: true
      bot-token: ${TELEGRAM_BOT_TOKEN}
    discord:
      enabled: false
      bot-token: ${DISCORD_BOT_TOKEN}
    whatsapp:
      enabled: false
    email:
      enabled: false
```

### 执行器配置

```yaml
hermes:
  executor:
    type: LOCAL
    docker:
      enabled: true
      image: hermes-agent:latest
    modal:
      enabled: false
      api-key: ${MODAL_API_KEY}
```

---

## 📖 API 文档

启动服务后访问：`http://localhost:8080/doc.html`

### 核心 API

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/chat` | POST | 对话接口 |
| `/api/admin/stats` | GET | 获取统计信息 |
| `/api/admin/tools` | GET | 工具列表 |
| `/api/admin/models` | GET | 模型列表 |
| `/api/admin/sessions` | GET | 会话列表 |
| `/api/rag/knowledge` | POST | 添加知识 |
| `/api/rag/search` | GET | 搜索知识 |

### 对话示例

```bash
curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": null,
    "userId": "user-001",
    "message": "你好"
  }'
```

---

## 🔧 开发指南

### 新增工具

```java
@Component
public class MyTool implements Tool {
    
    @Override
    public String getName() {
        return "my_tool";
    }
    
    @Override
    public String getDescription() {
        return "My custom tool";
    }
    
    @Override
    public ToolResult execute(ToolContext context) {
        // 实现逻辑
        return ToolResult.success("Done");
    }
}
```

### 新增 LLM Provider

```java
@Component
@ConditionalOnProperty(name = "spring.ai.my-provider.api-key")
public class MyProvider extends AbstractOpenAICompatibleProvider {
    
    @Value("${spring.ai.my-provider.api-key}")
    private String apiKey;
    
    @Override
    public String getProviderId() {
        return "my-provider";
    }
    
    @Override
    protected String getApiKey() {
        return apiKey;
    }
}
```

### 使用 Starter 集成

```java
@SpringBootApplication
@EnableHermesAgent
public class MyApp {
    
    @Autowired
    private HermesAgentTemplate agent;
    
    public void chat() {
        String response = agent.chat("你好");
    }
}
```

---

## 📊 性能调优

### JVM 参数

```bash
java -Xms512m -Xmx2048m \
     -XX:+UseG1GC \
     -XX:MaxGCPauseMillis=200 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -jar agent-boot.jar
```

### MySQL 调优

```sql
-- 连接数
SET GLOBAL max_connections = 500;

-- 缓冲池
SET GLOBAL innodb_buffer_pool_size = 1073741824;  -- 1GB
```

### Redis 调优

```bash
redis-server \
  --maxmemory 512mb \
  --maxmemory-policy allkeys-lru \
  --save 60 1000
```

---

## 🔒 安全建议

1. **修改默认密码** - 生产环境务必修改 MySQL/Redis/Admin 密码
2. **启用 HTTPS** - 使用 Nginx 反向代理配置 SSL
3. **限制 Admin 访问** - 仅允许内网访问 Admin API
4. **API Key 加密** - 使用 Jasypt 加密配置文件中的敏感信息
5. **定期备份** - MySQL 数据和 Redis 数据定期备份

---

## 📝 更新日志

### v1.0.0 (2024-07-14)

**新增功能**：
- ✅ 新增 3 个 LLM Provider（OpenRouter/HuggingFace/Moonshot）
- ✅ 新增 4 个消息网关适配器（WhatsApp/Email/Signal/HomeAssistant）
- ✅ 新增 TTS 语音合成和 STT 语音转录工具
- ✅ 新增 Serverless 执行后端（Modal/Daytona）
- ✅ 实现人格系统（SOUL.md）和上下文文件系统
- ✅ 实现跨平台对话连续性和 ACP 协议
- ✅ 实现轨迹压缩与训练数据导出
- ✅ 新增 Web UI Dashboard（Vue + Vite）
- ✅ 增强 CLI TUI（打字指示器/格式化输出）
- ✅ 新增 Spring Boot Starter 模块
- ✅ 新增 RAG 知识库集成
- ✅ 新增 Micrometer 指标监控

**功能完成度**：~95%

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📄 License

[MIT License](LICENSE)

---

## 🙏 致谢

- [Hermes Agent](https://github.com/NousResearch/hermes-agent) - 官方 Python 版本
- [Spring Boot](https://spring.io/projects/spring-boot) - 基础框架
- [Spring AI](https://spring.io/projects/spring-ai) - AI 集成框架

---

<p align="center">
  Made with ❤️ by Hermes Agent Team
</p>