# 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 状态来自日志与容器状态，不依赖侵入式埋点。