Agent Skill 适配 Onrobot 系列夹爪

该案例会展示如何在 AI Agent 中使用 dobot-plus 技能适配 Onrobot VG10 设备。相比手动编写 Lua、HTTP API 和 UI 页面，Skill 可根据设备协议文档自动生成插件脚手架，开发者只需准备 doc.md 并在 IDE 中调用 /dobot-plus 即可。

示例流程

环境搭建

开发前请确认本地环境满足以下要求。更详细的系统与工具说明见开发环境。

依赖	版本 / 说明
Node.js	v20 及以上
IDE	支持 Agent Skills（如 Cursor）
@dobot-plus/cli	全局安装，提供 `dpt` 命令
@dobot-plus/skill	全局安装，提供 `/dobot-plus` 技能

安装命令：

npm install -g @dobot-plus/cli @dobot-plus/skill@latest

安装完成后可通过以下命令验证：

node -v    # 应输出 v20.x 及以上
dpt -v     # 确认 CLI 可用

Skill 安装后会自动部署到 ~/.agents/skills/dobot-plus，并在 IDE 设置中启用 Agent Skills 后即可使用。更多安装细节见 Agent 技能。

准备工作

1. 创建插件项目

使用 @dobot-plus/cli 初始化一个空的 Dobot+ 插件项目：

dpt create

按提示填写插件信息，例如：

$ dpt create
? Please input plugin name: OnrobotVG10
? Please input plugin description: OnRobot VG10 vacuum gripper plugin
? Please input plugin version: 1-0-0-test
? Please input device IP: 192.168.5.1

创建成功后进入项目目录：

cd OnrobotVG10

2. 编写设备文档 doc.md

Skill 不会自动创建或修改 doc.md，需要开发者在项目根目录手动编写完整的设备协议文档。文档应至少包含：

通信协议参数（Modbus RTU 波特率、校验位、从站地址等）
寄存器地址与位域说明
设备功能列表（吸取、释放、读取真空度等）

VG10 使用 Modbus RTU 协议，物理层为 RS485。通过 Quick Changer 连接时，设备地址为 65 (0x41)。核心寄存器如下：

地址	寄存器名称	说明
0 (0x0000)	Channel A Control	通道 A 控制（Release / Grip / Idle）
1 (0x0001)	Channel B Control	通道 B 控制
2 (0x0002)	Current Limit	电流限制（mA，默认 500，最大 1000）
258 (0x0102)	Channel A Actual Vacuum	通道 A 实际真空度（只读）
259 (0x0103)	Channel B Actual Vacuum	通道 B 实际真空度（只读）

doc.md 中功能项应拆分为原子操作，例如 GripChannelA、ReleaseChannelA、GetVacuumA，而非合并为 ControlGripper。完整示例可参考 Agent 技能文档中的 VG10 示例，或根据文末附件中的 OnRobot Modbus 通讯协议自行整理。

使用 AI 辅助生成

若手头有厂商 PDF 手册，可将协议内容交给通用 AI 模型整理为 doc.md，再人工复核后写入项目根目录。Skill 只读取 doc.md，不会代为创建或修改该文件。

文档必须包含：

类别	说明
通信协议	协议类型、波特率、数据位、校验位、停止位
从站地址	Modbus RTU 的 `slaveID`（不同连接方式分别列出）
寄存器映射	十进制 + 十六进制地址、名称、读/写权限
位域说明	高低字节、bit 含义、枚举值与写入示例
功能语义	每个可对外暴露的原子操作（读/写/控制）

推荐章节结构：

设备概述
通信协议（含 Modbus RTU 参数与设备地址）
寄存器总览
寄存器详细说明（位域、枚举值、单位与范围）
操作流程
版本信息与安全注意事项

结构可参考 Agent 技能文档中的 VG10 完整示例。

将以下提示语复制到 ChatGPT、Cursor 等 AI 工具，并附上 OnRobot Modbus 通讯协议 PDF 的文本或截图：

你是一名工业设备协议文档整理助手。请根据我提供的设备手册内容，生成一份符合 Dobot+ Skill 要求的 doc.md 设备文档。

## 输出要求
1. 输出为 Markdown，只基于我提供的资料整理，不要臆造寄存器地址、位域或参数
2. 不确定的信息标注「待确认」，不要猜测
3. 使用中文，寄存器名、模式名保留英文原文

## 文档必须包含
1. 设备概述
2. 通信协议：Modbus RTU 参数（波特率、数据位、校验位、停止位）及设备地址（slaveID）
3. 寄存器总览表：地址（十进制 + 十六进制）、名称、读/写权限
4. 每个关键寄存器的详细说明：位域/字节组成、枚举值与寄存器值对照、单位与范围
5. 典型操作流程
6. 版本信息与安全注意事项

## 功能拆分规则
- 每个功能只做一件事，命名采用 camelCase 的「动词 + 名词」，如 SetSpeed、GetVacuum、GripChannelA
- 禁止合并：SetSpeedAndAcceleration、ControlGripper 等应拆成多个原子功能
- 只读状态函数需提供英文 camelCase 的 keyWord（如 actualVacuum）

## 位域与写入示例
若寄存器由多个字段组成，必须说明各 bit/字节含义，并给出组合写入示例（如 0x0114 = 高 8 位 0x01 模式 + 低 8 位 0x14 参数）。

