用 Compose Multiplatform 写鸿蒙特性,最大的疑问一直是:跨端框架渲染的界面,接得上鸿蒙的系统智能吗?这篇文章用 cmp_ohos_ai_agent——一个把小艺语音闭环装进 KMP 库的三方库——回答它:Kotlin/Compose 侧怎么注册技能、怎么从麦克风一路走到「客厅灯已打开」的 TTS 回话、怎么反向接住小艺的系统意图、又怎么把官方智能体组件调起来。它怎么封装、真机怎么跑通、我踩了哪些坑——把这三个问题一次讲透。

示例仓库:https://atomgit.com/dijun_520/cmp_ohos_ai_agent

社区引导:框架源码与版本发布见 https://atomgit.com/CPF-KMP-CMP/kotlin/tree/main-2.2.21-OH

CMP 鸿蒙社区: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. 语音闭环不是「系统帮我识别一句话」

只是「系统帮我识别一句话,我拿文本做点事」。用户对着手机说「打开客厅灯」,CoreSpeechKit 给我一串文字,我 if (text.contains("灯")),完事。

结果真机上一跑,事情比这复杂。第一个撞上来的不是识别,而是判定:我怎么知道这台设备上小艺到底可不可达?我顺手写了个 bundleManager.getBundleInfo("com.huawei.hmos.vassistant"),真机日志给了我当头一棒:

11-13 23:45:36.431 W [CmpAgentArkTS] getBundleInfo(com.huawei.hmos.vassistant)
failed: 201 BusinessError 201: Permission denied. An attempt was made to
GetBundleInfo forbidden by permission: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED.

GET_BUNDLE_INFO_PRIVILEGED 是系统级权限,三方应用申请不到,requestPermissions 里写了也白写。也就是说「查小艺装没装」这条路在最常见的机型上根本走不通——但小艺明明就在手机里。这个报错后面会回收:它逼出了可达性判定的三档兜底设计。

第二个被推翻的朴素理解是调起。我以为调起智能体就是 startAbility 到小艺的某个 Ability,或者查一下 AgentFrameworkKit 有没有 open(agentId) 之类的命令式接口。翻完文档发现:AgentFrameworkKit 根本没有任何命令式拉起入口,唯一的入口是 ArkUI 组件 FunctionComponent——而它是 ArkUI 组件,Compose 渲染不了它。跨端框架在这里不是「能不能画」的问题,是「组件根本没有挂载点」的问题。

第三个被推翻的是意图的方向。我原以为「接入小艺」是我单向调用系统;实际查 Intents Kit 文档才发现还有反向的一半:小艺自己听懂一句话之后,会通过 InsightIntent 框架回调到应用声明的执行器上——应用要能在后台被系统叫醒、接参数、干完活、再把结果回传给小艺,小艺才能接着向用户回话。这是一条完整的有来有回的通路。

所以这个题目的边界很清楚:跨端层(Kotlin/Compose)管业务与状态,ArkTS 层管系统能力,两边之间必须有且只有一条窄桥;系统给不了的(比如渲染 ArkUI 组件),就用宿主承载页绕过去。

拆下来是三件事:

  • 一条 Kotlin ↔ ArkTS 的双向桥,承载方法调用与事件推送;
  • 一套放跨端层的技能匹配引擎,让「我理解成了什么」可测试、可展示;
  • 两个系统入口:语音闭环(说 → 匹配 → 执行 → 回话)与意图闭环(小艺叫醒 → 执行 → 回传)。

2. 效果展示

CMP 示例「声控智家」真机首屏:能力探测全绿,设备面板、语音条、快捷指令与日志区完整渲染

整页都是一套 Compose 代码渲染的,信息很密,放大了逐块看。

先看能力卡片——这是应用启动后第一件事 detect() 一次跨端往返拿回来的结果:

能力卡片特写:七项探测全绿,右侧标注每项背后的 Kit 与判定依据

七行各对应一次真实探测,右侧的注释就是判定依据:

  • API 26 · TLR-AL00——deviceInfo.sdkApiVersion 与 productModel,整张卡的基线;
  • AgentKit · AgentFrameworkKit——canIUse("SystemCapability.AI.Agent.AgentKit"),能调起智能体组件的前提;
  • 语音识别 · CoreSpeechKit / 语音合成 · textToSpeech——ASR/TTS 两个 syscap 位,任一为假对应能力直接不可用;
  • 结果回传 · API 23+——insightIntentProvider.sendExecuteResult 的版本门槛,真机 API 26 通过;
  • 小艺 · 链路可达——注意它不是 bundle 查询的结果,而是 canOpenLink("vassistant://voice/main") 的第二档判定;
  • 已声明 Skill · smart-home@1.0.0 · system · EntryAbility——skillManager.getSkillInfosForSelf() 读回的技能「户口本」,版本、可见性、挂在哪个 Ability 上。

再看设备面板——业务本体,全部状态都在跨端层的 SmartHomeStore 里:

设备面板特写:三个房间的灯、两台空调与音乐状态,被语音改变的设备会高亮

  • 五台设备(客厅/卧室/书房的灯、客厅/卧室空调)+ 音乐开关,每台设备的右列就是当前状态,26度 · 制冷 这类文案来自 modeFor(temp)——28 度以上切制热;
  • 被语音改动的设备会在面板上高亮,数据源是 SmartHomeStore.lastChanged——这一行不是装饰,是「这句话落在了哪台设备上」的视觉回执;
  • 音乐行的开关状态由 music-playing / music-stop 两个技能翻转。

