parameters描述并验证输入
defineTool 从参数定义推导 args，并在执行前验证调用。
从插件到模型能力
让模型调用你的第一个工具。
把 greet 注册到工具表，验证参数，执行逻辑，再把规范值渲染成模型可读结果。
前置条件先完成“第一个插件”，并保留 scratch-plugin 目录和 cordis.yml。
scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-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) {
return `Hello, ${args.name}!`
},
}))
}一次工具调用经过四段契约
参数、执行结果和模型消息不是同一个对象。把每层分开，工具更容易测试和演进。
execute(args)运行工具逻辑
示例读取 name，并返回 Hello, Ada! 这样的规范值。
output.schema声明规范值
schema 约束 execute 的返回类型，本例是 string。
output.render转换为模型内容
render 接收规范值，并输出模型看到的 text 内容块。
替换插件文件并注册 greet
把页面顶部的完整代码写入 scratch-plugin/src/my-plugin.ts。inject 声明 tools 依赖，Cordis 会等工具注册表就绪后再运行 apply。
inject = ['tools']声明依赖，不靠加载顺序碰运气。
ctx.tools.register(...)注册项跟随插件生命周期，卸载插件时由上下文清理。
重启 Web UI，然后发起一次明确调用
继续使用第一个插件教程创建的 overlay。打开 Web UI 后，用官方示例提示词验证工具是否进入模型可用能力。
shell
pnpm dsh web --patch ./scratch-plugin/cordis.yml在 127.0.0.1:3080 输入Use the greet tool to greet Ada.
预期：模型调用 greet，并收到 Hello, Ada! 作为工具结果。
这个示例证明什么
最小示例只覆盖同步结果链。复杂工具需要继续查阅官方编写参考。
已经覆盖
参数 schema、类型推导、依赖注入、执行、规范值和文本渲染。
继续查阅
嵌套 schema、后台工作、策略钩子、Code Mode 和 UI cards。