steven_li
5ba5c7e4c1
集成新的Beaver后端服务到应用实例中，替换原有的nanobot实现。 主要变更包括： - 在Dockerfile和环境配置中添加Beaver相关路径和配置变量 - 更新工作目录结构从.nanobot到.beaver - 实现Beaver引擎加载器，支持配置文件加载和工具组装 - 添加内置工具如ListDirectoryTool、ReadFileTool、SearchFilesTool - 更新消息处理流程，支持通道适配器和网关模式 - 重构技能系统，支持显式工具提示和嵌入式检索 - 改进错误处理和生命周期管理 此变更使应用实例能够使用统一的Beaver后端进行AI代理运行时管理。
900 lines
26 KiB
Markdown
900 lines
26 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 framework + 最小内建工具`
|
||
5. `4.5 最小主链`
|
||
6. `5.1 memory 最小接入`
|
||
7. `5.2 skills 最小接入`
|
||
8. `6.1 session-first / event-source 第一阶段`
|
||
9. `6.2 runtime lifecycle 最小骨架`
|
||
10. `6.2.1 Web / Gateway 最小接主链`
|
||
11. app-instance Docker 镜像切到新 `beaver` 后端
|
||
|
||
更准确地说，当前 Beaver 已经有：
|
||
|
||
1. 一个可运行的 `AgentService -> AgentLoop` 主链
|
||
2. 一个外部化的 Session 子系统
|
||
3. 一个可工作的 tool loop 框架
|
||
4. Hermes 风格的 memory / skills 接入
|
||
5. LLM-driven 的 `SkillAssembler`
|
||
6. embedding-driven 的 `ToolAssembler`
|
||
7. MCP-style 本地工具描述
|
||
8. skill frontmatter `tools` 会影响本轮工具选择
|
||
9. `start()/submit_direct()/stop()/shutdown()/close()` 最小 lifecycle
|
||
10. FastAPI `/api/ping` + `/api/chat`
|
||
11. Gateway `MessageBus -> AgentService -> MessageBus` 最小桥接
|
||
12. Docker app-instance 使用 `/root/.beaver/config.json` 和 `/root/.beaver/workspace`
|
||
|
||
已经实测通过：
|
||
|
||
1. Docker image build
|
||
2. container `/api/ping`
|
||
3. `/api/chat` 调用 `qwen-plus`
|
||
4. Session SQLite 事件写入
|
||
5. 宿主机 `curl` 直连 app-instance
|
||
|
||
但还没有：
|
||
|
||
1. shell / web 等高风险或外部访问工具
|
||
2. 完整 tool permission gates
|
||
3. Web / Gateway 的 realtime streaming
|
||
4. bus retry / routing / persistence
|
||
5. delegation / swarm / team runtime
|
||
6. MCP 全量工具接回 runtime
|
||
7. checkpoint / rewind / fork / crash-resume
|
||
8. skill selector 的 embedding / LLM 选择细节还没有写入 Session event stream
|
||
9. 前端完整 auth / sessions / skills / files / ws 兼容新 Beaver API
|
||
|
||
---
|
||
|
||
## 3. 当前真实主链
|
||
|
||
当前主入口已经不是 CLI 逻辑，而是：
|
||
|
||
```python
|
||
service = AgentService()
|
||
await service.process_direct("你好")
|
||
```
|
||
|
||
上面是 direct/debug path。宿主层进入运行模式后，正式入口是：
|
||
|
||
```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()
|
||
```
|
||
|
||
模型与 provider 配置现在从 backend sandbox config 统一读取，而不是从前端或 channel
|
||
请求里传密钥。Docker 单实例部署时，配置路径优先级是：
|
||
|
||
1. `BEAVER_CONFIG_PATH`
|
||
2. `NANOBOT_CONFIG_PATH`
|
||
3. `BEAVER_HOME/config.json`
|
||
4. `NANOBOT_HOME/config.json`
|
||
5. `<workspace>/.beaver/config.json`
|
||
|
||
当前 app-instance 会把每个用户实例自己的数据目录挂到 `/root/.beaver`，所以
|
||
Beaver 会默认读取：
|
||
|
||
```text
|
||
/root/.beaver/config.json
|
||
```
|
||
|
||
这份配置跟随单个 sandbox 容器/数据卷，不放在前端，也不放在宿主机全局目录。
|
||
Web / Gateway / Channel 只传 `message/session_id/user_id` 等业务输入。
|
||
|
||
app-instance 镜像当前也已经切到新 Beaver 后端：
|
||
|
||
```text
|
||
entrypoint.sh
|
||
├─ 启动 python -m uvicorn beaver.interfaces.web.app:create_app --factory
|
||
├─ 使用 /root/.beaver/config.json
|
||
└─ 使用 /root/.beaver/workspace
|
||
```
|
||
|
||
旧的 `nanobot web`、`backend/nanobot`、`backend/bridge`、vendored `swarms` 不再进入新镜像。
|
||
|
||
这套 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`
|
||
- 可选接收 `ChannelManager` / channel adapters
|
||
- `ChannelManager` 和 `channels` 参数二选一：
|
||
- 传 `ChannelManager`：外部提前配置好 channel
|
||
- 传 `channels`：gateway 内部创建 `ChannelManager` 并注册这些 channel
|
||
- inbound 流向：
|
||
- channel adapter 发布 `InboundMessage`
|
||
- `MessageBus.inbound`
|
||
- gateway bridge 常驻消费
|
||
- `await service.handle_inbound_message(...)`
|
||
- outbound 流向：
|
||
- `AgentService` 内部完成 `InboundMessage -> OutboundMessage` 映射
|
||
- gateway bridge 写回 `MessageBus.outbound`
|
||
- 如果启用了 `ChannelManager`，则分发给对应 channel adapter
|
||
- 未启用 `ChannelManager` 时，保留直接消费 `bus.outbound` 的最小测试能力
|
||
- 同时等待 `stop_event`
|
||
- 退出时：
|
||
- 先尝试 `await service.shutdown(timeout_seconds=5.0, force=True)`
|
||
- 再等待 bridge 协程收尾；必要时取消 bridge
|
||
- 再等待 outbound dispatch 协程收尾；必要时取消 dispatch
|
||
- 如果 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
|
||
|
||
4. `beaver/interfaces/channels/*`
|
||
- 已有最小 channel adapter 层：
|
||
- `ChannelAdapter`
|
||
- `ChannelManager`
|
||
- `MemoryChannelAdapter`
|
||
- 当前 channel 职责很窄：
|
||
- 把外部输入发布成 `InboundMessage`
|
||
- 接收并投递 `OutboundMessage`
|
||
- `MemoryChannelAdapter` 只用于本地测试和内嵌接入，不是正式消息 broker
|
||
|
||
所以现在已经明确：
|
||
|
||
1. Web / Gateway 属于宿主层
|
||
2. 它们不直接 new `AgentLoop` 或绕过运行模式
|
||
3. 它们复用：
|
||
- `start()`
|
||
- `submit_direct()`
|
||
- `stop()`
|
||
- `shutdown()`
|
||
4. ownership 语义：
|
||
- 自己创建的 `AgentService`：自己负责 lifecycle
|
||
- 外部注入的 `AgentService`：默认不自动 start/shutdown，除非显式要求接管
|
||
5. gateway 已经从“只会常驻等待”推进到“最小消息桥接层”
|
||
- external inbound message
|
||
- channel adapter
|
||
- `MessageBus.inbound`
|
||
- `service.handle_inbound_message(...)`
|
||
- `MessageBus.outbound`
|
||
- channel adapter outbound delivery
|
||
|
||
### 3.2 总体链路
|
||
|
||
当前代码里的主链可以概括成：
|
||
|
||
```text
|
||
AgentService
|
||
-> AgentLoop
|
||
-> Session
|
||
-> Memory
|
||
-> SkillAssembler
|
||
-> ToolAssembler
|
||
-> 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
|
||
│ ├─ ToolAssembler
|
||
│ ├─ 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)
|
||
│ │
|
||
│ ├─ tool_assembler.assemble(task_description=task, activated_skills=..., ...)
|
||
│ │ ├─ always tools
|
||
│ │ │ ├─ memory
|
||
│ │ │ ├─ session_search
|
||
│ │ │ └─ skill_view
|
||
│ │ ├─ 读取 activated skill 的 frontmatter `tools`
|
||
│ │ ├─ 用 `text-embedding-v4` 对工具描述做相似度召回
|
||
│ │ ├─ 返回本轮选中的 ToolSpec
|
||
│ │ └─ ToolSpec 同时可导出 MCP descriptor 与 provider schema
|
||
│ │
|
||
│ ├─ sessions.append_message(event_type="tool_selection_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. `ToolAssembler`
|
||
6. `ToolExecutor`
|
||
7. `SkillsLoader`
|
||
8. `SkillAssembler`
|
||
9. `ContextBuilder`
|
||
|
||
### 4.2 `AgentLoop`
|
||
|
||
职责：执行单次 run。
|
||
|
||
当前已经负责：
|
||
|
||
1. direct run 主链
|
||
2. provider 调用
|
||
3. 最小 tool loop
|
||
4. session 事件写回
|
||
5. usage 汇总
|
||
|
||
当前还没负责：
|
||
|
||
1. 更复杂的 message bus mode
|
||
2. 多 worker / 并发调度
|
||
3. provider/client 级 async shutdown hooks
|
||
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. `tool_selection_snapshotted`
|
||
4. `system_prompt_snapshotted`
|
||
5. `run_completed`
|
||
6. `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`
|
||
5. `list_directory`
|
||
6. `read_file`
|
||
7. `search_files`
|
||
|
||
当前工具基础设施：
|
||
|
||
1. `ToolSpec`
|
||
- 以 MCP-style descriptor 作为本地统一描述
|
||
- 可导出 `to_mcp_descriptor()`
|
||
- 可导出 OpenAI-compatible `to_provider_schema()`
|
||
2. `ObjectBackedTool`
|
||
3. `ToolRegistry`
|
||
4. `ToolExecutor`
|
||
5. `ToolAssembler`
|
||
|
||
当前工具选择语义：
|
||
|
||
1. 工具选择是 **run-scoped**
|
||
2. `memory` / `session_search` / `skill_view` / 只读 filesystem tools 是 always tools
|
||
3. activated skill 的 frontmatter 可声明：
|
||
|
||
```yaml
|
||
---
|
||
tools:
|
||
- terminal
|
||
- read_file
|
||
---
|
||
```
|
||
|
||
4. `ToolAssembler` 会合并：
|
||
- always tools
|
||
- activated skill 显式声明的 tools
|
||
- task description embedding top10 tools
|
||
5. 当前只信任 frontmatter / metadata 里的显式 tools，不从 skill 正文里猜工具名
|
||
6. 如果 skill 声明了未注册工具，当前会忽略，不阻断 run
|
||
|
||
当前 filesystem tools 的边界：
|
||
|
||
1. `list_directory` 只能列当前 `ToolContext.workspace` 内的目录
|
||
2. `read_file` 只能读 workspace 内 UTF-8 文本文件
|
||
3. `search_files` 只能搜索 workspace 内文件名和 UTF-8 文本内容
|
||
4. 绝对路径如果解析后不在 workspace 内，会拒绝
|
||
5. workspace 内指向外部的符号链接，读取 / 搜索时会拒绝
|
||
6. 二进制文件会拒绝读取，并在搜索时跳过
|
||
|
||
当前还没有默认注册：
|
||
|
||
1. shell / exec tools
|
||
2. web search / web fetch tools
|
||
3. MCP tools
|
||
4. spawn / team tools
|
||
|
||
### 4.7 `Providers`
|
||
|
||
当前已经实现：
|
||
|
||
1. provider registry
|
||
2. runtime resolution
|
||
3. main provider
|
||
4. fallback provider
|
||
5. auxiliary provider
|
||
6. embedding runtime 配置线
|
||
|
||
当前状态：
|
||
|
||
1. fallback 已经是“每次调用都先 main，再 fallback”
|
||
2. auxiliary provider 已经可用于 skill 选择
|
||
3. embedding runtime 当前用于 SkillAssembler 的候选召回
|
||
4. embedding runtime 当前也用于 ToolAssembler 的工具召回
|
||
5. 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`
|
||
|
||
### 5.5 `Tools` 采用 MCP-style 描述
|
||
|
||
当前本地工具不再只是一段 OpenAI function schema，而是先收敛成：
|
||
|
||
```text
|
||
ToolSpec
|
||
├─ name
|
||
├─ description
|
||
├─ input_schema
|
||
├─ toolset
|
||
└─ always_available
|
||
```
|
||
|
||
其中 `name/description/input_schema` 可直接导出 MCP-style descriptor：
|
||
|
||
```json
|
||
{
|
||
"name": "memory",
|
||
"description": "...",
|
||
"inputSchema": {}
|
||
}
|
||
```
|
||
|
||
provider 需要的 OpenAI-compatible schema 由 `ToolSpec.to_provider_schema()` 转换出来。
|
||
|
||
---
|
||
|
||
## 6. 对照施工指南，我们现在处于哪一步
|
||
|
||
这部分严格对齐 `施工指南.md` 的第 6 阶段编号，不再自行改号。
|
||
|
||
### 6.1 第一步：Session 升级为事件源模型
|
||
|
||
当前状态：**基本完成第一阶段目标，但还不是完整 event-source 系统。**
|
||
|
||
已经具备：
|
||
|
||
1. `messages` 表已经承担主事件流语义
|
||
2. 每次 run 都有独立 `run_id`
|
||
3. `AgentLoop.process_direct()` 已按事件阶段写回 Session
|
||
4. 已有：
|
||
- `get_event_records(session_id)`
|
||
- `get_run_event_records(session_id, run_id)`
|
||
- `list_run_ids(session_id)`
|
||
- `get_visible_history(session_id)`
|
||
5. `session_search` 只检索可见 transcript，不把 hidden snapshots 当搜索候选
|
||
|
||
当前还没做：
|
||
|
||
1. `checkpoint`
|
||
2. `rewind`
|
||
3. `fork session`
|
||
4. `crash-resume protocol`
|
||
|
||
所以更准确地说：
|
||
|
||
1. `6.1` 的“Session-first / event-source 第一阶段”已经落地
|
||
2. 但更完整的 event-source 能力还没有做完
|
||
|
||
### 6.2 第二步：runtime 生命周期协议补齐
|
||
|
||
当前状态：**最小 lifecycle 骨架已经完成。**
|
||
|
||
已完成：
|
||
|
||
1. `EngineLoadResult.close()`
|
||
2. `AgentLoop.close()`
|
||
3. `AgentService.close()`
|
||
4. `AgentService.shutdown()`
|
||
5. `AgentLoop.run()`
|
||
6. `AgentLoop.stop()`
|
||
7. `AgentLoop.submit_direct()`
|
||
8. `AgentService.start()`
|
||
9. `AgentService.stop()`
|
||
10. `AgentService.submit_direct()`
|
||
|
||
还没做：
|
||
|
||
1. 统一 shutdown hooks
|
||
2. 更完整的 provider/client 资源释放协议
|
||
3. 多 worker / bus / 调度策略
|
||
|
||
### 6.2.1 Web / Gateway 现在如何接这套 lifecycle
|
||
|
||
当前状态：**最小宿主层接入已经完成。**
|
||
|
||
已经完成：
|
||
|
||
1. Web 通过 FastAPI lifespan 托管 `AgentService.start()/shutdown()`
|
||
2. Web 请求只走 `AgentService.submit_direct()`
|
||
3. Gateway 已有最小 `MessageBus -> AgentService.handle_inbound_message() -> MessageBus` 桥接
|
||
4. Gateway 已支持可选 `ChannelManager`，把 outbound 分发回 channel adapter
|
||
|
||
当前 app-instance Docker 已完成：
|
||
|
||
1. Dockerfile 只安装 `backend/beaver`
|
||
2. entrypoint 启动 `beaver.interfaces.web.app:create_app`
|
||
3. 每个实例挂载 `/root/.beaver`
|
||
4. 配置读取 `/root/.beaver/config.json`
|
||
5. workspace 使用 `/root/.beaver/workspace`
|
||
6. 宿主 `curl /api/chat` 已实测通过
|
||
|
||
这一小步还没做：
|
||
|
||
1. realtime streaming
|
||
2. retry / broker persistence
|
||
3. 外部真实 channel adapter 全量接入
|
||
|
||
### 6.3 第三步：回填 bus 模式
|
||
|
||
当前状态：**只完成了前置地基，还没有按施工指南真正收口。**
|
||
|
||
已经具备的前置件：
|
||
|
||
1. `MessageBus`
|
||
2. `InboundMessage`
|
||
3. `OutboundMessage`
|
||
4. `AgentService.handle_inbound_message()`
|
||
5. Gateway bridge 常驻消费 inbound 并写回 outbound
|
||
6. `AgentLoop.run()` 已有最小运行循环
|
||
|
||
但严格按 `施工指南.md` 来看，`6.3` 还没有正式完成，因为现在还缺：
|
||
|
||
1. 把 bus mode 明确成 runtime 的正式运行形态之一
|
||
2. 明确 `run()` 如何稳定消费 inbound message
|
||
3. 明确 bus mode 与 direct mode / queue mode 的职责边界
|
||
4. 明确停机、取消、冲刷 pending inbound 时的统一语义
|
||
5. 再决定后续是否需要更复杂的 worker / retry / routing
|
||
|
||
也就是说：
|
||
|
||
1. 现在不是“还没 bus”
|
||
2. 而是“已经把 bus 协议映射收口到 `AgentService`，但还没按施工指南把它扩成完整 bus runtime 模式”
|
||
|
||
### 6.4 单 agent lifecycle 如何扩展到 team
|
||
|
||
当前状态：**关系已经定死，但实现还没开始。**
|
||
|
||
当前已经明确：
|
||
|
||
1. team 不会共享一个大 `AgentLoop` 跑所有成员
|
||
2. 每个 team member 都应有自己独立的 `AgentService / AgentLoop`
|
||
3. team coordinator 在上层调度多个 member 实例
|
||
4. 因此当前这套 `start()/submit_direct()/stop()/close()` 首先是 member-level lifecycle
|
||
|
||
当前还没开始的部分：
|
||
|
||
1. delegation
|
||
2. team runtime
|
||
3. swarms orchestration backend
|
||
4. group discussion / workflow orchestration
|
||
|
||
---
|
||
|
||
## 7. 对照 `change.md`，哪些长期目标还没开始
|
||
|
||
`change.md` 讲的是总蓝图，不是当前施工编号。下面这些仍然是长期目标，还没有正式进入当前阶段实现：
|
||
|
||
1. skills 生命周期系统
|
||
- `SkillDraft`
|
||
- `SkillVersion`
|
||
- review / publish / rollback
|
||
2. Hermes-style learning loop
|
||
- 智能体定期整理 / 提示记忆
|
||
- 复杂任务完成后可自主创建技能
|
||
- 技能在使用过程中自我提升
|
||
- FTS5 + LLM 摘要的跨会话回忆增强
|
||
- Honcho 风格辩证用户建模
|
||
3. swarms 作为正式 backend 接回平台
|
||
4. delegation / subagent / team orchestration
|
||
|
||
当前只完成了这些基础入口：
|
||
|
||
1. curated memory CRUD
|
||
2. session_search
|
||
3. skill loader / skill_view
|
||
4. skill assembler
|
||
5. tool assembler
|
||
|
||
### 7.1 权限与治理
|
||
|
||
还没做：
|
||
|
||
1. 完整 permission gates
|
||
2. tool policy
|
||
3. MCP 工具治理
|
||
|
||
已完成的最小边界：
|
||
|
||
1. 只读 filesystem tools 强制限制在 `ToolContext.workspace`
|
||
2. 路径解析使用真实路径，防止相对路径、绝对路径、符号链接逃逸
|
||
3. 当前还没有 shell / write / network 工具，因此还没进入高风险授权阶段
|
||
|
||
### 7.2 前端兼容
|
||
|
||
当前只做了最小 chat response 兼容：
|
||
|
||
1. 前端 `sendMessage()` 已兼容 Beaver 的 `output_text`
|
||
|
||
还没做：
|
||
|
||
1. `/api/auth/*`
|
||
2. `/api/sessions`
|
||
3. `/api/status` 完整页面数据
|
||
4. `/api/skills`
|
||
5. `/api/files`
|
||
6. `/ws`
|
||
7. 浏览器端免登录或新 auth 接入策略
|
||
|
||
---
|
||
|
||
## 8. 下一步从哪开始最合理
|
||
|
||
如果严格按 `施工指南.md` 的施工顺序继续，下一步应是：
|
||
|
||
1. 完成 `6.3 回填 bus 模式`
|
||
- 明确 bus mode 的正式运行语义
|
||
- 让 `AgentLoop.run()` 与 `MessageBus` 的关系稳定收口
|
||
- 把 inbound / outbound 结果结构定稳
|
||
2. 然后再进入 `6.4`
|
||
- 先把 team lifecycle 关系写成更可实现的 coordinator 约束
|
||
3. 再进入第 7 阶段
|
||
- delegation
|
||
- local subagent
|
||
4. 再进入第 8 阶段
|
||
- team / swarms backend
|
||
|
||
如果按 `change.md` 的长期方向看，后面还要补：
|
||
|
||
1. skills 生命周期
|
||
2. Hermes-style learning loop
|
||
3. 更完整的 memory / governance / frontend
|
||
|
||
一句话总结：
|
||
|
||
**当前 Beaver 已经完成到“单 agent runtime + memory/skills + lifecycle + Web/Gateway 最小接入”，按施工指南的编号，下一步应是 `6.3 回填 bus 模式`。**
|
||
|
||
---
|
||
|
||
## 8. 文档维护要求
|
||
|
||
以后只要发生以下任一变动，必须同步更新本文件：
|
||
|
||
1. `EngineLoader` 装配项变化
|
||
2. `AgentLoop` 主链变化
|
||
3. `Session` 事件流结构变化
|
||
4. `Memory` 接入方式变化
|
||
5. `Skills` 装配方式变化
|
||
6. `Tools` 默认集合变化
|
||
7. Web / Gateway / multi-agent 真正接入主链
|