AI 翻译与自定义命令

AI 翻译与自定义命令是杰理（Jieli）iOS 蓝牙 SDK 生态中的一项能力组合：一方面通过蓝牙链路与音频设备配合实现"边说边译"（语音采集 → 识别 → 翻译 → 回放/播报），另一方面通过自定义命令通道让 App 向设备下发 SDK 标准协议之外的私有控制指令。本文档面向希望理解该能力边界、数据流向与集成要点的开发人员。

源码证据说明：本次文档生成受源码探索预算限制，未能读取到本仓库中可逐行引用的实现文件。文中对模块划分、协议帧结构、接口名称的描述基于杰理蓝牙 SDK 的公开架构约定与目录标题推断，凡未经源码验证的细节均以"待确认"标注，请以仓库实际源码为准。

Purpose and Scope

本页覆盖以下内容：

• AI 翻译能力在 App 与蓝牙设备之间的整体工作链路（录音、识别、翻译、播报）；
• 自定义命令的构造、下发、应答与回调机制，以及它与 SDK 标准命令的关系；
• 该能力涉及的关键集成点：蓝牙数据通道、协议帧格式、事件回调、云服务对接。

以下内容属于兄弟页面，不在此页展开：

• OTA 升级、固件烧录流程：参见 4.x 中 OTA 相关目录页；
• EQ/ANC 等音频参数控制：属于音频参数调节能力页；
• 设备连接与配对管理：属于连接管理页。

Overview

在杰理蓝牙 SDK（iOS）的典型产品形态中，App 通过 BLE 与 TWS 耳机、蓝牙音箱等设备通信。AI 翻译与自定义命令两条能力线共享同一条底层链路，但解决的问题不同：

1. AI 翻译（AI Translate）：解决"跨语言实时沟通"问题。典型流程是用户对着设备或手机说话，App 采集语音后调用云端 ASR（语音识别）与 MT（机器翻译）服务，得到译文后再以文本或 TTS 语音形式通过蓝牙通道回传给设备播放。其价值在于把手机的计算能力（网络、云端算力）与设备的音频外设（麦克风、扬声器）结合起来，实现低成本的随身翻译终端。

2. 自定义命令（Custom Command）：解决"标准协议之外的产品差异化控制"问题。SDK 标准协议覆盖连接、音频、OTA 等常规能力，但每个产品还有私有功能（如特殊 LED 灯效、自定义音效切换、专属设备状态查询）。自定义命令机制允许 App 按 JL 协议帧格式构造指令下发，并接收设备的应答帧，从而在不升级固件的前提下扩展产品功能。

两者在架构上正交：翻译能力是"应用层业务 + 云服务"的组合，自定义命令是"链路层透传 + 协议解析"的通道。理解这一点有助于在集成时分别定位问题——翻译卡顿多半出在云端链路，命令无响应多半出在协议帧或设备解析。

Architecture

下图展示 AI 翻译与自定义命令两条能力线在 App、SDK、BLE 通道、设备端与云端之间的整体架构关系（模块命名为通用表述，实际类名以仓库源码为准）：

flowchart TD
    subgraph sg_App["应用层 (App)"]
        UI["翻译 / 命令 UI 界面"]
        Rec["录音与音频采集"]
    end

    subgraph sg_SDK["JL SDK 层"]
        Manager["JL_Manager 核心管理器"]
        AI["AI 翻译流程控制"]
        Cmd["自定义命令构造/解析"]
        CB["协议回调与事件分发"]
    end

    subgraph sg_BLE["BLE 通道"]
        BLE["CoreBluetooth 连接"]
    end

    subgraph sg_Device["设备端"]
        Dev["蓝牙音频设备 (TWS/音箱)"]
    end

    subgraph sg_Cloud["云端服务"]
        ASR["语音识别 ASR"]
        MT["机器翻译 MT"]
        TTS["语音合成 TTS"]
    end

    UI --> AI
    UI --> Cmd
    Rec --> AI
    AI --> Manager
    Cmd --> Manager
    Manager --> BLE
    BLE --> Dev
    AI --> ASR
    ASR --> MT
    MT --> TTS
    TTS --> AI
    Dev -.->|"应答帧/设备事件"| CB
    CB --> UI

架构要点：

• AI 翻译链路：UI → AI 流程控制 → (本地录音 + 云端 ASR/MT/TTS) → 文本/语音回传 → 设备播报。翻译结果的呈现路径有两条：纯文本展示（App 内显示）与语音播报（下发设备播放）。
• 自定义命令链路：UI → 命令构造 → JL_Manager → BLE → 设备解析执行 → 应答帧 → SDK 回调 → UI。命令内容对 SDK 而言是"透传载荷"，语义由设备固件解释。
• 共享基础设施：两条链路都依赖 JL_Manager 提供的连接管理与数据通道，也都通过统一的协议回调机制把设备侧结果返回应用层。

AI 翻译能力详解

能力定位与产品形态

AI 翻译在杰理 SDK 产品中通常以"翻译模式"（Translation Mode）形式存在，典型形态包括：

• 双边对话翻译：两位用户各持一端（或轮流使用设备/手机），App 自动识别语向并交替翻译播报；
• 单向听译：App 持续监听并实时显示译文，适合会议、课堂场景；
• 语音播报：译文通过 TTS 合成后经蓝牙下发，由设备扬声器播放，适合免提场景。

端到端工作链路（翻译模式）

