B07 BLE 文件传输与日志文件

前置阅读：《B04 BLE 录音协议接口与命令体系》《B05 BLE 传输控制》《B06 BLE 事件处理与 CRC 组帧》前几篇讨论的是实时音频和控制命令，本篇讨论两类"离线数据"如何通过近场链路离开设备：一类是用户最关心的录音文件，一类是工程师最关心的诊断日志。它们共享同一套"命令触发、独立线程、按块发送、严格校验文件名"的文件导出设施，却服务于完全不同的对象和场景。

一、模块的由来与发展历程

1.1 当设备没有可靠网络时，文件怎么出来

实时上云是理想路径，但真实使用中设备常常处于没有配网、网络质量差或云端不可用的状态。此时录音被保存在本地闪存里（见 B02 的本地兜底段），用户仍然需要把这些录音取出来。近场蓝牙因此承担了"离线文件出口"的角色：手机直连设备，列出本地有哪些录音，逐个下载，必要时删除。这一功能在产品早期甚至是主通道——在 Wi-Fi 上云尚未稳定的阶段，蓝牙导出是用户拿回录音的唯一方式；即便在云能力成熟之后，它依然是弱网与售后场景下不可替代的兜底通道。文件传输模块就是在这种"从唯一通道到兜底通道"的演进中沉淀下来的。

1.2 为什么日志也要能近场取回

随着设备进入真实用户手中，另一个需求浮现：现场出了问题，工程师需要设备日志来定位，但设备不在实验室、没有调试串口、也未必能联网上传。于是日志文件也被纳入近场导出能力——手机连蓝牙，把设备闪存里保存的运行日志拉出来，回传给售后。日志文件与录音文件在数据形态上高度相似：都是闪存上的普通文件、都要列举、按块读取、走同一条无线通道发送。工程团队没有为日志另造一套传输机制，而是让日志复用录音文件的导出框架，只在目录、文件名规则、块大小上做区分。这种复用让一套经过实战检验的可靠传输同时服务了用户资产导出和设备诊断两类需求。

1.3 从阻塞回调到独立工作线程

早期文件操作曾尝试直接在蓝牙写回调或命令处理里完成，但很快暴露问题：扫描目录、打开文件、按块读闪存都是毫秒级甚至更慢的操作，放在蓝牙上下文里会卡住后续包接收，导致传输时断时续。团队随后把文件相关操作彻底从命令处理中剥离，为列举、读数据、删除分别建立独立线程，命令处理只负责唤醒对应线程。这一改造把"快命令、慢文件"清晰分层，是文件传输模块走向稳定的关键一步。为了让这些线程既不占用宝贵的常规内存、又拥有足够的栈深度，它们的栈被特别放置在不初始化内存段，块大小和栈深度也按三类操作的实际需要分别调优。

1.4 从单一蓝牙到蓝牙加 Wi-Fi 双通道

当本地文件较大、蓝牙带宽成为瓶颈时，工程又引入了 Wi-Fi 透传通道（见 B08）作为高速补充：文件和日志的数据面可以切到吞吐高得多的局域网上传输，控制面仍可由蓝牙协调。文件传输模块因此抽象出"按块取数据、走某条通道发送"的结构，蓝牙块和 Wi-Fi 块使用不同大小的发送缓冲——蓝牙约九百多到一千字节以匹配协商 MTU，Wi-Fi 则用一万二千字节左右的大块以摊薄协议开销。日志通道在当前版本默认仍只走蓝牙（Wi-Fi 传日志的编译开关被关闭），这也体现了"按实际价值决定是否启用高速通道"的务实取舍。

1.5 文件导出的三次范式更替

把本模块的历史按"谁掌握节奏"来分期，可以看到三次清晰的范式更替，每次更替都由一次具体的失败推动。第一期是"命令驱动逐块"：手机发一条"给我偏移X的块"，设备读一块回一块，节奏完全由请求方掌握——实现简单，但每块的往返开销让有效吞吐只有链路能力的一小部分，几MB的文件导出以十分钟计。第二期是"设备连续推送加偏移标注"：手机只发一次"从偏移X开始"，设备连续读发、每帧自带偏移，吞吐翻了几倍——但连续推送在链路抖动时会冲垮接收方，于是又补上了速度档位与水位退避（B05篇的流控思想在文件面的投影）。第三期是"通道抽象"：蓝牙与Wi-Fi的数据面统一为"块加偏移"的形态，通道切换（11.4节的教训）成为新的一等公民问题。三次更替的共同方向是：设备从"被动应答的存储"演化成"主动管理节奏的发送方"，可靠性问题的重心也从"能不能传"演进为"节奏与并发"。

范式的更替史对后来者的价值在于提醒：当前形态不是理所当然的。逐块应答模式今天看来低效，但它曾是保证"每块都确认"的最稳妥选择；连续推送的高吞吐是靠速度档位与接收方水位兜底才敢上的。评估任何一次"性能优化"时，都应当回看它砍掉的机制当年防的是什么——被砍的护栏若是真的过时了，砍掉是进步；若只是因为没出过事而被遗忘，砍掉就是欠账。这份历史清单与B03篇1.8节的三阶段演化、B05篇1.7节的参数觉醒史构成同一类资产：模块的记忆，就是模块的免疫力。

1.6 与USB导出的此消彼长

本模块的形态还有一个来自兄弟通道的塑形力：USB。早期产品形态里，用户导出大文件的主力是USB大容量存储——拔下设备插上电脑，文件系统直读，速度是无线通道的百倍。USB的存在让蓝牙导出长期只服务"边走边导"的轻量场景，参数（块大小、线程栈）都按小文件调优。后来产品去掉了USB接口（无线化与防水的产品诉求），蓝牙导出一夜之间从配角变成唯一近场出口，几MB的会议录音全部压到它身上——原有的参数立刻全面吃紧，才有了后来的双通道演进与线程栈重配。一次产品形态决策（去USB口）对软件架构的传导，前后花了两代固件才消化完。

这段此消彼长的历史留下两条可迁移的判断。其一：通道的"主力与兜底"地位会随产品形态翻转，软件层为通道做的所有假设（文件大小分布、使用频率、用户耐心）都要标注"当前产品形态下的假设"——产品形态一动，假设清单要全部重审。其二：被去掉的通道要留下"继承者清单"——USB原有的用户（大文件导出重度用户）与场景（电脑端整理）迁到哪里、谁接住他们的需求，这原本是产品决策的一部分，软件架构的演进计划（双通道、Wi-Fi透传）实际上就是这份继承者清单的执行记录。通道的兴替不是纯技术事件，把它放进产品史里看，参数的每次重配才显得顺理成章。

1.7 导出能力的产品生命周期视角

把本模块六年多的演进串起来看，会发现它对产品生命周期的三个阶段各有不同的"首要身份"，这个视角有助于理解为什么同一个模块在不同时期收到完全相反的提案。导入期（产品刚上市），导出的首要身份是"信任建立工具"——早期用户对"录音存在一个没有屏幕的小设备上"天然不安，"马上能导出到手机"是打消不安的最直接证据，这个阶段任何降低导出可用性的改动（哪怕为了省内存）都是战略错误。成长期，身份切换为"售后杠杆"——装机量上来后，日志导出把问题定位从返厂拉到远程（2.5节），此时投资方向是日志体系的深度（分级、审计、脱敏）。成熟期，身份又切换为"通道组合的一极"——上云稳定后，近场导出聚焦弱网兜底与大数据搬运（10.4节），此时最常见的错误提案是"近场导出已过时、砍掉"，每次这类提案的回应都靠同一组数字：弱网用户占比、大文件近场搬运频率、售后取日志的次数——数字在账本上（十四），立场就有出处。

生命周期视角的真正价值是解释"为什么这个模块历次裁撤提案全部被否"：不是它政治地位高，是它在每个阶段的身份恰好都踩在当期产品风险的最大值上。导入期砍它砍的是信任，成长期砍它砍的是售后成本曲线，成熟期砍它砍的是弱网用户的最后兜底。一个模块能否长期存活，取决于它能否持续回答"这个阶段谁最需要我"——文件传输层的答案每次都不一样，但每次都有答案，这就是它六年不倒的机制，比任何"战略重要性"的定性论述都更硬。

图示：三次范式更替与通道兴替（本章新增）

功能文字流程图（模块视角）——导出通道的权力交接史：

[范式一:命令线程顺手导出]      [范式二:独立文件线程]      [范式三:三线程+双通道]
┌──────────────┐          ┌──────────────┐        ┌──────────────┐
│ 大导出阻塞    │          │ 一线程干三类活  │        │ 列举/数据/删除 │
│ 全部命令      │──事故──→ │ 栈深互相拖累   │──事故──→ │ 各有独立栈与   │
│ (队列冻结)    │          │ (栈溢出)      │        │ noinit段,蓝牙  │
└──────────────┘          └──────────────┘        │ +Wi-Fi双通道   │
                                                  └──────────────┘
  USB时代:蓝牙导出只当配角(小文件轻量场景)
  去USB后:蓝牙一夜成为唯一出口 → 参数全面吃紧 → 假设清单重审(1.6节)
  推论:通道的主力/兜底地位随产品形态翻转,所有参数都标"当前形态假设"

工程注解： 这张演进图把 1.5/1.6 节的历史压成三格——每格右边的箭头写的不是"时间"而是"事故"：范式每次更替都是被具体翻车推的（队列冻结、栈溢出），不是设计者的先见；图尾推论是给未来维护者的预警：产品形态一动，这张图上的假设清单要全部重审一遍。

二、业务定位与计费关系

2.1 用户资产的近场出口

录音文件列表与下载直接面对用户资产。列出文件时，设备返回每个文件的名称、大小、时间等信息，这些信息与 B02 的清单保持一致，让用户在 App 上看到的就是设备真实存在的录音。需要强调的是，文件列表只呈现"有哪些文件、各多大"，计费判断在云端完成：本地兜底段在上云后按云端确认计费，本地文件本身不携带"这条要扣多少额度"的裁决。文件导出模块因此是一个中立的数据通道，它忠实地搬运用户已产生的录音，不因导出动作改变计费状态。真正涉及计费的删除或云端确认由其他模块按既定规则处理。

2.2 删除是敏感操作

删除文件在三类文件操作中风险最高：一旦删错，用户的原始录音可能永久丢失。因此删除命令同样走独立线程、同样要求文件名通过严格合法性校验，且业务层通常会把"设备端删除"限定在已经安全上云、或用户明确删除的文件上。对仅存在于本地、尚未上云的兜底段，产品策略往往倾向于谨慎保留或先导出，避免用户在不知情的情况下丢失唯一一份录音。文件传输模块在技术上提供删除能力，但删除的时机与前置条件由上层业务规则把关，这种"机制与策略分离"让底层保持简单、把关键的用户数据保护决策放在更靠近业务的地方。

2.3 日志的诊断价值与隐私边界

日志不计费、不直接产生用户价值，却是售后与研发的生命线。设备把运行轨迹写入闪存日志（按日期命名），出问题时通过近场导出。日志能还原断连、卡顿、异常重启等现场，其价值在无法远程复现的问题上尤为突出。但日志可能包含时间、网络标识、操作行为等敏感信息，因此日志导出通常要求设备已通过绑定鉴权、且日志内容应避免明文写入用户音频或敏感凭据。把日志访问限制在已绑定的可信手机、并对日志内容做必要脱敏，是在"可诊断"与"隐私保护"之间必须守好的边界。

2.4 传输完整性与计费可信的间接耦合

文件导出不直接参与计费，但它是计费可信链条上的一个间接环节，这层间接关系值得写明。场景是这样的：一场会议的云端部分因断网退回了本地（B02篇的本地兜底段），这份数据要在后续经导出或上云进入云端归档时，才按云端确认计费。导出通道此刻搬运的是"计费凭据的原始字节"——清单（B02篇）记载着这场会话哪几段原本属于云端，导出时清单与音频必须一起完整到达，凭据链才不断。因此本模块的两条纪律有计费侧的分量：其一，清单文件被后缀白名单排除在导出与删除之外（3.5节），保护了凭据不被用户侧误动——但上云流程要读清单时走的是系统内部路径，不受白名单限制，这条"外紧内通"的边界必须两侧都成立；其二，半截文件的"不完整即不可用"判定（9.2节）保证凭据永远以完整形态进入计费流程，杜绝"半份清单配整份音频"或反过来的错配。

这层耦合还定义了导出失败时的业务语义：导出中断不会让设备侧的计费状态发生任何变化——文件还在、清单还在、段信息原样，用户随时可以重试或换通道。导出是只读出口这一设计选择，让它天然成为计费链路上的"无副作用旁观者"；但凡未来有人想给导出加动作（比如"导出后自动标记已备份"），就要先回到计费篇重新过一遍"谁有权改计费状态"的裁决——本模块的全部安全感，正来自它对自己权限的克制。

2.5 售后流程中的导出角色：SLA视角

从售后流程的视角看，日志导出是整个服务体系的服务水平基座之一。一次典型售后事件的时长由三段组成：用户反馈（不可控）、远程诊断（依赖日志可得性）、修复闭环（固件升级或换机）。第二段里，"日志能不能拿到"直接决定事件是当天闭环还是两周拉锯——远程上传日志依赖设备联网，而恰恰是联网异常类问题最多，这时近场导出就是唯一通路。本模块因此要为一段看不见的指标负责：从售后决定要日志到日志到手的九十五分位时长。当前这个数字按"绑定手机在场、蓝牙导出单日日志"计约为分钟级，Wi-Fi透传可再压缩——售后SLA的预算表里有它的一个格子。

SLA视角倒逼出两条工程任务。其一，日志导出路径的健壮性要按"问题设备的日志"最坏情形设计——正在出问题的设备往往正是蓝牙最不稳、存储最可能异常的那台（11.3节的满盘边界正是售后高频现场），导出路径必须在这些恶劣条件下仍然能完成使命，否则诊断工具本身在战场上趴窝。其二，导出的操作复杂度要计入SLA——用户配合一次日志导出的每一步（连蓝牙、找菜单、点导出、回传）都有流失率，App侧的流程每多一步，SLA实测值就涨一截。把导出做成"点一下全后台"，与把它做稳同样重要。

图示：数据主权的保护等级分界（本章新增）

功能文字流程图（模块视角）——同一目录下两套完全不同的待遇：

┌─────────────── 录音文件(用户资产) ───────────────┐
│ 删除:敏感操作,层层把关(已上云确认/用户显式确认)      │
│ 导出:必须三验一签(9.6节)                            │
│ 轮转:不允许(删除权原则上在用户)                     │
└────────────────────────────────────────────────┘
┌─────────────── 日志文件(设备内部数据) ─────────────┐
│ 删除:系统自主,无需确认                             │
│ 导出:审计记录(9.7节),无需完整性仪式                 │
│ 轮转:按预算自主删老(6.6节)                          │
└────────────────────────────────────────────────┘
   同一套列举/校验/分块/删除框架,保护等级跟着数据主权走
   文件系统里没有"一视同仁",只有"按主权分级"

