EXTRA - Native Computer Use

---

什么是 Extra？它为何存在？

Extra 是由 yantraOS 开发的开源计算机使用协议和模型上下文协议（MCP）服务。它将大模型（包括 ChatGPT、Claude、Cursor 和 Gemini）直接连接到 Linux、macOS 和 Windows 上的实体桌面操作系统。Extra 用原生操作系统辅助功能树和低于 3 毫秒的 GPU 帧流，取代脆弱的纯视觉截图循环，实现像素级精准点击、即时输入，并将令牌成本降低多达 225 倍。

如今的 AI 助手可以写出精彩的文章和代码，却被困在聊天窗口里。当你需要它们点击按钮、打开应用、整理文件或在电子表格中输入数据时，它们只能给你文字说明。

Extra 让你的 AI 在 Linux、macOS 和 Windows 上拥有双手和双眼。

它将 Claude、Google Antigravity、Cursor、AGY 或任何自主 Agent 直接连接到你的桌面，提供高速屏幕视觉、像素级精准点击和即时输入。

• 无需笨重的浏览器扩展。
• 无需昂贵的云服务监视你的屏幕。
• 100% 开源、本地运行且保护隐私。

---

AI 助手能用 Extra 做什么？

Extra 运行后，你可以像和坐在桌边的真人助手交谈一样与 AI 交流：

• 📊 电子表格与数据： “打开 Excel 或 LibreOffice Calc，计算 Downloads 文件夹中发票 CSV 文件的总收入，并创建汇总图表。”
• 🗂️ 桌面与文件整理： “整理杂乱的桌面：将屏幕截图移到 Pictures，将 PDF 移到 Documents，并删除空文件夹。”
• 🌐 网络研究与数据录入： “打开 Chrome 或 Firefox，查找 5 个最便宜的东京航班，价格低于 800 美元，并将航班号和日期复制到文本便笺中。”
• ⚙️ 系统管理： “打开设置或终端，检查系统更新并确认服务运行正常。”
• 🎵 应用控制： “启动 Spotify 或 VLC，搜索低保真专注节拍音乐并开始播放。”

---

⚡ 快速入门（1 分钟）

你可以在 Linux、macOS 或 Windows 上几秒内完成 Extra 的设置：

选项 A：让你的 AI 帮你设置（主要方式——最简单）

将适用于你操作系统的单条指令复制并粘贴到 Claude Desktop、Google Antigravity、Cursor、Windsurf 或任意 MCP Agent 中：

• 🐧 适用于 Linux（Arch / yantraOS、Ubuntu、Debian、Fedora）：

  Setup Extra on my Linux machine: In Terminal run 'curl -sSL https://extra.yantraos.com/install.sh | bash', then read and configure ~/.extra/app/STARTER_PROMPT_LINUX.md so we are ready to use Extra.
  

• 🍏 适用于 macOS（Apple Silicon M1-M4 和 Intel）：

  Setup Extra on my Mac: In Terminal run 'curl -sSL https://extra.yantraos.com/install.sh | bash', then read and configure ~/.extra/app/STARTER_PROMPT_MACOS.md so we are ready to use Extra.
  

• 🪟 适用于 Windows（11 / 10）：

  Setup Extra on my PC: In PowerShell run 'iwr -useb https://extra.yantraos.com/install.ps1 -OutFile "$env:TEMP\install_extra.ps1"; & "$env:TEMP\install_extra.ps1"', then read and configure ~/.extra/app/STARTER_PROMPT.md so we are ready to use Extra.
  

你的 AI 将运行安装程序、配置 MCP 和本地规则，并回复：

“准备就绪！请重启 <你的 AI 应用，例如 Claude Desktop、Antigravity、Cursor、Windsurf> 以使其生效。”

---

选项 B：自行运行一行命令

• 🐧 Linux 终端（Arch / yantraOS、Ubuntu、Debian、Fedora）：

  curl -sSL https://extra.yantraos.com/install.sh | bash
  

• 🍏 macOS 终端：

  curl -sSL https://extra.yantraos.com/install.sh | bash
  

• 🪟 Windows PowerShell（分阶段执行，通过 Defender 检查）：

  iwr -useb https://extra.yantraos.com/install.ps1 -OutFile "$env:TEMP\install_extra.ps1"; & "$env:TEMP\install_extra.ps1"
  

自动安装程序将：

• 验证操作系统架构（Linux Wayland/X11、macOS 12.3+ 或 Windows 10/11 64 位）。
• 配置隔离的 Python 3.10+ 运行环境（~/.extra/venv）。
• 自动配置 Claude Desktop、Cursor、Windsurf 和 Antigravity（agy）。
• 运行健康诊断工具，并提供一步式入门提示词。

---

选项 C：开发者 Git 克隆

# Linux / macOS:
git clone https://github.com/AIYantra/extra.git ~/.extra/app
cd ~/.extra/app && ./install.sh

