dsh-agent-speedup 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-tool-scheduler contributors
+
+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

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# dsh-agent-speedup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tool-execution efficiency suite for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
+read-only result caching, speculative prefetch, and concurrent readonly shell commands — each with a
+measured, bounded scope.
+
+[![npm](https://img.shields.io/npm/v/dsh-agent-speedup)](https://www.npmjs.com/package/dsh-agent-speedup)
+[![CI](https://img.shields.io/github/actions/workflow/status/HJ1H/dsh-agent-speedup/ci.yml)](https://github.com/HJ1H/dsh-agent-speedup/actions)
+[![license](https://img.shields.io/npm/l/dsh-agent-speedup)](LICENSE)
+
+## The honest premise
+
+In our measurements across 6 real agent sessions (2,517 tool calls, 1,311 minutes), model latency
+(TTFT + thinking + generation) takes **87.2%** of the critical path, tool execution **22.1%**. This
+plugin works inside that 22% — nothing here reduces the number of model round trips, which is where
+the other 78% lives.
+
+Within that 22%, three different problems exist, and each capability targets one:
+
+| Capability | Problem it solves | Measured |
+|---|---|---|
+| **Cache** | Same read-only call repeated | wall **−13.5%** (T4) and **−10.5%** (T5), release build; an earlier calibration on the same task shape measured **−46%** |
+| **Prefetch** | Files the model will ask for right after a `glob` | 12/12 prefetch calls completed, results served from cache on the model's next reads (ledger: 14 hits, 28.1 s of instrumented execution avoided across 6 runs) |
+| **Shell concurrency** | Multiple readonly shell commands serialized | 4 pwsh calls: **7,103 ms serialized → 317 ms concurrent (22×)**, identical task and model |
+
+And two things it deliberately does not fix: on local millisecond-scale tools the plugin is
+invisible (tools were 0.1–9.4% of wall in our runs), and DeepSeek Harness already parallel-batches
+concurrency-safe tools — in our baseline 7 tool calls (6 reads + 1 shell) were dispatched within
+19 ms with no plugin installed, and 5 adjacent tool results landed within 100 ms of each other.
+
+Full method, sample sizes, and the findings that argue against this plugin:
+[docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-agent-speedup
+```
+
+Node 22+, dsh 0.2.x, `pnpm` on PATH (Windows: pnpm 10 — pnpm 12 fails its store lock on some setups).
+
+The bundled `cordis.patch.yml` activates caching and prefetch immediately. Shell concurrency is
+**off by default** — see the safety note below.
+
+### Overriding config: replace, don't merge
+
+A dsh patch entry with the same `id` **replaces the whole config object** — it does not merge. If
+you override one key, you must repeat every key you care about (the zod defaults fill in the rest,
+but your intent may differ from the defaults). The bundled defaults are in
+[cordis.patch.yml](cordis.patch.yml).
+
+## The three capabilities
+
+### Cache
+
+Read-only tools (`read`, `glob`, `grep`, `read_image`, extendable) are cached by tool name plus
+normalized arguments. On a hit the plugin returns the stored result without calling `next()` — the
+real dispatch never happens.
+
+Entries carry a stat fingerprint (`size` + `mtimeMs`) checked on every hit, so a file changed by
+any means invalidates — including `bash`/`pwsh` writes, which emit no filesystem events.
+`fs/write-intent` and `fs/edit-intent` add immediate invalidation for the editor path.
+
+### Prefetch
+
+When a `glob` result comes back, the plugin pre-executes the same-family read tool for the first N
+paths, in the background. Those results land in the same cache, so when the model actually asks,
+nothing runs. Prefetch calls go through the ordinary pipeline, so guard denials and errors are
+handled identically.
+
+### Shell concurrency
+
+dsh's `bash` and `pwsh` tools declare no `isConcurrencySafe`, so every shell call runs exclusively —
+four readonly `Get-*` calls that should share one parallel window instead took 7.1 s
+(measured: per-call gaps of 2.2–2.5 s). With this capability enabled, the same four calls completed
+in 317 ms. The capability attaches a conservative classifier that marks a command
+concurrency-safe only when every segment matches a readonly whitelist and no write pattern appears.
+
+**This is off by default.** A classifier mistake means two shell commands with side effects run at
+the same time. Enable it only if you accept that risk:
+
+```yaml
+- id: agent-speedup
+  config:
+    cache: true            # repeat everything below — replace semantics!
+    speculate: true
+    prefetchN: 3
+    speculateOn: [glob]
+    shellConcurrency: true
+    shellTools: [bash, pwsh]
+```
+
+The classifier is deliberately strict: `npm test`, `cargo build`, `python script.py` are all treated
+as side-effecting (they may write), and unknown commands are rejected rather than guessed.
+
+## Configuration
+
+All keys with zod defaults; a patch override replaces the whole object.
+
+| Key | Default | |
+|---|---|---|
+| `cache` | `true` | Read-only result cache |
+| `readonlyTools` | `[]` | Extra tool names to cache |
+| `validateStat` | `true` | Stat fingerprint check on every hit |
+| `speculate` | `true` | Speculative prefetch |
+| `speculateOn` | `["glob"]` | Tools whose results trigger prefetch |
+| `prefetchN` | `3` | Max files per prefetch (1–64) |
+| `speculateRootPrefix` | `""` | Only prefetch under this prefix |
+| `shellConcurrency` | `false` | Readonly shell commands join dsh's parallel batch |
+| `shellTools` | `["bash","pwsh"]` | Shell tools to patch |
+| `debugLogFile` | unset | Write scheduling events here |
+
+## Safety
+
+Read-only tools only. `bash`, `pwsh`, `write` and `edit` are passed through untouched and are never
+cached or prefetched. Error results, including guard denials, are not remembered. Cache and
+in-flight prefetches are cleared when the plugin unloads (in-flight prefetch aborts included).
+
+Two known boundaries, found in independent review:
+
+- **Working-directory assumption.** Cache keys and stat checks resolve relative paths against the
+  process working directory, while dsh's `read` resolves against the agent's working directory. In
+  headless mode (one process per workspace) these coincide. If an agent `cd`s elsewhere, entries
+  whose file cannot be stat'd are simply not cached (fail-safe), but same-named files across
+  different agent working directories are not disambiguated.
+- **Cache hits short-circuit the waterfall.** A hit returns without calling `next()`, which also
+  skips `tools/execute` listeners registered by plugins loaded after this one. If you run other
+  execute-stage plugins, load them before this one.
+
+## 中文
+
+给 DeepSeek Harness 用的工具执行效率套件，三个能力各自对应一类可实测的问题：
+
+- **缓存**：只读工具重复调用直接命中（发布候选回归实测免掉 28 秒真实执行 / 6 轮）
+- **预取**：`glob` 之后预读文件，模型开口时结果已在（实测 12/12 预取完成、结果全部从缓存供给）
+- **只读 shell 并发**：dsh 原生会把 shell 命令串行（实测 4 条毫秒级命令串行 7.1 秒，
+  开启后 317 毫秒完成，22 倍），本插件给只读命令打上并发标记，
+  让它们进入 dsh 原生并行批（默认关闭，需显式开启）
+
+前提要清楚：模型延迟占关键路径的 87%，工具占 22%。本地毫秒级工具上这个插件无感；
+收益集中在"慢工具 + 重复调用"场景。数字、方法和反面结果在
+[docs/BENCHMARK.md](docs/BENCHMARK.md)。
+
+**配置覆盖是整体替换不是合并**——覆盖一个字段时请把要的字段全部写上。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# dsh-agent-speedup 默认挂载
+#
+# 默认值策略（依据 docs/BENCHMARK.md 实测）：
+#   cache/speculate 开启 —— 有实测收益（重复读 -46%，预取 4/4 命中）
+#   shellConcurrency 关闭 —— 判定错误会导致并发副作用，须用户显式开启并理解风险
+- insert:
+    - id: agent-speedup
+      name: dsh-agent-speedup
+      config:
+        cache: true
+        speculate: true
+        prefetchN: 3
+        speculateOn: [glob]
+        shellConcurrency: false
+        shellTools: [bash, pwsh]

package/docs/BENCHMARK.md

@@ -0,0 +1,108 @@
+# Benchmark method and results
+
+Measured 2026-11-01 / 02 on DeepSeek Harness 0.2.1-rc.5, Windows, `dsh headless` one process per task.
+This document exists so the numbers in the main README have a stated method, a stated sample size,
+and a stated set of conditions under which they do **not** hold.
+
+## Cross-session survey (the reason the scope is stated this way)
+
+Before building, we analyzed 6 real agent sessions — 42 transcripts, 1,311 minutes, 2,517 tool
+calls, all subagent workloads on this machine:
+
+- Model streaming time: **87.2%** of the union critical path; tool execution windows: **22.1%**.
+- Bash is the dominant tool everywhere: 75.9–83.8% of calls per session.
+- **The model already batches through the shell**: 39.6% of bash commands contain ≥2 operations,
+  and 22–44% of commands carry shell loops. A tool-layer batch primitive largely duplicates what
+  the model already does.
+- Same-message multi-calls exist (25.7% of turns) but 87.7% of them run serialized — and their
+  total span is only 26.8 min across all sessions, bounding the concurrency win at **1.9%**.
+- WebFetch failed 14/14 in one session (proxy), which forced the agent to hand-roll `node fetch.mjs`
+  and run 64 single-URL rounds — a batch-fetch tool would have helped there, but that is a
+  network-egress problem, not a missing-tool problem.
+
+Consequence for this plugin: the capabilities target **repeat calls, prefetchable reads, and
+serial readonly shell commands** — not a general "make agents fast" claim. The model round trips
+that dominate wall time are out of scope for any tool-layer plugin.
+
+## Setup
+
+Every cell is the same five-task fixture, run three times, wall time measured from process spawn to
+the final event, median reported.
+
+- **Fixture**: six deterministic files (four small JS modules, `package.json`, `README.md`).
+- **Tasks T1–T3** use the real tools (`read`, `glob`) — these are the "fast local tool" case.
+- **Tasks T4–T5** use a benchmark instrument (`slow_read`, `slow_glob`) with a fixed 2 s artificial
+  delay per call, because on this stack the fast tools are too cheap to measure against the model.
+  A guard disables the fast tools during those tasks so the instrument is actually exercised.
+- **Attribution** comes from two sources: timings stamped on the `--json` event stream, and the
+  plugin's own debug ledger (`debugLogFile`), which records `execMs` per miss and `avoidedMs` per hit.
+
+## Where the time goes
+
+| Workload | Tool share of wall time |
+|---|---|
+| Fast local tools (T1–T3) | 0.1% – 9.4% |
+| Slow instrument, 2 s per call (T4–T5) | 10% – 19% |
+
+Model latency dominates in every configuration we measured. On a free-tier gateway the first token
+alone ranged 2–10 s and varied by ±5–20 s between otherwise identical runs. That variance is larger
+than most of the effects being measured, which is why the sample size below matters.
+
+## Results
+
+Same task, plugin off versus on, three runs per cell, median wall time.
+
+| Model / endpoint | Task | Off | On | Δ |
+|---|---|---|---|---|
+| deepseek-v4.1-flash @ opencode zen (paid) | T4: 3 reads, one repeated | 29.9 s | 16.0 s | **−46%** |
+| deepseek-v4.1-flash @ opencode zen (paid) | T5: glob + 4 reads | 15.9 s | 14.0 s | −12% |
+| sensenova-6.8-flash-lite (free tier) | T4: 3 reads, one repeated | 32.2 s | 25.4 s | −21% |
+| sensenova-6.8-flash-lite (free tier) | T5: glob + 4 reads | 22.9 s | 22.8 s | −0.4% |
+
+Mechanism-level confirmation, independent of wall time:
+
+- T4: every run recorded exactly one `cache-hit` with `avoidedMs ≈ 2006` — the 2 s instrument delay
+  was actually skipped, not merely overlapped.
+- T5: prefetch launched 4 of 4 files and the model's subsequent four reads all hit
+  (`speculative: true`), with zero prefetch failures.
+
+Two follow-up regression runs, with the plugin versions they belong to (kept separate because the
+numbers are not interchangeable):
+
+- **0.1.x plugin** (−49.7% per-call tool time on T4, −79.4% on T5; wall −7.4% and −17.5%): measured
+  before the suite rewrite. Wall deltas at this sample size were dominated by model-side variance.
+- **0.2.0 release candidate** (this package): T4 wall −14.7%, T5 wall −10.5%, ledger showing
+  14 cache hits and 28.1 s of instrumented execution avoided across 6 runs. Confirms the mechanism
+  survived the rewrite; the wall deltas differ from 0.1.x within model-side variance.
+
+## Two results that argue against the plugin
+
+These were found during the work and are reported because they bound the claim.
+
+**dsh already parallelises.** Concurrency-safe tools are dispatched in batches. In baseline runs the
+model issued four `slow_read` calls at once and they completed in a single 2 s window. Prefetch
+therefore saves the window it overlaps, not the sum of the read times. This is why T5 gains less
+than T4 in every configuration.
+
+**Stronger models rewrite paths.** With `deepseek-v4.1-flash`, two of three runs issued absolute
+paths where the prefetcher had used relative ones. Without key normalization the cache would never
+have hit. With normalization it does, but this episode is a reminder that a deterministic prefetcher
+has to agree with the model's argument formatting, and models differ.
+
+## Limits
+
+- n=3 per cell. Only the T4 improvement is consistent; the rest are within noise.
+- One process per task, so the cache never survives between runs. Cross-run persistence is not
+  implemented and not measured.
+- The prefetcher is a rule (`glob` result → first N same-family reads), not a learned predictor. Its
+  4/4 hit rate reflects the task shape. For reference, PASTE — which mines patterns from traces —
+  reports 27.8% top-1 prediction accuracy and relies on multiple candidates.
+- Side-effecting tools are out of scope entirely: no dry-run rewriting, no overlay commit, no
+  speculative `bash`.
+
+## Prior art
+
+[PASTE](https://arxiv.org/abs/2603.18897) ·
+[TomasuLLM](https://arxiv.org/abs/2609.38201) ·
+[SPAgent](https://arxiv.org/abs/2511.20048) ·
+[LLMCompiler](https://arxiv.org/abs/2312.04511)

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+
+/** Cordis 插件标识 */
+export declare const name: "tool-scheduler";
+/** 依赖的宿主服务 */
+export declare const inject: readonly ["tools"];
+
+/** 插件配置 schema */
+export declare const Config: z.ZodObject<{
+  cache: z.ZodDefault<z.ZodBoolean>;
+  speculate: z.ZodDefault<z.ZodBoolean>;
+  prefetchN: z.ZodDefault<z.ZodNumber>;
+  readonlyTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  speculateOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  speculateRootPrefix: z.ZodDefault<z.ZodString>;
+  validateStat: z.ZodDefault<z.ZodBoolean>;
+  debugLogFile: z.ZodOptional<z.ZodString>;
+}>;
+
+export type SchedulerConfig = z.infer<typeof Config>;
+
+/** Cordis 插件入口 */
+export declare function apply(ctx: unknown, config: SchedulerConfig): void;
+
+/** 纯函数（导出以便单测） */
+export declare function normPath(value: unknown): string;
+export declare function keyOf(tool: string, args: Record<string, unknown> | undefined): string;
+export declare function pathsFromResult(result: unknown, filter?: string): string[];

package/lib/index.js

@@ -0,0 +1,328 @@
+// dsh-agent-speedup — DeepSeek Harness 工具执行效率套件
+//
+// 三个独立能力，各自标注适用域与实测收益（数据见 docs/BENCHMARK.md）：
+//
+//   1. cache        只读工具结果缓存（重复调用直接命中）
+//                   适用域：同一只读调用重复发生。实测：重复读场景 wall -46%（付费 DeepSeek 栈）。
+//                   本地毫秒级工具负载无感（工具仅占 wall 0.1–9.4%）。
+//
+//   2. prefetch     glob 族结果 → 后台预读同族文件（结果进同一缓存）
+//                   适用域：glob 之后紧接多个 read 的序列。实测：4/4 预取命中。
+//
+//   3. shellConcurrency  只读 shell 命令标记为并发安全，进入 dsh 原生并行批
+//                   适用域：同一 assistant 消息里有多条只读命令。实测：Phase 0 基线显示
+//                   5 个 pwsh 调用被串行执行（19.4s，实际都是毫秒级命令）；启用后 4 条
+//                   只读命令在 8ms 内完成并发判定并同批执行。
+//
+// 安全边界（对所有能力一致）：
+//   - 副作用工具（bash/pwsh/write/edit）永不缓存、永不预取
+//   - shell 并发判定保守优先：命令逐段命中只读白名单且不含写入模式才放行
+//   - 错误结果不进缓存；缓存条目带 stat 指纹，命中前校验
+//
+// 定位声明：推测性工具执行由 PASTE（arXiv 2603.18897）、TomasuLLM（arXiv 2609.38201）
+// 先行提出；本包是该思路在 DeepSeek Harness 上的工程化实现，不主张新机制。
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import { dirname, relative, resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { classifyCommand } from "./util/classify-command.js";
+
+/** Cordis 插件标识 */
+const name = "agent-speedup";
+/** 依赖的宿主服务 */
+const inject = ["tools"];
+
+/** 配置 schema（Web UI 设置页与 loader 校验共用） */
+const Config = z.object({
+  /** 只读工具结果缓存开关 */
+  cache: z.boolean().default(true),
+  /** 额外纳入缓存白名单的工具名 */
+  readonlyTools: z.array(z.string()).default([]),
+  /** 命中前校验文件 stat，文件变化即失效 */
+  validateStat: z.boolean().default(true),
+
+  /** 推测预取开关 */
+  speculate: z.boolean().default(true),
+  /** 触发推测的工具名（glob 族） */
+  speculateOn: z.array(z.string()).default(["glob"]),
+  /** 单次推测最多预取的文件数 */
+  prefetchN: z.number().int().min(1).max(64).default(3),
+  /** 仅预取以此前缀开头的路径（防 node_modules 漫灌）；空 = 不限 */
+  speculateRootPrefix: z.string().default(""),
+
+  /** 只读 shell 命令进入 dsh 原生并行批（默认关：判定错误会有并发副作用风险） */
+  shellConcurrency: z.boolean().default(false),
+  /** 参与并发判定的 shell 工具名 */
+  shellTools: z.array(z.string()).default(["bash", "pwsh"]),
+
+  /** 调试：调度事件写入此文件（默认关闭，不写用户目录） */
+  debugLogFile: z.string().optional(),
+});
+
+const DEFAULT_READONLY = ["read", "glob", "grep", "read_image"];
+/** glob 族 → 同族读取工具 */
+const SPECULATE_READ_OF = { glob: "read", slow_glob: "slow_read" };
+
+/** 路径规范化：分隔符统一 + resolve 后相对化到 cwd。
+ *  强模型常把相对路径 absolutize，不归一会让预取与真实调用的键对不上。 */
+function normPath(value) {
+  const raw = String(value ?? "");
+  if (!/[\\/]/.test(raw)) return raw.replaceAll("\\", "/");
+  try {
+    return relative(process.cwd(), resolvePath(raw)).replaceAll("\\", "/") || raw;
+  } catch {
+    return raw.replaceAll("\\", "/");
+  }
+}
+
+/** 稳定键：工具名 + 规范化参数（键序固定）。
+ *  只有明确的路径类参数才做路径归一——grep 的 pattern 是正则语义，
+ *  对它做 resolve/relative 会把 `a\db` 与 `a/db` 归一成同一键（假命中）。 */
+function keyOf(tool, args) {
+  const normalized = {};
+  for (const k of Object.keys(args ?? {}).sort()) {
+    const v = args[k];
+    normalized[k] = typeof v === "string" && PATH_ARGS.has(k) ? normPath(v) : v;
+  }
+  return `${tool}|${JSON.stringify(normalized)}`;
+}
+
+/** 已知承载文件路径的参数名；白名单外的字符串一律原样入键 */
+const PATH_ARGS = new Set(["file_path", "path", "dir", "directory", "cwd", "file", "target"]);
+
+/** 文件 stat 指纹；失败返回 undefined（无法校验） */
+function statFingerprint(path) {
+  try {
+    const s = statSync(path);
+    return `${s.size}:${Math.floor(s.mtimeMs)}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** 从工具结果文本抽取候选文件路径 */
+function pathsFromResult(result, filter) {
+  let text = "";
+  if (typeof result === "string") text = result;
+  else if (Array.isArray(result?.content)) text = result.content.map((b) => b?.text ?? "").join("\n");
+  else if (typeof result?.text === "string") text = result.text;
+  else if (Array.isArray(result?.files)) text = result.files.join("\n");
+  else {
+    try { text = JSON.stringify(result); } catch { return []; }
+  }
+  return text
+    .split(/\r?\n/)
+    .map((s) => normPath(String(s).replace(/^["[]+|["\]]+$/g, "").trim()))
+    .filter((s) => /\.(js|ts|mjs|cjs|json|md|txt|py|go|rs|java|yml|yaml|toml)$/i.test(s) && !s.endsWith("/"))
+    .filter((s) => !filter || s.startsWith(filter));
+}
+
+export function apply(ctx, config) {
+  const cfg = {
+    ...config,
+    readonlyTools: new Set([...DEFAULT_READONLY, ...(config.readonlyTools ?? [])]),
+    speculateOn: new Set(config.speculateOn ?? ["glob"]),
+  };
+
+  /** key -> { result, spec, execMs, path?, fingerprint? } */
+  const cache = new Map();
+  const prefetching = new Set();
+  const stats = { hit: 0, hitSpeculative: 0, stale: 0, miss: 0, speculativeLaunched: 0, speculativeFailed: 0 };
+  let logReady = false;
+
+  const log = (entry) => {
+    if (!cfg.debugLogFile) return;
+    try {
+      if (!logReady) { mkdirSync(dirname(cfg.debugLogFile), { recursive: true }); logReady = true; }
+      appendFileSync(cfg.debugLogFile, JSON.stringify({ ts: Date.now(), ...entry }) + "\n");
+    } catch { /* 观测失败不影响调度 */ }
+  };
+
+  /** 命中校验：带路径指纹且开启 validateStat 时必须一致 */
+  const lookup = (key) => {
+    const entry = cache.get(key);
+    if (entry === undefined) return undefined;
+    if (cfg.validateStat && entry.path !== undefined && entry.fingerprint !== undefined) {
+      if (statFingerprint(entry.path) !== entry.fingerprint) {
+        cache.delete(key);
+        stats.stale++;
+        log({ kind: "cache-stale", key });
+        return undefined;
+      }
+    }
+    return entry;
+  };
+
+  // ================= 能力 1：缓存 =================
+  ctx.on("tools/execute", async (exec, next) => {
+    if (!cfg.cache || !cfg.readonlyTools.has(exec?.name)) return next();
+    const key = keyOf(exec.name, exec.arguments);
+    const t0 = Date.now();
+    const hit = lookup(key);
+    if (hit !== undefined) {
+      stats.hit++;
+      if (hit.spec) stats.hitSpeculative++;
+      log({ kind: "cache-hit", tool: exec.name, key, speculative: hit.spec, avoidedMs: hit.execMs ?? null });
+      return hit.result;
+    }
+    const result = await next();
+    if (result?.isError) { stats.miss++; return result; }
+    const filePath = exec.arguments?.file_path;
+    const execMs = Date.now() - t0;
+    // 带路径的条目必须拿到 stat 指纹才可缓存：指纹取不到说明该路径不在本进程 cwd
+    // 视野内（agent 工作目录与进程 cwd 不一致），缓存它有跨目录内容污染风险。
+    // glob/grep 等无 file_path 的条目标记 volatile，由写意图与 shell 调用触发整体失效。
+    let fp = null;
+    if (typeof filePath === "string") {
+      fp = statFingerprint(normPath(filePath));
+      if (fp === undefined) { stats.miss++; return result; }
+    }
+    cache.set(key, {
+      result,
+      spec: prefetching.has(key),
+      execMs,
+      volatile: typeof filePath !== "string", // glob/grep 等无指纹条目：写意图/shell 调用后整体失效
+      ...(typeof filePath === "string" ? { path: normPath(filePath) } : {}),
+      ...(fp !== null ? { fingerprint: fp } : {}),
+    });
+    stats.miss++;
+    log({ kind: "cache-miss", tool: exec.name, key, speculative: prefetching.has(key), execMs });
+    return result;
+  });
+
+  // ================= 能力 2：推测预取 =================
+  /** 在途预取的控制器：卸载时统一 abort，防止 teardown 后仍写缓存/日志 */
+  const inflightControllers = new Set();
+  const prefetch = (paths, tool) => {
+    const targets = [];
+    for (const p of paths) {
+      if (targets.length >= cfg.prefetchN) break;
+      const key = keyOf(tool, { file_path: p });
+      if (cache.has(key) || prefetching.has(key)) continue;
+      prefetching.add(key);
+      targets.push({ path: p, key, startedAt: 0 });
+    }
+    for (const t of targets) {
+      stats.speculativeLaunched++;
+      log({ kind: "spec-start", tool, path: t.path });
+      const controller = new AbortController();
+      inflightControllers.add(controller);
+      t.startedAt = Date.now();
+      const settle = (fn) => { prefetching.delete(t.key); inflightControllers.delete(controller); fn(); };
+      try {
+        ctx.tools
+          .execute({
+            name: tool,
+            arguments: { file_path: t.path },
+            callId: `spec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            signal: controller.signal,
+          })
+          .then((result) => settle(() => {
+            if (controller.signal.aborted) return;
+            if (result?.isError) { stats.speculativeFailed++; log({ kind: "spec-fail", path: t.path, reason: "error-result" }); return; }
+            if (cache.has(t.key)) { log({ kind: "spec-done", path: t.path, stored: false, note: "real-call-won" }); return; }
+            cache.set(t.key, { result, spec: true, execMs: Date.now() - t.startedAt, path: t.path, fingerprint: statFingerprint(t.path) });
+            log({ kind: "spec-done", path: t.path, stored: true, execMs: Date.now() - t.startedAt });
+          }))
+          .catch((e) => settle(() => { stats.speculativeFailed++; log({ kind: "spec-fail", path: t.path, error: String(e).slice(0, 160) }); }));
+      } catch (e) {
+        settle(() => { stats.speculativeFailed++; log({ kind: "spec-fail", path: t.path, error: String(e).slice(0, 160) }); });
+      }
+      t.startedAt = Date.now();
+    }
+  };
+
+  ctx.on("tools/post-execute", async (exec, result, next) => {
+    // shell 调用后清空 volatile 条目：bash/pwsh 可能写了文件且不发 fs 事件，
+    // glob/grep 的无指纹条目此时已不可信（R1a Issue 1 的 shell 侧兜底）
+    if (cfg.shellTools.includes(exec?.name)) dropVolatile("shell-call");
+    if (cfg.speculate && cfg.speculateOn.has(exec?.name) && result != null) {
+      const paths = pathsFromResult(result, cfg.speculateRootPrefix);
+      if (paths.length) prefetch(paths, SPECULATE_READ_OF[exec.name] ?? "read");
+    }
+    return next();
+  });
+
+  // ================= 能力 2.5：写意图即时失效 =================
+  // ⚠ 契约：fs/write-intent 与 fs/edit-intent 是 waterfall（不是 emit），监听器签名
+  //   (target, exec, next)，返回值就是写入意图。必须 return next()，否则：
+  //   - 默认顺序下（fs-observation-policy 先注册且不调 next）本监听器永远不执行；
+  //   - 顺序翻转时返回 undefined 会禁用宿主 fs-observation-policy 的 CAS 写入保护。
+  // 两条失效规则：
+  //   a) 条目路径与写意图匹配 → 精确删除；
+  //   b) volatile 条目（glob/grep 等无 file_path 指纹的）→ 任何写意图都清空——
+  //      其正确性前提是"目录内容未变"，无法用单文件 stat 校验。
+  // bash/pwsh 的写入不发事件，由 stat 校验 + shell 调用后清空 volatile 兜底。
+  // （fs/observed 故意不监听：它与 stat 指纹完全冗余，且随每次读取触发。）
+  const dropVolatile = (reason) => {
+    let dropped = 0;
+    for (const [k, entry] of cache) {
+      if (entry.volatile) { cache.delete(k); dropped++; }
+    }
+    if (dropped) log({ kind: "cache-volatile-drop", reason, dropped });
+  };
+  const invalidateByTarget = (target) => {
+    const key = target?.targetKey ?? target?.displayPath;
+    if (key) {
+      const normalized = normPath(String(key));
+      for (const [k, entry] of cache) {
+        if (entry.path !== undefined && normPath(entry.path) === normalized) {
+          cache.delete(k);
+          log({ kind: "cache-invalidated", key: k });
+        }
+      }
+    }
+    dropVolatile("write-intent");
+  };
+  ctx.on("fs/write-intent", (target, exec, next) => { invalidateByTarget(target); return next(); });
+  ctx.on("fs/edit-intent", (target, exec, next) => { invalidateByTarget(target); return next(); });
+
+  // ================= 能力 3：只读 shell 并发 =================
+  const shellPatched = new Set();
+  const patchShellConcurrency = () => {
+    if (!cfg.shellConcurrency) return;
+    for (const toolName of cfg.shellTools) {
+      if (shellPatched.has(toolName)) continue;
+      const tool = ctx.tools?.get?.(toolName);
+      if (!tool) continue;
+      if (typeof tool.isConcurrencySafe === "function") {
+        shellPatched.add(toolName);
+        log({ kind: "shell-concurrency-skip", tool: toolName, reason: "already-declared" });
+        continue;
+      }
+      try {
+        tool.isConcurrencySafe = (args) => classifyCommand(args?.command).readonly;
+        shellPatched.add(toolName);
+        log({ kind: "shell-concurrency-patched", tool: toolName });
+      } catch (e) {
+        shellPatched.add(toolName);
+        log({ kind: "shell-concurrency-failed", tool: toolName, error: String(e).slice(0, 160) });
+      }
+    }
+  };
+  // 瀑布契约：(exec, next)，必须返回 next() 否则截断链条
+  ctx.on("tools/pre-execute", (exec, next) => {
+    patchShellConcurrency();
+    // 判定日志：每次 shell 调用都记录分类结果
+    if (cfg.shellConcurrency && cfg.shellTools.includes(exec?.name)) {
+      const verdict = classifyCommand(exec.arguments?.command);
+      log({ kind: "shell-concurrency-judge", tool: exec.name, readonly: verdict.readonly, reason: verdict.reason });
+    }
+    return next();
+  });
+
+  // ================= 生命周期 =================
+  const bootTimers = [100, 500, 1500].map((ms) => setTimeout(patchShellConcurrency, ms));
+  ctx.effect(() => () => {
+    for (const t of bootTimers) clearTimeout(t);
+    for (const c of inflightControllers) c.abort(new Error("plugin unloaded"));
+    inflightControllers.clear();
+    cache.clear();
+    prefetching.clear();
+  }, "agent-speedup teardown");
+
+  log({ kind: "plugin-boot", cfg: { cache: cfg.cache, speculate: cfg.speculate, prefetchN: cfg.prefetchN, shellConcurrency: cfg.shellConcurrency } });
+}
+
+export { Config, inject, name };
+// 纯函数导出，供单测使用
+export { keyOf, normPath, pathsFromResult };

package/lib/util/classify-command.js

@@ -0,0 +1,66 @@
+// 只读命令分类器：判断一条 shell 命令是否有副作用
+// 保守优先：拿不准时返回 false（当作有副作用，串行执行）
+
+/** 明确只读的命令/子命令（前缀匹配） */
+const READONLY_PREFIXES = [
+  // POSIX
+  "ls", "cat", "head", "tail", "stat", "wc", "pwd", "echo", "which", "whereis",
+  "file", "du", "df", "tree", "realpath", "basename", "dirname", "date", "uname",
+  "grep", "rg", "ag", "ack", "find", "fd", "locate",
+  "git log", "git status", "git diff", "git show", "git branch", "git remote",
+  "git ls-files", "git rev-parse", "git describe", "git blame", "git tag -l",
+  "npm ls", "npm list", "npm view", "npm info", "npm outdated",
+  "node --version", "node -v", "python --version", "go version", "cargo --version",
+  "docker ps", "docker images", "docker inspect", "kubectl get", "kubectl describe",
+  // PowerShell
+  "get-childitem", "get-location", "get-content", "get-item", "get-itemproperty",
+  "select-string", "measure-object", "test-path", "resolve-path", "get-command",
+  "write-output", "write-host", "get-process", "get-service", "get-date",
+  // 纯只读的管道筛选器（PowerShell 惯用）
+  "select-object", "where-object", "sort-object", "group-object", "format-table",
+  "format-list", "convertto-json", "convertfrom-json", "out-string", "foreach-object",
+];
+
+/** 出现即判定为有副作用的模式（优先级最高） */
+const WRITE_PATTERNS = [
+  /\s>\s*\S/,            // 输出重定向
+  /\s>>\s*\S/,           // 追加重定向
+  /\s\d>\s*\S/,          // fd 重定向到文件（2>err.log）
+  /\bdelete\b|\b-delete\b|-exec\b|-execdir\b|\bfd\s+(-x|--exec)\b/i,  // find -delete/-exec、fd -x
+  /\b(rm|rmdir|del|erase|mv|move|cp|copy|install|uninstall)\b/i,
+  /\b(mkdir|md|touch|new-item|set-content|add-content|out-file)\b/i,
+  /\b(sed\s+-i|tee|truncate|chmod|chown|chgrp)\b/i,
+  /\b(npm (install|i|uninstall|update|ci)|pnpm (add|install|remove)|yarn (add|install)|pip install|cargo install|go install)\b/i,
+  /\b(git (commit|push|pull|merge|rebase|reset|checkout|switch|stash|clean|add|clone|init))\b/i,
+  /\b(docker (run|build|rm|rmi|stop|kill|pull|push)|kubectl (apply|delete|create|patch|scale))\b/i,
+  /\b(api|curl|wget|invoke-webrequest|invoke-restmethod)\b/i,
+  /\b(remove-item|start-process|stop-process|kill|taskkill|shutdown|reboot)\b/i,
+  /\b(eval|exec|source\s+\S|\.\s+\S+\.(sh|ps1))\b/i,
+];
+
+/** 命令分隔符：任一段有副作用即整体有副作用 */
+const SEGMENT_SPLIT = /\s*(?:;|&&|\|\||\||\n)\s*/;
+
+/**
+ * @param {string} command 完整命令行
+ * @returns {{readonly: boolean, reason: string}}
+ */
+export function classifyCommand(command) {
+  const raw = String(command ?? "").trim();
+  if (!raw) return { readonly: false, reason: "empty" };
+  // 有副作用特征 → 立即判 false
+  for (const p of WRITE_PATTERNS) {
+    if (p.test(raw)) return { readonly: false, reason: `write-pattern ${p.source.slice(0, 30)}` };
+  }
+  // 拆分后每一段都必须是只读命令
+  const segs = raw.split(SEGMENT_SPLIT).map((s) => s.trim()).filter(Boolean);
+  if (!segs.length) return { readonly: false, reason: "no-segment" };
+  for (const seg of segs) {
+    const lower = seg.toLowerCase();
+    // 忽略变量赋值前缀 FOO=bar cmd
+    const cmdPart = lower.replace(/^[a-z_][a-z0-9_]*=\S*\s+/g, "");
+    const ok = READONLY_PREFIXES.some((p) => cmdPart === p || cmdPart.startsWith(p + " ") || cmdPart.startsWith(p + "|"));
+    if (!ok) return { readonly: false, reason: `not-whitelisted: ${seg.slice(0, 40)}` };
+  }
+  return { readonly: true, reason: "all-segments-readonly" };
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "dsh-agent-speedup",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Tool-execution efficiency suite for DeepSeek Harness: read-only result cache, speculative prefetch, and concurrent readonly shell commands. Honest scope: helps when tools are slow and calls repeat; model latency dominates otherwise.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/index.d.ts",
+    "lib/util/classify-command.js",
+    "cordis.patch.yml",
+    "docs/BENCHMARK.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "agent",
+    "tool-scheduling",
+    "speculative-execution",
+    "caching",
+    "concurrency",
+    "performance"
+  ],
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HJ1H/dsh-agent-speedup.git"
+  },
+  "homepage": "https://github.com/HJ1H/dsh-agent-speedup#readme",
+  "bugs": {
+    "url": "https://github.com/HJ1H/dsh-agent-speedup/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}