企业官网建设流程全解析

Codex 也能调串口？我做了一个支持 Agent API 的 AI 通讯调试助手

本文介绍一个面向工业通讯调试场景的小工具：AI通讯调试助手 V1.0.0。它既可以作为普通串口/网口调试助手使用，也提供了本地 Agent API，让 Codex 或其他自动化 Agent 能在后台控制界面完成连接、发送、切换 HEX 显示、追加 CRC 等操作。

文章摘要

本文介绍一款支持 Agent API 的 AI通讯调试助手。它不仅具备串口、网口、HEX 收发、Modbus RTU CRC 自动追加和日志显示等常规调试功能，还可以被 Codex 等 AI Agent 通过本地 HTTP 接口调用，实现自动连接串口、扫描通讯参数、发送 Modbus 报文、切换 HEX 显示并观察收发日志。文章重点讲解工具的功能定位、使用场景，以及 Agent API 的接口设计和调用示例。

下载与源码

• GitHub 仓库：https://github.com/lidecong133/AICommTool
• V1.0.0 Release 地址：https://github.com/lidecong133/AICommTool/releases/tag/v1.0.0
• CSDN 下载地址：https://download.csdn.net/download/lidecong133/92977976
• 框架依赖版下载：AICommTool-v1.0.0-win-x64.zip
• 自包含版下载：AICommTool-v1.0.0-win-x64-self-contained.zip
• SHA256 校验文件：SHA256SUMS.txt
• Agent API 文档：仓库内docs/agent-api.md

如果目标电脑已经安装 .NET 8 Desktop Runtime，可以下载体积较小的框架依赖版；如果不确定运行环境，建议直接下载自包含版。

为什么做这个工具

传统串口调试助手通常是“人点按钮、人输入报文、人看日志”。这在普通调试时够用，但当我们希望 AI Agent 参与调试流程时，就会遇到几个问题：

• AI 不能稳定地直接操作复杂桌面控件；
• 连接参数、发送内容、日志状态需要结构化读取；
• Modbus RTU 报文需要自动追加 CRC；
• 既要让 Agent 后台操作，又要让用户在界面上看到每一步变化；
• 调试过程需要保留真实 TX/RX 日志，方便人工复核。

所以这个工具的设计目标不是简单地“再做一个串口助手”，而是把桌面调试助手变成一个可以被 AI 调用的本地工具。

工具定位

AI通讯调试助手是一个 Windows WinForms 桌面工具，当前 V1.0.0 主要包含：

• 串口调试；
• TCP Client / TCP Server 调试；
• HEX 和文本发送；
• HEX 和文本日志显示；
• 追加 CRLF；
• 串口 HEX 报文自动追加 Modbus RTU CRC；
• Modbus RTU CRC 校验摘要；
• Modbus TCP MBAP 摘要；
• 定时发送；
• 日志复制、清空、导出、过滤、搜索；
• 本地虚拟串口回环；
• 本地 Agent HTTP API。

界面上仍然保留了普通调试助手的操作方式。也就是说，即使不使用 AI，它也可以作为一个常规通讯调试助手使用。

功能场景

下面以 Codex 通过 Agent API 调用通讯调试助手完成 Modbus RTU 调试为例，说明这个工具可以覆盖的典型流程：

1. 启动 AI通讯调试助手；
2. Codex 连接本地 Agent API；
3. 在不知道通讯参数的情况下，从9600波特率开始扫描；
4. 识别到可用参数：COM5 115200,8,N,1；
5. 切换收发日志为 HEX 显示；
6. 自动发送 Modbus RTU 读取保持寄存器报文；
7. 工具自动追加 CRC；
8. 界面中显示 TX/RX 日志和 CRC 校验结果；
9. Codex 根据回包解析保持寄存器值。

关键点在于：Agent 的调用不是“后台偷偷发数据”，而是会同步到真实 WinForms 界面。用户能看到发送框内容变化，也能看到收发日志变化。

Agent API 设计思路

Agent API 默认监听本机：http://127.0.0.1:8765

它只绑定本地回环地址，默认不对局域网开放。设计上优先满足本机 Codex、脚本、自动化程序调用。

如果配置了 Token，请在请求头中携带：X-CommTool-Agent-Token: your-token

通用响应结构如下：

{ "ok": true, "message": "已发送 8 B", "txBytes": 8, "status": {} }

