omni-vu

omni.vu - 视觉理解与自动化

概述

omni.vu 让你能够查看和操作用户的 macOS 屏幕。你可以用它来：

• 查看用户看到的内容（屏幕捕获）
• 理解 AI 视觉识别的 UI 状态
• 检测变化并等待事件
• 操作鼠标和键盘

何时使用此技能

以下情况应主动使用 omni.vu：

1. 调试 UI 问题——“按钮没反应”→ 捕获并分析
2. 验证更改——修改 UI 代码后，检查渲染是否正确
3. 等待操作完成——构建结束、部署完成、测试运行
4. 了解上下文——用户描述你看不到的屏幕内容
5. 自动化重复任务——点击 UI 流程、填写表单
6. 编写文档——捕获功能截图

以下情况不要使用：

• 读取或写入文件（使用 Read/Write 工具）
• 运行终端命令（使用 Bash）
• 发起 API 调用（使用适当的工具）
• 用户尚未授予屏幕录制权限

工具参考

捕获工具

vu - 全屏捕获

vu(monitor=0, save_to_history=True)

捕获整个屏幕。返回 base64 图像。

使用场景：需要查看屏幕上的所有内容时。

vu_window - 窗口捕获

vu_window(window_id=None, title="VS Code", include_frame=False)

按 ID 或标题（部分匹配）捕获指定窗口。

使用场景：只需要查看某个应用的内容时。

工作流：

1. 调用 vu_list_windows 查看可用窗口
2. 找到 window_id，或使用标题匹配
3. 使用该 ID/标题调用 vu_window

vu_region - 区域捕获

vu_region(x=100, y=100, width=500, height=300)

捕获屏幕上的指定矩形区域。

使用场景：需要精确区域（错误消息、特定组件）时。

vu_list_windows - 列出窗口

vu_list_windows(filter_app="Chrome")

列出所有可见窗口及其元数据。

返回：{window_id, title, owner, x, y, width, height} 列表

vu_list_monitors - 列出显示器

vu_list_monitors()

列出已连接的显示器及其分辨率和缩放系数。

视觉工具

vu_describe - AI 视觉分析

vu_describe(
    prompt="What errors are visible?",
    provider="claude",  # or openai, gemini, ollama
    max_tokens=1024,
    capture_first=True
)

捕获屏幕并使用 AI 进行分析。

推荐提示词：

• “描述屏幕上看到的内容”
• “是否有可见的错误消息？”
• “构建/测试输出是什么状态？”
• “登录表单是否已正确填写？”
• “状态指示灯是什么颜色？”

提供商：

提供商	速度	质量	成本
claude	中等	优秀	$$
openai	快	很好	$$
gemini	快	良好	$
ollama	慢	不定	免费

实用工具

vu_diff - 变化检测

vu_diff(threshold=0.02, monitor=0)

检测屏幕自上次捕获后是否发生变化。

返回：{changed: bool, diff_percentage: float}

用于轮询模式：

# Wait for build to finish
while True:
    result = vu_diff(threshold=0.05)
    if result["changed"]:
        # Screen changed, check what happened
        analysis = vu_describe(prompt="Did the build succeed or fail?")
        break
    # Wait before checking again

vu_history - 捕获历史记录

vu_history(limit=10, capture_type="full_screen")

获取最近捕获的元数据。

vu_last - 上次捕获

vu_last()

返回最近一次捕获及其图像数据。

使用场景：需要重新分析但无需重新捕获时。

vu_status - 系统状态

vu_status()

返回系统信息：显示器、提供商、安全设置。

自动化工具

vu_click - 鼠标点击

vu_click(x=500, y=300, button="left", count=1)

在屏幕坐标处点击。

按钮：left、right、middle 次数：1（单击）、2（双击）、3（三击）

安全性：会根据屏幕边界验证坐标。

vu_move - 移动光标

vu_move(x=500, y=300, duration_ms=0)

将光标移动到指定位置。使用 duration_ms 设置动画移动。

vu_drag - 拖动操作

vu_drag(start_x=100, start_y=100, end_x=500, end_y=300, duration_ms=500)

从起始位置拖动到结束位置。

安全性：拖动距离最多为 2000px。

vu_scroll - 滚动

vu_scroll(direction="down", amount=3, x=None, y=None)

在当前位置或指定位置滚动。

方向：up、down、left、right 数量：滚动行数（1-20）

vu_type - 输入文本

vu_type(text="Hello World", delay_between_ms=0)