最后是快捷指令与文本兜底区——模拟器和调试场景的主力入口:

快捷指令与文本兜底特写:三条示例指令、调起智能体按钮与文本输入框

  • 三条快捷指令刻意覆盖三种匹配路径:「打开客厅灯」走示例句精确命中(1.0)、「关掉卧室的灯」走示例句、「客厅空调调到二十六度」还要额外过中文数字解析(二十六 → 26);
  • 「调起智能体」按钮单独一条路径:openAgent() → 承载页,是第 5.4 节的主角;
  • 文本输入框是模拟器没麦时的兜底入口,与语音共用同一条 dispatch 链路——闭环的匹配与执行不关心文本从麦来还是从键盘来,这让模拟器验证和单元测试都成为可能。

语音条的状态标签(「待命 / 正在听… / 匹配中… / 执行中… / 回话中…」)对应 AgentPhase 的五相流转;日志区每条带时间戳,记录探测结果、匹配得分与桥调用。

指令命中的瞬间才是这套闭环最有说服力的画面。点击快捷指令「打开客厅灯」:

点击「打开客厅灯」后:客厅灯行高亮并翻转为「开」,结果行显示 light-control 命中,状态机进入「回话中…」

一张图里能看到闭环的全部环节同时落地:

  • 设备面板:「客厅 灯」从「关」翻转为「开」,整行文字换成高亮色——这是 SmartHomeStore.lastChanged 触发的视觉回执,说明执行层真的改了业务状态;
  • 结果行(面板正下方新出现):✓ light-control · 1.0 · 0ms——技能名、得分、从拿到文本到执行完成的耗时;
  • 回话文案:「客厅灯已打开」——这串文字同时被送去 TTS 播报(speakResult=true),底部状态机同步进入「回话中…」;
  • 匹配依据:「示例句精确命中」——CommandMatch.reason 原样上屏,第 5.3 节说的「排查为什么命中」在这里兑现。

把结果行放大看,三行信息的分工一目了然:

匹配结果行特写:light-control · 1.0 · 0ms 与回话文案、匹配依据

得分 1.0 说明是示例句精确命中(不是相似度蹭进来的),0ms 说明执行层是内存内的纯业务操作——如果换成一个真的发 MQTT 开灯的 handler,这个数字就会变成真实耗时,这正是把 elapsedMs 放进结果结构的用意:

真机日志是闭环跑通的最硬证据:

