用 Kotlin Multiplatform 写鸿蒙特性,最别扭的一块就是"媒体 + AI"这种两边都不讲理的场景:音频渲染跑在系统音频线程上,转发一层 JS 桥就废了;小艺的语音识别、语音合成、AgentFrameworkKit 又全是 ArkTS Kit,Kotlin 够不着。一句话怎么从麦克风变成一次声场重构再变成一句朗读、以及这一切怎么被封装成业务侧三行代码的 HAR。

示例仓库:https://atomgit.com/dijun_520/kmp-ohos-agent-media
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-KMP-CMP/kotlin/tree/main-2.2.21-OH
KMP 鸿蒙社区:https://atomgit.com/CPF-KMP-CMP


0. 环境与实测设备

项目版本
开发工具DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk)
系统 APIHarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0)
hvigor6.26.8(@ohos/hvigor-ohos-plugin)
KMP/CMP 工具链kotlin 2.2.21-1.2.0 / CMP 1.9.2-1.2.0 / skiko 0.9.22.2-1.2.0(CPF-KMP-CMP 社区发布版,ohosArm64 + ohosX64 双目标)
Node.js≥ 22.11.0
实测设备华为(nova 14)

1. “音频走 ArkTS 转发一下不就行了”

既然 RN、Flutter 都已经把"小艺语音指令 → 操作闭环"趟过了,KMP 版无非是把桥接层从 MethodChannel 换成 napi。声场逻辑写进 commonMain,音频嘛,用哪个 Kit 的 ArkTS 接口放一放就行——48 kHz 的浮点数据从 Kotlin 算完,转成 ArkTS 的 Float32Array,交给某个播放 API,能有多难。

Kotlin 里渲染一帧,JSON 序列化成 base64 过桥,ArkTS 侧再解出来喂给 AVPlayer 风格的接口。真机上一跑,hilog 里每帧桥接耗时就不说了,更要命的是结构完全不对——音频不是"你算好一段放一段",是系统每个回调周期主动来向你要数据:

// OHAudio 的数据流方向:不是推,是拉
OH_AudioStreamBuilder_SetRendererWriteDataCallback(builder, callback, nullptr)
        ↓
系统音频线程周期性调用 callback(renderer, userData, audioData, audioDataSize)
        ↓
你必须在这一次调用里把「接下来要播的」填进 audioData,然后返回
        ↓
填慢了 / 没填 = underrun,听感上就是"卡一下"

也就是说,渲染函数会被系统音频线程以固定节奏调用,中途不能等锁、不能等 JS、不能分配太多内存。

另一个意外来自 AI 侧。我按惯例在 AgentFeature.ets 顶层写了 import { AgentController } from '@kit.AgentFrameworkKit',模拟器上装机、点开、闪退,一气呵成。faultlog 里只有一条不起眼的记录:

11-14 00:28:34.181  20252  20252 I C02D11/DfxSignalHandler:
    DFX_SignalHandler :: signo(6), si_code(-6), pid(20252),
    processName(com.example.immersiveoverlays), threadName(mersiveoverlays).
11-14 00:28:34.496  20252  20252 I C02D11/DfxSignalHandler:
    Finish handle signal(6) in 20252:20252.

signal 6(abort),发生在加载页面模块的阶段,连 aboutToAppear 都没进去。这个报错第 6 节会完整回收——它直接决定了 AgentFrameworkKit 那一层的写法。

所以这个题目的边界很清楚:音频线程里跑的必须是 Kotlin 本身,不是 JS;语音闭环的"大脑"(意图匹配)必须是纯 Kotlin,不依赖任何运行时;ArkTS 只保留两件事——画 UI,以及替 Kotlin 去够那些只存在于 ArkTS 世界的 Kit。

拆下来是三件事:

  • 用 cinterop 把 libohaudio.so 的 C API 暴露给 Kotlin/Native,写回调里直接跑渲染;
  • 把意图匹配、中文数字、声场 DSP 全部压进 commonMain,用 JVM 单测挡 bug;
  • 按 CPF 三方库的形态交付:Kotlin 编出 libkmpagentmedia.so,ArkTS 打成 HAR,中间 napi 只搬 JSON 字符串。

2. 效果展示

