串口 TCP 通信任务模板

串口和 TCP 是上位机项目最常见、也最容易出问题的部分。

使用 AI 做通信模块时，不要只说“帮我写串口通信”。必须把通信方式、设备角色、协议格式、示例报文、超时、重连、日志要求讲清楚。

0. 推荐通信架构

实际上位机项目里，建议把“数据接收”和“协议解析”分开，不要在接收事件或接收线程里直接做复杂解析、保存数据库或刷新 UI。

推荐流程：

串口/TCP 接收线程
    -> 只负责读取原始字节
    -> 写入接收缓存或线程安全队列
    -> 尽快返回，继续接收数据

协议解析线程
    -> 从缓存/队列取数据
    -> 处理粘包、半包、错误帧
    -> 校验 CRC 或校验和
    -> 解析成业务数据对象

业务分发层
    -> 根据项目需要决定：刷新界面 / 保存数据 / 触发报警 / 推进测试流程 / 写日志

这样做的好处：

1. 接收线程不被复杂解析、数据库保存、UI 刷新拖慢。
2. 高频数据或设备主动上报时更稳定。
3. 粘包、半包、错误帧可以集中在解析线程处理。
4. 解析后的数据可以按业务需要分发，不把通信层和界面层绑死。
5. 后续做模拟数据、日志回放、单元测试更方便。

基本原则：

1. 接收线程只做“收数据、入缓存、记录必要原始日志”。
2. 解析线程只做“组帧、校验、解析、输出业务对象”。
3. UI 刷新必须切回 UI 线程。
4. 数据保存不要阻塞接收线程。
5. 日志记录要控制频率，避免高频通信时日志拖慢程序。
6. 解析后的数据是否存储、显示、报警或参与业务流程，由实际项目决定。

0.1 通信任务先确认什么

通信任务不要一上来就让 AI 写 SerialPort、TcpClient 或协议解析代码。

先确认下面 5 件事：

必须确认	为什么重要	缺失时怎么处理
设备谁主动发起连接或发送数据	决定 Client/Server、轮询/上报、超时规则	先画连接和数据流，不写代码
一帧数据的边界怎么判断	决定粘包半包处理方式	没有帧头、长度、帧尾时先补协议规则
请求和响应是否一一对应	决定等待回复、超时、重发和并发限制	先定义命令流水号或禁止并发发送
解析后的数据去哪里	决定 UI、存储、报警、流程推进的分发接口	先定义业务对象和事件，不直接刷新 UI
如何验证通信正确	决定日志、模拟器、测试报文和真实设备测试	先准备正常帧、异常帧、断线场景

如果这些信息不清楚，AI 最多只能输出方案和待确认问题，不应该直接生成完整通信模块。

0.2 通信证据包

真实联调时，建议把下面材料整理成一个“通信证据包”，再交给 AI 分析或修改：

材料	最低要求
协议说明	帧头、长度、命令字、数据区、校验、帧尾、字节序
示例报文	至少 1 条发送帧、1 条正常接收帧、1 条异常帧
通信日志	带时间戳、方向、原始十六进制、解析结果、错误原因
连接状态	连接、断开、重连、超时、心跳状态变化
复现步骤	先做什么、设备什么时候回、软件什么时候异常
最近改动	最近改过协议、缓存、线程、UI 刷新、保存逻辑中的哪一块

日志格式建议：

2026-07-12 14:20:31.125 [TX] AA 55 04 01 00 64 XX XX
2026-07-12 14:20:31.136 [RX] AA 55 04 81 00 64 XX XX
2026-07-12 14:20:31.137 [PARSE] cmd=0x81 value=100 crc=ok
2026-07-12 14:20:35.000 [TIMEOUT] cmd=0x02 elapsed=3000ms retry=1

1. 通信任务输入信息

项目项	填写内容
通信方式	串口 / TCP Client / TCP Server / UDP / Modbus
设备角色	上位机主动连接 / 设备主动连接 / 主站 / 从站
连接参数	COM、波特率、IP、端口、超时、重试次数
协议格式	文本 / 十六进制 / 固定长度 / 长度字段 / 帧尾结束
示例报文	发送示例、接收示例、异常示例
发送周期	手动 / 定时 / 测试步骤触发 / 心跳
接收频率	低频 / 高频 / 设备主动上报
超时时间	等待回复多久算失败
重连规则	是否自动重连、间隔、最大次数
日志要求	是否记录原始报文、解析结果、错误原因
解析后用途	显示到界面 / 保存数据 / 触发报警 / 推进流程 / 只记录日志 / 不确定
验证方式	固定报文测试 / 模拟器 / 真实设备 / 长稳测试

