JARVIS/development-doc/plan/hermes-update/phase-h2-continuity-envelope.md

H2 Continuity Envelope

1. 目标

把 Conversation.agent_state 从“当前 runtime 顺手写进去的状态桶”升级成 runtime-neutral continuity envelope。

2. 当前问题

当前状态里：

• Jarvis continuity 已较丰富
• Hermes runtime metadata 仍较浅
• 两边并没有统一的 envelope

风险是：

• Hermes session state 覆盖 Jarvis continuity
• 回滚时状态结构混乱
• 后端重启后难以恢复 runtime continuity

3. 目标结构

建议方向：

{
  "version": 2,
  "active_runtime": "hermes",
  "runtime_state": {
    "jarvis": { "...": "fallback/runtime snapshot" },
    "hermes": {
      "session_id": "...",
      "status": "warm|resumed|cold|error",
      "last_used_at": "...",
      "restart_count": 0,
      "health": { "...": "..." }
    }
  },
  "product_continuity": {
    "turn_context": {},
    "pending_action": {},
    "task_state": {},
    "memory_checkpoint": {}
  },
  "migration": {
    "source": "jarvis-legacy",
    "updated_at": "..."
  }
}

4. 核心原则

1. Jarvis 拥有产品 continuity。
2. Hermes 拥有 runtime continuity。
3. envelope 负责把两者挂在一起。
4. 不能让 Hermes session id 替代产品 continuity。

5. 影响范围

• backend/app/models/conversation.py
• backend/app/services/agent_service.py
• backend/app/agents/state.py
• backend/app/services/agent_runtime/hermes_session_manager.py

6. 历史兼容

本阶段必须考虑：

• 兼容旧 agent_state
• 兼容 Jarvis-only 历史 conversation
• 允许逐步迁移，不要求一次性重写所有旧数据

7. 完成标准

• agent_state 有统一 envelope 结构
• Jarvis continuity 与 Hermes runtime state 不再互相覆盖
• 老 conversation 可兼容读取
• 为 H3 durable lifecycle 提供恢复所需元数据