CMD 命令工具 danhcng3822f/dsh-cmd-tool

dsh-cmd-tool

一个用于 DeepSeek Harness 的 Windows cmd 工具，与现有的 pwsh 工具并存。

该包通过 cordis.patch.yml 注册两个加载器条目：

| 行 id | 加载器说明符 | 作用 |
| cmd-sandbox | dsh-cmd-tool/executor | ctx.shell 提供者：CmdSandboxExecutor |
| tool-cmd | dsh-cmd-tool | 面向模型的 cmd 工具 |

工具行的说明符是裸包名，这一点至关重要：dsh-client-modules 通过遍历宿主加载器的条目并将每个条目的 name 解析为包根来发现浏览器端部分。子路径条目永远无法解析，其包随后会被永久视为没有客户端行——因此这里的 dsh-cmd-tool/tool 会悄无声息地让该包在 Web UI 中失去其 Cmd 行。包根（src/index.ts）正是出于这个原因重新导出了工具模块，而执行器则保持为子路径条目。

ctx.shell 只接纳一个提供者，因此该执行器替换了仅支持 PowerShell 的 pwsh-sandbox 行，而不是与之并存。补丁禁用了那一行并插入自己的行。CmdSandboxExecutor 继承自 SandboxPwshExecutor，仅重写 argv() 接缝，因此它保留了所有继承的机制——ACL 隔离、拒绝与运行器失败分类、截止时间、溢出文件、后台进程句柄——并且对于任何不携带本包内部标记的命令，仍然提供 PowerShell 方言。因此，未被改动的 pwsh 工具的行为与之前完全一致。

为什么命令要通过临时脚本执行

cmd.exe 会用自己的规则重新解析其命令行，而这些规则与 Node 和 Windows ACL 运行器所采用的 CRT/CommandLineToArgvW 引用规则不兼容。因此，将模型的命令文本作为 argv 元素交给 cmd.exe 是不可行的。这一点是在目标机器上实测得出的，而非假设：

| 策略 | echo "hello world" | dir "C:\Program Files" | if exist "C:\Windows" | %USERNAME% |
| cmd /d /s /c （Node 默认引用方式） | \"hello world\" ✗ | 语法错误 ✗ | NO ✗ | ok |
| cmd /d /c 配合 windowsVerbatimArguments | ok | ok | ok | ok |
| cmd /c %DSH_CMD%（环境变量） | ok | ok | ok | %USERNAME% ✗ |
| cmd /c call %DSH_CMD%（环境变量，二次展开） | ok | ok | ok | 'if' is not recognized ✗ |
| cmd /d 并将文本通过 stdin 管道传入 | 嘈杂的横幅 + 命令回显 ✗ | — | — | — |
| cmd /d /c | ok | ok | ok | ok |

另外两项发现排除了残存的备选方案：

- windowsVerbatimArguments 无法触及。SubprocessSpawnSpec 只暴露 argv，而 subprocess-local 调用 spawn(program, args, …) 时没有此类选项。即使可以触及，sandbox-windows-acl 的运行器也会用它自己的 CRT buildCommandLine() 重建子进程命令行，因此在所有受限模式下，文本在传给 cmd.exe 的途中都会被重新篡改。
- 环境变量间接引用要么丢失 %VAR% 展开，要么破坏命令关键字，而这两者都是模型所依赖的。

因此： 该工具将命令文本写入一个临时 .cmd 文件，执行器运行 cmd.exe /d /c 。该路径不包含引号字符，因此 CRT 引用能精确地往返传递它，cmd.exe 从磁盘逐字读取命令文本。该文件是 UTF-8 不带 BOM——BOM 会破坏第一行——使用 CRLF 行尾，并以 @echo off 开头，这样解释器就不会将每条命令回显到模型的输出中。/d 跳过 AutoRun；/c 使用时不带 /s，因为 /s 会剥离包含空格的脚本路径的外层引号，而 cmd 自身的默认规则会正确地剥离它们。

该工具和执行器通过 src/protocol.ts 共享一个事实——标记前缀 dsh-cmd-script:。该标记是本包两个入口之间的内部协议，绝不能到达模型：该工具根据用户的真实命令文本提供自己的任务标签、调用卡片和渲染输出。

批处理语义

