Preface¶

In DSH workflows, models often need to call pwsh to execute system commands. The issue isn’t whether commands can run, but rather that PowerShell itself has a set of common pitfalls around syntax, versions, encoding, and quoting: GBK console garbled text, $var: parsing, PS 5.1 ternary expressions, variable expansion inside double quotes, JS escaping, Start-Process quoting, -FeatureName arrays, DISM verbs, RestoreHealth source versions, CDN downloads, npm.cmd suffixes, && / || chaining, etc.

Running it once, seeing an error, and then going back to fix the script based on that error creates a slow loop. The idea behind @chaggle/dsh-powershell-check is to move some common pitfalls upfront: perform static checks before each pwsh tool call, return deny directly when a blocking rule is hit, and provide fix suggestions in the deny reason; it also bundles a powershell-check skill for on-demand loading within the session.

What This Is¶

@chaggle/dsh-powershell-check is a DeepSeek Harness (DSH) plugin, maintained by chaggle, licensed under MIT.

It does two things:

• Uses the official tools/pre-execute interception point to perform static checks before each pwsh tool call.
• Bundles the powershell-check skill and exposes it to the session skills directory via ctx.skills.registerProvider.

The plugin’s static heuristic rules target common high-frequency errors in AI-generated scripts. When a blocking violation is hit, the call is rejected with a fix suggestion in the deny reason; in warn mode, it only logs and does not block the call.

Core Features¶

Below are the points most relevant to daily use.

Automatic Gate¶

The plugin subscribes to the official tools/pre-execute interception point. Every pwsh tool call passes through static checks before execution:

• Blocking violations return deny, with the deny reason containing fix suggestions.
• advisory-level rules, such as R1, are allowed to pass.
• warn mode only logs and does not block.

This means the model doesn’t see a vague “command execution failed” error, but rather error feedback closer to a corrective action.

Bundled Skill¶

The plugin includes a powershell-check skill, registered to the skills directory via ctx.skills.registerProvider. Within a session, it can be used like any regular skill without relying on gate behavior.

Bilingual Output¶

Rule texts, CLI output, deny reason, and documentation are provided in both English and Simplified Chinese. The CLI supports --lang en or --lang zh to control output language.

Single Rule Source¶

The rule engine resides in src/checker.ts, with both the gate and CLI sharing the same set of rules. Updating rules keeps both sides consistent.

Self-Test¶

Supports --selftest, running 60 positive and negative cases covering R1-R19, focusing on common issues in AI-generated scripts.

Optional PSScriptAnalyzer Deep Check¶

Uses built-in rules by default. If configured:

analyzer: psscriptanalyzer

The plugin will append official static analysis when PSScriptAnalyzer is installed on the host. If the module is missing, it logs once and falls back to builtin rules.

Note that after enabling psscriptanalyzer, each deep check starts an analyzer pass, with module loading taking about 1-3 seconds. Enable it only when the additional coverage is worth the latency.

Installation & Enablement¶

Install as a Profile Plugin¶

Recommended to install as a profile plugin:

dsh plugin --profile <name> add @chaggle/dsh-powershell-check

Alternatively, add the plugin line directly to the profile layer config:

# $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

Where mode controls behavior:

• deny: Rejects pwsh calls that hit blocking violations.
• warn: Only logs and allows the call to continue.

lang controls the language of deny reason and logs:

• zh
• en

Install the Skill Only¶

If you only need the skill without the gate, clone the repository into any skill root directory:

git clone https://github.com/chaggle/dsh-powershell-check.git "$HOME/.dsh/skills/powershell-check"

Configuration¶

Common configuration options are as follows:

To enable PSScriptAnalyzer, first install the module on the host:

Install-Module PSScriptAnalyzer -Scope CurrentUser -Force

After configuring analyzer: psscriptanalyzer, PSScriptAnalyzer’s Error / ParseError level findings trigger deny; warning-level findings log and allow.

Typical Usage¶

Below are several reproducible CLI usages.

Check a Command Text¶

node scripts/check-pwsh.mjs -- "command text" [--lang en]

This performs a static check directly on the command text, suitable for quick validation before handing the command to pwsh.

Check a PowerShell File¶

Get-Content fix.ps1 -Raw | node scripts/check-pwsh.mjs - [--lang en]

This reads content from a file and pipes it to the checker via stdin.

Run Self-Test¶

node scripts/check-pwsh.mjs --selftest

After running, you can see how the current rule set performs on built-in positive and negative cases.

CLI Exit Codes¶

• 0: PASS
• 1: FAIL, listing violations and fix suggestions
• 2: usage error

Applicable Scenarios & Notes¶

Who It’s For¶

If you’re using DSH to drive pwsh and want to filter out some low-level but high-frequency PowerShell errors before execution, this plugin is a good fit. It’s especially suitable for:

• Static-checking pwsh commands generated by the model.
• Returning deny reason as actionable error feedback to the model.
• Checking PowerShell text independently in CI or local scripts.
• Needing bilingual rule texts and CLI output.

Points to Note¶

The plugin performs static heuristic checks, not full semantic analysis:

• Rules are based on pattern matching.
• R1 is at the advisory level.
• R4 may flag expected variable expansion; the fix text explains when it can be ignored.
• Enabling psscriptanalyzer introduces additional latency, with fallback to builtin if the module is missing.
• Code changes require the running harness to re-import the plugin; user patch lines can hot-reload, and module cache reloads when lines are replaced.

In terms of runtime boundaries, the plugin runs with the current dsh process permissions. Review the source code and license before deciding to include it in your profile.

Additionally, the plugin does not inject content into the prompt; the skill is exposed via the standard session skills directory. deny reason is returned as a tool error result without altering the request prefix.

Conclusion¶

The value of @chaggle/dsh-powershell-check lies in moving some common PowerShell errors from “post-execution failure” to “pre-execution interception,” and organizing the deny reason into feedback directly usable for fixes. For DSH workflows that frequently call pwsh, this provides a concrete pre-check layer.

Project repository:

https://github.com/chaggle/dsh-powershell-check

Community directory page (provided in the project lead):

https://www.skillhub.cn/plugins/chaggle/dsh-powershell-check