# 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 路径，替代硬编码路径 |