其中status与GET /api/status返回结构一致，方便调用方每次操作后同步界面状态。

Agent API 总览

下面分别展开说明。

1. 查询状态

接口：GET /api/status

PowerShell 示例：

Invoke-RestMethod -Method Get ` -Uri "http://127.0.0.1:8765/api/status"

典型返回：

{ "selectedTab": "serial", "serialOpen": true, "serialEndpoint": "COM5 115200,8,N,1", "serialSendText": "01 03 00 01 00 0A", "serialTimestamp": true, "serialHexLog": true, "serialAutoScroll": true, "serialHexSend": true, "serialAppendCrlf": false, "serialAppendRtuCrc": true, "serialRepeatSend": false, "serialDtrEnable": false, "serialRtsEnable": false, "serialTxBytes": 8, "serialRxBytes": 25, "networkOpen": false, "networkEndpoint": "TCP 客户端空闲", "networkSendText": "", "networkTimestamp": true, "networkHexLog": false, "networkAutoScroll": true, "networkHexSend": false, "networkAppendCrlf": false, "networkRepeatSend": false, "networkTxBytes": 0, "networkRxBytes": 0 }

这个接口是所有 Agent 自动化流程的入口。比如 Codex 可以先判断工具是否在线、当前是否已经打开串口、HEX 显示是否已勾选、TX/RX 计数是否增长。

2. 串口连接

接口：POST /api/serial/connect

请求体：

{ "portName": "COM5", "baudRate": 115200, "dataBits": 8, "parity": "None", "stopBits": "1", "encodingName": "UTF-8", "readTimeout": 1000, "writeTimeout": 1000, "dtrEnable": false, "rtsEnable": false, "closeExisting": true, "open": true }

字段说明：

PowerShell 示例：

$body = @{ portName = "COM5" baudRate = 115200 dataBits = 8 parity = "None" stopBits = "1" encodingName = "UTF-8" readTimeout = 1000 writeTimeout = 1000 closeExisting = $true open = $true } | ConvertTo-Json -Compress Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/serial/connect" ` -ContentType "application/json; charset=utf-8" ` -Body $body

调用后，界面左侧串口参数区会同步更新，按钮状态也会变成已连接状态。

3. 串口断开

接口：POST /api/serial/disconnect

示例：

Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/serial/disconnect"

这个接口用于关闭当前串口连接。关闭后状态区会显示未连接。

4. 串口发送

接口：POST /api/serial/send

请求体：

{ "text": "01 03 00 01 00 0A", "hexSend": true, "appendCrlf": false, "appendRtuCrc": true, "send": true }

字段说明：

读取 1 号从站保持寄存器 1-10 示例：

$body = @{ text = "01 03 00 01 00 0A" hexSend = $true appendRtuCrc = $true send = $true } | ConvertTo-Json -Compress Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/serial/send" ` -ContentType "application/json; charset=utf-8" ` -Body $body

这里的text不需要手动写 CRC。工具会根据appendRtuCrc=true自动追加 CRC16，界面日志里会显示完整发送帧。

5. 串口复选框选项

接口：POST /api/serial/options

请求体：

{ "timestamp": true, "hexLog": true, "autoScroll": true, "hexSend": true, "appendCrlf": false, "appendRtuCrc": true, "repeatSend": false, "dtrEnable": false, "rtsEnable": false }

字段说明：

只想打开 HEX 日志、HEX 发送和追加 CRC，可以这样调用：

$body = @{ hexLog = $true hexSend = $true appendRtuCrc = $true timestamp = $true autoScroll = $true } | ConvertTo-Json -Compress Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/serial/options" ` -ContentType "application/json; charset=utf-8" ` -Body $body

没有传入的字段会保持原状态，这样 Agent 可以只改自己关心的选项。

6. 网口连接

接口：POST /api/network/connect

TCP Client 请求体：

{ "mode": "TCP Client", "remoteHost": "127.0.0.1", "remotePort": 502, "encodingName": "UTF-8", "closeExisting": true, "open": true }

TCP Server 请求体：

{ "mode": "TCP Server", "localPort": 502, "encodingName": "UTF-8", "closeExisting": true, "open": true }

字段说明：

7. 网口断开

接口：POST /api/network/disconnect

示例：

Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/network/disconnect"

8. 网口发送

接口：POST /api/network/send

请求体：

{ "text": "00 01 00 00 00 06 01 03 00 01 00 0A", "hexSend": true, "appendCrlf": false, "send": true }

Modbus TCP 示例：

$body = @{ text = "00 01 00 00 00 06 01 03 00 01 00 0A" hexSend = $true send = $true } | ConvertTo-Json -Compress Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/network/send" ` -ContentType "application/json; charset=utf-8" ` -Body $body

9. 网口复选框选项

接口：POST /api/network/options

请求体：

{ "timestamp": true, "hexLog": true, "autoScroll": true, "hexSend": true, "appendCrlf": false, "repeatSend": false }

示例：

$body = @{ hexLog = $true hexSend = $true timestamp = $true autoScroll = $true } | ConvertTo-Json -Compress Invoke-RestMethod -Method Post ` -Uri "http://127.0.0.1:8765/api/network/options" ` -ContentType "application/json; charset=utf-8" ` -Body $body

