Electron 应用跑上鸿蒙之后,小艺是比日历、实况窗都更典型的"三个世界"问题:说话和播报攥在 ArkTS 的 CoreSpeechKit 手里,小艺入口(InsightIntent 意图、AgentExtensionAbility 智能体)是系统能力,而真正知道"下一首该放什么"的媒体状态躺在 Electron 主进程的 Node 里——中间隔着渲染进程、主进程、宿主 UIAbility 三个进程,没有共享运行时。怎么把这条链封装成 Electron 可用的三方库、执行权怎么在"桥在线的 Electron"和"离线时的原生兜底"之间路由、两端 NLU 怎么共用同一份意图目录。

示例仓库:https://atomgit.com/dijun_520/electron-ohos-voice-agent
社区引导:框架源码与版本发布见 https://atomgit.com/CPF-Electron/Electron/tree/v40.1.0-openharmony
CPF-Electron 鸿蒙社区:https://atomgit.com/CPF-Electron


环境与实测设备

项目版本
开发工具DevEco Studio 26.0(内置 SDK:DevEco Studio/sdk)
系统 APIHarmonyOS 7.0.0 / API 26(compatibleSdkVersion: 26.0.0)
Electron桌面示例 electron 40.1.0(Chromium 144 / Node 24);鸿蒙端为 CPF-Electron v40 运行时(libelectron.so)
Node.js≥ 22.11.0
实测设备HarmonyOS 7 PC(MateBook Pro)

1. “小艺不就是注册个入口吗”

题目是:给 Electron 鸿蒙应用接小艺。用户对小艺(或应用内麦克风)说"下一首"“我要听告白气球”“音量调到 30”,应用要听懂、执行、播报;反过来小艺也要能指挥这个播放器。

我的朴素理解很直接:小艺是个系统语音入口,在配置文件里注册一下,指令就会从系统流进来,我执行完把结果告诉系统就行。撑了不到半天,三份资料并排翻开之后被推翻了:

  1. 小艺递给你的是"请求",不是"结果"。 InsightIntent 意图框架把用户的话解析成结构化参数(intentName + params)递给 InsightIntentExecutor,AgentExtensionAbility 把 A2A 会话数据递给你——它们都不替你执行。执行完还要主动回填 ExecuteResult,小艺的语义卡才有东西可显示。也就是说,“注册入口"只解决"听懂”,"执行"从头到尾是应用自己的事。
  2. Electron 是三个世界,不是两个。 日历那篇的"JS 世界 vs ArkTS 世界"在这篇升级了:渲染进程(Chromium 画布)、主进程(libelectron.so 里跑的 Node)、宿主 UIAbility(ArkTS),三个进程在同一个沙箱里,但没有共享运行时,Node-API 桥注册不进去。日历那篇用的回环 TCP 还是唯一的路,只是这次桥的两端多了一层仲裁。
  3. 听与说只有 ArkTS 有。 CoreSpeechKit 的 speechRecognizer(离线、zh-CN、16k mono PCM)和 textToSpeech(离线播报)在 Node 世界没有等价物。往 Electron 里塞本地 ASR 模型意味着几十 MB 的模型文件和一套权限管理,而鸿蒙侧这些都是系统自带的。

真正把题目改写的是第三堵墙——装上 HAP、启动 Electron 容器那一刻:

// 真机 TLR-AL00,aa start EntryAbility(Electron 容器),Chromium 子进程派生失败
Error Code:16010004  Error Message: Capability not support
// hilog 侧:CustomChildProcess 派生被系统拒绝,容器 UI 起来后白屏

这台 phone 镜像不支持派生 Electron 的子进程,容器本身起不来。指令闭环的 Electron 端在真机上没有宿主。验证没有死路:桥的 Node 端是一份纯 JS(lib/main/bridge.js,零 Electron 依赖),从 macOS 通过 hdc fport 连到真机的回环端口,扮演的就是"Electron 主进程"——同一份代码、同一份协议、同一条线上的字节。 等容器镜像支持子进程的那天,把这份 JS 换回 main.js 里跑,协议一个字段都不用改。

所以题目的边界定下来:鸿蒙侧做耳朵(ASR)、嘴巴(TTS)和路由(NLU + 执行仲裁),Electron 侧做手(真正的媒体操作),中间一根回环 TCP 把执行权递过去——桥断了,原生兜底把手接回来,闭环不断。

拆下来是四件事:

  • 把 11 条媒体技能做成"一份目录、两端共用"(JS 与 ArkTS 逐条对齐),NLU 免模型、纯规则;
  • 回环 TCP 桥(NDJSON)双向打通:请求(probe/skills/execute/speak)+ 事件(command/result/state/asr);
  • 执行仲裁:桥在线把指令以 command 事件推给 Electron,8 秒内没等到 result 就回落原生 sink;
  • 小艺两条入口(InsightIntent / AgentExtensionAbility)接到同一个调度中心,真机跑完整轮闭环拿截图和协议原文当证据。

2. 效果展示

请添加图片描述

这是真机(nova 14,HarmonyOS 7.0.0.111)上的原生浮层,VoiceAgentHost 挂在 Electron 容器页(或 voice_native 原生页)之上,hitTestBehavior(None) 只吃自己子组件的触摸,不挡下层。这里每一处都不是装饰:

  • 能力行 桥 :47131 · ASR 可用 · TTS 可用 · Agent 可用 · peers 0 是浮层向 VoiceBridgeServer.capabilityJson() 拉到的快照——47131 是桥实际监听的端口,ASR/TTS 两项是真实 createEngine 一次再销毁的探测结论,peers 0 表示此刻没有 Electron 主进程连着;
  • 中间 11 个"模拟小艺意图"按钮(PlayMusic / NextTrack / AdjustVolume / …)不是摆设:每个按钮把 intentName 经 VoiceIntentMapper 回译成 skillId,走 dispatchIntent() ——和小艺语义拉起走的是同一条执行链路,只是入口不同;
  • 最底下两行是诊断信息:cap #4 {"native":true,"asr":true,...,"port":47131} 是第 4 次能力刷新的原始 JSON,22:28:54 桥已监听 127.0.0.1:47131 是浮层日志(这个调试手段的存在本身就是一个坑的故事,见坑八)。

