dashboard-nanobot/design/refactor-modularization-roadmap.md

# Dashboard Nanobot 模块化重构与远端桥接演进方案

本文档用于指导当前项目的结构性重构，并为后续“支持同机/远端龙虾 + Docker/Native 双运行模式”升级提前抽离边界。

补充约束：本路线图负责说明“为什么拆、先拆什么”；具体“怎么拆、拆到什么边界”为强制执行项，统一以下文为准：

- `design/code-structure-standards.md`

目标不是一次性大改所有代码，而是先把未来 2 个核心问题理顺：

- 当前前端/后端过于集中，后续功能迭代成本越来越高
- 执行层默认绑定“本机 Docker + 本机文件系统”，无法自然扩展到远端与 Native 模式

## 1. 结论先行

### 1.1 前端必须拆，但优先做“页面内模块化”，不是重写 UI

当前前端最大的问题不是样式，而是页面级组件承担了太多职责：

- 页面状态
- API 调用
- 业务编排
- 视图渲染
- 弹窗
- 文件预览
- 表单保存
- WebSocket/轮询

因此，前端应优先按“页面 -> 业务区块 -> 通用能力”三层拆分。

### 1.2 后端必须拆代码结构，但不建议现在把中央 backend 再拆成多个部署服务

当前 `backend/main.py` 已经承担：

- API 路由
- Bot 生命周期
- Workspace 文件操作
- Runtime 状态判断
- 日志/监控
- Provider 测试
- 平台默认值拼装

这会让未来远端执行支持非常困难。

建议：

- 现在：先把 `backend` 按领域和 provider 分层拆开，保持 **一个 central backend 服务**
- 后续：新增一个 **独立部署的桥接服务 `dashboard-edge`**

也就是说：

- 中央控制面 backend：保留，继续作为统一 API、数据库、权限、审计入口
- 执行桥接层：新增独立服务，不再内嵌在 central backend 中

### 1.3 为了支持远端龙虾，必须引入桥接服务，但不需要修改 nanobot 核心

推荐结构：

- `dashboard-backend`
  - 控制平面
  - 统一前端 API
  - DB / 权限 / 审计 / 聚合视图
- `dashboard-edge`
  - 执行平面
  - 部署在本机或远端节点
  - 管理该节点上的 Docker / Native Bot
  - 与 nanobot 的 `dashboard.py` channel 通信

这是未来最稳的演进方向。

### 1.4 `dashboard-edge` 应作为执行节点的标准组件

长期目标不是“只有远端机器需要 edge”，而是：

- 任何实际运行 Bot 的节点，都部署一个 `dashboard-edge`
- 同机部署场景下，central backend 与 edge 可以位于同一台机器
- 远端部署场景下，在远端 Bot 所在机器部署 edge

也就是说：

- `dashboard-backend` 负责控制平面
- `dashboard-edge` 负责执行平面
- 一个节点一个 edge，不是一个 Bot 一个 edge

这样本机与远端最终会走同一条执行链路，避免长期维护两套调用路径。

### 1.5 `dashboard-edge` 的长期职责不应只绑定 nanobot

当前第一阶段仍以 nanobot 为主，因为现有接入基础已经存在：

- workspace 生成
- `dashboard.py` channel
- 运行态日志解析

但从架构角度，`dashboard-edge` 应定位为“Bot Core Adapter Host”，即：

- edge 负责对接不同 Bot 核心
- 每类核心通过 adapter/executor 做本地适配
- 对上统一输出 dashboard 可理解的生命周期、命令、工作区、日志与状态协议

因此，未来可以扩展出：

- `NanobotCoreAdapter`
- `LobsterCoreAdapter`
- 其它兼容 Bot Core Adapter

控制面不需要理解不同核心的内部细节，只需要依赖统一 provider 契约。

## 2. 当前项目的主要结构问题

### 2.1 Frontend 问题

- `frontend/src/modules/dashboard/BotDashboardModule.tsx` 体量过大，已经承担多个页面级职责
- `BotWizardModule.tsx` 同时负责创建流程、provider 测试、五个 MD 文件编辑
- `PlatformDashboardPage.tsx` 混合平台设置、资源视图、Bot 管理视图
- 页面内部状态与 API 编排严重耦合，局部重构成本很高
- 公共能力分散：
  - Markdown 编辑器
  - workspace markdown 渲染
  - timezone 选项
  - page size 缓存
  - bot 访问工具

