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 做两件事：
- 禁用原执行器：
- id: pwsh-sandbox / disabled: true
- 插入本插件：
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 存在 ✓
运行时验证（三重证据互相印证）：
- harness 日志：shell 命令执行时出现
[rtk-rewrite] "orig" -> "rewritten"
（web 模式下落在启动重定向的日志文件，如 dsh-web.log）
- rtk history.db（
C:\Users\<user>\AppData\Local\rtk\history.db）：每次成功
改写入库一条 original_cmd → rtk_cmd 记录
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
