dsh-plugin-windows-guard

前言¶

DeepSeek Harness (DSH) 採用插件化架構。在 Windows 環境下開發或運維時，編碼錯亂、路徑解析、進程端口占用等問題高頻出現。dsh-plugin-windows-guard 旨在解決這些問題。

該插件由 Pasumao 維護，定位爲 Windows 環境防坑工具。它通過「守則層」+「主動防護層」兩層機制，提供預防性規則和運行時攔截能力，幫助開發者避免常見的編碼和系統操作錯誤。

核心功能¶

插件主要包含以下能力：

守則層：自動加載¶

默認自動加載兩個自包含 skill，按場景觸發：
- windows-enc：處理編碼、轉義、亂碼問題，涵蓋環境事實卡、編碼三鐵律、引號轉義速查、亂碼三不原則。
- windows-sys：處理路徑、進程、端口、跨平臺雜項（如 CRLF、ExecutionPolicy）。

主動防護層¶

插件提供三層運行時防護：

L2 亂碼檢測
監聽 pwsh 工具結果，檢測 GBK 誤解碼、FFFD 字符、中文變問號等亂碼特徵。檢測到後，在結果末尾自動附加 [windows-guard] 修復提示，不中斷執行。
L3 危險寫攔截
監聽 tools/pre-execute 事件。攔截不帶 -Encoding 的 Set-Content、Add-Content、Out-File 寫結構化文件命令，以及直接使用 > 重定向寫結構化文件。攔截後會提示使用 [System.IO.File]::WriteAllText(...) 的正確寫法。
L4 編碼工具
提供 windows_encode_detect（診斷文件編碼置信度）和 windows_encode_fix（修復爲 UTF-8 無 BOM，自動備份）兩個工具。

安裝與啓用¶

安裝命令如下：

dsh plugin --profile web add dsh-plugin-windows-guard

安裝完成後，需要重啓 dsh web 才能生效。插件自帶 cordis.patch.yml 配置，會自動掛載相關規則，無需手動修改配置文件。

配置¶

默認配置爲全開狀態，所有功能均啓用：

- insert:
    - id: dsh-plugin-windows-guard
      name: dsh-plugin-windows-guard
      config:
        enabled: true     # 總開關
        postCheck: true   # L2 亂碼檢測
        preCheck: true    # L3 危險寫攔截
        detectTools: true # L4 編碼診斷/修復工具

使用方式¶

安裝後無需額外配置即可使用：

自動守則加載：當模型遇到 Windows 命令、編碼、亂碼、路徑或進程任務時，會自動嘗試加載 windows-enc 或 windows-sys 技能。
亂碼提示：執行 pwsh 命令產生亂碼時，結果末尾會附帶修復提示。
命令攔截：若模型嘗試使用不帶 -Encoding 的命令寫入 JSON 等結構化文件，命令會被攔截，並返回正確的 API 調用示例。
手動工具調用：可直接調用 windows_encode_detect 查看文件編碼，或使用 windows_encode_fix 進行修復。

依賴與要求¶

該插件依賴以下環境：

Node.js：版本需 >= 22.5（需 full-icu 支持）。
DSH 核心：依賴 @deepseek-ai/cordis 版本 ^4.0.1。
運行時依賴：零運行時依賴、零構建。