串口 / TCP / 设备通信任务模板（V10）

内容类型：方法说明 + 模板难度：进阶适合：串口、TCP、SCPI、Modbus、自定义协议、超时、重连和设备联调阅读时间：约 12 分钟

通信任务最容易出现两种过度：用户只问一条命令，Agent 却重画通信架构；或者项目用 SCPI 文本协议，却机械加入半包、粘包、CRC 的“完整测试矩阵”。

V10 的原则是：先判断任务，再识别当前协议模型；只设计和验证真实存在的风险。

1. 先分任务

当前问题	路径	第一动作
“这条命令从哪里发？”	Read-Only Trace	最短调用链
已确认的 timeout / retry / 局部常量修改	Execution	核对当前实现后最小修改
“以前正常，最近开始超时”	RegressionFix	known-good + changed files + 同场景证据
“偶发失败，重试又好了”	Feedback Ladder	时间线 + TX/RX + Replay
新设备，但协议和行为已明确	Execution	Compact Brief + 适配已有 seam
新协议、并发、恢复和后果仍未知	Discovery	Facts / Decisions / Frontier

只有最后一类需要展开完整通信设计。

2. Facts 和 Decisions 分开

Facts 由 Agent 优先确认

当前 Transport 和库；
现有 Session owner；
发送、接收、解析入口；
当前 timeout/retry；
是否有 sequence / transaction id；
是否有 checksum；
最近相关 Git 变化；
是否已有 Fake / Replay / focused tests；
当前日志能否重建 TX→RX→PARSE 时间线。

Decisions 才需要项目人员决定

超时后继续、重试、断开、报警还是停机；
掉线是否改变主流程；
是否允许并发请求；
自动重连后是否重新配置；
写命令是否危险；
保存/诊断失败是否阻断业务；
真机验证允许执行到哪一步。

“通信失败”本身不等于 InterlockFault。

3. 先识别协议模型

不要把所有通信都理解成同一种“帧协议”。

模型	典型关注点
串口自定义二进制	buffer ownership、帧边界、校验、主动上报、串行化
TCP 自定义流协议	byte stream、frame boundary、request correlation、旧 session
SCPI/VISA	命令顺序、终止符、OPC/状态寄存器、error queue、单会话
Modbus RTU/TCP	功能码、异常码、地址/寄存器、端序、transaction id（TCP）
厂商 SDK	SDK 生命周期、线程/回调模型、错误码、版本兼容
文件/共享目录式交换	ownership、写入完成判定、原子替换、轮询/事件

协议模型决定后面的测试矩阵。

4. 最小证据包

按当前问题尽量保留：

text

Timestamp
Direction: TX / RX
Session / Connection
Command / Message
Raw Bytes / Raw Text
Parsed Result
Timeout / Retry / Cancellation
Device / Protocol Error
Business Consequence

如果日志很多，先转到日志与时间线诊断，找第一个异常点，不只看最后一条 Error。

5. RegressionFix：以前正常先比较以前

text

known-good
→ current bad
→ relevant changed files
→ method/config/protocol diff
→ same-scenario TX/RX/timing
→ first behavior delta

如果可疑代码在 known-good 中完全相同，单凭“看起来不合理”不能把它写成本次回归根因。

回退后恢复只能先写：

text

RolledBackToKnownGood

不自动等于 RegressionFixed。

6. Session Ownership

通信系统必须能回答：

text

谁创建连接？
谁拥有它？
谁允许发送？
谁负责 Stop / Cancel / Dispose？
重连时旧 session 何时彻底失效？

如果设备只允许单连接：

text

One Device
→ One Session Owner

诊断、恢复、健康查询优先复用已有会话或使用日志/Replay。不要为了“顺便查状态”偷偷再开第二个串口、TCP 或 SCPI client。

7. 新协议的设计输入

只有进入 Discovery 时才逐步补齐：

yaml

Transport:
Role:
Session:
  Ownership:
  Concurrency:
  Correlation:

MessageBoundary:
  Type: FixedLength | LengthField | Delimiter | Terminator | SDKManaged | Other

Integrity:
  Type: None | CRC | Checksum | ProtocolManaged

Timing:
  Timeout:
  Retry:
  Heartbeat:

Recovery:
  DisconnectConsequence:
  Reconnect:
  Resync:

DataSemantics:
  RawValue:
  Conversion:
  EngineeringUnit:

Logging:
  TxRxRaw:
  ParsedFields:
  ErrorCode:
  Timestamp:

Safety:
  DangerousWrites:
  HumanConfirmation:
  HardwareBoundary:

没有正式材料支持的内容标 Unknown / OpenDecision，不要补造。

8. 串口专项

重点看：

Port 参数是否与设备一致；
buffer ownership 是否清楚；
读写是否需要串行化；
主动上报与请求响应是否共享同一流；
timeout 后迟到响应是否污染下一请求；
Stop 后 read 是否退出；
重开前旧端口是否 Dispose；
是否重复事件订阅。

DataReceived 不等于“每次事件就是一帧”。应用需要根据实际协议决定读多少、怎样缓存和组消息。

9. TCP 专项

重点看：

Client / Server 角色；
connect/read/write 能否取消；
Receive == 0 是否正确视为对端关闭；
当前协议如何定义消息边界；
请求响应如何关联；
重连时旧任务是否还能读写；
新连接前旧 session 是否已失效；
重连后是否需要 login/subscribe/configure。

只有当前协议是基于 TCP byte stream 自行组帧时，才讨论粘包/半包；不要把这个词机械套到所有 TCP SDK 或上层协议。

10. 协议类型决定 focused 测试

所有通信任务通常都值得验证

text

