DSH plugin 怎么写工具插件：defineTool 参数与输出声明、execute 契约与 UI 卡片渲染

DSH plugin 写工具插件的固定套路是三步：声明 inject: ['tools']、在 apply 里 ctx.tools.register(defineTool({ ... }))、在 defineTool 里分别声明 parameters（模型能传什么）、output.schema（execute 必须返回什么）与 execute（怎么执行）。 无论你叫它 DSH插件 还是 DeepSeek插件，这套契约完全一样。

DSH plugin 工具插件的最小形态

一个工具插件 = 声明依赖 + 注册工具定义，注册是 effect 式的，插件卸载即自动注销。 官方给出的最小写法如下（来源）：

import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/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: 'read_file',
    description: 'Read a file from disk.',
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

inject: ['tools'] 不能省——它让 Cordis 先备好工具注册表，apply 里才敢直接用 ctx.tools。依赖声明的完整机制见 怎么写插件。

DSH plugin 的 parameters 与 output：一个进、一个出

parameters 管入参、output.schema 管出参，两者职责不重叠。 官方对这条边界的表述是：defineTool 从 parameters 推导并校验 execute 的 args；execute 返回的是 output.schema 声明的那个 canonical 值，再由 output.render 转成模型可见内容（来源）。

• 参数自动校验：类型、必填键、字面量约束、精确其一联合、嵌套值都由框架在 execute 之前验完——你不必再写类型判断，但 DSL 表达不了的约束（非空字符串、正数、跨字段规则）要自己查。
• description 是写给模型看的：它决定模型何时调用这个工具，不是注释。
• 输出只声明一个根值：可以是对象、数组、标量或 null——按「这个值的诚实形态」来选，不要为了界面好看把文案塞进 schema。

DSH plugin 的 execute 契约：四条硬规则

execute 是一份契约，不是普通函数——四条规则越界就会出问题。

1. 只返回一个 canonical 值。 不要返回内容块、不要让调用方从散文里解析 id 或字段；注册表会把它快照为无损 JSON、校验、冻结。
2. 抛异常即 isError。 基础设施故障（文件不存在、网络断）直接 throw；业务上的非理想结果仍返回 canonical 值，例如「进程非零退出」应当是一个正常返回值，由渲染器解释，而不是异常。
3. 遵守 exec.signal。 信号触发时取消在途工作——exec 还携带不可变的执行身份与 token，args 应视为只读输入。
4. 注册后不要改自己的定义。 同进程的类型化贡献不是序列化边界，注册后不得改动 schema 或替换回调；要热换工具就处置其所属 effect 再注册新的。

想做权限或埋点，别写进工具本体。 官方建议用 tools/pre-execute（放行 / 拒绝 / 追问策略）、ctx.tools.guard()（不可撤销的最终拒绝）、tools/execute（环绕派发加超时、重试、指标）、tools/post-execute（替换展示内容或结果）与 tools/result（观察不可变结果）这些扩展点，让工具体保持纯粹。

DSH plugin 的长时任务与 UI 卡片

耗时操作走后台任务通道，界面呈现交给纯函数卡片——两者都不要污染 canonical 值。 需要用 run_in_background 时，经 ctx.jobs.start({ kind, label, owner: exec.agent, run }) 注册，成功分支返回类型化的句柄（如 { kind: 'background', jobId }），Code Mode 绝不能去解析那句人类可读的 started background job bash-1 来取 id（来源）。

界面卡片通过两个可选方法声明，返回带 card 标签的渲染意图：

两条会咬人的硬规则：① 这些函数在实时流与会话回放中都会执行，因此必须是 args（与结果）的纯函数——不许 I/O、不许读会话状态、不许看时钟或随机数；② 界面专用格式不要混进模型结果，output.render 管面向模型的文案，presentationMeta 加卡片呈现管界面状态。

工具没有任何界面呈现时，会回退到通用卡片（标题 = 工具名，输入 = 原始参数），不会崩。界面相关的更多呈现方式见 插件界面开发。

DSH plugin 工具插件的自检与下一步

注册前过一遍这五项：

1. inject 里有没有 tools；
2. parameters 与 output.schema 是否描述清楚，description 是否面向模型；
3. execute 是否只返回 canonical 值、是否正确区分「抛异常」与「非理想结果」；
4. 是否兑现了 exec.signal；
5. 卡片呈现函数是否为纯函数。

需要可替换的实现时再拆包：把定义（Service Definition）、实现（Provider）、消费方（暴露成 tool）拆成三个包，详见 开发指南 的三角色设计；打包与发布见 打包成 bundle 与 发布到插件中心。插件装好后可在 DSH Plugin Hub 的已安装列表确认状态。