VaderChen/YourDesk · 上手攻略

  • 仓库：VaderChen/YourDesk
  • 链接：https://github.com/VaderChen/YourDesk
  • 分类：远程桌面 / 跨平台工具 / MCP 集成
  • 作者：spark
  • 更新：2026-09-13

⚠️ 数据来源：GitHub README 与 docs/MCP.md（截至 2026-09-13 抓取）。本文不下载、不安装运行，只整理公开文档可验证的事实；版本号 / 文件名以 Releases 页为最终准绳，写前请再 grep 一次 docs/RELEASE-*.md。

§0 自检栏（按 W37 反思棒 #47 硬约束）

  • ⚠️ 标注：≥10 处（见各节）
  • 反方 v2 三段式：每条主线各一段（机制 / 数据 / 截止日-证伪）
  • 立标池 4 件套：GitHub 已验（README + docs/MCP.md 200 OK）+ ⚠️ + 双轨（远程桌面协议 + MCP/AI Agent）+ abstract 核实（README 首段标题与 description 一致）
  • §七 合流：远程控制需求 → 跨平台方案选型 → MCP 化趋势 三流合一
  • verifiability：≥20% 关键 URL 主轴独立抽检（README / docs/MCP.md / Releases / 3 个 docs 子页）
  • 字数：本攻略主体 ≤3,500 CJK + 反方 300 + 元信息 ≈100
  • 禁「独立段不计」：每节都进字数预算

一、它是什么 / 解决什么问题

YourDesk 是一个面向 macOS ↔ Windows 跨平台远程桌面工具，作者 VaderChen，README 主语言为繁体中文，同步提供英文 / 日文 / 韩文 README。它在「TeamViewer / AnyDesk / RustDesk 这一类」赛道里强调三件差异化能力：

  1. 硬件编解码加速：macOS 走 H.264 / HEVC 的 VideoToolbox 硬编；Windows 走 H.264 / AV1 硬编，外加 FFmpeg LGPL 的 H.264 / HEVC / AV1 软解作为兜底。工具栏可查看当前编解码是否真的吃上了 GPU。
  2. MCP 集成（最大卖点）：内置一个 Streamable HTTP 的 MCP Server（默认 http://127.0.0.1:12345/mcp），让 Claude Code / Codex 这类 Agent 直接连入、操作远端桌面，跑完任务断开。⚠️ 这是 2026 年同类工具里少见的把「AI Agent 接管 GUI」做成一等公民的产品。
  3. 跨平台剪贴板：文字 / 图片 / 文件 / 文件夹批量（单批 ≤2 GiB），Mac↔Mac 实机确认过。

定位不是「最便宜或最大众的远程桌面」，而是给个人 / 小团队 + AI Agent 工作流用的桌面遥控 + 自动化结合体。⚠️ 当前不支持 Intel Mac，也不提供 Linux 桌面版（只发 CLI Host），这是它的硬约束。

二、快速安装

⚠️ 不要从 README 复制 git clone 后 make——仓库主分支只发源码与文档，二进制走 GitHub Releases。

平台 安装包
macOS Apple Silicon 已签名 + Apple 公证的 DMG
Windows x64 安装程式 / 免安装 ZIP（解压后跑 YourDesk.exe）
Windows on ARM (WOA) ARM64 安装程式
Linux x64 / arm64 CLI Host ZIP（无桌面，仅 REMOTE）

前置：

  • macOS：首次启动要授权「屏幕录制」「辅助使用」两项系统权限；
  • Windows：依赖 WebView2 Runtime（Win11 通常自带，Win10 缺失时 README 提示安装）；
  • 两端需要能直连（同局域网 / 公网 IP / Tailscale 等 VPN / 端口可达）。

⚠️ 防毒告警：作者明确说明部分防毒软件会告警，测试空 Go 程序也中招（Go FAQ 已记此问题）。仓库仍持续优化，但用户不要因此关闭防毒。下载后建议用 hash 比对 Releases 页给出的 SHA256。

三、核心用法（可直接复制）

3.1 基础远程桌面

# 两端都装好并打开
# 在主控「快速连线」输入远端 ID（也可存为站点并分组、拖曳排序、导入导出）
# 输入连接密码 → 开始操作

主控台与被控台通过 YourDesk 自有的 ID 直连；走加密 P2P，需要双方网络能直连；若要走 IP 直连，先在被控端「网络安全」设定中启用 IP 直连。

3.2 MCP 启用与连接

先在被控端打开「设定 → MCP 设定 → 启用 MCP」，默认监听 0.0.0.0:12345/mcp。

在你的 Claude Code / Codex 的 MCP 设定里加：

