@MarvekG/dsh-plugins
第一章：安装指南
> ⚠️ 从旧包名 @MarvekG/dsh-bug-fix 升级：必须先卸载再安装。
> 本包已更名为 @MarvekG/dsh-plugins，包名变了，不能走「更新」流程平滑切换（旧条目会残留在 profile 里）。请先执行：
>
> sh
> 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#
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 工具。它只会在以下条件同时满足时，把升级字段删除并按当前权限执行：
sandbox_permissions是该工具 schema 明确公开的枚举值；justification是非空字符串；- 请求权限不宽于当前调用、当前 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 单独挂载），把原生打开换成纯浏览器方案：
- 在同一个 web 服务上注册带回环围栏的
GET /view?path=<绝对路径>[&line=N]：文件渲染为行号表格（HTML 转义、tab=4、超 4 MiB 截断横幅、二进制识别不渲染），目录渲染为可继续点击进入的列表页。 - 通过
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 — 开放、友好的开发者社区。
