dashboard-nanobot/design/architecture.md

Dashboard Nanobot 架构设计文档（当前实现）

1. 设计原则

• 控制平面与数据平面分离。
• 引擎零侵入：不修改 nanobot 源码，仅通过 workspace 与容器管理接入。
• 镜像显式登记：系统不自动构建，不扫描 engines/，只使用 Docker 本地镜像 + DB 注册。
• 可观测性优先：通过容器日志流解析状态并推送到 WebSocket。

2. 核心组件

2.1 Frontend（React + Zustand）

• ImageFactoryModule：镜像登记与状态展示。
• BotWizardModule：引导创建与模型测试。
• BotDashboardModule：2D 运维控制台（无 3D），采用标准 LLM 聊天气泡视图 + 对话流中的思考动画 + workspace 文件浏览器。
• 全局支持 light/dark 与 中英文切换。

2.2 Backend（FastAPI + SQLModel + docker-py）

• 镜像 API：/api/images、/api/docker-images、/api/images/register
• Bot 生命周期 API：/api/bots、/api/bots/{id}/start|stop|command
• Workspace API：/api/bots/{id}/workspace/tree、/api/bots/{id}/workspace/file
• Provider 测试 API：/api/providers/test
• 监控通道：/ws/monitor/{bot_id}

2.3 Workspace 配置生成器

BotConfigManager.update_workspace 负责：

• 写入 .nanobot/config.json
• 写入 5 个 bootstrap 文件：
  • AGENTS.md
  • SOUL.md
  • USER.md
  • TOOLS.md
  • IDENTITY.md

3. 关键数据流

3.1 镜像流

1. 用户手动构建镜像（命令行）
2. 前端读取 /api/docker-images
3. 用户点击“加入数据库” -> /api/images/register
4. 后续创建向导只消费 /api/images 且筛选 READY

3.2 创建流

1. 前端提交 Bot 创建参数（镜像、provider、模型参数、5 个 md 文件）
2. 后端校验镜像可用并写入 botinstance
3. 启动时生成 workspace 文件并按资源配额拉起容器（CPU/内存/存储）

3.4 镜像升级流

1. 在运维面板基础配置中切换 image_tag
2. 后端更新 .nanobot/config.json
3. 用户手动执行 stop -> start，使新镜像生效
4. workspace 目录保持挂载，既有插件与脚本继续可用

3.3 运维流

1. 前端轮询 /api/bots 获取实例列表
2. 对运行中 bot 建立 WebSocket 连接
3. 后端解析日志，推送 AGENT_STATE 与 RAW_LOG

4. 当前约束

• Provider 测试接口当前只做 dashscope/openrouter。
• Skills 采用 workspace 文件系统模式管理，不再使用数据库注册表。
• Bot 状态来自日志与容器状态，不依赖侵入式埋点。