自定义界面交互
该案例说明如何在 AI Agent 中使用
dobot-plus技能时，通过Requirements.md中的功能描述定制插件 UI 的交互形式。Skill 会根据需求文档自动生成function.json与ui/Main.tsx；本文重点介绍页面布局约定、可用组件类型，以及如何在需求文档中显式指定或依赖默认推断。
示例流程
UI 页面是 Skill 工作流中的一环，与 Lua、HTTP、积木配置同步生成：
更完整的开发流程见 适配 Modbus 设备、适配 TCP 设备 或 适配 I/O 设备。生成完成后，如需微调交互逻辑，可手动编辑 ui/Main.tsx 再重新打包。
页面布局
dobot-plus 技能生成页面时，采用固定的左右分栏布局：
| 区域 | 位置 | 内容 |
|---|---|---|
| 设备状态 | 左侧 | 只读状态展示（读取类功能） |
| 控制面板 | 右侧 | 参数输入与操作按钮（写入 / 控制类功能） |
如下所示，左侧展示了 OnRobot VG10 设备的通道真空度、产品型号等信息；右侧展示了控制 VG10 吸盘吸取参数和吸取释放操作的控制面板。
请不要在 Requirements.md 中修改这种布局规则。 变更左右分栏、上下堆叠或多 Tab 等结构会让 Agent 表现不稳定，生成的页面也会变得不可预测。
页面使用 antd 作为基础组件库，用户可以参考 antd 组件库，在 Requirements.md 中为功能指明 UI 形式。
在 Requirements.md 中指定 UI
在每个功能的说明中，增加一行 UI 交互描述，Agent 会将其映射为 function.json 中的 ui 字段。
推荐写法
在 Requirements.md 功能描述中追加：
如某一设备的设置速度功能，其在 Requirements.md 中可做如下描述：
### SetSpeed — 设置速度
- 操作：写入速度寄存器，取值范围 0~100
- 参数：speed（number，默认 50）
- UI：滑块（Slider）
如此编写的 Requirements.md 在最后的交互界面生成时，设置速度这一功能会展示位滑块的交互形式。
功能与 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 | 右侧 |
组件类型
展示类组件
用于左侧「设备状态」区域，对应读取类、无用户输入的功能。
| 组件 | 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 控制案例，展示了按钮与只读状态的搭配：
# I/O 控制示例
> 通过控制柜数字输出（DO）向外部设备发送指令，通过数字输入（DI）读取外部设备运行状态。
## 1. 设备概述
本插件用于控制一台外部加工设备。设备通过控制柜 I/O 接口与机械臂系统交互，不依赖 Modbus 或 TCP 通讯。
## 2. 通信方式
| 项目 | 说明 |
| -------- | ------------------------------------------------- |
| 协议类型 | 控制柜 I/O |
| 输出端口 | DO（数字输出） |
| 输入端口 | DI（数字输入） |
| Lua API | `DO(index, ON\|OFF)`、`DI(index)`、`GetDO(index)` |
## 3. I/O 端口说明
| 端口 | 方向 | 高电平含义 | 低电平含义 |
| ---- | ---- | -------------- | -------------- |
| DO-1 | 输出 | 发送启动指令 | 空闲 / 未启动 |
| DO-2 | 输出 | 发送停止指令 | 空闲 / 未停止 |
| DI-1 | 输入 | 外部设备已启动 | 外部设备未启动 |
| DI-2 | 输入 | 外部设备已停止 | 外部设备未停止 |
## 4. 功能说明
### 4.1 StartDevice — 启动外部设备
- 操作：`DO(1, ON)`，向 DO-1 输出高电平
- UI：按钮
### 4.2 GetStartStatus — 获取启动状态
- 操作：读取 `DI(1)` 的值
- 返回值：`1` 表示 DI-1 有信号，设备启动成功；`0` 表示无信号，启动失败或未就绪
- UI：只读状态展示
### 4.3 StopDevice — 停止外部设备
- 操作：`DO(2, ON)`，向 DO-2 输出高电平
- UI：按钮
### 4.4 GetStopStatus — 获取停止状态
- 操作：读取 `DI(2)` 的值
- 返回值：`1` 表示 DI-2 有信号，设备停止成功；`0` 表示无信号，停止失败或未就绪
- UI：只读状态展示
## 5. 操作流程
### 启动流程
1. 调用 `StartDevice`，DO-1 输出高电平
2. 等待外部设备响应（建议 1~3 秒）
3. 调用 `GetStartStatus`，确认 DI-1 为高电平
### 停止流程
1. 调用 `StopDevice`，DO-2 输出高电平
2. 等待外部设备响应（建议 1~3 秒）
3. 调用 `GetStopStatus`，确认 DI-2 为高电平
## 6. 安全注意事项
- 操作前确认 DO 端口接线正确，避免误触发外部设备
- 停止指令发出后，应通过 DI 反馈确认设备已安全停机
- 若 DI 长时间无反馈，应排查外部设备故障或接线问题
生成结果说明
Skill 执行完成后，UI 效果如下：
常见问题
Agent 打包失败时，如何手动打包
插 件开发、调试完成后，在项目根目录执行：
dpt build
构建成功后，当前目录下会出现：
dist/— 构建后的插件源码，供开发者检查output/— 压缩后的 zip 包，文件名格式为<插件名>-<版本号>.zip，即最终导入文件
生成的 UI 组件类型与预期不符
在 Requirements.md 对应功能下补充明确的 UI： 描述，删除歧义表述后重新调用 /dobot-plus。若仅需微调单个控件，可手动更新 ui/Main.tsx。
按钮与参数控件位置混乱
Skill 约定：ui 为 button 的控件渲染在右侧表单底部；其余控制类组件渲染在表单字段区。请勿在 Requirements.md 中要求自定义布局。
想使用自定义组件或复杂页面
当前 Skill 面向标准 Dobot+ 插件场景，仅支持上述 antd 组件与固定左右布局。复杂交互需在 /dobot-plus 完成后手动改写 ui/Main.tsx。