Diting AI 语音 Demo 入门开发指南

概述

Voice Cloud LLM 是 HiDiting V100 上的云端语音助手。用户打开 OpenHarmony Lite Wearable 应用后，可以用本地唤醒词发起对话。应用显示当前对话状态，固件负责麦克风采集、连接 Coze、接收回复和扬声器播放。

启动应用 → 等待唤醒 → 采集语音 → 云端理解与生成 → 播放回复 → 等待下一轮对话

Demo 由 JS 前端和 Native 应用后端组成：

部分	目录	职责
JS 前端（OpenHarmony 应用）	`samples/js_samples/voice_cloud_LLM/`	页面入口、状态展示、主题动画，以及语音服务的启动、停止和状态订阅
Native 应用后端（设备侧）	`samples/native_samples/voice_cloud_LLM/`	本地唤醒、音频采集与播放、WebSocket 会话、云端通信和资源回收

用户在 JS 页面中操作。前端通过 @system.voiceCloudLlm 调用 Native 后端。后端完成设备侧语音处理和云端通信，再把状态和音频结果返回页面。进入应用时，JS 前端订阅语音状态并启动服务；退出应用时，它停止服务并恢复系统息屏策略。Native 后端属于示例应用的一部分，不能单独启动。

源码说明：

路径中的 LLM 为大写。在 Linux、WSL 和 GitCode 中需要保持大小写一致。

首次使用时，按“快速跑通 AI 语音 Demo”完成固件烧录、应用安装和语音对话。需要修改主题、云端智能体或本地唤醒模型时，再查阅高阶开发参考指南。代码走读、状态机和参数配置用于了解实现与调试。

快速跑通 AI 语音 Demo

硬件准备

HiDiting V100 开发板。
466×466 分辨率表盘。
扬声器。开发调试可使用 8 Ω/2 W 扬声器。
可访问互联网的网络环境。本文使用手机热点和蓝牙 PAN。

构建应用还需要 DevEco Studio 5.0 Release、匹配的 OpenHarmony SDK、Python 3 和仓库内的 ImageTool。

Coze 准备

登录 Coze 官网并注册账号。
创建个人访问令牌，记录 Access token。

下图红框中的内容是 Access token。
创建智能体，记录 URL 末尾的 bot id。

在电脑上创建 coze_setting.json：

{
  "token": "替换为个人访问令牌",
  "bots": [
    {
      "name": "默认智能体",
      "botid": "替换为智能体 ID"
    }
  ]
}

当前固件只读取 bots[0]。配置文件需要满足以下限制：

字段	要求
文件大小	不超过 8192 字节
`token`	1～255 字节；可带`Bearer` 前缀，正文仅允许字母、数字和 `-._~+/=`
`bots[0].name`	1～63 字节，不能包含控制字符
`bots[0].botid`	1～95 字节，只能包含字母、数字和`-._~`

不要把真实令牌写入源码或提交到仓库。调试时也不要在截图、日志和问题单中暴露令牌。

编译烧录

编译固件

完成一站式 CLI 环境配置后，在仓库根目录执行：

fbb set-target pack_diting_community
fbb build

固件产物为：

src/output/3322/fwpkg/diting-community.fwpkg

如果不使用一站式 CLI，也可以进入 src 目录执行：

python3 build.py pack_diting_community

准备应用图片转换工具

解压仓库中的 tools/graphic_tools.tar.gz，将 ImageTool 指向同时包含 images_tool.py 和 config.xml 的目录。

Linux 或 macOS：

export ImageTool=<absolute-path>/graphic_tools/image_converter_tool
export PYTHON=<absolute-path>/python3

Windows PowerShell：

$env:ImageTool = (Resolve-Path '<graphic_tools>\image_converter_tool').Path
$env:PYTHON = (Get-Command python.exe).Source

当前主题使用的 PNG 需要放在：

samples/js_samples/voice_cloud_LLM/entry/src/main/js/MainAbility/common/theme/assets/

