跳到主要内容

适配 TCP 设备

该案例展示如何在 AI Agent 中使用 dobot-plus 技能适配 TCP/IP 通讯协议的外部设备。与 Modbus 系列协议不同，TCP 设备通常通过自定义报文（字符串或二进制帧）交互，Skill 会根据 Requirements.md 中的报文格式与功能描述自动生成插件脚手架，开发者只需准备需求文档并在 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，需要开发者在项目根目录手动编写完整的 TCP 通讯文档。

文档必须包含​

类别说明
通信协议协议类型为 TCP，连接角色（客户端 / 服务端）
IP 地址设备或上位机的 IP，如 192.168.5.1
端口号TCP 端口，如 123
报文格式发送报文模板、响应报文格式、分隔符、结束符（如 \n）
功能语义每个可对外暴露的原子操作（发送指令 / 读取响应 / 状态查询）
操作流程典型交互时序（连接 → 发送 → 等待响应 → 断开或保持连接）

推荐章节结构​

  1. 设备概述
  2. 通信协议（TCP 参数：IP、端口、连接方式）
  3. 报文协议说明（指令格式、响应格式、示例）
  4. 功能说明（按原子操作拆分）
  5. 操作流程
  6. 版本信息与安全注意事项

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

TCP 与其他协议的区别​

对比项TCP 自定义协议Modbus RTU / TCPI/O 控制
协议字段"protocol": "tcp""protocol": "modbus-*""protocol": "io"
连接参数IP 地址、端口号寄存器地址 + 通讯参数DI/DO 端口号
底层 APIsendRequest（TCPWrite/Read）寄存器读写DI / DO
需求文档重点报文格式与交互时序寄存器映射、位域端口号与电平语义
是否生成 modbus.lua否是否

TCP 底层 API 说明见 TCP 指令。手动编写 TCP 插件可参考 TCP/IP 控制基础示例。

使用 AI 辅助生成​

若手头有设备通讯协议文档或厂商手册，可将 TCP 报文定义交给通用 AI 模型整理为 Requirements.md，再人工复核后写入项目根目录。

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

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

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

## 文档必须包含
1. 设备概述
2. 通信协议：TCP 参数（IP 地址、端口号、客户端/服务端角色）
3. 报文协议：每条指令的发送格式、期望响应格式、分隔符与结束符
4. 功能说明：每个原子操作单独一条，说明发送的报文内容与返回值解析方式
5. 典型操作流程（如连接 → 发送指令 → 等待响应）
6. 版本信息与安全注意事项

## 功能拆分规则
- 每个功能只做一件事，命名采用 camelCase「动词 + 名词」
- 禁止合并：MoveAndStop、ControlDevice 等应拆成多个原子功能
- 发送类与读取类功能分别定义
- 读状态类功能需说明返回值含义

---
以下是需要整理的设备资料：
[粘贴通讯协议 / 手册章节 / 报文示例]

生成后请人工核对：

  • IP 地址、端口号是否与现场设备一致
  • 报文格式（含分隔符、结束符）是否与设备手册一致
  • 响应解析规则是否清晰
  • 功能是否已拆分为原子操作

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

选择 Agent 模式

Agents

调用 /dobot-plus 技能

Requirements.md

设备案例​

以下示例通过 TCP/IP 控制一台外部升降柱设备：发送位置指令并读取响应。请先 dpt create 创建插件项目，再编写 Requirements.md。

升降柱 TCP 控制​

创建项目示例：

dpt create

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

$ dpt create
? Please input plugin name: lift
? Please input plugin description: A plugin demo for lift control via TCP
? Please input plugin version: 1-0-0-test
? Please input device IP: 192.168.5.1

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

cd lift
升降柱 TCP Requirements.md 完整示例
# 升降柱 TCP 控制

> 通过 TCP/IP 向外部升降柱发送位置指令，并读取设备响应。

## 1. 设备概述

本插件用于控制一台外部升降柱。设备通过 TCP 自定义报文与机械臂系统交互，不依赖 Modbus 或 I/O 通讯。

## 2. 通信协议

| 项目     | 说明                       |
| -------- | -------------------------- |
| 协议类型 | TCP                        |
| 连接角色 | 机械臂作为 **TCP 客户端**  |
| IP 地址  | 192.168.5.1                |
| 端口号   | 123                        |
| 报文编码 | ASCII 字符串，以 `\n` 结尾 |

## 3. 报文协议

### 3.1 移动到绝对位置

- **发送格式：** `moveTo_absolutePosition,<position>\n`
- **参数：** `position` 为整数，表示目标位置（单位：mm 或设备自定义单位）
- **响应：** 设备返回确认字符串（具体格式待确认时可标注）

**示例：**

| 操作       | 发送报文                        |
| ---------- | ------------------------------- |
| 移动到 100 | `moveTo_absolutePosition,100\n` |
| 移动到 50  | `moveTo_absolutePosition,50\n`  |

## 4. 功能说明

### 4.1 MoveTo — 移动到指定位置

- 操作：调用 `sendRequest("moveTo_absolutePosition," .. position .. "\n")`
- 参数：position（number，目标位置）
- UI：输入框 + 按钮

### 4.2 MoveUp — 上移

- 操作：在当前位置基础上增加固定偏移（如 +50），发送 `moveTo_absolutePosition,<新位置>\n`
- UI：按钮

### 4.3 MoveDown — 下移

- 操作：在当前位置基础上减少固定偏移（如 -50），发送 `moveTo_absolutePosition,<新位置>\n`
- UI：按钮

## 5. 操作流程

1. 插件加载时建立 TCP 连接（IP + 端口由 `function.json` 中的 protocol 配置）
2. 用户点击「上移」或「下移」，发送对应位置指令
3. 等待设备响应（`sendRequest` 内部自动读取）
4. 根据响应更新 UI 状态

## 6. 安全注意事项

- 操作前确认 IP、端口与设备手册一致
- 位置指令应在设备允许行程范围内
- 若长时间无响应，应排查网络连通性与设备状态

生成后重点检查：

  • Requirements.md 中 IP、端口是否与现场设备一致
  • 报文格式是否与设备协议文档一致
  • 每个功能是否只描述一种操作

Agent 技能使用​

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

/dobot-plus

skill demo

导入使用​

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

插件压缩包命名格式为：

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

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

常见问题​

Agent 打包失败时，如何手动打包​

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

dpt build

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

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

Skill 提示缺少 Requirements.md​

请确认 Requirements.md 位于插件项目根目录，且包含 IP、端口、报文格式和功能定义。Skill 不会代为创建该文件。

TCP 通信失败​

  • 确认设备 IP、端口与 Requirements.md 一致，控制器与设备网络互通
  • 确认报文格式（分隔符、结束符）与设备协议一致
  • 使用 dpt dev 连接真机时，核对 dpt.json 中的 IP 地址
  • 参考 TCP 指令 排查连接与读写

Agent 实现效果不理想​

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

相关链接​