（十五）YModbus自动化调用：CLI、HTTP、MCP怎么服务 AI Agent

GitHub 项目地址：https://github.com/lidecong133/YModbus

前面讲了协议、库、CLI、主站工具、从站工具。

这一篇聊一个后面的方向：怎么让这些能力被脚本、测试平台、AI Agent 稳定调用。

我不太喜欢把这件事说成“给软件加 AI”。真正有用的不是在界面上放一个聊天框，而是把主站读取、从站模拟、报文查看、诊断导出这些能力整理成清楚的工具入口。

AI Agent 不应该靠猜按钮位置来操作工业软件。

它应该调用一个明确的命令或接口，传入参数，拿到结构化结果。

为什么不建议让AI去点界面

图形界面是给人用的。

人可以看按钮、看表格、看颜色。AI 如果靠截图和鼠标去点，也能做一点事，但很脆弱。

比如你让它排查一个设备：

• 连接192.168.1.10:502
• 读取 UnitId1
• 从地址0开始读 10 个保持寄存器
• 连续读 5 次
• 看数值有没有变化
• 如果失败，整理错误和报文

如果这些动作只能通过界面完成，AI 就要识别窗口、点按钮、等刷新、读表格。按钮位置变一下、窗口被挡一下、语言切换一下，都可能失败。

如果有 CLI 或 HTTP 接口，它只需要调用：

ymodbusread-holding-registers--host 192.168.1.10--port 502--unit-id 1--address 0--quantity 10

返回 JSON，AI 再判断下一步。

这种方式才稳定。

第一层：先把CLI做好

最容易落地的是 CLI。

YModbus.Cli 已经是 JSON-first 的思路，适合脚本和 AI Agent。

例如读取保持寄存器：

ymodbusread-holding-registers--host 192.168.1.10--port 502--unit-id 1--address 0--quantity 10

返回结果里有success、values、hexValues、地址、数量、端点信息。

这对 AI 很友好。

它不需要从一段人类描述里猜结果，只要看字段。

一个很实际的自动化场景是对比两台设备：

1. 读 A 设备地址0..20
2. 读 B 设备地址0..20
3. 把不同地址列出来
4. 生成一段排查结论

这件事用界面做，会变成复制粘贴。

用 CLI 做，就可以变成一段可重复执行的流程。

写入必须有安全挡板

CLI 里写入默认 dry-run，这点很重要。

AI 可以帮你准备写入命令，但不应该默认真的写设备。

比如：

ymodbuswrite-single-register--host 192.168.1.10--port 502--unit-id 1--address 10--value 500

不加--confirm，就不真正写。

真正写入必须明确：

ymodbuswrite-single-register--host 192.168.1.10--port 502--unit-id 1--address 10--value 500--confirm

这条规则以后给 AI Agent 调用时也应该保留。

读操作可以自动化多一点。

写操作必须有明确授权。

批量写、循环写、写真实设备，更要谨慎。

第二层：控制正在运行的桌面工具

CLI 适合直接读写设备。

但有时候你想控制已经打开的主站/从站工具，比如：

• 打开一个工作区
• 让主站连接
• 让主站读一次
• 让从站启动或停止
• 对正在运行的桌面工具做冒烟测试

这时候可以用本地 Agent Bridge。

它不是让 AI 去点 WinForms 控件，而是在桌面程序旁边开一个本机 HTTP 控制口。

关键原则：

• 默认关闭
• 只监听127.0.0.1
• 请求必须带 token
• 用 CLI 或 HTTP 调用，不直接操纵按钮

启动主站工具时可以显式开启：

.\YModbus.MasterApp.exe--agent--agent-token 0123--agent-port 50521

启动从站工具：

.\YModbus.SlaveApp.exe--agent--agent-token 0123--agent-port 50522

然后用 Workbench CLI 控制：

dotnet run--project.\YModbus.Workbench.Cli\YModbus.Workbench.Cli.csproj--master status--token 0123 dotnet run--project.\YModbus.Workbench.Cli\YModbus.Workbench.Cli.csproj--master connect--token 0123 dotnet run--project.\YModbus.Workbench.Cli\YModbus.Workbench.Cli.csproj--masterread-once--token 0123 dotnet run--project.\YModbus.Workbench.Cli\YModbus.Workbench.Cli.csproj--slavestart--port 50522--token 0123

