dsh-pwsh-rtk-rewrite

DeepSeek Harness（DSH）原生 rtk 桥接插件：把 web profile 的 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"
# 连复合命令也能逐段改写：
"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 条改写日志一一对应）。

环境要求

• DeepSeek Harness ≥ 0.1.7（dsh CLI，插件机制 dsh plugin）
• rtk ≥ 0.50.0 在 PATH 上（rtk rewrite 子命令可用；可用 RTK_BIN 环境变量指定别名）
• Windows + PowerShell（插件替换的是 pwsh 执行器；bash/其他 shell 工具不受影响）

工作原理

DSH 的插件体系（cordis）允许一个 bundle 通过 patch 声明替换服务行。 每个 context 只允许一个 ctx.shell 实现，因此 patch 做两件事：

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

加载后 shell 能力由 RtkPwshExecutor 提供，执行流程：

execute(spec)
  ├─ RTK_DISABLED=1 ? ────────────────► 原样执行
  ├─ 命令以 "rtk "/"rtk.exe " 开头 ? ──► 原样执行（递归守卫）
  ├─ rtk rewrite "<cmd>"（5s 超时）
  │    ├─ exit 3 + stdout ──► 用改写后命令 super.execute({...spec, command})
  │    ├─ exit 1            ──► rtk 无等价（pwsh cmdlet 等），静默原样执行
  │    ├─ ENOENT            ──► rtk 不在 PATH，警告一次后原样执行
  │    └─ 超时/其他失败      ──► 原样执行
  └─ super.execute(spec)   （SandboxPwshExecutor：沙箱 confine 包住改写后命令）

关键设计决策

• 失败安全：任何改写失败（rtk 缺失、无等价、超时、异常）都跑原命令， 绝不阻塞或拒绝执行。插件只做「锦上添花」，永远不影响可用性。
• 沙箱语义完整保留：只覆写 execute(spec)，resolve()（沙箱 policy stamp） 不动；用展开 { ...spec, command: rewritten } 传递，workdir/timeoutMs/signal/ stdin/env 与沙箱字段全部原样。沙箱 confine 包裹的是改写后的命令。
• spec.command 是原始命令：UTF-8 preamble 在 PwshLocalExecutor 的 spawnSpec 层才拼接，execute() 看到的命令文本可安全直接喂给 rtk rewrite。
• 内置包从 dsh 本体安装路径解析：npm 上的 @deepseek-ai/dsh-pwsh-sandbox 版本落后于本机 dsh（registry 0.1.5-rc.3 vs 本机 0.1.7-rc.2），故该核心包声明为 peerDependency（供市场做 host-aware 兼容发现），运行时按顺序自动探测：DSH_INSTALL_PACKAGE_JSON 环境变量 → 正常依赖链 → Windows 布局 <node目录>/node_modules/@deepseek-ai/dsh → POSIX nvm 布局 <node目录>/../lib/node_modules/@deepseek-ai/dsh。
• rtk exit code 语义（实测 rtk 0.50.0，与 --help 文档的 "exits 0" 不同）： 支持的命令（含已是 rtk 形式的）exit 3 + 命令在 stdout；无等价 exit 1 无输出。 Node v24 的 execFile 把子进程退出码放在 err.code（数字），spawn 失败 （ENOENT）放字符串，所以判定统一用 Number(err.code)。

安装 / 卸载

# 从 npm（推荐，市场同源）
dsh plugin --profile web add dsh-pwsh-rtk-rewrite

# 或直接从本地源码目录（开发模式）
dsh plugin --profile web add E:\Code\dsh\Rtk

# 卸载
dsh plugin --profile web remove dsh-pwsh-rtk-rewrite

也可以在 DSH 内置插件市场（dshmarket）中 一键安装。安装后重启 GUI / 新会话生效（替换已安装代码需重启以加载新模块代）。

若插件找不到 dsh 本体的核心包，设置环境变量 DSH_INSTALL_PACKAGE_JSON 指向 dsh 安装目录下的 package.json 即可（一般自动探测已覆盖：正常依赖链、 Windows 布局 <node>/node_modules、POSIX nvm 布局 <node>/../lib/node_modules）。

禁用

• 单命令：环境变量 RTK_DISABLED=1（rtk 官方约定，插件同样遵守）
• 整行停用：profile patch 中 override rtk-pwsh-shell 行 disabled: true， 并恢复 pwsh-sandbox 行 disabled: false

验证

node test.js               # rtkRewrite 判定逻辑自检 + 模块加载（全部通过 ✓）
dsh --profile web --dump-config   # 确认 pwsh-sandbox disabled、rtk-pwsh-shell 存在 ✓

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

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 报 exit 1 无等价， 静默且不入库——无记录 ≠ 插件未工作，这是排查时最容易踩的坑。

文件结构

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

License

MIT © 2026 mengqi1436