deepseek-harness/docs/user/develop/basic/tool.zh.md

开发一个 Tool

English | 中文

Tool 是模型可以调用的能力。本文介绍如何用 defineTool 编写一个 tool。

最小示例

import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

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

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      // args is inferred as { name: string }.
      return `Hello, ${args.name}!`
    },
  }))
}

参数定义

parameters 用一种简洁的格式描述参数，框架会自动转换为模型需要的 JSON Schema。

基本类型

export const parameters = {
  path: { type: 'string', required: true },
  limit: { type: 'integer' },
  recursive: { type: 'boolean' },
  parent: { type: 'null' },
}
// Inferred type: { path: string; limit?: number; recursive?: boolean; parent?: null }

枚举

export const parameters = {
  mode: { type: 'string', required: true, enum: ['read', 'write', 'append'] },
}
// Inferred type: { mode: 'read' | 'write' | 'append' }

嵌套对象

export const parameters = {
  options: {
    type: 'object',
    additionalProperties: true,
    properties: {
      timeout: { type: 'number' },
      retries: { type: 'number' },
    },
  },
}
// The declared fields are inferred; additional JSON-valued keys are allowed.

数组

export const parameters = {
  tags: {
    type: 'array',
    items: { type: 'string' },
  },
}
// Inferred type: { tags?: string[] }

每个属性的字段

字段	类型	说明
type	'string' | 'number' | 'integer' | 'boolean' | 'null' | 'object' | 'array' | 'json'	值类型；json 接受任意无损 JSON 值
required	true	标记为必填（影响类型推导）
description	string	发送给模型的描述
enum / const	匹配类型的标量值	允许的字面量值，在编写和运行时边界校验
properties	ParameterSchemaSpec	对象的嵌套属性
additionalProperties	true | false	每个显式对象节点都必须声明
items	ValueSchemaSpec	数组的元素 schema
oneOf	至少两个 ValueSchemaSpec 分支	要求恰好匹配一个分支；代替 type 使用

外层 parameters 映射是一个隐式的开放对象。显式嵌套对象需自行选择是否开放；不通过 defineTool 注册的原始 JSON Schema 保持 JSON Schema 的默认开放语义。

execute 函数

execute 接收经过校验的 args（类型自动推导）和一个 exec 上下文对象：

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

export const tool = defineTool({
  name: 'example',
  description: 'Return an example result.',
  parameters: {},
  output: {
    schema: { type: 'string' },
    render: (_args, value) => [{ type: 'text', text: value }],
  },
  async execute(args, exec) {
    // args: inferred from parameters
    // exec: ToolExecution context

    // Return the value declared by output.schema.
    void args
    void exec
    return 'result here'
  },
})

返回值

execute 返回由 output.schema 声明的无损 JSON 值。output.render(args, value) 会将经过校验的值另外转换为 Native／模型可见的内容：

output: {
  schema: {
    type: 'object',
    additionalProperties: false,
    properties: {
      path: { type: 'string', required: true },
      content: { type: 'string', required: true },
    },
  },
  render: (_args, value) => [{ type: 'text', text: value.content }],
},
async execute(args) {
  return { path: args.path, content: await readFile(args.path, 'utf8') }
}

执行期间的程序化调用方可以使用规范值，但 tool/result 不会持久化该值；渲染后的内容和可选的 presentationMeta 才是可回放的投影。工具主体返回的值若不满足 schema 或不是无损 JSON，就会变为 INVALID_TOOL_OUTPUT 失败。

参数校验

defineTool 在调用 execute 之前会自动校验模型生成的参数。如果参数不合法，会抛出 ToolArgsError，框架将其转换为 isError 结果返回给模型，让模型自行修正。

你不需要在 execute 里手动校验参数类型。

展示层 (Presentation)

Tool 可以定义与传输方式无关的展示方法，供终端和 Web 客户端使用：

defineTool({
  name: 'bash',
  // ...
  output: {
    schema: { type: 'string' },
    render: (_args, value) => [{ type: 'text', text: value }],
  },
  presentCall(args) {
    return {
      card: 'terminal',
      title: args.command,
    }
  },
  presentResult(args, result) {
    return {
      card: 'terminal',
      output: result.content.map(b => b.type === 'text' ? b.text : '').join(''),
    }
  },
})

presentCall 和 presentResult 是纯函数，不能有副作用——UI 可能在流式传输中和会话回放中多次调用它们。

注册与卸载

ctx.tools.register() 返回值就是 disposer。但由于你在 ctx 上调用，框架已经自动追踪了这个注册——插件卸载时会自动移除 tool。你不需要手动调用 disposer。

// This is sufficient:
ctx.tools.register(defineTool({ /* ... */ }))

// No saved disposer or extra cleanup registration is needed.

完整实战示例

一个文件计数 tool：

import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import { readdir } from 'node:fs/promises'

export const name = 'file-counter'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'count_files',
    description: 'Count files in a directory.',
    parameters: {
      path: { type: 'string', required: true, description: 'Directory path' },
      extension: { type: 'string', description: 'Filter by extension (e.g. ".ts")' },
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          count: { type: 'integer', required: true },
          files: { type: 'array', required: true, items: { type: 'string' } },
        },
      },
      render: (_args, value) => [{ type: 'text', text: `Found ${value.count} files.` }],
    },
    async execute(args) {
      const entries = await readdir(args.path, { withFileTypes: true })
      let files = entries.filter(e => e.isFile())
      if (args.extension) {
        files = files.filter(f => f.name.endsWith(args.extension!))
      }
      return { count: files.length, files: files.map(file => file.name) }
    },
  }))
}

下一步

• 插件配置 — 让你的 tool 可配置
• 能力三件套 — 了解 seam/impl/consumer 模式