ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 照 Cookbook 加工具:schema、注册、准入与三步验证

插件开发发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin自定义工具defineToolCookbook
官方 Cookbook 给的是最小形态,真正跑完还要验证 schema 进了提示词、模型能调用、结果能渲染。本文按官方顺序走一遍加工具的全过程,并补上三条验收和五个策略扩展点。

官方 Cookbook 给的是一段能跑的最小形态,但「能跑」和「模型真的看见并能用」是两件事。 这篇按官方顺序把加工具走一遍,再把 Cookbook 没展开的三步验收和五个策略扩展点补上。现有 develop-tool-plugin 与 develop-tool-execute-contract 讲的是契约细节,这里讲的是照做之后怎么确认没做错。

DeepSeek Harness 最小工具:从 defineTool 到注册

一个工具最少需要四样东西:名字、给模型看的描述、参数 schema、返回值 schema。 官方最小形态如下(来源):

ts
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',
    parameters: {
      path: { type: 'string', required: true },
      limit: { type: 'number' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

这段代码里,inject 声明依赖 ctx.tools,apply 里注册,注册本身是副作用。插件卸载时,注册会随 fiber 一起撤销,不需要你手写反注册。

最小形态只保证「声明完整」,不保证「模型会用」。名字要像模型能理解的动作,描述要说清什么时候用,参数要能让模型填对。三者缺一个,工具就可能被模型忽略。

DeepSeek Harness execute 的四条规则

execute 不是普通函数,它受注册表的四条约束。 官方把规则写得很清楚,照做能避免大部分「工具能注册但不工作」的问题(来源):

  1. 参数已被校验 — defineTool 会在 execute 前校验模型生成的 arguments;你只需补 schema 表达不了的约束,例如非空字符串、正数、跨字段规则,并用 ToolArgsError 拒绝。
  2. 注册借用只读定义 — 注册后不要改 schema 或替换回调;要热替换工具,先 dispose 旧副作用,再注册替代品。
  3. 返回规范 JSON 值 — 返回 output.schema 声明的值,不要返回内容块或自然语言;注册表会快照、校验、冻结,再交给 output.render。
  4. 遵守 exec.signal — 取消时让 signal 的 reason 或 AbortError 直接传播,注册表会记录为 TOOL_ABORTED,不要替换成普通 Error。

这四条的共同点是「把工具当成流水线中的一段」,而不是一个孤立函数。参数、身份、返回值、取消都有明确归属,越界就会在某个环节失败。

还有两个可选但很有用的点:抛出带稳定 code 的 HarnessError 子类,能让失败结果保留错误名与错误码;presentationMeta 可以从同一个规范值派生可回放的卡片数据,避免为了渲染再持久化一份结果。

DeepSeek Harness 长时间运行:什么时候交给 ctx.jobs

工具要不要后台化,看它是否需要跨过当前调用返回。 官方建议通过 producer 配置控制 run_in_background,然后用 ctx.jobs.start({ kind, label, owner, run }) 注册后台任务(来源)。

判断标准可以简化成三条:

  • 几秒内能完成 — 直接在前台 execute 里做完,返回结果;
  • 分钟级但需要结果 — 仍然前台,但要遵守 exec.signal,让取消能生效;
  • 需要跨轮次或可被用户随时查看 — 交给 ctx.jobs,返回任务句柄,让 job_* 工具管理。

后台化以后,取消语义会变:ctx.jobs.start() 发布 id 后,应使用任务自有的取消信号,而不是 exec.signal。之后取消外层调用只会停止等待,不会终止已经发布的工作;生命周期归 job_kill、owner dispose 和 teardown 所有。

这条边界如果搞错,表现是「用户点了取消,任务还在跑」或「任务已经返回,后台还在写」。前者是把外层信号当成了任务信号,后者是没有把后台句柄交出去。

DeepSeek Harness 策略与观测:五个扩展点

不要在工具里内建部署策略,交给流水线的扩展点。 官方列出五个位置,各自职责不同(来源):

扩展点适合做什么不要拿它做什么
tools/pre-execute允许/拒绝/询问的可扩展策略写业务逻辑
ctx.tools.guard()最终的单调拒绝做可撤销的临时判断
tools/execute截止时间、重试、指标改工具返回值
tools/post-execute替换展示、阻止结果、附加上下文绕过程序化访问
tools/result观测不可变结果修改结果

这五个点的顺序是固定的:pre-execute 在分发前,guard 是最后的拒绝,execute 包住分发,post-execute 可以改展示,result 只观测。把策略放错位置,最常见的结果是「策略看起来生效了,但程序化调用绕过了它」。

一个经验:工具本体只做「这件事怎么做」,策略与观测放在插件层。这样同一个工具可以在不同部署里配不同的权限和指标,而不需要改工具代码。

DeepSeek Harness UI 卡片与 PTC 的两个额外检查

工具能返回结果,不等于 UI 和 PTC 都能正确使用它。 官方把 UI 卡片和 PTC 都列为独立关注点(来源):

  • UI 卡片 — output.render 只决定模型看到什么;UI 卡片由 presentCall / presentResult 声明。没有展示方法的工具会回退到通用卡片,标题是工具名、输入是原始 args。
  • PTC 模式 — 每个可见工具都会变成 await tools.<name>(args) 可调用的能力;output.schema 实际上也是程序化 API 的返回类型,所以不要把句柄藏在自然语言里。

这两项检查经常被忽略,因为它们在「模型能调用」之后才暴露。工具返回一段人类可读的文本,模型可能满意,但 UI 渲染成原始 JSON,或者 PTC 程序拿不到结构化的 id。

写工具时最好同时想三件事:模型看到什么、用户看到什么、程序拿到什么。三者可以不同,但都要有明确设计,而不是让默认行为兜底。

DeepSeek Harness 三步验证:跑完怎么验

加完工具,按三步验证,不要只看「没有报错」。 推荐顺序如下(来源):

  1. schema 进提示词 — 确认工具的 name、description、parameters 出现在模型可见的工具清单里;没有出现,先查 inject 与注册是否执行。
  2. 模型能调用 — 用一个明确需要该工具的任务触发调用;模型不调用,优先改 description 与参数描述,而不是怀疑注册。
  3. 结果能渲染 — 检查 output.render 的输出是否可读,UI 卡片是否回退到通用卡片,PTC 是否能拿到规范值。

三步都过,工具才算真的可用。只过第一步,是「注册成功但模型不用」;只过前两步,是「模型用了但用户看不懂」;三步都过,才进入调优。

最后对照旧文:develop-tool-plugin 讲插件里怎么组织工具,develop-tool-execute-contract 讲 execute 的契约细节;本篇补的是官方 Cookbook 的走查与验收。三者一起看,才不会把「能注册」误当成「能工作」。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 加一个自定义工具,最少要写哪几部分?

DeepSeek Harness 里,最少要写三部分:用 defineTool 声明 name、description、parameters 与 output,在 apply 里调用 ctx.tools.register 注册,并声明 inject 依赖。注册是副作用,插件卸载时会自动注销。

DeepSeek Harness 的工具参数还需要自己校验吗?

DeepSeek Harness 的 defineTool 会在 execute 前校验模型生成的参数,包括类型、必填键和字面量约束;schema 表达不了的跨字段规则仍需你在 execute 里用 ToolArgsError 拒绝。

DeepSeek Harness 的工具 execute 返回什么才算正确?

DeepSeek Harness 的工具应返回 output.schema 声明的规范 JSON 值,而不是内容块或自然语言。注册表会做无损快照与校验,再交给 output.render 渲染给模型看。

DeepSeek Harness 加完工具后,怎么确认模型真的能看见它?

DeepSeek Harness 里,看三处:工具的 schema 是否进入系统提示词组装,模型是否能发起该工具调用,结果是否能通过 output.render 正常渲染。三处都过,才算工具真的可用。

相关术语

defineTool
defineTool 是 DeepSeek Harness 声明面向模型工具的标准入口,用 name、description、parameters、output 与 execute 描述一个工具。— DeepSeek Harness 官方文档 - 工具编写参考
ctx.tools.register
ctx.tools.register 是 DeepSeek Harness 注册工具的调用,注册属于插件副作用,插件 fiber 卸载时会自动注销该工具。— DeepSeek Harness 官方文档 - 工具编写参考
规范 JSON 值
规范 JSON 值是 DeepSeek Harness 工具返回的无损结构化结果,注册表会快照、校验并冻结它,再交给渲染器展示给模型。— DeepSeek Harness 官方文档 - 工具编写参考
ToolArgsError
ToolArgsError 是 DeepSeek Harness 工具在 schema 无法表达的约束失败时抛出的参数错误,用于明确拒绝不合法的输入。— DeepSeek Harness 官方文档 - 工具编写参考

来源