76 lines
1.8 KiB
Markdown
76 lines
1.8 KiB
Markdown
|
# 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 契约
|