Skip to content
Projects

yolilin642-byte/screen-handoff

View on GitHub

yolilin642-byte/screen-handoff has 16 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 06:25 UTC. Last push 2026-11-09.

How these counts are measured

16 stars0 Forks

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Let an AI use your computer while you watch from your phone, and take over anytime. Self-hosted, built on CrossDesk.

AI

README.md

Original

screen-handoff · 让 AI 用你的电脑，你在手机上看着

你的 Windows 电脑上住一个小程序，AI 通过它截图、点鼠标、打字、开网页。你在手机上看实时画面，随时按「我来」接手，弄完按「还给你」。

是哪家的 AI 都行：跑在这台电脑上、能执行命令的 Agent 直接找它；跑在你 VPS 上的，经隧道找它；住在别人服务器上的聊天应用，只要能加 MCP 连接器，就经 VPS 上的连接器找它。

就是 computer use 那种用法：AI 干活，人看着；撞上登录、验证码、付款，人接手。

下面标着「没测过」的，是还没人真走过的地方。

它由哪几块拼成

块 跑在哪 干嘛的 非要不可？
CrossDesk 主机端 被控的电脑 把屏幕推出去，收远程的鼠标键盘 要。第三方开源（LGPL-3.0），一行没改
CrossDesk 信令 一台连得到的机器 让手机和电脑找到对方 要，而且得有一个带证书的 https 网址
网页客户端（改过） 跟信令同一个网址 在手机浏览器、聊天应用的直播卡、你自己的聊天页里看画面、点画面 要。LGPL-3.0，改过的部分在 web/
门 信令前面那层反向代理 不带钥匙的，连密码框都摸不到 强烈建议
中继（TURN） 任何有公网 IP 的机器 打不通直连时兜底转流量 多数时候用不上，可以以后再补
屏幕小程序 被控的电脑 AI 的手和眼：截图、点、打字、屏幕上的字幕、「我来」那把锁、每趟活的账 要。目前只有 Windows
OpenCLI 被控的电脑 AI 在你已经登录的 Chrome 里点网页 想让 AI 上网才要
连接器（MCP） VPS 聊天应用里的直播卡，给它的看屏幕、碰桌面、浏览器工具，OAuth 授权 只有官端聊天应用要用才要
操控台网页 跟信令同一个网址 不靠任何聊天 App，手机开网页就能看直播、看账、按「我来」 可选

画面走的是 WebRTC：多数时候手机和电脑直连，中继只兜底。屏幕小程序和 AI 之间的往来（截图、点、账）不走画面那条路，走的是另一根线。

 手机 ──https/wss──> 信令 + 门 + 网页客户端 (VPS)
   └──── 画面 (WebRTC，直连；不通走中继) ────> 电脑上的 CrossDesk 主机端

 AI
   ├─ 本地 Agent（在这台电脑上）── 本机 ──> 屏幕小程序 (127.0.0.1)
   ├─ 住在 VPS 上的 AI ── desk 门 ── 隧道 ──> 屏幕小程序
   └─ 官端聊天应用（在云上）── MCP ──> 连接器 (VPS) ── 隧道 ──> 屏幕小程序

 屏幕小程序
   ├─ hand-v2.exe  截图、鼠标、键盘
   ├─ overlay.exe  屏幕最上层的字幕和落点
   └─ OpenCLI      你的 Chrome

先认一认你家

