# 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、回滚策略。