跳转至

快速开始

本页面向持有 Android 工程和配套开发环境的接入工程师。公开文档仓库只包含文档，不能独立编译语音助手 APK。

当前推荐联调入口是 Ali flavor + Headless + Omni Launcher。Ali 已接入实际对话、业务路由和 TTS 链路；不能按早期 README 的 Stub 描述判断当前能力。

1. 准备环境

项目 当前工程要求
JDK 17；settings.gradle.kts 会拒绝其他主版本
Gradle 使用工程 Wrapper，当前为 8.13
Android Gradle Plugin 8.13.2
Kotlin 2.2.20
Android SDK compileSdk 36、targetSdk 35、minSdk 28
CPU 架构 应用打包限定 arm64-v8a
依赖 团队 Maven 访问权限、LocalRepo SDK、所需 JNI 资源
设备 ADB 可访问的适配设备，配套 Omni 和业务应用

minSdk 28 是构建声明，不等于所有车辆权限和外部 SDK 都能在普通 Android 9 设备完整工作。特别是平台权限、音频输入源及系统应用部署，需要使用设备适配方案验证。

先检查工具和设备：

java -version
./gradlew --version
adb devices -l
adb shell getprop ro.product.cpu.abi
adb shell getprop ro.build.version.sdk

工程读取 MAVENUSER、MAVENPASSWORD 和签名相关 Gradle 属性。由工程维护方提供实际依赖、签名材料与凭据，通过受控 CI 或本地未入库配置注入；不要把它们复制到文档仓库。Android SDK 路径由本机 local.properties 管理。

2. 选择构建变体

变体 用途与边界
aliDebug 当前主要开发与联调变体，包含 Debug 文本/TTS 注入入口
aliRelease 开启 R8 混淆，关闭 MOCK_E2E_ENABLED
jdo 独立引擎来源集，不能直接套用 Ali 专用调试入口
iflytek Gradle 预留渠道，声明不代表已有完整引擎实现

以下命令在 Android 工程根目录执行：

./gradlew :app:assembleAliDebug -PHEADLESS_MODE=true

Headless 默认值为 true。该模式阻止语音助手添加自己的悬浮窗，ASR、TTS、对话状态及 gRPC 推送仍然运行，Omni 消费这些事件并展示界面。

APK 文件名包含工程名、后端环境、变体和版本号，不要硬编码为 app-debug.apk。构建后查找真实输出：

find app/build/outputs/apk/ali/debug -name '*.apk' -type f

需要验证混淆版本时使用：

./gradlew :app:assembleAliRelease -PHEADLESS_MODE=true

两个独立开关

MOCK_E2E_ENABLED 由 Debug/Release 构建类型控制；GRPC_MOCK_ENABLED 则是独立的 Gradle 属性。不能仅凭 Release 关闭文本广播，就认定全部 Mock 服务均已关闭。正式交付应核对目标构建配置和实际监听端口。

3. 安装与首次启动

在允许普通覆盖安装的开发设备上，将下面的占位文件名替换为上一步输出：

adb install -r -t <构建产物.apk>
adb shell am start -n com.jidouauto.voiceassistant/.MainActivity

遇到签名冲突时，先核对现有应用签名和目标设备平台签名。系统镜像预装应用的升级方式由镜像集成规范决定，不要直接通过卸载或重刷绕过冲突。

首次运行按页面提示完成：

  1. 授予录音权限；按设备接入需要处理定位和悬浮窗设置。
  2. 完成账户登录。MainActivity 会检查登录状态，认证成功后请求启动 KWS。
  3. 确认 VoiceAssistantService 正常运行，再进入 Omni 联调。
  4. 通过配套 Omni 的唤醒入口发起一轮对话，观察识别文本、回复文本与播报。
flowchart LR
    A[安装 Ali APK] --> B[启动 MainActivity]
    B --> C[权限与登录]
    C --> D[VoiceAssistantService]
    D --> E[唤醒与对话]
    E --> F[gRPC 事件]
    F --> G[Omni 渲染]

4. 最小验证

先确认应用进程和服务存在：

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

Ali Debug 可以通过文本注入检查下游链路，绕开物理录音：

adb shell am broadcast \
  -a com.jidouauto.voiceassistant.MOCK_TEXT \
  -p com.jidouauto.voiceassistant \
  --es text '你好，请介绍一下你能做什么'

该入口是进程启动时动态注册的，必须先启动应用。默认 use_backend_routing=true，文本会进入后端路由；它不是离线模拟，也不验证麦克风和 ASR 准确率。

验收时分别记录：应用启动成功、服务正常、文本进入链路、Omni 收到事件、TTS 有声。广播返回完成只能证明广播发送过程结束，不能代替业务执行成功。

5. 常见阻塞

现象 先检查
Gradle 提示 JDK 不兼容 命令行与 Android Studio 的 Gradle JDK 是否都是 17
依赖解析失败 仓库访问权限、凭据注入和本地 SDK 是否齐备
APK 安装失败 ABI、系统版本、已有安装签名和系统应用升级策略
登录后无响应 服务状态、账户状态、后端连通和 KWS 初始化日志
有声音但没有悬浮窗 是否启用 Headless、Omni 是否建立正确的 gRPC 订阅
文本广播无效 是否为 Ali Debug、应用进程是否已启动、是否有非空 text

继续阅读 架构、Omni 接入 和 调试与维护。