前言¶

DeepSeek Harness（DSH）的 Web GUI 在桌面端通常以三欄佈局工作。拿到手機上後，會碰到幾個實際問題：三欄外殼擠在小屏裏、原生 browse 對話框不適合遠程、rc.6 的設置與特權 API 被限制在 loopback、http://隧道IP 訪問時瀏覽器缺少 crypto.randomUUID。

@az7627/dsh-mobile-remote 是 az7627 維護的 DSH 插件。它以雙面包方式接入，不改 Harness 源碼、不改 npx 安裝內容，目標是在 ≤760px 視口下把 Web GUI 收成單欄，把目錄選擇、文件管理、終端和設置做成手機可用，並通過 WireGuard 隧道地址提供遠程訪問增強。

這是什麼¶

• npm 包：@az7627/dsh-mobile-remote。npm 包名帶作用域，因爲無作用域的 dsh-mobile-remote 已被他人佔用。
• 維護者：az7627。
• 許可證：MIT。
• 適用範圍：按 DeepSeek Harness 0.1.0-rc.6 的 Web 外殼 DOM 契約實現；核心升級後需重新驗證並隨版本跟進。

核心功能¶

手機佈局與桌面零改動¶

在 ≤760px 視口下，插件把 DSH Web GUI 的三欄外殼收成單欄：

• 側邊欄變爲左滑抽屜，帶遮罩和左上角菜單按鈕。
• details 面板變爲全屏覆蓋層。
• 拖拽把手隱藏。
• 適配 iOS safe-area。
• 輸入框使用 16px，避免移動端聚焦縮放。
• 觸控目標不小於 36px。

桌面端保持原有佈局。所有手機規則收窄在媒體查詢內，桌面佈局與列寬不受影響。

彈窗與浮層手機化¶

真正的模態對話框，例如 primitives Modal 與設置面板，在手機上全屏化，內容區獨立滾動。普通彈層面板，例如菜單、上下文面板，仍保留自己的盒子與背景。

菜單、列表、帶背景陰影的面板等浮層如果出屏，會自動平移到屏幕內。觸發器位置變化時會跟隨重算。抽屜、詳情面板等自帶 transform 動畫的表面不受干擾。資料中說明已實測 320–430px 六檔寬度下，模型選擇菜單始終完整在屏。

預設標籤精簡¶

窄屏下，Agent 預設按鈕只顯示圖標加短標籤：

• 中文：標準 / 極簡 / PTC / 創造
• 英文同理

桌面端保持全稱。

目錄選擇頁重建¶

插件把 Harness 的目錄選擇交互釘爲 Web 目錄頁，並用自研界面取代內置 browse 對話框；宿主 browse 後端保留。

桌面端提供：

• 大對話框
• 左側快捷目錄
• 分欄瀏覽，即 Miller columns
• 四鍵工具欄
• 可點擊麪包屑路徑欄

手機端提供：

• 快捷目錄落地頁
• 單列列表加返回鍵
• 全屏呈現

文件管理¶

側邊欄“設置”上方新增“文件管理”入口，與目錄選擇器共用同一分欄視圖。

文件管理包含這些行爲：

• 每打開一個目錄追加一欄。
• 放不下時，底部橫向滾動條自動定位到最新欄。
• 每欄有獨立滾動條；展開新欄時，原欄滾動位置保持。
• 右鍵菜單支持：重命名、複製、粘貼、刪除、下載、選擇打開方式、複製文件地址、屬性、新建、上傳、刷新、在終端中打開。
• 粘貼時自動加 -copy-2 後綴，避免重名。
• 文本可預覽、編輯並保存。
• 圖片、視頻、音頻可內聯預覽。
• PDF 在新標籤頁打開。
• 未知類型可自定義打開方式。
• 十六進制編輯按 64KB 分窗，上限 8MB。
• 上傳上限 8MB。
• 刪除非空文件夾時二次確認。
• 文件夾屬性顯示遞歸統計的真實大小。
• 隱藏文件以半透明顯示。
• 手機端保留行內觸控按鈕。

瀏覽器內 PTY 終端¶

側邊欄終端按鈕可打開瀏覽器內終端。它使用宿主側 node-pty 會話，Windows 走 ConPTY；客戶端使用 xterm.js 渲染。

支持：

• 行編輯
• ANSI 顏色
• 全屏 TUI 應用
• 終端跟隨視口 fit，並同步 PTY 尺寸
• 輸出爲有界環形緩衝，大小 256KB
• 輪詢間隔 60ms
• 客戶端停止輪詢 10 分鐘後自動殺掉會話，避免 PowerShell 進程泄漏

文件管理右鍵“在終端中打開”可在任意目錄啓動終端。Windows 默認使用 PowerShell（-NoProfile），其他平臺使用 bash。

手機設置頁可用¶

rc.6 對非 loopback 瀏覽器的設置作用域會被釘爲內存持久化，手機上設置頁容易不發請求或整頁空白。

插件在可信遠程會話中把連接句柄的 isLoopback 置真，並對已消費舊值的設置消費者條目做一次 fiber 重應用，讓它們重新綁定到主機持久化傳輸。桌面 loopback 場景不受影響。

非安全上下文修復¶

手機經 http://隧道IP 這類非安全源訪問時，瀏覽器不提供 crypto.randomUUID，可能導致設置、目錄列表、模型、插件、預設等 RPC 調用失敗。

插件啓動時安裝基於 crypto.getRandomValues 的 UUIDv4 回退。crypto.getRandomValues 在任何源都可用，因此可以恢復 crypto.randomUUID 缺失導致的 RPC 調用。

