# Turbo IO · 原生鸿蒙 HarmonyOS SDK 与研究客户端

> **停止更新（2026-09-27）**：本目录保留既有研究源码和历史验收记录，作者不再维护、移植新功能或适配新固件。下面的“当前版本”和能力描述均指历史研究版本，不代表与最新 iOS / Android 同步。已知问题不再安排修复，后续开发请自行评估。

面向开发者的雷鸟 iO / RayNeo iO **原生 HarmonyOS** 客户端，ArkTS / ArkUI + BLE 协议 HAR。不运行 Android APK，不注入官方 App，也不需要 Root。

**这是学习研究用源码，不是给小白下载即用的成品。只发布源码，不提供 HAP / IPA / APK、预签名包、代签服务、证书或任何维护者 Key。** 沿用仓库 [PolyForm Noncommercial 1.0.0](../LICENSE)，仅非商业使用；第三方组件保留各自许可。

本次版本 **WORKBENCH 14 / 0.1.14**。主要测试设备：Mate X5，HarmonyOS 6.1 系列；工程 target API24、compatible API23，**API23 及其他机型没有全面实测**。详见 [验收与已知问题](VALIDATION.md)。

## 可以做什么

- 无官方账号的蓝牙发现、配对、认证、初始化、电量读取与自动重连。
- 眼镜唤醒 → 阿里实时 ASR / 云端 VAD → 自有 OpenAI 兼容模型 → 识别文字与回答显示，回答完成后退出。API 与提示词由用户填写。
- 待办下发、模拟天气、自定义短文字卡已获镜片确认；实时天气需自行配置和风。
- 原生高德地点搜索、步行/骑行/驾车路线代码，模拟/真实导航入口；指引文字发送到眼镜持续显示。**目前实际验收为步行算路和模拟镜片显示，不是完整外场验收。**
- App 内手动自定义通知、资料时间轴、Markdown / 文件导出等研究入口；平台能力不能与 iOS 混为一谈。

### 先知道这些限制

- **地图底图目前白屏**，尚不能承诺地图选点可用；先用文本搜索选目的地。
- 骑行/驾车已接原生接口并有自动测试，尚未做本版本真机验收；真实 GPS、偏航、弱信号和外场到达也未验全。
- 导航目前仅前台：离开导航页/退后台会停止，与蓝牙后台任务是两回事。
- 手机发起录音及眼镜菜单提词器仍有问题，暂不作为本版核心可用功能。
- WB14 插话与 TinyFish Tools 代码已接并测试，尚未完成这个安装版本的真人复验；模型响应当前不是 SSE，取回后分段显示；没有 TTS。
- 鸿蒙系统通知转发未实现；Codex / Claude Code / 其他 Agent 工具也未迁移到鸿蒙，不能套用 iOS 验收。
- 不能替换眼镜固件 UI，不能安装任意眼镜 App。自定义卡片能力有限，不是任意 Canvas/HTML。

## 从源码安装

### 1. 准备环境

