# Beaver Backend Overview

这是新 `Beaver` 后端的架构入口文档。

可视化入口：

- [Beaver Backend 可视化](backend-visualization.html)

## 给零基础读者的版本

可以先把这个后端理解成一个“帮用户完成任务的后台工厂”：

1. 用户在前端发一句话。
2. 后端入口把这句话接住。
3. 服务层判断它是闲聊，还是一个需要执行和跟踪的任务。
4. 如果是任务，系统会创建或继续一个 `Task`。
5. 运行内核 `AgentLoop` 准备上下文、选择技能、选择工具、调用模型。
6. 如果模型需要查文件、写文件、搜索或调用外部系统，就通过 `tools` 执行。
7. 执行结果会写回会话、任务记录和运行记录，后续可以继续追踪、验证和学习。

这套结构里最重要的原则是：**所有 agent 共用同一个运行内核 `engine`**。也就是说，主 agent 和被拆出去的小 agent 不是两套系统，它们最终都会回到 `AgentLoop`，使用同一套上下文、工具、技能和记录方式。

## 先认识几个词

- `interfaces`：入口层。负责接收 Web、CLI、Gateway、MCP 等不同来源的请求。
- `services`：应用服务层。负责把入口请求转成系统内部要做的事情。
- `engine`：运行内核。真正组织 prompt、调用模型、执行 tool loop 的地方。
- `coordinator`：多 agent 编排层。负责把复杂任务拆成 sequence、parallel 或 DAG。
- `skills`：技能层。可以理解成给 agent 的专项说明书。
- `tools`：工具层。可以理解成 agent 能按需调用的动作，例如读文件、写文件、搜索、执行命令。
- `memory`：记忆层。保存会话、任务结果、运行记录、反馈和技能学习数据。
- `permissions`：权限与治理层。负责约束哪些能力能用、怎么用。

## 一句话请求的流转

典型路径是：

`interfaces` -> `AgentService` -> `MainAgentRouter` -> `TaskService` / `TaskExecutionPlanner` -> `AgentLoop` -> `skills` / `tools` / `memory` -> 返回用户。

如果任务很简单，可能只走单 agent。如果任务更复杂，`TaskExecutionPlanner` 可能先生成一个 team plan，让 `coordinator` 安排多个 sub-agent 分别处理，最后再由主 agent 综合输出。

当前约束：

1. 所有 agent 共用 `engine`。
2. 多 agent 编排进入 `coordinator`。
3. skills、memory、permissions 独立成能力层。
4. `interfaces` 只做薄入口。