工程注解： 这张分界图是 2.2 节与 6.6 节的合图——理解本层策略问题的钥匙只有一句："谁的数据、谁有权动它"；把删除权、导出仪式、轮转自由三项按主权分档后，大量"该不该保护"的争论直接出清：保护等级不是技术参数，是产权设计。

三、架构设计

3.1 命令触发、线程干活的分层

文件传输采用典型的"命令触发、线程干活"结构。蓝牙命令处理在收到列举、取数据、删除等命令后，不直接执行文件 IO，而是把请求参数记录下来并唤醒对应的专用线程：列举线程扫描目录、数据线程按块读文件并发送、删除线程执行删除并回结果。三个线程相互独立，各自有独立的栈和生命周期，避免一种操作的栈占用或阻塞影响另一种。命令处理快速返回，慢操作全部异步完成，这与 B06 强调的"回调里不准慢"一脉相承。

3.2 三个独立线程与差异化栈深

录音文件侧的三个线程栈深度按工作内容差异化配置：列举和删除线程栈较大（约 4K），因为目录扫描和删除路径会嵌套调用文件系统、内存分配等较深的函数链；数据线程栈相对小（约 2K），因为它主要是"读一块、发一块"的扁平循环。日志文件侧同样有三个线程，但删除线程栈更小（约 1.5K），反映其删除路径更浅。这些栈数组都以特定对齐方式放在不初始化内存段——该段内存上电时不做清零初始化，可用于放置体积较大、又不需要零初值语义的栈，从而避免这些栈挤占需要保留或需要初始化的内存区域，是嵌入式内存精打细算的典型手法。

3.3 发送缓冲与块大小

数据线程使用一块按四字节对齐的静态发送缓冲，蓝牙场景大小约 960 字节（Opus 录音）或 1024 字节（其他格式），Wi-Fi 场景则约为三个 4040 字节、合计一万二千字节。蓝牙块大小特意小于典型协商 MTU，确保"帧头加一块数据"能够在单个或少量链路层包中发完，避免应用块被过度拆分；Wi-Fi 块则尽量大，以摊薄每条 TCP 报文和每次系统调用的固定开销。缓冲四字节对齐是为了满足某些 DMA 或协议栈接口对对齐的要求，也让数据拷贝更规整。

3.4 速度档位与流控配合

文件发送循环维护一个连接速度的档位概念（快、忙、空闲等），用于根据当前链路拥塞情况调节发送节奏。这一信息与 B05 的 RSSI、发送失败熔断和 B08 的发送缓冲区水位配合：链路畅通时尽快发，拥塞时主动退避，避免在已经拥塞的链路上继续灌满数据导致更多丢失。发送速率还留有调试开关，可在日志中打印每秒发出的字节数，帮助评估不同距离、机型下的真实吞吐，为块大小和发送间隔的调优提供数据支撑。

3.5 文件名合法性：先验白名单

无论列举、读取还是删除，来自手机的文件名都被视为不可信输入，必须先通过一个严格的白名单校验函数：长度必须精确等于约定值、后缀必须是录音格式或日志格式、前缀必须是系统定义的几种模式之一（录音区分速记、通话、纯录音、底座等模式；日志固定为运行日志前缀）、中间部分必须全部是数字（时间戳或日期）。只有全部通过才允许对该文件操作。这一设计从根本上杜绝了路径穿越（如带目录跳转符的名字）、通配符、以及操作到清单文件或其他系统文件的可能，是文件传输安全的核心闸门。

3.6 白名单的版本演化与"数字集"的边界细节

白名单函数看似一成不变，其实经历了两次必要演化，每次都暴露一个设计细节。第一次是序号后缀问题：文件名冲突消歧时在时间戳后追加了两位序号（11.2节的案例），白名单的"中间纯数字"约束恰好能容纳它——因为序号也是数字，且长度校验从"精确等于"改为"等于两种合法长度之一"。这次修改的教训是：白名单的每条约束都要预先回答"命名规则将来可能怎么变"，约束写得过死（精确一种长度）则命名规则被迫迁就安全，写得过松（范围长度）则安全被迫迁就命名——两者应当一起设计、一起评审，它们本来就是同一份契约的两面。第二次演化是跨链路需求：Wi-Fi透传（B08）复用同一白名单，但其文件名约定多了通道标志位——最终以"前缀集合扩容"解决，白名单函数参数化前缀表而结构不变。白名单的稳定层（长度、数字、后缀）与可变层（前缀集合）自此分明，可变层的变更只需改表，这为后续新增导出对象铺平了路（10.2节统一导出器的雏形已经在这次修改里出现）。

还有一条边界细节值得单独立案：数字校验用的是"字符是否为十进制数字"，而非"字符串能否解析为时间戳"。两者的区别在防御纵深——前者是结构校验（字符集合对），后者是语义校验（值域合理）。结构校验防路径穿越足够，语义校验防的是另一类攻击（如"时间戳全零"去试探系统文件）。本层选择只做结构校验、语义留给上层（文件管理按时间戳范围过滤），理由是校验函数应当"快且无依赖"——语义校验需要知道当前时间、合法时间范围，这些是会变的策略参数，放进闸门里会让闸门变重。分层又一次显现：闸门管安全，策略管语义，两层各自轻快。

3.7 线程栈的noinit段：从技巧到制度

三个线程栈放在不初始化内存段，最初是一个精打细算的技巧（5.3节），后来沉淀为一条内存布局制度，制度化的过程值得记录。第一阶段是单点技巧：数据线程栈2KB放noinit，省下2KB的初始化时间与清零开销。第二阶段是排查事故：一次调试发现某线程栈溢出后"又自己好了"——noinit段的栈溢出不破坏初始化数据（受害者是上次遗留的垃圾数据），故障时隐时现，比普通栈溢出更难抓。团队由此建立两条配套纪律：noinit栈一律配栈高水位统计与栈涂销检查（灌图样、事后查涂改边界），让"曾经溢出"留下痕迹；栈尺寸调整必须附最坏调用链的重测（B03篇案例五的教训在文件侧同样成立）。第三阶段是布局制度：链接脚本里把所有noinit栈集中成段并注释"此段内容跨复位不可信，仅限无初值依赖的缓冲与栈"，新栈想进段必须按纪律登记——noinit从"能省则省的技巧"升格为"有准入门槛的专用内存区"。

制度化的普适结论：嵌入式里每个"聪明的技巧"都值得走一遍这三阶段——单点试用、事故补课、门槛制度化。跳过第二阶段的技巧会在几年后以最难排查的形态索债；跳过第三阶段的技巧会泛滥（什么都往noinit塞），最终连最初的收益也被稀释。本模块的noinit段如今是全工程内存纪律的样板间，而它的第一条纪律恰恰是来自那场"自己好了"的事故——每个制度背后都应该能讲出一个具体的故事，讲不出故事的制度通常是被抄来的，抄来的制度没人真信。

图示：三线程架构与 noinit 栈总图（本章新增）

功能文字流程图（模块视角）——命令侧只派单，干活各有房：

手机命令(列举/导出/删除)
   │
   ▼
命令处理(快速派单+启动保活锁) ─── 慢活全部转包 ──┐
                                             │
   ┌─────────────────┬──────────────────┬───┴────────┐
   ▼                 ▼                  ▼            │
┌──────────┐   ┌──────────┐       ┌──────────┐        │
│ 列举线程   │   │ 数据线程   │       │ 删除线程   │        │
│ 栈~5KB    │   │ 栈~4KB    │       │ 栈~3KB    │        │
│ (深调用链: │   │ (扁平循环: │       │ (互斥上云) │        │
│  目录扫描) │   │  读→发→等) │       │           │        │
└──────────┘   └──────────┘       └──────────┘        │
   └── 栈体全部放在noinit段:不占初始化内存分配器 ───────┘
       调用链深度表+故障域表 差异大 → 分;差异小再谈省栈(5.2节)

程序文字流程图（执行视角）——数据线程的循环骨架（4.4节）：

循环:
  ①读文件块(960B蓝牙/12KB Wi-Fi,四字节对齐)
  ②CRC组帧(B06帧格式) → 按档位节奏发送
  ③应答/确认 → 包号+1 → 检查停止标志(一标志一出口,5.8节)
  ④末块? → 发结束标志+总大小 → 释放保活锁 → 收尾
  每步失败 → 同一收尾路径(与成功路径同设计同测试)

工程注解： 总图把 3.2/3.7 节的三线程与 noinit 段画成"各有各的房"——栈深按调用链实测定（差异化），放 noinit 段让内存分配器完全不知道它们存在；骨架图里最值得标注的是③：三种停止来源（取消/让位/系统事件）都只是置位者，退出权单点，这是本章事故库换回来的最贵的纪律。

四、代码实现

4.1 独立线程栈与发送缓冲

/* 列举/删除调用链较深，给较大栈；数据线程为扁平读写循环，栈较小 */
static char __aligned(ARCH_STACK_PTR_ALIGN) __in_section_unique(noinit)
    vm_list_stack[4096];
static char __aligned(ARCH_STACK_PTR_ALIGN) __in_section_unique(noinit)
    vm_data_stack[2048];
static char __aligned(ARCH_STACK_PTR_ALIGN) __in_section_unique(noinit)
    vm_del_stack[4096];

/* 蓝牙块略小于典型 MTU；四字节对齐便于协议栈/DMA 使用 */
#define VM_BLE_CHUNK   960
static uint8_t __aligned(4) g_send_buf[VM_BLE_CHUNK];

/* Wi-Fi 走大块，摊薄报文与系统调用开销 */
#define VM_WIFI_CHUNK  (3 * 4040)
static uint8_t __aligned(4) g_wifi_buf[VM_WIFI_CHUNK];

4.2 录音文件名白名单校验

/**
 * @brief 校验文件名是否为本机录音文件（白名单，拒绝一切非约定名字）
 * 形如 <模式前缀><14 位时间数字>.opus，长度固定
 * @note 不通过则拒绝列举/读取/删除，防止路径穿越与误操作系统文件
 */
static bool vm_name_is_safe(const char *name)
{
    if (strlen(name) != VM_NAME_LEN)          /* 长度必须精确 */
        return false;
    if (strcmp(&name[VM_SUFFIX_POS], VM_SUFFIX) != 0)
        return false;                          /* 必须是录音后缀，顺带排除清单等 */
    if (!vm_prefix_matches(name))              /* 必须是受认可的几种模式前缀 */
        return false;
    for (int i = VM_PREFIX_LEN; i < VM_SUFFIX_POS; ++i)
        if (!isdigit((unsigned char)name[i]))  /* 中间必须全为数字时间戳 */
            return false;
    return true;
}

4.3 列举线程骨架

static void vm_list_loop(void *a, void *b, void *c)
{
    struct fs_dir_t *dir = app_mem_malloc(sizeof(*dir));
    struct fs_dirent *ent = app_mem_malloc(sizeof(*ent));
    uint8_t reply[1] = {0};

    sys_wakelock_lock(STANDBY_S1);            /* 导出期间禁止进入低功耗待机 */

    if (!dir || !ent || fs_opendir(dir, VM_DIR) < 0) {
        reply[0] = 0x01;                       /* 失败码随列举应答回传 */
        lk_build_and_reply(LK_CMD_FILE_LIST, reply, 1);
        goto out;
    }
    while (fs_readdir(dir, ent) == 0 && ent->name[0]) {
        if (!vm_name_is_safe(ent->name))      /* 只导出合法录音 */
            continue;
        /* 汇总名称/大小，攒满一帧或结束时发送 */
    }
    fs_closedir(dir);
out:
    app_mem_free(dir); app_mem_free(ent);
    sys_wakelock_unlock(STANDBY_S1);
}

4.4 数据线程的按块读发循环

打开目标文件（文件名已过白名单）
offset = 请求起始偏移（支持断点续传）
while 未到文件尾 且 未收到停止:
    n = read(fd, g_send_buf, VM_BLE_CHUNK)
    若 link 拥塞 -> 按速度档位退避等待
    lk_build_and_reply(FILE_DATA, 携带 offset 的块)
    offset += n
发送"文件结束"标志；释放 wakelock

4.5 日志文件的区分

/* 运行日志：前缀 devlog + 日期，后缀 .log，位于隐藏日志目录 */
#define LOG_PREFIX   "devlog"
#define LOG_SUFFIX   ".log"
#define LOG_NAME_LEN 18            /* 如 devlog20260101.log */
#define LOG_DIR      "/.log"
/* 同样走"白名单校验 + 独立线程 + 按块发送"，块大小约 1KB */

图示：白名单的稳定层与可变层（本章新增）

功能文字流程图（模块视角）——身份不变量的极端化实现：

来自手机的文件名(不可信输入!)
   │
   ▼
┌─ 严格白名单(B07的"身份"不变量) ─────────────────┐
│ 稳定层(结构,冻结):                                 │
│   固定总长32B · 固定前缀8B · 中间12位纯数字 · .后缀  │
│ 可变层(内容,3.6节):                                │
│   前缀具体字符/数字含义 随命名特性扩展预留位          │
└──────────────────────────────────────────────────┘
   ├─ 结构不过 → 拒(路径穿越/通配/非法字符在结构层死亡)
   └─ 结构过 → 交文件系统(此时身份已可辩护)
   配套:设备侧生成文件名前自检(生成侧保证只产合法名)
        两端合起来 = "合法名字的闭包"(FAQ问五)

工程注解： 这张白名单图是全层安全的定海图——稳定层与可变层的切分让"安全"与"演进"不再打架：命名规则加特性动可变层，白名单的结构闸门十年不动；图尾的"闭包"注解是这一机制的最高形态：不仅闸门在验，出生端也在自检，非法名字从两头都被消灭。

五、关键机制深析

5.1 为什么必须先校验文件名再碰文件系统

文件名来自手机，是典型的不可信外部输入。如果直接把它拼进文件路径去打开、删除，恶意或有 bug 的 App 可以构造带目录跳转的名字访问录音目录之外的系统文件，或利用通配、特殊字符误删数据。白名单校验把"允许操作的文件"限定为一个极小的、可预测的集合：固定长度、固定后缀、固定几种前缀、中间纯数字。这样即便不做复杂的路径规范化，也能从结构上保证操作对象一定在录音目录里、一定是本设备自己生成的录音。顺带地，后缀校验还把清单文件（元信息）排除在导出与删除之外，避免用户或 App 直接操作内部账本文件。这种"用严格命名约定换安全"的做法，比"允许任意名字再想办法过滤"简单且可靠得多。

5.2 列举、读取、删除为何要三个线程

