DeepSeek Harness (dsh) 插件：dsh-niubash-only

前言¶

DeepSeek Harness（dsh）的插件生態強調“一切皆插件”。在 Windows 環境下，智能體模型容易習慣性地使用 PowerShell 或 CMD 的語法。這些命令在 Niubash 中往往不會報錯，而是產生靜默錯誤（例如 $env:PATH 會被當作空變量展開爲 :PATH，退出碼爲 0）。dsh-niubash-only 旨在解決這一問題，通過接管執行層、強制單一環境以及提供教學層，確保模型在 Windows 上也能寫出正確的 Bash 代碼。

插件定位¶

定位：DeepSeek Harness (dsh) bundle：Niubash 作爲唯一 shell 執行器 + Bash-on-Windows 教學。
作者：YMRwithNoworry
許可證：MIT

核心功能¶

該插件通過四個層級配合解決兼容性問題：

接管執行層
插件接管 ctx.shell 執行層，禁用第一方的 bash-sandbox / pwsh-sandbox，替換爲 dsh-niubash-only/executor。所有 shell 執行統一轉換爲 niu -c "<command>"。超時、輸出上限、spill 文件、後臺句柄等邏輯繼承第一方實現，但默認直接在本機運行（sandbox: false），不進行額外包裹。
拒絕其他 Shell（強制層）
執行器內置守衛，拒絕將執行權交給其他 shell（如 pwsh、powershell、cmd /c、wsl、nu、zsh 等）。對於 bash / sh，插件會探測本機同名命令是否解析到 Niubash 安裝目錄，否則一律拒絕。
方言預檢層
在命令執行前，插件會檢查並拒絕 PowerShell/CMD 的習慣寫法（如 $env:VAR、Get-ChildItem、if ($x...) 等），並將正確的 Bash 寫法寫入錯誤文本。字符串、註釋和 heredoc 體會被遮蔽，避免誤判。
教學層與失敗提示
註冊在宿主平面的教學層，包含 shell: niubash-rules（規則）、shell: niubash-guide（Bash on Windows 手冊）以及工具描述重寫。執行失敗時，stderr 末尾會追加一條基於真實錯誤的糾錯提示。

安裝與啓用¶

前置條件：
* dsh 版本 >= 0.2.0-rc.2
* Node.js >= 22.19.0
* 安裝 Niubash 1.1.4（配合 WinuxCmd 1.0.8）

安裝命令：

# 通過 GitHub 安裝
dsh plugin --profile web add github:YMRwithNoworry/dsh-niubash-only

# 或從 npm 安裝（確保 dsh 版本匹配）
dsh plugin --profile web add dsh-niubash-only

啓用前必讀：
dsh 0.2.0-rc.2 起會按 peerDependencies 校驗運行時版本，不匹配會拒絕安裝。安裝後必須重啓 profile。

衝突處理：
一個上下文只允許一個 ctx.shell 提供者。如果 profile 中已有其他 shell 執行器（如 dsh-nushell-only 或 @cmx666/dsh-winuxsh-bundle），必須先卸載或禁用，否則啓動會因重複註冊失敗。常見操作：

# 卸載衝突插件
dsh plugin --profile web remove dsh-nushell-only
dsh plugin --profile web remove @cmx666/dsh-winuxsh-bundle

驗證安裝：

dsh --profile web --dump-config | grep -n niubash

期望輸出應包含 niubash-executor 和 niubash-teaching 配置項，且 bash-sandbox / pwsh-sandbox 被禁用。

配置說明¶

插件默認通過 cordis.patch.yml 注入配置，主要包含兩個部分：

- id: niubash-executor
  name: dsh-niubash-only/executor
  config:
    timeoutMs: 120000
    enforceNiubashOnly: true   # 拒絕切換 shell
    dialectLint: true          # 預檢方言錯誤
    dialectHints: true         # 失敗時給提示
    sandbox: false             # 默認不啓用沙箱包裹

- id: niubash-teaching
  name: dsh-niubash-only/teaching
  config:
    guide: full                # 提供完整 Bash on Windows 手冊
    rewriteToolDescriptions: true

適用場景與注意事項¶

適用場景：在 Windows 環境下使用 DeepSeek Harness 開發智能體，希望強制模型使用 Bash 語法而非 PowerShell，或需要解決 Windows 原生 Shell 的兼容性難題。
權限注意：默認配置下 sandbox: false，執行直接在本機進行，結果事實會如實報告 mode: danger-full-access。
依賴注意：需確保本機 PATH 中存在 niu.exe，否則每次調用都會失敗。

總結¶

dsh-niubash-only 通過接管 ctx.shell 接口，配合方言預檢和教學層，將 Windows 上的智能體開發環境強制統一爲 Niubash。它不依賴沙箱隔離，而是通過嚴格的語法檢查和錯誤提示來保證執行的正確性，適合需要穩定 Bash 交互的開發者。