# H-3 Hermes Adapter 与上下文复用

## 1. 目标

Hermes 只作为新的执行 runtime 接进来，不重新发明一套 Jarvis memory / context / chat protocol。

也就是说：
- Jarvis 已有的上下文构建能力继续复用
- Hermes 输出被适配为现有 chat 消息流
- 前端尽量不理解 Hermes 内部细节

## 2. 可复用能力

### 2.1 Memory
- `backend/app/services/memory_service.py`

继续复用：
- conversation summary
- recalled memory
- user memory
- knowledge brain 注入

### 2.2 Skill shortlist
- `backend/app/agents/skills/retriever.py`

继续复用：
- request 相关 skill shortlist

### 2.3 Task graph
- `backend/app/agents/orchestration/task_graph.py`

继续复用：
- bounded task graph
- parallel worthiness 等前置分析

## 3. 推荐数据流

```text
AgentService
  -> 读取 conversation / message / files
  -> 构建 memory context
  -> 构建 skill shortlist
  -> 构建 task graph / runtime request context
  -> 根据 runtime 分发
      -> JarvisRuntimeAdapter
      -> HermesRuntimeAdapter
```

这样 Hermes 看到的是**已整理好的 runtime context**，而不是被迫直接复用 Jarvis 图内部状态机。

## 4. SSE 契约保持不变

继续沿用现有事件：
- `metadata`
- `progress`
- `chunk`
- `error`
- `done`

### 4.1 原因

前端现有：
- `conversationApi.chatStream()` 已解析这套事件
- `useChatView.ts` 已依赖这套事件更新 thinking state / orchestration panel

如果这里大改，会让前端接入成本飙升。

### 4.2 Hermes event mapping

Hermes 内部即使没有完全等价事件，也应该适配成：
- 初始化 / session 准备 -> `progress`
- 实际文本输出 -> `chunk`
- 错误 -> `error`
- 完成 -> `done`

缺字段可以降级，但 event 名称不要改。

## 5. 持久化与可观测性

继续沿用：
- `Message` 表保存 user / assistant 内容
- `Conversation.agent_state` 保存 runtime continuity 元数据
- `attachments` 可用于记录 Hermes 运行附加信息

建议：
- 把 Hermes 观测信息放在 runtime-tagged attachment 中
- 不把探测日志直接渲染进用户可见消息正文

## 6. 边界约束

1. Hermes continuity 与 Jarvis continuity 分开存
2. 不要让 Hermes adapter 直接改写现有 Jarvis graph 状态格式
3. 前端不直接显示“终端字节流”
4. Hermes 适配失败时，必须 clean fail

## 7. 完成标准

- [ ] 现有 memory pipeline 可被 Hermes 复用
- [ ] 现有 skill shortlist / task graph 可被 Hermes 复用
- [ ] Hermes 输出成功映射到既有 SSE 契约
- [ ] assistant message 按现有结构持久化
- [ ] Hermes continuity 数据不覆盖 Jarvis continuity 数据