dsh-nushell-only

English | 中文

把 DeepSeek Harness（dsh）的唯一 shell 换成 Nushell，并教会模型写 Nushell 语法的 Profile Bundle。

适配版本：dsh 0.1.5-rc.2（在 0.1.5-rc.2 与 0.1.5-rc.1 CLI + 0.1.5-rc.2 库上实测通过）。运行时要求 Node >=22.19.0、Nushell（实测 0.115.1，建议 >=0.100）。

它做了什么

一个插件、三件事，互相配合：

1. 接管 ctx.shell（执行层） bash-sandbox / pwsh-sandbox 两个第一方执行器被禁用，换成 dsh-nushell-only/executor：所有 shell 执行一律变成 nu --no-config-file -c "<command>"。 因为换的是能力接缝（capability seam）而不是模型工具，所以 dsh 里所有走 ctx.shell 的消费者都会用 Nushell：模型工具、后台任务（run_in_background）、hook 桥（dsh-hooks-*）、tmux-context、以及任何进程内插件调用。超时、输出上限、spill 文件、后台句柄、取消、沙箱策略与拒绝事实全部沿用第一方实现（继承 SandboxBashExecutor / SandboxPwshExecutor，只替换 argv）。 同时 --no-config-file 保证用户自己的 config.nu / env.nu 不会影响工具调用结果。

2. 拒绝"换个 shell 跑"（强制层） 执行器里带一个窄口径守卫：命令若在语句开头把执行权交给别的 shell（bash -c、sh -c、cmd /c、pwsh -Command、wsl …，含 sudo / env / busybox 包装与 ^bash、路径形式），直接以清晰的错误拒绝，并给出 Nushell 写法对照——而不是让模型收到一个看不懂的 Nu 解析错误。默认开启，可用 enforceNushellOnly: false 关闭，或用 foreignShellAllowlist 给个别调用点开白名单。

3. 教学层（提示词层）

   • shell: nushell-rules：强制规则（方言、每次调用全新进程、workdir、不许换 shell、数据是结构化的）。
   • shell: nushell-guide：语法手册 + bash/PowerShell → Nushell 对照表 + 常见坑；每次装配时求值，因此会带上探测到的 Nushell 版本号。
   • 把模型看到的 bash / pwsh 工具描述与 command 参数说明改写成 Nushell 方言（工具名字保持不变，避免破坏 preset、toolOrder、AGENTS.md 等对工具名的引用）。 教学层注册在宿主平面：即使 web 模式的 shell 工具来自 agent preset（独立 scope），描述重写与手册依然生效（已由集成测试验证）。

安装

# 从 GitHub 直接安装进某个 profile（推荐，不需要 npm 发布）
dsh plugin --profile web add github:YMRwithNoworry/dsh-nushell-only

# 锁定提交可复现（可选；把 <sha> 换成 README 所在提交）
dsh plugin --profile web add github:YMRwithNoworry/dsh-nushell-only#<sha>

# 或安装本地 checkout
dsh plugin --profile web add file:/path/to/dsh-nushell-only

安装后重启该 profile。npm 包名 dsh-nushell-only 目前尚未发布；上面的 GitHub 形式是无需 npm 账号即可使用的安装方式。dsh plugin 会把包登记进 dsh.profile.bundles（本包声明了 dsh.bundle.patch），补丁层会把上面两行插进组合树。

先卸掉旧的 dsh-nushell：一个上下文只允许一个 ctx.shell 提供者。如果 profile 里已经有 dsh-nushell（或任何其他 shell 执行器 bundle），请先：

dsh plugin --profile web remove dsh-nushell

否则启动时会因重复注册 shell 服务而失败。

验证：

dsh --profile web --dump-config | grep -n "nushell"
# 期望看到：bash-sandbox / pwsh-sandbox = disabled，以及 nushell-executor、nushell-teaching 两行

配置

补丁层默认配置（cordis.patch.yml）：

- id: nushell-executor
  name: dsh-nushell-only/executor
  config:
    timeoutMs: 60000
    maxTimeoutMs: 600000
    maxOutputBytes: 64000
    graceMs: 3000
    enforceNushellOnly: true   # 拒绝把命令交给别的 shell
    requireNu: true            # 找不到 nu 就启动失败（而不是每次调用都失败）
    verifyNu: true             # 启动时跑一次 `nu --version`

- id: nushell-teaching
  name: dsh-nushell-only/teaching
  config:
    guide: full                # full | compact | off
    rules: true
    rewriteToolDescriptions: true

执行器可选项：

字段	默认	含义
nuPath	$DSH_NU_PATH → nu	Nushell 可执行文件；优先级：本字段 > 环境变量 > PATH
nuArgs	['--no-config-file','-c']	argv 前缀，命令追加在最后
enforceNushellOnly	true	守卫开关
foreignShellAllowlist	[]	整条命令匹配的正则（字符串），命中则放行
requireNu	true	无法解析 nu 时启动即失败
verifyNu / verifyTimeoutMs	true / 10000	启动探测 nu --version 及其超时

cwd、timeoutMs、maxTimeoutMs、maxOutputBytes、maxSpillBytes、graceMs 沿用 dsh 自己的 shell 设置命名空间，settings.yaml 的 shell: 段仍然可以热改预算。