特權 API 解除 loopback 釘死¶

rc.6 會把設置、憑據、Agent 預設、模型發現等方法釘爲僅本機可用，手機上可能出現 403 forbidden。

插件把同源特權調用轉發到自己的 trusted-host 通道；宿主側再以迴環請求交給內置 apiProxy 分發。信任邊界仍是 profile 裏的 trustedHosts，也就是 WireGuard 隧道地址。

遠程增強¶

插件還提供遠程訪問相關增強：

• 斷線重連狀態條。
• 通用設置中的遠程訪問狀態行，包括綁定地址、信任來源、目錄選擇後端、插件版本，手機上可自查。
• PWA 增強：standalone manifest、PNG 圖標、apple-touch-icon。

安裝與啓用¶

先安裝插件，再重啓 Web 服務。

從 npm 安裝：

dsh plugin --profile web add @az7627/dsh-mobile-remote

重啓：

npx @deepseek-ai/dsh web

更新時，重新執行上面的 add 命令即可，pnpm 會安裝最新版。

卸載：

dsh plugin --profile web remove @az7627/dsh-mobile-remote

本地開發可以用 link 安裝：

dsh plugin --profile web add C:\path\to\dsh-mobile-remote

改完源碼後，執行構建並重啓 Web 服務即可，無需重新 add：

pnpm run build
npx @deepseek-ai/dsh web

開發流程：

pnpm install
pnpm run typecheck
pnpm test
pnpm run build

典型用法：WireGuard 手機遠程訪問¶

rc.6 的 webserver 只接受 127.0.0.1 / 0.0.0.0 綁定，且 CLI 有意拒絕 0.0.0.0，因此無法直接把服務綁到 10.66.66.1。遠程訪問採用本機綁定加 WireGuard 地址端口轉發。

先做 profile 配置。profile 文件爲：

~/.dsh/profiles/web/cordis.patch.yml

其中的 web-runtime 配置需要包含隧道地址的 trustedHosts，例如：

10.66.66.1
10.66.66.1:3080

配置後，手機請求才能通過 /api 信任柵欄。

再安裝端口轉發。這一步需要管理員權限：

netsh interface portproxy add v4tov4 listenaddress=10.66.66.1 listenport=3080 connectaddress=127.0.0.1 connectport=3080

最後以本機綁定方式啓動，並在手機上訪問：

http://10.66.66.1:3080

推薦無人值守啓動方式：

pwsh -File scripts\start-dsh-web.ps1 -InstallPortProxy
pwsh -File scripts\start-dsh-web.ps1
pwsh -File scripts\start-dsh-web.ps1 -RegisterStartup

其中：

• -InstallPortProxy：一次安裝端口轉發，需要管理員權限。
• 不帶參數：啓動服務，並檢測接口、端口占用、轉發狀態。
• -RegisterStartup：可選，註冊登錄自啓計劃任務。

典型用法：驗證腳本¶

驗證前先啓動一次性測試實例。這個實例與真實 ~/.dsh 隔離：

pwsh -File scripts\start-test-dsh.ps1

啓動地址：

http://127.0.0.1:3097

針對上面的隔離實例執行實測腳本：

node scripts/verify-mobile.mjs
node scripts/verify-file-manager.mjs http://127.0.0.1:3097
node scripts/verify-terminal.mjs http://127.0.0.1:3097
node scripts/verify-settings-loopback.mjs http://127.0.0.1:3097
node scripts/verify-usage-remote.mjs http://127.0.0.1:3097

清理隔離測試目錄：

pwsh -File scripts\start-test-dsh.ps1 -Remove

經過上面的步驟，可以分別在手機仿真、文件管理、終端、設置 loopback、遠程 usage 信任柵欄上驗證插件行爲。

注意：不要用共享 ~/.dsh 的實例跑驗證腳本。驗證瀏覽器打開會話會觸發加載修復，向真實會話日誌寫入 closers，可能與運行中實例的寫入衝突，造成日誌 seq gap。

適用場景與注意¶

適合這些場景：

• 想在手機上通過 WireGuard 隧道訪問本機 DSH Web GUI。
• 需要手機端可用的目錄選擇、文件管理、終端和設置。
• 希望桌面端佈局保持不變，只在小屏下啓用手機適配。
• 需要在可信遠程會話中調用原本被限制在 loopback 的設置、模型、預設、憑據等特權 API。

使用前需要注意：

• 插件在 dsh 進程權限下運行。安裝前應檢查源碼和 MIT 許可證。
• 信任邊界仍是 profile 中的 trustedHosts，也就是 WireGuard 隧道地址。
• 端口轉發安裝需要管理員權限。
• 文件管理上傳和十六進制編輯都有 8MB 上限。
• 終端輸出環形緩衝爲 256KB，輪詢間隔 60ms。
• 客戶端停止輪詢 10 分鐘後，插件會自動回收終端會話。
• Windows 默認使用 PowerShell（-NoProfile），其他平臺使用 bash。
• npm 包名必須帶作用域：@az7627/dsh-mobile-remote。
• 插件按 0.1.0-rc.6 的 Web 外殼 DOM 契約實現，核心升級後需要重新驗證。

結尾¶

@az7627/dsh-mobile-remote 把手機響應式、目錄選擇、文件管理、瀏覽器內終端、設置修復和 WireGuard 遠程增強放在同一個 DSH 插件裏。安裝後桌面端不受影響，手機端可以通過 WireGuard 隧道地址訪問 DSH Web GUI，並進行目錄瀏覽、文件操作、終端交互和設置查看。

社區目錄：az7627/dsh-mobile-remote

GitHub：az7627/dsh-mobile-remote