@MarvekG/dsh-plugins

第一章：安装指南

⚠️ 从旧包名 @MarvekG/dsh-bug-fix 升级：必须先卸载再安装。 本包已更名为 @MarvekG/dsh-plugins，包名变了，不能走「更新」流程平滑切换（旧条目会残留在 profile 里）。请先执行：

dsh plugin --profile web remove @MarvekG/dsh-bug-fix
dsh plugin --profile web add github:MarvekG/dsh-plugins
dsh web

卸载与重装之间不要重启 DSH Web，避免旧名缺失导致的装配告警。

1.1 从 GitHub 安装

需要先安装并确认 dsh 可以正常运行。默认从 GitHub 安装：

dsh plugin --profile web add github:MarvekG/dsh-plugins
dsh web

这里的 web 是 DSH profile 名称。如果使用其他 profile，把 web 换成对应的 profile 名称。

安装后，重启 DSH Web 即可生效。

1.2 固定版本

如果不想跟随仓库最新代码，可以在仓库地址后加 commit SHA：

github:MarvekG/dsh-plugins#<sha>

1.3 本地调试

克隆本仓库后，在仓库根目录执行：

dsh plugin --profile web add .
dsh web

1.4 卸载

从 web profile 移除插件：

dsh plugin --profile web remove @MarvekG/dsh-plugins

1.5 更新

更新时先移除旧版本，再安装新版本：

dsh plugin --profile web remove @MarvekG/dsh-plugins
dsh plugin --profile web add github:MarvekG/dsh-plugins
dsh web

本地调试时，把第二条命令替换为：

dsh plugin --profile web add .

1.6 运行测试

在插件目录执行：

npm test

1.7 多入口结构

本包使用 DSH 的子路径入口。当前入口：

@MarvekG/dsh-plugins/sandbox-same-mode
@MarvekG/dsh-plugins/path-viewer

它由 cordis.patch.yml 单独挂载。以后新增修复时，可以新增一个脚本、一个 exports 子路径和一个独立的 patch 行；每个入口拥有自己的 Cordis 生命周期，可以单独加载和卸载。

第二章：已解决的问题

本章按问题分别记录修复内容。后续新增问题时，继续在本章增加独立小节。

2.1 冗余沙箱权限请求

原始报错

session 权限已经切换为 danger-full-access 后，重试仍携带以下参数：

{
  "file_path": "/home/wang/codes/StickyProxy/plugin/internal/state/store.go",
  "content": "x",
  "sandbox_permissions": "workspace-write",
  "justification": "write the requested plugin fix outside the workspace"
}

DSH 在写入真正执行前报错：

sandbox escalation to "workspace-write" is not strictly wider than this call's current "danger-full-access" mode

为什么会报错

因为有效权限按 session 决定，工具 schema 会公开所有可能的升级目标。模型可能在较窄权限下收到重试指引，然后在 session 切换到相同或更宽权限后继续使用该参数。这个例子中，workspace-write 比当前的 danger-full-access 更窄，请求字段并没有增加能力，因此 DSH 正确地将它拒绝为非升级请求。

插件如何处理

插件会在工具注册时包装其执行函数，因此同时覆盖普通全局工具和 DSH Web 的 preset-scoped bash、pwsh、write、edit 工具。它只会在以下条件同时满足时，把升级字段删除并按当前权限执行：

1. sandbox_permissions 是该工具 schema 明确公开的枚举值；
2. justification 是非空字符串；
3. 请求权限不宽于当前调用、当前 session 的有效 sandbox 权限。

此时请求只是冗余声明，因而不弹审批，也不再报 not strictly wider。

真正的权限升级和所有非法输入仍然保持原来的流程：

• read-only → 更高权限：继续申请审批；
• workspace-write → danger-full-access：继续申请审批；
• 缺少说明、说明为空或参数不完整：继续报错；
• 未被工具 schema 公开的权限值（包括伪造的同级值）：仍由 DSH 原始参数校验拒绝。

插件不会绕过什么

插件不会扩大工作区，也不会修改 workspaceRoot，更不会偷偷增加权限。有效权限仍为 workspace-write 时，去掉冗余升级字段后，工作区外的请求仍可能因为沙箱工作区边界而被拒绝。

安装或更新后应重启 DSH Web，使新的 preset-scoped 工具注册时经过本插件；它不会追溯包裹重启前已存在的 session 工具定义。

2.2 点击路径改为弹出网页查看器

原始报错

在 DSH Web 里点击文件路径时报：

path open failed: path open failed: spawn powershell.exe ENOENT

为什么会报错

WSL 下 DSH 通过 powershell.exe 把路径交给 Windows 桌面打开。/etc/wsl.conf 配置了 [interop] appendWindowsPath = false 时，Windows 目录不会追加进 PATH，裸命令名 spawn 直接 ENOENT。而且「从 WSL 唤起 Windows 桌面」本就脆弱——GUI 本身就跑在 Windows 浏览器里。

插件如何处理

新增 dsh-plugins-path-viewer 条目（cordis.patch.yml 单独挂载），把原生打开换成纯浏览器方案：

1. 在同一个 web 服务上注册带回环围栏的 GET /view?path=<绝对路径>[&line=N]：文件渲染为行号表格（HTML 转义、tab=4、超 4 MiB 截断横幅、二进制识别不渲染），目录渲染为可继续点击进入的列表页。
2. 通过 webserver/index-inject 向 GUI 页面注入一段 head 脚本：拦截发往 /api/host.openPath、/api/host.openTextFile 的 RPC，改用 window.open('/view?path=…') 在新标签页展示，并按线上封包形状伪造成功应答（{type:'server-response',rpcId,result:{ok:true,value:{opened:true}}}）；若新标签页被浏览器拦截，自动放行原始请求。常见源码由 highlight.js 做语法高亮，未知扩展名安全地按纯文本展示。

全程不 spawn 任何 Windows 进程。配置项：maxBytes（单次渲染字节上限）与 intercept（改道的 RPC 方法列表）。安装或更新后重启 DSH Web 生效。

第三章：许可证与友情链接

本项目基于 MIT 许可证 开源。

友情链接

• linux.do — 开放、友好的开发者社区。