前言¶
在 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 倉庫：