1. 开启翻译模式：App 通过自定义命令（或 SDK 标准命令）告知设备进入翻译模式，设备通常切换麦克风采集策略（如开启双麦降噪、提高采样率）。
2. 语音采集：设备麦克风（经 BLE 音频链路或 App 直采）采集说话人语音；在"手机拾音"形态下则由 App 录音模块直接采集。
3. 语音识别（ASR）：App 将音频流或音频文件上传至云服务，转换为文本。该环节决定翻译延迟与准确率，通常需要网络可达。
4. 机器翻译（MT）：识别文本经翻译服务转为目标语言文本；语向可由用户预设，也可自动检测。
5. 结果呈现与播报（TTS）：译文在 App 界面展示；如需播报，则将译文文本发送给 TTS 服务合成语音，再通过蓝牙通道下发播放指令（或直接下发文本由设备端 TTS 播报——是否支持取决于固件能力，待确认）。

关键设计取舍

• 云端 vs 端侧翻译：云端方案准确率高、多语种支持好，但依赖网络；端侧方案离线可用但受限于设备算力。实际 SDK 是否内置端侧翻译能力需查阅源码确认（待确认）。
• 音频回传方式：设备侧拾音回传手机需要音频上行通道，实现复杂（涉及 BLE 音频或私有音频回传协议）；手机侧拾音则实现简单但受限于手机麦克风距离。两种形态的工程复杂度差异很大，集成前应明确产品定义。

自定义命令机制详解

与标准命令的关系

杰理蓝牙协议以"命令组（group）+ 命令字（command）"组织指令。SDK 标准命令覆盖连接管理、音频控制、OTA 等。自定义命令并非独立协议，而是：

• 复用同一套 JL 协议帧格式（帧头、长度、命令组、命令字、参数区、校验），
• 但命令组/命令字取值落在厂商私有区间（或由固件约定），
• SDK 对载荷做透传，不解释业务语义。

这种设计让协议解析与业务扩展解耦：SDK 只负责"可靠送达与应答匹配"，业务语义由 App 与固件共同约定。

命令帧构成（以 JL 协议惯例描述，具体字节序待确认）

上表为通用描述，杰理 SDK 各版本帧格式存在差异，请以仓库内协议解析源码为准（待确认）。

命令生命周期：构造 → 下发 → 应答 → 回调

flowchart LR
    A["业务层选择功能"] --> B["构造协议帧 (组/字/参数)"]
    B --> C["JL_Manager 发送接口"]
    C --> D["BLE 写入设备"]
    D --> E["设备解析并执行"]
    E --> F["设备回传应答帧"]
    F --> G["SDK 解析并派发回调"]
    G --> H["业务层更新 UI/状态"]

并发与状态管理要点

• 应答匹配：多条自定义命令并发下发时，App 需要通过命令字 + 序列号（或事务 ID）匹配应答，避免回调错乱（实现细节待确认）。
• 链路状态依赖：命令下发依赖 BLE 连接状态；连接断开时发送应排队或报错，重连后按需重发（重发策略待确认）。
• 长命令分片：若自定义命令载荷超过单帧上限，可能需要分片发送与重组，SDK 是否内置分片能力需查阅源码（待确认）。

核心流程

翻译模式时序

下图描述一次"边说边译 + 语音播报"的典型时序（以手机拾音、云端翻译、设备播报为例）：

sequenceDiagram
    participant U as 用户
    participant App as App 界面
    participant SDK as JL SDK
    participant Dev as 蓝牙设备
    participant Svc as 翻译云服务

    U->>App: 点击"开始翻译"
    App->>SDK: 下发开启翻译模式命令
    SDK->>Dev: BLE 写入命令帧
    Dev-->>SDK: 应答帧 (翻译模式已开启)
    SDK-->>App: 模式状态回调
    App-->>U: 提示"请说话"
    U->>App: 说话 (App 录音)
    App->>Svc: 上传音频 (ASR)
    Svc-->>App: 识别文本
    App->>Svc: 请求翻译 (MT)
    Svc-->>App: 译文文本
    App-->>U: 界面展示译文
    App->>Svc: 请求合成语音 (TTS)
    Svc-->>App: 语音数据
    App->>SDK: 下发播放/播报指令
    SDK->>Dev: BLE 写入指令帧
    Dev-->>U: 扬声器播报译文

自定义命令时序

sequenceDiagram
    participant App as App 业务层
    participant SDK as JL SDK
    participant Dev as 蓝牙设备

    App->>SDK: 构造自定义命令 (组/字/参数)
    SDK->>SDK: 封装 JL 协议帧 + 登记待应答
    SDK->>Dev: BLE 发送
    Dev->>Dev: 固件解析执行
    Dev-->>SDK: 应答帧
    SDK-->>App: 匹配应答并回调结果
    App->>App: 更新 UI / 触发后续业务

使用示例

本次文档生成受源码探索预算限制，未能读取到可引用的实现文件，因此本页不提供虚构代码示例。

在仓库中集成该能力时，建议按以下路径检索真实源码（路径为推断，需以仓库实际结构为准）：

• 搜索关键字 translate / AI / 命令，定位翻译模式入口与自定义命令构造代码；
• 搜索 sendData / sendCmd 类方法，确认 JL_Manager 的数据发送接口；
• 搜索协议解析相关文件，确认命令组/命令字的实际定义与帧格式。

若后续补充源码证据，本页将在此处以真实代码块 + 源文件链接替换上述说明。

配置选项

以下为集成该能力时通常涉及的配置项（具体键名与默认值需以仓库实际源码与头文件为准，标注"待确认"）：

API 参考（待源码确认）

以下接口为杰理 SDK 集成时通常会接触到的能力面，签名与行为均需以仓库实际源码为准：

依据约束规则"NEVER GUESS API SIGNATURES"，本页不在缺少源码证据的情况下罗列具体方法签名；请在仓库中检索 JL_Manager 及翻译相关类后补充本节。