前言¶
在 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
