deepseek-harness/docs/core-data-structures/tools.zh.md

工具

English | 中文

dsh-tools 的工具流水线。core.md 介绍了 ToolDefinition（唯一被提升到主干的流水线编写类型）和 ToolSchema（面向模型的协议格式（wire format）形状）。本页拥有完整的 ToolDefinition、用于构建它的类型化 schema DSL、受保护的执行形状，以及 UI 展示词汇。

源码：packages/core/tools/src/index.ts · packages/core/tools/src/schema.ts · packages/core/tools/src/presentation.ts

ToolDefinition — 一个已注册的工具

一个 ToolSchema（面向模型的字段）加上 execute 函数和可选的 UI 展示器。注册表持有这些定义；agent loop（智能体循环）通过它们分派调用。注册表的 schemas() 通过显式白名单构建面向模型的 ToolSchema[]——execute/presentCall/presentResult 绝不能泄漏到模型请求中。

interface ToolDefinition extends ToolSchema {
  execute(args: unknown, exec: ToolExecution): Promise<ToolExecuteReturn>
  /**
   * Cooperative tool-call timeout budget in milliseconds. Omit for no deadline.
   * Enforced by `@deepseek-ai/dsh-timeout-policy` (a `tools/execute` wrapper); it
   * is NEVER sent to the model — `schemas()` whitelists only name/description/
   * parameters. Declaring it asserts this tool forwards `exec.signal` to a
   * cooperative implementation that can reach quiescence when the signal aborts.
   */
  timeoutMs?: number
  /**
   * Optional: how to present the PENDING state of one call in a UI, derived from
   * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
   * its own input). Returns a {@link ToolCallView} (a `card`-tagged render intent),
   * or `undefined` (or omit the method) to fall back to a generic presentation
   * (title = tool name, raw args as input). Pure and side-effect-free: a UI may
   * call it during live streaming AND a session-log replay, so it must depend
   * only on `args`.
   */
  presentCall?(args: unknown): ToolCallView | undefined
  /**
   * Optional: how to present the COMPLETED state, given the same `args` and the
   * `result` (`execute`'s content + whether it errored). Returns a
   * {@link ToolResultView}, or `undefined` (or omit the method) to keep the
   * pending title and render the raw result content. Pure and side-effect-free
   * for the same replay reason.
   */
  presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined
}

execute 接收 args: unknown——原始的 ToolDefinition 自行校验输入。第一方工具不需要手写校验；它们使用 defineTool，由后者代为校验并收窄类型。

类型化 schema DSL

插件作者为每个属性编写带有布尔值 required: true 的规格，类型层面的辅助工具将规格映射为 execute 的参数类型——零类型断言。该 DSL 是为 ToolDefinition 提供类型的机制；它有意作为子页面细节，而非核心内容。

源码：packages/core/tools/src/schema.ts

interface SchemaProp {
  type: SchemaType
  /** Per-property required flag (NOT the JSON Schema top-level required array). */
  required?: true
  /** Human-readable description, surfaced in the JSON Schema as well. */
  description?: string
  /** Enum of allowed values (strings only). */
  enum?: string[]
  /** Default value. */
  default?: unknown
  /** Nested properties for type: 'object'. */
  properties?: SchemaSpec
  /** Items schema for type: 'array'. */
  items?: SchemaProp
}

type SchemaSpec = Record<string, SchemaProp>

SchemaType 是原始联合类型 'string' | 'number' | 'boolean' | 'object' | 'array'。InferArgs<S> 将一个 SchemaSpec 映射为 TS 参数类型——required: true 的属性成为必选键，其余为真正的可选：

type InferArgs<S extends SchemaSpec> = Simplify<
  & { [K in RequiredKeys<S>]: InferPropValue<S[K]> }
  & { [K in Exclude<keyof S, RequiredKeys<S>>]?: InferPropValue<S[K]> }
>

defineTool({ name, description, parameters, execute, … }) 将各部分串联：parameters 是一个 SchemaSpec，execute(args, exec) 获得 args: InferArgs<typeof parameters>，辅助函数将规格转换为 JSON Schema（schemaSpecToJsonSchema）用于协议传输，并在类型化函数体运行前校验模型生成的参数（validateArgs）。校验不通过时抛出 ToolArgsError（code: 'INVALID_ARGS'），注册表将其转为 isError 结果以便模型自行修正。为何用自定义 DSL 而非 schemastery：工具参数需要 JSON Schema（LLM（大语言模型）的协议格式），而非校验/转换——轻量 DSL 以最小的接口面积提供最佳的编写体验。

