Agent 框架源码
第 9 节:一个插件三段代码,工具五条义务
插件固定三段:inject 定启动时机、Config 做运行时校验、apply 只做注册。工具要过五条义务,其中「规范值」「渲染」「signal」三者分开最容易被忽略。LLM 适配器另有四条流式协议约定。
- 插件结构
- 三段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 签名写出实战路径 | 全页 |