每个人的家都不一样。先对一下你是哪种，再挑自己那条线走。

  1. 有 VPS，有域名：我们家就是这样。照第 1–7 章走。

  2. 有 VPS，没域名：网页是 https 的，信令就得是带证书的 wss，浏览器和聊天应用里的卡才肯连。最省事的是弄一个域名，也有不花钱的子域名、Cloudflare Tunnel 这类路子。没测过。

  3. 没有 VPS，只有一台电脑：信令可以直接借 CrossDesk 官方的公共服务器，site.json 里写 "signal": "public"，生成出来的网页就连官方的信令，不带门。网页本身找个放静态网页的地方挂上（Cloudflare Pages、GitHub Pages 这类，要占一个域名的根）。代价：

    • 门挂不上，只剩 CrossDesk 的设备号加密码一把锁；
    • 谁在什么时候连了谁，官方服务器那边看得见（画面多数时候直连，不经过它）；
    • 「我来」那颗按钮要靠家里的小程序和隧道，这种家没有，只能靠你一碰画面它就停四秒；
    • 官端聊天应用那条路要连接器，连接器得有个 VPS，这种家走不了。

    官方的公共信令认不认别的网站来连，没测过（我们家一直没连过公共服务器）。翻过上游开源的信令代码（crossdesk-server 的 src/signal_server.cpp）：握手时不查网页是从哪个网站来的，按理认；可官方服务器跑的是不是这一份、前面有没有再挡一层，不知道。只是想在手机上看、在手机上点，不嵌进任何聊天的话，直接用官方的 web.crossdesk.cn 就行，连这份网页都不用挂。

  4. VPS 在国内：没备案的域名，443 端口会被掐（我们撞过）。中继走 UDP、连 IP，不受这个影响，可以放国内，离手机近还快。

  5. 被控的是 Mac：屏幕小程序的手和字幕层有 mac 版（hand/hand-mac.swift、overlay-mac.swift，要 macOS 14 以上，自己用 swiftc 编），要在系统设置里给三道权限：屏幕录制、辅助功能、输入监控。写了，但还没编译过、没在 mac 上跑过。 有 mac 的人走一遍，最好。

  6. 被控的是 VPS：没有桌面，得先装虚拟桌面。不打算支持。

再认一认：你的 AI 住在哪

同一台电脑、同一套画面，AI 从哪儿伸手、你从哪儿看，四种人走的路不一样。

AI 怎么够到电脑 你在哪看直播、按「我来」 要哪几块
本地 Agent：跑在这台电脑上、能执行命令的都算（Claude Code、Codex、Cursor、Gemini CLI……） 直接敲本机的屏幕小程序（127.0.0.1），网页走 OpenCLI；照 skill/ 那份说明书做 操控台网页，或下面任意一种 不用连接器
AI 住在 VPS 上：Claude Code、Codex、自己写的 Agent 跑在 VPS 里，动的是家里这台电脑 在 VPS 本机敲隧道那头的 desk 门，带一把桌面钥匙；截图、点、打字、网页，跟本机那只手同一套，没有 force 操控台网页 要隧道。desk 门默认关着，填了钥匙才开（第 6 章最后一节）
官端聊天应用：能加自定义 MCP 连接器的都算（ChatGPT、Claude……），App 或网页 连接器在 VPS 上，经隧道回到家里的小程序；OAuth 授权，头一回输配对码 对话里叫出直播卡，卡上就有「我来」；应用不认卡的话，用操控台 要连接器、隧道。走通过的只有 ChatGPT，别家没测过
自建前后端（自己写的聊天页＋后端） 后端跟小程序在同一台电脑：直接敲本机。后端在 VPS 上：走 desk 门，跟上面「AI 住在 VPS 上」一样 聊天页里嵌一个 iframe 放网页客户端，听它往外报的 kaelLive 消息（连上、要密码、断了、卡不卡），协议写在第 4 章 看后端住哪

我们自己用的是本地 Agent、官端聊天应用和自建聊天页：本地 Agent 在电脑上干活，自己写的聊天页里嵌着那块小屏，官端那条是后来接上的。AI 住在 VPS 上那种我们没这么用过，desk 门只在测试副本上试过，真从 VPS 经隧道敲过来还没试。