### 2.2 Backend 问题

- `backend/main.py` 是单体入口，所有领域逻辑都堆在同一文件
- 运行时逻辑默认直接依赖本机资源：
  - Docker
  - 本地工作区
  - 本地 dashboard channel
- 路由层和业务层耦合严重
- 未来引入 remote/native 时，如果继续在 `main.py` 里堆条件分支，会快速失控

### 2.3 未来升级的真正分界线

本质上项目需要明确区分：

- 控制平面
- 执行平面
- nanobot 接入层

目前这三者是混在一起的。

## 3. 目标架构

### 3.1 总体分层

推荐把系统拆成 4 层：

1. `frontend`
   - 页面、组件、交互、状态编排
2. `dashboard-backend`
   - 统一 API、鉴权、DB、Provider 路由、审计
3. `dashboard-edge`
   - 本机或远端节点执行代理
4. `nanobot + dashboard.py`
   - Bot 本体，不修改核心

### 3.2 控制平面 vs 执行平面

#### 控制平面

职责：

- 统一 UI
- 统一 API
- 节点注册与节点状态
- Bot 元数据存储
- 权限与访问控制
- 操作审计
- 运行状态聚合

#### 执行平面

职责：

- 启停 Bot
- 管理 Docker / Host 进程
- 读写本机工作区
- 注入 dashboard channel 配置
- 与 Bot 的本地 dashboard channel 通信
- 收集运行日志与事件

补充原则：

- 执行平面的核心宿主是 `dashboard-edge`
- edge 内部可以再通过 core adapter 对不同 Bot 核心做协议适配
- central backend 不直接理解某个具体核心的启动脚本、端口、日志细节

### 3.3 支持矩阵

最终要支持 4 种执行模式：

- Local + Docker
- Local + Native
- Remote + Docker
- Remote + Native

这 4 种模式在控制面前端和 API 层应该尽量表现一致，只在 Provider/Executor 层分流。

## 4. Backend 是否需要拆分

### 4.1 代码结构上：必须拆

必须从当前单文件/弱分层状态拆成：

- API 路由层
- 领域服务层
- Provider 层
- 基础设施层

否则未来远端支持几乎只能靠 `if local else remote` 的条件分支硬堆。

### 4.2 部署形态上：中央 backend 不建议继续拆成多个控制面服务

不建议现在把 central backend 再拆成：

- bot-api
- workspace-api
- monitor-api

原因：

- 当前规模还不值得引入多控制面服务复杂度
- 主要痛点不是“服务数量不足”，而是“执行逻辑没抽象”
- 真正需要新增的，是独立的执行代理服务 `dashboard-edge`

### 4.3 最终建议

- 保留一个 central backend
- 新增一个 edge service
- central backend 内部彻底模块化

## 5. Backend 目标目录建议

建议逐步演进为：

```text
backend/
  app/
    main.py
    dependencies.py
    lifespan.py
  api/
    bots.py
    workspace.py
    monitor.py
    images.py
    platform.py
    topics.py
    nodes.py
  domain/
    bots/
      service.py
      runtime_service.py
      workspace_service.py
      schemas.py
    platform/
      service.py
    topics/
      service.py
    nodes/
      service.py
  providers/
    runtime/
      base.py
      local.py
      remote.py
    workspace/
      base.py
      local.py
      remote.py
    provision/
      base.py
      local.py
      remote.py
  infra/
    docker/
      manager.py
    workspace/
      files.py
    nanobot/
      config_manager.py
      dashboard_channel_client.py
    persistence/
      database.py
      repositories/
    settings/
      config.py
  models/
  schemas/
  services/
```

### 5.1 关键原则

- `api/` 只做 HTTP 协议转换，不做业务编排
- `domain/` 承担业务规则
- `providers/` 负责本机/远端、多运行模式适配
- `infra/` 负责 Docker、文件系统、dashboard channel、数据库等底层细节

## 6. Edge 服务目标目录建议

新增独立目录：

```text
edge/
  main.py
  api/
    bots.py
    workspace.py
    monitor.py
    health.py
  executors/
    base.py
    docker_executor.py
    native_executor.py
  adapters/
    dashboard_channel.py
    log_parser.py
  workspace/
    service.py
  runtime/
    service.py
  settings.py
```

### 6.1 Edge 的职责边界

只做“本节点执行代理”，不做：

- 全局权限模型
- 多节点聚合
- 平台配置中心
- 中央数据库业务

