2026arXiv: 2606.23449 (Technical Report); 源码分析基于 GitHub main 分支

AOHP 源码深度解读：Agent-Native OS 的架构实现与安全机制

AOHP: An Open-Source OS-Level Agent Harness for Personalized, Efficient and Secure Interaction

从源码层面深入剖析 AOHP（Android Open Harness Project）的四层垂直架构、15 组 CLI 命令设计、六阶段 UDAGen 生成管线、五层安全信息流防护，以及 11 个 OpenClaw Skills 的集成方式。本文基于完整项目源码（TypeScript/Java/Python）分析其系统边界、实现机制与设计取舍。

Shanhui Zhao (Tsinghua), Jiacheng Liu (Peking), Guohong Liu (Tsinghua), Jichao Yan (Tsinghua), Jialei Ye (Peking), Yuhao Yang (HKU), Yunxin Liu (Tsinghua, corr.), Yuanchun Li (Tsinghua, corr.)

AI解读Agent 架构操作系统Agent 安全源码分析Agent Framework

项目主页：github.com/aohp-os/aohp | 论文: arXiv:2606.23449 团队: 清华大学 (AIR) × 北京大学 × 香港大学 | 许可证: Apache 2.0 代码规模: TypeScript CLI ~2000 行、Python UDAGen ~3000 行、11 个 OpenClaw Skills、AOSP 系统层修改

1. 论文概览与项目边界

AOHP 的核心命题是：现代 Agent 的工作模式与以应用为中心的操作系统架构之间存在系统性不匹配。传统 Android 假设用户直接操作开发者定义的 GUI、一次只运行一个前台应用、权限绑定在应用边界上——这些假设在 Agent 需要跨应用传递数据、并行后台执行、处理事件流的场景下全面失效。

AOHP 的解决方案不是在应用层再叠一个框架，而是直接修改 AOSP（Android 16 QPR2）源码，将 Agent 提升为 OS 一级主体。其项目仓库包含四个独立组件：AOHP AgentDriver（系统级 Java/Kotlin 服务，通过 WebSocket 暴露 JSON-RPC 接口）、aohp CLI（TypeScript/Node.js 命令行自动化前端）、UDAGen（Python 应用生成管线）、OpenClaw Skills（11 个 YAML/Markdown 技能定义）。

图 1: AOHP 四层垂直架构——底层兼容 Android 生态，向上依次提供统一交互接口、能力编排层和个性化服务组合，高效智能体接口与安全信息流两大跨层机制贯穿全栈。

2. 四层架构的代码级实现

2.1 L1 — Android 生态层（兼容层）

AOHP 不构建全新 OS，而是在 AOSP 源码基础上叠加 Agent 原语。构建流程（scripts/build.sh）揭示了完整的编译管线：lunch aosp_cf_x86_64_phone_aohp-trunk_staging-userdebug 选择 AOHP 定制目标，然后依次执行 CLI 的 esbuild 打包、Alpine rootfs 模板重新封装（嵌入 aohp 二进制 + Node.js 运行时），以及 AOSP 平台增量编译 m -j10。系统以 Cuttlefish 虚拟机运行，支持网络桥接多实例（scripts/bridge_network.sh）。

2.2 L2 — 统一交互接口层（AgentDriver + JSON-RPC）

L2 是整个系统的事实通信中枢。AOHP AgentDriver 是一个系统级 Android 服务，在设备端监听 ws://127.0.0.1:6666，对外暴露完整的 JSON-RPC 2.0 协议。CLI 客户端 (cli/aohp/src/client.ts) 仅 52 行代码，实现了 WebSocket 连接、JSON 序列化、超时管理和错误处理的标准 RPC 调用模式，默认超时 120 秒。

RPC 类型定义 (cli/aohp/src/schema.ts) 展示了极简的协议设计：

typescript

type JsonRpcRequest = {
  id: string;       // UUID v4
  method: string;   // 命名空间.方法，如 "act.tap"
  params?: Record<string, unknown>;
};