按钮不是只能看——点一下 PlayMusic,结果卡、状态卡、日志行同时有反应:

请添加图片描述

结果卡 ✓ 播放音乐 · 小艺 · 意图 · media.play——来源徽标是「小艺 · 意图」而不是「网页」,说明这条指令走的是 InsightIntent 路径;日志行同步记下 15:50:07 模拟意图 PlayMusic。真实的小艺语义拉起最终也落在这个 dispatchIntent() 上,模拟按钮只是替你省了唤起小艺那一步。

请添加图片描述

这是能力行修好渲染之后的样子:桥:47131、语音、播报、Agent 四个圆点全绿,Electron 红着——正确,此刻没有对端连接。这枚红点不是"坏了",是仲裁器的状态灯:它红着的时候,每条指令都会走原生兜底。

下面这轮是完整闭环的协议原文(真机那轮,macOS 侧 Node 客户端经 hdc fport tcp:14715 tcp:47131 连入,bridge.js 同一份代码):

// 真机 TLR-AL00,15:33 那轮闭环,NDJSON 逐行原文(注释除外)
15:33:27  CONNECT 127.0.0.1:47131 (hdc fport)
15:33:27  TX {"v":1,"id":1,"type":"probe","payload":{}}
15:33:27  RX {"v":1,"id":1,"ok":true,"data":{"native":true,"asr":true,"tts":true,
             "agent":true,"intent":true,"port":47131,"skillsVersion":"voice-catalog/1.0.0"}}
15:33:28  TX {"v":1,"id":2,"type":"execute","payload":{"text":"我要听起风了"}}
15:33:28  RX {"v":1,"id":2,"ok":true,"data":{"matched":true,"skillId":"media.playSearch",
             "name":"点播","slots":{"query":"起风了"},"score":68}}
15:33:28  RX {"v":1,"event":"command","data":{"skillId":"media.playSearch","name":"点播",
             "slots":{"query":"起风了"},"text":"我要听起风了","source":"renderer"}}
15:33:29  TX {"v":1,"event":"result","data":{"ok":true,"display":"已为你播放 起风了",
             "speak":"好的,为你播放起风了","skillId":"media.playSearch",
             "title":"起风了","artist":"买辣椒也用券"}}
15:33:29  TX {"v":1,"event":"state","data":{"title":"起风了","artist":"买辣椒也用券",
             "playing":true,"volume":60}}

这轮日志里有四个值得指出的点:

  • execute 的应答和 command 事件是两条消息。 id:2 的应答只回答"这句解析成了什么"(skillId/slots/score),真正"去执行"的是紧跟着广播的 command 事件——解析和执行是解耦的,Node 侧拿到解析结果可以先做自己的校验;
  • score 68 是打分公式算出来的:media.playSearch 的模式 我要听{query} 固定词 3 个字、槽位填满 1 个 → 60 + 3 + 1×5 = 68(第 5.1 节细说);
  • result 和 state 是分开推的:result 说话卡,state 说播放器状态——正在播放卡不该等一条"执行结果"来刷新,它是持续同步的状态;
  • source: "renderer" 说明这条指令的来源是桥请求;同一字段在真实语音条时是 voice,小艺意图进来时是 intent。

请添加图片描述

这是 result/state 到达后一秒内的截图,完整闭环的证据链都在这一张里:结果卡 ✓ 已为你播放 起风了 · 网页 · media.playSearch(3.5 秒后自动收起,showResult 里的定时器);正在播放卡从"晴天 · 原生演示"切换成"起风了 · 买辣椒也用券 · 音量 60 · Electron 执行中"——歌名和歌手来自 state 事件的 title/artist 字段,来源标记由 NativeMediaSink.setBridgeMode() 驱动;底部徽标行 Electron 圆点变绿(peers > 0)。同一时刻设备外放 TTS"好的,为你播放起风了"——这句话先取 result.speak,缺省时回落到目录里 media.playSearch 的 ttsOk 模板 好的,正在播放{query} 填槽。

请添加图片描述

这轮是"音量调到八十"——中文数字十位组合的实测(这个坑在第 5.1 节和坑四都有戏份):结果卡 ✓ 音量已调到 80,正在播放卡同步到 音量 80。指令在桥上跑,播放器的"手"也在桥的另一端——但浮层看到的永远只有一个出口:DispatchCenter.finish()。

单轮看的是深度,跑批看的是覆盖。scripts/demo-shots.js 把 9 条技能串成一轮(每条都走 execute → command → result/state 全链路,回推后自动截图),真机一轮下来的 NLU 判定:

用户说skillIdscore槽位
我要听夜曲media.playSearch68query=夜曲
下一首media.next103—
音量调到八十五media.volume69level=85
静音media.mute102—
暂停media.pause102—
继续播放media.play104—
现在放的什么media.nowPlaying106—
上一首media.prev103—
别放了media.stop103—

带槽位的两条 score 偏低(68/69)是公式使然:固定段短、槽位加分少;纯指令 102-106 是 100 + 模式长度 的整段命中。这张表也是回归基线——目录里每条话术的改法,都该让这张表保持稳定(「别放了」最初被我归进 media.pause,跑批时当场现形,归回 media.stop 的过程见第 5.1 节)。

请添加图片描述

这张是另一轮"我要听告白气球"之后、对端断开前的截图(音量 60 · Electron 执行中)。对端一断,setBridgeMode(false) 立刻把状态卡拉回原生演示态——正在播放卡的"来源"永远是当下真实的执行方,这是仲裁器诚实的一面:它不假装 Electron 还在线。

桥之外的两个入口——真机上的语音条和文本条——也各有一轮实录。

按下「语音指令」,第一次会撞上系统的麦克风权限弹窗:

请添加图片描述

