Beaver Backend Module Blueprint
Flat Engineering Blueprint / app-instance/backend / 2026-05-25
SOURCE: app-instance/backend
STYLE: projcet_review/blueprinter.md
SCOPE: backend code + tests + architecture docs
MULTI-PAGE: backend_blueprint/index.html

项目是干嘛的

Beaver 后端是一个面向用户任务的 agent runtime。它接收来自 Web、WebSocket、CLI、Gateway、Cron 或 MCP 的请求， 用 Main Agent 判断这是不是一个需要跟踪的 Task；简单问题直接回复，复杂任务进入 Task mode。Task mode 会规划单 agent 或 team 执行，运行统一的 AgentLoop，选择技能和工具，调用模型，记录事实证据，并等待用户接受、修改或放弃。 只有用户接受后的 Task evidence 才会沉淀为可学习的 skill 候选。

UNIFIED ENGINE TASK MODE TEAM COORDINATOR SKILL LEARNING MCP TOOLS SCHEDULED TASKS

最关键的架构判断

主 agent、team node、sub-agent 都不各自实现一套 runtime；它们最后都回到同一个 beaver.engine.AgentLoop。 因此后续修改时要优先确认：入口层是不是薄的，服务层是不是只编排，真正 tool loop / prompt / provider / session 逻辑是不是仍在 engine 内收口。

interfaces -> services services -> engine engine -> skills/tools/memory

主执行流

这是后端最重要的一条路径，后续逐模块修改文档应该先对齐这条链路。

CHAT / TASK / ACCEPTANCE / LEARNING

1. 入口接收

/api/chat、WebSocket、CLI、Gateway 或 Cron 把用户消息转给 AgentService。

2. 意图路由

MainAgentRouter 结合 active task 和近期会话，判断 simple / new_task / continue / revise / close / abandon。

3. Task 建模

TaskService 写入 tasks.json 和 events.jsonl，维护 open/running/awaiting_acceptance/closed 状态。

4. 执行规划

TaskExecutionPlanner 让辅助模型选择 single 或 team，并为 team 生成 sequence / parallel / DAG 节点。

5. 统一运行

AgentLoop 冻结 memory，选 skill，选 tool，构建 prompt，调用 provider，执行 tool loop。

6. 事实证据

EvidenceBuilder 汇总 run/team/tool 证据。Evidence 只记录事实，不判断、不打分、不 gate。

7. 验收学习

用户接受 Task 后生成 accepted task evidence 和 learning candidates；worker 可生成 draft，但不会自动 approve/publish。

模块总览

每个模块下面都写明责任、逻辑、具体怎么做，以及关键文件。

MODULE RESPONSIBILITY MAP
foundation

底层配置、事件和通用模型

负责加载实例级配置、定义 provider/MCP/AuthZ/backend identity schema、提供 message bus 和 cron 数据模型。

  • 配置来源优先级：BEAVER_CONFIG_PATH、BEAVER_HOME/config.json、workspace 下 .beaver/config.json。
  • BeaverConfig.resolve_provider_target() 从默认模型、显式 provider 和已配置凭据推导运行目标。
  • MessageBus 用 async queue 承接 gateway inbound/outbound。
  • CronSchedule/CronJob/CronRunRecord 是定时任务持久化模型。
  • beaver/foundation/config/schema.py
  • beaver/foundation/config/loader.py
  • beaver/foundation/events/message_bus.py
  • beaver/foundation/models/cron.py
  • beaver/foundation/embedding.py
interfaces

薄入口层

