ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发的能力演进:加方法、加字段怎么不破坏调用方,弃用窗口怎么留才稳

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发向后兼容版本演进
插件升了一个小版本,别人的调用却挂了。本文把能力面的变更分成三类,讲清加字段、加方法与改签名的安全做法,并给出弃用窗口的四件事、版本号与变更日志的对应关系,以及新旧调用方并存的五步验证。

插件开发做到第二年,最贵的不是写新功能,而是别把别人的调用弄挂。 能力一旦被别的插件注入使用,它就不再是你一个人的代码:改一个字段名,可能让对方整个插件停在加载失败。DSH插件 的演进策略因此只有一条主线——加法自由,减法要排队。

DSH plugin 的三类破坏性变更

改名、改签名、改返回值形状,是三种最常见的“无声破坏”。(来源)

  1. 重命名 — 方法名、字段名、服务名。TypeScript 编译期还能提醒,运行时是 undefined。
  2. 改签名 — 参数顺序、必填性、类型收窄。老调用方按旧约定传参,运行到一半才炸。
  3. 改返回值形状 — 从数组改成对象、从可选改成必填、去掉某个字段。调用方读到 undefined 不一定报错,只是行为悄悄变了。

三类里最危险的是第三种:它常常不抛异常,只是让下游少了一段数据。排查成本远高于直接报错。

判断一次改动是否破坏,只需问:调用方不改一行代码,行为还一样吗?答案是否,就是破坏性变更。

加字段:DSH plugin 要可选 + 默认值

字段只增不减、新增即可选,是一条几乎零成本的兼容线。(来源)

给请求或返回值加字段时,三个动作要一起做:

  1. 声明为可选 — foo?: string,老调用方不传也合法。
  2. 在消费侧给默认 — 缺失时按旧行为处理,而不是按 undefined 分支。
  3. 写进类型注释或文档 — 说明它从哪个版本开始存在、缺省意味着什么。

反过来,把可选改成必填是破坏性的:老调用方不会传,运行时就缺值。确有必要收紧要,走弃用窗口,而不是直接改。

还有一类隐蔽的“加字段”:给枚举加新值。消费方如果用了穷举分支,新值会落到 default 里,行为可能完全不同。这类变更要提前通知,而不是当成纯加法。

DSH plugin 加方法与默认实现

新增方法不影响老调用方,新增接口参数才会。(来源)

在 service 上加一个方法,只要不动已有方法,调用方无需改动。这是最安全的一种演进。

需要注意的只有两点。第一,新方法如果要求调用方先做某件事(例如先初始化),那它就不是纯加法,要在文档里写清前置条件。第二,同一语义不要提供两套入口,旧方法能覆盖的场景就别再加一个近义方法。

如果要替换旧方法,按三步走:

  1. 新方法先上,行为与旧方法保持一致。
  2. 旧方法保留,内部转调新方法,并在每次调用时记录一次警告。
  3. 等调用方迁移完,再跨一个主版本删除旧方法。

这样两边的行为始终一致,不会出现“新旧结果不同”的诡异 bug。

DSH plugin 的弃用窗口与迁移提示

弃用不是删掉,而是让旧路径继续可用,同时明确告诉调用方该走了。(来源)

一个可执行的弃用窗口包含四件事:

  1. 标记 — 在类型注释与文档里写明“已弃用,请改用 X”。
  2. 告警 — 旧方法被调用时记录一次日志,便于统计还有谁在用。
  3. 并存 — 新旧同时可用,行为保持一致。
  4. 删除 — 确认无调用方后,跨一个主版本再移除。

窗口长度没有统一标准,但至少要覆盖“别人的发布节奏”。插件由使用者自行安装,不会自动跟随你的版本,所以删除前的等待通常比库作者想象的更久。

DSH plugin 的版本号与变更日志

版本号是索引,变更日志才是迁移依据。(来源)

约定可以很简单:加功能升次版本,修 bug 升补丁,删除或改变已有行为升主版本。但仅靠语义化版本号,调用方无法知道“我要改哪一行”。

