工具管线:校验、执行与呈现
0.2.1-rc.5 ·
核对日期: ·
官方来源。
DSH 仍处于公开预览阶段,升级后请重新核对版本敏感步骤。工具报错时,先判断业务代码是否已经执行
同样显示“调用失败”,可能发生在输入校验拒绝时、业务执行中或输出校验拒绝后——输入校验先于工具体执行,INVALID_ARGS 拒绝意味着业务 execute 从未开始。它们的恢复方式不同,尤其不能把输出错误当成“什么都没发生”并自动重试写操作。
| 失败位置 | 业务副作用可能发生吗 | 排查与恢复 |
|---|---|---|
| defineTool 参数不合法,INVALID_ARGS | 该 helper 尚未进入业务 execute | 对照参数类型与 required;修复输入后再调用 |
| guard 拒绝 | 该次业务 execute 未进入 | 检查调用方权限和拒绝原因;不要通过后置插件把拒绝改成允许 |
| execute 抛错或收到取消 | 可能已经部分执行 | 等待调用收敛并检查实际状态;按工具自身幂等或补偿约定恢复 |
| canonical 输出不合法,INVALID_TOOL_OUTPUT | 业务 execute 可能已完成 | 修正返回数据和输出 schema;先确认副作用,避免盲目重放 |
| UI 卡片不完整或回放降级 | 仅凭呈现无法判断执行成败 | 检查最终 tools/result、canonical value 与模型 content,不从卡片外观推断 |
原始 ToolDefinition 不会因为声明了 parameters 就自动获得 defineTool 的输入保护。使用原始注册入口时,execute 仍需校验 unknown。以下实验直接运行 helper,刻意不把它包装成完整工具注册表。
页头的适用版本是 0.2.1-rc.5(b830ec95);下方实验固定于更早的 0.2.1-rc.3(1f81c047,2026-10-23 发布),是历史条目的可追溯脚本与结果。对照两个固定版本:实验取用的五个源文件,加上条目来源链接的注册表 index.ts 与上游测试 tools.spec.ts,共七件在两版本间逐字节相同。2026-11-07 本次在 rc.3 与 rc.5 两组固定文件上重跑同一脚本均打印 PASS(本次环境 Node v22.23.4,原实验为 Node 24;tsx 4.20.6 相同);即便如此,它仍是直接调用 helper 的局部 probe,不是 rc.5 完整管线实跑。
固定源码的参数校验与取消对照
使用 Node.js 24、npm 和一个新的练习目录;把 source_repo 换成含该 commit 的官方源码仓绝对路径。仅提取五个真实源文件,原仓不切换版本。tsconfig 的路径映射只提供两个模块入口,没有替换其实现,也不做完整类型检查。
set -euo pipefail
source_repo=/absolute/path/to/deepseek-harness
revision=1f81c047fc48fa190a683e469daa699857e9afe8
git -C "$source_repo" cat-file -e "$revision^{commit}"
npm init -y
npm pkg set type=module
npm install --save-exact tsx@4.20.6
mkdir snapshot
git -C "$source_repo" archive "$revision" \
packages/core/tools/src/schema.ts \
packages/core/tools/src/json-schema.ts \
packages/llm/llm/src/error.ts \
packages/util/values/src/index.ts \
packages/util/values/src/partial-json.ts | tar -x -C snapshot
cat > tsconfig.json <<'JSON'
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@deepseek-ai/dsh-llm": ["./snapshot/packages/llm/llm/src/error.ts"],
"@deepseek-ai/dsh-util-values": ["./snapshot/packages/util/values/src/index.ts"]
}
}
}
JSON保存为 check-tools.ts,运行 node --import tsx check-tools.ts。60 秒是等待分支的上限;实验在分支启动后立即发送取消,不需要等待一分钟。
import assert from 'node:assert/strict'
import { setTimeout as delay } from 'node:timers/promises'
import { defineTool } from './snapshot/packages/core/tools/src/schema.ts'
import { validateJsonSchemaValue } from './snapshot/packages/core/tools/src/json-schema.ts'
let calls = 0
let active = 0
let cleaned = 0
const started = Promise.withResolvers<void>()
const tool = defineTool({
name: 'probe',
description: 'Check argument validation and cooperative cleanup',
parameters: {
mode: { type: 'string', enum: ['echo', 'wait'], required: true },
text: { type: 'string', required: true },
},
output: {
schema: {
type: 'object', additionalProperties: false,
properties: { text: { type: 'string', required: true } },
},
render: (_args, value) => [{ type: 'text', text: value.text }],
},
async execute(args, exec) {
calls++
active++
try {
exec.signal.throwIfAborted()
if (args.mode === 'wait') {
started.resolve()
await delay(60_000, undefined, { signal: exec.signal })
}
return { text: args.text }
} finally {
await Promise.resolve()
active--
cleaned++
}
},
})
const control = new AbortController()
// This direct helper probe supplies only the field used by its body.
const exec = { signal: control.signal } as Parameters<typeof tool.execute>[1]
const args = { mode: 'echo', text: 'ok' }
const value = await tool.execute(args, exec)
assert.deepEqual(value, { text: 'ok' })
assert.deepEqual(tool.output.render(args, value), [{ type: 'text', text: 'ok' }])
await assert.rejects(tool.execute({ mode: 'echo', text: 42 }, exec), { code: 'INVALID_ARGS' })
assert.equal(calls, 1)
const pending = tool.execute({ mode: 'wait', text: 'later' }, exec)
await started.promise
assert.equal(active, 1)
control.abort()
await assert.rejects(pending, { name: 'AbortError' })
assert.equal(active, 0)
assert.equal(cleaned, 2)
assert.deepEqual(validateJsonSchemaValue(tool.output.schema, value), [])
assert.ok(validateJsonSchemaValue(tool.output.schema, { text: 42 }).length > 0)
console.log('PASS tools: invalid input skipped body; abort settled; active=0; cleaned=2')预期打印 PASS tools: invalid input skipped body; abort settled; active=0; cleaned=2。正常输入得到 canonical value 和模型文本;数字 text 在业务代码前抛出 INVALID_ARGS,calls 仍为 1。等待分支收到 AbortSignal 后拒绝,finally 完成后 active 为 0,两次真实进入业务代码的调用都经过回收。
最后两条断言直接调用真实 JSON Schema validator,分别接受合法值、拒绝错误类型。直接调用 defineTool.execute 不会运行完整注册表的输出归一化和校验,因此这里不声称获得了 INVALID_TOOL_OUTPUT 结果。该错误码及其发生阶段来自固定注册表源码和上游测试。也未运行 guards、超时策略、MCP、UI 或模型;局部 exec 只提供示例业务代码使用的 signal,不代表完整 ToolRunContext。
调用资源与注册资源如何回收
每次调用打开的文件、连接或订阅应在 execute 自己的 try / finally 中回收;异步操作应观察或继续传递 exec.signal,并在返回或拒绝前等待自己启动的工作结束。示例使用支持取消的 timers/promises,finally 是可观察的回收检查点。取消是协作请求,不能强行终止忽略 signal 的同进程代码。
注册表条目、长期监听器等插件资源则交给所属 scope 的 effect / disposer。卸载工具注册不等于终止它之前已经启动的调用;退出时要停止新输入并等待拥有方回收,参见Agent 循环与生命周期。声明 timeoutMs 本身也不是强制杀进程:固定版本由工具超时策略插件执行预算,业务代码仍需配合取消。
实际接入后,按“合法参数 → 非法参数 → guard 拒绝 → 执行中取消 → 非法输出”检查对应结果与回收,再核对模型 content 和 UI。render 生成模型内容;presentCall / presentResult 负责可回放呈现,不放业务副作用。若取消仍挂起,先查底层 API 是否支持 signal 及清理是否被 await;若输出校验失败,先查返回 DTO,再考虑重试。
固定来源:defineTool、JSON Schema 子集与 validator、注册表与执行合同、上游工具回归。局部实验最初在 rc.3 固定文件上运行,2026-11-07 在 rc.3 与 rc.5 两组固定文件上重跑均通过;完整管线未在此实验中运行。
定义与可见性
工具在 Cordis 作用域注册,装配时按调用方可见性生成模型 schema。timeoutMs、isConcurrencySafe 等属于 Host 元数据,不能把整个定义对象原样交给模型;schema 使用明确允许的字段。
底层 ToolDefinition.execute 接收 unknown 参数,工具必须自己校验。defineTool 帮助校验并收窄类型;不能因为声明了 JSON Schema 就假设任意原始 execute 都会自动得到可信参数。非法输入与非法输出分别报告 INVALID_ARGS 和 INVALID_TOOL_OUTPUT。
执行顺序
pre-execute → monotonic guards → execute
→ projectContent → post-execute → finalizeContent → tools/result权限 guard 的拒绝是单调的,后面的插件不能改回允许。取消与超时按执行上下文传播,错误保持失败状态;tools/result 是完成后的不可变观察事件,不是继续改写结果的入口。
结果给谁看
output schema 约束 canonical value。render 生成给模型的 ContentBlock,不是只给 UI;presentCall / presentResult 是 UI 卡片的纯呈现函数。展示函数不应拥有业务副作用或替代结果校验。大输出、权限与超时由对应策略插件承担,不是每个工具都天然具备。
验证一个工具
检查作用域可见性、合法与非法参数、被 guard 拒绝、取消、非法输出及两种呈现路径。不要通过只验证 UI 卡片来证明模型收到正确结果。