图片文件必须与 common/theme/current_theme.js 中的引用完全一致。构建任务会检查文件并在中间目录完成图片转换，不需要手工生成或提交 .bin 文件。

构建应用

建议使用官网下载的最新版本 DebugKits，获取方式见 DebugKits 工具使用指南。通过 DebugKits 上传应用包、配置或模型文件前，先在串口执行 AT+PM=0 关闭低功耗，再开始上传。

参考 OpenHarmony JS 应用开发用户指南的 JS 应用开发与发布 章节完成DevEco Studio 5.0 Release工具准备。
使用 DevEco Studio 打开 samples/js_samples/voice_cloud_LLM。
选择 Build > Build Hap(s) 构建得到应用包 BIN 文件，文件位于工程 entry/build/default/outputs/default/bin/ 目录下。
使用 DebugKits 的 System > 上传文件，把应用包 BIN 文件上传为 /user/voice_cloud_llm.bin。进度达到 100% 才表示上传完成（文件较大，需要耐心等待上传完成）。操作方法参见 DebugKits 工具使用指南。
在串口执行 AT+OHOS=OHOSFWK_BM_SET,disable 关闭验签。
在串口执行 AT+OHOS=OHOSFWK_BM_INSTALL,/user/voice_cloud_llm.bin 完成应用包安装。

只修改 JS、页面样式或主题图片时，重新构建并安装 BIN 即可，不需要重编固件。

上板运行

烧录 diting-community.fwpkg，打开 UART2 串口监视器。Windows USB DFU 示例：
```
fbb flash -f "$env:FBB_SDK_DIR\output\3322\fwpkg\diting-community.fwpkg" --chip 3322 -d --timeout 180
fbb monitor --port COM3 --baud 750000
```
将 COM3 替换为实际日志串口。其他烧录方式参见一站式 CLI 开发环境使用指南。 2. 在串口执行 AT+PM=0 关闭低功耗，再进行后续配网和文件上传。 3. 在表盘中进入“设置 > 蓝牙 > 连接新手机”，按提示确认，页面显示“连接已打开”后，在手机蓝牙设置中搜索页面显示的设备名称并配对连接。打开手机热点并启用蓝牙共享网络。 4. 执行 AT+NET=NETSTACK_SWITCH,PAN 切换到蓝牙 PAN 配网。串口日志出现 pan CONNECTION_CONNECTED 即配网成功。 5. 使用 DebugKits 的 System > 上传文件，把 coze_setting.json 上传为 /user/coze_setting.json。进度达到 100% 才表示上传完成。操作方法参见 DebugKits 工具使用指南。 6. 安装应用包 BIN 后，启动 Voice Cloud LLM 应用。 7. 页面显示“等待唤醒”后，说出固件支持的唤醒词，例如“小艺小艺”。页面转变为倾听动画，显示“请说话”后即可开始对话。 8. 回复过程中如需重新提问，再次说出当前固件支持的唤醒词，打断本轮回复；待页面显示“请说话”后提出新问题。

启动应用后，页面会自动订阅语音状态并启动语音服务；退出应用时，页面会停止服务、取消状态订阅并恢复系统息屏策略。每次启动语音服务时，应用都会重新读取 /user/coze_setting.json。

默认 DSP Provider 映射的唤醒词包括“小艺小艺”“你好悠悠”“小薇小薇”和“嗨，塞莉亚”。使用 ModelZoo 替换本地唤醒模型后，应改用所选模型支持且已配置的唤醒词。

连续对话空闲约 15 秒后，应用会回到等待唤醒状态。

如需定制本地唤醒模型，参见使用 ModelZoo 替换本地唤醒模型。首次运行可先使用默认 DSP 唤醒，无需执行模型替换步骤。

代码走读

代码结构

JS 前端主要文件：

