DeepTrial/dsh-bash-rtk

在 DeepSeek Harness（dsh）的 bash 执行器里，把符合条件的 shell 命令路由给 rtk（Rust Token Killer）执行 —— 压缩工具输出、省 token、其余一概不变。

English version

---

目录

• 快速示例
• 环境要求
• 为什么需要它
• 工作原理
• 安装与启用
• API / 配置
• 哪些命令会被路由
• 开发
• 许可证

---

快速示例

插件在 resolve() 边界重写命令 —— 在实际执行之前：

输入 (command)	解析后的输出	原因
git status	rtk git status	简单命令 + 在白名单内
cargo build --release	rtk cargo build --release	简单命令 + 在白名单内
git status | grep x	git status | grep x	复杂 shell —— 直接透传
ls -la	ls -la	不在白名单 —— 直接透传
git status（无 rtk）	git status	二进制缺失 —— 恒等回退

其余一切 —— 工作目录、超时、环境变量、退出码、沙箱隔离 —— 均原样继承。

环境要求

• Node.js: >= 20.0.0
• rtk: rtk --version 在 PATH 上退出码为 0（需单独安装，例如 cargo install rtk）

为什么需要它

LLM agent 在冗长的工具输出上浪费大量 token（git log、cargo build、pytest 输出……）。rtk 已知道如何把这些输出压缩 30–90%。本插件把这套过滤接到 dsh 的 bash 执行器上，让每个符合条件的命令自动走 rtk —— 且对实际运行内容零语义改动。

工作原理

model → dsh bash 工具 → RtkBashExecutor.resolve()
                              │
              ┌───────────────┴────────────────┐
         符合条件？                        不符合条件
   （简单命令 + 在白名单内）          （复杂 / 未知命令）
              │                                │
      rtk <子命令> …                  命令原样执行
   （rtk 压缩输出）              （逐字节透传）

三道独立关卡决定路由（见 src/wrap.ts）：