该设计被接受的后果是，命令以批处理文件语义执行，而非交互式提示符语义。实践中两个差异很重要：

- for 循环变量需要双百分号：%%i，而非 %i。 双百分号也是字面量 % 的转义。写 for %%i in (a b) do @echo item=%%i。
- %0 和 %~dp0 命名的是测试框架自身的临时脚本文件，而非工作区或调用者。使用 %CD% 获取工作目录。

%VAR% 正常展开环境变量；!VAR! 需要先执行 setlocal enabledelayedexpansion。这两个差异都在模型看到的工具描述中说明，因此模型无需自行发现它们。

安装

快捷方式

cd D:\dsh-cmd-plugin
.\install.ps1 # Windows PowerShell

cd /d/dsh-cmd-plugin
./install.sh # Git Bash

任一包装脚本都会执行下面的步骤 1–3——构建、注册、链接——然后提示你重启 dsh。它是幂等的（重新运行绝不会重复条目），接受 --profile （默认 web）和 --home （默认 $DSH_HOME，否则 ~/.dsh），并且 --uninstall 会撤销它。

逻辑位于 scripts/install.mjs，两个包装脚本只是转发给它，原因有二：配置文件清单是 JSON，而可移植地编辑 JSON 需要 jq（不保证有）或 Node（保证有——dsh 运行在它之上）；并且此插件仅限 Windows，而 bash 在 Windows 上默认未安装。在 Git Bash 下 .sh 包装脚本可用；在 WSL 下不可用，因为此插件所需的 Windows 路径在那里不存在。

没有脚本会重启 dsh。 正在运行的服务器承载着调用安装程序的 shell，因此它无法重启自身；最后一步始终由你完成。

详细方式

该包的 exports 指向 lib/（. → lib/index.js，./executor → lib/executor.js），而 .gitignore 排除了 lib/。因此，全新克隆的仓库根本没有可加载的入口点，在构建之前注册该 bundle 会因缺少 dsh-cmd-tool 而导致加载器失败。构建是第一个安装步骤，而不是事后才考虑的事。

1. 构建包

cd D:\dsh-cmd-plugin
npm run build

tsc -p tsconfig.json 将宿主部分（src/）编译到 lib/（NodeNext，声明文件输出到 lib/types/），而 node build-client.mjs 将浏览器部分（src/client/）打包进 lib/client.js。随后加载器入口和客户端入口通过包的 exports 映射进行解析。

构建需要 node_modules，所以要先执行 npm install —— 关于为什么这样做是安全的以及这些依赖是什么，请参见下文的 @deepseek-ai 导入如何解析。

npm run check 会对两部分进行类型检查。宿主的 tsconfig.json 有意
排除了 src/client/（那一部分需要 JSX 和 DOM 库）；客户端配置 tsconfig.client.json 则覆盖了它。

没有任何东西监视 src/。每次在那里修改后都要重新构建并重启，否则正在运行的服务器会继续加载之前的 lib/。

2. 在 profile 中注册该 bundle

编辑 $DSH_HOME/profiles/web/package.json（在本机上， C:\Users\Admin\.dsh\profiles\web\package.json）：

- 在 dependencies 中添加："dsh-cmd-tool": "link:D:/dsh-cmd-plugin"
- 将 "dsh-cmd-tool" 追加到 dsh.profile.bundles 数组的末尾

位置很重要：该 bundle 必须位于 @deepseek-ai/dsh-base 之后，因为它贡献的补丁层会禁用基础 bundle 插入的一行。然后安装该链接：

cd C:\Users\Admin\.dsh\profiles\web
pnpm install

3. 重启 dsh web

dsh.profile.bundles 在启动时读取，并且不会热重载。（ profile 自身的 cordis.patch.yml 会热重载；bundle 列表则不会。）
在期望 cmd 工具出现之前，请重启服务器。

同一次重启也覆盖了浏览器部分：shell 在启动时根据已安装的 dsh.client 声明组合其客户端插件图。重启后，重新加载页面 —— 浏览器运行的是之前提供的 bundle。

4. 验证组合后的树

在重启之前或之后，可以在不启动服务器的情况下转储组合后的配置：