samples/js_samples/voice_cloud_LLM/
├── entry/hvigorfile.ts
│   └── 校验并转换当前主题图片
└── entry/src/main/js/MainAbility/
    ├── app.js
    ├── common/theme/
    │   ├── current_theme.js
    │   └── assets/
    └── pages/index/
        ├── index.hml
        ├── index.css
        ├── voice_page.js
        ├── voice_state.js
        ├── voice_animation.js
        └── voice_animation_config.js

Native 应用后端主要文件：

samples/native_samples/voice_cloud_LLM/
├── voice_cloud_llm.cpp
├── voice_cloud_llm_audio_capture.cpp
├── voice_cloud_llm_audio_player.cpp
├── voice_cloud_llm_ws_client.cpp
├── voice_cloud_llm_protocol.cpp
├── voice_cloud_llm_config.cpp
└── ace_adapter/

ACE Lite 中的 @system.voiceCloudLlm 模块位于：

src/ohos/foundation/arkui/ace_engine_lite/frameworks/src/core/modules/voice_cloud_llm/

核心函数

位置	函数或配置	作用
`voice_page.js`	`createVoicePage()`	管理页面生命周期、语音服务调用和动画状态队列
`voice_animation.js`	`createAnimationWindow()`	每次向组件装载不超过 20 个逻辑时间片
`voice_animation_config.js`	`STATE_CLIPS`、`TRANSITION_CLIPS`	把语音状态映射到循环动画和转场动画
`current_theme.js`	`CURRENT_THEME`	配置当前主题图片及每张图的显示时长
`voice_cloud_llm_module.cpp`	`VoiceCloudLlmModule`	向 JS 提供启动、停止、状态查询和状态订阅接口
`voice_cloud_llm_service.cpp`	`StartVoiceCloudLlmService()`、`StopVoiceCloudLlmService()`	读取`/user/coze_setting.json` 并调用设备侧语音接口
`voice_cloud_llm.cpp`	`VoiceCloudLlmWorker`	处理唤醒、会话、超时和资源回收
`ace_adapter/`	`RegisterVoiceCloudLlmNativeApi()`	连接 ACE 模块和设备侧语音组件

页面的 onShow 会订阅状态并调用 start()；onHide 和 onDestroy 会执行幂等清理。如果固件没有 @system.voiceCloudLlm，应用仍能打开，但会提示“当前固件缺少语音模块”。

状态机

页面按对话进度显示以下状态：

等待唤醒
   │ 本地唤醒词
   ▼
请说话 ──► 思考中 ──► 正在回复 ──► 等待说话
   ▲                                   │
   └──────────── 用户继续说话 ──────────┘
                                       │ 空闲约 15 秒
                                       ▼
                                    等待唤醒

页面状态	含义	典型触发条件
等待唤醒	本地唤醒引擎正在监听	应用启动、会话结束或异常恢复
请说话	麦克风采集已开始	检测到唤醒词，或连续对话中检测到新一轮语音
思考中	用户说话结束，等待云端生成回复	设备侧检测到用户说话结束
正在回复	正在播放云端返回的 PCM 音频	收到下行音频数据
等待说话	本轮回复结束，可继续提问	云端会话完成

设备侧后端还维护 WebSocket 连接、会话创建、配置同步和资源回收等状态。这些状态不会直接显示在页面上，而是映射为上述页面状态或错误提示。修改主题时不需要调整设备侧状态机。

参数配置

先判断参数属于哪一层。不同层的修改方式不同。

配置内容	位置	生效方式
Coze token、智能体 ID	`/user/coze_setting.json`	重新进入应用，无需重编 BIN 或固件
主题图片和动画显示时长	`common/theme/`	重新构建并安装 BIN
页面文案和样式	`pages/index/`	重新构建并安装 BIN
音频格式、超时和队列	`voice_cloud_llm_config.h`	重新构建并烧录固件

音频规格

当前默认值位于 samples/native_samples/voice_cloud_LLM/include/voice_cloud_llm_config.h：