1. 安装华为官方 [DevEco Studio](https://developer.huawei.com/consumer/cn/deveco-studio/)，安装 HarmonyOS SDK / Native 工具链。本项目本机基线是 DevEco Studio 6.1.1.268、API24。
2. 准备华为开发者账号与可用于目标手机的**自己的调试签名/Provision**。账号、设备注册和有效期要求以华为开发者平台为准。
3. 手机打开开发者模式与 USB 调试，USB 连接电脑，解锁并确认信任/调试授权。不能仅凭插上线就认定设备可用。
4. 从仓库克隆，**保留整个目录结构**：`core-probe/Vendor/opus-1.5.2` 是鸿蒙音频编译依赖。高德 SDK 由 ohpm 下载，不需要官方 APK/IPA。

```sh
git clone https://github.com/Turbo1123/Turbo-IO.git
cd Turbo-IO/harmony-sdk
# 仅首次创建；不要覆盖已有本机签名。
test -f build-profile.json5 || cp build-profile.example.json5 build-profile.json5
```

Windows 用户用资源管理器把 `build-profile.example.json5` 复制为 `build-profile.json5`；不要修改模板中的 `useNormalizedOHMUrl: true`（高德 bytecode HAR 需要）。

### 2. 配置自己的签名

DevEco 打开 **`harmony-sdk` 目录**，等待项目同步和 ohpm 依赖安装。进入项目签名配置，登录自己的开发者账号，为当前 Bundle 配置/生成目标手机可用的调试签名。不要使用或索取维护者证书。

- 默认 Bundle：`org.turboio.harmony.research`。首次可保留；若修改，需同步 `AppScope/app.json5`、`BluetoothBackground.ets` 的 WantAgent Bundle 和 `NotificationSession.ets` 的来源标识，再更新高德绑定。
- `build-profile.json5`、私钥、密码和 Provision 必须留在本机，已加入忽略规则。
- **高德绑定的是完整签名 App ID，不只是 Bundle。** 用自己的签名重新编译后，App ID 与维护者不同，需要申请自己的鸿蒙 SDK Key。

### 3. 编译与安装

DevEco 选择已解锁的真实手机，运行 `entry` / `EntryAbility`。首次根据系统提示确认安装和权限。已有数据时优先覆盖安装，**不要为排查问题直接卸载或清数据**。

macOS 也可使用：

```sh
bash scripts/build-macos.sh hap
# 可选：单独构建协议 HAR
bash scripts/build-macos.sh har
```

`DEVECO_HOME` 可指定 IDE 的 Contents 目录。HAP 输出到 `entry/build/default/outputs/default/`；未配置签名时只有 unsigned，不能当作可安装包。脚本只编译，不自动安装。

若使用 HDC，先 `hdc list targets` 核对自己的手机，再用 `hdc -t <目标设备> install -r <本机生成的 signed.hap>` 覆盖安装。设备锁屏或未信任时先解决手机授权，不绕过系统限制。

## 配对眼镜

1. **首次从官方切换**：在官方 App 解绑 → 原手机系统蓝牙“忽略此设备” → 长按眼镜按钮约 5 秒，蓝灯持续闪烁。
2. 开 Turbo IO 按向导允许蓝牙，选择正确眼镜，确认系统配对弹窗。
3. 等待认证、状态回读及电量出现；“扫描到设备”不等于已绑定。
4. 不要与官方 App 同时抢连。已经绑定 Turbo IO 后，日常打开 App 自动重连，不必重复解绑/重置。
5. 后台蓝牙首次在设置页开启，等待系统授予持续任务。小时级锁屏稳定性、进程被杀后的恢复尚未全面验证，不能保证永不掉线。

## 服务配置

所有 Key 默认空，保存在本机 AssetStore。输入框留空代表保留已经保存的值，不回显旧 Key。**不要把 Key 发到 Issue/PR/截图，也不要放进源码。**

| 服务 | 需要自己填写什么 | 说明 |
| --- | --- | --- |
| 阿里流式 ASR | Host、模型名、Key | 使用自己开通的实时识别服务；通用 Host 不代表你的模型已获权限，专属网关需填自己的 Host |
| 大模型 | HTTPS OpenAI 兼容地址、模型名、Key、提示词 | 配置完成后默认语音待命；只有眼镜唤醒才收音，不是常驻上传 |
| TinyFish | Key、搜索工具开关并保存 | 只注册 `web_search`；当前鸿蒙未接 Codex 工具；会把搜索查询发往搜索服务 |
| 和风天气 | API Host、Key、城市/位置 | 未配置不编造实时天气；模拟发送不是实况 |
| 高德 | **鸿蒙 SDK Key + 完整 App ID 绑定** | 不能用 iOS/Android/Web Key；首次显式同意地图服务说明 |

录音文件上传 ASR 必须逐条手动确认；本地原件保留。服务费用和配额由使用者承担。

## 导航怎么测试

1. 高德控制台创建自己的鸿蒙 Key，绑定本机签名的完整 App ID；获取方式见 [官方入门](https://lbs.amap.com/api/harmonyosnext-navi-sdk/gettingstarted)。不要复制维护者 App ID。
2. 「功能 → 导航 → 服务配置」填写 Key，阅读隐私政策后启用地图服务。SDK 将处理鉴权/网络信息；搜索词和起终点发送给高德；真实模式使用精确位置。
3. 室内先关闭“使用我的定位”，填写出发地（例如北京站）。填写目的地 → 搜索地点 → 点选结果。当前地图白屏问题未解决，**先不要依赖地图选点**。
4. 选步行，点“规划路线”；失败会显示错误码。手填起点使用城市内首个匹配，请核对路线。
5. 点“模拟并显示眼镜”，观察距离/转向变化。**模拟模式不读取当前位置，也不代表真实导航已验收。** 不需要去官方字幕页初始化。
6. 点“停止导航与镜片显示”。如果退出未确认，实际用眼镜按钮返回首页后再点“确认眼镜已回首页”。不要虚假确认。
7. 外场真实导航需打开“使用我的定位”、允许精确定位、重新规划；保持 App 前台。请以道路标识为准，不在驾驶中调试或依赖研究版保障安全。

本轮步行例：约 5.2 公里 / 37 路段，已收到模拟 SDK 回调，用户确认眼镜可见。骑行、驾车与地图渲染分别验收，不将步行结果外推。

## 通知与权限

### App 内手动通知

这是 Turbo IO 通过蓝牙主动发送自定义文字，**不是获取其他 App 的通知**。需要连接眼镜、蓝牙权限，以及「通知」页的通知总开关。可以使用合成测试文字，不需要先上传私人通知。

### 鸿蒙系统通知转发（未实现）

转发微信等通知，需要完整权限链：

1. 满足 `ohos.permission.SUBSCRIBE_NOTIFICATION` 对应用/签名/证书授权的要求。当前构建 SDK 定义为 `system_basic` / `system_grant`，支持 Provision 授权；**不是普通 normal 应用仅声明后就自动拥有**。
2. 实现 `NotificationSubscriberExtensionAbility`，通过官方通知订阅扩展 API 建立蓝牙设备订阅。
3. 再由用户在系统通知订阅设置中明确授权，选择可转发的应用。普通“允许 Turbo IO 发送通知”开关不等于允许它读取其他应用通知。
4. 获取最小必要文本，过滤敏感内容，不默认入库、不默认发给模型，并支持撤回授权。

**本版没有实现这条链，也没有承诺开发者普通个人签名一定能获批。** 具体资格、申请流程与系统页面以华为最新要求为准；权限申请路径仍需确认，不应伪造系统应用、修改 APL 冒充权限或建议用户反复开关无关设置。参考 [华为通知订阅扩展](https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/notification-subscriber-extension)。

### 权限速查

| 能力 | 权限或用户动作 | 缺少时 |
| --- | --- | --- |
| 连接眼镜 | 蓝牙授权、系统配对确认 | 无法连接，不重置用户设备 |
| 后台蓝牙保持 | 开启本 App 开关并由系统授予持续任务 | 只做前台，不假称后台已生效 |
| 真实导航 | 高德同意状态、系统定位开启、精确定位 | 提示错误，可改模拟测试 |
| 手动通知 | 蓝牙连接、应用内通知总开关 | 不发送 |
| 系统通知转发 | 特殊订阅权限/证书、扩展实现、用户授权 | **本版不支持** |
| 云 ASR/模型/搜索 | 网络与本人服务配置 | 提示配置/网络错误，不复用维护者 Key |

## 测试与贡献

```sh
# 需要 Node.js 22.18+，以及安装了 ArkTS 工具链的 DevEco。
node --test tests/*.test.mjs
```

本版 243 项测试覆盖真实 ETS/TS 代码与模拟平台 API，**不是 243 项真机功能验收**。源码/测试/编译/安装/协议回执/镜片显示是不同层次。提交问题请附版本、脱敏错误码和复现步骤；不要附签名、Key、录音、私人聊天或设备唯一标识。

### 后续优先级

1. 地图白屏、地图选点、骑行/驾车与真实外场导航验收。
2. 插话与 TinyFish 真机回归、锁屏/断连恢复长期测试。
3. 系统通知订阅权限路径与可选转发。
4. 手机起录和眼镜菜单提词器列表握手，放在后续研究，不阻塞这次源码发布。

依赖许可见 [第三方说明](../THIRD_PARTY_NOTICES.md)。请自行编译签名，不向项目索取现成安装包。