拆开三个线程首先是栈和阻塞隔离的需要：列举要遍历目录、可能嵌套较深；删除涉及文件系统删除和可能的空间回收；读取则是长时间持续循环。若共用一个线程或在命令上下文执行，一个大目录的列举可能阻塞读取、一次删除的抖动可能影响命令响应。三个线程各自有明确任务和独立栈，一次只处理一类操作，时序清晰、互不干扰。其次是职责与故障隔离：列举失败不应中断正在进行的下载，删除异常不应污染列举结果。差异化的栈深度则避免了"为最深的那个操作给所有线程配大栈"的内存浪费——在内存以 KB 计的设备上，每个线程省下的 2K 栈都有意义。

5.3 不初始化内存段放栈的用意

线程栈通常占用大块内存，且栈不需要任何初始值（运行时由函数调用自然使用）。把这些栈放入不初始化（noinit）段，意味着上电时引导程序不会逐字节清零它们。这样做有两个收益：一是缩短启动时对这块内存的初始化时间；二是把这些大块内存与需要零初始化或需要跨复位保留的内存区域分开管理，提升内存布局灵活性。配合显式的栈指针对齐，既满足架构对栈对齐的要求，又不牺牲安全性。使用这一手法的前提是清楚该段不保证初值——因此只用于确实不依赖初值的栈和缓冲，绝不能放需要从 0 开始的全局状态。

5.4 断点续传与偏移语义

文件下载在弱蓝牙环境下随时可能中断（手机来电、走出距离、链路抖动）。若每次都从头重传，大文件几乎无法成功导出。数据线程因此支持带起始偏移的读取请求：手机记录已成功收到的字节位置，中断后从该偏移重新请求，设备 seek 到对应位置继续读发。偏移与文件大小在数据帧里携带，手机据此拼回完整文件并判断是否到达结尾。偏移语义把"一次必须传完"的强假设放松为"可以分多次、可续传"，是大文件在不可靠近场链路上能够可靠导出的关键，也让 App 能实现进度显示和失败重试。

5.5 保活锁与导出期间的功耗取舍

列举、下载、删除期间设备持有一把待机锁，阻止系统进入低功耗待机。原因是文件传输可能持续数秒到数十秒，若中途设备进入深度待机，蓝牙可能被挂起、文件系统可能进入低功耗状态，导致传输中断或失败。持锁期间系统保持在足以维持蓝牙和闪存工作的状态，功耗高于待机，但这是用户主动发起导出时可接受的代价。操作结束（无论成功失败）必须释放锁，让设备恢复正常功耗策略。在失败返回路径上也要确保释放锁——代码在列举失败的退出分支同样释放，正是为了避免"出错后忘记解锁、设备永久无法休眠"的漏电缺陷。

5.6 块大小背后的带宽账

蓝牙块取约 960 字节而非更大，是因为单帧应用数据加上帧头后要能装进协商好的 ATT 载荷，过大要在应用层被协议栈再切分，过小则帧头占比上升、有效带宽下降。960 字节是在典型 MTU 下兼顾"少分片、高载荷率"的经验值。Wi-Fi 块取约 12KB，则是因为局域网 TCP 的单次发送成本主要来自每报文的协议栈处理和系统调用，块越大单位有效数据的固定开销越低。两条通道用不同块大小，本质上是在各自的 MTU 和每包成本约束下做最优解，而不是追求一个统一数字。配合速度档位和速率调试日志，这些值都应在真机不同工况下实测标定。

5.7 数据线程的节拍器：从毫秒间隔到档位自适应

数据线程的发送节奏管理经历了一次从固定到自适应的演进，值得作为"档位思想"的完整案例。最初的设计是一个固定的帧间延时（若干毫秒），思路是"宁可慢一点也别冲垮链路"——实测在近距离下白白损失三成吞吐，而远距离下固定延时又不够长、照样丢包。问题出在固定值假设了链路状态恒定，而链路状态恰恰是最大的变量。档位化改造后，线程只维护三态（畅通、正常、拥塞）与两个阈值：连续发送无失败计"畅通"，偶发失败回落"正常"，连续失败或水位告警进"拥塞"。每个档位绑定不同的帧间延时，档位切换带迟滞（连续N次才切换，B05篇7.5节的思想直接复用）。改造后近距吞吐回到链路上限、远距丢包率下降，两个工况同时改善——这是"把链路状态显式化"带来的典型双赢，也是档位思想（用离散档位逼近连续变量）在嵌入式里最常见的一次落地。

节拍器的实现里还有一条容易被忽略的细节：延时本身用的是什么时钟？数据线程的延时走的是工作队列的定时器而非忙等，线程在等待期间让出CPU——这让导出期间的CPU占用几乎全部集中在读闪存与组帧的瞬间，等待时段系统可以正常调度其他任务。曾有同事图省事用了忙等循环，一台设备在导出时按键响应明显变钝，就是导出线程把调度饿的。等待的实现方式（让出型对忙等型）是线程设计里"看不见的品质"，评审时值得专门问一句。

5.8 停止信号的三种来源与统一出口

数据线程在运行中可能收到三种停止请求：用户在App点了取消（停止传输命令）、用户点了另一个文件的导出（当前让位）、系统级事件（低电关机、固件升级前导）。三种来源的语义不同——取消要回"已取消"应答、让位要保留断点、系统事件要快速收敛——但出口必须统一：线程只有一个停止标志位与一个收尾路径，三种来源都只是置位者。曾有一版实现为三种来源各写了一段"专属停止逻辑"，三段代码各自维护"停止后的状态"，一次重构后三段逻辑的语义分叉了——取消的版本会复位偏移（下次从头传），让位的版本保留偏移，系统版本直接不收尾——三者交错调用时状态机彻底混乱。修复删掉了全部专属逻辑，回到"一标志一出口"，差异下沉为"置位时附带一个请求原因"，收尾路径按原因选择应答与保留策略。

这条纪律的通用表述：线程的退出权必须单点。多个来源可以请求退出，但"怎么退、退到哪"只允许有一份代码——任何为"特殊场景"另写的退出路径，都会在某个组合调用下与主路径分叉。这与B01篇"事件必排队、串行不重入"是同一族纪律：并发的入口可以有无数个，决策的出口永远只有一个。收尾路径是线程生命周期里最容易被写花的地方，把它做成"所有退出都经过的独木桥"，桥上的每一步（停读、关文件、发结束、释放锁）才可能被逐一审计。

5.9 读与发的重叠：单缓冲下的流水线账

数据线程的循环体是"读一块、发一块"：向文件系统发起读，把数据从闪存搬进发送缓冲，再走通道发出，等确认，然后下一块。这个朴素循环里藏着一笔常被忽略的流水线账：读与发是串行的——读的时候链路在闲，发的时候闪存在闲，两样最慢的资源永远只有一样在干活。按典型数字验算：蓝牙工况下读 960 字节占约一两毫秒（含文件系统调用），发送按链路速率占数十毫秒，读的占比很小，串行浪费可以忽略；但 Wi-Fi 工况下发送快了两个数量级，读的几毫秒开始占总时长的两三成——通道升级后，原来免费的串行浪费突然成了主要瓶颈。这就是"瓶颈随通道漂移"的典型形态：为 960 字节时代写出的循环，在 12KB 时代要重新验算。

解决重叠的经典答案是双缓冲（乒乓）：读进缓冲A的同时发缓冲B，两份960字节的内存换三成吞吐。工程在 Wi-Fi 通道上做过这个改造的评估，结论暂缓——原因是蓝牙通道上收益不成立（读占比太小），而Wi-Fi透传通道的发送路径（B08篇）本身已有自己的缓冲与流控层次，再叠加乒乓会把两层的缓冲账搅在一起。裁决记录在案：等Wi-Fi通道的实测数据显示"读占比超过一成半"再启动，触发条件写死，避免"顺手优化"的冲动型改造。这笔账的教育意义在于：流水线优化的前提是先把两段的耗时账算清楚——不算账就上双缓冲，常见结局是白花一份内存，买到一个谁也感知不到的百分点。

图示：偏移续传与节拍器（本章新增）

程序文字流程图（执行视角）——绝对偏移的三方语义：

手机:请求(文件名,偏移O)
   │
   ▼
设备:seek(O) → 读一块 → 回(块数据,本块序号)
   │
   ▼
手机:追加到本地文件O位置 → 下一次请求(O+块长)
   │
   ▼
末块语义:块内偏移为负一 → "这是最后一块"(显式结束,5.4节负一幽灵的解)
   │
   ▼
重连续传:心跳对账点(B05序号) → 两端从同一对账点继续
   规则:定位用绝对偏移不用相对块号 → 中断后任意位置恢复都简单

功能文字流程图（模块视角）——节拍器三档（5.7节）：

[畅通档] 连续无失败 ──帧间延时小→ 近距吞吐顶到链路上限
    │ 连续N次失败/水位告警(带迟滞)
    ▼
[正常档] 偶发失败回落 → 帧间延时中
    │ 连续M次失败
    ▼
[拥塞档] 连续失败 → 帧间延时大/暂停待恢复
    │ 连续K次成功(迟滞解除)
    ▼
[畅通档]...
 延时全部走定时器让出CPU(忙等=饿死别人,按键变钝事故的教训)

工程注解： 两张图合起来是"传输的三件套"——偏移管"在哪"、序号管"缺没缺"、节拍管"多快"；节拍器图特意画出"让出型等待"的注释：导出线程的等待走定时器，CPU 留给别人——这类"看不见的品质"（5.7 节）恰恰是图示最能表达的：箭头上的每个等待，都该标出"等待时谁在用 CPU"。

六、日志通道专题

6.1 运行日志的产生与存储

设备运行时各模块通过统一日志接口输出信息，日志系统可将内容先写入环形缓冲、再由落盘机制写入闪存上按日期命名的日志文件（形如 devlog 加日期加 .log），存放在隐藏的日志目录。按日期切分便于定位特定时间的问题，也让日志总量可被轮转控制，避免日志无限增长占满存储。日志记录的粒度覆盖连接事件、状态切换、错误码、关键流程节点，足以在没有串口的情况下还原大部分现场。近场导出让这些日志能在用户配合下被售后取回。

6.2 复用而非重造

日志导出与录音导出在机制上几乎一致：都是"列举目录、白名单校验文件名、按块读取、走通道发送、可删除"。因此日志侧也有列举、数据、删除三个独立线程和一块约 1KB 的发送缓冲，文件名校验只认固定的日志前缀、后缀、长度和中间日期数字。复用同一套机制意味着可靠传输、断点续传、保活锁、速度档位这些能力日志通道自动获得，也意味着任何对传输框架的改进两类导出同时受益。差异只体现在目录、命名规则、栈深度和是否启用 Wi-Fi 这些参数上。

6.3 为什么默认不开 Wi-Fi 传日志

录音文件大、对带宽敏感，值得在 Wi-Fi 可用时走高带宽通道；日志文件通常小得多（单个日志几十到几百 KB），用蓝牙导出耗时本就可接受，而启用 Wi-Fi 传日志要额外拉起网络、处理连接和功耗，复杂度与收益不成比例。因此日志走 Wi-Fi 的编译开关在当前版本默认关闭。这个决策体现了"不为低频低价值需求长期保留高复杂度路径"的克制——机制在代码中保留（开关可开），但默认配置选择最简单够用的方案。是否开启应由真实的日志体量和售后流程需求驱动，而不是因为技术上能做就默认打开。

6.4 日志导出的安全与脱敏

日志可能间接暴露用户行为和网络信息，因此导出同样限定在已绑定设备的可信手机。研发在写日志时应避免把用户音频内容、Wi-Fi 密码、绑定凭据等敏感数据明文落盘；对必要的标识可做截断或哈希。导出后日志在手机侧和回传链路上的处理也应纳入隐私管理。诊断能力与隐私保护并不矛盾，关键是把"日志里该写什么、谁能取、取走后怎么存"在开发规范里讲清楚，而不是无差别地记录一切、再无限制地开放导出。

6.5 日志分级的现场价值与成本

日志内容按诊断价值分级是本通道最重要的内部设计，分级直接决定"一次导出能解决多少问题"。当前的三级体系：错误级（错误码、异常分支、断连原因）永远落盘，量小而信息密度最高；关键流程级（状态切换、命令到达、传输起止）按模块开关落盘，覆盖"还原操作序列"的需要；调试级（逐帧流水、参数值）默认只在内部固件开启，量产版通过诊断命令临时打开。分级的成本纪律是：日志写入走环形缓冲加异步落盘，任何等级的日志都不允许阻塞调用方——为此日志接口的格式化放在落盘线程而非调用点，调用方只留一个指针加等级的入队动作。

分级的现场价值在一次典型客诉里体现得最清楚：用户反馈"设备每周总有一次莫名断连"，错误级日志立刻显示每次断连前的协议栈错误码集中为同一种超时——而关键流程级日志显示该超时总发生在同类的操作组合之后。两级日志合起来，一个原本"无法复现"的问题当天收敛到了可复现的触发条件。反例同样有教育意义：早期有一版日志没分级、全量落盘，闪存被日志吃掉三成空间且落盘线程频繁拖慢系统——日志系统自己成了性能问题，是被6.6节的容量预算制度管住的。日志的设计目标从来不是"记录一切"，是"让下一次导出的几分钟里，有最大概率命中要找的那几行"。

6.6 日志的容量预算与轮转策略

日志文件按日期切分（6.1节），但没有明说的另一半制度是容量预算：日志目录有总容量上限，逼近上限时最老的日期文件先删（与B02篇9.5节循环覆盖的策略同源，但日志的删除权在设备侧自己手里）。预算的推导按"最坏诊断窗口"计算：售后关注的现场通常在最近十四天内，那么预算至少要保住十四天的日志量；按最坏记录密度（全等级开、问题复现期的密集输出）估算单日上限，两者相乘即预算。当前的取值留了余量，但"余量"两个字必须落在推导纸上（B03篇8.4节验算表的纪律再次适用），否则日志与录音抢空间的每次冲突都只能临时裁决。

轮转策略还有一个与录音文件相反的细节值得对照：录音的删除是敏感操作、层层把关（2.2节），日志的删除却是系统自主、无需确认的——因为两者的数据主权不同：录音是用户资产，日志是设备内部诊断数据，用户对它的预期就是"帮我留着问题现场，别占地方"。这个对比澄清了一个容易混淆的问题：不是所有文件都需要同等保护，保护等级跟着数据主权走。同类对比还有：日志允许设备自己删（轮转），录音的删除权原则上在用户；日志不需要断点续传之外的完整性仪式（丢了就丢了），录音的导出必须有一致性判定（9.2节）。文件系统里没有"一视同仁"，只有"按主权分级"——把这条想清楚，文件管理的大部分策略问题都有了判据。

6.7 落盘线程的最坏时延账

