自定义 UI
该案例说明如何在 AI Agent 中使用
dobot-plus技能时，通过Requirements.md中的功能描述定制插件 UI 的交互形式。Skill 会根据需求文档自动生成function.json与ui/Main.tsx；本文重点介绍页面布局约定、可用组件类型，以及如何在需求文档中显式指定或依赖默认推断。
示例流程
UI 页面是 Skill 工作流中的一环，与 Lua、HTTP、积木配置同步生成：
更完整的开发流程见 适配 Modbus-RTU 设备 或 适配 I/O 设备。
页面布局
dobot-plus 技能生成页面时，采用固定的左右分栏布局：
| 区域 | 位置 | 内容 |
|---|---|---|
| 设备状态 | 左侧 Card | 只读状态展示（读取类功能） |
| 控制面板 | 右侧 Card | 参数输入与操作按钮（写入 / 控制类功能） |
请不要在 Requirements.md 中修改这种布局规则。 变更左右分栏、上下堆叠或多 Tab 等结构会让 Agent 表现不稳定，生成的页面也会变得不可预测。
页面统一使用 antd 作为基础组件库（react@18 + antd@5），根节点为 DobotPlusApp，并通过 MQTT 推送实时刷新左侧状态区。
在 Requirements.md 中指定 UI
在每个功能的说明中，增加一行 UI 交互描述，Agent 会将其映射为 function.json 中的 ui 字段。
推荐写法
在功能章节（如 ### 4.1 SetSpeed — 设置速度）下追加：
### 4.1 SetSpeed — 设置速度
- 操作：写入速度寄存器，取值范围 0~100
- 参数：speed（number，默认 50）
- UI：滑块（Slider）
也可使用简短形式：
- UI：按钮
- UI：只读状态展示
- UI：下拉选择（选项：模式 A / 模式 B / 模式 C）
功能与 UI 的对应关系
| 功能类型 | 典型命名 | 建议 UI | 放置区域 |
|---|---|---|---|
| 无参控制 | StartDevice、OpenGripper | Button | 右侧控制区 |
| 带参写入 | SetSpeed、SetForce | Slider / Input / Select | 右侧控制区 |
| 枚举选择 | SetMode、SetChannel | Select / Radio / Dropdown | 右侧控制区 |
| 布尔开关 | EnableVacuum | Switch / Checkbox | 右侧控制区 |
| 状态读取 | GetStartStatus、GetPosition | Tag / Text / Table | 左侧状态区 |
| 文件操作 | ImportConfig | Upload | 右侧控制区 |
读取类功能还需在 Agent 分解时分配 keyWord（英文 camelCase 名词，如 startStatus），用于 MQTT 状态推送与页面绑定。写入类功能的 keyWord 为空字符串。
组件类型
以下组件类型与 function.json 中 ui 字段的枚举值一一对应。
展示类组件
用于左侧「设备状态」区域，对应读取类、无用户输入的功能。
| 组件 | ui 值 | 适用场景 | Requirements.md 示例 |
|---|---|---|---|
| 只读文本 | 无固定枚举，由 Agent 选用 tag 或 Statistic 展示 | 数值、字符串等单一状态 | UI：只读文本 / UI：只读状态展示 |
| Tag | tag | 布尔或枚举状态，需颜色区分 | UI：Tag 标签（1=运行中，0=已停止） |
| Table | table | 多行、多字段状态列表 | UI：表格展示各通道状态 |
控制类组件
用于右侧「控制面板」区域。带参数的功能在表单中渲染控件；ui 为 button 的功能统一 排列在表单底部按钮区。
| 组件 | ui 值 | 适用场景 | Requirements.md 示例 |
|---|---|---|---|
| Input | input | 数值或文本参数输入 | UI：输入框（范围 0~255） |
| Slider | slider | 连续数值调节（速度、力度等） | UI：滑块（0~100） |
| Select | select | 多选一，选项较多 | UI：下拉选择（选项：A / B / C） |
| Dropdown | dropdown | 下拉菜单式选择 | UI：Dropdown 下拉菜单 |
| Radio | radio | 少量互斥选项 | UI：单选（开 / 关 / 自动） |
| Switch | switch | 布尔开关 | UI：开关 |
| Checkbox | checkbox | 布尔勾选 | UI：复选框 |
| Button | button | 无参即时操作（启动、停止、复位） | UI：按钮 |
| Upload | upload | 文件导入 | UI：文件上传 |
默认推断规则
若功能说明中未显式指定 UI 类型，Agent 会根据功能语义与参数类型进行推断：
| 功能特征 | 默认 UI |
|---|---|
| 无参数的控制 / 触发操作 | Button |
| 带 number 类型参数，且有明确范围 | Slider |
| 带 number / string 参数，无范围或需精确输入 | Input |
| 参数为枚举或有限选项 | Select 或 Radio |
| 参数为 boolean | Switch |
| 只读状态，返回 boolean 或离散枚举 | Tag |
| 只读状态，返回 number / string | 只读文本（Statistic 展示） |
| 返回多行结构化数据 | Table |
建议在需求文档中显式写出 UI 类型，尤其是边界情况（如「力度用滑块、模式用单选、状态用 Tag」），可显著减少生成结果与预期不符的情况。
完整示例片段
以下片段摘自 I/O 控制案例，展示了按钮与只读状态的搭配：
### 4.1 StartDevice — 启动外部设备
- 操作：`DO(1, ON)`，向 DO-1 输出高电平
- UI：按钮
### 4.2 GetStartStatus — 获取启动状态
- 操作：读取 `DI(1)` 的值
- 返回值：`1` 表示启动成功；`0` 表示未就绪
- UI：只读状态展示
Modbus 设备中常见的参数 + 控制组合示例：
### 4.1 SetVacuumLevel — 设置真空力度
- 操作：写入寄存器 0x0001，取值范围 0~100（%）
- 参数：level（number，默认 50）
- UI：滑块
### 4.2 ActivateVacuum — 开启真空
- 操作：写入控制字 bit0 = 1
- UI：按钮
### 4.3 GetVacuumStatus — 获取真空状态
- 操作：读取状态寄存器 bit0
- 返回值：`1` 已开启，`0` 已关闭
- UI：Tag 标签
生成结果说明
Skill 执行完成后，UI 相关文件如下：
| 文件 | 说明 |
|---|---|
function.json | 每个功能的 ui、keyWord、params 等定义 |
ui/Main.tsx | 插件控制界面（Agent 根据 function.json 补全 TODO） |
.dobot/http/http.ts | 前端 HTTP 请求封装 |
lua/httpAPI.lua | 控制器侧 HTTP 接口 |
Agent 会先通过 page.js 生成 Main.tsx 脚手架，再按 function.json 与 Skill 内置规范补全交互逻辑。生成后如需微调文案或样式，可直接编辑 ui/Main.tsx；国际化文案位于 Resources/i18n/。
注意： Skill 生成 UI 时仅允许使用 antd 组件，不要使用 @dobot-plus/components。
UI 案例截图
- OnRobot VG10（Modbus RTU，滑块 + 按钮 + 状态展示）
- 大寰 AG-95
- I/O 控制（按钮 + 只读状态）
常见问题
生成的 UI 组件类型与预期不符
在 Requirements.md 对应功能下补充明确的 UI： 描述，删除歧义表述后重新调用 /dobot-plus。若仅需微调单个控件，也可直接修改 function.json 中的 ui 字段，再手动更新 ui/Main.tsx。
左侧状态区没有数据
- 确认读取类功能已分配
keyWord（可在function.json中检查） - 确认
DobotPlusApp的 MQTT 推送正常（Skill 默认useMqtt={true}） - 使用
dpt dev连接真机，确认 Lua 逻辑返回值正确
按钮与参数控件位置混乱
Skill 约定：ui 为 button 的控件渲染在右侧表单底部；其余控制类组件渲染在表单字段区。请勿在 Requirements.md 中要求自定义布局。
想使用自定义组件或复杂页面
当前 Skill 面向标准 Dobot+ 插件场景，仅支持上述 antd 组件与固定左右布局。复杂交互需在 /dobot-plus 完成后手动改写 ui/Main.tsx，或参考 基础示例 自行编写 UI。