cd D:\deepseek-harness
node --import tsx/esm apps/cli/src/bin.ts --profile web --dump-config > $env:TEMP\web-composed.yml
Select-String -Path $env:TEMP\web-composed.yml -Pattern 'pwsh-sandbox|cmd-sandbox|tool-cmd' -Context 0,4

预期：一行 pwsh-sandbox 带有 disabled: true，外加一行名为 dsh-cmd-tool/executor 的 cmd-sandbox 和一行名为 dsh-cmd-tool 的 tool-cmd。

如果 pwsh-sandbox 补丁报告 "entry not found"，请停止：此时 executor 行会与基础 bundle 在 ctx.shell 上的注册发生冲突，下一次启动将会失败。请报告这一偏差，而不是绕过它。

为什么尽管 tool-pwsh 被禁用，cmd 仍会出现这个 bundle 插入的两行都落在宿主平面上，因此 cmd 工具注册在宿主的 tools 注册表中，并且对每个会话都可见。

pwsh 工具则不是：@deepseek-ai/dsh-web-app 禁用了宿主平面的 tool-pwsh、tool-bash 和 tool-jobs 行，而 Web 界面改为通过agent preset 按会话挂载它们——对于默认的 standard preset，即 DSH checkout 中的 apps/cli/config/agent-presets/standard/agent.cordis.yml。该 preset 的 tool-pwsh 消费了此 bundle 提供的宿主平面 ctx.shell，这就是为什么替换 pwsh-sandbox 能让 pwsh 继续工作，而不是将其破坏。--dump-config 转储只显示宿主组合，因此其中出现被禁用的 tool-pwsh 行是预期行为，并不意味着 pwsh 工具消失了。

Web UI 中的 Cmd 行

如果没有本包附带的浏览器端部分，cmd 调用会渲染为通用的 "Tool call" 行。Web 客户端通过 dsh-client-ui-tool 私有的表（TOOL_VARIANTS / TOOL_TITLES）对工具行进行分类；未列出的工具名会落入 others 变体，其标题就是字面量 "Tool call"。更糟的是，由于通用卡片优先使用终端视图的描述，而不是从参数派生的摘要，工具自身的名称根本不会到达该行——toolName 只是一个 data-tool 属性。

设计上的补救措施是带键的 tool.call.toolview 座位：注册的键会替换通用行。src/client/ 注册了 cmd 键，其行标题为 "Cmd"，携带该调用的终端卡片，因此它作为 shell 工具之一与 Bash 和 Pwsh 行并列，而不是作为一个未分类的行。

这一半是独立的构建，也是独立的生命周期：

- node build-client.mjs 将 src/client/index.tsx 打包进 lib/client.js（esbuild，CommonJS 闭包工厂，externals 从 shell 自身的 PLATFORM_MODULES 列表实时读取，因此模块标识不会漂移）。npm run build 在 tsc 之后运行它。
- package.json 的 dsh.client 块声明了平台（web）以及必须首先挂载的客户端插件，shell 的模块扫描正是通过这种方式发现这一半。该扫描在启动时运行，因此添加或移除该块需要重启服务器。
- 它仅使用平台模块来组合该行（@deepseek-ai/dsh-client-ui-primitives 提供 DisclosureRow、StateDot、TerminalBlock 和图标；@deepseek-ai/dsh-client-ui-slots 提供 locale 座位）。dsh-client-ui-tool 不是共享平台模块，因此它的行组件和卡片模型无法从这里导入——这就是在 src/client/CmdRow.tsx 中重新实现的原因。
- 该行携带自己的 locale 命名空间（cmd-tool），而不是借用对话的命名空间，后者的字典同样无法导入。它的终端字符串是有意从该字典复制的：TerminalBlock 的内置标签默认是中文，因此省略 labels 会悄悄地将中文混入英文 UI。
- 样式是内联的，而不是 CSS 模块：CSS 导入会让 esbuild 生成一个没有任何东西加载的同级样式表。行的外观来自 DisclosureRow，其样式随 shell 一起提供。

@deepseek-ai 导入如何解析

此插件导入的每个 @deepseek-ai/ 包都在 dependencies 中声明为直接指向其在 DSH 检出目录中所在目录的 file: 链接——例如 "@deepseek-ai/dsh-pwsh-sandbox": "file:D:/deepseek-harness/packages/shell/pwsh-sandbox"。npm 会为这些创建符号链接，因此导入会解析到正在运行的 dsh 所加载的确切模块。

