前言¶

DSH（DeepSeek Harness）採用插件化架構，默認以本地模式運行。在開發調試或演示場景下，有時需要在手機端預覽 WebUI 效果。由於 DSH 默認不開放局域網訪問，直接通過瀏覽器訪問本地端口通常受限於安全策略或網絡隔離。下面介紹 hw-cola/dsh-remote-control 插件，它通過反向代理和二維碼授權機制，將本地 DSH WebUI 暴露給局域網設備。

簡介¶

這是一個 DSH 客戶端插件，用於手機遠程控制。

由 hw-cola 維護，基於 MIT 協議開源。插件通過啓動一個獨立的 Node 子進程監聽局域網端口，將流量轉發到本地 DSH 服務。核心功能是在設置面板增加「遠程控制」頁，支持自動探測局域網 IP、生成二維碼、掃碼驗籤以及設備白名單管理。

核心功能¶

設置面板與局域網探測¶

安裝後，DSH 設置面板會新增「遠程控制」頁（僅電腦端顯示）。

1. 開啓開關：點擊「允許局域網訪問」開關，插件會自動探測並列出本機的局域網 IPv4 地址。
2. 多網卡切換：當存在多個網卡時，用戶可以在列表中切換選中的 IP 地址。
3. 二維碼生成：二維碼隨選中地址實時生成。插件內置純 JS QR 編碼器（Byte 模式、ECC-M、版本 1~10），無第三方依賴，支持離線使用。
4. 自動刷新：二維碼每 60 秒自動刷新，舊碼立即失效，防止中間人重放攻擊。

掃碼驗籤與安全攔截¶

爲了防止未授權的局域網訪問，插件實現了嚴格的驗籤機制。

1. 掃碼授權：非本機來源（非 127.0.0.1 或 localhost）訪問必須先掃碼。二維碼 URL 攜帶一次性驗籤 token（?rcnt_t=<token>）。Token 校驗通過後，服務端會簽發 rcnt_auth Cookie 並跳轉到乾淨地址。
2. Cookie 有效期：已授權設備憑 Cookie 持續訪問，最長有效期爲 7 天。
3. 403 攔截：未授權直接訪問會返回 403 提示頁，且插件會攔截 WebSocket 握手，確保無法建立連接。
4. 本機訪問：本機使用 localhost 或 127.0.0.1 訪問不受影響，直連 DSH；本機使用局域網 IP 訪問同樣需要掃碼（因爲來源非迴環，屬於「非本機」訪問）。
5. 白名單機制：支持最多 32 臺設備的白名單管理。白名單持久化在 ~/.dsh/remote-control/devices.json。顯示設備名（按 User-Agent 解析）、IP、授權與最近活躍時間，支持單獨移除。

代理與兼容性處理¶

1. 反向代理：獨立 Node 子進程監聽 0.0.0.0:<端口>，將請求轉發到 127.0.0.1:<端口>，並將 Host/Origin 頭改寫爲迴環地址，以繞過 DSH 的瀏覽器信任籬笆。
2. 非安全上下文：手機訪問通常處於非安全上下文（HTTP），crypto.randomUUID 不可用。代理會在 HTML 響應中自動注入 polyfill。
3. Windows 防火牆：在 Windows 下，開啓時會自動創建並複用名爲「DSH Remote Control」的入站 TCP 規則，無需手動配置。

安裝與啓用¶

安裝命令¶

安裝依賴 pnpm 和 DSH 後，執行以下命令：

dsh plugin --profile web add "git+https://github.com/hw-cola/dsh-remote-control.git"

若需釘到指定版本：

dsh plugin --profile web add "git+https://github.com/hw-cola/dsh-remote-control.git#v1.0.0"

本地開發模式：

dsh plugin --profile web add "link:${PATH}/dsh-remote-control"

啓動與刷新¶

安裝完成後，必須重啓 dsh web 以便插件的 cordis 補丁層生效。隨後刷新瀏覽器頁面，設置面板中即可看到「遠程控制」頁。

注意事項¶

1. 安全性：通信仍是 HTTP 明文，同網段可嗅探 token 或 Cookie。已授權設備之間等價共享訪問權。DSH WebUI 本身無登錄認證，請僅在可信網絡中使用，用畢務必關閉開關。
2. 數據持久化：開關狀態僅存於宿主進程內存，重啓 dsh 後默認關閉；但設備白名單持久化在 ~/.dsh/remote-control/devices.json，重啓後已授權設備免重新掃碼。
3. 卸載清理：卸載會終止代理子進程。設備白名單文件不會自動刪除，需要時請手動清理該文件。
4. 兼容性：插件在 DSH 0.1.1-rc.2 上開發測試。客戶端 API 仍在迭代，大版本升級後若功能異常，請檢查倉庫是否有適配版本。

總結¶

該插件解決了 DSH 本地開發中無法在手機端直接訪問的問題。通過掃碼授權和二維碼刷新機制，在提供便利的同時限制了未授權訪問。使用時需注意網絡環境的安全性與白名單文件的管理。