6.5节规定了"任何等级的日志都不允许阻塞调用方"，这条纪律的完整实现还依赖一笔最坏时延账：环形缓冲被填满时会发生什么？落盘线程来不及消费、调用方又要写入时，系统的选择只有三种——阻塞调用方（违反纪律）、丢弃新日志（丢现场）、覆盖最老日志（丢历史）。工程的取值是"按等级丢弃"：环形缓冲满时，新来的低等级日志直接丢弃并计数，错误级日志允许挤掉缓冲里的调试级条目，只有"缓冲里全是错误级且仍满"这一极端情形才丢错误级。这套规则的实质是给日志排了优先级的兜底序——正常时全收，紧张时保高弃低，极端时保最有诊断价值的最后防线。丢日志本身也要留痕：每级被丢的条数记入一个计数器，诊断命令可查——"日志说谎"（明明有问题却没记录）与"日志缺席但不解释"相比，后者更可恨，因为前者查得出原因，后者让人怀疑整个日志系统。

最坏时延账的另一头是落盘线程的调度优先级。落盘线程优先级取低了，闪存稍慢（比如录音同时在写）时缓冲就逼近满，进入丢日志区；取高了，又可能反过来饿到别的任务。工程的定法是先定指标再定优先级：目标是"错误级日志在系统最忙时（录音落盘加BLE吞吐峰值同时发生）仍不丢"，按这个目标实测标定优先级，而不是凭直觉取中间值。这类"以最坏工况定参数"的方法在本篇反复出现（9.4节、10.6节），因为文件与日志系统的服务对象恰恰是"出问题的时刻"——系统最忙的时候往往就是要诊断的时候，这时候丢错误级日志，等于消防队在火灾现场缺水。

图示：日志生命周期全景（本章新增）

功能文字流程图（模块视角）——一条日志从出生到退役：

各模块调用日志接口(等级+指针,入队即返回,不阻塞调用方)
   │
   ▼
环形缓冲 → 落盘线程(格式化在落盘侧!6.5节)
   │
   ▼
按日切分:devlog+日期.log,隐藏目录
   │
   ├─ 错误级:永远落盘(量小信息密度最高)
   ├─ 关键流程级:按模块开关
   └─ 调试级:量产默认关,诊断命令临时开
   │
   ▼
容量预算(6.6节):十四天最坏诊断窗口 × 最坏单日密度 = 总上限
   │ 逼近上限
   ▼
轮转:删最老日期(系统自主,无需确认——数据主权分级图)
   │
   ▼
导出:绑定手机+审计记录(9.7节) → "日志的导出会留下日志"(自指闭环)

工程注解： 这张全景图把第六章串成一条河——从入队到退役，每个渡口都有一章把守；最值得看的是三个"渡口设计"：格式化放落盘侧（调用方零成本）、预算按最坏窗口算（余量落推导纸）、导出留审计（事后可答"谁取走了什么"）——日志系统的目标从来不是记录一切，是让下一次导出的几分钟里，有最大概率命中要找的那几行。

七、开源对照：乐鑫与通用方案

7.1 ESP-IDF 的文件分发与 OTA 式分块

在 ESP-IDF 生态里，通过 GATT 分发文件常见做法与本工程高度一致：自定义特征值承载、应用层按块切分、带偏移的请求应答、接收方回确认后再发下一块。开源的蓝牙 OTA 组件更是把"分块、偏移、校验、断点续传、结束标志"做成了成熟范式，本设备的文件下载在数据面几乎是"反向的 OTA"（设备是发送方、手机是接收方），设计要点完全可以互鉴。差异在于 ESP 组件常依赖 FreeRTOS 任务和动态内存，本工程用静态线程栈和静态缓冲换取内存确定性。ESP 的 FAT/VFS 抽象也提供了与 Zephyr 文件系统类似的 open/read/seek 接口，移植偏移续传逻辑很直接。

7.2 经典串口协议与蓝牙串口服务

蓝牙经典 SPP 或 BLE 上的 Nordic UART Service 提供的是字节流式通道，文件传输协议（如 XMODEM、YMODEM）在这种字节流上用块号、校验、ACK/NAK、重传来保证可靠文件传输。本工程的偏移续传与这些经典协议精神相同，但用"绝对偏移"而非"相对块号"来定位，使得中断后从任意位置恢复都更简单，也天然支持手机端随机拼接。对照经典协议有助于理解：可靠文件传输的本质是"把文件切成可确认的小块、用某种定位信息保证不重不漏、用校验保证内容正确"，具体用块号还是偏移、停等还是滑窗，都是在延迟和复杂度之间的取舍。

7.3 双通道与流控的工程共识

ESP 及很多物联网设备在文件导出上也采用"控制走低带宽可靠通道、数据走高带宽通道"的组合（如蓝牙配网后切 Wi-Fi 传输）。本工程蓝牙控制加可选 Wi-Fi 数据的双通道路线与此一致。流控方面，各方案普遍通过接收方 ACK 速率或发送缓冲水位来约束发送节奏，本工程的速度档位和缓冲区水位退避是同一思路的轻量实现。这些跨平台共识说明：可靠文件传输的难点不在某条具体链路，而在块、定位、确认、流控这几个抽象要素的协同。

7.4 蓝牙Mesh与多跳传输的对照：复杂度天花板

把视野再放大一档，蓝牙Mesh生态里的文件传输（固件分发就是典型）展示了"多跳不可靠链路上的可靠传输"长什么样：Mesh的传输模型要处理拓扑、中继、泛洪去重，文件分发协议（如BTP）在它之上再做分块、确认与重试，其状态机复杂度是点对点传输的数倍。对照的价值是标定复杂度天花板：本工程的传输假设"一条链路、两端直连"成立，所以偏移续传可以极简；一旦链路变成多跳（例如未来产品做设备间中继），偏移续传的"单路径顺序流"假设全部作废，得向Mesh方案的方向重构。把天花板提前画出来的意义，是防止有人低估"加一个中继功能"的代价——那不是在现有传输上"多传一段"，是推倒重来一级复杂度。

Mesh对照还有一个反向收获：它对"慢而稳"的坚持。Mesh文件分发的单块确认几乎是停等式的，吞吐极低但每一步都确认——因为多跳环境下任何"连续推送"的假设都站不住。这提醒我们评估本工程的连续推送设计时保持清醒：它的前提（蓝牙点对点、链路延迟有界）是产品形态送的礼物，不是普适真理。传输协议的一切"快"都建立在"链路性质已知"上，链路性质一变，慢而稳永远是安全垫底。

7.5 开源OTA组件的"反向使用"清单

7.1节提到本设备的文件下载是"反向的OTA"，这里把对照展开成一份可操作清单——开源OTA组件里值得"反向取经"的五件东西。其一，分块指纹：成熟OTA在每块里带块序号加CRC，续传时逐块验证防止"拼错位置"——本工程当前靠帧CRC保证传输中完整，但"多次断续拼接"的累计正确性还没有块级验证（10.3节的摘要校验正是补这一课）。其二，进度持久化：OTA组件普遍把进度写到非易失存储，App重启后续传——本工程进度在App内存里，App被杀进度丢（10.3节已列）。其三，双镜像回滚思想：OTA失败自动回退旧固件——对导出的类比是"传输失败时保证源文件状态完全未变"，本工程因只读导出天然满足，但未来若做"导出后删除"类联动就要补。其四，下载限速接口：OTA常提供按场景限速（升级中保前台性能）——本工程的速度档位可以借鉴它把"档位"暴露成产品可配参数。其五，完成校验的仪式感：OTA升级完成后做整包校验才置"有效"标志——导出的对应物就是9.2节的"结束标志加总大小"判定，本工程已有、但可对照升级为摘要校验。五件清单里两件已补进演进方向，三件正在路上——开源对照的最实际产出，就是这样一张"别人已经踩过的坑、我们还没走到"的路线图。

7.6 取经的纪律：什么时候不该学开源

7.5节列了五件该学的，这一节补一条同样重要的判据：什么时候不该学。开源组件与本工程的约束不同，盲目移植的代价不比不学小。三条"不学"的判据，均来自真实教训。第一条，动态内存不学：多数OTA组件的任务与缓冲走动态分配（灵活、可伸缩），本工程的静态纪律（14.1节）一旦破例就是先河效应——第一个动态分配会引来第二个，确定性账本从此作废。曾有同事移植某开源组件的"按文件大小动态选缓冲"方案，评审被否的理由就一条：它把内存确定性换成了吞吐的零星收益，账算不平。第二条，通用性不学：开源组件要服务千行百业，接口带大量本产品永远用不到的参数与分支（多分区、多镜像、多下载源）；照单全收意味着我们的测试面被别人永远用不到的路径撑大。判据是按8.5节的五问裁剪：五问用不到的分支一律删，删完剩下的一般不到原代码量的三成。第三条，配置式流控不学：开源组件习惯把流控做成"每字节配置项"（精细），本工程的档位式是"三档带迟滞"（粗但稳）——档位的思想（B05篇7.5节）恰恰建立在"不追求精细"上，移植精细配置等于把已验证的简化推倒重来。

三条判据合成一句总纪律：向开源学机制，不学形态；学它踩过的坑（7.5节），不学它为自己客户长出的枝叶。判断一段开源代码属于哪类，最快的问法是"这个设计在解决谁的问题"——解决的是可靠传输本身，学；解决的是它生态的兼容与规模，不学。这条纪律让开源对照六年来的收益始终为正：取经清单越攒越长，移植包袱一件没背。

图示：反向 OTA 与取经三分法（本章新增）

功能文字流程图（模块视角）——开源对照的两张清单：

本工程导出 = "反向OTA"(设备发,手机收)
   │
   ▼
┌─ 该学清单(7.5节,踩过的坑我们还没到) ─────────────┐
│ 分块指纹(防拼接错)  进度持久化(App被杀不丢)          │
│ 双镜像思想(源文件状态不变)  限速接口  完成校验仪式     │
└──────────────────────────────────────────────────┘
┌─ 不学清单(7.6节,为别人生态长的枝叶) ───────────────┐
│ 动态内存分配(静态纪律不破例)  通用性参数(五问裁剪)    │
│ 配置式精细流控(三档带迟滞是已验证的简化)              │
└──────────────────────────────────────────────────┘
   判据一句话:向开源学机制,不学形态
   分辨法:问"这个设计在解决谁的问题"——
        解决可靠传输本身→学;解决它生态的兼容与规模→不学

工程注解： 这张双清单图把 7.5/7.6 节的取经纪律变成可执行的核对动作——每次对照开源，产出物就是两栏清单而不是感想；图的底部分辨法是全系列"学机制不学形态"的操作化：一个问题定方向，六年来让开源对照的收益始终为正、包袱一件没背。

八、跨平台横向对比

8.1 Linux/Android 的 MTP 与文件管理

消费电子导出文件最常见的高层协议是 MTP（媒体传输协议），手机和相机通过它向电脑展示文件列表、支持下载删除。MTP 由操作系统和协议栈实现了对象枚举、分块传输、存储管理等复杂能力，应用无需关心块和偏移。相比之下，本设备没有资源实现完整 MTP，而是在 BLE 上用极简的"列表 + 偏移读 + 删除"原语自建了最小够用的文件访问协议。二者层次不同：MTP 是通用、丰富但笨重的标准，本工程协议是专用、精简但需要自己保证可靠的定制方案。Android 上 App 侧拿到这些数据后则写入应用沙箱或媒体库，遵循其存储权限模型。

8.2 ADB、调试桥与诊断日志

Android 工程师取日志依靠 adb pull 和 logcat，Linux 设备可直接 scp 或挂载文件系统。这些方式都假设有较高速的物理或网络连接和成熟工具链。资源受限设备没有这些，把日志导出压缩到蓝牙通道上，本质上是为"没有 ADB、没有网络、只有一部手机"的现场提供一个等价能力。理解这一点就能明白日志导出功能为何值得做：它把原本只存在于实验室的高权限诊断能力，裁剪、加密、鉴权后安全地送到了售后现场。

8.3 与对象存储 / HTTP 下载的对照

云端文件下载基于 HTTP 范围请求（Range）和对象存储，天然支持偏移续传、状态码、完整性校验（ETag），并有成熟的断点下载库。本工程设备端的偏移续传可以看作把 HTTP Range 的思想手工实现在 BLE 私有协议上：请求带偏移、响应带偏移和数据、结束靠文件大小判断。差别在于 HTTP 跑在 TCP/IP 上、可靠与重传由协议栈保证，而 BLE 文件传输要在应用层自己处理节奏与失败。正是因为近场链路缺少 TCP 那样成熟的可靠字节流保证，偏移、块、结束标志这些要素才必须在应用层显式存在。

8.4 资源约束塑造的形态差异

综合来看，桌面和手机平台靠操作系统与标准协议获得"开箱即用"的文件传输能力，代价是庞大的协议栈和资源占用；本设备在 KB 级内存和有限带宽下，用静态缓冲、独立线程、白名单文件名、偏移续传和轻量流控，自建了一套恰好够用的文件导出设施。它不如 MTP 通用、不如 HTTP 强大，但在"近场、点对点、设备资源极少、要导出的文件种类完全已知"的特定形态下，是复杂度与可靠性的合理平衡。这种"用对业务的先验知识（文件命名完全可控）来换取实现的极简与安全"的思路，正是嵌入式系统设计的典型特征。

8.5 对比收束：文件传输的五个不变量

把MTP、HTTP、XMODEM、OTA与本工程五种方案放到一起，可以提炼出文件传输的五个不变量——无论介质与协议怎么变，这五件事必须有人管。不变量一是定位（哪一段数据）：块号、偏移、范围请求是同一概念的三种编码。不变量二是边界（何时结束）：总大小、结束标志、目录遍历完结都是边界声明，没有边界声明的传输永远"不知道自己完了没有"。不变量三是完整性（对不对）：逐块校验、整包摘要、帧CRC都是完整性，覆盖粒度不同。不变量四是节奏（多快）：流控、限速、停等，全是谁听谁的问题。不变量五是身份（哪个文件）：文件名、对象句柄、URL——白名单校验在本工程里就是身份不变量的极端化实现。五个不变量各自回答一个问题，任何文件传输方案都是对五问的某种回答——用这张清单去评审未来的新传输方案（比如5G消息、点对点WiFi直连），缺失的问就是设计缺陷，多余的答就是过度设计。对照章节写到这里，最有价值的产出往往就是这种"跨方案的公因式"——它比任何单一方案的知识都长寿。

8.6 从"五个不变量"到评审检查单

8.5节的五不变量还有一步从知识到工具的转化值得记录：把它变成新导出方案的评审检查单。转化规则很简单——每个不变量对应检查单上的一个必答题，答案必须同时给出"谁负责、失败时什么表现、怎么验证"三个字段。以历史评审为例：配置备份的预演评审（10.7节）过这张单时，"完整性"一问暴露了真问题——配置是KB级小文件，逐块CRC加三验一签的成本相对收益失衡，但"导入方向的配置写入"必须加原子替换与校验，因为导入失败的半截配置会让设备带病启动——同一个不变量在导出与导入两个方向上的合理答案完全不同。这次暴露让检查单加了脚注：五问先问"方向"，再按方向定答案的粒度。