示例应用叫「随声场」:一个可见的 3D 声场——小提琴在左前方、大提琴在右前方、雨声在正后方,你可以拖滑杆、转头,也可以直接说话让它重排。这和 RN 版空间音频的"影院通路"场景刻意做了差异化:RN 版验证的是空间音频通路本身,这一版验证的是"语音指令到操作"的闭环长在声场上是什么样。

模拟器上随声场的全景:能力芯片、声场雷达、指标行

这里每一行状态都不是装饰:

  • 顶部 ASR ✗ / TTS ✗ / AgentKit ✗ / Skill 0——这是模拟器,四项能力全部缺席。这三个勾叉来自 CapabilityProbe.detect() 的真实探测结果(syscap + 实际可达性),不是写死的标签;
  • 雷达图上小提琴(蓝色高亮)已经被移到左侧——这是我刚点完示例句「把小提琴放到左边」之后的状态,hilog 里对应的回执是 reply: 小提琴放到左边;
  • 指标行 RMS/PEAK 此时是 0‰——模拟器上 OHAudio 渲染器可以创建。

语音指令「向右转四十五度」生效后的同一个界面

对比上一张,两个变化:转头滑杆从 0° 走到 45°,雷达图中央的听者三角整体旋转了 45°——而声源点没有动。这正是 listener.set 和 scene.source 两条指令的区别:转的是"你",不是"它们"。声场里所有声源的相对方位角随之重算(等功率声像 + ITD),一个指令、一次重排。

真机 TLR-AL00:ASR/TTS/AgentKit 全部点亮,正弹出麦克风授权

真机上三个能力芯片全部是 ✓:SystemCapability.AI.SpeechRecognizer、SystemCapability.AI.TextToSpeech、SystemCapability.AI.Agent.AgentKit 探测都通过。屏幕中央的弹窗是 abilityAccessCtrl.requestPermissionsFromUser 拉起的系统授权框——麦克风是 user_grant 权限,必须先授权再建引擎,顺序反了只会拿到一串 10022000xx 的错误码。

真机上音频开始渲染:RMS 110‰、PEAK 26%、STATUS render

这是全文我最想给你看的一张图:STATUS render、RMS-L/R 各 110‰、PEAK 26%。这三个数字意味着 Kotlin 写的 DSP 正在被 OHAudio 的音频线程以 48 kHz 消费。RMS 两声道相等是因为小提琴(-55°)、大提琴(+45°)、雨声(180°)三个声源的声像混合后恰好左右均衡,单选一个声源拖动滑杆就能看到明显偏移。

真机上「调起小艺」拉起的智能体承载页

点「调起小艺」,startAbility 把应用自己的 AgentHostAbility 拉到前台,页面标题「随声场 · 智能体」下面就是 AgentFrameworkKit 的 FunctionComponent(左侧那枚带光斑的「随声场」胶囊)。这是 ArkUI 组件,没有命令式 API——想调起智能体,唯一的路就是让一个 ArkUI 页面去渲染它,这也是本库要内置承载页的原因。

3. 原理:一句话从麦克风到扬声器,到底走了几步

先把整条链路的参与者摆到一张表里:

事件/调用方向所在线程应用要回答什么
invoke(method, argsJson)ArkTS → KotlinJS 线程一个 JSON 字符串(同步)
onEvent(cb) 注册ArkTS → C++JS 线程把回调包成 threadsafe function
OH_AudioRenderer_OnWriteDataCallback系统 → Kotlin音频线程未来约 10–20 ms 的立体声样本
asr.onResult / onError系统 → ArkTSJS 线程最终文本交给谁
meter 事件Kotlin → ArkTS音频线程投递 → JS 线程消费电平数据(约 100 ms 一次)
speak 事件Kotlin → ArkTS同上朗读内容(由 TTS 消费)
agentDialogOpened/ClosedAgentKit → ArkTSJS 线程双向链路是否真的通了

两个模型判断贯穿全文,先放在这里。

第一个:AudioRenderer 的写回调是音频线程,谁也不许在那里排队。 回调里做的事只有三件:从引擎取一帧、写进 audioData、返回。任何"等一下 UI"、"发一条跨线程消息再等回复"的写法都会以 underrun 的形式被用户听见。所以渲染函数必须是纯函数——给定场景状态,产出样本,不碰任何会阻塞的东西。

