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