允许 "Electron" 访问你的麦克风?——文案里的 “Electron” 是应用名(签名 profile 的 bundle 对应 label),副标题「语音指令需要使用麦克风进行语音识别」来自 module.json5 里 ohos.permission.MICROPHONE 的 reason 资源。允许之后 ASR 引擎真正开始拾音:

请添加图片描述

胶囊变成红色「在听…(点按结束)」,下方浮出一行「正在听…说完自动执行」——这一态由 SpeechPipeline.listen() 驱动,转写片段经 emitter 投回 UI 线程,说完自动进 NLU。不方便说话的场景走文本条:输入「播放晴天」回车,走的还是同一个 DispatchCenter:

请添加图片描述

结果卡 ✓ 点播 · 晴天 · 语音条 · media.playSearch,正在播放卡是「晴天 ▶ · 原生演示」——此刻桥上没有对端,仲裁器把执行权交给了原生 sink,来源标记如实写着「原生演示」。输错的话术也有兜底路径,没有听懂「N播放晴天」 的失败卡(✗ 红色样式)同样如实呈现,不装懂。

最后诚实交代边界:这轮验证里,command 的执行方是 macOS 上跑同一份 bridge.js 的 Node 客户端,不是真机上的 Electron 主进程——因为这台 phone 镜像派生不了 Chromium 子进程(坑一)。协议层、NLU 层、仲裁层的代码与真机 Electron 容器中将要跑的完全一致,差的那一层只是"Node 进程住在哪个沙箱里"。

3. 原理:一句「我要听起风了」从说到做完,系统到底走了哪几步

把这条指令的完整旅程画出来,一共五段:

[麦克风] CoreSpeechKit speechRecognizer(离线 ASR,zh-CN 16k mono S16)
    │ onResult: "我要听起风了"(isLast → final)
    ▼
[HAR] VoiceCoordinator.postFinal ── emitter(VOICE_EVENT_ID) 跨线程投递 → UI 线程
    ▼
[HAR] DispatchCenter.dispatch("我要听起风了", source='voice')
    │ NluEngine.match → { skillId: 'media.playSearch', slots: {query: 起风了} }
    │ 仲裁:bridgeOnline()? ── peers > 0 ──▶ 是
    ▼
[HAR] VoiceBridgeServer.broadcast('command', {...})        ← 执行权在这里移交
    ▼
[Node] bridge.on('command') → agent.handle(cmd) → handlers['media.playSearch']()
    │ 真正的媒体操作(切歌/查曲库/改音量)
    │ bridge.sendEvent('result', {...}) + sendEvent('state', {...})
    ▼
[HAR] DispatchCenter.onBridgeResult / onBridgeState
    │ finish() → VoiceCoordinator.postResult(结果卡)+ SpeechPipeline.speak(TTS)
    ▼
[浮层] 结果卡 ✓ 3.5s · 正在播放卡「Electron 执行中」 · 设备外放播报

反向链路(小艺指挥播放器)是另外两个入口、同一个调度中心:

[小艺] "用声控媒体台播放起风了"
    ▼ InsightIntent 意图框架(insight_intent.json: PlaySearch, domain Media.NAudioPlaying)
[宿主 entry] EntryVoiceIntentExecutor.onExecuteInUIAbilityForegroundMode(name, param)
    │ VoiceIntentMapper.skillIdForIntent('PlaySearch') → 'media.playSearch'   ← 参数回译
    ▼
[HAR] DispatchCenter.dispatchIntent('media.playSearch', {query: ...}, 'intent')
    │ ……此后与正向链路完全相同(仲裁 → command/result → 结果卡 → TTS)
    ▼
[宿主] InsightIntentSupport.executeResult(ok) → 小艺语义卡显示执行结果

[小艺 Agent] A2A 会话数据
    ▼ AgentExtensionAbility(type: agent,API 24+)
[宿主 entry] EntryAgentExtensionAbility → AgentSupport.handleAgentData(data)
    │ extractUserText → DispatchCenter.dispatch(text, 'agent')   ← 同一个大脑

把三个入口和它们的方向列成表:

入口方向递给应用的东西应用要回答什么
应用内语音条用户 → 应用ASR 转写文本直接执行(NLU 在应用内)
InsightIntent小艺 → 应用intentName + 结构化 params回填 ExecuteResult(resultCount/responseMessage)
AgentExtensionAbility / A2A小艺 ↔ 应用会话 JSON(用户文本/指令卡)同步返回应答 JSON
回环桥 command应用内(原生 → Node){skillId,name,slots,text,source}result 事件 + 可选 state 事件
回环桥 executeNode → 原生{text}应答(解析结果)+ 广播 command

这张表里最容易被想岔的是最后一行:Node 侧的 execute 不是"让原生执行一条指令",而是"把一句话交给原生的 NLU"——解析完原生会把 command 再广播回来,Node 真正执行。为什么不直接在 Node 里解析?因为两条路要用同一颗大脑:小艺意图和语音条都汇到 ArkTS 侧的调度中心,Node 若另养一套解析,两条入口就会在边界上分叉。

三个细节值得单独说:

一,ASR 是"写入音频"模型,会话要显式收尾。 startListening({sessionId, audioInfo}) 之后引擎内部录音(16 kHz、单声道、S16),finish(sessionId) 主动结束本轮、引擎补发最终结果,cancel(sessionId) 直接丢弃。回调线程不是 UI 线程——onResult 到达后要经 emitter 投回 UI 线程再碰 @State,这条投递链就是 VoiceCoordinator 存在的理由。

二,TTS 的失败不阻断闭环。 引擎起不来(部分镜像无离线 TTS 资源)或 speak 抛错时,SpeechPipeline.speak() 返回 false、结果卡照常弹出——宁可没有播报,不能让状态卡死。播报文案有两级兜底:result.speak(Electron 侧写的)→ 目录模板 ttsOk/ttsFail 填槽。

