常见问题¶

本页按现象给出定位顺序。涉及构建与运行行为的答案以当前 Ali 实现为准；外部 SDK、系统权限、车辆硬件和真实交易仍需目标环境验证。

文档仓库可以编译 APK 吗？¶

不能。公开仓库只发布 MkDocs 站点源码，Android 工程、受限 SDK、团队依赖和签名材料不包含在其中。站点本地预览与 Cloudflare 发布见文档维护与发布，APK 构建见快速开始。

Ali 还是占位实现吗？¶

不是。当前 Ali 来源集已有实际对话仓库、SDK 事件映射、业务路由、指令处理与 TTS 链路。早期文档中的 Ali Stub 描述不能作为当前实现依据。

这也不意味着所有 flavor 等价。jdo 使用自己的来源集，iflytek 是 Gradle 预留渠道；Ali 的广播注入和业务处理器不能直接套用到其他渠道。

为什么 JDK 已安装，Gradle 仍然失败？¶

工程在 settings.gradle.kts 明确检查运行 Gradle 的 Java 主版本必须为 17。终端的 java、Android Studio 的 Gradle JDK 和 CI 使用的 JDK 可能不同。

java -version
./gradlew --version

先比较两处输出，再调整当前工程运行环境。不要为规避错误删除版本检查。

最低 Android 版本到底是多少？¶

当前 gradle.properties 声明 MIN_SDK_VERSION=28，同时 TARGET_SDK_VERSION=35、COMPILE_SDK_VERSION=36。历史经验文档及某些 Manifest 注释仍提到 30，应优先遵循当前构建值。

最低版本只决定 APK 的安装下限。平台音频权限、车载服务、外部组件最低版本及厂商定制行为，需要单独评估。

安装后为什么没有语音悬浮窗？¶

HEADLESS_MODE 默认开启。语音助手继续执行会话与播报，把事件通过 gRPC 推送给 Omni，由 Omni 显示对话和业务内容。

依次检查：

VoiceAssistantService 是否运行。
Omni 是否连接正确的正式 gRPC 服务并完成订阅。
识别文本与业务事件是否进入 GrpcEventBroadcaster。
Omni 是否收到消息并映射为当前页面状态。

不要把“没有语音助手自己的窗口”单独判为失败。架构关系见架构。

应用能打开，为什么没有进入唤醒状态？¶

MainActivity 会申请录音权限并检查账户。认证成功后才请求启动 KWS。先确认登录、录音权限和服务状态，再检查 KWS 初始化及音频源选择。

adb shell pidof com.jidouauto.voiceassistant
adb shell dumpsys activity services com.jidouauto.voiceassistant

进程存在只说明应用在运行，不代表 Ali 会话或录音链路已准备好。

`MOCK_TEXT` 广播没有效果怎么办？¶

先使用 aliDebug 启动应用。接收器是进程初始化时动态注册的，不能依赖向已停止应用发送广播来冷启动它。再检查文本非空，以及 [MockTextInput] 日志是否出现。

Release 会关闭该接收器。广播终端显示完成也不能证明模型回复或业务结果已经返回，应继续检查路由与事件日志。

文本注入是不是离线测试？¶

不是。默认 use_backend_routing=true，走后端路由；设为 false 时走 Ali 直接文本请求。这两条路径都可能依赖网络与账户。

文本注入可以把问题范围缩小到下游，但不能验证物理麦克风、KWS 准确率和 ASR 音频识别质量。具体参数见调试与维护。

`50062` 与 Omni 端口可以混用吗？¶

不可以。50062 是当前默认 Mock 指令 gRPC 端口，用于 ASR/KWS 等调试注入；Omni 使用正式接口订阅事件与参与应用控制。应按 Omni 接入选择 Proto 和端口，并核对设备日志中的实际配置。

端口连通只说明 TCP/服务路径可达，不能证明订阅类型、消息映射和业务执行正确。

Release 是否自动关闭全部 Mock？¶

不能这样判断。MOCK_E2E_ENABLED 由构建类型设置，Release 为 false；GRPC_MOCK_ENABLED 来自独立 Gradle 属性，默认配置仍可能打开 Mock gRPC/HTTP 控制服务。

交付前检查目标构建参数及运行监听状态。只验证广播失效不足以证明所有 Mock 入口均已关闭。

为什么业务卡片出现，应用却没有执行？¶

业务结果、AppCtrl 分发、Launcher 接收和目标应用执行是不同阶段。先按同一轮标识关联 Business.Result、AppCtrlDispatcher、Launcher 回执，再核对目标应用安装与当前状态。

flowchart LR
    A[业务结果] --> B[AppCtrl 分发]
    B --> C[Omni 接收与回执]
    C --> D[目标应用执行]
    D --> E[观察实际结果]

卡片出现不能代替导航已启动、媒体已播放或车辆状态已改变的验证。

源码有 `MUSIC_PLAY`，为什么不能按它接入？¶

当前 Ali 注册集合使用 MediaCenterCommandHandler 的 MEDIA_CONTROL 入口。旧 MediaCommandHandler 虽仍存在源码中，但不在当前 Ali CommandModule 注册集合内。

接入时检查“常量定义 → 处理器支持名称 → DI 注册 → 运行路径”四个环节，不能仅搜索到类名就认定该能力有效。

点单已生成订单，是否代表扣款完成？¶

不代表。order_created、payment_sign_required、payment_success 和 payment_failed 是不同状态。应以服务端明确返回的支付动作与业务数据更新卡片。

需要签约时客户端保留业务会话；支付成功后清理待签约状态并轮换会话。异常或超出点单范围时按相应状态处理，不应补写成功。详见业务能力。

为什么音频杂音大、识别为空或播报变速？¶

先区分输入与输出：录音链检查权限、输入设备、采样率、通道数和 Mic/Ref 布局；播报链检查 PCM 实际采样率、位深与声道数是否和播放器一致。

对多通道设备，错误的物理通道数会使帧边界错位。先使用 AudioDiagnostic Probe 判断通道，再用 Pipeline 验证降噪。当前 TTS 捕获默认 24 kHz 单声道 PCM_16LE，按错误采样率播放会造成时长与音调异常。

提交问题时需要哪些信息？¶

提供构建变体与版本、设备系统版本、复现步骤、预期行为、实际行为和对应时间段日志。跨应用问题追加 Omni 版本及 AppCtrl 回执；音频问题追加实际采样格式、通道布局和已脱敏的短片段。

日志、截图、搜索索引和 PCM 都可能携带用户内容。对外共享时删除真实身份、凭据、位置和订单数据，保留错误码、脱敏标识和可复现步骤。