1. Native 监听：按 Android 版本分流#

Native 模块里统一监听电话状态：

• Android 12+（API 31+）使用 TelephonyCallback.CallStateListener
• 旧版本回退 PhoneStateListener.LISTEN_CALL_STATE

并把系统状态映射成业务状态字符串：

• CALL_STATE_RINGING -> RINGING
• CALL_STATE_OFFHOOK -> OFFHOOK
• CALL_STATE_IDLE -> IDLE

这一步的价值是“归一化”。后续 JS 层无需理解 Android 细节，只处理 3 个稳定状态。

2. RN 事件桥接：NativeEventEmitter 的正确姿势#

JS 侧用 NativeEventEmitter 订阅 onCallStateChanged，并在组件卸载时 remove；
Native 模块实现 addListener/removeListeners 空方法，避免 RN 新架构下的告警与兼容问题。

另一个容易忽略的点：Native 发事件前先判断 hasActiveReactInstance()。
否则 React 实例未激活时直接 emit，在某些机型上会抛异常或丢事件。

3. 为什么不走电话广播（ACTION_PHONE_STATE_CHANGED）#

理论上广播也能拿到状态，但实践里在 Android 13+ 与部分 ROM 上，动态注册标志和系统策略都更容易踩坑。
所以我选择以 Telephony API 为主通道，广播只作为历史方案参考，不作为核心链路依赖。

如果你的目标是“上线可长期稳定运行”，建议直接走 TelephonyCallback/PhoneStateListener 这条主线。

4. 状态机与防抖：避免重复转写的关键#

我用的是“状态机 + 时间窗”组合，而不是“收到 IDLE 就立刻转写”：

• 仅在 OFFHOOK -> IDLE 这个转移上触发后处理
• idleDebounceMs：压制短时间重复 IDLE
• offhookMaxAgeMs：限制必须是“最近一次真实通话”
• postCallDelayMs：挂断后延迟执行，等待录音文件落盘
• pipelineLock + lastPipelineAt：串行化后处理链路，防止并发重入

这组策略解决的是两个高频线上问题：

• 同一通话被重复转写
• 录音文件还没写完就开始识别，结果空文本或失败

下图把「状态归一 + 转移触发 + 防抖/时间窗 + 延迟扫描」压成一条可读路径（与前台服务里的实现思想一致；RN 前台链路也会做类似的 OFFHOOK -> IDLE 判断，但后台兜底仍以前台服务为准）：

5. 前台服务与 JS 的协同边界#

这里我专门做了职责切分，避免“两边都转写一次”：

• App 非前台：JS 收到 IDLE 也不执行转写，交给前台服务处理
• App 前台：JS 可执行前台链路（用于更快反馈）

也就是说，前台服务是最终兜底通道；JS 是增强通道，不是唯一通道。
这个边界明确后，架构会稳定很多。

6. 权限时序：先授权再 startListen#

READ_PHONE_STATE 没拿到时，即便 startListen() 调用了，系统通常也不会回调。
正确顺序是：

1. 先检查/申请权限
2. 权限通过后再 startListen
3. 页面销毁或不再需要时 stopListen

并且要把“模块不可用”“权限被拒绝”两类失败区分展示，方便用户自助处理。

1. Gradle：vosk-android 与 JNA#

vosk-android 依赖 JNA 做本地库加载。若只引 Vosk、不处理 JNA 的打包形态，真机上常见直接崩：

UnsatisfiedLinkError: ... libjnidispatch.so not found in resource path

做法是：显式引入 JNA 的 AAR（内含各 ABI 的 libjnidispatch.so），并在 Vosk 依赖里 exclude 掉它自带的 jna 模块，避免版本/打包冲突。示例：

1
// Vosk 依赖 JNA；须使用 jna 的 AAR（内含各 ABI 的 libjnidispatch.so）
2
implementation("net.java.dev.jna:jna:5.13.0@aar")
3
implementation("com.alphacephei:vosk-android:0.3.38") {
4
    exclude group: "net.java.dev.jna", module: "jna"
5
}

版本号可按官方发布更新；关键是 AAR + exclude 这一对组合，不要只写一行 vosk-android 就以为万事大吉。

2. 模型放进 assets：目录名与必备文件#

从 Vosk 模型列表 下载中文小模型（示例目录名 vosk-model-small-cn-0.22），解压后整个目录放到：

android/app/src/main/assets/vosk-model-small-cn-0.22/

