Agent Skill 适配 DH PGE50
该案例展示如何在 AI Agent 中使用
dobot-plus技能适配 大寰机器人（DH-Robotics）PGE 系列 工业电动夹爪（以 PGE-50 为例）。PGE 系列支持 Modbus RTU 与 IO 两种控制方式；本案例聚焦 Modbus RTU。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: DhPGE50
? Please input plugin description: DH-Robotics PGE-50 electric gripper plugin
? Please input plugin version: 1-0-0-test
? Please input device IP: 192.168.5.1
创建成功后进入项目目录：
cd DhPGE50
2. 编写设备文档 doc.md
Skill 不会自动创建或修改 doc.md，需要开发者在项目根目录手动编写完整的设备协议文档。文档应至少包含：
- 通信协议参数（Modbus RTU 波特率、校验位、从站地址等）
- 寄存器地址与取值范围说明
- 设备功能列表（初始化、设 力、设速、设位、读状态等）
一份可用的 doc.md 内容如下：
# PGE系列驱控一体式电爪 - 软件开发文档
## 概述
PGE系列为工业型平行电爪，支持**Modbus-RTU（RS485）** 和 **IO模式** 控制。可控制夹爪的**位置、力值、速度**，并支持 状态反馈。
---
## 一、通信规格（RS485 Modbus-RTU）
| 参数 | 默认值 |
|------|--------|
| 设备ID | 1 |
| 波特率 | 115200 |
| 数据位 | 8 |
| 停止位 | 1 |
| 校验位 | 无 |
> 支持功能码：`03`（读寄存器）、`06`（写单个寄存器）、`04`、`10`
---
## 二、寄存器地址表
### 2.1 基础控制地址表（读写）
| 功能 | 地址（16进制） | 说明 | 取值范围 |
|------|----------------|------|-----------|
| 初始化夹爪 | 0x0100 | 写入 0x01：回零；0xA5：完全标定 | 只写 |
| 力值 | 0x0101 | 夹持力（百分比） | 20–100（0x14–0x64 ） |
| 位置 | 0x0103 | 目标位置（千分比） | 0–1000（0x000–0x3E8） |
| 速度 | 0x0104 | 运行速度（百分比） | 1–100（0x01–0x64） |
### 2.2 状态反馈地址表（只读）
| 功能 | 地址（16进制） | 返回值说明 |
|------|----------------|--------------|
| 初始化状态 | 0x0200 | 0：未初始化；1：成功；2：初始化中 |
| 夹持状态 | 0x0201 | 0：运动中；1：到位未夹物；2：夹住物体；3：物体掉落 |
| 实时位置 | 0x0202 | 当前实际位置（千分比） |
### 2.3 参数配置地址表（读写）
| 功能 | 地址（16进制） | 说明 |
|------|----------------|------|
| 写入保存 | 0x0300 | 写入 1：保存参数到Flash |
| 初始化方向 | 0x0301 | 0：张开；1：闭合 |
| 设备ID | 0x0302 | 1–247 |
| 波特率 | 0x0303 | 0：115200；1：57600；2：38400；3：19200；4：9600；5：4800 |
| 停止位 | 0x0304 | 0：1位；1：2位 |
| 校验位 | 0x0305 | 0：无；1：奇校验；2：偶校验 |
| 自动初始化 | 0x0504 | 0：不上电初始化；1：上电自动初始化 |
---
## 三、指令示例
### 3.1 初始化夹爪
```text
发送：01 06 01 00 00 01 49 F6
返回：01 06 01 00 00 01 49 F6
```
### 3.2 设置力值为30%
```text
发送：01 06 01 01 00 1E 59 FE
返回：01 06 01 01 00 1E 59 FE
```
### 3.3 设置位置为500‰（50%行程）
```text
发送：01 06 01 03 01 F4 78 21
返回：01 06 01 03 01 F4 78 21
```
### 3.4 设置速度为50%
```text
发送：01 06 01 04 00 32 48 22
返回：01 06 01 04 00 32 48 22
```
### 3.5 读取夹持状态
```text
发送：01 03 02 01 00 01 D4 72
返回：01 03 02 00 02 39 85 （02表示已夹住物体）
```
### 3.6 保存所有配置参数
```text
发送：01 06 03 00 00 01 48 4E
返回：01 06 03 00 00 01 48 4E
```
---
## 四、IO模式控制说明
### 4.1 输入引脚定义（NPN，0V有效）
| INPUT1 | INPUT2 | 动作 |
|--------|--------|------|
| 高阻（0） | 高阻（0） | 第1组参数 |
| 0V（1） | 高阻（0） | 第2组参数 |
| 高阻（0） | 0V（1） | 第3组参数 |
| 0V（1） | 0V（1） | 第4组参数 |
### 4.2 输出引脚反馈（NPN）
| OUTPUT1 | OUTPUT2 | 状态 |
|---------|---------|------|
| 高阻 | 高阻 | 运动中 |
| 0V | 高阻 | 到位未夹物 |
| 高阻 | 0V | 夹住物体 |
| 0V | 0V | 物体掉落 |
---
## 五、开发注意事项
- 控制前必须先**初始化夹爪**（写入0x01或0xA5）
- 初始化或参数修改后，建议执行**写入保存（0x0300）**
- IO模式和485模式可同时存在，但**控制冲突时遵循“先发先响应”**
- 初始化过程中（约0.5~3秒）**不要发送控制指令**
- 修改ID、波特率等参数后需**重启夹爪生效**
---
## 六、调试建议
- 使用官方调试软件或任意串口工具（如Modbus Poll）
- 硬件连接：24V、GND、485A、485B
- 推荐使用USB转485模块进行PC调试
doc.md 中功能项应拆分为原子操作，例如 Initialize、SetForce、SetSpeed、SetPosition、GetGripperState、GetCurrentPosition，而非合并为 ControlGripper。
doc.md 要点摘要
| 寄存器 | 写入值示例 | 说明 |
|---|---|---|
| Initialization (0x0100) | 1 / 0xA5 | 普通初始化 / 完全初始化 |
| Force (0x0101) | 30（30%） | 示例帧：01 06 01 01 00 1E |
| Speed (0x0104) | 50（50%） | 示例帧：01 06 01 04 00 32 |
| Position (0x0103) | 500（500‰） | 示例帧：01 06 01 03 01 F4 |
| Gripper State (0x0201) | 只读 | 2 表示检测到物体 |
支持的 Modbus 功能码：0x03 读保持寄存器、0x04 读输入寄存器、0x06 写单寄存器、0x10 写多寄存器。
使用 AI 辅助生成
若手头有厂商 PDF 手册，可将协议内容交给通用 AI 模型整理为 doc.md，再人工复核后写入项目根目录。
文档必须包含：
| 类别 | 说明 |
|---|---|
| 通信协议 | 协议类型、波特率、数据位、校验位、停止位 |
| 从站地址 | Modbus RTU 的 slaveID（默认 1） |
| 寄存器映射 | 含 0x0104 Speed 在内的完整基本控制寄存器 |
| 取值范围 | 力 20–100%、速度 1–100%、位置 0–1000‰、状态枚举 |
| 功能语义 | 每个可对外暴露的原子操作 |
结构可参考 AG-95 示例 或 OnRobot VG10 示例。
将以下提示语复制到 ChatGPT、Cursor 等 AI 工具，并附上 PGE 系列 Modbus 手册 PDF：
你是一名工业设备协议文档整理助手。请根据我提供的 DH-Robotics PGE 系列（如 PGE-50）夹爪手册，生成符合 Dobot+ Skill 要求的 doc.md。
## 输出要求
1. 只基于提供的资料整理，不臆造寄存器；不确定处标「待确认」
2. 使用中文，寄存器名保留英文
3. 注明机型为外置控制器或驱控一体（若资料中有说明）
## 文档必须包含
1. 设备概述（PGE 工业夹爪，Modbus RTU / RS485）
2. 通信协议：默认 slaveID=1，115200，8N1；0x0302/0x0303 可改地址与波特率
3. 寄存器总览：0x0100 初始化、0x0101 力、0x0104 速度、0x0103 位置、0x0200–0x0202 状态
4. 取值范围：Force 20–100%、Speed 1–100%、Position 0–1000‰、Gripper State 0–3
5. 操作流程：初始化 → SetForce → SetSpeed（可选）→ SetPosition → 读状态
6. 线序与安全注意事项
## 功能拆分规则
- camelCase「动词+名词」：Initialize、SetForce、SetSpeed、SetPosition、GetGripperState、GetCurrentPosition
- 禁止 ControlGripper、SetForceAndSpeed 等合并写法
- 只读状态提供 keyWord（如 gripperState、currentPosition）
## 写入示例（功能码 0x06）
- 初始化：01 06 01 00 00 01
- 30% 力：01 06 01 01 00 1E
- 50% 速度：01 06 01 04 00 32
---
以下是需要整理的设备资料：
[粘贴 PDF 文本 / OCR / 手册章节]
生成后请人工核对：
- 寄存器地址与数据格式是否与官方手册一致
slaveID、波特率是否与现场夹爪一致- 初始化流程与
0x0201状态枚举是否与手册一致 - 功能是否已拆分为原子操作
确认无误后保存为项目根目录 doc.md，再调用 /dobot-plus。
Agent 技能使用
1. 在 IDE 中调用 Skill
打开插件项目，在 IDE Chat 中输入：
/dobot-plus
Agent 会自动完成：解析 doc.md → 生成并校验 function.json → 生成 Lua / HTTP / 积木 / UI 脚手架 → 在 lua/[项目名].lua 中留出业务逻辑框架。
2. 检查生成结果
| 文件 / 目录 | 说明 |
|---|---|
function.json | 协议参数与各功能寄存器地址 |
lua/*.lua | Modbus 读写与业务逻辑 |
ui/Main.tsx | 插件控制界面 |
configs/Blocks.json / Scripts.json | 积木与脚本配置 |
开发者应重点检查：
SetSpeed是否映射到地址 260 (0x0104)，而非 AG 系列中预留的0x0102protocol.slaveID是否为 1（或与现场一致）lua/[项目名].lua是否 在控制前包含初始化逻辑
3. 本地调试（可选）
需要对功能预验证时可执行；若直接打包到上位机验证可跳过。
dpt dev
- 选择 No：仅调试 UI
- 选择 Yes：连接真机，经
httpAPI.lua下发 Modbus 控制 PGE-50
打包构建
dpt build
构建成功后生成 dist/ 与 output/<插件名>-<版本号>.zip。
导入使用
- 打开 DobotStudio Pro → Dobot+ 插件管理
- 卸载同名旧版本（如有）
- 导入
output/下 zip 包 - 在导航栏使用控制界面、积木与脚本编程
详细步骤见 快速入门 — 构建和使用。
常见问题
Skill 提示缺少 doc.md
确认 doc.md 在项目根目录，且包含协议参数、寄存器表（含 Speed）与功能定义。
生成的功能缺少 SetSpeed
检查 doc.md 是否写明 0x0104 寄存器。PGE 与 AG 协议相近但 PGE 必须包含速度寄存器说明，否则 Skill 可能不会生成 SetSpeed。
写入位置/力无响应
- 确认已完成初始化（
0x0200= 1，蓝灯常亮） - 确认 485 接线与线序、24V 供电
- 外置控制器型确认 RS485 接在控制盒而非仅夹爪动力线
Modbus 通信失败
- 核对波特率、校验位（默认 115200、无校验）
- 核对
dpt.jsonIP 与总线地址无冲突 - 保存参数写入
0x0300后设备 1–2 秒内不响应属正常现象
与 AG 系列文档混用
AG-95 无 0x0104 速度寄存器；勿将 AG 的 doc.md 直接用于 PGE。可参考 AG-95 示例 的文档结构，但寄存器表须以 PGE 手册为准。
Agent 实现效果不理想
- 确认现场的设备通讯参数是否与手册一致
- 检查
doc.md文档中的描述是否有模糊或者前后冲突的地方 - 检查 Agent 模型能力，vscode Copilot 中需要使用 GPT-5.4 及以上模型，Cursor 中 Auto 模式下表现良好。
相关链接
- PGE 外置控制器 Modbus 简明手册（英文）
- PGE 驱控一体 Modbus 简明手册（英文）
- PGE 驱控一体产品操作手册（中文）
- DH AG-95 Skill 示例（同类 Modbus 夹爪，无 Speed 寄存器）
- Agent 技能使用说明