三,仲裁只在 dispatch 时判定一次,但不猜未来。 bridgeOnline() 是 peerCount() > 0 的当下快照,dispatchViaBridge 内部挂 8 秒超时——超时不是因为"猜桥快断了",而是因为 command 可能被对端收到却没回 result(进程崩了、网络分区在这个回环上不存在,但进程死是存在的)。超时回落不是重试,是换执行方:sink 兜底执行同样的 skillId,闭环的结果永远有一个出口。

这两个细节(跨线程投递 + 8 秒兜底)决定了后面所有的降级逻辑,第 5 节逐个展开。

4. 工程怎么搭

三方库的目录形态对齐 atomgit 上 RN 系三方库的惯例——根目录 lib/(JS 侧)+ ohos/(HAR)+ example/:

electron-ohos-voice-agent/
├── lib/                          # 纯 JS:主进程 / 预加载 / 渲染层 / 共享件
│   ├── main/
│   │   ├── bridge.js             #   VoiceAgentBridge:端口探测 + 重连 + 请求配对 + 事件分发
│   │   └── index.js              #   VoiceAgent:handle()/execute()/speak()/syncState()/registerIpc()
│   ├── preload/index.js          #   contextBridge 暴露 window.voiceAgent
│   ├── renderer/                 #   网页语音 HUD(Web Speech API → 同一条执行链路)
│   └── shared/
│       ├── protocol.js           #   NDJSON 编解码 + 端口表 + 请求/事件类型常量
│       └── intents.js            #   11 条技能目录 + 规则 NLU(与 ArkTS 逐条对齐)
├── types/index.d.ts              # TS 类型(Skill / ParsedCommand / ExecuteResult / VoiceAgent)
├── ohos/electron_ohos_voice_agent/
│   ├── Index.ets                 #   导出:VoiceAgentHost / VoiceBridgeServer / DispatchCenter / …
│   └── src/main/ets/
│       ├── VoiceBridgeServer.ets #   TCPSocketServer:4 端口探测 + NDJSON + 请求/事件分发
│       ├── DispatchCenter.ets    #   调度中心:仲裁 + 8s 兜底 + 结果卡/TTS 出口
│       ├── NluEngine.ets         #   规则 NLU(normalize/match/parseNumber,镜像 intents.js)
│       ├── IntentCatalog.ets     #   11 条技能目录(与 intents.js 互为镜像)
│       ├── NativeMediaSink.ets   #   原生兜底:内置演示曲库 + setBridgeMode()
│       ├── SpeechPipeline.ets    #   CoreSpeechKit 离线 ASR/TTS + 真实探测
│       ├── VoiceCoordinator.ets  #   emitter 跨线程投递(socket/ASR 线程 → UI 线程)
│       ├── VoiceAgentHost.ets    #   原生浮层(自检面板/结果卡/正在播放卡/麦克风胶囊)
│       ├── InsightIntentSupport.ets  # 意图回译 + 执行 + ExecuteResult 回填
│       ├── AgentSupport.ets      #   AgentExtensionAbility 数据处理(A2A JSON)
│       └── A2ASupport.ets        #   createA2AServer 使用方包装(import lazy)
│   └── templates/                #   宿主薄子类模板(执行器不能放 HAR)+ insight_intent.json 模板
├── example/
│   ├── electron-app/             # 声控媒体台:main.js handlers + preload + 网页 UI
│   └── ohos-host/                # 鸿蒙容器工程:electron(entry) + voice_native(feature)
│       ├── electron/             #   Electron 容器(libelectron.so + web_engine)
│       └── voice_native/         #   纯 ArkUI 入口:浮层 + 意图/Agent 执行器注册
├── scripts/
│   ├── build-hap.sh              # 构建 + 安装(entry/feature 双 HAP)
│   └── smoke.js                  # 协议/NLU/桥冒烟(9 项断言,无需设备)
└── dist/                         # voice-agent-console.hap + voice-agent-native.hap

这次整理最关键的变化,是把"能跑"变成"能复用",三条边界卡死:lib/ 不依赖 Electron 类型(bridge.js 只用 Node 的 net,桌面 macOS 也能跑同一份冒烟测试);HAR 不承载系统执行器(InsightIntentExecutor / AgentExtensionAbility 必须住在宿主 entry,HAR 只提供逻辑与薄子类模板);example 只走公共 API(main.js 里没有一行摸到 bridge 内部字段)。

Electron 侧接入三步,十几行:

// example/electron-app/main.js(节选)
const { createVoiceAgent } = require('electron-ohos-voice-agent');

const agent = createVoiceAgent({ window: win });   // ① 创建并自动连桥
agent.registerIpc(ipcMain);                        // ② 渲染层通道(window.voiceAgent)

agent.handle(async (cmd) => {                      // ③ 统一执行器:三条入口汇到这里
  const fn = handlers[cmd.skillId];
  const result = fn ? fn(cmd) : { ok: false, reason: '未实现的指令:' + cmd.skillId };
  sync();                                          //   syncState → 原生正在播放卡
  return result;                                   //   返回值即 result 事件载荷
});

鸿蒙侧两步:页面挂浮层,Ability 里启动桥:

// 宿主页面(voice_native/pages/NativeIndex.ets,节选)
import { VoiceAgentHost } from 'electron-ohos-voice-agent';

Stack() {
  Column().linearGradient(...)   // 底色(Electron 容器页这里换成 WebWindow())
  VoiceAgentHost()               // 全屏浮层,hitTestBehavior(None)
}

// NativeEntryAbility.onCreate
VoiceBridgeServer.shared().start();   // 返回实际端口(0 = 全部被占)

小艺意图的宿主侧声明(HAR 模板复制 + 两处 metadata):

// voice_native/src/main/module.json5(节选)
"abilities": [{
  "name": "NativeEntryAbility",
  "metadata": [
    { "name": "ohos.insightIntent",         "resource": "$profile:insight_intent" },
    { "name": "ohos.insightIntent.executor", "value": "EntryVoiceIntentExecutor" }
  ]
}],
"extensionAbilities": [{
  "name": "EntryAgentExtensionAbility",
  "srcEntry": "./ets/EntryAgentExtensionAbility.ets",
  "type": "agent",
  "exported": true
}]

