kiyoakii/xinliqiu-sdk

选用指南

AI 根据 README 整理 · 2026/10/24 08:56:29

适用场景

适用于希望自主掌控OPPO AI心力球录音数据、避免使用官方云端服务的用户。

查看 README 依据

条目表：每条 68 字节 = 64 字节名称 + u32 负载长度 负载紧接其后，按表顺序排列 enpt 信封（音频条目内部） "enpt" | u16 密钥长 | u16 nonce长 | RSA-2048 PKCS#1 v1.5 包裹的 32 字节 AES 密钥 | 12 字节 nonce | u16 0x0118 | u8 密钥版本 | u8 保留 | 密文 | 16 字节 GCM tag | u16 16 | u16 24 | "enpt" ``` 明文是 **40 字节 / 20 毫秒一包**的 Opus，单声道 16 kHz。尾部没有样本计数字段。 --- ## 安全 - 凭据与私钥由你提供，不离开进程 - 存储后端只接收密文 - 解密总是显式调用 - 无遥测、无统计、不回传 详见 [docs/security.md](docs/security.md) --- ## 常见问题 **为什么不直接用官方 App？** 官方 App 是正常路径。这个项目是给想自己掌控录音、不想走云端的人。 **能读别人的设备吗？** 不能。你需要那台设备的凭据和对应私钥。没有后门，以后也不会有。 **为什么标记重点被列为不可用？**

使用方式

通过Python库或CLI使用，支持配对、同步录音、解密音频，并可部署Cloudflare存储。

查看 README 依据

常用方法：`status()`、`inventory_totals()`、`sync_range()`、`collect_voiceprint()`、`record_start()` / `record_stop()`。 > **时长怎么算：** 容器里没有原生样本数。得到的时长是**包数 × 20ms**，与麦克风实际录制时长不等。 --- ## CLI ```bash xinliqiu capabilities # 能力边界 xinliqiu status # 是否在录 xinliqiu inventory # 存量统计 xinliqiu storage # 占用与低空间阈值 xinliqiu record start | stop xinliqiu voiceprint 30 --out ./captures xinliqiu sync 0 1800000000000 --out ./captures xinliqiu sync 0 1800000000000 --store cloudflare ``` 凭据：配对后自动记住；也可用 `XINLIQIU_DEVICE_ID` 等环境变量或命令行参数覆盖。 --- ## 给 agent 的约束

这个项目有一套 CLI 和一个 Python 库，两者等价。让 agent 用 CLI 最容易核对， 因为它每一步都能把真实输出贴出来。 1. **先看能力边界。** `xinliqiu capabilities` 的输出就是权威答案，不要基于 `unavailable` 的项做设计。 2. **同步不是幂等的。** 设备可能对同一个窗口回 `count: 0`，那是真实答复； 不要为了拿到文件而疯狂重试。 3. **音频默认不解密。** 只有显式给出私钥路径才会产出明文。 4. **失败就停。** 任何一步失败都停下来报告卡在哪里，不要循环重试。 ## 存储（可选） 不跨机器用就跳过这一节。 ### 设备里能存多少 ```python >>> ball.storage_info() {'item_count': 55, 'used_bytes': 1875120, 'free_bytes': None, 'total_bytes': None, 'pressure': 'unknown', ...} ``` **设备只报用了多少，不报总共多少。** `free_bytes` 与 `total_bytes` 是 `None`，不是编造的数字。 但设备在几个固定阈值上会有动作： | 剩余空间 | 设备行为 | |---|---|

部署要求

运行需要Python环境，依赖bleak库；配对需要蓝牙，不需要OPPO手机、账号或root。

查看 README 依据

## 这是什么 心力球是一个录音小设备。**录音用它自己里面安装的公钥加密，只有对应私钥的主人能读回来。** 这个 SDK 就是那条读回路径。 ``` 设备 ──蓝牙──► 你的代码 ──► 你的存储 ──► 你的 agent │ │ Python 库 Cloudflare / CLI ``` 两种接口，同一套实现：Python 库与 CLI。协议全部在本仓库内实现，运行在 `bleak` 上。 > **非官方项目。** 与 OPPO 无关联。只用于你自己拥有的设备和你自己的凭据。 > [法律声明](LEGAL.md) --- ## 能力边界 这张表就是 SDK 运行时返回的数据，会原样交给你的代码和 agent。 **可用** | 能力 | 说明 | |---|---| | 鉴权 | 复用已有凭据，不需重新配对 | | 读状态 | 是否在录、电量、错误码 | | 库存统计 | 某时间段内的条目数与字节数 | | 按范围取回 | 拿到设备时钟窗口内的容器 | | 解密 | RSA 解封装 + AES-256-GCM，用你的私钥 | **可用，但有前提** | 能力 | 限制 | |---|---|

