@wingsbutterfly/dsh-rtk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.1.0
+
+Initial release — a port of `pi-rtk-optimizer` to the DeepSeek Harness plugin
+model.
+
+### Command rewriting
+
+- Rewrites `bash`/`pwsh` commands to their rtk equivalents by delegating to
+  `rtk rewrite`; rtk remains the only source of rewrite rules.
+- Honors rtk's exit-code contract: `0`/`3` carry a rewrite on stdout, `1` means
+  no equivalent, `2` means rtk refused and stderr explains why.
+- `rewrite` and `suggest` modes, plus a runtime guard that runs the original
+  command whenever rtk cannot be proven available.
+- Scopes an isolated `RTK_DB_PATH` onto rewritten commands so rtk's usage
+  history does not reach the working tree.
+- Restores the original arguments as soon as dispatch returns, so the session
+  log and later pipeline stages keep seeing the call the model made.
+
+### Output compaction
+
+- Multi-stage pipeline over `bash`, `read`, and `grep` results: ANSI stripping,
+  build filtering, test aggregation, git compaction, linter aggregation, search
+  grouping, source filtering, smart truncation, and hard truncation.
+- Preserves the harness result contract: `[exit code: N]`, `[stderr]`,
+  `[timed out after …]`, `[sandbox: …]`, and truncation markers are lifted out
+  before the body is rewritten and restored verbatim afterwards.
+- Never inflates a result — a technique that would not shrink the text is
+  discarded and reported as no change.
+- Lossy `read` compaction and source filtering are off by default, and every
+  numeric bound is clamped on load.
+
+### Configuration and commands
+
+- Full configuration surface mirroring `pi-rtk-optimizer`'s documented
+  defaults, registered as the `dsh-rtk` settings namespace with the
+  composition's `config:` block as its base layer.
+- `/rtk`, `/rtk show`, `/rtk path`, `/rtk verify`, `/rtk stats`,
+  `/rtk clear-stats`, `/rtk reset`, and `/rtk help`.
+- Session savings metrics by tool and by technique.
+
+### Notes on the port
+
+- Streamed bash output is not sanitized: the harness has no equivalent of Pi's
+  `tool_execution_*` hooks.
+- The Windows-specific shell fixups and the hashline/anchor-safe read handling
+  are not ported; the target deployment is POSIX with the harness's own `read`
+  format.
+- A host-plane row and a preset row both want the same process-global settings
+  namespace. The second instance to mount now follows the first through the
+  settings event instead of failing the mount.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wings1848
+
+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,214 @@
+# dsh-rtk
+
+[![CI](https://github.com/wings1848/dsh-rtk/actions/workflows/ci.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/wings1848/dsh-rtk/actions/workflows/codeql.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/codeql.yml)
+[![Secrets](https://github.com/wings1848/dsh-rtk/actions/workflows/secrets.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/secrets.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/wings1848/dsh-rtk/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.18.0-brightgreen.svg)](https://nodejs.org)
+[![中文文档](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-blue)](https://github.com/wings1848/dsh-rtk/blob/main/README.zh.md)
+
+RTK command rewriting and tool-output compaction for the [DeepSeek Harness](https://github.com/deepseek-ai/dsh).
+
+`dsh-rtk` rewrites `bash` commands to their [rtk](https://github.com/rtk-ai/rtk) equivalents before they run, and compacts noisy tool output before it reaches the model. It is a port of [`pi-rtk-optimizer`](https://github.com/MasuRii/pi-rtk-optimizer) to the harness's plugin model.
+
+```
+model asks:  git status
+runs:        rtk git status
+model sees:  Branch: main
+             Modified: 2 files
+               src/a.ts
+```
+
+![How dsh-rtk works](https://raw.githubusercontent.com/wings1848/dsh-rtk/main/docs/assets/how-it-works.svg)
+
+## Features
+
+### Command rewriting
+
+- Every command with an rtk equivalent is rewritten before dispatch; commands rtk does not support run untouched.
+- **rtk stays the source of truth.** The plugin carries no rewrite table of its own — it asks the installed binary via `rtk rewrite`, so support tracks whatever rtk version is installed.
+- **`rewrite` and `suggest` modes.** `rewrite` replaces the command; `suggest` runs it unchanged and reports the equivalent it would have used.
+- **Runtime guard.** With `guardWhenRtkMissing` on (the default), a call that cannot prove rtk is available runs the original command. A missing optimizer never blocks work.
+- Rewritten commands get an isolated `RTK_DB_PATH`, so rtk's usage history does not land in the working tree.
+
+### Output compaction
+
+A multi-stage pipeline over `bash`, `read`, and `grep` results:
+
+| Stage | What it does |
+|---|---|
+| ANSI stripping | Removes terminal color and formatting sequences |
+| Build filtering | Extracts compiler errors and warnings, drops progress chatter |
+| Test aggregation | Collapses runner output to pass/fail/skip plus failure excerpts |
+| Git compaction | Summarizes `git status`, `git diff`, and `git log` |
+| Linter aggregation | Counts issues and ranks them by rule and file |
+| Search grouping | Groups `grep`-style matches by file |
+| Source filtering | `none`, `minimal`, or `aggressive` comment/whitespace removal (off by default) |
+| Smart truncation | Keeps signatures and imports when dropping lines (off by default) |
+| Hard truncation | Final character budget |
+
+Two properties are load-bearing:
+
+- **The harness contract survives.** A `bash` result ends with status markers — `[exit code: N]`, `[stderr]`, `[timed out after …]`, `[sandbox: …]`. Compaction lifts those out before rewriting the body and puts them back afterwards; the model is told to check `[exit code: N]` on every call, and the Web UI parses that same line for its exit-status pill.
+- **Compaction never inflates a result.** If a technique would not actually shrink the text, the original is kept and nothing is reported.
+
+### Oversized output belongs to the harness
+
+When `dsh-spill-policy` is mounted, it writes a full result to disk and keeps a head/tail preview inline — that truncation is **recoverable**. This plugin's own hard truncation is not, and it runs first: at its 12 000-character default it fires far below spill's 50 000-byte threshold, so spill never sees a large result at all and the file that would have let a reader see the rest is never written.
+
+With `deferToHarnessSpill` on (the default) the plugin turns its own truncation off whenever the spill service is present, so a runaway command's output stays readable. Set it to `false` to keep the plugin's bound regardless.
+
+
+### Session metrics
+
+`/rtk stats` reports how many characters compaction saved, per tool and per technique.
+
+## Install
+
+### 1. Install the package
+
+```bash
+dsh plugin --profile web add @wingsbutterfly/dsh-rtk
+```
+
+Working from a checkout instead? Link it where the composition resolves bare
+specifiers:
+
+```bash
+mkdir -p ~/.dsh/node_modules/@wingsbutterfly
+ln -s /path/to/dsh-rtk ~/.dsh/node_modules/@wingsbutterfly/dsh-rtk
+```
+
+### 2. Add one row to an agent preset
+
+`dsh-rtk` is an **agent-plane** row: it registers listeners into the tool pipeline and contributes no service, so it needs no `isolate` realm. Add it to the preset whose sessions should be optimized:
+
+```yaml
+- id: rtk
+  name: '@wingsbutterfly/dsh-rtk'
+  config:
+    enabled: true
+    mode: rewrite
+```
+
+To try it without touching an existing preset, copy one and add the row:
+
+```
+# ask a cordis-preset agent to run this
+agentPresets.copy('standard', 'rtk', 'RTK 优化')
+```
+
+The row works at the host plane too (add it to `~/.dsh/cordis.patch.yml` instead), which covers every session in the deployment — but that needs a host restart, and a host row plus a preset row would both want the same process-global settings namespace. Pick one plane.
+
+## Configuration
+
+Every field is optional; defaults are shown.
+
+```yaml
+- id: rtk
+  name: '@wingsbutterfly/dsh-rtk'
+  config:
+    enabled: true                    # master switch
+    mode: rewrite                    # rewrite | suggest
+    guardWhenRtkMissing: true        # run the original when rtk is unavailable
+    showRewriteNotifications: false  # append a one-line rewrite note to the result
+    rtkExecutable: rtk               # name or absolute path
+    rewriteTimeoutMs: 3000           # deadline for one `rtk rewrite` call
+    compactedTools: [bash, read, grep]
+    outputCompaction:
+      enabled: true
+      stripAnsi: true
+      readCompaction:
+        enabled: false               # lossy read compaction; off so code reads stay exact
+      sourceCodeFilteringEnabled: false
+      preserveExactSkillReads: false
+      sourceCodeFiltering: none      # none | minimal | aggressive
+      aggregateTestOutput: true
+      filterBuildOutput: true
+      compactGitOutput: true
+      aggregateLinterOutput: true
+      groupSearchOutput: true
+      trackSavings: true
+      deferToHarnessSpill: true      # let the harness spill policy own oversized output
+      smartTruncate:
+        enabled: false
+        maxLines: 220                # 40–4000
+      truncate:
+        enabled: true
+        maxChars: 12000              # 1000–200000
+```
+
+The configuration is also registered as the `dsh-rtk` namespace in the harness settings document, so it can be edited there and takes effect without a restart. A composition `config:` block supplies the `base` layer; the settings document supplies the user layer on top.
+
+> **Why `readCompaction` is off by default.** Filtering or truncating a `read` result can leave the model editing against text that no longer matches the file. Everything on by default is lossless for the body text it summarizes, or only fires on outputs whose whole shape is being replaced.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/rtk` | Show configuration and runtime status |
+| `/rtk show` | Same as `/rtk` |
+| `/rtk path` | Where the configuration is stored |
+| `/rtk verify` | Check whether the rtk executable is usable |
+| `/rtk stats` | Compaction savings for this session |
+| `/rtk clear-stats` | Reset the savings counters |
+| `/rtk reset` | Restore configuration defaults |
+| `/rtk help` | Usage text |
+
+## How it works
+
+Both halves ride the tool pipeline rather than wrapping a tool, because the harness offers exactly two seams that fit:
+
+- **Rewriting rides `tools/execute`.** `tools/pre-execute` deliberately may not mutate arguments — they are logged and presented before dispatch, so a rewrite there would desync the recorded call from the one that ran. The around-dispatch stage is the only place the executing command may differ, and `dsh-rtk` scopes the change to a single call: the original arguments are restored as soon as dispatch returns, so later pipeline stages and the session log still see what the model asked for.
+
+- **Compaction rides `tools/post-execute`**, the stage that may replace result content.
+
+Both listeners register in the scope the row was mounted into. A preset row therefore covers exactly its own agent (the preset's standing scope is an ancestor of every session that joins it), and a host row covers every agent in the process.
+
+Only the `tools` service is a hard dependency. `settings`, `commands`, and `systemPrompt` are resolved with `ctx.get`, so a composition that omits any of them still gets the optimization.
+
+### Caveat: the rewriting seam is not a sanctioned extension point
+
+The harness documents `tools/execute` wrappers as wrappers that "may change only `exec.signal`". Replacing `arguments` is **not a supported extension point** — it works because the execution object is not frozen until its result is notified, and the failed alternative is worse: `tools/pre-execute` deliberately may not rewrite input (arguments are logged and presented before dispatch), and a tool cannot be re-registered over one in the same layer.
+
+`dsh-rtk` takes that seam knowingly, and pays for it where it can: the replacement is scoped to a single call and restored in `finally`, and every failure path falls back to the command the model sent. If a future harness version freezes the execution object earlier, rewriting goes quiet rather than breaking — commands run unrewritten and compaction is unaffected, because `tools/post-execute` *is* a documented content-replacement stage.
+
+## Differences from pi-rtk-optimizer
+
+| pi-rtk-optimizer | dsh-rtk |
+|---|---|
+| Rewrites `event.input.command` in the `tool_call` hook | Replaces `exec.arguments` for the duration of one dispatch, then restores it |
+| Compacts in the `tool_result` hook | Compacts in the `tools/post-execute` waterfall |
+| `/rtk` opens a TUI settings modal | `/rtk` prints status text; configuration lives in the harness settings document |
+| Config is a JSON file it owns | Config is a harness settings namespace layered over the composition's `config:` block |
+| Streams are sanitized through `tool_execution_*` hooks | No equivalent hook exists, so streamed output is not sanitized |
+| Windows-specific shell fixups | Not ported; the target deployment is POSIX |
+
+Everything else — the rewrite delegation to `rtk rewrite`, the exit-code contract, the guard when rtk is missing, the documented default for every compaction switch, and each technique's algorithm — is ported as-is.
+
+## Development
+
+```bash
+pnpm install          # or link the peer packages manually
+pnpm run typecheck    # tsc --noEmit against the real harness types
+pnpm test             # builds first, then runs node --test test/
+pnpm run build        # emit lib/
+pnpm run check        # typecheck + test
+```
+
+The tests import `lib/`, so `pnpm test` builds before it runs; a `src/` edit that is never built would otherwise pass the suite unnoticed.
+
+The port's acceptance evidence, including the eight defects later reviews and live testing surfaced, is in [https://github.com/wings1848/dsh-rtk/blob/main/docs/verification.md](https://github.com/wings1848/dsh-rtk/blob/main/docs/verification.md).
+
+`test/integration.test.ts` drives the real `apply()` through a stand-in context and calls the real `rtk` binary, so it fails on a machine without rtk installed — that is intentional: the rewrite path is the feature.
+
+## Star history
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/wings1848/dsh-rtk/output/star-history-dark.svg">
+  <img alt="Star history chart" src="https://raw.githubusercontent.com/wings1848/dsh-rtk/output/star-history-light.svg">
+</picture>
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,211 @@
+# dsh-rtk
+
+[![CI](https://github.com/wings1848/dsh-rtk/actions/workflows/ci.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/wings1848/dsh-rtk/actions/workflows/codeql.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/codeql.yml)
+[![Secrets](https://github.com/wings1848/dsh-rtk/actions/workflows/secrets.yml/badge.svg)](https://github.com/wings1848/dsh-rtk/actions/workflows/secrets.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/wings1848/dsh-rtk/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.18.0-brightgreen.svg)](https://nodejs.org)
+[![English](https://img.shields.io/badge/README-English-blue)](https://github.com/wings1848/dsh-rtk/blob/main/README.md)
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 用的 RTK 命令重写 + 工具输出压缩插件。
+
+`dsh-rtk` 会在 `bash` 命令执行前把它改写成等价的 [rtk](https://github.com/rtk-ai/rtk) 命令，并在工具输出进入模型上下文前压缩它。它是 [`pi-rtk-optimizer`](https://github.com/MasuRii/pi-rtk-optimizer) 在 harness 插件模型上的移植。
+
+```
+模型发出：  git status
+实际执行：  rtk git status
+模型看到：  Branch: main
+            Modified: 2 files
+              src/a.ts
+```
+
+![How dsh-rtk works](https://raw.githubusercontent.com/wings1848/dsh-rtk/main/docs/assets/how-it-works.svg)
+
+## 功能
+
+### 命令重写
+
+- 有 rtk 等价命令的调用会在派发前被改写；rtk 不支持的命令原样执行。
+- **rtk 始终是唯一事实来源。** 插件不带自己的重写表，而是通过 `rtk rewrite` 询问已安装的二进制，所以支持范围跟随你装的 rtk 版本。
+- **`rewrite` 与 `suggest` 两种模式。** `rewrite` 替换命令；`suggest` 原样执行并报告本可使用的等价命令。
+- **运行时守卫。** `guardWhenRtkMissing`（默认开）下，无法确认 rtk 可用的调用会执行原命令——缺少优化器永远不会挡住工作。
+- 被改写的命令会带上隔离的 `RTK_DB_PATH`，rtk 的使用历史不会落进工作目录。
+
+### 输出压缩
+
+针对 `bash`、`read`、`grep` 结果的多阶段管线：
+
+| 阶段 | 作用 |
+|---|---|
+| ANSI 剥离 | 去掉终端颜色与格式转义序列 |
+| 构建过滤 | 提取编译错误与警告，丢弃进度噪音 |
+| 测试聚合 | 折叠为 通过/失败/跳过 计数加失败摘录 |
+| Git 压缩 | 归纳 `git status`、`git diff`、`git log` |
+| Linter 聚合 | 统计问题数并按规则与文件排名 |
+| 搜索分组 | 按文件归组 `grep` 风格匹配 |
+| 源码过滤 | `none` / `minimal` / `aggressive` 注释与空白处理（默认关） |
+| 智能截断 | 丢行时保留签名与 import（默认关） |
+| 硬截断 | 最终字符预算 |
+
+有两条性质是**硬性不变量**：
+
+- **harness 的结果契约必须存活。** `bash` 结果以状态标记结尾——`[exit code: N]`、`[stderr]`、`[timed out after …]`、`[sandbox: …]`。压缩会先把这些标记摘出来，重写正文后再原样接回；模型被要求在每次调用后检查 `[exit code: N]`，Web UI 也解析同一行来画退出状态。
+
+- **压缩绝不把结果变大。** 如果某个技术不能真正缩短文本，就保留原文并且不上报。
+
+### 超大输出归 harness 管
+
+`dsh-spill-policy` 挂载时，它会把完整结果落盘、上下文里只留头尾预览——这种截断是**可恢复的**。而本插件的硬截断不可恢复，且**跑在前面**：默认 12000 字符的阈值远低于 spill 的 50000 字节阈值，于是 spill 根本看不到大结果，那个本可以让读者看到剩余内容的落盘文件也就永远不会产生。
+
+`deferToHarnessSpill` 开启时（默认），只要 spill 服务在场，插件就关掉自己的截断，让失控命令的输出保持可读。设为 `false` 则无论 spill 是否挂载都保留插件自己的上限。
+
+
+### 会话统计
+
+`/rtk stats` 报告本次会话省下多少字符，按工具与按技术两个维度。
+
+## 安装
+
+### 1. 安装包
+
+```bash
+dsh plugin --profile web add @wingsbutterfly/dsh-rtk
+```
+
+想从本地检出直接用？软链到组合能解析裸模块名的位置：
+
+```bash
+mkdir -p ~/.dsh/node_modules/@wingsbutterfly
+ln -s /path/to/dsh-rtk ~/.dsh/node_modules/@wingsbutterfly/dsh-rtk
+```
+
+### 2. 给一个 agent preset 加一行
+
+`dsh-rtk` 是 **agent 平面**的行：它只往工具管线里注册监听器、不发布任何服务，所以不需要 `isolate` realm。把它加到你希望被优化的 preset：
+
+```yaml
+- id: rtk
+  name: '@wingsbutterfly/dsh-rtk'
+  config:
+    enabled: true
+    mode: rewrite
+```
+
+不想动现有 preset，就复制一个再加行：
+
+```
+# 让 cordis preset 的 agent 执行
+agentPresets.copy('standard', 'rtk', 'RTK 优化')
+```
+
+这一行挂在 **host 平面**同样有效（写进 `~/.dsh/cordis.patch.yml`），会覆盖该部署下的所有会话——但需要重启宿主，而且 host 行与 preset 行会同时想要同一个进程级 settings 命名空间。**两个平面只选一个。**
+
+## 配置
+
+所有字段可选，下列为默认值。
+
+```yaml
+- id: rtk
+  name: '@wingsbutterfly/dsh-rtk'
+  config:
+    enabled: true                    # 总开关
+    mode: rewrite                    # rewrite | suggest
+    guardWhenRtkMissing: true        # rtk 不可用时执行原命令
+    showRewriteNotifications: false  # 在结果末尾附加一行改写说明
+    rtkExecutable: rtk               # 名字或绝对路径
+    rewriteTimeoutMs: 3000           # 单次 `rtk rewrite` 的截止时间
+    compactedTools: [bash, read, grep]
+    outputCompaction:
+      enabled: true
+      stripAnsi: true
+      readCompaction:
+        enabled: false               # 有损 read 压缩；默认关，保证读到的代码是精确的
+      sourceCodeFilteringEnabled: false
+      preserveExactSkillReads: false
+      sourceCodeFiltering: none      # none | minimal | aggressive
+      aggregateTestOutput: true
+      filterBuildOutput: true
+      compactGitOutput: true
+      aggregateLinterOutput: true
+      groupSearchOutput: true
+      trackSavings: true
+      deferToHarnessSpill: true      # 把超大输出让给 harness 的 spill 策略
+      smartTruncate:
+        enabled: false
+        maxLines: 220                # 40–4000
+      truncate:
+        enabled: true
+        maxChars: 12000              # 1000–200000
+```
+
+配置同时注册为 harness 设置文档里的 `dsh-rtk` 命名空间，可以在那里编辑并即时生效、无需重启。组合里的 `config:` 块提供 `base` 层，设置文档在其上叠加用户层。
+
+> **为什么 `readCompaction` 默认关。** 过滤或截断 `read` 结果，可能让模型拿到的文本与文件不再一致，编辑就会失配。默认开启的每一项，要么对它归纳的正文是无损的，要么只作用于整个形态都会被替换掉的输出。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `/rtk` | 显示配置与运行时状态 |
+| `/rtk show` | 同 `/rtk` |
+| `/rtk path` | 配置存放位置 |
+| `/rtk verify` | 检查 rtk 可执行文件是否可用 |
+| `/rtk stats` | 本次会话的压缩收益 |
+| `/rtk clear-stats` | 重置收益计数 |
+| `/rtk reset` | 恢复配置默认值 |
+| `/rtk help` | 用法说明 |
+
+## 工作原理
+
+两部分都挂在工具管线上，而不是包装某个工具，因为 harness 恰好提供两个合适的接缝：
+
+- **重写走 `tools/execute`。** `tools/pre-execute` 被刻意设计为不能修改参数——参数在派发前就已记入日志并呈现，在那里改写会让记录下来的调用与实际执行的不一致。around-dispatch 阶段是唯一能让「执行的命令」与「记录的命令」不同的地方，而 `dsh-rtk` 把改动限制在单次调用内：派发一返回就恢复原始参数，后续管线阶段与会话日志看到的仍是模型发出的调用。
+
+- **压缩走 `tools/post-execute`**，这是允许替换结果内容的阶段。
+
+两个监听器都注册在该行被挂载的 scope 里。因此 preset 行恰好覆盖它自己的 agent（preset 的 standing scope 是每个加入它的会话的祖先），而 host 行覆盖进程内所有 agent。
+
+硬依赖只有 `tools` 服务。`settings`、`commands`、`systemPrompt` 都用 `ctx.get` 解析，缺少其中任何一个的组合仍然能获得优化。
+
+### 注意：改写所用的接缝不是官方扩展点
+
+harness 对 `tools/execute` wrapper 的文档原话是「may change only `exec.signal`」。替换 `arguments` **不是受支持的扩展点**——它能生效，只是因为执行对象要等到结果被通知时才被冻结。而失败的替代方案更糟：`tools/pre-execute` 被刻意设计为不能重写输入（参数在派发前就已记入日志并呈现），同一 layer 内也无法用新工具覆盖已有工具。
+
+`dsh-rtk` 是**知情地**用了这条接缝，并在力所能及处做了对冲：替换只作用于单次调用、在 `finally` 里恢复，任何失败路径都退回模型发出的原命令。若未来的 harness 提前冻结执行对象，改写会**静默失效**而不是报错——命令按原样执行，压缩不受影响，因为 `tools/post-execute` 是**有文档记载的内容替换阶段**。
+
+## 与 pi-rtk-optimizer 的差异
+
+| pi-rtk-optimizer | dsh-rtk |
+|---|---|
+| 在 `tool_call` 钩子里改 `event.input.command` | 在一次派发期间替换 `exec.arguments`，随后恢复 |
+| 在 `tool_result` 钩子里压缩 | 在 `tools/post-execute` waterfall 里压缩 |
+| `/rtk` 打开 TUI 设置面板 | `/rtk` 输出文本状态；配置存在 harness 设置文档里 |
+| 配置是它自己管的 JSON 文件 | 配置是 harness 设置命名空间，叠加在组合的 `config:` 块之上 |
+| 通过 `tool_execution_*` 钩子清洗流式输出 | harness 没有对应钩子，故不清洗流式输出 |
+| Windows 专用 shell 修正 | 未移植；目标部署是 POSIX |
+
+其余部分——把重写委托给 `rtk rewrite`、退出码契约、rtk 缺失时的守卫、每个压缩开关的默认值、以及各项技术的算法——都是原样移植。
+
+## 开发
+
+```bash
+pnpm run typecheck    # 用真实 harness 类型跑 tsc --noEmit
+pnpm test             # 先构建，再跑 node --test test/
+pnpm run build        # 产出 lib/
+pnpm run check        # typecheck + test
+```
+
+测试 import 的是 `lib/`，所以 `pnpm test` 会先构建；否则只改 `src/` 而没构建的回归会静默通过。
+
+`test/integration.test.ts` 用替身上下文驱动真实的 `apply()`，并调用真实的 `rtk` 二进制，所以在没装 rtk 的机器上会失败——这是有意的：重写路径就是这个功能本身。
+
+## Star history
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/wings1848/dsh-rtk/output/star-history-dark.svg">
+  <img alt="Star history chart" src="https://raw.githubusercontent.com/wings1848/dsh-rtk/output/star-history-light.svg">
+</picture>
+
+## 许可证
+
+MIT

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,51 @@
+# Third-party notices
+
+`dsh-rtk` is MIT licensed (see [LICENSE](LICENSE)). It is a derivative of an
+MIT-licensed project, whose notice is reproduced below as that license requires.
+
+---
+
+## pi-rtk-optimizer
+
+Copyright (c) 2026 MasuRii
+
+Licensed under the MIT License.
+
+Derived from <https://github.com/MasuRii/pi-rtk-optimizer>, version 0.9.0.
+
+What came from it: the decision to delegate rewriting to `rtk rewrite` instead of
+maintaining a rule table; rtk's exit-code contract (`0`/`3` carry a rewrite on
+stdout, `1` means no equivalent, `2` means rtk refused); the runtime guard that
+runs the original command when rtk is unavailable; the output-compaction pipeline
+and each of its techniques (ANSI stripping, build filtering, test aggregation, git
+compaction, linter aggregation, search grouping, source filtering, and both
+truncation stages); the documented default of every configuration field; and the
+`/rtk` command surface.
+
+What did not: the seam it hooks (Pi's `tool_call`/`tool_result` events rather than
+this harness's `tools/execute` and `tools/post-execute`), the TUI settings modal,
+streamed-output sanitization, and the Windows-specific shell fixups. Each is
+recorded under "Differences from pi-rtk-optimizer" in [README.md](README.md), and
+[docs/verification.md](docs/verification.md) holds this port's acceptance evidence.
+
+---
+
+## MIT License, as it applies to the project above
+
+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/docs/assets/how-it-works.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 840 500" width="840" height="500" role="img" aria-label="dsh-rtk rewrites bash commands to rtk and compacts the result before the model sees it">
+  <title>How dsh-rtk works</title>
+  <desc>A command flows from the model through a rewrite stage to rtk, then through a compaction stage back to the model. Measured on git status: 1050 characters become 215, an 80% reduction.</desc>
+
+  <!-- Opaque background: GitHub and npm render on both light and dark themes, so
+       a transparent plate designed for one of them smears on the other. -->
+  <rect width="840" height="500" fill="#f8fafc"/>
+  <rect x="0.5" y="0.5" width="839" height="499" fill="none" stroke="#e2e8f0"/>
+
+  <text x="32" y="52" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="25" font-weight="700" fill="#0f172a">dsh-rtk</text>
+  <text x="32" y="78" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" font-size="14" fill="#64748b">rewrites bash commands to rtk, then compacts what comes back</text>
+
+  <!-- Stage 1: what the model asked for -->
+  <rect x="32" y="104" width="776" height="72" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+  <text x="52" y="132" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="600" fill="#94a3b8" letter-spacing="0.6">THE MODEL ASKS FOR</text>
+  <text x="52" y="160" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="17" fill="#0f172a">git status</text>
+
+  <!-- connector -->
+  <line x1="120" y1="176" x2="120" y2="212" stroke="#0ea5e9" stroke-width="2"/>
+  <path d="M120 220 L115 210 L125 210 Z" fill="#0ea5e9"/>
+  <text x="140" y="203" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="#0284c7">tools/execute</text>
+  <text x="258" y="203" font-family="system-ui, -apple-system, sans-serif" font-size="13" fill="#64748b">— argument replaced for this call only</text>
+
+  <!-- Stage 2: what actually runs -->
+  <rect x="32" y="228" width="776" height="72" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+  <text x="52" y="256" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="600" fill="#94a3b8" letter-spacing="0.6">WHAT ACTUALLY RUNS</text>
+  <text x="52" y="284" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="17" fill="#0f172a">rtk git status</text>
+  <text x="330" y="284" font-family="system-ui, -apple-system, sans-serif" font-size="12.5" fill="#94a3b8">rtk stays the source of truth — it decides what it supports</text>
+
+  <!-- connector -->
+  <line x1="120" y1="300" x2="120" y2="336" stroke="#10b981" stroke-width="2"/>
+  <path d="M120 344 L115 334 L125 334 Z" fill="#10b981"/>
+  <text x="140" y="327" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="600" fill="#059669">tools/post-execute</text>
+  <text x="290" y="327" font-family="system-ui, -apple-system, sans-serif" font-size="13" fill="#64748b">— body summarized, status markers kept</text>
+
+  <!-- Stage 3: what the model sees -->
+  <rect x="32" y="352" width="776" height="116" rx="10" fill="#ffffff" stroke="#cbd5e1"/>
+  <text x="52" y="380" font-family="system-ui, -apple-system, sans-serif" font-size="12" font-weight="600" fill="#94a3b8" letter-spacing="0.6">THE MODEL SEES</text>
+  <text x="52" y="412" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="15" fill="#0f172a">Branch: main</text>
+  <text x="52" y="434" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="15" fill="#0f172a">Modified: 2 files</text>
+  <text x="52" y="456" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="15" fill="#0f172a">[exit code: 0]</text>
+
+  <!-- measured outcome -->
+  <rect x="470" y="394" width="318" height="56" rx="8" fill="#ecfdf5" stroke="#a7f3d0"/>
+  <text x="490" y="418" font-family="system-ui, -apple-system, sans-serif" font-size="13" fill="#065f46">measured on a 40-file repo</text>
+  <text x="490" y="440" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="700" fill="#047857">1050 &#8594; 215 chars  (&#8722;80%)</text>
+</svg>