# dsh-agent-speedup 中文文档

规范地址：https://npmcn.com/package/dsh-agent-speedup/

版本：0\.2\.5
npm 元数据更新时间：2026-11-03T12:47:09.777Z
中文译文更新时间：2026-11-03T13:02:17.342Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dsh-agent-speedup
原文对照：https://npmcn.com/package/dsh-agent-speedup/?lang=original
项目主页：https://github.com/HJ1H/dsh-agent-speedup#readme
源码仓库：https://github.com/HJ1H/dsh-agent-speedup

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：98.6 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis \>=4\.0\.0，@deepseek-ai/dsh-tools \>=0\.2\.0-rc\.0
- 首次发布：2026-11-02T17:55:03.812Z
- 最新版本发布：2026-11-03T12:29:39.555Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

DeepSeek Harness的工具执行效率套件：只读结果缓存，推测预取和并发只读shell命令。诚实作用域：在工具运行缓慢和调用重复时提供帮助；模型延迟占主导地位。

## 安装

```sh
npm install dsh-agent-speedup
```

也可以使用：`pnpm add dsh-agent-speedup`、`yarn add dsh-agent-speedup`、`bun add dsh-agent-speedup`

## README

# dsh-agent-speedup

工具执行效率套件 [DeepSeek利用](https://github.com/deepseek-ai/deepseek-harness)： 只读结果缓存、推测预取和并发只读shell命令—每个命令都有一个 测量的，有限的范围。

[![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)](https://npmcn.com/package/dsh-agent-speedup/LICENSE)

## 诚实的前提

在我们对6个真实代理会话（2,517个工具调用，1,311分钟）的测量中，模型延迟 （TTFT +思考+生成）需要 **87.2%** 关键路径，工具执行 **22.1%**。这 插件在22%的范围内工作-这里没有减少模型往返的次数，这就是 剩下的78%活了下来。

在这22%的问题中，存在三个不同的问题，每个能力针对一个问题：

| 能力 | 它解决的问题 | 测量 |
| --- | --- | --- |
| **缓存** | 重复的只读调用 | 重复读 **2023 ms→7 ms** （连续运行，5运行对） |
| **动态合并** | 同一个调用在一个并行批处理中重复 | 3同时读取跨度 **共计2027毫秒**不是6秒 |
| **预取** | 文件后，模型将立即请求 `glob` | 工具的时间 **10 084 ms→2 065 ms（−79.5%）**;每次读值 **2016毫秒→11毫秒** |
| **壳牌并发** | 序列化多个只读shell命令 | 4 PWSH调用： **7 103 ms→317 ms （22×）** |

有两件事它故意没有解决：在本地毫秒级的工具插件 无形的（工具在我们的运行中占了0.1-9.4%），DeepSeek Harness已经并行批处理了 并发安全的工具——在我们的基线中有7个工具调用（6个读取+ 1个shell）被调度 19毫秒，没有安装插件，5个相邻的工具结果落在100毫秒内。

**不同于HarnessMM的图层。** [HarnessMM](https://arxiv.org/abs/2610.32813) 同样的目标 深寻挽具，但它移除 _模型推理调用_ 通过重播谨慎的决定；这个插件 去除 _工具执行_ 从不讲道理。它们组成了一个决策图 工具调用，缓存命中使这些调用更便宜。看到 [文档/ BENCHMARK.md](https://npmcn.com/package/dsh-agent-speedup/docs/BENCHMARK.md#harnessmm-arxiv-261032813--closest-neighbour-different-layer) 对于会计警告，如果两者都安装。

完整的方法，样本大小，以及反对这个插件的发现： [文档/ BENCHMARK.md](https://npmcn.com/package/dsh-agent-speedup/docs/BENCHMARK.md)。

## 安装

```bash
dsh plugin --profile web add dsh-agent-speedup
```

Node 22+, dsh 0.2.x， `pnpm` （Windows: pnpm 10 - pnpm 12在某些设置上失败了它的store锁）。

的捆绑 `cordis.patch.yml` 立即激活缓存和预取。Shell并发性是 **默认关闭** -请参阅下面的安全说明。

### 重写config: replace，而不是merge

一个具有相同的盘补丁条目 `id` **替换整个配置对象** -它不合并。如果 你覆盖了一个键，你必须重复你关心的每个键（默认值填充其余的键）， 但您的意图可能与默认值不同)。捆绑的默认值已经出现 [cordis.patch.yml](https://npmcn.com/package/dsh-agent-speedup/cordis.patch.yml)。

## 三种能力

### 缓存

只读工具(`read`， `glob`， `grep`， `read_image`（可扩展）按工具名称加进行缓存 归一化参数。在命中时，插件返回存储的结果而不调用 `next()` - - - 真正的调度从未发生过。

条目携带一个统计指纹(`size` + `mtimeMs`)检查每次点击，所以文件被 任何方法都是无效的——包括 `bash`/`pwsh` 写，它不会产生文件系统事件。 `fs/write-intent` 和 `fs/edit-intent` 为编辑器路径添加即时无效。

相对路径解析 **座席会话工作目录**，同样的基础盘自己的 `read` 使用，所以代理 `cd`S不能与其他地方的同名文件冲突。 缓存是一个LRU，由 `maxEntries` （默认512），以及文件更改的结果 _在_ 读取的数据不被存储。

**空中凝聚。** DSH在一个并行批处理中调度一个回合的只读调用。一批 两次包含相同的调用都会错过缓存，因为两个调用都没有完成。调用 当一个相同的调用仍在运行时到达，共享执行而不是重复执行 这涵盖了单独缓存无法处理的并行情况。

工具名称是逐字匹配的。 `read`， `glob`， `grep` 和 `read_image` 是内置的；任何自定义 必须列出要缓存的MCP工具 `readonlyTools` (在 `speculateOn` 如果结果是 应该触发预取)。不知名的名字永远不会被认为是安全的。

### 预取

当一个 `glob` 结果返回时，插件对第一个N预执行同族读取工具 路径，在背景中。这些结果都在同一个缓存中，所以当模型真正问， 没有运行。预取调用通过普通的管道-相同的代理上下文，相同的工作 目录，相同的保护-因此拒绝和错误被相同地处理。

### 壳牌并发

近年来的 `bash` 和 `pwsh` 工具声明没有 `isConcurrencySafe`，因此每个shell调用都独占地运行- 四个只读的 `Get-*` 而应该共享一个并行窗口的调用只需要7.1秒 （测量：每次呼叫间隔为2.2-2.5秒）。启用此功能后，完成了相同的四个调用 317年。该功能附加一个标记命令的保守分类器 只有当每个段都匹配只读白名单并且没有出现写模式时，并发安全。

**默认情况下是关闭的。** 一个分类器错误意味着两个带有副作用的shell命令运行在 同一时间。只有在你接受风险的情况下才启用它：

```yaml
- id: agent-speedup
  config:
    cache: true            # repeat everything below — replace semantics!
    readonlyTools: []
    validateStat: true
    maxEntries: 512
    speculate: true
    prefetchN: 3
    speculateOn: [glob]
    speculateRootPrefix: ""
    shellConcurrency: true
    shellTools: [bash, pwsh]
```

分类器是故意严格的： `npm test`， `cargo build`， `python script.py` 都得到了治疗 作为副作用（他们可能会写），未知的命令被拒绝而不是猜测。 子命令按谓词处理，而不是按程序名处理 `git branch` （list）是只读的 `git branch new` （create）不是； `git remote` 列出了但 `git remote add` 重写配置; `find` 允许 `-print` 但不是 `-fprint`/`-exec`/`-delete`； `file -C`， `tree -o`， `date -s` 被拒绝了。

有四个类被直接拒绝，因为它们的效果只有在运行时才知道：command 替换(`$(...)`引号) `${VAR}` 展开，转义shell元字符，和 `NAME=value cmd` 前缀(`GIT_EXTERNAL_DIFF`， `LD_PRELOAD`， `NODE_OPTIONS` 所有让一个“只读” 命令运行任意代码)。PowerShell脚本块(`{ ... }`,这 `Where-Object` / `ForEach-Object` 执行)也被拒绝。一个光秃秃的 `&` 将命令行分开，如下所示 `;` ——一个 攻击者无法将写入器隐藏在后台作业后面。

对这个分类器进行对抗性审查是发布过程的一部分；它发现的逃生通道 0.2.2中的每一个都包含一个回归测试(参见 `test/classify-command.test.js`， `R2` 套房)。

## 配置

所有默认值为zd的键；补丁覆盖替换整个对象。

| 关键 | 默认的 |  |
| --- | --- | --- |
| `cache` | `true` | 只读结果缓存 |
| `readonlyTools` | `[]` | 要缓存的额外工具名称 |
| `validateStat` | `true` | 对每个命中的人进行指纹检查 |
| `maxEntries` | `512` | 缓存结果的LRU上限（1-100000） |
| `speculate` | `true` | 投机预取 |
| `speculateOn` | `["glob"]` | 其结果触发预取的工具 |
| `prefetchN` | `3` | 每次预取最大文件数（1-64） |
| `speculateRootPrefix` | `""` | 只在该前缀下预取 |
| `shellConcurrency` | `false` | 只读shell命令加入dsh的并行批处理 |
| `shellTools` | `["bash","pwsh"]` | 要修补的Shell工具 |
| `debugLogFile` | 设置 | 在这里写入调度事件 |

## 安全

只读工具。 `bash`， `pwsh`， `write` 和 `edit` 没有被碰触过，永远不会 缓存或预取。错误结果，包括守卫拒绝，不会被记住。缓存和 当插件卸载时，在线预取将被清除（包括在线预取中止）。

在独立审查中发现的一个已知边界：

-   **Cache击中了瀑布，使其短路。** hit返回而不调用 `next()`，这也是 跳过 `tools/execute` 在此之后加载的插件注册的监听器。如果你运行其他 执行阶段插件，在此之前加载它们。

从0.2.1开始的工作目录边界是 **固定** 在0.2.2中：键和状态检查现在使用 `workingDirectory` （代理的会话目录），带有process-`cwd` 只有在这种情况下才能后退 服务未挂载。如果根本无法获取指纹，则不缓存该条目。

## 中文

深寻线束

-   **缓存**英文：1 .中文：5 .中文：2023ms→7ms)
-   **在途合并**： 3‰，2027ms, 6‰，1‰，1‰，1‰，1‰，1‰，1‰
-   **预取**：`glob` 10.08秒→2.07秒，−79.5%； 2016ms→11ms,−99.5%)
-   **壳，壳，壳**/ / / / / / / / / / 开启后 317 毫秒完成，22 倍），本插件给只读命令打上并发标记， 【中文翻译】
-   **判定粒度**：按子命令和参数判定，不按程序名放行——`git branch`（列举）只读、 `git branch new`（创建）不是；`find -print` 放行、`-fprint/-exec/-delete` 拒绝。 命令替换、`${VAR}`、转义元字符、`NAME=value cmd` 缀，PowerShell 一律拒绝（它们的实际行为要到运行时才知道）

前提要清楚：模型延迟占关键路径的 87%，工具占 22%。本地毫秒级工具上这个插件无感； 收益集中在"慢工具 + 重复调用"场景。数字、方法和反面结果在 [文档/ BENCHMARK.md](https://npmcn.com/package/dsh-agent-speedup/docs/BENCHMARK.md)。

**配置覆盖是整体替换不是合并**——覆盖一个字段时请把要的字段全部写上。

## 许可证

麻省理工学院

## 常见问题

### dsh-agent-speedup 是什么？

DeepSeek Harness的工具执行效率套件：只读结果缓存，推测预取和并发只读shell命令。诚实作用域：在工具运行缓慢和调用重复时提供帮助；模型延迟占主导地位。

### 如何安装 dsh-agent-speedup？

在项目目录运行 npm install dsh-agent-speedup，或使用 pnpm add / yarn add / bun add。

### dsh-agent-speedup 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### dsh-agent-speedup 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dsh-agent-speedup 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dsh-agent-speedup 可以商用吗？

dsh-agent-speedup 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### dsh-agent-speedup 还在维护吗？

最新版本 0\.2\.5 发布于 2026/11/03（今天）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。