2. 串口任务模板

需要提供的信息

项目项	填写内容
串口号	COM1、COM2 或用户选择
波特率	9600、115200 等
数据位	7 / 8
停止位	1 / 1.5 / 2
校验位	None / Odd / Even
打开逻辑	启动自动打开 / 用户点击打开
关闭逻辑	用户关闭 / 程序退出释放
接收方式	事件接收 / 后台线程 / 异步读取；接收逻辑应尽快返回
数据缓存	接收线程写入缓存或队列，解析线程独立处理
帧解析	帧头、长度、命令字、数据区、校验、帧尾
CRC 校验	是否需要，算法是什么
超时处理	超时提示、重试、记录日志
异常日志	打开失败、接收异常、解析失败

发给 AI 的模板

请你作为 C# WPF 上位机通信模块开发助手，帮我设计串口通信模块。

通信参数：
协议格式：
发送报文示例：
接收报文示例：
粘包半包风险：
CRC 校验方式：
超时处理：
异常日志要求：
解析后的数据用途：

请输出：
1. 模块职责划分。
2. 串口打开/关闭流程。
3. 接收线程设计：只负责读取原始字节并写入缓存/队列。
4. 解析线程设计：从缓存/队列取数据，处理组帧、校验和解析。
5. 解析后的业务数据如何分发到 UI、存储、报警或业务流程。
6. 超时和异常处理策略。
7. 需要的类和方法清单。
8. 测试用例和验收点。

先给设计方案，不要直接写完整代码。

3. TCP 任务模板

需要提供的信息

项目项	填写内容
模式	Client / Server
IP 与端口	目标 IP、监听端口、本地端口
连接建立	手动连接 / 自动连接 / 启动监听
断线重连	是否需要、重连间隔、最大次数
心跳机制	心跳报文、周期、超时次数
接收缓存	接收线程写入缓存或队列，解析线程独立处理粘包半包
协议边界	固定长度、长度字段、帧尾、分隔符
超时重发	哪些命令需要等待回复和重发
异常恢复	断线、连接失败、发送失败、解析失败
解析后用途	显示到界面 / 保存数据 / 触发报警 / 推进流程 / 只记录日志 / 不确定

发给 AI 的模板

请你作为 C# WPF 上位机 TCP 通信模块开发助手，帮我设计 TCP 通信模块。

TCP 模式：
连接参数：
协议格式：
心跳要求：
断线重连规则：
粘包半包处理要求：
超时重发要求：
日志要求：
解析后的数据用途：

请输出：
1. TCP 连接状态机。
2. 连接、断开、重连、心跳流程。
3. 接收线程设计：只负责读取原始字节并写入缓存/队列。
4. 解析线程设计：从缓存/队列取数据，处理组帧、校验和解析。
5. 解析后的业务数据如何分发到 UI、存储、报警或业务流程。
6. 异常恢复策略。
7. UI 状态显示建议。
8. 测试清单。

4. 协议解析模板

字段	示例	说明
帧头	AA 55	用于识别一帧开始
长度	0A	数据区或整帧长度
命令字	01	区分不同功能
数据区	00 64	实际业务数据
校验位	CRC16	校验帧是否正确
帧尾	0D 0A	用于识别结束
示例帧	AA 55 04 01 00 64 XX XX	完整示例
解析结果	命令=读取数据，值=100	AI 应输出的结构化结果

协议解析 Prompt：

请根据下面协议格式，帮我设计协议解析流程。

帧头：
长度规则：
命令字：
数据区：
校验方式：
帧尾：
示例报文：

请输出：
1. 如何从缓存中找完整帧。
2. 如何处理半包、粘包、错误帧。
3. 如何校验 CRC。
4. 如何把数据区解析成业务对象。
5. 解析线程和接收线程如何解耦。
6. 解析后的业务对象如何交给显示、存储或业务流程。
7. 异常日志应该记录什么。
8. 测试报文清单。

4.1 协议测试报文矩阵

协议解析不能只测“正常一帧”。至少准备下面这些报文：