11-13 23:45:36.246 I [CmpAgentArkTS] bridge created
11-13 23:45:36.430 I [CmpAgentArkTS] listSkills: 1 条
11-13 23:45:36.433 I [CmpAgentArkTS] hasXiaoyi: canOpenLink(vassistant://voice/main) = true
11-13 23:45:36.433 I [CmpAgentArkTS] detect: api=26 agentKit=true asr=true tts=true skills=1
11-13 23:45:36.434 I [CmpAgentArkTS] bridge#1 detect ok
11-13 23:45:36.439 I [CmpAgentArkTS] bridge#2 getAgentCard ok
11-13 23:47:20.107 I [CmpAgentArkTS] bridge#3 speak ok
11-13 23:47:20.110 I [CmpAgentArkTS] bridge#4 speak ok

bridge#N 是跨端方法调用的序号:#1/#2 是启动时的能力探测与智能体名片读取;#3/#4 是点击「打开客厅灯」之后的两条 TTS 调用。

截图上没有但同样验过的:「调起智能体」按钮拉起 AgentHostAbility 承载页,并回抛 agentDialogOpened 事件;智能体卡片内要加载真实内容需要 agentId 在小艺开放平台完成注册,库与示例里都做成了配置项,注册后填入即可。

3. 原理:一句话要穿过几层,才能变成一次操作

系统侧的入口和回调,先用一张表收拢:

能力方向背后 Kit应用要回答什么
能力探测Kotlin → ArkTS → KotlinAbilityKit(syscap/skillManager/bundleManager)六个能力位的真假
语音识别ArkTS → Kotlin(事件流)CoreSpeechKit ASRVAD 起止、中间/最终文本、错误码
语音合成Kotlin → ArkTSCoreSpeechKit TTS无需回答,成败不阻断
技能声明构建期静态声明skillProfiles + SKILL.mdentry 模块的 module.json5 里写「户口本」
意图执行系统 → ArkTS → KotlinIntents Kit(InsightIntentExecutor)执行结果(code + payload),经 completeIntent 回传
智能体调起Kotlin → ArkTS(startAbility)AgentFrameworkKit(懒加载)一个能挂 FunctionComponent 的 ArkUI 承载页
意图共享Kotlin → ArkTSIntents Kit(shareIntent,需平台报备)一次结构化的意图记录

这张表里最容易被低估的是「语音识别」那一行的方向。识别引擎不是应用拉起来就完事,它是一个有生命周期的会话:startListening 建会话,onEvent 推 VAD(1 = 开始说话,3 = 结束),onResult 不断推中间结果,isFinal 才是可信文本;松手对应 finish(),放弃对应 cancel()。每一次状态变化都要沿桥推回 Kotlin 侧,UI 才有得画。

第二个关键认知:**匹配引擎不该放进 ArkTS,也不该让云端做。**技能表跟着业务走,业务全在跨端层(Kotlin),那就把匹配也放跨端层——它就能热注册、能在 JVM 上直接单测、能把「我理解成了什么」连同得分与理由一起展示给用户。ArkTS 原生侧只提供系统能给的元数据与系统能力本身。

第三个关键认知是那条窄桥的形状。不是 Flutter 那种自带 MethodChannel 的宿主环境——CMP 在鸿蒙上的运行时是 libkn.so 加一个 ArkUI 容器,Kotlin 与 ArkTS 之间没有现成通道,只有 NAPI。所以「一条窄桥」在实现上是:ArkTS 侧一个桥对象暴露唯一的 invoke(callId, method, argsJson),Kotlin 侧通过 napi_call_function 调它;结果与事件经两个导出函数回推。

4. 工程怎么搭

完整目录树(带职责注释):

cmp_ohos_ai_agent/
├── cmp_ohos_ai_agent/                    # KMP 库模块(交付物本体)
│   └── src/
│       ├── commonMain/kotlin/com/cmp/ohos/aiagent/
│       │   ├── MiniJson.kt               # 零依赖极简 JSON(K/N 上没有现成的)
│       │   ├── Models.kt                 # 通道数据模型(与 ArkTS 接口一一对应)
│       │   ├── SkillRegistry.kt          # 技能注册表 + 三路加权匹配 + 中文数字槽位
│       │   ├── AgentBridge.kt            # 传输层接口 AgentTransport(expect)
│       │   ├── CmpAiAgent.kt             # 公共 API 门面(单例)
│       │   └── CmpAiAgentController.kt   # 状态机 Controller(StateFlow 驱动 Compose)
│       ├── ohosMain/kotlin/...           # NapiAgentTransport:NAPI 桥 actual
│       ├── jvmMain/kotlin/...            # EchoTransport:JVM 交叉验证用
│       └── commonTest/kotlin/...         # 匹配引擎 9 个单元测试
├── example/
│   ├── composeApp/                       # CMP 示例:声控智家
│   │   └── src/ohosMain/.../MainArkUIViewController.kt  # @CName 导出(必须在 app 模块!)
│   └── harmonyApp/                       # DevEco 壳工程
│       └── entry/
│           ├── src/main/cpp/napi_init.cpp      # 4 个导出入口的 C 包装
│           ├── src/main/ets/agent/CmpAgentBridge.ets   # 系统桥(Kit 封装)
│           ├── src/main/ets/agent/AgentFeature.ets     # AgentFrameworkKit 懒加载壳
│           ├── src/main/ets/entryability/AgentHostAbility.ets  # 智能体承载页宿主
│           ├── src/main/ets/pages/AgentHost.ets        # FunctionComponent 承载页
│           ├── src/main/ets/intents/SmartHomeIntentExecutor.ets  # 意图执行器
│           ├── skills/smart-home/                      # 技能「户口本」(SKILL.md)
│           └── src/main/resources/base/profile/insight_intent.json
└── scripts/oh_run.sh                     # 一键构建 + 签名 + 安装启动

这次整理最关键的变化,是把「能跑」变成「能复用」,边界钉了三条:

  1. 库不依赖页面:cmp_ohos_ai_agent 里没有任何 UI 代码,Controller 只吐 StateFlow<AgentUiState>,Compose 侧 collectAsState() 自由发挥;
  2. 原生模块独立:CmpAgentBridge.ets、napi 包装、执行器都在 example 的 entry 里,库的 ohosMain 只留桥协议实现;
  3. example 只走公共 API:示例页面从头到尾只 import com.cmp.ohos.aiagent.*,不碰桥细节——保证三方库接入方看到的表面就是全部。

业务侧最小接入就四步(示例真实代码的浓缩):

// example/composeApp - SmartHome.kt(节选,浓缩为最小接入)
// 1. 注册技能:业务逻辑全在跨端层
registerSkill(SkillDefinition(
    name = "light-control",
    examples = listOf("打开客厅灯", "关掉卧室的灯"),
    keywords = listOf("灯", "打开", "关闭"),
    slots = listOf(
        SlotSpec(name = "room", required = true, values = listOf("客厅", "卧室", "书房")),
        SlotSpec(name = "action", required = true, pattern = Regex("(打开|关闭|关掉|开一下)")),
    ),
    handler = { ctx -> SkillResult(message = store.setLight(ctx.slots["room"]!!, ctx.slots["action"] == "打开")!!) },
))

// 2. Controller 接进 Compose
val controller = CmpAiAgentController(hotWords = listOf("客厅", "空调"))
val ui by controller.state.collectAsState()

// 3. 按住说话:识别最终文本自动进 dispatch
controller.start()   // 松手 controller.stop()

// 4. 接住小艺反向调用的意图(结果自动回传)
controller.bindIntentHandler { invocation, params -> handleSystemIntent(invocation, params) }

ArkTS 侧宿主要配的五件事(少一件,对应能力就哑):MICROPHONE 权限、querySchemes: ["vassistant"]、UIAbility 的 ohos.insightIntent.config metadata、skillProfiles 技能声明、AgentHostAbility 承载页。

通道协议只有一条调用一个事件流。调用是「callId 配对」的 JSON 行:

Kotlin → ArkTS:  invoke(callId=3, method="speak", argsJson='{"text":"客厅灯已打开"}')
ArkTS → Kotlin:  CmpAgentOnBridgeResult(callId=3, json='{"__error":null}')   # 成功
                 CmpAgentOnBridgeResult(callId=3, json='{"__error":"麦克风权限被拒绝"}')  # 失败
ArkTS → Kotlin:  CmpAgentOnEvent('{"kind":"voice","voice":{"kind":"result","text":"打开客厅灯","isFinal":true}}')

竞态细节有两个,都体现在协议设计里:一是 callId 在 JS 主线程分配并登记,与完成回调天然同线程配对,pending 表不需要加锁;二是事件流用 MutableSharedFlow(extraBufferCapacity = 64),ArkTS 推事件(JS 线程)与 Kotlin 消费(Default 线程)解耦,VAD 起止这类高频事件不会被 UI 卡顿反压阻塞。

5. 把代码讲透

5.1 NAPI 桥:callId 配对与三条线程纪律

接收侧最容易写错的是线程。NAPI 的规则是:napi_env 只能在创建它的 JS 线程上用。Kotlin 侧的协程跑在 Default 线程,直接碰 env 就是未定义行为——而崩溃栈不会告诉你原因,只会随机 abort。

// cmp_ohos_ai_agent/src/ohosMain/kotlin/com/cmp/ohos/aiagent/NapiAgentTransport.kt
// NapiAgentTransport.call()(节选)
override suspend fun call(method: String, argsJson: String): String {
    if (!isReady) throw IllegalStateException("CmpAgentBridge 尚未 install")
    val deferred = kotlinx.coroutines.CompletableDeferred<String>()
    // napi 只能在 JS 主线程上调;Main 由 initMainHandler(env) 接管。
    // 登记 + 发起 + (另一端)完成都收口在 JS 线程,pending 表无需加锁。
    val callId = kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Main) {
        val id = ++NapiHolder.callSeq
        pending[id] = deferred
        napiInvoke(method, argsJson, id)
        id
    }
    return deferred.await()
}

