auv：AI Agent 工具实践指南

团队讨论auv时，我会先把用途说清楚： 不，我们不是使用计算机，而是通过应用程序使用... OS 自动化的统一编排层，0 代币成本。在日常自动化场景里，常见问题是输入边界、依赖和失败处理如果不清楚就很难稳定复用，这正是评估时需要盯住的地方。落地前可以用一项范围明确的真实任务完成最小试跑，用配置时间、输出质量、异常信息和维护痕迹判断它是否真的省事。如果团队属于愿意先做小范围验证并复查原始文档的团队，它有继续测试的理由；否则先看替代方案会更省时间。

auv

auv 表示应用程序使用通过...。

• 通过 auv-apple-music 使用 Apple Music 应用程序...
• macOS 媒体控制通过 auv-media-macos 使用...
• Balatro（是的游戏 Balatro）通过 auv-game-balatro 应用程序使用...
• ...更多，等待您的实施。

将其视为可编程计算机的使用，无需代理。

开始使用

安装

直接从GitHub安装：

cargo install --git https://github.com/moeru-ai/auv auv-cli --bin auv
auv --help

第三方 Protobuf 源包含在存储库中；货物安装做 不需要 Buf 或单独的 Protobuf 依赖项生成步骤。请参阅 macOS Git 安装验证。

安装后直接使用auv CLI：

auv --help
auv invoke --help

设置

macOS

需要向启动auv的进程授予OS权限， 通常是您的终端应用程序。

打开 系统设置 -> 隐私和安全 并启用：

更改权限后，重新启动终端进程并重新运行：

auv doctor
auv invoke app.probePermissions

了解auv

对于 Cua、agent-browser 和 类似的计算机使用项目，常见的是执行 screenshot、read image、click、type、 wait，并按顺序进行后续验证步骤，然后要求LLMs或代理判断下一步动作。

flowchart LR
  A[Agent] --> B[screenshot]
  B --> C[read image]
  C --> D[decide next step]
  D --> E[click]
  E --> F[wait]
  F --> G[type]
  G --> H[verify]
  H --> D

许多重复序列可以压缩为可重用的 GUI 操作。 打开应用程序，等待准备就绪，填写表格并检查结果 应该作为一个命令来调用，而不是在同一个命令上花费代币 每次都一步步循环。

现代代理经常使用 技能 或项目 编排工具调用、CLIs 和脚本的指令。但内置的 计算机使用的表面，例如 OpenAI 电脑使用 或 克劳德计算机使用， 仍然主要是交互式模型工具循环，不可编写脚本 GUI 自动化 图书馆。

与 剧作家 类似，如果我们可以组织这些动作会怎么样？ 成可执行脚本，可重用？

• Ran screenshot
  └ saved screen.png
• Ran read image screen.png
  └ form is visible
• Ran click "Email"
  └ clicked
• Ran type "[email protected]"
  └ typed
• Ran screenshot
  └ saved after.png
• Ran verify form state
  └ ready

pub fn open_and_fill_form(
  app: &mut AppSession,
  data: FormData,
) -> AuvResult<OperationResult> {
  app.open()?;
  app.wait_for_ready()?;
  app.fill(data)?;
  app.verify_submitted()
}

• Ran screenshot
  └ saved page-1.png
• Ran OCR visible rows
  └ 12 rows
• Ran scroll
  └ scrolled down
• Ran OCR visible rows
  └ 10 rows, 4 repeated
• Ran guess when to stop
  └ uncertain

pub fn scan_visible_rows(
  region: &mut WindowRegion,
) -> AuvResult<ScrollScanArtifact> {
  region.scan_rows_until_stop()
}

• Ran click target
  └ clicked
• Ran screenshot
  └ saved after-click.png
• Ran semantic check
  └ mismatch
• Ran retry manually
  └ repeated tool loop

pub fn verify_and_retry<F>(
  mut operation: F,
) -> AuvResult<OperationResult>
where
  F: FnMut() -> AuvResult<OperationResult>,
{
  retry_until_verified(&mut operation)
}

auv 期望代理编写、测试和改进可重用的 GUI E2E 自动化 测试和快速应用操作。

事实上，auv并不是一个计算机使用的代理。它不运送代理或安全带。 它提供工具、CLIs、驱动程序和可验证的可观察结果，以便代理能够 构建可重用的 GUI 操作。

auv 适用于编码代理和代理产品，例如：

• 阿佩拉
• 法典
• 克劳德代码
• Pi代理
• LobeHub
• 基米 CLI
• ...带上你自己的

这意味着：

• 如果你的代理可以调用CLI，auv就可以作为电脑使用。
• 如果您的代理可以编写代码，auv 可以将重复的 GUI 工作移至可重用的位置 Rust 或 JavaScript/TypeScript 操作。一旦 GUI 流最终确定为 操作，重复执行可以接近零推理令牌成本。
• auv 的守护进程和扩展 APIs 使用版本化的 Protobuf/gRPC 合约。一个 具有兼容的 Protobuf/gRPC 生成器的语言可以生成客户端 这些合约没有 auv 发明另一种特定于语言的协议。 第一方 SDK 质量、包装和文档仍然是分开的 支持声明：Rust 和 JavaScript/TypeScript 现已上市，同时 第一方 Python SDK 仍在计划中。

可重用的部分按职责划分，但它们使用一次执行 模型而不是成为不相关的包装器：

