半帧响应为什么也会返回成功：读懂 Microi吾码 V8.Tcp 的三种结束方式

Microi吾码

5人浏览 · 2026-09-13 10:01:49

Microi吾码 · 2026-09-13 10:01:49 发布

半帧响应与完整确认的责任边界

Microi吾码技术分析 · 概念图与实测证据分开标注

摘要｜ 收到字节不等于收到完整报文。沿着当前 V8.Tcp 源码和三组本机回环结果，拆开 Timeout、Truncated 与设备执行成功之间的边界。

✦ 01 / 一字节响应，为什么不是失败

AI 帮我们写设备接口时，最容易补出一句看似合理的判断：Code 等于 1，就把任务改成已完成。问题是，这个 1 究竟属于哪一层？我沿着 Microi吾码的 V8.Tcp 调用读到接收循环，发现一个更具体的边界。

本次问题｜ 接收端已经收到一个字节，随后等到超时。当前实现保留这一个字节，并返回 Code=1、ReceiveEndReason=Timeout、Truncated=false。

这不是凭空假设。本文用当前 V8Tcp.cs 做了独立本机回环验证，分别模拟部分响应超时、达到接收上限和远端关闭。它验证网络原子行为，不代表真实打印机、客户现场或生产部署已验收。

接收循环的三种结束方式：超时、上限、远端关闭

接收循环的三种结束方式：超时、上限、远端关闭

✦ 02 / 平台原子和业务编排各管什么

Microi 的接口引擎可以编排权限、可信设备配置、业务状态和返回值；V8.Tcp 提供有界的连接、发送与接收能力。平台不知道每一款设备报文的长度字段、校验算法和应答语义，因此不能替业务把任意字节认定为成功回执。

入口：接口引擎取得经过权限校验的设备配置。
底层：V8.Tcp.SendAndReceive 完成一次有界网络交互。
协议层：校验完整报文、序号、命令和校验值。
业务层：根据设备确认与持久状态推进任务。

AI 开发的分工｜ 让 AI 生成接口引擎编排时，先给它真实返回字段和设备协议。缺少协议时，输出“待确认”比发明一个成功条件更可靠。

✦ 03 / Timeout 也可能带着数据回来

接收循环受到 ReceiveTimeout 的时间约束。超时发生时，如果还没有收到数据，就进入失败路径；如果已有数据，则保留已经读到的部分，把结束原因设为 Timeout。外层随后组装返回数据。

var r = V8.Tcp.SendAndReceive({
  Host: trustedDevice.Host, Port: trustedDevice.Port,
  Hex: protocolCommandHex,
  ReceiveTimeout: 3, MaxReceiveBytes: 4096
});
// trustedDevice 与命令必须来自可信配置及协议编排。

示例中的变量不是平台内置对象。Host 和 Port 不能直接透传外部 V8.Param；protocolCommandHex 也必须由业务允许的命令规则构造。参数写对只解决调用方式，不替代设备协议和访问权限。

别把超时改名｜ 收到部分字节后超时，应继续保留 Timeout 这个事实。把它统一包装成“设备已完成”，会让后续排障丢失最有价值的信息。

✦ 04 / Truncated=false 的否定范围很小

当前源码用 ReceiveEndReason 是否等于 MaxReceiveBytes 来计算 Truncated。因此 false 只排除了“本次因为达到接收上限而结束”这一种情况，并不证明响应是完整的一帧。

Timeout + false：可能只是收到前缀，剩余字节没有及时到达。
RemoteClosed + false：只说明对端关闭连接，是否完整还要看协议。
MaxReceiveBytes + true：已经达到本次接收上限，不能直接当完整响应解析。

三个返回组合的含义，不能从 Truncated 反推业务成功

三个返回组合的含义，不能从 Truncated 反推业务成功

一个常见的逻辑跳步｜ 没有被容量上限截断，不等于没有被时间边界截短。字段名读起来像完整性判断，实际含义仍应由源码和协议共同确定。

✦ 05 / 三组回环结果把边界固定下来

验证程序直接编译当前 V8Tcp.cs，并仅监听本机随机端口。第一组发送 06 后保持连接，接收超时；第二组发送 16 字节但把接收上限设为 4；第三组发送 06 后关闭连接。三组断言均通过。

部分响应超时：Code=1，Hex=06，ReceiveEndReason=Timeout，Truncated=false。
达到上限：Code=1，Hex=00010203，ReceiveEndReason=MaxReceiveBytes，Truncated=true。
远端关闭：Code=1，Hex=06，ReceiveEndReason=RemoteClosed，Truncated=false。

当前源码独立回环验证：3/3 行为断言通过，非实物设备验收

当前源码独立回环验证：3/3 行为断言通过，非实物设备验收

中央测试项目最初因正在运行的 API 锁定输出文件而未完成，因此本文没有把那次构建当成测试通过。随后使用独立临时输出完成上述三组验证，未停止共享 API 服务。这个范围需要和“全量测试通过”明确区分。

✦ 06 / 给 AI 一个不会过度承诺的判断顺序

设备协议各不相同，本文不虚构一套通用 ACK 校验器。可复用的是判断顺序：先确认调用结果，再确认报文边界，最后才把响应关联到当前业务命令。

if (r.Code !== 1) return r;
var d = r.Data;
if (d.Truncated || d.ReceiveEndReason === "Timeout") {
  return { Code: 0, Msg: "响应待确认，请查询原任务状态" };
}
// 仍需按具体设备协议验证长度、校验值、命令与序号。

上面是保守示意，不能直接覆盖所有协议。有的协议允许持续连接，有的以长度或结束符定界，有的只有单字节确认。是否把 Timeout 判为待确认，必须根据完整报文是否已经得到证明来决定。

事务还要再看一步｜ 接口引擎返回 Code≠1 会回滚共享数据库事务，但已经发送到外部设备的字节不会随之撤回。不能把数据库回滚理解成设备动作撤销。