Zorv AI 的 ACI 3.0 架构：一套永不改 AIDL 的智能体能力接口1. 引言：从"应用孤岛"到"能力编排"

1. 引言：从"应用孤岛"到"能力编排"

在传统 Android 生态中，应用之间是相互隔离的"孤岛"。即使 AI 助手再聪明，也无法直接调用第三方应用的功能——除非开发者把私钥、权限和业务逻辑全部暴露给主控端，这既不安全也不现实。

Zorv AI 通过 ACI（Assistance Capability Interface，智能体能力接口）3.0 解决了这一痛点。它是一套把「设备侧能力」以受控、可编排、可跨进程的方式暴露给 AI 主控端的框架。

项目开源地址：github.com/Quor-a/Zorv…

一句话概括 ACI 的核心思想：

ACI = 一套通用 call(AidlAciRequest) 接口 + 一套受控端注册能力的机制。加能力不改 AIDL 契约，所有新能力都通过同一个通用接口路由。

第三方应用只要实现 ACI 受控端，就能把自己的功能（如读取健康数据、控制智能家居、触发某个业务动作）安全地交给 Zorv AI 的 AI 去调用——无需把私钥、权限、业务逻辑暴露给主控端。

2. 设计哲学与目标

ACI 3.0 的设计并非凭空而来，而是围绕六个核心目标展开：

设计目标	说明
契约稳定	AIDL 只定义 `call(request)`，新能力靠 `request.action` 区分，永不改接口
权限最小	受控端只声明自己真正需要的权限，库带入的权限必须 `tools:node="remove"` 剥除
可认证	每次调用经过 `onVerifyToken` 钩子校验，防止任意应用冒用
可编排	主控端可把多个受控端能力组合成一条工具链
跨进程	基于 Android AIDL / Binder，天然跨进程、跨应用
可原生	高频/底层能力走 `libacihost.so` 原生层，避免 JVM 开销

其中，"契约稳定"是最关键的设计决策——它保证了 ACI 框架本身可以独立演进，而不会因为新增一个业务能力就破坏既有接口。

3. 总体分层架构

ACI 3.0 采用清晰的四层架构，从底层契约到顶层业务能力各司其职：

