JARVIS/development-doc/plan/hermes-update/phase-h-1-runtime-boundary.md

H-1 Runtime Adapter 边界

1. 目标

在不改变现有 Jarvis 默认行为的前提下，先把 chat 主流程改造成可切换 runtime 的结构。

核心思想：

• router 不变
• SSE 契约尽量不变
• AgentService 内新增 runtime 分发边界
• Jarvis 先被包装成默认 runtime
• Hermes 作为显式实验 runtime 并存

2. 当前主链路

当前 chat 路径：

frontend/useChatView.ts
  -> frontend/api/conversation.ts
  -> POST /api/conversations/chat/stream
  -> backend/app/routers/conversation.py
  -> backend/app/services/agent_service.py
  -> backend/app/agents/graph.py

问题在于：

• AgentService 直接耦合 Jarvis 图运行时
• 没有 runtime selector
• Hermes 无法以低风险方式并入

3. 本阶段目标结构

conversation router
  -> AgentService
      -> resolve runtime
      -> JarvisRuntimeAdapter | HermesRuntimeAdapter

3.1 关键要求

1. Jarvis 仍为默认 runtime
2. 不改现有 URL 和 SSE event name
3. 前端只需要传一个可选 runtime 字段
4. backend 可以继续把 Hermes 视为“可插拔执行器”

4. 数据契约

建议在 chat request 中增加：

• runtime: "jarvis" | "hermes" | null

规则：

• null / 未传：默认 jarvis
• jarvis：保持现有行为
• hermes：转入 Hermes adapter

5. 推荐文件调整

Backend

• backend/app/schemas/conversation.py
  • 增加 runtime 字段
• backend/app/services/agent_service.py
  • 增加 runtime 解析
  • 增加 runtime dispatch
• 新目录：backend/app/services/agent_runtime/
  • base.py
  • jarvis_runtime.py
  • hermes_runtime.py

Frontend

• frontend/src/api/conversation.ts
  • 请求体增加 runtime
• frontend/src/pages/chat/composables/useChatView.ts
  • 增加 selectedRuntime 状态

6. 约束

• 本阶段不要求 Hermes 已经完整可运行
• 允许先落 Hermes adapter 骨架
• 但不允许破坏 Jarvis 现有路径

7. 完成标准

• runtime 字段进入 request schema
• backend 已有 runtime dispatch 入口
• Jarvis 仍能正常完成原有 chat / chat_stream
• Hermes 可以作为占位 runtime 被请求到
• SSE 事件协议未被破坏