desktop-touch-mcp

1|# desktop-touch-mcp 2| 3| 4| 5|日本語 6| 7|> Windows 计算机操控 MCP 服务器。 让 Claude、Cursor 或任何 MCP 客户端看到并操控你的 Windows 10/11 桌面——屏幕截图、UI Automation、Chrome CDP、键盘/鼠标、终端——采用先发现后操作的语义化定位避免猜测像素坐标，以及每次操作的感知守护在错误窗口输入发生前拦截。 8| 9|bash 10|npx -y @wangkang1133/desktop-touch-mcp 11| 12| 13|31 个工具，原生 Rust 引擎（UIA 2ms），零配置 PowerShell 回退，完整 CJK 支持，MIT 许可。将上述命令添加到你的 Claude / Cursor / VS Code Copilot 配置中，Claude 就能操控记事本、Excel、Chrome、Windows Terminal 及你机器上的任何其他应用。 14| 15|> 为什么比像素点击更好？ 两个核心理念贯穿每个工具：先发现后操作——desktop_discover 返回带有短期租约的可交互实体而非原始坐标，desktop_act 操作的是你想要什么，而不是它在哪里——以及每次操作的感知守护，在输入落地前验证目标窗口的身份和边界，在错误窗口输入和过期坐标点击发生前拦截。 16|> 17|> 底层实现：Rust 原生引擎带来 82 倍平均加速（UIA 焦点查询 2ms，SSE2 加速图像差异检测 13-15 倍），引擎不可用时透明回退到 PowerShell。npm 启动器仅获取与安装版本匹配的 GitHub Release 标签，并在解压前验证 Windows 运行时 zip 的完整性。 18| 19|--- 20| 21|## 🔧 相比原版的修改（Fork 改进） 22| 23|本仓库是 Harusame64/desktop-touch-mcp 的 Fork，进行了以下增强： 24| 25|### 1. 支持 0.0.0.0 远程访问 26| 27|原版 HTTP 模式仅监听 127.0.0.1（仅本地访问），本 Fork 改为默认监听 0.0.0.0，允许来自任意网络接口的远程连接。 28| 29|- 新增 --host 参数：可自定义绑定地址（默认 0.0.0.0） 30|- 移除 DNS Rebinding 限制：原版仅允许 localhost/127.0.0.1 的 Host 头请求，现已放开 31|- 放宽 CORS 策略：原版仅允许 localhost 来源，现已对所有 Origin 均允许（由 API Key 保障安全） 32| 33|### 2. 新增 API 密钥认证 34| 35|当服务器暴露到网络时，强烈建议启用 API 密钥认证以防止未授权访问： 36| 37|- 新增 --api-key 参数：启动时通过命令行指定密钥 38|- 支持环境变量：通过 MCP_API_KEY 环境变量设置密钥 39|- 认证方式： 40| - HTTP 请求头 X-API-Key: *** 41| - URL 查询参数 ?api_key=your-secret-key42|- **未提供正确密钥**：返回401 Unauthorized 错误 43| 44|```bash 45|# 通过命令行指定密钥： 46|npx -y @wangkang1133/desktop-touch-mcp --http --api-key your-secret-key 47| 48|# 或通过环境变量： 49|MCP_API_KEY=your-secret-key npx -y @wangkang1133/desktop-touch-mcp --http 50| 51|# 完整远程访问配置： 52|npx -y @wangkang1133/desktop-touch-mcp --http --host 0.0.0.0 --port 8080 --api-key your-secret-key 53|``` 54| 55|--- 56| 57|## 功能特性 58| 59|- **⚡ 高性能 Rust 原生引擎** — UIA 桥接和图像差异引擎使用 Rust 编写（napi-rs+windows-rs），作为原生 .node 插件加载。专用 MTA 线程的直接 COM 调用消除了 PowerShell 进程创建——getFocusedElement 在 **2ms** 内完成（快 160 倍），getUiElements 使用批量 BFS 算法在 **~100ms** 内返回完整树。图像差异操作使用 **SSE2 SIMD** 实现 13-15 倍吞吐量。原生引擎不可用时，所有功能透明回退到 PowerShell——零配置。 60|- **🎯 标记集（SoM）视觉回退** — 游戏、RDP 会话和非无障碍 Electron 应用在 UIA 完全不可见时仍返回可点击元素。screenshot(detail="text") 自动检测 UIA 稀疏性并激活混合非 CDP 管道：Rust 加速的灰度 + 双线性放大 → Windows OCR → 聚类 → 红色边界框注释带编号徽章（[1]、[2]…）。返回两个并行表示：用于空间定位的视觉 PNG 和带 clickAt坐标的语义elements[] 列表——无需 CDP。 61|- **🔁 视觉目标一键确认** — 在 UIA 不可见的目标（Electron、PWA、游戏、自定义画布、RDP 窗口）上，desktop_act可将操作后确认合并到自身响应中：可选的roiCapture携带*仅变化区域*的 PNG 裁剪加上无租约的下一个可见控件预览。Agent 确认其点击效果并在一次调用中找到下一个目标，无需单独的desktop_state+screenshot。在视觉目标上默认对可见变更开启（returnCapture:"on-change"）；传 returnCapture:"never" 抑制，"always" 强制。结构化目标（浏览器/CDP、UIA 丰富的原生应用）从不附加——这些响应保持不变。 62|- **LLM 原生设计** — 围绕 LLM 的思维方式而非人类点击方式构建。run_macro 将多个操作批量合并为一次 API 调用；diffMode仅发送自上一帧以来变化的窗口。最小令牌，最小往返。 63|- **响应式感知图** — 为窗口或浏览器标签注册lensId，传递给操作工具，并在每次操作后获得守护检查的 post.perception反馈。减少重复的screenshot/desktop_state调用，防止错误窗口输入或过期坐标点击。 64|- **完整 CJK 支持** — 使用 Win32GetWindowTextW获取窗口标题，避免 nut-js 乱码。支持日语/中文/韩语环境的 IME 旁路输入。 65|- **三层令牌缩减** —detail="image"（~443 tok）/ detail="text"（~100-300 tok）/ diffMode=true（~160 tok）。仅在需要时发送像素。 66|- **1:1 坐标模式** — dotByDot=true以原生分辨率捕获（WebP）。图像像素 = 屏幕坐标——无需缩放计算。将origin+scale传入mouse_click，服务器自动转换坐标——消除偏移和缩放 bug。 67|- **浏览器捕获数据缩减** — grayscale=true（约 50% 大小）、dotByDotMaxDimension=1280（自动缩放并保留坐标）和 windowTitle + region子裁剪有助于排除浏览器边框和其他无关像素。重型捕获的典型缩减：50-70%。 68|- **Chromium 智能回退** — Chrome/Edge/Brave 上的detail="text" 自动跳过 UIA（在那里极慢）并运行 Windows OCR。hints.chromiumGuard+hints.ocrFallbackFired标志所走路径。 69|- **UIA 元素提取** —detail="text"以 JSON 返回按钮名称和clickAt坐标。Claude 无需查看屏幕截图即可点击正确元素。 70|- **自动停靠 CLI** —window_dock(action='dock')将任何窗口吸附到屏幕角落并置顶。设置DESKTOP_TOUCH_DOCK_TITLE='@parent'在 MCP 启动时自动停靠托管 Claude 的终端——进程树遍历器无论标题如何都能找到正确的窗口。 71|- **紧急停止（Failsafe）** — 将鼠标移至**屏幕左上角（0,0 的 10px 内）**可立即终止 MCP 服务器。 72| 73|--- 74| 75|## 系统要求 76| 77|| | | 78||---|---| 79|| 操作系统 | Windows 10 / 11（64 位）| 80|| Node.js | 推荐 v20+（已在 v22+ 上测试）| 81|| PowerShell | 5.1+（Windows 自带）——仅在 Rust 原生引擎不可用时作为回退使用 | 82|| Claude CLI | 必须有claude命令可用 | 83| 84|> **注意：** nut-js 原生绑定需要 Visual C++ Redistributable。 85|> 如未安装，请从 [Microsoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) 下载。 86| 87|--- 88| 89|## 安装 90| 91|```bash 92|npx -y @wangkang1133/desktop-touch-mcp 93|``` 94| 95|npm 启动器严格按 npm 包版本解析运行时。对于包X.Y.Z，仅获取 GitHub Release 标签 vX.Y.Z，下载 desktop-touch-mcp-windows.zip，验证 SHA256 摘要后解压至 %USERPROFILE%.desktop-touch-mcp。已验证的缓存版本在后续运行中复用。 96| 97|设置 DESKTOP_TOUCH_MCP_HOME可覆盖缓存根目录。 98| 99|> **在共享或 CI 网络上？** 首次运行会读取 GitHub Releases API 来定位运行时 zip。匿名限制为每 IP 每小时 60 次请求，共享公网地址（CI 运行器、办公 NAT）可能在你开始下载前就耗尽配额。在环境中设置GITHUB_TOKEN（或 GH_TOKEN），启动器会认证请求，将限额提升至 5,000 次/小时。普通家用网络无需 Token。 100| 101|> **从源码检出运行启动器？** 源码构建的 bin/launcher.js 携带占位完整性哈希（sha256: "PENDING"）而非最终哈希。启动器拒绝下载并运行未验证的运行时——此防护阻止意外发布或未完成的启动器静默启动未验证代码。已发布的 npm 版本始终附带真实 SHA256，终端用户不会遇到此问题。如果刻意从源码运行启动器，设置 DESKTOP_TOUCH_MCP_ALLOW_UNVERIFIED=1跳过完整性验证（仅限开发）。 102| 103|### 注册到 Claude CLI 104| 105|在~/.claude.json的mcpServers下添加： 106| 107|```json 108|{ 109| "mcpServers": { 110| "desktop-touch": { 111| "type": "stdio", 112| "command": "npx", 113| "args": ["-y", "@wangkang1133/desktop-touch-mcp"] 114| } 115| } 116|} 117|``` 118| 119|**无需系统提示词。** 命令参考会通过 MCPinitialize响应的instructions字段自动注入到 Claude 中。 120| 121|### 注册到其他客户端（HTTP 模式） 122| 123|需要 HTTP 端点的客户端（GPT Desktop、VS Code Copilot、Cursor 等）可使用内置的 Streamable HTTP 传输： 124| 125|```bash 126|npx -y @wangkang1133/desktop-touch-mcp --http 127|# 或指定自定义端口： 128|npx -y @wangkang1133/desktop-touch-mcp --http --port 8080 129|# 或指定自定义绑定地址（默认 0.0.0.0 支持远程访问）： 130|npx -y @wangkang1133/desktop-touch-mcp --http --host 0.0.0.0 --port 8080 131|``` 132| 133|服务器默认在http://0.0.0.0:23847/mcp启动（可从所有网络接口访问）。在 MCP 客户端设置中注册此 URL。健康检查端点为http://0.0.0.0:<port>/health。 134| 135|#### API 密钥认证 136| 137|将服务器暴露到网络时，**强烈建议**启用 API 密钥认证以防止未授权访问： 138| 139|```bash 140|# 通过命令行参数指定密钥： 141|npx -y @wangkang1133/desktop-touch-mcp --http --api-key your-secret-key 142| 143|# 或通过环境变量指定： 144|MCP_API_KEY=your-secret-key npx -y @wangkang1133/desktop-touch-mcp --http 145|``` 146| 147|客户端必须通过以下方式之一在请求中包含 API 密钥： 148|- **HTTP 请求头**：X-API-Key: *** 149|- URL 查询参数：?api_key=your-secret-key 150| 151|未提供正确密钥的请求将收到 401 Unauthorized 响应。 152| 153|在 HTTP 模式下，系统托盘图标会显示活动 URL 并提供快速复制和在浏览器中打开的快捷方式。 154| 155|### 开发安装 156| 157|bash 158|git clone https://github.com/wangkang1133/desktop-touch-mcp.git 159|cd desktop-touch-mcp 160|npm install 161| 162| 163|安装后构建： 164| 165|bash 166|npm run build 167| 168| 169|对于本地检出，直接注册构建好的服务器： 170| 171|json 172|{ 173| "mcpServers": { 174| "desktop-touch": { 175| "type": "stdio", 176| "command": "node", 177| "args": ["D:/path/to/desktop-touch-mcp/dist/index.js"] 178| } 179| } 180|} 181| 182| 183|> 注意： 将 D:/path/to/desktop-touch-mcp 替换为你克隆此仓库的实际路径。 184| 185|--- 186| 187|## 工具（31 个优化工具） 188| 189|> 📖 完整参考：docs/system-overview.md — 关于参数、返回模式和坐标数学的详尽指南。 190| 191|### 🌐 World-Graph V2（主路径） 192|| 工具 | 说明 | 193||---|---| 194|| desktop_discover | 观察桌面。返回带有租约的可交互实体（UIA、CDP、终端、视觉 SoM）。| 195|| desktop_act | 通过租约验证对实体执行操作（点击、输入、拖拽、选择）。返回语义差异——在视觉目标上可选附加 roiCapture（变化区域 PNG + 下一个目标预览）。| 196| 197|### 👁️ 观察与状态 198|| 工具 | 说明 | 199||---|---| 200|| desktop_state | 轻量级检查：焦点、活动窗口、光标和自动感知注意力信号。| 201|| screenshot | 多模式捕获：detail='text'（UIA/OCR）、diffMode（P 帧）、dotByDot（1:1）和 background。返回轻量的 screenshot://by-ref/{id} 链接指向已保存图像，而非每次内联像素。| 202|| screenshot_query / screenshot_gc | 检查和清理磁盘上的屏幕截图缓存：screenshot_query 不重新读取像素即可列出已保存捕获；screenshot_gc 按保留策略回收空间（默认试运行）。| 203|| workspace_snapshot | 即时会话概览：一次调用获取所有窗口缩略图 + UI 摘要。| 204|| server_status | 诊断检查原生引擎健康状态和功能激活。| 205| 206|### ⌨️ 输入与控制 207|| 工具 | 说明 | 208||---|---| 209|| keyboard | 发送键盘输入。支持后台输入（WM_CHAR）和 IME 安全的剪贴板旁路。| 210|| mouse_click / mouse_drag | 精确坐标交互，带寻的和强制焦点保护。| 211|| scroll | 多策略：raw（滚轮）、to_element、smart（虚拟列表）和 capture（拼接）。| 212|| click_element | 传统 UIA 按名称/ID 点击（实体不可用时的回退）。| 213| 214|### 🌐 浏览器 CDP（Chrome/Edge/Brave） 215|| 工具 | 说明 | 216||---|---| 217|| browser_open / browser_navigate | 幂等的调试模式启动和可靠导航。| 218|| browser_click / browser_fill / browser_form | 高层 DOM 交互，跨重绘和框架重渲染稳定。| 219|| browser_eval | 通过 js（脚本）、dom（HTML）和 appState（SPA 数据提取）深度检查。| 220|| browser_overview / browser_search / browser_locate | 语义发现、类 grep DOM 搜索和像素精确坐标查找。| 221| 222|### 🛠️ 工具与工作流 223|| 工具 | 说明 | 224||---|---| 225|| terminal | 统一命令执行：run（发送 + 等待 + 读取）、read（OCR/UIA）和 send。run 完成模式：quiet、pattern 和 exit（等待命令完成 + 返回退出码——参见终端命令完成）。| 226|| wait_until | 高效的服务端轮询，等待窗口、焦点、文本或 URL 状态变化。| 227|| window_dock / focus_window | 窗口管理：pin（置顶）、unpin、dock（角落吸附）和 focus。| 228|| workspace_launch | 启动应用并自动检测新 HWND（支持本地化标题）。| 229|| run_macro | 批量最多 50 个操作为单次往返，实现最大效率。| 230|| clipboard / notification_show | 系统级文本交换和用户提醒。| 231| 232|### 📊 办公（Excel） 233|| 工具 | 说明 | 234||---|---| 235|| excel | 通过 COM 编写和运行 Excel VBA 宏。action='run_vba' 将宏写入受信任位置并运行；action='check_access_vbom' 是只读预检。运行仅公式工具无法实现的 VBA。一次性设置：node scripts/enable-access-vbom.mjs。| 236| 237|--- 238| 239|## 标准工作流（v1.0.0） 240| 241|V2 World-Graph 界面（desktop_discover / desktop_act）是推荐的调度路径。四步调用模式对原生应用、浏览器和终端完全一致。 242| 243| 244|desktop_state → 定位：焦点窗口/元素、模态框、注意力信号 245|desktop_discover → 发现可操作实体（返回租约 + windows[]） 246|desktop_act(lease, …) → 对实体操作（返回 attention + post.perception） 247|desktop_state → 确认世界按预期变化 248| 249| 250|点击——优先级顺序： 251| 252| 253|browser_click(selector) → Chrome / Edge（CDP，跨重绘稳定） 254|desktop_act(lease, action='click') → 原生 / 对话框 / 视觉（基于实体；在 desktop_discover 后使用） 255|click_element(name | automationId) → 原生 UIA 回退，当 desktop_act 返回 ok:false 256|mouse_click(x, y, origin?, scale?) → 像素最后手段；仅用于 dotByDot 屏幕截图的 origin+scale 257| 258| 259|恢复提示——每次观察后阅读 response.attention，在 desktop_discover / desktop_act 上阅读 response.warnings[]。常见原因： 260| 261|- lease_expired / lease_generation_mismatch / lease_digest_mismatch / entity_not_found → 重新调用 desktop_discover 262|- modal_blocking → response.blockingElement（存在时）命名阻塞模态框；通过 click_element(name=blockingElement.name) 关闭后重试 263|- entity_outside_viewport → scroll(action='to_element' | 'raw')，然后重新调用 desktop_discover 264|- executor_failed → 回退到 click_element / mouse_click / browser_click 265| 266|租约生命周期： 267| 268|- 每次 desktop_discover 响应携带 softExpiresAtMs（约为 TTL 窗口的 60%）。超过该时间戳后 LLM 应考虑重新调用 desktop_discover，即使租约在技术上仍然有效——lease.expiresAtMs 是唯一正确性边界。 269|- TTL 适应 view 模式（action/explore/debug）、实体数量和响应有效载荷大小。上限 60 秒。 270|- 设置 DESKTOP_TOUCH_DISABLE_FUKUWARAI_V2=1 回退到 v1 工具界面（get_windows / get_ui_elements / set_element_value）——仅用于故障排查，V2 是推荐默认。 271| 272|--- 273| 274|## 终端命令完成（until） 275| 276|terminal(action='run') 在一次调用中发送命令、等待完成并读取输出。如何判定"完成"由 until 控制： 277| 278|| 模式 | 等待条件 | 最佳用途 | 279||---|---|---| 280|| quiet（默认）| 输出静止 quietMs 毫秒 | 短的交互式命令 | 281|| pattern | 期望在输出中出现的字符串/正则 | 有已知最终标记的长命令 | 282|| exit | 命令实际完成 | 需要完成状态或退出码时 | 283| 284|> 锚定注意事项（#384）： 最终行没有尾随换行的命令会将标记粘到下一个提示符而没有行边界（printf X → Xuser@host:~$），因此末尾锚定的 pattern（X\s*\n / X$）永远无法匹配。对于完成使用 mode:'exit'；对于内容匹配使用裸标记（不带 \n/$）。mode:'pattern' 也接受可选的 quietMs 稳定回退：until:{mode:'pattern', pattern, quietMs:1000} 在输出稳定这么长时间后以 reason:'quiet' 完成（无 matchedPattern）——而不是挂起等到 timeoutMs。这是可选的（省略 quietMs 则一直等待模式匹配；有中间静默间隔的长命令不受影响）。 285| 286|### until:{mode:'exit'} — 真正的完成 + 退出码 287| 288|启发式模式可能在常见的"追加哨兵"惯用法上误判（some-task; echo DONE 被 DONE 匹配）：哨兵也出现在回显的命令行中，对于多行命令没有可靠方法区分回显和真实输出。mode:'exit' 消除了猜测——服务器追加自己的完成标记，其打印形式不同于输入形式，因此永远不会匹配回显命令（即使多行输入），并返回真实的进程退出码： 289| 290|js 291|terminal({ 292| action: 'run', 293| windowTitle: 'pwsh', 294| input: 'npm run build', 295| until: { mode: 'exit', shell: 'powershell' }, 296|}) 297|// → completion: { reason: 'exited', exitCode: 0, elapsedMs: … } 298|// output: 仅命令的真实输出（注入的标记已被剥离） 299| 300| 301|- 显式传递 shell（'bash' 或 'powershell'）。shell:'auto' 从终端窗口检测 shell，但无法看到在 SSH 或 WSL 内运行的 shell——窗口看起来仍像其本地主机——因此对于远程/嵌套会话传递远端的 shell（auto 否则会警告并可能选择外层 shell）。真正无法识别进程的窗口（如 Windows Terminal）返回 ExitModeShellAmbiguous。 302|- 一等 shell： bash 和 powershell。cmd.exe 尚不支持（ExitModeShellUnsupported）。 303|- 不安全输入被预先拒绝（ExitModeUnsafeInput）而非挂起：以半构造终止的命令（未闭合引号、here-doc、$(…)、尾随 \ 或 PowerShell 反引号）。 304|- 退出模式控制自身的传递，因此塑造传递的 sendOptions（method / preferClipboard / pressEnter / chunkSize / pasteKey）被以 InvalidArgs 拒绝；焦点选项仍然可用。 305| 306|--- 307| 308|## 浏览器 CDP 自动化 309| 310|对于 Web 自动化，连接启用远程调试端口的 Chrome 或 Edge——无需 Selenium 或 Playwright。 311| 312|bash 313|# 以 CDP 模式启动 Chrome 314|chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp 315| 316| 317| 318|browser_open({launch:{}}) → 按需启动调试模式 Chrome + 列出标签页（幂等） 319|browser_open() → 仅连接（无 CDP 端点时失败） 320|browser_locate({selector:"#submit"}) → CSS 选择器 → 物理屏幕坐标 321|browser_click({selector:"#submit"}) → 一键找到 + 点击（自动聚焦浏览器） 322|browser_eval({action:"js", expression:"document.title"}) → 执行 JS，返回结果 323|browser_eval({action:"dom", selector:"#main", maxLength:5000}) → outerHTML，截断至 maxLength 字符 324|browser_eval({action:"appState"}) → 一次性 SPA 状态（Next/Nuxt/Remix/Apollo/GitHub react-app/Redux SSR） 325|browser_fill({selector:"#email", value:"user@example.com"}) → 填充 React/Vue/Svelte 受控输入（状态安全） 326|browser_overview() → 链接/按钮/输入 + ARIA 切换 + 每个元素的 viewportPosition 327|browser_search({by:"text", pattern:"..."}) → 带置信度排名的 DOM grep 328|browser_navigate({url:"https://example.com"}) → 通过 CDP 导航（无地址栏交互） 329| 330| 331|在同一标签页中链式调用时，传 includeContext:false 省略 activeTab/readyState 注释（每次调用约节省 150 token）。布尔/对象参数接受 LLM 友好的字符串拼法（"true"、"{}"）。 332| 333|browser_locate 返回的坐标已考虑浏览器边框（标签栏 + 地址栏高度）和 devicePixelRatio，因此可直接传给 mouse_click，无需任何缩放。 334| 335|推荐的 Web 工作流： 336| 337|browser_open({launch:{}}) → browser_eval({action:"dom"}) → browser_locate(selector) → browser_click(selector) 338| 339| 340|--- 341| 342|## 启动时自动停靠 CLI 343| 344|全屏操作其他应用时保持 Claude CLI 可见。在 MCP 配置中设置环境变量，停靠窗口在每次 MCP 启动时自动吸附到位。 345| 346|json 347|{ 348| "mcpServers": { 349| "desktop-touch": { 350| "type": "stdio", 351| "command": "npx", 352| "args": ["-y", "@wangkang1133/desktop-touch-mcp"], 353| "env": { 354| "DESKTOP_TOUCH_DOCK_TITLE": "@parent", 355| "DESKTOP_TOUCH_DOCK_CORNER": "bottom-right", 356| "DESKTOP_TOUCH_DOCK_WIDTH": "480", 357| "DESKTOP_TOUCH_DOCK_HEIGHT": "360", 358| "DESKTOP_TOUCH_DOCK_PIN": "true" 359| } 360| } 361| } 362|} 363| 364| 365|| 环境变量 | 默认值 | 说明 | 366||---|---|---| 367|| DESKTOP_TOUCH_DOCK_TITLE | （未设置 = 关闭） | @parent 遍历 MCP 进程树找到托管终端——免疫标题/分支/项目变化。或使用字面子串。| 368|| DESKTOP_TOUCH_DOCK_CORNER | bottom-right | top-left / top-right / bottom-left / bottom-right | 369|| DESKTOP_TOUCH_DOCK_WIDTH / HEIGHT | 480 / 360 | 像素（"480"）或工作区比例（"25%"）——4K/8K 自动适配 | 370|| DESKTOP_TOUCH_DOCK_PIN | true | 置顶切换 | 371|| DESKTOP_TOUCH_DOCK_MONITOR | 主显示器 | 来自 desktop_state({includeScreen:true}) 的显示器 ID | 372|| DESKTOP_TOUCH_DOCK_SCALE_DPI | false | 为真时，将像素值乘以 dpi / 96（按显示器缩放可选）| 373|| DESKTOP_TOUCH_DOCK_MARGIN | 8 | 屏幕边缘内边距（像素）| 374|| DESKTOP_TOUCH_DOCK_TIMEOUT_MS | 5000 | 目标窗口出现的最长等待时间 | 375| 376|> 输入路由注意事项： 当置顶窗口激活时（如 Claude CLI），keyboard(action='type') / keyboard(action='press') 会将按键发送到它，而不是你要输入的目标应用。在键盘操作前始终先调用 focus_window(title=...)，然后通过 screenshot(detail='meta') 验证 isActive=true。 377| 378|### 屏幕截图缓存（按引用存储） 379| 380|screenshot 和其他视觉结果返回轻量的 screenshot://by-ref/{id} 链接指向磁盘上保存的图像，而非每次内联像素，因此常规的观察-操作-确认循环消耗的令牌大大减少。缓存自动限制自身大小，screenshot_query / screenshot_gc 让你检查和清理它。通过以下设置调整存储： 381| 382|| 环境变量 | 默认值 | 说明 | 383||---|---|---| 384|| DESKTOP_TOUCH_SCREENSHOTS_DIR | （每用户缓存目录） | 将缓存固定到特定文件夹。如默认文件夹无法创建或写入（如企业策略阻止在用户配置文件下新建文件夹），服务器自动探测此目录 → 运行时目录 → OS 临时文件夹，使用第一个可写的而非直接放弃缓存。| 385|| DESKTOP_TOUCH_SCREENSHOT_MAX_COUNT | 200 | 缓存中最多保留此数量的捕获。| 386|| DESKTOP_TOUCH_SCREENSHOT_MAX_BYTES | 256 MiB | 磁盘上缓存总大小上限。| 387|| DESKTOP_TOUCH_SCREENSHOT_MAX_AGE_MS | （关闭） | 丢弃超过此毫秒数的旧捕获（可选）。| 388|| DESKTOP_TOUCH_SCREENSHOT_AUTOPRUNE | on | 自动修剪缓存以容纳新捕获。设 0 禁用。| 389|| DESKTOP_TOUCH_SCREENSHOT_MIN_EVICT_AGE_MS | 60000 | 不自动驱逐比此更年轻的捕获（ms），因此刚拿到的 by-ref 链接足够时间打开，即使同一 PC 上有另一个 AI/进程也在捕获。0 禁用。| 390| 391|### 自动感知（始终开启） 392| 393|Phase 4 将显式 perception_* 工具族私有化——v0.12 自动感知层自动在每个 desktop_state 和 desktop_act 响应上附加 attention 信号。操作工具在传入 windowTitle 时也会自动守护。不再需要手动注册/读取/遗忘 lens。 394| 395| 396|# desktop_state 始终返回注意力信号 397|desktop_state() → {focusedWindow, focusedElement, modal, attention:"ok", ...} 398| 399|# 操作工具在传入 windowTitle 时自动守护： 400|keyboard({action:"type", text:"hello", windowTitle:"Notepad"}) 401|→ post.perception:{status:"ok"} // 守护失败时阻止不安全输入 402| 403|# 当注意力为 dirty / stale / settling 时，用 desktop_state 刷新： 404|desktop_state() // 通过自动感知重新评估注意力 405| 406| 407|对于高级固定目标工作流，lensId 参数仍然可在操作工具上使用（keyboard、mouse_click、mouse_drag、click_element、browser_click、browser_navigate、browser_eval、desktop_act）。省略 lensId 即走正常自动感知路径。底层注册表、热目标缓存和传感器循环不变；仅退役了显式的 perception_register / perception_read / perception_forget / perception_list 工具。 408| 409|--- 410| 411|## 鼠标寻的校正 412| 413|当 Claude 调用 screenshot(detail='text') 读取坐标，几秒后调用 mouse_click 时，目标窗口可能已移动。寻的系统自动校正此偏移。 414| 415|| 层级 | 启用方式 | 延迟 | 作用 | 416||------|---------|------|------| 417|| 1 | 自动启用（如缓存存在）| <1ms | 窗口移动时应用 (dx, dy) 偏移 | 418|| 2 | 传 windowTitle 提示 | ~100ms | 窗口被遮挡时自动提前 | 419|| 3 | 传 elementName/elementId + windowTitle | 1–3s | 窗口大小变化时重新查询 UIA 获取新坐标 | 420| 421| 422|# 仅层级 1（自动） 423|mouse_click(x=500, y=300) 424| 425|# 层级 1 + 2：如窗口被隐藏则同时提前 426|mouse_click(x=500, y=300, windowTitle="Notepad") 427| 428|# 层级 1 + 2 + 3：窗口大小变化时也重新查询 UIA 429|mouse_click(x=500, y=300, windowTitle="Notepad", elementName="Save") 430| 431|# 关闭寻的控制——不校正 432|mouse_click(x=500, y=300, homing=false) 433| 434| 435|homing 参数在 mouse_click、mouse_drag 和 scroll 上可用。缓存在每次 screenshot()、desktop_discover()、focus_window() 和 workspace_snapshot() 调用时自动更新。 436| 437|### mouse_click 图像局部坐标（origin + scale） 438| 439|使用 dotByDotMaxDimension 拍摄 dotByDot 屏幕截图时，响应会打印 origin 和 scale 值。无需手动计算屏幕坐标，直接复制到 mouse_click 中： 440| 441| 442|# 屏幕截图响应： 443|# origin: (0, 120) | scale: 0.6667 444|# 点击图像像素 (ix, iy)：mouse_click(x=ix, y=iy, origin={x:0, y:120}, scale=0.6667) 445| 446|mouse_click(x=640, y=300, origin={x:0, y:120}, scale=0.6667, windowTitle="Chrome") 447|# 服务器转换：screen = (0 + 640/0.6667, 120 + 300/0.6667) = (960, 570) 448| 449| 450|这消除了整类偏移和缩放 bug。不传 origin/scale 时，x/y 仍为绝对屏幕像素（行为不变）。 451| 452|--- 453| 454|## screenshot 关键参数 455| 456| 457|detail="image" — PNG/WebP 像素（默认） 458|detail="text" — UIA 元素 JSON + clickAt 坐标（无图像，~100-300 tok） 459|detail="meta" — 仅标题 + 区域（最省，~20 tok/窗口） 460|dotByDot=true — 1:1 WebP；image_px + origin = screen_px 461|dotByDotMaxDimension=N — 限制最长边（响应包含用于坐标计算的 scale） 462|grayscale=true — 文本密集型捕获约缩小 50%（代码/AWS 控制台） 463|region={x,y,w,h} — 带 windowTitle：窗口局部坐标（排除浏览器边框） 464| 不带：虚拟屏幕坐标 465|diffMode=true — 首次调用 I 帧，之后 P 帧（仅变化窗口）（~160 tok） 466|ocrFallback="auto" — detail='text' 在 uiaSparse 或为空时自动触发 Windows OCR 467| 468| 469|推荐的 Chrome 组合（减少 50-70% 数据）： 470| 471|screenshot(windowTitle="Chrome", 472| dotByDot=true, dotByDotMaxDimension=1280, grayscale=true, 473| region={x:0, y:120, width:1920, height:900}) # 跳过浏览器边框 474| 475| 476|推荐工作流： 477| 478|workspace_snapshot() → 完整概览（重置差异缓冲区） 479|screenshot(detail="text", windowTitle=X) → 获取 actionable[].clickAt 坐标 480|mouse_click(x, y) → 直接点击，无需计算 481|screenshot(diffMode=true) → 仅检查变化（~160 tok） 482| 483| 484|--- 485| 486|## 安全 487| 488|### 紧急停止（Failsafe） 489| 490|将鼠标移至屏幕左上角（0,0 的 10px 内）可立即终止 MCP 服务器。 491| 492|- 每次工具检查：checkFailsafe() 在每个工具处理器前运行 493|- 后台监控：500ms 轮询作为长时间操作的备份 494|- 触发范围：10px 495| 496|### API 密钥认证（本 Fork 新增） 497| 498|当通过 HTTP 模式将服务器暴露到网络时，启用 API 密钥认证可防止未授权访问。 499| 500|- 启用方式：启动参数 --api-key <密钥> 或环境变量 MCP_API_KEY 501|