# Windows:
git clone https://github.com/AIYantra/extra.git "$HOME\.extra\app"
cd "$HOME\.extra\app" ; .\install.ps1

---

连接到任何兼容 MCP 的 AI

Extra 开箱即用，适用于任何支持 Model Context Protocol（MCP） 的 Agent。如果你使用 Cursor、Windsurf 或自定义 Agent，请将此片段添加到 MCP 配置中：

{
  "mcpServers": {
    "extra": {
      "command": "npx",
      "args": ["-y", "@yantraos/extra-desktop"]
    }
  }
}

或使用原生 Python：

{
  "mcpServers": {
    "extra": {
      "command": "python",
      "args": ["-m", "extra.mcp.server"]
    }
  }
}

---

Extra 的底层工作原理是什么？

Extra 采用自主双平面架构，将视觉感知与硬件操作解耦。在感知方面，Extra 将低于 3 ms 的 GPU 帧捕获（DirectX DXGI、Metal、Spectacle）与操作系统辅助功能层级检查（COM UI Automation、AT-SPI2、Quartz）相结合。在操作方面，Extra 以零坐标漂移的方式分发无损内核和 Win32 硬件事件，确保在各种分辨率和显示缩放比例下实现确定性控制。

Extra 从底层开始便以速度、可靠性和令牌效率为设计目标：

1. 👁️ 超快屏幕捕获（< 3 ms）： 使用原生 DirectX Desktop Duplication（DXGI），在 3 毫秒内获取清晰的桌面帧，不会拖慢电脑，也不会模糊文本。
2. 🎯 像素级精准点击： Extra 不会从模糊的屏幕截图中猜测坐标，而是查询原生 Windows 辅助功能树（UI Automation），以 100% 的数学精度点击确切的按钮、菜单或文本框。
3. ⚡ 即时输入： 通过原生 Win32 Unicode 注入，在 5 毫秒内输入 500 个字符，不会漏字，并全面支持表情符号和各种国际语言。
4. 🛑 无限循环停滞保护： 如果应用冻结或点击没有产生可见结果，Extra 会立即检测到并安全停止，避免在无休止的循环中耗费令牌。
5. 🔒 100% 本地运行，保护隐私： Extra 完全在你的设备上运行。不会向任何云服务发送屏幕截图、按键记录或遥测数据。

---

📊 性能对比

指标 / 能力	传统脚本（PyAutoGUI）	云端视觉模型	Extra 引擎
屏幕捕获速度	150 – 300 ms	80 – 150 ms	1.8 – 3.2 ms（DirectX DXGI）
输入速度（100 个字符）	2.5 – 5.0 秒	1.0 – 2.0 秒	< 0.005 秒（Win32 即时输入）
点击准确率	~60%（显示缩放时会失败）	~82%（视觉估算）	99.4%（原生 Windows UIA）
多显示器 DPI 支持	在 125%/150% 缩放下失效	需要手动调整	自动（PerMonitorV2）
AI 令牌成本	高（每一步都要完整截图）	高（完整视觉数据负载）	降低 70%（智能元素树）
停滞预防	无（会无限卡住）	基本超时	智能视觉变化检测

---

🛠️ 内置工具（MCP Suite — 20 个原生工具）

连接到 Extra 后，你的 AI 助手即可通过 20 个原生工具全面、独立地控制桌面：

工具名称	功能
extra_launch	直接打开任意应用、实用工具或 URL（calc、notepad、settings、edge、chrome）
extra_focus_window	通过原生线程输入附加，将任意窗口置于前台
extra_click	以亚像素级 DPI 精度点击，采用类人的贝塞尔曲线和语义视觉定位（target="..."）
extra_stroke	沿多个路径点绘制流畅、连续的笔刷曲线，并支持压力感应和 Catmull-Rom 平滑
extra_type	即时注入文本，零延迟，全面支持表情符号，并使用 Win32 Unicode 数据包
extra_hotkey	发送键盘快捷键（Ctrl+C、Win+E、Alt+Tab、Enter）
extra_batch_actions	以亚毫秒级速度执行硬件操作和 SOUL 反射动作的原子列表（eval、assert、wait_for_state）
extra_snap_layout	以编程方式停靠并排列窗口，构成并排或分屏布局，耗时不足 15ms
extra_fs_batch	高速批量执行文件系统操作，并兼容 Windows Defender 受控文件夹访问
extra_inspect_ui	实时扫描无障碍 UI 树和交互元素节点
extra_click_element	根据无障碍 ID 或语义目标，精确点击 UI 元素
extra_scroll	平滑地向上、向下、向左或向右滚动滚轮
extra_drag	在不同坐标之间拖放文件、窗口或滑块
extra_screenshot	以不足 25ms 的耗时捕获高分辨率桌面画面，并可选择添加 Set-of-Mark 视觉标记
extra_browser	直接提取 Edge/Chrome 中的 DOM 内容，或触发合成 API 快速通道
extra_task_start	激活环境屏幕边缘脉冲效果和光标跟踪光环
extra_task_complete	通知任务已完成：闪烁翠绿色边框、播放提示音并分析轨迹
extra_indicate_status	直接以编程方式控制桌面活动、完成和空闲状态指示器
extra_recall_memory	通过 KùzuDB + FastEmbed，在不足 2ms 内回忆以往的任务工作流、产物和已知问题
extra_scout_app	发现 UI 框架（Electron/Win32/Viewport）和通用快捷键，并生成 SKILL 操作手册
extra_evolve_skill	将新验证的零停顿快速通道固化为永久技能操作手册