第二个:闭环的核心资产是"意图 → 动作"这个纯函数。 语音只是触发器之一:麦克风识别结果、示例句按钮、模拟器上的文本兜底,最终都汇到同一个入口 voice.dispatch(text)。匹配、槽位抽取、动作应用、回复生成全在 commonMain 的纯 Kotlin 里——这意味着它可以在 JVM 上被 15 个单元测试反复蹂躏。

链路上有两处降级是设计出来的,不是出了事故再补的:

  1. 模拟器没有 agentKitHsp——AgentFrameworkKit 的动态 import 会失败,被 check() 接住后 isAvailable() = false,openAgent 返回明确的文案,而不是崩溃;
  2. 模拟器没有离线 TTS 音色——textToSpeech.createEngine 抛 1002300005,speak() 捕获后只打日志。

4. 工程怎么搭

kmp-ohos-agent-media/
├── kmp-agent-media-core/               # KMP 模块:大脑 + 耳朵
│   ├── build.gradle.kts                #   ohosArm64/ohosX64 目标 + cinterop 配置 + 产物同步任务
│   ├── src/commonMain/kotlin/.../
│   │   ├── SpatialDsp.kt               #   纯数学:等功率声像、Woodworth ITD、距离/仰角衰减
│   │   ├── SpatialMixer.kt             #   三种音色合成(小提琴/大提琴/雨声)+ 立体声渲染
│   │   ├── Intent.kt                   #   中文数字解析 + 三路加权意图匹配
│   │   ├── SkillCatalog.kt             #   7 个声场 Skill:话语 → 动作的解释器
│   │   ├── AgentMediaEngine.kt         #   会话状态机 + call() 分发 + 事件广播
│   │   └── Json.kt                     #   手写最小 JSON(commonMain 不能引 kotlinx.serialization)
│   ├── src/ohosMain/kotlin/.../
│   │   ├── OhaudioBackend.kt           #   cinterop 直调 libohaudio,音频线程入口
│   │   └── Bridge.kt                   #   @CName 导出 5 个 C 符号给 napi 层
│   └── src/commonTest/                 #   15 个 JVM 单元测试
├── harmony/agent_media/                # ArkTS HAR:嘴 + 手
│   ├── src/main/cpp/napi_init.cpp      #   napi 桥:call/onEvent + threadsafe function
│   ├── src/main/cpp/include/arm64-v8a/ #   Gradle 同步进来的 K/N 头文件
│   ├── libs/arm64-v8a/                 #   Gradle 同步进来的 libkmpagentmedia.so
│   └── src/main/ets/
│       ├── AgentMedia.ets              #   门面:业务侧唯一需要认识的类
│       ├── NativeBridge.ets            #   napi 调用 + JSON 解码 + 事件分发
│       ├── Capability.ets              #   能力探测(syscap / canOpenLink / 技能列表)
│       ├── SpeechFeature.ets           #   ASR + TTS(全部懒加载 + 降级)
│       ├── AgentFeature.ets            #   AgentFrameworkKit 薄封装(动态 import)
│       └── Types.ets                   #   扁平数据接口(ArkTS 严格模式友好)
├── example/ohos/                       # 示例「随声场」
│   └── entry/src/main/ets/pages/
│       ├── Index.ets                   #   雷达图 + 滑杆 + 按住说话 + 日志
│       └── AgentHost.ets               #   智能体承载页(FunctionComponent)
└── scripts/oh_run.sh                   # 一键:K/N 编译 → HAP → 签名 → 安装 → 启动

这次整理最关键的变化,是把"能跑"变成"能复用",三条边界划死:

  1. lib 不依赖页面。HAR 里没有任何 @Entry 页面,AgentHost.ets 属于 example——承载页本来就是每个应用自己的事,库只负责告诉你怎么写;
  2. 原生模块独立构建。libkmpagentmedia.so 由 Gradle 任务编译并拷进 HAR 的 libs/,hvigor 拿到的是现成产物,不感知 Kotlin 的存在;
  3. example 只走公共 API。页面里能出现的调用只有 AgentMedia.*,雷达图的数据全部来自事件,没有一处直接摸 NativeBridge。

业务侧的最小接入,三步:

// example/ohos/entry/src/main/ets/pages/Index.ets - aboutToAppear()(节选)
import { AgentMedia } from '@kmp-ohos/agent-media';

const context = this.getUIContext().getHostContext() as common.UIAbilityContext;

// 1. 探能力 + 挂事件 + 建语音引擎(幂等,可重复调用)
const cap = await AgentMedia.setup(context);

