MacPilot
adeelahmad/MacPilot加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下这样的场景：周一早晨，你一边喝着咖啡，一边对着终端随口说一句"帮我打开 Chrome，搜索最新的 Python 教程，然后把所有结果保存到桌面"。你的 Mac 像一位贴心的私人助理，准确无误地完成了这一切——这就是 MacPilot 正在努力实现的事情。
MacPilot 是一个将 GPT 大语言模型与 macOS 原生系统能力深度融合的 UI 自动化框架。与传统的脚本式自动化（如 AppleScript、Automator）不同，它允许用户用自然语言（英文）描述想要的操作，系统自动理解意图、规划步骤、执行动作，全程无需编写任何代码。
macOS 拥有业界最成熟的原生自动化体系——AppleScript 自 1993 年起就是 macOS 的脚本引擎，Accessibility API 赋予了应用读取和控制 UI 的能力，Vision Framework 则提供了强大的 OCR 和图像识别能力。然而，这套体系长期存在两个核心痛点：
第一，门槛高。 AppleScript 语法独特，学习曲线陡峭；Accessibility API 需要编写 Objective-C/Swift 代码，普通用户难以触及。
第二，缺乏智能。 传统自动化本质上是"死板的指令执行"——用户必须精确告诉系统点击哪个按钮、输入什么文字。一旦界面稍有变化，整个脚本就会失效。
近年来，随着 LLM（大型语言模型）能力的爆发，业内出现了多个将自然语言引入自动化的尝试：OpenAI 的 GPT-4V 具备视觉理解能力，Anthropic 的 Claude Code 能操作终端，GitHub Copilot 可以在 IDE 中辅助编程。但专注于 macOS 桌面 UI 自动化 + 自然语言指令 这一交叉领域的产品化开源项目，MacPilot 是少数有完整架构设计的之一。
MacPilot 的架构采用经典的分层设计，自上而下分为三层：
最上层：自然语言理解层。 用户输入的英文指令首先经过 GPT 分析，拆解为结构化的操作意图（Action Plan）。这一层利用 OpenAI API（支持 GPT-4、GPT-4o 等多模态模型），将模糊的日常语言转化为精确的操作步骤。
中间层：Actor 执行系统。 MacPilot 内部实现了 Actor 模式（借鉴自分布式系统设计），将每一个操作封装为独立的 Actor。每个 Actor 负责一种具体能力——比如 ClickActor 负责点击，TypeActor 负责输入文字，NavigateActor 负责菜单导航。GPT 生成的 Action Plan 会路由到具体的 Actor 执行。
最底层：系统交互层。 Actor 通过 pyobjc 框架调用 macOS 原生能力：
此外，项目还集成了 SQLAlchemy + Alembic 做状态持久化（记录 UI 状态快照，支持错误恢复），使用 Pydantic v2 做输入输出校验，Rich 做终端富文本输出，Click 做 CLI 界面。
from macpilot import MacPilot
import asyncio
async def main():
pilot = MacPilot()
# 一句英文，GPT 解析，自动拆解并执行
await pilot.execute("Open Chrome and search for 'Python tutorials'")
asyncio.run(main())
这个看似简单的调用背后，GPT 会先分析意图（"打开 Chrome" + "搜索内容"），然后规划步骤（启动应用 → 等待窗口出现 → 定位搜索框 → 输入文字 → 回车），最后由 Actor 系统按顺序执行。
complex_workflow = """
1. Find all PDFs in Downloads
2. Create a folder named Documents
3. Move PDFs older than 30 days
4. Create a summary spreadsheet
"""
await pilot.execute(complex_workflow)
GPT 自动识别这是一个包含条件判断（文件年龄）、文件操作和多步骤串行的复杂任务，并生成对应的执行计划。
MacPilot 提供了类似"宏录制"的 Pattern 注册机制：
from macpilot.patterns import register_pattern
@register_pattern("login_flow")
async def handle_login(username: str, password: str):
return [
{"action": "click", "target": "username_field"},
{"action": "type", "text": username},
{"action": "click", "target": "password_field"},
{"action": "type", "text": password},
{"action": "click", "target": "login_button"}
]
Pattern 可以参数化，支持复杂的登录、填表等高频操作复用。
多模态感知能力。 通过 pyobjc-framework-Vision 调用 Apple Vision，MacPilot 可以"看见"屏幕上的 UI 元素——不仅能识别文字（OCR），还能检测按钮、输入框等控件的位置，实现类似 GPT-4V 的视觉理解能力。这在处理非标准界面（第三方应用、自定义控件）时尤为重要。
自愈机制（Self-healing）。 传统的 UI 自动化一旦界面变化就完全失效。MacPilot 引入了错误恢复机制：当某一步操作失败时，系统会重新"观察"当前界面，让 GPT 分析失败原因并尝试替代方案。
Actor 架构的解耦性。 每个 Actor 独立负责一种操作，新增操作类型只需实现新的 Actor，无需修改核心逻辑。这使得项目具备良好的可扩展性。
平台锁定严重。 这是 macOS 专属项目，核心依赖 pyobjc 系列库完全无法在 Linux/Windows 上运行。即便尝试 Docker 化也几乎不可能——pyobjc 依赖 macOS 内核的 Objective-C 运行时，属于系统级绑定。
OpenAI API 成本。 每次指令解析都需要调用 GPT-4o 等大模型，在高频使用场景下 Token 消耗不可忽视。虽然 README 提到 Roadmap 中将支持本地 LLM，但目前阶段完全依赖云端 API。
稳定性与可靠性。 UI 自动化本身对界面一致性高度敏感，不同 macOS 版本、不同 DPI 缩放、不同主题都可能影响识别准确率。README 中 RoadMap 明确列出了"improved error recovery"和"performance optimizations"作为高优先级任务，说明当前版本在这方面仍有提升空间。
无许可证。 项目仓库中没有 LICENSE 文件，意味着默认版权保留，不允许自由使用和分发。这是一个重要的法律风险，使用前需要联系作者获取明确授权。
安装方式通过 pip 或源码安装：
pip install macpilot
# 或
git clone https://github.com/adeelahmad/macpilot.git
cd macpilot
pip install -e .
运行时依赖较多：需要 macOS 12.0+、Python 3.9+、Homebrew，以及手动开启 Accessibility 权限（系统设置 → 隐私与安全性 → 辅助功能）和屏幕录制权限（系统设置 → 隐私与安全性 → 屏幕录制）。这些权限是 macOS 自动化操作的必要前提。
使用体验上，对于有 Python 基础的开发者，API 设计友好（async/await + Pydantic 校验），代码可读性高。但对于完全没有编程背景的普通用户，仅靠"输入英文指令"的体验尚未达到开箱即用的程度——README RoadMap 中明确规划了 Web Dashboard 和 Visual Workflow Builder，这些才是降低使用门槛的关键。
MacPilot 的出现填补了一个真实存在的需求空白：用自然语言操控 macOS 桌面。它的价值不仅在于让普通用户"免代码自动化"，更在于展示了 GPT 与 macOS 原生能力深度结合的可能性——Vision Framework 的视觉感知 + GPT 的语义理解 + Accessibility API 的操控能力，这三者的结合是 macOS 平台独有的优势组合。
从项目现状看，MacPilot 仍处于早期阶段（v0.1.0），代码覆盖测试已有框架但完整度待验证，文档中 RoadMap 占据大量篇幅说明很多能力还是"规划中"而非"已实现"。但其架构设计清晰，技术选型合理（async Python + Actor 模式 + Pydantic），随着本地 LLM 支持和 Visual Builder 的落地，有望成为 macOS AI 自动化领域的标杆项目。
对于有 macOS 自动化需求的开发者（UI 测试、RPA 场景、桌面工具构建），MacPilot 是值得关注和研究的方向；但对于普通用户，建议等待其 Web UI 上线后再尝试——目前阶段仍属于"开发者预览版"。