dsh-router-ext-rtk 0.3.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CARVIN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+<h1 align="center">dsh-router-ext-rtk</h1>
+
+<p align="center">dsh-router 的 RTK 扩展插件</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-router-ext-rtk"><img src="https://img.shields.io/npm/v/dsh-router-ext-rtk?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square" alt="MIT license"></a>
+  <a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.2-rc.1+" src="https://img.shields.io/badge/DSH-0.1.2--rc.1%2B-4d6bfe" /></a>
+</p>
+
+<p align="center">
+  <a href="#快速安装">快速安装</a> ·
+  <a href="#能力">能力</a> ·
+  <a href="#与核心的分工">与核心的分工</a> ·
+  <a href="https://github.com/CARVIN94/dsh-router/blob/main/docs/ext.md">扩展开发</a>
+</p>
+
+为 [dsh-router](https://github.com/CARVIN94/dsh-router) 提供 **RTK(Rust Token Killer)**
+真实代理:把 agent 每次 bash 工具调用改写成 `rtk <cmd>`(如 `git status` →
+`rtk git status`),削减发给 LLM 的 60–90% bash 输出。
+
+单独装它没用——核心提供**面板与开关存储**,本插件提供**改写与拦截**。
+
+## 快速安装
+
+先装核心,再装本插件,然后**重启 `dsh web`**:
+
+```bash
+dsh plugin --profile web add dsh-router-core
+dsh plugin --profile web add dsh-router-ext-rtk
+```
+
+`dsh plugin add` 会在 profile 里 `pnpm add`,并自动把声明了 `dsh.bundle.patch`
+的包加入 `dsh.profile.bundles`(本插件即声明了,见 `cordis.patch.yml`)。
+
+然后在「设置 → 路由 → **扩展**」页打开 **RTK** 开关。
+
+### 前置:本机装 RTK
+
+RTK 是 [rtk-ai/rtk](https://github.com/rtk-ai/rtk)(Rust Token Killer),
+**不是** Rust Type Kit(`reachingforthejack/rtk`)。
+
+```bash
+brew install rtk
+# 或
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+```
+
+验证:
+
+```bash
+rtk --version   # 应返回 0.x
+rtk gain        # 应显示 token 节省统计(不是 command not found)
+```
+
+**未装 rtk 时开关开不了**:插件启动自检会报 `ready:false`,核心拒绝开启(API 409),
+面板内容区红字提示原因。装上后重启 `dsh web` 即可。
+
+## 能力
+
+| 能力 | 说明 |
+|---|---|
+| 真实代理 | 每条 bash 命令经 `rtk rewrite` 改写后执行,LLM 读的是压缩后的输出。 |
+| 降级安全 | rtk 缺失 / 无等价改写 / spawn 失败 → 命令原样执行,**绝不报错**。 |
+| 只拦 bash | 其他工具(含 `run_code` 体内自起的子进程)不动。 |
+| 开关自检 | 启动时探测 rtk;不可用时核心拒绝开启并给出问题描述。 |
+| 开关持久化 | 状态存核心的 `<profile>/data/ext.json`,默认关(**插件经 `router.extStore` 读写,不自己存**)。 |
+
+> 实测:`ls` 走代理后输出变成 rtk 树形格式(带文件大小与 `... (N filtered)`),
+> `rtk gain` 报 3 条命令省 280 tokens(61.9%)。
+
+## 配置
+
+| 环境变量 | 作用 |
+|---|---|
+| `DSH_RTK_BIN` | 显式指定 rtk 可执行文件路径。缺省走 `PATH`,再兜底常见安装路径(`~/.local/bin/rtk`、`/opt/homebrew/bin/rtk`、`/usr/local/bin/rtk`、`~/.cargo/bin/rtk`)。 |
+
+## 与核心的分工
+
+核心 = **管理面**,本插件 = **执行面**(2026-09 重构:拦截与裁决从核心归还插件,
+核心只在一个消费者时代挂是纯亏损)。
+
+核心负责:持有 `router.ext` 注册表(发现)、渲染面板与 `/router/api/ext`(展示)、
+把开关与插件数据落盘 `<dataDir>/ext.json`(`router.extStore` service)、按
+`getState().ready` 裁决能否开启(不可用时拒 409、面板开关禁开)。
+
+本插件负责:**自己挂 `tools/execute` 拦截 bash**、按「核心存的 `enabled` + 自己报的
+`ready`」裁决、命中则用改写后的命令短路执行;`rtk rewrite` 退出码解读与探活也在这里。
+
+本插件**无状态**:开关与数据都经 `router.extStore` 读写(`isEnabled` / `readData`),
+不自己 file IO、没有数据目录。
+
+```
+src/
+  index.ts       插件入口(host 半,注册 rtk 扩展器 + 挂拦截)
+  intercept.ts   拦截实现(挂 tools/execute、裁决、短路)—— 无状态
+  rtk.ts         RTK 扩展器实现(rewrite 退出码解读、rtk 定位/探活)—— 无状态
+  contract.ts    router.ext 契约副本(自含,与 dsh-router 契约同步)
+  *.test.ts      测试
+cordis.patch.yml  bundle patch,把插件插入 DSH cordis bundle stack
+```
+
+> ponytail: 天花板 —— 本插件自己挂监听,多扩展插件各自挂时**顺序不可控**。目前只有
+> rtk 一家,无所谓;第二家出现时要收敛(升级路径:核心暴露顺序委派的共享工具方法,
+> 而不是收回拦截)。
+>
+> **头号坑**:`tools.get('bash', exec.agent)` 的 agent scope 不能省 —— 不带只查全局
+> 视图,查不到 → 静默走原样、从不改写、不报错。已在 `intercept.ts` 文件头 + 测试锁定。
+
+完整契约见 [dsh-router 的 `docs/ext.md`](https://github.com/CARVIN94/dsh-router/blob/main/docs/ext.md)。
+
+### `rtk rewrite` 退出码
+
+RTK 权限默认 least-privilege,**几乎没有命令会落到 Allow(0)**——常见命令
+(`git status` / `ls` / `cat` …)都返回 **Ask(3)**。真实代理下用户已显式开启开关
+= 授权改写,所以退出码 3 也**采用** stdout,不弹二次确认:
+
+| 退出码 | 语义 | 行为 |
+|---|---|---|
+| 0 | Allow,有等价改写 | 采用 stdout |
+| 1 | 无等价 | 放行(原样执行) |
+| 2 | Deny 规则 | 放行(不做阻断) |
+| 3 | Ask,有等价改写但默认要人工确认 | **采用 stdout**——用户已授权 |
+| — | spawn 失败 / 超时(2s) | 放行 |
+
+## 开发
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build        # lib/index.js
+```
+
+## 致谢
+
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) —— Rust Token Killer,命令输出压缩器。
+
+## 许可证
+
+[MIT](LICENSE)
+
+## 免责声明
+
+本项目仅用于学习与技术研究,请勿用于商业用途。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-router-ext-rtk bundle patch
+#
+# Mounts dsh-router-ext-rtk into the DSH cordis bundle stack. This plugin
+# provides the `router.ext` cordis service (host half) so dsh-router can
+# delegate bash tool calls to the RTK command rewriter. dsh-router holds the
+# `router.ext` aggregate table and defers via ctx.inject, so order vs
+# dsh-router doesn't matter.
+- insert:
+    - id: dsh-router-ext-rtk
+      name: 'dsh-router-ext-rtk'

package/lib/index.js

@@ -0,0 +1,265 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/rtk.ts
+/**
+* RTK (Rust Token Killer) 扩展器 —— 只负责「改写一条命令」+「报自己是否可用」。
+*
+* 开关状态**不归本插件管**:核心持久化(`<dataDir>/ext.json`)并代存,插件经
+* `router.extStore` service 读,不自己 file IO、没有状态文件。
+*
+* 拦截/裁决/短路也不归这里 —— 见 `intercept.ts`(本插件自己挂 `tools/execute`)。
+*
+* 真实代理语义:对每条 bash 命令调 `rtk rewrite "<cmd>"`,按 rtk 的退出码协议
+* 解读。注意 rtk 的权限默认是 Ask(least-privilege),几乎没有命令会稳定落到
+* Allow(0)——常见命令(git status / ls / cat …)都走 Ask(3)。我们这里做**真实
+* 代理**:用户已经在面板**显式开启**了开关 = 明确授权改写,所以 Ask(3) 也直接
+* 采用 stdout,不弹任何二次确认。只有兜底命令按原文理解:无等价(1)放行、
+* Deny(2)原样(不阻断)、spawn 失败放行。
+*
+*   | 退出码 | 语义                                                      | 行为                 |
+*   |--------|-----------------------------------------------------------|----------------------|
+*   | 0      | Allow,有等价改写                                          | 采用 stdout          |
+*   | 1      | 无等价,原样                                               | 放行                 |
+*   | 2      | Deny 规则(Claude 原生 deny)                               | 放行(不做阻断)       |
+*   | 3      | Ask,有等价改写但默认要人工确认                             | **采用 stdout**——用户已授权,
+*   |        |                                                           | 真实代理不弹确认框    |
+*
+* 状态(只报运行时事实,不持久化):
+*   - `ready`:rtk 二进制是否可用。未装 rtk 时核心会拒绝开启(面板开关禁开、
+*     API 拒 409),并在内容区红字显示 `detail`。
+*   - `detail`:不就绪时的说明(「本机未装 rtk…」)。
+*
+* rtk 二进制定位优先顺序:
+*   1. `$DSH_RTK_BIN`(显式覆盖)
+*   2. `rtk`(PATH)
+*   3. 常见路径兜底: `~/.local/bin/rtk`、`/opt/homebrew/bin/rtk`、`/usr/local/bin/rtk`、`~/.cargo/bin/rtk`
+*/
+/** rtk rewrite 退出码(与 rtk hooks/claude 一致)。 */
+const RTK_EXIT_ALLOW = 0;
+const RTK_EXIT_NO_REWRITE = 1;
+const RTK_EXIT_DENY = 2;
+const RTK_EXIT_ASK = 3;
+/** 常见 rtk 安装路径(brew / quick-install ~/.local/bin / cargo)。 */
+const FALLBACK_RTK_PATHS = [
+	"~/.local/bin/rtk",
+	"/opt/homebrew/bin/rtk",
+	"/usr/local/bin/rtk",
+	"~/.cargo/bin/rtk"
+];
+/** 展开首个 `~/` 前缀。 */
+function expandHome(p) {
+	return p.startsWith("~/") || p.startsWith("~\\") ? join(homedir(), p.slice(2)) : p;
+}
+/**
+* 定位 rtk 可执行文件。返回 `'rtk'`(走 PATH,交给 execFileSync 解析)、绝对路径,
+* 或 `undefined`(找不到)。不缓存——`rewrite` 每次重查,避免「装了 rtk 后被缓存的
+* 失败卡死」;探活缓存见 `rtkReady`。
+*/
+function resolveRtkBin(envBin) {
+	const explicit = envBin !== void 0 && envBin !== "" ? [envBin] : [];
+	for (const raw of [
+		...explicit,
+		"rtk",
+		...FALLBACK_RTK_PATHS
+	]) {
+		if (raw === "rtk") return "rtk";
+		const p = expandHome(raw);
+		try {
+			accessSync(p, constants.X_OK);
+			return p;
+		} catch {}
+	}
+}
+/** rtk 可用性探活(缓存:成功存版本,失败存 null)。 */
+let probe = void 0;
+function resetProbe() {
+	probe = void 0;
+}
+function rtkReady() {
+	if (probe !== void 0) return probe !== null;
+	try {
+		const out = execFileSync("rtk", ["--version"], {
+			encoding: "utf8",
+			timeout: 2e3
+		}).trim();
+		probe = out === "" ? null : out;
+	} catch {
+		probe = null;
+	}
+	return probe !== null;
+}
+/**
+* 调 `rtk rewrite` 并解释退出码。缺 rtk / spawn 失败 / 无改写 → 放行,永不抛。
+*/
+function tryRewrite(command, bin) {
+	let target = bin;
+	if (target === void 0) {
+		target = resolveRtkBin(process.env.DSH_RTK_BIN);
+		if (target === "rtk") try {
+			execFileSync("rtk", ["--version"], {
+				encoding: "utf8",
+				timeout: 2e3
+			});
+		} catch {
+			return { rewritten: null };
+		}
+		else if (target === void 0) return { rewritten: null };
+	}
+	let out;
+	let code = 0;
+	try {
+		out = execFileSync(target, ["rewrite", command], {
+			encoding: "utf8",
+			timeout: 2e3
+		}).trim();
+	} catch (err) {
+		const e = err;
+		if (typeof e.status !== "number") return { rewritten: null };
+		code = e.status;
+		out = (e.stdout ?? "").toString().trim();
+		if (code === RTK_EXIT_DENY) return { rewritten: null };
+		if (code === RTK_EXIT_NO_REWRITE) return { rewritten: null };
+		if (code !== RTK_EXIT_ALLOW && code !== RTK_EXIT_ASK) return { rewritten: null };
+		if (out === "") return { rewritten: null };
+	}
+	if ((code === RTK_EXIT_ALLOW || code === RTK_EXIT_ASK) && out !== "" && out !== command) return { rewritten: out };
+	return { rewritten: null };
+}
+/**
+* 组装 ext-rtk 的扩展器实例(注册进 router.ext 表)。
+*
+* 注意:不接收 stateFile —— 开关归核心存,插件无状态(除 rtk 探活缓存)。
+* 契约里没有 `rewrite`:核心只认声明 + getState,改命令是本插件自己拦截时用的。
+*/
+function createRtkExt(envBin) {
+	rtkReady();
+	return {
+		id: "rtk",
+		name: "RTK",
+		description: "bash 命令输出压缩,削减发给 LLM 的 60–90% bash 输出(需本机装 rtk)",
+		getState: () => {
+			const ready = rtkReady();
+			return {
+				ready,
+				detail: ready ? void 0 : "本机未装 rtk:brew install rtk 或 curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh"
+			};
+		},
+		dispose: () => {
+			resetProbe();
+		}
+	};
+}
+//#endregion
+//#region src/intercept.ts
+/**
+* bash 调用拦截 —— ext-rtk **自己**挂 `tools/execute`、自己裁决、自己短路。
+*
+* 2026-09 重构:原来这层在 dsh-router 核心(`src/ext/proxy.ts`),核心代挂、代裁决、
+* 代短路。核心只在一个消费者时是纯亏损(共享表 + inject 广播 + 契约两份同步,只为
+* 留 40 行委派),所以归还插件:核心退成**管理面**(注册表面板 + 代存开关/数据)。
+*
+* 挂点语义:`tools/execute` 是 around-dispatch waterfall。我们不调 `next()` 短路整条
+* 链路。改写在 token 冻结之后、工具 body 执行之前发生:sandbox 审批 / guard 等前置
+* 已在 prepare 阶段做过,我们只在**同一授权的调用**里换命令字符串,不绕过任何审批。
+*
+* 关键不变量:
+*   - 只拦 `name === 'bash'`。其他工具(含 run_code 体内自起的子进程读取)不动。
+*   - 本插件未开启(核心 `extStore.isEnabled('rtk')`)或 rtk 未就绪 → 原样 `next()`。
+*   - 命中后直接调 bash 工具定义的 `execute(改写后参数, exec)`,返回
+*     `{ isError:false, value }`,由 registry 用名义 arguments(原始命令)re-render。
+*   - 任何一步出问题都退回 `next()`:命令永不因本扩展而失败。
+*
+* **头号坑(必须守住)**:`tools.get('bash', exec.agent)` 的第二个参数(agent scope)
+* 不能省。工具注册在 agent scope 里,只查全局视图查不到 'bash' → **静默走 next()、
+* 从不改写、不报错**。症状极具迷惑性(开关全开、命令正常、就是不生效)。
+*
+* ponytail: 天花板 —— 本插件自己挂监听,意味着多扩展插件各自挂时顺序不可控。目前
+*   只有 rtk 一家,无所谓;第二家出现时要收敛(升级路径:核心暴露顺序委派的共享工具
+*   方法,而不是收回拦截)。
+*/
+/**
+* 挂 bash 拦截。返回清理函数（cordis 的 on 监听随 fiber 卸载自动注销，返回值供显式组合）。
+*
+* @param ctx cordis context（`get('tools')` 懒查工具服务，与加载顺序解耦）
+* @param isEnabled 读核心存的开关（本插件不存开关）
+* @param isReady 本插件自报的运行时就绪
+*/
+function mountRtkIntercept(ctx, isEnabled, isReady, envBin) {
+	const toolsOf = () => {
+		const t = ctx.get("tools");
+		return t && typeof t.get === "function" ? t : void 0;
+	};
+	const listener = async (exec, next) => {
+		if (exec.name !== "bash" || exec.signal.aborted) return next();
+		const args = exec.arguments;
+		const cmd = args?.command;
+		if (typeof cmd !== "string" || cmd.trim() === "") return next();
+		if (!isEnabled()) return next();
+		if (!isReady()) return next();
+		const rewritten = tryRewrite(cmd, envBin).rewritten;
+		if (rewritten === null) return next();
+		const tools = toolsOf();
+		if (!tools) return next();
+		const bashTool = tools.get("bash", exec.agent);
+		if (!bashTool) return next();
+		try {
+			return {
+				isError: false,
+				value: await bashTool.execute({
+					...args,
+					command: rewritten
+				}, exec)
+			};
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return {
+				isError: true,
+				error: { message },
+				content: [{
+					type: "text",
+					text: `Error: ${message}`
+				}]
+			};
+		}
+	};
+	ctx.on("tools/execute", listener);
+	return () => {};
+}
+//#endregion
+//#region src/contract.ts
+/** 读取当前 router.ext 表（同一 live 对象，可追加）。 */
+function currentExts(ctx) {
+	const c = ctx;
+	return c.get?.("router.ext") ?? c.router?.ext;
+}
+/** 读取扩展存储服务——插件用它读开关、读写自己存的数据。 */
+function currentExtStore(ctx) {
+	const c = ctx;
+	return c.get?.("router.extStore") ?? c.router?.extStore;
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-router-ext-rtk";
+function apply(ctx) {
+	ctx.inject(["router.ext"], (sctx) => {
+		const exts = currentExts(sctx);
+		if (!exts) return void 0;
+		if (exts.rtk) return void 0;
+		const ext = createRtkExt();
+		exts.rtk = ext;
+		ctx.emit("internal/service", "router.ext", exts);
+		ctx.logger?.info?.("[dsh-router-ext-rtk] registered router.ext: rtk");
+		const store = currentExtStore(sctx);
+		const unmount = mountRtkIntercept(ctx, () => store?.isEnabled("rtk") === true, () => ext.getState().ready);
+		return () => {
+			unmount();
+			ext.dispose?.();
+			delete exts.rtk;
+			resetProbe();
+		};
+	});
+}
+//#endregion
+export { apply, name };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "dsh-router-ext-rtk",
+  "version": "0.3.12",
+  "description": "DSH plugin: RTK (Rust Token Killer) extension for dsh-router. Registers a command-rewrite ext via the router.ext cordis service so dsh-router ships every bash tool call through `rtk rewrite`, cutting 60-90% of LLM-bound bash output.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CARVIN94/dsh-router-ext-rtk.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf lib && tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"src/**/*.test.ts\""
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "peerDependenciesMeta": {
+    "cordis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2"
+  }
+}

package/src/contract.ts

@@ -0,0 +1,97 @@
+/**
+ * `router.ext` 通用契约副本 —— 与 dsh-router/src/ext/contract.ts 逐字同步。
+ *
+ * dsh-router-ext-rtk 是独立 npm 包,不能 import dsh-router 的 src(避免安装期
+ * 依赖拉取整个路由核心),所以复制这份契约。改动契约必须**两处同步**
+ * (dsh-router/src/ext/contract.ts + 本文件)——鸭子类型,tsc 抓不到跨仓漂移。
+ *
+ * 分工(2026-09 重构):dsh-router 核心只做**管理面**(注册表面板 + 代存开关/数据),
+ * 拦截 `tools/execute`、裁决 enabled+ready、短路执行全部归扩展插件自己。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** 扩展器唯一 id（注册键）。 */
+export type ExtId = string
+
+/**
+ * 扩展器当前状态（**运行时事实**，由插件现算，不持久化）。
+ *
+ * 注意：`enabled` 不在这里 —— 开关状态归核心持久化（`<dataDir>/ext.json`），
+ * 插件只负责做事 + 报自己是否可用。
+ */
+export interface ExtState {
+  /** 运行时是否就绪（如 RTK 二进制是否可用）；false 时即使开启也不生效。 */
+  ready: boolean
+  /** 不就绪时的一句话说明（如「本机未装 rtk」），面板红字显示。 */
+  detail?: string
+}
+
+/**
+ * 注册到 `router.ext` 表的扩展器实现。核心（面板/API）只认这几个成员。
+ * 注意**没有 `rewrite`** —— 怎么改一条命令是插件的私事，核心不感知。
+ */
+export interface RouterExt {
+  /** 扩展器 id，也是 `router.ext` 表里的注册键。 */
+  readonly id: ExtId
+  /** 面板显示名（如「RTK」）。 */
+  readonly name: string
+  /** 面板副标题说明。 */
+  readonly description?: string
+  /** 当前运行时状态（ready + 不就绪时的说明）。 */
+  getState(): ExtState
+  /** 卸载清理（表删除时由 dsh-router 调用，可选）。 */
+  dispose?(): void
+}
+
+/** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */
+export interface ExtInfo {
+  id: string
+  name: string
+  description?: string
+  /** 核心持久化的开关（默认关）。 */
+  enabled: boolean
+  /** 插件报的运行时就绪状态。 */
+  ready: boolean
+  /** 不就绪时的说明（面板红字）。 */
+  detail?: string
+}
+
+/** `router.ext` 共享聚合表：`{ [extId]: RouterExt }`（同一 live 对象可追加）。 */
+export interface RouterExtService {
+  [extId: string]: RouterExt
+}
+
+/**
+ * 扩展的存储面（核心 provide，插件 inject）。
+ *
+ * 插件**不自己 file IO**：落盘位置由核心锚定（不跟 cwd 跑），读写都经核心。
+ * 落盘形状：`<dataDir>/ext.json` = `{ "<id>": { "enabled": boolean, "data": unknown } }`
+ */
+export interface ExtStoreService {
+  /** 是否开启（未记录过 = 默认关）。 */
+  isEnabled(id: string): boolean
+  /** 置开关（面板/API 调）。 */
+  setEnabled(id: string, enabled: boolean): void
+  /** 读插件自己的数据块（没有 = undefined）。 */
+  readData<T = unknown>(id: string): T | undefined
+  /** 写插件自己的数据块（覆盖；与 enabled 同文件原子落盘）。 */
+  writeData(id: string, value: unknown): void
+}
+
+/** 读取当前 router.ext 表（同一 live 对象，可追加）。 */
+export function currentExts(ctx: Context): RouterExtService | undefined {
+  const c = ctx as unknown as {
+    get?: (key: string) => unknown
+    router?: { ext?: RouterExtService }
+  }
+  return (c.get?.('router.ext') ?? c.router?.ext) as RouterExtService | undefined
+}
+
+/** 读取扩展存储服务——插件用它读开关、读写自己存的数据。 */
+export function currentExtStore(ctx: Context): ExtStoreService | undefined {
+  const c = ctx as unknown as {
+    get?: (key: string) => unknown
+    router?: { extStore?: ExtStoreService }
+  }
+  return (c.get?.('router.extStore') ?? c.router?.extStore) as ExtStoreService | undefined
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * dsh-router-ext-rtk —— DSH 插件 host half。
+ *
+ * 通过 cordis service `router.ext`(聚合表 `{ [extId]: RouterExt }`)把 RTK 注册给
+ * dsh-router,让面板/设置页能看到它;并**自己**挂 `tools/execute` 拦截 bash 调用。
+ *
+ * 2026-09 重构后的分工:
+ *   - dsh-router 核心 = 管理面(注册表面板 + 代存开关/数据,`router.extStore`)。
+ *   - 本插件 = 执行面(自己挂 tools/execute、自己按 enabled+ready 裁决、自己短路执行)。
+ *
+ * 本插件**无状态**:开关由 dsh-router 核心持久化(`<dataDir>/ext.json`),这里经
+ * `router.extStore` 读,不自己 file IO、不存状态文件。
+ *
+ * cordis 的 `ctx.provide` 每个 service name 只允许一个插件注册,多个扩展插件不能各
+ * 自 provide `router.ext`(会抛 "service has been registered")。本插件像供应商插件
+ * 那样用共享表模式:`inject` 等待该 service(由 dsh-router 核心先 provide 空表),
+ * 把 `rtk` 追加进共享表后广播一次 `internal/service`,让 dsh-router 读到。
+ * 该模式与插件加载顺序无关。
+ *
+ * 拦截在拿到 `router.ext` 之后才挂(顺序:注册 → 拦截),所以开关/存储就绪前不会有
+ * 半开的拦截窗口。
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { createRtkExt, resetProbe } from './rtk.ts'
+import { mountRtkIntercept } from './intercept.ts'
+import { currentExts, currentExtStore, type RouterExtService } from './contract.ts'
+
+export const name = 'dsh-router-ext-rtk'
+
+export function apply(ctx: Context): void {
+  // 等 router.ext 可用后,把 rtk 追加进共享聚合表并通知 dsh-router 重扫。
+  ctx.inject(['router.ext'], (sctx) => {
+    const exts = currentExts(sctx)
+    if (!exts) return undefined
+    if (exts.rtk) return undefined // 已注册
+    const ext = createRtkExt()
+    exts.rtk = ext
+    ctx.emit('internal/service', 'router.ext', exts)
+    ctx.logger?.info?.('[dsh-router-ext-rtk] registered router.ext: rtk')
+
+    // 自挂拦截:开关问核心存储,ready 问自己;裁决与短路都在 intercept.ts。
+    // ctx 是 cordis Context,但 `on('tools/execute', ...)` 的鸭子签名鸭子类型过不去
+    // (事件名是 keyof Events,字符串传不进)——与 dsh-router 核心同款 cast。
+    const store = currentExtStore(sctx)
+    const unmount = mountRtkIntercept(
+      ctx as unknown as {
+        get: (name: string) => unknown
+        on: (name: string, listener: (...args: unknown[]) => unknown) => unknown
+      },
+      () => store?.isEnabled('rtk') === true,
+      () => ext.getState().ready,
+    )
+    return () => {
+      unmount()
+      ext.dispose?.()
+      delete exts.rtk
+      resetProbe()
+    }
+  })
+}
+
+// 类型引用确保契约副本被编译检查(避免死代码引起的不一致漂移)。
+export type { RouterExtService }

package/src/intercept.test.ts

@@ -0,0 +1,162 @@
+/**
+ * bash 拦截测试 —— node --test 直接跑。
+ *
+ * 锁定 2026-09 重构后归本插件的裁决/短路语义:
+ *   - 开关关 / rtk 不就绪 → 原样 next(),绝不改写
+ *   - 只拦 bash;非 bash、command 非字符串、已 abort → 原样
+ *   - 命中后用**改写后**的命令执行
+ *   - `tools.get('bash', exec.agent)` 必须带 agent scope —— 不带查不到,静默原样(头号坑)
+ *   - 执行抛错 → 转成 error envelope,不向外抛
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, writeFileSync, chmodSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { mountRtkIntercept, RTK_EXT_ID, type BashExec, type Envelope } from './intercept.ts'
+
+/** 造一个真能跑的假 rtk:`rtk rewrite <cmd>` → 输出 `RTK(<cmd>)`,退出码 0。 */
+function fakeRtkBin(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'ext-rtk-'))
+  const fp = join(dir, 'rtk')
+  writeFileSync(fp, '#!/bin/sh\necho "RTK($2)"\n')
+  chmodSync(fp, 0o755)
+  return fp
+}
+
+interface Ctx {
+  get: (name: string) => unknown
+  on: (name: string, fn: unknown) => unknown
+}
+
+/** 最小 cordis-like ctx:记录 tools.get 的调用,并交出监听函数供手动触发。 */
+function fakeCtx(opts: { bashTool?: { execute: (args: unknown, exec: unknown) => Promise<unknown> } } = {}) {
+  const gets: Array<{ name: string; scope: unknown }> = []
+  let listener: ((exec: BashExec, next: () => Promise<Envelope>) => Promise<Envelope>) | undefined
+  const ctx: Ctx = {
+    get: (name) => (name === 'tools' ? { get: (n: string, scope?: unknown) => {
+      gets.push({ name: n, scope })
+      return n === 'bash' && scope !== undefined ? opts.bashTool : undefined
+    } } : undefined),
+    on: (name, fn) => {
+      if (name === 'tools/execute') listener = fn as typeof listener
+      return () => {}
+    },
+  }
+  const call = (exec: BashExec): { res: Promise<Envelope>; nexted: () => boolean } => {
+    let nexted = false
+    const res = (listener as NonNullable<typeof listener>)(exec, async () => {
+      nexted = true
+      return { isError: false }
+    })
+    return { res, nexted: () => nexted }
+  }
+  return { ctx, gets, call }
+}
+
+const RTK_BIN = fakeRtkBin()
+
+/** 挂拦截,返回 ctx 与触发入口。`bin` 缺省用一个真能改写的假 rtk。 */
+function setup(o: { enabled?: boolean; ready?: boolean; bin?: string; execute?: (args: unknown, exec: unknown) => Promise<unknown> } = {}) {
+  const h = fakeCtx(o.execute === undefined ? {} : { bashTool: { execute: o.execute } })
+  const unmount = mountRtkIntercept(
+    h.ctx,
+    () => o.enabled !== false,
+    () => o.ready !== false,
+    o.bin ?? RTK_BIN,
+  )
+  return { ...h, unmount }
+}
+
+function bashExec(over: Partial<BashExec> = {}): BashExec {
+  return { name: 'bash', arguments: { command: 'git status' }, signal: new AbortController().signal, agent: 'a1', ...over }
+}
+
+test('ext id 与核心 ext.json 的键一致', () => {
+  assert.equal(RTK_EXT_ID, 'rtk')
+})
+
+test('开关关 → 原样,不查工具', async () => {
+  const h = setup({ enabled: false, ready: true })
+  const { res, nexted } = h.call(bashExec())
+  await res
+  assert.equal(nexted(), true)
+  assert.equal(h.gets.length, 0)
+})
+
+test('rtk 不就绪 → 原样,不查工具', async () => {
+  const h = setup({ enabled: true, ready: false })
+  const { res, nexted } = h.call(bashExec())
+  await res
+  assert.equal(nexted(), true)
+  assert.equal(h.gets.length, 0)
+})
+
+test('非 bash 工具 → 原样', async () => {
+  const h = setup()
+  const { res, nexted } = h.call(bashExec({ name: 'read' }))
+  await res
+  assert.equal(nexted(), true)
+  assert.equal(h.gets.length, 0)
+})
+
+test('command 非字符串 / 已 abort → 原样', async () => {
+  const h = setup()
+  const a = h.call(bashExec({ arguments: { command: 42 } }))
+  const aborted = new AbortController()
+  aborted.abort()
+  const b = h.call(bashExec({ signal: aborted.signal }))
+  await a.res
+  await b.res
+  assert.equal(a.nexted(), true)
+  assert.equal(b.nexted(), true)
+})
+
+test('命中 → 用改写后的命令执行(不是原命令)', async () => {
+  const executed: Array<{ command?: unknown }> = []
+  const h = setup({ execute: async (args) => {
+    executed.push(args as { command?: unknown })
+    return 'OK'
+  } })
+  const { res, nexted } = h.call(bashExec())
+  const out = await res
+  assert.equal(nexted(), false, '命中后不应再走 next()')
+  assert.deepEqual(executed, [{ command: 'RTK(git status)' }])
+  assert.equal(out.isError, false)
+})
+
+test('tools.get 必须带 agent scope —— 不带查不到 bash,静默原样(头号坑)', async () => {
+  let ran = 0
+  const h = setup({ execute: async () => {
+    ran += 1
+    return 'OK'
+  } })
+  // 带 agent:查的是 ('bash', exec.agent)
+  await h.call(bashExec()).res
+  assert.equal(h.gets[0]?.name, 'bash')
+  assert.equal(h.gets[0]?.scope, 'a1')
+  assert.equal(ran, 1)
+
+  // 不带 agent → tools.get 返回 undefined → 原样,一次都不执行
+  const before = ran
+  const { res, nexted } = h.call(bashExec({ agent: undefined }))
+  await res
+  assert.equal(nexted(), true)
+  assert.equal(ran, before)
+})
+
+test('无等价改写 → 原样(假 rtk 不存在)', async () => {
+  const h = setup({ bin: join(tmpdir(), 'definitely-not-rtk') })
+  const { res, nexted } = h.call(bashExec())
+  await res
+  assert.equal(nexted(), true)
+})
+
+test('执行抛错 → 转成 error envelope,不向外抛', async () => {
+  const h = setup({ execute: async () => {
+    throw new Error('boom')
+  } })
+  const out = await h.call(bashExec()).res
+  assert.equal(out.isError, true)
+  assert.match(out.error?.message ?? '', /boom/)
+})

package/src/intercept.ts

@@ -0,0 +1,115 @@
+/**
+ * bash 调用拦截 —— ext-rtk **自己**挂 `tools/execute`、自己裁决、自己短路。
+ *
+ * 2026-09 重构:原来这层在 dsh-router 核心(`src/ext/proxy.ts`),核心代挂、代裁决、
+ * 代短路。核心只在一个消费者时是纯亏损(共享表 + inject 广播 + 契约两份同步,只为
+ * 留 40 行委派),所以归还插件:核心退成**管理面**(注册表面板 + 代存开关/数据)。
+ *
+ * 挂点语义:`tools/execute` 是 around-dispatch waterfall。我们不调 `next()` 短路整条
+ * 链路。改写在 token 冻结之后、工具 body 执行之前发生:sandbox 审批 / guard 等前置
+ * 已在 prepare 阶段做过,我们只在**同一授权的调用**里换命令字符串,不绕过任何审批。
+ *
+ * 关键不变量:
+ *   - 只拦 `name === 'bash'`。其他工具(含 run_code 体内自起的子进程读取)不动。
+ *   - 本插件未开启(核心 `extStore.isEnabled('rtk')`)或 rtk 未就绪 → 原样 `next()`。
+ *   - 命中后直接调 bash 工具定义的 `execute(改写后参数, exec)`,返回
+ *     `{ isError:false, value }`,由 registry 用名义 arguments(原始命令)re-render。
+ *   - 任何一步出问题都退回 `next()`:命令永不因本扩展而失败。
+ *
+ * **头号坑(必须守住)**:`tools.get('bash', exec.agent)` 的第二个参数(agent scope)
+ * 不能省。工具注册在 agent scope 里,只查全局视图查不到 'bash' → **静默走 next()、
+ * 从不改写、不报错**。症状极具迷惑性(开关全开、命令正常、就是不生效)。
+ *
+ * ponytail: 天花板 —— 本插件自己挂监听,意味着多扩展插件各自挂时顺序不可控。目前
+ *   只有 rtk 一家,无所谓;第二家出现时要收敛(升级路径:核心暴露顺序委派的共享工具
+ *   方法,而不是收回拦截)。
+ */
+import { tryRewrite } from './rtk.ts'
+
+/** Pending-call 的最小形状（只取我们需要的字段）。 */
+export interface BashExec {
+  name: string
+  arguments: unknown
+  signal: AbortSignal
+  /** 调用方 agent —— `tools.get()` 必须带它，见文件头头号坑。 */
+  agent?: unknown
+}
+
+/** `bash` 工具参数（只作用于 command 字段）。 */
+interface BashArgs {
+  command?: unknown
+  [k: string]: unknown
+}
+
+/** around-wrapper 返回的规范化结果（registry 能消费的形状）。 */
+export interface Envelope {
+  isError: boolean
+  value?: unknown
+  error?: { message: string }
+  content?: Array<{ type: 'text'; text: string }>
+}
+
+/** ToolRuntime 的最小可见面。get 的第二个参数是 scope(agent)。 */
+interface ToolRuntimeFace {
+  get(name: string, scope?: unknown): { execute: (args: unknown, exec: unknown) => Promise<unknown> } | undefined
+}
+
+/** ext id —— 与核心 ext.json 里的键、面板注册键一致。 */
+export const RTK_EXT_ID = 'rtk'
+
+/**
+ * 挂 bash 拦截。返回清理函数（cordis 的 on 监听随 fiber 卸载自动注销，返回值供显式组合）。
+ *
+ * @param ctx cordis context（`get('tools')` 懒查工具服务，与加载顺序解耦）
+ * @param isEnabled 读核心存的开关（本插件不存开关）
+ * @param isReady 本插件自报的运行时就绪
+ */
+export function mountRtkIntercept(
+  ctx: {
+    get: (name: string) => unknown
+    on: (name: string, listener: (...args: unknown[]) => unknown) => unknown
+  },
+  isEnabled: () => boolean,
+  isReady: () => boolean,
+  envBin?: string,
+): () => void {
+  const toolsOf = (): ToolRuntimeFace | undefined => {
+    const t = ctx.get('tools')
+    return t && typeof (t as { get?: unknown }).get === 'function' ? (t as ToolRuntimeFace) : undefined
+  }
+
+  const listener = async (exec: BashExec, next: () => Promise<Envelope>): Promise<Envelope> => {
+    if (exec.name !== 'bash' || exec.signal.aborted) return next()
+    const args = exec.arguments as BashArgs
+    const cmd = args?.command
+    if (typeof cmd !== 'string' || cmd.trim() === '') return next()
+
+    // 裁决归本插件:开关(核心存的) + 就绪(自己报的),任一不满足 → 原样。
+    if (!isEnabled()) return next()
+    if (!isReady()) return next()
+
+    const rewritten = tryRewrite(cmd, envBin).rewritten
+    if (rewritten === null) return next()
+
+    const tools = toolsOf()
+    if (!tools) return next()
+    // 必须带 agent scope —— 见文件头头号坑。
+    const bashTool = tools.get('bash', exec.agent)
+    if (!bashTool) return next()
+
+    try {
+      const value = await bashTool.execute({ ...args, command: rewritten }, exec)
+      return { isError: false, value } as Envelope
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return {
+        isError: true,
+        error: { message },
+        content: [{ type: 'text', text: `Error: ${message}` }],
+      } as Envelope
+    }
+  }
+
+  ctx.on('tools/execute', listener as never)
+  return () => {}
+}

package/src/rtk.test.ts

@@ -0,0 +1,33 @@
+/**
+ * RTK 扩展器测试 —— node --test 直接跑。
+ *
+ * 覆盖:
+ *   - rtk 缺失时 tryRewrite 无害放行(不抛、返回 rewritten:null)
+ *   - getState 报运行时就绪状态(不报 enabled —— 开关归核心)
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createRtkExt, tryRewrite } from './rtk.ts'
+
+test('rtk 缺失时 tryRewrite 无害放行', () => {
+  const res = tryRewrite('git status', join(tmpdir(), 'definitely-not-rtk'))
+  assert.equal(res.rewritten, null)
+})
+
+test('getState 只报运行时事实(ready/detail),不含 enabled', () => {
+  const ext = createRtkExt()
+  const st = ext.getState()
+  assert.equal(typeof st.ready, 'boolean')
+  // 开关归核心,插件不报也不存
+  assert.equal('enabled' in st, false)
+})
+
+test('扩展器身份就绪,声明里不含 rewrite(核心不感知改写)', () => {
+  const ext = createRtkExt()
+  assert.equal(ext.id, 'rtk')
+  assert.equal(ext.name, 'RTK')
+  // 契约已剔除 rewrite:改命令是本插件私事,经 intercept.ts 自己拦截时用
+  assert.equal('rewrite' in ext, false)
+})

package/src/rtk.ts

@@ -0,0 +1,171 @@
+/**
+ * RTK (Rust Token Killer) 扩展器 —— 只负责「改写一条命令」+「报自己是否可用」。
+ *
+ * 开关状态**不归本插件管**:核心持久化(`<dataDir>/ext.json`)并代存,插件经
+ * `router.extStore` service 读,不自己 file IO、没有状态文件。
+ *
+ * 拦截/裁决/短路也不归这里 —— 见 `intercept.ts`(本插件自己挂 `tools/execute`)。
+ *
+ * 真实代理语义:对每条 bash 命令调 `rtk rewrite "<cmd>"`,按 rtk 的退出码协议
+ * 解读。注意 rtk 的权限默认是 Ask(least-privilege),几乎没有命令会稳定落到
+ * Allow(0)——常见命令(git status / ls / cat …)都走 Ask(3)。我们这里做**真实
+ * 代理**:用户已经在面板**显式开启**了开关 = 明确授权改写,所以 Ask(3) 也直接
+ * 采用 stdout,不弹任何二次确认。只有兜底命令按原文理解:无等价(1)放行、
+ * Deny(2)原样(不阻断)、spawn 失败放行。
+ *
+ *   | 退出码 | 语义                                                      | 行为                 |
+ *   |--------|-----------------------------------------------------------|----------------------|
+ *   | 0      | Allow,有等价改写                                          | 采用 stdout          |
+ *   | 1      | 无等价,原样                                               | 放行                 |
+ *   | 2      | Deny 规则(Claude 原生 deny)                               | 放行(不做阻断)       |
+ *   | 3      | Ask,有等价改写但默认要人工确认                             | **采用 stdout**——用户已授权,
+ *   |        |                                                           | 真实代理不弹确认框    |
+ *
+ * 状态(只报运行时事实,不持久化):
+ *   - `ready`:rtk 二进制是否可用。未装 rtk 时核心会拒绝开启(面板开关禁开、
+ *     API 拒 409),并在内容区红字显示 `detail`。
+ *   - `detail`:不就绪时的说明(「本机未装 rtk…」)。
+ *
+ * rtk 二进制定位优先顺序:
+ *   1. `$DSH_RTK_BIN`(显式覆盖)
+ *   2. `rtk`(PATH)
+ *   3. 常见路径兜底: `~/.local/bin/rtk`、`/opt/homebrew/bin/rtk`、`/usr/local/bin/rtk`、`~/.cargo/bin/rtk`
+ */
+import { execFileSync } from 'node:child_process'
+import { accessSync, constants } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import type { ExtState } from './contract.ts'
+
+/**
+ * 一次改写的结果:改写后的命令,或 `{ rewritten: null }` 表示原样执行。
+ *
+ * 本插件私有(不在 `router.ext` 契约里)—— 怎么改命令是插件的实现细节,核心不感知。
+ */
+export type RewriteResult = { rewritten: string } | { rewritten: null }
+
+/** rtk rewrite 退出码(与 rtk hooks/claude 一致)。 */
+const RTK_EXIT_ALLOW = 0
+const RTK_EXIT_NO_REWRITE = 1
+const RTK_EXIT_DENY = 2
+const RTK_EXIT_ASK = 3
+
+/** 常见 rtk 安装路径(brew / quick-install ~/.local/bin / cargo)。 */
+const FALLBACK_RTK_PATHS = [
+  '~/.local/bin/rtk',
+  '/opt/homebrew/bin/rtk',
+  '/usr/local/bin/rtk',
+  '~/.cargo/bin/rtk',
+]
+
+/** 展开首个 `~/` 前缀。 */
+function expandHome(p: string): string {
+  return p.startsWith('~/') || p.startsWith('~\\') ? join(homedir(), p.slice(2)) : p
+}
+
+/**
+ * 定位 rtk 可执行文件。返回 `'rtk'`(走 PATH,交给 execFileSync 解析)、绝对路径,
+ * 或 `undefined`(找不到)。不缓存——`rewrite` 每次重查,避免「装了 rtk 后被缓存的
+ * 失败卡死」;探活缓存见 `rtkReady`。
+ */
+export function resolveRtkBin(envBin?: string): string | undefined {
+  const explicit = envBin !== undefined && envBin !== '' ? [envBin] : []
+  for (const raw of [...explicit, 'rtk', ...FALLBACK_RTK_PATHS]) {
+    if (raw === 'rtk') return 'rtk' // PATH 命中交给 execFileSync(找不到时 execute 抛错,由 tryRewrite 兜)
+    const p = expandHome(raw)
+    try {
+      accessSync(p, constants.X_OK)
+      return p
+    } catch {
+      // 下一个候选
+    }
+  }
+  return undefined
+}
+
+/** rtk 可用性探活(缓存:成功存版本,失败存 null)。 */
+let probe: string | null | undefined = undefined
+
+export function resetProbe(): void {
+  probe = undefined
+}
+
+function rtkReady(): boolean {
+  if (probe !== undefined) return probe !== null
+  try {
+    const out = execFileSync('rtk', ['--version'], { encoding: 'utf8', timeout: 2000 }).trim()
+    probe = out === '' ? null : out
+  } catch {
+    probe = null
+  }
+  return probe !== null
+}
+
+/**
+ * 调 `rtk rewrite` 并解释退出码。缺 rtk / spawn 失败 / 无改写 → 放行,永不抛。
+ */
+export function tryRewrite(command: string, bin?: string): RewriteResult {
+  let target = bin
+  if (target === undefined) {
+    target = resolveRtkBin(process.env.DSH_RTK_BIN)
+    // 探活失败(rtk 不在 PATH 且不在 FALLBACK)→ 放行
+    if (target === 'rtk') {
+      try {
+        execFileSync('rtk', ['--version'], { encoding: 'utf8', timeout: 2000 })
+      } catch {
+        return { rewritten: null }
+      }
+    } else if (target === undefined) {
+      return { rewritten: null }
+    }
+  }
+  let out: string | undefined
+  let code = 0
+  try {
+    out = execFileSync(target, ['rewrite', command], { encoding: 'utf8', timeout: 2000 }).trim()
+  } catch (err) {
+    const e = err as { status?: number; stdout?: string | Buffer }
+    if (typeof e.status !== 'number') return { rewritten: null } // spawn 失败放行
+    code = e.status
+    out = (e.stdout ?? '').toString().trim()
+    if (code === RTK_EXIT_DENY) return { rewritten: null } // deny 规则:原样,不阻断
+    if (code === RTK_EXIT_NO_REWRITE) return { rewritten: null }
+    // 退出码 3(Ask):真实代理下用户已授权,采用 stdout(前提是确实现改了)。
+    if (code !== RTK_EXIT_ALLOW && code !== RTK_EXIT_ASK) return { rewritten: null }
+    if (out === '') return { rewritten: null }
+  }
+  // 退出码 0/3 + 非空输出且确实改写 → 采用;否则原样。
+  if ((code === RTK_EXIT_ALLOW || code === RTK_EXIT_ASK) && out !== '' && out !== command) {
+    return { rewritten: out }
+  }
+  return { rewritten: null }
+}
+
+/**
+ * 组装 ext-rtk 的扩展器实例(注册进 router.ext 表)。
+ *
+ * 注意:不接收 stateFile —— 开关归核心存,插件无状态(除 rtk 探活缓存)。
+ * 契约里没有 `rewrite`:核心只认声明 + getState,改命令是本插件自己拦截时用的。
+ */
+export function createRtkExt(envBin?: string) {
+  // 启动即自检:探测 rtk 是否可用(缓存到 probe),让核心初次 getState 就有 ready
+  // /detail,而不是等到第一次 rewrite 才懒查。用户后续装好 rtk,重启插件后恢复。
+  rtkReady()
+  return {
+    id: 'rtk',
+    name: 'RTK',
+    description: 'bash 命令输出压缩,削减发给 LLM 的 60–90% bash 输出(需本机装 rtk)',
+    getState: (): ExtState => {
+      const ready = rtkReady()
+      return {
+        ready,
+        detail: ready
+          ? undefined
+          : '本机未装 rtk:brew install rtk 或 curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh',
+      }
+    },
+    dispose: (): void => {
+      resetProbe()
+    },
+  }
+}