参数	默认值	宏
编码格式	上行默认 G.711 A-law；关闭宏后为 PCM	`VOICE_CLOUD_LLM_UPLINK_CODEC_G711A`
上行采样率	采集 16000 Hz；G.711 上行 8000 Hz	`VOICE_CLOUD_LLM_INPUT_SAMPLE_RATE`、`VOICE_CLOUD_LLM_G711_SAMPLE_RATE`
下行采样率	16000 Hz	`VOICE_CLOUD_LLM_OUTPUT_SAMPLE_RATE`
声道数	单声道	`VOICE_CLOUD_LLM_DEFAULT_CHANNELS`
位宽	16 bit	`VOICE_CLOUD_LLM_DEFAULT_BITS`
基础帧长	20 ms	`VOICE_CLOUD_LLM_UPLINK_FRAME_MS`
每批帧数	8	`VOICE_CLOUD_LLM_UPLINK_BATCH_FRAMES`

这些参数同时影响音频驱动、云端协议和缓存大小。应用主题开发不需要修改它们。

超时与容量规格

参数	默认值	宏或常量
WebSocket 连接超时	10 s	`VOICE_CLOUD_LLM_CONNECT_TIMEOUT_MS`
会话响应超时	30 s	`VOICE_CLOUD_LLM_RESPONSE_TIMEOUT_MS`
连续对话空闲超时	15 s	`VOICE_CLOUD_LLM_IDLE_TIMEOUT_MS`
Worker 消息队列	64	`VOICE_CLOUD_LLM_QUEUE_DEPTH`
预采集缓存	20 批次，约 3.2 s	`voice_cloud_llm.cpp` 中的 `VOICE_CLOUD_LLM_PENDING_FRAMES_MAX`
WebSocket 分片上限	64 KiB	`voice_cloud_llm_ws_client.cpp` 中的 `VOICE_CLOUD_LLM_WS_FRAGMENT_MAX_LEN`

这些参数属于设备侧固件。修改后需要重新构建并烧录固件。

应用动画参数

应用动画参数位于 samples/js_samples/voice_cloud_LLM/entry/src/main/js/MainAbility/pages/index/voice_animation_config.js：

参数	默认值	常量
动画逻辑时间片	50 ms	`FRAME_TICK_MS`
单次动画装载窗口	20 个时间片	`MAX_ACTIVE_FRAMES`

samples/js_samples/voice_cloud_LLM/entry/src/main/js/MainAbility/common/theme/current_theme.js 中的 hold 是图片显示时长参数，1 个单位对应 50 ms。例如 hold: 6 表示显示约 300 ms。单次动画装载窗口表示单次装载时间片数量，与主题中物理图片的总数无关。

修改这些参数后只需重新构建并安装 BIN，不需要重编固件。

高阶开发参考指南

主题、文案和页面布局都在 OH 应用里修改，不需要改固件。替换本地唤醒模型则需要重新构建固件并部署模型文件。

替换 OH 应用主题

当前主题目录是：

samples/js_samples/voice_cloud_LLM/entry/src/main/js/MainAbility/common/theme/
├── current_theme.js
└── assets/

替换步骤：

在 voice_cloud_LLM 工程外准备一套主题，保留原始文件作为备份。
将要使用的 466×466 PNG 放入 assets/。目录内只能放当前主题实际使用的图片。
修改 current_theme.js，让每个 src 指向 /common/theme/assets/<文件名>.png。
为每张图设置正整数的显示时长参数 hold。1 个单位对应 50 ms。
删除 assets/ 中未被清单引用的 PNG，并补齐清单引用但缺失的 PNG。
清理应用构建目录，重新构建并安装 BIN。

构建脚本要求图片平铺在 assets/ 中，文件名使用小写字母、数字和下划线。清单引用与实际 PNG 必须完全一致，否则构建会直接报错。

也可以使用工程提供的 Skill 辅助生成、替换和部署主题，见使用 Skill 定制动画主题。