协议速查(NDJSON,每行一个 JSON;v 固定为 1):

方向消息说明
Node → 原生{v,id,type,payload} type=probe/skills/execute/speak/dismiss请求,按 id 配对,6s 超时
原生 → Node{v,id,ok,data}请求应答
原生 → Node{v,event:"command",data:{skillId,name,slots,text,source}}执行权移交
Node → 原生{v,event:"result",data:{ok,display,speak,skillId,title,artist}}执行结果(说话卡 + 填槽 TTS)
Node → 原生{v,event:"state",data:{title,artist,playing,volume}}播放器状态(正在播放卡)
原生 → Node{v,event:"asr"/"log",data}听写中间结果 / 调试日志

这张表要配一个提醒才完整:请求和事件是两种消息——请求的字段叫 payload,事件的字段叫 data。第 6 节坑三就是这条差异教我做的。

最后是三道闸,每一道都对应一种"线还在、事没成"的竞态:

  • 请求配对闸(6s):Node 侧每个请求按 id 挂 pending 表,6 秒没等到应答直接 reject——不给"半死连接"留侥幸;
  • 执行兜底闸(8s):command 广播后原生只等 8 秒 result,超时回落 sink——command 是 fire-and-forget,它需要的不是重试而是换执行方;
  • 断连切闸(即时):peer 断开 → setBridgeMode(false) → 状态卡来源标记回落"原生演示",下一条指令直接走 sink。没有轮询、没有延迟确认,on('close') 里同步完成。

5. 把代码讲透

5.1 一份目录,两端共用:NLU 的打分与槽位

这套 NLU 没有模型,只有一份目录和一条打分公式。IntentCatalog.ets(ArkTS)与 intents.js(Node)逐条镜像,目录项长这样:

// IntentCatalog.ets - build()(节选)
list.push(new VoiceSkillDef('media.playSearch', '点播', '按歌名或歌手点播',
  ['播放{query}', '放{query}', '我要听{query}', '来首{query}', '给我放{query}', '搜{query}'],
  [new VoiceSlotDef('query', SLOT_TEXT, true, ['告白气球', '周杰伦'])],
  '好的,正在播放{query}', '没有找到{query}'));

每个技能带四样东西:utterances(模式,{槽位} 内插)、slots(类型与是否必填)、ttsOk/ttsFail(播报模板)。匹配时模式被编译成"固定词段 + 槽位段"的序列:

// NluEngine.ets - matchPattern()(节选)
if (segs.length === 1 && segs[0].slot === null) {
  if (text !== segs[0].text) {
    return null;
  }
  m.score = 100 + fixedLen;          // 整段命中:"下一首" → 103,稳压一切带槽位的匹配
  return m;
}
// ……带槽位的路径:固定词越长、槽位填得越满,分越高
m.score = 60 + fixedLen + filled * 5;   // "我要听起风了" → 60 + 3 + 1×5 = 68

三个细节值得单独说:

第一,打分公式解决的是模式间的抢人。 “音量调到八十"同时可能擦到 音量{level}(命中)和 音量大点(不命中)——整段命中 100+ 档、带槽位 60+ 档的设计让"精确短语"永远赢过"模糊擦边”,实测 下一首 得 103、我要听告白气球 得 68,目录内部不会打架。

第二,槽位是贪婪的,但边界由下一个固定词决定。 我要听{query} 里 query 一直吃到句尾;音量{level}和{level}之间 这种双槽位模式(如有)靠中间固定词切段。槽位抽取后按声明类型规整:number 类型走 parseNumber,非数字原样保留。

第三,中文数字的坑不在匹配、在词法。 parseNumber 的第一版逐字查表,八十 返回 8——十位组合不存在于单字表里。修法是先收集连续中文数字段,再按"十"的位置组合:

// NluEngine.ets - parseNumber()(节选,修复后)
const tenIdx = chars.indexOf('十');
if (tenIdx > 0) {
  const tenV = cn.get(chars[tenIdx - 1]);
  const ten = (tenV !== undefined ? tenV : 1);
  let ones = 0;
  for (let i = tenIdx + 1; i < chars.length; i++) { /* 个位 */ }
  return ten * 10 + ones;      // "八十" → 80,"八十五" → 85
}
if (tenIdx === 0) { /* "十五" → 10 + 5 */ }

同一份修法在 intents.js 里同步了一遍——目录和 NLU 是镜像的,任何一端修 bug 不同步另一端,两条入口就会分叉出两种行为,这比 bug 本身更危险。冒烟测试里压了一条 ['音量调到八十', 'media.volume', '80'],两端谁再退步都会在无设备的 CI 里先红。

数字之外还有一类更隐蔽的错:归错意图。跑批截图时「别放了」的结果卡写着 ✓ 已停止播放 · media.pause——display 是我 Node 侧写的、skillId 却是 NLU 判的,两行一对照就露馅:我把「别放了」编进了 pause 的话术表,但用户语境里它是"别放了=别播了=停下别唱了",更贴近 stop。修正只是把这条话术从 pause 的 utterances 挪进 stop(两端同步 + 冒烟用例补上 ['别放了', 'media.stop']、['不听了', 'media.stop']),真机复测结果卡变成 已停止播放 · media.stop。这类错的教训不是"NLU 不准",而是执行结果卡要把 skillId 亮出来——没有那个小字,归错意图根本不会被看见。

5.2 执行仲裁:8 秒兜底闸门

DispatchCenter 是所有入口共用的闭环,仲裁就一段:

// DispatchCenter.ets - dispatch()(节选)
if (DispatchCenter.bridgeOnline()) {
  outcome = await DispatchCenter.dispatchViaBridge(match, text, source);
} else {
  outcome = DispatchCenter.dispatchViaSink(match);
}
DispatchCenter.finish(outcome, match.skillId, source);