正常请求/响应或正常输入输出
超时/取消（若相关）
Stop / Dispose / Recreate（若本次涉及生命周期）
日志和错误上下文

自定义流式二进制协议

按实际定义选择：

半包；
多帧同一 receive；
前导垃圾/重新同步；
长度非法；
buffer 上限。

有 CRC / Checksum 的协议

才增加：

校验正确；
校验错误；
校验覆盖范围。

SCPI

更关注：

terminator；
command sequence；
query/write 交替；
*OPC? / status / error queue（设备实际支持时）；
timeout 后会话是否仍同步；
不建立第二互斥会话。

Modbus

更关注：

unit/slave id；
function code；
exception response；
register range；
endian/word order；
transaction id（TCP）。

厂商 SDK

更关注：

SDK 返回码；
callback/threading；
handle lifetime；
version/driver compatibility。

没有的协议特性就不测试。 “测试矩阵完整”不是把所有网络名词填一遍。

11. Measurement Semantics

设备通信值建议沿链检查：

text

RawValue
→ Decode
→ Conversion
→ EngineeringValue
→ ThresholdBasis / Display / Record

必要时明确：

text

Aggregation
LoggedUnit

更完整说明见测量值语义。

12. 偶发现场问题：Timeline + Replay

13. 验证等级

变化	建议验证
纯日志/显示文本	V0/V1
局部通信代码且业务语义不变	V1/V2 focused
timeout、retry、字段、换算	V2 + Fake/Replay/focused test
reconnect、session、state、并发、事件后果	V3 + WorkflowSmoke
公共协议/SDK/Schema/发布兼容	V4

0 tests matched 不是 TestPassed。

14. 真实设备边界

默认：

text

HardwareAction: ForbiddenByDefault

未经明确授权，不自动执行：

高压输出；
电机/伺服运动；
阀门、继电器、加热、气路等状态改变；
清配置、写固件、恢复出厂；
会破坏现场数据的动作。

安全且获授权的只读查询可作为反馈梯度后段，但也不能假设“读取一定无副作用”。

软件侧做到当前范围、真机尚未执行时写：

text

HardwareVerification: HardwarePending

不是 EnvironmentBlocked。

详见真实设备操作安全。

15. 四个最常用 Prompt

Read-Only

text

$host-computer-dev
只做 Read-Only Trace，不修改代码。
请找到【命令/字段】的发送入口、接收/解析位置、最终数据去向和相关 timeout/retry。
到证据足够回答问题时停止，不做架构重设计、构建或测试。

Execution

text

$host-computer-dev
这是已经明确的通信修改，请走 Execution。
CurrentBehavior:
RequestedBehavior:
NonGoals:

先核对当前协议模型、session owner 和 affected scope，再做最小修改；只跑匹配本次语义的 focused 验证。

RegressionFix

text

$host-computer-dev
这个通信问题以前正常、最近才出现。
请先确定 known-good，比较相关 changed files、配置、协议/命令和同场景 TX/RX，不要从当前代码里随便挑一个可疑点当根因。

Discovery

text

$host-computer-dev
我要接入一个新设备，协议/恢复/并发仍有关键未知。
请先从设备手册、协议和样例报文确认 Facts，再建立 Decision Tree / Frontier；只问会改变实现结果的业务决策。
Blocking Frontier 清零后输出最小通信设计和验证计划。

16. 常见反模式

用户只问一条命令，Agent 重画整个架构；
用户说“以前正常”却不看 Git；
把每次 TCP Receive 当成一条业务消息；
SCPI 任务也固定要求 CRC/粘包测试；
为诊断开第二个真实设备 Session；
把 retry 数增加当成根因修复；
重试后恢复就写“网络抖动已确认”；
Fake/Replay 通过后写“真机验证通过”。

下一步

一句话原则

先识别通信任务和协议模型，再验证真正存在的边界；通信测试不是把半包、粘包、CRC、重连、真机全部固定跑一遍。

串口 / TCP / 设备通信任务模板（V10） ​

1. 先分任务 ​

2. Facts 和 Decisions 分开 ​

Facts 由 Agent 优先确认 ​

Decisions 才需要项目人员决定 ​

3. 先识别协议模型 ​

4. 最小证据包 ​

5. RegressionFix：以前正常先比较以前 ​

6. Session Ownership ​

7. 新协议的设计输入 ​

8. 串口专项 ​

9. TCP 专项 ​

10. 协议类型决定 focused 测试 ​

所有通信任务通常都值得验证 ​

自定义流式二进制协议 ​

有 CRC / Checksum 的协议 ​

SCPI ​

Modbus ​

厂商 SDK ​

11. Measurement Semantics ​

12. 偶发现场问题：Timeline + Replay ​

13. 验证等级 ​

14. 真实设备边界 ​

15. 四个最常用 Prompt ​

Read-Only ​

Execution ​

RegressionFix ​

Discovery ​

16. 常见反模式 ​

下一步 ​

一句话原则 ​

串口 / TCP / 设备通信任务模板（V10）

1. 先分任务

2. Facts 和 Decisions 分开

Facts 由 Agent 优先确认

Decisions 才需要项目人员决定

3. 先识别协议模型

4. 最小证据包

5. RegressionFix：以前正常先比较以前

6. Session Ownership

7. 新协议的设计输入

8. 串口专项

9. TCP 专项

10. 协议类型决定 focused 测试

所有通信任务通常都值得验证

自定义流式二进制协议

有 CRC / Checksum 的协议

SCPI

Modbus

厂商 SDK

11. Measurement Semantics

12. 偶发现场问题：Timeline + Replay

13. 验证等级

14. 真实设备边界

15. 四个最常用 Prompt

Read-Only

Execution

RegressionFix

Discovery

16. 常见反模式

下一步

一句话原则