ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 ToolRestriction:条件准入与执行 waterfall

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessToolRestriction条件准入工具注册表
插件想让某类工具只在特定步骤可见,结果注册了却一直不出现,或出现后拦不住。本文讲 ToolDefinition 哪些字段会进模型请求、ToolRestriction 只过滤继承内容、when 条件准入与 ResolvedToolSet 的生命周期。

“工具注册了却看不见”和“工具看得见却拦不住”,在 DSH plugin 里是两个不同机制的问题。 前者通常是 ToolRestriction 或 when 在过滤,后者往往是你改错了层:真正决定分派的是步骤的准入集合,不是注册表里的存在性。 DSH插件 与 DeepSeek插件 的工具体系共用一份准入规则,restriction 和 when 各管一段。

ToolDefinition 里哪些字段能进模型请求

只有三个字段会被投影给模型,其余全部留在宿主侧。(来源)

ToolDefinition 由一个面向模型的 ToolSchema、必需的规范输出声明、execute 函数、仅供宿主使用的调度器元数据、可选的最终内容回调与可选 UI 展示函数组成。注册表持有这些定义,循环通过它们分派调用。

注册表的 schemas() 通过显式允许列表构建 ToolSchema[]。官方点名的不能泄漏字段是:output、execute、projectContent、finalizeContent、timeoutMs、isConcurrencySafe、presentCall 与 presentResult。

这条白名单解释了为什么 timeoutMs 这类“看着像参数”的字段不该出现在工具描述里。声明它实际上是断言:本工具会把 exec.signal 转发给一个能在信号中止时到达静止的协作式实现。它的执行约束由 @deepseek-ai/dsh-tool-call-timeout-policy 施加,是 tools/execute 的包装层,不是协议字段。

isConcurrencySafe 同理:它是纯同步分类器,只有返回 true 才算加入并行组;省略、抛错、返回非 true 都按独占处理。选中并发的执行不得修改父级拥有的状态。

两个内容回调的时机不同,别混着用。projectContent 在 tools/post-execute 策略之前安装执行准备后的内容,回调在调用开始时捕获,只对进入 post-execute 的规范化结果运行一次,策略替换仍是权威;finalizeContent 是面向模型内容的同步最后一道变换,执行器在每个规范化结果上恰好调用一次,包括绕过 post-execute 的流水线失败,且必须全函数、不得抛错。

展示回调则是纯函数:presentCall 与 presentResult 可能在实时流式与日志回放两种场景被调用,因此只能依赖入参与持久结果投影,不能读外部可变状态。

必填的 output 与被拒绝的原始 schema

output 是必填契约,render 才是模型看到的内容来源。(来源)

ToolOutputDefinition 包含三部分:schema、render 与可选 presentationMeta。schema 是原始受支持 JSON Schema,强制校验每个成功的规范值;render 是纯投影,从已校验参数与值生成 native 或模型内容;presentationMeta 是可回放的展示投影。

插件作者用同一套 DSL 描述参数与输出。ValueSchemaSpec 支持 string、number、integer、boolean、null、array、object、仅作者侧可用的 json,以及要求恰好命中一个分支的 oneOf。两条硬规则:显式对象节点必须声明 additionalProperties: true | false;{ type: 'json' } 编译成仅含注解、不施加约束的原始 schema。

InferValue<S> 在 16 层容器内保留字面量约束与对象开放性,之后回退为 JsonValue,避免耗尽 TypeScript 的类型实例化栈;运行时校验仍会遍历完整 schema。参数不匹配抛 ToolArgsError(INVALID_ARGS),函数体或后置策略产生无效值抛 ToolOutputError(INVALID_TOOL_OUTPUT),两者都走常规工具错误路径。

注册本身是一项受信任的同进程约定:注册表以 readonly 输入借用定义,要求声明 output,校验原始 schema,并检查 timeoutMs 必须为正有限值等语义要求。不支持的关键字会被拒绝,而不是在未强制执行的情况下获准进入。

ToolRestriction 只过滤继承内容

它管的是“从上层继承来的工具”,不管你自己注册的。(来源)

ToolRestriction 作用于该作用域继承来的工具:部署全局层,加上其链上的每个祖先作用域。注册表把 readonly 名称编译为私有集合,对多个限制取交集,再叠加该作用域自身的注册——后者不受约束,因此被委派的子 agent 会保留其回报所依赖的工具。

两种过滤语义差别很大:

  • 仅 deny — 允许后续未列出的继承工具通过;
  • allow 列表 — 排除未列出的继承工具。

还有两个边界:它不影响作用域自有注册,也不影响保留的 PTC 模式传输。如果你发现“限制写了但工具还在”,先确认那个工具是不是本作用域注册的;如果是,restriction 按定义管不到它。

条件准入:when 决定这一步能不能用

when 不是可见性开关,它是步骤级准入判定。(来源)

