开发 dsh plugin 怎么避免工具名冲突：DeepSeek Harness 命名空间、前缀与排查

dsh plugin 的工具名冲突很少以「冲突」两个字出现，它更像一次莫名其妙的调用失败。 两个插件都注册了 search，模型却把请求发给了后装的那个，日志里只剩一行看起来正常的工具清单。DeepSeek Harness 里工具名就是调用契约，名字重叠，契约就换了主人。

两个 dsh plugin 同时注册 search 之后

调用打到错误实现，通常不是模型选错，而是注册表里同一个键只剩一个值。

我最早遇到这件事，是在一个笔记插件和一个本地检索插件同时启用之后。单独装任何一个都正常，两个一起装，笔记插件的 search 开始返回检索插件的结果，参数结构还对不上。 调用方看到的是「参数错误」，而不是「工具重名」，所以第一反应很容易跑偏到提示词上。把其中一个插件停掉，错误立刻消失，这才把怀疑对象拉回注册环节。

工具注册的本质是往一张表里写键值。工具名是键，插件提供的实现是值，键相同的时候，表里不会出现两行，只会有一行被后来者覆盖，或者后来者直接注册失败。 具体是覆盖还是失败，取决于加载顺序和运行时对重复项的处理策略。DeepSeek Harness 的日志通常只在启动阶段提一句，之后所有调用都按最终那张表走。

这就是为什么故障看起来像「模型变笨了」。模型拿到的工具描述可能来自 A，实际执行却是 B，返回值自然对不上预期。 参数校验、权限检查、结果格式都在错误的实现里发生，报错信息也就指向了错误的方向。只看单次调用，几乎无法判断问题出在名字上。

想快速确认，把变量压缩到只剩「启用组合」。只开 A 跑一次，只开 B 跑一次，再同时开跑一次；如果同时开的结果既不等于 A 也不等于 B，或者随启用顺序变化，基本可以认定是撞名。这个对照实验比读十遍日志都快，也更适合在别人的机器上复现。

在日志里认出 dsh plugin 的注册冲突

日志不会写「你撞名了」，它只会留下注册顺序和一份被覆盖过的工具清单。

先把启动日志按插件名分组。正常注册通常是一条插件加载记录跟着若干条工具注册记录，撞名时会出现两种异常：某条注册记录后面跟着 already registered 之类的提示，或者两个插件都加载成功，但工具总数比预期少。后一种最容易被忽略，因为没有任何错误级别。

1. 在启动日志里搜 duplicate、already registered、override 三个词，先看有没有直接提示。
2. 找到工具清单输出，确认 search 这一行归属哪个插件，而不是只看它是否存在。
3. 调一次出问题的工具，把入参和返回值与两个插件的文档分别对照。
4. 交换两个插件的启用顺序重启，观察错误是否跟着顺序变化。
5. 只保留一个插件复跑同一请求，确认行为回到预期。

这几步里，最有信息量的是交换顺序。覆盖型冲突会随着顺序翻转而换实现，报错内容也跟着变；注册失败型冲突则表现为「谁先加载谁赢」，后加载的插件工具直接不在清单里。两种表现对应两种改法。先分清再动手，能省掉很多无效改名。

必要时把完整工具清单导出来做 diff：一份只开 A，一份只开 B，一份全开。三份清单里同名但描述不同的条目，就是嫌疑对象。把这个 diff 贴进 issue，比贴一句「工具调用不对」有用得多，维护者一眼就能看出是名字问题还是实现问题。

给 dsh plugin 的工具起名：几种取舍

起名没有唯一正确答案，但「通用词裸奔」几乎总是最差的选择。

给工具起名时，我在可读性和唯一性之间来回权衡。名字太短，用户好记，但生态里所有人都会想到同一个词；名字太长，唯一性上去了，调用示例又变得难读。 比较务实的做法，是先按插件规模选一种策略，再保证同一插件内部风格一致。

单点工具适合短前缀，成组工具适合命名空间，两者也可以叠加。真正要避免的是「一半加前缀、一半不加」，这种混合风格会让读者以为没前缀的那些是内置工具。前缀本身不必追求极致短，稳定比短更重要，因为用户脚本记的是完整名字。

还有一种隐性冲突来自依赖插件。你自己的插件只注册了两个工具，但依赖链里某个包可能也注册了同名工具，而且在你之前加载。排查时不要只看自己的代码，把启用插件列表整个过一遍，尤其是那些「装上就忘了」的辅助包。

旧 dsh plugin 改名时怎么不伤用户

改名最贵的部分不在代码，而在别人已经写好的脚本和提示词。

一个已经上架的 DSH插件 改工具名，影响的远不止自己的仓库。用户的工作流里可能硬编码了旧名字，提示词里也可能反复提到它。 代码里改一行、文档里改一段，看起来干净，实际是把迁移成本转嫁给了使用者。

比较稳妥的做法是保留旧名一段时间，让新旧两个名字指向同一实现，并在文档里标注弃用时间。如果运行时不允许注册别名，就在插件层做一次转发：旧工具名接收参数，转调新实现，并在日志里提示一次。这样脚本不会立刻断，作者也能观察还有多少人在用旧名。

改名公告要写清楚三件事：旧名、新名、最后支持旧名的版本。只写「重命名了工具」等于没说，用户不知道要不要改、什么时候改。很多 DeepSeek插件 的升级事故，最后都落在这种信息缺口上，而不是代码本身。

把命名检查写进 dsh plugin 的发布流程

把撞名检查放在发布前，比放在用户报障后便宜一个数量级。

我的做法是在本地跑一个最小启用集：把自己的插件和一两个常见插件同时装上，启动后导出工具清单，检查有没有同名条目。这个动作不需要完整的测试环境，几分钟就能跑完，却能拦住大部分低级冲突。成本低到可以每次发版都做。

如果团队有 CI，可以把「工具清单快照」纳入构建产物。每次发布前对比上一版，新增工具如果与依赖树里的名字重复，就让构建失败。快照同时还能发现意外删除的工具，避免用户升级后突然少了一个入口。

发布页上也值得放一份工具名列表，并与 DSH Plugin Hub 的条目信息对齐。用户在安装前能核对名字，遇到冲突时也能快速判断该找哪个插件作者。命名是接口的一部分，公开它并不会增加维护负担。

冲突解决之后，dsh plugin 应该留下什么约定

一次撞名值得留下一套约定，而不是一个只在当天有效的补丁。

那次事故之后，我给自己的插件定了两条规矩：所有工具名必须带插件前缀，成组工具再加一层命名空间；新增工具前先在启用清单里搜一遍。规矩不复杂，但它把「想起来才查」变成了默认动作，新同事照着做也不会漏。写下来之后，它就不再依赖某个人记得。

工具名会长期出现在脚本、日志、提示词和用户记忆里，它的生命周期往往比实现本身更长。起名时多花十分钟，后面可能少改很多次。真正难的不是想出一个不冲突的名字，而是让这个名字在几年后仍然说得通。

来源：开发第一个插件、插件与生命周期、npm @deepseek-ai/dsh。