前言¶

在 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-check skill，并通过 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 和日志语言：

• zh
• en

仅安装 skill¶

如果只需要 skill，不需要 gate，可以把仓库克隆到任意 skill 根目录：

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

配置¶

常见配置项如下：

如果要启用 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：PASS
• 1：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