业务能力¶

本页面向业务接入与维护工程师，说明当前 Ali 来源集实际注册的指令处理器、数据流及能力边界。这里的“已实现”指源码已接通相应调用和事件处理，不代表本次文档发布已验证真实车辆、外部账户或订单交易。

业务如何进入应用¶

语音文本经后端路由或 SDK 事件转换为领域指令，由 CommandExecutorImpl 按处理器声明的指令名分派。业务结果以 ChatEvent.Business.Result 等事件进入展示链路；需要外部应用承载时，再由 AppCtrlDispatcher 协调 Omni。

flowchart TD
    A[ASR 最终文本或文本注入] --> B[后端路由与 SDK 事件映射]
    B --> C[CommandExecutorImpl]
    C --> D[已注册 CommandHandler]
    D --> E[业务 UseCase 或外部 SDK]
    E --> F[业务数据与状态事件]
    F --> G[Omni 卡片与 AppCtrl]
    E --> H[回复播报]

Command 的领域接口如下。它是应用内部 Kotlin 类型，不是可直接发送到任意 HTTP 地址的请求协议：

data class Command(
    val name: String,
    val arguments: Map<String, Any>,
)

当前能力矩阵¶

能力	当前入口	实现与依赖
媒体检索与控制	`MediaCenterCommandHandler` / `MEDIA_CONTROL`	通过媒体 Agent 处理输入，消费结果和控制信号，协调媒体中心
导航	`NavigationCommandHandler` / `navigation_raw_input`	将文本与候选 POI 交给导航 UseCase / SDK
应用打开与切换	`AppCommandHandler` / `AppCommand.supportedNames()`	处理已定义的目标应用与媒体入口，依赖设备安装情况
系统控制	`SystemCommandHandler`	解析支持的音量、亮度等命令并调用系统控制能力
小红书	`RednoteCommandHandler` / `REDNOTE`	消费美食、兴趣点、路书等 Agent 事件，支持详情和导航衔接
点单支付	`PaymentCommandHandler` / `PAYMENT`	流式点单、订单状态、签约提示和支付结果卡片
景区票务	`TicketsCommandHandler`	景区 Agent 请求、票务卡片、回复与失败状态
主题生成、AI Widget	对应主题、Widget 处理器	已加入 Ali 注册集合，依赖对应服务和组件
车辆能力	`VEHICLE_CONTROL` 事件及车辆领域抽象	已有结果与路由处理；物理车控闭环需设备侧实现与验证

以注册表判断当前入口

Ali CommandModule 注册了 MediaCenterCommandHandler，没有注册源码中仍保留的 MediaCommandHandler。不要仅凭存在 MUSIC_*、VIDEO_* 旧处理类，就把它们列为当前生产指令入口。VehicleAdapter 接口也不能证明车辆硬件已完成适配。

媒体与导航¶

媒体 Agent 入口使用 MEDIA_CONTROL，arguments.text 是非空查询文本，contextId 用于关联上下文。处理器消费媒体结果与控制信号；列表出现、应用打开和播放成功是三个不同的观察点。

内部调用示例：

Command(
    name = "MEDIA_CONTROL",
    arguments = mapOf(
        "text" to "播放轻音乐",
        "contextId" to "example-turn-001",
    ),
)

导航处理器当前仅声明 navigation_raw_input：

参数	行为
`input_text`	必须非空；缺失时记录警告并返回未处理
`poi_list`	可选候选 POI，交给处理器解析
`poiArray`	可选完整候选数组，保留给导航 SDK

导航验收应覆盖首次查询、候选选择和最终导航启动。定位不可用、目标应用未安装或 SDK 返回错误时，应检查失败结果与错误日志，不能把语音回复当成导航已经开始。

小红书与跨应用结果¶

REDNOTE 入口把 text 和 contextId 交给小红书 Agent。流事件再决定美食列表、兴趣点、路书、详情打开或导航动作。

“找附近的美食”依赖当前位置；“打开第一个”依赖前轮候选结果。联调时保留同轮上下文，并使用新的会话验证候选为空和索引无效的行为。

源码中存在多个 rednote_* 事件/指令常量，不应把它们全部当成 Ali 注册表直接开放的独立入口。查询命中后还要分别验证列表渲染、详情应用启动和导航 SDK 返回结果。

点单与支付¶

PAYMENT 接收 text、contextId，以及可选 suppressStreaming。处理器构造 PaymentOrderRequest(sessionId, message)，收集 OrderAgentChatUseCase 的流事件，合并增量文本并输出支付业务卡片。

同一轮点单使用同一个业务会话。存在待签约会话时优先复用它，避免签约返回后丢失订单上下文。

flowchart LR
    A[选择品牌与门店] --> B[菜单与商品规格]
    B --> C[确认订单]
    C --> D[订单创建]
    D --> E{后端返回状态}
    E --> F[需要签约]
    F --> G[保留会话继续交互]
    E --> H[支付成功]
    H --> I[清理待签约并轮换会话]
    E --> J[支付失败或错误卡片]

主要 action 包括：

阶段	`action`
选择	`show_sellers`、`show_stores`、`show_menu`、`show_goods_detail`
确认与创建	`confirm_order`、`order_created`
支付	`payment_sign_required`、`payment_success`、`payment_failed`
订单查询	`show_order_history`、`show_order_detail`
对话	`chat`，以及未识别动作对应的 `NONE`

order_created 与 payment_success 含义不同。客户端必须根据服务端动作和业务字段呈现当前步骤，不得在订单创建时展示支付成功。

后端锁域结果指示超出点单范围时，处理器会解除支付领域锁、重置支付会话并清理待签约状态。流请求失败时会记录错误并发送错误卡片。该行为应通过测试环境返回值覆盖，避免用真实交易验证错误分支。

接入与回归检查¶

用文本注入验证路由是否选择正确业务域。
核对命令名与参数，确认处理器位于 Ali CommandModule 注册集合。
跟踪同一 contextId 的业务请求、结果事件、Omni 卡片和外部应用动作。
验证空结果、网络错误、应用缺失、重复点击、退出后重新进入。
点单增加商品规格缺失、确认失败、签约等待、支付失败与成功后新会话。
真机车控单独记录硬件状态反馈；事件产生或语音播报不能替代执行回执。

新增能力时复用 CommandHandler、领域 UseCase 和事件通道，避免把业务请求放入 Activity。公共字段与展示契约参见接口参考，外部应用回执参见 Omni 接入。