Hermes Service API

Hermes Service 是一个将 Hermes Agent CLI 能力封装为 REST API 的中间件服务。支持多用户隔离、会话持久化、IP/API Key 安全认证。

版本: v1.3.0 运行端口: 默认 9123 (可通过 config.yaml 修改)

---

启动方式

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

响应:

{
  "status": "healthy",
  "service": "hermes-service",
  "multi_user": true
}

2. 获取 Hermes 状态

GET /api/v1/status

响应:

{
  "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	否	初始消息（暂未使用）

响应:

{
  "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

响应:

{
  "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 获取）

响应:

{
  "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}

响应:

{
  "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)

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