检查单的第二次实战是外部方案评估：供应商提过一套"手机直读设备文件"的私有方案，材料里主打"速度提升数倍"。过检查单时五问只答了节奏一问（速度），完整性含糊、身份完全依赖应用层约定、边界靠"超时判定"——超时判边界意味着"传输慢一点就会被误判为结束"，与三验一签的截断事故（9.6节）是同一族缺陷。评估结论当场从"性能讨论"转向"可靠性不成立"，节省了整个验证排期。这两次实战让检查单获得了正式地位：新通道、新对象、新方案的评审必过五问，答案入评审记录。跨方案对照的产出能走多远，取决于它能不能变成下次决策时的第一道关卡——公因式写在纸上只是知识，钉在评审流程上才是制度。

图示：五不变量的公因式图（本章新增）

功能文字流程图（模块视角）——任何文件传输方案都要回答的五问：

                    一次文件传输
   ┌───────────┬───────────┬───────────┬───────────┬───────────┐
   ▼           ▼           ▼           ▼           ▼
 定位:        边界:        完整性:      节奏:       身份:
 哪段数据?    何时结束?    对不对?      多快?       哪个文件?
 块号/偏移/   总大小/结束   逐块CRC/     流控/限速/   文件名/句柄/
 范围请求      标志/遍历完   整包摘要/帧CRC 停等        URL
 (本工程=绝对偏移)(=结束标志+总大小)(=块CRC+三验一签)(=档位节拍)(=白名单!)
   │
   └→ 用五问评价新方案:缺的问=设计缺陷,多余的答=过度设计
      已两次实战(配置备份预演/供应商方案评估,8.6节)

工程注解： 公因式图是第八章跨方案对照的最大产出——五种方案（MTP/HTTP/XMODEM/OTA/本工程）的全部差异都落在五问的不同答案上，而五问本身五年不变；把五问钉进评审流程（8.6 节），知识就变成制度：新方案的评审第一动作是填这张图的五栏，填不出的栏目当场暴露。

九、安全与健壮性专题

9.1 删除安全与回收

删除操作要同时保证文件和可能存在的关联资源处理一致：删除录音时应考虑对应的清单条目、临时文件、已写入但未关闭的句柄。安全做法通常是先确认文件已关闭、再删除数据文件、最后更新清单，避免删了数据却留下指向它的账本记录，或删一半异常导致目录不一致。删除线程在执行前同样过文件名白名单，防止误删。对还在上云过程中的文件，删除需要与传输/上云逻辑互斥，避免一边读一边删。把删除当作一个需要多资源协调的事务性动作，而非简单的一次系统调用，能避免大量存储一致性问题。

9.2 传输中断与半截文件

下载中断在手机端可能留下半截文件。协议用"结束标志 + 文件总大小"让手机能区分"完整到达"和"中途断开"：只有收到结束标志且累计字节等于总大小，才把临时文件标记为完整可用，否则保留为可续传的临时数据。设备侧则因为是只读导出，中断不会破坏源文件，重连后从偏移继续即可。这样设计使得无论断多少次，源文件始终安全，最终完整性由接收端显式判定，不会把半截录音误当成完整文件呈现给用户或上传。

9.3 速率调试与容量预期

发送速率调试开关能打印实际吞吐，帮助校准用户预期和参数：在典型手机与距离下蓝牙导出每秒若干 KB，一个几 MB 的录音可能需要几十秒，这一事实应在 App 交互上通过进度和剩余时间体现，而不是让用户面对一个看似卡住的界面。速率日志还能暴露异常：吞吐突然下降往往对应干扰、距离变远或手机进入后台限速。把容量和速率的真实数字在设计阶段测清楚，是决定"哪些文件默认走蓝牙、哪些提示用 Wi-Fi"的依据。

9.4 存储与内存的边界情形

需要覆盖的边界包括：目录为空、目录中文件很多、单个文件超过静态缓冲需要多次读、读到闪存坏块、文件大小与清单记录不一致、导出过程中存储被拔出或进入低功耗。对这些情形，线程应通过返回码和失败应答优雅退出、释放内存和保活锁，而不是卡死或永久占用线程。列举时动态申请目录和目录项对象、用完即释放，也是为了让大目录遍历不至于长期占用固定内存。把"失败路径和成功路径一样被认真设计"作为这一层的质量标准，尤其重要，因为文件操作恰恰是最容易遇到存储异常的地方。

9.5 威胁建模：以攻击者视角过一遍导出面

安全专题值得补一次正式的威胁建模，用攻击者视角把导出面全部过一遍。攻击面一：文件名注入（3.5节白名单已覆盖——穿越、通配、非法字符在结构层被拒）。攻击面二：枚举探测——攻击者通过列举命令探知设备上有哪些文件（时间戳即使用习惯），这层信息泄露被绑定鉴权前置拦截：未绑定连接连列举命令都发不出来（B04篇闸门），探测面收窄为已绑定方。攻击面三：传输截获——链路加密覆盖。攻击面四：篡改注入——伪造数据帧向手机塞假录音？发送侧只有设备一方（通知单向），注入需要先破解链路加密，攻击成本已超出该资产价值。攻击面五：拒绝服务——持续请求列举或传输耗电（B05篇案例六的教训），由速度档位与背压限速兜底。攻击面六：删除滥用——已绑定方恶意删除？删除走业务层"已上云或用户明确确认"的前置（2.2节），机制层的最后防线是删除同样过白名单。

六个攻击面的评估结论：导出面没有高危未覆盖项，但有两处值得记录的残余风险——已绑定手机的合法拥有者本身就是"攻击面六"的潜在主体（夫妻共用设备场景），产品的回答是删除需用户显式确认而非自动策略兜底；攻击面二的信息泄露在"已绑定但手机丢失"场景下依然成立，回答是绑定可解绑、日志导出有审计记录（谁在何时取走了什么）。威胁建模的价值不在发现惊天漏洞，在于把"我们为什么认为它安全"写成可复核的论证——安全评审再问起时，答案已经在纸上等了六年。

9.6 一致性判定的仪式化：完整文件的"三验一签"

9.2节确立了"结束标志加总大小"的完整性判定，工程实践里它被进一步仪式化为"三验一签"流程，仪式化的价值是把判定从"App的实现选择"升格为"协议承诺"。三验：收端校验结束标志已收、累计字节等于总大小、帧序号无缺口（B05篇序号副产品的第三次复用）；一签：三验全过后，App把文件从临时区移入正式区并登记设备侧清单的标识——至此文件才获得"完整"身份。仪式的每一验都有失败对应：标志未到则保留临时区等待续传，字节不符则从差异点续传，序号有缺口则按缺口定位重取——三种失败都收敛到"继续传"而非"重头来"，这正是偏移续传设计的红利兑现。

仪式化的另一面是拒绝捷径：曾有快速迭代版本的App为了赶进度，只验了"字节等于大小"就宣布完整——漏验结束标志导致一次"设备还没发完、App以为完了"的截断事故（设备侧最后的冲刷块还没发出，App按大小凑齐了就收工，实际凑齐的是错误的大小预期）。此后三验成为联调验收的强制断言，任何一验的缺失都是红灯。完整性判定之所以要仪式化，因为它是"半截录音冒充完整录音"这道用户信任底线的唯一守门人——守门人的检查单少一项，底线就塌一角。

9.7 导出会话的审计记录

9.5节的威胁建模留下了"日志导出有审计记录"这个承诺，这里把它的实现写实。每一次导出会话（不论录音还是日志）在设备侧留一条审计记录：谁（绑定的连接代数，B06篇的连接代数戳复用为审计主体标识）、何时（会话起止时间）、取了什么（文件名）、取走多少（字节数）、结果如何（完成或中断及原因）。审计记录本身写入日志系统（6.5节的错误级或关键流程级），于是形成了一个自指结构：日志的导出会留下日志。这条自指曾被评审质疑"递归无意义"，回应是审计的价值不在递归本身，而在"事后可答"——手机丢失后用户解绑重绑时，客服能回答"过去十四天里谁取走过日志、取走了哪天的"（9.5节攻击面二的残余风险正是靠这个回答兜底的）。

审计记录的边界也要讲清楚，防止对它的期望膨胀：它不记录文件内容，只记录元数据（名与量）；它不防删除（攻击面六的场景里，恶意者删完录音再删日志？——日志在隐藏目录且删除命令过白名单，App侧的删除命令只认录音命名规则，日志文件名根本不在其白名单内，这层不对称是审计成立的前提）。审计记录是"事后追溯"而非"事中阻止"——把它定位成安全机制是高估，定位成责任机制才准确。凡是多方共享数据的产品（哪怕只有两方：用户与其手机），"谁在什么时候动过什么"的元数据账本都是信任纠纷的最终证据，它的成本低（每会话几行日志），价值在第一次"我没取过日志"的扯皮里一次性回收。

图示：六攻击面与三验一签（本章新增）

功能文字流程图（模块视角）——攻击面过堂图：

以攻击者视角过导出面(9.5节):
 ①文件名注入 ────→ 白名单结构层拒(3.5节图) [关]
 ②枚举探测 ────→ 绑定鉴权前置(B04闸门) [关]
 ③传输截获 ────→ 链路加密 [关]
 ④篡改注入 ────→ 发送侧只有设备+加密 [关]
 ⑤拒绝服务 ────→ 档位背压限速兜底 [关]
 ⑥删除滥用 ────→ 业务前置+白名单 [关]
 残余风险登记:明文窃听?窗口短+攻击成本>资产价值 → 登记(高敏场景即升级)

┌─ 完整性的仪式:三验一签(9.6节) ──────────────┐
│ 验一:结束标志已收?  验二:累计字节=总大小?         │
│ 验三:帧序号无缺口?   三验全过 → 一签:移入正式区  │
│ 任一失败 → 收敛到"继续传"而非"重头来"(续传红利)    │
│ 三验=联调强制断言(截断事故后,少一验即红灯)        │
└──────────────────────────────────────────────┘

工程注解： 两张图分别对应"为什么我们敢说它安全"与"半截文件为什么冒充不了完整"——攻击面图的产出是可复核的论证（六个"关"各有归属、一处残余登记在案带触发条件）；三验一签则是用户信任底线的守门人检查单：守门人的检查单少一项，底线塌一角，9.6 节那次截断事故就是检查单少验一项的现场代价。

十、运用要点与演进方向

10.1 参数与线程的调优纪律

线程栈深度应依据实际调用链测量（配合栈高水位统计）而非拍脑袋：过小会发生栈溢出，过大会浪费本可用于缓冲的内存。块大小、发送间隔、速度档位阈值则应在真实手机、真实距离、握持与口袋等工况下用速率日志实测标定，优先保证最差工况不丢、再追求平均吞吐。新增一种导出对象（如未来的配置备份）时，优先复用现有线程与白名单框架，只增加命名规则和目录参数，避免另起炉灶。

10.2 向统一文件传输抽象演进

录音和日志两套导出已经高度相似，未来可抽取统一的"文件导出器"：参数化目录、命名校验器、块大小、允许的通道，列举/读/删三个线程作为通用执行体，录音和日志只提供各自的配置。这样偏移续传、保活锁、流控、结束判定等逻辑只需维护一份。抽象的前提是两类导出的共性确实稳定、差异都能被配置表达；在出现第三种导出对象（如配置、波形缓存）时，抽象的收益会更加明显。

10.3 更强可靠性与校验

当前偏移续传保证了可恢复，若要进一步防止传输内容在多次拼接后出错，可在结束阶段对整文件做一次摘要校验（如复用设备已有的 CRC/哈希能力），手机比对设备给的摘要与本地拼得文件的摘要，一致才认定完整。这对跨多次断续传输、甚至跨蓝牙与 Wi-Fi 混合传输的大文件尤其有价值。增量进度也可持久化到手机侧，使得 App 被杀掉重启后仍能继续未完成的导出。可靠性投资应优先投向"完整性能否被确定性验证"这一用户最敏感的环节。

10.4 与云通道的长期分工

随着上云稳定性提升，近场导出会进一步聚焦三类场景：弱网兜底、大文件的本地快速搬运、售后取日志。文件传输模块不必追求取代云端，而应把这三类场景做到极稳、极简、极省电，并与云通道在清单、段状态上保持一致，让用户无论从云还是从近场拿到的录音都对得上账。与 B08 的 Wi-Fi 透传协同，让"控制在蓝牙、大数据在局域网"的分工长期成立，是这一模块清晰的演进方向。

10.5 统一导出器的裁决记录

10.2节提出了统一文件导出器的演进方向，这里补充它的正式裁决记录，防止"抽象"沦为口号。裁决分两步。第一步问共性是否真实：列举、读、删三线程的逻辑在录音与日志两侧已经逐行对比——共性占比超过九成，差异只有四类（目录、命名校验参数、块大小、允许通道），全部能被配置表达——共性真实成立。第二步问时机是否成熟：抽象的成本是要为两侧未来的分化兜底——若某侧未来出现"通用框架表达不了"的需求（比如日志需要按日期范围列举、录音按会话分组），框架就得加钩子、加分支，抽象收益开始倒贴。当前两侧都没有这类需求的苗头，且第三种导出对象（配置备份）已在产品路线图上——两个条件（共性真实、有下一个用户）都满足，裁决通过，排期实施。

裁决记录里还留了一票反对意见值得存档：有评审成员认为日志与录音的删除语义差异（6.6节的数据主权之别）会在统一框架里被抹平，主张先保留两套。回应是把删除语义做成导出器配置的一部分（删除前置策略由各侧注入），框架只管机制。这一票反对的价值在于它提前点中了统一化最可能翻车的位置——机制可以统一，策略必须留在各侧，这句话后来写进了导出器框架的文档首页。评审记录里的一票反对常比全票通过更有营养，它逼着设计者把"为什么能合"讲到无懈可击。

10.6 性能与功耗的联合验收：导出的"每MB成本"

本模块的验收指标体系值得专列一节，它把性能与功耗合并成了一个可跨版本比较的量纲：每MB导出的时间与电量。蓝牙通道的当前基线：每MB若干秒、若干毫安时；Wi-Fi通道：每MB数秒以内、电量另有分布（高吞吐但高瞬时电流，总电量按文件大小摊薄后可能反超蓝牙——小文件反而蓝牙省电）。基线的用途有二：其一，版本回归的判断依据——任何改动让"每MB成本"劣化超过一成即触发分析；其二，产品侧的通道推荐依据——App按文件大小与剩余电量给出"用蓝牙还是Wi-Fi"的建议，建议的数学就是这个基线表。

