前言¶

DeepSeek Harness (DSH) 採用插件化架構，旨在通過系統提示注入來規範智能體的行爲。在現有的 DSH 插件生態中，多數針對 WSL（Windows Subsystem for Linux）的插件假設環境是從 WSL 向外橋接的。如果你在原生 Windows（無 WSL）環境下運行 DSH，現有的插件無法覆蓋 PowerShell 的原生特性。

在原生 Windows 上直接使用 PowerShell 時，智能體常在命令鏈、編碼處理和文件系統交互上犯錯。dsh-windows-native 插件通過注入一份系統提示，將這些常見的“腳註陷阱”提前告知智能體，避免其在執行過程中反覆試錯。

插件介紹¶

dsh-windows-native 是一個專門針對原生 Windows (non-WSL) 環境的 DSH 插件。它不提供外部工具或二進制文件，而是一段系統提示注入，用於指導智能體在處理 PowerShell 語法、控制台編碼以及 Windows 文件系統特性時的正確做法。

該插件由 lucifergzsz414 維護，採用 MIT 許可證。它基於作者在原生 Windows 環境中踩過的實際坑點整理而成，目前處於早期階段。

核心功能¶

插件通過系統提示告知智能體以下 Windows 環境下的關鍵細節：

1. 命令鏈與執行邏輯¶

PowerShell 5.1 等原生版本不原生支持 && 或 || 命令鏈。
* 使用 ; 替代：如果需要順序執行，請使用分號 ;。
* 替代寫法：也可以使用 A; if ($?) { B } 的形式。
* SSH 調用陷阱：在 PowerShell 中轉發包含嵌套引號的 SSH 命令（如 ssh host "sudo python3 -c \"...\"") 可能會靜默掛起。建議將命令寫入本地文件，然後通過 scp 傳輸執行。

2. 編碼與文本處理¶

Windows 控制台通常不是 UTF-8，且 Python 的 subprocess 會使用系統區域設置（中文 Windows 默認爲 GBK）解碼子進程輸出。
* 控制台輸出：不要依賴控制台顯示的中文文本，即使數據本身是正確的，顯示可能已亂碼。
* 避免內聯多行非 ASCII 文本：不要通過 -c "..." 或內聯 heredoc 傳遞多行非 ASCII 文本，應先寫入文件再運行。
* Python subprocess：顯式指定 encoding="utf-8", errors="replace"，否則子進程可能因解碼錯誤而崩潰。
* 文件寫入：Set-Content 和 Add-Content 默認使用系統 ANSI 編碼（中文 Windows 爲 GBK），寫入中文文本時需添加 -Encoding utf8 參數，否則磁盤文件會損壞。

3. 文件系統與系統保留名稱¶

• 符號鏈接與 Junction：創建 junction 或 symlink 需要管理員權限或開啓開發者模式。若權限不足，操作會靜默失敗，請檢查實際是否存在。
• 保留名稱：NUL、CON、PRN、AUX、COM1-9、LPT1-9 在 Windows 的任何目錄下都是保留名稱。不要嘗試使用 > nul 重定向輸出，這可能會創建一個名爲 nul 的文件。請使用 $null 或 Out-Null。
• Office 文件鎖定：如果文件被 Word、Excel 或 WPS 打開，嘗試寫入會拋出普通的 PermissionError，這不是數據損壞，無需重試。

4. 工具特定問題¶

• Docker 卷掛載：在 docker run 中使用 -v "C:\path\file.yaml:/container/path:ro" 時，路徑中的冒號 : 可能導致掛載被錯誤拆分，導致掛載失敗但容器仍顯示健康。建議使用 docker exec 進入容器檢查文件。
• Node.js 二進制文件：在此插件構建的目錄中構建的 .node npm 綁定是 Windows 二進制文件。如果將其部署到 Linux 服務器，程序會在運行時報錯，儘管 npm install 可能成功。
• 進程終止與端口釋放：殺死外層任務運行器（如 job wrapper）並不會釋放端口，如果底層的 node/python 進程仍在運行，端口仍被佔用。必須找到真實的 PID 進行終止。
• 計劃任務無窗口：即使使用 -WindowStyle Hidden，計劃任務有時仍會閃爍控制台窗口。要實現完全無窗口運行，應使用 pythonw.exe 配合 CREATE_NO_WINDOW 標誌。

安裝與啓用¶

通過 DSH 的插件管理器安裝該插件：

dsh plugin add dsh-windows-native

安裝後，需要在配置文件中指定注入條件。默認情況下，插件會僅在檢測到 windows 時生效，但你可以調整配置：

when: windows   # 僅在原生 Win32 環境注入，或改爲 "always" 全局注入
order: 15       # 確保在其他系統提示注入之後執行
extraNotes: ""  # 可在此處追加自定義備註

適用場景與注意¶

• 適用場景：直接在原生 Windows (PowerShell) 上運行 DeepSeek Harness，且環境爲非 WSL。
• 注意：該插件本質上是一段系統提示注入，會直接修改智能體的行爲模式。在安裝前，建議查看其源碼以確保符合你的安全策略。
• 狀態說明：插件目前處於早期階段，列表長度基於作者的個人踩坑經驗，可能並非涵蓋所有 Windows 腳註。如果遇到插件未覆蓋的問題，請直接提交包含實際失敗信息的 PR。

結尾¶

dsh-windows-native 爲在原生 Windows 上構建智能體提供了基礎的防禦機制。它將複雜的系統特性轉化爲清晰的指令，幫助智能體規避編碼和文件系統層面的常見錯誤。更多細節和源碼，請查閱插件目錄或 GitHub 倉庫。