type JsonRpcResponse = {
  id: string;
  ok: boolean;
  result?: unknown;
  error?: { code: string; message: string };
};

AgentDriver 将传统 Android 接口和 Agent 需求归一化为四种调用模式：API（系统服务调用）、CLI（shell 命令执行）、Structured UI（增强型 UI 层级树，flags bitmask 0x7 控制装饰过滤/离屏标记/视觉标记）、Rendered GUI（JPEG 截图回退）。Agent 优先走符号化路径（API/CLI/Structured UI），仅在兼容性需要时回退到像素级 GUI 操作，这是效率提升的核心来源。

2.3 L3 — AOHP 能力层

能力层在 L2 的统一接口之上封装了三个 OS 级能力模块：

System Memory：OS 管理的跨应用偏好存储和任务状态，取代各应用内部碎片化的记忆。
Skills：可复用的服务能力封装，通过 OpenClaw 兼容的技能描述文件（SKILL.md）定义，每个技能直接映射到 CLI 命令组。
UI Utilities：为 L4 的生成式入口提供 UI 构建工具。

2.4 L4 — 个性化服务组合层

组合层将 L3 的能力组装为面向用户的服务入口。用户看到的是"健康管理""礼物推荐"等任务级概念，而非具体应用的界面。L4 的核心机制通过 UDAGen 管线实现，详见第 4 节。

3. aohp CLI：命令组设计与接口抽象

CLI (cli/aohp/src/index.ts，约 2000 行) 是整个系统的自动化前端。基于 Commander.js 框架，通过 esbuild 打包为单文件可执行 Node.js 脚本。其 15 组命令的设计直接映射了 AgentDriver 的 RPC 能力边界：

命令组	RPC 前缀	核心能力
`display`	`display.*`	虚拟显示器的创建/销毁/列表/启动器/焦点
`app`	`app.*`	应用包列表/信息/启动/杀死/前台/运行时快照
`act`	`act.*`	点击/长按/滑动/按键/文本输入/节点操作/进度条/文件路径追踪
`ui`	`ui.*`	UI 层级树获取（增强型 + 原始）、节点查找、焦点字段文本
`shot`	`shot.*`	全屏/区域/节点截图（JPEG Base64 + 本地保存）
`event`	`event.*`	Toast/通知事件流的注册/排泄/注销/状态查询
`sensor`	`sensor.*`	硬件相机拍照
`sys`	`sys.*`	剪贴板/通知栏/设备信息/电池/网络/唤醒/睡眠/解锁
`sms`	`sms.*`	SMS 发送（地址/联系人名称两种寻址方式）
`file`	`file.*`	文件扫描/列表/状态/快照/差异/文件夹展示/分享
`sandbox`	`sandbox.*`	Linux chroot 沙箱的完整生命周期管理
`uda`	`uda.*`	用户定义应用的配置/输入/生成/状态/安装/启动

关键的架构决策：

(a) Structured UI 与 Enhanced UI Tree：CLI 默认使用 flags=0x7 获取增强型 UI 树——合并了装饰过滤(0x1)、离屏标记(0x2)和视觉标记(0x4)，将传统 Accessibility Tree 转化为低冗余、高语义的结构化表示。输出的 compact HTML 格式可直接被 Agent 解析，避免了像素级截屏→视觉模型解析→坐标定位的低效链路。

(b) 文件路径追踪（filePathReport）：这是一个精妙的设计。当 Agent 执行可能产生文件的操作（如导出、保存）时，--file-path-report 参数触发一个后置文件扫描：在指定时间窗口内，扫描 downloads/pictures/dcim/documents 等根目录下的最近文件，通过 MIME 类型过滤和递归深度控制（maxDepth=4, maxFiles=2000），自动将 GUI 操作产生的文件反射为结构化观测。机制参数可精细调优：settleMs（操作后等待 1200ms）、retryDelayMs（无匹配时重试 1000ms）、timeoutMs（扫描预算 3000ms）。

