# Dashboard Nanobot 技术规范书（当前实现）

本文档描述当前代码已落地的 Dashboard Nanobot 控制平面规范，覆盖前端流程、后端接口、配置文件生成和运行约束。

## 1. 产品目标

系统围绕三步主流程：

1. 镜像工厂：仅管理 Docker 本地镜像与数据库登记状态。
2. 引导创建：基于 READY 镜像创建 Bot，填写模型参数与代理文件。
3. 运维 Dashboard：2D 控制台管理 Bot 对话、状态、日志与启停。

## 2. 前端模块规范

### 2.1 镜像工厂（Image Factory）

- 页面显示两类列表：
  - 数据库已登记镜像（来源 `/api/images`）
  - Docker 本地镜像（来源 `/api/docker-images`）
- 系统不再自动扫描 `engines/`。
- 仅通过“加入数据库”动作调用 `/api/images/register` 完成登记。
- 创建向导仅允许使用 `status=READY` 的已登记镜像。

### 2.2 引导创建（Bot Wizard）

- 采用 4 步流程：
  1. 选择 READY 镜像
  2. 模型与参数
  3. 代理文件配置
  4. 确认创建
- Provider 支持：`dashscope`、`openrouter`、`openai`、`deepseek`。
- 提供模型连通性测试按钮（调用 `/api/providers/test`）。
- 标准模型参数：
  - `temperature`
  - `top_p`
  - `max_tokens`
  - `cpu_cores`
  - `memory_mb`
  - `storage_gb`
- 参数编辑交互：
  - `temperature`、`top_p` 使用滑轨
  - `max_tokens` 使用数字输入 + 快捷档位
  - `cpu_cores`、`memory_mb`、`storage_gb` 使用数字输入
- 代理文件配置项（全部可编辑并持久化）：
  - `AGENTS.md`
  - `SOUL.md`
  - `USER.md`
  - `TOOLS.md`
  - `IDENTITY.md`
- 渠道配置：
  - 创建向导只配置“可选外部渠道”（飞书/QQ 等）
  - `dashboard` 渠道为内置渠道，不在向导中生成渠道块
  - 全局 `sendProgress/sendToolHints` 作为独立开关提交

### 2.3 运维 Dashboard（2D）

- 不使用 3D 场景。
- 三栏布局：
  - 左侧：Bot 列表、镜像、启停操作
  - 中间：标准 LLM 对话区（Bot 左气泡 + 用户右气泡）；Bot 处于 THINKING 时在对话流中显示思考动画
  - 右侧：运行遥测、最后反馈、workspace 文件浏览器（双击进目录/返回上级/双击文件弹窗预览）
- 支持实时状态更新（WebSocket `/ws/monitor/{bot_id}`）。
- Skills 管理入口仅在运维面板（更多菜单）：
  - 列出当前 Bot 的 `workspace/skills` 内容
  - 支持删除技能目录/文件
  - 支持上传 zip 并安全解压到 `workspace/skills`
- workspace 可视化接口：
  - `/api/bots/{bot_id}/workspace/tree`
  - `/api/bots/{bot_id}/workspace/file`

### 2.4 主题与语言

- 支持 `light/dark` 切换。
- 支持 `中文/English` 切换。
- 切换状态保存在浏览器 `localStorage`。

## 3. 后端行为规范

### 3.1 镜像登记策略

- `/api/images`：只返回数据库登记镜像，并和 Docker 实时对账更新状态。
- `/api/docker-images`：列出本地 `nanobot-base:*`。
- `/api/images/register`：将本地镜像显式写入登记表。

### 3.2 Bot 创建与启动

- `/api/bots` 创建时必须满足：
  - 镜像已登记
  - 镜像状态 `READY`
  - 本机 Docker 存在该镜像
- `/api/bots/{id}/start` 启动前写入 workspace：
  - `.nanobot/config.json`
  - `.nanobot/workspace/AGENTS.md`
  - `.nanobot/workspace/SOUL.md`
  - `.nanobot/workspace/USER.md`
  - `.nanobot/workspace/TOOLS.md`
  - `.nanobot/workspace/IDENTITY.md`
- 容器资源配额来自 `config.json.runtime.resources`：
  - `cpuCores`
  - `memoryMB`
  - `storageGB`

### 3.3 基础镜像升级策略

- 运维面板基础配置允许切换 `image_tag`。
- 切换镜像时后端仅更新配置文件，不自动重启容器。
- 需由用户手动执行停止/启动，使新镜像生效。
- 因 workspace 挂载路径不变，已安装插件、脚本和产物文件会保留。

### 3.3 Provider 测试接口

- `/api/providers/test` 当前支持：
  - `openrouter`（`/models`）
  - `dashscope`（`/models`）
- 返回模型预览列表与匹配提示。

### 3.4 Skills 文件系统接口

- `GET /api/bots/{bot_id}/skills`：列出 `workspace/skills` 一级技能项。
- `POST /api/bots/{bot_id}/skills/upload`：上传 zip，做路径安全校验后解压安装。
- `DELETE /api/bots/{bot_id}/skills/{skill_name}`：删除指定技能目录/文件。

## 4. Workspace 规范

宿主机目录：`workspace/bots/{bot_id}/.nanobot/`

```text
.nanobot/
├── config.json
└── workspace/
    ├── AGENTS.md
    ├── SOUL.md
    ├── USER.md
    ├── TOOLS.md
    ├── IDENTITY.md
    ├── memory/
    └── skills/
```

`skills/` 目录下每个一级目录（或单文件）视为一个可管理技能单元。

## 5. 与 nanobot 的兼容原则

- 不侵入 nanobot 源码。
- 控制平面通过文件与容器生命周期管理进行编排。
- Bootstrap 文件命名与 `nanobot.agent.context.ContextBuilder.BOOTSTRAP_FILES` 对齐。