JARVIS/development-doc/plan/hermes-update/phase-h1-agent-service-inversion.md

H1 AgentService 架构倒置

1. 目标

把 AgentService 从“Jarvis runtime 本体”重构成“Jarvis 产品层编排器”。

也就是说，AgentService 只做三件事：

1. request assembly
2. runtime dispatch
3. finalization

2. 当前问题

当前 backend/app/services/agent_service.py 同时承载：

• memory / retrospective / skills / task graph 装配
• Jarvis graph 执行
• Hermes runtime dispatch
• SSE 流组装
• message / agent_state / observability 持久化

这导致：

• Hermes 只能是分支，不是核心
• Jarvis runtime 难以真正 adapter 化
• 后续 fallback / rollout 容易继续堆在一个文件里

3. 目标结构

conversation router
  -> AgentService
      -> assemble runtime request
      -> resolve runtime via registry/factory
      -> dispatch to runtime adapter
      -> finalize persistence and observability

4. 关键动作

4.1 Request Assembly

保留在 Jarvis product shell：

• memory context
• retrospective
• skill shortlist
• task graph
• time context
• conversation continuity load

4.2 Runtime Dispatch

• 建立 runtime registry / factory
• JarvisRuntimeAdapter 正式承接旧 graph 路径
• HermesRuntimeAdapter 成为默认目标 runtime
• 避免 if runtime == ... 继续扩散

4.3 Finalization

• assistant message 落库
• attachments/runtime metadata 落库
• Conversation.agent_state 更新
• runtime observability report 持久化

5. 推荐文件变更

• backend/app/services/agent_service.py
• backend/app/services/agent_runtime/base.py
• backend/app/services/agent_runtime/jarvis_runtime.py
• backend/app/services/agent_runtime/hermes_runtime.py
• 可选新增：backend/app/services/agent_runtime/registry.py

6. 设计约束

1. 不破坏 router / API 路径。
2. 不改变前端 SSE 事件名。
3. Jarvis graph 在本阶段仍保留为 fallback。
4. 先把职责边界立住，再调整默认 runtime。

7. 完成标准

• AgentService 明确分为 assembly / dispatch / finalization
• Jarvis runtime 被正式 adapter 化
• Hermes path 不再只是散落的 if-branch
• 为 H2/H3 continuity 与 session lifecycle 留出清晰边界