当前配置使用以下动画片段名：

片段	用途
`sleeping_loop`	等待唤醒循环
`wake_up`	从等待唤醒进入请说话
`listening_loop`	请说话循环
`listening_to_thinking`	从请说话进入思考中
`thinking_loop`	思考中循环
`thinking_to_speaking`	从思考中进入正在回复
`speaking_loop`	正在回复循环
`sit_down`	从回复进入等待说话
`idle_daze`、`idle_rub_eye`	等待说话时交替播放
`idle_to_listening`	连续对话重新进入请说话
`lie_down`	空闲超时后回到等待唤醒

只换图片时保留这些片段名最省事。如果需要增删片段，还要同步修改 voice_animation_config.js 中的 STATE_CLIPS 和 TRANSITION_CLIPS。

主题图片数量没有代码上限，但图片越多，BIN 越大，安装和传输时间也越长。优先复用图片并延长显示时长（增大 hold），不要为延长静止画面复制多份相同 PNG。备用、历史和生成失败的主题应放在 voice_cloud_LLM 目录之外，避免被误带入应用工程。

调整动画速度和显示时长

多数节奏调整只需要修改 current_theme.js 中每张图片的显示时长（hold）：

sleeping_loop: [
  { src: '/common/theme/assets/sleeping_loop_000.png', hold: 4 },
  { src: '/common/theme/assets/sleeping_loop_001.png', hold: 2 },
],

这里第一张图显示约 200 ms，第二张图显示约 100 ms。增大 hold 会延长显示，减小 hold 则会加快切换。

MAX_ACTIVE_FRAMES = 20 是运行时窗口大小。单张图片的显示时长即使超过 20 个时间片，运行时也会分多个窗口继续使用同一张图片，不需要复制资源。

如果确实需要改变全局时间粒度，可以修改 voice_animation_config.js 中的 FRAME_TICK_MS。这会影响所有片段，修改后应完整检查转场和循环节奏。

修改状态文案和页面布局

状态文案位于：

entry/src/main/js/MainAbility/pages/index/voice_state.js

页面结构和样式位于：

entry/src/main/js/MainAbility/pages/index/index.hml
entry/src/main/js/MainAbility/pages/index/index.css

可以直接修改“等待唤醒”“请说话”“思考中”“正在回复”和“等待说话”等文案，也可以调整文字颜色、字号、背景和状态栏位置。表盘画布为 466×466，修改 CSS 后要检查文字是否超出屏幕，以及错误提示是否遮挡主题主体。

更换云端智能体

只更换 Coze 智能体时，不要修改源码。更新 /user/coze_setting.json 中的 token 和 bots[0]，重新进入应用即可。

如果修改了文件但应用仍使用旧配置，先确认上传目标是 /user/coze_setting.json，再检查 DebugKits 进度是否达到 100%。应用在每次启动语音服务时读取该文件。

接入非 Coze WebSocket 服务需要重写鉴权和协议事件映射，不属于应用主题定制范围。这类改动会影响设备侧状态机、超时恢复和音频格式，应配套增加协议测试和板端测试。

使用 ModelZoo 替换本地唤醒模型

默认 Demo 使用 DSP 识别唤醒词。HiSpark ModelZoo 提供了 HiDiTing AI 语音应用唤醒词替换方案，支持将 GRU-S、GRU-M、GRU-L 接入本应用，也提供自定义唤醒词的训练和部署流程。替换的只是设备上的唤醒模型，不会更换 Coze 云端智能体。

建议先按上板运行跑通默认 Demo，再根据需求选择入口：

你的需求	操作入口	需要准备什么
先试用现成模型，用 `left`、`right` 等已有词唤醒	唤醒词替换教程	ModelZoo、SDK、AI adaptor、模型转换环境及教程要求的音频数据
换成自己指定的唤醒词	GRU-S/M/L 自定义唤醒词训练教程	额外准备目标词、非目标词的 WAV 录音和训练环境

