通信证据包（V10）

内容类型：调查模板难度：进阶适合：串口、TCP、SCPI、Modbus、协议、超时、重连和现场偶发问题阅读时间：约 8 分钟

通信调查的目标不是“收集越多越安全”，而是能够回答：第一处可观察异常发生在哪里，当前结论由什么证据支持？

一句“收不到数据”可能对应 Transport、Protocol、Session、Cancellation、Parser、Business Mapping 或 UI。证据包只为当前问题收集足够材料，不要求一次填满全部字段。

1. 先看问题类型

问题	第一优先证据
只查当前命令/解析链	Read-Only Trace，不必先做完整证据包
明确局部修改	当前行为 + 目标行为 + focused input/output
以前正常、最近异常	known-good + changed files + 同场景新旧证据
偶发 timeout / retry 后恢复	时间戳 TX/RX + Session + cancel/retry + Timeline
解析值错误	Raw + 协议定义 + Expected / Actual Parse
第二次启动失败 / 重连异常	Session owner + Stop/Dispose 时间线
新设备联调	协议 Facts + 示例报文 + Open Decisions

2. 最小通用证据

尽量保留：

text

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

例如：

text

14:20:31.125 [TX] session=1 cmd=READ_STATUS
14:20:31.136 [RX] session=1 raw="..."
14:20:31.137 [PARSE] state=Ready
14:20:35.000 [TIMEOUT] cmd=READ_DATA retry=1
14:20:35.120 [RECOVERY] action=retry

格式可以不同，但要能重建时间线。

如果日志来源很多，直接使用日志与时间线诊断。

3. Raw、Parse、Engineering 分层

text

Raw Frame/Text
→ Parsed Field
→ Engineering / Business Value

例如：

text

Raw: 04 E2
Parsed: 1250
Conversion: ×0.1 V
EngineeringValue: 125.0 V

只提供“125 V”无法判断问题在传输、端序、解析还是换算。

涉及测量值见测量值语义。

4. RegressionFix：以前正常就先比以前

yaml

KnownGood:
  CommitOrVersion:
  DateOrBuild:

CurrentBad:
  CommitOrVersion:

ChangedFiles:
  - relevant transport/parser/session/config/workflow files

SameScenarioEvidence:
  OldTxRx:
  NewTxRx:
  OldTiming:
  NewTiming:

BehaviorDelta:
  - first observable difference

根因候选优先从 BehaviorDelta 往回追。

如果旧代码和当前完全相同，不能因为它“看起来不合理”就写成本次 regression cause。

5. 偶发问题：先找第一个异常点

text

T0 Connected
T1 TX A
T2 RX / no RX evidence
T3 timeout / cancel / error
T4 retry / reconnect
T5 recovery

然后问：

第一个和正常路径不同的事件是什么？

只有时间线仍不能解释时，再给 1–3 个可证伪假设。

例如：

text

H1: first response arrived after timeout and was consumed by retry
Evidence needed: request/session id + RX time + retry start

不要列十几个“都有可能”的原因。

6. Session Owner 是通信证据的一部分

现场问题常常不是“协议错”，而是：

旧 read 没退出；
新 session 已建立；
两个 timer 同时轮询；
第二个 SCPI client 改变了设备状态；
response 被另一请求消费。

至少能回答：

text

Session Owner:
CreatedAt:
StopRequestedAt:
CancelledAt:
DisposedAt:
ReconnectedAt:

如果设备只支持单会话，调查也不要为了取证另开第二连接。

7. Replay：能回放就不要反复撞真机

真实 TX/RX 可以整理成：

yaml

Scenario: first request timeout, retry succeeds
Steps:
  - AtMs: 0
    Direction: TX
    Raw: "..."
  - AtMs: 23
    Direction: RX
    Raw: "..."
  - AtMs: 3000
    Event: Timeout
  - AtMs: 3150
    Direction: TX
    Raw: "..."
Expected:
  - delayed response is not associated with the retry

Replay 的价值：

修复前后使用同一输入；
稳定复现时序；
不依赖设备持续在线；
可以逐步转成回归测试。

已有 Fake/Replay seam 时优先复用。

8. 协议证据按实际模型收集

自定义二进制帧

可能需要：

text

FrameBoundary
ByteOrder
Length
Checksum（如果协议有）
NormalRaw
FailingRaw
ExpectedParse
ActualParse
BufferContext

只有当前问题涉及 byte-stream 分帧时，才补 receive chunk / half / multiple-frame 证据。

SCPI