并且建议把“核心适配”显式纳入 edge 边界：

- edge 内部管理 `CoreAdapter`
- 负责把不同核心的运行方式转换成统一执行接口
- central backend 不直接依赖某个核心的私有实现

## 7. Frontend 目标结构建议

前端建议按“页面/区块/共享能力”拆，而不是继续让超大页面组件承担一切。

推荐结构：

```text
frontend/src/
  app/
    routes/
    providers/
  pages/
    dashboard/
    onboarding/
    platform/
    image-factory/
  widgets/
    bot-list/
    bot-chat/
    workspace-panel/
    bot-settings/
    topic-feed/
    platform-overview/
  features/
    bot-control/
    bot-editor/
    workspace-preview/
    skill-install/
    mcp-config/
    topic-config/
    cron-config/
  entities/
    bot/
    workspace/
    topic/
    platform/
    node/
  shared/
    api/
    ui/
    hooks/
    lib/
    markdown/
    i18n/
```

### 7.1 优先拆分的页面

#### `BotDashboardModule`

优先拆成：

- `BotHeader`
- `BotControlBar`
- `BotConversationPanel`
- `BotWorkspacePanel`
- `BotRuntimePanel`
- `BotSettingsModals`
- `WorkspacePreviewModal`
- `BotSkillSection`
- `TopicFeedSection`

并把状态和副作用抽入 hooks：

- `useBotRuntime`
- `useWorkspaceBrowser`
- `useBotEditor`
- `useBotConversation`
- `useBotMonitorStream`

#### `BotWizardModule`

优先拆成：

- `WizardBaseStep`
- `WizardModelStep`
- `WizardAgentFilesStep`
- `WizardSummaryStep`
- `useBotWizardForm`
- `useProviderTest`

#### `PlatformDashboardPage`

优先拆成：

- `PlatformOverviewPanel`
- `PlatformBotsPanel`
- `PlatformSettingsPanel`
- `PlatformUsagePanel`

## 8. Provider 抽象建议

### 8.1 RuntimeProvider

统一接口：

- `start_bot`
- `stop_bot`
- `restart_bot`
- `send_command`
- `get_status`
- `get_recent_logs`
- `stream_monitor`
- `get_resource_snapshot`

### 8.2 WorkspaceProvider

统一接口：

- `list_tree`
- `read_file`
- `write_markdown`
- `upload_files`
- `download_file`

### 8.3 ProvisionProvider

统一接口：

- `create_bot`
- `delete_bot`
- `upgrade_bot`
- `sync_config`

### 8.4 实现矩阵

- `LocalDockerRuntimeProvider`
- `LocalNativeRuntimeProvider`
- `RemoteDockerRuntimeProvider`
- `RemoteNativeRuntimeProvider`

但对上层 API 来说，尽量只感知：

- `LocalRuntimeProvider`
- `RemoteRuntimeProvider`

具体 Docker / Native 再由 provider 内部选择 executor。

## 9. 数据模型建议

当前 `BotInstance` 不足以表达远端执行目标，需要新增节点维度。

### 9.1 建议新增 Node 实体

建议字段：

- `id`
- `name`
- `endpoint`
- `auth_type`
- `auth_secret_ref`
- `enabled`
- `status`
- `capabilities_json`
- `last_heartbeat_at`

### 9.2 BotInstance 建议新增字段

- `node_id`
- `runtime_kind`
  - `docker`
  - `native`
- `location_kind`
  - `local`
  - `remote`

或者简化为：

- `node_id`
- `runtime_kind`

其中：

- `node_id = local` 表示同服务器
- 其它 `node_id` 表示远端节点

### 9.3 迁移策略

现有数据默认迁移为：

- `node_id = local`
- `runtime_kind = docker`

保证老实例零感知升级。

## 10. 与 nanobot 的关系

原则保持不变：

- 不修改 nanobot 核心
- 继续复用 `dashboard.py`
- 由 dashboard 侧负责桥接与配置注入

具体职责：

- central backend 不直接操作 nanobot
- edge 负责：
  - 生成/更新 `.nanobot/config.json`
  - 确保 `channels.dashboard` 注入正确
  - 调用 dashboard channel

## 11. 分阶段实施路线

### Phase 1：前端拆大文件，不改 API

目标：

- 仅拆页面组件、hooks、services
- API 不变
- 行为不变

优先级：

- `BotDashboardModule`
- `BotWizardModule`
- `PlatformDashboardPage`