"每MB成本"作为联合指标还有个微妙的好处：它天然惩罚"为了快而费电"与"为了省电而龟速"两个方向的极端优化，只奖励真正提高效率的改动（同时降低时间与电量）。单一指标（只测吞吐或只测电流）会让调参跑偏——曾有版本把发送间隔调到极限追求吞吐榜好看，每MB成本实测绘出后电流劣化三成，当场退回。联合量纲是参数调优的缰绳，把它立为验收主指标的那一刻起，调优的方向就被自动校正了。

10.7 第一种新导出对象的前置设计：配置备份

10.5节的裁决依据之一是"第三种导出对象（配置备份）已在路线图上"，这里把它作为"新对象接入导出框架"的预演记录下来，检验框架配置的表达力。配置备份的需求形态：用户换机或重新绑定后，想把设备上的配置（Wi-Fi凭据引用、偏好设置、自定义参数）搬到新手机——它比录音小几个数量级（KB级）、敏感度却高一个等级（含凭据引用）、且需要"导入"这个录音从未有过的方向。逐项过配置：目录参数（配置目录，直接可配）；命名校验（新命名规则，白名单稳定层不动、可变层加一条，3.6节的设计红利首次兑现）；块大小（KB级文件用蓝牙块即可，不用另立）；允许通道（凭据敏感，默认只允许蓝牙且要求绑定态——现成的约束直接复用）。配置的前四项全部落在既有框架的表达力内，真正的缺口是"导入方向"——现有框架只设计了设备到手机的单向导出，导入需要新增"接收、写文件、校验、原子替换"一整套反向机制，这部分的复杂度与导出等量齐观，且引入新的攻击面（恶意配置注入），需要独立的威胁建模。

前置设计的结论：导出方向的配置备份可以直接上框架，导入方向另立专项。这个预演验证了10.5节裁决的核心假设——框架的表达力对"同方向的新对象"确实够用，差异如预期全部落在配置层；同时它提前画出了框架的边界——"反向"不是配置能表达的差异，是新的机制。把边界画在预演阶段而非开发阶段，是这份裁决记录最大的省：真到排期时，配置备份的导出部分是三天的事，导入部分是三个月的事，两个数字分开报，路线图的期望就不会错位。

图示：统一导出器与每MB成本（本章新增）

功能文字流程图（模块视角）——配置化抽象的验收结构：

┌─ 统一文件导出器(10.5节裁决通过) ──────────────┐
│ 通用执行体:列举/读/删三线程+续传+保活+流控+三验   │
│ 配置注入:目录│命名校验器│块大小│允许通道│删除前置 │
│              ↑                                    │
│  录音侧注入 ─┤  日志侧注入 ─┐  配置备份(预演,10.7)│
│              └→ 反对票存档:机制可统一,策略留各侧   │
└─────────────────────────────────────────────────┘

┌─ 每MB成本(10.6节,联合验收主指标) ──────────────┐
│ 蓝牙:每MB数十秒+若干mAh │ Wi-Fi:每MB数秒内+mAh另分布 │
│ 用途①:版本回归,劣化超一成即分析                     │
│ 用途②:App通道推荐(基线表交点=推荐阈值)               │
│ 天然惩罚两个极端:为快费电/为省龟速,只奖励真提效      │
└─────────────────────────────────────────────────┘

工程注解： 上图把"抽象"画成配置注入的形态——反对票（删除语义会不会被抹平）被结构吸收为"删除前置策略由各侧注入"，机制与策略的分界正是抽象能否立住的判据；下图则是全章验收制度的锚：联合量纲立为主指标的那一刻，调参方向就被自动校正了——这是"指标设计即行为设计"的教科书案例。

十一、文件导出的实战案例专题

11.1 大文件总是传到 99% 失败

售后早期收到一类反馈：一段较长的会议录音用蓝牙导出，进度条几乎走到尽头却提示失败，重试几次都在接近末尾处中断。抓日志发现传输本身没有报错，问题出在设备在导出持续一段时间后进入了低功耗待机——保活锁只在列举线程里被正确持有，数据线程某条提前返回的分支漏掉了加锁，设备在长时间传输后判定空闲而休眠，蓝牙随之被挂起。之所以总在"99%"处暴露，是因为小文件在休眠超时前就能传完，只有大文件的传输时长足够触发休眠。修复是把加锁移到数据线程的统一入口、解锁放进所有退出路径必经的收尾处，并用代码评审逐分支核对锁的配对。这个案例说明低功耗保活不能只在"主流程"正确，任何提前返回、异常分支都必须成对释放；同时它也提醒，与时序时长相关的缺陷往往只在足够大的数据量下才出现，测试必须覆盖最大尺寸文件而不能只用几十 KB 的样本。

11.2 文件名时间戳重复与覆盖之忧

还有一类问题与命名规则相关。录音文件名以时间戳为核心，曾出现两次录音因设备实时时钟未校准（长时间断电后时间回到默认值）而生成相同时间戳文件名的隐患，理论上可能互相覆盖或在白名单去重时产生歧义。防护有两层：文件管理在生成名字时会检查同名文件是否已存在，必要时追加区分序号，保证名字唯一；导出白名单只认既定结构，重复时间戳若带了序号会因"中间必须纯数字、长度固定"的规则被谨慎处理。这个案例把一个看似纯命名约定的问题和"RTC 未校准"这一硬件现实联系起来，也说明白名单校验不仅是安全闸门，也会反向约束命名规则的设计——任何为了消歧而加入名字的字符，都必须在白名单里有明确位置，否则会出现"文件确实存在、却因为名字不合规而导不出来"的尴尬。

11.3 存储接近写满时的导出与删除

当闪存使用率接近写满，导出和删除都可能遇到异常：读取时碰到写入阶段因空间不足而截断的文件，删除时文件系统回收空间耗时变长甚至返回错误。设备侧的做法是让数据线程对每次读返回值都做判断，读到异常长度或错误码时停止发送并回传失败，而不是把垃圾数据继续发给手机；删除则在文件系统返回失败时如实回报、不假装成功，避免 App 以为已释放空间。容量预警（录音阶段就提示空间）比导出阶段处理更治本，但导出侧对"满盘"这一边界的优雅处理仍然必要，因为用户恰恰会在空间紧张时更频繁地尝试导出和清理。把存储写满列入文件导出的必测边界，能有效避免现场出现"越满越导不出、越导不出越没法清理"的死锁体验。

11.4 蓝牙切 Wi-Fi 时的状态清理

一次从蓝牙导出中途切换到 Wi-Fi 高速通道的测试中，出现过两边都在发送、手机收到交错数据的混乱。根因是切换时蓝牙数据线程没有被干净停止，旧的发送循环和新的 Wi-Fi 发送短暂并存。修复确立了通道切换的串行纪律：先让当前通道的数据线程收到停止信号、退出循环、释放文件句柄和保活锁，确认其完全停止后，再由新通道从同一偏移重新打开文件发送；任何时刻只有一条通道在真正读取发送。这与底座 OTA 模式需要与其他传输隔离的思想一致——共享同一份文件资源的多条数据通道绝不能并发。案例把"偏移续传很灵活"的优点和"灵活容易导致并发误操作"的风险同时暴露出来，结论是续传可以跨通道，但通道之间的控制权交接必须是严格串行、可确认的。

11.5 删除成功却看不到空间释放

偶有用户反馈删除录音后，系统显示的可用空间没有立即增加。排查发现删除逻辑本身成功，但文件在删除瞬间仍被另一个模块的句柄引用（例如本地播放或上云尚未完全结束），某些文件系统在句柄关闭前不会真正回收簇。修复是在删除前先确保所有可能占用该文件的模块（播放、上云、导出）都已停止并关闭句柄，再执行删除，并在删除后回读目录确认条目消失。这个案例把"删除一个文件"从一次系统调用还原成一个需要多方协调的动作，也印证了文件操作与系统其他活动之间必须有明确的互斥和生命周期约定。对用户界面而言，在确认空间真正回收前不宜立即宣称"已释放多少空间"，以免数字对不上再次引发不信任。

11.6 给维护者的阅读建议

阅读文件导出这一层，建议把注意力放在三条主线而不是具体函数上：第一条是"一个外部文件名如何被证明安全"，即白名单的每一条约束各自防住了什么；第二条是"一个慢操作如何不拖累协议栈"，即命令处理与独立线程的分工、栈放在哪里、保活锁如何成对；第三条是"一次传输如何在任意中断后仍然不重不漏"，即偏移、结束标志、总大小和通道串行交接。把这三条主线理顺，再看具体实现就会发现代码不过是这些原则的落地，遇到新增导出对象或新增通道时，也能据此判断该复用什么、该严守哪条纪律。最容易犯的错误恰恰是只模仿了"读一块发一块"的表面循环，却漏掉了文件名白名单、失败路径解锁和通道互斥这些决定产品可靠性的隐式约定，结果在正常演示中一切良好、一到真实用户的复杂工况就频繁出问题。

图示：导出问题的分诊流程（本章新增）

程序文字流程图（执行视角）——"导出失败/慢/不完整"的定位路径：

现象
 ├─ 传到99%失败 ──→ 末块语义负一?对账点一致? → 5.4/11.1路径
 ├─ 传得慢 ──→ 读速率日志:档位长期低位? → 链路(五状态环)/闪存双流竞争分诊
 ├─ 名字报非法 ──→ 生成侧自检日志+白名单可变层核对 → 11.2/案例四路径
 ├─ 删除后空间没回 ──→ 目录项审计+11.5路径
 └─ 混通道切换失败 ──→ 11.4状态清理清单
 每条路径的尽头 → 制度转化表(十二)里的对应行
 (现象→根因→修复→制度,四段有出处,无出处的猜测不进清单)

工程注解： 这张分诊树把第十一章的六个实战专题串成"症状到制度"的直线——注意每条路径的终点不是"修复"而是"制度转化表的对应行"：本层要求每例事故都在转化表上有归宿，"修了但没沉淀"按未修复处理；这也让分诊树本身成为制度的一部分：终点有出处的树才配当排错工具。

十二、现场案例库

第十一章的实战专题重在"怎么定位"，本案例库收录十例完整事故全貌，覆盖线程与栈、通道与并发、存储边界、命名契约与跨端协作五类现场。文件传输的案例有个共同背景：它们几乎都在"真实用户的真实数据量"下才现身——测试环境的几份小样本永远喂不饱这些边界。

案例一：列举线程栈的"深水区"。 一位用户存了近千条短录音（每次想到什么就录一段），点开列表后设备蓝牙复位。日志回捞显示列举线程栈溢出踩进了相邻内存。根因比表面更深：目录条目上千时，文件系统的目录枚举路径会缓存多级索引，调用链深度随目录规模增长——栈的定容当初按"百条录音"的目录规模标定，没人写明这个前提。修复按最坏目录规模（白名单上限条数）重标栈深，并在列举循环里加了栈水位检查：每枚举两百条断言一次剩余栈，逼近则分批应答（列表分段返回，App侧再拼接）。制度沉淀：栈深度的标定条件必须写进常量注释；目录规模是栈深的隐性依赖，目录规模上限与栈深要挂进同一张验算表。

案例二：两个App同时导出。 用户的手机与平板都绑定了设备，两边同时点了导出同一文件。两个数据线程（当时的设计里蓝牙通道的数据线程竟然有两个实例——历史遗留）各自打开同一文件、各发各的，手机收到的数据流两路交错，文件彻底报废。深挖发现"双实例"是早期为"边传边录"并行而留下的，后来录音与导出的互斥已由传输状态管理，双实例失去存在理由却没被清理。修复删除第二实例，并规定：每类数据通道的执行体永远单例，并行需求一律由上层排队而非下层复制。制度沉淀：为旧需求留下的并行结构，在需求消失的当次重构就要清理——"以后可能用得上"在数据平面上从来不是保留双执行体的理由。

案例三：满盘时刻的连锁崩。 用户在存储将满时连续操作：导出失败、删除报错、再导出更失败。三条线索并查发现是三个独立缺陷被满盘同时引爆：导出读链没处理"文件尾部截断"的返回值（把垃圾块发出去了）；删除线程在文件系统返回错误时没释放保活锁（设备从此无法休眠，电池一夜耗尽——9.1节"失败路径同样认真"的代价）；而满盘本身源于录音阶段的空间预警阈值太晚。修复三处，并把"满盘"做成专项测试场景：预置容量耗尽的存储，跑全命令矩阵。制度沉淀：资源耗尽是"缺陷放大器"，平时各自潜伏的三个缺陷会在满盘时同框爆发——边界测试必须包含资源耗尽档，它测的不是单个功能，是全部失败路径的成色。

案例四：时间戳命名的世纪边界。 一次跨年夜里生产测试全部失败——RTC校准流程在闰年判定上有个老缺陷，日期算错后生成的日志文件名带了非法日期数字，白名单拒绝它、列举里看不见它，日志系统却坚持认为"今天的日志在写"，反复创建反复失败，闪存写放大飙升。定位靠的是日志系统自己的计数器（创建失败计数）——诊断工具诊断了自己。修复RTC闰年、命名函数增加"日期合法性"自检（命名前先验证，不合法立即告警而非默默生成）。制度沉淀：一切由时间派生的标识，都要在生成处做合法性自检——时间戳类缺陷总在边界日期（闰年、跨月、跨年）引爆，自检成本低到忽略、爆炸成本高到离谱。

案例五：Wi-Fi块的DMA对齐坑。 Wi-Fi透传引入12KB大块后，偶发传输数据错乱——抓包显示12KB块内容与源文件不符，蓝牙通道却正常。最终定位到DMA要求更高对齐，12KB缓冲的首地址落在非对齐边界上，DMA搬运从某个偏移开始错位；小块的蓝牙缓冲恰好天然对齐所以幸免。修复给Wi-Fi缓冲加了显式对齐属性并断言地址；制度沉淀：对齐要求跟着缓冲的消费者（DMA/协议栈）走，不跟着分配方式走——静态数组的"碰巧对齐"不可依赖，一切进入DMA路径的缓冲必须显式对齐加编译期断言（B06篇布局三条件的姊妹条款）。

案例六：续传偏移的"负一"幽灵。 有用户反馈导出的录音结尾有约一秒的重复内容。定位发现是续传时机的竞态：断连发生瞬间，App侧记录的"已收位置"比实际多算了一块——最后一块已发出但App只收了一半就断了，App按"发出计数"记位而非"收完整块计数"记位，续传从早一块开始，拼出的文件里那块出现了一半接一半的重复。修复是App侧改按"完整收块计数"记录续传位置；设备侧配合在续传应答里带上"本会话已发的最后偏移"做交叉校验。制度沉淀：续传位置的记账语义必须在两端协议文档里写死——"发出"与"收到"是两个不同的量，记账永远按可验证的一侧（收完整块）而不是乐观的一侧（发出）。

