开发 dsh plugin 怎么定包名：scope、slug 与 Hub 条目 id 的对应关系

开发 dsh plugin 时，包名、显示名、条目 id 与命令名经常被当成同一个东西，直到第一次改名才发现它们各自牵着不同的引用。 设计命名方案的重点不是起一个好听的名字，而是先确定哪个名字承担身份，哪些名字只是它的投影。

四个名字不是一回事：DSH plugin 的身份分层

包名决定安装与依赖解析，显示名决定用户第一眼看到什么，条目 id 与命令名则决定入口是否稳定。

在 npm 生态里，包名是唯一身份。安装命令、依赖树、锁文件都围绕它展开，一旦发布就很难更改。显示名只存在于界面和文档里，可以随产品定位调整，不会影响已经装好的用户。

条目 id 是市场侧的定位符，用来拼详情页地址；命令名是用户真正敲进终端的那几个字符。后两者都可以和包名不同，但必须能反查到包名，否则用户从条目页找不到安装方式，或者从命令猜不到包。反查关系一旦断了，四个名字就会各自漂移，最后连作者都要靠搜索才能确认它们属于同一个项目。

把四者分开看，命名就不再是起名，而是设计一套可持续的引用关系。这套关系越早写进 README，后面接手的人越不容易改错地方。反过来，如果等到用户开始安装才补文档，往往已经有一批人记住了错误的名字。

实际工单里最常见的混淆，是把显示名当成安装名反馈给用户。用户照着界面上的名字去搜索，搜到的是另一个作者的包，装完自然跑不起来。这类问题表面是文档错误，根子却是四者的映射从来没有被写清楚。

包名是锚点：DeepSeek Harness 插件怎么定 scope 与 slug

先把包名定死，scope、slug 与显示名都从它派生，后续冲突会少很多。

包名通常由 scope 和功能词组成。scope 表达归属，个人开发者可以用自己的 ID，团队则用组织名，保持同一作者的所有插件一致。功能词要短、可读、全小写，用连字符分隔，避免版本号和促销词。

slug 一般由包名去掉 scope 后转换而来，用于 URL 和目录。它不需要和包名逐字相同，但应当一眼看出对应关系。一个实用做法是先在 DSH Plugin Hub 上搜同类插件，看看已有条目的命名习惯，再决定自己的功能词是否过于接近。

如果包名与同类只差一个字符，短期可能蹭到搜索，长期一定会在 issue 和文档里被反复混淆。命名冲突的代价不会立刻出现，而是在用户报告装错包的那一天集中爆发。到那时再改名，已经发布的版本、教程和脚本都成了迁移对象。

定名之前，最好在 npm 上实际搜一次，而不是凭印象判断。带 scope 的包还要确认组织是否有发布权限，否则名字再合适也发不出去。这些检查花不了几分钟，却能避免推到一半才发现要重来。

DSH plugin 的显示名、条目 id 与命令名如何从包名派生

三者都可以不同，但每一个都要能指回包名，这是映射关系的底线。

显示名可以带空格与大小写，面向人类阅读；条目 id 通常是小写连字符，面向 URL；命令名则要短到适合反复输入。三者不一致并不可怕，可怕的是没有任何一处文档说明它们的对应关系。用户从任何一个入口进来，都应该能猜到另外几个名字长什么样。

一个简单原则是：包名里出现的功能词，至少在显示名或命令名里保留一次。这样即使名字被翻译、缩写或改写，搜索和反查仍然能找到同一个插件。反过来，如果三个名字各用一套词，再完整的文档也救不回用户的困惑。

映射表里最容易被低估的是命令名。它看起来只是终端里的一个别名，实际上会被写进脚本、CI 配置和别人的笔记。命令名一旦变化，报错往往出现在与插件开发完全无关的项目里，排查成本比改显示名高得多。

改名的代价：DSH插件 旧入口的迁移窗口

改名不是替换字符串，而是要同时处理已安装用户、旧链接和写死命令的脚本。

包名一改，旧依赖会立刻断掉，锁文件里的旧名字也不会自动迁移。比较稳妥的做法是先发布一个迁移版本，让旧包继续可装，但启动时提示新包名与安装命令。这个窗口通常需要覆盖一个完整的升级周期。

条目 id 与命令名同理。旧详情页如果直接 404，外部引用和搜索结果都会失效；旧命令如果突然消失，自动化脚本会在半夜报错。能配置重定向就配置，不能配置就至少保留一个会打印迁移说明的占位入口。

改名的成本主要不在代码，而在所有引用过这个名字的地方。DSH插件 的作者如果早期就把映射关系写进 README，迁移时会轻松很多，也不会出现新旧两套文档互相打架的情况。真正麻烦的是那些没有仓库记录的用法，例如别人脚本里的一行命令。

迁移窗口的长度没有统一标准，但至少要覆盖用户的一次正常升级。窗口太短，很多人还没看到通知就已经装不上；窗口太长，维护两套名字又会持续消耗精力。比较务实的做法是设定一个明确的截止日期，并在旧包的启动信息里反复提示。

把映射写进文档：DSH plugin 的 README 约定

再好的命名，如果没有写进文档，下一位维护者仍然要从代码里反推四个名字的关系。

README 开头用一行写清包名、显示名、条目 id 与命令名，比写一大段产品介绍更有用。安装命令紧随其后，确保用户复制的那一行与当前发布版本一致。很多装错包的问题，源头就是文档里的安装命令还停留在旧名字。

文档还应该说明哪个名字是稳定的、哪个可能变化。包名和命令名属于承诺，显示名与条目 id 可以调整；把这条边界写出来，用户才知道升级时该固定什么。没有这层说明，任何一次改名都会被理解成破坏性变更。

Hub 条目也要能和仓库互相指路。条目页给出包名与安装命令，仓库首页给出条目链接，两条路径形成闭环。只在一侧维护映射，另一侧迟早会变成过期信息。

最后，把这份映射纳入发布检查。每次发版前对照一遍 README、Hub 条目与实际命令，发现不一致就先改文档再发版。命名设计的价值，最终体现在这些不起眼的核对动作里。

上架前的命名检查：DeepSeek插件 最容易踩的冲突

命名检查不是形式主义，它决定审核被打回几次，也决定用户能不能顺利安装。

提交之前，先把四个名字写成一行映射，再逐项验证。写不出这行映射，说明命名还没有收敛；映射里出现两个不同的功能词，说明定位还在摇摆。这一行文字也能直接放进审核说明，省去来回解释的时间。

1. 在 npm 搜索包名，确认没有同名或只差一个字符的包。
2. 在 Hub 搜索 slug 与显示名，确认不与同类条目混淆。
3. 用条目 id 打开详情页，确认能反查到包名与安装命令。
4. 在干净环境里执行安装命令，确认命令名与文档一致。
5. 把映射关系写进 README，作为后续改名的依据。

五项都过再提交，比被打回后反复修改便宜得多。DeepSeek插件 的命名问题往往不是创意不足，而是四个名字各说各话，最后连作者自己都要翻代码确认。把检查结果贴进提交说明，审核者也能一眼看出映射是否闭合。

来源：开发第一个插件、DSH Plugin Hub 插件条目、npm @deepseek-ai/dsh。