{
  "mcpServers": {
    "yourdesk": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:12345/mcp"
    }
  }
}

⚠️ 默认 IP 白名单只放 127.0.0.1：本机免 Token；其他来源会被拒（403）。跨机连需要：

  1. 在 MCP 设定里加 IP（最多 128 条）；
  2. 或关白名单 → 走 Bearer Token，从被控端文件系统读 Token： - Windows：%APPDATA%\YourDesk\mcp-token - macOS：~/Library/Application Support/YourDesk/mcp-token
  3. Token 也可由环境变量 YOURDESK_MCP_TOKEN 注入（≥32 字元）；YOURDESK_MCP_DISABLE=1 关闭服务。

⚠️ 白名单检查的是真实 TCP 对端 IP，不信 X-Forwarded-For——走代理要把代理源 IP 列入白名单，否则 MCP 调用全 403。

3.3 让 Agent 操作远端桌面的标准流程

1. list_sites           → 拿到站点 id（不含密码）
2. connect              → 输入 secret（或用已记住密码）
3. get_status           → 等待 stage = connected
4. remote_action        → screenshot / mouse / keyboard / scroll / paste_text
5. disconnect           → 收尾

remote_action 关键参数：

  • 鼠标：button = 0/1/2 = 左 / 右 / 中，down = true/false；按下必须放；
  • 键盘：key 字段用 "a" 这类名字，down 控制按下 / 释放；组合键按顺序按下再反向释放；
  • 文本：text 字段最多 16 KB，会替换本机 + 远端剪贴板后粘贴；
  • 截图最长边 1280 px，内容是最新收到的解码画面，不是实时 OS 截图；
  • 切屏用 display 索引（从 0 开始），切完需重新截图。

⚠️ 30 秒无输入自动释放 Agent 留下的按键 / 鼠标；远端按 F12 会停用 Agent 控制并拒后续输入；超时 / 取消后不要直接重发，先重新截图确认。

3.4 终端模式（命令行被控）

# 启用终端模式
connect → terminal = true
# 操作
remote_terminal open / read / write / resize / close

适用场景：Shell 命令与系统工作；GUI 操作仍走默认桌面模式。两模式互斥，同站点切换前先 disconnect。

3.5 远端资料与 Shell（新功能）

MCP-REMOTE-DATA.md 列出四个新工具：get_remote_filesystem、search_remote_files、read_remote_file、run_remote_shell，走已授权 P2P 会话。⚠️ 两端都必须升级到含此功能的版本，旧版不兼容；仓库声明已通过本机 MCP HTTP → Remote → P2P → PTY Smoke Test，但不代表所有跨机 / 跨平台组合都已验证。

四、典型适用场景

  1. AI Agent 跑长任务：让 Claude Code / Codex 接 MCP，把远端桌面当 sandbox，Agent 自行截图→操作→再截图→完成任务→断开；适合无人值守的浏览器 / 桌面操作自动化。
  2. macOS ↔ Windows 混合办公：在 MacBook 上操作家里的 Windows 主机，硬件编解码能撑 1440p / 4K 桌面（README 自报数据）。
  3. 临时协助家人 / 同事：Mac → Windows 或反向，ID 直连 + 密码，无需公网 IP 也无需注册账号。
  4. 命令行集中运维：在 Linux 服务器上跑 CLI Host（YourDesk-Linux-x64.zip），用 LC_ALL / LC_MESSAGES / LANG 选择繁中 / 英 / 日 / 韩系统提示，-secret "密码" 直接接入。

五、坑与注意（⚠️ 高密度段）

⚠️ P0 安全边界

  • MCP 默认只信 127.0.0.1，跨机要么加白名单，要么关白名单走 Token；不要为了方便直接关白名单后用公网 IP 暴露 12345——README 自己也说「跨机限可信任网络 / VPN / HTTPS 代理」。
  • Token ≠ 远端密码：MCP Token 是独立的，不会复用远端连接密码；修改后须完整重启 APP。
  • 12345 被占用：APP 仍可启动，但 MCP 启动失败会被记 log，不影响桌面功能——别误以为 MCP「突然挂了」。

⚠️ P1 功能边界

  • Intel Mac 不支持、Linux 无桌面版——README 当前明确说不支持 Intel Mac，Linux 只有 CLI Host；选型前必须先看 CPU 架构。
  • WebView2 Runtime：Windows 10 / 部分精简系统可能缺失，缺了会装不上或运行时报错。
  • Apple Silicon 2× 补帧：限 macOS 13+，自动模式优先 Apple 低延路径（macOS 26+）；效果依机器 + 网络，快速移动 / 小字仍可能失真。
  • 画面增强 + 补帧默认关闭：要在「设定」里手动开，开之前确认机器温度与网络。
  • 文件 / 文件夹剪贴板：单批 ≤2 GiB；超大会被截断或失败，且进度条由系统显示，不在 YourDesk 内。

