跳到主要内容

适配 I/O 设备

该案例展示如何在 AI Agent 中使用 dobot-plus 技能适配 控制柜 I/O（DI/DO）或 末端 I/O（ToolDI/ToolDO）的外部设备。相比手动编写 Lua、HTTP API 和 UI 页面，Skill 可根据 Requirements.md 中的 I/O 功能描述自动生成插件脚手架，开发者只需准备需求文档并在 IDE 中调用 /dobot-plus 即可。

示例流程​

环境搭建​

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

依赖版本 / 说明
Node.jsv20 及以上
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 后即可使用。

编写 Requirements.md（通用要求）​

Skill 不会自动创建或修改 Requirements.md，需要开发者在项目根目录手动编写完整的 I/O 功能文档。

文档必须包含​

类别说明
通信方式控制柜 DI/DO，或末端 ToolDI/ToolDO（二者不可混用，需明确指定）
I/O 端口每个功能对应的端口号、输入/输出类型
电平含义高电平 / 低电平分别代表什么设备状态或动作
状态判定读取类功能的成功 / 失败条件（如 DI-1 有信号表示启动成功）
功能语义每个可对外暴露的原子操作（输出控制 / 状态读取）
操作流程典型启停、复位等时序说明（含等待与超时建议）

推荐章节结构​

  1. 设备概述
  2. 通信方式（控制柜 I/O 或末端 I/O）
  3. I/O 端口详细说明（端口号、方向、电平含义）
  4. 功能说明（按原子操作拆分）
  5. 操作流程
  6. 版本信息与安全注意事项

文档中功能拆分应尽可能原子化，即每个功能只做一件事。命名建议采用 camelCase 的「动词 + 名词」，如 StartDevice、GetStartStatus。

I/O 与 Modbus 的区别​

对比项I/O 控制Modbus RTU
协议字段"protocol": "io""protocol": "modbus-rtu"
底层 APIDI / DO / GetDO 或 ToolDI / ToolDO寄存器读写
需求文档重点端口号与电平语义寄存器地址、位域、通讯参数
是否生成 modbus.lua否是

控制柜 I/O 的 Lua API 说明见 IO 指令；末端 I/O 见 Tool 指令。

使用 AI 辅助生成​

若手头有设备接线图、PLC 交互说明或厂商手册，可将 I/O 定义交给通用 AI 模型整理为 Requirements.md，再人工复核后写入项目根目录。

AI 提示词可以参考如下内容：

你是一名工业设备 I/O 集成文档整理助手。请根据我提供的资料，生成一份符合以下要求的 Requirements.md 设备文档。

## 输出要求
1. 输出为 Markdown，只基于我提供的资料整理，不要臆造端口号、电平含义或时序
2. 不确定的信息标注「待确认」，不要猜测
3. 功能命名保留英文 camelCase，如 StartDevice、GetStopStatus

## 文档必须包含
1. 设备概述
2. 通信方式：明确是控制柜 DI/DO 还是末端 ToolDI/ToolDO
3. I/O 端口表：端口号、方向（输入/输出）、高/低电平含义
4. 功能说明：每个原子操作单独一条，说明使用的端口与期望电平
5. 典型操作流程（如启动 → 等待反馈 → 确认状态）
6. 版本信息与安全注意事项

## 功能拆分规则
- 每个功能只做一件事，命名采用 camelCase「动词 + 名词」
- 禁止合并：StartAndStopDevice、ControlDevice 等应拆成多个原子功能
- 写操作（DO 输出）与读操作（DI 输入）分别定义
- 读状态类功能需说明返回值含义（如 1=成功，0=失败）

---
以下是需要整理的设备资料：
[粘贴接线说明 / 手册章节 / PLC 交互表]

生成后请人工核对：

  • 通信方式（控制柜 / 末端）是否与实际接线一致
  • DI/DO 端口号是否与现场接线一致
  • 高/低电平含义是否与设备手册一致
  • 功能是否已拆分为原子操作
  • 状态读取的成功 / 失败判定是否清晰

确认无误后，将文件保存为项目根目录的 Requirements.md，再在 IDE Agent 会话中调用 /dobot-plus。

Requirements.md

设备案例​

以下示例通过控制柜 DI/DO 与外部设备交互：DO 输出启动 / 停止指令，DI 读取设备反馈状态。请先 dpt create 创建插件项目，再编写 Requirements.md。

