yumoqing
2152ae9d40
- Fix chat command args: use '-q --source tool' for non-interactive mode in send_session_message to avoid entering interactive CLI - Fix auth_method KeyError: add 'auth_method: header' default in fallback config - Persist session registry to data/sessions.json so sessions survive restarts - Dynamic path resolution via get_hermes_home() instead of hardcoded paths - Update README with full API documentation (v1.3.0) - Add .gitignore for data/, __pycache__/, .venv/
259 lines
5.7 KiB
Markdown
259 lines
5.7 KiB
Markdown
# Hermes Service API
|
|
|
|
Hermes Service 是一个将 Hermes Agent CLI 能力封装为 REST API 的中间件服务。支持多用户隔离、会话持久化、IP/API Key 安全认证。
|
|
|
|
**版本**: v1.3.0
|
|
**运行端口**: 默认 9123 (可通过 config.yaml 修改)
|
|
|
|
---
|
|
|
|
## 启动方式
|
|
|
|
```bash
|
|
cd ~/repos/hermes-service
|
|
python3 main.py
|
|
# 或使用 uvicorn
|
|
uvicorn main:app --host 127.0.0.1 --port 9123
|
|
```
|
|
|
|
---
|
|
|
|
## 认证机制
|
|
|
|
所有 API 端点均受 `validate_ip_and_apikey()` 装饰器保护：
|
|
|
|
1. **IP 白名单**：当 `security.enable_ip_check: true` 时，仅允许 `allowed_ips` 中的 IP 访问
|
|
2. **API Key**：当 `security.enable_api_key: true` 时，需在请求头中提供有效 API Key
|
|
|
|
### API Key 传递方式
|
|
|
|
| auth_method | 请求头 | 示例 |
|
|
|-------------|--------|------|
|
|
| `header` (默认) | `X-API-Key: <key>` | `X-API-Key: 5ftyuvhfhi3345` |
|
|
| `bearer` | `Authorization: Bearer <key>` | `Authorization: Bearer 5ftyuvhfhi3345` |
|
|
|
|
---
|
|
|
|
## API 端点清单
|
|
|
|
### 1. 健康检查
|
|
|
|
```
|
|
GET /health
|
|
```
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"service": "hermes-service",
|
|
"multi_user": true
|
|
}
|
|
```
|
|
|
|
### 2. 获取 Hermes 状态
|
|
|
|
```
|
|
GET /api/v1/status
|
|
```
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"status": "running",
|
|
"version": "Hermes Agent v0.11.0 (2026.4.23)"
|
|
}
|
|
```
|
|
|
|
### 3. 创建会话
|
|
|
|
```
|
|
POST /api/v1/sessions
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"user_id": "user123"
|
|
}
|
|
```
|
|
|
|
**请求体**:
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `user_id` | string | 是 | 用户唯一标识 |
|
|
| `initial_message` | string | 否 | 初始消息（暂未使用） |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"user_id": "user123",
|
|
"hermes_path": "/d/hermesai/users/user123/hermes-agent",
|
|
"status": "created"
|
|
}
|
|
```
|
|
|
|
**说明**: 首次为该用户创建会话时，会自动从 BASE_HERMES_PATH 复制完整环境到 `/d/hermesai/users/{user_id}/`，实现用户隔离。
|
|
|
|
### 4. 执行任意命令
|
|
|
|
```
|
|
POST /api/v1/execute
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"command": ["chat", "-q", "Hello", "--source", "tool"],
|
|
"user_context": {"user_id": "user123"},
|
|
"timeout": 300
|
|
}
|
|
```
|
|
|
|
**请求体**:
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `command` | list[string] | 是 | Hermes CLI 命令参数列表 |
|
|
| `user_context` | object | 否 | 用户上下文，含 `user_id` 时使用隔离环境 |
|
|
| `timeout` | int | 否 | 超时秒数，默认 300 |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"stdout": "Hello! How can I help you today?",
|
|
"stderr": "",
|
|
"returncode": 0
|
|
}
|
|
```
|
|
|
|
### 5. 发送会话消息
|
|
|
|
```
|
|
POST /api/v1/sessions/{session_id}/messages
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"message": "What is Python?"
|
|
}
|
|
```
|
|
|
|
**请求体**:
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `message` | string | 是 | 发送给 AI 的消息内容 |
|
|
| `user_context` | object | 否 | 用户上下文（暂未使用，从 session 获取） |
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"response": "Python is a high-level, general-purpose programming language...",
|
|
"success": true
|
|
}
|
|
```
|
|
|
|
**说明**: 内部使用 `hermes chat -q <message> --source tool` 非交互模式执行，确保返回单一响应而非进入交互会话。`--source tool` 标记使会话不会出现在用户的常规 CLI 会话列表中。
|
|
|
|
### 6. 获取会话信息
|
|
|
|
```
|
|
GET /api/v1/sessions/{session_id}
|
|
```
|
|
|
|
**响应**:
|
|
```json
|
|
{
|
|
"user_id": "user123",
|
|
"local_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"created_at": "2026-04-25T11:30:00.000000",
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 会话持久化
|
|
|
|
会话数据持久化存储在 `data/sessions.json` 文件中，服务重启后可恢复已有会话。
|
|
|
|
**存储路径**: `<service_dir>/data/sessions.json`
|
|
**格式**: JSON
|
|
**线程安全**: 使用 threading.Lock 保护写入操作
|
|
|
|
---
|
|
|
|
## 路径解析机制
|
|
|
|
Hermes 基础路径通过以下优先级动态解析：
|
|
|
|
1. `HERMES_HOME` 环境变量（最高优先级，用于测试/开发）
|
|
2. `hermes_constants.get_hermes_home()`（从 hermes-agent 模块导入）
|
|
3. 默认回退路径 `/d/hermesai/.hermes`
|
|
|
|
这使得服务能自适应 hermes-agent 的位置变化，无需硬编码路径。
|
|
|
|
---
|
|
|
|
## 配置文件 (config.yaml)
|
|
|
|
```yaml
|
|
security:
|
|
enable_ip_check: true # 启用 IP 白名单
|
|
allowed_ips: # 允许的 IP / CIDR
|
|
- "127.0.0.1"
|
|
- "8.222.165.87"
|
|
enable_api_key: true # 启用 API Key 认证
|
|
auth_method: "header" # 认证方式: "header" 或 "bearer"
|
|
api_key_header: "X-API-Key" # API Key 请求头名称
|
|
api_keys:
|
|
- key: "your-api-key"
|
|
description: "Production key"
|
|
expires_at: null
|
|
|
|
nginx:
|
|
trusted_proxies:
|
|
- "127.0.0.1"
|
|
enable_real_ip: false # 从 X-Forwarded-For 提取真实 IP
|
|
|
|
service:
|
|
host: "127.0.0.1"
|
|
port: 9123
|
|
log_level: "info"
|
|
|
|
cors:
|
|
allow_origins: ["*"]
|
|
allow_credentials: true
|
|
allow_methods: ["*"]
|
|
allow_headers: ["*"]
|
|
```
|
|
|
|
---
|
|
|
|
## 用户隔离
|
|
|
|
每个用户拥有独立的 Hermes 环境：
|
|
|
|
```
|
|
/d/hermesai/users/
|
|
user123/
|
|
hermes-agent/ # 完整 Hermes Agent 副本
|
|
.hermes/ # 用户配置和会话数据
|
|
user456/
|
|
hermes-agent/
|
|
.hermes/
|
|
```
|
|
|
|
首次使用时自动创建，`.venv` 通过软链接共享以节省磁盘空间。
|
|
|
|
---
|
|
|
|
## v1.3.0 变更日志
|
|
|
|
| 修复项 | 说明 |
|
|
|--------|------|
|
|
| chat 命令参数 | `send_session_message` 改用 `-q --source tool` 非交互模式，避免进入交互 CLI |
|
|
| auth_method 默认值 | 默认配置中增加 `auth_method: 'header'`，防止启用 API Key 时抛 KeyError |
|
|
| 会话持久化 | 新增 `data/sessions.json` 持久化，服务重启后会话不丢失 |
|
|
| 动态路径解析 | 通过 `_resolve_hermes_home()` 动态获取 Hermes 路径，替代硬编码路径 |
|