DeepSeek Harness 照 Cookbook 加工具:schema、注册、准入与三步验证
官方 Cookbook 给的是一段能跑的最小形态,但「能跑」和「模型真的看见并能用」是两件事。 这篇按官方顺序把加工具走一遍,再把 Cookbook 没展开的三步验收和五个策略扩展点补上。现有 develop-tool-plugin 与 develop-tool-execute-contract 讲的是契约细节,这里讲的是照做之后怎么确认没做错。
DeepSeek Harness 最小工具:从 defineTool 到注册
一个工具最少需要四样东西:名字、给模型看的描述、参数 schema、返回值 schema。 官方最小形态如下(来源):
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 不是普通函数,它受注册表的四条约束。 官方把规则写得很清楚,照做能避免大部分「工具能注册但不工作」的问题(来源):
- 参数已被校验 —
defineTool会在 execute 前校验模型生成的 arguments;你只需补 schema 表达不了的约束,例如非空字符串、正数、跨字段规则,并用ToolArgsError拒绝。 - 注册借用只读定义 — 注册后不要改 schema 或替换回调;要热替换工具,先 dispose 旧副作用,再注册替代品。
- 返回规范 JSON 值 — 返回
output.schema声明的值,不要返回内容块或自然语言;注册表会快照、校验、冻结,再交给output.render。 - 遵守 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 三步验证:跑完怎么验
加完工具,按三步验证,不要只看「没有报错」。 推荐顺序如下(来源):
- schema 进提示词 — 确认工具的 name、description、parameters 出现在模型可见的工具清单里;没有出现,先查 inject 与注册是否执行。
- 模型能调用 — 用一个明确需要该工具的任务触发调用;模型不调用,优先改 description 与参数描述,而不是怀疑注册。
- 结果能渲染 — 检查
output.render的输出是否可读,UI 卡片是否回退到通用卡片,PTC 是否能拿到规范值。
三步都过,工具才算真的可用。只过第一步,是「注册成功但模型不用」;只过前两步,是「模型用了但用户看不懂」;三步都过,才进入调优。
最后对照旧文:develop-tool-plugin 讲插件里怎么组织工具,develop-tool-execute-contract 讲 execute 的契约细节;本篇补的是官方 Cookbook 的走查与验收。三者一起看,才不会把「能注册」误当成「能工作」。
常见问题
DeepSeek Harness 里,最少要写三部分:用 defineTool 声明 name、description、parameters 与 output,在 apply 里调用 ctx.tools.register 注册,并声明 inject 依赖。注册是副作用,插件卸载时会自动注销。
DeepSeek Harness 的 defineTool 会在 execute 前校验模型生成的参数,包括类型、必填键和字面量约束;schema 表达不了的跨字段规则仍需你在 execute 里用 ToolArgsError 拒绝。
DeepSeek Harness 的工具应返回 output.schema 声明的规范 JSON 值,而不是内容块或自然语言。注册表会做无损快照与校验,再交给 output.render 渲染给模型看。
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 官方文档 - 工具编写参考
来源
- DeepSeek Harness 官方文档 - 工具编写参考· deepseek-harness
- DeepSeek Harness 官方文档 - 工具子系统· deepseek-ai