611 lines
16 KiB
Markdown
611 lines
16 KiB
Markdown
# Beaver Backend Flow
|
||
|
||
这份文档只记录两件事：
|
||
|
||
1. 我们**为什么这么实现**
|
||
2. 当前代码里**真实已经实现了什么**
|
||
|
||
它不是蓝图，也不是未来设计草稿。以后只要主链、装配逻辑、运行时边界发生变化，就必须同步更新它。
|
||
|
||
---
|
||
|
||
## 1. 参考项目各自借什么
|
||
|
||
当前 Beaver 的实现思路，主要借了三个参考项目，但借的点是分开的。
|
||
|
||
### 1.1 `OpenHarness`
|
||
|
||
借的是**模块边界和 Harness 形态**：
|
||
|
||
1. `Harness / Runtime` 应该和 Web、Gateway、产品接入分开
|
||
2. `skills / memory / tools / session / orchestration` 都属于平台层
|
||
3. 运行时最好是可装配的，而不是所有逻辑都塞进一个大 agent 类
|
||
|
||
所以 Beaver 现在一直在做的事情，是把：
|
||
|
||
- `EngineLoader`
|
||
- `AgentLoop`
|
||
- `ContextBuilder`
|
||
- `Session`
|
||
- `Tools`
|
||
- `Skills`
|
||
|
||
收成一个清晰的运行内核。
|
||
|
||
### 1.2 `hermes-agent`
|
||
|
||
借的是**memory、skills、session 的运行时风格**：
|
||
|
||
1. memory 用 curated CRUD + frozen snapshot
|
||
2. `session_search` 查历史细节，不把所有历史都塞进 memory
|
||
3. skills 用：
|
||
- 显式 skill loading path
|
||
- 激活后的 skill 正文显式注入
|
||
|
||
所以 Beaver 现在这些点都明显受 Hermes 影响：
|
||
|
||
1. `MemoryService` + frozen snapshot
|
||
2. `session_search`
|
||
3. `skill_view`
|
||
4. activated skill messages
|
||
|
||
### 1.3 `swarms`
|
||
|
||
借的是**后面多智能体 orchestration 的方向**：
|
||
|
||
1. team orchestration
|
||
2. swarm strategy
|
||
3. multi-agent execution backend
|
||
|
||
但要注意：它现在**还不是当前主链的核心**。
|
||
当前我们主要先把单 agent runtime 打稳，多智能体还没正式接回主链。
|
||
|
||
---
|
||
|
||
## 2. 当前我们到底做到哪了
|
||
|
||
当前已经不是“搭骨架”阶段了，而是：
|
||
|
||
**最小单 agent runtime 已经跑通。**
|
||
|
||
现在已经完成的核心段落是：
|
||
|
||
1. `4.1 session`
|
||
2. `4.2 provider`
|
||
3. `4.3 context`
|
||
4. `4.4 tools`
|
||
5. `4.5 最小主链`
|
||
6. `5.1 memory 最小接入`
|
||
7. `5.2 skills 最小接入`
|
||
8. `6.1 session-first / event-source 第一阶段`
|
||
|
||
更准确地说，当前 Beaver 已经有：
|
||
|
||
1. 一个可运行的 `AgentService -> AgentLoop` 主链
|
||
2. 一个外部化的 Session 子系统
|
||
3. 一个可工作的 tool loop
|
||
4. Hermes 风格的 memory / skills 接入
|
||
5. LLM-driven 的 `SkillAssembler`
|
||
|
||
但还没有：
|
||
|
||
1. 更完整的 shutdown hooks
|
||
2. Web / Gateway 的 bus / channels / realtime 全量接入
|
||
3. delegation / swarm / team runtime
|
||
4. 权限系统
|
||
5. MCP 全量工具接回 runtime
|
||
|
||
---
|
||
|
||
## 3. 当前真实主链
|
||
|
||
当前主入口已经不是 CLI 逻辑，而是：
|
||
|
||
```python
|
||
service = AgentService()
|
||
await service.process_direct("你好")
|
||
```
|
||
|
||
同时，第 6 阶段的最小运行循环已经有了：
|
||
|
||
```python
|
||
service = AgentService()
|
||
await service.start()
|
||
result = await service.submit_direct("你好")
|
||
await service.stop()
|
||
service.close()
|
||
```
|
||
|
||
宿主层现在也已经开始接到这条 lifecycle 上：
|
||
|
||
```python
|
||
app = create_app() # FastAPI lifespan 内部托管 AgentService.start()/shutdown()
|
||
await run_gateway() # Gateway 常驻进程托管 AgentService.start()/shutdown()
|
||
```
|
||
|
||
这套 lifecycle 当前明确是：
|
||
|
||
1. `start()` 进入一个 `AgentLoop` 实例的运行模式
|
||
2. 运行模式下，外部任务只能走 `submit_direct()`
|
||
3. 运行模式下，不允许再直接调用 `process_direct()`
|
||
4. `stop()` 是 **instance-scoped**
|
||
- 只针对当前这个 `AgentLoop` 实例
|
||
- 不是 session-scoped
|
||
- 也不是 platform-scoped
|
||
5. `stop()` 调用后会拒绝新任务，已入队任务正常收尾
|
||
6. `stop()` / `shutdown()` 支持 graceful timeout；必要时可 force cancel
|
||
7. `close()` 只能在该实例已停止后调用
|
||
|
||
### 3.1 Web / Gateway 当前怎么接
|
||
|
||
这一层现在已经不是纯占位了，而是最小宿主层：
|
||
|
||
1. `beaver/interfaces/web/app.py`
|
||
- FastAPI lifespan 启动时：
|
||
- 创建或接收 `AgentService`
|
||
- 如果 app 自己创建 service，则 `await service.start()`
|
||
- Web 接口现在有最小正式 schema：
|
||
- `WebChatRequest`
|
||
- `WebChatResponse`
|
||
- `WebStatusResponse`
|
||
- `/api/chat` 请求：
|
||
- 用结构化 request schema 校验输入
|
||
- `await service.submit_direct(...)`
|
||
- 把常见 runtime / config 错误收成 HTTP 错误
|
||
- 外部注入但尚未进入 running mode 的 service，会返回 `503`
|
||
- `/api/ping`：
|
||
- 返回 `status/running/mode`
|
||
- 不会为了 health check 额外 boot runtime
|
||
- app 关闭时：
|
||
- 如果 app 自己创建 service，则 `await service.shutdown(timeout_seconds=5.0, force=True)`
|
||
- app 自己接管 lifecycle 时：
|
||
- 若 `start()` 失败，会立即 `close()` 做 startup cleanup
|
||
|
||
2. `beaver/interfaces/gateway/main.py`
|
||
- `run_gateway()` 启动时：
|
||
- 如果 gateway 自己创建 service，则 `await service.start()`
|
||
- 持有最小 `MessageBus`
|
||
- 常驻消费 `bus.inbound`
|
||
- 调 `await service.submit_direct(...)`
|
||
- 把结果写回 `bus.outbound`
|
||
- 同时等待 `stop_event`
|
||
- 退出时：
|
||
- 先尝试 `await service.shutdown(timeout_seconds=5.0, force=True)`
|
||
- 再等待 bridge 协程收尾；必要时取消 bridge
|
||
- 如果 gateway 自己接管 lifecycle 且 `start()` 失败：
|
||
- 会立即 `close()` 做 startup cleanup
|
||
- 未处理完的 inbound：
|
||
- 不再静默丢下
|
||
- 会被冲刷成结构化 outbound error
|
||
|
||
3. `beaver/foundation/events/message_bus.py`
|
||
- 已有最小：
|
||
- `MessageBus`
|
||
- `InboundMessage`
|
||
- `OutboundMessage`
|
||
- 当前只做双队列桥接：
|
||
- `inbound`
|
||
- `outbound`
|
||
- 还没有 broker / topic routing / retry / persistence
|
||
|
||
所以现在已经明确：
|
||
|
||
1. Web / Gateway 属于宿主层
|
||
2. 它们不直接 new `AgentLoop` 或绕过运行模式
|
||
3. 它们复用：
|
||
- `start()`
|
||
- `submit_direct()`
|
||
- `stop()`
|
||
- `shutdown()`
|
||
4. ownership 语义：
|
||
- 自己创建的 `AgentService`：自己负责 lifecycle
|
||
- 外部注入的 `AgentService`：默认不自动 start/shutdown，除非显式要求接管
|
||
5. gateway 已经从“只会常驻等待”推进到“最小消息桥接层”
|
||
- external inbound message
|
||
- `MessageBus.inbound`
|
||
- `service.submit_direct(...)`
|
||
- `MessageBus.outbound`
|
||
|
||
### 3.2 总体链路
|
||
|
||
当前代码里的主链可以概括成：
|
||
|
||
```text
|
||
AgentService
|
||
-> AgentLoop
|
||
-> Session
|
||
-> Memory
|
||
-> SkillAssembler
|
||
-> ContextBuilder
|
||
-> Provider
|
||
-> ToolExecutor
|
||
-> Session writeback
|
||
```
|
||
|
||
### 3.3 详细顺序
|
||
|
||
```text
|
||
用户输入 task
|
||
│
|
||
├─ AgentService.create_loop()
|
||
│ ├─ 创建 AgentLoop(profile, loader)
|
||
│ └─ loop.boot()
|
||
│
|
||
├─ AgentLoop.boot()
|
||
│ └─ EngineLoader.load()
|
||
│ ├─ SessionManager
|
||
│ ├─ MemoryStore
|
||
│ ├─ MemoryService
|
||
│ ├─ ToolRegistry
|
||
│ ├─ ToolExecutor
|
||
│ ├─ SkillsLoader
|
||
│ ├─ SkillAssembler
|
||
│ └─ ContextBuilder
|
||
│
|
||
├─ AgentLoop.process_direct(task)
|
||
│ │
|
||
│ ├─ 生成 `session_id` / `run_id`
|
||
│ │
|
||
│ ├─ memory_service.reload_for_new_run()
|
||
│ │ └─ 建立本轮 frozen memory snapshot
|
||
│ │
|
||
│ ├─ sessions.ensure_session(session_id)
|
||
│ ├─ sessions.append_message(event_type="run_started", hidden)
|
||
│ │
|
||
│ ├─ make_provider_bundle()
|
||
│ │ ├─ main provider
|
||
│ │ ├─ fallback provider
|
||
│ │ ├─ auxiliary provider 可用于 skill 选择
|
||
│ │ └─ embedding runtime 提供 embeddings 的 model/api_key/api_base
|
||
│ │ 说明：它是独立配置线，只支持 OpenAI-compatible embeddings endpoint
|
||
│ │
|
||
│ ├─ skill_assembler.assemble(task_description=task, provider=selector_provider, embedding_runtime=..., ...)
|
||
│ │ ├─ 读取全量可用 skill 候选摘要
|
||
│ │ ├─ 用 `text-embedding-v4` 对全量候选做相似度召回
|
||
│ │ ├─ 把召回结果交给 LLM 做最终选择
|
||
│ │ └─ 返回 activated_skills
|
||
│ │
|
||
│ ├─ ContextBuilder.build_skill_activation_messages(...)
|
||
│ ├─ 如果 activated_skills 非空：
|
||
│ │ └─ sessions.append_message(event_type="skill_activation_snapshotted", hidden)
|
||
│ │
|
||
│ ├─ ContextBuilder.build_messages()
|
||
│ │ ├─ system prompt 包含：
|
||
│ │ │ ├─ base system prompt
|
||
│ │ │ ├─ session metadata
|
||
│ │ │ ├─ execution context
|
||
│ │ │ └─ frozen memory snapshot
|
||
│ │ ├─ messages 里显式插入 activated skill messages
|
||
│ │ ├─ 再拼 visible history
|
||
│ │ └─ 最后追加当前 user input
|
||
│ │
|
||
│ ├─ sessions.update_system_prompt()
|
||
│ ├─ sessions.append_message(event_type="system_prompt_snapshotted", hidden)
|
||
│ ├─ sessions.append_message(event_type="user_message_added")
|
||
│ │
|
||
│ ├─ 进入最小 tool loop
|
||
│ │ ├─ provider.chat(messages, tools=schemas)
|
||
│ │ ├─ sessions.update_usage()
|
||
│ │ ├─ sessions.append_message(event_type="assistant_message_added")
|
||
│ │ ├─ ContextBuilder.add_assistant_message(...)
|
||
│ │ ├─ 如果没有 tool calls：
|
||
│ │ │ └─ 结束
|
||
│ │ └─ 如果有 tool calls：
|
||
│ │ ├─ ToolExecutor.execute_tool_call(...)
|
||
│ │ ├─ sessions.append_message(event_type="tool_result_recorded")
|
||
│ │ ├─ ContextBuilder.add_tool_result(...)
|
||
│ │ └─ 再回 provider.chat(...)
|
||
│ │
|
||
│ ├─ 成功结束：
|
||
│ │ └─ sessions.append_message(event_type="run_completed", hidden)
|
||
│ │
|
||
│ ├─ 异常结束：
|
||
│ │ ├─ 补 assistant error message
|
||
│ │ └─ sessions.append_message(event_type="run_failed", hidden)
|
||
│ │
|
||
│ └─ return AgentRunResult
|
||
│ ├─ session_id
|
||
│ ├─ run_id
|
||
│ ├─ output_text
|
||
│ ├─ finish_reason
|
||
│ ├─ tool_iterations
|
||
│ ├─ provider_name
|
||
│ ├─ model
|
||
│ └─ usage
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 当前模块边界
|
||
|
||
### 4.1 `EngineLoader`
|
||
|
||
职责：装配运行时依赖。
|
||
|
||
当前已经装配：
|
||
|
||
1. `SessionManager`
|
||
2. `MemoryStore`
|
||
3. `MemoryService`
|
||
4. `ToolRegistry`
|
||
5. `ToolExecutor`
|
||
6. `SkillsLoader`
|
||
7. `SkillAssembler`
|
||
8. `ContextBuilder`
|
||
|
||
### 4.2 `AgentLoop`
|
||
|
||
职责：执行单次 run。
|
||
|
||
当前已经负责：
|
||
|
||
1. direct run 主链
|
||
2. provider 调用
|
||
3. 最小 tool loop
|
||
4. session 事件写回
|
||
5. usage 汇总
|
||
|
||
当前还没负责：
|
||
|
||
1. 更复杂的 message bus mode
|
||
2. 多 worker / 并发调度
|
||
3. 更完整的 runtime lifecycle
|
||
4. multi-agent orchestration
|
||
|
||
### 4.3 `Session`
|
||
|
||
职责：外部化的运行事实存储。
|
||
|
||
当前实现重点：
|
||
|
||
1. `sessions` 表
|
||
- projection / summary row
|
||
2. `messages` 表
|
||
- 当前主事件流
|
||
3. `run_id`
|
||
- 把同一个 session 里的多次 run 切开
|
||
|
||
当前主要读取接口：
|
||
|
||
1. `get_event_records(session_id)`
|
||
- 整个 session 的完整事件流
|
||
2. `get_run_event_records(session_id, run_id)`
|
||
- 某一次 run 的事件片段
|
||
3. `list_run_ids(session_id)`
|
||
- 发现当前 session 中有哪些 run
|
||
4. `get_visible_history(session_id)`
|
||
- 给 ContextBuilder 用的可见历史切片
|
||
5. `session_search`
|
||
- 只检索可见 transcript
|
||
- 不把 hidden prompt / skill snapshot 当成搜索候选
|
||
|
||
当前关键 hidden 事件：
|
||
|
||
1. `run_started`
|
||
2. `skill_activation_snapshotted`
|
||
3. `system_prompt_snapshotted`
|
||
4. `run_completed`
|
||
5. `run_failed`
|
||
|
||
### 4.4 `Memory`
|
||
|
||
职责：durable facts，不是 transcript。
|
||
|
||
当前实现重点：
|
||
|
||
1. curated CRUD
|
||
2. frozen snapshot
|
||
3. 每次新 run 开始时刷新 snapshot
|
||
4. 当前 run 中途写 memory 不反向污染本轮 prompt
|
||
|
||
### 4.5 `Skills`
|
||
|
||
职责：外置 skill 装配与按需查看。
|
||
|
||
当前实现重点：
|
||
|
||
1. `SkillsLoader`
|
||
- 扫描 `workspace/skills/*/SKILL.md`
|
||
- 扫描 builtin skills
|
||
2. `SkillAssembler`
|
||
- 输入 task description + 候选 skill 摘要
|
||
- 先用 embedding 做语义召回
|
||
- 再调一次 LLM 直接选择 skills
|
||
- 没有匹配时返回空 skills
|
||
3. `skill_view`
|
||
- 显式加载 skill 正文或支持文件
|
||
4. activated skills
|
||
- 按 Hermes 风格作为显式消息注入
|
||
|
||
当前 skill 语义已经定成：
|
||
|
||
1. **run-scoped**
|
||
- skill 激活只对当前 run 生效
|
||
2. **不是 session-scoped**
|
||
- 不默认跨 run 持久化为 session 状态
|
||
3. **explicit loading path**
|
||
- `skill_view`
|
||
4. **no-match means no skill injection**
|
||
- 如果 assembler 没选出 skill
|
||
- 当前 run 不拼接 skill messages
|
||
- 也不会写 `skill_activation_snapshotted`
|
||
|
||
### 4.6 `Tools`
|
||
|
||
当前内建工具：
|
||
|
||
1. `echo`
|
||
2. `memory`
|
||
3. `skill_view`
|
||
4. `session_search`
|
||
|
||
当前工具基础设施：
|
||
|
||
1. `ToolSpec`
|
||
2. `ObjectBackedTool`
|
||
3. `ToolRegistry`
|
||
4. `ToolExecutor`
|
||
|
||
### 4.7 `Providers`
|
||
|
||
当前已经实现：
|
||
|
||
1. provider registry
|
||
2. runtime resolution
|
||
3. main provider
|
||
4. fallback provider
|
||
|
||
当前状态：
|
||
|
||
1. fallback 已经是“每次调用都先 main，再 fallback”
|
||
2. auxiliary provider 已经可用于 skill 选择
|
||
3. auxiliary provider 还没有进入主对话 tool loop
|
||
|
||
---
|
||
|
||
## 5. 当前最重要的设计决定
|
||
|
||
这几条是现在已经定下来的，不应该再反复漂：
|
||
|
||
### 5.1 `Session-first`
|
||
|
||
当前 Beaver 明确在往这个方向走：
|
||
|
||
1. 运行事实优先写回 Session
|
||
2. Session 是 replay / audit / resume 的基础
|
||
3. prompt 不是状态源，Session 才是
|
||
|
||
### 5.2 `Harness != Product Interface`
|
||
|
||
当前主入口已经是：
|
||
|
||
- `AgentService`
|
||
- `AgentLoop`
|
||
|
||
而不是 CLI 本身。
|
||
CLI、Web、Gateway 后面都应该只是接口层。
|
||
|
||
### 5.3 `Skill selection` 外置
|
||
|
||
已经不再让 `AgentLoop` 自己“决定该选哪个 skill”，而是：
|
||
|
||
```text
|
||
task description
|
||
-> SkillAssembler
|
||
-> AgentLoop
|
||
```
|
||
|
||
### 5.4 `Skills` 采用 Hermes 风格
|
||
|
||
不是：
|
||
|
||
- skill 正文长期塞进 system prompt
|
||
- summary 让模型自己猜怎么展开
|
||
|
||
而是：
|
||
|
||
1. activated skill messages
|
||
2. `skill_view`
|
||
|
||
---
|
||
|
||
## 6. 当前还没完成什么
|
||
|
||
这部分是接下来继续施工的重点。
|
||
|
||
### 6.1 运行时生命周期
|
||
|
||
已做第一步：
|
||
|
||
1. `EngineLoadResult.close()`
|
||
2. `AgentLoop.close()`
|
||
3. `AgentService.close()`
|
||
4. `AgentService.shutdown()`
|
||
|
||
已做第二步的最小版本：
|
||
|
||
1. `AgentLoop.run()`
|
||
2. `AgentLoop.stop()`
|
||
3. `AgentLoop.submit_direct()`
|
||
|
||
还没做：
|
||
|
||
1. 统一 shutdown hooks
|
||
2. 更完整的 provider/client 资源释放协议
|
||
3. 多 worker / bus / 调度策略
|
||
|
||
### 6.2 Web / Gateway 接主链
|
||
|
||
现在主链已经能跑，但还没正式变成：
|
||
|
||
1. Web 真正调用 `AgentService.process_direct()`
|
||
2. Gateway 真正调用 `AgentService.process_direct()`
|
||
|
||
### 6.3 Session 更完整的 event-source 能力
|
||
|
||
还没做：
|
||
|
||
1. checkpoint
|
||
2. rewind
|
||
3. fork session
|
||
4. crash-resume protocol
|
||
|
||
### 6.4 Multi-agent / swarms
|
||
|
||
还没正式接回主链：
|
||
|
||
1. delegation
|
||
2. team runtime
|
||
3. swarms orchestration backend
|
||
|
||
但 lifecycle 关系已经先定下来了：
|
||
|
||
1. team 不会共享一个大 `AgentLoop` 跑所有成员
|
||
2. 每个 team member 都应有自己独立的 `AgentService / AgentLoop`
|
||
3. team coordinator 在上层调度多个 member 实例
|
||
4. 因此当前这套 `start()/submit_direct()/stop()/close()` 首先是 member-level lifecycle
|
||
2. team runtime
|
||
3. swarms backend
|
||
4. group discussion / workflow orchestration
|
||
|
||
### 6.5 权限与治理
|
||
|
||
还没做：
|
||
|
||
1. permission gates
|
||
2. tool policy
|
||
3. MCP 工具治理
|
||
|
||
---
|
||
|
||
## 7. 下一步从哪开始最合理
|
||
|
||
如果现在继续施工，最合理的顺序是：
|
||
|
||
1. 先把 `flow.md` 作为当前基线固定下来
|
||
2. 再继续第 6 阶段：
|
||
- runtime lifecycle
|
||
- `boot / close / run / stop`
|
||
3. 然后再接：
|
||
- Web / Gateway
|
||
4. 最后才是：
|
||
- multi-agent / swarms
|
||
|
||
一句话总结：
|
||
|
||
**当前 Beaver 已经有一个可运行的单 agent runtime；接下来不是继续堆局部能力，而是把它升级成有完整生命周期的标准 harness。**
|
||
|
||
---
|
||
|
||
## 8. 文档维护要求
|
||
|
||
以后只要发生以下任一变动，必须同步更新本文件：
|
||
|
||
1. `EngineLoader` 装配项变化
|
||
2. `AgentLoop` 主链变化
|
||
3. `Session` 事件流结构变化
|
||
4. `Memory` 接入方式变化
|
||
5. `Skills` 装配方式变化
|
||
6. `Tools` 默认集合变化
|
||
7. Web / Gateway / multi-agent 真正接入主链
|