21 KiB
工具
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 展示函数组成。注册表持有这些定义，循环通过它们分派调用。注册表的 schemas() 通过显式允许列表构建面向模型的 ToolSchema[]；execute/timeoutMs/isConcurrencySafe/presentCall/presentResult 绝不能泄漏到模型请求中。
/** A registered tool: its schema plus the execution function. */
interface ToolDefinition extends ToolSchema {
/**
* Run one accepted call. Async work must observe or forward `exec.signal` and
* settle only after its owned work reaches quiescence. The registry preserves
* caller cancellation through around-dispatch signal replacement and does
* not abandon this promise, but it cannot hard-kill same-process code.
* @param args - losslessly snapshotted, frozen model arguments.
* @param exec - execution identity, cancellation signal, and context deferral.
* @returns model-facing content plus optional private presentation metadata.
*/
execute(args: unknown, exec: ToolRunContext): 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
/**
* Pure synchronous classifier for overlap with sibling tool calls. Only
* `true` opts in; omission, exceptions, non-`true` returns, and invalid
* `defineTool` arguments are exclusive. This metadata is never model-visible.
*
* Opted-in executions must not mutate parent-owned state. Shared state must
* tolerate concurrent dispatch; recorder races are permitted only when they
* commute or fail closed. See the
* [parallel-tool-call Agent Note](../../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
* for the full contract.
* @param args - parsed arguments; `defineTool` validates before calling.
* @returns Whether this call may join a parallel group.
*/
isConcurrencySafe?(args: unknown): boolean
/**
* 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
/** One schema-spec property entry. */
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[]
/**
* Model-visible JSON Schema default annotation. Validation does not apply it;
* dynamic tool mounts may supply it even though first-party definitions do not.
*/
default?: unknown
/** Nested properties for type: 'object'. */
properties?: SchemaSpec
/** Items schema for type: 'array'. */
items?: SchemaProp
}
/**
* The author-facing parameter schema: a shallow map of property name to
* {@link SchemaProp}. Required-ness is a per-property boolean (`required:
* true`), not a separate array.
*/
type SchemaSpec = Record<string, SchemaProp>
SchemaType 是原始联合类型 'string' | 'number' | 'boolean' | 'object' | 'array'。InferArgs<S> 将一个 SchemaSpec 映射为 TS 参数类型——required: true 的属性成为必选键，其余为真正的可选：
/**
* Infer the TS argument type for a complete {@link SchemaSpec}.
*
* Properties marked `required: true` are required keys; all others are
* genuinely optional keys (`?`), so callers may omit them entirely.
*
* Example:
* ```ts
* type Args = InferArgs<{ path: { type: 'string'; required: true }; limit: { type: 'number' } }>
* // → { path: string; limit?: number }
* ```
*/
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 列表则排除它们。
/**
* Per-scope filter over global tools. Restrictions intersect and do not affect
* scoped registrations or the reserved Code Mode transport.
*/
interface ToolRestriction {
/** Global tool names that stay visible; everything else is removed. */
readonly allow?: readonly string[]
/** Global tool names removed from visibility. */
readonly deny?: readonly string[]
}
执行：可扩展的 waterfall（瀑布式事件）加单调策略
ctx.tools.execute() 接受由调用方拥有且包含必需 readonly signal 的 ToolExecutionInput，将其解析后的 JSON 参数一次性物化为流水线拥有的 ToolExecution，然后让调用依次经过 tools/pre-execute（可重排的 allow/deny/ask waterfall）→ 已注册的单调 guard → tools/execute（环绕分派包装层）→ tools/post-execute（检查/替换结果）→ tools/result（不可变的权威结果）。只有 tools/execute 视图可以替换必需的 signal。最终产出为 ToolExecutionResult。
/** Opaque call identity that permits correlation without exposing mutable execution state. */
type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
/**
* Caller-supplied description of one tool call. {@link ToolRegistry.execute}
* adds the registry-owned token to form a pipeline {@link ToolExecution};
* callers do not choose that token.
*/
interface ToolExecutionInput {
readonly callId: CallId
readonly name: string
/** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
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
/** Required caller-owned cancellation for this invocation. */
readonly signal: AbortSignal
}
工具函数体接收运行时扩展。deferContext() 是组合工具的通道：它记录嵌套分派产生的上下文，而不会在外层调用尚未结束时注入这些上下文。
/**
* Runtime context handed to a tool implementation after the registry has
* accepted a {@link ToolExecution}. A composite tool uses
* {@link deferContext} to ferry context produced by nested dispatches back to
* the outer result; the loop appends it only after the outer `tool/result`.
*/
interface ToolRunContext extends ToolExecution {
/**
* Defer one nested-dispatch context until this tool's final result reaches
* the agent loop. Contexts retain their individual source and metadata and
* are emitted in call order.
*/
deferContext(context: HookContext): void
}
agent loop（智能体循环）向注册表查询每个待处理调用的执行模式，并据此形成独占屏障和滚动池并行执行：
/**
* Scheduling mode for one pending call. `parallel` may overlap with siblings;
* `exclusive` runs alone and forms an ordering barrier.
*/
type ToolExecutionMode =
| { kind: 'parallel' }
| { kind: 'exclusive' }
/**
* One pending tool call inside the registry pipeline. Parsed arguments cross
* one lossless-JSON materialization boundary before policy and are deep-frozen;
* call identity, the caller signal, and the registry-assigned {@link token} are
* readonly. The registry freezes the complete object before `tools/result`
* observers run.
*/
interface ToolExecution extends ToolExecutionInput {
/** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
readonly token: ToolExecutionToken
}
/**
* Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
* may replace the signal for its delegated lifetime, but it cannot remove it.
* The registry fuses every replacement with the captured caller signal.
*/
interface ToolDispatchExecution extends Omit<ToolExecution, 'signal'> {
/** Cancellation signal visible to the next wrapper or tool body. */
signal: AbortSignal
}
ToolExecutionToken 是不透明的运行时 Symbol，仅用于身份比较。策略执行前，execute() 会物化并冻结参数、拒绝非 JSON 输入并分配 token。身份字段、调用方必需的 signal 和可选的 parent token 均保持 readonly。ToolDispatchExecution 包装层可以替换 signal 但不能移除；注册表会在调用工具函数体前重新融合调用方的 signal。最终观察者接收冻结的执行身份。
ToolGuard 是感知作用域的最终预分派策略。其形状有意不包含 allow 结果：undefined 保留 waterfall 的决策，而返回的 reason 只能缩减权限，因此后续监听器无法撤销它。
/**
* A monotonic execution guard evaluated after every `tools/pre-execute`
* listener and before the tool body. Returning a reason denies the call;
* returning `undefined` leaves it unchanged. Because guards have no allow
* result, listener ordering cannot turn a denial back into permission.
* @param execution - the identity-protected call after extensible pre-execute policy completed.
* @returns a final denial reason, or `undefined` to leave the call allowed.
*/
type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined
/** The outcome of one tool call. */
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
/**
* Model-facing context for the next request, separate from this tool result. The loop
* accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
*/
additionalContexts?: 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：
/**
* Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
* `ask` runs only after an approval service returns `allowed-once` and otherwise
* denies. Input rewriting is excluded because arguments are already logged and
* presented.
*/
type PreToolDecision =
| { kind: 'allow' }
| { kind: 'deny'; reason: string }
| { kind: 'ask'; reason?: string }
/**
* Post-dispatch decision: accept or replace content, attach context for the next
* request, or block by turning corrective feedback into an error result.
*/
type PostToolDecision =
| { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: HookContext[] }
| { kind: 'block'; feedback: ContentBlock[]; additionalContexts?: HookContext[] }
调用 next() 获取默认决策，或直接返回一个决策以短路。前置策略可以 deny 或 ask；只有 allowed-once 才继续执行，而未授权、缺少审批通道或服务、或无 agent 的请求都会变为拒绝。Guard 仍可施加最终拒绝。参数不可被改写，因为历史记录、审计、UI 和执行必须保持一致。
后置策略可以替换内容；块会变为包含纠正反馈的 isError 结果。tools/result 在归一化后接收冻结的执行和结果；观察者无法对其进行变换，观察者的失败也会被隔离。未知工具和抛出异常的工具都会变为结构化错误（ToolNotFoundError 映射为 UNKNOWN_TOOL），调用失败但不终止当前轮次。
结构化输出 schema 子集
调用方用来向 subagent 要求机器可读结果的词汇（SubagentStartRequest.outputSchema，见 subagent.md），或工作流 agent() 调用使用的词汇。它有意不是完整的 JSON Schema：schema 原样传给模型作为强制工具的 parameters，产出的值由 validateStructuredValue 在客户端校验——因此每个被接受的关键字都必须是校验器实际执行的，assertSupportedOutputSchema 会大声拒绝其他任何内容（OutputSchemaError，列出所有违规项）。两个遍历器仅推理自有可枚举属性（JSON 不携带其他内容），并拒绝会有损序列化的非纯对象（Date、Map）。
/** The scalar values `enum`/`const` may carry (finite numbers only). */
type StructuredScalar = string | number | boolean | null
/** The `type` keywords the subset accepts. */
type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
/**
* One node of the structured-output schema subset. Recursive via `properties`
* and `items`; see the module doc for the exact keyword semantics.
*/
interface StructuredSchemaNode {
type: StructuredSchemaType
/** Nested property schemas (`type: 'object'` only). */
properties?: Record<string, StructuredSchemaNode>
/** Required property names; each must appear in `properties`. */
required?: string[]
/** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */
additionalProperties?: boolean
/** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */
items?: StructuredSchemaNode
/** Allowed values (scalar types only). */
enum?: StructuredScalar[]
/** The single allowed value (scalar types only). */
const?: StructuredScalar
/** Annotation, ignored for validation. */
description?: string
/** Annotation, ignored for validation. */
title?: string
/** Annotation, ignored for validation (must still be JSON data). */
default?: unknown
/** Annotation, ignored for validation (must still be JSON data). */
examples?: unknown
}
schema 是一个以 object 为根的节点（enum/const 仅限标量；description/title/default/examples 是注解，允许但忽略，但仍要求为 JSON 数据——它们随协议传输）：
/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */
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'）用于为通用卡片选择图标。FileLocation（{ path, line? }）与 FileDiff（{ path, oldText, newText }）是共享的文件卡片词汇。该设计由渲染意图联合类型 Agent Note（agent 决策记录）固定；ACP 桥接层将 diff 卡片映射为 { type: 'diff' } 内容块，将 terminal 卡片映射为 _meta 终端约定，并根据会话 cwd 将文件卡片标题转换为相对路径。
完整的展示字段文档见 packages/core/tools/src/presentation.ts。bash schema 与执行器见 bash.md；通用后台控制见 tasks.md。