从 npm 安装相同的包正是要避免的情况：树中出现第二份 @deepseek-ai/cordis 副本会破坏该插件。请固定到你实际正在运行的检出目录。

这些路径是绝对路径且因机器而异——D:/deepseek-harness 是本机的检出目录。在另一台机器上，请在 npm install 之前重写这些 file: 路径（或重新运行生成它们的生成器）。

不要用指向 $DSH_HOME/profiles/node_modules/@deepseek-ai 的 node_modules/@deepseek-ai 联接来替换这些。* 那是此包最初的设计，而且它具有破坏性：npm install 会把联接目标当作自己的树，修剪其中的符号链接，并清空所有通过它解析的包的 DSH 模块回退——而不仅仅是这一个。如果发生这种情况，回退会在下一次 dsh 启动时由 healProfilesModuleFallback 重建；若要在不重启的情况下修复它，请从检出目录中已构建的 @deepseek-ai/dsh-app-boot 运行该导出，并以应用清单路径（apps/cli/package.json）作为其参数。

确认解析指向的是 harness 包而不是副本：

node -e "console.log(require.resolve('@deepseek-ai/dsh-pwsh-sandbox/package.json',{paths:['D:/dsh-cmd-plugin']}))"

配置

工具（tool-cmd）行：

| 旋钮 | 默认值 | 效果 |
| enableRunInBackground | true | 声明并接受 run_in_background。当为 false 时，该参数会从 schema 中省略，并且在执行时被拒绝。 |
| setCodePage | true | 生成脚本的 chcp 行。 |
| codePage | 65001 | 该行设置的代码页（UTF-8，即子进程收集器解码所用的代码页）。 |
| scriptDir | /dsh-cmd | 每个进程的临时脚本目录的根目录。 |

执行器（cmd-sandbox）行：

| 旋钮 | 默认值 | 效果 |
| cmdPath | 已解析 | 显式的 cmd.exe。省略时，先探测 %ComSpec%，然后探测 \System32\cmd.exe；两者都失败时，将裸名称 cmd.exe 留给 PATH 解析。 |

执行器还通过 SandboxPwshExecutor.Config 继承每个 dsh-pwsh-local 旋钮：cwd、timeoutMs、maxTimeoutMs、 maxOutputBytes、maxSpillBytes、graceMs 和 pwshPath。

cmdPath 和 codePage 仅是组合入口旋钮，不是 settings.yaml 旋钮。 codePage 属于该工具，而 dsh-tool-pwsh 的形状——它这个工具是镜像式的——完全不安装设置部分，因此工具的配置来自组合入口。cmdPath 属于执行器，其继承的构造函数用 dsh-pwsh-local 的 schema 注册了 shell 设置命名空间，而该 schema 并未声明此字段。

要覆盖，可通过编辑某个 profile 自己的 cordis.patch.yml 中的该行，重新声明整个 config 值——补丁会替换某一行的 config，而不是合并它。

已知限制

