WIN-JHFT4D3SIVT\caoxiaozhu
21c869db62
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# 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、回滚策略。
|