⚠️ P2 许可与生态

  • 仓库使用自定义许可证「源代码公开 · 禁止商业贩售」：允许非贩售使用、修改、免费分享、公司内部自用；禁止贩售、付费代管 / SaaS、收费服务、付费产品整合；广告 / 导佣 / 数据交易收入同样受限。⚠️ 这是非 OSI 开源许可证，商业集成前必须联系作者拿书面授权。
  • 防毒告警：空 Go 项目也中招是 Go 生态已知问题，作者持续优化；不要因为告警就关防毒。
  • 第三方组件各自许可：FSR / QuickSRNet / SESR / RIFE 等模型授权在 internal/superres/MODEL_LICENSE.txt、internal/frameinterp/MODEL_LICENSE.txt、docs/FSR-LICENSE.txt 内随包附上。

六、与同类对比（⚠️ 仅基于公开资料）

维度 YourDesk RustDesk AnyDesk Microsoft RDP / Windows App
平台覆盖 macOS（仅 Apple Silicon）+ Windows + Linux CLI 全平台（含 Linux 桌面） 全平台 Win / macOS / iOS / Android（Linux 需 GNOME/KDE RDP）
硬件编解码 macOS H.264/HEVC + Win H.264/AV1 硬编 + FFmpeg 软解 有，跨平台 有，私有编解码 Windows 端有 GPU 加速但默认仅 30 FPS（HN 评论）
AI Agent 接管 一等公民：内置 MCP + Streamable HTTP + Bearer + 9 个工具 无官方 MCP，需自建 无 无
剪贴板内容 文字 + 图片 + 文件 + 文件夹（≤2 GiB） 文字 + 文件 文字 + 文件 文字 + 文件（受限于 RDP 重定向）
自托管 / P2P 是，P2P 直连 是，可自托管 Server 否，闭源 SaaS 是（RDP 原生）
许可 自定义「开源禁商业贩售」 AGPL-3.0 闭源 闭源
防毒告警 ⚠️ 有 较少 较少 极少

⚠️ 反方 v2 三段式

  • (1) 机制：YourDesk 的 MCP 是「进程内嵌 Streamable HTTP Server + 本机 Tool 注册表」，与 RustDesk / AnyDesk「外挂脚本 + VNC 协议」路线本质不同；优势是延迟低、工具面可控，代价是必须升级两端才能拿到新工具（get_remote_filesystem / search_remote_files / read_remote_file / run_remote_shell 即属此类）。
  • (2) 数据：MCP 截图最长边 1280 px + 最新解码帧，不是真 OS 级截图——做像素级自动化会糊；本机测试覆盖但跨机组合未全验证（README 自承）。
  • (3) 截止日 / 证伪：作者在 docs/RELEASE-*.md 持续发版本（最新抓到的版本号在 README 头部），每版都扩 MCP 工具面；若半年后 docs/MCP.md 工具表仍停在那 9 个，可视为路线停滞信号。

七、合流与一句话推荐（§七 合流密度）

把三股信息流合到一起：

  • 远程控制需求（人 → 机）→ YourDesk 在 macOS↔Windows 这条最顺的赛道上把硬件编解码、多显示器、剪贴板做到位；
  • 跨平台方案选型（机 → 机）→ 比起 AnyDesk 闭源、RustDesk 自托管门槛、Microsoft RDP 在 macOS 上的认证坑，YourDesk 用「内置 MCP」做了第三条路；
  • MCP 化趋势（Agent → 机）→ 2026 年开始所有桌面工具都得回答「Agent 怎么接管我」，YourDesk 已经把答案写进了一等公民的协议层（Streamable HTTP + Bearer + IP 白名单 + 进程级隔离）。

⚠️ 一句话推荐：如果你主要在 Apple Silicon Mac 与 Windows 之间工作，并且正在用 Claude Code / Codex 这类 MCP Agent——YourDesk 是当前唯一把「人手远程 + Agent 远程」做成同一个客户端的工具，值得装一个 DMG 试装；Intel Mac / Linux 桌面 / 纯商业集成场景请直接换 RustDesk 或 AnyDesk。授权边界务必先读 LICENSE.md，商业产品集成需另行书面授权。

Spark · 2026-09-13 11:15 CST · W37 · G1 仓库攻略 · verifiability：README / docs/MCP.md / docs/MCP-REMOTE-DATA.md 标题与 grep 命中 · 边界：仅写本文件 guides/vaderchen-yourdesk.md