Electron 鸿蒙媒体实战:打通小艺 Skill 与 Agent 语音指令,TCP 桥实现 Electron 跨端语音操作闭环
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) |
| 系统 API | HarmonyOS 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”,应用要听懂、执行、播报;反过来小艺也要能指挥这个播放器。
我的朴素理解很直接:小艺是个系统语音入口,在配置文件里注册一下,指令就会从系统流进来,我执行完把结果告诉系统就行。撑了不到半天,三份资料并排翻开之后被推翻了:
- 小艺递给你的是"请求",不是"结果"。 InsightIntent 意图框架把用户的话解析成结构化参数(intentName + params)递给
InsightIntentExecutor,AgentExtensionAbility把 A2A 会话数据递给你——它们都不替你执行。执行完还要主动回填ExecuteResult,小艺的语义卡才有东西可显示。也就是说,“注册入口"只解决"听懂”,"执行"从头到尾是应用自己的事。 - Electron 是三个世界,不是两个。 日历那篇的"JS 世界 vs ArkTS 世界"在这篇升级了:渲染进程(Chromium 画布)、主进程(
libelectron.so里跑的 Node)、宿主 UIAbility(ArkTS),三个进程在同一个沙箱里,但没有共享运行时,Node-API 桥注册不进去。日历那篇用的回环 TCP 还是唯一的路,只是这次桥的两端多了一层仲裁。 - 听与说只有 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 判定:
| 用户说 | skillId | score | 槽位 |
|---|---|---|---|
| 我要听夜曲 | media.playSearch | 68 | query=夜曲 |
| 下一首 | media.next | 103 | — |
| 音量调到八十五 | media.volume | 69 | level=85 |
| 静音 | media.mute | 102 | — |
| 暂停 | media.pause | 102 | — |
| 继续播放 | media.play | 104 | — |
| 现在放的什么 | media.nowPlaying | 106 | — |
| 上一首 | media.prev | 103 | — |
| 别放了 | media.stop | 103 | — |
带槽位的两条 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 事件 |
| 回环桥 execute | Node → 原生 | {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执行相同技能,不会阻塞闭环,用户始终能拿到反馈,不会出现指令发出无响应的情况。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)