打通 CMP 与鸿蒙系统智能:三方库承载语音匹配、TTS 播报、小艺 Agent 调用与意图回调全链路
用 Compose Multiplatform 写鸿蒙特性,最大的疑问一直是:跨端框架渲染的界面,接得上鸿蒙的系统智能吗?这篇文章用
cmp_ohos_ai_agent——一个把小艺语音闭环装进 KMP 库的三方库——回答它:Kotlin/Compose 侧怎么注册技能、怎么从麦克风一路走到「客厅灯已打开」的 TTS 回话、怎么反向接住小艺的系统意图、又怎么把官方智能体组件调起来。它怎么封装、真机怎么跑通、我踩了哪些坑——把这三个问题一次讲透。
社区引导:框架源码与版本发布见 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) |
| 系统 API | HarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0) |
| hvigor | 6.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. 效果展示

整页都是一套 Compose 代码渲染的,信息很密,放大了逐块看。
先看能力卡片——这是应用启动后第一件事 detect() 一次跨端往返拿回来的结果:

七行各对应一次真实探测,右侧的注释就是判定依据:
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 的五相流转;日志区每条带时间戳,记录探测结果、匹配得分与桥调用。
指令命中的瞬间才是这套闭环最有说服力的画面。点击快捷指令「打开客厅灯」:

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

得分 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 → Kotlin | AbilityKit(syscap/skillManager/bundleManager) | 六个能力位的真假 |
| 语音识别 | ArkTS → Kotlin(事件流) | CoreSpeechKit ASR | VAD 起止、中间/最终文本、错误码 |
| 语音合成 | Kotlin → ArkTS | CoreSpeechKit TTS | 无需回答,成败不阻断 |
| 技能声明 | 构建期静态声明 | skillProfiles + SKILL.md | entry 模块的 module.json5 里写「户口本」 |
| 意图执行 | 系统 → ArkTS → Kotlin | Intents Kit(InsightIntentExecutor) | 执行结果(code + payload),经 completeIntent 回传 |
| 智能体调起 | Kotlin → ArkTS(startAbility) | AgentFrameworkKit(懒加载) | 一个能挂 FunctionComponent 的 ArkUI 承载页 |
| 意图共享 | Kotlin → ArkTS | Intents 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 # 一键构建 + 签名 + 安装启动
这次整理最关键的变化,是把「能跑」变成「能复用」,边界钉了三条:
- 库不依赖页面:
cmp_ohos_ai_agent里没有任何 UI 代码,Controller 只吐StateFlow<AgentUiState>,Compose 侧collectAsState()自由发挥; - 原生模块独立:
CmpAgentBridge.ets、napi 包装、执行器都在 example 的 entry 里,库的 ohosMain 只留桥协议实现; - 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 执行器只做转发,采用两段式应答,先回复系统受理状态,业务执行结果异步回传,保证小艺不会超时卡住。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)