# Beaver Backend 重构蓝图 ## 命名说明 当前项目正式名称已经不是 `nanobot`，而是 `beaver`。 这份文档里如果出现 `nanobot/...`，一律表示“当前仓库里还没迁走的历史代码路径 / 现状实现位置”，不代表目标命名。 后续重构目标应统一收敛到： 1. 产品名、项目名、运行时内核名统一按 `beaver` 表达。 2. `nanobot` 只作为迁移期遗留路径存在，最终应逐步退出目录、模块和文档命名。 3. 新增目录、新增模块、新增文档都应优先使用 `beaver` 命名，而不是继续扩散 `nanobot`。 ## 1. 这次重构到底要解决什么 当前后端已经不是“功能不够”，而是“能力已经长出来了，但结构还停留在早期阶段”。 现在项目里同时存在这些事实： 1. `AgentLoop` 已经承担了太多职责，既管主 agent 对话，又管工具、委派、MCP、会话、事件、memory。 2. `web/server.py` 已经变成超大文件，FastAPI app factory、chat API、session、文件、skills、cron、A2A、Outlook 都放在一起。 3. `agent_team` 已经接上了 `swarms`，但目前更像“业务层直接借用第三方 runtime”，不是“我们自己的多智能体平台”。 4. `skills` 已经有加载、安装、审核，但本质还是 Markdown 说明书，不是可学习、可演化、可评估的能力对象。 5. 项目里已经隐约出现了三个方向，但还没有被统一成一个完整架构： - `swarms` 提供多智能体架构能力 - `hermes-agent` 提供 skill 生命周期与长期演进思路 - `OpenHarness` 提供模块化的 harness 设计方法 所以这次重构不是简单“整理目录”，而是把项目从“围绕一个 CLI 主 agent 生长出来的系统”升级成“所有 agent 共享同一内核的自有 agent harness 平台”。 ## 2. 我是怎么想的 我的核心判断是：我们不能继续把第三方库、业务流程、执行控制、UI/API 接口揉在一起，而是应该先定义我们自己的稳定边界，再让第三方能力挂进来。 换句话说，目标不是“把仓库改得更像 swarms / hermes / OpenHarness”，而是： 1. 用 `swarms` 的强项来解决“团队编排”。 2. 用 `hermes-agent` 的强项来解决“skills 怎么创建、维护、学习、沉淀”。 3. 用 `OpenHarness` 的强项来解决“工程边界、模块职责、可维护性”。 4. 最终收口成我们自己的抽象和目录，而不是长期让第三方结构反向塑造我们。 这意味着后续所有设计都应遵守四条原则： ### 2.1 我们要有自己的抽象 不能让业务代码直接依赖： - `third_party/swarms` 的导入路径 - `SwarmRouter` 的参数细节 - 某个第三方 skill 文件格式 - 某个第三方 runtime 的副作用 我们应该先定义自己的核心对象，例如： - `AgentDescriptor` - `SkillSpec` - `SkillVersion` - `TeamSpec` - `ExecutionPlan` - `ProcedureRecord` - `RunRecord` - `BridgeResult` 第三方库只能作为 adapter / backend 存在。 ### 2.2 所有 agent 共享同一套运行内核 后面不应该再保留“CLI 单 agent”和“其他 agent 另一套执行方式”这种概念分叉。 正确做法应该是： 1. 所有 agent 都复用同一个 `AgentLoop` / engine。 2. 主 agent、subagent、team member、A2A local specialist 都只是不同的运行配置和上下文。 3. tools、skills、memory、permissions、MCP、delegation 都在同一套内核里装载。 4. CLI 只是一个 interface，作用是把用户输入送进内核，而不是代表一种单独的 agent 类型。 这样做的意义是： 1. 所有 agent 的能力边界一致。 2. 不会再出现“这个能力只在 CLI 主 agent 可用，子 agent 不一致”的问题。 3. agent 的差异只存在于 profile / policy / prompt / runtime context，而不是存在于不同执行栈里。 ### 2.3 Harness 和业务要分开 当前很多逻辑混在一起：既有“平台级能力”，也有“具体产品接入”。 后面应该分成两层： 1. Harness 层 - tool use - skills - memory - delegation - orchestration - governance 2. Product / Interface 层 - web API - gateway - channel adapters - Outlook / WhatsApp / 外部服务接入 这样平台能力才能稳定，接入层才能随产品变化而变化。 ### 2.4 多智能体是平台能力，不是工具技巧 现在 `spawn_agent_team` 已经存在，但在结构上还像“一个高级工具”。 后面应该把 multi-agent 当成正式 runtime 能力： - 有 plan 层 （计划） - 有 strategy 层 （策略） - 有 execution backend 层 （执行后端） - 有 result normalization 层 （结果归一化） - 有 memory / procedure reuse 层 （内存/过程重用） - 有 governance / safety / skill constraints （治理/安全/技能限制） 这里要特别说明 `2.4` 和 `2.5` 的关系： 1. multi-agent 不是独立于 skills 的第二套指导系统。 2. 我们仍然保留之前的群组讨论机制，也就是“探索式协作 + 流程化执行”两种能力都保留。 3. 但无论是探索式 group discussion，还是流程化 sequential / rearrange / hierarchy，都必须受 skills 指引和约束。 4. 也就是说，skills 决定“应该如何思考、遵守什么边界、优先采用什么方法”，而 multi-agent 负责“由几个人、以什么结构去执行”。 所以后续正确关系应是： `skills -> 约束与方法指导` `multi-agent -> 在 skills 约束下进行探索、讨论、流程化执行` ### 2.5 skills 必须变成生命周期系统 现在的 skills 更像可读文档包，适合“手工维护”，不适合“自动学习”。 如果以后要做到自动创建、自动修订、自动推荐、自动淘汰，skills 必须具备： - 结构化元数据 - 版本号 - 来源与 lineage - 审核状态 - 效果统计 - 与 procedure 的映射关系 - 可回滚、可禁用、可发布 并且这里的 `skills` 不应只服务于“工具使用技巧”，而应成为整个 agent 系统的统一指引层，包括： 1. 主 agent 如何规划和执行 2. subagent / team member 如何行动 3. memory 如何参与判断 4. procedure reuse 如何被触发和约束 5. multi-agent 讨论时允许采用哪些方法、角色分工和输出习惯 换句话说： 1. memory / procedure reuse 不是独立于 skills 的平行系统。 2. 但 memory 的实现标准要以 `hermes-agent` 为准，而不是继续沿用当前偏自由发挥的记忆模型。 3. skills 提供全局行为指引；memory 只保存跨会话仍然有价值的稳定事实；session_search 负责找回历史细节；procedure 只作为可选优化层。 这里要明确四者分工： 1. `skills` - 指导“怎么做” - 约束工具使用、讨论方式、流程化执行方式 2. `memory` - 保存 durable facts - 例如用户偏好、环境事实、项目约定、工具 quirks 3. `session_search` - 检索历史会话细节 - 不把大量过程细节直接塞进 memory 4. `procedure` - 作为 coordinator 内部的复用优化 - 不是主 memory 契约，也不是主要 prompt 注入来源 ## 3. 现有项目现在是咋样的 ### 3.1 当前的主结构 从代码上看，`app-instance/backend` 当前大致是这几块。 注意：下面这些路径仍写作 `nanobot/...`，是因为这里描述的是“现状代码位置”，不是目标命名。 1. 启动与装配 - `nanobot/cli/commands.py` - `nanobot/__main__.py` 2. agent 运行时 - `nanobot/agent/loop.py` - `nanobot/agent/context.py` - `nanobot/agent/tools/*` - `nanobot/session/*` - `nanobot/providers/*` 3. 多 agent / 委派 - `nanobot/agent/delegation.py` - `nanobot/agent_team/*` - `nanobot/a2a/*` 4. Web / Gateway / Channels - `nanobot/web/server.py` - `nanobot/channels/*` - `bridge/` 5. 技能与插件 - `nanobot/skills/*` - `nanobot/agent/skills.py` - `nanobot/agent/plugins.py` 6. 外部运行时耦合点 - 当前主要是 vendored `swarms` ### 3.2 当前已经有的优点 这套代码不是没基础，相反已经有几个很有价值的雏形： 1. 已经有 `AgentRegistry`、`DelegationManager`、`agent_team`，说明“统一委派层”思路已经出现。 2. 已经有 `ProcedureMemory` 和 `RunMemory`，说明“从执行中学习”的基础数据层已经出现。 3. 已经有 `skills` 的加载、安装、审核，说明“受控扩展机制”已经存在。 4. 已经有 `SwarmsBridge`、`SwarmsPolicy`、`SwarmsRunPlanner`，说明多智能体桥接已经不是空白。 所以这次重构不是推倒重来，而是把这些散落的雏形收敛成一个完整架构。 ### 3.3 当前最主要的问题 #### 问题一：装配逻辑散落 同一个后端能力，在 CLI、Web、Gateway 中经常重复装配，甚至行为已经开始漂移。 这会导致： 1. 同样的配置在不同入口行为不同。 2. 改一个入口容易漏另一个入口。 3. 测试覆盖变难。 #### 问题二：`AgentLoop` 太重，但又没有成为唯一内核 `AgentLoop` 已经不是纯 loop，而是“半个 runtime 内核”。 这会导致： 1. 主 agent 与其他 agent 的边界不清。 2. tool、memory、delegation、session、events 相互缠绕。 3. 很多能力只能靠继续往 `AgentLoop` 里塞。 4. 同时又没有真正做到“所有 agent 都统一复用它”。 #### 问题三：`swarms` 接入边界不干净，而且 `third_party` 目录本身会持续恶化维护成本 当前 `agent_team` 虽然有 bridge，但仍然直接依赖： 1. `sys.path` 注入 vendored `swarms` 2. 顶层 `swarms` 包导入副作用 3. `SwarmRouter` 的参数细节 4. `AutoSwarmBuilder` 自己的 LLM 栈 这意味着现在不是“我们调度 swarms”，而是“我们的平台有一部分被 swarms runtime 反向定义了”。 另外，`third_party/` 这种目录在这个项目里不应该长期存在。它会带来两个问题： 1. 仓库边界不清，到底哪些代码是我们的，哪些不是，很难维护。 2. 一旦改动第三方源码，升级、回滚、排障都会变得更脆弱。 #### 问题四：skills 还是静态文档包 现在的 skill 系统适合： - 展示 - 人工安装 - prompt 注入 但不适合： - 自动学习 - 自动合并 - 自动评估 - 版本回滚 - 基于效果做选择 #### 问题五：接口层和核心层耦合过深 `web/server.py` 过大说明一个事实： 平台内核与外部 API、外部接入、外部服务没有完成分层。 ## 4. 后面应该怎么改 ## 4.1 先把系统改成 OpenHarness 风格的能力分组 这里我建议明确参考 OpenHarness 那种“按能力分组、核心目录更扁平”的结构，而不是继续按历史演化路径堆目录。 核心思路是： 1. 用 `engine` 作为唯一运行内核。 2. 用 `coordinator` 负责委派和多 agent 编排。 3. 用 `tools`、`skills`、`memory`、`permissions` 作为独立能力层。 4. 用 `interfaces` 只放 CLI / Web / Gateway / Channels 这类入口。 5. 用 `integrations` 放外部协议和外部系统适配。 这样拆完之后，模块关系应变成： `interfaces -> engine/coordinator/tools/skills/memory -> foundation` 而不是像现在这样互相横穿。 ## 4.2 彻底去掉 `third_party/`，把 `swarms` 改造成可替换 backend ### 当前状态 现在的 `agent_team` 已经接通： - `GroupChat` - `SequentialWorkflow` - `ConcurrentWorkflow` - `AgentRearrange` - `MixtureOfAgents` - `HierarchicalSwarm` 但这些能力还不是“平台正式能力集合”，而是“当前 bridge 恰好能跑通的一部分 swarms 类型”。 更重要的是，当前它们依赖 `third_party/swarms` 这个 vendored 目录，这是后续必须去掉的。 ### 目标状态 后续应该先定义我们自己的团队执行抽象： ```text TeamSpec -> TeamPlanner -> ExecutionPlan -> StrategyBackend -> NormalizedResult ``` 然后： 1. `SwarmsBackend` 只是 `StrategyBackend` 的一个实现。 2. 平台对外暴露的是自己的策略名和能力矩阵。 3. `swarms` 只负责执行，不再负责定义平台边界。 4. 仓库内不再保留 `third_party/`。 5. `swarms` 要么作为外部依赖安装，要么把真正需要的最小能力内聚到我们自己的 backend 模块中。 ### 具体改法 1. 抽出 `coordinator/backends/base.py` - 定义统一 backend 接口 2. 抽出 `coordinator/backends/swarms/` - 把 `swarms_adapter.py` - `swarms_bridge.py` - `swarms_policy.py` - `swarms_planner.py` 中 swarms 相关逻辑收进去 3. 在平台层定义正式支持的 strategy - `group_chat` - `sequential` - `concurrent` - `rearrange` - `mixture` - `hierarchical` - 后续预留 `graph` - 后续预留 `heavy` 4. 所有 strategy 的输入输出都转成我们的统一模型 ### 结果 改完之后： 1. `third_party/` 目录消失。 2. 上层不再知道 `third_party/swarms` 这个路径。 3. 对上层透明的是 `SwarmsBackend`，不是 vendored 源码目录。 ## 4.3 把 `skills` 从静态文档升级成能力生命周期系统 ### 当前状态 现在 skill 基本等于： - 一个目录 - 一个 `SKILL.md` - 一点 frontmatter - 一点审核流程 ### 目标状态 后续 skill 至少要分成三类对象： 1. `SkillDraft` - 自动生成或人工创建 - 还没发布 2. `SkillVersion` - 某个稳定版本 - 可启用/禁用/回滚 3. `SkillRuntimeView` - 当前对模型暴露的生效版本 同时 skill 应该带这些元信息： - `id` - `name` - `version` - `summary` - `usage_rules` - `inputs` - `outputs` - `dependencies` - `source` - `derived_from_procedure` - `review_status` - `metrics` ### 自动学习建议 不要直接让 agent 在线改 live skills。 正确链路应该是： `run result -> procedure candidate -> skill draft -> review -> publish -> runtime use` 这比“自动改 `SKILL.md`”安全得多，也更适合生产环境。 ### 结果 改完之后，skills 不再只是 prompt 资源，而是平台知识层的一等对象。 ## 4.4 以 `hermes-agent` 的 memory 模型为基线重做 memory 层 这里要明确：新的 memory 设计不再以当前 `ProcedureMemory` 为中心，而是以 `hermes-agent` 的 memory 模型为准。 ### 主 memory 契约 新的主 memory 契约应是： 1. 一个统一的 `memory` tool 2. 三个核心动作： - `add` - `replace` - `remove` 3. 两个目标存储： - `memory`：agent 的环境事实、项目约定、工具经验 - `user`：用户画像、偏好、习惯、纠正记录 它的行为应对齐 Hermes： 1. `add` - 追加新条目 - 精确重复时跳过 - 超限时返回当前条目和占用情况 2. `replace` - 用 `old_text` 的短语义片段匹配条目并整体替换 - 多条匹配时要求更精确的 `old_text` 3. `remove` - 也是通过 `old_text` 的语义片段删除 - 多条匹配时同样要求更精确匹配 这里要采用“子串匹配”而不是 UUID，因为这更符合 LLM 的操作习惯。 ### 写入安全与并发安全 新的 memory 层应保留 Hermes 这几个关键约束： 1. 写入前扫描注入/渗透模式 2. 在锁内重新从磁盘加载目标文件 3. 做重复检测和字符上限检测 4. 通过临时文件 + `os.replace()` 做原子写入 也就是说，并发安全的关键不是“先读后写”，而是： `scan -> lock -> reload -> validate -> atomic write` ### 冻结快照模式 新的 memory 层必须采用 frozen snapshot，而不是“每次 memory 写入都改 system prompt”。 规则是： 1. 会话开始时，从磁盘加载 `memory` 和 `user` 2. 立刻冻结成 system prompt snapshot 3. 会话中写入 memory 时，只更新磁盘上的 live state 4. 当前会话里的 system prompt 保持不变 5. 下一个会话开始时，再重新加载最新 memory ### session_search 取代“把所有过程细节塞进 memory” 大量过程细节不应继续塞进 `memory`。 因此新后端应该明确区分： 1. `memory` - 保存小而精的、跨会话稳定有效的事实 2. `session_search` - 检索历史会话 - 支持“无 query 浏览最近会话”和“有 query 的全文搜索 + 摘要” 这个能力后续应在 Beaver 中落成： - `beaver/memory/curated/*` - `beaver/memory/search/*` - `beaver/tools/builtins/memory.py` - `beaver/tools/builtins/session_search.py` ### `ProcedureMemory` 的新定位 这不表示 `ProcedureMemory` 没价值，而是它的地位要下降： 1. `ProcedureMemory` 不再是主 memory 契约 2. 它不应该直接承担“跨会话记忆”职责 3. 它更适合作为 coordinator 内部的流程复用与路由优化层 新的优先级应是： 1. 用户偏好、纠正、环境事实 -> `memory` 2. 历史会话细节 -> `session_search` 3. 稳定方法论和工作法 -> `skills` 4. 团队/流程复用优化 -> `ProcedureMemory` ## 4.5 CLI 不再代表单 agent 模式，只保留为薄入口 当前入口层太厚，后续应该改成： 1. CLI 只做参数解析与 runtime 启动 2. Web 只做 API 与 request/response 映射 3. Gateway 只做渠道接入与消息转发 所有核心能力都由统一的 application services 提供，例如： - `ChatApplicationService` - `DelegationApplicationService` - `TeamRunApplicationService` - `SkillApplicationService` - `MemoryApplicationService` 同时要明确一条原则： CLI 不是“单 agent 专用模式”。 它只是这些 interface 之一： - CLI - Web - Gateway - Channel 无论从哪个入口进来，最终都进入同一套 `AgentLoop` / engine。 这样就不会再出现“CLI 一套 agent，其他入口另一套 agent”的问题。 ## 5. 具体改动后会是什么样 ## 5.1 所有 agent 共用同一套 engine ### 现在 `CLI/Web/Gateway -> 各自装配一套 AgentLoop 或相关依赖` ### 之后 `CLI/Web/Gateway/Channel -> AgentEntryService -> AgentLoop(engine) -> tools/skills/memory/permissions/delegation` 结果是： 1. 主 agent、subagent、team member 复用同一套 engine。 2. 装载逻辑只在 engine 内统一处理一次。 3. 不再保留“CLI 单 agent 概念”。 4. 测试可以直接测 engine 和 service，而不是分别测入口分支。 ## 5.2 多 agent 场景 ### 现在 `spawn_agent_team -> DelegationManager -> AgentTeamOrchestrator -> SwarmsPlanner/Bridge -> SwarmRouter` ### 之后 `spawn_agent_team` `-> DelegationService` `-> TeamApplicationService` `-> TeamPlanner` `-> ExecutionPlan` `-> StrategyBackendRegistry` `-> SwarmsBackend` `-> NormalizedTeamResult` 结果是： 1. 团队能力不再绑定某个第三方 runtime 结构。 2. 可以逐步增加第二种 backend，而不推翻平台层。 3. `swarms` 只是其中一个可插拔执行器。 ## 5.3 skill 场景 ### 现在 `SkillsLoader -> 读 SKILL.md -> 摘要注入 / 手动审核安装` ### 之后 `SkillCatalog` `-> SkillDraftStore` `-> SkillReviewService` `-> SkillPublisher` `-> SkillRuntimeResolver` 结果是： 1. skill 可以有版本。 2. skill 可以从 procedure 生成。 3. skill 可以审核和回滚。 4. skill 可以做效果分析和推荐。 ## 5.4 运行学习场景 ### 现在 `Run details 混在 session / memory / procedure 中` ### 之后 `Run transcript` `-> session_search index` `Durable fact` `-> memory(add/replace/remove)` `Stable method / workaround / reusable workflow` `-> SkillCandidateGenerator` `-> SkillDraft` `-> Review` `-> Publish` `Repeated execution pattern` `-> optional ProcedureMemory` 结果是： 1. durable facts、历史细节、稳定方法三类信息终于分层。 2. 自动学习不会把临时过程污染到主 memory。 3. skills 仍是最高层指导系统，而 memory 变成受控 CRUD 系统。 ## 6. 分阶段落地建议 这次重构不应该一次性推翻，建议分四期做。 ### 第一期：边界清理 目标： 1. 把入口装配统一掉 2. 把 `web/server.py` 开始拆分 3. 把 swarms 相关代码聚到单独 backend 目录 交付物： - 统一 app factory / service wiring - 初步拆分 web routes - `orchestration/backends/swarms/` ### 第二期：平台抽象固化 目标： 1. 定义 team / skill / memory / session_search 的正式模型 2. 让上层只依赖平台模型 交付物： - `TeamSpec` - `SkillSpec` - `ExecutionPlan` - `MemoryEntry` - `MemorySnapshot` - `SessionSearchResult` - `SkillDraft` - `SkillVersion` ### 第三期：skills 生命周期 目标： 1. 从“文档技能”升级到“版本化能力” 2. 打通“稳定方法 -> SkillDraft” 3. 按 Hermes 基线完成 memory CRUD、frozen snapshot、session_search 交付物： - skill catalog - review/publish flow - runtime resolver - memory tool - session search tool ### 第四期：高级多智能体能力 目标： 1. 放开更多正式支持的 strategy 2. 评估 `GraphWorkflow`、`HeavySwarm` 3. 增加 fallback / retry / policy routing 交付物： - 完整 strategy registry - 多 backend 能力矩阵 - team execution fallback ## 7. 重构后的推荐目录 下面这个目录我已经按你说的方向收紧了： 1. 不保留 `third_party/` 2. 不保留“CLI 单 agent”这类结构暗示 3. 尽量参考 OpenHarness 那种按能力分组、观感更规整的布局 4. 每个目录后面都加中文说明 ```text app-instance/backend/ ├── change.md # 这份重构蓝图 ├── README.md # 后端总说明 ├── workflow.md # 运行链路说明 ├── docs/ # 架构文档和迁移文档 │ ├── architecture/ # 核心架构说明 │ └── migration/ # 分阶段迁移计划 ├── beaver/ │ ├── foundation/ # 最底层公共设施：配置、模型、事件、错误、工具函数 │ │ ├── config/ # 配置定义与加载 │ │ ├── models/ # 全局共享数据模型 │ │ ├── events/ # 统一事件模型与事件派发 │ │ ├── errors/ # 统一错误类型 │ │ └── utils/ # 通用工具函数 │ ├── engine/ # 统一 agent 内核，所有 agent 都复用这里 │ │ ├── loop.py # AgentLoop 主循环与执行入口 │ │ ├── loader.py # tools、skills、memory、permissions 的统一装载 │ │ ├── context/ # 上下文拼装 │ │ ├── session/ # 会话状态与持久化 │ │ ├── providers/ # LLM provider 适配 │ │ └── runtime/ # 运行时辅助对象与执行上下文 │ ├── tools/ # 工具系统 │ │ ├── registry/ # 工具注册与发现 │ │ ├── builtins/ # 内置工具 │ │ ├── mcp/ # MCP 工具适配 │ │ └── policies/ # 工具权限与调用约束 │ ├── skills/ # 技能系统 │ │ ├── builtin/ # 内置技能内容 │ │ ├── catalog/ # 技能目录、索引与查询 │ │ ├── drafts/ # 自动生成或待审核的 skill draft │ │ ├── reviews/ # 技能审核流 │ │ ├── publisher/ # 技能发布与版本切换 │ │ └── resolver/ # 运行时技能解析与注入 │ ├── memory/ # 记忆与经验沉淀系统 │ │ ├── curated/ # Hermes 风格的 MEMORY / USER 持久记忆 │ │ ├── search/ # session_search 与历史会话检索 │ │ ├── runs/ # 单次执行记录 │ │ ├── procedures/ # 可选的流程复用优化层 │ │ └── stores/ # 底层存储与原子写实现 │ ├── permissions/ # 权限、沙箱、治理规则 │ │ ├── policies/ # 权限策略 │ │ ├── guards/ # 执行前检查 │ │ └── profiles/ # 不同 agent 运行权限画像 │ ├── coordinator/ # 多 agent 协调层，参考 OpenHarness 的 coordinator 风格 │ │ ├── delegation/ # 委派与任务分发 │ │ ├── registry/ # agent registry 与 agent descriptor │ │ ├── planner/ # 团队 planning 与 execution plan 生成 │ │ ├── execution/ # 执行控制、fallback、聚合 │ │ ├── backends/ # 可替换的多 agent backend │ │ │ ├── base.py # backend 抽象接口 │ │ │ └── swarms/ # swarms backend 封装，不再直接暴露第三方目录 │ │ └── team/ # team 级模型与编排对象 │ ├── services/ # application services，对外提供统一能力入口 │ │ ├── agent_service.py # 统一 agent 运行入口 │ │ ├── team_service.py # 多 agent 执行入口 │ │ ├── skill_service.py # 技能管理入口 │ │ ├── memory_service.py # memory 查询与写入入口 │ │ └── admin_service.py # 平台管理入口 │ ├── interfaces/ # 薄入口层，不承载核心业务 │ │ ├── cli/ # CLI 入口，只负责把请求送进 services/engine │ │ ├── web/ # FastAPI 接口层 │ │ │ ├── app.py # Web app factory │ │ │ ├── routes/ # 路由拆分 │ │ │ ├── schemas/ # Web 请求/响应模型 │ │ │ └── deps.py # Web 依赖装配 │ │ ├── gateway/ # 常驻 worker / gateway 入口 │ │ └── channels/ # Telegram/Slack/Email 等渠道入口 │ ├── integrations/ # 外部系统与协议集成 │ │ ├── a2a/ # A2A 协议与 client │ │ ├── mcp/ # MCP 连接与管理 │ │ ├── outlook/ # Outlook 集成 │ │ ├── whatsapp/ # WhatsApp bridge 适配 │ │ └── providers/ # 外部 provider 特定集成 │ ├── plugins/ # 插件系统 │ │ ├── loader.py # 插件发现与装载 │ │ ├── registry.py # 插件注册表 │ │ └── hooks.py # 插件 hooks │ └── templates/ # 默认模板、system prompt 模板、内置文本资源 ├── tests/ # 测试 │ ├── unit/ # 单元测试 │ ├── integration/ # 集成测试 │ ├── e2e/ # 端到端测试 │ └── fixtures/ # 测试数据与夹具 └── bridge/ # 独立 Node/bridge 代码，作为外部桥接层保留 ``` ## 8. 最终结论 这次重构的本质不是“把代码拆小一点”，而是完成三件事： 1. 把当前项目从“围绕 `AgentLoop` 生长的单体系统”升级成“所有 agent 共用一个 engine 的可维护 harness 平台”。 2. 把 `swarms` 从“放在 `third_party/` 里的深耦合运行时”降级成“可替换的多智能体 backend”。 3. 把 `skills` 从“静态 Markdown 包”升级成“可学习、可审核、可发布、可回滚的能力系统”。 如果这三件事做成了，后面再扩多智能体架构、自动学习、插件生态、外部接入，代码就不会继续失控。