DSH 远程隧道云 · 官方客户端插件
@qzsy/dsh-bridge 是 DSH 远程隧道云的官方客户端插件：一条命令把本机 DeepSeek Harness 接入云端隧道，在手机、平板或任意设备上安全远程使用。
- 独立实现：包内所有代码均为本仓库自研（MIT，版权见 LICENSE），不依赖、不包含任何第三方 dsh 隧道插件。
- 独立身份：插件 id/name
qzsy-dsh-bridge、RPC 通道/qzsy-dsh-bridge、设置项与 provide 服务均为本插件命名；数据目录~/.dsh/qzsy-dsh-bridge/，默认本地端口3092（可配置）。 - 轻量：只做 SaaS 隧道 + 本地门禁代理 + 设置面板，不包含 IM 机器人、Cloudflare、自建隧道、多网卡等额外功能。
安装
<name> 换成你的 DSH profile（如 web / desktop）：
dsh plugin --profile <name> add @qzsy/dsh-bridge
安装后在 设置 → 远程访问 打开面板（插件 id 为 qzsy-dsh-bridge，DSH 组件列表会显示本插件而非其它隧道插件）。
绑定设备（接入 DSH 远程隧道云）
无感授权流程（推荐，全程不需要输入设备码、也不需要设本地口令）：
- 面板中确认 SaaS 网关地址：官方云为
wss://dsh.b.nps.qzsyzn.com/_gw/connect（自建部署填自己的网关地址），点「保存网关」。 - 点「立即登录授权」：插件自动申请设备码并在系统浏览器打开
https://<控制面>/device/authorize?code=...。 - 在浏览器登录 SaaS 账号 → 点「授权此设备」→ 回到 DSH 面板。
- 面板会自动轮询并完成绑定，绑定后自动开启隧道，随后出现「显示二维码」按钮。 绑定成功后，面板顶部会出现账号卡片：头像、昵称/邮箱/用户名、剩余时长、本月已用、 累计已用与授权时间；每 60 秒自动刷新，也可手动「刷新」。
- 手机扫码（
https://<控制面>/open/<publicId>）→ 登录 SaaS 账号 → 自动验证隧道归属并签发一次性 ticket，跳转进入本机 DSH。
需要手动输入设备码时，可展开面板「高级：手动设备码 / 局域网口令」，用「获取设备码」走旧流程。 绑定信息（
deviceId/deviceSecret）只保存在本机~/.dsh/qzsy-dsh-bridge/config.json（权限 0600）；面板只显示掩码。解绑会清除本机凭证，设备本身需在控制台吊销。
公网地址形态
- Host（主）：
https://<publicId>.b.nps.qzsyzn.com/—— 多租户生产形态，根路径资源天然隔离。 - Path（兼容）：
https://<平台域名>/<prefix>/t/<publicId>/...—— 单隧道演示/无泛域名环境。
面板会把 Host 路由（存在时）显示为主地址，并同时列出 Path 路由。
手机访问
窄屏（≤ 767px）访问 DSH 时，插件会自动把左侧栏改成抽屉，不需要额外配置：
- 内容区占满屏宽，左上角「菜单」按钮打开会话 / 工作区 / 插件入口；
- 支持手势：左缘向右滑打开、抽屉内向左滑关闭，拖动时跟手，松手吸附；
- 模型切换器在手机上改为底部 sheet：全宽、抓手、遮罩，支持下拉/点遮罩关闭；
- 全面屏自动避开安全区：刘海 / 状态栏 / 底部 home indicator 不遮挡内容；
- 点遮罩、点会话行、按 Esc 或转回桌面宽度都会自动收起；
- 桌面端保持 DSH 原生布局，不受影响。
本地门禁与安全语义
插件会在本机监听一个代理端口（默认 3092），把请求转发给 DSH 本体并注入 DSH 原生
loopback 会话 cookie。来源判定：
| 来源 | 判定 | 结果 |
|---|---|---|
| 物理本机回环 | 连接来自 127.0.0.1 / ::1 且未带隧道标记 | 免认证，享有本机特权 |
| SaaS 隧道 | 携带 x-dsh-internal-tunnel 标记，并带网关注入的 x-qzsy-gate: ts.uid.hmac | 验签通过（HMAC-SHA256、±60 秒）即认证；未验签一律 401，不再要求本地口令 |
| 局域网 / 其它直连 | 非回环且无有效隧道标记 | 需本地口令登录或 ?auth= 令牌换取会话（可选能力） |
/__qzsy_bridge__/loopback-token只对物理回环签发；经隧道访问一律 403。- 隧道访客由网关信任头认证：hello-ack 为每条连接下发随机 32 字节
gate.secret，网关在校验一次性 ticket 且账号为隧道 owner 后附加x-qzsy-gate；插件验签通过即放行，不依赖本地口令。 x-qzsy-gate由网关先剥掉客户端伪造值再附加；插件转发 DSH 前也会剥离该头与隧道标记。- 本地口令是可选的局域网直连能力（面板「高级」里可设置），与 SaaS 扫码进入互不影响；
?auth=固定令牌同样只用于局域网/直连，请只发给可信设备。
配置
配置文件：~/.dsh/qzsy-dsh-bridge/config.json
| 字段 | 默认 | 说明 |
|---|---|---|
port | 3092 | 本地门禁代理端口 |
gatewayUrl | wss://dsh.b.nps.qzsyzn.com/_gw/connect | SaaS 网关地址（也接受 http(s)） |
autoStart | false | 随 DSH 启动自动开启隧道 |
deviceId / deviceSecret | — | 绑定后写入，勿手工复制到其它设备 |
tunnel / routesVersion | — | 云端下发的只读缓存 |
access.token / access.sessionSecret | 自动生成 | 本地访问令牌与会话签名密钥 |
也支持 cordis 配置（见 cordis.example.yml）：port、targetPort、gatewayUrl。
故障排查
| 现象 | 排查 |
|---|---|
| 面板显示「未绑定」 | 确认网关地址可访问；重新点「立即登录授权」，确认浏览器里已点「授权此设备」 |
| 授权页提示设备码无效/过期 | 设备码 10 分钟有效，回面板重新点「立即登录授权」 |
| 开启隧道一直「连接中」 | 检查 wss://.../_gw/connect 是否可直连（公司代理/防火墙可能拦截 WebSocket） |
握手失败 auth_failed / revoked | 设备已吊销或令牌失效：解绑后重新绑定；被吊销需在控制台重新添加设备 |
| 打开公网地址 401 | 隧道来源只认网关 x-qzsy-gate 签名：确认控制台/网关已升级到支持无感授权（hello-ack 下发 gate.secret），并重新扫码获取新 ticket |
| 本机 3092 被占用 | 在 config.json 或 cordis 配置里改 port |
| 请求 502 | DSH 本体不可达：确认 dsh web 在运行，或配置 targetPort |
| WebSocket 打不开 | 确认网关与反代放行 WS Upgrade；插件会透传 ws-open/accept/frame/close |
已知限制（v3.2.0）
getStatus为面板引导接口，免 adminToken，只返回脱敏状态（设备 id/secret 均掩码，不含访问令牌与二维码；openUrl由 /open/ 二次校验归属）。- adminToken 每次进程启动随机生成，只经物理回环
/__qzsy_bridge__/loopback-token签发；重启 DSH 后需重新领取（面板自动完成）。 - 访问口令登录已内置限流（同一 IP 连续 5 次失败锁定 60 秒）；请使用足够强的口令，并只在内网/可信网络暴露本地端口。
- 修改或清除访问口令会轮换会话签名密钥，所有已登录的远程访客会立即失效。
access.token为固定本地令牌（?auth=链接可重复使用），README 已说明泄露处置方式；吊销设备后请解绑并重新绑定以轮换设备密钥。
开发与测试
npm install
node client/build.mjs # 重建 client/client.js
node --test test/*.test.mjs # 全量单测
测试覆盖：v2 握手、心跳与心跳超时、HTTP/SSE/WebSocket 转发、route-update、drain、 4003 吊销终态、断线重连、门禁三类来源、打包身份（全包无第三方包名残留）。
协议与许可
- 控制通道协议 v2 契约见仓库
docs/architecture/saas-tunnel.md，共享类型见packages/tunnel-protocol。 - 本包以 MIT 许可发布，版权归本仓库（qzsy）所有，详见 LICENSE。