JARVIS/development-doc/plan/hermes-update/phase-h5-event-mapper-and-sse-contract.md

H5 Event Mapper 与 SSE 契约

1. 目标

建立一层稳定的 Hermes event -> Jarvis SSE 映射边界，让前端无需理解 Hermes 内部事件模型。

2. 当前约束

前端当前主要依赖：

• frontend/src/api/conversation.ts
• frontend/src/pages/chat/composables/useChatView.ts

并假设 SSE 事件名为：

• metadata
• progress
• chunk
• error
• done

Hermes-first 改造不能让 UI 直接去消费 Hermes-native event。

3. 推荐映射原则

3.1 保持外部契约稳定

对前端继续输出：

• metadata
• progress
• chunk
• error
• done

3.2 Hermes richer event 不直接外泄

更细的 runtime 细节：

• tool trace
• retry/restart details
• health transitions
• session diagnostics

应该进入：

• runtime observability
• attachments
• agent_state metadata

而不是直接让 UI 依赖这些字段。

4. 推荐映射关系

• session prepare / hydrate / warm reuse -> progress
• assistant content delta -> chunk
• execution failure -> error
• finish signal -> done
• conversation/message identity -> metadata

5. 推荐文件变更

• 新增：backend/app/services/agent_runtime/hermes_event_mapper.py
• 修改：
  • backend/app/services/agent_runtime/hermes_runtime.py
  • backend/app/services/agent_service.py
  • frontend/src/api/conversation.ts（如需轻量兼容字段扩展）

6. 设计约束

1. SSE 事件名不破坏。
2. 前端 parser 不因 Hermes-first 被重写。
3. 缺失字段允许降级，但事件序列必须稳定。
4. 错误事件不能导致 assistant message 持久化乱序。

7. 完成标准

• Hermes runtime 有明确的 event mapping 边界
• 前端现有 SSE parser 继续可用
• richer diagnostics 有单独落点，不污染 UI 契约