DeepSeek Harness 工具目录怎么读:一个工具的 schema、准入条件与执行流水线
工具目录不是「工具列表」,而是一张反查表:从模型看到的工具名,查回插件包、依赖、写入影响与别名。 官方 tool-catalog 的英文源由生成器在真实上下文中启动每个工具插件并读取 ctx.tools.schemas() 生成,中文版作为评审对侧维护(来源)。会用这张表,排查「模型为什么不用某个工具」会快很多。
DeepSeek Harness 目录范围:它列的是什么
目录列的是已发布插件提供的模型可见工具,不是所有函数。 官方范围是 packages/*/tool-* 下已发布的产品工具,每个工具按默认配置启动;examples/ 里的演示工具(例如 echo)不在范围内(来源)。
三个范围细节值得记住:
- 只列模型可见的 — 插件内部的辅助函数、服务方法不在目录里;
- 按默认配置启动 — 如果某个 Config 字段必填且没有默认值,生成器必须选择分支,并在包说明里记录;
- 名称可能是加载时配置 — 例如
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;如果存在随产品发布的别名,包的说明会记录(来源)。
这带来两个实用结论:
- 搜索工具时同时搜包名与别名 — 只搜一个名字,可能漏掉同一能力;
- 不要在插件里硬编码工具名 — 部署可能改名,硬编码会在换 profile 后失效。
别名不是重复注册,而是同一能力的不同入口。看到两个名字指向同一个包,先确认它们是否共享 schema;共享则只是别名,不共享则可能是两个不同工具。
如果模型调用了一个你没见过的工具名,先在目录里搜别名列,再搜包名。两步都找不到,才考虑是第三方插件自定义的工具。
DeepSeek Harness 工具缺席的三种原因
工具在目录里有记录,但在你的部署里不可用,通常只有三种原因。 按排查顺序(来源):
- 包没加载 — profile 或组合包没有挂载该工具包;看依赖图与启动配置;
- 配置关闭 — 工具是选择启用的,例如 terminal 的六个工具;看部署说明;
- 运行时依赖缺失 — 例如 lsp 没有提供方、图片工具没有 attachments;工具可能不注册或返回结构化错误。
三种原因的区分方法不同:第一种看包在不在,第二种看配置项,第三种看运行时能力。不要用一个方法套三种。
还有一种「看起来缺席」:工具名被配置改了。它不是缺席,而是换了名字;在目录里查别名与部署说明即可确认。
排查时先记录「目录里有、当前没有」这个事实,再按三种原因逐一排除。不要在日志里盲搜工具名,先确认它是否真的加载。
DeepSeek Harness 查表练习:从一个工具名反查
拿一个真实工具名走一遍,比读十遍目录说明有用。 以 glob 为例(来源):
- 搜名称列 — 找到
glob,同一行还有grep; - 看工具包 — 它来自
@deepseek-ai/dsh-tool-fs-search; - 看依赖 — 依赖
ctx.subprocess,通过随包 ripgrep 运行,不经过 shell; - 看写入影响 — 产生
tool/call与tool/result,没有额外持久事件; - 看部署说明 — 超过上限时可通过
ctx.spillStore保存完整列表,共置部署可用定位信息读取。
五步走完,你就知道它为什么不需要宿主机安装 rg、为什么没有 run_in_background、以及结果超限时去哪找完整列表。这比在日志里猜「为什么 grep 不走 shell」快得多。
旧文 dsh-tool-pipeline-explained 讲执行流水线,develop-tool-execute-contract 讲写工具的契约;本篇补的是官方目录的查表方法。目录、流水线、契约三件套一起用,工具问题就不再靠猜。
常见问题
DeepSeek Harness 的 tool-catalog 列的是已发布插件向 ctx.tools 提供的面向模型的工具,每个工具按默认配置启动;必填且无默认值的配置会记录生成器选择的分支。
DeepSeek Harness 的工具名可以是加载时配置,例如 subagent 的 toolName 可被部署改名;目录会记录随产品发布的别名,但部署仍可能使用不同名称或额外名称。
DeepSeek Harness 里不是这样。DeepSeek Harness 的 glob 与 grep 通过 ctx.subprocess 调用随包提供的 ripgrep 二进制,作为普通前台调用运行,不经过 shell 层,也不要求宿主机安装 rg。
DeepSeek Harness 的 lsp 工具要求已注册提供方;没有提供方时查询会返回结构化的 LSP_UNAVAILABLE 错误,而不是改变工具 schema 或静默失败。
相关术语
- 工具目录
- 工具目录是 DeepSeek Harness 官方生成的工具清单,列出模型可见名称、所属插件包、依赖、写入影响与别名。— DeepSeek Harness 官方文档 - 工具 Schema 目录
- 工具包映射
- 工具包映射是工具目录里的对照表,把模型可见工具名映射到背后的插件包与服务 seam。— DeepSeek Harness 官方文档 - 工具 Schema 目录
- 工具别名
- 工具别名是同一插件包随产品发布的另一个模型可见名称,部署也可能通过配置提供不同名称或额外名称。— DeepSeek Harness 官方文档 - 工具 Schema 目录
- 工具缺席
- 工具缺席是指某个工具在目录里有记录,但当前部署的选择器中不存在,通常由未加载包、配置关闭或运行时依赖缺失导致。— DeepSeek Harness 官方文档 - 工具 Schema 目录
来源
- DeepSeek Harness 官方文档 - 工具 Schema 目录· deepseek-harness
- DeepSeek Harness 官方文档 - Tool 执行· deepseek-harness