全量目录扫描¶

最后更新：2026-08-27

属性目录有两个模式，必须根据用途选择。

模式	行为	默认权限
`DIRECTORY`	查询已启用来源的可发现描述符，可选当前缓存值	`property.directory`，包含值另需 `property.read`
`LIVE_FULL_SCAN`	顺序触发已启用来源的实时目录采集，APVP 临时进入全量模式	另需 `property.full_scan`

LIVE_FULL_SCAN 的固定保护¶

单次最多运行 15 秒。
同一应用至少间隔 30 秒再次发起。
10 秒内的并发/重复请求可以复用短期快照。
结果仍通过 pageToken + snapshotToken 稳定分页，不能要求一个 Binder 事务返回全部属性。
某个来源失败不会抹掉其他来源已经获得的结果；检查页面状态和每条记录状态。

var token = ""
var snapshot = ""
do {
    val page = client.queryPropertyDirectory(
        EvccPageRequest(
            requestId = UUID.randomUUID().toString(),
            pageToken = token,
            source = Source.AUTO,
            limit = 200,
            includeValues = true,
            mode = DirectoryMode.LIVE_FULL_SCAN,
            snapshotToken = snapshot,
        )
    )
    check(page.status == Status.OK) { page.message }
    consume(page.items)
    token = page.nextPageToken
    snapshot = page.snapshotToken
} while (token.isNotEmpty())

第一页的 snapshotToken 必须原样带到后续页；只传 pageToken 会返回 INVALID_ARGUMENT。快照约保留 60 秒，且与调用应用、目录模式、来源、查询词和 includeValues 绑定。令牌过期或查询条件变化时，应丢弃两个令牌并从第一页重新查询。这样翻页期间上游属性变化不会造成记录重复、跳项或跨查询串页。

APVP 风险¶

APVP 的属性列表主要通过订阅集合获得。实时全量扫描可能临时切换监听模式、重建上游流并增加车辆链路负载，因此：

不要把它用作轮询接口或应用首页刷新机制。
普通开发工具先用 DIRECTORY 搜索，明确需要当前全量值时才让用户手动启动扫描。
扫描过程中属性可能只有描述符而暂时没有值；检查 initialized，不要把空值当成 0。
“全量”表示当前车型、当前 EVCC 版本和已启用来源能够发现的属性，不代表车厂协议理论全集。
扫描前后可能出现短暂来源状态变化；依赖实时控制的应用应处理 SOURCE_CHANGED 和序号重同步。

网页辅助调试台只能导入 EVCC 已导出的目录 JSON 并在浏览器本地筛选，不能远程触发车机全量扫描。