ACI（Agent Capability Interface）：安卓本地智能体能力接口框架深度解析-三亩地-编程学习日记

一、核心定位与技术范式

ACI（Agent 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["QuroAciManager<br/>- discover() 发现<br/>- bind() 绑定<br/>- getCapabilities() 取清单<br/>- 结果注入 LLM"] end subgraph Service["受控端（应用服务）"] B["BaseACIService 子类<br/>- onCreateCapabilities()<br/>- onCall() 处理<br/>- onCheckPermission()"] C["WakeReceiver<br/>进程唤醒"] end A -- "AIDL Binder<br/>call/callAsync" --> B A -- "ACTION_WAKE<br/>广播" --> C B -- "ACIResponse" --> A

2.2 核心能力矩阵

以官方 ZorvAI 浏览器受控端为例，其暴露的 30 个能力（2026-08-01 测试通过率 28/30）涵盖以下维度：

能力类别	数量	典型能力
基础操作	13	browser_open, browser_read, browser_back
智能代理	7	browser_crawl, browser_search
资源管理	2	browser_download, browser_share
完整方案	6	form_fill, payment_process
交互增强	1	virtual_mouse
网络扩展	1	http_request

关键能力技术规格：

能力 ID	关键入参	技术说明
`browser_open`	`url`（必填）	打开并导航至指定 URL
`browser_read`	—	读取当前页面 HTML（clean 模式返回精简 DOM，v1.0.8 修复 Binder 1MB 传输限制）
`browser_crawl`	—	抓取结构化正文及出站链接
`browser_search`	`query`（必填） `engine`（可选）	调用搜索引擎检索，支持 bing/google/baidu/ddg
`browser_script`	`code`（必填）	在当前页面注入并执行 JavaScript
`http_request`	`url`/`method`/`headers`/`body`	发送原生 HTTP 请求

2.3 通信机制

3.1 角色与核心组件

角色	职责	关键类
控制端	服务发现、绑定、能力清单获取、调用发起、结果注入 LLM	`QuroAciManager`+`IACIService`桩
受控端	继承`BaseACIService`，声明能力，实现业务逻辑	`BaseACIService`/`Capability`/`ACIRequest`/`ACIResponse`
Binder 契约	定义跨进程方法接口	`IACIService.aidl`/`IACICallback.aidl`
权限模型	5 层鉴权机制	`aci_permissions.xml`+`onCheckPermission()`

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(): List<Capability>`	必须	注册能力清单
`onCall(request: ACIRequest): ACIResponse`	必须	同步处理单次调用
`onCallAsync(request, callback)`	可选	异步处理；默认切线程后调用`onCall`
`onCheckPermission(request, callerPkg): Boolean`	可选	自定义调用方校验，默认返回`true`
`onBeforeCall`/`onAfterCall`	可选	钩子函数，默认仅日志记录

关键实现细节：Capability.create(String id, String description)的第二个参数是面向 LLM 的自然语言描述，而非版本号（方法内部固定version = "1.0"）。若误将 "1.0" 作为 description 传入，将导致 LLM 无法正确理解能力语义。

三、架构设计与通信机制

3.1 角色与核心组件

角色	职责	关键类
控制端	服务发现、绑定、能力清单获取、调用发起、结果注入 LLM	`QuroAciManager`+`IACIService`桩
受控端	继承`BaseACIService`，声明能力，实现业务逻辑	`BaseACIService`/`Capability`/`ACIRequest`/`ACIResponse`
Binder 契约	定义跨进程方法接口	`IACIService.aidl`/`IACICallback.aidl`
权限模型	5 层鉴权机制	`aci_permissions.xml`+`onCheckPermission()`

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(): List<Capability>`	必须	注册能力清单
`onCall(request: ACIRequest): ACIResponse`	必须	同步处理单次调用
`onCallAsync(request, callback)`	可选	异步处理；默认切线程后调用`onCall`
`onCheckPermission(request, callerPkg): Boolean`	可选	自定义调用方校验，默认返回`true`
`onBeforeCall`/`onAfterCall`	可选	钩子函数，默认仅日志记录

四、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 9+（targetSdk ≥ 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（必填）
入参`method`	HTTP 方法，默认 GET
入参`headers`	请求头 JSON 字符串
入参`body`	请求体（原样发送）
返回`status_code`	HTTP 状态码（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 最小受控端实现（Kotlin）

class 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: MutableList<Capability>) { 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:exported="true"> <intent-filter> <action android:name="com.ai.assistance.aci.ACTION_BIND" /> <action android:name="com.ai.assistance.aci.ACTION_WAKE" /> </intent-filter> </service>

6.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 隐私与离线执行边界重定义

维度	传统云端 Agent	ACI 本地 Agent
工具调用路径	公网 HTTP → 远程 API	Binder 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 为开发者提供了将传统应用升级为智能体友好型应用的最短路径，也为用户开启了无需学习复杂操作即可享受全设备自动化服务的新可能。

日记详情

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

一、核心定位与技术范式

1.1 本地化架构的核心定义

1.2 技术价值定位

二、功能架构与核心能力

2.1 架构概览

2.2 核心能力矩阵

2.3 通信机制

3.1 角色与核心组件

3.2 完整调用时序

3.3 五层鉴权模型

3.4 BaseACIService 方法契约

三、架构设计与通信机制

3.1 角色与核心组件

3.2 完整调用时序

3.3 五层鉴权模型

3.4 BaseACIService 方法契约

四、HTTP 能力与操控台架构

4.1 http_request 技术实现

4.2 ACI HTTP 操控台：云边端协同架构

4.2.1 架构变革：从单体智能到云边端协同

4.2.2 开发范式变革：从编码自动化到声明式编排

4.2.3 能力边界变革：从信息处理到环境交互

4.2.4 控制端实现：QuroAciManager 全生命周期管理

五、开发者接入指南

5.1 环境准备

5.2 五步接入流程

六、代码实现示例

6.1 最小受控端实现（Kotlin）

6.2 Manifest 注册配置

6.3 能力定义完整范式

七、技术范式变革

7.1 从"功能驱动"到"意图驱动"

7.2 应用能力的"语义自描述化"

7.3 本地组网的自动化延伸

7.4 隐私与离线执行边界重定义

八、总结与展望

8.1 核心价值总结

8.2 技术演进方向

8.3 开发者生态建设

8.4 结语