# Beaver Backend 多页模块蓝图

基于 `app-instance/backend/beaver` 源码拆出的模块级审阅文档。每个大模块独立成页，页内继续拆小模块、执行流程、数据流和 prompt 组装点。

## 项目在做什么

这个后端是 Beaver 的本地/服务端 agent runtime。它把 Web、CLI、MCP、定时任务等入口统一成 session run，再通过 Intent Agent 判断是否进入内部 Task 模式；Task 模式会计划单 agent 或 team graph，装配 skills/tools/memory，调用 provider，执行工具循环，收集 evidence，并把结果交给用户验收。只有用户接受后的 Task evidence 才进入 skill learning，生成候选、草稿、审核和发布链路。

入口Web / CLI / Gateway / Cron
->
服务编排AgentService / CronService / TeamService
->
运行内核AgentLoop + ContextBuilder
->
能力装配Skills / Tools / Memory
->
模型与工具Providers + ToolExecutor
->
任务验收Evidence / User Acceptance

## 大模块页

### Foundation

配置、事件总线、cron 数据结构、embedding 检索基础设施。

beaver/foundation

### Interfaces

Web API、静态 UI、CLI、Gateway、MCP server 和外部通道入口。

beaver/interfaces

### Services

产品级用例层，负责把入口请求变成 agent run、task run、cron run、team run。

beaver/services

### Engine

运行内核，负责加载依赖、构造上下文、执行 LLM/tool loop、落 session 事件。

beaver/engine

### Providers

统一 provider 协议和 OpenAI/LiteLLM/Anthropic/Codex/Custom 的适配转换。

beaver/engine/providers

### Tasks

内部 Task 模式：路由、计划、team 技能解析、事实证据和用户验收。

beaver/tasks

### Coordinator

把 team graph 节点调度到本地子 agent，管理依赖输出和节点证据。

beaver/coordinator

### Tools

工具规格、注册表、按 run 选择工具、执行器、内置工具和 MCP 工具包装。

beaver/tools

### Skills

Skill 目录、LLM 选择、注入、草稿、审核、发布、学习流水线。

beaver/skills

### Memory

curated memory、session SQLite、run receipt、skill learning store。

beaver/memory

### Integrations

MCP、AuthZ、Outlook 等外部集成边界。

beaver/integrations

### Permissions

当前是预留骨架，用来承载后续权限策略。

beaver/permissions

## Prompt 组装总图

所有直接构造 LLM messages 的位置集中在 Prompt Atlas。模块页中只保留与该模块有关的 prompt 流程，详细字段顺序、system/user message 内容结构、fallback 逻辑都在 Prompt Atlas 展开。

Intent Agent判断 simple/task/revise/new/close
->
Planner判断 single/team，生成 graph
->
Skill Select选择 published skill 或临时 guidance
->
ContextBuildersystem prompt + skill activation + history + user
->
User Acceptance用户接受、修改或放弃

## 已知核对点

定时任务路径有一处疑似运行时错误： `services/agent_service.py` 的 `run_scheduled_task()` 末尾写 event payload 时引用了未定义的 `job` 和 `run`，应改用函数参数 `cron_job_id`、`scheduled_run_id`、`cron_job_name`。