BLEA

BLEA

BLEA — 蓝牙低功耗自动化 — 是一款通用的 Agent 插件，旨在安全、确定性地处理 BLE 工作。它为 AI Agent 提供可移植的技能、机器可读的 CLI、本地 MCP 服务、带防护措施的自动化，以及离线证据采集、差异比较和回放功能。

该项目专为 Agent 反复执行的 BLE 工作而设计：检查操作系统的蓝牙访问权限、查找附近合适的设备、发现 GATT 服务、保留并比较原始字节证据、在更改状态前先读取并订阅，以及仅在获得明确授权后才执行写入。

界面	作用
Agent Plugin 1.0.0	打包可移植的标识、技能和 MCP 声明。
Agent Skill	向 Agent 传授 BLE 工作流、安全边界和恢复规则。
CLI	为脚本、终端以及任何可使用 shell 的 Agent 输出确定性的 JSON/JSONL。
MCP	将相同的运行时作为本地结构化工具提供，并管理 BLE 会话。

ble 可执行文件是共用的运行时。常规子命令使用 CLI 界面；ble mcp 则启动 stdio MCP 服务。因此，MCP 协议是一等界面，并非隐藏在无关 CLI 产品中的第二个工具。

安装

BLEA 需要 Python 3.10 或更高版本。蓝牙访问由操作系统通过 Bleak 提供。

使用 Agent 提示词快速安装

将此提示词提供给可使用 shell 的 Agent：

Read https://github.com/Nitmi/blea and follow its README to install BLEA for me.

如需手动安装，请使用下方的详细步骤。

从 PyPI 安装最新发布的 Python 运行时：

uv tool install blea
ble --help

对于 Codex，请先安装运行时，再安装公开的 Git 市场包：

codex plugin marketplace add Nitmi/blea
codex plugin add blea@blea

要使用 Skills CLI 仅安装可移植的 Agent Skill：

npx skills add Nitmi/blea --skill ble

对于 OpenClaw，请从其公开的 ClawHub 列表安装相同的可移植 Skill：

openclaw skills install @nitmi/blea
# Or use the registry CLI directly:
clawhub install @nitmi/blea

Skill 会传授工作流和安全策略，但不会安装 Python 运行时。在要求 Agent 访问实时蓝牙硬件或启动本地 MCP 服务之前，请按上述说明从 PyPI 安装 blea。Skill 源文件位于 skills/ble/SKILL.md，ClawHub 公开版本为 @nitmi/blea。

安装后，请启动新的 Agent 任务。市场包提供 BLE Skill 和 MCP 声明，但不会安装 Python 运行时或操作系统蓝牙权限。有关发布标签、旧版 0.6.0 桥接方案和更新流程，请参阅 docs/installation.md。

从代码检出目录中直接通过工作树安装命令运行时：

uv tool install --editable .
ble --version

用于仓库开发：

uv sync --extra dev
uv run ble --help

独立 Windows 发行版

从 0.6.5 开始，每个发行版都包含 blea-<version>-windows-x86_64.zip，其中有一个单文件 ble.exe 和一个清单，用于绑定其 SHA-256、版本、目标平台和源代码提交。运行时不需要 Python。标签工作流会在一个 GitHub 托管的 Windows 运行器上构建两次，拒绝哈希值不一致的 ZIP，运行 ble --version 和不依赖适配器的证据回放，并生成 GitHub 构建来源证明。它不会运行 doctor、扫描或访问蓝牙硬件。

使用前请验证压缩包：

gh attestation verify blea-0.7.0-windows-x86_64.zip `
  --repo Nitmi/blea `
  --source-ref refs/tags/v0.7.0 `
  --signer-workflow Nitmi/blea/.github/workflows/binary-release.yml `
  --deny-self-hosted-runners

证明文件可证明构建来源于该代码库；它不是 Windows Authenticode 签名，也不能证明蓝牙适配器、外围设备或固件的身份。

Python 运行时和 Agent Plugin 是两个相关的安装单元：PyPI 会安装 ble 可执行文件，而 Agent Plugins 1.0.0 客户端会加载此代码库目录，以发现 plugin.json、mcp.json 和 skills/ble。请先安装运行时，以便插件的本地 stdio MCP 服务能在 PATH 中找到 ble。有关源码、插件、更新、权限和验证方式，请参阅 docs/installation.md。

CLI

