AI 时代,如何做一个生产级 Android BLE SDK ?

6 阅读43分钟

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-…

目录

  1. 一个几百行的 MVP,为什么不够
  2. 成熟 SDK 在解决什么:开源项目与能力地图
  3. 实验:让 AI 参考开源项目,差距到底在哪里
  4. 生产级的两层差距
  5. 青竹 SDK:设计总览与能力边界
  6. 主线 A:通信控制面
  7. 主线 B:多 SDK 治理,宿主加协议插件
  8. 把设计串起来:一个批量场景,以及怎样证明
  9. 用工程经验指导 AI
  10. 结语
  11. 附录

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.5k2026-04Apache-2.0易用性不只是 API 少,要把重连、超时、分包变成统一能力
Android-BluetoothKit约 3.7k2020-02Apache-2.0成熟 SDK 要管"请求"和"连接资源",不只是"设备"(历史设计案例,不建议新项目直接使用)
RxAndroidBle约 3.5k2025-06Apache-2.0异步、错误、生命周期可以用统一模型组织,并提供 Mock 便于测试
Android-BLE约 2.9k2024-11Apache-2.0性能体验取决于队列、发送节奏、进度和取消机制
Android-BLE-Library(Nordic)约 2.4k2026-10BSD-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 的项目,我的建议是不要重写,而是渐进收敛。这是一套方法,不是内置工具:

  1. 盘点。 列出各 SDK 里重复实现的公共能力,以及真正由协议决定的差异。很多"差异"其实只是重复实现的细节不同。
  2. 抽象。 把公共能力上移到宿主,把真正的差异定义成插件契约。
  3. 试点。 选一个新协议或一类新设备,先以插件方式接入,验证契约是否够用。
  4. 适配。 把老协议栈包成适配层,逐个迁移,让老设备先在宿主的调度和资源管理下运行,再逐步替换内部实现。
  5. 交付。 产品按插件组合,淘汰不再需要的 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 在边界内加速;最后由工程师核对源码、承担判断。

三句话总结:

  1. AI 已能完成大量标准化编码,但"这条链路能跑通"不等于"能通过生产验收"。
  2. 生产级的差距有两层:单个 SDK 的控制面,和多个 SDK 并存的治理。青竹的关键设计,是用"任务、调度、治理"解决前者,用"一个宿主加协议插件"解决后者,并且让两者互相成就:只有资源有了唯一所有者,调度和治理才真正生效。当前边界已在 5.2 节列出,数据验证仍在补齐。
  3. 经验决定 AI 的上限。AI 最擅长在明确边界内加速实现,也最容易把推演写成事实。
工程师                          AI
├─ 识别隐性需求                 ├─ 生成基础实现
├─ 定义架构与插件边界  →        ├─ 补齐测试和文档
├─ 制定验收标准                 ├─ 按审查意见修复
├─ 核对源码事实                 └─ 放大实现与整理效率
└─ 承担最终判断

最后一句话:

AI 降低了写代码的成本,但没有降低做出正确工程决策的难度。工程师负责定义问题、边界和验收标准;AI 负责放大实现、测试和验证准备的效率。经验越清晰,AI 才越可靠。

给读者的自检清单

如果你也在做设备通信类的 SDK,不妨对照一下:

  1. 你给 AI 的需求里,有没有写明状态机、线程模型和错误模型?
  2. 你的验收标准,是"能跑通",还是覆盖了断连、弱信号、并发和生命周期?
  3. 你怎样防止 AI 把"规划目标"和"教学示例"写成"已经实现的能力"?
  4. 文档里的每个技术声明,能不能对应到具体的类、方法或调用链?
  5. 你的 App 里,现在有几套各自扫描、各自连接的 BLE 实现?BLE 资源有没有唯一的所有者?
  6. 新增一种设备,需要改多少处已有代码?同一个公共缺陷,要修几处?

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 能力有没有被统一治理"。