RTK 命令重写 mengqi1436/DSH-Rtk-rewrite

dsh-pwsh-rtk-rewrite

一个原生 rtk 桥接插件，用于 DeepSeek Harness（DSH）：它把桌面配置档的 shell 执行器替换成 rtk 重写子类，于是每条 pwsh shell 命令在执行前都会透明地经 rtk rewrite "<cmd>" 重写，让 rtk 的紧凑输出格式在每次工具调用时都省下 token。

已在真机验证（2026-09-25，dsh 0.1.7-rc.2 + rtk 0.50.0 + Node v24.19.0）：

[rtk-rewrite] "git status" -> "rtk git status"
[rtk-rewrite] "cat E:\\CLI\\dsh-web.log" -> "rtk read E:\\CLI\\dsh-web.log"
Even compound commands are rewritten segment by segment:
"cat a.log; git status; grep -c x b.log"
-> "rtk read a.log; rtk git status; rtk grep -c x b.log"

命令一跑，rtk gain 就实时上涨（实验：Total commands 10274 → 10277，与 dsh-web.log 里 3 行重写日志一一对应）。

兼容性

0.2.0（验证于 2026-09-29）：@deepseek-ai/dsh-pwsh-sandbox@0.2.0-rc.1 的 lib/index.js 与 0.1.7-rc.2 逐字节相同（252 行，0 diff）。SandboxPwshExecutor 具名导出、execute(spec) 签名、resolve() 策略戳层全都没变——本插件无需改代码；peerDependencies 已放宽到 >=0.2.0-rc.1 <0.3.0-0（自 v1.1.0 起）。

0.2.0-rc.2（验证于 2026-09-30）：@deepseek-ai/dsh-pwsh-sandbox@0.2.0-rc.2 的 lib/index.js 与 0.2.0-rc.1 逐字节相同（SHA256 同为 BED19D2C…，252 行，0 diff）。包内唯一的变化是 package.json 里的版本号（rc.1 → rc.2）——rc.2 里那个常驻 PowerShell 修复（「完成状态后跟空格时命令结束检测失败，导致丢失退出码或泄漏内部标记」）位于 dsh 内核，不在这个 sandbox 包里。桌面版 0.2.0-rc.2 app.asar 内附带的 dsh-pwsh-sandbox 副本也提取出来比对过：与 npm 上的 rc.2 逐字节相同（SHA256 一致）。

桌面版适配（2026-09-30 真机验证并修复，v1.1.3）：桌面版 0.2.0-rc.2 的 dsh 内核打包在 resources\app.asar 里；桌面配置档的依赖链和 node 目录布局都解析不到内核包，于是插件原有的四条探测链全部落空 → rtk-pwsh-shell 服务加载失败，补丁悄悄回退到原生 shell（装配层的补丁声明本身没错——实际探测 loadProfileDirectory 已确认）。v1.1.3 新增第五条 Electron 桌面布局探测链 <exe dir>\resources\app.asar\dsh\node_modules\@deepseek-ai\dsh，在桌面主进程里能命中（多亏 Electron 的 asar fs 支持）；node test.js 在同一形态下 6 项检查全过。装完 v1.1.3 后重启桌面应用即可，不需要 DSH_INSTALL_PACKAGE_JSON。

环境要求

- DeepSeek Harness ≥ 0.1.7（含 0.2.0-rc.1 / 0.2.0-rc.2） 桌面应用（dsh 命令行，配合 dsh plugin 机制）
- PATH 上有 rtk ≥ 0.50.0（rtk rewrite 子命令可用；用 RTK_BIN 环境变量指向别名）。契约已对照 rtk 0.51.0 在 2026-10-03 重新验证：退出码语义未变。
- Windows + PowerShell（插件替换 pwsh 执行器；bash 及其他 shell 工具不受影响）

工作原理

DSH 的插件系统（cordis）允许 bundle 通过补丁声明替换服务线。每个上下文只允许一个 ctx.shell 实现，所以补丁做两件事：

1. 禁用原执行器：- id: pwsh-sandbox / disabled: true
2. 插入本插件：insert: - id: rtk-pwsh-shell / name: 'dsh-pwsh-rtk-rewrite'

加载后，shell 能力由 RtkPwshExecutor 提供：

execute(spec)
├─ RTK_DISABLED=1 ? ────────────────► run as-is
├─ command starts with "rtk "/"rtk.exe " ? ──► run as-is (recursion guard)
├─ rtk rewrite "<cmd>" (5s timeout)
│ ├─ exit 3 + stdout ──► super.execute({...spec, command: rewritten})
│ ├─ exit 1 ──► no rtk equivalent (pwsh cmdlets etc.), silently run as-is
│ ├─ ENOENT ──► rtk not on PATH, warn once then run as-is
│ └─ timeout/other ──► run as-is
└─ super.execute(spec) (SandboxPwshExecutor: sandbox confine wraps the rewritten command)

关键设计决策