三个细节值得单独说:

  • 第一,CMP 的 Dispatchers.Main 不是 Android 那个主线程调度器——它由 initMainHandler(env) 在入口处接管,直接绑到鸿蒙 JS 事件循环上。所以 withContext(Dispatchers.Main) 在这里不是「切 UI 线程」,是「切回 napi 合法线程」。
  • 第二,挂起不阻塞:deferred.await() 挂起的是 Kotlin 协程,JS 事件循环照常转。反例是 runBlocking——一旦在 JS 线程上跑它,桥自己就把桥堵死了,所有后续调用包括完成回推全卡死。
  • 第三,pending 表免锁不是偷懒:登记(call 分支)、发起(napiInvoke)、完成(complete,由 agentOnBridgeResultBinding 从 JS 线程进入)三步全收口在 JS 主线程,同一时间只有一条执行流在碰这张表。

一个反直觉陷阱:complete() 收到空 JSON 时应该让对应调用失败而不是永远挂起——ArkTS 侧 dispatch 抛异常也会走 CmpAgentOnBridgeResult(callId, {"__error":...}),Kotlin 侧解析到 __error 要转成异常抛出,调用方才能进 catch 分支。桥上不存在「没有结果」这种状态,只有「结果还没到」。

5.2 三类事件一条流

语音、系统意图、智能体弹层,三类异构事件在桥上共用一条 CmpAgentOnEvent(json):

// 三类事件的真实负载形状(kind 区分)
{"kind":"voice","voice":{"kind":"result","sessionId":"cmpagent_1763...","text":"打开客厅灯","isFinal":false,"isLast":false}}
{"kind":"intent","intent":{"instanceId":17,"intentName":"ControlDevice","paramsJson":"{\"device\":\"客厅灯\",\"action\":\"open\"}"}}
{"kind":"agentDialog","agentDialog":{"kind":"opened","agentId":"com.example.smarthome.HomeAgent"}}
// cmp_ohos_ai_agent/src/commonMain/kotlin/com/cmp/ohos/aiagent/CmpAiAgentController.kt
// onVoice()(节选):识别事件驱动状态机
private fun onVoice(voice: VoiceEvent) {
    when (voice.kind) {
        "vadBegin" -> log("检测到说话开始")
        "vadEnd" -> log("说话结束,等待识别结果")
        "result" -> {
            val r = voice.result ?: return
            _state.update { it.copy(transcript = r.text) }
            if (r.isFinal) {
                _state.update { it.copy(phase = AgentPhase.matching) }
                externalScope.launch { dispatchInternal(r.text) }
            }
        }
        "complete" -> {
            if (_state.value.phase == AgentPhase.listening) {
                // 松手了但没等到 isFinal(比如静音):回到 idle
                _state.update { it.copy(phase = AgentPhase.idle) }
            }
        }
        "error" -> fail("识别出错 ${voice.errorCode}: ${voice.errorMessage}")
    }
}

三个细节值得单独说:

  • 第一,isFinal 与 isLast 是两个语义。isFinal 是「这句话认准了」;isLast 是「本次会话不会再有结果」。拿 isLast 当触发点会漏掉「松手后紧跟的最终结果」。
  • 第二,complete 不等于结果。静音几秒松手,ASR 会走 onComplete 而不给 isFinal 结果——状态机必须在这个分支把 listening 收回 idle,否则按钮永久卡在「正在听」。
  • 第三,中间文本也要上屏。transcript 每次都更新,用户说话时能看到自己被听成了什么——这不是装饰,是端侧识别「听没听对」的唯一反馈渠道,热词有没有生效看这里最快。

