工具插件：defineTool

一、完整实战：greet 工具Hands-On

把 L12 的 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}!`
    },
  }))
}

重启（或热重载）后，在 Web UI 里对模型说："用 greet 工具向 Ada 问好"——模型会调用 greet，并把收到的 Hello, Ada! 作为工具结果继续对话。

二、defineTool 解剖Anatomy

三、execute 的六条契约The Contract

1. 参数已校验。模型生成的 arguments 进入 execute 前已按 schema 验证（类型、必填、枚举）；schema 表达不了的约束（非空字符串、正数、跨字段规则）要自己查。
2. 返回规范值（canonical value）。只返回 schema 声明的那个值，框架负责快照、校验、冻结再交给 render。不要返回内容块，不要让调用方从散文里解析字段。
3. 抛异常或返回非法值 = isError。基础设施故障就抛；业务上的"不理想结果"（如命令退出码非零）是正常返回值，交给渲染层解释。
4. 尊重 exec.signal。取消信号，触发时应尽快中止在途工作（传给底层 API / 读文件都带上）。
5. 把 args 当只读。执行身份（callId、name、arguments、token）在派发中不可变。
6. 异步通知用 exec.agent.inject()——给下一次请求追加模型可见的上下文。它不是唤醒：空闲的智能体仍保持空闲（L07 的收件箱规则）。

// 一个更真实的例子：参数带取消信号的文件读取
async execute(args, exec) {
  // args 类型自动推断为 { path: string; limit?: number }
  return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
}

四、UI 渲染意图：工具的"门面"要提前想Render Intent

工具结果的 UI 展示是设计的一部分（仓库明文规定"写工具时就要决定"），通过纯展示函数声明卡片类型：

两条硬规则：① 纯函数——展示函数在直播和回放时都会跑，禁止 I/O、读会话状态、时钟/随机；② UI 专用格式不进模型结果——代码块装饰、相对路径美化是 UI 的事，模型内容保持干净。

五、两个进阶能力Advanced

后台任务：run_in_background 模式

长任务不堵会话：配置里开启后台门控 → execute 里走 ctx.jobs.start({ kind, label, owner: exec.agent, run })，成功返回类型化的后台句柄（如 { kind: 'background', jobId }），模型稍后用 job_* 控制工具查询/停止。Code Mode 绝不能从人类可读文字里解析 jobId——句柄必须是结构化的。

Code Mode 免费接入

Code Mode（模型写代码调工具的模式）里，每个已注册工具自动变成 await tools.greet({ name: 'Ada' })——参数和返回类型从同一套 schema 推导，调用走正常执行管线，你什么都不用做。因此 output.schema 要当真正的程序 API 设计：直接返回句柄和字段，人类解释留在 render。