视觉理解智能体 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

灵瞳是 Crab Claw 内置的视觉 AI 子智能体，基于 C++/Rust 混合架构构建，能够真正"看见"你的桌面屏幕——理解界面内容、识别 UI 元素、操控鼠标键盘，在非 Web 场景中实现桌面级自动化。

为什么需要灵瞳

看见桌面

不依赖 DOM 或 API，通过屏幕截图 + 视觉模型理解任意桌面应用界面。原生应用、系统设置、IDE 均可操控。

精准操控

屏幕坐标级的鼠标点击、双击、文本输入、滚动操作。可精确定位按钮、输入框、菜单项等 UI 元素。

独立 LLM 会话

拥有独立的 LLM 模型配置，可以使用与主智能体不同的模型（如视觉能力更强的 Claude Sonnet）。

macOS 深度集成

通过 Accessibility API + TCC 权限框架实现系统级屏幕录制和辅助功能访问，安全合规。

子智能体化架构

与 Open Coder 同级的完整子智能体——拥有独立 LLM session、委托合约、质量审核、异步求助通道。

与浏览器互补

Browser 工具专注 Web 自动化（CDP 更快更精确），灵瞳专注桌面应用/跨应用场景。两者共存互补。

架构概览

shell

┌──────────────────────────────────────────────────────────────┐
│  主智能体                                                     │
│  "帮我在 Sketch 中调整这个按钮的颜色"                          │
│       │                                                      │
│       ▼ spawn_argus_agent                                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  灵瞳子智能体 (独立 LLM Session)                        │  │
│  │  ├─ 专用系统提示词 (announce_argus.go)                  │  │
│  │  ├─ DelegationContract (合约约束)                       │  │
│  │  ├─ 质量审核 + 交付门控                                 │  │
│  │  └─ AgentChannel (异步求助通道)                         │  │
│  │       │                                                │  │
│  │       ▼ argus_* 内部工具                                │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  ArgusBridge (Go ← MCP IPC → Rust/C++)          │  │  │
│  │  │  ├─ 进程管理 + 健康监控                           │  │  │
│  │  │  ├─ MCP 工具代理                                  │  │  │
│  │  │  ├─ 指数退避重启 (1s→60s, max 5)                  │  │  │
│  │  │  └─ macOS TCC 权限检测                            │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
│       │                                                      │
│       ▼                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Argus 核心 (C++/Rust 混合, macOS App Bundle)          │  │
│  │  ├─ 屏幕捕获 (Screen Recording API)                    │  │
│  │  ├─ 视觉分析 (元素识别 + 场景描述)                      │  │
│  │  ├─ 鼠标键盘操控 (Accessibility API)                    │  │
│  │  └─ OCR 文本提取                                       │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│  主智能体                                                     │
│  "帮我在 Sketch 中调整这个按钮的颜色"                          │
│       │                                                      │
│       ▼ spawn_argus_agent                                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  灵瞳子智能体 (独立 LLM Session)                        │  │
│  │  ├─ 专用系统提示词 (announce_argus.go)                  │  │
│  │  ├─ DelegationContract (合约约束)                       │  │
│  │  ├─ 质量审核 + 交付门控                                 │  │
│  │  └─ AgentChannel (异步求助通道)                         │  │
│  │       │                                                │  │
│  │       ▼ argus_* 内部工具                                │  │
│  │  ┌──────────────────────────────────────────────────┐  │  │
│  │  │  ArgusBridge (Go ← MCP IPC → Rust/C++)          │  │  │
│  │  │  ├─ 进程管理 + 健康监控                           │  │  │
│  │  │  ├─ MCP 工具代理                                  │  │  │
│  │  │  ├─ 指数退避重启 (1s→60s, max 5)                  │  │  │
│  │  │  └─ macOS TCC 权限检测                            │  │  │
│  │  └──────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
│       │                                                      │
│       ▼                                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  Argus 核心 (C++/Rust 混合, macOS App Bundle)          │  │
│  │  ├─ 屏幕捕获 (Screen Recording API)                    │  │
│  │  ├─ 视觉分析 (元素识别 + 场景描述)                      │  │
│  │  ├─ 鼠标键盘操控 (Accessibility API)                    │  │
│  │  └─ OCR 文本提取                                       │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

工具集

灵瞳提供两类工具——感知工具（只读观察）和交互工具（实际操控）：

感知工具（低风险，自动放行）

工具	说明	典型用途
`argus_capture_screen`	截取当前屏幕	获取桌面状态快照
`argus_describe_scene`	描述屏幕内容	理解当前界面布局和状态
`argus_locate_element`	定位 UI 元素	找到按钮、输入框、菜单项的位置
`argus_read_text`	OCR 文本提取	读取屏幕上的文字内容

交互工具（需审批确认）