意图事件与语音事件走同一条流是刻意设计:CmpAiAgent.init() 在消费层把 kind == "intent" 的事件截下路由到注册的处理器,其余继续广播给 UI。

5.3 三路加权匹配:0.3 阈值的由来

匹配引擎与 Flutter 版(skill_registry.dart)、RN 版(registry.ts)是同一套算法,Kotlin 重写:

// cmp_ohos_ai_agent/src/commonMain/kotlin/com/cmp/ohos/aiagent/SkillRegistry.kt
// matchCommand()(节选)
fun matchCommand(utterance: String, threshold: Double = 0.3): CommandMatch? {
    val text = normalize(utterance)
    if (text.isEmpty()) return null
    var best: CommandMatch? = null
    val uttGrams = bigrams(utterance)
    for (skill in registry.values) {
        val slots = extractSlots(utterance, skill.slots)
        val missing = skill.slots.filter { it.required && !slots.containsKey(it.name) }
        if (missing.isNotEmpty()) continue   // 必填槽位缺失直接出局
        var score = 0.0
        val reasons = mutableListOf<String>()
        if (skill.examples.any { normalize(it) == text }) {
            score = 1.0
            reasons.add("示例句精确命中")
        } else {
            var bestSim = 0.0
            for (e in skill.examples) {
                val sim = jaccard(uttGrams, bigrams(e))
                if (sim > bestSim) bestSim = sim
            }
            if (bestSim > 0) { score += bestSim * 0.6; reasons.add("示例相似 ${((bestSim*100).toInt())/100.0}") }
            val hits = skill.keywords.filter { text.contains(normalize(it)) }
            if (hits.isNotEmpty()) { score += min(hits.size * 0.18, 0.9); reasons.add("关键词 ${hits.joinToString("/")}") }
        }
        if (score > 0 && (best == null || score > best.score)) {
            best = CommandMatch(skill, if (score > 1) 1.0 else score, reasons.joinToString(";"), slots)
        }
    }
    if (best == null || best.score < threshold) return null
    return best
}

三路权重的分工:示例句精确命中 1.0(开发者写下的标准说法);字符二元组 Jaccard 相似度最多贡献 0.6(「把客厅灯开一下」这类口语变形);关键词每个 +0.18、封顶 0.9(「灯」「打开」这类词面的兜底)。中文不分词,所以用字符二元组替代词袋——这在中文短句上比编辑距离稳。

三个细节值得单独说:

  • 第一,阈值 0.3 是实测出来的:再低,随便一句话蹭到一两个关键词就误触发;再高,「来点音乐吧」这种短口语进不来(二元组相似度对短句天然吃亏)。
  • 第二,必填槽位缺失直接出局,不参与打分。这句话听起来多余,实际是关键:没有它,「帮我打开那盏灯」会因为关键词命中拿 0.36 分、超过阈值、然后在 handler 里撞上 room == null。
  • 第三,reason 字段不是日志装饰。它随 CommandMatch 一起返回,UI 上能直接展示「示例相似 0.42;关键词 灯/打开」——排查「为什么没命中 / 为什么命中错了」时,这比猜快得多。

槽位抽取的顺序是枚举优先 → 正则 → 默认值,且中文数字有独立解析器:parseChineseNumber("三十五") = 35、("一百二") = 120、("两") = 2——「一百二」这种口语省略(尾数省略「十」)和「两百零五」里的零都要单独处理,这些分支都有单测盖着。空调温度技能就靠它:用户说「调到二十六度」,temp 槽位抽到 二十六,再转成 26。

5.4 调起智能体:没有命令式接口,就造一条承载页的路

AgentFrameworkKit 没有 open(agentId)。唯一入口是 ArkUI 组件 FunctionComponent,Compose 渲染不了它。所以「跨端调起智能体」的可见路径是:

// example/harmonyApp/entry/src/main/ets/agent/CmpAgentBridge.ets
// openAgent()(节选):多路降级
private async openAgent(optionsJson: string): Promise<OpenAgentResult> {
    // 第 1 条路:宿主承载页(唯一真能把智能体弹出来的路径)
    if (hostAbility !== '') {
        const hostWant: Want = {
            bundleName: selfBundle,
            abilityName: hostAbility,
            parameters: { 'agentId': agentId, 'queryText': queryText },
        };
        await this.context.startAbility(hostWant);   // 成功即返回 via='host'
    }
    // 第 0 条兜底:openLink 走系统链接解析,最接近「用户点了小艺链接」
    await this.context.openLink(XIAOYI_URI, { appLinkingOnly: false });
    // 深链三连:viewData → qiankun action → 纯 ability
    // (对 VoiceAbility 依次尝试三种 Want 形状,全失败后按错误码给结论)
    if (lastCode === 16000001) {
        // 小艺 VoiceAbility 未对三方导出,需走小艺开放平台报备 + 承载页方案
    }
}

承载页那一侧,页面 body 只干一件事:

// example/harmonyApp/entry/src/main/ets/pages/AgentHost.ets(节选)
build() {
    Column() {
        if (canIUse('SystemCapability.AI.Agent.AgentKit') && this.agentId !== '') {
            FunctionComponent({
                agentId: this.agentId,
                options: { queryText: this.queryText, title: '小艺' } as FunctionOptions,
                controller: this.controller,
                onError: (err: BusinessError) => { /* ... */ },
            })
        } else {
            // 模拟器缺 agentKitHsp 的降级文案
        }
    }
}