- 渲染器是冻结的副本。 src/render.ts 和 src/background.ts 是 @deepseek-ai/dsh-tool-pwsh 对应文件的刻意孪生副本，因为 dsh-tool-pwsh 没有导出 ./render 子路径，而其 ./src/ 是 TypeScript 源码，已构建的安装无法加载。因此上游的渲染修复不会到达此包；必须手动移植。
- 上游耦合。 该包继承 SandboxPwshExecutor 并禁用 pwsh-sandbox 行。如果某个 DSH 版本重命名了该行或更改了 SandboxPwshExecutor.argv，就需要重新审视此包。失败模式是在 ctx.shell 重复时启动时大声失败（shell 服务只接受一个提供者，同时挂载两者会在重复服务注册时失败）——绝不会是静默失败。
- 浏览器端与客户端的私有行表耦合。 它之所以存在，正是因为 TOOL_VARIANTS / TOOL_TITLES 位于 dsh-client-ui-tool 内部，无法从外部扩展；如果未来的版本使它们可扩展——或者只是列出 cmd——这一行就变得多余，应当删除而不是维护。它还重新实现了 terminalCardModel 的推导逻辑，因为 dsh-client-ui-tool 不是共享平台模块；上游对 callView / resultView 线格式的更改必须手动移植到这里。
- engines.node 声明为 >=22.0.0，但提交的 vitest 拉取的 vite 要求 >=22.12.0（vite 7.3.6 声明 ^20.19.0 || >=22.12.0）。这仅影响开发：已发布包的运行时要求是所声明的 >=22.0.0。相关地，npm run check 不会对 tests/ 进行类型检查——tsconfig.json 只包含 src//.ts。
- 临时脚本的生命周期。 脚本位于 /dsh-cmd// 下，并在调用结束时被移除（后台调用随作业一起处置它们的脚本）。移除是尽力而为的：刚退出的 cmd.exe 或扫描器仍可能持有该文件，移除失败会留下文件，直到 24 小时清理（pruneStaleScriptDirs，它使用目录年龄，因为无法区分已死 pid 和被复用的 pid）。脚本还位于工作区之外；在两种受限模式下读取都不受限制，因此受限子进程始终可以读取自己的脚本，而写入发生在不受限的宿主进程中。
- chcp 会更改与宿主终端共享的控制台代码页—— pwsh-local 的编码前导码已经具有相同的副作用。设置 setCodePage: false 可抑制它。
- 集成测试套件在非 Windows 上会自动跳过（describe.skipIf(process.platform !== 'win32')）。
该跳过路径在此主机上未经验证，而此主机仅支持 Windows：该测试套件在此处从未真正被观察到走跳过分支。
- 成本。 每次调用多一次文件写入，以及一次 unlink。前台调用在调用内完成这两者；后台调用会持有该文件，直到其进程结束。

测试

cd D:\dsh-cmd-plugin
npx vitest run # 80 tests across 7 files
npm run check # type-checks both halves (host + client)

如果缺少 node_modules，请运行 npm install：@deepseek-ai/ 依赖是 file: 链接，因此 npm 会恢复它们，而不是修剪一个共享目录（参见 @deepseek-ai 导入如何解析）。

tests/integration.spec.ts 通过真实的 CmdSandboxExecutor 和 ctx.tools.execute() 来演练真实的 cmd.exe：包含空格的带引号路径、 %VAR% 展开、if exist … else、多行 if 块、对集合使用 for %%i、输出重定向、exit /b N、最后状态为非零的命令、 Unicode echo、workdir 被遵守，以及一个用 job_output 收集并用 job_kill 停止的后台作业。它还证明 PowerShell 方言仍然通过同一个执行器运行。该测试套件在非 Windows 上会自动跳过，因此在 Windows 上的一次绿色运行是唯一能证明任何事情的运行。

它的第二个块在 workspace-write 下组合相同的栈——这是此包作为默认值发布的模式——因此被标记的命令确实会经过 Windows ACL 运行器：受限命令会运行并返回其输出，工作区内的写入会成功，而工作区外的写入会被拒绝并渲染为 [sandbox: file access denied under workspace-write mode]。该块安装了 ctx.sandbox.internals.windowsAclRunnerEntry，即核心提供者自己的测试钩子，并且仅出于一个原因：dsh-sandbox-local 通过 import.meta.resolve 定位运行器，而 vitest 的 SSR 转换——@deepseek-ai/ 会触及它，因为那些 file: 链接解析到本项目之外——会将 import.meta 重写为一个没有 resolve 的 shim。如果没有这个替换，这里的每个受限调用都会在任何运行器生成之前以 __vite_ssr_import_meta__.resolve is not a function 失败，因此此包中的任何测试套件都无法演练限制。该钩子会短路那一次调用并替换为真实的运行器路径；运行器、受限令牌、ACL 授予以及拒绝分类全都是生产环境的。

其余六个测试套件与平台无关，并使用假执行器或纯函数：protocol.spec.ts（标记往返）、resolve.spec.ts （cmd.exe 解析分支）、script.spec.ts（脚本体、编码、CRLF 规范化、处置、修剪）、render.spec.ts（结果渲染）、 executor.spec.ts（argv 覆盖和组合后的 Config schema），以及 tool.spec.ts（消费者接口——注册、验证、升级门控、每条路径上的释放、presentResult）。

许可证

MIT——参见 LICENSE。

版权所有 (c) 2026 danhcng3822f。