# Hermes Agent 跨机器部署 — 需求文档

**日期**: 2026-06-20
**状态**: 已确认，待实现

## 概述

EternalAI 生成的角色配置（Soul.md + config.yaml）需要能直接复制到远程 Hermes Agent 中使用。EternalAI 服务器与 Hermes Agent 可能不在同一台机器上，用户通过 CLI 拉取命令（curl）跨机器获取配置文件。

## 用户场景

用户在 EternalAI Web UI 创建角色后，需要在另一台安装了 Hermes Agent 的机器上部署该角色。用户不希望 EternalAI 直接写入 Hermes 目录，而是生成可直接使用的文件，通过 curl 命令拉取后手动放置到 Hermes profile 目录。

## 工作流程

```
服务器 A (EternalAI)                    服务器 B (Hermes Agent)
┌─────────────────────┐                ┌─────────────────────┐
│ 1. 设置页生成 API Key│                │                     │
│    (eak_xxxxx)       │                │ 5. hermes profile   │
│                      │                │    create role-mio  │
│ 2. 创建角色 → 发布   │                │                     │
│    生成 Soul.md +    │                │ 6. curl 拉取文件    │
│    config.yaml       │                │    SOUL.md          │
│                      │                │    config.yaml      │
│ 3. 角色管理页显示    │  4. 用户复制   │                     │
│    curl 命令模板     │──── curl ────▶│ 7. 配置 .env        │
│    (含 API Key)      │    命令执行    │    (API 密钥)       │
│                      │                │                     │
│                      │                │ 8. role-mio chat    │
└─────────────────────┘                └─────────────────────┘
```

### 用户在 Hermes 机器上的操作

```bash
# 1. 创建 profile
hermes profile create role-mio

# 2. 拉取 SOUL.md
curl -H "Authorization: Bearer eak_xxx" \
     https://eternalai.example.com/api/hermes/roles/<id>/SOUL.md \
     -o ~/.hermes/profiles/role-mio/SOUL.md

# 3. 拉取 config.yaml
curl -H "Authorization: Bearer eak_xxx" \
     https://eternalai.example.com/api/hermes/roles/<id>/config.yaml \
     -o ~/.hermes/profiles/role-mio/config.yaml

# 4. 配置 API 密钥
echo "OPENROUTER_API_KEY=sk-or-xxx" > ~/.hermes/profiles/role-mio/.env

# 5. 启动
role-mio chat
```

## 功能需求

### 1. API Key 管理

- 用户在设置页生成长期 API Key（格式：`eak_` + 32 位随机 hex）
- API Key 列表显示：名称、创建时间、最后使用时间、Key（脱敏显示）
- 支持删除 API Key
- API Key 存储在数据库中，使用 bcrypt 哈希存储（只明文显示一次）

### 2. Hermes 配置 API

两个端点，均需 API Key 认证：

- `GET /api/hermes/roles/:id/SOUL.md` — 返回角色的 SOUL.md 内容（text/plain）
- `GET /api/hermes/roles/:id/config.yaml` — 返回适配后的 Hermes config.yaml（text/plain）

认证方式：`Authorization: Bearer eak_xxxxx`

权限：API Key 所属用户只能拉取自己创建的角色。

### 3. config.yaml 格式适配

EternalAI 数据库中的角色数据 → Hermes config.yaml 格式：

| EternalAI 字段 | Hermes config.yaml 字段 |
|---|---|
| `role.model` | `model:` |
| `role.temperature` | `temperature:` |
| `role.maxTokens` | `max_tokens:` |
| `role.enableMemory` | `memory.enabled:` |
| `role.enableTools` | `tools.enabled:` |

### 4. Web UI 部署指南

角色管理页每个角色卡片增加"Hermes 部署"区域：
- 显示完整的 curl 命令模板（自动填入服务器地址、角色 ID、API Key）
- 操作步骤说明
- 复制按钮

## 非功能需求

- API Key 使用 bcrypt 哈希存储，明文只在生成时显示一次
- Hermes API 端点返回 `text/plain` 格式，适合 curl 直接输出到文件
- config.yaml 适配在后端完成，用户拉取到的文件可直接使用