(c) 节点级进度条操作：act.set_node_progress 支持两种语义——原始值模式（-V，直接设置 SeekBar 的底层数值如亮度 -25）和百分比模式（-P，0-100 沿全跨度定位）。当 Agent 只知道"调到 75% 亮度"而不清楚底层数值范围时，CLI 会自动探测节点范围（通过一次 50% 的试探性 ACTION_SET_PROGRESS 调用获取 min/max），再计算目标值，避免了 Agent 需要理解设备特定数值范围的认知负担。

(d) OpenClaw 兼容输出：截图和操作结果通过 buildOpenClawPiToolResult() 构建为与 OpenClaw Agent 框架兼容的多模态内容块（{ content: [{type: "text"}, {type: "image", data, mimeType}], details: {...} }），确保 CLI 可以直接作为 OpenClaw 的 tool 后端使用。

4. UDAGen：六阶段应用生成管线

UDAGen (udagen/) 是一个完整的 Python 应用生成系统，基于 Pydantic 数据模型、litellm LLM 客户端和模块化管线架构。

4.1 配置管理（`config.py`）

UdaGenerationConfig 通过 25+ 个配置字段精细控制生成行为，支持三层配置源（环境变量 → .env 文件 → 命令行参数），优先级逐层递增。关键设计决策：

代理清理：clear_proxy_env=True（默认）会在生成前自动清除 http_proxy/https_proxy 等环境变量，防止代理干扰 API 调用。
LLM 抽象：通过 litellm.completion 统一调用接口，支持任意 OpenAI 兼容端点（UDA_MODEL、UDA_BASE_URL、UDA_LLM_PROVIDER）。
参考图像生成：集成火山引擎 Seedream API（doubao-seedream-5.0-lite）为应用生成 1440×2560 参考设计图，支持 text/vision 两种输入模式。
温度分层：设计阶段 design_temperature=0.25、构建阶段 build_temperature=0.35、优化阶段 refinement_temperature=0.25。

4.2 六阶段管线（`pipeline.py`）

UdaPipeline 类编排了完整的生成管线，每阶段有独立的 LLM 提示词模板：

text

阶段 1: 输入收集 (collect_input_bundle)
├── 扫描输入目录，解析 .md/.json/.yaml/.csv 等格式
├── 生成 InputBundle (Pydantic 模型，含文件摘要和内容预览)
└── 排除已生成的中间产物的路径，避免上下文污染

阶段 2: Mock 生成 (generate_mock_bundle)
├── 仅在无结构化输入（OpenAPI/JSON Schema）时触发
├── LLM 自动生成接口文档 (interface_brief.md + interface_examples.json)
└── 生成 Mock HTTP 服务器代码 (Python http.server)

阶段 3: PRD 起草 (draft_prd)
├── 将 InputBundle JSON 喂入 LLM，生成 ProductRequirementsDoc
├── 包含产品目标、用户角色、核心功能、成功指标
└── 同时输出 prd.json + prd.md（人类可读版本）

阶段 4: 设计规范 (draft_design)
├── 将 PRD JSON + InputBundle JSON 喂入 LLM
├── 生成 DesignSpec：包含页面设计、导航、数据绑定、Mock 策略
└── 输出 design_spec.json + design_spec.md

阶段 5: 应用代码生成 (build_app)
├── 将完整生成上下文（PRD + DesignSpec + InputBundle + 参考图）喂入 LLM
├── LLM 返回文件映射 JSON → 写入 app/ 目录
└── 生成纯 HTML/CSS/JS 静态应用

阶段 6: 迭代优化 (run_refinement, 默认 2 轮)
├── 每轮将当前生成文件 + DesignSpec + 生成上下文重新提交给 LLM
├── 重点修复导航断裂、数据绑定丢失、响应式适配问题
└── 每轮最多重试 2 次 JSON 解析失败

4.3 数据模型（`models.py`）

管线的结构化程度体现在 Pydantic 模型的精细度上：

