Agent Skill 适配 DH AG95
该案例展示如何在 AI Agent 中使用
dobot-plus技能适配 大寰机器人（DH-Robotics）AG-95 电动夹爪。相比手动编写 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: DhAG95
? Please input plugin description: DH-Robotics AG-95 electric gripper plugin
? Please input plugin version: 1-0-0-test
? Please input device IP: 192.168.5.1
创建成功后进入项目目录：
cd DhAG95
2. 编写设备文档 doc.md
Skill 不会自动创建或修改 doc.md，需要开发者在项目根目录手动编写完整的设备协议文档。
文档应至少包含：
- 通信协议参数（Modbus RTU 波特率、校验位、从站地址等）
- 寄存器地址与取值范围说明
- 设备功能列表（初始化、设力、设位、读状态等）
一份可用的 doc.md 文档如下：
# AG系列电爪 Modbus-RTU 功能文档
## 一、通讯参数
| 参数 | 默认值 |
| --------- | ---------- |
| Modbus ID | 2 |
| 波特率 | 115200 |
| 数据位 | 8 |
| 停止位 | 1 |
| 校验位 | 无 |
| 协议 | Modbus-RTU |
---
## 二、寄存器地址速查表
### 控制寄存器（可写）
| 功能 | 地址 | 取值范围 | 说明 |
| -------- | ------ | ----------- | ------------------------- |
| 初始化 | 0x0100 | 0x01 / 0xA5 | 单向初始化 / 完全初始化 |
| 力值 | 0x0101 | 20-100 | 夹持力百分比 |
| 目标位置 | 0x0103 | 0-1000 | 千分比，0=张开，1000=闭合 |
### 状态寄存器（只读）
| 功能 | 地址 | 返回值 | 说明 |
| ---------- | ------ | ------- | -------------------------------- |
| 初始化状态 | 0x0200 | 0/1/2 | 0=未初始化，1=成功，2=进行中 |
| 夹持状态 | 0x0201 | 0/1/2/3 | 0=运动中，1=到位，2=夹住，3=掉落 |
| 实时位置 | 0x0202 | 0-1000 | 当前实际位置 |
---
## 三、功能指令示例
> 以下示例中 Modbus ID 均为 2（地址码为 01）
### 1. 初始化夹爪
#### 完全初始化（闭合再张开，标定行程）
```plaintext
发送：02 06 01 00 00 A5 48 4D
返回：02 06 01 00 00 A5 48 4D
```
#### 单向初始化（根据初始化方向寄存器执行）
```plaintext
发送：02 06 01 00 00 01 49 F6
返回：02 06 01 00 00 01 49 F6
```
> 初始化时间 0.5~3 秒，完成前不可控制
---
### 2. 设置力值
```plaintext
# 设置力值为 50%
发送：02 06 01 01 00 32 59 FD
返回：02 06 01 01 00 32 59 FD
```
| 力值(%) | 16进制数据 |
| ------- | ---------- |
| 20 | 00 14 |
| 50 | 00 32 |
| 100 | 00 64 |
---
### 3. 夹取物体（设置目标位置）
```plaintext
# 夹取到 500 位置（千分比）
发送：02 06 01 03 01 F4 78 21
返回：02 06 01 03 01 F4 78 21
```
| 位置 | 16进制数据 |
| ------------ | ---------- |
| 0（张开） | 00 00 |
| 500（半闭） | 01 F4 |
| 1000（闭合） | 03 E8 |
---
### 4. 释放物体（张开到 0 位置）
```plaintext
发送：02 06 01 03 00 00 79 F6
返回：02 06 01 03 00 00 79 F6
```
---
### 5. 读取夹持状态
```plaintext
发送：02 03 02 01 00 01 D4 72
返回：02 03 02 00 02 23 98
```
| 返回值 | 状态 |
| ------ | ---------------------- |
| 00 00 | 运动中 |
| 00 01 | 到达位置（未夹到物体） |
| 00 02 | 夹住物体 |
| 00 03 | 物体掉落 |
---
### 6. 读取实时位置
```plaintext
发送：02 03 02 02 00 01 24 72
返回：02 03 02 03 E8 B8 FA
```
> 03 E8（16进制）= 1000（十进制）
---
### 7. 读取初始化状态
```plaintext
发送：02 03 02 00 00 01 85 B2
返回：02 03 02 00 01 B8 44
```
| 返回值 | 状态 |
| ------ | ---------- |
| 00 00 | 未初始化 |
| 00 01 | 初始化成功 |
| 00 02 | 初始化中 |
---
## 四、组合操作流程
### 夹取物体完整流程
```plaintext
1. 初始化（如果未初始化）
发送：02 06 01 00 00 A5 48 4D
2. 设置力值（如50%）
发送：02 06 01 01 00 32 59 FD
3. 设置目标位置（如500）
发送：02 06 01 03 01 F4 78 21
4. 读取状态确认夹住
发送：02 03 02 01 00 01 D4 72
→ 返回 00 02 表示夹住物体
```
### 释放物体完整流程
```plaintext
1. 设置目标位置为 0
发送：02 06 01 03 00 00 79 F6
2. 读取状态确认到位
发送：02 03 02 01 00 01 D4 72
→ 返回 00 01 表示到位（未夹到物体）
```
---
## 五、指示灯状态
| 状态 | 指示灯 |
| ---------- | ----------------- |
| 未初始化 | 红灯闪烁 |
| 初始化完成 | 蓝灯常亮 |
| 夹住物体 | 绿灯常亮 |
| 物体掉落 | 绿灯闪烁 |
| 收到命令 | 紫灯闪烁（蓝+红） |
---
## 六、注意事项
1. **必须先初始化**，否则夹爪不响应控 制指令
2. 初始化完成后，**蓝灯常亮**才可控制
3. 修改参数后需向 `0x0300` 写入 `0x01` 保存到 Flash
4. 更换指尖后必须执行 `0xA5` 完全初始化
5. IO 模式和 Modbus 模式互斥，不可同时使用
6. 指令均为 **16进制**，CRC校验码需正确计算
---
## 七、CRC校验计算
参数选择：
- CRC-16
- 多项式：MODBUS (0x8005)
- 初始值：0xFFFF
- 异或值：0x0000
- 输入/输出反转：是
doc.md 中功能项应拆分为原子操作，例如 Initialize、SetForce、SetPosition、GetGripperState、GetCurrentPosition，而非合并为 ControlGripper。可参考下文「doc.md 要点摘要」或文末附件中的大寰 AG 系列 Modbus 手册自行整理完整文档。
doc.md 要点摘要
编写 doc.md 时，建议至少覆盖以下寄存器说明（其余配置寄存器如 0x0300–0x0303 可按需补充）：
| 寄存器 | 写入值示例 | 说明 |
|---|---|---|
| Initialization (0x0100) | 1 / 0xA5 | 普通初始化 / 完全初始化（找满行程） |
| Force (0x0101) | 30（表示 30%） | 十六进制示例：0x001E |
| Position (0x0103) | 500（表示 500‰） | 十六进制示例：0x01F4 |
| Gripper State (0x0201) | 只读 | 2 表示检测到物体 |
使用 AI 辅助生成
若手头有厂商 PDF 手册，可将协议内容交给通用 AI 模型整理为 doc.md，再人工复核后写入项目根目录。Skill 只读取 doc.md，不会代为创建或修改该文件。
文档必须包含：
| 类别 | 说明 |
|---|---|
| 通信协议 | 协议类型、波特率、数据位、校验位、停止位 |
| 从站地址 | Modbus RTU 的 slaveID（默认 1，若已修改须注明） |
| 寄存器映射 | 十进制 + 十六进制地址、名称、读/写权限 |
| 取值范围 | 力、位置、状态枚举及单位 |
| 功能语义 | 每个可对外暴露的原子操作（读/写/控制） |
推荐章节结构：
- 设备概述
- 通信协议（含 Modbus RTU 参数与设备地址）
- 寄存器总览（基本控制寄存器 + 配置寄存器）
- 寄存器详细说明（取值范围、枚举、读写示例）
- 操作流程（初始化 → 设力 → 设位 → 读状态）
- 版本信息与安全注意事项
结构可参考 OnRobot VG10 示例 或 Agent 技能文档 中的章节组织方式。
将以下提示语复制到 ChatGPT、Cursor 等 AI 工具，并附上大寰 AG 系列 Modbus 手册 PDF 的文本或截图：
你是一名工业设备协议文档整理助手。请根据我提供的 DH-Robotics AG-95 夹爪手册内容，生成一份符合 Dobot+ Skill 要求的 doc.md 设备文档。
## 输出要求
1. 输出为 Markdown，只基于我提供的资料整理，不要臆造寄存器地址或参数
2. 不确定的信息标注「待确认」，不要猜测
3. 使用中文，寄存器名保留英文原文
## 文档必须包含
1. 设备概述（AG-95 电动夹爪，Modbus RTU / RS485）
2. 通信协议：默认 slaveID=1，115200，8N1；说明 0x0302/0x0303 可改地址与波特率
3. 寄存器总览表：0x0100 初始化、0x0101 力、0x0103 位置、0x0200/0x0201/0x0202 状态
4. 每个寄存器的取值范围与枚举（如 Gripper State 0–3、Force 20–100%、Position 0–1000‰）
5. 典型操作流程：先初始化并等待 0x0200=1，再 SetForce、SetPosition，最后读 0x0201
6. 版本信息与安全注意事项（24V 供电、勿强行插拔航插等）
## 功能拆分规则
- 每个功能只做一件事，命名采用 camelCase 的「动词 + 名词」
- 示例：Initialize、SetForce、SetPosition、GetGripperState、GetCurrentPosition
- 禁止合并：ControlGripper、SetForceAndPosition 等应拆成多个原子功能
- 只读状态函数需提供英文 camelCase 的 keyWord（如 gripperState、currentPosition）
## 位域与写入示例
给出 Modbus 写单寄存器示例（功能码 0x06），如初始化：01 06 01 00 00 01；设 30% 力：01 06 01 01 00 1E。
---
以下是需要整理的设备资料：
[粘贴 PDF 文本 / OCR 内容 / 手册章节]
生成后请人工核对：
slaveID是否与夹爪实际地址一致（出厂默认为 1）- 寄存器地址是否与手册一致（尤其
0x0100、0x0101、0x0103、0x0201） - 力、位置的取值范围是否写清（20–100%、0–1000‰）
- 功能是否已拆分为原子操作，且包含初始化步骤说明
确认无误后，将文件保存为项目根目录的 doc.md，再调用 /dobot-plus。
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中填充函数框架，提示开发者补充业务逻辑
2. 检查生成结果
Skill 执行完成后，项目目录中会新增或更新以下关键文件：
| 文件 / 目录 | 说明 |
|---|---|
function.json | 功能定义与协议参数（含 protocol.slaveID、波特率等） |
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中protocol.slaveID是否为 1（或与现场一致）- 各功能的
address是否与doc.md一致（如SetForce→ 257、SetPosition→ 259） lua/[项目名].lua中是否在控制前调用了初始化逻辑
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 控制 AG-95
调试通过后，可根据需要调整 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 从站地址。AG-95 出厂默认为 1；若通过 0x0302 修改过地址，须在文档与 function.json 中保持一致。
写入位置/力无响应
- 确认夹爪已完成初始化（
0x0200读值为1，指示灯蓝色常亮） - 确认 485 接线（A/B 未接反）、供电 24V 正常
- 确认波特率、校验位与夹爪当前配置一致
Modbus 通信失败
- 确认控制器 485 参数与
doc.md一致（默认 115200、无校验） - 使用
dpt dev连接真机时，核对dpt.json中的 IP 地址 - 总线上仅连接必要设备，避免地址冲突
夹到物体但状态未更新
读取 0x0201（Gripper State）：值为 2 表示检测到物体。轮询间隔不宜过短，避免与写寄存器冲突。
Agent 实现效果不理想
- 确认现场的设备通讯参数是否与手册一致
- 检查
doc.md文档中的描述是否有模糊或者前后冲突的地方 - 检查 Agent 模型能力，vscode Copilot 中需要使用 GPT-5.4 及以上模型，Cursor 中 Auto 模式下表现良好。
相关链接
- AG 系列 Modbus-RTU 简明手册（英文）
- AG 系列操作手册 Modbus 版（中文）
- OnRobot VG10 Skill 示例（doc.md 结构与 AI 提示语参考）
- Agent 技能使用说明