前言¶
在 DSH 工作流裏，模型經常需要調用 pwsh 執行系統命令。問題不在於命令是否能跑通，而在於 PowerShell 本身有一批容易踩中的語法、版本、編碼和引號坑：GBK 控制檯亂碼、$var: 解析、PS 5.1 三元表達式、雙引號內變量展開、JS 轉義、Start-Process 引號、-FeatureName 數組、DISM 動詞、RestoreHealth 源版本、CDN 下載、npm.cmd 後綴、&& / || 鏈等。
先跑一遍，看到報錯，再根據報錯回改腳本，這個循環很慢。@chaggle/dsh-powershell-check 的思路是把部分常見坑前置：在每次 pwsh 工具調用執行前做靜態檢查，命中阻斷級規則時直接返回 deny，並在 deny reason 裏給出修復建議；同時捆綁 powershell-check skill，供會話中按需加載。
這是什麼¶
@chaggle/dsh-powershell-check 是一個 DeepSeek Harness（DSH）插件，維護者爲 chaggle，許可證爲 MIT。
它做兩件事：
- 通過官方
tools/pre-execute攔截點，對每次pwsh工具調用執行前做靜態檢查。 - 捆綁
powershell-checkskill，並通過ctx.skills.registerProvider暴露到會話技能目錄。
插件的靜態啓發式規則面向 AI 生成腳本中常見的高頻錯誤。命中阻斷級違規時，調用會被拒絕，拒絕原因包含修復建議；warn 模式下只記錄日誌，不阻斷調用。
核心功能¶
下面介紹幾個和日常使用最相關的點。
自動 gate¶
插件訂閱官方 tools/pre-execute 攔截點。每次 pwsh 工具調用在執行前都會經過靜態檢查：
- 阻斷級違規返回
deny，deny reason包含修復建議。 advisory級別規則，例如 R1，可以通過。warn模式只記錄日誌，不阻斷。
這意味着模型看到的不是“命令執行失敗”的模糊報錯，而是更接近修復動作的錯誤反饋。
捆綁 skill¶
插件自帶 powershell-check skill，通過 ctx.skills.registerProvider 註冊到技能目錄。會話中可以把它當作普通 skill 使用，不必依賴 gate 行爲。
雙語輸出¶
規則文本、CLI 輸出、deny reason 和文檔同時提供英文與簡體中文。CLI 可用 --lang en 或 --lang zh 控制輸出語言。
單一規則源¶
規則引擎位於 src/checker.ts，gate 與 CLI 共用同一套規則。更新規則後，兩邊行爲一致。
自測¶
支持 --selftest，運行 60 個正負案例，覆蓋 R1-R19，聚焦 AI 生成腳本中的常見問題。
可選 PSScriptAnalyzer 深度檢查¶
默認使用內置規則。若配置：
analyzer: psscriptanalyzer
插件會在宿主已安裝 PSScriptAnalyzer 的情況下追加官方靜態分析。模塊缺失時記錄一次並回退到 builtin 規則。
需要注意的是，啓用 psscriptanalyzer 後，每次深度檢查會啓動一次 analyzer pass，模塊加載約 1-3 秒。只有在額外覆蓋範圍值得這個延遲時再開啓。
安裝與啓用¶
作爲 profile 插件安裝¶
推薦作爲 profile 插件安裝：
dsh plugin --profile <name> add @chaggle/dsh-powershell-check
也可以直接把插件行加入 profile 層配置：
# $DSH_HOME/profiles/<name>/cordis.patch.yml
- insert:
- id: dsh-powershell-check
name: @chaggle/dsh-powershell-check
config:
mode: deny # deny | warn
lang: zh # zh | en
其中 mode 控制行爲：
deny：命中阻斷級違規時拒絕pwsh調用。warn：只記錄日誌，允許調用繼續。
lang 控制 deny reason 和日誌語言：
zhen
僅安裝 skill¶
如果只需要 skill，不需要 gate，可以把倉庫克隆到任意 skill 根目錄：
git clone https://github.com/chaggle/dsh-powershell-check.git "$HOME/.dsh/skills/powershell-check"
配置¶
常見配置項如下：
| Key | Default | 含義 |
|---|---|---|
mode |
deny |
deny 阻斷命中阻斷級違規的 pwsh 調用；warn 只記錄日誌並放行 |
lang |
zh |
deny reason 與 warn 日誌語言，支持 zh 或 en |
analyzer |
builtin |
builtin 只使用捆綁規則；psscriptanalyzer 在宿主安裝模塊後追加 PSScriptAnalyzer |
如果要啓用 PSScriptAnalyzer，先在宿主安裝模塊：
Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
配置 analyzer: psscriptanalyzer 後，PSScriptAnalyzer 的 Error / ParseError 級別發現會觸發 deny；warning 級別會記錄日誌並放行。
典型用法¶
下面給出幾個可復現的 CLI 用法。
檢查一段命令文本¶
node scripts/check-pwsh.mjs -- "command text" [--lang en]
這一步直接對命令文本做靜態檢查，適合在把命令交給 pwsh 前快速驗證。
檢查一個 PowerShell 文件¶
Get-Content fix.ps1 -Raw | node scripts/check-pwsh.mjs - [--lang en]
這一步從文件讀取內容，再通過 stdin 傳給檢查器。
運行自測¶
node scripts/check-pwsh.mjs --selftest
運行後可以看到當前規則集在內置正負案例上的表現。
CLI 退出碼¶
0：PASS1：FAIL，會列出違規項和修復建議2：usage error
適用場景與注意¶
適合誰¶
如果你正在用 DSH 驅動 pwsh，並且希望把一些低級但高發的 PowerShell 錯誤擋在執行前，這個插件比較合適。它尤其適合以下場景：
- 模型生成
pwsh命令後，希望先做一層靜態檢查。 - 需要把
deny reason作爲可操作的錯誤反饋回傳給模型。 - 想在 CI 或本地腳本里獨立檢查 PowerShell 文本。
- 需要中英文規則文本和 CLI 輸出。
需要注意的點¶
插件是靜態啓發式檢查，不是完整語義分析：
- 規則基於模式匹配。
- R1 是
advisory級別。 - R4 可能標記預期內的變量展開，修復文本會說明何時可以忽略。
- 啓用
psscriptanalyzer會帶來額外延遲，模塊缺失時會回退到builtin。 - 代碼變更需要運行中的 harness 重新導入插件；用戶 patch 行可以熱重載，模塊緩存在行替換時重載。
運行邊界上，插件以當前 dsh 進程權限運行。安裝前應檢查源碼和許可證，再決定是否納入自己的 profile。
另外，插件不會向 prompt 注入內容；skill 通過標準會話技能目錄暴露。deny reason 作爲工具錯誤結果返回，不改變請求前綴。
結尾¶
@chaggle/dsh-powershell-check 的價值在於把一部分 PowerShell 常見錯誤從“執行後報錯”提前到“執行前攔截”，並把拒絕原因組織成可直接用於修復的反饋。對 DSH 工作流裏頻繁調用 pwsh 的場景，這是一個比較具體的前置檢查層。
項目倉庫：
https://github.com/chaggle/dsh-powershell-check
社區目錄頁（項目線索中給出）：
https://www.skillhub.cn/plugins/chaggle/dsh-powershell-check