InputBundle：统一输入抽象，聚合来自多来源文件的结构化摘要。
ProductRequirementsDoc：包含目标用户、核心场景、功能需求、约束条件。
DesignSpec：包含 pages（页面级设计）、navigation（导航模式，默认 bottom-tabs）、mock_strategy（static/server/hybrid/none）、personalization_signals（个性化信号）、editable_surfaces（用户可编辑区域）。
PageDesign：每个页面定义 primary_components、data_bindings、actions、states（loading/empty/error）和响应式适配说明。

4.4 日志与可观测性

LLMClient.chat_completion() 将所有 LLM 交互记录到 JSONL 格式的聊天日志（udagen_chat_logs.jsonl），包含完整消息对、模型名、时间戳和 token 用量。这提供了完整的生成过程审计追踪。

5. 安全机制：五层信息流防护

AOHP 的安全设计建立在一个核心前提上：Agent 的 LLM 上下文是攻击面和隐私泄露面的核心。一旦敏感明文进入 Agent 上下文，它就变得不可控——可能被模型记忆、被工具调用意外泄露、或被 prompt injection 诱导输出。因此，AOHP 的安全架构目标是让敏感数据完全绕过 Agent 的 LLM 上下文。

5.1 Source Sanitization（源头脱敏）

在敏感数据从系统流向 Agent 时，AgentDriver 在 OS 层面自动将明文替换为类型化占位符。例如，银行卡号 6222-xxxx-xxxx-1234 被替换为 <payment-card:uuid-abc123>，家庭住址被替换为 <shipping-address:uuid-def456>。Agent 在整个推理和工具调用过程中只能看到这些不可逆的占位符，无法获悉实际明文。

5.2 Trusted Vault Executor（可信金库执行器）

当 Agent 需要对敏感数据执行操作（如提交支付、填写地址）时，它不传递数据本身，而是提交意图声明（例如 { action: "pay", card_ref: "<payment-card:uuid-abc123>", amount: "¥299" }）。可信执行器在受信环境中解析占位符、验证策略、完成实际操作，并将结果返回给 Agent——中间没有任何明文进入 Agent 上下文。

5.3 Taint Tracking（污点追踪）

借鉴 TaintDroid 的学术传统，AOHP 实现了 OS 级的全链路污点追踪。从数据进入系统开始，污点元数据跟随数据流经复制、变换、组合、传输的每一步。这意味着即使敏感数据被拼接到一段纯文本中、被编码为 Base64、或被序列化到 JSON 中，其污点标记仍然可被追踪。

5.4 Policy Enforcement（策略执行）

在系统出口（网络、文件系统、剪贴板）和状态变更边界（支付确认、权限变更），策略引擎检查污点标记并决定是否需要用户显式审批。策略是声明式定义的，与 Agent 的行为逻辑解耦。

5.5 Fail-Closed Default（未授权默认拒绝）

当访问请求超出声明的策略范围时，系统默认拒绝而非暴露数据。这与传统 Android 的"默认允许 + 运行时权限弹窗"模型形成根本性对比。安全评测中全部 5 类测试（敏感显示脱敏、普通操作免审批、敏感操作需确认、未授权默认拒绝、事件脱敏追溯）均通过。

5.6 安全机制的代码层实现位置

安全机制不是独立模块，而是纵向嵌入 AgentDriver 的 RPC 处理链路中：

Source Sanitization 发生在 AgentDriver 的 响应序列化层——在 JSON-RPC 响应返回给 Agent 之前，字段级检查并替换敏感标记。
Taint Tracking 发生在 数据访问拦截层——所有通过 AgentDriver 访问的系统数据（文件内容、剪贴板、通知文本）都经过 taint source 标记。
Policy Enforcement 发生在 RPC 方法拦截层——敏感操作（支付、地址填写、文件分享）在到达实际执行器之前先经过策略引擎。
Fail-Closed 是 默认拒绝策略——在策略引擎中，任何未匹配到显式允许规则的操作默认返回拒绝。

6. OpenClaw Skills 集成