更常见的是：

text

Command sequence
Terminator
Response text
Timeout
*OPC?/status（设备支持时）
Error queue
Session state

Modbus

常见：

text

Unit/Slave ID
Function
Address/Register
Raw request/response
Exception code
Endian/word order
Transaction ID（TCP）

不要用一套 CRC/粘包表覆盖所有通信模型。

9. 连接、timeout 和重连

记录：

text

Disconnected
→ Connecting
→ Connected
→ RequestPending
→ Timeout/Error
→ Retry/Reconnecting
→ Resynchronized

重点看：

谁触发断开；
旧任务是否退出；
新 session 建立前旧 session 是否仍能收数据；
reconnect 后是否需要重新 login/subscribe/configure；
timeout 是 transport 还是业务等待；
cancel 与 timeout 是否混成同一路径。

这些通常比简单把 retry 3 改成 5 更接近根因。

10. EvidenceGrade

等级	典型证据	可写结论
A	稳定自动复现 + 修复后转绿	RootCauseConfirmed
B	稳定 Fake/Replay + 代码证据	高置信软件侧根因
C	日志 + 时间线 + known-good + 代码	强候选 / 条件性确认
D	单次现场现象 / 推断	怀疑 / 候选

“重试后恢复”通常只够标 SuspectedTransient。

11. 软件证据和真机证据分开

Fake/Replay 可以证明解析、状态映射、请求关联等软件行为，但不能自动证明：

实际设备固件行为；
真实驱动时序；
高压/运动等设备动作；
现场网络和保护链。

软件侧已经验证，但真机尚未执行时：

text

HardwareVerification: HardwarePending

不是 EnvironmentBlocked。

真实设备操作见真实设备操作安全。

12. 操作员信息与诊断证据分层

操作员层可以显示：

text

设备通信异常，请检查连接后重试。

维护诊断则保留：

text

原始命令/响应
底层异常
错误码
timeout
retry
session/request
时间线

不要为了“界面简洁”删掉现场调查证据。

13. 通用调查 Prompt

text

$host-computer-dev
我正在排查一个设备通信问题。

现象：
是否以前正常：
最后正常版本/时间：
通信方式/设备：
已有 TX/RX/日志/协议：
复现条件：稳定 / 偶发 / 重试恢复 / 现场才有

请先建立最短证据时间线，并找第一个异常点。
如果是近期回归，先比较 known-good 与相关改动。
优先使用现有 Fake / Replay。
只有证据仍不能解释时，再给 1–3 个可证伪假设。
结论标 EvidenceGrade A/B/C/D；需要真机但未执行的步骤标 HardwarePending。

14. 常见反模式

只有截图，没有 TX/RX；
只有工程值，没有 Raw；
用户说“以前正常”，却不看 Git；
偶发问题没有时间戳；
一开始列十几个原因；
为调查开第二个真实设备会话；
重试恢复后写“网络抖动已确认”；
修复前后换了测试输入；
Replay 通过后写“真机已验证”。

下一步

一句话原则

通信证据包不是字段越多越好，而是能让时间线、Session、Raw 数据和当前结论形成一条可验证的最短证据链。

通信证据包（V10） ​

1. 先看问题类型 ​

2. 最小通用证据 ​

3. Raw、Parse、Engineering 分层 ​

4. RegressionFix：以前正常就先比以前 ​

5. 偶发问题：先找第一个异常点 ​

6. Session Owner 是通信证据的一部分 ​

7. Replay：能回放就不要反复撞真机 ​

8. 协议证据按实际模型收集 ​

自定义二进制帧 ​

SCPI ​

Modbus ​

9. 连接、timeout 和重连 ​

10. EvidenceGrade ​

11. 软件证据和真机证据分开 ​

12. 操作员信息与诊断证据分层 ​

13. 通用调查 Prompt ​

14. 常见反模式 ​

下一步 ​

一句话原则 ​

通信证据包（V10）

1. 先看问题类型

2. 最小通用证据

3. Raw、Parse、Engineering 分层

4. RegressionFix：以前正常就先比以前

5. 偶发问题：先找第一个异常点

6. Session Owner 是通信证据的一部分

7. Replay：能回放就不要反复撞真机

8. 协议证据按实际模型收集

自定义二进制帧

SCPI

Modbus

9. 连接、timeout 和重连

10. EvidenceGrade

11. 软件证据和真机证据分开

12. 操作员信息与诊断证据分层

13. 通用调查 Prompt

14. 常见反模式

下一步

一句话原则