147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# 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` 对齐。
|