dsh-plugin-qr-connect

dsh plugin --profile web add dsh-plugin-qr-connect

dsh-plugin-qr-connect

<p align="center">

<a href="https://github.com/mervyn-teo/dsh-plugin-qr-connect">

<img src="assets/banner.png" alt="dsh-plugin-qr-connect 横幅 — 扫码即可让任意设备连接到你的 DeepSeek Harness Web UI" width="100%">

</a>

</p>

[English](README.md) | 中文

一个 DeepSeek Harness（DSH）Web

插件：在侧边栏底部「设置」按钮上方添加一个 二维码按钮。它运行一个小型、

带鉴权的反向代理，让同一网络（或公网）上的手机扫码后安全地打开 Web UI。它是

一个持久化的 bundle 插件（Host 半边 + 浏览器半边），每次启动都会自动加载。

演示

<p align="center">

<img src="assets/demo-v2.gif" alt="dsh-plugin-qr-connect 演示 — 点击二维码按钮、扫码、连接" width="360">

</p>

功能

• 添加一个全宽按钮（sidebar.footer.action，id qr-connect），堆叠在官方

「插件」按钮上方。

• 点击后打开一个淡入淡出的面板，显示 两个 二维码：
• 本地网络 — http://<局域网 IP>:<端口>/?auth=<密钥>。
• 公网 — http://<公网 IP>:<端口>/?auth=<密钥>（蓝色）。
• 反向代理（一个监听 0.0.0.0:<端口> 的 node 子进程）校验密钥，签发会话

Cookie（默认 30 天），然后转发到回环 Web UI —— 包括 WebSocket 升级，使实时

更新也能同步到手机。

• 密钥默认每 30 秒轮换一次，二维码同步刷新（可配置，0 表示关闭自动刷新）。
• 点击二维码复制对应链接；公网二维码带有信息提示（悬浮显示「仅在端口转发后可用」）。
• 在 设置 → 插件 中提供 QR connect 配置卡片，可设置代理端口、会话时长、

刷新间隔。

• 通过 DSH 的 locale 服务支持英文与中文界面。

文件

文件 · 用途

lib/index.js · Host 半边 —— 运行反向代理与 /__qr/* 状态路由。

lib/client.js · 浏览器半边 —— 二维码按钮与配置卡片。

lib/proxy.cjs · 带鉴权的反向代理子进程（HTTP + WebSocket）。

cordis.patch.yml · 插入插件行的组合补丁。

package.json · 包元数据（dsh.bundle + dsh.client 清单）。

安装

dsh plugin --profile web add github:mervyn-teo/dsh-plugin-qr-connect

然后重启 dsh web —— Host bundle 在启动时加载。

默认配置在 cordis.patch.yml（port、sessionDays、refreshSeconds、publicHost）。可在

那里（或 profile 自带的 cordis.patch.yml）修改后重启，或在运行时通过配置卡片

调整。publicHost 是公网二维码使用的自定义域名或 IP，代替自动检测的公网 IP

（支持 host、host:port 或完整的 https:// 源；留空则自动检测）。Host 半边提供三个同源路由供浏览器半边使用：GET /__qr/info、

POST /__qr/rotate 与 GET|POST /__qr/config。

依赖

• DSH 需要挂载 subprocess、fs、webServer 服务。
• DSH 宿主能访问公网以查询公网 IP（https://api.ipify.org）。
• 扫码设备需要能访问代理端口（宿主机防火墙可能需要放行）；公网二维码还需要

公网可访问（端口转发）。

本地 IP 与公网 IP 的探测在进程内完成（不再依赖 ip/curl/shell 命令），手动

轮换密钥通过子进程 stdin 通知，因此 Host 半边可在 Windows、macOS、Linux 上运行。

安全

该代理会把完整的 agent shell 暴露给任何能访问该端口的设备，仅靠 30 秒密钥和

会话 Cookie 保护。请使用较短的会话时长，将其视为可信网络内的便利工具，而不是

强化的远程访问层。

许可证

[MIT](LICENSE)