---

🏛️ 仓库结构

extra/
├── assets/                 # Brand logos and banners
├── bin/                    # Node.js CLI executable (npx @yantraos/extra-desktop)
├── core/                   # Sovereign Core Automation Engine
│   ├── platform/           # Platform Abstraction Layer (PAL facade for Win32 & macOS)
│   │   ├── windows/        # Win32 SendInput, DXGI capture, UIA, and focus
│   │   └── macos/          # ScreenCaptureKit, CoreGraphics, and AXUIElement
│   ├── soul/               # System One Ultra-fast Layer (Decider, Eyes, Grammar, Schemas)
│   ├── memory/             # KùzuDB episodic knowledge graph & FastEmbed embeddings
│   ├── evolution/          # Autonomous skill crystallizer & API synthesizer
│   ├── scout/              # Application discovery, CDP sniffer, and session vault
│   ├── motion/             # Human-like Bezier cursor flight and spline dynamics
│   ├── capture.py          # Unified high-speed desktop screen capture
│   ├── geometry.py         # PerMonitorV2 DPI scaling & display normalization
│   ├── indicators.py       # Ambient screen pulse, cursor halo, and harmonic chime
│   ├── input_engine.py     # PAL input facade (clicks, strokes, typing, batching)
│   ├── focus.py            # Window activation, snapping, and layout management
│   ├── uia_plane.py        # Accessibility tree inspection and Set-of-Mark labeling
│   └── stall_breaker.py    # Closed-loop perceptual diffing & safety killswitch
├── fastpath/               # High-speed deterministic execution
│   ├── shell.py            # Native app launcher with crash-recovery auto-suppression
│   ├── browser.py          # Playwright & Chromium DevTools Protocol (CDP) bridge
│   ├── fs.py               # CFA-compliant batch filesystem engine
│   └── web/                # Synthesized Web-to-API fast-paths
├── mcp/                    # Model Context Protocol
│   └── server.py           # Standard JSON-RPC stdio/SSE server (20 native tools)
├── tests/                  # Exhaustive 1,883-test official verification suite
├── cli.py                  # CLI runner (extra doctor, test, indicators, run, inspect, snap)
├── install.ps1             # 1-line PowerShell installer (Windows)
├── install.sh              # 1-line bash installer (macOS)
├── pyproject.toml          # PyPI package manifest (extra-desktop v0.3.3)
├── package.json            # npm package manifest (@yantraos/extra-desktop v0.3.3)
├── server.json             # Official MCP registry manifest
├── glama.json              # Glama MCP ecosystem manifest
├── smithery.yaml           # Smithery 1-click deployment manifest
├── requirements.txt        # Enterprise-audited dependency manifest
├── STARTER_PROMPT.md       # Master AI system prompt & setup directive
├── docs/                   # Full System Architecture & Specifications
└── RELEASE_NOTES.md        # Comprehensive version release notes

---

🛡️ 企业级信任与安全

• 绝不使用未经验证的二进制文件： 不包含来自独立维护者的来历不明的已编译 .dll 或 .pyd 文件。
• 符合 Microsoft 和 Anthropic 标准： 完全基于 Microsoft 系统调用（ctypes）、Anthropic 官方 mcp SDK 和 PSF 软件包构建。
• 故障安全保护： 提供屏幕角落紧急退出功能（(0, 0)）和全局紧急停止快捷键（Ctrl+Alt+Shift+Q）。

---

🌌 yantraOS 独立生态系统的一部分

Extra 是 yantraOS 的 Windows 桥接工具；yantraOS 是专为自主计算打造的独立 Arch Linux 操作系统。

如果你想要不带任何操作系统遥测的裸机 AI 自主能力、亚微秒级操作系统内核调度以及原生 Wayland 硬件控制，请访问 yantraos.com。

---

🤝 参与贡献

欢迎内核黑客、自动化研究人员和 AI 开发者参与贡献！
请参阅我们的贡献指南和行为准则。

如需报告漏洞，请参阅我们的安全策略。

---

📜 许可证

本项目依据 MIT 许可证发行。详情请参阅 LICENSE。
Copyright (c) 2026 Euryale Ferox Private Limited.