注册可以携带 when 条件。AgentLoop 为每个拟议步骤、以捕获的模型选择调用一次 ctx.tools.resolve();返回的集合决定三件事:该步骤的工具声明、执行器分区,以及批次中的每次调用,包括 PTC 程序的子调用。

执行时 ctx.tools.executable() 应用这个集合;没有集合时排除条件注册。同名替换或新的限制会阻止尚未开始的调用使用已准入的注册,步骤批次结束后循环释放集合。

resolve() 是按步骤调用一次,不是按每次工具调用。所以把昂贵判断放进 when 会拖慢步骤准备,需要复用的结果应该在插件激活期准备好。

ToolActivationContext 只有三项:agent、modelSelection 与 signal。三条写作纪律:

  1. 省略 when 即启用;
  2. 返回 false 会同时从声明与分派中排除,不是只藏起来;
  3. 条件不得修改注册、不得启动工具工作,异步条件必须观察 signal;条件拒绝会让步骤准备失败。

第 3 条最容易被忽视。在 when 里发起一次网络请求或写一个文件,会把“准备步骤”变成副作用阶段,出错时表现为步骤准备失败,而不是工具失败。

ResolvedToolSet:一次步骤的准入快照

准入集合有明确生命周期,过期后不能复用。(来源)

ResolvedToolSet 只有两个方法:dispose() 在步骤的工具批次落定后关闭准入;view(scope) 读取在原作用域里仍然可见的准入注册。

view 的 scope 参数语义很硬:传入确切的请求方 agent,另一个 scope 永远不会被准入;返回的是原始定义,但会排除已被移除或受限的注册。也就是说它给的是“当前这一刻真实可用的集合”,不是注册表全量。

这套机制让同名覆盖与限制变更变成可解释的:resolve 一次快照,执行期只认这份快照,批次结束后释放。你如果在批次中途替换了定义,尚未开始的调用会看到新限制,而不是继续用旧准入。

验证:同一工具在不同步骤下的可见性

验证要分三层:声明里在不在、分派时能不能调、换限制后是否立刻失效。(来源) 六步:

  1. 注册一个带 when 的工具,让条件返回 false,断言 schemas() 里没有它,且调用被拒。
  2. 让条件返回 true,断言它出现在该步骤的声明里,且批次可以调用。
  3. 在同一作用域注册同名工具,断言自有注册不受 ToolRestriction 影响。
  4. 给父作用域加 deny,断言子作用域的 view(scope) 看不到该工具;把 deny 去掉,断言恢复。
  5. 在批次中途替换同名定义,断言未开始的调用按新限制处理。
  6. 让 when 抛错,断言步骤准备失败,而不是产生一个空工具集继续跑。

如果第 1 步工具仍然出现,先检查是不是另一个作用域注册了同名工具——when 只对它所属的那条注册生效。

工具执行流水线的完整阶段,可以对照工具执行契约;写一个带 schema 的工具见工具插件。

一句话收束: 只有三个字段进模型请求,output 是必填契约,restriction 只管继承、when 只管本步骤,准入集合按批次释放。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 timeoutMs 会发给模型吗?

不会,DSH plugin 的 schemas() 只白名单 name、description 与 parameters。DSH plugin 明确说明 output、execute、timeoutMs、isConcurrencySafe 等字段绝不能泄漏到模型请求中。

DSH plugin 的 ToolRestriction 能限制本作用域自己注册的工具吗?

不能,DSH plugin 的 restriction 只作用于继承内容。DSH plugin 的注册表先对继承工具取限制交集,再叠加该作用域自身的注册,后者不受约束。

DSH plugin 的 when 返回 false 会发生什么?

DSH plugin 会把该工具从声明与分派中一起排除。DSH plugin 的 when 省略即启用,返回 false 则该步骤既看不到也调不到;如果条件本身抛出,步骤准备直接失败。

DSH plugin 中途做同名替换,会影响已经开始的工具调用吗?

DSH plugin 保护的是尚未开始的调用。DSH plugin 的同名替换或新的限制会阻止未开始的调用继续使用已准入的注册,步骤批次结束后循环释放准入集合。

相关术语

ToolDefinition
ToolDefinition 是一个已注册工具,包含面向模型的 ToolSchema、必填 output、execute 函数与宿主专用元数据。— packages/core/tools/src/index.ts
ToolRestriction
ToolRestriction 是单作用域对继承工具的实时过滤器,只有 allow 与 deny 两个可选名称列表。— packages/core/tools/src/index.ts
ToolActivationContext
ToolActivationContext 是 when 条件的输入,含准备步骤的 agent、捕获的模型选择与取消信号。— packages/core/tools/src/index.ts
ResolvedToolSet
ResolvedToolSet 是一个步骤准入后的注册集合,提供 view 读取与 dispose 关闭准入。— packages/core/tools/src/index.ts

来源