前言¶
在 DeepSeek Harness（DSH）裏跑桌面型 Agent 時，常見情況是：模型在真機上點窗口、輸驗證碼、掃二維碼，你在聊天裏只能看到文字描述，無法確認界面真實狀態，也很難在關鍵時刻代勞一兩步。傳統做法往往是另開端口做遠程桌面，或把憑證暴露給瀏覽器，安全和運維成本都偏高。
下面介紹社區插件 dsh-desktop-view（維護者 soffits，分類：客戶端）。它把 cua-spacesd 生成的桌面流與 Cua 的 Web 查看器，經 DSH 既有登錄與 Web 服務中繼到界面右側；默認只觀看，需要時再「接管 / 歸還」，且不額外開端口或子域。
這是什麼¶
dsh-desktop-view 在 DSH Web UI 中提供 Agent 運行機器的實時畫面與聲音：你能看到、聽到桌面上的操作；在驗證碼、二維碼登錄、意外彈窗等場景下可臨時接管，歸還後 Agent 繼續。流與票據留在服務端，瀏覽器只持有短時中繼票據，並與你的 DSH 登錄綁定。
- 倉庫：soffits/dsh-desktop-view
- 目錄頁：SkillHub 插件條目
- 插件包版本（package.json）：0.2.0；許可證 MIT
核心功能¶
界面入口¶
- 右側邊欄 Desktop 標籤：可從邊欄指引進入，或從會話頭部的 monitor 按鈕進入。
- 全屏頁
/desktop-view/，由你的 DSH 同源提供；適配手機、支持觸摸、可直鏈打開。 - URL 參數
?control=1：直達接管模式。Agent 需要協助時可發送
/desktop-view/?control=1&help=1&session=<其 session id>，歸還控制後可將其喚醒以繼續任務。
觀看與接管¶
- 默認是觀看模式：可見可聽，點擊、按鍵、剪貼板與文件會被拒絕。
- 選擇 Take control 進入接管；Give back 回到觀看。長時間無輸入、或關閉視圖後，接管會自動結束。
- 僅隱藏 Desktop 標籤（切到其他邊欄、摺疊邊欄、換會話）時，接管狀態仍保留；流會暫停，再次打開繼續看。
接管模式下可用能力¶
在持有控制權期間，可使用桌面查看器的完整能力：鼠標、鍵盤與觸摸、屏幕鍵盤、剪貼板同步、拖拽上傳、文件瀏覽與下載、顯示器選擇、縮放；在桌面支持時還可使用麥克風。
與 Agent 的協作¶
插件會向 stateFile 寫入小型 JSON，Agent 在操作桌面前應讀取；每次控制權變化會通知打開該視圖的會話。聊天中會以簡短的 Desktop control 行展示相關提示（取決於 notifyAgent 配置）。
stateFile 示例：
{
"controller": "user",
"since": "2026-11-08T12:00:00.000Z",
"sessionId": "01H…",
"updatedAt": "2026-11-08T12:00:04.120Z"
}
當用戶持有控制權時，controller 爲 "user"；否則爲 null，並可能記錄 lastReason（released、idle、disconnected、replaced、stopped）。驅動桌面的腳本或 Skill 應在 controller 非 null 時讓出操作。
安全要點（README 摘要）¶
- 插件路徑上的請求經 DSH 准入：Host/Origin 圍欄、簽名 Cookie，僅 owner 可訪問。
- cua-spacesd 的 env token 與插件簽發的 viewer 票據不離開 Host 進程；瀏覽器僅持有短時 relay 票據。
- 觀看模式使用只讀 viewer 票據，daemon 側拒絕輸入、剪貼板與文件；同一時刻只有一個視圖持有控制權。
- 插件頁面使用
no-store、無 referrer、嚴格的同源 CSP。
顯示的桌面查看器由運行時的 cua-spacesd 提供（Cua FSL-1.1-MIT）；本插件獨立於 Cua，不包含或再分發該查看器。
環境與依賴¶
安裝前請確認：
| 項 | 要求 |
|---|---|
| DSH | 0.2.2-rc.1 或更高（engines 寫明 dsh >=0.2.2-rc.1 <0.3.0-0） |
| cua-spacesd | 0.12 或更高，與 DSH 同機；DSH 進程能訪問 env token（Cua 桌面鏡像上通常爲 127.0.0.1:3211，token 在 /run/cua/env-token） |
| Node | >= 22（package.json engines） |
| 瀏覽器 | Chrome、Edge、Firefox 或 Safari 17+；移動端支持 iOS Safari 與 Android Chrome |
安裝與啓用¶
官方推薦從 GitHub 直接添加（web profile）：
dsh plugin --profile web add github:soffits/dsh-desktop-view
也可在 DSH Web UI 的插件管理器中添加對應 bundle。添加後需重啓 DSH。
DSH 生態強調「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係，本文安裝步驟以倉庫 README 爲準。
配置項¶
各選項出現在 Web UI 中 desktop-view 插件行的字段裏：
| 配置 | 默認值 | 說明 |
|---|---|---|
endpoint |
http://127.0.0.1:3211 |
cua-spacesd 監聽地址；宜保持 loopback，因該地址會接收 env token |
tokenFile |
/run/cua/env-token |
env token 文件路徑，始終留在服務端 |
maxFps |
30 |
查看器請求幀率；降低可減 CPU 與帶寬 |
clipboard |
true |
接管時是否同步剪貼板 |
filesRoot |
~ |
接管時可瀏覽、上傳、下載的桌面目錄；留空則禁用文件傳輸 |
microphone |
true |
接管且在桌面支持時是否允許向桌面發送麥克風 |
idleSeconds |
120 |
無輸入多少秒後自動從接管回到觀看 |
stateFile |
/tmp/dsh-desktop-view/control.json |
插件寫入控制狀態供 Agent 讀取的路徑 |
notifyAgent |
wake |
控制權變化時如何通知會話：wake / quiet / off（見 README 對喚醒行爲的說明） |
典型用法¶
- 安裝插件並重啓 DSH，確認本機 cua-spacesd 已運行且 token 路徑可達。
- 在 Web UI 打開正在使用桌面的會話，從右側 Desktop 或會話頭 monitor 進入，先以觀看模式確認 Agent 操作。
- 遇到需人工介入的界面時，點擊 Take control，完成驗證碼、登錄或對話框處理；需要剪貼板或文件時，在接管模式下使用同步與上傳/下載（受
clipboard、filesRoot約束）。 - 完成後點擊 Give back，或依賴空閒超時自動歸還；若 Agent 曾發送帶
help=1的鏈接，歸還後按notifyAgent策略可能被喚醒繼續。 - 移動端可直接打開
/desktop-view/或帶?control=1的鏈接，在觸摸環境下完成同樣流程。
適用場景與注意¶
適合誰：在 DSH 上跑依賴真實桌面環境的 Agent（Cua 等），需要在不額外暴露端口的前提下，從瀏覽器觀看、旁聽並在關鍵時刻接管的開發與運維場景。
安裝前建議：
- 插件以當前 DSH 進程權限運行；接管模式下文件與剪貼板能力受配置限制，但仍應對照 源碼與 MIT 許可證 自行評估。
- 僅在與 README 一致的環境中使用：cua-spacesd、DSH 版本與 loopback token 假設不匹配會導致無法拉流或無法簽發票據。
- 自定義 Skill 若會驅動同一桌面，務必週期性讀取
stateFile，在用戶接管期間停止自動化點擊/輸入，避免與用戶爭搶控制權。
結尾¶
dsh-desktop-view 把 Agent 所在機器的視聽流收進 DSH 同源 Web UI：平時觀看，遇事接管，歸還後繼續，並借 DSH 登錄與中繼控制暴露面。若你正在 SkillHub 或 GitHub 檢索客戶端類插件，可用目錄頁 soffits/dsh-desktop-view 跳轉，完整說明與問題反饋見 GitHub 倉庫。