// 2. 听事件:场景快照 / 会话日志 / 电平 / 朗读
AgentMedia.on((event: AgentMediaEvent) => this.onEvent(event));

// 3a. 出声 + 语音闭环
AgentMedia.startAudio();                    // OHAudio FAST 通路
AgentMedia.startListening();                // onTouch Down;onTouch Up 时 stopListening()
const r = AgentMedia.say('把小提琴放到左边'); // 文本兜底,与语音走同一条链路

// 3b. 调起智能体
await AgentMedia.openAgent({ agentId: 'com.example.immersiveoverlays.SpatialFieldAgent' });

通道协议是"字符串进、字符串出"的单入口 + 单事件流。call() 支持的方法一张表说得完:

method作用返回关键字段
audio.start / audio.stop / audio.state渲染开关与状态ok / running / underflows
scene.get / scene.source / listener.set声场查询与修改scene 快照
voice.begin / voice.partial / voice.cancel / voice.dispatch语音会话ok / matched / reply
capability.set把 ArkTS 探到的能力告诉引擎—
agent.opened智能体调起回执—
selftest离线渲染 1 秒自检peak / rms

事件按 kind 区分,JSON 行长这样:

{"kind":"meter","peak":0.26,"rmsL":0.11,"rmsR":0.11,"frames":144000,"sources":{"violin":0.31}}
{"kind":"scene","reason":"voice.place","scene":{"preset":"music","playing":true,"sources":[...]}}
{"kind":"speak","text":"小提琴放到左边"}

两个容易被忽略的窗口期,都在时序上:

  1. 事件注册晚于首次调用。ensureInit() 里 onEvent() 只注册一次,如果业务先 startAudio() 再注册监听,最早的 meter 会丢。库的处理是把 setup() 做成"探能力之前先挂好内部监听",业务侧的 on() 只是往转发数组里加元素;
  2. audio.start 早于音频参数就绪。写回调一旦注册,系统可能在几毫秒内就来要数据,此时如果引擎还在等 scene.get,回调拿到的就是空场景。引擎的处理是默认场景常驻(三个声源一开始就在),audio.start 只是打开水龙头,不存在"回调到了但没水"的状态。

5. 把代码讲透

5.1 cinterop:头文件不进仓库,klib 会"静默变空"

Kotlin/Native 调 C API 靠 cinterop,配置本身不复杂,但这次最坑的一条(第 6 节坑 2)就出在这里,先把正确写法立起来。

// kmp-agent-media-core/build.gradle.kts - ohosArm64 {}(节选)
val ohaudioDef: File = layout.buildDirectory.file("cinterop/ohaudio.def").get().asFile
ohaudioDef.parentFile.mkdirs()
ohaudioDef.writeText("""
    headers = ${cinteropInclude.absolutePath}/ohaudio/native_audio_common.h \
               ${cinteropInclude.absolutePath}/ohaudio/native_audio_renderer.h \
               ${cinteropInclude.absolutePath}/ohaudio/native_audio_stream_base.h
    compilerOpts = -I${cinteropInclude.absolutePath}
    linkerOpts = -lohaudio
""".trimIndent())

三个细节值得单独说:

第一,头文件必须 vendoring 进仓库(src/ohosMain/cinterop/include/,从 SDK sysroot 拷出来的 6 个文件,约 140 KB)。从 sysroot 直接引的用法更"干净",但会生成的 klib 是空的,而且不报错。

第二,headers 里的路径必须是绝对路径。cinterop 会把这一行原样变成 #include "X",相对路径会相对它自己的临时目录解析,直接找不到文件。

第三,产物同步用 Gradle Copy 任务,hvigor 侧不感知 Kotlin:

// kmp-agent-media-core/build.gradle.kts - syncDebugBinariesToHar(节选)
tasks.register<Copy>("syncDebugBinariesToHar") {
    from(linkTask.get().outputFile)                       // libkmpagentmedia.so
    into(rootProject.file("harmony/agent_media/libs/arm64-v8a"))
}

5.2 音频回调:staticCFunction 只认顶层函数

写回调是一个 C 函数指针,Kotlin 侧用 staticCFunction 构造——它要求函数必须是顶层或静态的,捕获不了实例。回调又需要访问引擎和混音器,于是只能走单例:

// kmp-agent-media-core/src/ohosMain/kotlin/.../OhaudioBackend.kt - onAudioData()(节选)
internal fun kmpAudioWriteData(
    renderer: CPointer<OH_AudioRenderer>?,
    userData: COpaquePointer?,
    audioData: COpaquePointer?,
    audioDataSize: Int
): Int = OhaudioBackend.shared?.onAudioData(audioData, audioDataSize) ?: 0

internal fun onAudioData(audioData: COpaquePointer?, audioDataSize: Int): Int {
    val engine = engineProvider() ?: return 0
    val frames = audioDataSize / 8          // 2 声道 × F32(4 字节)
    if (frames <= 0 || frames * 2 > scratch.size) return 0
    engine.render(frames, scratch)          // 纯 Kotlin:混音 + 空间化,一个 malloc 都没有
    val dst = audioData?.reinterpret<FloatVar>() ?: return 0
    for (i in 0 until frames * 2) {
        dst[i] = scratch[i]
    }
    framesWritten += frames
    return 0                                // AUDIO_DATA_CALLBACK_RESULT_VALID
}

三个细节值得单独说:

第一,scratch 缓冲是成员变量,启动时一次分配 8192×2 个 float。音频线程上分配内存不是不可以。

第二,ITD 用分数延迟实现。Woodworth 模型算出的延迟通常不是整数个采样点,SpatialMixer 里维护 512 点的环形缓冲,读取位置带小数部分线性插值。头半径取 8.75 cm、声速 343 m/s,最大 ITD 约 0.65 ms——在 48 kHz 下大约 31 个采样点,缓冲给 512 是留了余量给声道交换。

第三,回调的返回值不是"写了多少帧",是结果枚举。返回 0 表示数据有效;填不满就是 underflow,系统自己会计数,audio.state 里那个 underflows 就是这么来的。

5.3 意图匹配:

commonMain 里的意图匹配器要同时喂三种输入:精确的示例句(用户点了按钮)、口语的变体(“帮我把小提琴挪到左边点儿”)、以及带数字的方位(“向右转四十五度”)。单一策略必翻车,最后落成三路加权:

// kmp-agent-media-core/src/commonMain/kotlin/.../Intent.kt - match()(节选)
fun match(utterance: String, skills: List<SkillSpec>, threshold: Double = 0.42): MatchResult? {
    val norm = normalize(utterance)
    var best: MatchResult? = null
    for (skill in skills) {
        var score = 0.0
        var via = ""
        for (example in skill.examples) {              // 路 1:示例句精确/高相似
            val s = similarity(norm, normalize(example))
            if (s > 0.99) { score = 1.0; via = "exact" }
            else if (s * 0.62 > score) { score = s * 0.62; via = "fuzzy" }
        }
        for (keyword in skill.keywords) {              // 路 2:关键词命中
            if (norm.contains(keyword) && 0.48 + keyword.length * 0.02 > score) {
                score = 0.48 + keyword.length * 0.02; via = "keyword"
            }
        }
        if (score >= threshold && (best === null || score > best.score)) {
            best = MatchResult(skill.id, score, via)
        }
    }
    return best
}

阈值 0.42 是调出来的:低于它,"现在几点了"这种闲聊会被 sound.query 的"在哪"误伤;高于 0.5,"小提琴挪左边点"这种口语变体又匹配不上。

中文数字解析器藏过一个真 bug:初版把「两百零五」解析成 250。原因是我把"零"当成纯跳过处理,后面一位就乘了当前位权。

// kmp-agent-media-core/src/commonMain/kotlin/.../Intent.kt - ChineseNumber(节选)
private var afterZero = false
// ...解析循环内:
if (ch == '零') { afterZero = true; continue }
val unit = unitOf(ch)                       // 十/百/千/万
if (unit > 0) { /* 正常乘位权 */ }
else {
    val digit = ch - '0'
    acc += digit * (if (afterZero) 1 else currentUnit)
    afterZero = false
}

这类 bug 真机上一辈子都测不全,但 JVM 单测里就是一行断言——这也是把大脑压进 commonMain 最大的回报。

5.4 napi 双工桥:内存所有权和线程计数

napi 层只有 136 行 C++,但有两处写错就是崩溃。

先看出向。ArkTS → Kotlin 是同步调用,字符串内存的归属必须钉死:

// harmony/agent_media/src/main/cpp/napi_init.cpp - call 导出(节选)
{"call", nullptr, [](napi_env env, napi_callback_info info) -> napi_value {
    // ...读出 method 与 argsJson 两个 std::string...
    const char* out = static_cast<const char*>(
        kmp_agentmedia_call(const_cast<char*>(method.c_str()),
                            const_cast<char*>(args.c_str())));
    napi_value result;
    napi_create_string_utf8(env, out != nullptr ? out : "{\"ok\":false}",
                            NAPI_AUTO_LENGTH, &result);
    kmp_agentmedia_free(const_cast<char*>(out));   // Kotlin malloc,C++ free
    return result;
}, nullptr, nullptr, nullptr, napi_default, nullptr},

契约只有一条:谁 malloc 谁 free 的规矩在跨语言边界上是反的——Kotlin 侧返回的字符串一律由 C++ 侧转成 JS 字符串后立刻 free。kmp_agentmedia_version() 返回的字符串同样要 free(这条是后来补的,第一次评审漏了)。两边都是 musl libc 的分配器,这个契约才成立;哪天换了分配器,这里就是第一个爆的地方。

再看入向。Kotlin → ArkTS 的事件(meter、speak、scene)可能从音频线程发出,直接调 JS 函数等于在错误的线程碰 napi,必须绕 napi_threadsafe_function:

// harmony/agent_media/src/main/cpp/napi_init.cpp - HostEmit()(节选)
static void HostEmit(const char* json) {          // 由 Kotlin 调,可能在音频线程
    if (g_tsfn == nullptr) { free(const_cast<char*>(json)); return; }
    auto* copy = strdup(json);                    // 拷一份再排队
    free(const_cast<char*>(json));                // 原串按契约立刻还
    if (copy == nullptr) { return; }
    if (napi_call_threadsafe_function(g_tsfn, copy, napi_tsfn_nonblocking) != napi_ok) {
        free(copy);                               // 队列满了就丢电平帧,不阻塞音频线程
    }
}

napi_create_threadsafe_function 的 initial_thread_count 这次特意填了 2:JS 线程一个,音频线程一个。官方语义是"将会使用这个函数的线程数"。

队列满时选择丢弃而不是阻塞:meter 事件本来就是约 100 ms 一次的心跳,丢一帧 UI 什么也看不出来;音频线程被阻塞 10 ms

5.5 AgentFrameworkKit:只有动态 import 能活

第 1 节埋的那个 signal 6 在这里回收。AgentFrameworkKit 由系统的 agentKitHsp 提供,模拟器等环境没有它,而顶层静态 import 的解析发生在模块加载期,早于任何 try/catch 能覆盖的范围——所以现象是进程 abort,faultlog 里连个 JS 堆栈都没有。

唯一活路是动态 import,让"找不到 HSP"变成一个可以被接住的异常:

// harmony/agent_media/src/main/ets/AgentFeature.ets - check()(节选)
async check(context: common.UIAbilityContext, agentId: string): Promise<boolean> {
  if (!this.isSyscapOk() || agentId.length === 0) {
    return false;
  }
  try {
    const kit: ESObject = await import('@kit.AgentFrameworkKit');   // 懒加载
    const ControllerClass: ESObject = kit.AgentController;
    if (this.controller === null) {
      this.controller = new ControllerClass();
    }
    this.available = await this.controller.isAgentSupport(context, agentId);
    return this.available;
  } catch (e) {
    const err = e as BusinessError;
    // 1022400011 隐私协议未同意 / 1022400012 华为账号未登录 → 都归为「不可用」
    console.warn(`${TAG} isAgentSupport(${agentId}) failed: ${err.code} ${err.message}`);
    this.available = false;
    this.controller = null;
    return false;
  }
}

三个细节值得单独说:

第一,canIUse 挡不住所有情况。syscap 声明支持但 HSP 缺失的组合是存在的(系统裁剪),所以 canIUse 只做前置短路,真正的兜底是 try/catch。

第二,isAgentSupport 的失败码要分类。1022400011(隐私协议)、1022400012(未登录)说明 Kit 本身是好的,只是这个账号还没准备好——文案里要和"设备不支持"区分开,否则用户会以为手机坏了。

第三,承载页是应用自己的,但库要替它把参数铺好。openAgent() 用 startAbility 带 agentId 和 queryText 拉起 AgentHostAbility,后者把 want 参数写进 AppStorage,FunctionComponent 从那里读。深链 vassistant://voice/main 只作兜底,且要求宿主在 module.json5 声明 querySchemes,否则 canOpenLink 直接 17700056。