案例七：日志轮转删掉正在写的文件。 跨天时刻，日志轮转策略删除最老日志，恰好当天目录里有"同名日期"的文件（设备时间被回拨过）——轮转把"最老"判定成了"今天"，删掉了正在写的日志。写线程的句柄还开着，闪存上文件已消失，后续日志全部写进了已删除的簇链，重启后一切无痕。修复两层：轮转增加"当前活跃日志豁免"（按打开句柄判定而非仅按日期判定）；文件系统层面确认删除语义（打开中的文件删除在各实现的等待行为不同，驱动层显式处理）。制度沉淀：任何"自动删除"策略都要过"正在使用"这道闸——B02篇循环覆盖的排除逻辑在此再次应验，跨模块通用的判据值得进公共评审清单。

案例八：列举的分帧与App的贪心解析。 千条录音的列举结果被设备分成多帧应答（案例一的修复产物），某版本App的解析器假设"列举结果一帧到齐"，第二帧到达时按错误格式解析、界面显示乱码文件名。根因是协议文档对"分帧列举"的描述只有一句"可能分帧"，没写分帧规则（每帧N条、帧序号、结束标志）。修复按协议版本升级流程补齐分帧协议（B04篇纪律全程走了一遍），App按新版本实现。制度沉淀：凡是"可能"的协议行为，都必须有完整的分帧/顺序规范——"可能分帧"三个字对实现者等于没说；灰区清单（B06篇9.6节）再添一类：可变长应答的分帧规则。

案例九：保活锁的隐式继承。 一次"边导出边充电"的测试里，导出完成后设备依然不休眠。排查发现充电模块在导出开始时也持有一把锁，导出释放了自己的锁，充电模块的锁语义却在"拔线时释放"——测试时线没拔，锁合法地在岗。表面上这不该算缺陷（充电时不休眠是产品预期），真正的问题是两层：设备没有任何工具能回答"此刻为什么不休眠"（B01篇唤醒锁账本的思想还没落到这个平台版本）；导出结束时应答里没有带"仍持锁原因"的提示。修复是把唤醒锁账本机制移植过来（登记每把锁的持有者与原因，诊断命令一查便知），并规定长操作的完成应答附带当前锁状态。制度沉淀：多模块共享的资源（锁、缓冲、句柄）必须配"账本式"诊断——出问题时能立刻点名"是谁在占"，这类工具的成本是一次性的，价值在每一次"谁占着谁"的扯皮里复利。

案例十：导出速率的用户预期管理。 一次客诉：用户导出一场三小时的会议（数十MB），界面进度条龟爬，用户认定设备坏了，反复取消重试——每次重试都从续传点继续，但用户不知道，看着进度条又从头看感觉（其实是App显示了总进度），愤怒升级。问题不出在传输（速率正常），出在预期：App没有告知"这个文件按当前速率需要约X分钟"，用户对着沉默的进度条脑补了故障。修复是App侧显示预估剩余时间加"建议改用Wi-Fi"提示（10.6节基线表的产品化），设备侧提供速率查询命令。制度沉淀：凡是耗时超过一分钟的操作，"预期管理"（预估、进度、可中止）就是功能的一部分而不是体验的锦上添花——用户对不可见的等待只有一种解读：坏了。

十例分布：三例是资源边界（一、三、五），两例是并发与单例纪律（二、七），三例是跨端契约与协议灰区（六、八、十），两例是时间与命名的边界（四、九）。与前几篇相比，本层案例的显著特点是"跨端责任"占三成——文件传输的用户体验一半由App写就，设备端再稳，灰区与预期管理掉链子，客诉照样记在硬件头上。这也是10.6节基线表要产品化的原因：把工程数字翻译成用户语言，是这一层对客诉率最实在的贡献。

案例库的最后值得补一张"制度转化表"：十例事故各自沉淀成了什么，转化是否完成。逐例对账：案例一（栈深水区）转化为3.2节的差异化栈深与栈高水位巡检制度，已固化两代版本；案例二（双App并发）转化为5.8节统一停止出口与并发矩阵文档，完成；案例三（满盘连锁）转化为6.6节日志容量预算与2.3节的存储水位联动，完成；案例四（时间戳世纪边界）转化为11.2节命名规则修订与白名单可变层新条目，完成；案例五（DMA对齐）转化为3.3节四字节对齐纪律加构建期断言，完成；案例六（续传负一）转化为5.4节"块内偏移负数即末块"的显式语义加向量测试，完成；案例七（日志轮转误删）转化为3.5节后缀白名单对内部文件的保护，完成；案例八（列举分帧）转化为分帧机制加"应答帧长度上限"的评审必检项，完成；案例九（保活锁隐式继承）转化为唤醒锁账本移植加"完成应答附锁状态"的接口约定，完成；案例十（预期管理）转化为14.3节时延分解表喂给App的预估算法与通道推荐，完成。十例全部闭环。

这张表本身的用意比表更值一提：案例库如果不做转化对账，会退化成"讲故事专栏"——故事越攒越多，同类事故照发不误，案例库反而成了"我们重视质量"的装饰品。转化对账把每个案例钉在它换来的制度上，让"复盘"这个词有了验收标准：一次复盘的产出不是会议纪要，是被改掉的设计、被补上的测试、被写下的条款。这一层十例无一复发，靠的不是记录，是转化表右列的那些机制在替记忆值班。

图示：十例的根因分布与转化对账（本章新增）

功能文字流程图（模块视角）——案例库的两张统计图：

┌─ 根因分布 ─────────────────────────────────────┐
│ 资源边界(栈深/满盘/DMA对齐)   3例                  │
│ 并发与单例纪律(双App/轮转误删)  2例                 │
│ 跨端契约与协议灰区(负一/分帧/预期) 3例              │
│ 时间与命名边界(世纪/保活锁)   2例                  │
└─────────────────────────────────────────────────┘
      ↓ 本层显著特点:跨端责任占三成(设备再稳,App掉链子照样客诉)

┌─ 制度转化对账(十例闭环) ──────────────────────────┐
│ 每例 → 对应制度(3.2差异化栈深/5.8统一出口/6.6容量预算…│
│        …/5.4负一语义/8.7锁账本/10.6每MB成本)      │
│ 转化率 10/10 · 复发率 0/10                        │
│ 复盘的验收标准:被改掉的设计+被补上的测试+被写下的条款 │
└─────────────────────────────────────────────────┘

工程注解： 分布图揭示本层与前面各篇的结构差异——"跨端责任三成"意味着这一层的交付物里必须包含给 App 的契约（并发矩阵、基线表、三验定义）；对账图则是案例库不退化为"讲故事专栏"的机制：右列那些制度在替记忆值班，所以十例无一复发。

十三、常见问题 FAQ

以下十二问按本层评审、联调与售后现场的频率排序，答案以可操作判据为主。文件传输层的问答多数都能落到"两个数字加一条纪律"——数字可标定，纪律可评审，这是这一层可制度化程度仅次于编解码层的原因。

问一：为什么不把整个文件一次性发出去？ 答：因为链路不可靠且缓冲有限。一次性发送意味着全部数据进缓冲后一次推送——缓冲装不下（KB级内存对MB级文件），链路抖一次全部重来。分块把"必须一口气成功"放松为"逐块渐进"，每块都是独立可确认、可重发的单元。判据：块大小的选取按"单块传输失败的代价"（一块重发的时间）与"块开销"（帧头占比）的平衡点定——960字节是蓝牙MTU约束下的平衡点，12KB是TCP场景的平衡点，都不是哲学，是算术。

问二：为什么三个操作三个线程，而不是一个文件线程？ 答：三个理由（5.2节）：栈深隔离（列举的深调用链不该连累数据的扁平循环）、阻塞隔离（删除的抖动不该打断下载）、失败隔离（列举失败不该中断传输）。一个线程的方案省两份栈（约7KB），但把三类操作的最坏调用链叠进同一个栈、把三种故障域耦进同一个执行体——7KB买不回这个耦合的排障成本。判据：合不合线程，先画"调用链深度表"和"故障域表"，两张表差异大就分，差异小再谈省栈。

问三：块CRC有了，为什么还要考虑整文件校验？ 答：两者防的错误不同（10.3节）。块CRC防"传输中坏"，防不了"拼接错"——多次断续、跨通道续传时，块都对但拼错位置的风险存在（案例六的重复块就是拼接错的近亲）。整文件摘要防的是"累计错误"，它在结束时对全局做一次裁决。判据：凡传输可能分多次、跨通道、跨App版本完成，整文件校验的收益就大于其成本（一次哈希计算）；一次性直连完成则块CRC已够。

问四：日志为什么按天切分而不是单文件追加？ 答：四个理由的合力：定位（按日期找现场，导出时按天取）、轮转（按天删最老的，6.6节的预算实现基础）、导出粒度（用户只要出事那天，单文件得整块拉）、损坏隔离（写坏一天不殃及全部历史）。单文件追加的方案在这四点上全输，唯一的赢面是"少几个目录项"——这个收益可以忽略。判据：文件的切分维度应当跟着"最小有用单元"走，日志的最小有用单元是天，录音的（B02篇）是会话——切分对了，导出、轮转、定位三件事全部顺理成章。

问五：白名单会不会误伤合法文件？ 答：会，而且发生过（案例四的非法日期文件、11.2节带序号的文件名），这正是白名单设计的核心张力：严格性换来安全，代价是对命名规则的"不合规则即拒绝"。工程的解法不是放宽白名单，而是双向靠拢：命名生成侧保证只产合法名（生成前自检），白名单侧为每个新命名特性预留位置（3.6节的稳定层与可变层）。判据：凡是新命名特性，评审必过两关——生成器会自检吗？白名单的结构层（长度、数字、后缀）需要动吗？后一关要是答案是"要动"，通常说明命名设计本身有问题，回去改命名而不是改闸门。

问六：导出期间能录音吗？ 答：能，这是产品设计而非技术限制——录音走文件环与编码管线（B03篇），导出走独立数据线程，两者共享的只有闪存带宽与链路。实测导出时开始录音，音频落盘会有轻微延迟增加（闪存双流竞争），实时外发若同时进行则三条流共享链路（B05篇案例十的让路规则生效）。但注意反向问题：录音期间删除被互斥（9.1节），列举可以但会慢（目录扫描与录音落盘抢闪存）。判据：并发能力的清单要按操作对逐一评审（"录音加导出可以、录音加删除不行、导出加升级不行"），逐对写进协议文档的"并发矩阵"，别让App去猜。

问七：为什么设备不做"导出完成自动删除"？ 答：因为删除是敏感操作、导出是尽力而为操作——用尽力而为去触发敏感操作，等于把用户的原始录音押在一个不可靠的通道上（导出成功≠云端已有≠可删）。删除的把关（已上云确认或用户显式操作）必须由业务层独立判断，与导出这件事解耦（2.2节的机制与策略分离）。若产品未来要"导出即转移"语义（存储紧张场景），正确做法是导出三验一签完成后由云端回执确认、再走独立删除流程——把"确认完成"与"执行删除"分成两次握手，永远比"导出完顺手删"多一道保险，而那道保险正是用户数据的生命线。

问八：12KB的Wi-Fi块会不会太大，TCP分片了怎么办？ 答：会分片，且这是预期行为。12KB块在TCP层被切成若干报文是TCP的正常工作，应用层不感知——块大小的选取针对的是"每次系统调用与每报文开销的摊薄"，不是"不分片"。真正要防的是把TCP当成永不丢的幻觉：透传通道的流控（B08篇的三级水位）仍然必要，因为TCP重传在拥塞时会让发送方堆积。判据：应用块大小优化的对象是"应用层的每块固定成本"，链路层的分片问题由链路层解决——两层各自优化各自的账，别把TCP的账记到应用块头上。

问九：日志会不会把闪存写坏？ 答：寿命账算过：错误级加关键级日志的日均写入量在百KB级，摊到日志专用区的擦写预算，年限余量充足（B03篇12.4节的算法）。真正的风险不在量在"写法"：同步写（每条日志立刻落盘）会把随机小写放大到闪存上，工程用环形缓冲加批量落盘压掉了这个放大。判据：日志系统的寿命审计要测"每条日志的介质成本"（放大系数乘条数），而不是只看日志文件大小——写法不同，同样大小的日志对闪存的伤害差一个数量级。

问十：列举结果会不会太大撑爆应答帧？ 答：按设计不会——列举分帧（案例八的修复）让结果按帧流式返回，App侧拼接，单帧负载恒定。真正要审的是另一个量：千条录音的列举总耗时（目录扫描加多次帧发送），当前实测秒级且放独立线程不阻塞命令。判据：列举的容量上限要与"列表功能的产品容忍时长"一起评审——目录扫描上限（如两千条）不是文件系统的上限，是"用户愿意等列表多久"的产品决策，工程把这个决策翻成扫描上限与分帧参数，两头都得有出处。

问十一：如果只能给文件传输层留三条纪律，留哪三条？ 答：第一，来自手机的一切输入过白名单，来自设备的文件名生成前自检——两端合起来保证"合法名字的闭包"；第二，一切长操作单执行体、单停止标志、单收尾路径——并发入口千万个，退出独木桥一座；第三，一切失败路径与成功路径同设计、同测试、同释放——锁、句柄、内存，成功时怎么拿的失败时就怎么还。三条合起来防住的恰是本篇十例的全部十类根因，纪律不多，但一条都不能少。

问十二：这一层最被低估的能力是什么？ 答：日志导出。用户看不见它，营收不依赖它，但它把"售后SLA"（2.5节）从按周拉到按天，是产品口碑里最沉默的杠杆。被低估的常见形态是"砍日志功能省内存""日志导出排不上优先级"——每次这类提案，值得把9.5节的六攻击面与案例三（满盘连锁）的复盘再讲一遍。诊断能力的账要在它救回第一次重大客诉时才被人看见，而到那时候再补建，要等下一个季度版本——这就是为什么本层把日志导出按"生命线"而不是"功能"来排期。

图示：文件传输层问答决策树（本章新增）

程序文字流程图（执行视角）——十二问压成四路：

导出类问题
 ├─ 快慢路:"为什么这么慢?" → 基线对比(每MB) → 落后在哪段?
 │         (时延分解表:命令段/打开段/逐块段/收尾段各有主人)
 ├─ 对错路:"传的对不对?" → 三验各过了吗? 块CRC失败分布?
 │         (完整性=块CRC+三验一签,两层各管一类错)
 ├─ 身份路:"名字合法吗/误删?" → 白名单日志+生成侧自检+审计记录
 │         (身份不变量:两端闭包)
 └─ 并发路:"能同时XX吗?" → 查并发矩阵(录音+导出✓/录音+删除✗/导出+升级✗)
           (矩阵逐对写进协议文档,别让App去猜)