AOHP 通过 11 个 OpenClaw 兼容的技能定义文件（skills/*/SKILL.md），将 CLI 能力直接映射为 AI Agent 可调用的工具。每个 SKILL.md 包含：

YAML frontmatter：技能名、描述、OpenClaw 元数据（emoji 图标、依赖的二进制文件 aohp、目标 OS linux）
使用场景说明：何时应调用该技能
命令参考：完整的 CLI 命令表格和示例
RPC 映射：CLI 命令到 JSON-RPC 方法的对应关系

技能的模块化设计使 Agent 可以按需加载——执行 GUI 操作时加载 aohp-ui-actions，需要沙箱执行时加载 aohp-sandbox，生成应用时加载 aohp-uda + uda-app。这意味着 Agent 的上下文不会被全量工具描述淹没，而是根据任务动态组装工具集。

7. 实验结果

基于 30 项真实移动端任务的基准测试（OpenClaw Agent 在 AOHP vs 原生 Android）：

指标	原生 Android	AOHP	改善
任务完成率	54.44%	75.56%	+21.12%
工具调用次数	233	129	-44.64%
执行时长	33.94 min	18.93 min	-44.21%
Token 消耗	7.10M	3.44M	-51.55%
LLM 请求次数	273	143	-47.62%

Token 消耗降低的核心原因是"更少的步骤 → 更短的上下文"——Agent 每步操作和观测都会堆积到上下文中，AOHP 用更少的步骤完成相同任务，上下文自然更紧凑。具体而言，输入 Token 减少 51.50%，输出 Token 减少 57.48%。

8. 设计启示

8.1 接口分层的经济学

AOHP 的四种交互模式（API > CLI > Structured UI > Rendered GUI）揭示了一个根本性的效率原则：接口的语义越丰富，Agent 的理解成本越低。在 API 层面，Agent 只需要理解参数 schema；在 Structured UI 层面，Agent 可以基于节点 ID 精确操作；而在 Rendered GUI 层面，Agent 需要通过视觉模型解析像素、定位坐标、验证结果——每一步都昂贵且容易出错。AOHP 通过 OS 级改造，将 Agent 的操作尽可能推向符号化路径。

8.2 安全的正确层次

AOHP 的安全设计展示了一个关键洞察：安全约束的最有效执行点在 OS 层，而非 Agent 层或 LLM 层。AgentSpec 和 GuardRail 类方案在 Agent 输出后进行检测和拦截，但它们能够访问的上下文有限，且依赖于对 LLM 行为的假设。AOHP 在数据访问的源头（系统调用层）执行约束——在敏感数据离开系统之前就完成了脱敏和标记。这种"前置式"安全架构的原理性优势在于：不需要信任 Agent 的行为或 LLM 的输出。

8.3 Agent-Native OS 的可实现性

AOHP 证明了一个重要命题：Agent-Native OS 不需要从零开始构建。通过 AOSP 的模块化修改——新增 AgentDriver 系统服务、扩展 Input/Display/File 等框架层——可以在保留完整 Android 生态兼容性的前提下，实现 OS 级的 Agent 原生支持。这对于 Agent-Native OS 从研究原型走向产业落地具有重要的参考价值。

8.4 局限性

AOHP 目前是一个研究原型，存在若干未解决的问题：对自定义渲染引擎、反自动化逻辑、未文档化行为的应用兼容性覆盖不足；能力发现仍然依赖手动标注，缺乏对遗留应用的自动推理；虚拟显示、沙箱、事件流的并发执行尚未纳入移动端的热/内存限制策略；细粒度信息流控制产生的大量审批决策需要更智能的用户界面。

9. 参考链接

本文基于 AOHP 项目完整源码（TypeScript CLI ~2000 行、Python UDAGen ~3000 行、11 个 OpenClaw Skills、AOSP 系统层修改）进行架构分析。代码审查范围涵盖 cli/aohp/src/（index.ts, client.ts, schema.ts, act-key.ts, build.mjs）、udagen/（pipeline.py, config.py, models.py, llm.py, prompts.py, collector.py, mockgen.py）、skills/*/SKILL.md、scripts/build.sh 等核心文件。

研究