### Phase 2：后端拆主文件，不改功能

目标：

- 从 `backend/main.py` 中拆出：
  - bot lifecycle 路由
  - workspace 路由
  - bot service
  - workspace service
  - runtime service
- 行为保持不变

### Phase 3：引入 Provider 抽象，保留本机 Docker

目标：

- 在不改变当前功能的前提下，把执行逻辑走 provider
- 当前 provider 先只实现 local docker

这是最关键的“抽骨架”阶段。

### Phase 4：补 Local Native 模式

目标：

- 支持同机宿主机直装
- 通过 `NativeExecutor` 管理进程/端口/workspace

### Phase 5：新增 `dashboard-edge`

目标：

- 远端节点部署 edge 服务
- central backend 引入 remote provider
- 不改前端 API，只增加节点/运行模式字段

### Phase 6：前端补节点视图

目标：

- 节点管理页
- Bot 运行位置与运行模式选择
- 节点资源与健康状态展示

### Phase 7：本机执行路径统一切到 edge

目标：

- 逐步让同机 Docker / Native 也通过本机 edge 执行
- central backend 不再保留长期的“本机直连执行层”
- 最终形成“所有执行节点统一经由 edge”的稳定结构

## 12. 本轮重构建议的落地顺序

如果从今天开始进入真正改造，建议按下面顺序推进：

1. 先拆前端大页面
2. 再拆 backend main.py
3. 然后引入 provider interface
4. 再实现 local native
5. 最后接入 remote edge

原因：

- 页面和 `main.py` 的可维护性问题已经是当前痛点
- provider 抽象是远端能力的必要前提
- native 支持可以提前验证抽象是否合理
- remote edge 是最后一公里，不应该在结构没理顺前硬接

## 13. 建议的下一步动作

下一步不要直接开始“远端龙虾支持”的业务开发，而应先做一轮基础重构：

### 13.1 前端第一刀

从 `BotDashboardModule` 开始，拆成：

- workspace
- conversation
- runtime
- settings modal
- skills/topic

### 13.2 后端第一刀

从 `backend/main.py` 中先抽 3 个领域：

- bots lifecycle
- workspace
- bot runtime snapshot / config sync

### 13.3 provider 第一版

先定义接口，不着急做 remote：

- `RuntimeProvider`
- `WorkspaceProvider`
- `ProvisionProvider`

并用当前本机逻辑实现 `Local*Provider`。

---

本方案的核心思想只有一句话：

**中央 backend 保持控制平面，新增 edge 作为执行平面；先做代码结构分层，再做远端与 native 支持。**

## 14. 为什么不是一开始就直接拆成 backend + edge

这个问题的关键不在于“是否值得上 edge”，而在于“当前代码是否已经具备承接 edge 的稳定边界”。

答案是：**方向上应该从一开始就以 backend + edge 为目标，但工程实施上不应该在现有单体逻辑不拆的情况下直接硬接 edge。**

原因如下。

### 14.1 当前 central backend 还没有稳定的 provider 边界

如果现在直接上 edge，但 central backend 仍然保持现状，那么会出现：

- 本机逻辑继续直连 Docker / 文件系统
- 远端逻辑走 edge
- API 路由层同时理解本机细节和远端细节

结果会形成两套执行路径：

- local direct
- remote edge

这会让后续统一 Native、统一工作区、统一日志协议变得更贵。

### 14.2 先拆结构不是绕路，而是在降低总成本

先做结构重构的价值是：

- 把当前隐式耦合改成显式边界
- 先定义 provider / executor / adapter 契约
- 为 edge 预留稳定接入点

这样后续接 edge 是“接到标准接口上”，不是“插进一团已有业务里”。

### 14.3 如果现在直接硬上 edge，代价反而更大

直接开做 edge 的风险：

- central backend 仍然需要保留大量本机直连逻辑
- 远端功能会复制一套相似业务编排
- 前端状态和 API 语义可能被迫提前扭曲
- 最后仍然要回头拆 `main.py` 和超大页面组件

也就是说，不是“现在拆结构，后面代价更大”，而是：

- **如果现在不先拆结构，后面引入 edge 的总代价更大**

### 14.4 推荐理解方式

正确顺序不是：

- 先重构
- 再考虑 edge

而是：

- 先以 edge 为最终目标设计边界
- 再做最小必要的结构重构
- 然后把 edge 接入这些边界

因此，这两件事不是对立关系，而是前后依赖关系。