- 故障安全：任何重写失败（rtk 缺失、无等价命令、超时、报错）都执行原命令。本插件绝不会阻塞或拒绝执行——它只做加法。
- 沙箱语义完整保留：只覆盖 execute(spec)；resolve()（沙箱策略戳）不动。spec 以 { ...spec, command: rewritten } 传下去，workdir/timeoutMs/signal/stdin/env 及所有沙箱字段原样保留。沙箱 confine 包裹的是重写后的命令。
- spec.command 是原始命令：UTF-8 前导只在 PwshLocalExecutor（lib/index.js）内部的 spawnSpec 层添加，所以 execute() 看到的命令文本可以直接喂给 rtk rewrite。
- 内置包从 dsh 安装本身解析：npm 上的 @deepseek-ai/dsh-pwsh-sandbox 副本常常滞后于（或偏离）运行中宿主自带的副本（registry 曾长期停在 0.1.5-rc.3；0.2.0 恢复发布，但桌面 bundle 仍可能组装出不同的 rev），所以核心包声明为 peerDependency（供市场做宿主感知的兼容性发现），运行时则按顺序自动探测： DSH_INSTALL_PACKAGE_JSON 环境变量 → 常规依赖链 → Windows 布局 <node dir>/node_modules/@deepseek-ai/dsh → POSIX nvm 布局 <node dir>/../lib/node_modules/@deepseek-ai/dsh → Electron 桌面布局 <exe dir>/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh （自 v1.1.3 起；桌面主进程内 fs 对 asar 透明，已验证命中）。
- rtk 退出码语义（用 rtk 0.50.0 验证过，2026-10-03 又用 0.51.0 复验；与 --help 的说法不一致，--help 声称「exits 0」）：受支持的命令——包括已经是 rtk 形式的命令——退出码为 3，命令本身打印到 stdout；没有等价命令时退出码为 1，且无输出。Node v24 的 execFile 会把子进程退出码放在 err.code 上（数字），而 spawn 失败（ENOENT）放的是字符串，所以所有检查都走 Number(err.code)。
- RTK_DISABLED=1 只在插件的 JS 层生效（index.js 在改写前会检查它）。rtk rewrite 子命令本身不认这个变量（用 rtk 0.51.0 验证过）：手动跑 rtk rewrite 时带上 RTK_DISABLED=1，照样会改写。

安装 / 卸载

前置条件：DSH 桌面版 0.2.0-rc.2+ 自带 dsh 命令——点桌面菜单栏里的 「Manage dsh command」 就能装上；不需要单独装 Node/pnpm。

安装（版本号要写死：@latest 会被 release-age 检查回滚到更旧的版本）：

dsh plugin --profile desktop add dsh-pwsh-rtk-rewrite@1.1.3 --registry=https://registry.npmjs.org/

卸载：

dsh plugin --profile desktop remove dsh-pwsh-rtk-rewrite

也可以从 DSH 内置插件市场（dshmarket）安装。装完重启桌面应用 / 开新会话（替换已安装的代码需要重启才能加载新模块）。

内核包解析：桌面版 dsh 内核打包在安装目录的 app.asar 里（Windows 上例如 E:\Tool\DSH\resources\app.asar\dsh\），桌面配置档的依赖链和 node 目录布局都找不到它。从 v1.1.3 起，插件自带一条 Electron 桌面布局探测链，在桌面进程内会自动命中 app.asar 内核包——不用任何配置。 旧版本（≤ 1.1.1）在桌面端会因为解析失败静默回退到原生 shell（症状：插件装了但 rtk 从不触发）；当时的手动绕法是，在桌面进程环境里把 DSH_INSTALL_PACKAGE_JSON 设为 <desktop install dir>\resources\app.asar\dsh\node_modules\@deepseek-ai\dsh\package.json。升到 v1.1.3 后就不需要这个变量了。

验证：重启桌面应用后，跑一条 rtk 肯定认识的命令（比如 git status），看 rtk gain 的 Total commands 计数有没有涨——或者在工具输出里找 rtk 的紧凑格式。

生效范围：桌面应用同样是 Windows + pwsh 环境，插件照常工作；装完重启桌面应用。

禁用

- 单条命令：环境变量 RTK_DISABLED=1（rtk 自己的约定；插件在 JS 层认它）
- 整行：在配置档补丁里，把 rtk-pwsh-shell 那行覆盖为 disabled: true，再把 pwsh-sandbox 那行恢复为 disabled: false

验证

node test.js # rtkRewrite 决策逻辑自检 + 模块加载
（模块加载只在 Electron 桌面主进程内通过；裸 node 读不到 asar 内核包，所以那项检查在那里会报失败）

运行时验证（三份互相印证的证据）：

1. Harness 日志：shell 命令执行时会出现 [rtk-rewrite] "orig" -> "rewritten"（web 模式下会写进启动时重定向的日志文件，比如 dsh-web.log）
2. rtk history.db（C:\Users\<user>\AppData\Local\rtk\history.db）：每次改写成功都会记成一行 original_cmd → rtk_cmd
3. rtk gain：命令执行时 Total commands 计数会往上走

注意：探测命令要挑 rtk 肯定认识的（git status、cat 等）。
pwsh 特有的命令（Write-Output、裸 Get-ChildItem……）会让 rtk 以退出码 1 结束，找不到对应写法——悄无声息，也不留记录。没有记录 ≠ 插件没生效；这是排查时最常见的坑。

文件结构

├── index.js # RtkPwshExecutor（唯一源码：rtkRewrite + execute 拦截） ├── cordis.patch.yml # bundle 补丁：禁用 pwsh-sandbox + 插入 rtk-pwsh-shell ├── package.json # dsh.bundle.patch 指向补丁文件；无 npm 依赖 ├── test.js # 最小自检：改写决策规则 + 模块加载 ├── README.md # 英文（本文件） └── README_zh.md # 中文

许可

MIT © 2026 mengqi1436