米德宝/AIDL 兼容接口¶
最后更新：
“米德宝/AIDL 联动”保留了一套早于 EVCC 开放 API 的兼容 Binder 接口，供已有米德宝及历史第三方 客户端继续运行，并从 EVCC 3.1.3 起为银河悬浮窗歌词提供自动音乐共享。这里的“v1”“v2”“v3”是 这套兼容协议自己的版本，不是 EvccApi 1.0，也不是 产品界面中的“EVCC 开放 API”。
选择对应的接入接口
旧接口与 EvccApi 在 AIDL 文件、Binder Action、数据模型、权限和订阅语义上均不兼容。复制旧 AIDL、只修改包名或只更换绑定 Action 都不能完成迁移。新应用应使用公开 Contract、Client SDK 和 Demo。银河悬浮窗歌词的音乐共享使用本文所列 v3 独立音乐回调，仅对指定包名和签名开放。
两套接口的边界¶
| 项目 | 旧版米德宝/AIDL | EVCC 开放 API |
|---|---|---|
| 用途 | 固定项目的属性快照与银河音乐共享 | 面向第三方开发者的标准能力接口 |
| Binder Action | com.kooo.evcc.midebao.BIND |
com.kooo.evcc.evccapi.BIND |
| 主接口 | IMidebaoLinkBridge |
IEvccApi + 授权会话 |
| 数据格式 | 全量 JSON 字符串快照 | 类型化 Parcelable 记录 |
| 目录 | 由旧版五项数据配置决定 | 能力查询、解析和稳定分页目录 |
| 属性定位 | 主要按属性 ID，读取无法精确指定来源/区域 | ID 或名称、AUTO/显式来源、可选区域 |
| 初始化 | 注册时推送全量快照，客户端容忍重复 | 初始化状态和 INITIAL_SNAPSHOT |
| 增量 | 属性发送全量 JSON；音乐另有运行周期、序号和歌词版本 | 逐项事件、会话序号和缺口重同步 |
| 写入 | 旧 v1 无；旧 v2 追加字符串写入 | 类型化写入、预检查、逐项结果和限流 |
| 授权 | 旧联动开关与旧应用列表 | 包名、UID、签名、授权修订号和分类权限 |
| 生命周期 | 客户端自行处理 Binder 和重复快照 | SDK 支持重绑、恢复订阅和重同步 |
两套接口的用户授权完全独立。旧列表中的应用不会自动获得 EvccApi 权限，EvccApi 授权也不会开放旧 Binder。云端显示开关和用户本地开关同样分开，开发者不能把一方可绑定当作另一方已经启用。
旧协议版本说明¶
- 旧 v1：读取运行状态、读取全量 JSON 快照、注册和取消快照回调。
- 旧 v2：保持前五个方法的 Binder 顺序，并在接口尾部追加属性写入。
- v3：保持原六个方法的 Binder 顺序，在末尾追加音乐快照、音乐订阅和取消订阅。属性快照仍为 v2，音乐 JSON 使用独立的
schemaVersion: 1。 - 这些接口均不提供 EvccApi 的类型化属性模型、能力目录、细粒度属性监听或分类权限会话。
历史客户端仍需在绑定后调用旧接口的 getProtocolVersion()，不要根据 EVCC 应用版本猜测旧协议版本。
旧状态字符串属于用户可读文本，不能按固定中文分支业务。旧回调发送的是全量状态，客户端必须容忍首次
注册和主动读取获得重复内容。
兼容协议资料曾在不同 EVCC 版本上分别核对，只用于维护已经存在的客户端。当前运行时返回的旧协议 版本和实际快照字段优先于历史文字；兼容文档不能用来推断 EvccApi 的行为。
完整接口、请求、返回和时序见 v1 协议参考、 v2 属性协议参考、v3 音乐扩展 及音乐接口定义。
银河音乐共享接入¶
开启“米德宝联动”“米德宝 AIDL 联动”及音乐转发后，银河可以注册独立音乐回调，自动获取歌曲、 当前歌词、上游完整歌词、进度、BPM 和播放状态。无需配置属性或自动化变量，属性配置为空或解析失败 也不阻断音乐共享。
音乐方法始终校验银河唯一包名、Binder UID 和签名。旧版 AIDL 的开放读取、应用写入名单及 EvccApi 授权均不授予音乐权限。合法银河客户端在关闭分享时仍可获取清空状态，已注册的合法订阅在重新开启后 恢复。完整歌词按版本分片传送；接收端应按运行周期、歌曲和版本重组，并自行外推播放进度。
绑定、注册、重连、分片重组、清空和进度示例，以及字段、错误处理和验收项，均收录在 音乐接口定义。银河客户端需要升级后接入新回调。
迁移到 EvccApi¶
- 移除客户端中的
IMidebaoLinkBridge、IMidebaoLinkCallback和旧 Binder Action。 - 引入公开
evccapi-contract与evccapi-client，在 Manifest 声明开放 API 普通权限和 EVCC 包可见性。 - 引导用户在“EVCC 开放 API”中为当前签名的应用授权；不要尝试迁移旧授权记录。
- 连接后校验
apiMajor，建立授权会话，并以grantedPermissions和queryCapabilities()判断 能力。 - 将全量 JSON 解析改为
EvccPropertyRecord/EvccVariableRecord；分别处理类型、初始化状态、 实际来源、区域、歧义和错误状态。 - 将旧五项固定配置改为目录查询、精确解析或应用自己维护的完整订阅集合。
- 将“每次回调替换整个快照”改为“初始快照建立基线 + 增量事件更新 + 缺口后重同步”。
- 写入前先使用
validateOnly，再执行真实请求；批量写入不是事务，不能在失败时盲目重放。 - 用 Demo 的 SDK 与 Raw AIDL 模式分别验证授权、Binder 和车辆属性源问题。
迁移期间可以让同一个应用临时保留两套客户端，但必须用独立连接状态、数据模型和权限提示，不能把旧 快照与 EvccApi 事件混入同一序号基线。完成验证后应移除旧客户端，避免长期维护两套语义。
仍需保留旧接口的场景¶
现有米德宝/AIDL 属性客户端和银河 v3 音乐共享继续使用此接口。面向一般第三方的新目录、属性监听、 Shell 或系统控制能力使用 EvccApi。旧银河音乐共享是指定接收方的独立通道；新的通用音乐能力已由开放 API 1.1 提供。
新接入请从开放 API 快速开始开始；迁移属性和监听时阅读属性模型与 初始化、监听与重同步。
弃用与迁移（API 1.1）¶
新集成使用音乐接口，现有银河按迁移指南切换。旧服务保留至少一个完整发布周期，实际移除另行公告。仅升级 EVCC 不代表客户端已经迁移。