dispatchViaBridge 是整个库里最容易写错的一个函数,它不是"发出去就行":

// DispatchCenter.ets - dispatchViaBridge()(节选)
return new Promise<SinkOutcome>((resolve: (value: SinkOutcome) => void) => {
  const timeout = setTimeout(() => {
    if (DispatchCenter.pendingResult !== null) {
      DispatchCenter.pendingResult = null;
      VoiceCoordinator.postLog('桥执行超时,原生兜底');
      resolve(DispatchCenter.dispatchViaSink(match));   // ← 换执行方,不是重试
    }
  }, 8000);
  DispatchCenter.pendingResult = (outcome: SinkOutcome) => {
    clearTimeout(timeout);
    DispatchCenter.pendingResult = null;
    resolve(outcome);
  };
  VoiceBridgeServer.shared().broadcast('command', cmd as Object);
});

三个细节值得单独说:

第一,pendingResult 是单槽不是队列。 一次只有一条指令在等桥执行;第二条指令进来时如果上一条还没回,超时闸会保证 8 秒后槽位清空。要不要做队列是产品判断——语音指令的用户期待"最后一条说了算",排队反而是伤害。

第二,sink 兜底执行的是同一个 skillId。 dispatchViaSink(match) 拿的是同一个 match(skillId + slots),不是"随便播个默认歌"。兜底的语义是"换个手执行同一个意图",用户看到的仍是他要的那个结果(演示曲库版)。

第三,finish 是唯一出口。 无论走桥还是走 sink,finish() 统一负责"结果卡 + TTS",来源标记(source)如实进卡。浮层不需要知道也不该知道指令是哪条路执行的——它只渲染结果。这一刀切下去之后,仲裁逻辑再改(比如加超时档位、加对端心跳)都不用碰 UI。

5.3 回环 TCP 桥:事件与请求是两种消息

服务端从 4 个端口里挑一个能听的:

// VoiceBridgeServer.ets - start()(节选)
const candidates: number[] = (ports !== undefined && ports.length > 0) ? ports : DEFAULT_PORTS;
for (let i = 0; i < candidates.length; i++) {
  const ok = await this.listen(candidates[i]);   // 47131..47134 依次试
  if (ok) {
    return this.port;
  }
}

为什么是 4 个端口:沙箱里其他组件(或并行的另一个 Electron 应用)可能占着 47131,端口表是双端镜像的常量(DEFAULT_PORTS),Node 侧按同一顺序探测——谁先占住谁是服务端,后连的对端按序找。127.0.0.1 回环不走网卡、无权限声明负担,是日历那篇验证过的老路,这次只是把它从"两个进程"扩展到"三个进程"。

handleLine 的分发顺序是这段代码的命门:

// VoiceBridgeServer.ets - handleLine()(节选)
const id = Number(msg['id'] ?? 0);
const type = String(msg['type'] ?? '');
const payload: ESObject = msg['payload'] ?? {};

// Node → 原生的单向事件(result / state):数据在 msg['data']
const evt: ESObject = msg['event'];
if (evt !== undefined && evt !== null && evt !== '') {
  this.onNodeEvent(String(evt), msg['data'] ?? {});   // ← 先判事件,再进请求 switch
  return;
}

三个细节值得单独说:

第一,事件判别必须在请求 switch 之前。 事件消息没有 type 字段,msg['type'] 会落进 default: unknown type——我曾把事件分支放在 switch 之后,所有 result/state 都被当成未知类型丢掉了(坑三的另一半)。先判 event 再判 type,两种消息永不串线。

第二,NDJSON 的缓冲是按 peer 隔离的。 TCP 不保证一次 message 回调是一条完整行,peer.buffer 按连接各自攒、按 \n 切——多 peer 并发时缓冲绝不共享,否则 A 的半行会拼进 B 的行头。

第三,Node 侧的重连是指数退避,上限 10 秒。 bridge.js 断线后从端口 0 重新探测,失败轮数翻倍退避;连上后 retries 清零。容器刚启动时桥可能还没 listen,Node 先起也没关系——退避会把它等回来。

5.4 语音管线:真实探测,失败即降级

能力探测不做"查配置"这种假动作,真建一次引擎再销毁:

// SpeechPipeline.ets - probeAsr()(节选)
const extra: Record<string, Object> = {
  'locate': 'CN',
  'recognizerMode': 'short'
};
const engine = await speechRecognizer.createEngine({
  language: 'zh-CN',
  online: 1,
  extraParams: extra
});
engine.shutdown();
return true;              // false 分支:权限没给、镜像无引擎、参数不被支持

三个细节值得单独说:

第一,探测失败的原因要在 probe 响应里能区分。 probeAsr 内部把 e.code/e.message 写进 hilog,浮层自检面板把结论展示成"ASR 可用/不可用"。降级的前提是"知道为什么降级"——权限问题和镜像缺资源是完全不同的两种修法。

第二,recognizerMode: 'short' 不是可选项。 离线引擎按短语音设计(zh-CN、16k、单声道、S16),长句不是"效果差"而是会话行为不保证。音频参数在 startListening 时显式声明,采样率错会直接抛错——这也是自动化回放的抓手:录一段 16k PCM 按块喂进去,无需真人即可验证全链路。

第三,麦克风权限必须先于 createEngine。 顺序反了引擎照样建出来,但每个会话都拿不到音频、onError 才见真章。浮层"语音指令"按钮的按下回调里第一行就是 requestPermissionsFromUser——这是 Qt 那篇踩过的同一个坑,这次直接按对的顺序写。

5.5 小艺两条入口:薄子类 + 参数回译

InsightIntentExecutor 和 AgentExtensionAbility 不能放进 HAR——系统执行器要求 srcEntry 指向宿主模块的编译产物。HAR 的做法是:逻辑全在库里,宿主只复制一个薄子类:

