AI 时代,如何做一个生产级 Android BLE SDK ?
一次"让 AI 参考开源项目写 BLE SDK"的实验,以及青竹 SDK 如何同时解决两类生产问题:批量通信的可靠性,和大型 BLE 项目里的多 SDK 维护。
摘要
- AI 在几分钟内就能生成一个 BLE MVP,参考成熟开源项目后,还能做出双机调通的教学级 SDK。这是真实的、值得认真对待的能力。
- 但"理想链路成功过一次"不等于"能通过生产验收"。中间隔着两层差距:
- 第一层,通信控制面:单个 SDK 内部的状态、调度、超时、取消、重试、恢复、诊断和验证。
- 第二层,多 SDK 治理:大型 BLE 项目里,多套设备 SDK 并存,重复实现、互相争用、难以裁剪和升级。
- 两层问题是连在一起的:第一层的所有治理手段(统一扫描、串行建连、连接容量、任务调度),都要求 BLE 资源只有一个所有者,而多 SDK 并存恰恰打破了这一点。
- 本文用一组实验说明这两层差距从哪里来,再用我这几年积累的青竹 SDK,说明这些经验如何被收进"任务式、资源调度、异常治理、宿主加协议插件"四个机制里。
- 最后讨论有经验的工程师应该如何指导 AI:把经验变成约束,而不是把约束留在脑子里。
github地址:github.com/qingzhu-ai-…
目录
- 一个几百行的 MVP,为什么不够
- 成熟 SDK 在解决什么:开源项目与能力地图
- 实验:让 AI 参考开源项目,差距到底在哪里
- 生产级的两层差距
- 青竹 SDK:设计总览与能力边界
- 主线 A:通信控制面
- 主线 B:多 SDK 治理,宿主加协议插件
- 把设计串起来:一个批量场景,以及怎样证明
- 用工程经验指导 AI
- 结语
- 附录
1. 一个几百行的 MVP,为什么不够
1.1 一个很典型的故事
先讲一个虚构但很典型的故事。
小明是一名 AI 全栈工程师,从没做过 Android,更没做过 BLE。他接到任务:做一个 Android BLE SDK,加一个能演示的 Demo。他没有先研究 BLE,直接打开 AI 工具,输入了这样一段提示词:
帮我写一个 Android BLE SDK,并写一个可以运行的 Demo。
1. 使用 Kotlin。
2. 支持扫描、连接、断开、发送数据和接收通知。
3. Demo 提供扫描、连接和发送按钮,并显示设备返回的数据。
4. 处理 Android 蓝牙权限,代码要简单、容易接入。
协议:广播名以 DEMO_ 开头;一个 Service,一个 Write 特征,一个 Notify 特征;
数据帧由 HEADER、COMMAND、LENGTH、PAYLOAD、CHECKSUM 组成;
手机写入配置命令,设备通过 Notify 返回成功或失败。
提示词、协议和代码均为虚构的公开示例。
这段需求其实不算差:有平台、有语言、有功能、有协议。几分钟后,几百行核心代码出来了:
点击扫描 → 收到广播 → 点击连接 → 发现服务 → 开启 Notify
→ 点击发送 → 收到响应 → 页面显示"配置成功"
演示一切正常。这并不意味着 AI 没价值,恰恰相反:一个没有 BLE 经验的人,在很短时间内跑通了完整链路,这是很现实的价值。
但它只证明了一件事:
在当前设备、当前环境、当前操作步骤下,这条理想链路成功过一次。
1.2 接入正式 App 之后
小明把 SDK 接入正式 App,交给测试。反馈很快来了:
| 测试反馈 | 背后可能涉及的工程问题(需要实测定位) |
|---|---|
| 扫描慢,有时很久才发现设备 | 扫描模式、过滤、周期、系统版本 |
| 连接慢,经常失败或超时 | 状态机、超时、重试、服务发现、系统兼容 |
| 发送慢,而且经常中断 | GATT 操作串行、分包、MTU、写入类型、响应匹配 |
| 批量配置很慢 | 设备间编排、等待策略、失败恢复、进度管理 |
| App 经常闪退 | 线程切换、生命周期、回调时序、资源释放 |
仅凭现象不能断定具体原因,但它们共同说明:Demo 的成功路径,和正式 App 的使用场景之间,隔着很大一段距离。 Demo 默认一台手机、一台设备、距离近、信号好、用户一步一步点、失败了手动再试;正式 App 面对的是多设备和批量任务、弱信号、设备不响应、中途断连、页面退出、后台切换、不同机型和系统版本,以及长时间运行。
1.3 补丁越打越厚
小明继续让 AI 修:加重连、加等待、加分包、加重试、加延时、加队列、加特殊设备兼容……每个要求单看都合理。
如果没有统一的状态机、任务调度、错误模型和生命周期设计,这些补丁会散落在回调和条件分支里:代码膨胀、职责混杂、状态不一致、问题互相影响、新增设备要改一大片。
所以"代码变多"只是表象,更深的问题是:
复杂性一直在增加,但没有被统一抽象和管理。
MVP 回答的是"链路能不能走通";成熟 SDK 回答的是"复杂度增长之后,系统还能不能保持正确、稳定、可维护"。在继续打补丁之前,先看看成熟的开源项目已经解决了哪些问题。
2. 成熟 SDK 在解决什么:开源项目与能力地图
2.1 调研方法
我选了五个高关注度的 Android BLE 开源项目,只读仓库页面和 README,不分析源码,目的是看它们对外提供了什么能力、背后解决了什么通用问题。
数据快照:2026 年 11 月 16 日。Star 为 GitHub 页面约数,提交时间来自公开记录。Star 反映关注度,不能单独证明生产使用,也不等于仍在维护。
| 项目 | Star | 最近公开提交 | 许可证 | 给我们的启发 |
|---|---|---|---|---|
| FastBle | 约 5.5k | 2026-04 | Apache-2.0 | 易用性不只是 API 少,要把重连、超时、分包变成统一能力 |
| Android-BluetoothKit | 约 3.7k | 2020-02 | Apache-2.0 | 成熟 SDK 要管"请求"和"连接资源",不只是"设备"(历史设计案例,不建议新项目直接使用) |
| RxAndroidBle | 约 3.5k | 2025-06 | Apache-2.0 | 异步、错误、生命周期可以用统一模型组织,并提供 Mock 便于测试 |
| Android-BLE | 约 2.9k | 2024-11 | Apache-2.0 | 性能体验取决于队列、发送节奏、进度和取消机制 |
| Android-BLE-Library(Nordic) | 约 2.4k | 2026-10 | BSD-3-Clause | 完整的请求模型;本身不含扫描,靠清晰的职责边界组合能力 |
高 Star 不等于仍在维护,持续维护也不等于适合你的场景。Star 帮我们找到值得研究的项目,但不能代替选型。
2.2 能力地图
把五个项目的能力合起来看,一个成熟 SDK 要思考的,早已不止"扫描、连接、发数据":
| 能力层次 | 需要解决的问题 |
|---|---|
| 基础通信 | 扫描、连接、服务发现、读写、Notify、Indicate |
| 状态与调度 | 连接状态、请求队列、操作顺序、超时、取消、重试 |
| 异常恢复 | 断连、蓝牙状态变化、服务发现失败、缓存与错误处理 |
| 数据传输 | 分包合包、长写入、发送节奏、进度与取消 |
| 性能控制 | MTU、PHY、连接优先级,以及可测量的吞吐与延迟 |
| 资源管理 | 多设备连接、句柄、监听、任务的统一释放 |
| 使用体验 | 统一错误模型、日志、文档、回调或响应式 API |
| 测试与演进 | Mock、自动化测试、模块边界与新能力扩展 |
这张图并不要求每个项目实现全部,它的作用是帮我们判断:面对自己的场景,哪些是必需的。
成熟 SDK 的核心不是功能越多越好,而是把状态、异步、异常、资源和扩展的复杂性,收进清晰的模块边界。
3. 实验:让 AI 参考开源项目,差距到底在哪里
3.1 实验做法
有了能力地图,我做了一次真实的编码实验。不是让 AI 一次性生成整个工程,而是拆成四步:克隆五个开源仓库;让 AI 分析各自的优缺点和架构;依次实现扫描、连接、数据传输;再写一个独立的模拟从端用于联调。
最终产出三个互相隔离的模块(我称这次实验为 Fullstack 实验):
fullstack-ble-sdk:扫描、连接状态机、GATT 单飞队列、Notify、MTU、分包写。fullstack-ble-demo:权限、扫描列表、连接初始化、发送与响应日志。fullstack-ble-peripheral-sim:仅用原生 API 实现广播、GATT Server、写请求响应、串行 Notify。
AI 从开源项目中提炼了四项值得实现的设计:扫描会话统一终结;服务发现完成后才进入就绪;每连接单飞 GATT 队列;操作超时后重置连接,隔离迟到回调。
验证结果分层说明:6 个基础单元测试、三个模块的 Lint、AAR 和 APK 构建均通过;用两台 Android 10 手机分别运行主从端,人工确认扫描、连接、发送、Notify 的基本闭环调通。
3.2 人工复查发现的问题
AI 的初版并不完美,复查时发现:
- 从端响应没有考虑 MTU 限制;
- 多个 Notify 连续提交,缺少单飞队列;
- 断开后立即重连,可能撞上地址记录尚未释放;
- Android 13 新 GATT API 的同步返回值常量用得不准;
- 资源释放写在同一个
try里,前一步异常会跳过后一步。
还有一类更隐蔽的问题,编译、Lint、单元测试都发现不了:AI 会把合理的设计推演,写成"已经存在的事实"。 比如把"学习器算法存在"写成"主链路已经自动闭环",把教学伪代码写得像真实 API。这类问题只能靠对照源码、追调用链来发现。第 9 节会专门讨论。
3.3 这个实验证明了什么
先说清楚:双机调通,只证明基本链路可行,不代表性能、兼容性、长期稳定性和复杂异常场景通过了验收。
再说一个必须小心的结论。我给 AI 的需求本来就是"教学级、只用原生 API、不引入 Rx 或协程",所以这个实验不能证明"AI 做不到企业级"。它能证明的是:
AI 能很好地完成"你说出来的需求"。生产级的差距,在于那些没人说出来的需求。
因此我把 Fullstack 当作"教学级基线",不当作成熟开源库的能力上限。下表每一行,都先问"教学版这样做为什么合理",再问"生产场景为什么需要更多":
| 场景 | 教学版的合理取舍 | 生产场景为什么需要更多 |
|---|---|---|
| 任务管理 | 只有连接和连接内的操作队列 | 业务要自己补"找到设备、发送中、可取消、失败重试",每个页面理解不同 |
| 多设备 | 每连接独立队列 | 设备一多,同时建连会压垮手机蓝牙栈,批量反而更慢 |
| 超时 | 超时后重置整条连接,稳妥隔离迟到回调 | 一个小请求卡住会拖累同一连接上其他任务;业务也无法只取消某一个任务 |
| 重试 | 默认不重试,不会误重发 | 临时失败的成功率靠业务补;但盲目重发可能让设备重复执行,需要协议配合幂等 |
| 断线 | 断了就关闭,交给业务 | 批量任务做到一半被打断,只能人工重来 |
| 大文件 | 按 MTU 切包,写完报进度 | 手机写完不等于设备收齐,需要回执核对字节数和片数 |
| 新协议 | 固定 Service 和特征 | 每增加一种设备就往核心里加 if/else |
| 排查问题 | 错误对象和 Demo 日志 | 只知道"失败了",不知道卡在扫描、连接、排队、写入还是设备 |
这张表里,前面大部分是单个 SDK 内部的问题,而"新协议"这一行已经指向另一个方向:当一个项目需要支持的设备越来越多,问题就不再只发生在一个 SDK 里了。
4. 生产级的两层差距
4.1 两层差距概览
| 层次 | 问题的范围 | 核心问题 | 本文对应章节 |
|---|---|---|---|
| 第一层:通信控制面 | 单个 SDK 内部 | 状态、调度、超时、取消、重试、恢复、诊断、验证 | 第 6 节 |
| 第二层:多 SDK 治理 | 整个 App,多套 SDK 并存 | 重复实现、资源争用、状态与错误模型不一致、无法裁剪与演进 | 第 7 节 |
很多关于"BLE SDK 性能"的讨论只停留在第一层。但在大型 BLE 项目里,第二层的问题往往更持久:性能问题可以靠一次优化缓解,而多套 SDK 并存带来的维护成本,是随着时间、设备种类和团队规模不断累积的。
4.2 第二层问题:大型 BLE 项目里的多 SDK 并存
一个大型 BLE 项目通常是这样长大的:每接入一类新设备,要么引入厂商提供的 SDK,要么团队自己再写一套,要么在已有封装上再加一层。几年之后,App 里常常是这个样子:
App
├─ 设备 SDK A 自带扫描、连接、重试、分包
├─ 设备 SDK B 另一套实现,错误码与回调风格不同
├─ 设备 SDK C 又一套,依赖的基础库版本也不同
└─ 若干基础封装库,各自封装一部分公共逻辑
以下是大型 BLE 项目中常见的表现,并非针对某个具体项目的统计。
| 常见表现 | 带来的后果 |
|---|---|
| 扫描、连接、超时、重试、分包在每个 SDK 里各写一遍 | 同一个缺陷要在多处分别修复,修复进度不一致,行为也不一致 |
| 各 SDK 各自启停扫描、各自发起连接 | 争用同一个蓝牙适配器;系统对应用启动扫描的频率有限制,多套 SDK 各自启停更容易触碰;没有全局的连接数与建连节奏控制 |
| 状态模型、错误码、回调风格各不相同 | 业务页面要为每套 SDK 写一份适配和状态判断,只能靠复制粘贴维护 |
| 所有设备协议被一起打包 | 只用到一类设备的产品,也要带上全部协议和依赖 |
| 新增一种设备的成本高 | 要么再接一套 SDK,要么在业务层堆条件分支 |
| 公共行为一改就牵一发而动全身 | 不知道会影响哪些设备,回归范围无法控制 |
这些问题的根因可以归结为一句话:
BLE 资源(蓝牙适配器、扫描、连接数、GATT 操作时序)在一个进程里是共享的,但"谁拥有它们"从来没有被设计过。 多套 SDK 并存时,每一套都以为自己独占这些资源。
这就是两层问题的连接点:第一层里的串行建连、连接容量、统一扫描会话、任务调度,只有在单一所有者之下才成立。如果扫描和连接散落在多套互不知情的 SDK 里,再好的调度策略也无处落脚。所以,多 SDK 治理不是第一层的"附加功能",而是第一层能够生效的前提。
青竹 SDK 的设计,就是同时对这两层问题的回答。
5. 青竹 SDK:设计总览与能力边界
5.1 三个阶段,两条主线
BLE SDK 的演进,大致可以分成三个阶段:
阶段一:BLE 工具库 Scan → Connect → Write → Notify
业务自己组织完整流程
阶段二:工程化 SDK 状态机 · 请求队列 · 超时 · 重连 · 分包
SDK 封装"单连接"的复杂性
阶段三:青竹的目标架构 业务意图(Command)
任务池与生命周期
批量调度与资源控制
恢复与诊断
平台适配(扫描 / 连接 / GATT)
协议插件
SDK 管理"跨设备、跨阶段、跨协议"的复杂性
阶段三的关键,是同时回答第 4 节提出的两层问题。青竹的关键设计,归纳为两条主线、四个主题:
| 主线 | 主题 | 一句话 |
|---|---|---|
| A. 通信控制面 | 任务式 | 客户端只表达"我要做什么" |
| 资源调度 | 批量与多设备下,建连、连接、传输各自治理 | |
| 异常治理 | 设备换地址、扫描假死、断连、传输不闭环,都由 SDK 管理 | |
| B. 多 SDK 治理 | 宿主加协议插件 | 一个宿主拥有全部 BLE 资源,公共能力上移,协议差异下沉到插件 |
这些单项设计本身都不是全新的概念:队列、重试、插件化在业界都有先例。我想说明的是,怎样把它们组合成一套既适合批量 BLE 场景、又能收敛多 SDK 并存局面的完整架构。
5.2 当前能力边界
为了不让后文的描述被误读,这里先把当前状态集中列出,后文不再逐节重复:
| 能力 | 当前状态 |
|---|---|
| 任务式模型、占位任务自动寻人、重试、取消与删除 | 已实现 |
| 串行建连闸门、连接容量(硬件体检 + 建议值 + 持久化) | 已实现 |
| 传输窗口 | 已实现;固定可配置,默认 1(串行),不是自适应 |
| 并发学习器 | 算法已实现;批量结果自动回灌学习器尚未接通 |
| 稳定身份、扫描自愈、心跳重连、传输治理、设置与日志 | 已实现 |
| 批量操作 | 循环调用单台 submit,没有独立的 submitBatch |
| 任务列表订阅 | 当前为单 listener 覆盖式 |
| 任务状态 | 没有独立的 FAILED,失败原因保存在 error 字段 |
| 宿主加协议插件(一个宿主 AAR + 每种设备类型一个插件 AAR) | 已实现 |
| 协议插件的优先级、冲突告警、启停与版本管理、自动化测试 | 未完成 |
| 老协议栈迁移到插件的适配 | 是方法论,没有内置迁移工具 |
| 可编程从端 | 支持手工故障场景和统计展示;没有自动断言、弱信号与丢包注入、双端自动对账 |
| 性能、兼容性、长时间稳定性,以及多 SDK 治理的维护收益 | 尚无系统实测数据(见 8.2) |
6. 主线 A:通信控制面
6.1 主题一:任务式,所有操作皆任务
问题。 普通 SDK 的单位是"设备"或"回调"。业务要自己拼状态:设备找到了吗?现在是扫描、排队、连接还是发送?失败要不要重试?取消该停在哪一步?这个回调属于新任务还是旧任务?
以前,业务大概是这样写的:
startScan { device ->
connect(device) { ok ->
if (ok) discoverServices {
enableNotify {
write(data) { result -> updateUi(result) }
}
}
}
}
// 还要自己补:超时、断连、重试、页面销毁、迟到回调……
做法。 把扫描、排队、连接、发送、取消、重试统一提升为任务。现在业务只表达意图:
val task = sdk.submit(device, command) // 真实 API
sdk.subscribe { tasks -> render(tasks) } // 订阅任务列表的全量快照
task.cancel() // 取消当前动作,任务回到待机
task.delete() // 彻底删除
任务 = 一个设备 + 一条可选命令。 可以类比下载管理器:任务有状态、进度、错误和生命周期,UI 不再需要在十几个回调里拼状态,只订阅任务列表。
command 不是一串字节,而是一张"说明单":做什么、带什么数据、发完是否保持连接、断线后是否恢复。常见的六种意图如下(字段细节见附录 A):
| 意图 | 含义 |
|---|---|
| 只连接 | 连上并保持,等待后续命令 |
| 只发数据 | 没连接时由 SDK 自动找设备、排队、连接,再发送 |
| 连接、发送、自动断开 | 一次性短任务(默认行为) |
| 连接、发送、保持连接 | 设备后续还要继续通信 |
| 批量 | 一批设备共用同一张说明单 |
| 删除 | 终止当前动作、断开、清理状态 |
任务的状态流转可以这样理解:
READY / UNKNOWN → SEARCHING → QUEUED → CONNECTING → CONNECTED → SENDING
├─ 保持连接 → CONNECTED
└─ 发送后断开 → READY
失败或超时 → 未超过重试次数:回到 QUEUED
→ 超过重试次数:回到 READY / UNKNOWN,保留 error
有三个设计细节值得说明。
状态和结果是分开的。 状态回答"它现在在做什么",error 回答"上一次出了什么问题"。所以任务失败后回到待机,原因留在 error 里,由 UI 据此展示失败态,而不是另造一个 FAILED 状态。这样"连接和执行阶段"与"本次执行结果"是两个独立维度,不会因为失败而丢失任务本身。
取消和删除是两件事。 取消是"这次不做了,任务还在列表里";删除是"这个任务彻底离场"。
迟到回调被隔离。 每一轮操作带有"代次",旧回调携带旧代次,到达时直接丢弃,不会误伤新任务。
只填 MAC,任务自己寻人
任务式设计最能体现价值的,是批量场景。
以前,批量操作的客户端要先扫描,等每台设备都出现,再拿结果逐个连接、发送,还要自己维护"哪些没扫到、哪些要重扫、超时怎么办":
startScan { devices ->
for (mac in macs) {
val found = devices.firstOrNull { it.mac == mac }
if (found == null) { pendingMacs.add(mac); continue }
connect(found) { write(command) { disconnect(found) } }
}
}
现在,批量页只需要一串 MAC:
macs.forEach { mac -> sdk.submit(mac, command) } // 只有 MAC,没有设备对象
sdk.subscribe { tasks -> render(tasks) }
调用链是:
submit(mac, command) → 占位任务(设备为空,MAC 作为身份)
→ SDK 自动拉起扫描 → 任务进入 SEARCHING
→ 扫描结果到达,匹配设备身份 → 填入设备对象
→ 自动建连 → 自动发送 → 按命令保持连接或断开
输入是"目标设备 + 要做什么",输出是 SDK 自己完成寻人、建连和发送。
但需要说清楚它的适用条件,避免被理解成"任意旧 MAC 都能找到设备":
- 设备必须在广播,并且能被扫描到;
- 匹配不只比对 BLE MAC,还会归一化大小写和冒号,并比对稳定身份和广播元数据里的设备 MAC;
- 地址会轮换的设备,靠的是协议插件声明的身份字段,而不是 MAC 本身;
- 寻人超时当前是 30 秒,超时进入任务级重试,默认最多 3 次、间隔 1.5 秒;
stopScan()是唯一停止入口,会退订 UI 回调并停止底层扫描;任务需要寻人时仍可按需重新拉起。
6.2 主题二:资源调度,串行建连、分层治理
问题。 多设备场景容易走向两个极端。全部同时连:看起来快,但手机蓝牙栈和设备端都被压住,出现连接失败、GATT 异常、回包错乱,甚至设备假死。全部串行(连 A、发 A、断 A,再连 B):稳定,但批量太慢。
经验。
建连阶段要串行;已建好的连接可以保留多条;发送阶段通过固定窗口配置成并发,默认串行。
做法是把"建连""连接容量""传输窗口"拆开,各自治理:
| 层次 | 当前策略 | 目的 |
|---|---|---|
| 建连 | 串行闸门,一次只发起一个连接 | 避免多个 connectGatt 同时发起而冲突 |
| 连接容量 | 硬件体检 + 历史经验得出建议值,写入连接池,由连接池决定最终生效 | 不同手机使用更合适的连接数 |
| 传输窗口 | 固定可配置,默认 1 台,手动设为 N 才并发发送 | 在稳定性和吞吐之间留出调节空间 |
| 单设备内部 | GATT 操作串行 | 保证协议命令顺序和状态正确 |
类比一下:建连像停车场入口,一次只放一辆车;车停好后,卸货区默认开一个窗口,也可以按现场能力手动开多个。
注意这套机制有一个隐含前提:全局只有一个"停车场入口"。如果多套 SDK 各自开了一个入口,串行闸门就形同虚设。这正是第 7 节要解决的问题。
关于并发学习器,要说实话。 学习器的规则已经实现:一轮全部成功则建议 +1;失败率偏高则建议 −1(不是减半);失败过的并发度会被记为上限,避免来回震荡;样本太少、中途取消、整批失败时跳过本轮;结果可持久化。但是:
批量结果自动回灌学习器的闭环,在当前主链路里尚未接通。 目前是在初始化和手动切换时应用建议值。我不会说"每批执行完都会自动调整并发",因为这还没有做完。
6.3 主题三:异常治理
设备换地址、扫描假死:稳定身份、新鲜地址与扫描自愈
很多 SDK 把 MAC 当身份证。但真实设备会轮换地址、交替广播身份帧和数据帧;扫描跑久了还会出现系统不回调、息屏后失效、系统扫描器"隐形降级"等问题。
做法是把"设备是谁"和"这次用什么地址连"拆开:
- 用稳定身份标识同一台设备,地址变化后据此重新找到它;
- 连接前判断地址是不是刚扫到的"新鲜地址",避免拿旧地址盲连;
- 设备离开范围时置灰而不是立刻删除,身份帧和数据帧归并为同一台设备;
- 扫描有看门狗:长时间无广播则重启、亮屏时检查、周期性重新注册,旧会话迟到的回调不污染新会话。
假死连接:心跳与自动重连
STATE_CONNECTED 只表示某一刻链路建立了。设备可能走远、重启、掉电,页面却还显示"已连接"。
做法:设备空闲时按协议能力发心跳(业务收发本身就是存活证明,不额外打扰);心跳与业务命令走同一条按设备串行的链路,不会插队串包;连续不响应达到阈值(默认 2)后,判定离线、主动断开、等待设备重新广播,再按退避策略重连。主动断开与意外断开分开处理,不会把用户取消误判成故障。
重连默认是关闭的(OFF),需要在命令里显式声明恢复策略。
手机发完不等于设备收齐:传输治理
手机端写完最后一片,只说明本地写回调成功。
做法:先做能力协商再分片;用有限在途窗口做流水线;链路拥塞时回退并延迟重发,保证顺序;设置停滞检测;进度按任务节流;用发送代次丢弃取消或重试之前的迟到进度;最后以设备回执核对字节数和片数,区分"手机发完"和"设备收齐"。
只有一个 GATT 数字:设置中心、阶段日志与错误诊断
出问题时最常见的信息是 133、8、19 这样的数字。做法是:强类型的设置中心统一登记参数,拼错名字或类型不匹配会立即抛错而不是静默失效;日志按扫描、连接、传输、任务分阶段;常见 GATT 状态码翻译成"什么问题、怎么排查";任务自带状态、进度、结果和错误,天然是诊断上下文。
7. 主线 B:多 SDK 治理,宿主加协议插件
7.1 设计目标:一个所有者,多种协议
回到第 4.2 节的根因:BLE 资源共享,却没有所有者。青竹的做法是让宿主成为唯一的所有者,协议差异则下沉到插件。
并存时代 青竹架构
App App
├─ SDK A(自带扫描/连接/重试) └─ 青竹宿主
├─ SDK B(另一套实现) ├─ 任务池与生命周期
├─ SDK C(又一套) ├─ 扫描会话 / 连接池 / 建连节奏
└─ 若干基础封装库 ├─ GATT 操作队列 / 传输治理
├─ 设置、日志、统一错误模型
└─ 协议插件 A / B / C(只声明差异)
核心调度层不认识具体设备,只认识统一的插件契约。这样,第 6 节里的串行建连、连接容量、统一扫描会话、任务调度,都有了唯一的落脚点。
7.2 职责划分:什么留在宿主,什么交给插件
| 宿主负责(公共能力) | 插件负责(协议差异) |
|---|---|
| 任务池、状态机、生命周期 | 协议 ID |
| 扫描会话、看门狗、自愈 | 广播识别器与扫描配置 |
| 连接池、串行建连、连接容量 | 稳定身份字段 |
| GATT 单飞队列、超时、取消、重试 | 连接前钩子与 GATT 就绪钩子 |
| 传输窗口、拥塞退避、回执核对框架 | 心跳指令与节奏 |
| 设置中心、阶段日志、统一错误模型 | 协议自己的配置参数 |
| 按协议 ID 路由消息 | 消息处理器(install 时注册) |
判断一段逻辑放哪里的标准很朴素:如果换一种设备它也一样,就属于宿主;如果它由某个设备的协议决定,就属于插件。
7.3 插件契约
| 插件声明什么 | 作用 |
|---|---|
| 协议 ID | 字符串对象而非枚举,新增协议不改核心 |
| 广播识别器、扫描配置 | "这条广播是不是我的设备" |
| 身份字段 | 地址轮换时,用什么识别同一台设备 |
| 连接前钩子、GATT 就绪钩子 | 重寻址、协议准备、能力协商 |
| 心跳指令与节奏 | 这台设备的心跳命令、间隔、容错 |
| 配置参数 | 协议自己的可配置项和默认值 |
| install 装配 | 注册消息处理器,核心按协议 ID 路由 |
注册是幂等的,重复注册不会重复装配。插件贯穿扫描、身份、连接、心跳、消息路由和断开清理的完整生命周期。
插件化不是把
if/else搬到另一个文件,而是把协议从识别、扫描、连接、配置、心跳到消息路由的完整生命周期交给插件自治,同时让资源始终由宿主统一管理。
7.4 交付形态:一个宿主,按需组合
一个宿主 AAR,加每种设备类型一个 AAR。 App 只引入宿主和需要的插件(目录和文件名为教学示例):
libs/
├── ble-core-sdk.aar 宿主(必须,只有一个)
├── ble-device-type-a.aar
└── ble-device-type-c.aar
不同产品线可以按插件组合交付:只做设备类型 A 的产品,不必带上其他协议。
7.5 对已有多 SDK 项目:怎样迁移
对一个已经有多套 SDK 的项目,我的建议是不要重写,而是渐进收敛。这是一套方法,不是内置工具:
- 盘点。 列出各 SDK 里重复实现的公共能力,以及真正由协议决定的差异。很多"差异"其实只是重复实现的细节不同。
- 抽象。 把公共能力上移到宿主,把真正的差异定义成插件契约。
- 试点。 选一个新协议或一类新设备,先以插件方式接入,验证契约是否够用。
- 适配。 把老协议栈包成适配层,逐个迁移,让老设备先在宿主的调度和资源管理下运行,再逐步替换内部实现。
- 交付。 产品按插件组合,淘汰不再需要的 SDK 和基础库。
AI 在这个过程中很有用:它能很快找出"哪些代码长得像"、生成适配层骨架、补迁移期的回归测试。但能不能真正收敛,取决于工程师能否判断哪些差异是真差异、插件边界怎么划、兼容路径怎么保留。这部分在第 9 节再展开。
7.6 设计目标与代价
设计目标(均为目标,尚未度量):
- 新增一种协议,不需要修改宿主核心;
- 公共缺陷只在宿主修复一次,所有设备受益;
- 业务层面对统一的任务模型、状态和错误模型,不再为每套 SDK 写适配;
- 产品可以按需裁剪协议,降低包体积和依赖;
- 公共行为变更的回归范围,由"所有 SDK"收敛为"宿主 + 受影响插件"。
但统一也有代价,需要坦诚列出:
- 宿主成为所有设备的共同依赖。 宿主一旦有缺陷,影响面比单个 SDK 更大,所以对宿主的 API 兼容性、版本管理和回归测试要求更严格。
- 插件契约需要演进。 契约一旦发布就是承诺,修改要谨慎,需要版本管理。
- 当前这部分尚不完整:插件优先级、冲突告警(比如两个插件都声称认识同一条广播)、启停与版本管理、自动化测试都还没有完成,见 5.2。
8. 把设计串起来:一个批量场景,以及怎样证明
8.1 一个批量场景
前面讲的是设计,现在把两条主线串到一个场景里,看它们是否协同。
场景: 向一批 MAC 下发同一条配置命令。这批设备里,有的正常,有的地址会变,有的心跳不应答,有的根本不在场;其中还混有两种不同协议的设备。
macs.forEach { mac -> sdk.submit(mac, command) }
sdk.subscribe { tasks -> render(tasks) }
按设计,各类设备的预期表现如下:
| 设备情况 | 预期行为 | 对应设计 |
|---|---|---|
| 正常设备 | SEARCHING → QUEUED → CONNECTING → SENDING → READY | 任务式、自动寻人、串行建连 |
| 不在场的 MAC | 停在 SEARCHING,30 秒后重试,最终回到待机并保留 error | 寻人超时、任务级重试 |
| 地址会变的设备 | 断开后重新广播,即使系统换了地址,任务仍能据稳定身份找到它 | 稳定身份、新鲜地址 |
| 心跳不应答的设备 | 保持连接的设备连续无响应,判定离线,主动断开,等待广播后重连 | 心跳、退避重连 |
| 传输中途被打断 | 进度停滞触发停滞检测;回执核对不通过则不算完成 | 传输治理 |
| 两种协议的设备混在同一批 | 同一个宿主统一扫描与调度,由各自插件识别广播、按协议 ID 路由消息 | 宿主加协议插件 |
| 全程 | 任务列表持续刷新,每台设备都能看到卡在哪一步 | 任务快照、阶段日志 |
需要注意几点:心跳场景要求设备先以"保持连接"并声明了重连策略的方式连上(重连默认关闭);地址变化依赖系统的地址随机化,并不保证每次都会换;传输中断目前需要手工触发,没有自动注入;多协议混合批次是按契约设计的预期行为。
这个场景是我用来检验"这些设计是否协同工作"的,上表是设计与代码层面的预期行为,不是已经系统整理过的实测结果。
8.2 怎样证明:验证计划与当前局限
坦白说,到目前为止,青竹的设计仍然是"有经验支撑的设计主张",不是"被验证过的成果"。两层问题,需要两类证据。
第一类:通信可靠性与性能。
| 验证场景 | 基线 A(Fullstack + 循环) | 基线 B(成熟开源库 + 循环) | 青竹 |
|---|---|---|---|
| N 台设备批量配置:成功率 / 耗时中位数 / P95 | 待实测 | 待实测 | 待实测 |
| 设备中途断开 | 待实测 | 待实测 | 待实测 |
| 设备长时间无响应 | 待实测 | 待实测 | 待实测 |
| 地址轮换 | 待实测 | 待实测 | 待实测 |
| 长时间稳定运行(可选) | 待实测 | 待实测 | 待实测 |
测试条件需要固定:手机型号与系统版本、外设与固件、数据量、距离与无线环境,每个场景多轮重复,记录成功率、中位数和 P95。
第二类:多 SDK 治理的可维护性。 这类证据不是跑出来的,而是统计出来的:
| 指标 | 衡量方式 | 青竹的设计目标 | 实测 |
|---|---|---|---|
| 新增一种协议需要修改的宿主代码 | 以真实新增一个示例协议为例,统计改动的宿主文件与行数 | 0 | 待统计 |
| 同一公共缺陷的修复点数量 | 对比"多套 SDK 并存"与"统一宿主" | 1 | 待统计 |
| 业务层适配代码量 | 统计业务页面中针对不同 SDK 的适配与状态判断代码 | 显著减少 | 待统计 |
| 应用包体积 | 对比"全部协议打包"与"只带所需插件" | 随插件裁剪下降 | 待统计 |
| 公共行为变更的回归范围 | 统计需要回归的协议与设备类型 | 收敛到宿主加受影响插件 | 待统计 |
当前已知的局限也在这里说清楚:
- 从端由手机模拟,同时能模拟的设备数和服务的连接数有限,测出的上限可能是从端的,而不是 SDK 的;
- 可编程从端目前只支持手工故障场景,没有自动断言、弱信号与丢包注入、双端自动对账;
- 兼容性矩阵(机型、系统版本)和长时间稳定性,尚未系统验证;
- 可维护性指标要在真实的多 SDK 项目或可复现的模拟项目上统计,才有说服力。
企业级不是一个功能标签,而是能被测试、被观测、被长期维护验证的工程质量。这部分是我下一步最优先要补的。
9. 用工程经验指导 AI
前面形成了一个清楚的对照:AI 能很快写出扫描、连接、写入,但复杂 SDK 的难点在问题定义、边界约束和验收标准。那么怎样让 AI 不只是"写得快",而是"写进正确的工程边界"?
9.1 一个协作流程
确认真实能力与当前边界
→ 定义目标、约束、接口和验收标准
→ 设计架构和模块边界
→ 拆分任务并交给 AI
→ 构建、单元测试、Lint 与人工审查
→ 真机联调、手工故障场景、必要的性能测量
→ 把审查结论和边界清单沉淀为下一轮上下文
Fullstack 实验就是这样做的:资料输入 → 架构决策(三个隔离模块、主从不共享实现)→ 分块实现 → 工具验证 → 人工审查 → 文档写完后逐项对照源码。
最后一步发现的问题,值得单独列出:
- 学习器真实存在,但主链路还没有自动回灌;
Command.send()、settings.define()、central.runScenario()是教学抽象,不是源码方法;- 传输窗口是固定值,默认串行,不是自适应;
- 批量是循环调用单台
submit,没有submitBatch; - 任务状态里没有
FAILED。
AI 的风险不只是"代码写错",还有把合理的设计推演写成已经存在的事实。这种问题,编译、Lint、单测都发现不了。
9.2 差的提示词和好的提示词
差的:
帮我写一个高性能、高扩展性的 Android BLE SDK。
没有目标、边界和验收标准,AI 只能按常见模板生成,甚至把"应该这样设计"写成"已经这样实现"。
好的提示词,至少包含五类信息:
目标:实现扫描、连接、服务发现、Notify、MTU 和写入;Demo 完成双机联调。
资料边界:只用公开资料;不确定的能力标注"待核对",不要补造。
技术约束:主从端完全独立;每条连接内 GATT 操作必须串行;
操作超时后必须处理迟到回调;适配 Android 12+ 权限和 Android 13 GATT API。
输出要求:区分真实 API、教学伪代码和规划目标;单独列出当前不支持的能力;
不把"算法模块存在"写成"主链路已经闭环"。
验收:队列与分包有单测;Lint 无错误;APK 与 AAR 能构建;两台真机跑通;
文档明确列出不支持的能力。
经验要先变成目标、约束、接口、验收和事实边界,AI 才能真正发挥效率。
9.3 一个尚未完成的对照实验
第 3 节的结论是"差距在没人说出来的需求,而不是 AI 能力"。要把这个论点真正站稳,最直接的验证是:用上面这类带经验约束的提示词,让 AI 重新做一轮,看它补齐了什么,又仍然遗漏了什么。
这个对照实验我还没有完成,所以本文不对结果做任何预设。我会在后续补充,并如实记录两种可能:它补齐了哪些,以及哪些仍然需要工程师的判断。
9.4 工程师要交给 AI 的工程资产
| 工程资产 | 作用 |
|---|---|
| 状态机图 | 约束连接、任务、协议状态,避免回调拼接 |
| 线程模型 | 哪些状态在哪个线程改,哪些回调切主线程 |
| 错误模型 | 错误分类、原生状态、终态、回调次数 |
| 操作队列规则 | 单连接单飞、超时、取消、迟到回调处理 |
| 协议契约 | 帧格式、边界、响应核对、失败语义 |
| 插件边界定义 | 哪些属于宿主、哪些属于插件,契约如何版本化 |
| 能力边界清单 | 区分已实现、教学伪代码、规划目标、未接通的闭环 |
| 源码核对记录 | 每个技术声明对应的真实类、方法或调用链 |
| 测试矩阵与性能指标 | 覆盖正常、断连、并发、生命周期、系统版本;没数据就不写结论 |
9.5 AI 在多 SDK 收敛中的位置
多 SDK 治理是一个很适合观察"AI 能做什么、不能做什么"的场景:
- AI 擅长:扫描多套代码,找出重复实现;按已定的插件契约生成适配层骨架;为迁移期补回归测试;整理差异对照表。
- AI 不能自动判断:哪些差异是协议的真差异,哪些只是重复实现的细节;插件边界应该划在哪里;老协议栈中哪些"怪异行为"是为兼容某批设备而保留的,不能随便抹平;迁移顺序和兼容窗口怎么定。
后者需要对业务、设备和历史的理解,这些经验很少写在代码里,所以最容易被 AI 忽略,也最需要工程师来定义。
9.6 AI 能承担什么,不能自动承担什么
AI 能高效承担:生成公开 API 和数据结构;按既定状态机补齐实现;写单测和工具类;按明确的审查意见修复局部缺陷;整理文档与对照表;根据源码生成待核对的事实清单。
AI 不能自动承担:判断哪些隐性需求决定生产成败;没有数据时设定性能目标或宣称达标;决定重试、取消、幂等的安全边界;划定宿主与插件的边界;判断真机兼容矩阵和故障场景是否充分;保证文档与当前源码完全一致;对最终结果和线上责任负责。
协作方式不是"工程师写得更快",而是:工程师把问题、边界和验收标准定义清楚;AI 在约束内加速实现、测试和整理;最后由工程师做源码核对和工程判断。
10. 结语
回到开头的三个问题。
AI 独立完成一个 BLE SDK,能做到什么程度? 几百行就能做出 MVP;参考成熟开源项目,还能做出扫描、连接、Notify、MTU、串行写和双机联调的教学级 SDK。对需求明确、复杂度和性能要求不高、验收标准简单的项目,AI 已经能承担大量标准化编码工作,这会明显压缩"把需求翻译成样板代码"的工作量。(这是我的个人判断。)
从能运行到生产可用,缺什么? 缺两层东西。第一层是通信控制面:状态、调度、超时、取消、重试、恢复、诊断和验证。第二层是多 SDK 治理:当项目里的设备越来越多,谁来拥有 BLE 资源、公共能力放在哪里、协议差异怎么隔离。前者决定一个 SDK 能不能稳定,后者决定一个项目能不能长期维护。
有经验的工程师应该怎样使用 AI? 把经验变成目标、约束、接口、验收和事实边界,让 AI 在边界内加速;最后由工程师核对源码、承担判断。
三句话总结:
- AI 已能完成大量标准化编码,但"这条链路能跑通"不等于"能通过生产验收"。
- 生产级的差距有两层:单个 SDK 的控制面,和多个 SDK 并存的治理。青竹的关键设计,是用"任务、调度、治理"解决前者,用"一个宿主加协议插件"解决后者,并且让两者互相成就:只有资源有了唯一所有者,调度和治理才真正生效。当前边界已在 5.2 节列出,数据验证仍在补齐。
- 经验决定 AI 的上限。AI 最擅长在明确边界内加速实现,也最容易把推演写成事实。
工程师 AI
├─ 识别隐性需求 ├─ 生成基础实现
├─ 定义架构与插件边界 → ├─ 补齐测试和文档
├─ 制定验收标准 ├─ 按审查意见修复
├─ 核对源码事实 └─ 放大实现与整理效率
└─ 承担最终判断
最后一句话:
AI 降低了写代码的成本,但没有降低做出正确工程决策的难度。工程师负责定义问题、边界和验收标准;AI 负责放大实现、测试和验证准备的效率。经验越清晰,AI 才越可靠。
给读者的自检清单
如果你也在做设备通信类的 SDK,不妨对照一下:
- 你给 AI 的需求里,有没有写明状态机、线程模型和错误模型?
- 你的验收标准,是"能跑通",还是覆盖了断连、弱信号、并发和生命周期?
- 你怎样防止 AI 把"规划目标"和"教学示例"写成"已经实现的能力"?
- 文档里的每个技术声明,能不能对应到具体的类、方法或调用链?
- 你的 App 里,现在有几套各自扫描、各自连接的 BLE 实现?BLE 资源有没有唯一的所有者?
- 新增一种设备,需要改多少处已有代码?同一个公共缺陷,要修几处?
11. 附录
附录 A:命令模型与 Builder(真实 API)
命令是一张"说明单",字段如下:
type CONNECT | SEND
instruction 业务指令(通常为 JSON)
payload 可选的一份二进制数据
attachments 可选的多个附件(Map<String, Object>,核心只统计其中的 byte[])
keepConnected 发完是否保持连接
connectParams 连接前可能需要的参数
reconnectPolicy 意外断开后的恢复策略(默认 OFF)
构造方式:
QCommand.builder().connect().build();
QCommand.builder().connect(params).build();
QCommand.builder().send(json).build();
QCommand.builder().send(json, bytes).build();
QCommand.builder().send(json, attachments).build();
QCommand.builder().send(json).keepConnected().build();
QCommand.builder().send(json).disconnectAfter().build();
QCommand.builder().send(json).connectParams(params).build();
QCommand.builder().connect().reconnect(policy).build();
默认值与注意点:
send默认发完断开,keepConnected()才保持连接;reconnectPolicy默认OFF,不是默认无限重连;send(...)重载会清空connectParams,短连接如果还要带连接参数,需在send(...)之后调用.connectParams(params);connect()负责"连上并保持",没有后续send;- 核心只传递命令,不关心
action的含义,具体含义由协议插件解析,新增指令不需要修改任务池 API。
任务句柄:execute(command) 追加命令;cancel() 取消当前动作,任务回到待机但仍在列表中;delete() 彻底删除。SDK 门面:submit(device 或 mac, command?)、subscribe(listener)、getTasks()。
附录 B:关键设计与教学基线对照
| 维度 | Fullstack(教学基线) | 青竹的关键设计 |
|---|---|---|
| 编程模型 | 扫描、连接、写入分别调用 | 所有操作统一为任务 |
| 目标输入 | 先扫描到设备,再拿设备对象连接 | 可只提交 MAC + 命令,自动寻人、连接、发送 |
| 批量 | 客户端自行编排,逐台等待扫描 | 循环提交,由任务池统一调度、去重、重试、清理 |
| 多设备 | 每连接独立队列,无全局治理 | 串行建连、传输窗口可配置、连接容量建议 |
| 设备身份 | 按地址找设备 | 稳定身份、地址轮换、新鲜地址判断 |
| 扫描 | 启动、失败、超时、停止 | 看门狗、自愈、会话代次 |
| 断连 | 交给宿主处理 | 心跳、假死判断、主动断开、退避重连 |
| 传输 | MTU 切片,逐包写 | 有限在途窗口、拥塞退避、停滞检测、回执核对 |
| 诊断 | 错误码与 Demo 日志 | 设置中心、阶段日志、GATT 错误解释、任务快照 |
| 协议扩展 | 固定 Service 与特征 | 插件契约、注册表、消息路由、按需裁剪 |
| 多 SDK 并存 | 不涉及(单一教学实现) | 宿主唯一拥有 BLE 资源,协议以插件接入,产品按插件组合交付 |
| 验证 | 最小模拟器返回固定 OK | 可编程从端、手工故障场景、双端统计展示(自动化验证尚未实现) |
附录 C:多 SDK 现状自评表
如果你想评估自己的项目是否存在第二层问题,可以逐项打分:
| 检查项 | 是 / 否 |
|---|---|
| App 里是否有两套及以上各自管理扫描的 BLE 实现? | |
是否有两套及以上各自发起 connectGatt,且没有全局的连接数与建连节奏控制? | |
| 超时、重试、分包的逻辑,是否在多个 SDK 里各写了一遍? | |
| 不同 SDK 的状态模型与错误码,业务层是否要分别适配? | |
| 一个公共缺陷是否需要在多处分别修复? | |
| 只用到部分设备的产品,是否仍要打包全部协议? | |
| 新增一种设备,是否要新增一套 SDK 或在业务层加条件分支? |
多数项为"是",说明项目的主要矛盾可能已经不是"某一次通信够不够快",而是"BLE 能力有没有被统一治理"。