flowchart LR
  A[CLI / MCP / Rust / JS / generated clients] --> B[typed operation]
  B --> C[local or remote Device / Runner]
  C --> D[capability Driver]
  D --> E[direct result]
  D --> F[Run trace and artifacts]
  E --> G[separate semantic verification]

驱动程序拥有自己的平台功能，操作箱拥有自己的可重用工作流程， auv-tracing 拥有 Run 证据和工件。视觉覆盖仍然是 独立的信任和调试界面；绘制光标永远不会代表 输入传递或语义验证。这种封装结构让另一个 前端或生成的语言客户端重用相同的操作，而不是 围绕 CLI 重新实现它们。

为什么还要构建 auv？

auv 诞生于 项目 AIRI 构建通用游戏代理的基础知识，自 2024 年以来，我们尝试构建代理以允许 LLMs 玩以下游戏，您可以在以下存储库中找到我们如何实现代理：

• 巴拉特罗
• 坎巴拉太空计划
• 异星工厂
• 球顶保持器

我们还实现了更多游戏，您可以在 项目 AIRI 组织中找到，但这四个游戏需要 YOLO、OCR、屏幕理解和计算机使用能力。

现在您拥有了可以为任何应用程序、游戏构建的框架。

自从 Vercel 发布了 agent-browser 以来，我们就爱上了它，并用它辅助代理构建了许多 Web 项目，但我们发现代理调用 agent-browser CLI 来执行命令所需的循环太慢且效率低下，而在计算机使用中世界上，许多操作可以重复数千次，就像Playwright/Vitest允许我们为应用程序编写E2E测试一样，我们为什么不将这种编写代码来控制应用程序的想法扩展到计算机使用世界呢？

能力矩阵

与其他计算机使用项目相比，auv 可以做什么。

• ✅：是的。
• ❌：没有。
• ⚠：部分支持。单元格说明了限制。
• ⏳：计划中的。
• ——：未评估。

平台支持来自本机桌面驱动程序行。其他行名称 仅当他们的支持不同时才使用平台。

| 能力 | auv | Cua | @oai/sky[^天空]

⚠ Windows：颜色 only ❌ Linux | ❌ | ❌ | ❌ | ❌ | | 滚动到列表 | ✅ 库和应用程序 integrations ❌ 通用 CLI | ❌ | ❌ | ❌ | ✅ 浏览器 lists ❌ 桌面列表 | | 反馈意见 | ✅ 尝试、回退、干扰、验证 | ✅ 输出和轨迹 | ⚠ 执行后读取状态 | ⚠ 仅元数据 | ⚠断言和痕迹 | | YOLO / 定制型号 | ✅ | ✅ | ❌ | ❌ | ❌ |

• 滚动扫描是auv存在的主要原因。大多数桌面自动化堆栈 可以滚动并捕获屏幕截图。他们不做页记录、行 候选人、裁剪工件、OCR 片段或明确的停止原因。目前的 滚动扫描的实现是合同工作。旧款 scan window-region CLI 当可重用的API被清除时将返回。
• 反馈是机器可读的操作证据。它记录了输入 路径、更改、工件、回退和验证结果。这个证据 告诉操作何时重试、停止或失败。

[^device-entry]: Evidence 级别：特定于配置的已安装主机测试。 此 API 锁定和解锁现有登录会话。它不登录 来自注销屏幕的用户。 2026-10-01测试跑了300次正常使用 lock/unlock 循环。 API 第一次尝试就通过了 298 个周期（99.33%）。 所请求的 OS 状态在 299 个周期 (99.67%) 中的第一次尝试时发生。 所有 300 个周期均以 USABLE 状态结束。该测试使用的停留时间为 15， 20、25 和 30 秒。单独的压力测试使用了接近于零的延迟。它 测量的是 OS 过渡准备情况，而不是正常使用可靠性。阅读 设备锁定合约及平台证据 对于类型化合约、本机机制和配置限制。原始的 日志保留在本地。它们不在耐用的证据包中。

[^ghost-cursor]: auv 未定义数字光标限制。主机内存和 WindowServer 资源限制实际计数。幽灵光标是可见的 覆盖。他们不提供输入或证明行动结果。

声明。 检查的包是来自 ChatGPT 的 @oai/sky 0.7.1 应用程序。它无法从公共 npm 注册表中获得。没有本机执行或 本机二进制检查支持此列。请参阅 本地天空 API 研究 和 后台交付比较。

发展

auv

cargo fmt --check
cargo check
cargo test

要更新供应商的 Protobuf 依赖项，请参阅 Protobuf源码分发参考。

@auv-js/sdk

先决条件

• Node.js (LTS)
• pnpm
• 缓冲器

[!NOTE]

如果你使用原型，那么

原型安装 buf
原型安装节点
原型安装 pnpm

，这应该可以帮助您安装必要的工具。

pnpm install
pnpm generate:proto
pnpm exec playwright install chromium
pnpm build
pnpm test:run
pnpm lint
pnpm typecheck

文档

更改根或包 READMEs 中的标题后，运行 pnpm docs:update。 此命令更新所有三个目录。

有用的切入点：

auv doctor
auv invoke <command-id> --help
auv serve --help
auv devices list
auv runner --help
auv run --help
auv mcp serve
auv plugin list

使用 docs/TERMS_AND_CONCEPTS.md 共享词汇。耐用的设计和 证据记录位于 docs/ai/references/ 下。

相关

[!NOTE]

该项目是 项目 AIRI 生态系统的一部分。