6. 踩坑与经验

坑 1:Gradle 卡在 Kotlin/Native 下载上,构建直接被杀。 第一次跑 linkDebugSharedOhosArm64,构建卡在 > Task :cinteropOhaudioOhosArm64 纹丝不动,最后 Gradle 守护进程直接消失:

Gradle build daemon disappeared unexpectedly (may have been killed or may have crashed)
Exit code 137

排查发现它在下载 300 MB 的 kotlin-native-prebuilt-2.2.21-1.2.0-macos-aarch64.tar.gz,超时被杀。鸿蒙适配版 Kotlin 的原生编译器不在常规镜像里。修复:本机已有解压好的编译器,在 gradle.properties 里指过去:

kotlin.native.home=/Users/dijun/.konan/kotlin-native-prebuilt-macos-aarch64-2.2.21-1.2.0
kotlin.native.cacheKind=none

这条教训是:适配版 Kotlin 的构建,网络环境不可依赖,本地编译器路径要作为标准配置写进仓库文档。

坑 2:cinterop 生成的 klib 是空的,而且不报错。 def 文件指向 SDK sysroot 里的头文件,构建绿了,linkDebugSharedOhosArm64 也绿了,但生成的 klib 里只有一行 package {}——所有 ohaudio 符号一个都没有:

$ grep -c "OH_AudioStreamBuilder" build/bin/ohosArm64/debugShared/*.klib
0

一开始以为是头文件路径错了,换成符号链接、复制头文件、加 -I,都一样。后来才反应过来:cinterop 对 sysroot 里的头文件按"系统头"处理,声明直接被跳过,整个过程静默无声。修复就是把 6 个 ohaudio 头文件拷进仓库,headers 用绝对路径指向它们。

坑 3:AgentFrameworkKit 静态 import,模拟器点开即闪退。 就是第 1 节那个 signal 6:

DFX_SignalHandler :: signo(6), si_code(-6), pid(20252), processName(com.example.immersiveoverlays)

现象与 Flutter 版结论一致:静态 import 让进程在加载页面模块时直接 abort,try/catch 救不了。真机上有 agentKitHsp 所以一切正常,模拟器必挂。修复是把 import 挪进 check() 里动态执行(见 5.5),"设备不支持"从此变成一个可展示的芯片,而不是一个闪退。能力 Kit 的 import 位置不是风格问题,是生存问题。

坑 4:ASR 引擎创建失败 1002200001。 CreateEngineParams 按离线思路填了 online: 0:

[kmp-agent-media] 语音识别引擎创建失败 1002200001: Asr CreateEngineParams is wrong!

官方示例里 online 是 1,实现对 0 的校验直接拒绝。改成 online: 1 立刻通过。照着类型签名写参数不够,对着官方示例抄参数才算数。

坑 5:maxAudioDuration 给 12000,直接 401。

[kmp-agent-media] 识别失败 401: maxAudioDuration invalid, please input between [20000, 60000]

这个报错反而是所有语音报错里最友好的一个——区间都告诉你了。recvTimeout 顺手一起改成 20000。带区间的参数校验先查文档再填默认值,别拿"感觉合理"的数字去撞墙。

坑 6:TTS 音色 interaction-general 不被支持。 模拟器和真机先后报出两种错:

[kmp-agent-media/speech] speak failed 1002300005: create engine error!     ← 模拟器:无音色资源
[kmp-agent-media/speech] speak failed 401: create param is error,style not support!  ← 真机

前者是设备能力缺失,降级(不打断闭环);后者换官方示例的 interaction-broadcast 解决。同一行代码在两类设备上报不同的错,降级逻辑要按"哪一层失败"来写,而不是按"哪台设备"。

坑 7:ArkTS 的 @Builder 传参不随 @State 重渲染。 指标行用 @Builder metric(label, value) 传参,真机上明明音频在响,RMS 却永远停在 0‰。一开始怀疑是 Kotlin 侧 meter 事件没发出来,在 napi 层插桩才发现事件全到了,是 ArkTS 不刷。@Builder 的参数在首次构建时求值,之后不追踪来源状态的变化;要么把状态读取写进 Builder 体内,要么像本仓库最后采用的方案——用 @State 数组 + ForEach 渲染芯片行、用内联 Column 渲染指标行。ArkUI 的响应式边界比 React 更窄,传参即快照。

坑 8:三方库 HAR 依赖解析失败连环坑。 example 集成本地 HAR 时先后撞了三堵墙:Failed to resolve OhmUrl(useNormalizedOHMUrl 要关)、Missing module info for local modules '@kmp-ohos/agent-media'(HAR 要注册进 example 的 build-profile.json5 的 modules 数组)、module.json5 file not found(HAR 自己的 src/main/module.json5 一个都不能少):

Error Message: Missing module info for local modules '@kmp-ohos/agent-media'

7. 现在怎么用:从 三方库 到依赖

HAR 目前随仓库交付(发布到 ohpm 的流程走通后补链接),业务侧接入:

# 方式一:源码依赖(当前)
# oh-package.json5
# "dependencies": { "@kmp-ohos/agent-media": "file:../harmony/agent_media" }
cd example/ohos && hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

# 方式二:一键脚本(K/N 编译 + HAP + 安装 + 启动)
./scripts/oh_run.sh device      # 或 emulator / 设备序列号

测试方面:commonMain 的 15 个 JVM 单元测试覆盖 DSP(等功率归一、ITD 边界)、混音(可听性、左右声道、暂停静音)、意图(中文数字、匹配、最长别名、动作解释)、引擎(分发、JSON 往返、离线自检),./gradlew :kmp-agent-media-core:jvmTest 一键跑。真机验证结果:引擎初始化、OHAudio 渲染(RMS 110‰ / PEAK 26%)、文本路径闭环(reply: 小提琴放到左边 / reply: 向右转 45 度)、麦克风授权与 ASR 会话、智能体承载页渲染,全部在 TLR-AL00(API 26)实机通过;仓库 docs/ 下有截图与 hilog 原文。


总结:

这篇项目不是简单把空间音频、语音能力拼在一起,而是在KMP/CMP鸿蒙这套还在社区演进的工具链上,解决一个天然矛盾:实时音频线程对低延迟的刚性约束,和鸿蒙AI能力全部绑定ArkTS Kit的割裂现状。常规跨端方案习惯把音频数据交给JS桥转发,会直接引入不可控的调度延迟,极易出现音频断流、underrun,本方案选择用cinterop直连OHAudio,让DSP、声场渲染逻辑原生跑在Kotlin/Native的音频回调线程内,完全绕开JS层的数据拷贝,守住音频链路的时序底线。

整个系统做了清晰的职责拆分,把变化稳定、可单元测试的核心逻辑全部收敛到commonMain。空间声学算法、声源混音、中文数字解析、口语意图匹配、会话状态机这些业务大脑,不依赖任何鸿蒙平台API,能够在JVM上批量跑单元测试,提前把大部分语义匹配、声学计算的bug拦截下来,不用反复刷机调试。而ArkTS侧只承担两个不可替代的工作:渲染ArkUI界面,以及封装仅ArkTS可访问的CoreSpeechKit、AgentFrameworkKit,两者之间通过轻量化napi字符串协议通信,只传递指令和事件,不传输大块音频采样数据。

针对鸿蒙AgentKit的特殊坑点,方案没有回避系统限制,而是用动态import的方式做能力懒加载与降级兜底。静态导入会在模块加载阶段直接触发进程abort,模拟器、裁剪系统上会直接闪退;动态捕获异常之后,能力探测结果可以对外暴露,上层业务可以根据设备是否支持Agent、ASR、TTS,给出差异化提示,而不是一刀切崩溃。同时配套了完整的能力探测机制,通过syscap校验+运行时试调用双重判断,区分“设备不支持”“账号未登录”“隐私协议未同意”等不同失败场景,给用户明确反馈。

在工程交付形态上,项目最终沉淀为可复用HAR三方库,严格隔离内核、桥接层与示例代码。KMP内核编译产出so库,由Gradle任务自动同步到HAR,hvigor不需要感知Kotlin编译流程;对外只暴露极简的AgentMedia门面,业务接入只需要三行代码完成初始化、事件监听、启动音频与语音会话,内部的napi线程安全函数、内存生命周期、音频缓冲管理、意图调度全部封装在底层。线程安全的边界也做了精细处理,音频线程抛出的电平、场景事件通过napi_threadsafe_function投递到JS线程,队列满时直接丢弃非关键帧,绝不阻塞音频渲染回调。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