模型是否“真的打进 APK”，不要靠猜，建议在代码里做一次 必备文件探测（打开 assets 流读第一个字节），例如校验这些相对路径是否存在且可读：

• uuid
• am/final.mdl
• graph/HCLr.fst
• ivector/final.ie
• conf/model.conf

任意缺失都视为 模型未就绪，在 UI 上给出明确提示，而不是等到 unpack 或 Recognizer 才报错。

3. 首次加载：StorageService.unpack 解压到应用私有目录#

assets 里的是压缩包式资源，运行时一般要解压到应用可写目录。vosk-android 提供 StorageService.unpack：

• 入参：context、assets 下模型目录名、解压目标子目录名（如 "model"）
• 成功回调里拿到 Model 实例
• 失败回调里拿到异常（磁盘空间、IO、资源损坏等）

业务侧建议把 Model 做成 进程内单例（@Volatile + synchronized），避免前台服务与 RN Module 各加载一份、占双倍内存。

4. 线程模型：不要在主线程解压 / 转写#

unpack 与转写都是重活。推荐固定套路：

• RN 暴露的 @ReactMethod：只做 executor.execute { ... promise.resolve/reject }，避免阻塞 JS 桥
• 前台服务里同步转写：单独 Executor + CountDownLatch 阻塞等待完成，保证服务逻辑串行、可预期

同一套转写逻辑建议抽成 Helper 单例（例如 VoskTranscribeHelper），Module 与 Service 共用，避免两份实现漂移。

5. 调用转写：Recognizer 只吃「16 kHz 波形」#

Vosk 的 Recognizer(model, 16000.0f) 表示 16 kHz 采样率。因此输入音频必须归一到这条约束：

其它后缀直接在原生层 reject 或抛 IllegalArgumentException（例如「仅支持 wav/m4a/mp3」），RN 侧映射成 UNSUPPORTED_FORMAT，不要默默返回空字符串让用户以为“识别很差”。

解码路径上要特别注意：

• 选第一条 audio/ MIME 的轨道
• 处理 INFO_OUTPUT_FORMAT_CHANGED 更新采样率/声道
• finally 里 release MediaCodec 与 MediaExtractor，避免泄漏

6. 从结果 JSON 取文本#

Recognizer.finalResult 返回的是 JSON 字符串，常见形态里文本字段为 text。用 JSONObject 取 optString("text", "") 即可；解析失败时返回空串并打日志，避免整个管道因 JSON 抖动崩溃。

7. React Native 侧：薄封装 + 两类 API#

建议 RN 只暴露两个能力，命名可以贴近实际文件类型（方法名带 Wav 也行，但注释要写清支持 mp3/m4a）：

1. checkModelReady() → 返回 { ready, modelPath, message? }
   • modelPath 建议放给人看的说明（例如「在 APK 的 assets/xxx」），不要假装是磁盘绝对路径
2. transcribeWavFile(absolutePath) → 返回 { text, path }

TypeScript 侧用 NativeModules 强类型包一层，统一处理「模块不存在」（未编译进 dev client）的情况：

1
const { VoskTranscribe } = NativeModules as { VoskTranscribe?: VoskTranscribeModuleType };
2

3
export const transcribeService = {
4
  isAvailable() {
5
    return Platform.OS === 'android' && !!VoskTranscribe?.transcribeWavFile;
6
  },
7
  async transcribeWavFile(filePath: string) {
8
    if (!this.isAvailable()) throw new Error('离线转写模块不可用');
9
    return VoskTranscribe!.transcribeWavFile(filePath);
10
  },
11
  async checkModelReady() {
12
    if (!this.isAvailable()) {
13
      return { ready: false, modelPath: '…说明需完整编译安装…', message: '…' };
14
    }
15
    return VoskTranscribe!.checkModelReady();
16
  },
17
};

页面或业务里推荐顺序：

1. 先 checkModelReady()，未就绪则提示卸载重装 / 检查 assets
2. 再对扫描到的绝对路径调用 transcribeWavFile

原生 Promise 侧建议区分：

• FILE_NOT_FOUND：路径错或文件尚未写完
• UNSUPPORTED_FORMAT：后缀或解码失败
• TRANSCRIBE_FAILED：其它运行时错误

这样 UI 可以针对性提示，而不是统一「失败请重试」。

8. 排障速查表#

转写结果侧若要做产品化，可额外带上 sourcePath、耗时等字段，便于统计与客服回放。