工程注解： 这棵树把 FAQ 的"两个数字加一条纪律"特征画成四路——每路的终点都是一张前文图（基线表/三验图/白名单图/并发矩阵）；本层问答高度制度化的原因也在图上：文件传输的设计问题几乎都能拆成"数字可标定、纪律可评审"的两半，这正是小结里"可制度化程度最高之层"的注脚。

十四、文件传输的资源与确定性账本

本篇多处承诺过"账要落在纸上"（6.6节的容量预算、10.6节的每MB成本），本章把这一层占用的资源统一入账，供评审时对照：任何新提案要加内存、加线程、加缓冲，先在本账本上找到它要挤占的科目。账本分五页：内存、CPU与调度、时延、能耗、测试资产。

14.1 内存账：三个线程的栈与四块缓冲

第一页记内存。静态科目五笔：列举线程栈、数据线程栈、删除线程栈、录音发送缓冲、日志发送缓冲。栈的账在3.2节与3.7节已详细展开，这里只补总账与余量：三栈合计约12KB（列举最深约5KB、数据约4KB、删除约3KB，均按实测高水位加两成余量标定），放在noinit段后不占初始化内存分配器；录音发送缓冲960字节对齐四字节，日志发送缓冲约1KB，两者不同时活跃但都按常驻记账（静态分配不问活跃与否，这是用确定性换灵活性的固定税）。动态科目两笔：列举时的目录与目录项对象按需申请、用完即释（9.4节），单次峰值约数百字节且有申请失败处理——这是本层仅有的动态内存，规模与风险都控制在可审计范围内。

内存账的评审规则：任何人要给这一层加常驻内存（比如5.9节讨论过的双缓冲），必须在账本上指出被挤占科目或证明余量。账本维护的仪式与B05篇11.7节相同：每次改动凡涉及这五笔静态科目的任何一笔，账本表格同步更新，评审必附新旧对照。这套仪式的成本是每次改动多写两行表，收益是内存问题从"压测时才爆炸"提前到"评审时就能吵"——而评审桌上吵，永远比线上炸便宜。账本上还有一个容易漏记的科目：文件系统内部的工作缓冲（每次打开文件的会话开销）。它不出现在本模块的代码里，却真实消耗在文件系统的调用链里——凡是通过系统间接占用的资源，账本设"隐含科目"单列，这是账本区别于"内存分配表"的地方：分配表记代码写过的，账本记系统花掉的。

14.2 CPU 与调度账：导出时处理器把时间花在哪

第二页记CPU。数据线程的循环（4.4节）把时间花在五处：读闪存、CRC计算、帧头组装、栈调用发送、等待（让出）。典型分布按真机剖析：等待占大头（蓝牙工况下八成以上时间在等链路层搬运与对端确认，5.7节的节拍器让出型延时是主要构成）；CRC与组帧占百分之几（960字节的CRC是毫秒以下的事）；读与栈调用合计占剩余的一到两成。这个分布的工程含义有三层：其一，导出对CPU的总需求很低，导出期间系统有充分的算力余量跑录音与上云（问六的并发能力在此有数据支撑）；其二，任何"优化发送循环CPU占用"的提案都找错了科目——CPU不是瓶颈，链路等待才是，优化要在等待模型上做文章（档位、重试、缓冲水位，B05篇的主场）；其三，剖析数据是"让出型延时"制度的量化证据——若等待那八成时间不是让出而是忙等，CPU账会立刻翻成八成占用，系统其余任务被饿（5.7节的按键变钝事故就是这笔账的现场版）。

调度账还记一笔优先级税：三个线程的优先级都低于音频与蓝牙协议栈的实时任务、与上云任务同级、高于日志落盘（6.7节按最坏时延账定的）。这个排序的依据是"谁的服务对象更时间敏感"：音频丢一拍是用户可闻的缺陷，导出慢半秒没人知道——优先级排序本质上是缺陷可感知度的排序。这条依据写进账本的意义，是防止未来的"导出提速"提案顺手提升线程优先级：提速的正道是减少等待（更好的档位、更大的块），不是抢占别人——在账本科目上动手脚刷出来的快，都从别人的慢里偷的。

14.3 时延账：一次导出的时延分解表

第三页记时延。把"手机点导出到文件完整"全程分解，各段时延的可解释来源如下表所列（以10MB文件、蓝牙通道、畅通档为基准工况）：命令往返与权限确认（百毫秒级，受蓝牙连接间隔影响，B05篇连接参数的账）、文件打开与清单核对（十毫秒级）、逐块循环（主体段：每块读一两毫秒加发送确认几十毫秒，乘块数——10MB约一万一千块，累计数百秒）、结束帧与三验一签（百毫秒级，含App侧落盘）。分解表的第一个用途是预期管理（案例十的教训产品化）：App的预估剩余时间不再拍脑袋，而是按"当前档位的实测块耗时乘剩余块数"计算，预估误差可控制在两成内。第二个用途是性能归因：任何"导出变慢"的客诉，先对分解表量各段——逐块段变长是指针指向链路（B05篇的五状态环会给出佐证），打开段变长指向文件系统（可能与录音落盘竞争闪存），命令段变长指向连接参数——分解表把"慢"从一个形容词拆成三个有主人的科目。

时延账里还有一个特别的行：最坏情况的时延。最坏工况（远距、干扰、拥塞档、闪存双流竞争）下的每块耗时可达基准的十倍，即10MB文件最坏接近半小时——这个数字必须进App的文案设计（超过某预估时长就提示改Wi-Fi），也必须进售后的预期话术。工程数字的诚实义务是连同最坏值一起报，只报基准值的最坏后果，就是把"你们产品半小时传不完"的客诉留给自己。

14.4 能耗账：每MB的电量与保活锁的时间

第四页记能耗，核心量纲是10.6节的"每MB成本"。这里补能耗侧的分解账：蓝牙导出的电量由三段构成——链路维持（保活锁期间的待机功耗上浮，B01篇锁账本的电量口径）、CPU与闪存动作（很小，见14.2）、无线发射（主体）。Wi-Fi导出的构成相同但分布迥异：瞬时电流高一个量级、传输时间短一个数量级、总电量的胜负取决于文件大小（大文件Wi-Fi省、小文件蓝牙省，10.6节基线表的结论）。能耗账给产品侧的输出是那张"按文件大小推荐通道"的决策表；给工程侧的输出是一条设计纪律：保活锁的持有时长就是能耗账的最大自变量——一切缩短传输时间的优化（块大小、档位、续传减少重传）同时都是能耗优化，这一层的"快"与"省"是同一件事的两面。

能耗账还要记一笔"隐性持有"：9.1节删除与上云互斥期间，删除线程的保活锁也上着——删除通常只占秒级，但上云队列拥堵时互斥等待会拉长持锁时间。这笔账的审计方法与B01篇锁账本一致：锁的持有时长进统计计数器，诊断命令可查"最长一次删除持锁多久"。能耗账本与锁账本在这条科目上共用一套审计设施——这也是账本制度的复利：为功耗建的计数器，顺手回答了并发审计的问题。

14.5 测试资产账：这一层靠什么锁住回归

第五页记测试资产，即"这一层的正确性由哪些可重复执行的资产保证"。存量清单四类：其一，白名单校验的向量测试（合法名全过、非法名全拒、边界名逐条断言——3.6节每次演化必须同步扩充，这是资产里最怕过时的一类）；其二，偏移续传的注入测试（脚本在随机块号注入中断、跳块、重复请求，断言续传后文件与源逐字节一致——5.4节的语义由它锁死）；其三，三验一签的验收断言（App侧联调用例覆盖三验各自的失败路径，9.6节截断事故后补建的资产）；其四，三个线程的退出路径测试（5.8节统一出口重构后，三种停止来源的两两组合用例——组合爆炸做了裁剪，取了现场概率最高的组合）。四类资产的共同纪律与B06篇15.5节相同：每次缺陷修复必须在资产里找到或新增对应用例，"修了但没测"的缺陷按未修复处理。

资产账里也有一笔负资产要如实记录：并发矩阵（问六的录音加导出、录音加删除等操作对）目前靠手工用例维持，没有自动化——手工资产在版本节奏快时的衰减是可预见的，账本里记下它的手工属性与折旧风险，是为了让"并发矩阵自动化"在下一次资源分配的讨论里有出处可查。账本的诚实义务不只对内存与电量，也对自己：测试体系哪里薄，账本知道，评审桌就得知道。

图示：五页账与隐含科目（本章新增）

功能文字流程图（模块视角）——账本科目与评审规则：

┌─ 14.1 内存页 ─────────────────────────────────────┐
│ 静态五笔:三栈12KB(高水位+两成余量)+两块发送缓冲         │
│ 动态一笔:列举目录对象(可审计)  隐含科目:文件系统内部缓冲 │
│ 规则:加常驻先在账上找到挤占科目(内存官司的出庭规则)      │
└──────────────────────────────────────────────────┘
┌─ 14.2 CPU页 ─────────────────────────────────────┐
│ 八成在等(链路+对端) → 优化CPU=找错科目,调档位才是正道   │
│ 优先级税:音频>协议栈 >导出=上云 >日志落盘               │
└──────────────────────────────────────────────────┘
┌─ 14.3 时延页 ────────────────────────────────────┐
│ 基准:逐块段占大头(一万一千块×几十ms)  最坏:基准×10       │
│ 输出:App预估剩余时间(误差<20%)+最坏值进文案              │
└──────────────────────────────────────────────────┘
┌─ 14.4 能耗页 ────────────────────────────────────┐
│ 核心自变量:保活锁持有时长 → 快与省是同一件事的两面       │
│ 隐性持有:删除互斥上云期的锁时长(共用锁账本审计)         │
└──────────────────────────────────────────────────┘
┌─ 14.5 测试资产页 ─────────────────────────────────┐
│ 白名单向量/续传注入/三验断言/退出组合                  │
│ 负资产如实记:并发矩阵仍是手工(折旧中,改进有出处)        │
└──────────────────────────────────────────────────┘

工程注解： 这张五页账总图是十四章的目录化——每一页都有一条"评审规则"嵌在框内而非框外（加内存先找科目、优化CPU先找对科目、最坏值必须进文案、负资产必须留名），把规则画进科目表本身，是账本从"记录工具"变成"裁决工具"的关键一笔。

十五、本篇小结

BLE 文件传输与日志模块是设备离线数据的近场出口。它把列举、读取、删除三类慢文件操作从蓝牙命令处理中彻底剥离，交给各自独立、栈深差异化、且栈体放在不初始化内存段的专用线程执行，命令侧只做快速派单并在操作期间用待机锁阻止系统休眠；它用一块四字节对齐、蓝牙约 960 字节、Wi-Fi 约 12KB 的静态发送缓冲配合绝对偏移续传、结束标志和速度档位流控，让大文件在不可靠近场链路上可分块、可恢复、不重不漏地导出；它把来自手机的文件名当作不可信输入，用"固定长度、固定后缀、固定前缀、中间纯数字"的严格白名单从结构上杜绝路径穿越与误操作，并顺带保护内部清单文件；它让诊断日志（按日期命名、存放隐藏目录）复用同一套列举、校验、分块、删除框架，默认只走蓝牙以克制复杂度，同时通过绑定鉴权和内容脱敏守住隐私边界。与 ESP-IDF 的 GATT 文件分发与 OTA 式分块、XMODEM/YMODEM 经典块协议、MTP 通用媒体传输、ADB 诊断桥以及 HTTP 范围下载相对照，这套实现是资源受限、对象类型完全已知的点对点形态下复杂度与可靠性的合理平衡，演进方向包括统一文件导出器、整文件摘要校验和与云通道长期分工。

把本篇的深层线索收拢成几句可带走的话。第一条线索是"慢操作必有其自己的执行体"：从命令线程里的阻塞调用，到共享文件线程，再到三个独立差异化栈深的线程，这条演进线的每一步都是被具体事故推的（栈深水区、删除抖动打断下载），而非设计者的先见——它留给维护者的判据是9.4节那句话，失败路径和成功路径一样被认真设计，而失败路径认真与否的第一块试纸，就是它有没有自己的执行体。第二条线索是"身份先于一切"：白名单不校验在文件名这一个点上，而是这一层对整个体系的总纲——文件名是这一层里唯一来自对方的"指针"，指针不验，后面所有机制（偏移、续传、删除）都是在给不可信的输入盖可信的章；3.6节的稳定层与可变层设计，则让这道闸门在命名规则演化面前保持可治理。第三条线索是"仪式守护底线"：三验一签、删除前置、白名单前自检，这三个仪式共同守住一条用户信任底线——用户的原始录音在任何故障、任何误操作、任何组合时序下不被损坏、不冒充完整、不被无声删除；仪式的成本是每次多几条断言，仪式的收益是底线事件从"偶发事故"降级为"不可能事件"。

第四条线索是这一层特有的"跨端责任"：十例里有三例的根因在App侧、两例的修复落在产品文案（预期管理、通道推荐），文件传输的用户体验一半由另一端写就——这决定了这一层的工程产出里必须包含给对端的契约（并发矩阵、基线表、三验定义），只把自己这端做稳，在这层不算完成。第五条线索是账本制度在本层的全面落地：容量预算（6.6）、每MB成本（10.6）、内存五科目与时延分解（十四），账本把这一层最常扯皮的科目——内存给谁、慢归谁、电从哪里省——全部翻译成评审桌上可查的数字；这一层也因此成为全部八篇里可制度化程度最高的层之一，因为它的几乎每个设计问题都能落到"两个数字加一条纪律"的问答形态里（十三问的通览即是明证）。维护者若只能带走一句话，带走这一句：文件传输的一切可靠性设计，都在回答同一道题——怎么把用户最宝贵的数据，从一块不可靠的链路上，不重不漏地搬到另一端；白名单、偏移、档位、三验，都只是这道题在不同位置的分步作答。

图示：五条线索与三层咬合（本章新增）

功能文字流程图（模块视角）——全层机制在一张合同网上：

 手机App ──文件名(过白名单)──→ [命令侧:派单+保活锁]
                                  │
              ┌───────── 列举/数据/删除三线程(noinit栈) ─────────┐
              │                                               │
        B02清单+文件 ──偏移读块──→ [B06帧+CRC] ──→ [B05档位节拍] ──→ 链路
              │                                    ↑
              └── 三验一签(收端判定) ←── 心跳对账点 ──┘
   五条线索在图上的位置:
   慢操作自有执行体(三线程) / 身份先于一切(白名单) / 仪式守底线(三验)
   跨端责任一半在App / 账本把扯皮变成数字

工程注解： 收官图把小结的五条线索直接标进机制网——三线程、白名单、三验是设备端的承诺，对账点与基线表是发给 App 的合同，五页账是评审桌的裁决依据；本层所有新增图示（白名单图、三验图、五问图、账本图）在这张网上都有坐标，这是"图示体系"的最后一层价值：每张图不仅自己可读，还能互相指路。