Skip to content

dsh-wire

Verified

dsh-wire · v0.7.5 · MIT · Web UI

把电脑上的 DSH 会话接到手机:手机直连电脑读取真实会话,不做本地镜像。公网只传文本。

Install

dsh plugin add dsh-wire

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Readme

dsh-wire

把电脑上的 DSH 会话接到手机上:手机直连电脑读真实会话,不在本地复制一份对话。

一个 npm 包,两端同装。电脑端负责把会话暴露出去(配 Cloudflare 快速隧道), 手机端负责把「远程会话」透明地接到本机的会话服务上。


为什么不用「本地镜像」

旧的远程方案是在手机上真的建一个会话、把电脑的事件抄进去。这条路必然脆弱:

  • 抄写的一方要额外维护 seq 对齐与 turn 闭合;
  • 只要有一行不符合引擎的 v4 格式,dsh-session-format-v3-to-v4 的读取侧只重抛、不恢复, 整条会话就再也读不出来(表现为「会话从列表里消失」);
  • 于是每修一个 bug 就加一层补偿逻辑,bug 只会越修越多。

dsh-wire 换一条路:手机端不持有会话数据。

镜像方案 dsh-wire
手机上的会话数据 自己维护一份副本 没有副本
seq 对齐 必须校准 不存在
turn 闭合 必须保证 不存在
写坏风险 会损坏会话列表 无盘可写
断线重连 要判断"我缺了哪几条" 重新问电脑要即可

实现上就是一层薄代理:认得出远程 sessionId,把 list / read / prompt 转发给电脑; 其它 id 原样透传,本地会话的行为一点不变。


安装

电脑和手机各装一次,用 DSH 自己的插件命令(全局 npm i -g 装进去不会被加载):

dsh plugin --profile web add [email protected]

⚠️ 一定要带版本号。只写包名时 pnpm 会命中本地缓存,装到旧版本, 表现为"升级了但行为没变"。

装完重启 DSH,插件会作为 profile 层自动加载(0.1.1 起声明了 dsh.bundle,0.2.4 起提问与权限申请都能转到手机; 更早的版本只会被当成普通依赖,装进去也不生效)。

两端必须是同一个版本——协议版本不一致时会在 hello 阶段明确拒连,而不是"尽力兼容"。


配对(不用碰配置文件)

装完不需要改任何配置文件。 两端各自重启 DSH,插件会自己判断自己是电脑还是手机、 自己连默认中转,电脑端直接生成配对码。想自建中转才需要写配置(见下)。

重启后打开 设置 → 远程配对:

  1. 电脑上:页面直接显示 6 位配对码,点一下即可复制。码 5 分钟有效,过期点「重新生成配对码」。
  2. 手机上:在同一个页面输入这 6 位,点「连接」。

连上后手机端立刻出现电脑上的会话,两端都不用重启。页面会实时显示手机是否在线、 隧道地址、中转地址和本机端口——出问题时不用再去翻日志。

手写配置文件依然可用(见下),但一般不需要。


配置

配置文件在 ~/.dsh/dsh-wire/config.json(也可以写在插件的内联配置里,优先级更高)。

电脑端

{
	"role": "desktop",
	"rendezvous": "https://wire.example.com",
	"cloudflared": "cloudflared"
}
  • rendezvous:中转服务地址,用来让手机在隧道域名变化后找到你。
  • cloudflared:可执行文件路径,留空则走 PATH。

启动后会:

  1. 在 127.0.0.1 上起一个随机端口的 HTTP 服务;
  2. 拉起 cloudflared tunnel --url ... 拿到 https://xxx.trycloudflare.com;
  3. 把地址登记到中转,首次登记会生成 6 位配对码(5 分钟内有效,用后即焚);
  4. 隧道重启导致域名变化时自动续约,不需要人工干预。

配对码会打印到日志,也写在 ~/.dsh/dsh-wire/pairing.json。

手机端

{
	"role": "mobile",
	"rendezvous": "https://wire.example.com",
	"pairCode": "ABCDEF"
}

首次配对用 pairCode;配对成功后换发长期凭据,pairCode 可以删掉。 之后每次启动只做一次 resolve 拿当前地址,域名怎么变都不用管。

局域网调试可以跳过中转,直接写:

{
	"role": "mobile",
	"desktopOrigin": "http://192.168.1.10:12345",
	"desktopToken": "<电脑端 ~/.dsh/dsh-wire/token.txt 的内容>"
}

部署中转服务

中转是一台固定地址的小服务,只保存 设备 → 当前隧道地址 的映射, 不转发、不存储任何会话内容。

node server/rendezvous.js --port 18907 --data /var/lib/dsh-wire

建议前面套一层 nginx / Caddy 提供 TLS。健康检查:GET /health。

端点:/register、/resolve、/renew、/heartbeat。 安全措施:配对码 5 分钟一次性、设备令牌只存 sha256 摘要、/resolve 每 IP 每分钟 20 次。


隧道起不来怎么办(两种出路)

公网隧道依赖 cloudflared 这个外部程序,它不是 Node 依赖,npm 装插件不会带上它。 设置页会直接告诉你找没找到:

  • 找到了 — 显示版本和路径,隧道正常。
  • 没找到 — 红色提示 + 一个「下载 cloudflared」按钮。点一下自动下到插件状态目录 (~/.dsh/dsh-wire/bin/),不污染系统,下完自动起隧道,不用重启。 下不到(比如连不上 GitHub)也不要紧,走第二条路。

