JARVIS/development-doc/plan/hermes-update/README.md

Hermes-first 重构计划索引

本目录用于沉淀 Jarvis 从“自研 agent 主流程 + Hermes 可选 adapter”转向 Hermes-first 架构 的分阶段计划。

目标不是把 Jarvis 砍掉重写，而是把架构中心调整为：

• Hermes：默认 execution core
• Jarvis：product shell，负责 chat UI、conversation/message 持久化、memory/knowledge/task、continuity、observability、rollback

---

当前目标

1. 不再把 Hermes 只看作可选 runtime，而是作为默认核心方向。
2. 保留 Jarvis 的产品价值，不把业务层能力粗暴塞进 Hermes 黑盒。
3. 保证 chat 仍是连续会话体验，不接受每轮冷启动。
4. 保持现有 /api/conversations/chat/stream 与 SSE 契约稳定。
5. 保留迁移期 fallback / 回滚能力，不做不可逆替换。

---

文档说明

文件	说明
README.md	总览、阶段关系、总体原则
adr-hermes-first-architecture.md	Hermes-first 的架构决策记录
phase-h0-ownership-and-adr.md	ownership matrix、边界与成功标准
phase-h1-agent-service-inversion.md	AgentService 从 runtime 本体转为产品层编排
phase-h2-continuity-envelope.md	Conversation.agent_state 的 runtime-neutral envelope
phase-h3-durable-session-lifecycle.md	Hermes durable session lifecycle
phase-h4-product-shell-assembly.md	Jarvis product shell 的 pre-runtime assembly
phase-h5-event-mapper-and-sse-contract.md	Hermes event -> Jarvis SSE mapper
phase-h6-frontend-hermes-first-session-model.md	前端从 runtime toggle 过渡到 Hermes-first session model
phase-h7-default-rollout-and-fallback.md	默认切换、灰度、fallback 与回滚
checklist.md	分阶段执行清单

---

推荐阅读顺序

1. adr-hermes-first-architecture.md
2. phase-h0-ownership-and-adr.md
3. phase-h1-agent-service-inversion.md
4. phase-h2-continuity-envelope.md
5. phase-h3-durable-session-lifecycle.md
6. phase-h4-product-shell-assembly.md
7. phase-h5-event-mapper-and-sse-contract.md
8. phase-h6-frontend-hermes-first-session-model.md
9. phase-h7-default-rollout-and-fallback.md
10. checklist.md

---

当前总体状态（2026-04-10）

Phase	状态	说明
H0	进行中	已明确从 adapter-first 转向 Hermes-first，需要先补完整文档
H1	待开始	AgentService 仍过于集中，Jarvis runtime 尚未完全 adapter 化
H2	待开始	Conversation.agent_state 尚未统一成 runtime-neutral envelope
H3	待开始	HermesSessionManager 仍偏进程内原型
H4	待开始	Jarvis 的 memory/skills/task graph 仍需固化为 product shell 装配层
H5	待开始	SSE 兼容已初步存在，但缺少稳定事件映射边界
H6	待开始	前端仍把 runtime 视作用户可切换字符串，而非 session model
H7	待开始	还没有服务端默认 runtime policy / rollout / fallback 策略

---

总体实施原则

1. 先文档后开发：先写清楚阶段文档，再按文档开发。
2. Hermes 做核心，Jarvis 做产品：不让 Jarvis 继续承担主 runtime 本体。
3. 连续对话优先：必须支持 warm session / resumed session，而不是每轮冷启动。
4. 契约稳定优先：前端继续消费稳定 SSE，不直接理解 Hermes 内部事件。
5. 渐进切换优先：迁移期间保留 fallback 和回滚，不做一次性替换。
6. 复用优先：memory、skill shortlist、task graph、conversation persistence 尽量保留为 Jarvis 产品层能力。

---

Ownership Matrix（摘要）

Hermes Core

• session lifecycle
• runtime resume / recovery
• turn execution loop
• chunk streaming
• runtime-internal tool loop

Jarvis Product Shell

• conversation/message persistence
• memory context assembly
• skill shortlist
• task graph
• product continuity
• SSE contract
• runtime observability
• rollout / fallback policy

Shared Contracts

• runtime prepared context
• runtime event model
• continuity envelope
• health / metrics metadata

---

阶段依赖图

H0 -> H1 -> H2 -> H3 -> H4 -> H5 -> H6 -> H7

说明：

• 没有 H1，就无法真正把 Jarvis 从 runtime 本体降级为产品层。
• 没有 H2/H3，就无法让 Hermes-first 具备可靠 continuity。
• 没有 H5/H6，前端会被 Hermes 内部细节污染。
• 没有 H7，就无法安全默认切换。

---

关键风险

1. 把 Hermes session id 错当成完整 continuity。
2. 让前端直接依赖 Hermes-native event 细节。
3. AgentService 持续膨胀成新的耦合中心。
4. runtime toggle 长期暴露为普通用户负担。
5. 只靠进程内 session manager，缺少 durable 恢复。
6. 没有 rollback policy 就直接默认切换。

---

当前代码锚点

Backend

• backend/app/services/agent_service.py
• backend/app/services/agent_runtime/base.py
• backend/app/services/agent_runtime/hermes_runtime.py
• backend/app/services/agent_runtime/hermes_session_manager.py
• backend/app/models/conversation.py
• backend/app/schemas/conversation.py
• backend/app/routers/conversation.py

Frontend

• frontend/src/api/conversation.ts
• frontend/src/pages/chat/composables/useChatView.ts
• frontend/src/pages/chat/index.vue
• frontend/src/stores/conversation.ts
• frontend/src/api/agent.ts

---

预期阶段结论

当本轮文档与实施完成后，应该达到：

• Hermes 成为默认 execution core 的明确落地方向。
• Jarvis 保留为 product shell，而不是继续扩展自研 runtime。
• chat 继续是消息流产品，不变成终端模拟器。
• 默认切换前拥有清晰的灰度、fallback、回滚策略。