feat(docs): add development documentation, prototypes, and war-room components

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-04-11 08:49:41 +08:00
parent 1ca8855751
commit 21c869db62
1218 changed files with 11858 additions and 0 deletions
--- a/development-doc/plan/hermes-update/README.md
+++ b/development-doc/plan/hermes-update/README.md
@@ -0,0 +1,160 @@
+# 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
+
+---
+
+## 阶段依赖图
+
+```text
+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、回滚策略。
--- a/development-doc/plan/hermes-update/adr-hermes-first-architecture.md
+++ b/development-doc/plan/hermes-update/adr-hermes-first-architecture.md
@@ -0,0 +1,84 @@
+# ADR：Hermes-first 架构
+
+## 状态
+
+Accepted（进入实施规划）
+
+## 背景
+
+Jarvis 当前已经具备较强的自研 agent runtime 能力，但核心执行链路仍然偏自定义、偏集中式，导致：
+
+- 执行 runtime 与产品层耦合过深
+- Hermes 虽已接入真实 bridge，但仍只是 adapter 分支
+- 长驻 session、恢复、执行循环等能力没有形成更清晰的 runtime ownership
+- 前端虽然能切 runtime，但本质仍是 Jarvis-centered UX + backend branching
+
+同时，用户明确表达：
+
+- 更偏好 Hermes 的体系化能力
+- 不希望继续扩展自研 agent 主链路
+- 希望连续对话、常驻 session、不冷启动
+- 要求先文档后开发
+
+## 决策
+
+采用 **Hermes-first architecture**：
+
+- Hermes 成为默认 execution core
+- Jarvis 保留为 product shell
+- 旧 Jarvis graph 在迁移期保留为 fallback / specialist path
+- 前端继续使用 Jarvis chat product shell，而不是直接暴露 Hermes 终端形态
+- SSE 契约保持稳定，由 Jarvis 负责做 runtime event mapping
+
+## 责任边界
+
+### Hermes 负责
+- session lifecycle
+- runtime resume / restart / health
+- execution loop
+- chunk streaming
+- runtime-internal tool orchestration
+
+### Jarvis 负责
+- conversation/message persistence
+- memory / knowledge / retrospective assembly
+- skill shortlist
+- task graph shaping
+- product continuity envelope
+- SSE contract
+- observability / metrics / attachments
+- rollout / fallback / rollback policy
+
+## 不采用的方案
+
+### 方案 A：继续保持 adapter-first
+不采用原因：
+- Hermes 长期只会是支线 runtime
+- `AgentService` 会继续膨胀
+- 无法真正把架构中心从 Jarvis runtime 本体迁走
+
+### 方案 B：直接删除 Jarvis，自上而下改成 Hermes 原生产品
+不采用原因：
+- 会丢失 Jarvis 已有的 conversation、memory、task、业务层价值
+- 缺乏迁移和回滚路径
+- 风险过高
+
+## 影响
+
+正向影响：
+- runtime 职责更清晰
+- 长驻 session 方向更明确
+- 后续维护重心从“造 runtime”转向“做产品能力”
+
+负向影响：
+- 迁移期需要同时维护 Hermes default path 与 Jarvis fallback path
+- 需要重构 `AgentService` 和 continuity state
+- 需要补 durable lifecycle 和 rollout policy
+
+## 验收标准
+
+1. Hermes 成为默认 execution core。
+2. Jarvis 仍保留 product shell 能力。
+3. 多轮对话 continuity 不依赖每轮冷启动。
+4. SSE 前端契约保持稳定。
+5. 默认切换有灰度与回滚路径。
--- a/development-doc/plan/hermes-update/checklist.md
+++ b/development-doc/plan/hermes-update/checklist.md
@@ -0,0 +1,65 @@
+# Hermes-first 执行清单
+
+## H0 Ownership / ADR
+
+- [x] 新增 Hermes-first `README.md`
+- [x] 新增 ADR：Hermes-first architecture
+- [x] 明确 ownership matrix
+- [x] 明确 Jarvis product shell 与 Hermes core 的边界
+- [x] 明确成功标准与关键风险
+
+## H1 AgentService 架构倒置
+
+- [ ] 把 `AgentService` 明确拆分为 assembly / dispatch / finalization
+- [ ] 正式 adapter 化 Jarvis graph 路径
+- [ ] 引入 runtime registry / factory
+- [ ] 减少 `if runtime == ...` 的散落逻辑
+- [ ] 保持 router / SSE 契约不破坏
+
+## H2 Continuity Envelope
+
+- [ ] 设计统一 `Conversation.agent_state` envelope
+- [ ] 加入 `active_runtime`
+- [ ] 加入 `runtime_state.hermes`
+- [ ] 保留 Jarvis product continuity
+- [ ] 增加 migration/version metadata
+- [ ] 补充兼容旧状态读取策略
+
+## H3 Durable Session Lifecycle
+
+- [ ] 升级 `HermesSessionManager` 为 durable lifecycle manager
+- [ ] 支持 warm / resumed / cold 状态
+- [ ] 支持 hydrate / recreate / idle reclaim
+- [ ] 增加 health / restart / stale session 处理
+- [ ] 补充 session recovery 测试
+
+## H4 Product Shell Assembly
+
+- [ ] 固化 memory assembly
+- [ ] 固化 skill shortlist assembly
+- [ ] 固化 task graph assembly
+- [ ] 把这些能力统一收敛到 prepared context
+- [ ] 保证 Hermes 不直接吞掉产品层职责
+
+## H5 Event Mapper / SSE
+
+- [ ] 新增 Hermes event mapper 边界
+- [ ] 保持 `metadata/progress/chunk/error/done`
+- [ ] richer diagnostics 落到 observability / attachments
+- [ ] 保证前端 parser 无需重写
+
+## H6 Frontend Hermes-first Session Model
+
+- [ ] 减少 `jarvis` 默认 runtime 假设
+- [ ] 减少 Jarvis-specific runtime 文案耦合
+- [ ] 提升 session/run metadata 为一等状态
+- [ ] runtime toggle 收缩为灰度/调试能力
+- [ ] 保持 chat 仍是消息流体验
+
+## H7 Default Rollout / Fallback
+
+- [ ] 引入默认 runtime policy
+- [ ] 支持 cohort / feature flag rollout
+- [ ] 保留 Jarvis graph fallback 路径
+- [ ] 定义 rollback 条件与动作
+- [ ] 用真实对话与指标验证默认切换时机
--- a/development-doc/plan/hermes-update/phase-h-0-recon-and-poc.md
+++ b/development-doc/plan/hermes-update/phase-h-0-recon-and-poc.md
@@ -0,0 +1,112 @@
+# H-0 Hermes 现状探测与 PoC 边界
+
+## 1. 目标
+
+在不影响现有 Jarvis 主流程的前提下，确认 Hermes 是否适合作为 Jarvis chat 的可嵌入 runtime。
+
+本阶段只回答 4 个问题：
+
+1. Hermes 更适合如何接入：Python API、单次 CLI、长驻 CLI、gateway，还是其他形式？
+2. Hermes 是否支持 conversation 级别的长驻 session / resume？
+3. Hermes 是否能在后端被程序化调用，而不是只能人工交互？
+4. Hermes 的接入是否能保持 Jarvis 现有 chat 页面协议稳定？
+
+## 2. 当前已知信息
+
+### 2.1 来自 Hermes 仓库的直接结论
+
+- Hermes 主入口是 CLI：`hermes`
+- 提供 single query 模式：`-q` / `query`
+- 提供 `resume` 机制
+- 提供 gateway 模式
+- README 明确说明：原生 Windows 不受支持，建议 WSL2
+- `run_agent.py` 暴露了更直接的 Python 级 `chat(message, stream_callback=...)` 接口
+- 内部有 SQLite session store，说明其本身有 session persistence 概念
+
+### 2.2 对 Jarvis 的意义
+
+这说明 Hermes **不是只能人手操作的纯 TUI**，而是具备：
+
+- 单次 query 入口
+- session 恢复能力
+- Python 层 chat 接口
+- streaming callback 可能性
+
+因此它存在被 Jarvis 后端托管成 runtime 的现实基础。
+
+## 3. 本阶段输出
+
+### 3.1 必须验证的能力
+
+1. **安装方式**
+   - 是否能在当前环境隔离安装
+   - 是否需要迁移到 WSL2 才具备稳定运行条件
+
+2. **非交互调用能力**
+   - 是否能用 CLI 单次 query 跑通
+   - 是否能用 Python 直接调用 `run_agent.py` 的 chat 接口
+
+3. **session 能力**
+   - 是否能创建、恢复、复用 session
+   - 是否适合绑定 `conversation_id`
+
+4. **输出接法**
+   - 是否能通过 callback / stdout 获取稳定文本流
+   - 是否可被映射成 Jarvis 现有 SSE 事件
+
+### 3.2 不在本阶段做的事
+
+- 不改现有 Jarvis 默认运行链路
+- 不重写前端 chat 页面
+- 不直接删除或停用 LangGraph 主流程
+- 不引入一次性大迁移
+
+## 4. 推荐 PoC 边界
+
+### 4.1 推荐优先级
+
+1. **优先验证 Python chat 接口**
+   - 理由：比解析 TUI 更稳
+   - 若可行，首版桥接应优先走这个路径
+
+2. **其次验证 CLI 单次 query + resume**
+   - 作为备选方案
+   - 若 Python 接口不可控，可退而求其次
+
+3. **最后才考虑 TUI/PTY 桥接**
+   - 成本高
+   - 不适合作为 Jarvis chat 的第一接法
+
+### 4.2 PoC 成功标准
+
+- 能在隔离环境中启动 Hermes
+- 能程序化发送一条消息并得到结果
+- 能确认 session 可复用或可 resume
+- 能形成一个后端 runtime adapter 可实现的最小桥接思路
+
+## 5. 可能结论及后续影响
+
+### 结论 A：Python chat 接口稳定
+- 最优方案
+- H-1/H-2 直接围绕 Python adapter + session manager 展开
+
+### 结论 B：CLI `-q` + `resume` 稳定
+- 可接受
+- H-2 要更强调 session 句柄与进程生命周期管理
+
+### 结论 C：只能稳定跑 TUI
+- 风险显著升高
+- 需重新评估是否值得继续集成
+
+### 结论 D：当前环境无法稳定运行
+- 可能需要 WSL2 或远程服务化托管
+- 再决定是否继续推进
+
+## 6. 验证清单
+
+- [ ] 拉取 Hermes 仓库到隔离目录
+- [ ] 明确 install 依赖与 Python 版本要求
+- [ ] 确认单次 query 调用方式
+- [ ] 确认 Python chat 接口是否可用
+- [ ] 确认 session / resume 的可编程性
+- [ ] 记录接入建议结论，作为 H-1 输入
--- a/development-doc/plan/hermes-update/phase-h-1-runtime-boundary.md
+++ b/development-doc/plan/hermes-update/phase-h-1-runtime-boundary.md
@@ -0,0 +1,90 @@
+# H-1 Runtime Adapter 边界
+
+## 1. 目标
+
+在不改变现有 Jarvis 默认行为的前提下，先把 chat 主流程改造成**可切换 runtime** 的结构。
+
+核心思想：
+- router 不变
+- SSE 契约尽量不变
+- `AgentService` 内新增 runtime 分发边界
+- Jarvis 先被包装成默认 runtime
+- Hermes 作为显式实验 runtime 并存
+
+## 2. 当前主链路
+
+当前 chat 路径：
+
+```text
+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. 本阶段目标结构
+
+```text
+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 事件协议未被破坏
--- a/development-doc/plan/hermes-update/phase-h-2-long-lived-session-manager.md
+++ b/development-doc/plan/hermes-update/phase-h-2-long-lived-session-manager.md
@@ -0,0 +1,107 @@
+# H-2 长驻 Hermes Session Manager
+
+## 1. 目标
+
+让 Hermes 以 conversation 级别的长驻 session 运行，而不是每条消息都重新冷启动。
+
+这是本次接入最关键的用户体验目标：
+- 连续上下文
+- 无缝多轮对话
+- 降低重复初始化耗时
+- 避免“每次都像重新开机”
+
+## 2. 会话归属原则
+
+Hermes session 以 `conversation_id` 作为主键绑定。
+
+原因：
+1. Jarvis 现有 chat 的持久化中心本来就是 conversation
+2. 前后端现有逻辑都已围绕 conversation 组织
+3. conversation 是最自然的“连续对话上下文容器”
+
+必要时可组合：
+- `user_id + conversation_id`
+
+## 3. 会话管理职责
+
+建议新增 `HermesSessionManager`，负责：
+
+1. 根据 conversation 获取或创建 Hermes session
+2. 保存内存态句柄
+3. 记录 last_used 时间
+4. 做每会话锁，防止并发 turn 污染
+5. 做 idle timeout 回收
+6. 在异常时受控重建 session
+
+## 4. 与持久化层的关系
+
+### 4.1 内存态
+内存里保存：
+- session handle
+- lock
+- last_used
+- health status
+- restart count
+
+### 4.2 数据库存储
+建议把 Hermes runtime 元数据落入 `Conversation.agent_state`，但不要覆盖现有 Jarvis continuity。
+
+建议结构：
+
+```json
+{
+  "runtime": "jarvis | hermes",
+  "runtime_state": {
+    "jarvis": { ... },
+    "hermes": {
+      "session_id": "...",
+      "last_used_at": "...",
+      "restart_count": 0,
+      "status": "healthy"
+    }
+  }
+}
+```
+
+这样支持：
+- 并存
+- 切换
+- 回滚
+- 不破坏旧 continuity 数据
+
+## 5. 生命周期建议
+
+```text
+用户发起消息
+  -> 根据 conversation 找 session
+  -> 有则复用
+  -> 无则创建
+  -> 执行消息
+  -> 更新 last_used / 状态
+  -> 空闲超时后回收
+```
+
+### 5.1 回收策略
+- conversation 长时间无活动后可回收
+- 但回收前要把必要 runtime 元数据保存到 `agent_state`
+
+### 5.2 异常策略
+- 首次异常：尝试一次受控重建
+- 重建失败：返回 clean error
+- 不能因此破坏 Jarvis 默认路径
+
+## 6. 关键设计约束
+
+1. 一个 conversation 同一时刻只能有一个进行中的 Hermes turn
+2. 不允许两个并发消息写进同一个 Hermes session
+3. session manager 不能成为 Jarvis 主流程的单点故障
+4. Hermes 失败时，不能污染 conversation 的历史结构
+
+## 7. 完成标准
+
+- [ ] `conversation_id` 能稳定映射到 Hermes session
+- [ ] session 可复用，不是每轮冷启动
+- [ ] 有 per-conversation lock
+- [ ] 有 idle timeout / cleanup 机制
+- [ ] 有 crash / recreate 基础机制
+- [ ] metadata 可写入 `Conversation.agent_state`
--- a/development-doc/plan/hermes-update/phase-h-3-adapter-and-context-reuse.md
+++ b/development-doc/plan/hermes-update/phase-h-3-adapter-and-context-reuse.md
@@ -0,0 +1,102 @@
+# H-3 Hermes Adapter 与上下文复用
+
+## 1. 目标
+
+Hermes 只作为新的执行 runtime 接进来，不重新发明一套 Jarvis memory / context / chat protocol。
+
+也就是说：
+- Jarvis 已有的上下文构建能力继续复用
+- Hermes 输出被适配为现有 chat 消息流
+- 前端尽量不理解 Hermes 内部细节
+
+## 2. 可复用能力
+
+### 2.1 Memory
+- `backend/app/services/memory_service.py`
+
+继续复用：
+- conversation summary
+- recalled memory
+- user memory
+- knowledge brain 注入
+
+### 2.2 Skill shortlist
+- `backend/app/agents/skills/retriever.py`
+
+继续复用：
+- request 相关 skill shortlist
+
+### 2.3 Task graph
+- `backend/app/agents/orchestration/task_graph.py`
+
+继续复用：
+- bounded task graph
+- parallel worthiness 等前置分析
+
+## 3. 推荐数据流
+
+```text
+AgentService
+  -> 读取 conversation / message / files
+  -> 构建 memory context
+  -> 构建 skill shortlist
+  -> 构建 task graph / runtime request context
+  -> 根据 runtime 分发
+      -> JarvisRuntimeAdapter
+      -> HermesRuntimeAdapter
+```
+
+这样 Hermes 看到的是**已整理好的 runtime context**，而不是被迫直接复用 Jarvis 图内部状态机。
+
+## 4. SSE 契约保持不变
+
+继续沿用现有事件：
+- `metadata`
+- `progress`
+- `chunk`
+- `error`
+- `done`
+
+### 4.1 原因
+
+前端现有：
+- `conversationApi.chatStream()` 已解析这套事件
+- `useChatView.ts` 已依赖这套事件更新 thinking state / orchestration panel
+
+如果这里大改，会让前端接入成本飙升。
+
+### 4.2 Hermes event mapping
+
+Hermes 内部即使没有完全等价事件，也应该适配成：
+- 初始化 / session 准备 -> `progress`
+- 实际文本输出 -> `chunk`
+- 错误 -> `error`
+- 完成 -> `done`
+
+缺字段可以降级，但 event 名称不要改。
+
+## 5. 持久化与可观测性
+
+继续沿用：
+- `Message` 表保存 user / assistant 内容
+- `Conversation.agent_state` 保存 runtime continuity 元数据
+- `attachments` 可用于记录 Hermes 运行附加信息
+
+建议：
+- 把 Hermes 观测信息放在 runtime-tagged attachment 中
+- 不把探测日志直接渲染进用户可见消息正文
+
+## 6. 边界约束
+
+1. Hermes continuity 与 Jarvis continuity 分开存
+2. 不要让 Hermes adapter 直接改写现有 Jarvis graph 状态格式
+3. 前端不直接显示“终端字节流”
+4. Hermes 适配失败时，必须 clean fail
+
+## 7. 完成标准
+
+- [ ] 现有 memory pipeline 可被 Hermes 复用
+- [ ] 现有 skill shortlist / task graph 可被 Hermes 复用
+- [ ] Hermes 输出成功映射到既有 SSE 契约
+- [ ] assistant message 按现有结构持久化
+- [ ] Hermes continuity 数据不覆盖 Jarvis continuity 数据
--- a/development-doc/plan/hermes-update/phase-h-4-frontend-toggle-and-evaluation.md
+++ b/development-doc/plan/hermes-update/phase-h-4-frontend-toggle-and-evaluation.md
@@ -0,0 +1,85 @@
+# H-4 前端切换与并行评估
+
+## 1. 目标
+
+让 chat 页面在尽量不改变现有体验的前提下，支持切换 `jarvis | hermes`，并进入受控评估期。
+
+重点不是做新 UI，而是：
+- 能切换 runtime
+- 能继续对话
+- 能收集真实效果
+- 不影响现有默认使用路径
+
+## 2. 前端最小改动原则
+
+### 2.1 继续复用现有页面
+主要锚点：
+- `frontend/src/pages/chat/composables/useChatView.ts`
+- `frontend/src/api/conversation.ts`
+- `frontend/src/pages/chat/index.vue`
+
+### 2.2 最小改动内容
+
+1. 增加 `selectedRuntime`
+2. 在发送消息时把 runtime 放入 request body
+3. 页面可加一个轻量 toggle / selector
+4. 不改变现有消息渲染逻辑
+5. 不把页面改造成“网页终端”
+
+## 3. 评估期策略
+
+### 3.1 默认值
+- Jarvis 仍为默认 runtime
+- Hermes 为显式选择项
+
+### 3.2 评估维度
+
+必须记录：
+- 首 token 延迟
+- 完整回复耗时
+- 第二轮/第三轮连续对话体验
+- session 是否稳定复用
+- 工具调用效果
+- memory 是否有效承接
+- 异常率 / 重启率
+- 开发维护复杂度
+
+### 3.3 用户体验标准
+
+如果 Hermes 要成为默认 runtime，至少应满足：
+1. 不比 Jarvis 更割裂
+2. 不出现频繁 session 丢失
+3. 前端不需要额外理解复杂运行细节
+4. 整体体验更像连续助手而不是一次性问答器
+
+## 4. 验收建议
+
+### Frontend
+- [ ] Jarvis 默认聊天体验不变
+- [ ] 可切换到 Hermes 并成功发消息
+- [ ] 历史会话读取不崩
+- [ ] orchestration panel 不因 Hermes 字段较少而崩溃
+
+### Backend
+- [ ] Hermes 路径不影响 Jarvis 默认路径
+- [ ] SSE 解析不需要重写
+- [ ] conversation/message 结构保持兼容
+
+### Product
+- [ ] 可以真实比较两个 runtime
+- [ ] 结论可支持“继续替换”或“放弃替换”
+
+## 5. 阶段结论输出
+
+本阶段结束后，应明确给出以下结论之一：
+
+### 结论 A：Hermes 明显更优
+- 新开一轮“默认切换 / 逐步替换”规划
+
+### 结论 B：Hermes 可保留为实验 runtime
+- 不切默认
+- 继续特定场景使用
+
+### 结论 C：Hermes 不适合当前 Jarvis
+- 中止替换计划
+- 保留本轮探索结论供后续参考
--- a/development-doc/plan/hermes-update/phase-h0-ownership-and-adr.md
+++ b/development-doc/plan/hermes-update/phase-h0-ownership-and-adr.md
@@ -0,0 +1,87 @@
+# H0 Ownership Matrix 与架构决策
+
+## 1. 目标
+
+先把 Hermes-first 的 ownership matrix、边界和成功标准写清楚，防止后续开发过程中又回到“先写 adapter，最后发现架构中心没变”。
+
+## 2. 核心判断
+
+这轮改造的目标不是：
+
+- 给 Jarvis 再挂一个更强的 runtime adapter
+
+而是：
+
+- 让 Hermes 成为默认 execution core
+- 让 Jarvis 退回 product shell
+
+## 3. Ownership Matrix
+
+### 3.1 Hermes Core
+
+Hermes 应负责：
+
+1. session lifecycle
+2. runtime resume / recovery
+3. execution loop
+4. chunk streaming
+5. runtime-internal tool orchestration
+6. runtime health / restart metadata
+
+### 3.2 Jarvis Product Shell
+
+Jarvis 应负责：
+
+1. conversation / message 持久化
+2. user / auth / permission 边界
+3. memory context assembly
+4. retrospective / knowledge 注入
+5. skill shortlist
+6. task graph / parallel worthiness 分析
+7. product continuity
+8. SSE contract
+9. observability / attachments / metrics
+10. rollout / fallback / rollback policy
+
+### 3.3 Shared Contracts
+
+需要显式建模的共享边界：
+
+1. runtime prepared context
+2. runtime event model
+3. continuity envelope
+4. session health metadata
+5. rollout policy metadata
+
+## 4. 关键边界原则
+
+1. 不把 Hermes session id 直接当成完整 continuity。
+2. 不让前端直接依赖 Hermes-native event。
+3. 不把 memory / skill / task graph 直接挪进 Hermes 黑盒。
+4. 不让 `AgentService` 继续充当 runtime 本体。
+5. 不把 runtime 选择长期暴露为普通用户负担。
+
+## 5. 目标文件锚点
+
+### 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`
+
+### Frontend
+- `frontend/src/api/conversation.ts`
+- `frontend/src/pages/chat/composables/useChatView.ts`
+- `frontend/src/stores/conversation.ts`
+
+## 6. 成功标准
+
+- [ ] Hermes-first 的 ownership matrix 被写清楚
+- [ ] 保留 Jarvis product shell 的范围被写清楚
+- [ ] fallback / rollback 必须存在这一点被写清楚
+- [ ] 后续 phase 的顺序依赖被写清楚
+
+## 7. 本阶段结论
+
+只有先把 ownership 定义清楚，后面 H1-H7 才不会演变成“代码改了很多，但架构中心没有变”。
--- a/development-doc/plan/hermes-update/phase-h1-agent-service-inversion.md
+++ b/development-doc/plan/hermes-update/phase-h1-agent-service-inversion.md
@@ -0,0 +1,82 @@
+# 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. 目标结构
+
+```text
+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 留出清晰边界
--- a/development-doc/plan/hermes-update/phase-h2-continuity-envelope.md
+++ b/development-doc/plan/hermes-update/phase-h2-continuity-envelope.md
@@ -0,0 +1,76 @@
+# 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. 目标结构
+
+建议方向：
+
+```json
+{
+  "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 提供恢复所需元数据
--- a/development-doc/plan/hermes-update/phase-h3-durable-session-lifecycle.md
+++ b/development-doc/plan/hermes-update/phase-h3-durable-session-lifecycle.md
@@ -0,0 +1,71 @@
+# H3 Durable Session Lifecycle
+
+## 1. 目标
+
+把 `HermesSessionManager` 从“进程内 session 缓存”升级成支持恢复、重建、观测的 durable lifecycle manager。
+
+## 2. 当前问题
+
+当前 `backend/app/services/agent_runtime/hermes_session_manager.py` 已有：
+- conversation -> session 基础映射
+- per-conversation lock
+- last_used / restart_count / metadata
+
+但它仍然偏原型：
+- 依赖当前进程内内存
+- 后端重启后的恢复能力不足
+- warm / resumed / cold 没有显式状态
+- recovery policy 不够清晰
+
+## 3. 生命周期目标
+
+```text
+message arrives
+  -> lookup by conversation
+  -> warm session exists? reuse
+  -> else hydrate from agent_state
+  -> if hydrate success => resumed
+  -> else create fresh => cold
+  -> execute turn
+  -> update state/metrics
+  -> idle reclaim if needed
+```
+
+## 4. 必要能力
+
+1. warm / resumed / cold 状态区分
+2. conversation 级别锁
+3. runtime health 检查
+4. restart / recreate 策略
+5. idle reclaim
+6. safe rehydrate
+7. stale session 检测
+8. error 状态记录
+
+## 5. 与 envelope 的关系
+
+持久化来源：
+- `Conversation.agent_state.runtime_state.hermes`
+
+运行态来源：
+- `HermesSessionManager`
+
+原则：
+- warm session 提升性能
+- durable metadata 保障可恢复性
+- 不能要求一个 Hermes 进程永远不死
+
+## 6. 推荐文件变更
+
+- `backend/app/services/agent_runtime/hermes_session_manager.py`
+- `backend/app/services/agent_runtime/hermes_runtime.py`
+- `backend/app/services/agent_service.py`
+- `backend/app/models/conversation.py`
+- 新增或补充测试：session resume / recreate / restart / idle reclaim
+
+## 7. 完成标准
+
+- [ ] conversation 能恢复到正确 Hermes session 或重建新 session
+- [ ] warm / resumed / cold 状态可区分
+- [ ] 后端重启后 continuity 不直接断裂
+- [ ] recovery/failure 有清晰记录
--- a/development-doc/plan/hermes-update/phase-h4-product-shell-assembly.md
+++ b/development-doc/plan/hermes-update/phase-h4-product-shell-assembly.md
@@ -0,0 +1,83 @@
+# H4 Product Shell Assembly
+
+## 1. 目标
+
+固化 Jarvis 在 Hermes-first 架构中的角色：Jarvis 不是 runtime 本体，而是 **pre-runtime product shell**。
+
+## 2. 为什么保留 Jarvis Product Shell
+
+如果直接把 memory / skill / task graph 也推给 Hermes：
+- Jarvis 已有产品价值会丢失
+- 业务能力会进入黑盒
+- 回滚与可观测性会变差
+
+所以 Hermes-first 不等于“Jarvis 退化成纯 UI”。
+
+## 3. 保留的装配能力
+
+### 3.1 Memory Assembly
+- `backend/app/services/memory_service.py`
+
+继续负责：
+- recalled memory
+- conversation summary
+- user memory
+- knowledge brain 注入
+
+### 3.2 Skill Shortlist
+- `backend/app/agents/skills/retriever.py`
+
+继续负责：
+- request 相关 skill shortlist
+- 激活建议
+
+### 3.3 Task Graph / Runtime Request Context
+- `backend/app/agents/orchestration/task_graph.py`
+- `backend/app/agents/schemas/orchestration.py`
+
+继续负责：
+- bounded task graph
+- parallel worthiness
+- runtime request summary
+
+### 3.4 Retrospective / Product Guardrails
+- `backend/app/agents/learning/*`
+- `backend/app/agents/tools/time_reasoning.py`
+
+继续负责：
+- retrospective 注入
+- 时间上下文
+- 产品级指令与 guardrails
+
+## 4. 目标数据流
+
+```text
+router
+  -> AgentService
+      -> load conversation/product continuity
+      -> assemble memory/skills/task graph/retrospective/time context
+      -> build RuntimePreparedContext
+      -> dispatch to Hermes runtime
+      -> map events and finalize persistence
+```
+
+## 5. 关键原则
+
+1. Hermes 接收的是已组装好的 Jarvis product context。
+2. Jarvis 保留用户级/产品级理解能力。
+3. 不把 Hermes 当作唯一知识与策略拥有者。
+4. 装配层必须可测试、可观察、可回滚。
+
+## 6. 推荐文件变更
+
+- `backend/app/services/agent_service.py`
+- `backend/app/services/memory_service.py`
+- `backend/app/agents/skills/retriever.py`
+- `backend/app/agents/orchestration/task_graph.py`
+- `backend/app/services/agent_runtime/base.py`
+
+## 7. 完成标准
+
+- [ ] Jarvis product shell 的装配职责被明确固化
+- [ ] Hermes 收到的是统一的 prepared context
+- [ ] memory / skills / task graph 不被直接塞回 Hermes 黑盒内部
--- a/development-doc/plan/hermes-update/phase-h5-event-mapper-and-sse-contract.md
+++ b/development-doc/plan/hermes-update/phase-h5-event-mapper-and-sse-contract.md
@@ -0,0 +1,75 @@
+# 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 契约
--- a/development-doc/plan/hermes-update/phase-h6-frontend-hermes-first-session-model.md
+++ b/development-doc/plan/hermes-update/phase-h6-frontend-hermes-first-session-model.md
@@ -0,0 +1,68 @@
+# H6 前端 Hermes-first Session Model
+
+## 1. 目标
+
+让前端从“runtime toggle + Jarvis 默认假设”过渡到 **Hermes-first session model**。
+
+## 2. 当前问题
+
+当前前端已经支持：
+- `runtime: 'jarvis' | 'hermes'`
+
+但本质上仍存在：
+- 默认 runtime = jarvis
+- 大量 Jarvis-specific 文案与状态
+- runtime 只是一个请求字符串
+- session/run metadata 不是一等状态
+
+## 3. 方向
+
+前端长期目标不是让用户一直选 runtime，而是：
+- 普通用户默认走 Hermes-first 路径
+- runtime toggle 仅保留给灰度、调试、回滚
+- conversation/session/run metadata 进入更明确的状态模型
+
+## 4. 推荐调整点
+
+### 4.1 Transport Layer
+- `frontend/src/api/conversation.ts`
+
+保持 transport 职责，不再承载过多 runtime 语义。
+
+### 4.2 Chat Runtime State
+- `frontend/src/pages/chat/composables/useChatView.ts`
+- `frontend/src/stores/conversation.ts`
+
+需要逐步减少：
+- `selectedRuntime = 'jarvis'` 这类默认假设
+- `jarvisNote` / `JARVIS THINKING` 等强绑定文案
+- 仅靠本地拼装 model label 的方式
+
+### 4.3 Session/Run Metadata
+建议逐步提升为一等状态：
+- active runtime
+- run status
+- session status（warm/resumed/cold）
+- runtime diagnostics summary
+
+## 5. UI 原则
+
+1. chat 仍是消息流，不变成终端模拟器。
+2. 普通用户不需要长期理解 runtime 架构。
+3. 迁移期保留 toggle，但它属于 admin/dev 工具。
+4. 历史 conversation 渲染逻辑应尽量保持稳定。
+
+## 6. 推荐文件变更
+
+- `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`
+
+## 7. 完成标准
+
+- [ ] 前端减少 Jarvis-default 假设
+- [ ] runtime toggle 可转向灰度/调试用途
+- [ ] session/run metadata 开始成为一等状态
+- [ ] 普通聊天体验保持稳定
--- a/development-doc/plan/hermes-update/phase-h7-default-rollout-and-fallback.md
+++ b/development-doc/plan/hermes-update/phase-h7-default-rollout-and-fallback.md
@@ -0,0 +1,66 @@
+# H7 默认切换、灰度与 Fallback
+
+## 1. 目标
+
+让 Hermes 从“可选 runtime”安全过渡为默认路径，同时保留 fallback 与回滚能力。
+
+## 2. 核心原则
+
+1. 不做一次性全量切换。
+2. 默认切换必须由服务端策略控制。
+3. Jarvis graph 在迁移期保留为 fallback / specialist path。
+4. 回滚不能破坏 conversation/message 数据。
+
+## 3. 推荐 rollout 顺序
+
+### Stage 1：显式 opt-in
+- 仅对开发/内部用户开放
+- 用户可显式选择 Hermes
+
+### Stage 2：内部默认 Hermes
+- 对内部账号或灰度 cohort 默认走 Hermes
+- 保留 fallback 开关
+
+### Stage 3：新会话默认 Hermes
+- 仅新 conversation 默认 Hermes
+- 历史 conversation 可按策略维持原路径或迁移
+
+### Stage 4：全量默认 Hermes
+- 普通用户默认走 Hermes-first
+- runtime toggle 从主 UI 淡出
+
+## 4. Fallback 策略
+
+触发 fallback 的场景示例：
+- Hermes session hydrate 失败
+- Hermes runtime health 不达标
+- 连续 error/restart 达到阈值
+- 某类 specialist workflow 尚未迁移
+
+fallback 目标：
+- 切回 Jarvis graph 或受控备用路径
+- 不丢 conversation continuity
+- 不破坏前端 SSE 契约
+
+## 5. 回滚要求
+
+1. 服务端可按 feature flag / policy 回滚默认 runtime。
+2. 不要求修改前端主交互逻辑即可回滚。
+3. 历史 conversation 的 `agent_state` 仍能兼容读取。
+4. 回滚后仍可保留 Hermes metrics 用于复盘。
+
+## 6. 推荐文件变更
+
+- `backend/app/services/agent_service.py`
+- `backend/app/routers/conversation.py`
+- `backend/app/schemas/conversation.py`
+- `frontend/src/pages/chat/composables/useChatView.ts`
+- `frontend/src/pages/chat/index.vue`
+- 可能新增：runtime policy / feature flag 配置模块
+
+## 7. 验收标准
+
+- [ ] 有清晰 rollout policy
+- [ ] 有 fallback 策略
+- [ ] 有 rollback 机制
+- [ ] Hermes 默认切换不会成为不可逆操作