beaver_project/app-instance/backend/移植指南.md

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 那种结构。