远程扫码配对 neutron42-jp/dsh-remote-qr

rdsh-remote-link

一个 DeepSeek Harness 插件：侧边栏底部加一个按钮，显示这个 Web GUI 的带 token 的 URL 和二维码，手机或另一台设备扫码即可配对，不用再手敲启动 token。

任何 Web 配置档都能用。URL 完全取自 Host 对外公布的值——不写死主机、端口、协议或路径。

桌面端的面板

要解决的问题

dsh web 启动时只打印一次 http://host:port/?token=…。终端一滚，这行 URL 就没了；在手机上敲它更是受罪；而且它写的主机名，手机往往根本连不上，因为桌面端是通过 localhost 打开的。

它做什么

| 部分 | 职责 |
| Host（index.js） | 提供 GET /api/remote-link，返回 { url, source, warning?, svg }。URL 来自 ctx.connection.authenticatedUrl(<root>)——和 dsh web 打印、打开 URL 用的是同一个调用——二维码就是该 URL 的 SVG。 |
| 浏览器（client.js） | 在 sidebar.footer.action 里注册一个操作，紧挨着 Settings；面板挂在 shell.overlay。每次打开都重新拉取，按 Escape 或点面板外关闭。 |

浏览器支持 Popover API 时，面板会提升到顶层，因此不会被侧边栏那一列裁掉，也不会压在移动端抽屉下面。

二维码只对不显示它的那台设备有用，所以面板在 760px 以下隐藏二维码：手机拿到 URL 和复制按钮，桌面端拿到给手机扫的二维码。

它就在侧边栏底部，紧挨着 Settings：

侧边栏底部的操作

安装

把这个目录作为 bundle 装进提供 Web UI 的配置档——Settings → Plugins，或者在智能体会话里用 plugin_manager（install_bundle，target 填这个目录）。装完不用重启就生效；如果那一行没激活，把 bundle 开关切一次。

没有依赖：二维码编码器已内置。

它给出哪个 URL

根地址按下面的顺序选取，响应里的 source 会说明命中了哪条规则：

| 部署情况 | 根地址 |
| config.publicUrl | 取该值，规范化成以 / 结尾 |
| --public-url，或任何非回环的对外公布根地址 | 原样使用该 URL——协议、端口、挂载路径都保留 |
| 监听器绑定在 LAN 或 Tailnet 地址 | 监听器的 origin |
| 回环监听器，且带 --trusted-host | tailscale status --json → Self.DNSName，加上监听器端口和协议 |
| 回环，且没有 trusted hosts | 回环 origin，外加 loopbackOnly 警告；绝不运行 tailscale |
| Tailscale 缺失或执行失败 | 回环 origin，外加 tailscaleUnavailable 警告 |

config.publicUrl 是可选的配置档行配置字符串，用于外部根地址既不是对外公布的那个、也不是 Tailscale 名字的部署。它没有 schema，所以在请求时校验，不可用就忽略并打一条控制台警告。

关于 token

- Host 为每个进程签发一个启动 token。插件从不存储、记录或缓存它：每次打开都请求新的已认证 URL，响应带 cache-control: no-store。
- 打开 URL 一次，就用 token 换一个签名 cookie（默认 30 天），绑定到该主机名和端口，然后重定向到干净 URL。扫过一次的设备重启后仍保持会话。
- 路由位于 Connection 的浏览器认证围栏内，精确 Fetch 路由拒绝非所有者对端，所以 liveshare 查看者读不到 token。
- 从不改写当前 origin：如果桌面端打开的是 http://127.0.0.1:3080，而部署对外宣告 https://dsh.example.com，二维码携带后者。

要求

- Web 配置档：插件注入 connection、webApp 和 webServer，其他配置档下插件保持不激活。
- 任意当前版本的 Chromium、Safari 17+ 或 Firefox 125+，用于顶层堆叠。旧引擎把面板留在 shell.overlay 内：仍不被裁剪，但手机抽屉会盖在它上面。

测试

npm test

覆盖上面的部署矩阵（包括挂载前缀、scheme 保留、IPv6 回环、TLS 监听器，以及缺少 tailscale 的情况）、路由形状，以及二维码编码的是带 token 的 URL。

安全

URL 就是持有者凭证。看到二维码的人都能以所有者身份登录，直到 cookie 过期，所以对待截图和屏幕共享要像对待密码一样。

明文 HTTP 会在网络上暴露 token 和 cookie；在监听器上终止 TLS（--tls-cert），或把流量留在 Tailscale、WireGuard 这类私有网络内。

许可证

MIT。vendor/qrcode.js 是 qrcode-svg 1.1.0（MIT），本身源自 Kazuhiko Arase 的 "QRCode for JavaScript"；见 vendor/LICENSE-qrcode-svg。