ble doctor --json
ble scan --timeout 8 --json
ble inspect --device "id:AA:BB:CC:DD:EE:FF" --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --read-offset 16 --json
ble read --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a19 --json
ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble subscribe --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a37 --duration 15 --jsonl
ble observe --device "id:AA:BB:CC:DD:EE:FF" --duration 10 --jsonl
ble diff before.blea.jsonl after.blea.jsonl --json
ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble exchange \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --write-characteristic 12345678-1234-1234-1234-1234567890ab \
  --notify-characteristic 87654321-4321-4321-4321-ba0987654321 \
  --text ping --duration 5 --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" --jsonl

只有当观测到的设备中恰好有一个设备名称匹配时，才接受该设备名称。优先使用 scan 返回的平台标识符；在 macOS 上，这通常是 UUID，而不是 MAC 地址。

每个二进制值都包含 length、hex、base64 和可安全替换的 UTF-8 表示形式。 JSON 错误使用稳定的原因和退出代码，便于 Agent 恢复。

probe 使用分页。请持续读取 next_read_offset，直到其值为 null。分页计数和特征级别的失败信息位于 read_page 下；ok=true 表示页面已执行，而 read_page.has_failures 会告知是否有任何特征读取失败。每个结果都包含简短的 profile_summary。CLI 默认包含完整的 GATT 配置文件，并支持 --no-include-profile；MCP 工具默认省略该配置文件，以便重复分页时保持内容简洁。

连接命令会报告 timeout_scope=per_backend_operation。其超时分别应用于发现、连接和每项 GATT 操作，而不是限制整个命令的总耗时。GATT 条目包含 uuid_namespace。BLEA 仅针对规范的 Bluetooth Base UUID 报告库描述，以避免根据自定义 128 位 UUID 的前导字节推断出错误的标准名称。

observe 会发现支持 notify/indicate 的特征，并在单个连接上持续监测一段有限时长。省略 --characteristic 可选择所有支持事件的特征；重复指定该参数可显式选择多个特征。结果会分别列出订阅失败、清理失败和通知事件；没有事件的监测窗口只能作为该采样窗口的证据。

诊断后保存完整的只读证据包：

ble capture \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --output capture.blea.jsonl \
  --max-reads 128 \
  --observe-duration 10 \
  --redact-identifiers \
  --json

capture 会记录广播、规范化的 GATT 配置文件、每项可读特征的结果、有时长限制的通知、操作错误以及经过验证的最终摘要。它不会执行写入、配对或配置更改，且只有在原子关闭后才会替换目标文件。JSONL 文件是权威产物；命令的 JSON 结果则是精简摘要。Evidence Format v1 契约和确定性验证器位于 docs/evidence-format-v1.md。

无需 Bluetooth 适配器或设备，即可比较两个完整的证据包：

ble diff before.blea.jsonl after.blea.jsonl --json
ble diff before.blea.jsonl after.blea.jsonl --fail-on-change --json

diff 会验证两个 Evidence Format v1 输入，将其转换为稳定的 BLE 语义，并输出已排序的 JSON Pointer 变更。默认情况下，它会忽略采集 ID、时间戳、运行时元数据、采样时长，以及 5 dBm 以内的 RSSI 变化。使用 --strict-rssi 可进行精确的 RSSI 比较。除非有意使用 --allow-different-devices 进行跨设备比较，否则设备标识符必须一致。二进制载荷会作为整体变更处理，因此单个值发生变化时，不会分别产生 Hex、Base64 和 UTF-8 噪声。发生常规差异时命令仍会成功退出；--fail-on-change 会在打印完整结果后返回代码 3，供 CI 使用。契约位于 docs/diff-format-v1.md。

无需 Bluetooth 适配器或实体设备，即可重放完整的证据包：

ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl probe --max-reads 32 --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble replay capture.blea.jsonl observe --duration 10 --jsonl
ble replay capture.blea.jsonl run examples/replay-read-only.yaml --json

重放会通过与实时设备相同的只读后端接口，还原广播、GATT、读取结果、已捕获的失败、订阅结果和通知时间线。默认的 --speed 0 模式会立即且确定性地执行；在操作前指定正数 --speed，即可按该倍数保留记录的通知间隔。缺失的观测会返回稳定的 replay_miss 原因，而不是虚构值或成功结果。重放绝不会访问真实适配器，也不会发送或模拟写入或交换操作。完整契约位于 docs/replay-format-v1.md。

配对

在 Windows 和 Linux 上，显式的 OS 配对和取消配对是相互独立、受保护且仅执行一次的操作。 两者都要求使用最新扫描结果中的精确 id: 选择器、--allow-pairing，以及与解析出的标识符相同的 --confirm-device。发现设备的默认时长为 5 秒（--scan-timeout），与配对操作单独的 60 秒超时不同。取消配对会移除 OS 配对关系，并可能断开其他客户端的连接，因此请先关闭任何活动的 BLEA 会话。这两种操作都不会自动重试， 并且都会返回结构化 JSON 结果。macOS 不支持通过 Bleak 显式配对/取消配对； 访问受保护的 GATT 时，OS 会提示进行配对。即使提供了配对标志，回放模式仍为只读。

ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble unpair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --json

