好的实现不会依赖用户反复刷新碰运气，而会让每个阶段有明确输入、输出、超时和终态。 单一偏移量只适合严格顺序且前缀连续的传输。并行、乱序或部分可靠通道会形成多个已完成岛屿；如果只保存百分比或最高偏移，刷新后可能跳过中间缺口。
文件传输要同时对账发送偏移、接收落盘、分块校验和双方终态。进度条到达百分之百，只能说明字节进入队列，不能证明文件完整可用。
先定义系统契约
先从数据和协议能保证的事实出发，再决定界面承诺。下面的规则都应有明确所有者、边界值和兼容策略，不能只存在于某次代码评审的口头共识里。
- 接收端只在块可靠落盘后把区间并入 manifest，并以事务保存两者关系。
- 重连时发送已收区间的规范化压缩表示，由发送端计算缺口并限批补发。
- 任务版本、文件摘要和块大小必须匹配，不能把旧 manifest 套到新选择的文件。
真正的断点续传保存的是可证明的已完成集合，而不是一个好看的进度数字；manifest、块存储和最终摘要必须形成一条可恢复证据链。
哪些情况会破坏契约
最值得优先排查的是会静默留下错误事实的故障：界面看似恢复，底层队列、权限或计数却已分叉。这类问题通常在下一次动作才暴露。
- 区间相邻合并有一位偏差，导致最后一个字节被重复或永久漏掉。
- manifest 先写成功而块事务失败，刷新后系统把不存在的数据报告为已收到。
- 缺口列表过大直接放进一条信令消息，弱网重连时再次超过消息上限。
如何逐条验证契约
验证时同时观察两端状态、持久化记录和可观测指标。单看某个按钮或一次接口响应，无法证明整个闭环成立。
- 随机生成重叠、相邻和逆序区间，用性质测试验证规范化结果与原集合等价。
- 在每次块写入与 manifest 提交之间强制崩溃，重启后不得跳过未落盘块。
- 制造上万个离散缺口，验证分页交换、补发公平性和最终摘要。
最终结果应同时满足正确性、可恢复性和可解释性。任何一项只能依赖刷新页面或工程师猜测，都说明协议闭环仍不完整。