ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 工具目录怎么读:一个工具的 schema、准入条件与执行流水线

概念与架构发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin工具目录Tool Schema执行流水线
官方 tool-catalog 把模型可见工具名、插件包、依赖与写入影响放在一张表里。本文教你怎么从工具名反查包、读 schema 四段、判断别名与缺席原因,再用一条查表练习收尾。

工具目录不是「工具列表」,而是一张反查表:从模型看到的工具名,查回插件包、依赖、写入影响与别名。 官方 tool-catalog 的英文源由生成器在真实上下文中启动每个工具插件并读取 ctx.tools.schemas() 生成,中文版作为评审对侧维护(来源)。会用这张表,排查「模型为什么不用某个工具」会快很多。

DeepSeek Harness 目录范围:它列的是什么

目录列的是已发布插件提供的模型可见工具,不是所有函数。 官方范围是 packages/*/tool-* 下已发布的产品工具,每个工具按默认配置启动;examples/ 里的演示工具(例如 echo)不在范围内(来源)。

三个范围细节值得记住:

  1. 只列模型可见的 — 插件内部的辅助函数、服务方法不在目录里;
  2. 按默认配置启动 — 如果某个 Config 字段必填且没有默认值,生成器必须选择分支,并在包说明里记录;
  3. 名称可能是加载时配置 — 例如 tool-subagent 的 toolName,部署可以用不同名称或额外名称提供同一个包。

因此,目录是「产品默认形态」的快照,不是「你这台机器当前启用了什么」的实时列表。判断当前部署有没有某个工具,还要看 profile 与插件加载状态。

目录的完整性由 verify-tool-catalog 守卫:它会 glob 匹配 packages/*/tool-*,遗漏包会让检查失败。这意味着新工具不太可能悄悄缺席文档,但可能因为配置没启用而在你的部署里缺席。

DeepSeek Harness 工具包映射表怎么读

映射表把一行拆成六列:工具包、模型可见名称、依赖、写入影响、别名、部署说明。 这六列分别回答不同问题(来源):

列回答的问题排查用途
工具包它由哪个包提供定位源码与版本
模型可见名称模型看到的名字在提示词与日志里搜索
依赖它需要哪些 ctx 能力判断为什么没注册
写入影响它会写哪些事件或状态评估权限与副作用
别名是否有第二个名字解释「同一个工具两个名」
部署说明默认行为与限制判断配置是否需要改

读表时先看「依赖」列。一个工具没有出现,最常见的原因是某个依赖服务没有加载;例如 lsp 工具要求提供方,terminal 工具是选择启用的。依赖不满足时,工具可能根本不注册,而不是注册后报错。

