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

lidecong133

265人浏览 · 2026-06-14 08:39:22

lidecong133 · 2026-06-14 08:39:22 发布

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 调试为例，说明这个工具可以覆盖的典型流程：

启动 AI通讯调试助手；
Codex 连接本地 Agent API；
在不知道通讯参数的情况下，从 9600 波特率开始扫描；
识别到可用参数：COM5 115200,8,N,1；
切换收发日志为 HEX 显示；
自动发送 Modbus RTU 读取保持寄存器报文；
工具自动追加 CRC；
界面中显示 TX/RX 日志和 CRC 校验结果；
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 总览

方法	路径	作用
`GET`	`/api/status`	查询当前串口、网口、发送框、复选框和计数状态
`POST`	`/api/serial/connect`	设置串口参数并打开串口
`POST`	`/api/serial/disconnect`	关闭串口
`POST`	`/api/serial/send`	写入串口发送框并按选项发送
`POST`	`/api/serial/options`	设置串口页复选框
`POST`	`/api/network/connect`	设置网口参数并连接 TCP Client 或启动 TCP Server
`POST`	`/api/network/disconnect`	关闭网口连接或监听
`POST`	`/api/network/send`	写入网口发送框并按选项发送
`POST`	`/api/network/options`	设置网口页复选框

下面分别展开说明。

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
}

字段说明：

字段	类型	说明
`portName`	string	串口名，例如 `COM5`
`baudRate`	number	波特率，例如 `9600`、`115200`
`dataBits`	number	数据位，常用 `8`
`parity`	string	校验位：`None`、`Even`、`Odd`、`Mark`、`Space`
`stopBits`	string	停止位：`1`、`1.5`、`2`，也支持 `One`、`OnePointFive`、`Two`
`encodingName`	string	文本收发编码，例如 `UTF-8`、`ASCII`、`GBK`
`readTimeout`	number	读超时，单位 ms
`writeTimeout`	number	写超时，单位 ms
`dtrEnable`	bool	是否启用 DTR
`rtsEnable`	bool	是否启用 RTS
`closeExisting`	bool	打开前是否先关闭已有串口
`open`	bool	是否立即打开串口

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
}

字段说明：

字段	类型	说明
`text`	string	要写入发送框的内容
`hexSend`	bool	是否按 HEX 发送
`appendCrlf`	bool	是否追加 CRLF
`appendRtuCrc`	bool	是否自动追加 Modbus RTU CRC
`send`	bool	`true` 表示写入发送框后立即发送，`false` 表示只更新发送框

读取 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
}

字段说明：

字段	对应界面选项
`timestamp`	时间戳
`hexLog`	HEX 显示
`autoScroll`	自动滚动
`hexSend`	HEX 发送
`appendCrlf`	追加 CRLF
`appendRtuCrc`	追加 CRC
`repeatSend`	周期发送
`dtrEnable`	DTR 使能
`rtsEnable`	RTS 使能

只想打开 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
}

字段说明：

字段	说明
`mode`	`TCP Client` 或 `TCP Server`
`remoteHost`	TCP Client 远程地址
`remotePort`	TCP Client 远程端口
`localPort`	TCP Server 本地监听端口
`encodingName`	文本编码
`closeExisting`	是否先关闭已有连接
`open`	是否立即连接或监听

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 按候选参数逐个尝试。

典型流程：

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

建议探测报文：

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

典型响应长度：

请求	含义	正常响应长度
`01 03 00 00 00 01`	读 1 个保持寄存器	7 字节
`01 03 00 01 00 05`	读 5 个保持寄存器	15 字节
`01 03 00 01 00 0A`	读 10 个保持寄存器	25 字节

在这个使用示例中，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 负责尝试、发送、判断；工具负责真实通讯和日志呈现；人可以随时看界面复核。