前言¶

DSH 的工作區默認是本機目錄。做跨機器開發時，經常出現這樣的需求：模型、Agent、會話和記憶希望留在本機運行和保存，而真正要讀寫的代碼與產物在遠程服務器上。手動用 scp/rsync 來回同步，既容易漏文件，也很難把遠程終端、端口轉發接到 Agent 的能力裏。

wilshi/dsh-ssh-workspace 處理的是這件事：它把服務器目錄通過 SSH/SFTP 映射爲一個受控的本地緩存工作區，並在此基礎上提供衝突安全的雙向同步、遠程終端和端口轉發。插件由 WilShi 維護，許可證爲 MIT。

這是什麼¶

一句話定位：DSH 的 SSH 遠程工作區插件。模型、Agent、會話和記憶繼續運行並保存在本機，服務器目錄通過 SSH/SFTP 映射爲受控的本地緩存工作區。

它針對兩類問題：

1. 讓遠程目錄能像本地工作區一樣被 DSH 採用和打開；
2. 在本地緩存與服務器之間做安全的雙向同步，衝突時不會靜默覆蓋。

插件面向 DSH 0.2.1-rc.5（@deepseek-ai/cordis 4.0.5 / @deepseek-ai/* 0.2.1-rc.5）構建，Node 要求 ^22.19.0 || ^24.0.0。

核心功能¶

以下能力均來自插件 README。

遠程工作區創建¶

有兩個入口：

• 工作區入口：點擊側邊欄「工作區 → +」，或在會話空白頁點擊「選擇工作區」。「添加工作區」會直接打開本插件的創建對話框。對話框左上角的「選擇本機文件夾」可以回到系統目錄選擇器，用來添加普通本地工作區。
• 設置頁入口：打開「設置 → 遠程工作區 → 添加遠程工作區」。

插件佔用 DSH 0.2.1 的 sidebar.workspaces.directoryFlow 和 conversation.hero.workspace.directoryFlow 兩個目錄流插槽，以優先級 -1 遮蔽內置文件夾選擇器，因此上面的「選擇本機文件夾」是保留的回退路徑。

認證方式¶

支持密碼、OpenSSH 私鑰（可帶口令）、本機 SSH Agent，以及系統 OpenSSH 配置。系統模式會複用 ~/.ssh/config、Include、ProxyJump、ProxyCommand、Kerberos 和安全密鑰等現有能力。

密碼、私鑰和口令只會寫入 DSH 憑據服務；普通配置、日誌和安裝包不保存這些內容。

雙向同步與衝突處理¶

• 文件在本地緩存和服務器之間雙向同步，兩側變更都會觸發快速同步；監聽不可用時自動退化爲輪詢。
• 同一文件兩側同時變化時不會靜默覆蓋。設置頁會保留衝突副本，並要求用戶選擇本地版本或服務器版本。
• 穩定文件使用本地快照快速確認，不會在每個輪詢週期重新讀取和哈希整個工作區；舊版本同步清單會在下一次安全同步時自動補齊該快照。
• 上傳、下載和遠端哈希會在傳輸前後複覈文件快照；傳輸途中任一側文件變化時會中止本次文件操作，而不是提交不完整內容。
• 同步發現大量已跟蹤文件可能被刪除時會先暫停，設置頁必須由用戶明確確認後纔會繼續。
• 服務器離線或網絡異常時，後臺同步會逐步延長重試間隔，最長 5 分鐘，避免持續佔用網絡；「立即同步」不受該等待限制。

遠程終端與端口轉發¶

• 側邊卡片終端會自動連接遠程 PTY；普通本地工作區仍使用本機終端。
• 遠端存在 tmux 時，終端在網絡中斷或側邊卡片暫時關閉後會保留並續接輸出，兼容 tmux 1.8 等企業老版本。
• 設置頁可以發現服務器監聽端口和進程名，並一鍵轉發到本機；轉發意圖會保存，客戶端重啓後自動恢復。連接中斷會明確提示，並可一鍵重試或清理。

模型工具與內核¶

• 標準 DSH Agent 可調用 ssh_workspace_run 和 ssh_workspace_sync。
• 內置 Codex / Claude Code 原生內核在 SSH 工作區中使用同名遠程工具執行命令；文件編輯仍落在受控緩存並同步到服務器。

遠端助手¶

遠程助手優先使用服務器上的 Python 3。沒有 Python 3 的 Linux x86_64/arm64 服務器會自動部署隨包原生助手（Go 靜態二進制），不要求管理員安裝依賴。原生助手也不可用時，內置 SSH 會繼續使用純 SFTP 同步。

同步容量與安全邊界¶

同步容量：

• 單文件最大 6GB。
• 單個遠程工作區同步數據總量最大 100GB。
• 單個遠程工作區最多掃描 50,000 個條目。
• 上傳、下載和哈希均採用流式處理，不會把整個大文件一次性讀入內存。

安全邊界：

• 首次連接必須確認服務器主機指紋，後續連接固定該指紋。
• Web 配置 API 僅接受本機同源渲染器請求。
• 默認排除 .git、node_modules 和 .dsh-conflicts。
• 符號鏈接不會被當作普通文件遞歸跟隨。

這些容量邊界是 DSH 客戶端的保護性限制；SSH/SFTP 服務端本身還可能受到磁盤空間、用戶配額、文件系統和管理員策略約束。

安裝與啓用¶

官方安裝命令如下，安裝後需要重啓 dsh web：

dsh plugin --profile web add @wilshi/dsh-ssh-workspace

包內自帶 cordis.patch.yml（bundle patch）。加載器會把宿主側掛成一條 loader 行，瀏覽器側按 dsh.client 聲明注入「設置 → 遠程工作區」和新建遠程工作區流程。

典型用法¶

以下是 README 給出的創建流程。

1. 填寫名稱、服務器地址、SSH 端口、用戶名、服務器目錄和認證方式。
2. 點擊「測試連接」，覈對並固定主機指紋。
3. 點擊「保存並創建工作區」。新工作區會出現在左側工作區列表中。

創建成功後，插件會把本地緩存目錄交給 DSH 採用並打開。

移除連接會刪除公開連接配置、憑據記錄和 DSH 工作區註冊，但故意保留本地緩存，避免誤刪用戶文件。

適用場景與注意¶

適合需要把遠程服務器目錄當作 DSH 工作區使用、且希望在本地保留模型與 Agent 運行環境的開發者。插件對鎖文件、衝突副本、端口轉發和遠程終端都做了處理，適合把 SSH 工作區納入日常開發流。

幾點需要注意：

• 插件以當前 dsh 進程的權限運行；請確認運行 dsh 的賬戶對目標目錄和憑據有訪問權限。
• 安裝第三方插件前應先檢查源碼與許可證，本插件爲 MIT 許可證。
• 插件面向 DSH 0.2.1-rc.5 構建，Node 要求 ^22.19.0 || ^24.0.0；版本不匹配時可能需要覈對兼容性。

結語¶

wilshi/dsh-ssh-workspace 的價值在於把「本地緩存 + 衝突安全同步 + 遠程終端」這三件事打包成一個 DSH 工作區入口，讓遠程服務器目錄可以直接被 Agent 採用。

目錄頁：https://www.skillhub.cn/plugins/WilShi/dsh-ssh-workspace

GitHub：https://github.com/WilShi/dsh-ssh-workspace