Saltar al contenido principal
K

dsh-link

k-w7/dsh-link

Continúa en el teléfono una sesión de DSH de escritorio: chatea, observa la salida en vivo y recibe el resultado en el móvil cuando termina un turno en el escritorio.

Instalar

dsh plugin --profile web add github:k-w7/dsh-link

README

在同一局域网里,把手机上的 DSH 和电脑上的 DSH 直连起来。 手机接着用电脑的会话、看实时输出;电脑每轮跑完把结果推回手机;电脑还能把新版本插件直接推到手机──无隧道、无第三方域名、无公网中继。

  • 手机端不另开模型:直接驱动电脑上那一台,模型、工作区、文件都在电脑那边;
  • 流量只走局域网(跨网络可选 DDNS,见下文);
  • 一个包,两端都装:启动时读 <DSH_HOME>/dsh-remote/role.json 的 role,只加载对应那一半实现。

当前版本 0.22.0。

它是什么、不是什么

是不是
手机 ↔ 电脑 的局域网直连桥远程桌面 / 投屏
手机接着用电脑的 DSH 会话手机自己跑模型推理
自签证书 + 指纹 pin 的加密链路依赖任何第三方账号或云端
每轮结束把结果推回手机全量会话云同步

工作原理

  1. 配对:手机先发起,电脑弹卡片确认(卡上 6 位数字与手机端一致)。确认后手机进入设备白名单,拿到一把 pairKey 用于反向通道。
  2. 通道:两端各起一个 TLS 网关(电脑 8899 / 手机 8898),自签证书 + 指纹 pin,不信任系统 CA。手机 → 电脑走 RPC 与 SSE 实时流;电脑 → 手机走 agent-message / plugin-install,凭 x-link-key + 时间戳 + 一次性 nonce。
  3. 打开会话(0.20.7 起):联机时同步会话一律走远端流──先取电脑的历史快照,再纯转发电脑的实时事件;本地镜像只在断线时兜底。这样不会出现「本地镜像半截 → 官方读盘判损坏 → 历史加载失败」。
  4. 自动同步(autosync):每 syncIntervalMs(缺省 10 秒,最小 5 秒)拉一次电脑的会话清单,把新出现、非空白、非归档的会话登记到手机侧边栏。基线只记真正建成的 id;逐条失败进退避表(10s → 10min)并上报,不会一次失败就永久拉黑。

所有运行时数据都在 <DSH_HOME>/dsh-remote/(默认 ~/.dsh/dsh-remote/),不进仓库、不上传。

安装

两端装同一版本(跨版本时反向通道可能因协议差异 401):

# 电脑、手机各一次
dsh plugin add @k-w7/dsh-link@0.21.1

# 离线也可以
dsh plugin add --offline file:k-w7-dsh-link-0.21.1.tgz

# 确认/写角色:电脑 desktop,手机 mobile
#   <DSH_HOME>/dsh-remote/role.json → {"role": "desktop"}
#   <DSH_HOME>/dsh-remote/role.json → {"role": "mobile"}

# 重启 DSH

首次启动按平台预填角色(Windows / macOS → desktop,其余 → mobile),可随时改;也可用插件配置 { role } 或环境变量 DSH_LINK_ROLE 覆盖。

配对(只做一次)

  1. 电脑:设置 → 局域互联,确认监听地址与端口(默认 0.0.0.0:8899);
  2. 手机:设置 → 局域互联 → 填电脑局域网 IP 与端口 → 「测试连接」(显示证书指纹前 8 位与耗时)→「保存并连接」;
  3. 电脑弹出确认卡片:卡上 6 位数字应与手机端一致,核对后点「允许」;
  4. 手机状态变为「已连接」,电脑勾选的工作区自动同步过来。

提示「电脑不认识这台手机」= 不在白名单里,重走第 2~3 步。

日常用法

  • 接续电脑会话:手机打开电脑页签,选工作区/会话直接发消息,实时看输出。

  • 回合结束通知:只回投手机发起的那一轮;触发条件(每轮 / 仅出错 / 仅长任务)与保留天数在 设置 → 局域互联 → 通知推送 里配。

  • 手机 → 电脑 主动推消息(给 agent / 本机调用方,无 UI):

    POST /api/dsh-remote/rpc          // 手机本地宿主桥(同源)
    { "method": "sendToDesktop", "params": { "text": "把今天的报告发我", "sessionId": "…(可选)" } }
    // { "ok": true, "sessionId": "…" } 或 { "ok": false, "error": "…" }
    
  • 电脑给手机装 / 升级插件:

    node <profile>/node_modules/@k-w7/dsh-link/scripts/link-install.mjs <插件.tgz>
    # 也可显式指定 --url https://<手机>:8898 与 --key <pairKey>
    

    手机会弹一张确认卡(必须人工点「允许」),装完返回 requiresRestart: true,重启手机 DSH 才生效。

    • 0.20.0 起确认不再依赖「活着的运行时根 agent」:没有 agent 时改走手机界面上的确认条;只有当手机界面一个订阅者都没有(App 不在前台/没加载)时才回 503 no-confirm-channel。
    • 收包端支持 scope 包名(@scope/name),inbox 与 backups 目录不会因为 / 拼不出来而 ENOENT。
  • 手机给电脑推插件:手机装了比电脑新的版本时,会自动把包推给电脑换装(电脑重启后生效)。

