@deepseek-ai/dsh-lazy-tools

Readme

<div align="center">

# dsh-lazy-tools

**为 DeepSeek Harness 提供的 CodeBuddy 风格延迟工具加载插件。**

一个 `tool_search` + `defer_execute_tool` 覆盖层，让工具 schema 在真正需要之前
不会进入模型上下文。

*减少 token 消耗 · 缩小上下文窗口 · 保持工具可发现*

[English](README.en.md)

</div>

---

## 它是做什么的

大多数编码 Agent 会把**每一个**可用工具的 JSON Schema 都塞进提示词——
包括模型最终根本不会用到的工具。`dsh-lazy-tools` 颠覆了这个模型：工具
默认被**延迟（deferred）**，只有当模型主动请求时才进入上下文。

被延迟的工具会从模型可见的工具集中剔除，因此它们的 schema（乃至名字）
永远不会进入模型上下文。模型通过 `tool_search` 按需发现它们，激活后
即可直接调用。

这是一个**纯粹的暴露控制层**：

- 它**不拥有、也不实现**任何工具。
- 被延迟的工具是全局注册表里的工具（包括 MCP 等第三方工具）；本插件只持有
  它们的 `name` / `description` / `parameters` 用于发现。
- 它**不代理执行**——`tool_search` / `defer_execute_tool` 只负责*激活*，激活后
  模型直接调用该工具本身。

因为完全实现在 agent 层，它**适用于任何模型与任何提供商**（DeepSeek、
OpenAI、Anthropic、Gemini……），不依赖提供商原生的延迟工具协议（如
Anthropic `tool_reference` 或 OpenAI 的 deferred-tool input items）。

## 特性

- 🔍 **按需发现** — `tool_search` 通过精确工具名（`tool_names`）或关键词
  （`queries`，中英文均可）查找工具，命中即激活。
- ⚡ **懒激活** — 命中的工具加入该 agent 的可见集合，下一轮模型请求即可
  直接调用。
- ⚡ **按名激活** — `defer_execute_tool` 按精确工具名直接激活一个已知工具。
- 🧭 **无侵入** — 在 `agent.ctx` 上通过 `ctx.tools.restrict()` 过滤可见工具，
  与父/子代理的既有限制天然取交集，绝不放宽其他策略。
- 🎛️ **灵活配置** — CodeBuddy 风格 `Defer(...)` / `NoDefer(...)` 模式，支持 `*`
  通配符与全局 `deferToolLoading` 开关。
- 🛡️ **自保守卫** — `tool_search` 与 `defer_execute_tool` 注册在 agent 自身作用域，
  永不被延迟，`Defer(*)` 无法把系统锁死。

## 安装

从 GitHub 仓库安装为外部 bundle：

```bash
dsh plugin --profile <profile> add git:github.com/studyzy/dsh-lazy-tools
```

> 也可以先 `git clone` 到本地，再从本地目录安装。该 bundle 通过
> `cordis.patch.yml` 注入一个名为 `lazy-tools` 的插件。

## 配置

配置写在 profile 的 `cordis.yml` 中该插件的 `config` 字段下，使用 CodeBuddy
风格语法：

```yaml
- id: lazy-tools
  name: '@deepseek-ai/dsh-lazy-tools'
  config:
    defer: ['glob', 'web_search', 'Defer(fetch_*)']
    noDefer: ['bash']
    deferToolLoading: true
```

| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `defer` | `string[]` | `[]` | 要延迟的工具名或 `Defer(pattern)` 条目。裸名等价于 `Defer(name)`。`*` 是唯一通配符——`Defer(*)` 延迟除守卫工具外的所有工具。 |
| `noDefer` | `string[]` | `[]` | 必须保持可直接调用的工具名或 `NoDefer(pattern)` 条目。裸名等价于 `NoDefer(name)`。**始终优先于 `defer`。** |
| `deferToolLoading` | `boolean` | `true` | 全局开关。为 `false` 时不延迟任何工具。 |

修饰符大小写不敏感（`defer(bash)` ≡ `Defer(bash)`）。优先级（从高到低）：
`noDefer` > `defer` > `deferToolLoading`。

### 示例

```yaml
# 延迟所有 fetch_* / web_* 工具，始终保持 bash 可用
config:
  defer: ['Defer(fetch_*)', 'Defer(web_*)']
  noDefer: ['bash']
```

```yaml
# 延迟除守卫工具对（tool_search / defer_execute_tool）之外的一切
config:
  defer: ['Defer(*)']
```

```yaml
# 按前缀延迟 MCP 网关工具
config:
  defer: ['mcp*']
```

## 工作原理

| 组件 | 作用 |
|---|---|
| `tool_search` | 搜索当前不可见的工具。`tool_names` 精确查找，`queries` 关键词查找（中英文）。命中即把工具加入可见集合并返回匹配结果。 |
| `defer_execute_tool` | 按精确工具名激活一个延迟工具，使模型可直接调用。适合激活已知名字的工具。 |
| 拦截 | `tools/pre-execute` 监听器会在模型直接调用未加载的延迟工具时返回 `deny`，提示先调用 `tool_search` 或 `defer_execute_tool`。 |
| 激活 | 命中的工具写入该 agent 的 `restrict({ allow })` 集合，从下一轮模型请求开始对模型可见、可直接调用。 |

### 流程

```
Prompt: 只有 tool_search + defer_execute_tool 的 schema 可见
   │
   ▼
model: tool_search({ tool_names: ["glob"] })
   │  └─ 返回 glob 的匹配状态，并把它加入该 agent 的可见集合
   ▼
下一轮: model 直接调用 glob（完整 schema 已进入工具列表）
```

## 设计约束与已知限制

- **激活后下一轮生效。** `tool_search` 激活工具后，*当前*模型请求的工具列表
  已经固定（schema 在下一轮请求头才更新），因此同一轮内直接调用仍会被
  `tools/pre-execute` 拦截。请在结果返回后、下一轮再调用。
- **延迟工具在搜索前不可见。** 模型看不到延迟工具的名字，只能依赖
  `tool_search` 的检索来发现它们。
- **与其他限制取交集。** 插件只挂自己的 `allow` 子集，绝不放宽其他 `restrict`
  （如父/子代理策略）。被其他策略拒绝的工具即使被搜索命中也会标记为
  `unavailable`。
- **状态不跨会话持久化。** 已加载的工具集仅在当前进程内生效；resume / fork
  后新 agent 会重新按配置延迟。这是为了避免外部插件写入未在
  `KNOWN_SESSION_EVENT_TYPES` 注册的自定义会话事件。
- **仅全局工具。** 已注册在 agent 自身作用域的工具始终可见，不在延迟目录内。

## 开发

```bash
pnpm install
pnpm run typecheck   # TypeScript 类型检查
pnpm test            # vitest 单元 + 集成测试
pnpm run lint        # oxlint
pnpm run build       # tsc + tsdown 打包到 lib/
```

## License

本项目以 MIT 许可证发布。