跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-05
课程目录 · 11 节

Agent 框架源码

第 9 节:一个插件三段代码,工具五条义务

核对 2026-11-05 更新 1 次 引用 0 个来源

插件固定三段:inject 定启动时机、Config 做运行时校验、apply 只做注册。工具要过五条义务,其中「规范值」「渲染」「signal」三者分开最容易被忽略。LLM 适配器另有四条流式协议约定。

关键事实 · 4 条口径随行标注
插件结构
三段inject 依赖、Config schema、apply 注册
工具义务
五条参数校验、规范返回值、渲染分离、遵守 signal、失败即抛
先验证的 profile
sdk-minimal37 条完整显式配置树,出问题易定位
再挂载的 profile
web220 条装配,base 99 加 web-app 121

一个插件就三段:依赖、配置、apply

dsh 的插件没有基类要继承,没有生命周期方法要实现。形态固定为三样东西加一个函数:

export const name = 'my-tool'
export const inject = ['tools']                 // ① 依赖:等 ctx.tools 就绪
export const Config = z.object({ /* … */ })     // ② 配置 schema
export function apply(ctx: Context, config) {   // ③ 注册
  ctx.tools.register(defineTool({ /* … */ }))
}

三段各承担一件事。inject 决定启动时机——不写依赖就可能在 ctx.tools 还不存在时执行 apply,得到一个 undefined 报错。Config 是运行时校验的 schema,插件从配置里收到的值一定已经过它。apply 里只做注册,不做初始化逻辑。

热重载(HMR)能安全工作的前提就是这三段无副作用:apply 里注册的东西全部可撤销,插件重新执行时旧的注册先被回收。所以不要在 apply 里写文件、不要建长期连接、不要往模块级变量塞状态——这些都不受 fiber 管理,重载后会泄漏。

装载的完整时序长这样,注意「工具可见」发生在注册成功之后、下一轮组装时:

dsh 启动 → 读 profile → 叠四层 patch → 长出插件树
   │
   ├─ 你的插件:inject 声明了 tools
   │     └ 等 ctx.tools 就绪(顺序由依赖图定,不由挂载位置定)
   │
   ├─ apply(ctx, config) 执行
   │     └ ctx.tools.register(defineTool(...)) → 返回精确 disposer
   │           └ schema 自动流入系统提示词组装
   │
   ├─ 下一个 turn 组装提示词
   │     └ 模型这时才第一次看到这个工具
   │
   └─ 插件卸载 / HMR
         └ fiber dispose → 注册撤销 → 工具从所有 agent 可见集合消失

工具插件的五个义务,漏一个就会出问题

下面是一个最小的合法工具。它看起来简单,但五个义务一个都不能省:

import { readFile } from 'node:fs/promises'
import { defineTool } from '@deepseek-ai/dsh-tools'

ctx.tools.register(defineTool({
  name: 'read_file',
  description: 'Read a file from disk.',        // 模型看到的全部说明
  parameters: {
    path: { type: 'string', required: true, description: 'Absolute file path' },
    limit: { type: 'number' },                  // 默认可选
  },
  output: {
    schema: { type: 'string' },                 // 规范返回值
    render: (_args, value) => [{ type: 'text', text: value }],
  },
  async execute(args, exec) {
    // args 已按 schema 推导出类型:{ path: string; limit?: number }
    return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
  },
}))
五条都做了,工具才算「接进去」而不是「凑合用」
义务 怎么做 漏了会怎样
参数已校验 用 parameters 声明,execute 里直接信任类型 自己写校验,且和 schema 两套真相
返回规范值 只返回 output.schema 推导的值 返回内容块,程序化调用方无法解析
渲染分离 output.render 负责模型可见文本 自然语言里塞 id,调用方要正则抠
遵守 signal exec.signal 传给 IO 取消后进程挂住或继续跑
失败即抛 基础设施故障抛异常,标 isError 把失败当成功结果,模型以为办成了

第二条和第三条的分离最值得学。output.schema 是给程序看的,output.render 是给模型看的,两者从同一个值派生,但受众不同。这样 PTC 模式(让模型写代码调工具)能拿到结构化结果,普通对话能拿到自然语言,不用为两种模式写两套工具。

还有个细节:schema 会自动流入系统提示词组装,你不需要手动登记。ctx.tools.register() 一调用,这个工具的 name、description、parameters 就进入了下一轮提示词。

接模型与接设置:两处最容易忽略的契约

写 LLM 适配器比写工具难,因为流式协议有硬约定。四条最容易踩的:

两个参考实现共同验证过的约定
约定 正确做法 错误做法
usage 与 finish 的顺序 缓冲到提供方流结束再统一 flush 边收边发,遇到「末尾只发 usage 的分片」就丢
工具参数格式 arguments 全程是原始 JSON 字符串,增量走 argumentsDelta 返回已解析对象,消费方解析崩
块 index 按首次出现顺序分配,同一块的增量复用同一 index 每次增量新分配,前端拼不出一个块
错误两条路径 传输故障从 stream() 抛;提供方带内故障以 finish{kind:'error'} 结束 一律抛异常,带内错误被当传输故障重试

还有一条反直觉的:不支持的能力要抛错,不许静默丢弃。提供方不支持 stop sequences,而调用方传了 stop,正确做法是抛 LlmError(..., 'UNSUPPORTED_OPTION')。静默丢掉会让调用方以为限制生效了,实际模型根本没停。

设置卡这边有个必踩的坑:想让某个字段在运行时改、不用重启,必须声明成 Volatile:

export interface Config {
  endpoint: Volatile<string | undefined>
  retries: Volatile<number>
}

export const Config = z.object({
  endpoint: z.string().volatile(),
  retries: z.number().step(1).min(0).default(3).volatile(),
})

export function apply(ctx: Context, config: Config): void {
  ctx.on('loader/volatile-update', () => {
    ctx.logger.info('Retry limit: %d', config.retries.get())
  })
}

两个使用纪律:在操作开始时读 .get(),不要在异步流程中间反复读(值会变,一次请求里前后不一致);跨字段校验用 .check(),它在持久化前由 Host 执行,不进入表单 schema,所以能做「A 有值则 B 必填」这类规则。

最后一句经验:插件写完后先在 sdk-minimal profile 下验证,那里的配置树是完整显式的 37 条,出问题容易定位;确认无误再挂到 web profile 的 220 条装配里(base 99 加 web-app 121)。

变更记录

日期类型改了什么范围
新建 按官方 cookbook 与真实 defineTool 签名写出实战路径 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型