ACI（Agent Capability Interface）：安卓本地智能体能力接口框架深度解析

一、核心定位与技术范式ACIAgent Capability Interface智能体能力接口是 ZorvAI 项目的核心框架其设计目标明确将安卓设备上任意应用的功能转化为 AI Agent 可编排的本地工具无需公网传输或云端中转。1.1 本地化架构的核心定义ACI 的本地化特性需明确定义其无需公网特性特指工具调用链路——AI 调度应用能力时指令与结果在同一安卓设备的进程间通过 Android Binder IPC 流转数据全程不出设备。这与大模型推理位置云端或端侧正交。ACI 解决的是Agent 执行器本地化问题而非Agent 推理引擎本地化。1.2 技术价值定位传统 AI Agent 工具调用存在两种局限公网 HTTP 请求远程 API存在延迟、隐私泄露风险生态内封闭调用仅能操作 Agent 自有功能ACI 开创了第三条技术路径将设备上已存在的海量应用功能通过标准化接口转化为 AI 可理解、可调用的工具集。二、功能架构与核心能力2.1 架构概览ACI 采用控制端/受控端双边架构基于 AIDL Binder 实现跨进程通信flowchart TD subgraph Control[控制端Zorv AI] A[QuroAciManagerbr/- discover() 发现br/- bind() 绑定br/- getCapabilities() 取清单br/- 结果注入 LLM] end subgraph Service[受控端应用服务] B[BaseACIService 子类br/- onCreateCapabilities()br/- onCall() 处理br/- onCheckPermission()] C[WakeReceiverbr/进程唤醒] end A -- AIDL Binderbr/call/callAsync -- B A -- ACTION_WAKEbr/广播 -- C B -- ACIResponse -- A2.2 核心能力矩阵以官方 ZorvAI 浏览器受控端为例其暴露的 30 个能力2026-08-01 测试通过率 28/30涵盖以下维度能力类别数量典型能力基础操作13browser_open, browser_read, browser_back智能代理7browser_crawl, browser_search资源管理2browser_download, browser_share完整方案6form_fill, payment_process交互增强1virtual_mouse网络扩展1http_request关键能力技术规格能力 ID关键入参技术说明browser_openurl必填打开并导航至指定 URLbrowser_read—读取当前页面 HTMLclean 模式返回精简 DOMv1.0.8 修复 Binder 1MB 传输限制browser_crawl—抓取结构化正文及出站链接browser_searchquery必填engine可选调用搜索引擎检索支持 bing/google/baidu/ddgbrowser_scriptcode必填在当前页面注入并执行 JavaScripthttp_requesturl/method/headers/body发送原生 HTTP 请求2.3 通信机制3.1 角色与核心组件角色职责关键类控制端服务发现、绑定、能力清单获取、调用发起、结果注入 LLMQuroAciManagerIACIService桩受控端继承BaseACIService声明能力实现业务逻辑BaseACIService/Capability/ACIRequest/ACIResponseBinder 契约定义跨进程方法接口IACIService.aidl/IACICallback.aidl权限模型5 层鉴权机制aci_permissions.xmlonCheckPermission()3.2 完整调用时序服务发现控制端通过discover()扫描设备上的受控端服务进程绑定通过bind()建立 Binder 跨进程连接能力获取受控端通过getCapabilities()返回能力清单含 ID、描述、参数 schema调用执行控制端发起call()/callAsync()同步/异步调用结果返回受控端返回ACIResponse执行结果进程唤醒针对 Android 11 的 stopped-state控制端先发送ACTION_WAKE广播唤醒受控端进程LLM 获取能力清单后自主决策调用策略与参数传递实现多应用协同的自动化任务编排。3.3 五层鉴权模型ACI 采用分层安全校验机制Android Manifest 权限系统级权限声明Binder UID 校验进程身份验证onCheckPermission()业务级白名单应用级访问控制aci_permissions.xml策略规则配置化权限管理能力级细粒度权限按能力声明访问权限任一层次拒绝都将中断调用流程。3.4 BaseACIService 方法契约方法是否必重写技术说明onCreateCapabilities(): ListCapability必须注册能力清单onCall(request: ACIRequest): ACIResponse必须同步处理单次调用onCallAsync(request, callback)可选异步处理默认切线程后调用onCallonCheckPermission(request, callerPkg): Boolean可选自定义调用方校验默认返回trueonBeforeCall/onAfterCall可选钩子函数默认仅日志记录关键实现细节Capability.create(String id, String description)的第二个参数是面向 LLM 的自然语言描述而非版本号方法内部固定version 1.0。若误将 1.0 作为 description 传入将导致 LLM 无法正确理解能力语义。三、架构设计与通信机制3.1 角色与核心组件角色职责关键类控制端服务发现、绑定、能力清单获取、调用发起、结果注入 LLMQuroAciManagerIACIService桩受控端继承BaseACIService声明能力实现业务逻辑BaseACIService/Capability/ACIRequest/ACIResponseBinder 契约定义跨进程方法接口IACIService.aidl/IACICallback.aidl权限模型5 层鉴权机制aci_permissions.xmlonCheckPermission()3.2 完整调用时序服务发现控制端通过discover()扫描设备上的受控端服务进程绑定通过bind()建立 Binder 跨进程连接能力获取受控端通过getCapabilities()返回能力清单含 ID、描述、参数 schema调用执行控制端发起call()/callAsync()同步/异步调用结果返回受控端返回ACIResponse执行结果进程唤醒针对 Android 11 的 stopped-state控制端先发送ACTION_WAKE广播唤醒受控端进程LLM 获取能力清单后自主决策调用策略与参数传递实现多应用协同的自动化任务编排。3.3 五层鉴权模型ACI 采用分层安全校验机制Android Manifest 权限系统级权限声明Binder UID 校验进程身份验证onCheckPermission()业务级白名单应用级访问控制aci_permissions.xml策略规则配置化权限管理能力级细粒度权限按能力声明访问权限任一层次拒绝都将中断调用流程。3.4 BaseACIService 方法契约方法是否必重写技术说明onCreateCapabilities(): ListCapability必须注册能力清单onCall(request: ACIRequest): ACIResponse必须同步处理单次调用onCallAsync(request, callback)可选异步处理默认切线程后调用onCallonCheckPermission(request, callerPkg): Boolean可选自定义调用方校验默认返回trueonBeforeCall/onAfterCall可选钩子函数默认仅日志记录关键实现细节Capability.create(String id, String description)的第二个参数是面向 LLM 的自然语言描述而非版本号方法内部固定version 1.0。若误将 1.0 作为 description 传入将导致 LLM 无法正确理解能力语义。四、HTTP 能力与操控台架构4.1 http_request 技术实现http_request能力自 v1.0.14 引入其技术意义超越简单的 HTTP 请求代理。该能力使 AI 可通过 ACI 调度受控浏览器发起任意 HTTP 请求核心价值在于本地组网——直接访问同网段设备的明文 HTTP 服务规避公网明文传输限制。能力范围Web API / 私有接口调用网页内容抓取第三方服务对接局域网设备访问路由器后台、NAS、智能家居、IoT 设备、树莓派等支持 HTTP 方法GET / POST / PUT / DELETE / PATCH / HEAD 及自定义方法支持自定义请求头与请求体平台限制与解决方案Android 9targetSdk ≥ 28默认禁止明文 HTTP 流量。受控端需在networkSecurityConfig中将base-config的cleartextTrafficPermitted设为true并对localhost、127.0.0.1、10.0.2.2、local域名开放访问。由于 Android NSC 不支持按私有网段配置白名单如192.168.0.0/16只能全局放开——此为平台限制非框架缺陷。接口契约定义项目说明入参url目标 URL必填入参methodHTTP 方法默认 GET入参headers请求头 JSON 字符串入参body请求体原样发送返回status_codeHTTP 状态码int返回response_headers响应头 JSON返回response_body响应体超过 15 万字符截断返回truncated是否截断boolean控制端QuroAciTools.renderHttpResult负责自动解压response_body_gz并将格式化后的状态码、响应头、响应体注入 LLM 上下文。4.2 ACI HTTP 操控台云边端协同架构ACI HTTP 操控台作为连接 ZorvAI决策与规划中心与受控端感知与执行终端的神经中枢实现了三个层面的技术范式变革4.2.1 架构变革从单体智能到云边端协同云端ZorvAI负责意图理解、任务分解、逻辑推理思考做什么边缘端ACI 操控台标准化协议转换与调度终端受控端将指令转化为具体操作动手怎么做通过标准化协议智能体的大脑与手脚实现解耦部署与独立升级任何兼容 ACI 协议的执行器均可成为 ZorvAI 的手实现执行终端多样化。4.2.2 开发范式变革从编码自动化到声明式编排开发者无需为每个网站编写特定爬虫或自动化脚本。通过自然语言或高级指令向 ZorvAI 描述任务目标ZorvAI 通过 ACI 操控台动态生成并下发针对当前网页结构的操作序列。维护负担从应对 UI 变更转移到提升智能体泛化能力。4.2.3 能力边界变革从信息处理到环境交互结合浏览器这一通用数字环境接口AI Agent 能力边界得到质的拓展操作任意 Web 界面邮箱登录、CRM 操作、在线表单、电商比价处理非结构化信息图片、图表、验证码敏感操作在本地浏览器环境完成数据无需上传云端4.2.4 控制端实现QuroAciManager 全生命周期管理服务发现通过PackageManager扫描声明com.ai.assistance.aci.ACTION_BIND的 Service连接池管理维护 Binder 连接处理断开重连能力缓存缓存Capability列表避免每次对话重新绑定调用日志记录时间戳、目标服务、能力 ID、入参摘要、返回状态与耗时结果渲染QuroAciTools.renderHttpResult解压、格式化受控端返回结果五、开发者接入指南5.1 环境准备aci-core为纯本地库以 AAR 二进制形式分发非 Maven Central 坐标仅依赖androidx.annotation:annotation:1.7.1。获取方式方式 A从 ZorvAI Releases v1.0.6 下载aci-core-release.aar放入模块libs/目录方式 B切换到项目的aci-core独立分支git checkout aci-core此为可独立构建的 Android 库工程5.2 五步接入流程引入 aci-core在build.gradle.kts中声明implementation(files(libs/aci-core-release.aar))声明权限在aci_permissions.xml中定义 5 层鉴权模型在AndroidManifest.xml中声明 ACI 权限继承 BaseACIService实现onCreateCapabilities()声明能力清单处理调用在onCall()中实现业务逻辑返回ACIResponse在onCheckPermission()中实现权限校验注册与暴露在Manifest中注册 Service必须声明ACTION_BIND和ACTION_WAKE两个 intent-filter六、代码实现示例6.1 最小受控端实现Kotlinclass MyAciService : BaseACIService() { override fun onCreate() { // 使用 try-catch 包装 super.onCreate()避免 onCreateCapabilities 异常导致 Service 崩溃 try { super.onCreate() } catch (e: Exception) { Log.e(ACI, onCreateCapabilities failed, e) } } override fun onCreateCapabilities(caps: MutableListCapability) { caps.add( Capability.create(open_url, 在浏览器打开指定网址) .addParam(url, string, true, 目标网址) .addFlag(Capability.FLAG_BACKGROUND) ) caps.add( Capability.create(get_device_info, 获取设备基本信息) .addParam(detail_level, string, false, 详细程度brief/full) ) } override fun onCall(req: ACIRequest): ACIResponse { return when (req.capability) { open_url - { val url req.getString(url) if (url.isNullOrBlank()) { return ACIResponse.error(ACIError.INVALID_PARAMETER, url is required) } // 实际打开逻辑 ACIResponse.success() .putResult(launched, true) .putResult(url, url) } get_device_info - { val level req.getString(detail_level) ?: brief val info if (level full) { mapOf( model to Build.MODEL, brand to Build.BRAND, sdk to Build.VERSION.SDK_INT ) } else { mapOf(model to Build.MODEL) } ACIResponse.success().putResult(device, info) } else - ACIResponse.error( ACIError.CAPABILITY_NOT_FOUND, unknown capability: ${req.capability} ) } } override fun onCheckPermission( request: ACIRequest, callerPkg: String ): Boolean { // 仅允许 ZorvAI 主程序或自身调用 return callerPkg com.ai.assistance.quro || callerPkg packageName } }6.2 Manifest 注册配置service android:name.MyAciService android:exportedtrue intent-filter action android:namecom.ai.assistance.aci.ACTION_BIND / action android:namecom.ai.assistance.aci.ACTION_WAKE / /intent-filter /service6.3 能力定义完整范式Capability.create(browser_open, 打开浏览器到指定网址) .addParam(url, string, true, 目标网址) .addParam(headers, json, false, 自定义请求头) .addFlag(Capability.FLAG_BACKGROUND)参数说明第一个参数能力 ID全局唯一标识符第二个参数面向 LLM 的自然语言描述非版本号addParam参数名 / 类型 / 是否必填 / 描述addFlag能力标志位如FLAG_BACKGROUND表示支持后台执行七、技术范式变革7.1 从功能驱动到意图驱动传统操作范式用户 → 打开应用 → 定位功能 → 执行操作ACI 驱动范式用户 → 自然语言意图 → AI 任务分解 → 多应用协同调度 → 自动化完成应用场景示例用户指令周五下午团队复盘将 Q3 销售数据发送给团队成员AI 执行链路日历应用ACI 受控端→ 创建会议日程表格应用 → 读取 Q3 销售数据邮件应用 → 群发数据文档提醒应用 → 提前 15 分钟通知全程无需用户手动操作任一应用界面。7.2 应用能力的语义自描述化ACI 要求受控端在onCreateCapabilities()中使用自然语言描述能力并声明参数 schema使应用功能首次具备机器可读的语义层。UI 不再是功能的唯一入口能力声明成为 Agent 时代应用设计的核心范式。7.3 本地组网的自动化延伸通过http_request能力Agent 的操作边界从手机屏幕内扩展到整个局域网可调度智能家居设备、访问 NAS 文件系统、调用路由器接口、对接树莓派服务实现物理空间的自动化控制。7.4 隐私与离线执行边界重定义维度传统云端 AgentACI 本地 Agent工具调用路径公网 HTTP → 远程 APIBinder IPC → 同设备应用数据流转范围用户数据需上传至云端服务器数据全程在设备内流转不出本地隐私保护级别依赖服务商隐私政策与加密传输操作系统级进程隔离无网络传输离线可用性依赖网络连接断网即失效完全离线可用仅需本地应用支持延迟与响应受网络质量影响存在百毫秒级延迟进程间通信微秒级延迟执行成本按 API 调用次数或流量计费零额外网络成本仅设备算力消耗部署复杂度需维护云端服务与 API 网关仅需设备端应用集成 ACI SDK生态开放性受限于服务商开放的 API 接口可接入设备上任意应用功能技术影响隐私计算新范式敏感操作如银行转账、医疗记录查询可在完全离线的环境下由 AI 代理完成消除数据泄露风险。边缘智能新场景在无网络或弱网环境工厂车间、野外作业、军事应用中AI 仍能调度本地应用完成复杂任务。成本结构重构企业无需为每个 AI 工具调用支付云端 API 费用大幅降低规模化部署成本。实时性突破金融交易、工业控制等对延迟敏感的场景可实现亚毫秒级 AI 决策与执行闭环。八、总结与展望8.1 核心价值总结ACI 框架通过标准化本地应用能力接口实现了三大技术突破执行本地化将 AI Agent 的工具调用从云端迁移到设备端消除网络延迟与隐私泄露风险。生态开放化打破应用孤岛使任意第三方应用功能成为 AI 可调用的工具。意图驱动化用户通过自然语言描述任务目标AI 自主分解并调度多应用协同完成。8.2 技术演进方向短期演进1-2年能力发现协议标准化建立设备间 ACI 服务发现与协商机制跨设备协同实现手机、平板、PC、IoT 设备间的 ACI 能力互操作动态能力热插拔支持运行时注册/注销能力无需重启服务中期演进3-5年能力市场与分发建立 ACI 能力商店开发者可发布、用户可订阅能力模块意图理解增强结合设备上下文位置、时间、使用习惯优化任务分解策略联邦学习集成在保护隐私的前提下实现跨设备能力使用模式的协同优化长期愿景5年以上操作系统级集成ACI 协议成为 Android/iOS/鸿蒙等操作系统的标准组件全场景自动化从数字世界扩展到物理世界通过 ACI 调度机器人、无人机等实体设备自主进化系统AI Agent 基于 ACI 能力使用反馈自主优化任务规划与执行策略8.3 开发者生态建设ZorvAI 团队计划围绕 ACI 构建完整开发者生态SDK 与工具链提供 IDE 插件、调试工具、性能分析器能力认证体系建立能力质量、安全性、性能的认证标准最佳实践库收集各行业场景的 ACI 集成案例与模板社区与论坛建立开发者交流平台共享经验与解决方案8.4 结语ACI 不仅是一个技术框架更是重新定义人机交互范式的关键基础设施。它将应用从封闭的功能集合转变为开放的、可编排的能力单元使 AI 真正成为用户的数字助手而非简单的信息检索工具。随着 ACI 生态的成熟我们有望见证一个全新的应用开发与使用范式——应用的价值不再仅由其 UI 体验决定更由其通过 ACI 暴露的能力丰富度与智能化程度衡量。在 AI 原生时代ACI 为开发者提供了将传统应用升级为智能体友好型应用的最短路径也为用户开启了无需学习复杂操作即可享受全设备自动化服务的新可能。