前言¶
在 DeepSeek Harness（DSH）这类宿主环境中，智能体经常需要在 Windows 终端里执行命令。常见问题不是“会不会调工具”，而是命令本身带了 bash 习惯、粘贴提示符、CRLF 污染或断行符错误，导致工具调用先失败，再浪费一轮修复。
已有做法通常是让 agent 直接执行失败命令，或者人工检查后再执行。powershell-fix 是面向 DSH 的 host-layer 插件：它给智能体提供一个 powershell_fix 工具，先检查并修复 Windows PowerShell 命令中的常见语法问题，再通过宿主 shell 通路执行修正后的命令。执行过程继续走宿主原有的沙箱、审批和超时策略，插件本身不额外增加权限。
这是什么¶
powershell-fix 是 DSH host 层插件，仓库维护者是 GuTianshuo，许可证为 MIT，package.json 中声明的版本为 0.1.0。
它解决的是一个很具体的问题：当 bash 风格、粘贴污染或续行符错误的命令进入 Windows PowerShell 环境时，先做本地检查与修复，再决定是否执行。它把这类问题收敛到一次 powershell_fix 调用中，而不是让错误命令直接进入宿主 shell。
核心功能¶
下面介绍已核实的几类能力。
提供 powershell_fix 工具¶
插件会向 profile 暴露 powershell_fix 工具。该工具接收待检查、修复或执行的命令，并支持 command、可选 shell、可选 execute 和可选 description 等调用字段。
修复 Windows PowerShell 命令中的语法污染¶
插件可以处理几类常见的粘贴和执行前问题：
- 规范化复制粘贴带来的 CRLF 以及杂散 CR 字符。
- 去除粘贴进来的 shell 提示符。
- 修复续行符相关问题。
- 将 bash 风格的行续行转换为 PowerShell 反引号续行。
- 对无法安全重写的命令给出警告，而不是盲目重写。
正确的 PowerShell 命令会原样通过，修复逻辑也保持幂等：对已经修复过的命令再次执行修复，不会继续改变命令语义。
bash 命令到 PowerShell 的保守映射¶
插件会把一些常见 bash 命令映射为 PowerShell 等价写法；对于不适合自动改写的命令，它会提示对应的 PowerShell 思路，而不是直接替换。
这个“能改则改、不能改则警告”的策略比较重要：它降低误修风险，也保留智能体继续判断的空间。
执行走宿主 shell 通路¶
修正后的命令通过宿主 DSH 的 shell 通路执行。执行策略与宿主内置 pwsh 工具使用同一套沙箱、审批和超时策略。
也就是说，插件不绕过 DSH 的宿主控制，也不新增执行权限。它只把命令整理成更接近可执行形态，后续执行仍由宿主策略约束。
危险命令只修复，不自动执行¶
插件内置执行门禁。对于语义上破坏性较强的命令，即使命令已被修复，它也会拒绝自动执行。
已核实的拒绝类型包括：
- 根目标递归删除类命令。
Format-Volume。Clear-Disk。Set-ExecutionPolicy。del /s或del /q。- 环境或系统持久化写入类命令。
这类命令不会被自动执行，插件只会停留在修复或警告层面。
支持 dry-run¶
如果只想检查与修复，不想执行，可以使用 dry-run 模式：
{
"command": "<待检查命令>",
"execute": false
}
也可以通过配置项 autoExecute: false 关闭自动执行。
安装与启用¶
先准备本地插件目录，例如 /path/to/powershell-fix。下面命令会把插件安装到指定 profile 的 host 层：
dsh plugin --profile web add file:/path/to/powershell-fix
这里的 file:/path/to/powershell-fix 是本地路径安装方式，表示从本地目录安装，而不是从远程仓库地址拼接安装命令。
安装完成后，重启 harness。经过上面的步骤，该 profile 下的每个会话都可以获得 powershell_fix 工具。
如果后续修改了插件源码，需要注意本地 file: 依赖可能已经复制过旧的 lib/*.js。建议在 profile 中删除旧的依赖副本，再重新执行安装命令：
# 在 profile 中删除旧副本
node_modules/powershell-fix
# 重新安装
dsh plugin --profile web add file:/path/to/powershell-fix
典型用法¶
下面是 powershell_fix 的调用形态示意。command 是必填项，shell、execute 和 description 是可选字段：
{
"command": "<要检查、修复或执行的命令>",
"shell": "powershell51",
"execute": true,
"description": "check and run after fix"
}
如果只想做修复检查，不执行命令，可以这样调用：
{
"command": "<要检查或修复的命令>",
"execute": false,
"description": "fix-only dry-run"
}
配置项 autoExecute 的默认值是 true，timeoutMs 的默认值是 60000。也就是说，默认情况下，工具在修复后可能进入自动执行流程；但危险命令仍会被执行门禁拦截，不会自动执行。
开发验证¶
插件声明零运行时依赖。peer dependencies 为：
{
"peerDependencies": {
"@deepseek-ai/dsh-tools": "*",
"@deepseek-ai/schemastery": "*"
}
}
这些依赖从宿主侧解析。
开发时可以运行以下命令：
node --test
这条命令运行单元测试。
如果要检查 profile 目录的挂载与运行路径，可以运行：
node acceptance/mount_check.mjs <profile_web_dir>
其中 <profile_web_dir> 需要替换为实际的 profile 目录。
如果要做真实引擎执行检查，可以运行：
node acceptance/real_pwsh_e2e.mjs
适用场景与注意¶
它适合以下场景：
- 使用 DSH 在 Windows 上执行 PowerShell 命令。
- 智能体经常把 bash 风格命令粘贴到终端。
- 命令经常因 CRLF、提示符、续行符或引号问题失败。
- 希望先检查与修复，再进入宿主执行策略。
需要注意几点：
- 插件不额外增加权限。
- 命令执行仍走宿主 shell 通路，并受宿主沙箱、审批和超时策略约束。
- 危险命令会被执行门禁拦截，不会自动执行。
autoExecute默认为true，如果只想检查不执行，应使用execute: false或autoExecute: false。- 安装前建议先检查源码与许可证。当前仓库许可证为 MIT。
链接¶
GitHub 仓库：