在本 profile 的 cordis.patch.yml 里按 id 覆盖即可，例如：

- id: nushell-executor
  config:
    nuPath: 'C:\Users\me\AppData\Local\Programs\nu\bin\nu.exe'
    enforceNushellOnly: false

"只用 Nushell" 的边界

插件能保证的是经过 ctx.shell 的一切都是 Nushell。以下情况它管不到，README 明说，避免误判：

1. preset 里自己 spawn shell 的行。例如本机 ~/.dsh/.agent-presets/liangshen/agent.cordis.yml 的 custom-bash.mjs（Windows 上直接 ctx.subprocess.spawn(['bash.exe','-c',...])）与 persistent-shell 组（PTY 常驻 bash）。这类工具绕开 ctx.shell，插件既无法改写它的执行，也不会改写它的描述（描述重写只针对自称 bash -c / pwsh -Command 的第一方工具，以免说谎）。要用 Nu-only，请在这些 preset 文件里把对应行 disabled: true（Windows 上 tool-pwsh 会通过 ctx.shell 变成 Nu，可以顶上），或把 persistent-shell 组整体禁用。
2. 嵌套调用。nu -c 'bash -c "..."' 里层是字符串参数，守卫按设计不看字符串内部；nu 当然也能启动别的程序。守卫挡的是"模型想绕过 Nu"这类显式 handoff，不是沙箱。
3. dsh-hooks-claude-code / dsh-hooks-codex 的 hook 命令。它们通过 ctx.shell 执行，现在就是 Nushell：为 bash 写的 hook（&&、$VAR、export）会失败。要么把 hook 改写成 Nushell，要么给执行器关掉守卫/把 profile 里的 hook 桥禁用。
4. TUI 的常驻 PTY shell（dsh-terminal-bash + dsh-tool-bash-persistent）走的是 terminal 接缝，不是 ctx.shell，插件不替换它。需要常驻 Nu 会话时目前只能自行把这两行换成 dsh-terminal-bash 的 shellPath: nu 变体（readiness 会退化为"输出静默推断"，未在本包内验证），或者改用一次性工具。

沙箱与权限不变：danger-full-access 直接执行，受限模式仍然经 ctx.sandbox.confine() 包裹 Nu 的 argv，并照常上报 mode / denied / enforcement 事实（Windows ACL 链与 POSIX 链接口均已实测包裹成功）。

教学层给了模型什么

guide: full 时，系统提示里会出现（顺序紧贴 shell 工具引导位）：

• 规则段：方言是 Nushell、每次调用全新进程（cd/let/$env 不保留，用 workdir）、不加载 config.nu、换 shell 会被拒、管道里是结构化数据、open --raw 读文本。
• 语法手册：let/mut/$env/插值/if/match/def/try/for；表与列表（where/select/get/sort-by/each/group-by）；外部命令（^git、complete、退出码）；文本处理（split row/parse/lines/str *）；路径与环境（path *、$nu.*、单引号与转义）。
• 对照表：&&、$VAR、export、$(...)、a > f、cat|grep、head/tail/wc、sed -n、find、xargs、rm -rf… 的 Nushell 写法。
• 坑：空匹配的 ls **/*.md 会报错（用 glob）、> 是比较不是重定向、open 可能返回结构化文本、内建命令会遮蔽同名外部程序、sort-by 需要列名、大小/时长是有类型的值。

手册里的每个 nu 代码块都会被 test/guide.test.mjs 用本机真实的 nu 跑一遍，所以例子不是"看起来对"，而是跑得通。

开发与验证

node --test test/                 # 36 个单元测试（守卫 / 手册 / 教学层 / 执行器 argv 与沙箱路径）
node test/integration.mjs         # 端到端：建临时 DSH_HOME、装 profile、真实启动、20 项断言
node test/integration.mjs --mode workspace-write   # 受限沙箱模式下再跑一遍

集成测试会依次验证：ctx.shell 就是 NushellExecutor、nu --version、Nu 内建管道、表管道、外部命令、非零退出以结果上报、外部 shell handoff 被拒、系统提示含规则/手册/对照表、bash/pwsh 描述与参数说明已改写、preset 子 scope 里的 shell 工具同样被改写、沙箱事实正确上报。可用 DSH_INTEGRATION_CLI=/path/to/@deepseek-ai/dsh/lib/bin.js 指定要驱动的 CLI。

node dev/link-peers.mjs 把本机的 dsh 安装里的 @deepseek-ai/* 软链到 node_modules/，供 checkout 直接跑测试（正式安装由 pnpm + dsh 自身的模块回退负责）。

排错

现象	处理
启动报 cannot resolve the Nushell executable	装 Nushell / 把 nu 加进 PATH / 设 nuPath 或 DSH_NU_PATH；临时先跑可设 requireNu: false
启动报 failed its --version probe	nu 不可执行或损坏；verifyNu: false 可跳过探测
启动报重复注册 shell 服务	还有别的 shell 执行器 bundle（如 dsh-nushell）没卸掉
工具调用报 Nushell-only shell: refusing …	模型在写别的 shell；让它按错误提示改写成 Nushell，或确有需要时用 foreignShellAllowlist
模型仍写 bash	检查 guide: full、rewriteToolDescriptions: true；再看模型侧 toolOrder/preset 是否把 shell 工具换成了自建工具

许可

MIT。