对于需要六位 PIN 的 Windows 设备，请设置进程级环境变量，并通过 --pin-env 传入其名称。PIN 不会包含在 CLI 参数或 BLEA 的结果字段中。 例如，在本地设置 BLEA_PAIR_PIN 后：

ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
  --confirm-device "AA:BB:CC:DD:EE:FF" --pin-env BLEA_PAIR_PIN --json

此路径使用 Windows 自定义配对的 ProvidePin，并要求加密和身份验证。 它会刷新 OS 配对状态，并报告 paired_before、paired_after、pin_used 和 authentication_verified。如果设备已配对，则会报告 already_paired，但不会声称已测试所提供的 PIN。此路径不会回退到较低保护级别，也不会自动接受数字比较。使用后请删除环境变量。MCP ble_pair 接受相同的 PIN，参数名为 pin；即使 BLEA 不会在结果中包含 PIN，MCP 主机仍可能在其历史记录中保留工具参数。

不提供 PIN 时，配对使用 Bleak 的平台行为。固定版本 Bleak 1.1.1 的 Windows 后端只处理仅需确认的配对；不会收集 PIN。Linux 使用配置的 BlueZ 配对代理；BLEA 的显式 PIN 参数目前仅支持 Windows。通用配对/取消配对结果成功，仅表示后端操作完成，并不单独证明 OS 配对存储中的状态。 取消配对会移除主机上的配对关系，但无法证明外围设备已清除其自身存储的密钥。 Windows PIN 接受情况记录了经过测试的配置。

受保护的写入

写入操作同时需要 --allow-write，并要求对解析出的标识符进行精确确认：

ble write \
  --device "id:AA:BB:CC:DD:EE:FF" \
  --characteristic 12345678-1234-1234-1234-1234567890ab \
  --hex 01 \
  --allow-write \
  --confirm-device "AA:BB:CC:DD:EE:FF" \
  --read-back \
  --json

YAML 写入和交换操作还需满足另外两项保护条件：工作流必须启用写入，每个会更改状态的步骤都必须声明 dangerous: true，且其前置步骤必须成功。策略还必须包含精确的 confirm_device 标识符。请参阅 examples/guarded-write.yaml 和 examples/esp32-burst-exchange.yaml。

对于写入会触发通知的协议，请使用 exchange。它会先启用通知订阅，再执行受保护的写入，然后在限定时长内收集事件。 写入特征和通知特征可以相同，也可以不同。这样可以避免并发启动独立会话订阅和写入操作所造成的竞争条件。

如需重复执行检查，exchange 步骤可以断言确切的通知数量、UTF-8 或 Hex 内容、最后一条通知，以及订阅清理情况。使用独立的调用门控运行受保护的 YAML 工作流：

ble run examples/esp32-burst-exchange.yaml --allow-write --json

运行前，请将示例中的设备标识符和确认值替换为最新扫描返回的精确值。

MCP 与 Agent 插件

直接启动本地 stdio 服务：

ble mcp

MCP 接口包括一次性工具、离线 ble_diff 比较器、离线 ble_replay 运行器，以及有状态会话工具。会话让 Agent 只需连接一次，即可检查、读取、观测、订阅、执行带防护的请求/通知交互或写入，然后断开连接。ble_exchange 和 ble_session_exchange 会在写入前以原子方式完成订阅。 ble_pair 和 ble_unpair 提供与 CLI 相同的精确设备配对防护；它们是一次性操作，不会作用于现有 GATT 会话。 ble_session_list 会显示活动租约，ble_session_close_all 则用于显式恢复。 MCP 客户端退出时，服务会断开所有会话；默认情况下，超过 120 秒未活动的会话会被清理。将 BLEA_SESSION_IDLE_SECONDS 设为其他正数可更改超时，设为 0 则会停用闲置会话清理，但仍会在关闭时清理。

使用 ble_session_close 关闭已知会话。只有在恢复未知会话 ID、显式关闭失败或确认存在泄漏状态时，才使用 ble_session_close_all。

若要针对单个捕获文件而非硬件提供常规 MCP BLE 工具，请启动专用的回放服务：

ble replay capture.blea.jsonl mcp

每项基于回放的 BLE 操作结果都会标明证据，并包含 replay.read_only=true。即使客户端使用实时设备授权字段调用现有的写入或交互工具，ReplayBackend 也会拒绝该操作。