Codex 调用流程示例：未知 Modbus 参数扫描

如果连接了一个 Modbus RTU 从站，但不知道通讯参数，可以让 Agent 按候选参数逐个尝试。

典型流程：

1. 调用GET /api/status判断工具是否在线；
2. 枚举系统串口，例如COM5；
3. 从9600开始尝试常见波特率；
4. 尝试8N1、8E1、8O1、8N2；
5. 每组参数调用/api/serial/connect；
6. 设置/api/serial/options：hexLog=true、hexSend=true、appendRtuCrc=true；
7. 调用/api/serial/send发送探测报文；
8. 再查/api/status，通过serialRxBytes增量判断是否收到响应；
9. 根据响应长度判断是否符合 Modbus RTU 格式。

建议探测报文：

01 03 00 00 00 01 01 03 00 01 00 05 01 03 00 01 00 0A

典型响应长度：

在这个使用示例中，Codex 从9600开始扫描，最终识别到：COM5 115200,8,N,1

随后发送读取保持寄存器 10-20 的报文：01 03 00 0A 00 0B

工具自动追加 CRC，界面中显示：

TX 8B 01 03 00 0A 00 0B 24 0F [RTU Unit=1 FC=0x03 CRC OK] RX 27B 01 03 16 00 00 42 48 00 00 3F 00 00 00 00 03 00 03 00 00 00 00 3F 00 00 01 A7 60 [RTU Unit=1 FC=0x03 CRC OK]

这就形成了一个很清晰的人机协作链路：Agent 负责尝试、发送、判断；工具负责真实通讯和日志呈现；人可以随时看界面复核。

适合哪些场景

这个工具比较适合：

• 上位机开发过程中的串口调试；
• Modbus RTU 设备现场参数确认；
• TCP Client / TCP Server 简单收发测试；
• 自动化脚本批量发送测试报文；
• AI Agent 辅助排查通讯参数；
• 教学或培训场景中讲解“AI 如何调用本地工业软件工具”。

它不适合替代完整 SCADA、PLC 编程软件或复杂协议主站。它更像是一个轻量、开放、可被 Agent 调用的通讯调试工作台。

当前限制

V1.0.0 中 Agent API 主要返回状态、发送字节数和 TX/RX 计数。历史日志文本和最新 RX 原始字节暂时没有通过 API 直接返回。

也就是说，如果 Agent 要自动解析寄存器值，目前可以通过界面日志或后续扩展接口实现。后续计划增加类似接口：GET /api/serial/logs、GET /api/serial/last-rx。

这样 Agent 就可以直接读取最新回包并完成寄存器解析。

小结

AI通讯调试助手 V1.0.0 的核心价值，不只是“能发串口数据”，而是让桌面通讯调试工具具备了可被 Agent 调用的能力。

普通用户可以继续用按钮和文本框调试串口、网口；Codex 或其他 Agent 可以通过 HTTP API 在后台执行连接、发送、切换选项、扫描参数等动作；所有关键变化又会同步显示到界面上，方便人随时接管和确认。

对工业自动化调试来说，这是一种很实用的组合：AI 负责重复尝试和流程编排，人负责判断目标和确认结果。

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

V1.0.0 下载：https://github.com/lidecong133/AICommTool/releases/tag/v1.0.0

推荐标签

#C##WinForms#串口调试#Modbus#工业自动化#Codex#AI Agent#上位机开发