三个细节值得单独说:

  • 第一,降级顺序有讲究:承载页(via=host)是真路;openLink 是「语义正确但界面未必出现」的兜底(返回值里 isInteractive=false 时 UI 应提示「调用被接受,界面可能不出现」);深链三连是老系统兼容路。全失败时看错误码:16000001 意味着小艺没对三方导出该 Ability——这不是代码能修的,结论是「报备 + 承载页」,错误信息里直接把这句话给出去。
  • 第二,FunctionController 的回调必须 off。页面退出后 controller 仍持有回调,不解绑就泄漏——aboutToDisappear 里一对 off() 是成对的卫生习惯。
  • 第三,agentId 的传递用 AppStorage 而不是 want 直读:承载页 Ability 是 singleton,第二次进入走 onNewWant 而不是 onCreate——漏了 onNewWant 就会出现「第二次进来还是上次的 agentId」。

5.5 InsightIntent 反向调用:小艺叫醒你,你要记得回话

反向的一半由三块组成。声明(构建期):

// example/harmonyApp/entry/src/main/resources/base/profile/insight_intent.json(节选)
{
    "intentName": "ControlDevice",
    "domain": "SmartDevice",
    "srcEntry": "./ets/intents/SmartHomeIntentExecutor.ets",
    "uiAbility": { "ability": "EntryAbility", "executeMode": ["background"] },
    "inputParams": [
        { "name": "device", "type": "string", "required": true },
        { "name": "action", "type": "string", "required": true },
        { "name": "value", "type": "string" }
    ]
}

执行器(ArkTS 侧,只做转发):

// example/harmonyApp/entry/src/main/ets/intents/SmartHomeIntentExecutor.ets(节选)
async onExecuteInUIAbilityBackgroundMode(
    name: string, param: Record<string, Object>,
): Promise<insightIntent.ExecuteResult> {
    const instanceId: number = this.context.instanceId;
    const forwarded: boolean = forwardIntent(instanceId, name, JSON.stringify(param));
    if (!forwarded) {
        // libkn.so 还没起来:如实回失败,别让小艺干等到超时
        return { code: 1, result: { 'message': '应用还没准备好,请先打开应用再试' } };
    }
    // 已转发给 Kotlin:真正的结果由 Kotlin 侧 completeIntent() 回传
    return { code: 0, result: { 'message': '已受理' } };
}

Kotlin 侧(业务真正发生的地方 + 回传):

// cmp_ohos_ai_agent/src/commonMain/kotlin/com/cmp/ohos/aiagent/CmpAiAgent.kt
// routeIntent()(节选)
private suspend fun routeIntent(invocation: IntentInvocation) {
    val handler = intentHandlers[invocation.intentName] ?: intentHandlers[null]
    val result = if (handler == null) {
        // 没有处理器也要回话,否则小艺侧只能干等到超时
        SkillResult(ok = false, message = "未注册意图处理器:${invocation.intentName}")
    } else { try { handler.handle(invocation, invocation.params) }
             catch (e: Exception) { SkillResult(ok = false, message = "执行失败:${e.message}") } }
    runCatching { completeIntent(invocation.instanceId, result) }
}

三个细节值得单独说:

  • 第一,instanceId 是整条回路的钥匙。执行器从小艺拿到它,转发给 Kotlin,Kotlin 干完活再带着它调 completeIntent——对不上号,小艺那边就一直挂着等。
  • 第二,两段式应答:执行器先回 code 0「已受理」解除系统侧的即时等待,真正的执行结果由 Kotlin 异步回传。
  • 第三,执行器必须写在 entry 模块:InsightIntentExecutor 依赖 UIAbility 生命周期,这类能力不能声明在 HAR 里。

技能与系统意图共用同一段业务 handler 是示例刻意的安排:语音闭环(A 路)和小艺意图闭环(B 路)最后落到同一个 handleSystemIntent / setLight。

6. 踩坑和经验

坑 1:size_t 不在你想的那个包里。

Kotlin/Native 侧写 NAPI 绑定,我按 C 语言的直觉 import 了 kotlinx.cinterop.size_t,编译直接报错:

e: NapiAgentTransport.kt:24:25 Unresolved reference 'size_t'.
e: NapiAgentTransport.kt:25:30 Unresolved reference 'size_tVar'.

一开始以为是 ohos 的 cinterop 没暴露 POSIX 类型。后来才反应过来:ArkTS 的 napi klib 自带一份独立的 size_t typealias——klib 依赖只有 stdlib,它在自己的包里重新生成了 C 头文件里的类型。strings 查 klib 的 knm 清单确认了真实位置:

// 正确写法
import platform.ArkTS.ArkTS_Napi_NativeModule.size_t
import platform.ArkTS.ArkTS_Napi_NativeModule.size_tVar

klib 里 C 类型的真实包名,用 knm 清单确认,不要靠猜。

坑 2:库模块里的 @CName 会被 tree-shaking 整个裁掉。

这是全文最值钱的一个坑。我把三个事件入口(install / onEvent / onBridgeResult)直接写在库的 ohosMain 里、用 @CName 导出,hvigor 构建 cpp 时报:

error: use of undeclared identifier 'cmpAgentOnEventBinding'
      ; did you mean 'CmpAgentOnEventWrapper'?