再看「写入影响」列。它会告诉你工具是否产生 tool/call、tool/result、fs/*、job/* 等事件;这决定了它在权限、审计和回放里的位置。

最后看「部署说明」。同一工具在不同 profile 里可能有不同行为,例如 bash 在有 job 注册表时提供 run_in_background,没有注册表时 schema 不含该参数。

DeepSeek Harness 一个工具的 schema 四段

一个工具的 schema 至少看四段:name、description、parameters、output。 这四段分别决定「叫什么」「什么时候用」「怎么填」「返回什么」。(来源)

  • name — 模型调用时使用的标识;改名会影响提示词、日志与已有调用;
  • description — 模型判断何时使用的唯一线索;写得太泛,工具会被忽略;
  • parameters — JSON Schema 形状、必填项、枚举与默认值;模型据此填参数;
  • output — 返回值的规范形状与渲染方式;决定程序化调用与 UI 卡片。

排查「模型不用某个工具」时,先看 description,再看 parameters。description 没有说清使用场景,模型不会主动选;参数描述不清,模型会填错后放弃。

排查「工具调用了但结果不对」时,先看 output schema。返回值与 schema 不一致,注册表会判定失败;返回值是自然语言而不是规范 JSON,程序化调用就拿不到结构。

目录里的 schema 是默认配置下的形状。部署改了配置,schema 可能变化;例如桌面端与 Web 端的同名工具可能有不同参数。

DeepSeek Harness 别名与配置改名

同一个包可以有多个模型可见名称,目录会记录随产品发布的别名,但部署仍可改名。 官方明确说:注册的工具名称可以是加载时配置,例如 tool-subagent 的 toolName;如果存在随产品发布的别名,包的说明会记录(来源)。

这带来两个实用结论:

  1. 搜索工具时同时搜包名与别名 — 只搜一个名字,可能漏掉同一能力;
  2. 不要在插件里硬编码工具名 — 部署可能改名,硬编码会在换 profile 后失效。

别名不是重复注册,而是同一能力的不同入口。看到两个名字指向同一个包,先确认它们是否共享 schema;共享则只是别名,不共享则可能是两个不同工具。

如果模型调用了一个你没见过的工具名,先在目录里搜别名列,再搜包名。两步都找不到,才考虑是第三方插件自定义的工具。

DeepSeek Harness 工具缺席的三种原因

工具在目录里有记录,但在你的部署里不可用,通常只有三种原因。 按排查顺序(来源):

  1. 包没加载 — profile 或组合包没有挂载该工具包;看依赖图与启动配置;
  2. 配置关闭 — 工具是选择启用的,例如 terminal 的六个工具;看部署说明;
  3. 运行时依赖缺失 — 例如 lsp 没有提供方、图片工具没有 attachments;工具可能不注册或返回结构化错误。

三种原因的区分方法不同:第一种看包在不在,第二种看配置项,第三种看运行时能力。不要用一个方法套三种。

还有一种「看起来缺席」:工具名被配置改了。它不是缺席,而是换了名字;在目录里查别名与部署说明即可确认。

排查时先记录「目录里有、当前没有」这个事实,再按三种原因逐一排除。不要在日志里盲搜工具名,先确认它是否真的加载。

DeepSeek Harness 查表练习:从一个工具名反查

拿一个真实工具名走一遍,比读十遍目录说明有用。 以 glob 为例(来源):

  1. 搜名称列 — 找到 glob,同一行还有 grep;
  2. 看工具包 — 它来自 @deepseek-ai/dsh-tool-fs-search;
  3. 看依赖 — 依赖 ctx.subprocess,通过随包 ripgrep 运行,不经过 shell;
  4. 看写入影响 — 产生 tool/call 与 tool/result,没有额外持久事件;
  5. 看部署说明 — 超过上限时可通过 ctx.spillStore 保存完整列表,共置部署可用定位信息读取。

五步走完,你就知道它为什么不需要宿主机安装 rg、为什么没有 run_in_background、以及结果超限时去哪找完整列表。这比在日志里猜「为什么 grep 不走 shell」快得多。

旧文 dsh-tool-pipeline-explained 讲执行流水线,develop-tool-execute-contract 讲写工具的契约;本篇补的是官方目录的查表方法。目录、流水线、契约三件套一起用,工具问题就不再靠猜。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的 tool-catalog 列的是所有工具,还是只列默认启用的工具?

DeepSeek Harness 的 tool-catalog 列的是已发布插件向 ctx.tools 提供的面向模型的工具,每个工具按默认配置启动;必填且无默认值的配置会记录生成器选择的分支。

DeepSeek Harness 的工具名为什么有时和包名对不上?

DeepSeek Harness 的工具名可以是加载时配置,例如 subagent 的 toolName 可被部署改名;目录会记录随产品发布的别名,但部署仍可能使用不同名称或额外名称。

DeepSeek Harness 的 glob 和 grep 是走 shell 吗?

DeepSeek Harness 里不是这样。DeepSeek Harness 的 glob 与 grep 通过 ctx.subprocess 调用随包提供的 ripgrep 二进制,作为普通前台调用运行,不经过 shell 层,也不要求宿主机安装 rg。

DeepSeek Harness 的 lsp 工具在什么情况下会报错?

DeepSeek Harness 的 lsp 工具要求已注册提供方;没有提供方时查询会返回结构化的 LSP_UNAVAILABLE 错误,而不是改变工具 schema 或静默失败。

相关术语

工具目录
工具目录是 DeepSeek Harness 官方生成的工具清单,列出模型可见名称、所属插件包、依赖、写入影响与别名。— DeepSeek Harness 官方文档 - 工具 Schema 目录
工具包映射
工具包映射是工具目录里的对照表,把模型可见工具名映射到背后的插件包与服务 seam。— DeepSeek Harness 官方文档 - 工具 Schema 目录
工具别名
工具别名是同一插件包随产品发布的另一个模型可见名称,部署也可能通过配置提供不同名称或额外名称。— DeepSeek Harness 官方文档 - 工具 Schema 目录
工具缺席
工具缺席是指某个工具在目录里有记录,但当前部署的选择器中不存在,通常由未加载包、配置关闭或运行时依赖缺失导致。— DeepSeek Harness 官方文档 - 工具 Schema 目录

来源