逐字输入文本。

注意：请先点击目标字段！

vu_hotkey - 键盘快捷键

vu_hotkey(keys="cmd+s")

执行键盘快捷键。

格式：modifier+key（例如，cmd+c、ctrl+shift+s、cmd+opt+i） 修饰键：cmd、ctrl、alt/opt、shift

被屏蔽的快捷键（出于安全考虑）：

• cmd+q（退出）
• cmd+shift+q（注销）
• cmd+opt+esc（强制退出）

常见工作流

1. 调试 UI 问题

User: "The submit button doesn't do anything when I click it"

1. vu_describe(prompt="Describe the form and submit button state")
2. Analyze: Is button disabled? Is there validation error?
3. If needed: vu_window(title="Chrome") for focused capture
4. Check console: vu_describe(prompt="Are there any errors in the developer console?")

2. 验证构建/部署

User: "Run the build and let me know when it's done"

1. Run: npm run build (via Bash)
2. Loop: vu_diff(threshold=0.05)
3. When changed: vu_describe(prompt="What is the build status? Did it succeed or fail?")
4. Report result

3. 填写表单

User: "Fill out the registration form with test data"

1. vu_describe(prompt="What form fields are visible?")
2. vu_click(x=field_x, y=field_y)  # Click first field
3. vu_type(text="[email protected]")
4. vu_hotkey(keys="tab")  # Move to next field
5. vu_type(text="Test User")
6. Continue for each field...
7. vu_click(x=submit_x, y=submit_y)  # Submit
8. vu_describe(prompt="Was the form submitted successfully?")

4. 浏览 UI

User: "Open the settings panel in VS Code"

1. vu_list_windows(filter_app="Code")
2. vu_window(title="Code")  # Capture VS Code
3. vu_hotkey(keys="cmd+,")  # Open settings
4. vu_diff()  # Wait for settings to open
5. vu_describe(prompt="Are the VS Code settings now visible?")

5. 监控变化

User: "Watch the dashboard and tell me when the status changes"

1. vu()  # Initial capture
2. Loop every 5 seconds:
   - vu_diff(threshold=0.02)
   - If changed: vu_describe(prompt="What changed on the dashboard?")
3. Report changes to user

最佳实践

1. 操作前先捕获

点击或输入前，始终先捕获并分析：

❌ Bad: vu_click(x=500, y=300)  # Hope it's the right spot

✅ Good:
1. vu_describe(prompt="Where is the submit button?")
2. Parse coordinates from description
3. vu_click(x=parsed_x, y=parsed_y)

2. 使用合适的捕获范围

Full screen → General context, multi-app workflows
Window → Single app focus, cleaner output
Region → Specific element, faster/smaller

3. 使用具体的视觉提示词

❌ Vague: "What do you see?"

✅ Specific:
- "Is there an error message visible? If so, what does it say?"
- "What is the status of the test runner? Passing, failing, or running?"
- "List all form fields visible and their current values"

4. 限制自动化频率

不要频繁点击。操作之间稍作等待：

vu_click(x=100, y=100)
# Wait for UI response
vu_diff(threshold=0.01)
vu_click(x=200, y=200)

5. 操作后进行验证

始终验证自动化操作是否成功：

vu_type(text="[email protected]")
vu_describe(prompt="What text is now in the email field?")

故障排除

“权限被拒绝”或捕获结果为空

→ 授予屏幕录制权限：System Settings > Privacy > Screen Recording

自动化无法正常工作

→ 授予辅助功能权限：System Settings > Privacy > Accessibility

视觉分析失败

→ 检查环境变量中的 API 密钥 → 尝试其他提供商：vu_describe(provider="openai")

坐标似乎不正确

→ 使用了 Retina 显示屏？坐标使用逻辑点，而非像素 → 使用了多显示器？通过 vu_list_monitors() 检查显示器排列

快捷键被屏蔽

→ 出于安全考虑，某些危险快捷键（如 cmd+q）会被屏蔽 → 如确有必要，可在配置中取消屏蔽

配置

环境变量：

OMNI_VU_ANTHROPIC_API_KEY=sk-ant-...    # For Claude vision
OMNI_VU_OPENAI_API_KEY=sk-...           # For GPT-4 vision
OMNI_VU_DEFAULT_PROVIDER=claude          # Default AI provider
OMNI_VU_SAFETY_LEVEL=medium              # low/medium/high

历史记录存储位置：~/.omni.vu/captures/