共用能力模型¶
最后更新：
本页只解释各接入方式都会遇到的 EVCC 概念。具体接口名称、请求字段和权限以对应协议页为准。
属性¶
属性由 ID 或精确名称标识，并可能带有来源和区域。EVCC 将五种来源整理为统一记录，但不会凭空补充 来源本身没有的元数据。读取结果应同时检查状态、实际来源、初始化状态和时间戳，不能只检查值字段。
| 来源 | 含义 |
|---|---|
VHAL |
Android Vehicle HAL 属性 |
APVP |
车型 APVP 属性链路 |
VEHICLE_AIDL |
车辆厂商 AIDL 属性源 |
CAPI |
车辆 Car API 属性源 |
ADAPT_API |
EVCC 车型适配属性源，自动选择兼容版本 |
SOA |
独立的车辆 SOA 属性源 |
开放 API 的 AUTO 默认按 VHAL → APVP → VEHICLE_AIDL → CAPI → ADAPT_API → SOA 解析，并返回实际
来源。其他接入方式可能只有属性 ID 输入，应以各自文档为准。
区域¶
同一个属性可能有全局、左侧、右侧或其他区域。未指定区域时，开放 API 优先区域 0；如果只有一个
非零区域，可以直接选中；存在多个非零候选时返回 AMBIGUOUS_AREA，调用方必须明确区域。
初始化与缓存¶
刚连接时没有变化事件，不代表属性值为空。EVCC 会优先返回已经初始化的缓存；没有初值、来源换代或 调用方明确要求刷新时，才访问上游。订阅顺序是“登记需求 → 缓存读取 → 必要时刷新 → 初始快照 → 增量事件”。读取失败应返回明确状态，调用方不能把空字符串当成未知值。
变量¶
变量是自动化、公式、Lua 和开放 API 共用的进程级运行时数据。变量名区分业务含义，值使用统一类型 模型。写入或删除变量可能立即触发其他规则和脚本，第三方 App 应避免高频重复写入相同值。
动作¶
动作是 EVCC 已注册的受控操作。不同动作可能需要普通或高权限授权；动作存在于能力目录不代表当前 设备、前台状态和权限一定允许执行，调用前可查询能力并使用预检查。
生命周期和按需订阅¶
EVCC 不会为了开放 API 偷偷开启用户已经关闭的属性源。APVP 等按需属性会由 EVCC 聚合活动会话需求， 第三方 App 只需维护自己想监听的完整集合。一次性提交完整集合比短时间逐项新增更稳定。
来源断线、EVCC 重启或事件序号出现缺口时，应重建基线。推荐客户端 SDK 会自动重绑、恢复最后一次 成功的订阅集合并提示业务执行重同步。
安全边界¶
属性写入、车辆动作、系统设置、实时全量扫描和 Shell 可能影响车辆或系统稳定性。开放 API 采用应用 身份和分类权限控制；实时全量扫描、Shell 与系统写入不随普通权限预设自动开放。
API 1.1 音乐能力¶
音乐权限/扩展能力通过 queryCapabilities 查询，当前歌曲的资源状态及控制命令通过 EvccMusicState 判断；不要求配置属性或变量。
API 1.2 音量组¶
SDK 和 Demo 1.2.0 提供查询、读取、设置和增减，包含 Java/Kotlin 示例。先确认协议与独立音量权限；旧服务返回 UNSUPPORTED，重连不重放写入。见音量组接入说明。