章节

  1. 准备：要哪些东西、按什么顺序走、一路攒下哪几把钥匙
  2. VPS：信令、Caddy、证书
  3. 电脑上装 CrossDesk 主机端：先有信令，它才有地方连
  4. 门：给信令挂上钥匙
  5. 网页客户端：换上改过的那份
  6. 屏幕小程序：装、起、开机自启、隧道
  7. 本地 Agent 用它（跑在这台电脑上的 AI）：OpenCLI、说明书、「我来」；AI 住在 VPS 上的，看这章最后一节
  8. 官端聊天应用用它（住在服务商那边的 AI，经 VPS 上的连接器）：OAuth、直播卡、看屏幕、碰桌面、上网的工具。具体按哪儿拿 ChatGPT 写，走通过的只有它
  9. 中继（可选）
  10. 出了问题去哪看

仓库里有什么

路径 是什么
server.mjs、hand-client.mjs、start.vbs 屏幕小程序：主程序、跟两只手说话的那层、不弹窗的起法（第 5 章）
hand/ 两只手的源码：hand.cs、overlay.cs（Windows，自己编）；*-mac.swift（mac，没编译过）
oc.ps1 Windows 上给本地 Agent 用的 OpenCLI 包装：每一步先报字幕、先问「我来」按没按着（第 6 章）
typetest.html 试手的小页：小程序起着时打开 http://127.0.0.1:5260/typetest，让 AI 往格子里打字、点几下，看落没落对
web/ 改过的 CrossDesk 网页客户端：生成脚本、两个小脚本、改了哪些（第 4 章）；console/ 是操控台网页
connector/ 给官端聊天应用的 MCP 连接器和直播卡（第 7 章）
skill/computer-hands/ 给 AI 读的说明书；住在 VPS 上的再读里面的 vps.md（第 6 章）
tools/ 查门、查中继、隧道看门、OpenCLI 的「我来」补丁
site.example.json、deploy/door.example.json 配置的例子。你自己的 site.json、door.json 放进 deploy/，.gitignore 挡着不进仓库
docs/ 上面 0–9 章

先读这段：安全

  • 这是把整台电脑交出去。 拿到门钥匙加 CrossDesk 密码的人，就能看见、点到你的整块屏幕；开了 desk 门的话，拿到桌面钥匙又进得了你 VPS 的人也一样。钥匙别发群、别截图。
  • AI 看到的截图会送到它的服务商那里（Anthropic、OpenAI……）。屏幕上开着什么，它就看得见什么。
  • 「我来」怎么拦：你按下以后，屏幕小程序那把锁就合上，AI 的每一下都会被挡回来；你一碰鼠标键盘，它也会停 4 秒。但本地 Agent 就在这台电脑上，理论上它可以绕开这个小程序，直接调别的命令。拦得住的是这个小程序，拦不住一个想绕路的本机程序。OpenCLI 的后台窗（--window background）也不过这道闸，那里一样登着你的号（第 6 章）。
  • 付款、发帖、删东西：我们的约定是这些永远由人来按。工具上没有替你下单、替你发帖的现成按钮，可 AI 能在你登录着的网页上点，点到「发送」，就等于你发了。

许可证

整个仓库按 LGPL-3.0 发布，跟 CrossDesk 一样。条文在 LICENSE，LGPL 是在 GPL 上加的几条许可，所以 GPL-3.0 的全文也放在 COPYING。

  • 能拿去用、改、商用；把改过的东西发给别人时，改过的部分要照样按 LGPL 公开源码。
  • web/ 底下改过的 CrossDesk 网页客户端：原作者 kunkundi/crossdesk-web-client，本来就是 LGPL-3.0，web/LICENSE 是它原样的那份。改了哪些写在 web/CHANGES.md。
  • tools/opencli-2.0.2-guard/：改的是 OpenCLI 的三个文件，那几份照它原来的 Apache-2.0。
  • CrossDesk 主机端和信令：没改，请从上游下载：crossdesk、crossdesk-server（都是 LGPL-3.0）。

作者

Sylvia，Kael，Codex