前言¶
DSH 通常讓智能體在服務器工作區中讀寫文件。如果目標文件在本機，常見做法是先上傳、複製，或依賴額外的同步方式；DSH 改完之後，還需要把結果回傳到本地。
dsh-local-project 針對這個場景：把本地文件夾導入爲服務器 DSH 工作區，並把 DSH 對服務器鏡像的修改同步回本地文件夾。
這是什麼¶
dsh-local-project 是一個 DSH 插件，由 0xKcyzz 維護，許可證爲 MIT。
它的定位是：用戶在瀏覽器中選擇本地文件夾，DSH 在服務器端創建對應的工作區鏡像；之後 DSH 使用原生工具直接操作服務器鏡像，並把文件改動同步回本地。
核心功能¶
下面介紹已覈實的幾項能力：
- 在「添加工作區」入口選擇本地文件夾，自動上傳並在服務器創建鏡像工作區。
- DSH 使用原生
read、write、edit、glob、bash工具直接操作服務器鏡像，無需自定義工具。 - DSH 修改文件後，通過 WebSocket 即時同步回本地。
- WebSocket 斷線後會自動重連，並補齊漏掉的變更。
- 「刪除項目」只刪除服務器副本與工作區記錄，不影響本地文件。
- 刷新頁面後，可以從服務器恢復項目列表，並重新選擇本地文件夾恢復同步。
- 插件提供
/local-project/*HTTP 接口和 WebSocket 推送，支持創建、上傳、列出、下載、刪除和變更恢復。
安裝與啓用¶
先執行官方安裝命令：
dsh plugin --profile web add github:0xKcyzz/dsh-local-project
安裝後需要重啓 DSH。重啓後，「添加工作區」會打開本地項目導入對話框。
如果本地項目的服務器鏡像目錄不使用默認位置，可以配置環境變量：
DSH_LOCAL_PROJECT_ROOT
默認值：$DSH_HOME/workspaces
典型用法¶
下面是一個可復現的使用流程：
1、在 DSH 側邊欄或空狀態中點擊「添加工作區」。
2、輸入項目名稱，點擊「選擇文件夾並導入」。
3、在系統對話框中選擇本地文件夾。該步驟需要 Chrome / Edge 瀏覽器授權。
4、首次導入會開始上傳文件。完成後，左側工作區列表會出現「本地項目: 名稱」。
5、打開該工作區對話。DSH 操作的是服務器鏡像副本，文件改動會自動同步回本地。
適用場景¶
適合這類使用方式：在瀏覽器中把本機代碼或資料交給遠程 DSH 直接讀寫，同時保留本地副本。
它更適合 DSH 側發起修改的場景。DSH 在服務器鏡像中改文件後，變更會推送回本地；本地已有的文件可以隨首次導入上傳到服務器。
注意事項¶
使用前注意以下限制：
- 需要瀏覽器支持 File System Access API：Chrome / Edge（含 Chromium）。Firefox / Safari 不支持。
- 單個文件上限約 15MB，上傳使用 base64 JSON。超大文件不建議放入項目。
- 不傳播單個文件的刪除：只有「刪除項目」會整包刪除服務器副本。本地和服務器各自刪除的文件，不會被對面清除。
- 本地改動不會自動上傳：只有首次導入會上傳本地文件。之後本地手動修改的文件，不會同步到服務器。
- 即時推送需要保持 WebSocket 連接。斷線後會自動重連，並補齊漏掉的變更。
- 桌面端 Electron 窗口若 File System Access API 不可用，請用系統瀏覽器打開 DSH 的 Web 地址。
- 插件會隨 DSH 插件機制加載，並以當前 DSH 進程的權限執行相關操作。安裝前應檢查源碼與許可證。
鏈接¶
GitHub 倉庫：https://github.com/0xKcyzz/dsh-local-project