本仓库本身是一个 Agent Plugins 1.0.0 软件包：

blea/
├── plugin.json                        portable plugin identity
├── mcp.json                           portable local stdio MCP declaration
├── skills/ble/SKILL.md                portable Agent Skill
├── .codex-plugin/plugin.json          root ChatGPT/Codex package metadata
├── .mcp.json                          root ChatGPT/Codex MCP declaration
├── .agents/plugins/marketplace.json   public Git marketplace catalog
└── plugins/blea/                      installable Codex distribution mirror

插件配置要求在 PATH 中安装 ble 可执行文件。可移植规范会分发 Skill 和 MCP 元数据；原生蓝牙运行时的安装及操作系统权限仍由各平台负责。

本仓库还包含 server.json，这是 PyPI 分发包的官方 MCP Registry 软件包元数据。它声明了本地 stdio 服务和 mcp 软件包参数；不会宣称提供托管或远程 BLE 服务。匹配的 PyPI 版本发布成功后，发布流程会使用短期 GitHub OIDC 凭据，将此元数据发布到官方 MCP Registry。命名空间保留 GitHub 登录名的规范大小写，因为 Registry 授权和软件包所有权标记区分大小写。

根目录中的 Dockerfile 是用于 MCP 协议检查和无适配器工具的 Registry 沙箱。它会构建与版本对齐的发布检出版本并启动 ble mcp，因此发布候选版本 CI 可以在该版本发布到 PyPI 之前运行。它并不意味着容器可以访问主机的蓝牙适配器；如需执行实时 BLE 操作，请使用上文介绍的原生主机安装方式。

OpenAI 插件目录的提交仅使用可移植 Skill。BLEA 的 MCP 服务保持在本地，因为实时 BLE 需要用户的原生主机和适配器；它不会被作为公共远程 MCP 端点提供。提交文案、限制、入门提示词和审核案例记录在 docs/openai-plugin-submission.md 中。

公开的 Codex 分发包已在安装章节所示的不可变 Git 引用处注册，并通过 codex plugin add blea@blea 安装。固定引用不会在刷新市场快照时自动切换到其他版本。若要更换版本，请移除已配置的市场，在新的 v<version> 标签处重新添加市场，重新安装插件，并启动新的 Agent 任务。不要将单独安装 Python 软件包视为安装了 Agent Skill 或 MCP 声明。

平台状态

Windows 11 已通过 ESP32-S3 BLEA 测试服务完成硬件验证，涵盖发现、GATT、通知、受保护的交换、采集和回放。macOS 和 Linux 目前通过了单元测试，并在 CI 中回放相同的真实设备证据，但尚未在实体主机上测试其原生蓝牙适配器路径。在发布验收报告另有说明之前，请将这两个平台视为“已通过 CI + 回放验证；原生 BLE 硬件未验证”。

有关具体的支持级别、隐私要求、硬件验收流程和当前证据矩阵，请参阅 docs/platform-acceptance.md。

开发

uv sync --extra dev
uv run python scripts/sync_codex_plugin.py --check
uv run python scripts/check_agent_package.py
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build --clear --no-create-gitignore
uv run python scripts/check_distribution.py dist

单元测试使用虚拟 BLE 后端，不需要附近有硬件。CI 在 Windows、macOS 和 Linux 上运行。每个 CI 任务还会针对已纳入版本控制的完整证据夹具运行 examples/replay-read-only.yaml，无需适配器即可对 CLI 和 Workflow 进行端到端冒烟测试。

根目录下的 .codex-plugin、.mcp.json 和 skills 路径是 Codex Plugin 的唯一事实来源。更改这些内容后，请运行 uv run python scripts/sync_codex_plugin.py；CI 使用 --check 检查并拒绝不一致。仓库内的 Agent 软件包检查器会验证两个 Codex Plugin 根目录、其 MCP 声明、Skill 元数据和 agents/openai.yaml，无需依赖维护者个人的 Skill 目录。分发检查器还会拒绝 sdist 中缺失的 marketplace 文件，以及 Python wheel 中缺失的 Plugin 元数据。

真实适配器支持情况与 CI 分开跟踪；CI 成功不代表原生硬件支持。

发布历史记录在 CHANGELOG.md 中。维护者应遵循 docs/releasing.md，完成制品、Trusted Publishing、Plugin 和发布后检查。

配套项目

有关串口、UART、COM 端口、USB 转 TTL 和固件控制台工作流，请参阅 baud-cli。它提供适合 Agent 使用的 baud CLI 和可移植 Skill，支持带防护措施的 YAML 自动化、结构化输出以及归档的原始字节证据。