dsh-wire
Verifieddsh-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,插件会自己判断自己是电脑还是手机、 自己连默认中转,电脑端直接生成配对码。想自建中转才需要写配置(见下)。
重启后打开 设置 → 远程配对:
- 电脑上:页面直接显示 6 位配对码,点一下即可复制。码 5 分钟有效,过期点「重新生成配对码」。
- 手机上:在同一个页面输入这 6 位,点「连接」。
连上后手机端立刻出现电脑上的会话,两端都不用重启。页面会实时显示手机是否在线、 隧道地址、中转地址和本机端口——出问题时不用再去翻日志。
手写配置文件依然可用(见下),但一般不需要。
配置
配置文件在 ~/.dsh/dsh-wire/config.json(也可以写在插件的内联配置里,优先级更高)。
电脑端
{
"role": "desktop",
"rendezvous": "https://wire.example.com",
"cloudflared": "cloudflared"
}
rendezvous:中转服务地址,用来让手机在隧道域名变化后找到你。cloudflared:可执行文件路径,留空则走PATH。
启动后会:
- 在
127.0.0.1上起一个随机端口的 HTTP 服务; - 拉起
cloudflared tunnel --url ...拿到https://xxx.trycloudflare.com; - 把地址登记到中转,首次登记会生成 6 位配对码(5 分钟内有效,用后即焚);
- 隧道重启导致域名变化时自动续约,不需要人工干预。
配对码会打印到日志,也写在 ~/.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这层,而是包装服务方法——换来的是不依赖运行期端点命名。