负责把 HTTP、WebSocket、CLI、Gateway、MCP server 的输入转换成服务层调用，不应保存核心执行逻辑。

  • Web app lifespan 启动 AgentService running mode、CronService 和可选 skill learning worker。
  • /api/chat 和 /ws/{session_id} 都委托给 _run_web_direct() / AgentService。
  • 文件 API 分两类：聊天附件 workspace/files/<id> 与 workspace 浏览/上传/预览。
  • MCP interface 暴露 memory/tools server，Gateway 用 MessageBus 桥接渠道。
  • beaver/interfaces/web/app.py
  • beaver/interfaces/web/files.py
  • beaver/interfaces/cli/main.py
  • beaver/interfaces/gateway/main.py
  • beaver/interfaces/mcp/*.py
  • beaver/interfaces/channels/*.py
services

应用服务编排层

负责把入口请求转成系统内部流程：agent 运行、task mode、cron、team、memory、skill hub、process projection。

  • AgentService 是主入口，区分 direct mode 和 running mode。
  • _process_with_main_agent() 先做意图分类，再决定是否进入 Task。
  • _run_task_mode() 管理 task planning、team 执行、主 agent synthesis、evidence 记录和用户验收状态。
  • CronService 负责持久化定时任务、计算下一次运行、记录 history。
  • SessionProcessProjector 把隐藏 task/team 事件投影给前端过程视图。
  • beaver/services/agent_service.py
  • beaver/services/team_service.py
  • beaver/services/cron_service.py
  • beaver/services/process_service.py
  • beaver/services/skillhub_service.py
engine

统一 agent 运行内核

这是主 agent 和 delegated agent 共用的核心。它装配 runtime，构建上下文，选择技能和工具，驱动 provider/tool loop，并记录所有运行事件。

  • EngineLoader 装配 session、memory、run store、skill store、tool registry、MCP manager、task/evidence 服务。
  • AgentLoop.process_direct() 是单次运行主链；running mode 下只能通过 queue submit_direct()。
  • 每个 run 独立捕获 frozen memory snapshot，避免 parallel team runs 共享快照互相污染。
  • 运行时写入 run_started、skill activation、tool selection、LLM request、tool result、run completed/failed 等事件。
  • beaver/engine/loader.py
  • beaver/engine/loop.py
  • beaver/engine/context/builder.py
  • beaver/engine/providers/*.py
  • beaver/engine/session/*.py
providers

模型 provider 抽象与选路

把不同模型网关统一成 LLMProvider.chat()，返回统一 LLMResponse 和 ToolCallRequest。

  • ProviderRuntime 描述解析后的 provider、model、api mode、凭据、headers、routing。
  • ProviderBundle 同时包含 main、fallback、auxiliary、embedding runtime。
  • FallbackProviderChain 在主 provider 返回 error 或抛异常时按单次调用切到 fallback。
  • 实现包含 LiteLLM、Anthropic、OpenAI Codex API、OpenAI-compatible custom。
  • beaver/engine/providers/base.py
  • beaver/engine/providers/runtime.py
  • beaver/engine/providers/factory.py
  • beaver/engine/providers/registry.py
  • beaver/engine/providers/litellm.py
  • beaver/engine/providers/anthropic.py
  • beaver/engine/providers/codex.py
tasks

内部 Task、事实证据和用户验收

负责把“需要执行和跟踪”的用户请求变成可持久化、可重试、可验收的 Task。

  • MainAgentRouter 使用 LLM JSON 决策区分 simple/task/continue/revise/close/abandon。
  • TaskExecutionPlanner 让辅助模型选择 single 或 team，并限制 team 节点最多 6 个。
  • TaskSkillResolver 为 team node 匹配 published skill；没有匹配时生成 one-run ephemeral guidance。
  • EvidenceBuilder 只记录事实证据；Task 是否完成只由用户验收决定。
  • beaver/tasks/models.py
  • beaver/tasks/service.py
  • beaver/tasks/router.py
  • beaver/tasks/planner.py
  • beaver/tasks/skill_resolver.py
  • beaver/tasks/evidence.py
  • beaver/tasks/store.py
coordinator

多 agent / team 编排

负责把 team execution graph 转成多个 delegated runs。v1 真正实现的是 sequence、parallel、DAG；其它 strategy 目前保留但未实现。

  • ExecutionGraph.validate() 校验节点唯一、依赖存在、无环，以及 strategy 是否已实现。
  • TeamGraphScheduler 按策略运行节点，失败依赖会把后续节点标记 blocked。
  • LocalAgentRunner 为每个节点生成 child session，并仍调用同一个 AgentLoop。
  • Agent registry 和 LocalSubagentStore 支持管理 specialist/subagent，但当前 Task 主链主要走 generic skill worker。
  • beaver/coordinator/models.py
  • beaver/coordinator/execution/scheduler.py
  • beaver/coordinator/local.py
  • beaver/coordinator/registry/*.py
  • beaver/coordinator/subagents.py
tools

工具契约、选择和执行

负责把内建工具和 MCP 工具统一暴露为 provider function schema，并在 tool loop 里执行模型返回的调用。

  • ToolSpec 是工具元数据和 schema 的事实来源，可导出 MCP descriptor 和 provider schema。
  • ToolAssembler 按 always tools、skill tool hints、embedding retrieval 选择本轮工具。
  • ToolExecutor 兼容 ToolCallRequest 和 OpenAI 风格 dict，解析参数并调用 registry。
  • 内建工具覆盖 memory、session search、filesystem、web fetch/search、terminal/process/code、cron、skill admin、delegation utility。
  • beaver/tools/base.py
  • beaver/tools/registry/tool_registry.py
  • beaver/tools/runtime/executor.py
  • beaver/tools/assembler/task_assembler.py
  • beaver/tools/builtins/*.py
  • beaver/tools/mcp/wrapper.py
skills

技能目录、选择、生命周期和学习

负责发现、选择、注入、版本化、审核、发布和自动学习 Beaver skills。

  • SkillsLoader 读取 workspace published skills、plugin/extra dirs、builtin skills，解析 frontmatter 和工具提示。
  • SkillAssembler 用 embedding 召回候选，再用 LLM 做 shortlist/final 选择，并返回 SkillContext。
  • SkillSpecStore 管理 skill.json、current.json、versions、drafts、reviews。
  • SkillLearningPipelineService 协调 candidate -> draft -> safety/eval -> review -> approve -> publish。
  • beaver/skills/catalog/*.py
  • beaver/skills/assembler/*.py
  • beaver/skills/specs/*.py
  • beaver/skills/drafts/service.py
  • beaver/skills/reviews/service.py
  • beaver/skills/publisher/service.py
  • beaver/skills/learning/*.py
memory

会话、长期记忆、运行记忆和学习状态

负责保存对话事件、长期记忆、run receipt、skill effect、skill learning candidates 和安全/eval 报告。

  • 会话存 SQLite，包含 sessions、messages 和 FTS5 messages_fts。
  • 长期记忆只有 MEMORY.md 和 USER.md 两个桶，写入前扫描 prompt injection / secret exfiltration 风险。
  • run memory 用 JSONL 保存 RunRecord 和 SkillEffectRecord。
  • skill learning store 维护候选状态、performance snapshot、safety report、eval report。
  • beaver/engine/session/*.py
  • beaver/memory/curated/*.py
  • beaver/memory/runs/*.py
  • beaver/memory/skills/*.py
  • beaver/memory/search/transcript_store.py
integrations

外部系统与协议集成

负责连接 AuthZ、MCP 和 Outlook。WhatsApp、A2A、providers 目录当前主要是占位。

  • MCPConnectionManager 支持 stdio 和 streamable HTTP MCP server，并把远端 tools 注册成 mcp_{server}_{tool}。
  • 远端 MCP 可用 AuthZ backend token 模式，通过 backend identity 换取 bearer token。
  • Outlook integration 通过 AuthZ 或直接凭据连接，维护 workspace meta，提供 status/overview/messages/events/detail。
  • AuthzClient 负责用户/backend 注册、权限查询、token 签发。
  • beaver/integrations/mcp/connection.py
  • beaver/integrations/authz/client.py
  • beaver/integrations/outlook/__init__.py
  • beaver/integrations/a2a/__init__.py
  • beaver/integrations/whatsapp/__init__.py
permissions

权限与治理层

目录已经存在，但当前基本是空骨架。实际权限约束主要散落在具体工具、workspace path 校验、memory safety 和 skill draft safety 中。

  • permissions/guards、policies、profiles 只有 docstring。
  • ToolsConfig.restrict_to_workspace 已在配置 schema 里存在，但需要逐工具核对是否真正执行。
  • 后续如果要做能力治理，应把工具执行、MCP sensitive 标记、provider/terminal/file 操作统一接入这里。
  • beaver/permissions/__init__.py
  • beaver/permissions/guards/__init__.py
  • beaver/permissions/policies/__init__.py
  • beaver/permissions/profiles/__init__.py

核心数据落点

这些文件/数据库是运行后最重要的事实来源。后续核对行为是否符合预期时，优先看这里。

PERSISTENCE MAP
数据 位置 写入者 用途
Session / transcript event stream <workspace>/sessions/state.db SessionManager / AgentLoop 保存可见对话、隐藏 system snapshots、tool calls/results、run lifecycle、usage、FTS 搜索。
Task records <workspace>/tasks/tasks.json TaskService 保存 task goal/status/run_ids/skill_names/acceptance history。
Task events <workspace>/tasks/events.jsonl TaskService 保存 created/run_started/run_completed/evidence_recorded/accepted/revised/closed/abandoned。
Curated memory <workspace>/memory/curated/MEMORY.md, USER.md MemoryTool / MemoryStore 长期注入 prompt 的稳定事实；每个 run 冻结快照。
Run receipts / skill effects <workspace>/memory/runs/*.jsonl AgentLoop / AgentService 用户验收入口 skill learning 的原始执行证据、用户验收事件和 final accepted run 标记。
Skills lifecycle <workspace>/skills/<name>/... SkillSpecStore / draft/review/publisher services published versions、drafts、reviews、current version、supporting files。
Skill learning state <workspace>/memory/skills/... SkillLearningStore 候选、performance snapshot、safety report、eval report。
Cron jobs and runs <workspace>/cron/jobs.json CronService 定时任务配置、next_run、history、notification/task linkage。
Agent registry / subagents <workspace>/agents/registry.json, *_agent/AGENTS.json AgentRegistry / LocalSubagentStore 管理 builtin/workspace/learned agents 和本地 sub-agent workspace。

关键流程拆解

这些流程是后续逐模块修改时最容易产生偏差的地方。

CONTROL FLOWS

Simple chat

  • 入口调用 AgentService._process_with_main_agent()。
  • MainAgentRouter 返回非 task。
  • 关闭 skill assembly 和 tools：include_skill_assembly=False、include_tools=False。
  • 仍通过 AgentLoop 写 session/run 事件，但不创建 Task。

Task mode single

  • 创建或复用 open task。
  • planner 返回 single，主 agent 直接运行。
  • 运行后构建 TaskEvidencePacket。
  • 运行后状态变 awaiting_acceptance；用户 accept/revise/abandon 决定关闭、修订或放弃。

Task mode team

  • planner 生成 ExecutionGraph。
  • TaskSkillResolver 给节点绑定 published skill 或 ephemeral guidance。
  • TeamService 运行节点，节点仍调用 AgentLoop。
  • 主 agent synthesis 使用 team evidence，通常关闭工具调用，避免重复执行子 agent 已做的事情。

Skill learning

  • 每个 run 记录 activated skill receipt 和 effect。
  • 用户 accept task 后才生成候选；证据包含整个 task 的所有 runs，并标记 final_accepted_run_id。
  • worker 只生成 draft、做 safety/eval，不自动 approve/publish。
  • publish 必须有 approved review、passing safety、没有失败 eval；high risk 还需要显式确认。

后续核对问题清单

这些问题适合配合 brainstorming / grill-me 逐模块核对想法和现有项目是否一致。

REVIEW PROMPTS
产品目标
这个后端当前更像“任务型 agent runtime”，不是普通聊天后端。你想保留 Task runtime 的 Plan -> Run -> Evidence -> User Acceptance 主体验，还是把它降级成可选高级模式？
主入口边界
interfaces/web/app.py 已经超过 3000 行，包含 auth、files、skills、cron、chat 等。后续是否要拆 route 模块，还是先保持单文件以降低迁移风险？
Task 自动化程度
现在 Main Agent 会自动 Task 化复杂请求。你是否接受模型分类误差？是否需要用户显式确认创建 Task？
Team 执行策略
当前真正实现 sequence / parallel / DAG，其它策略只是保留枚举。是否要支持更多 coordinator，还是坚持 v1 只做三种稳定策略？
Agent registry 角色
registry/search/target resolver 已存在，但 Task 主线主要绑定技能而不是 specialist agent。你希望 team node 优先找 specialist agent，还是继续 generic skill worker？
权限治理
permissions 目录目前是骨架。terminal、filesystem、web、MCP、Outlook 等能力是否需要统一 policy gate？
Skill 学习闭环
候选生成应依赖 task accepted。你希望只从用户接受的 task evidence 学习，还是允许人工从 abandoned/revised 历史中手动创建候选？
外部集成
Outlook/AuthZ/MCP 已经比较具体；A2A/WhatsApp 仍是占位。后续应该优先补协议，还是先收紧已有集成的权限和错误处理？

代码观察与风险点

这些不是修改建议的最终结论，只是阅读代码后值得后续逐项核对的偏差点。

OPEN RISKS

定时 Task 路径存在明显变量错误

AgentService.run_scheduled_task() 末尾更新 assistant event payload 时引用了 job.id、run.scheduled_run_id、job.name， 但该函数参数只有 cron_job_id、cron_job_name、scheduled_run_id。这条路径如果执行到这里会触发 NameError。

权限层还没有真正成为执行闸门

permissions 目录为空骨架，实际保护分散在工具实现和路径校验里。若后续开放 terminal、filesystem、MCP sensitive tools，需要统一执行前 policy。

Web auth 是本地单用户风格

本地 auth 文件以 username/password 字段读写，使用 token/handoff code 做前端会话。若目标是多用户或公网后端，需要重新评估密码存储、token 生命周期和权限边界。

Skill eval 目前偏轻量启发式

SkillDraftEvaluator 基于历史 accepted task evidence 和草稿长度/内容做 bounded report，不是真正 replay。它只属于 skill draft 治理，不属于 Task runtime。

接口层过大

interfaces/web/app.py 同时承载 app factory、lifespan、auth、provider config、sessions、files、agents、MCP、Outlook、skills、cron、chat、helper functions。 后续修改时容易产生跨功能回归。

已经落地的稳定点

可依赖：统一 AgentLoop、session event stream、Task evidence/acceptance 状态、team graph v1、skill lifecycle gates、MCP wrapper、workspace path containment。

测试覆盖信号

单元测试覆盖了当前后端多数关键行为，可作为后续修改文档的回归索引。

TEST INDEX

Task / acceptance

test_task_mode_feedback.py, test_task_evidence.py, test_task_execution_planner.py, test_task_skill_resolver.py

Engine / providers

test_websocket_chat.py, test_main_agent_router.py, test_litellm_thinking_mode.py, test_imports.py

Team / process

test_agent_team_v1.py, test_agent_registry_resolver.py, test_process_projection.py

Skills / tools / web

test_phase5_skills_runtime.py, test_skill_learning_*.py, test_tool_assembler.py, test_web_files_api.py