flowchart TB
    subgraph CTRL[&#34;主控端 / Controller（Zorv AI 主程序）&#34;]
        A1[&#34;AI 推理引擎\n(LLM + Tool Calling)&#34;]
        A2[&#34;ACI Client\n(AidlAciClient)&#34;]
    end

    subgraph CORE[&#34;契约层 / aidl-aci-core (v1.0.26)&#34;]
        B1[&#34;IAidlAciService.aidl&#34;]
        B2[&#34;AidlAciRequest&#34;]
        B3[&#34;AidlAciResponse&#34;]
        B4[&#34;AidlAciError&#34;]
        B5[&#34;Capability\n(能力元信息)&#34;]
        B6[&#34;BaseAidlAciService\n(受控端基类)&#34;]
    end

    subgraph LIB[&#34;高层封装 / lib_aci (com.ai.assistance.quro.libaci)&#34;]
        C1[&#34;AciHandler&#34;]
        C2[&#34;CapabilitySpec&#34;]
        C3[&#34;CapabilityRegistry&#34;]
        C4[&#34;AciRouter&#34;]
        C5[&#34;PermissionGuard&#34;]
    end

    subgraph APP[&#34;参考实现 / aci-app (com.ai.assistance.quro.aciapp)&#34;]
        D1[&#34;AciAppService&#34;]
        D2[&#34;AciAppWakeReceiver&#34;]
        D3[&#34;MainActivity&#34;]
    end

    subgraph CAP[&#34;能力包 / cap_main&#34;]
        E1[&#34;业务能力\n(main.* / sub.*)&#34;]
    end

    A1 --> A2
    A2 -->|&#34;call(request)&#34;| B1
    B1 --> B6
    B6 --> C1
    C1 --> C4
    C4 --> C3
    C3 --> E1
    B2 -.定义.-> CORE
    B3 -.定义.-> CORE
    B4 -.定义.-> CORE
    B5 -.定义.-> CORE
    C1 --> C2
    C5 --> C3
    D1 --> B6
    D2 --> D1

分层说明

契约层（aidl-aci-core）：定义跨进程通信的"语言"。IAidlAciService 只有 call() 一个方法，请求/响应/错误/能力元信息全部由 AidlAciRequest / AidlAciResponse / AidlAciError / Capability 承载。
高层封装（lib_aci）：受控端开发者的"舒适层"，把注册、路由、鉴权封装成 AciHandler / CapabilityRegistry 等，免去手写 Binder 样板。
参考实现（aci-app）：一个完整可跑的受控端示例，证明框架端到端可用。
能力包（cap_main）：具体业务能力的集合，main. 前缀为一级能力、sub. 前缀为子能力。

4. 核心模块与职责

4.1 aidl-aci-core（契约层，namespace `ai.aidl.aci.core`）

类 / 接口	职责
`IAidlAciService`	AIDL 接口，仅 `call(AidlAciRequest): AidlAciResponse` 一个方法
`AidlAciRequest`	请求包：`action` + `params`（JSON）+ `token` + `caller`
`AidlAciResponse`	响应包：`code` + `data`（JSON）+ `error`
`AidlAciError`	结构化错误：`code` / `message` / `detail`
`Capability`	能力元信息：`id` / `name` / `description` / `paramsSchema`
`BaseAidlAciService`	受控端 Service 基类，提供 `onVerifyToken` 钩子与默认路由骨架

4.2 lib_aci（高层封装，namespace `com.ai.assistance.quro.libaci`）

类	职责
`AciHandler`	单条能力的处理器：解析 `AidlAciRequest` → 执行 → 返回 `AidlAciResponse`
`CapabilitySpec`	能力的声明式描述（id / 路由 / 是否需要鉴权 / 参数 schema）
`CapabilityRegistry`	能力注册表，按 `action` 映射到 `AciHandler`
`AciRouter`	路由器：把 `request.action` 分发到对应 `AciHandler`
`PermissionGuard`	权限守卫：校验调用方包名是否在 `CONTROLLER_PKGS` 白名单

CONTROLLER_PKGS 白名单硬编码为：

com.ai.assistance.quro（主控端主包）
com.ai.assistance.quro.browser（内置浏览器组件）

4.3 aci-app（参考实现，namespace `com.ai.assistance.quro.aciapp`）

组件	职责
`AciAppService`	继承 `BaseAidlAciService`，实现 `onCreateCapabilities()` / `onCheckPermission()` / `onCall()`
`AciAppWakeReceiver`	接收唤醒广播，拉起受控端进程（应对被系统回收）
`MainActivity`	调试/配置入口，可视化展示已注册能力

5. 关键抽象：一次能力调用的完整链路

理解 ACI 最好的方式，是追踪一次完整的能力调用。下面这张时序图展示了从 AI 引擎到具体业务能力的全过程：

sequenceDiagram
    participant AI as AI 引擎
    participant Client as ACI Client
    participant SVC as BaseAidlAciService
    participant Guard as PermissionGuard
    participant Router as AciRouter
    participant H as AciHandler(能力)

    AI->>Client: tool_call → call(request)
    Client->>SVC: Binder.call(request)
    SVC->>SVC: onVerifyToken(request.token)
    alt token 无效
        SVC-->>Client: AidlAciError(401)
    else token 有效
        SVC->>Guard: checkCaller(callingPackage)
        Guard-->>SVC: 是否在 CONTROLLER_PKGS
        SVC->>Router: route(request.action)
        Router->>H: dispatch(params)
        H-->>Router: AidlAciResponse
        Router-->>SVC: response
        SVC-->>Client: response
        Client-->>AI: data
    end

要点：AIDL 全程只有一个 call 方法；action 决定走哪个 AciHandler；鉴权发生在 onVerifyToken 与 PermissionGuard 两道关卡。

6. 受控端声明铁律

任何实现 ACI 受控端的应用，Manifest 必须剥除库带入的多余权限，否则会被主控端拒绝或触发安全告警：

<!-- 铁律：库带入的权限一律剥除，只保留自己真正声明的 -->
<uses-permission
    android:name="android.permission.READ_PHONE_STATE"
    tools:node="remove" />

tools:node="remove" 用于覆盖依赖库注入的 <uses-permission>。
AciAppService 必须 android:exported="true" 且声明 android:permission="ai.aci.permission.CALL"。
<queries> 必须包含 ACTION_BIND / ACTION_WAKE 以及主控端包名 com.ai.assistance.quro，否则跨进程绑定失败。

7. Token 认证模型

安全是 ACI 的基石。每次跨进程调用都必须通过 Token 校验，防止任意应用冒用能力：

flowchart LR
    A[&#34;受控端生成\n一次性/会话 Token&#34;] --> B[&#34;写入安全存储&#34;]
    B --> C[&#34;主控端读取 Token\n随 request 发送&#34;]
    C --> D[&#34;BaseAidlAciService\n.onVerifyToken(token)&#34;]
    D -->|&#34;通过&#34;| E[&#34;继续路由&#34;]
    D -->|&#34;拒绝&#34;| F[&#34;AidlAciError(401)&#34;]

BaseAidlAciService.onVerifyToken 是受控端必须实现的钩子。
主控端每次 call 都携带 request.token，未通过校验直接返回错误，杜绝任意应用冒用能力。

8. 通用桥（Intent / Provider）

除 AIDL 直连外，ACI 提供两类通用桥，让受控端复用既有 Android 机制：

桥	用途
`AciIntentBridge(intent)`	把 ACI 请求桥接到一个 `Intent`，复用现有 Activity/Service/Broadcast 逻辑
`AciProviderBridge(provider)`	把 ACI 请求桥接到 `ContentProvider`，适合数据读取类能力

9. 原生层（ACI Native）

高频 / 底层能力不走 JVM，而是下沉到原生层，避免虚拟机开销：

flowchart LR
    JVM[&#34;AciNativeBridge (JNI)&#34;] --> SO[&#34;libacihost.so&#34;]
    SO --> SYS[&#34;系统底层 API\n(文件/进程/硬件)&#34;]

libacihost.so：受控端原生宿主库，承载性能敏感能力。
AciNativeBridge：JNI 桥，Java 侧 AciHandler 可把执行委托给原生函数。

10. 能力扩展：如何新增一个能力而不改 AIDL

这是 ACI 3.0 最重要的设计承诺：永远不用改 AIDL。

新增一个能力只需三步：声明 → 实现 → 注册。

// 1) 声明能力（CapabilitySpec）
val spec = CapabilitySpec(
    action = "main.light.toggle",     // main. 一级能力
    needAuth = true,
    paramsSchema = """{"type":"object","properties":{"on":{"type":"boolean"}}}"""
)

// 2) 实现处理器（AciHandler）
class LightToggleHandler : AciHandler(spec) {
    override fun handle(params: JSONObject): AidlAciResponse {
        val on = params.optBoolean("on")
        // ... 执行业务 ...
        return AidlAciResponse.ok(JSONObject().put("done", on))
    }
}

// 3) 注册（CapabilityRegistry）
CapabilityRegistry.register(LightToggleHandler())

主控端只需 call("main.light.toggle", {on:true}) 即可调用，无需重新编译契约层。

11. 与 Zorv AI 主控端的关系

ACI 并非孤立存在，它与 Zorv AI 的「灵魂注入」和「记忆库」共同构成 能力 × 人格 × 记忆 的三位一体架构：

flowchart TB
    AI[&#34;Zorv AI 主控端\n(Controller)&#34;] -->|&#34;tool_calling&#34;| ACI[&#34;ACI Client&#34;]
    ACI -->|&#34;Binder&#34;| APP[&#34;aci-app / 任意受控端&#34;]
    APP --> CAP[&#34;业务能力&#34;]
    AI --> Soul[&#34;灵魂层提示词\n(见《灵魂注入》文档)&#34;]
    AI --> Mem[&#34;记忆库\n(见《记忆库》文档)&#34;]

主控端把 ACI 能力注册为 AI 的 function calling 工具。
AI 在对话中自主决定是否调用某个 ACI 能力（如"打开灯"、"读取健康数据"）。
ACI 与「灵魂注入」「记忆库」共同构成 Zorv AI 的能力 × 人格 × 记忆三位一体架构。

12. 总结与展望

ACI 3.0 通过"一个通用接口 + 注册机制"的设计，为 Android 生态提供了一种安全、可编排、跨进程的能力开放范式。它的核心价值在于：

对主控端：无需为每个新能力重新编译契约层，AI 可以动态发现并调用任意受控端能力。
对受控端：只需实现 BaseAidlAciService 并注册 AciHandler，即可安全地把能力开放给 AI，无需暴露私钥与业务逻辑。
对生态：任何应用都可以成为 AI 的"器官"，共同构建一个真正可编排的智能体生态。

如果你对 ACI 的实现细节感兴趣，欢迎访问项目源码：

开源地址：github.com/Quor-a/Zorv…

配套文档：本文档聚焦 ACI 框架本身；LSPosed/ADB/系统级浮窗能力参见《LSPosed 与系统级浮窗技术架构》，小程序渲染见《小程序技术架构》，人格与心跳见《灵魂注入与 AI 心跳人格自动孵化》，长期记忆见《记忆库架构介绍》。

Zorv AI 的 ACI 3.0 架构：一套永不改 AIDL 的智能体能力接口