技能介绍

要解决什么问题

在 Linux、macOS 或 Windows 上让 Agent 直接操作真实蓝牙低功耗（BLE）外设时，常见痛点是：命令语法分散在 airctl --help 里、连接状态未检查就读写 GATT、用户输入的 MAC、UUID 或写入载荷未校验便拼进 shell，以及通知流式输出导致 LLM 会话无法结束。本技能把 airctl 的常用路径固化为可复用的工作流，而不是临时猜命令。

技能如何工作

执行任何 airctl 操作前，技能要求先核对 前置条件（CLI 是否可用、包来源是否为 AirCtl），再按 决策树 选择场景：按设备名扫描并连接、读/写特征值、连接后保活，或为 Agent 做 快照轮询（airctl ble events --last N，避免无 --last 的常驻流）。

核心能力包括：

输入校验：设备地址（MAC）、别名（仅字母数字与下划线）、UUID（短码或完整 128 位）、Handle（正整数）、写入数据（hex: / text: / base64: 或无前缀按 hex 处理）、扫描过滤用的设备名（禁止 shell 元字符）。
GATT 操作：scan → connect → characteristics → read / write，支持短 UUID（如 2A19）与完整 UUID。
保活策略：优先订阅带 notify/indicate 的特征；否则周期性读只读特征；读写特征需谨慎。
常见 UUID 对照表 与 错误处理表（未配对、特征不存在、未连接、守护进程未启动等）。

适用边界与注意点

技能依赖本机蓝牙适配器与平台栈（如 Linux 上 BlueZ 5.55+）。需要配对的外设必须先由系统在 OS 层完成配对，否则会出现 “Insufficient Authentication”。不会在未获用户确认的情况下自动执行 pip install；别名中必须用下划线而非连字符。文档未列出的子命令应先 airctl --help 核实，禁止跳过决策树步骤。