1. 项目定位与用途
Ghost OS 是一个原生 macOS 命令行工具，定位为 AI 代理的“眼睛和双手”。它通过系统级集成，使任何连接 MCP 协议的 AI 代理（如 Claude）能够直接操作 Mac 上的图形界面，将 AI 从文本交互扩展到完整的计算机使用能力。项目与 Shadow（提供记忆与智能）和 Specter（提供持久化部署）共同构成完整的 AI 代理生态系统，实现从感知、记忆到执行的闭环。
项目档案命令行工具
Ghost OS - macOS AI 代理图形界面操作工具：完整计算机使用能力、自学习食谱与 MCP 集成
ghostwright/ghost-os：Ghost OS 是 macOS 命令行工具，为 AI 代理提供完整的图形界面操作能力，使其能感知、操控任意应用程序，无需截图或视觉模型。本页整理它解决什么问题、适用场景、安装方式和使用方法。
AI 总结
Ghost OS 是 macOS 命令行工具，为 AI 代理提供完整的图形界面操作能力，使其能感知、操控任意应用程序，无需截图或视觉模型。
中文项目介绍
Ghost OS 是专为 AI 代理设计的 macOS 系统级工具，解决 AI 无法与图形用户界面交互的核心问题。它通过 CGEvent tap 和辅助功能 API，让 AI 能够“看见”界面元素并执行点击、输入等操作，无需依赖截图或视觉模型推理。项目采用模块化架构，包含感知、操作、学习、食谱管理等核心模块，支持 20+ MCP 工具和自学习食谱功能。用户可录制操作序列生成可复现的自动化流程，适用于邮件发送、跨应用工作流、数据采集等多种场景。安装需 macOS 14+、Swift 6.2 环境及输入监控权限，通过 ghost setup 完成配置。
详细信息与使用说明
2. 解决的问题
传统 AI 代理受限于文本交互，无法执行点击按钮、填写表单、切换应用等 GUI 操作。Ghost OS 通过 macOS 辅助功能 API 和 CGEvent tap 技术，直接捕获和注入系统事件，结合辅助功能树解析界面结构，使 AI 能够理解界面元素并执行精确操作，且无需截图或视觉模型推理，大幅降低延迟和计算复杂度。
3. 适用场景
主要适用场景包括：自动化办公（发送邮件、处理文档、管理日历等重复性任务）；跨应用工作流（在 Finder、Slack、浏览器间执行多步骤操作）；数据采集（从网页和应用程序中提取结构化信息）；软件测试（自动执行 GUI 测试场景并验证结果）；个人助理（执行日常计算机操作如文件管理、消息发送等）。仓库中示例食谱涵盖 gmail-send、arxiv-download、slack-send、finder-create-folder 等。
4. 安装方式
根据仓库信息，安装需满足：macOS 14 或更高版本、Swift 6.2 环境。关键步骤为在系统设置中授予 Input Monitoring 权限（隐私与安全 > 输入监控），然后运行 ghost setup 命令完成配置向导。该命令将配置权限、MCP 设置、食谱安装及自检。仓库未明确给出详细的 Swift 安装步骤或二进制下载方式，也未提供独立于 MCP 的命令行使用示例。
5. 使用方式
Ghost OS 主要通过 MCP 协议与 AI 代理集成。使用预定义食谱执行任务：ghost_run recipe:"gmail-send" params:{recipient, subject, body}。创建自定义食谱：ghost_learn_start 开始录制，手动操作后 ghost_learn_stop 停止，系统自动合成参数化食谱并保存。可直接调用感知工具（context、state、find、read、inspect、element_at）解析界面，或操作工具（click、type、press、hotkey、scroll、annotate、hover）执行动作。所有工具需在 MCP 服务器运行时通过 AI 代理调用。
6. 补充说明与实现特点
项目采用模块化 Swift 架构，核心模块包括：Actions（GUI 操作与焦点管理）、Learning（操作录制与食谱合成）、MCP（协议服务器与工具调度）、Perception（界面解析）、Recipes（食谱存储与执行）、Screenshot（多显示器捕获）、Vision（可选视觉模型集成，通过 vision-sidecar 的 Python 服务实现）。v2 版本已通过 extensive 测试，20/20 MCP 工具功能正常，gmail-send、arxiv-download 等食谱测试成功。自学习功能通过 CGEvent tap 捕获操作并合成参数化食谱，无需视觉模型。
思维导图
Ghost OS
核心能力
GUI 感知与操作
MCP 协议集成
自学习食谱
技术架构
Actions 模块
Learning 模块
MCP 模块
Perception 模块
Recipes 模块
Screenshot 模块
Vision 模块
生态项目
Shadow（记忆）
Specter（部署）
使用方式
预定义食谱
自定义录制
工具调用
系统要求
macOS 14+
Swift 6.2
Input Monitoring 权限
常见问题
Ghost OS 是否需要视觉模型或截图？
不需要。Ghost OS 通过 CGEvent tap 和辅助功能树解析界面，直接获取元素信息和操作，无需视觉推理，降低延迟和计算复杂度。
支持哪些 macOS 版本和 AI 代理？
需 macOS 14 或更高版本。通过 MCP 协议兼容任何支持 MCP 的 AI 代理，如 Claude Code。仓库中明确标注平台为 macOS 14+，Swift 6.2，MCP 兼容。
如何创建自定义自动化流程？
使用 ghost_learn_start 开始录制，手动执行任务后 ghost_learn_stop 停止，系统会自动合成参数化食谱并保存，后续可通过 ghost_run 调用。录制过程通过 CGEvent tap 捕获操作并辅以辅助功能树上下文。
安装需要哪些权限？
必须在系统设置中授予 Input Monitoring 权限（隐私与安全 > 输入监控），以便捕获和注入键盘鼠标事件。运行 ghost setup 命令将引导完成权限配置。
Ghost OS 与 Shadow、Specter 的关系？
Ghost OS 提供 GUI 操作能力（眼睛和双手）；Shadow 提供记忆和智能（14 模态捕获、本地 LLM、建议生成）；Specter 提供持久化部署（VM、DNS、TLS、TUI 仪表盘）。三者共同构成完整 AI 代理生态，可独立或组合使用。