第二条路:局域网直连。 手机和电脑连同一个 WiFi 时,完全不需要隧道、不需要公网、 不需要中转,也不需要 cloudflared。电脑端「连接信息」里有一整行直连串:

http://192.168.1.5:12345/?t=<令牌>

点一下复制,粘到手机端的输入框里就行。手机端既能填 6 位配对码,也能直接粘这行。

这条路是刻意放在最前面的兜底:隧道能否建立取决于外网、CF 和这个二进制, 而同一 WiFi 下的直连只取决于你的路由器。

关于 Cloudflare 快速隧道的三个事实

官方文档(Quick Tunnels → Limitations)明确写了,本项目的设计直接照它来:

限制 本项目的处理
不支持 SSE 不用 SSE。事件走单通道长轮询,服务端最多挂 25 秒
单隧道 200 个并发请求 一台设备只开一条长轮询,in-flight 恒为 1
没有可用性保证 隧道崩溃自动重启(指数退避),地址变化自动续约
域名每次都变 由中转消除,手机端无感

验证

npm test

55 项,覆盖:

  • 电脑端:鉴权、路由、序列化、长轮询的"有数据立即返回 / 无数据挂起后唤醒"
  • 手机端代理:本地会话原样透传、远程会话转发、未经 list 直接按 id 打开也能命中、卸载后完整还原
  • 端到端:真实 HTTP 服务 + 真实客户端 + 真实代理,验证"手机看到电脑的会话、读到内容、把消息发过去"
  • 中转:配对码一次性、隧道地址变化后凭据解析到新地址、令牌校验、限速
  • 插件装载:apply() 契约、inject 全可选、desktop 角色真的开始监听、mobile 未配置时不破坏本地会话
  • 提问队列:等待、超时、任意 payload(选项答案与审批结论共用一条通道)

除了单测,还在两个真实 DSH 实例 + 真实浏览器上跑通了完整回路: 侧边栏显示远程会话 → 点开加载历史 → 从界面发消息到电脑 (电脑端收到 {sessionId, content:[{type:'text',…}], mode:'followup'})。 过程中的四个真实契约差异见 docs/DESIGN.md 第 7-9 节。


隧道起不来时,它会自己逐项检查

不用再猜。隧道失败后设置页会出现一张检查表,逐项列出结果:

  • cloudflared 二进制(版本、路径、能不能执行)
  • 本机服务是否在正常响应
  • Cloudflare 的域名能不能解析
  • 连不连得上 Cloudflare 的 443
  • 配对中转服务是否可达
  • 有没有设置代理环境变量
  • 系统里有没有残留的 cloudflared 进程

每项都给出「正常 / 注意 / 不通」和对应的下一步,还有「重新检查」按钮。 完整的失败情况清单见 docs/failure-modes.md。

万一角色认错了

插件按平台自动判断"这台是电脑还是手机"(安卓 → 手机端,其余 → 电脑端)。 判断依据是本机路径长什么样,绝大多数情况都对;万一某个安卓发行版没被认出来, 设置页最底下有一行「认错了?点这里换过来」,点一下就会把角色写进配置。 它需要重启 DSH 才生效。

在手机上新建会话,也开在电脑上

手机端是遥控器。电脑上已有的会话,手机上都能打开、发消息、回答问题, 全部在电脑上执行。

你在手机上点「New Session」新建的会话也一样:只要电脑连着,它会自动变成 电脑上的会话,消息交给电脑执行——电脑端会按同一个 id 建出这个会话。

判断依据是「这个会话里还没有真实内容」。如果那个会话已经有你以前在手机上 留下的对话,那就不会被挪走,仍然在手机本地跑——挪了你会看到内容凭空少一截。

手机上没看到新内容?退出会话再点进来

手机端是靠定时拉取拿电脑上的新内容的。发完消息后,如果界面上迟迟没有 变化,退出这个会话、再点进来一次,一定能看到最新进度——所有内容都在 电脑上,手机只是显示得慢一点,消息不会丢。

掉线了会自己回来

  • 手机先开、电脑后开:手机按 5→10→20…→60 秒退避重试,电脑一上线就自动连上,不用回设置页点按钮。
  • 电脑重启换了隧道地址:手机连续几次连不上后自己重新解析地址,不用重新配对。
  • 看不太懂的报错都翻译过了:fetch failed、HTTP 530、ECONNREFUSED 这些不会直接丢给用户, 而是换成「发生了什么 + 最可能的原因 + 现在能做什么」。

提问与权限申请

电脑端的 agent 提问、以及需要提权才能继续的操作,都会推到手机上; 手机不在场时电脑端照常自己处理,两边都不锁死。

  • 选项提问:单选 / 多选,每题都带一个「其他:」自由输入框
  • 跳过:和 DSH 原生 Skip 一致——回一个空选择,模型据此跳过本题继续干活, 不会把控制权交回电脑
  • 权限申请:显示工具名和申请理由,「允许一次 / 拒绝」,决定直接落到 agent
  • 谁先答谁算:两端同时挂起,用户在电脑前就秒答;不在电脑前, 手机上什么时候上线都来得及接手(手机离线时给 10 分钟窗口)
  • 另一端自动收起:本机先答了,手机那张卡会自动消失,不会点了没反应

已知限制

  • 当前版本只支持文本。图片/附件会以事件形式原样下发,但手机端不回传附件。
  • 手机端不缓存会话内容:断网时远程会话不可读(这是"不复制"的代价,也是它不会写坏的原因)。
  • 未接入 rpc.intercept 这层,而是包装服务方法——换来的是不依赖运行期端点命名。