// templates/EntryVoiceIntentExecutor.ets(宿主 entry 模块,薄子类)
export default class EntryVoiceIntentExecutor extends InsightIntentExecutor {
  onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>,
    pageLoader: window.WindowStage): insightIntent.ExecuteResult | Promise<insightIntent.ExecuteResult> {
    return InsightIntentSupport.execute(name, param).then((ok: boolean) => {
      return InsightIntentSupport.executeResult(ok, '');
    });
  }
  // onExecuteInUIAbilityBackgroundMode:锁屏/后台场景,同样转发
}

InsightIntentSupport.execute 做的就是参数回译:PlaySearch + {query: 起风了} → skillIdForIntent('PlaySearch') 得 media.playSearch,结构化参数直接进 dispatchIntent()(免一次 NLU);文本型入口(A2A 的用户话)则回译成中文走 dispatch(text, 'agent')。意图目录的 intentName 与 skillId 的映射是静态表——11 条技能、11 个意图、一一对应,新增技能时三处(目录 JS、目录 ArkTS、intentName 映射)同步加。

三个细节值得单独说:

第一,AgentFrameworkKit 一律 import lazy。 它的实现体在 HMS 的 HSP 里,静态 import 是启动期绑定,镜像缺 HSP 就是进程 abort(Qt 那篇坑一的亲兄弟);import lazy 延迟到第一次触碰才抛错,可被接住、可降级。库里的 A2ASupport 全程用它。

第二,ExecuteResult 是小艺看见的"执行结果"。 executeResult(ok, display) 回填的结构决定小艺语义卡显示"已完成"还是"失败"——桥在线时这个 ok 来自 Electron 的 result 事件,所以小艺的卡片诚实反映的是 8 秒闸门裁决后的真实结果,不是"我把指令递出去了"。

第三,模拟意图按钮是真链路的开关。 浮层上那 11 个按钮不是 demo 装饰:它们走 dispatchIntent(),与小艺拉起唯一差别是"没有系统的语义解析在前"。注册材料齐不齐(平台侧 intentName 注册)不影响这条链——这让"小艺接入"可以从第一天就在真机上验证,不等平台审核。

6. 我踩过的坑

坑一:Electron 容器在这台 phone 镜像上起不来——16010004 Capability not support。 装上 HAP、aa start EntryAbility,容器 UI 起来后白屏,Chromium 子进程派生被系统拒绝:

Error Code:16010004  Error Message: Capability not support
// hilog:CustomChildProcess fork 失败,渲染进程无法创建

一开始以为是签名或权限漏了,把 maxChildProcess、权限表、profile 逐项核对都没问题——是镜像本身不支持派生(2in1/特定镜像支持,phone 镜像不支持)。教训:能力探测要前置到"选宿主"这一层——voice_native feature 模块就是为这一天准备的纯 ArkUI 入口,闭环验证不等容器。

坑二:probe 全绿、徽标永远红——@Builder 按值传参不响应。 最迷惑的一个:自检面板里 cap #4 {"asr":true,...,"port":47131} 明明白白,底部徽标行四个红点纹丝不动。排查从"是不是探测没跑"一路查到"是不是单例被建了两次",最后才反应过来:

// 反例:把 @State 算成布尔再传给 @Builder —— 状态变化后徽标永不重建
this.dot(this.capability.port > 0, '桥')

// 正解:@Builder 体内直接读 this.capability
if (this.capability.port > 0) { this.dot(true, '桥:' + String(this.capability.port)) }

@Builder 的参数是按值传递的,快照在首次渲染时就定型了。 结果卡、正在播放卡全踩过同一脚。教训:ArkUI 里凡是"数据对了但 UI 不动",先查 @Builder 传参,再查别的。

坑三:ok:true 进去,✗ 执行失败 出来——事件字段是 data 不是 payload。 桥上收到的 result 事件明明 ok:true,浮层结果卡却永远显示失败。把线上字节抓下来逐行看,才发现请求走 {id,type,payload}、事件走 {event,data},而 handleLine 里事件分支拿的是 msg['payload']——事件消息里这个字段不存在,取出来永远是 {}。教训:双语义消息(请求/事件)共线传输时,字段判别要集中在一处、且有协议测试压着——smoke.js 的第 2 项就是为它写的。

坑四:“音量调到八十” = 音量 8。 中文数字单字查表的经典事故(5.1 节已讲)。真机上结果卡显示 音量已调到 8,用户听到的是"音量已调到八"。教训:中文口语解析的 bug 不在匹配规则里,在词法细节里,每一条都要有断言压着。

坑五:HAR 编译五连击。 首次编译一口气报了五个:Namespace 'emitter' has no exported member 'Callback'(emitter 不导出 Callback 类型,改 ((e: emitter.EventData) => void));Property 'flexWrap' does not exist on RowAttribute(Row 没有 flexWrap,换 Flex 或重新布局);arkts-no-any-unknown(ESObject 也要显式标);arkts-no-untyped-obj-literals({ eventId } 要先声明 emitter.InnerEvent 类型);arkts-no-implicit-return-types(生成执行器的 lambda 返回类型必须写全)。外加 textToSpeech.FinishResponse 不存在(TTS 回调类型是 StopResponse/SynthesisResponse/CompleteResponse)。教训:ArkTS 严格模式没有"先跑起来再补类型"这条路,类型是入场券。

坑六:insight_intent.json 的 schema 与 .ets 后缀。 第一版把注册项写成字符串数组,hvigor 报 Schema validate failed——insightIntentsSrcEntry 必须是对象数组;改成对象数组后又报 Cannot find the file .../PlayMusicIntent,因为 srcEntry 少了 .ets 后缀。两处修正:

// resources/base/profile/insight_intent.json(节选,正确形状)
{
  "insightIntents": [
    { "intentName": "PlaySearch", "domain": "Media.NAudioPlaying", "intentVersion": "1.0.0",
      "displayName": "点播", "srcEntry": "./ets/insightintents/PlaySearchIntent.ets" }
  ],
  "insightIntentsSrcEntry": [ { "srcEntry": "./ets/insightintents/EntryVoiceIntentExecutor.ets" } ]
}