会话同步模型(0.21.x)

场景行为
联机 + 打开某个同步会话走远端流:取电脑历史快照 + 转发电脑实时事件,不读本地镜像
断线 + 打开同步会话回退读本地镜像(所以离线时能否看历史取决于镜像是否完整)
新会话出现autosync 每 10 秒拉清单导入;空白会话(还没说话)不导入,等它有内容后自然进来
电脑侧归档手机侧跟着归档;电脑清单为空时不做减法(避免瞬时失败把整批会话清空)
本地镜像坏了命中 corrupt / SessionFormatError 时把旧日志改名隔离(不删,可还原)再重建

0.20.9 / 0.21.1 起,联机时不再往本地镜像搬历史(drainPreloadQueue 与 growMirrors 都已停)。原因:手写事件搬运过不了官方 v4 surface 校验(真机:写入 2000+ 条后仍报 SessionFormatError: system/…),只会反复「写坏 → 隔离 → 重建」,白耗流量。代价是断线时看不了历史,本来也看不了。

诊断与日志

位置内容
<DSH_HOME>/dsh-remote/desktop-debug.log(电脑)网关/通知/权限卡,以及 RPC 追踪:`rpc <方法>
<DSH_HOME>/dsh-remote/phone-diag.jsonl(电脑)手机每 5 分钟推来的一条现场快照:paths / workspaceMap / baselines 计数 / synced / remote / 最近 10 行手机日志。不插 USB 也能查手机侧
手机 App 沙箱 …/dsh-remote/mobile-debug.log手机端完整日志;只有 hdc 读得到

常用判读:

# 手机问过什么、电脑回了什么
Get-Content ~/.dsh/dsh-remote/desktop-debug.log -Tail 200 | Select-String ' rpc '
# 手机侧现场(每 5 分钟一条)
Get-Content ~/.dsh/dsh-remote/phone-diag.jsonl -Tail 1 | ConvertFrom-Json | Select-Object at,reason,synced,remote

配置

文件(<DSH_HOME>/dsh-remote/)用途
role.json本机角色:desktop / mobile
link.json网关:port / listen / upstreamPort / addressFamily / allowGlobal / discovery / ddns;同步节奏:syncIntervalMs(缺省 10s、最小 5s)、memsyncIntervalMs(记忆同步,缺省 30s、最小 10s)
link-peer.json(电脑)反向通道:url / key / certFp;link-install 与通知共用
link-client.json(手机)电脑地址信任:certFp / allowHost / allowSelfSigned
mobile.json(手机)电脑端点、设备身份、notifyTargetSession、resolveSources
devices.json(电脑)设备白名单(含 deviceKey,不要提交、不要外传)
setup.json(电脑)sessionSync 策略(scope / newSync / delSync / keepDays)、共享工作区列表
autosync.json(手机)每个电脑目录的基线 id 列表与失败退避表(baselines / retry)
phone-diag.jsonl(电脑)手机诊断快照(2 MB 轮转一次)

端口:电脑网关 8899、手机网关 8898、本机中继 17890(电脑)/ 本机 DSH 3120(手机)、局域网发现 UDP 8897。

网络选项

  • 地址族:ipv4(默认)/ dual / ipv6。IPv6 无 NAT,全局地址默认不监听、不写进证书;要暴露必须显式开 allowGlobal(日志会告警)。
  • 自动发现:同网段点「自动查找」即可找到电脑(UDP 广播);找到 ≠ 信任,仍要走配对与 pin。广播不过路由器。
  • 跨网络(可选):电脑把当前地址写到你自己的服务器(ddns),手机从 resolveSources 读回来。必须 https。

安全边界

接触面门槛说明
GET /link/ping无只回 {ok,name,ver,fp},供「测试连接」用
反代路径电脑:设备白名单 + HMAC;手机:回环放行,非回环必须 x-link-key + 时间戳 + nonce验不过一律 403
POST /link/claim手机发起 + 电脑卡片确认桌面端确认只允许本机回环调用
电脑 → 手机通道x-link-key + 时间戳 + 一次性 noncenonce 缺失 401、重放 401
电脑 → 手机装插件同上 + 手机人工确认没有订阅者时 fail-closed 回 503

取舍:自签证书 + 指纹 pin(TOFU)不用 CA;未 pin 就不发(不发比发错人好);listDirectory 可浏览全盘但列不出 $DSH_HOME 后代与 .ssh/.aws/AppData 一类凭据目录;证书 SAN 漂移只告警不自动重签。

刻意不做的事

  • 不做公网中继 / 第三方隧道服务(跨网络只支持写到你自己的服务器);
  • 不要求注册外部账号;
  • 不做虚拟组网(Tailscale / WireGuard 那一类);
  • 不做网络层门禁(防火墙、单包授权属于系统与路由器);
  • 不做云端同步与托管。

排障速查

现象原因处理
手机连不上不同网段 / 端口被占确认同一局域网;看电脑日志 监听失败 … EADDRINUSE
「电脑不认识这台手机」不在白名单手机重新配对,电脑点「允许」
推插件回 503 no-confirm-channel手机界面没有订阅者(App 不在前台)打开手机 DSH 停在任意会话再推;确认卡必须人工点「允许」
推插件回 401两端版本不一致(旧版不带 nonce)两端升到同一版本
会话里「历史加载失败」本地镜像是空壳/损坏,而联机远端流没走起来确认已连电脑(follow 拦截 … fromRemote=true 应出现在手机日志);升级到 ≥0.20.7
会话显示成「(未命名对话)」电脑侧那条会话本来没标题0.20.1 起占位文案不再写进本地日志;正常会显示官方「未命名」
通知不推送该轮不是手机发起的 / 没指定回投会话 / notify=false看电脑日志 notify 跳过(…) 的具体原因
一律 401两端版本不一致两端升到同一版本

开发与测试

npm test        # 语法检查 + 行为自检(10 组,全绿才算过)
npm run build   # 由 lib/mobile/client.js 重建包内 chunk(lib/client.mobile.js)
  • lib/client.js 必须是经典脚本 bundle(不能写 import);手机 UI 是包内 chunk,由 scripts/build-client-chunk.mjs 生成。
  • tests/session-sync.mjs / tests/plugin-install-confirm.mjs 是静态守卫:钉住「基线只记成功 id」「诊断不依赖 run()」「空壳走远端流」「收包端 scope 名」这些一改就丢会话的行为。
  • 发版:npm publish(scope @k-w7)。注意 pnpm publish 会假成功(2FA 下只 staged),要用官方 npm CLI + NODE_AUTH_TOKEN。

版本历史

版本变更
0.21.1联机时 growMirrors(启动补深)也停掉,不再白写坏镜像。
0.21.0插件安装确认卡按官方提问卡规格重排(20px 圆角 / elevation-panel 阴影 / 11px 眉标 / 16px 标题 / 整行 40px 选项)。
0.20.9联机时停掉本地镜像历史搬运(drainPreloadQueue),不再「写坏 → 隔离 → 重建」循环。
0.20.7联机时同步会话一律走远端流(快照 + 纯转发 SSE),本地镜像只作离线兜底。
0.20.5打开镜像前先补历史(2.5s 上限);corrupt 命中隔离重建一次;no-window 有限重试。
0.20.4listWorkspaceSessions 补上「cwd 命中但没挂在工作区」的会话(非 subagent)。
0.20.3收包端支持 scope 包名(inbox/@k-w7/… ENOENT)。
0.20.2诊断快照改独立定时器(run() 提前 return 时也能上报)。
0.20.1会话同步修复:基线只记成功 id + 退避表、blank 不进基线、原子写、in-flight 锁、空清单护栏;标题走官方 sessionTitle;新增 RPC 追踪与 linkDiag 诊断。
0.20.0电脑推插件不再依赖「活着的运行时根 agent」:改走手机界面确认条(SSE plugin-install-request + RPC answerPluginInstall)。
0.19.0包名迁到组织:@klrsl/dsh-link → @k-w7/dsh-link(收包白名单同时认新旧名)。
0.18.38对端地址自动跟随 DHCP(devices.json 的 lastIp);setup.json 的 host 跟随本机 IPv4。
0.18.36局域网直连主链路:两段式配对、设备白名单 + HMAC + nonce、IPv6/双栈、发现、DDNS、通知回投、sendToDesktop、插件双向分发、记忆同步、会话镜像。
0.18.37同步节奏改成「连上就同步」:autosync 缺省 10s、memsync 缺省 30s,均可配。
0.18.x稳定性收口:seq 平移与预载、镜像唤醒、归档处理、标题三级回落、pairKey 自愈。
0.2.0首次连接配置向导、工作区多选与四档隐藏策略、配对状态轮询;UI 去渐变/毛玻璃/emoji。
0.1.4手机 → 电脑 agentMessage / sendToDesktop;通知回投目标 notifyTargetSession。
0.1.2通知重试;手机端 /link/plugin-install 与 scripts/link-install.mjs。
0.1.0单包:desktop/mobile 按 role.json 分半加载。

来源与许可

MIT。衍生自 pht88888888/dsh-jiuling-remote-plugins(MIT),保留原作者版权;在此基础上移除公网隧道链路,改为局域网 TLS 直连,并补齐双向唤醒、通知、设备白名单与插件分发。

Plugins relacionados