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 交互的开发者。