**设备是投递队列，不是可重读的档案库。** 每次同步交付的是「尚未交付过」的容器； 同一个容器只会来一次。所以： - 第一次同步通常就把待发内容全部取回； - 之后对同一窗口再同步会得到 `count: 0`，那是真实答复，不是失败； - **丢掉一次交付就再也取不回来了。** 落盘位置要可靠，别把 `--out` 指向临时目录。 --- ## 开始使用 **不需要 OPPO 手机、不需要 OPPO 账号、不需要 root。** ```bash pip install "xinliqiu-sdk[all]" xinliqiu scan # 找到设备 id xinliqiu pair --device <id> --out-dir ./creds # 配对，自动记住凭据 xinliqiu status # 应能正常返回 ``` 配对约两分钟，**不会格式化、不会刷写任何东西**。 ### 关于配对：两个槽位，先到先得 设备只保留**两个**凭据槽位。 ``` 槽位 0 = 你的手机 槽位 1 = 这台电脑 ← SDK 配对后占用 ``` 手机和电脑可以**同时使用**，互不影响。但**同时最多只有两台**。

已知限制

标记重点、笔记归档、AI键对话模式不可用；手机录的旧录音无法解密；设备存储容量有限，私钥丢失录音永久无法解密。

查看 README 依据

| 录音 | 只在检测到人声时生成文件。全程没说话，就什么也没有 | | 分段 | 语音间有静音会切成多个文件；单个文件约 60 秒。尾部静音会保留一小段 | | 声纹采集 | 单次 1–127 秒，适合短采样，不适合长录音 | | Opus → WAV | 容器里没有原生时长，只能按包数×20ms 推算 | **不可用** | 能力 | 原因 | |---|---| | 标记重点 (`mark`) | 蓝牙、App、实体键都没能触发它 | | 笔记归档 (`.note.opus`) | 蓝牙上无法进入该路径 | | AI 键对话模式 | 该键只是录音开关，松手不会结束 | 三项都从多个方向验证过，确实不存在。 ### 录音导出 `sync_range` 会请求一个设备时钟窗口，接收设备推送的文件： ```python result = ball.sync_range(0, now, output_dir=Path("./captures")) # {'files': [...], 'count': n, 'bytes': total} ``` 每个文件按 `setup-req` → 分块 → `complete-req` 走完，发送方给了 MD5 就校验， 不匹配则删除并报错，不会留下一个损坏的文件。

#### 再配一次不会挤掉手机 SDK 会把你第一次配对时用的槽位标识（alias）记在配置里。再次配对时 **复用它**，设备认出同一个 alias 就会**原地更新那个槽位**，不走淘汰。 所以你重复跑 `pair` 不会把手机踢出去。只有第三台全新设备才会挤掉最旧的。 #### 手机录的旧录音，解不开 手机配对时，录音公钥是 OPPO 服务器下发的（`device_security_config`）， 私钥在服务器那边。所以： | 步骤 | 能做到吗 | |---|---| | 电脑配对 | 能 | | 把已有录音的密文拉下来 | 能 | | **解成能听的音频** | **不能，永远不能** | | `init` 之后新录的 | 能，那之后用的是你的公钥 | 这个 SDK 对已有用户的意义是：**从今往后的录音归你自己。** ### 想解密，必须先给设备装一把你自己的公钥 配对（`pair`）只建立连接，不碰加密密钥。**没装过你自己的公钥，录音就无法被你解密**—— 设备用它出厂时写入的那把公钥加密，对应私钥不在你手上。 装公钥这一步（`init`）需要设备认可的一小段签名材料，那段材料只能从官方 App 的 安装包里取——**签名密钥由你自己提供，本项目不附带它**。 ```bash xinliqiu init \

丢了私钥，后果准确地说是： - **已经录下的录音**：解不开了 - **设备本身**：没坏，继续正常录音 - **新录的录音**：仍然用设备里那把公钥加密，而你手上已经没有对应的私钥了，**同样解不开** 所以丢了私钥 ≈ 失去了从这个设备读出任何可听内容的能力。没有恢复、 没有重置、没有人能帮你。 所以： ```bash xinliqiu keygen # 生成到 ~/.config/xinliqiu/owner.pem，权限 0400 ``` **生成后立即把 `~/.config/xinliqiu/owner.pem` 复制到本机以外的地方**： 密码管理器、加密备份、或一个抽屉里的 U 盘。不要把它留在项目目录里—— `cd` 一下或删个文件夹就可能没了。 找 agent 帮你接入时，它会在 `init` 之前停下来要求你先备份并确认。 详细步骤：[docs/getting-started.md](docs/getting-started.md) --- ## Python ```python from pathlib import Path from aipin_sdk import Xinliqiu, Credentials, parse_cmpt_file, decrypt_enpt, to_wav