一开始以为是 cpp 少 include 了头文件。nm -gU libkn.so 一查——三个符号根本不在导出表里,只有 app 模块的 MainArkUIViewController 幸存。后来才反应过来:K/N sharedLib 的链接根只有 app 模块(持有 export 声明的那一层),库 KLIB 里的 @CName 符号被视为不可达代码,直接被裁。修复分两步:库内保留三个普通的公开函数(不带 @CName),把 @CName 导出包装挪进 example 的 MainArkUIViewController.kt:

// example/composeApp/src/ohosMain/.../MainArkUIViewController.kt
@OptIn(ExperimentalForeignApi::class, ExperimentalNativeApi::class)
@CName("cmpAgentOnEventBinding")
fun cmpAgentOnEventBindingExport(env: napi_env, info: napi_callback_info): napi_value =
    agentOnEventBinding(env, info)

对三方库作者来说,「能编译」和「符号活着」是两回事,每次改导出后都该 nm 一眼。

坑 3:platform.posix 的时间类型在 ohos target 上不存在。

写 nowIsoTime() 时我按 JVM 直觉用了 time_tVar/tm/tm_hour,报错连发三条:

e: Platform.ohos.kt:6:25 Unresolved reference 'time_tVar'.
e: Platform.ohos.kt:12:9 Unresolved reference 'tm'.
e: Platform.ohos.kt:12:20 Unresolved reference 'tm_hour'.

ohos target 的 posix cinterop 覆盖面和 Linux 不一样,依赖具体的 sysroot 头文件。与其跟它纠缠,不如绕开:Kotlin 2.x 自带 kotlin.time.Clock,拿 epoch 毫秒加 8 小时时区偏移算本地时间,K/N 与 JVM 两侧通用。跨端代码里凡是 posix 才有的东西,先找 Kotlin stdlib 的等价物,找不到再降级到 cinterop。

坑 4:argv[0] 被当成正则下标。

取 NAPI 参数数组时写了 C 程序员的本能写法 argv[0],编译器给我回了一个完全不相干的报错:

e: Argument type mismatch: actual type is 'MatchGroup?',
   but 'CPointer<napi_value__>?' was expected
e: Unresolved reference. None of the following candidates is applicable
   because of a receiver type mismatch: fun MatchGroupCollection.get(...)

MatchGroup 是哪来的?Kotlin 里 [0] 是 get 运算符重载,在这个上下文里它解析到了正则的 MatchGroupCollection。CPointer 数组的正确下标写法是指针算术:

val json = argStringValue(env, (argv + 1L)!!.pointed.value)

在 cinterop 代码里,方括号下标不是 C 的下标,是 Kotlin 的运算符重载。

坑 5:AgentFrameworkKit 顶层静态 import,进程直接 abort。

AgentFeature.ets 第一版在文件头静态 import { AgentController } from '@kit.AgentFrameworkKit',模拟器一启动就崩,日志只有一句 cppcrash: load hsp failed。这个 Kit 由 HMS 的 agentKitHsp 提供,模拟器与部分定制镜像上没有这个 hsp——顶层静态 import 让加载器在启动时强解析,解析失败直接 abort,连 try-catch 的机会都没有。修复是把强依赖拆进独立文件,桥侧动态加载:

// CmpAgentBridge.ets - isAgentSupported()(节选)
try {
    const feature = await import('./AgentFeature');
    return await feature.isAgentSupport(this.context, agentId);
} catch (e) {
    return false;   // 加载失败只表现为「能力探测结果为 false」,进程不受影响
}

不是所有 Kit 都能静态 import——HMS 独占 HSP 背书的 Kit 必须懒加载。

坑 6:ArkTS 严格模式三连击。

桥代码从 JS 习惯写法迁移过来,hvigor 一口气报了三类错:

ArkTS:Error: Object literal must correspond to some explicitly declared class
or interface (arkts-no-untyped-obj-literals) At File: CmpAgentBridge.ets:173:16
ArkTS:Error: Use explicit types instead of "any", "unknown" (arkts-no-any-unknown)
ArkTS:Error: Compile time error: Expected 1 arguments, but got 0.

逐个修:dispatch 里所有 return {} 换成显式声明的接口实例(SkillsResult、IsSupportedResult,空对象统一 const empty: Record<string, Object> = {});as unknown as ListenOptions 这种投机转换改成逐字段构造;.d.ts 里的入口函数补全参数类型。ArkTS 不是 TypeScript 的超集玩法,是运行时强约束——类型系统对着检查器写,不是对着编译器写。

坑 7:回话播了两遍。

第 2 节日志里 bridge#3 与 bridge#4 两条 speak ok 间隔 3ms,播报念了两遍同一句话。排查发现是双层回话:CmpAiAgent.dispatch() 在 skill.speakResult=true 时发起一次 TTS,Controller.dispatchInternal 的成功分支又进了 speaking 过渡帧并调了一次 speakResult()。两处都没错,错在职责没有收口。修复原则一句话:TTS 由 dispatch 统一回话,Controller 只做状态流转——修复后 Controller 的成功分支只切 speaking 相,不再发起第二次 speak。