类型	示例说明	期望结果
正常完整帧	一次接收刚好是一帧	解析成功，输出业务对象
半包	一帧拆成两次或多次接收	缓存等待，不误报错误
粘包	一次接收包含两帧或多帧	连续解析出多条业务对象
前置噪声	正常帧前有无效字节	丢弃噪声，找到帧头
CRC 错误	校验位故意错误	丢弃或标记错误，记录日志
长度错误	长度字段与实际数据不一致	不越界解析，记录错误
未知命令字	命令字不在协议表内	记录未知命令，不崩溃
超长数据	超过协议最大长度	丢弃或截断，防止缓存无限增长
断线中收到残帧	连接中断前只有半帧	清理状态或按策略保留，不能污染下次连接

发给 AI 的测试报文 Prompt：

请根据下面协议，生成协议解析测试报文矩阵。

要求覆盖：
1. 正常完整帧。
2. 半包。
3. 粘包。
4. 前置噪声。
5. CRC 错误。
6. 长度错误。
7. 未知命令字。
8. 超长数据。
9. 断线前残帧。

请输出每条报文的十六进制示例、分包方式、期望解析结果和日志要求。

协议如下：
【粘贴协议】

5. 常见问题排查

问题	优先检查
收不到数据	端口/IP、线缆、设备是否发送、接收事件是否绑定
数据乱码	文本编码、十六进制显示、波特率、协议理解是否错误
CRC 错误	CRC 算法、初始值、高低字节顺序、校验范围
偶发丢包	接收线程是否被解析/保存/UI 刷新阻塞，缓存队列是否溢出，日志是否过重
粘包半包	是否按协议边界解析，而不是按一次接收当一帧
TCP 断开不重连	状态机、异常捕获、重连定时器、资源释放
UI 卡死	通信线程是否阻塞 UI 线程，是否同步等待
解析延迟	解析线程是否处理太慢，是否需要限流、批处理或丢弃策略
日志看不出问题	是否记录原始报文、时间戳、连接状态、异常堆栈

6. 通信实现禁区

下面这些写法在小 Demo 里可能能跑，但在真实上位机项目里容易出问题：

1. 把一次 DataReceived 或一次 ReadAsync 当成完整一帧。
2. 在接收事件里直接解析复杂协议、保存数据库或刷新 UI。
3. 没有最大缓存长度，异常数据可能导致内存持续增长。
4. 没有连接状态机，连接、断线、重连、手动断开混在一起。
5. 发送命令后没有超时、重试、取消或并发控制。
6. UI 上只显示“连接成功”，但日志里没有原始报文和状态变化。
7. CRC 算法没有固定测试样例，靠现场设备返回来猜。
8. 修改协议解析后只测正常帧，不测半包、粘包和异常帧。

7. 通信修改后的最小验收

修改内容	最小验收
改连接/断开	能连接、能断开、重复连接断开 3 次状态正常
改重连/心跳	拔线或停服务后进入断线状态，恢复后按规则重连
改发送命令	正常响应、超时、发送失败都有日志和 UI 状态
改协议解析	正常帧、半包、粘包、CRC 错误、未知命令都按预期处理
改数据分发	UI、保存、报警或流程推进只收到解析后的业务对象
改日志	能按时间线追踪连接、发送、接收、解析、异常
高频接收	接收不卡 UI，日志不会拖慢程序，缓存不会持续增长

8. AI 提示词模板

设计通信模块

请先不要写代码。请根据我的通信需求，设计一个适合 C# WPF 上位机的通信模块。

要求接收线程和解析线程分开：
1. 接收线程只负责接收原始字节并写入缓存/队列。
2. 解析线程从缓存/队列取数据，处理粘包、半包、校验和协议解析。
3. 解析后的业务数据再根据项目需要分发到 UI、存储、报警或业务流程。

请说明类职责、状态流转、异常处理、日志记录和验收点。

生成协议解析类

请根据下面协议文档和示例报文，设计协议解析类。

重点说明：
1. 如何处理粘包、半包、错误帧和 CRC 校验。
2. 解析线程如何从接收缓存/队列读取数据。
3. 解析后的业务对象如何输出给上层。

不要假设每次接收都是完整一帧，也不要把复杂解析放在接收线程里。

分析日志

下面是通信日志。请按时间线分析连接、发送、接收、解析、异常之间的关系，先定位可能原因，不要直接给代码。

排查丢包

我的上位机通信偶发丢包。请根据代码、日志和协议，列出可能原因、需要补充的日志、最小复现方法和排查顺序。

优化重连

请帮我设计 TCP 自动重连策略。要求避免重复连接、资源泄漏、UI 状态混乱，并说明断线、重连中、已连接、连接失败的状态切换。

增加异常处理

请检查下面通信代码的异常处理是否完整，重点关注打开失败、发送失败、接收异常、解析失败、超时和断线恢复。