适配 TCP 设备
该案例展示如何在 AI Agent 中使用
dobot-plus技能适配 TCP/IP 通讯协议的外部设备。与 Modbus 系列协议不同，TCP 设备通常通过自定义报文（字符串或二进制帧）交互，Skill 会根据Requirements.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 后即可使用。
编写 Requirements.md（通用要求）
Skill 不会自动创建或修改 Requirements.md，需要开发者在项目根目录手动编写完整的 TCP 通讯文档。
文档必须包含
| 类别 | 说明 |
|---|---|
| 通信协议 | 协议类型为 TCP，连接角色（客户端 / 服务端） |
| IP 地址 | 设备或上位机的 IP，如 192.168.5.1 |
| 端口号 | TCP 端口，如 123 |
| 报文格式 | 发送报文模板、响应报文格式、分隔符、结束符（如 \n） |
| 功能语义 | 每个可对外暴露的原子操作（发送指令 / 读取响应 / 状态查询） |
| 操作流程 | 典型交互时序（连接 → 发送 → 等待响应 → 断开或保持连接） |
推荐章节结构
- 设备概述
- 通信协议（TCP 参数：IP、端口、连接方式）
- 报文协议说明（指令格式、响应格式、示例）
- 功能说明（按原子操作拆分）
- 操作流程
- 版本信息与安全注意事项
文档中功能拆分应尽可能原子化，即每个功能只做一件事。命名建议采用 camelCase 的「动词 + 名词」，如 MoveUp、GetPosition。
TCP 与其他协议的区别
| 对比项 | TCP 自定义协议 | Modbus RTU / TCP | I/O 控制 |
|---|---|---|---|
| 协议字段 | "protocol": "tcp" | "protocol": "modbus-*" | "protocol": "io" |
| 连接参数 | IP 地址、端口号 | 寄存器地址 + 通讯参数 | DI/DO 端口号 |
| 底层 API | sendRequest（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 模式
调用 /dobot-plus 技能
设备案例
以下示例通过 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
导入使用
- 打开 DobotStudio Pro，进入 Dobot+ 插件管理界面
- 若已安装同名插件，需先卸载旧版本
- 点击导入，选择
output/目录下生成的 zip 文件 - 安装完成后，在导航栏中找到插件入口，即可使用控制界面、积木编程和脚本编程功能
插件压缩包命名格式为：
<插件名>_v<主版本号>-<次要版本号>-<修复版本号>-<版本状态>.zip
导入与使用的详细截图说明见 快速入门 — 构建和使用。
常见问题
如何查看通讯报文
使用网络调试工具创建 TCP 客户端。
- PC 端作为 TCP Client
- 确保 PC 、控制器、 末端设备的网络链路正常
- TCP 客户端 IP 和端口需要根据实际 TCP Server 来确定，一般情况下，需要查看末端设备的 TCP Server 配置信息
- 报文参数根据实际的报文内容选择
HEX或ASCII格式 - TCP Server 端口请避免使用 502、8080、60000 三个端口号
- 使用虚拟控制器进行调试时，创建 TCP Client 时的 IP 地址需要和真实的虚拟控制器 IP 保持一致，虚拟控制器 IP 可在上位机首页 “IP地址” 属性下查看
连接建立后，即可查看插件和末端设备的往来通讯报文。
常用的 TCP 调试工具如下：
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 模式下表现良好