一项能力能否长期维护，不取决于演示是否成功，而取决于团队能否解释每个状态、每次重试和每一份残留数据。 应用 goodput 排除协议头、重传和未确认缓冲，更接近用户进度。小文件主要受握手与首块影响，应与稳态大文件分开。
可观测性应回答故障发生在哪个阶段、影响多少会话和是否仍在扩大。事件字段使用白名单与低基数维度，用户内容、密钥和完整网络身份不进入遥测。
设计时必须回答的问题
落地时要把关键选择变成稳定契约：输入如何校验、状态由谁推进、资源何时释放、旧版本如何降级。只有这样，后续优化才不会改变原有语义。
- 每秒计算 ACK 字节差并写入指数桶，首 3 秒标记 warmup；标签仅含路径、大小档、浏览器大版和结果，不含文件名。
- 为状态写出唯一所有者、版本号和终态；任何回调只能修改自己创建的版本。
- 上线参数必须有保守默认值、服务端上限和灰度开关，不能把浏览器传来的数字直接当作资源预算。
“文件吞吐直方图：区分应用 Goodput、线路码率和小文件偏差”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
边界情况不是附加项
不要把异常路径理解成弹一次提示。它还包括在途工作如何停、对端如何获知、残留数据如何处置，以及下一次操作是否会继承旧状态。
- 完成时用 size/duration 会把暂停和用户等待混入网络吞吐；只记录成功大文件则掩盖低速用户更常取消的幸存者偏差。
- 失败被压成一个布尔值，调用方无法区分可重试、需用户介入与永久拒绝，最终形成无限循环。
- 指标标签直接包含用户或任务标识，既制造高基数成本，也让诊断数据泄露不必要的身份信息。
用证据确认它真的可用
验证需要先写预期状态轨迹，再执行故障注入。每个阶段同时核对用户可见结果、两端协议状态、持久记录和资源计数，才能证明闭环成立。
- 以已知整形速度传输 1 KB、1 MB、1 GB 并注入暂停、重传和取消，验证直方图能区分启动、稳态和失败样本。
- 用乱序、重复和延迟消息驱动状态机，确认旧版本被丢弃且显式停止不会被自动恢复覆盖。
- 分别覆盖直连、中转、弱网、后台标签页和移动端，报告不能只给平均值或一次成功截图。
可以上线的标准是：用户知道当前发生了什么，系统在异常后能停止或恢复，资源不会无界增长，运维也能从最小必要证据定位阶段。