dsh-rtk

Readme

# dsh-rtk — RTK (Rust Token Killer) 原生 DSH 插件

把本机 [RTK](https://github.com/rtk-ai/rtk)（Rust Token Killer）以 DSH 原生插件
方式接入 DeepSeek Harness：模型通过 `pwsh` 工具执行的命令会被**自动改写**为
RTK 过滤版本（`git status` → `rtk git status`），压缩后的输出再返回给模型，
与 Claude Code / Codex 的 PreToolUse 钩子等价，**模型无需显式写 `rtk` 命令**。

## 原理

- 拦截点：DSH 官方 `tools/execute` around-dispatch waterfall。该瀑布允许监听器
  不调用 `next()` 而自行执行并返回结果（`tools/pre-execute` 刻意禁止改写参数，
  因此这里是受支持的钩子位）。
- 判定：`rtk rewrite <command>` 退出码 0/3 且输出非空 → 有 RTK 等价命令；
  1（passthrough）或 2（deny）→ 原样执行，交还 DSH 自身的权限流程。
- 执行：插件只调用 `rtk rewrite` 获取改写文本；随后将改写后的命令作为嵌套的
  原生 `pwsh` 分发交回 DSH。cwd、sandbox、审批、超时、取消与终端卡片渲染均由
  pwsh 工具自身负责。
- 安全边界：`run_in_background` 调用、带 `sandbox_permissions` 的调用、命中
  `excludeCommands` 前缀的命令一律原样放行；RTK 二进制缺失/崩溃时回退原始命令。

## 上游项目署名

`dsh-rtk` 是独立的 DSH 集成层，不包含、复制或再分发 RTK 的源码或二进制；它仅调用
用户本机已安装的 `rtk` CLI。RTK（Rust Token Killer）上游项目由
[rtk-ai/rtk](https://github.com/rtk-ai/rtk) 提供，并采用
[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可证。

## 安装

插件未发布到 npm。开发时可使用本地 `link:` 依赖；公开 GitHub 安装会从源码
执行本包的 `prepare` 构建脚本，因此只应安装可信、固定 commit 的版本。

```sh
# 1. 在插件目录构建
cd D:\AI\DeepSeek\plugins-split\dsh-rtk
pnpm install && pnpm build

# 2. 挂载到目标 profile（以 devtools-test 为例）
#    在 <profile>/package.json 的 dependencies 添加：
#      "dsh-rtk": "link:D:/AI/DeepSeek/plugins-split/dsh-rtk"
#    在 <profile>/package.json 的 dsh.profile.bundles 添加 "dsh-rtk"
#    在 <profile>/cordis.patch.yml 添加：
#      - id: rtk
#        name: dsh-rtk
#        config:
#          enabled: true
#          announceToAgent: true
```

挂载后**重启 `dsh web`**：模型后续的 pwsh 命令自动被 RTK 压缩。

### 从 GitHub 安装

```sh
# 使用发布后的不可变 commit；首次安装会提示 pnpm 允许执行 prepare。
dsh plugin --profile demo add github:dd2673/dsh-rtk#<commit-sha>

# 在 $DSH_HOME/profiles/demo/pnpm-workspace.yaml 中复制 pnpm 报错里打印的精确键，再重试 add。
allowBuilds:
  "dsh-rtk@https://codeload.github.com/dd2673/dsh-rtk/tar.gz/<commit-sha>": true
```

随后用 `dsh --profile demo --dump-config` 确认存在 `dsh-rtk` bundle 层，再启动或
重启该 profile。`allowBuilds` 允许安装时在本机执行本包源码，务必固定 commit 并先审查源码。

## 配置

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `enabled` | boolean | `true` | 插件总开关 |
| `announceToAgent` | boolean | `true` | 是否向 Agent 宣告插件 |
| `rtkBin` | string | `rtk` | RTK 二进制路径（可用绝对路径） |
| `askMode` | `'rewrite' \| 'passthrough'` | `rewrite` | `rtk rewrite` 退出码 3（ask）时的处理 |
| `excludeCommands` | string[] | `[]` | 前缀匹配、永不重写的命令 |
| `interceptedTools` | string[] | `['pwsh']` | 被拦截改写的工具名 |
| `defaultTimeoutMs` | number | `120000` | 模型未指定 timeoutMs 时的超时 |

## 开发

```sh
pnpm install --filter dsh-rtk...
pnpm --filter dsh-rtk test
pnpm --filter dsh-rtk build
```

## 已知限制

- 带 `sandbox_permissions` 的调用、后台调用及排除前缀的命令保持原样，不会改写。
- `tools/execute` 钩子作用于顶层工具调用；插件自身发起的嵌套 pwsh 分发不会再次
  改写，因此不会递归。`run_code` 等其他嵌套子调度不重写。
- 会话日志记录原始工具参数（hook 语义与 Claude Code 一致，输出为压缩版）。
- RTK 只覆盖其内置命令族；不支持的命令原样执行。