---
以下是需要整理的设备资料：
[粘贴 PDF 文本 / OCR 内容 / 手册章节]

生成后请人工核对：

slaveID 是否与 Quick Changer 等实际连接方式一致（VG10 为 65）
寄存器地址、读/写权限是否与原厂手册一致
位域说明是否足以推导 Modbus 写入值（如 Grip 模式 + 真空度百分比）
功能是否已拆分为原子操作

确认无误后，将文件保存为项目根目录的 doc.md，再调用 /dobot-plus。

3. 确认硬件连接

VG10 通过 Quick Changer 或 RS485 接口连接至机械臂末端
控制器 485 通道参数需与协议一致（波特率 1000000 bit/s，Even 校验，8 数据位，1 停止位）
调试时确认 dpt.json 中的控制器 IP 与实际设备一致

{
  "ip": "192.168.5.1",
  "pluginPort": 22100
}

Agent 技能使用

1. 在 IDE 中调用 Skill

打开插件项目，在 IDE Chat 中输入：

/dobot-plus

Agent 会按 Skill 定义的工作流自动执行，无需逐步确认：

读取并解析项目根目录的 doc.md
将功能拆分为原子功能项，写入 function.json
校验 function.json 格式
生成 httpAPI.lua、userAPI.lua、modbus.lua、积木配置、脚本配置等脚手架
生成 ui/Main.tsx 控制页面
在 lua/[项目名].lua 中填充函数框架，提示开发者补充业务逻辑

skill demo

2. 检查生成结果

Skill 执行完成后，项目目录中会新增或更新以下关键文件：

文件 / 目录	说明
`function.json`	功能定义与协议参数
`lua/*.lua`	Modbus 读写与业务逻辑
`lua/httpAPI.lua`	UI 请求的 HTTP 接口
`lua/userAPI.lua`	积木 / 脚本编程接口
`configs/Blocks.json`	积木编程配置
`configs/Scripts.json`	脚本编程配置
`ui/Main.tsx`	插件控制界面
`.dobot/http/http.ts`	前端 HTTP 请求封装

开发者应重点检查 function.json 中的从站地址、寄存器映射是否与 doc.md 一致，并在 lua/[项目名].lua 中确认 Modbus 读写逻辑正确。

3. 本地调试（可选）

开发人员需要对功能进行预验证时，可进行此步操作，如果想构建后导入上位机验证，可跳过此步骤。

进入插件项目目录，启动开发服务器：

dpt dev

命令行会提示是否连接真机调试 Lua：

$ dpt dev
? Debug lua on real device? Yes
? Please check the device IP: 192.168.5.1 (y/n)

选择 No：仅调试 UI 页面，可在浏览器中预览按钮布局与交互
选择 Yes：连接真机，UI 操作会通过 HTTP 请求下发至控制器，经 httpAPI.lua 调用 Modbus 控制 VG10

调试通过后，可根据需要调整 UI 文案、国际化资源（Resources/i18n/）以及积木 / 脚本配置。

打包构建

插件开发、调试完成后，在项目根目录执行：

dpt build

构建成功后，当前目录下会出现：

dist/ — 构建后的插件源码，供开发者检查
output/ — 压缩后的 zip 包，文件名格式为 <插件名>-<版本号>.zip，即最终导入文件

导入使用

打开 DobotStudio Pro，进入 Dobot+ 插件管理界面
若已安装同名插件，需先卸载旧版本
点击导入，选择 output/ 目录下生成的 zip 文件
安装完成后，在导航栏中找到插件入口，即可使用控制界面、积木编程和脚本编程功能

插件压缩包命名格式为：

<插件名>_v<主版本号>-<次要版本号>-<修复版本号>-<版本状态>.zip

导入与使用的详细截图说明见快速入门 — 构建和使用。

常见问题

Skill 提示缺少 doc.md

请确认 doc.md 位于插件项目根目录，且包含完整的协议参数、寄存器地址和功能定义。Skill 不会代为创建该文件。

生成的从站地址不正确

检查 doc.md 中是否明确写了 Modbus 从站地址（Quick Changer 连接 VG10 时为 65）。Skill 会从文档中提取 slaveID 写入 function.json。

Modbus 通信失败

确认 485 通道参数与 VG10 协议一致
确认 Quick Changer 或 RS485 接线正常
使用 dpt dev 连接真机时，核对 dpt.json 中的 IP 地址

Agent 实现效果不理想

确认现场的设备通讯参数是否与手册一致
检查 doc.md 文档中的描述是否有模糊或者前后冲突的地方
检查 Agent 模型能力，vscode Copilot 中需要使用 GPT-5.4 及以上模型，Cursor 中 Auto 模式下表现良好。

示例流程​

环境搭建​

准备工作​

1. 创建插件项目​

2. 编写设备文档 doc.md​

使用 AI 辅助生成​

3. 确认硬件连接​

Agent 技能使用​

1. 在 IDE 中调用 Skill​

2. 检查生成结果​

3. 本地调试（可选）​

打包构建​

导入使用​

常见问题​

Skill 提示缺少 doc.md​

生成的从站地址不正确​

Modbus 通信失败​

Agent 实现效果不理想​

相关链接​