macOS Desktop Controller v2 - macOS 14 兼容版

基于 Python + AppleScript 的 macOS 14 兼容桌面自动化控制器，提供稳定可靠的 UI 自动化能力。

🏗️ 架构设计

┌──────────────────────────────┐
│        用户触发层/接口        │
│  - Terminal CLI / 界面        │
│  - Chatbot/数字人接口         │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│         调度 & 核心 Agent      │
│  - Action Queue / Task Manager │
│  - Skill Dispatcher            │
│  - 状态 & 超时管理              │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│       技能模块层 (Skills)      │
│  - app_control_skill          │
│  - click_skill / drag_skill   │
│  - vision_skill               │
│  - workflow_skill             │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        系统执行层 (Executor)   │
│  - Python + PyAutoGUI         │
│  - AppleScript / Automator    │
│  - subprocess 调用 / CLI      │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        macOS 14 系统层         │
│  - Accessibility / UI Events  │
│  - Screen Capture / Permissions│
└──────────────────────────────┘

🎯 功能特性

🔧 核心技能模块

1. app_control_skill - 应用控制

• 启动/关闭应用：精确控制应用的启动、关闭、重启
• 窗口管理：移动、调整大小、最小化、最大化窗口
• 应用切换：在不同应用间快速切换
• 状态监控：检查应用运行状态和窗口信息

2. click_skill - 精确交互

• 点击操作：基于坐标、元素ID或视觉识别的精确点击
• 输入控制：键盘输入、热键组合、文本输入
• 拖拽操作：元素间的拖拽、文件拖拽
• 滚动控制：平滑滚动，支持不同方向和速度

3. vision_skill - 视觉控制

• 屏幕截图：全屏、窗口、指定区域的截图
• 视觉识别：基于截图的元素识别和分析
• 模板匹配：使用 OpenCV 进行精确的图像匹配
• 实时监控：桌面状态的实时监控和分析

4. workflow_skill - 工作流管理

• 任务串联：多任务串联，执行完整工作流
• 条件判断：基于视觉或状态的条件分支
• 循环控制：重复执行的任务循环
• 错误处理：完善的错误处理和重试机制

🛠️ 安装要求

系统要求

• macOS 14.x (兼容性验证)
• Python 3.8+
• pip 包管理器

依赖安装

# 基础依赖
pip install pyautogui opencv-python numpy pillow

# 可选依赖（增强功能）
pip install pyobjc-framework-Cocoa pyobjc-framework-Quartz

macOS 权限设置

系统设置 → 隐私与安全性
✅ 辅助功能（控制鼠标键盘）
✅ 屏幕录制（截图识别）
✅ 自动化（控制 Safari / Finder / App）

📖 使用示例

基本应用控制

from macos_desktop_controller import app_control

# 启动应用
app_control.open_app("Safari")

# 激活窗口
app_control.activate_window("Safari")

# 关闭应用
app_control.close_app("Safari")

精确交互操作

from macos_desktop_controller import click_control

# 坐标点击
click_control.click_at(500, 300)

# 文本输入
click_control.write_text("Hello World", interval=0.05)

# 拖拽操作
click_control.drag_from_to(100, 100, 500, 500, duration=1.0)

视觉识别操作

from macos_desktop_controller import vision_control

# 截图分析
screen = vision_control.capture_screen()

# 模板匹配
position = vision_control.find_template("target.png", threshold=0.8)
if position:
    click_control.click_at(position[0], position[1])

工作流执行

from macos_desktop_controller import workflow

# 定义工作流
workflow_steps = [
    {"action": "open_app", "params": {"app_name": "Safari"}},
    {"action": "wait", "params": {"duration": 2}},
    {"action": "click_template", "params": {"template": "search_bar.png"}},
    {"action": "write_text", "params": {"text": "macOS automation"}},
    {"action": "press_key", "params": {"key": "enter"}},
]

# 执行工作流
workflow.execute_steps(workflow_steps)

⚙️ 配置选项

配置文件 (config.json)

{
    "default_timeout": 30,
    "retry_count": 3,
    "screenshot_dir": "/tmp/screenshots",
    "template_dir": "/tmp/templates",
    "log_level": "INFO",
    "automation_delay": 1.0,
    "mouse_speed": 0.5,
    "keyboard_delay": 0.05
}

环境变量

export MACOS_CONTROLLER_LOG_LEVEL=INFO
export MACOS_CONTROLLER_SCREENSHOT_DIR=/tmp/screenshots
export MACOS_CONTROLLER_TEMPLATE_DIR=/tmp/templates

🎨 高级功能

1. 智能等待

# 等待元素出现
position = vision_control.wait_for_template("login_button.png", timeout=30)
if position:
    click_control.click_at(position[0], position[1])

# 等待应用激活
app_control.wait_for_app_active("Safari", timeout=10)

2. 批量操作

# 批量点击多个位置
positions = [(100, 100), (200, 200), (300, 300)]
for pos in positions:
    click_control.click_at(pos[0], pos[1])
    time.sleep(0.5)

3. 条件执行

# 条件判断
if vision_control.find_template("error_dialog.png"):
    # 处理错误
    click_control.click_template("ok_button.png")
else:
    # 正常执行
    click_control.write_text("Success")

🔧 故障排除

常见问题

1. 权限问题

# 检查辅助功能权限
osascript -e 'tell application "System Events" to get the name of every process whose background only is false'

# 添加到辅助功能白名单
sudo spctl --add /path/to/your/script

2. 图像识别失败

# 调试截图
vision_control.capture_screen("/tmp/debug.png")

# 调整阈值
position = vision_control.find_template("target.png", threshold=0.6)

3. 应用控制问题

# 检查应用状态
if app_control.is_app_running("Safari"):
    print("Safari is running")
else:
    print("Safari is not running")

调试模式

import logging
logging.basicConfig(level=logging.DEBUG)

# 启用调试模式
from macos_desktop_controller import set_debug_mode
set_debug_mode(True)

📊 性能优化

1. 缓存机制

# 启用截图缓存
vision_control.enable_cache(True)

# 设置缓存过期时间
vision_control.set_cache_timeout(5.0)

2. 批量处理

# 批量截图
screenshots = vision_control.capture_multiple_screens(["screen1", "screen2"])

# 批量模板匹配
results = vision_control.batch_find_templates(["template1.png", "template2.png"])

🔄 更新日志

v2.0.0 (2026-06-09)

• ✅ 完全重构为模块化架构
• ✅ 支持 macOS 14.x 兼容性
• ✅ 新增视觉识别模块
• ✅ 新增工作流管理
• ✅ 完善的错误处理机制
• ✅ 详细的日志记录

v1.0.0 (2026-06-08)

• ✅ 基础应用控制功能
• ✅ 鼠标键盘控制
• ✅ 基础截图功能

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📞 支持

• 📧 Email: support@example.com
• 🐛 Issues: GitHub Issues
• 📖 文档: 项目 Wiki

此技能专为 macOS 14.x 设计，提供稳定可靠的桌面自动化能力。使用前请确保已正确配置所有依赖项和系统权限。