前言¶
在 DSH 中處理多個項目時，agent 經常需要同時讀取、搜索和修改分散在不同目錄裏的文件。逐個目錄打開、逐個路徑查找，會讓跨項目任務變慢，也讓界面管理變得零散。
dsh-virtual-workspace 的做法是：先把多個項目目錄組成一個命名的虛擬工作區，再讓 agent 通過統一的路徑語法和工具來訪問這些目錄。
這是什麼¶
dsh-virtual-workspace 是 DeepSeek Harness（DSH）的一個動態 Cordis 插件，由 KevinWen7415 維護，許可證爲 MIT。
它把多個項目目錄組織成命名虛擬工作區，並提供 agent 工具 vws、側邊欄抽屜管理、內置工作區列表鏡像，以及和會話沙箱一致的寫入升級。
核心功能¶
虛擬工作區與虛擬路徑¶
插件維護“名字 → 多個項目目錄”的映射組，一次定義後可以在各會話中使用。
agent 可使用 名字:/相對路徑 的虛擬路徑語法訪問成員目錄。文件操作取首個命中，目錄操作取並集。
vws 工具¶
插件提供 agent 工具 vws，包含 13 個動作：
list
add
remove
add-dir
remove-dir
set-mirror
resolve
read
write
edit
ls
find
grep
工具與提示段註冊在根上下文，任何會話的 agent 都能調用 vws 並看到工作區清單。
側邊欄抽屜與列表鏡像¶
插件接管側邊欄頭部的“＋ 添加工作區按鈕”。點擊後向下彈出抽屜，用於創建普通工作區、聯立虛擬工作區，以及管理既有工作區。
成員目錄會註冊爲內置工作區條目，標題格式爲“工作區名 · 目錄名”。插件只清理自己創建的條目。
沙箱一致¶
讀取不受限。
寫入和編輯遵循調用會話的沙箱邊界；越界被拒後，可使用 sandbox_permissions + justification 進行一次性審批升級。
持久化與語言¶
工作區定義保存在：
<部署工作區根>/.vws-workspaces.json
本機示例爲：
C:\Users\<用戶>\.vws-workspaces.json
重啓後會自動恢復。
界面支持簡體中文（zh）和英文（en）。zh 顯示簡體中文，其餘語言回退英文，語言切換即時生效。
安裝形態¶
該插件可以以 bundle 方式安裝，也可以作爲動態 Cordis 插件運行。
bundle 同時攜帶 Host 與 Client，進程重啓後自動加載，不依賴會話。
動態安裝無需構建。代碼約束爲純 JavaScript，不使用 import/require/JSX/TypeScript；Client 使用 React.createElement；文件操作必須經 ctx.fs 服務。
package.json 中的版本爲 1.2.2。依賴爲：
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
peerDependencies 爲：
"@deepseek-ai/cordis": "^4.0.1"
安裝與啓用¶
bundle 安裝¶
先確認 DSH profile 名稱，然後執行：
dsh plugin --profile <name> add github:KevinWen7415/dsh-virtual-workspace
dsh --profile <name>
bundle 同時攜帶 Host 與 Client，進程重啓後自動加載，不依賴會話。
動態安裝¶
在 DSH 會話中發送：
請從這個倉庫自動安裝插件：https://github.com/KevinWen7415/dsh-virtual-workspace（讀取 src/host.js 與 src/client.js，用 cordis_define 定義後 cordis_run 激活）
如果 DSH 機器無法訪問 GitHub，需要先本地克隆：
git clone https://github.com/KevinWen7415/dsh-virtual-workspace
然後按本地路徑繼續安裝。
首次激活含瀏覽器 UI 的包需要頁面審批；審批被拒不會自動重試。
手動動態安裝¶
手動安裝分三步：
1、調用 cordis_define，plugin 設置爲：
{ "kind": "new", "idPrefix": "vws" }
將 src/host.js 與 src/client.js 的函數體分別填入 code.host 和 code.client。
2、記錄返回的 pluginId 與 packageId。
3、調用 cordis_run，使用 mode run。
審批通過並收到成功通知後，刷新頁面。
驗證安裝¶
1、點擊側邊欄頭部“＋”，確認彈出 Virtual Workspaces 抽屜。
2、在抽屜中添加一個工作區。
3、在對話中發送：
用 vws list 列出虛擬工作區
agent 返回工作區狀態即表示安裝可用。
典型用法¶
用自然語言驅動¶
可以對 agent 說：
讀 EDB:/src/xxx
在 EDB 裏搜索 xxx
把 EDB 的 xxx 改成 yyy
如果寫入超出當前會話邊界，agent 會發起升級請求；批准後完成一次性寫入。
更新與回滾¶
更新版本：
對同一 pluginId 用 cordis_define（kind: existing）追加新包，再 cordis_run mode update
回滾：
cordis_run mode run 指定 currentPackageId
停用：
cordis_stop
卸載前需要先清理工作區或鏡像，再執行：
cordis_stop
cordis_undefine
卸載前清理方式是在抽屜中移除工作區，或關閉鏡像。如果卸載後內置列表仍有殘留條目，可以在官方側邊欄手動刪除。
進程重啓後¶
動態插件隨 DSH 進程存續。DSH 進程重啓後，需要對原 pluginId 再次 cordis_run 激活；工作區定義持久化，不會丟失。
適用場景與注意¶
適合以下場景：
- 多個項目目錄需要一起讀取、搜索或修改。
- 希望 agent 通過統一命名路徑訪問多個目錄。
- 希望在側邊欄中創建、管理和鏡像虛擬工作區。
- 需要保留 DSH 的會話沙箱邊界，並在越界寫入時走一次性審批。
注意事項：
- 插件以當前 DSH 進程權限運行；安裝前應檢查源碼與許可證。
- 許可證爲 MIT。
- 讀取不受限；寫入和編輯受調用會話沙箱邊界限制。
- 動態安裝依賴 DSH 進程；進程重啓後需要重新激活。
- 如果 DSH 機器無法訪問 GitHub，需要先本地克隆倉庫。
- 工作區定義保存在
.vws-workspaces.json，卸載或遷移前應瞭解該文件位置。
鏈接¶
- GitHub：https://github.com/KevinWen7415/dsh-virtual-workspace
- 目錄頁（獨立站點）：https://www.skillhub.cn/plugins/KevinWen7415/dsh-virtual-workspace
