DeepSeek Harness 工具怎么注册？DSH plugin 的 ToolDefinition 与执行流水线

DeepSeek Harness 里一个已注册工具就是一份 ToolDefinition：一份 schema 加一个执行函数，其中 output 声明是必填的；参数与输出用同一套 JSON 值 schema 描述（来源）。 工具是模型与外界之间的桥：模型自己不能读写文件、不能访问网络，它只能「请求调用工具」，真正干活的是注册进系统的那份执行函数。这篇讲工具怎么注册、怎么被模型看见、怎么跑；内置工具清单见《DeepSeek Harness 内置工具有哪些》，自己写一个工具见《怎么开发一个工具插件》，工具在链路里的位置见《DeepSeek Harness 一轮对话怎么跑》。

为什么工具是模型与外界之间的桥

模型只能生成文本，它无法直接触碰文件系统、网络或任何外部资源——所有对外动作都必须经由工具完成，这也是工具机制存在的根本原因（来源）。 这条边界一旦想清楚，几件事就顺了：

1. 工具决定「能做什么」：模型能读到多少能力说明，取决于有哪些工具被注册进当前环境；没注册的能力，模型连「想」都无从想起。
2. 工具是权限的落点：因为真正的执行发生在工具里，所以「某个动作会不会动你的文件」要看工具本身与它受到的约束，而不是看模型说了什么。
3. 工具是插件能力的主要出口：一个 DSH plugin 想让模型获得新本事，最常见的方式就是注册一个工具；这也是「一切皆插件」最直观的体现。

所以理解工具机制，等于理解「模型能做多少事、这些事由谁执行、又受什么限制」这三个问题的答案。

一个工具是什么：schema 加执行函数

DeepSeek Harness 里一个已注册的工具就是一份 ToolDefinition——一份 schema 加一个执行函数，output 声明为必填，执行函数只在被接受的调用上运行并返回规范值（来源）。 三个要点：

1. schema 定义边界：描述工具接受哪些参数、返回什么，是模型能看到的那部分；模型据此判断「该用哪个工具、要传什么」。
2. output 必填：返回值必须有明确的规范声明，执行结果据此校验，模型拿到的内容因此是可预期的。
3. 执行函数负责干活：拿到已冻结的参数快照后运行，返回符合 output 声明的值；它不与模型直接对话，只按约定收参数、给结果。

注册是一项同进程内的受信约定：注册表校验 schema 与语义要求，再让执行与展示共享同一份已解析定义。自己写工具的做法见《怎么开发一个工具插件》。

参数与输出共用一套 schema

DeepSeek Harness 用同一套 JSON 值 schema DSL 描述工具的参数和输出，作者用一套词汇声明类型，编译时再转成受支持的原始 JSON Schema 子集（来源）。 这样设计的好处：

1. 声明一致：参数与输出不做两套词汇，减少两头写法不一致带来的问题。
2. 支持常见类型：string、number、integer、boolean、null、array、object，以及要求恰好命中一个分支的 oneOf；覆盖了绝大多数工具的形状。
3. 默认开放、受控收紧：原始 JSON Schema 默认保持开放，不支持的关键字会被拒绝，而不是放进来却不强制执行——宁可提前报错，也不留下「声明了却没生效」的隐患。
4. 作者侧类型推导：因为是一套受控词汇，写声明时配合工具作者侧的类型推导，能更早发现参数与输出的写法问题。

工具是怎么被模型看见的：schema 投影进提示词

模型之所以「知道」有哪些工具，是因为工具的 schema 被投影进了每轮的系统提示词前缀——模型读到的工具说明，正是从注册表投影出来的那一份（来源）。 这条连线解释了三个现象：

1. 注册即可见：工具一旦注册成功，其 schema 就参与前缀组装，模型在后续轮次里便能看到它。
2. 工具越多，前缀越长：每多一个工具，就多一段说明要写进前缀，这也是上下文开销的一个主要来源；相关机制见《DeepSeek Harness 系统提示词怎么来的》。
3. 改了 schema 就改了模型的行为依据：调整参数说明或描述，会直接影响模型「什么时候用、怎么用」这个工具，而不只是文档意义上的变化。

执行流水线：waterfall 让执行可环绕

工具执行走一条可扩展的 waterfall 事件流水线并施加单调策略，各环节按瀑布式语义依次处理（来源）。 为什么用 waterfall、而不是直接调函数：

1. 执行可环绕：在真正的执行函数前后都留有环节，插件可以在不改工具本身的前提下介入，比如包装执行、记录、施加额外约束。
2. 单调策略保证不放松：流水线上施加的策略按单调方向收紧——下游环节可以加限制，但不会把上游已定的约束撤销，因此约束只会越来越严，不会互相抵消。
3. ctx.tools 是服务入口：注册、schema 投影与分派执行都通过这个入口暴露，DSH plugin 借此参与工具生命周期，而不是去改内核。

作用域过滤：ToolRestriction 怎么收窄可见范围

在 DeepSeek Harness 里，ToolRestriction 是某个作用域对其继承来的工具施加的实时过滤器：它按名称收窄当前作用域可见的工具集合，多个限制取交集，而该作用域自身的注册不受影响（来源）。 三点值得记住：

1. 只作用于继承来的工具：它筛的是「从上层继承下来的可见集合」，不惩罚自己在当前作用域里注册的工具。
2. 多个限制取交集：叠加的限制只会让范围更窄，不会互相放宽，与流水线的单调策略是同一个思路。
3. 子作用域因此各有视野：被委派的子 agent 可以在更窄的工具集里工作，同时仍保留它回报结果所依赖的那些工具——这正是限制「自身注册不受约束」的意义。

理解工具流水线的注意事项

把工具当成「schema + 执行函数 + 环绕流水线」三件事，就不容易混。

1. 模型只看到 schema：说明与参数是模型可见的部分，执行细节不暴露给协议。
2. output 不能省：返回值必须规范声明，否则结果无从校验。
3. 注册是一种受信约定：同进程内的注册表会校验 schema 与语义要求，别指望系统替你兜住不合规的定义。
4. 执行可被环绕：waterfall 设计上留出了介入点，方便插件协作，也意味着约束可被下游收紧。
5. 可见范围可按作用域收窄：ToolRestriction 决定某作用域能看到哪些继承工具，多个限制取交集。
6. 工具越多前缀越长：注册工具同时增加能力与上下文开销，两者要一起权衡。
7. 内置清单看实操文：有哪些现成工具见《DeepSeek Harness 内置工具有哪些》；工具在链路中的位置见《DeepSeek Harness 一轮对话怎么跑》。

来源：DeepSeek Harness 官方文档 - 工具子系统、官方文档 - 核心子系统。