首次尝试建议选择现成的 GRU-S 模型，按以下顺序操作。具体安装命令和脚本参数以链接中的教程为准，无需在两份文档之间拼接命令。

准备环境。 获取 ModelZoo 仓库，按工具链环境准备和唤醒词替换教程的“准备环境”安装依赖，确认 SDK 满足接入要求。这里使用的是模型转换与固件编译环境，不是 DevEco 的 JS 应用构建环境。
配置并构建。 按替换教程的“配置与运行”填写本机路径，选择 gru-s，将 WAKEUP_LABELS 设为 left,right，再从 ModelZoo 仓库根目录执行教程中的运行命令。先保存 SDK 的已有改动，脚本会修改其构建配置。仅修改标签不能增加模型未学过的词；自定义词请走表格中的训练入口。
部署配套文件。 构建完成后，打开 ModelZoo 下的 solutions/voice_cloud_llm_wakeup/output/gru-s/runtime/，按其中的 README.txt 操作：烧录 voice-cloud-llm-gru-s.fwpkg，再通过 DebugKits 上传文件，把 user/gru-s.exeom 上传为板端的 /user/gru-s.exeom。前者是固件，后者是模型，两者必须来自同一个部署包；只安装 JS BIN 不会替换模型。
回到应用验证。 沿用上板运行中的网络、Coze 和 JS 应用配置，但保留刚烧录的 ModelZoo 固件，不要再烧回默认固件。启动应用，等页面显示“等待唤醒”后，说 left 或 right，确认能正常对话，再测试回复期间的唤醒词打断。此时默认 DSP 的中文唤醒词不再适用。

自定义词的训练教程包含“数据准备”“训练与自动导出”和“接入 HiDiTing AI 语音应用唤醒词替换方案”，请按顺序完成。自训模型的部署包位于训练输出目录的 export/runtime/，文件名和板端路径与现成模型不同，例如 GRU-S 自训模型使用 /user/gru-s-custom.exeom，不要套用上述现成模型的路径。

无法唤醒时，先检查固件与模型是否配套、上传路径是否正确、所说词汇是否在配置中，再查看串口中的模型加载或推理错误。coze_setting.json 不用于切换本地唤醒模型。

使用 Skill 定制动画主题（可选）

开发环境准备好后，只需描述想要的角色和画风，AI AGENT 就可以按工程提供的 Skill 生成主题，并完成资源替换和应用构建。 你负责提出需求、确认预览，不需要自己画出每一帧、编辑图片清单或逐条运行处理脚本。需要上板时，可以继续让 AI AGENT 部署到 HiDiTing 开发板。

首次使用准备

AI 能力： 所用 AI AGENT 需要能读取本地工程、执行命令，并使用支持图像生成的多模态模型或生图工具。仅支持文字问答，或只能理解图片而不能生成图片的模型，不满足自动生图要求。可使用 ChatGPT 中可用的图像生成功能制作素材；若生图与本地 AI AGENT 不在同一工具中，需要下载图片，再把文件路径交给 AI AGENT 继续处理。ChatGPT 对话中的生图不等于已经具备本机编译、串口连接和部署能力。
本地环境： 在 Windows 原生 NTFS 目录中打开 hs-fbb 仓库，准备 DevEco Studio、Python 和 ImageTool。在 DevEco 中打开一次 samples/js_samples/voice_cloud_LLM，完成 SDK 和 Hvigor 初始化。上板还需安装 DebugKits、连接 HiDiTing 开发板，并保持 Windows 桌面解锁。
Skill 入口： 工程自带 samples/js_samples/voice_cloud_LLM/voice-cloud-theme/SKILL.md。让 AI AGENT 读取该文件并按其中流程执行，不要假设仅打开仓库就会自动启用 Skill。工具路径和 Python 依赖可先由 AI AGENT 按 Skill 检查，再根据提示补齐。

描述主题需求