外部设备 I/O 控制​

创建项目示例：

dpt create

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

$ dpt create
? Please input plugin name: io
? Please input plugin description: A plugin demo for external device IO control
? Please input plugin version: 1-0-0-test
? Please input device IP: 192.168.5.1

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

cd io
I/O 控制 Requirements.md 完整示例
# 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 长时间无反馈，应排查外部设备故障或接线问题

生成后重点检查：

  • Requirements.md 中通信方式是否为 控制柜 I/O（若实际使用末端 I/O，应改为 ToolDI/ToolDO 并调整端口说明）
  • DO/DI 端口号是否与现场接线一致
  • 每个功能是否只描述一种操作

末端 I/O 场景（ToolDI / ToolDO）​

若设备接在机械臂末端而非控制柜，需求文档中应将通信方式改为末端 I/O，并在功能说明中使用 ToolDO / ToolDI API。手动编写时可参考 IO 控制基础示例。

Agent 技能使用​

1. 在 IDE 中调用 Skill​

打开插件项目，在 IDE Chat 中使用斜杠指令：

/dobot-plus

skill demo

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

  1. 读取并解析项目根目录的 Requirements.md
  2. 将功能拆分为原子功能项，写入 function.json（protocol.protocol 为 io）
  3. 校验 function.json 格式
  4. 生成 httpAPI.lua、userAPI.lua、积木配置、脚本配置等脚手架
  5. 生成 ui/Main.tsx 控制页面
  6. 在 lua/[项目名].lua 中实现 I/O 读写逻辑（使用 DI / DO 等 API）

2. 检查生成结果​

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

文件 / 目录说明
function.json功能定义，protocol.protocol 为 io
lua/[项目名].luaI/O 读写与业务逻辑
lua/httpAPI.luaUI 请求的 HTTP 接口
lua/userAPI.lua积木 / 脚本编程接口
configs/Blocks.json积木编程配置
configs/Scripts.json脚本编程配置
ui/Main.tsx插件控制界面
.dobot/http/http.ts前端 HTTP 请求封装

I/O 协议不会生成 modbus.lua。Agent 会在 lua/[项目名].lua 中直接使用 DI、DO、GetDO（或 ToolDI、ToolDO）实现各功能。

生成后的 Lua 逻辑示例：

-- 启动外部设备：DO-1 输出高电平
projectName.StartDevice = function()
    DO(1, ON)
end

-- 读取启动状态：DI-1 有信号返回 1，否则返回 0
projectName.GetStartStatus = function()
    return DI(1) == ON and 1 or 0
end

3. 本地调试（可选）​

开发人员需要对功能进行预验证时，可进行此步操作；若计划构建后在上位机验证，可跳过此步骤。

确认硬件连接

  • 控制柜 DI/DO 接线与 Requirements.md 中的端口定义一致
  • 调试时确认 dpt.json 中的控制器 IP 与实际设备一致
{
  "ip": "192.168.5.1",
  "pluginPort": 22100
}

进入插件项目目录，在命令行中执行调试指令：

dpt dev

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

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

连接真机后，保存 Lua 文件会自动同步至控制器，可在浏览器界面中测试 DO 输出与 DI 读取。

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

打包构建​

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

dpt build

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

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

导入使用​

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

插件压缩包命名格式为：

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

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

案例插件 UI 截图​

io

常见问题​

Skill 提示缺少 Requirements.md​

请确认 Requirements.md 位于插件项目根目录，且包含 I/O 端口定义和功能说明。Skill 不会代为创建该文件。

DO 输出后 DI 无反馈​

  • 确认 DI/DO 接线与 Requirements.md 中的端口号一致
  • 确认外部设备已上电且处于可响应状态
  • 部分设备响应有延迟，可在 Lua 逻辑中增加适当等待后再读取 DI

控制柜 I/O 与末端 I/O 混用​

Requirements.md 中应明确选用一种通信方式。控制柜使用 DI / DO；末端使用 ToolDI / ToolDO，二者 API 不同，不可在同一功能中混用。

Agent 实现效果不理想​

  • 检查 Requirements.md 中端口号、电平含义是否描述清晰
  • 确认功能已拆分为原子操作（一个函数只做一件事）
  • 检查 Agent 模型能力：VS Code Copilot 建议使用 GPT-5.4 及以上；Cursor 中 Auto 模式下表现良好

相关链接​