dsh-pwsh-quoting-guard：解决 PowerShell 命令字符串引号转义问题

前言¶

在 Windows 环境下使用 DSH（DeepSeek Harness）时，模型在编写 PowerShell 命令时经常受困于引号转义问题。路径中包含空格、中文字符、特殊符号（如 $、%）或嵌套引号时，命令执行极易失败或产生不可预期的行为。dsh-pwsh-quoting-guard 插件通过引入结构化数据传递机制，将“命令字符串”这一层转义负担移除，确保数据准确传递。

插件简介¶

名称：dsh-pwsh-quoting-guard
维护者：fengbai2233
分类：admin-security
许可证：MIT

该插件提供两个工具：pwsh_script 和 run_argv。它们通过结构化数组传递参数，避免模型进行复杂的引号转义，同时钉住 UTF-8 编码，确保在 Windows PowerShell 5.1 等执行器下行为稳定。

安装与启用¶

使用以下命令将插件添加到指定的 profile 中：

dsh plugin --profile web add dsh-pwsh-quoting-guard

安装后需要重启 dsh web 使组合生效。

工具说明¶

插件提供两个核心工具，用于不同的场景。

pwsh_script¶

通过 $DSH_ARGS 结构化传递数据，正文（script）作为单个元素传递，避免引号转义。
* 参数：
* script (string, 必填)：PowerShell 脚本正文。
* args (string[])：参数列表，按顺序绑定到 $DSH_ARGS[0]。
* 特性：零运行时依赖，钉住 UTF-8 编码，支持 cwd 参数。

run_argv¶

直接将参数作为 argv 传递，完全绕过 shell 解析，适合执行原生程序并保真参数。
* 参数：
* program (string, 必填)：可执行文件名或绝对路径。
* args (string[])：参数向量。
* cwd (string)：工作目录，默认为会话工作区。

使用示例¶

示例 1：读取含特殊字符的路径

{
  "script": "(Get-Content -LiteralPath $DSH_ARGS[0] -Raw).Trim()",
  "args": ["E:\\deepseekwork\\插件\\.dsh-tmp\\$100 %TEMP% it's dir\\sample file.txt"]
}

示例 2：在指定目录运行 node 并保真参数

{
  "program": "node",
  "args": ["-e", "console.log(process.cwd(), process.argv.slice(1))", "a\\\"b'c"],
  "cwd": "E:\\deepseekwork\\插件\\.dsh-tmp\\$100 %TEMP% it's dir"
}

工作原理¶

结构化隔离：pwsh_script 将脚本正文作为单个 argv 元素交给 PowerShell 的 -Command，数据通过 $DSH_ARGS 数组传递，模型无需关心转义。
Shell-free：run_argv 直接调用 ctx.subprocess.spawn，参数不被 shell 解析或展开，保证参数原样传入。
环境对齐：注入 NO_COLOR、PAGER 等环境变量，并处理沙箱权限，确保输出格式与标准工具一致。

已知限制¶

无后台任务：pwsh_script 不支持 run_in_background，长任务建议使用官方 pwsh 工具。
行号偏移：当参数值包含换行符时，脚本行号会偏移。
提示段唯一性：提示段名在同一层内必须唯一，避免因重名导致插件树加载失败。
硬性依赖：inject 声明是硬性的，必须声明 ['subprocess', 'tools'] 才能访问相关上下文。

故障排查¶

工具不可见：检查是否已重启 dsh web。
启动失败：若报错 cannot get property "tools" without inject，检查是否正确声明了 inject。
重名错误：检查是否在 profile 和 preset 中同时安装了该插件。

结尾¶

dsh-pwsh-quoting-guard 通过结构化的工具接口，解决了 Windows 环境下 PowerShell 命令行参数传递中最棘手的转义问题。对于需要处理复杂路径或执行原生程序的场景，它能显著减少因引号错误导致的重试和 token 浪费。

GitHub: https://github.com/fengbai2233/dsh-pwsh-quoting-guard
Catalog: https://www.skillhub.cn/plugins/fengbai2233/dsh-pwsh-quoting-guard