同一处还留着一个后遗症,第 2 节那张交互截图里能看到:speaking 相切进去之后没有回 idle 的出口——结果行已经刷新、TTS 也在播,但状态标签会一直停在「回话中…」(未命中路径有 400ms 后回 idle 的兜底,成功路径漏了同样的出口)。这是当前版本已知的小毛病,不影响功能;它证明了一件事:一个过渡状态没有出口,UI 就会替你把这件事记在脸上。

坑 8:GET_BUNDLE_INFO_PRIVILEGED 申请了也没有。

第 1 节埋的那条 201 Permission denied 在这里回收。我最初把 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 加进 requestPermissions,权限弹窗都没弹(系统级权限不进 ACL 流程),getBundleInfo 照样 201。最后落成三档兜底判定:① 查小艺 bundle(真机上必失败,失败不代表没装);② canOpenLink('vassistant://voice/main')(需要宿主声明 querySchemes,漏声明报 17700056);③ 自家 Skill 被技能中心收录(skillManager.getSkillInfosForSelf())。


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

库以 KMP 源码模块形式接入(后续会随 atomgit 发布 Maven 坐标):

// settings.gradle.kts
includeBuild("../cmp_ohos_ai_agent")

// example/composeApp/build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.cmp.ohos:cmp_ohos_ai_agent:0.1.0")
        }
    }
}

构建与安装(真机):

# 1. K/N 编译并发布到 harmonyApp(约 2m16s,JDK 17)
./gradlew :example:composeApp:publishDebugBinariesToHarmonyApp

# 2. hvigor 构建签名 HAP(约 5m40s,产物约 33MB)
cd example/harmonyApp && hvigorw assembleHap --mode module -p product=default -p buildMode=debug

# 或者一键:构建 + 签名 + hdc install + aa start
./scripts/oh_run.sh debug

匹配引擎与 JSON 解析共 9 个单元测试,全部跑在 JVM 上(commonMain 源码零平台依赖,jvmTest 直接跑),覆盖示例句精确命中、相似度匹配、关键词兜底、中文数字解析(含「一百二」省略与「两百零五」的零)、JSON 往返。真机验证结果:能力探测六项全绿、文本指令闭环全通、真机语音会话(ASR 识别 + TTS 回话)、调起智能体拉起承载页并回抛 agentDialogOpened。


总结:

本文围绕自研 KMP 三方库 cmp_ohos_ai_agent,解决 Compose Multiplatform(CMP)跨端鸿蒙应用对接鸿蒙系统智能能力 的核心难题,打通语音识别、技能匹配、TTS 播报、小艺 Agent 唤起、InsightIntent 反向意图回调完整双向链路,同时给出工程架构、核心源码逻辑、真机验证结果与大量落地踩坑经验。

开篇先点明核心痛点:CMP 是跨端渲染框架,本身没有原生通道调用鸿蒙系统 Kit,且 AgentFrameworkKit 没有命令式拉起接口,唯一入口是 ArkUI 的 FunctionComponent,CMP 无法直接渲染;同时小艺可达性不能通过 getBundleInfo 判断(需要系统特权权限,三方应用无法申请);另外接入小艺不只是单向调用,还存在系统侧通过 InsightIntent 后台唤醒应用、执行指令并回传结果的反向通路。基于这些约束,整体方案确立分工原则:Kotlin/CMP 跨端层承载业务状态、技能匹配引擎;ArkTS 原生层封装鸿蒙系统能力、权限与生命周期,两层之间通过一条基于 NAPI 的窄桥通信,桥协议采用 callId + JSON 模型,分离调用请求与事件推送。

整体链路包含两大闭环:语音闭环(麦克风采集 → CoreSpeechKit ASR 识别输出文本 → 跨端技能匹配引擎解析 → 执行业务动作 → TTS 语音播报结果)、小艺意图闭环(小艺在系统侧识别指令,通过 InsightIntent 唤醒应用执行器,转发指令到 CMP 层执行业务,执行完成后回传结果给小艺)。

工程架构上采用分层解耦设计,库本身无 UI 代码,对外只暴露 StateFlow 状态流供 Compose 页面订阅,保证库可复用;原生相关的承载页、NAPI 包装、意图执行器放在示例壳工程 entry 模块,库只保留跨端协议与抽象。技能匹配引擎放在 commonMain,实现跨平台可测试,支持 JVM 单元验证,采用三路加权匹配算法:示例句精确命中得 1.0 满分、字符二元组 Jaccard 相似度最高贡献 0.6、关键词累加最高 0.9,设置 0.3 阈值控制误触发,内置中文数字解析、槽位抽取逻辑,必填槽缺失直接过滤,匹配结果附带命中原因,方便调试。

通信桥是整套方案的核心,基于 NAPI 实现 Kotlin ↔ ArkTS 双向通信,严格遵守 NAPI 线程约束:napi_env 仅能在 JS 主线程使用,利用 Dispatchers.Main 绑定鸿蒙 JS 事件循环;通过 callId 在 JS 线程登记 pending 回调,天然免锁;事件统一单路分发,语音、系统意图、智能体弹窗事件共用一套事件流,使用 MutableSharedFlow 做背压缓冲,避免高频 VAD 事件阻塞。针对 FunctionComponent 无法在 CMP 渲染的问题,设计了ArkUI 承载页方案,通过 startAbility 拉起独立承载页挂载智能体组件,搭配深链、openLink 多级降级策略,兼容不同设备。InsightIntent 执行器只做转发,采用两段式应答,先回复系统受理状态,业务执行结果异步回传,保证小艺不会超时卡住。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