注册是一个受信任的同进程契约。注册表以 readonly 输入借用类型化定义，仅校验语义要求（如 timeoutMs 必须为正有限值）；schemas() 在模型边界处物化显式的面向模型投影，使执行和展示共享同一份已解析定义，而不会将回调泄漏到协议上。

ToolRestriction — 单个作用域的实时全局过滤器

ToolRestriction 仅作用于实时的部署全局工具层。注册表将 readonly 名称编译为私有集合，对多个限制取交集，再叠加作用域本地工具。仅 deny 的过滤器允许后续未列出的全局工具通过，而 allow 列表则排除它们。

interface ToolRestriction {
  readonly allow?: readonly string[]
  readonly deny?: readonly string[]
}

执行：可扩展的 waterfall（瀑布式事件）加单调策略

ctx.tools.execute() 接收调用方拥有的 ToolExecutionInput，将其解析后的 JSON 参数一次性物化为流水线拥有的 ToolExecution，然后依次通过 tools/pre-execute（可重排的 allow/deny/ask waterfall）→ 已注册的单调 guard → tools/execute（around-dispatch 包装层）→ tools/post-execute（检查/替换结果）→ tools/result（不可变的权威结果）。最终产出为 ToolExecutionResult。

type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }

interface ToolExecutionInput {
  readonly callId: CallId
  readonly name: string
  /** Parsed JSON arguments (unknown — tools validate their own input). */
  readonly arguments: unknown
  /** The agent on whose behalf the call runs (set by the agent loop). */
  readonly agent?: Agent
  /**
   * Opaque token of the enclosing transport execution, when one exists. Code
   * Mode sets this on SDK sub-dispatches so commit-style observers can wait for
   * the outer `run_code` outcome without receiving its live mutable execution.
   */
  readonly parent?: ToolExecutionToken
  signal?: AbortSignal
}

interface ToolExecution extends ToolExecutionInput {
  /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
  readonly token: ToolExecutionToken
}

ToolExecutionToken 是一个不透明的运行时 Symbol，仅用于身份比较。在策略执行之前，execute() 物化并冻结参数、拒绝非 JSON 输入、分配 token。身份字段和可选的 parent token 保持 readonly；只有 signal 可以在分派前后变化。最终观察者接收到的是冻结的执行身份。

ToolGuard 是感知作用域的最终预分派策略。其形状有意不包含 allow 结果：undefined 保留 waterfall 的决策，而返回的 reason 只能缩减权限，因此后续监听器无法撤销它。

type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

interface ToolExecutionResult {
  content: ContentBlock[]
  isError: boolean
  /**
   * Set when the call failed with a {@link HarnessError}: machine-routable
   * `{ name, code }` for retry/sandbox plugins and replay. The model-facing
   * text in `content` is always present; this is extra structure for code.
   */
  error?: ToolErrorInfo
  /**
   * Extra model-facing context a `tools/post-execute` listener attached for the
   * NEXT request (Claude Code's PostToolUse `additionalContext`). It is NOT part
   * of this call's `content` — `content`/`feedback` shape the tool RESULT, but
   * `additionalContext` is a SEPARATE `context/message`. A step can carry
   * multiple tool calls, so the loop BUFFERS every call's `additionalContext`
   * and appends them only AFTER all `tool/result`s for the step, keeping
   * tool-call/result adjacency intact. Carried on the result purely to ferry it
   * from `execute()` up to the loop's per-step buffer.
   */
  additionalContext?: HookContext
  /**
   * The tool-private presentation payload from a successful `execute` (the object
   * return form). Threaded onto the `tool/result` session event and back into
   * {@link ToolResult} for `presentResult`. Opaque (`unknown`); absent when the
   * tool attached none or the call failed.
   */
  meta?: unknown
}

结果仅承载产出。调用身份保留在不可变的 ToolExecution 上，后者伴随结果经过每个钩子，并出现在持久化的 tool/call / tool/result 会话事件上，因此包装层无法创建第二个相互矛盾的身份。

注册表在 tools/result 之前立即物化并冻结最终接受的结果。其内容、结构化错误、附加上下文和展示元数据必须通过 JSON 无损往返；无效的产出会被转为 JSON 安全的 isError 结果，从而保证被观察到的实时产出对后续持久化的 tool/result 追加是安全的。