工具	风险等级	说明
`argus_click`	中	点击指定屏幕坐标
`argus_double_click`	中	双击指定坐标
`argus_type_text`	中	在当前焦点位置输入文本
`argus_scroll`	低	滚动页面
`argus_open_url`	高	打开 URL（NoNetwork 合约可阻断）
`argus_run_shell`	高	执行 Shell 命令（NoSpawn 合约可阻断）

主智能体直接可用

argus_capture_screen 是唯一保留给主智能体直接调用的灵瞳工具——简单截屏无需启动完整子智能体。其余工具仅在灵瞳子智能体会话内可用。

与浏览器工具的区别

维度	Browser 工具	灵瞳 (Argus)
操控对象	浏览器内网页	任意桌面应用
操控方式	CDP 协议 + DOM/ARIA	屏幕坐标 + Accessibility API
精确度	像素级精确（基于 DOM 元素）	视觉定位（依赖截图分析）
适用场景	Web 自动化（网页表单、爬虫）	桌面应用（IDE、设计工具、系统设置）
性能	更快（直接 CDP 通信）	稍慢（需截图→分析→操控）
依赖	Chrome/Brave/Edge	macOS Accessibility + TCC

选择策略：Web 自动化优先用 Browser（更快更精确），桌面应用/跨应用场景用灵瞳。两者可在同一任务中组合使用。

macOS 深度集成

TCC 权限框架

灵瞳在 macOS 上需要两项系统权限：

权限	用途	TCC 名称
Screen Recording	屏幕截图和内容捕获	`kTCCServiceScreenCapture`
Accessibility	鼠标键盘操控和 UI 元素访问	`kTCCServiceAccessibility`

自动代码签名

裸二进制需要 codesign 才能获得 TCC 权限。灵瞳通过 EnsureCodeSigned() 自动完成签名：

检查二进制是否已签名
未签名则使用 codesign --force --sign - 自动签名
确保权限在系统重启后仍然持久化

Sequoia 月度重授权检测

macOS Sequoia (15+) 引入了屏幕录制权限的月度重新授权机制：

灵瞳读取 ScreenCaptureApprovals.plist 计算到期天数
距过期 <=5 天时主动预警
argus.permission.check RPC 供前端查询权限状态和恢复指引

独立模型配置

灵瞳拥有完全独立的 LLM 模型配置，不与主智能体或其他子智能体共享：

json

{
  "subAgents": {
    "screenObserver": {
      "provider": "anthropic",
      "model": "claude-sonnet-4",
      "apiKey": "sk-...",
      "baseUrl": "",
      "enabled": true,
      "intervalMs": 1000,
      "changeThreshold": 0.02
    }
  }
}
{
  "subAgents": {
    "screenObserver": {
      "provider": "anthropic",
      "model": "claude-sonnet-4",
      "apiKey": "sk-...",
      "baseUrl": "",
      "enabled": true,
      "intervalMs": 1000,
      "changeThreshold": 0.02
    }
  }
}

三级 Fallback：

subAgents.screenObserver 显式配置（最高优先级）
agents.defaults.model.primary（主 agent 默认模型）
硬编码默认值（anthropic/claude-sonnet-4）

二进制发现机制

灵瞳核心是独立的 C++/Rust 二进制，通过 4 级优先级发现：

优先级	来源	说明
1	`$ARGUS_BINARY_PATH` 环境变量	开发/调试用
2	`.app bundle` 内嵌	macOS App 打包场景
3	`~/.crabclaw/bin/argus`	用户安装目录
4	`PATH` 系统路径	`exec.LookPath` 查找

发现后进行三重校验：存在性 + 可执行权限 + 非目录检查。

故障恢复

机制	说明
启动失败保留	Start() 失败后保留 bridge 实例，允许前端 UI 重试
进程监控重启	指数退避（1s→60s），最多重启 5 次
快速崩溃熔断	60s 内崩溃 3 次触发熔断，停止重启
结构化错误	ArgusStartError 包含 Phase/Reason/Recovery 字段
状态广播	`argus.status.changed` 事件实时广播到前端
并发安全	RWMutex 保护 bridge 实例的读写访问

使用示例

在聊天中自然语言使用灵瞳：

shell

> 截取当前桌面截图
> 帮我在 Figma 中找到"导出"按钮并点击
> 读取 Xcode 控制台中的错误信息
> 在系统偏好设置中切换暗色模式
> 帮我操作 Sketch 调整这个图标的大小
> 截取当前桌面截图
> 帮我在 Figma 中找到"导出"按钮并点击
> 读取 Xcode 控制台中的错误信息
> 在系统偏好设置中切换暗色模式
> 帮我操作 Sketch 调整这个图标的大小

灵瞳的 AI 会自动执行：截屏 → 理解界面 → 定位元素 → 执行操控 → 验证结果。

相关文档：浏览器自动化 · 编程子智能体 · 能力树与权限 · 安全与审批