教训:意图框架的配置校验是逐字段的,报错指向的文件不一定是有问题的那个字段。

坑七:assembleHap 只打 entry,feature 要分开装。 assembleHap 产物只有 electron(entry) 一个 HAP,voice_native(feature) 不在里面;改用 assembleApp 打出 .app,真机安装报 no signature file(.app 的签名路径和 HAP 不同)。最终姿势:两个模块各自出 signed HAP,hdc install entry.hap feature.hap 一次装两个。教训:多模块应用在命令行构建下的第一课,是搞清楚每个 hvigor 任务名的产物边界。

坑八:INFO 级 hilog 被系统丢弃 + 同包名版本号拉锯。 真机排查时发现自家应用的 info 日志一条都看不到——系统默认丢弃应用域 INFO,只剩 W/E;坑二那种"数据对了 UI 不动"的问题在日志层完全隐形,最后靠浮层诊断行(cap #N {...})和 hdc fport + 协议探针定位。同一台测试机还和其他实验共用 com.example.immersiveoverlays,并行安装互抬 versionCode,9568263 install version downgrade 拉锯了几轮,uninstall + install 绕过。教训:真机调试不能只信 hilog,屏上诊断行 + 协议探针是"日志被吞"时的第二条命。

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

Electron 应用接入。 npm 包导出主进程/预加载/渲染层三个入口:

// main.js
const { createVoiceAgent } = require('electron-ohos-voice-agent');
const agent = createVoiceAgent({ window: mainWindow });
agent.handle(async (cmd) => {           // cmd = { skillId, name, slots, text, source }
  if (cmd.skillId === 'media.playSearch') return player.play(cmd.slots.query);
  if (cmd.skillId === 'media.next') return player.next();
  return { ok: false, display: '不支持' };
});
agent.registerIpc(ipcMain);

// preload.js —— 一行
require('electron-ohos-voice-agent/preload');

自定义技能传 createVoiceAgent({ skills: [...] })(结构同 DEFAULT_SKILLS),鸿蒙侧 HAR 的 IntentCatalog.ets 同步——目录是三处镜像的(JS / ArkTS / intentName 映射),只改一处会在真机上分叉。

鸿蒙容器工程接入。 oh-package.json5 依赖 "electron-ohos-voice-agent": "file:../voice_agent",页面挂 VoiceAgentHost(),Ability 里 VoiceBridgeServer.shared().start();小艺意图按 templates/ 的清单复制薄子类 + insight_intent.json + 两处 metadata。

构建与验证。

bash scripts/build-hap.sh --install       # 打包 + 双 HAP 安装(HDC_TARGET=<serial> 指定设备)
hdc shell aa start -a NativeEntryAbility -b com.example.immersiveoverlays -m voice_native
node scripts/smoke.js                     # 协议/NLU/桥冒烟,9 项断言,无需设备

总结:

本文围绕CPF-Electron 鸿蒙端语音媒体控制完整落地方案展开,核心解决鸿蒙PC/手机环境下,Electron容器、ArkTS原生系统能力、小艺意图与Agent智能体之间跨进程语音指令闭环难题,本质是打通一套“小艺语音入口→鸿蒙原生ASR/NLU仲裁→TCP桥转发给Electron主进程执行→结果回传+TTS播报”的降级可控链路,同时处理鸿蒙Electron生态本身的容器能力限制、多进程隔离、系统语音API约束等特有痛点。

整个场景最大的底层矛盾,是三套运行环境互相隔离带来的“三个世界”割裂:Chromium渲染进程、Electron主进程(Node)、鸿蒙宿主UIAbility(ArkTS)不存在共享运行时,Node层无法直接调用鸿蒙CoreSpeechKit离线语音识别、TTS播报;而小艺的InsightIntent意图框架、AgentExtensionAbility智能体能力又只能在ArkTS侧接入,媒体播放状态、曲库、播放逻辑却托管在Electron的Node主进程,原生没有办法直接读取和控制。RN方案里复用的回环TCP NDJSON桥,成为这套跨进程通信的基础载体,在不侵入Electron底层源码、不新增复杂Node-API绑定的前提下,完成双向消息传递。

整套方案的架构设计上,鸿蒙侧承担感知、理解、调度、兜底播报的职责,Electron侧承担业务执行、媒体状态维护的职责。鸿蒙侧内置完整调度中心DispatchCenter,统一接收三类语音指令来源:应用内麦克风语音条、小艺InsightIntent意图拉起、小艺A2A Agent会话消息,所有入口最终收敛到同一套NLU规则引擎和执行仲裁逻辑,保证不同入口的语义理解行为一致,避免多入口语义分叉。NLU采用规则模板匹配而非大模型,维护一份两端镜像的技能目录,JS侧intents.js和ArkTS侧IntentCatalog.ets逐条对齐,包含点播、切歌、音量调节、暂停、停止、查询播放信息等11项媒体技能,支持槽位提取、中文数字解析,并设计打分公式,固定短语整段命中高分优先,带槽位点播指令分数次之,规避不同模板互相抢占匹配的问题,配套冒烟测试用例,提前捕获语义匹配、中文数字解析这类容易出错的逻辑。

通信层采用本地回环TCP服务,在47131~47134端口范围内自动探测可用端口,服务端跑在鸿蒙HAR内,Node客户端在Electron主进程连接,协议采用NDJSON按行分隔,严格区分请求消息和事件消息两类结构:请求携带id、type、payload,支持配对应答、6秒超时;事件携带event、data,用于下发指令、回传执行结果、同步播放器状态、推送ASR中间文本,在解析时优先判断事件分支,规避字段混淆的bug。TCP连接做了单连接状态管理、断线即时感知、客户端指数退避重连,同时对每条指令加入8秒执行超时仲裁机制:桥在线时,调度中心把解析后的command指令广播给Electron等待结果;8秒内没有收到result回包,自动切换到原生媒体兜底Sink执行相同技能,不会阻塞闭环,用户始终能拿到反馈,不会出现指令发出无响应的情况。

Logo

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

更多推荐