# hermes-java

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

## Basic Information

- **Project Name**: hermes-java
- **Description**: Hermes Agent — Java rewrite of NousResearch/hermes-agent. ReAct loop, OpenAI function calling, tool registry, memory, context compression, web UI.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Java

Hermes Java 是一个面向 SaaS 化个人助手场景的 Agent 平台，支持 Web + REST + Webhook 接入，具备多租户、鉴权、策略、审计、计量、任务队列与计费基础能力。

## 快速导航

- 架构总览（含架构图/时序图/流程图）：[`docs/architecture/project-handbook.md`](docs/architecture/project-handbook.md)
- API 总览：[`docs/architecture/api-surface.md`](docs/architecture/api-surface.md)
- 功能清单：[`docs/architecture/feature-catalog.md`](docs/architecture/feature-catalog.md)
- 架构文档索引：[`docs/architecture/README.md`](docs/architecture/README.md)
- 任务拆解与执行包：[`docs/execution/gml4-saas/README.md`](docs/execution/gml4-saas/README.md)

## 核心能力

- ReAct Agent：工具调用循环、上下文压缩、记忆增强
- 多租户 SaaS 基建：JWT、TenantContext、RBAC（admin/user）
- 业务治理：工具策略引擎、审计日志、幂等、防重放
- 商业化基础：计量配额、成本估算、账单/对账
- 稳定性：持久化任务队列（重试、死信、恢复）
- 合规：数据导出、删除、保留策略

## 项目结构

```text
hermes-java/
├── hermes-core/      # Agent核心、领域服务、鉴权、数据访问
├── hermes-gateway/   # Web/API入口、Webhook适配、过滤器
├── hermes-tools/     # Delegate/MCP/Cron/TTS等扩展工具
├── hermes-skill/     # 技能扩展模块
└── docs/             # 架构、计划、执行文档
```

## 技术栈

- Java 17, Spring Boot 3.4
- MySQL 8 + Flyway
- MyBatis-Plus
- Spring WebFlux
- Micrometer + Actuator + Prometheus

## 本地启动（开发）

### 1) 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8+

### 2) 零配置本地启动（推荐）

如果你只是想把工作台先跑起来，不依赖远程 MySQL，可以直接使用本地 `local` 配置：

```bash
export OPENAI_API_KEY='your_api_key'
export JWT_SECRET='change-me-in-production-at-least-32-chars!!'
mvn -pl hermes-gateway spring-boot:run -Dspring-boot.run.profiles=local
```

默认登录账号：

- 工作空间：`default`
- 邮箱：`admin@hermes.local`
- 密码：`admin123`

本地数据会落在 `./.data/hermes-local.mv.db`。

### 3) MySQL 模式

创建数据库，例如 `hermes`，并配置以下环境变量：

```bash
export DATABASE_URL='jdbc:mysql://localhost:3306/hermes?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC'
export DATABASE_USER='root'
export DATABASE_PASSWORD='root'
export OPENAI_API_KEY='your_api_key'
export JWT_SECRET='change-me-in-production-at-least-32-chars!!'
```

### 4) 编译与测试

```bash
mvn clean test
```

### 5) 启动服务

```bash
mvn -pl hermes-gateway spring-boot:run
```

启动后访问：<http://localhost:8080>

## 常用接口

- 鉴权：`/api/v1/auth/*`
- 聊天：`/api/v1/chat/send`
- 会话：`/api/v1/chat/sessions`
- 任务：`/api/v1/tasks/*`
- 策略：`/api/v1/policy/*`
- 计量：`/api/v1/usage/*`
- 合规：`/api/v1/compliance/*`
- 运营：`/api/v1/ops/*`
- 健康检查：`/api/v1/health`

完整清单见：[`docs/architecture/api-surface.md`](docs/architecture/api-surface.md)

## 关键配置

配置文件：

- `hermes-gateway/src/main/resources/application.yml`
- `hermes-core/src/main/resources/application.yml`

重点配置项：

- `hermes.model.*`：模型与路由参数
- `hermes.auth.*`：JWT 密钥与 token TTL
- `hermes.rate-limit.*`：限流策略
- `hermes.task-queue.*`：任务队列 worker 参数
- `spring.datasource.*`：MySQL 连接
- `spring.flyway.*`：迁移脚本路径（`db/migration-mysql`）

## 生产化注意事项

- 必须替换默认 `JWT_SECRET` 与数据库口令
- 收紧 CORS 白名单与公开路由
- 关闭默认租户回退策略（建议仅开发环境保留）
- 接入统一日志、指标、告警与备份
- 对高风险工具调用启用审批策略

## License

MIT