GuTianshuo/powershell-fix

powershell-fix

一个用于 DeepSeek Harness (DSH) 的宿主层插件，它能在 Windows PowerShell 命令语法错误消耗一次工具调用往返之前，检测并自动修复这些错误——然后通过宿主 shell 接缝，在常规沙箱/审批策略下执行修正后的命令。

AI 智能体（以及人类）经常把 bash 风格的命令粘贴到 Windows 终端中。本插件为智能体提供一个工具——powershell_fix——用于检查、修复并安全地运行此类命令。

它能修复什么

行级卫生（现实中最常见的破坏来源）

| 问题 | 修复 |
|---|---|
| 复制粘贴产生的 CRLF / 游离 \r | 规范化为 LF |
| 粘贴进来的 shell 提示符（每行开头的 PS C:\> 、C:\> 、$ ） | 剥离 |
| 续行符后的行尾空白（不可见的破坏） | 移除 |
| bash 的 \ 续行 | 改为 PowerShell 反引号 |
| -Parameter 行前缺少续行符 | 插入反引号 |
| 空行前悬空的反引号 | 移除 |
| 引号不配对 | 警告（绝不盲目重写） |

bash → PowerShell 语义转换

| bash | PowerShell |
|---|---|
| export NAME=value | $env:NAME='value'（同一命令中的 $NAME 引用改写为 $env:NAME） |
| unset NAME | if (Test-Path Env:NAME) { Remove-Item Env:NAME }（带守卫；支持链式命令中的内联形式） |
| > /dev/null、2> /dev/null、&> /dev/null | > $null、2> $null、> $null |
| a && b / a || b | 在 PowerShell 7+ 上保留；在 Windows PowerShell 5.1 上拆分为 if ($?) { … }（自动检测引擎） |
| ls -la path | Get-ChildItem path -Force |
| rm -rf x | Remove-Item x -Recurse -Force |
| mkdir -p a/b/c | New-Item -ItemType Directory -Force … |
| touch f | 更新时间戳或 New-Item -ItemType File |
| grep [-r] [-v] pat f… | Select-String（通过 Get-ChildItem -Recurse 实现递归） |
| which x / command -v x | (Get-Command x -ErrorAction SilentlyContinue).Source |
| head -n N f / tail -n N f / tail -f f | Get-Content -TotalCount N / -Tail N / -Wait |
| sed、awk、chmod、裸 $PATH 风格的环境变量引用 | 给出警告并附 PowerShell 等价写法（绝不盲目重写） |

正确的 PowerShell 会原样通过（无操作保证，由回归测试覆盖）。修复器是幂等的：fix(fix(x)) === fix(x)。

安全性

- 执行通过宿主 ctx.shell 接缝进行——与内置 pwsh 工具使用相同的沙箱、审批和超时策略。本插件不增加任何权限。
- 内置的执行闸门会拒绝自动执行语义上具有破坏性的命令，即使它们已被修复：针对根目标的递归删除（rm -rf /、Remove-Item C:\ -Recurse）、Format-Volume、Clear-Disk、Set-ExecutionPolicy、del /s|/q，以及环境/系统持久化写入（setx、[Environment]::Set、New-ItemProperty、Set-ItemProperty、reg add）。
- execute: false（或 autoExecute: false 配置）提供试运行：只修复，不执行。
安装（宿主层——对所有会话可用）

该包声明了 dsh.bundle.patch，因此将其安装到某个 profile 时会自动把它加入该 profile 的层栈——无需任何 agent-preset 行：

dsh plugin --profile web add file:/path/to/powershell-fix

协调过程会注意到 dsh.bundle 声明，并将 powershell-fix 追加到 dsh.profile.bundles；随包提供的 cordis.patch.yml 会在宿主层插入该插件行。重启 harness 后，该 profile 上的每个会话都会获得：

- 工具 powershell_fix
- 一个系统提示词章节，讲解原生 PowerShell 语法以及何时调用该工具

注意：pnpm 的 file: 依赖会复制 lib/*.js——编辑源码后，请删除 profile 中的 node_modules/powershell-fix 并重新运行 add 命令（“Already up to date”具有误导性）。

工具契约

// powershell_fix({ command, shell?, execute?, description? })
{
"ok": true,
"platform": "win32",
"shell": "powershell51",          // auto-detected engine: pwsh | powershell51
"original": "export A=1 && echo $A",
"fixed": "$env:A='1'; if ($?) { echo $env:A }",
"changed": true,
"fixes": [{ "rule": "ENV_EXPORT", "notes": ["…"] }],
"warnings": [{ "rule": "BARE_VAR", "note": "…" }],
"execution": { "mode": "auto", "exitCode": 0, "stdout": "…", "stderr": "…" }
// execution.mode: auto | dry-run | skipped-dangerous | aborted
}

配置（cordis 行 / dsh.bundle 默认值）：autoExecute（默认 true）、timeoutMs（默认 60000）。

开发

零运行时依赖（引擎为纯 JS）；peer 依赖 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 从宿主解析。

node --test                          # unit tests (engine, 57 assertions)
node acceptance/mount_check.mjs    # mount + live-path check
node acceptance/real_pwsh_e2e.mjs    # fixed commands executed by the real engine

中文说明

DSH host 层插件:在 Windows 终端上自动检测并修复 PowerShell 命令语法错误(bash 语法、续行符错误、粘贴带入的提示符与 CRLF),修复后经宿主 shell 缝隙执行——沙箱/审批策略与内置 pwsh 工具完全一致,危险命令只修复不执行。声明 dsh.bundle.patch,装入 profile 即对所有会话生效,无需改任何 preset。

许可证

MIT