变更日志里至少写三段:

  1. 新增了什么 — 哪些方法、字段,从哪个版本可用。
  2. 改变了什么 — 行为差异,尤其是默认值变化。
  3. 删除了什么 — 替代方案与迁移步骤。

三段都写清楚,调用方升级时才能判断自己是否受影响。

一份 DSH plugin 演进自检

发布前过一遍,能挡住大部分“升级即故障”。(来源)

  1. 列出本次改动的所有公开方法、字段与服务名,逐项问“老调用方不改代码还成立吗”。
  2. 检查是否有必填字段新增、是否有可选字段收紧。
  3. 检查枚举是否新增取值,消费方的穷举分支是否会漏。
  4. 检查弃用是否有标记、告警与替代方案。
  5. 检查变更日志是否写了新增、改变、删除三段。

验证:新旧调用方并存

同一份 service,用旧约定与新约定各调一次,结果应当一致。(来源)

  1. 保留一个只按旧字段构造请求的调用方,升级插件后断言它仍能正常调用。
  2. 用新字段构造请求,断言新行为生效,且旧字段缺省时走默认分支。
  3. 调用被标记弃用的旧方法,断言它仍可用、行为与新方法一致,并产生一条告警。
  4. 给枚举加一个新值,断言旧消费方不会因此崩溃,且新值有明确处理路径。
  5. 删除旧方法后重新加载旧调用方,断言失败信息明确指出缺哪个方法,而不是 undefined。

如果第 1 步失败,说明你把可选字段写成了必填;第 5 步只报 undefined,说明缺少类型或运行时校验,调用方无法自我诊断。

配置侧的演进规则可以对照配置怎么演进;把能力做成 service 的完整写法见自定义服务。

一句话收束: 加法自由——字段可选、方法新增;减法排队——先标记、再并存、最后跨主版本删除;三种破坏性变更都要有迁移路径,变更日志写清新增、改变与删除。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发时给请求对象加一个必填字段,为什么会让老调用方直接报错?

因为 DSH plugin 的老调用方不会传这个字段,而必填意味着缺失即非法。插件之间以 TypeScript 接口协作,运行时也不会替你补默认值;把字段改成可选并提供默认行为,才是兼容的加法。

DSH plugin 的 service 加一个新方法,需要同步改所有调用方吗?

不需要,DSH plugin 的新增方法只要不改动已有签名,就无需同步改调用方。调用方通常只使用自己依赖的方法,新增方法属于纯加法;真正会破坏的是重命名、改参数顺序或改返回值形状,这三类必须走弃用流程。

DSH plugin 插件开发怎么标记一个方法即将弃用,给调用方留出迁移时间?

DSH plugin 的弃用做法是保留旧方法并标注弃用,同时提供新方法,在旧方法里记录一次警告。框架没有强制的弃用机制,约定要靠文档与类型注释;等确认没有调用方后再删除,删之前至少跨一个小版本。

DSH plugin 插件版本号该怎么跟能力变更对应,什么时候该升主版本?

DSH plugin 的版本号约定是纯加功能升次版本,修 bug 升补丁版本,删除或改变已有行为升主版本。插件由使用者自行安装,不会自动跟随上游,所以主版本变更必须在变更日志里写清楚迁移步骤,不能只靠语义化版本号暗示。

相关术语

Service
Service 是挂载在 ctx 上的命名能力,插件用它向其他插件公开方法,调用方通过 inject 声明依赖后获得同一个实例。— DeepSeek Harness 官方文档 - 服务与依赖
inject
inject 是插件声明必需服务的字段,声明后框架会等到服务就绪再执行 apply,服务消失时依赖方自动卸载。— DeepSeek Harness 官方文档 - 服务与依赖
破坏性变更
破坏性变更指会让既有调用方在无改动情况下失效的修改,典型是重命名、改签名与改返回值形状。— DeepSeek Harness 官方文档 - 服务与依赖
弃用窗口
弃用窗口是从标记旧能力到删除它的这段时间,期间新旧并存,调用方可以按自己的节奏迁移。— DeepSeek Harness 官方文档 - 插件与生命周期

来源