351 lines
29 KiB
Markdown
351 lines
29 KiB
Markdown
# backend-old -> backend 可用移植指南
|
||
|
||
这份文档描述的是：从 `app-instance/backend-old` 迁到新的 `app-instance/backend` 时，哪些 Python 代码是可用的、应该放到新目录的哪里、哪些可以直接迁、哪些必须拆分后迁。
|
||
|
||
本文默认遵守以下前提：
|
||
|
||
1. 新后端统一使用 `beaver` 命名。
|
||
2. 所有 agent 最终都复用同一套 `beaver.engine.AgentLoop`。
|
||
3. 新代码按当前新目录落点来放，不再向 `nanobot/` 回写。
|
||
4. 不保留 `third_party/`。
|
||
5. memory 设计以 `hermes-agent` 为基线：统一 CRUD memory tool + frozen snapshot + session_search。
|
||
|
||
## 1. 迁移范围
|
||
|
||
本文覆盖的是 `backend-old` 中的自有 Python 源码：
|
||
|
||
- `backend-old/nanobot/**/*.py`
|
||
- `backend-old/nanobot/llm_audit.py`
|
||
|
||
本文明确不覆盖：
|
||
|
||
- `.venv/`
|
||
- `.pytest_cache/`
|
||
- `.ruff_cache/`
|
||
- `third_party/`
|
||
- `bridge/` 里的 Node 代码
|
||
|
||
## 2. 迁移判定说明
|
||
|
||
| 判定 | 含义 |
|
||
| --- | --- |
|
||
| `可直接迁移` | 改导入路径、命名后可基本原样落到新位置 |
|
||
| `小幅重构` | 主体逻辑可复用，但要改依赖注入、类型名或路径 |
|
||
| `拆分迁移` | 旧文件职责过大，必须拆成多个新文件 |
|
||
| `重写迁移` | 只保留行为目标，不建议原样搬代码 |
|
||
| `不迁移` | 不进入新后端 |
|
||
|
||
## 3. 总体迁移顺序
|
||
|
||
建议按下面顺序迁：
|
||
|
||
1. `foundation/config + foundation/events + foundation/models + foundation/utils`
|
||
2. `skills + plugins`
|
||
3. `memory(curated + session_search baseline)`
|
||
4. `engine/session + engine/providers + engine/context + engine/loop`
|
||
5. `tools`
|
||
6. `coordinator`
|
||
7. `interfaces/web + interfaces/cli + interfaces/channels + services`
|
||
8. `integrations/a2a + integrations/outlook + integrations/authz + integrations/mcp`
|
||
|
||
原因：
|
||
|
||
1. `engine`、`coordinator`、`interfaces` 都依赖 `config`、`events`、`models`。
|
||
2. `skills` 和 `memory` 必须先定契约，因为 system prompt 注入、memory tool、session_search 都会反向约束 engine。
|
||
3. `web/server.py`、`cli/commands.py` 只有在服务层和内核层稳定后才值得拆。
|
||
|
||
## 4. 包初始化文件如何处理
|
||
|
||
下面这些旧 `__init__.py` 不建议原样迁移，只保留“最小 re-export”或空包文件：
|
||
|
||
- `nanobot/__init__.py`
|
||
- `nanobot/a2a/__init__.py`
|
||
- `nanobot/agent/__init__.py`
|
||
- `nanobot/agent_team/__init__.py`
|
||
- `nanobot/authz/__init__.py`
|
||
- `nanobot/bus/__init__.py`
|
||
- `nanobot/channels/__init__.py`
|
||
- `nanobot/cli/__init__.py`
|
||
- `nanobot/config/__init__.py`
|
||
- `nanobot/cron/__init__.py`
|
||
- `nanobot/heartbeat/__init__.py`
|
||
- `nanobot/providers/__init__.py`
|
||
- `nanobot/session/__init__.py`
|
||
- `nanobot/templates/__init__.py`
|
||
- `nanobot/templates/memory/__init__.py`
|
||
- `nanobot/utils/__init__.py`
|
||
- `nanobot/web/__init__.py`
|
||
|
||
统一处理规则：
|
||
|
||
1. 不复制旧的 lazy import / `__getattr__` 设计。
|
||
2. 目标文件稳定后，再在对应 `beaver/*/__init__.py` 里做显式导出。
|
||
|
||
## 5. Foundation 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/config/schema.py` | `Config`, `AgentDefaults`, `AgentsConfig`, `ProviderConfig`, `ProvidersConfig`, `ToolsConfig`, `ChannelsConfig`, `AuthzConfig`, `BackendIdentityConfig` | `beaver/foundation/config/schema.py` | `小幅重构` | 主体模型可迁；`Config._match_provider/get_provider*` 这类 provider 解析逻辑移到 `beaver/engine/providers/factory.py`。 |
|
||
| `nanobot/config/loader.py` | `get_config_path`, `get_data_dir`, `load_config`, `save_config`, `_migrate_config` | `beaver/foundation/config/loader.py` | `可直接迁移` | 迁移时把默认路径和 `beaver` 命名改掉。 |
|
||
| `nanobot/config/paths.py` | `get_data_dir`, `get_media_dir` | `beaver/foundation/config/paths.py` | `可直接迁移` | 纯 path helper。 |
|
||
| `nanobot/utils/helpers.py` | `ensure_dir`, `get_workspace_path`, `get_sessions_path`, `get_skills_path`, `timestamp`, `truncate_string`, `safe_filename`, `parse_session_key` | `beaver/foundation/utils/helpers.py` | `可直接迁移` | 纯工具函数，直接复用。 |
|
||
| `nanobot/bus/events.py` | `InboundMessage`, `OutboundMessage` | `beaver/foundation/events/messages.py` | `可直接迁移` | 建议作为全局消息模型。 |
|
||
| `nanobot/bus/queue.py` | `MessageBus` | `beaver/foundation/events/message_bus.py` | `小幅重构` | 类本身可迁，但后续由 `services` 和 `interfaces/gateway` 注入。 |
|
||
| `nanobot/agent/process_events.py` | `new_run_id`, `utc_now_iso`, `process_event_sink`, `process_run_context`, `current_process_run_id`, `has_process_event_sink`, `emit_process_event` | `beaver/foundation/events/process.py` | `可直接迁移` | 这是全局过程事件层，应该上提。 |
|
||
| `nanobot/agent/run_result.py` | `normalize_summary_text`, `contains_placeholder_summary`, `has_meaningful_summary`, `AgentRunResult` | `beaver/foundation/models/run_result.py` | `可直接迁移` | 给 engine、coordinator、services 共享。 |
|
||
| `nanobot/cron/types.py` | `CronSchedule`, `CronPayload`, `CronAction`, `CronExecutionResult`, `CronJobState`, `CronJob`, `CronStore` | `beaver/foundation/models/cron.py` | `可直接迁移` | 纯类型定义。 |
|
||
| `nanobot/llm_audit.py` | `write_llm_audit_event`, `redact_mapping`, `summarize_messages`, `summarize_tool_calls`, `summarize_tools`, `summarize_exception` | `beaver/foundation/utils/llm_audit.py` | `可直接迁移` | 审计逻辑不应挂在旧根路径。 |
|
||
|
||
## 6. Engine 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/session/manager.py` | `Session`, `SessionManager` | `beaver/engine/session/models.py`, `beaver/engine/session/manager.py` | `可直接迁移` | `Session` 和 `SessionManager` 建议拆开。 |
|
||
| `nanobot/agent/context.py` | `ContextBuilder.build_system_prompt`, `build_messages`, `add_tool_result`, `add_assistant_message` | `beaver/engine/context/builder.py` | `小幅重构` | 需要改成只注入 frozen memory snapshot，而不是直接读 live memory。 |
|
||
| `nanobot/agent/loop.py` | `AgentLoop` 全类 | `beaver/engine/loop.py` | `拆分迁移` | 旧文件过载，不能整块搬。 |
|
||
| `nanobot/agent/memory.py` | `MemoryStore.read_long_term`, `write_long_term`, `append_history`, `get_memory_context`, `consolidate` | `beaver/memory/curated/store.py`, `beaver/memory/curated/snapshot.py`, `beaver/memory/search/transcript_store.py` | `重写迁移` | 新标准不再沿用旧 `consolidate()` 模型；按 Hermes 改成 CRUD memory + frozen snapshot + session transcript search。 |
|
||
| `nanobot/providers/base.py` | `ToolCallRequest`, `LLMResponse`, `LLMProvider` | `beaver/engine/providers/base.py` | `可直接迁移` | provider 契约层。 |
|
||
| `nanobot/providers/registry.py` | `ProviderSpec`, `find_by_model`, `find_gateway`, `find_by_name` | `beaver/engine/providers/registry.py` | `可直接迁移` | registry 自包含度高。 |
|
||
| `nanobot/providers/litellm_provider.py` | `LiteLLMProvider` | `beaver/engine/providers/litellm.py` | `小幅重构` | 主要改导入路径和 `Config` 依赖。 |
|
||
| `nanobot/providers/openai_codex_provider.py` | `OpenAICodexProvider`, `_convert_messages`, `_consume_sse`, `_friendly_error` | `beaver/engine/providers/codex.py` | `小幅重构` | 主体可迁。 |
|
||
| `nanobot/providers/custom_provider.py` | `CustomProvider` | `beaver/engine/providers/custom.py` | `可直接迁移` | 文件小，直接迁。 |
|
||
| `nanobot/providers/transcription.py` | `GroqTranscriptionProvider` | `beaver/engine/providers/transcription.py` | `可直接迁移` | 辅助 provider，不阻塞主线。 |
|
||
| `nanobot/agent/subagent.py` | `SubagentManager.run_local_task`, `_build_local_tools`, `_build_subagent_prompt`, `_strip_think`, `_tool_hint` | `beaver/engine/runtime/local_runner.py` | `重写迁移` | 新架构下不应保留 `SubagentManager` 这个名字；只抽出本地 agent 运行能力。 |
|
||
| `nanobot/agent/subagents.py` | `normalize_subagent_id`, `SubagentSpec`, `LocalSubagentStore` | `beaver/coordinator/registry/local_subagent_store.py` | `小幅重构` | 数据结构可复用，但要切到 `beaver` 命名和新 registry。 |
|
||
|
||
### 6.1 `agent/loop.py` 函数级拆分
|
||
|
||
旧 `nanobot/agent/loop.py` 应这样拆：
|
||
|
||
| 旧函数 | 新位置 |
|
||
| --- | --- |
|
||
| `AgentLoop.__init__` | `beaver/engine/loop.py` |
|
||
| `apply_runtime_config` | `beaver/engine/loader.py` |
|
||
| `_register_default_tools` | `beaver/engine/loader.py` + `beaver/tools/registry/tool_registry.py` |
|
||
| `_connect_mcp`, `_clear_mcp_tools`, `reload_mcp_servers`, `get_mcp_servers_view` | `beaver/engine/runtime/mcp_runtime.py` |
|
||
| `_set_tool_context` | `beaver/engine/loop.py` |
|
||
| `_build_skills_loader` | `beaver/skills/resolver/runtime.py` |
|
||
| `_run_agent_loop`, `_process_message`, `_save_turn`, `process_system_announcement`, `process_direct` | `beaver/engine/loop.py` |
|
||
| `_get_consolidation_lock`, `_prune_consolidation_lock`, `_consolidate_memory` | `不直接迁移；改成 beaver/tools/builtins/memory.py + beaver/memory/curated/* + beaver/memory/search/*` |
|
||
| `run`, `stop`, `close_mcp` | `beaver/engine/loop.py` |
|
||
|
||
## 7. Tools 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/agent/tools/base.py` | `Tool`, `validate_params`, `to_schema` | `beaver/tools/base.py` | `可直接迁移` | 工具基类。 |
|
||
| `nanobot/agent/tools/registry.py` | `ToolRegistry` | `beaver/tools/registry/tool_registry.py` | `可直接迁移` | registry 逻辑自包含。 |
|
||
| `nanobot/agent/tools/filesystem.py` | `ReadFileTool`, `WriteFileTool`, `EditFileTool`, `ListDirTool` | `beaver/tools/builtins/filesystem.py` | `小幅重构` | 路径保护规则建议进一步抽到 `beaver/permissions/guards/filesystem.py`。 |
|
||
| `nanobot/agent/tools/shell.py` | `ExecTool`, `_guard_command`, `_guard_protected_paths` | `beaver/tools/builtins/shell.py` | `小幅重构` | 命令保护逻辑建议下沉到 `permissions/guards/shell.py`。 |
|
||
| `nanobot/agent/tools/web.py` | `WebSearchTool`, `WebFetchTool` | `beaver/tools/builtins/web.py` | `可直接迁移` | 改导入路径即可。 |
|
||
| `nanobot/agent/tools/message.py` | `MessageTool`, `set_context`, `set_send_callback`, `start_turn` | `beaver/tools/builtins/message.py` | `可直接迁移` | 保持 tool 形态。 |
|
||
| `nanobot/agent/tools/spawn.py` | `DelegationTool`, `SpawnSubagentTool`, `SpawnAgentTeamTool`, `NestedDelegateTool` | `beaver/tools/builtins/spawn.py` | `小幅重构` | tool 壳可留；执行全部接 `beaver/coordinator/delegation/manager.py`。 |
|
||
| `nanobot/agent/tools/cron.py` | `CronTool` | `beaver/tools/builtins/cron.py` | `可直接迁移` | 与 `CronService` 对接即可。 |
|
||
| `nanobot/agent/tools/cron_action.py` | `CronActionTool` | `beaver/tools/builtins/cron.py` | `小幅重构` | 合并成同一 cron 工具模块更合理。 |
|
||
| `nanobot/agent/tools/mcp.py` | `MCPToolWrapper`, `connect_mcp_servers`, `_describe_mcp_exception` | `beaver/tools/mcp/wrapper.py`, `beaver/tools/mcp/connect.py` | `小幅重构` | 连接逻辑和 wrapper 分开。 |
|
||
| `无旧文件一一对应（以 Hermes 为准新增）` | `memory_tool(action, target, content, old_text)` | `beaver/tools/builtins/memory.py` | `新增实现` | 统一 memory CRUD 工具，优先级高于旧 `MemoryStore.consolidate()` 逻辑。 |
|
||
| `无旧文件一一对应（以 Hermes 为准新增）` | `session_search(query, role_filter, limit)` | `beaver/tools/builtins/session_search.py` | `新增实现` | 历史会话检索不再靠把大量过程细节塞进 memory。 |
|
||
|
||
## 8. Skills、Plugins、Memory 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/agent/skills.py` | `SkillsLoader.list_skills`, `load_skill`, `load_skills_for_context`, `build_skills_summary`, `get_always_skills`, `get_skill_metadata`, `get_skill_agent_cards`, `list_skill_agent_cards` | `beaver/skills/catalog/loader.py`, `beaver/skills/resolver/runtime.py` | `拆分迁移` | catalog 负责扫描/索引/元数据；resolver 负责运行时注入。 |
|
||
| `nanobot/agent/skill_reviews.py` | `SkillReviewManager` | `beaver/skills/reviews/manager.py` | `小幅重构` | ZIP 解包、安全检查、review 状态管理都能复用。 |
|
||
| `nanobot/agent/plugins.py` | `PluginAgent`, `PluginCommand`, `Plugin`, `PluginLoader` | `beaver/plugins/models.py`, `beaver/plugins/loader.py`, `beaver/plugins/registry.py` | `小幅重构` | 这是最适合先迁的一批。 |
|
||
| `nanobot/agent/marketplace.py` | `MarketplaceEntry`, `MarketplacePluginInfo`, `MarketplaceManager` | `beaver/plugins/marketplace.py` | `可直接迁移` | 市场逻辑相对独立。 |
|
||
| `nanobot/agent_team/memory.py` | `ProcedureMemory`, `RunMemory`, `task_tokens`, `similarity_score`, `clip_confidence` | `beaver/memory/procedures/procedure_memory.py`, `beaver/memory/runs/run_memory.py` | `小幅重构` | 这些不再代表主 memory 契约，而是 coordinator/analytics 的可选优化层。 |
|
||
| `nanobot/agent/memory.py` | `MemoryStore` | `beaver/memory/curated/store.py`, `beaver/memory/curated/snapshot.py`, `beaver/memory/search/transcript_store.py` | `重写迁移` | 见第 6 节；memory 基线改成 Hermes 风格。 |
|
||
| `nanobot/skills/subagent-manager/scripts/subagentctl.py` | `cmd_list`, `cmd_show`, `cmd_create`, `cmd_delete`, `cmd_set_system_prompt`, `cmd_add_mcp_http`, `cmd_add_mcp_stdio`, `cmd_remove_mcp` | `beaver/interfaces/cli/subagentctl.py` | `小幅重构` | 只迁 CLI 管理能力，不再绑定 `nanobot` store。 |
|
||
|
||
### 8.1 `agent/skills.py` 函数级拆分
|
||
|
||
| 旧函数/方法 | 新位置 |
|
||
| --- | --- |
|
||
| `list_skills`, `get_skill_metadata`, `get_skill_agent_cards`, `list_skill_agent_cards` | `beaver/skills/catalog/loader.py` |
|
||
| `load_skill`, `load_skills_for_context`, `build_skills_summary`, `get_always_skills` | `beaver/skills/resolver/runtime.py` |
|
||
| `_strip_frontmatter`, `_parse_nanobot_metadata`, `_check_requirements`, `_get_missing_requirements`, `_get_skill_description` | `beaver/skills/catalog/utils.py` 或 `loader.py` 内部私有函数 |
|
||
|
||
### 8.2 Memory 迁移基线
|
||
|
||
新的 memory 迁移必须遵守下面这条，而不是直接复制旧 `MemoryStore + ProcedureMemory` 设计：
|
||
|
||
1. 持久化记忆只保留两类：
|
||
- `memory`
|
||
- `user`
|
||
2. 写操作统一通过 `memory` tool：
|
||
- `add`
|
||
- `replace`
|
||
- `remove`
|
||
3. `replace/remove` 使用短语义片段匹配，不要求 UUID
|
||
4. 写入协议必须是：
|
||
- 注入扫描
|
||
- 文件锁
|
||
- 锁内 reload
|
||
- 重复/上限检测
|
||
- 原子写入
|
||
5. system prompt 只注入 frozen snapshot
|
||
6. 历史细节通过 `session_search` 检索，不扩大 memory
|
||
7. 稳定的方法论、工作法、可复用技巧进入 `skills`
|
||
8. `ProcedureMemory` 只保留为 coordinator 的复用优化
|
||
|
||
## 9. Coordinator 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/agent/agent_registry.py` | `AgentDescriptor`, `WorkspaceAgentStore`, `AgentRegistry` | `beaver/coordinator/registry/models.py`, `workspace_store.py`, `agent_registry.py` | `拆分迁移` | descriptor、store、registry 三类职责应拆开。 |
|
||
| `nanobot/agent/delegation.py` | `DelegationRun`, `DelegationManager` | `beaver/coordinator/delegation/manager.py`, `beaver/coordinator/execution/delegation_run.py`, `beaver/coordinator/delegation/events.py` | `拆分迁移` | 旧文件职责最重，不能原样搬。 |
|
||
| `nanobot/a2a/client.py` | `A2AClient`, `A2AError`, `A2AUnsupportedMethodError`, `A2AStreamEvent` | `beaver/integrations/a2a/client.py` | `小幅重构` | A2A 是协议层，适合独立迁。 |
|
||
| `nanobot/agent_team/types.py` | `ExecutionMode`, `ResolvedTeamPlan`, `SwarmsRunSpec`, `SwarmsRunResult`, `ProcedureRecord`, `RunRecord`, `BridgeAttempt`, `BridgeResult` | `beaver/coordinator/team/types.py` | `可直接迁移` | 类型层稳定，但 `ProcedureRecord/RunRecord` 不再作为主 memory 契约。 |
|
||
| `nanobot/agent_team/orchestrator.py` | `AgentTeamOrchestrator.run_task` | `beaver/coordinator/team/orchestrator.py` | `小幅重构` | 是 team 主入口。 |
|
||
| `nanobot/agent_team/provisioning.py` | `ProvisioningManager`, `SpecialistProvisionResult` | `beaver/coordinator/team/provisioning.py` | `重写迁移` | 旧实现绑定 `LocalSubagentStore + Config + gateway port`，要改成新 registry 接口。 |
|
||
| `nanobot/agent_team/target_resolver.py` | `TargetResolver.resolve_team_targets`, `_select_existing_for_role_with_llm` | `beaver/coordinator/team/target_resolver.py` | `小幅重构` | 主要改 provider/registry/provisioning 注入。 |
|
||
| `nanobot/agent_team/swarms_policy.py` | `SwarmsPolicy` | `beaver/coordinator/backends/swarms/policy.py` | `可直接迁移` | 纯 guardrail，可先迁。 |
|
||
| `nanobot/agent_team/swarms_planner.py` | `SwarmsRunPlanner` | `beaver/coordinator/planner/swarms.py` | `小幅重构` | planner 逻辑稳定，但要切掉 `third_party` 假设。 |
|
||
| `nanobot/agent_team/swarms_bridge.py` | `SwarmsBridge` | `beaver/coordinator/backends/swarms/bridge.py` | `小幅重构` | 结果归一化和 backend 运行桥接分层很好。 |
|
||
| `nanobot/agent_team/swarms_adapter.py` | `ensure_swarms_importable`, `load_swarms_runtime`, `safe_swarms_name`, `NanobotAgentAdapter` | `beaver/coordinator/backends/swarms/runtime.py`, `adapter.py` | `重写迁移` | 不再允许 `third_party/` 路径探测；只保留 adapter 设计。 |
|
||
|
||
### 9.1 `agent/delegation.py` 函数级拆分
|
||
|
||
| 旧函数/方法 | 新位置 |
|
||
| --- | --- |
|
||
| `dispatch_subagent`, `dispatch_agent_team`, `_dispatch`, `_run_dispatch` | `beaver/coordinator/delegation/manager.py` |
|
||
| `_emit_team_progress`, `_emit_agent_started`, `_emit_agent_finished`, `_emit_agent_cancelled`, `_emit_group_started`, `_emit_group_finished`, `_publish_prefixed_progress`, `_emit_direct_user_message` | `beaver/coordinator/delegation/events.py` |
|
||
| `_run_team_member_for_swarms`, `_execute_descriptor`, `_build_progress_callback`, `_build_task_callback` | `beaver/coordinator/execution/member_runner.py` |
|
||
| `_resolve_single`, `_resolve_nested_delegate`, `_normalize_skill_names`, `_build_skill_context`, `_augment_task_with_skills` | `beaver/coordinator/delegation/manager.py` |
|
||
| `cancel`, `cancel_all`, `_cancel_remote_tasks`, `_announce_cancelled` | `beaver/coordinator/execution/cancel.py` 或先保留在 `manager.py` |
|
||
| `_announce_single_result`, `_announce_orchestrator_result`, `_publish_announcement`, `_notify_direct_announcement` | `beaver/coordinator/delegation/announcement.py` |
|
||
|
||
## 10. Services 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/cron/service.py` | `CronService` | `beaver/services/cron_service.py` | `小幅重构` | 保持后台服务角色，不要再埋在 `nanobot/cron/` 目录。 |
|
||
| `nanobot/cron/runtime.py` | `run_cron_job`, `_build_execution_context`, `_resolve_session_key` | `beaver/services/cron_runtime.py` | `小幅重构` | 与 `AgentLoop`、Web、CLI 的对接点要更新。 |
|
||
| `nanobot/heartbeat/service.py` | `HeartbeatService` | `beaver/services/heartbeat_service.py` | `可直接迁移` | 后台服务类，自包含度高。 |
|
||
|
||
## 11. Interfaces 层迁移映射
|
||
|
||
### 11.1 CLI
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/__main__.py` | 模块入口 | `beaver/interfaces/cli/main.py` | `可直接迁移` | 只保留入口壳。 |
|
||
| `nanobot/cli/commands.py` | `main`, `version_callback`, `agent`, `gateway`, `web`, `onboard`, `_create_workspace_templates`, `status`, `channels_*`, `cron_*`, `provider_*` | `beaver/interfaces/cli/main.py`, `beaver/interfaces/cli/commands/*.py`, `beaver/services/*.py` | `拆分迁移` | 旧 CLI 同时做了命令声明、provider 装配、gateway/web 启动、cron 管理。 |
|
||
|
||
### 11.2 `cli/commands.py` 函数级拆分
|
||
|
||
| 旧函数 | 新位置 |
|
||
| --- | --- |
|
||
| `main`, `version_callback` | `beaver/interfaces/cli/main.py` |
|
||
| `agent` | `beaver/interfaces/cli/commands/agent.py`，内部调用 `beaver/services/agent_service.py` |
|
||
| `gateway` | `beaver/interfaces/gateway/main.py` |
|
||
| `web` | `beaver/interfaces/cli/commands/web.py`，内部调用 `beaver/interfaces/web/app.py` |
|
||
| `_make_provider` | `beaver/engine/providers/factory.py` |
|
||
| `onboard`, `_create_workspace_templates`, `status` | `beaver/services/admin_service.py` + CLI 薄包装 |
|
||
| `channels_main`, `channels_status`, `channels_login` | `beaver/interfaces/cli/commands/channels.py` |
|
||
| `cron_main`, `cron_list`, `cron_add`, `cron_remove`, `cron_enable`, `cron_run` | `beaver/interfaces/cli/commands/cron.py` + `beaver/services/cron_service.py` |
|
||
| `provider_main`, `_register_login`, `provider_login`, `_login_openai_codex`, `_login_github_copilot` | `beaver/interfaces/cli/commands/providers.py` + `beaver/services/admin_service.py` |
|
||
| `_flush_pending_tty_input`, `_restore_terminal`, `_init_prompt_session`, `_print_agent_response`, `_is_exit_command`, `_read_interactive_input_async`, `_exit_after_group_help`, `_get_bridge_dir` | `beaver/interfaces/cli/tty.py` |
|
||
|
||
### 11.3 Web
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/web/server.py` | `create_app`, `WebSocketBroadcaster`, 所有 `*Request/*Response` 模型、所有 auth / handoff / route helper | `beaver/interfaces/web/app.py`, `deps.py`, `realtime.py`, `auth.py`, `routes/*.py`, `schemas/*.py` | `拆分迁移` | 这是第二个最大拆分热点。 |
|
||
| `nanobot/web/files.py` | `save_file`, `get_file_metadata`, `list_files`, `browse_workspace`, `save_to_workspace`, `delete_workspace_path`, `create_workspace_dir` | `beaver/interfaces/web/files.py`, `beaver/interfaces/web/routes/files.py` | `小幅重构` | 纯文件 API 逻辑，应该从 `server.py` 分离出去。 |
|
||
| `nanobot/web/outlook.py` | `connect_workspace`, `disconnect_workspace`, `outlook_status`, `get_overview`, `get_message_detail`, `list_messages`, `list_events`, `ensure_outlook_mcp_registration` | `beaver/integrations/outlook/service.py`，由 `beaver/interfaces/web/routes/outlook.py` 调用 | `小幅重构` | 核心逻辑应放 integration，不应继续留在 web 包下。 |
|
||
|
||
### 11.4 `web/server.py` 函数级拆分
|
||
|
||
| 旧函数/类型 | 新位置 |
|
||
| --- | --- |
|
||
| `create_app` | `beaver/interfaces/web/app.py` |
|
||
| `ChatRequest`, `ChatResponse` | `beaver/interfaces/web/schemas/chat.py` |
|
||
| `AddCronJobRequest`, `ToggleCronJobRequest` | `beaver/interfaces/web/schemas/cron.py` |
|
||
| `AddMarketplaceRequest`, `ApproveSkillReviewRequest` | `beaver/interfaces/web/schemas/plugins.py`, `skills.py` |
|
||
| `AddAgentRequest`, `_discover_agent_payload`, `_manual_agent_payload`, `_should_auto_discover_agent` | `beaver/interfaces/web/routes/agents.py` + `beaver/interfaces/web/schemas/agents.py` |
|
||
| `MCPServerRequest` | `beaver/interfaces/web/schemas/mcp.py` |
|
||
| `SubagentRequest` | `beaver/interfaces/web/schemas/delegation.py` |
|
||
| `OutlookConnectionRequest` | `beaver/interfaces/web/schemas/outlook.py` |
|
||
| `LoginRequest`, `RegisterRequest`, `AuthzRegisterBackendRequest`, `LocalBackendIdentityRequest`, `HandoffConsumeRequest` | `beaver/interfaces/web/schemas/auth.py` |
|
||
| `WebSocketBroadcaster` | `beaver/interfaces/web/realtime.py` |
|
||
| `_issue_web_token`, `_require_web_user`, `_issue_handoff_code`, `_consume_handoff_code`, `_prune_handoff_codes`, `_handoff_*` | `beaver/interfaces/web/auth.py` |
|
||
| `_register_routes` | 删除；改为 `beaver/interfaces/web/routes/*.py` 各自注册 |
|
||
| `_make_provider` | 删除；使用 `beaver/engine/providers/factory.py` |
|
||
| `_serialize_job` | `beaver/interfaces/web/serializers/cron.py` 或 `schemas/cron.py` |
|
||
|
||
### 11.5 Channels
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/channels/base.py` | `BaseChannel` | `beaver/interfaces/channels/base.py` | `可直接迁移` | 通道抽象基类。 |
|
||
| `nanobot/channels/manager.py` | `ChannelManager` | `beaver/interfaces/channels/manager.py` | `小幅重构` | 初始化逻辑要改为 `beaver` config。 |
|
||
| `nanobot/channels/dingtalk.py` | `NanobotDingTalkHandler`, `DingTalkChannel` | `beaver/interfaces/channels/dingtalk.py` | `小幅重构` | 改命名和 config 依赖。 |
|
||
| `nanobot/channels/discord.py` | `_split_message`, `DiscordChannel` | `beaver/interfaces/channels/discord.py` | `可直接迁移` | 主要改导入路径。 |
|
||
| `nanobot/channels/email.py` | `EmailChannel` | `beaver/interfaces/channels/email.py` | `可直接迁移` | 通道逻辑自包含。 |
|
||
| `nanobot/channels/feishu.py` | `_extract_*`, `FeishuChannel` | `beaver/interfaces/channels/feishu.py` | `可直接迁移` | 保持通道粒度。 |
|
||
| `nanobot/channels/matrix.py` | `_filter_matrix_html_attribute`, `_render_markdown_html`, `_build_matrix_text_content`, `MatrixChannel` | `beaver/interfaces/channels/matrix.py` | `可直接迁移` | 主要改导入。 |
|
||
| `nanobot/channels/mochat.py` | `MochatBufferedEntry`, `DelayState`, `MochatTarget`, `MochatChannel` | `beaver/interfaces/channels/mochat.py` | `小幅重构` | 依赖 config 较多。 |
|
||
| `nanobot/channels/qq.py` | `_make_bot_class`, `QQChannel` | `beaver/interfaces/channels/qq.py` | `可直接迁移` | 主要改配置路径。 |
|
||
| `nanobot/channels/slack.py` | `SlackChannel` | `beaver/interfaces/channels/slack.py` | `可直接迁移` | 主要改导入路径。 |
|
||
| `nanobot/channels/telegram.py` | `_markdown_to_telegram_html`, `_split_message`, `TelegramChannel` | `beaver/interfaces/channels/telegram.py` | `可直接迁移` | 通道逻辑自包含。 |
|
||
| `nanobot/channels/whatsapp.py` | `WhatsAppChannel` | `beaver/interfaces/channels/whatsapp.py` | `小幅重构` | 作为通道入口保留；桥接细节可抽到 `beaver/integrations/whatsapp/bridge.py`。 |
|
||
|
||
## 12. Integrations 层迁移映射
|
||
|
||
| 旧文件 | 关键类/函数 | 新位置 | 判定 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `nanobot/a2a/client.py` | `A2AClient` 全类 | `beaver/integrations/a2a/client.py` | `小幅重构` | 见第 9 节。 |
|
||
| `nanobot/web/outlook.py` | Outlook MCP 连接、状态、消息和日历方法 | `beaver/integrations/outlook/service.py` | `小幅重构` | 见第 11 节。 |
|
||
| `nanobot/authz/client.py` | `BackendRegistrationResult`, `AuthzClient` | `beaver/integrations/authz/client.py` | `可直接迁移` | 纯外部服务 client；新目录里需新增 `authz/`。 |
|
||
| `nanobot/providers/transcription.py` | `GroqTranscriptionProvider` | `beaver/integrations/providers/transcription.py` 或 `beaver/engine/providers/transcription.py` | `可直接迁移` | 二选一，取决于后续是否把 transcription 视为主 provider。 |
|
||
| `nanobot/agent/tools/mcp.py` | `connect_mcp_servers` | `beaver/integrations/mcp/connection.py` + `beaver/tools/mcp/wrapper.py` | `小幅重构` | 协议连接与工具包装分开。 |
|
||
|
||
## 13. 明确不迁移的内容
|
||
|
||
| 路径 | 处理方式 | 原因 |
|
||
| --- | --- | --- |
|
||
| `backend-old/third_party/**` | `不迁移` | 新后端不保留 vendored 第三方目录。 |
|
||
| `backend-old/.venv/**` | `不迁移` | 环境文件。 |
|
||
| `backend-old/.pytest_cache/**` | `不迁移` | 缓存。 |
|
||
| `backend-old/.ruff_cache/**` | `不迁移` | 缓存。 |
|
||
| `backend-old/bridge/**` | `保留为外部桥接层，不按 Python 代码移植` | 这是独立 Node bridge。 |
|
||
|
||
## 14. 第一批最值得迁的文件
|
||
|
||
如果要先挑“收益最高、风险最低”的一批，顺序建议是：
|
||
|
||
1. `nanobot/config/loader.py` -> `beaver/foundation/config/loader.py`
|
||
2. `nanobot/config/paths.py` -> `beaver/foundation/config/paths.py`
|
||
3. `nanobot/config/schema.py` -> `beaver/foundation/config/schema.py`
|
||
4. `nanobot/utils/helpers.py` -> `beaver/foundation/utils/helpers.py`
|
||
5. `nanobot/agent/process_events.py` -> `beaver/foundation/events/process.py`
|
||
6. `nanobot/agent/run_result.py` -> `beaver/foundation/models/run_result.py`
|
||
7. `nanobot/session/manager.py` -> `beaver/engine/session/models.py` + `manager.py`
|
||
8. `nanobot/providers/base.py` / `registry.py` / `custom_provider.py` / `litellm_provider.py` / `openai_codex_provider.py`
|
||
9. `nanobot/agent/context.py` -> `beaver/engine/context/builder.py`
|
||
10. `nanobot/agent/tools/base.py` / `registry.py` / `filesystem.py` / `shell.py` / `web.py` / `message.py`
|
||
11. `nanobot/agent/plugins.py` -> `beaver/plugins/*`
|
||
12. `nanobot/agent/skills.py` -> `beaver/skills/catalog/loader.py` + `resolver/runtime.py`
|
||
13. `nanobot/agent_team/types.py` -> `beaver/coordinator/team/types.py`
|
||
14. `nanobot/agent_team/memory.py` -> `beaver/memory/procedures/*` + `beaver/memory/runs/*`
|
||
15. 以 Hermes 基线新增 `beaver/tools/builtins/memory.py`
|
||
16. 以 Hermes 基线新增 `beaver/tools/builtins/session_search.py`
|
||
|
||
## 15. 最后一句话
|
||
|
||
从 `backend-old` 移到新的 `backend`，最重要的不是“先把文件复制过来”，而是始终按这个原则落：
|
||
|
||
1. `foundation` 放公共模型、配置、事件、工具函数
|
||
2. `engine` 放统一 agent 内核
|
||
3. `tools` 放工具本身
|
||
4. `skills` 放全系统指导层
|
||
5. `memory` 放经验沉淀
|
||
6. `coordinator` 放委派和多 agent 编排
|
||
7. `services` 放应用服务
|
||
8. `interfaces` 放 CLI / Web / Gateway / Channels 薄入口
|
||
9. `integrations` 放 A2A / MCP / Outlook / Authz 这类外部系统
|
||
|
||
只要旧文件进入新目录时严格按这条边界落，新后端就不会再次长回 `backend-old` 那种结构。
|