这就很适合自动化验证。

比如发布前自动启动从站、打开主站、读一次保持寄存器、确认返回成功。

这比人工点一遍更可重复。

一个更贴近现场的例子

假设你有一个客户发来的工作区，说主站读不到数据。

AI Agent 如果有工具入口，可以这样做：

1. 打开从站模拟工作区
2. 启动从站
3. 打开主站工作区
4. 执行一次读取
5. 如果失败，读取主站和从站的状态
6. 导出最近报文
7. 总结是连接问题、站号问题、地址问题，还是异常响应

这里 AI 做的是“串流程”和“整理证据”。

人仍然负责判断是否要对真实设备写入、是否要修改现场参数。

这个边界很重要。

第三层：HTTP接口适合做中间层

Agent Bridge 的 HTTP 形态大概是这样：

GET http://127.0.0.1:50521/status X-YModbus-Agent-Token: 0123

执行命令：

POST http://127.0.0.1:50521/command Content-Type: application/json X-YModbus-Agent-Token: 0123 { "command": "read-once", "arguments": {} }

返回结构保持简单：

{"success":true,"message":"Read succeeded.","data":{}}

这个接口不一定直接暴露给最终用户。

它更像一个中间层：CLI 可以调用它，测试程序可以调用它，将来的 MCP Server 也可以调用它。

这样 WinForms 界面不用被 AI 直接操作，核心逻辑也能复用。

第四层：MCP适合最后封装

MCP 的价值，是把这些能力注册成 AI Agent 能识别的工具。

比如：

• modbus_read_holding_registers
• modbus_scan_units
• workbench_master_read_once
• workbench_slave_start
• workbench_open_workspace
• workbench_get_status

但我不建议一开始就直接做 MCP。

更稳的路线是：

1. 先把核心库做好
2. 再把 CLI 做稳
3. 桌面工具用本地 Agent Bridge 暴露有限命令
4. 最后 MCP 只是包一层工具描述

这样即使不用 MCP，CLI 和 HTTP 接口本身也有价值。

哪些能力可以放给AI

我会分级。

低风险，可以自动化：

• 查看状态
• 读取线圈和寄存器
• 扫小范围 UnitId
• 获取报文
• 打开工作区
• 启动本机从站模拟
• 生成报告

中风险，需要明确确认：

• 写单个寄存器
• 写单个线圈
• 修改从站模拟数据
• 执行较大范围扫描

高风险，不建议自动放开：

• 批量写真实设备
• 循环写真实设备
• 长时间高频轮询
• 修改关键设备参数
• 对未知地址范围盲扫

这个边界不是为了限制 AI，而是为了保护现场。

工业通讯工具跟普通办公软件不一样。读错一般还能解释，写错可能影响设备。

返回结果要带诊断信息

给 AI 调用的接口，不能只返回一句“失败”。

最好带上：

• 是否成功
• 端点
• UnitId / SlaveId
• 功能码
• 起始地址
• 数量
• 数值
• 十六进制值
• 错误类型
• 异常码
• 请求/响应报文
• 耗时

比如读取失败时，如果能告诉 AI “设备返回 Illegal Data Address”，它就能建议检查地址和数量。

如果只是 “timeout”，它会建议查 IP、端口、站号、串口参数。

返回信息越结构化，AI 越不容易胡猜。

我希望YModbus最后变成什么样

YModbus 不只是一个 NuGet 包。

我更希望它慢慢变成一套完整的 Modbus 调试底座：

• 核心库给开发者用
• CLI 给脚本和自动化用
• 主站工具给现场读设备用
• 从站工具给模拟和复现问题用
• Agent Bridge 给运行中的桌面工具提供本地控制入口
• MCP Server 给 AI Agent 提供标准工具接口

这样以后你可以直接说：

帮我读一下192.168.1.10的 1 号站，地址0..20，如果失败，把可能原因按优先级列出来。

AI 不需要猜按钮。

它调用工具，拿结果，整理证据。

人做最后确认。

这才是我觉得 AI Agent 在工控调试里比较靠谱的用法。