调试与维护¶

本页适用于 Ali 联调设备。按“输入 → 路由 → 业务 → 推送 → 展示/播放”逐段验证，保留同一轮请求的时间、contextId 和结果；不要将 Mock 返回成功等同于真实用户流程通过。

选择验证入口¶

入口	主要覆盖	不覆盖
真实唤醒与说话	KWS、录音、ASR 及全部下游	需要目标硬件和服务可用
`MOCK_TEXT` 广播	文本之后的后端路由与业务链	物理录音与 ASR 识别质量
Mock ASR / KWS 控制服务	注入 ASR 最终文本或唤醒事件	真实唤醒算法与麦克风
AppCtrl 测试脚本	业务事件到 Omni 应用控制	模型理解、真实业务服务成功
TTS 捕获	指定文本的真实播报与 PCM 输出	KWS、ASR、业务路由

文本注入¶

安装 aliDebug 并先启动应用、完成登录与服务准备。接收器在进程初始化时动态注册，Release 由 MOCK_E2E_ENABLED=false 禁用。

adb shell am start -n com.jidouauto.voiceassistant/.MainActivity
adb shell am broadcast \
  -a com.jidouauto.voiceassistant.MOCK_TEXT \
  -p com.jidouauto.voiceassistant \
  --es text '播放轻音乐'

Extra	默认值	用途
`text`	无	非空输入；仅预热时可省略
`warmup_only`	`false`	仅准备无录音会话，不发送文本
`use_backend_routing`	`true`	走与最终 ASR 类似的后端路由入口
`pre_emit_user`	`true`	预发用户识别完成事件，供 Omni 展示
`show_text_on_ui`	`true`	控制直接文本调用的展示参数
`force_interrupt`	`true`	控制直接文本调用的打断参数

默认路由分支调用 triggerBackendRoutingForMock，不会同时再发一次 Ali transcript。设置 use_backend_routing=false 才调用 DialogueStateManager.sendTextMessage，用于单独检查 Ali 直接文本回复链。后两个展示/打断参数传给直接文本分支，不应当作后端路由分支的通用开关。

adb shell am broadcast \
  -a com.jidouauto.voiceassistant.MOCK_TEXT \
  -p com.jidouauto.voiceassistant \
  --ez use_backend_routing false \
  --es text '你好'

Mock ASR / KWS 控制面板¶

当前 PAD 侧启动 AppCommandMockGrpcServiceHost，默认 Mock gRPC 端口为 50062；Omni 正式事件接口与它不同。该能力由 GRPC_MOCK_ENABLED 控制，端口可由配置覆盖，应以设备日志为准。

在 Android 工程根目录准备 Python 环境，并通过 ADB 转发避免写入设备网络地址：

python3 -m venv .venv-grpc
.venv-grpc/bin/python -m pip install -r scripts/requirements-grpc-control.txt
adb forward tcp:50062 tcp:50062
.venv-grpc/bin/python core/mock-grpc/mock-asr/scripts/mock_asr_server.py \
  --http-bind 127.0.0.1 --http-port 8080 --pad 127.0.0.1:50062

打开控制脚本给出的本机页面地址。脚本会按 Proto 自动生成 Python 客户端，输出到工程构建目录。面板通过 SubmitCommand 注入 Mock ASR、KWS 等命令；健康响应只说明服务可访问，还要核对语音助手日志与 Omni 实际状态。

PAD 另有 HTTP 控制服务，支持 /api/health、/api/mock-asr、/api/mock-kws、/api/mock-trigger 和 /api/asr-forward-toggle。这些是联调入口，不作为业务应用正式集成 API。

场景测试与现有脚本¶

仓库保留 MockScenarioParser 和 MockScenarioRunner，支持 user_input、agent_status、llm_response、vehicle_follow_up 四类步骤。解析器要求非空 steps；duration_ms 不小于零；typing_duration_ms 为 -1 或不大于步骤时长的非负数。

场景入口状态

当前 Ali MockGrpcClientManager 实际初始化 ASR、KWS、Trigger 服务，未看到创建 MockScenarioRunner 或调用解析器的活动入口。场景类属于保留实现，不能直接声称把场景 JSON 发给当前控制服务即可执行。完整回归优先使用已接通的文本、Mock ASR/KWS 与 AppCtrl 入口。

已有 AppCtrl 冒烟脚本可以发送导航、媒体和小红书等测试事件：

bash scripts/test_appctrl.sh

该脚本执行后需要人工核对 Launcher 的 AppCtrl / APP_CTRL 和语音助手的 AppCtrlDispatcher 日志，以及前台应用变化。脚本内“指令发送完毕”不是断言全部场景通过。

建议固定记录四组用例：冷启动首轮、连续两轮、回复中打断、业务失败后再试。对每组分别检查输入文本、业务结果、播报完成、Omni 复位，避免只比较截图。

日志定位¶

adb shell pidof com.jidouauto.voiceassistant
adb shell dumpsys activity services com.jidouauto.voiceassistant
adb logcat -d > voiceassistant-session.log

线索	定位内容
`[MockTextInput]`	广播接收、会话准备和路由分支
`AliDialogueRepositoryImpl`	Ali 会话与对话事件
`MockGrpcClientManager`	Mock 服务启动、注入失败
`GrpcEventBroadcaster`	事件向 Omni 推送
`AppCtrlDispatcher`	外部应用控制分发
`PaymentCommandHandler`	点单会话、流失败、签约和支付状态

日志可能含识别内容、账户或订单字段。分享排障记录前保留必要时间与错误码，替换真实身份、位置、凭据和订单标识。

音频诊断¶

真实说话无识别而文本注入正常时，先看录音权限、输入设备、通道布局及 KWS/ASR 入流。不要直接把问题归因于模型。

flowchart LR
    A[设备原始多通道 PCM] --> B[确认 Mic 与 Ref 布局]
    B --> C[ECNR 输入映射]
    C --> D[降噪输出]
    D --> E[KWS 或 ASR]

工程包含独立诊断应用：

./gradlew :AudioRecordSource:AudioDiagnostic:app:assembleDebug
adb install -r -t AudioRecordSource/AudioDiagnostic/app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.jidouauto.audio.diagnostic/.DiagnosticActivity

诊断应用依赖音频 JNI 库及适配设备的平台权限；普通安装是否可用取决于设备。先在 Probe 模式确认候选通道，分别提供人声和系统播放声，试听各通道以辨认 Mic/Ref，再进入 Pipeline 模式验证降噪效果。channelLayout 中 0 表示 Mic、1 表示 Ref。实际输入通道数必须与 HAL 匹配；框架内部补齐 ECNR 输入不等于可以随意填错物理通道数。

捕获 TTS¶

服务运行后，在 Ali Debug 使用以下入口：

adb shell am broadcast \
  -a com.jidouauto.voiceassistant.MOCK_TTS_CAPTURE \
  -p com.jidouauto.voiceassistant \
  --es text '在呢' --es out sample_welcome.pcm

捕获文件写入应用外部文件目录的 tts_capture 子目录。当前默认格式为 24 kHz、单声道、16 位小端 PCM，应同时核对活动播放器配置与捕获日志。先等待流结束并确认文件非空，再取出文件试听；不要把尚未写完的 PCM 当成断音证据。sample_rate 不能替代对实际采样格式的确认。

相关原理见语音链路，典型问题见常见问题。