在 AI AGENT 中打开仓库，发送以下需求，将角色和画风换成你想要的效果：

请先读取并遵循 samples/js_samples/voice_cloud_LLM/voice-cloud-theme/SKILL.md，把语音助手主题改成一只蓝色小猫，简洁卡通风格，表情活泼。先检查开发环境和生图工具，缺少依赖时告诉我需要补齐什么。生成主题后先给我看预览，确认后再替换资源、构建 BIN，暂不上板，不修改语音逻辑。

AI AGENT 按 Skill 组织生图要求，处理图片尺寸、动画配置和资源校验。预览不满意时，直接提出修改意见，例如“颜色浅一点，思考时的表情更明显”；确认后再构建应用。已有素材也可以交给 AI AGENT，但仍需按 Skill 检查布局和各状态画面，不能把任意一张角色图片直接当作完整动画主题。

确认后部署

连接开发板后，可以继续提出部署需求：

主题预览已确认，请按同一个 Skill 将构建好的应用安装到已连接的 HiDiTing 开发板并启动。先检查部署环境和端口连接，保留构建、部署日志，不修改语音逻辑。

部署完成后，仍需查看板上等待唤醒、倾听、思考和回复时的实际动画；脚本确认应用已启动，不代表屏幕效果已经验收。主题修改不需要重编固件，手动操作方式见替换 OH 应用主题。

判断是否需要重编固件

修改内容	BIN	固件
主题图片、显示时长、页面文案和 CSS	重新构建	不需要
JS 生命周期或状态动画逻辑	重新构建	不需要，前提是系统接口未变
`@system.voiceCloudLlm` 接口	重新构建	重新构建并烧录
设备侧音频、WebSocket、唤醒或状态机	通常不变	重新构建并烧录
`/user/coze_setting.json`	不需要	不需要

固件和 BIN 应从同一版本源码构建。系统接口有变更时，旧 BIN 与新固件混用可能出现模块不可用、状态值不一致或启动失败。

第三方依赖清单

本应用运行时使用的第三方服务只有 Coze。DevEco Studio、OpenHarmony SDK、ImageTool 和 Python 用于构建应用，不参与板端语音会话。

第三方服务	用途	配置位置
Coze WebSocket 语音会话	云端 VAD、对话生成和语音合成	`/user/coze_setting.json`

应用构建工具：

工具	用途	配置位置
DevEco Studio 与 OpenHarmony SDK	构建 BIN	JS 应用工程
ImageTool 与 Python 3	将主题 PNG 转换为板端图片格式	`ImageTool`、`PYTHON` 环境变量

WebSocket、cJSON、音频和本地唤醒能力来自工程或平台 SDK，不需要单独安装。默认云端地址是 wss://ws.coze.cn/v1/chat。

异常排查手册

现象	检查方法
页面提示“当前固件缺少语音模块”	当前固件没有`@system.voiceCloudLlm`。重新构建并烧录 `diting-community.fwpkg`
页面提示“语音状态订阅失败”	检查固件与 BIN 是否来自同一版本，退出应用后重新进入
页面提示“语音服务启动失败”	检查`/user/coze_setting.json` 的路径、JSON 格式、字段长度、token 和 bot ID
蓝牙 PAN 无法联网	确认手机已开启蓝牙共享网络，并检查`pan CONNECTION_CONNECTED`、DNS、系统时间和 TLS
说出唤醒词后无响应	确认应用在前台且页面显示“等待唤醒”，再检查麦克风和固件支持的唤醒词
说话后没有云端回复	检查网络、Coze 智能体、token、麦克风和扬声器；查看串口中的 WebSocket 或云端错误
云端回复较慢	在 Coze 智能体配置中选择响应更快的模型，按业务需要关闭深度思考
动画构建提示资源不一致	对照`current_theme.js`，删除未引用 PNG，补齐缺失 PNG，并检查文件名大小写
动画黑屏或不切换	确认图片是 466×466 PNG，显示时长参数`hold` 为正整数，片段名与 `voice_animation_config.js` 一致
BIN 过大或上传较慢	减少物理图片，复用图片并增加显示时长（`hold`）；工程内只保留当前主题
连续对话自动结束	默认空闲超时约 15 秒，重新说出唤醒词即可

