Zorv AI 文档

主题

ACI 2.0 与 SDK 路线图 ​

ACI（Agent Capability Interface，智能体能力接口） 是一套运行在同一台 Android 设备内、无需 Root、基于 AIDL Binder 的本地跨应用调用框架。任何 Android App 都能通过 aci-core 把自己暴露成「可被 AI 调用的能力」，由 Zorv AI 的 LLM 自动编排。

完整的受控端接入手册（5 步接入、能力定义、权限模型、真实踩坑）见 GitHub · ACI 开发者手册。

本页聚焦两件事：

  1. 已落地的 ACI 2.0 治理层（v1.0.15 起随主程序发布）
  2. 规划中的 ACI SDK 2.0 分层 Roadmap（把「能力接口」升为「平台」）

一、已落地的 ACI 2.0 治理层 ​

在 v1.0.15 中，ACI 从「裸调用」补上了治理内核，真机测试 42/42 全过 0 失败（浏览器 30 + WorkflowACI 10 + 主程序 2）：

组件作用关键设计
QuroAciErrors标准化错误模型 {code, message, suggestion, layer}命名空间 aci-protocol，码段 15xx / 24xx / 25xx，刻意避开 aci-core 标准码 0 / 400 / 403 / 404 / 500 / 503 / 504 / 505，避免与受控端既有错误码冲突
QuroAciProtocol协议版本化与协商aci-protocol-v1 协议版本化 + negotiate(peer) 协商两端最高兼容版本
QuroAciEvents进程内事件总线含 SERVICE_BOUND / UNBOUND / CALL_FAILED / DISCOVERED / PROTOCOL_NEGOTIATED

受控端 QuroMainAciService 新增 aci_protocol 能力暴露，并统一错误码 / 超时 / 坏请求返回；控制端 QuroAciManager 接入协议协商、错误解析与事件下发。

治理层带来的改变 ​

  • 错误可读：控制端拿到的是带 suggestion（LLM 可解析修复建议）的结构化错误，而非裸 HTTP 风格码。
  • 协议可协商：新老受控端共存时通过 negotiate 选最高兼容版本，降低「存量设备集体失联」风险。
  • 可观测：调用失败、绑定状态变化、协议协商结果都能经事件总线被上层订阅。

二、ACI SDK 2.0 分层 Roadmap（规划中） ​

以下为架构评审与 Roadmap 校准结论（来自 docs/ROADMAP-aci-sdk2-2026-08-02.md）。当前状态：方向认可（🟢 Go），按 Phase 0→4 分期，禁止一步到位。

当前 ACI 是「能力接口」；SDK 2.0 要把它升为「平台」。核心判断：

  • 最关键的单一阻塞项：协议版本化今天完全为零（Capability.create 写死 version="1.0"）。不先立版本，所有「兼容适配器 / 向前向后兼容」都是空谈——这是 Phase 0 的唯一硬目标。
  • 最大过度设计风险：一上来铺 4 种传输（IPC / WS / HTTP / gRPC）+ 4 种语言（C / C++ / Python / TS / Go）。建议先抽象接口 + 复用已有 Binder，再分期加 HTTP / WS。
  • 必须降噪的两点：① 跨设备网关是双刃剑（当前 ACI 刻意 local-only），必须默认关 + LAN-only + 临时令牌；② 动态能力热加载在 Android 上坑极多，先做配置驱动清单。

分层栈（下层为上层提供契约） ​

┌─ 工具链层   CLI / Manifest 可视化编辑器 / .aciplug 打包 / 兼容测试套件
├─ 多语言绑定  Core(C/C++) · Python · TS/JS · Go   （High/Low-level API + 配置外部化 + 能力注册表）
├─ Runtime 层   任务编排（Create/Snapshot/Resume/Cancel/Delegate）· 超时熔断 · 上下文/长会话 · 事件订阅
├─ Transport 层  ACIAdapter 抽象：Binder(IPC) · HTTP · WebSocket · (gRPC 延后) · 跨设备网关(安全评审后)
└─ Kernel 层    aci-protocol SemVer + 协商 · 契约(Capability/Request/Response/Error) · 治理(凭证/HTTPS信任/审计/错误模型)

关键点：Runtime 必须建在 Transport 之上（任务跨多次调用 / 跨传输），而非与 Transport 并列；协议版本化是整个栈的「地基开关」。

分阶段计划 ​

Phase 0 — SDK Kernel 地基（必须先做，阻塞一切后续）

  • 协议版本化：独立 aci-protocol SemVer，Capability / ACIRequest / ACIResponse 增加 protocol_version 字段，启动协商。
  • Adapter 抽象：新增 ACIAdapter 接口（send / receive / lifecycle），把现有 Binder 下沉为 BinderAciAdapter，BaseACIService 重构为薄桥接。
  • 标准化错误模型：ACIError 增加 code + message + llm_fix_hint。
  • 治理横切并进内核：凭证托管（密钥库，非每次 LLM 明文 headers）、HTTPS 自签信任策略、控制端 ACI 调用审计（QuroAciManager.call 落盘 JSONL）。
  • SDUI 快照加 schema_version + 兼容降级提示。

Phase 1 — Runtime 执行层：任务原语（TaskCreate / TaskSnapshot / TaskResume / TaskCancel / TaskDelegate）、断点续执行（状态持久化）、超时熔断、上下文 / 长会话。

Phase 2 — Transport 可插拔 + 事件订阅：Binder（已有）、HTTP（复用 http_request 底座）、WebSocket（新增）；事件订阅模型（受控端主动推送）；跨设备网关单列安全评审（默认关 / LAN-only / 临时令牌）。

Phase 3 — 多语言 SDK + 分层能力发现：能力注册表 + 标签检索；语言优先级 Python → TS/JS → Go → C/C++ Core；High/Low-level API 分层 + 配置外部化。

Phase 4 — 工具链 + 生态：ACI CLI、Manifest 可视化编辑器、.aciplug 插件包、兼容测试套件、官方高频 App 适配器参考实现、能力市场。

三、已知资产（别重建） ​

  • 多受控端统一控制台入口已上线（QuroAciCenterScreen）。
  • Adapter 模式已有成功先例：QuroBotAdapter / QuroDirectBotAdapter（微信 / 飞书 / QQ），ACI Adapter 应直接复用同一思想。
  • 响应体大小处理 / 超时已在 http_request 落地（>2MB 标 truncated、>15 万字符 gzip、控制器 15s 硬上限），Transport 层不必从零造。
  • SDUI 控制台基础设施已就绪（AciConsoleContract / AciConsoleModel）。

四、官方受控端能力清单（节选） ​

受控端「ZorvAI 浏览器」已暴露 30 个能力（13 基础 + 7 agentic + 2 资源/分享 + 6 完整方案 + 1 虚拟鼠标 + 1 HTTP 传输）。常用项：

能力入参返回说明
browser_openurl(必填)launched / ready / url打开并导航到指定网址
browser_readmode(可选)html + truncated（大页 html_gz）读取当前页 HTML（v1.0.8 修复 Binder ~1MB 溢出）
browser_crawl—text / links / link_count抓取结构化正文 + 出站链接
browser_searchquery / engine结果页结构化数据用搜索引擎检索关键词
browser_scriptcode(必填)result当前页执行任意 JavaScript（高危，仅可信会话）
http_requesturl / method / headers / bodystatus_code / response_*v1.0.14 新增，支持同网段 LAN 明文

完整契约见 ACI 开发者手册 §13。

Zorv AI · 设备端 AI Agent · Apache-2.0 开源

Copyright © 2026 Zorv AI Team