1. 复杂度 — 任何 shell 元字符（| & ; < > \ $`）都会取消资格。包装这些会改变实际运行内容，故直接透传。
2. 白名单 — 仅 rtk 实际实现的已知开发工具才符合资格（wrap.ts 中的映射表）。
3. 可用性 — 若 PATH 上找不到 rtk 二进制，变换退化为恒等：部署行为与原始本地执行器完全一致。

版本说明

本插件不捆绑、不锁定 rtk 版本。dsh 启动时会探测 PATH 上的 rtk --version（见 src/index.ts 的 resolveRtk()）。因此：

• rtk 发布新版本时，任何在本地升级了 rtk 的用户会自动获得新行为 —— 无需更新本插件。
• 本插件版本（本仓库）与 rtk 版本相互独立，请勿混为一谈。本说明给出的是测试所基于的最低 rtk 版本，而非锁步版本号。

要求： rtk 在 PATH 上（rtk --version 退出码为 0）。插件不会安装或管理 rtk —— 你必须自行安装并更新 rtk（例如 cargo install rtk 或下载发布二进制）。当 rtk 缺失时，插件静默退化为透传。

兼容性与版本对齐

本插件以 dsh 0.2.1-alpha.1 为验证基准，同时继续支持 0.1.x 线。

dsh 会对每个插件的安装做兼容性门禁：@deepseek-ai/dsh-app-boot 读取插件的 peerDependencies，对其中每个 @deepseek-ai/dsh / @deepseek-ai/dsh-* 条目按当前运行中的 dsh 版本执行 semver.satisfies(runtime, range, { includePrerelease: true })。若某个范围的所有分支都无法纳入 0.2.1-alpha.1（例如 0.1.1 版本的 … || >=0.1.1-rc.1 <0.2.0-0），该检查即失败，插件管理器会以 is incompatible with dsh 0.2.1-alpha.1 拒绝安装（除非手动通过 dsh plugin allow-version 授予精确版本豁免）。插件市场（marketplace）对 engines.dsh 与宿主 peer 采用同样的"预发布感知"判定。

现在随包发布的范围（见 package.json 的 peerDependencies）增加了显式的 0.2.x 分支：

"@deepseek-ai/dsh-bash-local":   ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.1.1 || >=0.1.1-rc.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0"
"@deepseek-ai/dsh-bash-sandbox": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.1.1 || >=0.1.1-rc.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0"
"@deepseek-ai/dsh-shell":        ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.1.1 || >=0.1.1-rc.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0"

预发布分支规则依然成立：像 >=0.0.1-rc.1 <0.3.0 这样"看起来很宽"的范围，在 node-semver 默认规则下会静默排除所有 0.1.0-* / 0.1.1-* / 0.2.0-* 预发布（只有当某比较符与候选版本同 major.minor.patch 元组、且自身也带预发布标签时才放行）。由于 dsh 的门禁与市场都以 includePrerelease: true 求值，上面那些显式的 <0.x.0-0 上界正是让 0.2.1-alpha.1 这类运行中的预发布版本被接受的原因。

package.json 同时把宿主要求声明在发现工具读取的位置：

"engines": { "node": ">=20.0.0", "dsh": ">=0.1.0-rc.6 <0.2.0 || >=0.2.0-0 <0.3.0-0" }

（dsh.plugin.json 为旧版读取器镜像同一范围；dsh 自身读取的是 package.json。）

三个 @deepseek-ai/dsh-* peer 仍在 peerDependenciesMeta 中标记为 optional，因此它们缺失时插件仍可安装（此时退化为透传）。@deepseek-ai/cordis 不是 peer 依赖——它由 dsh 在运行时注入，这里只作为类型检查用的 dev 依赖。

0.2 移植具体改了什么。 执行接缝没变——插件仍然只覆写 resolve()，0.2 的 ShellExecSpec 只是多了一个 sandboxPolicy 字段，展开后原样透传。真正需要改的是编译期：模块说明符 cordis → @deepseek-ai/cordis（无作用域的旧别名已不存在），以及测试使用的执行器接口（run()/start() 被 execute() + result() 取代；SandboxProvider.confine() 变为 async 并返回 Promise<ConfinedArgv>；SandboxPolicyService 现在需要 ctx.sessionProjections）。

已知的版本错位： dsh（聚合包，即 npx @deepseek-ai/dsh 安装的）与其 @deepseek-ai/dsh-* 子包处于独立的 semver 轨道——聚合包可能是 0.1.1-rc.2，而发布的子包仍是 0.0.1-rc.1。上述范围锁定到已发布的子包版本，但 dsh 是用它自己的版本去校验这些范围的，因此每条受支持的发布线都需要一个显式分支。跟进匹配更新请关注 releases。

安装与启用

插件默认禁用 —— 安装后不会生效，需手动开启。

# 1) 从本地 checkout 安装
dsh plugin --profile web add "<path-to-this-dir>"

# 2) 或直接用最新 GitHub release tarball 安装（无需本地 clone）
dsh plugin --profile web add \
  "https://github.com/DeepTrial/dsh-bash-rtk/releases/latest/download/dsh-bash-rtk-latest.tgz"

# 通过可选 overlay 启用 —— 在你的 profile 的 cordis.patch.yml 中添加：
#   - id: bash-sandbox
#     disabled: true
#   - id: bash-rtk
#     disabled: false

dsh web   # 重启以生效

内置的 overlay 片段位于 cordis.patch.yml。它会用 RtkSandboxBashExecutor（保留文件隔离）替换原生的沙箱执行器，并保留非隔离的 RtkBashExecutor 供 danger-full-access 场景使用。

API / 配置

两个执行器均接受与其原生对应物（LocalBashExecutor / SandboxBashExecutor）相同的基础配置，外加一个可选字段：

选项	类型	默认值	说明
rtkAvailable	boolean	resolveRtk() 结果	强制启用或禁用 rtk 包装。适用于测试或二进制路径非标准的部署环境。

其余选项 —— cwd、timeoutMs、graceMs 等 —— 均原样继承自上游执行器。

哪些命令会被路由

符合 rtk 包装条件的命令集合由 rtk 本身定义 —— 权威且持续维护的列表见 rtk 命令参考 / README.md。本插件镜像该列表；当 rtk 新增子命令时，升级 rtk（而非本插件）即可生效。

复杂命令 —— 管道、&&/;、重定向、$( )、环境变量赋值 —— 无论白名单如何，始终以原生方式运行。

开发

# 1. 克隆插件
git clone https://github.com/DeepTrial/dsh-bash-rtk.git

# 2. 安装插件构建所依赖的已发布 harness 包
cd dsh-bash-rtk && pnpm install --ignore-scripts

# 3. 运行检查
pnpm run check        # 类型检查 + 测试 + 构建
pnpm run test         # 仅测试
pnpm run typecheck    # 仅 tsc

devDependencies 固定到插件构建与测试所依赖的已发布 @deepseek-ai/dsh-* / @deepseek-ai/cordis 版本（当前为 0.2.1-alpha.1 线），不再需要同级的 deepseek-harness 源码仓。

许可证

MIT