每个拦截 waterfall 返回一个类型化的 Decision（与 agent/* seam 共享的惯用模式）。tools/pre-execute 监听器接收 (exec, next) 并返回 PreToolDecision；tools/execute 包装层返回 ToolExecutionResult；tools/post-execute 监听器接收 (exec, result, next) 并返回 PostToolDecision：

type PreToolDecision =
  | { kind: 'allow' }
  | { kind: 'deny'; reason: string }
  | { kind: 'ask'; reason?: string }

type PostToolDecision =
  | { kind: 'accept'; content?: ContentBlock[]; additionalContext?: HookContext }
  | { kind: 'block'; feedback: ContentBlock[]; additionalContext?: HookContext }

调用 next() 获取默认决策，或直接返回一个决策以短路。前置策略可以 deny 或 ask；只有 allowed-once 才继续执行，而未授权、缺少审批通道或服务、或无 agent 的请求都会变为拒绝。Guard 仍可施加最终拒绝。参数不可被改写，因为历史记录、审计、UI 和执行必须保持一致。

后置策略可以替换内容；block 会变为包含纠正反馈的 isError 结果。tools/result 在归一化后接收冻结的执行和结果；观察者无法对其进行变换，观察者的失败也会被隔离。未知工具和抛出异常的工具都会变为结构化错误（ToolNotFoundError 映射为 UNKNOWN_TOOL），调用失败但不终止当前轮次。

结构化输出 schema 子集

调用方用来向 subagent 要求机器可读结果的词汇（SubagentStartRequest.outputSchema，见 subagent.md），或工作流 agent() 调用使用的词汇。它有意不是完整的 JSON Schema：schema 原样传给模型作为强制工具的 parameters，产出的值由 validateStructuredValue 在客户端校验——因此每个被接受的关键字都必须是校验器实际执行的，assertSupportedOutputSchema 会大声拒绝其他任何内容（OutputSchemaError，列出所有违规项）。两个遍历器仅推理自有可枚举属性（JSON 不携带其他内容），并拒绝会有损序列化的非纯对象（Date、Map）。

type StructuredScalar = string | number | boolean | null

type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'

interface StructuredSchemaNode {
  type: StructuredSchemaType
  properties?: Record<string, StructuredSchemaNode>
  required?: string[]
  additionalProperties?: boolean
  items?: StructuredSchemaNode
  enum?: StructuredScalar[]
  const?: StructuredScalar
  description?: string
  title?: string
  default?: unknown
  examples?: unknown
}

schema 是一个以 object 为根的节点（enum/const 仅限标量；description/title/default/examples 是注解，允许但忽略，但仍要求为 JSON 数据——它们随协议传输）：

type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }

工具展示 UI 词汇

工具希望其调用在 UI 中如何呈现（编辑器工具调用卡片、CLI 日志行），提供方无关，使工具在不依赖任何客户端协议的情况下描述自身。presentCall/presentResult 返回一个 card 标签的渲染意图——一个可辨识联合类型，UI 桥接层据此分发：

• ToolCallView（待执行）：{ card: 'generic', title, kind?, rawInput?, content?, locations? }（默认卡片；locations 是 { path, line? }[]，表示调用读取/修改的文件，供编辑器跟随）、{ card: 'terminal', title, description?, cwd? }（shell 命令→终端卡片）、或 { card: 'diff', title, diffs, locations? }（文件创建/修改→行内 diff 卡片；diffs 是 { path, oldText, newText }[]，新文件时 oldText: null）。
• ToolResultView（已完成）：{ card: 'generic', title?, content? }、{ card: 'terminal', title?, output?, exitCode?, signal? }（捕获的运行输出 + 退出状态；有能力的 UI 显示退出状态标签，无能力的 UI 获得桥接层从 output 派生的围栏 ```console 回退）、或 { card: 'diff', title?, diffs }（已完成的文件变更→要展示的变更，通常是从变更前后内容计算出带上下文行的已应用 hunk，或在没有前像时的整文件 diff——例如文件创建。tool_call_update 的内容会替换调用的内容，因此变更工具即使与调用时的片段重复也要返回此卡片，以防结果文本覆盖 diff）。

ToolCallKind（'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'）为 generic 卡片选择图标。FileLocation（{ path, line? }）和 FileDiff（{ path, oldText, newText }）是共享的文件卡片词汇。该设计固定在渲染意图联合类型 RFC 中；ACP 桥接层将 diff 卡片映射为 { type: 'diff' } 内容块，将 terminal 卡片映射为 _meta 终端约定，并将文件卡片的标题相对于会话 cwd 做相对化处理。

完整的展示字段文档见 packages/core/tools/src/presentation.ts。bash 工具自身的 schema（bash/bash_output/bash_kill）及其驱动的执行器见 bash.md。