注意事项

固件编译开关

src/build/config/target_config/3322/config.py 中的 diting-community 目标默认定义了 CONFIG_VOICE_CLOUD_LLM_ENABLE 宏。

这个宏同时控制以下内容：

编译 voice_cloud_LLM 设备侧语音组件。
编译 ace_voice_cloud_llm JS 系统模块。
向 ACE Lite 注册 @system.voiceCloudLlm。

如果要关闭 Voice Cloud LLM，需要从 diting-community 的 defines 中移除 CONFIG_VOICE_CLOUD_LLM_ENABLE，并从 ram_component_set 中移除 voice_cloud_LLM_set。修改后重新构建固件。

如果只是暂时不用语音助手，不必关闭编译开关；不安装或不启动 BIN 即可。关闭宏后，仍然安装 Voice Cloud LLM BIN，页面会提示“当前固件缺少语音模块”。

配置与资源

应用会把麦克风音频发送到第三方云服务。部署前需要确认用户授权、云服务条款和隐私要求。
使用单独的最小权限令牌。令牌泄露后立即撤销并轮换。
/user/coze_setting.json 是板端运行时配置，不要提交到仓库。
应用工程内只保留当前主题。备用主题放在 voice_cloud_LLM 目录之外。
不限制主题图片数量，但需要考虑 BIN 大小、板端存储、安装时间和运行内存。
主题目录只放清单引用的 PNG，不要提交构建生成的 .bin 或 entry/build/。
修改 JS 或主题时只需更新 BIN；修改 Native 后端、ACE 系统接口或唤醒能力时必须重新烧录固件。
页面退出会停止语音服务。调试后台行为时不要把正常的生命周期停止误判为服务异常。

附录：可选的 Voice Cloud Theme skill

voice_cloud_LLM/voice-cloud-theme/ 提供主题预览、资源校验、DevEco 构建、DebugKits 上传和 DFX 验证。日常开发仍按本指南前面的人工步骤进行，需要自动处理主题时再使用它。

入口文件是 samples/js_samples/voice_cloud_LLM/voice-cloud-theme/SKILL.md。在 Windows 原生 NTFS 路径、仓库根目录的 PowerShell 中运行预检：

$SkillRoot = (Resolve-Path 'samples/js_samples/voice_cloud_LLM/voice-cloud-theme').Path
$env:VOICE_CLOUD_PROJECT = (Resolve-Path 'samples/js_samples/voice_cloud_LLM').Path
$env:VOICE_CLOUD_THEME_RUNS = Join-Path $env:TEMP 'voice-cloud-theme-runs'

powershell.exe -NoProfile -ExecutionPolicy Bypass -File `
  (Join-Path $SkillRoot 'scripts/windows_preflight.ps1') `
  -Project $env:VOICE_CLOUD_PROJECT -Require build -Quiet `
  -ResultJson (Join-Path $env:VOICE_CLOUD_THEME_RUNS 'preflight.json')

预检会从参数、环境变量、工程工具目录、用户常用目录、Windows PATH 和 DevEco 注册表中查找工具。ImageTool 使用官方变量名 ImageTool，目录中应有 images_tool.py 和 config.xml。缺少工具时，查看结果 JSON 的 Guidance 字段。ImageTool 的获取和目录结构见图形工具使用指南，DebugKits 的安装和连接见DebugKits 工具使用指南。

预检通过后，按 SKILL.md 执行主题替换、构建或部署。运行记录、预览、日志、结果 JSON 和回滚快照放在临时目录或工程目录之外。仓库中的默认主题使用旧版图片清单；复用它时，请提供匹配的 spec。