dsh plugins 到底指什么：DeepSeek Harness 插件、插件包、市场条目与运行实例四层区分

dsh plugins 在搜索框、安装命令和插件列表里说的并不是同一件事，混着用就会得到互相矛盾的结论。 这里把插件概念、npm 包、市场条目和运行实例四层拆开，说明每层由什么证据支撑，以及排障时先看哪里。DSH插件 的大多数「装了没用」，其实是后两层没有走完。

dsh plugins 的四层含义，为什么不能混着说

四层不是同一个对象的四个名字，而是四种粒度不同的事实。

概念层描述的是一类能力，比如「让工作区多一个代码审查入口」，它回答插件能做什么，而不是某个具体版本能不能装。文档和 README 都停留在这一层，写得再细，也不会承诺你手上的 CLI 版本一定支持。选型阶段看概念层没有问题，拿它当安装依据就容易失望。

包层是分发单位，有唯一包名、版本号和依赖树，npm 上的元数据与 lockfile 里的记录都属于这一层。判断两个入口是不是同一个插件，最可靠的办法是对包名，而不是对显示名。安装、升级和回滚都发生在这一层，所以它也是四层里身份最稳定的一层。

条目层是 DSH Plugin Hub 里的展示信息，包含显示名、作者、分类、截图和简介，负责让人发现和比较。这些字段由作者维护，可以改名、换图、调整描述，因此它适合用来找插件，不适合用来做唯一标识。一个条目通常对应一个包，但条目名和包名对不上是常态。

实例层是插件被某个 profile 加载之后形成的运行对象，有自己的配置和状态，可能处于 PENDING、ACTIVE 或 FAILED。同一份包在 web 和 desktop 两个 profile 里可以各有一个实例，互不影响。包装上了不等于实例起来了，这正是「列表里有、界面里没有」的根源。

从 DeepSeek Harness 文档到运行实例，每层该看什么证据

每一层都有独立证据，跨层推断就是误会的起点。

概念层的证据是文档和示例，它能告诉你能力边界，却证明不了某个版本已经发布。包层的证据是 npm 页面和 lockfile，包存在、版本可解析，才谈得上安装。条目层的证据是市场页面，实例层的证据则是 dsh plugin list 与状态输出，四者不能互相替代。

把四层放在一起对照，最容易看清哪种说法只走到了哪一步。表格里的「不能证明什么」一列，值得在每次争论时反复引用。任何一层缺失，都只能称为线索，而不是结论。

最常见的跨层推断，是看到市场里有条目就以为本机已经可用。条目页会展示版本和安装命令，但不会读取你的 profile，也不会告诉你插件停在了 PENDING。在 DSH Plugin Hub 的插件条目 里核对包名之后，仍然要回到命令行确认实例状态。

反过来，只盯着命令行也会漏掉信息。dsh plugin list 能说明本机装了什么、跑没跑起来，却不会告诉你市场里有没有更合适的替代品，或者这个包是否已经停止维护。证据要成组出现，结论才站得住。

DSH插件 装上了却搜不到，通常是哪一层断了

搜不到、装不上、不生效是三个不同层的故障，先分清再动手。

「搜不到」大多发生在条目层，可能是关键词不对，也可能是插件根本没进市场索引，此时换包名搜索往往更快。DSH插件 的显示名经常和包名不一致，用中文描述搜不到，不代表插件不存在。先拿到准确包名，再回市场或 npm 验证，能省掉很多无效尝试。

「装不上」属于包层问题，常见原因是版本不存在、registry 配置不对，或者依赖冲突导致解析失败。这时看安装命令的完整报错，比反复点安装按钮有用。装完之后用 dsh plugin list 对照包名和版本，才能确认落盘的是你想装的那一个。

「不生效」则要落到实例层，先确认目标 profile 是否启用了插件，再看状态是不是 ACTIVE。页面没刷新、客户端缓存未更新，也会造成已经加载但界面没变化的假象。把这三类故障分开之后，排查就不用在四层之间来回跳。

DSH plugin 的包名与市场条目为什么会对不上

显示名是给人看的，包名是给机器用的，两者本来就不要求一致。

作者给插件起一个顺口的显示名，同时把包发布在某个 scope 下，这两件事可以独立决定。市场条目里通常会给出安装命令或包名，那才是安装时真正生效的字符串。只记住显示名，换一台机器就可能装到同名但不同作者的插件。

另一个常见落差是版本。条目页展示的版本可能滞后于 npm 的最新发布，也可能只列了稳定版，而你想装的是预发布版。遇到这种情况，以包和 lockfile 为准，条目只作为线索。把条目当权威，会在「市场说 1.4，命令行装到 1.5」时产生不必要的怀疑。

需要长期维护的项目，最好把包名和版本一起写进项目文档，而不是只留一个市场链接。链接会改版，包名和版本不会无缘无故消失。等到交接时，这份记录比任何截图都更容易核对。

DSH plugin 出问题时，按什么顺序查最省时间

从实例往上查最快，因为它是最终事实，而包和条目都只是候选。

拿到一台出问题的机器，先别急着重装。按下面的顺序走一遍，通常两三步就能定位到层，剩下的时间用来验证而不是猜测。顺序本身不复杂，难的是每一步都留下可核对的输出。

1. 运行 dsh plugin list，记下包名与版本，先确认目标插件确实在列表里。
2. 看实例处于 ACTIVE、PENDING 还是 FAILED，失败信息往往直接指向原因；状态对不上时不要急着重装，先把这条输出留作后续对照。
3. 确认这个实例从哪个 profile 加载，别在另一个 profile 里找同样的包。
4. 用包名去 npm 或 lockfile 核对版本，排除被解析成别的范围；版本一致，再检查条目页上的兼容声明与维护状态。

条目层的核对只用来判断值不值得继续追，不能替代本机状态。把断掉的层与对应证据写下来，下次遇到同类问题可以直接复用。若条目页显示的版本落后于 npm，就以包和 lockfile 为准，条目只当线索。

如果清单里根本没有目标包，问题就停在包层，先去确认包名与 registry，而不是继续查实例。反过来说，包在、状态是 ACTIVE，却仍看不到界面变化，就要去看客户端缓存与页面刷新。把「有没有」「跑没跑」「看不看得见」分开记录，结论才不会互相污染。

顺序不是死的，如果报错已经明确指向安装失败，就从包层开始。真正要避免的是在没有证据的情况下重装、换版本、清缓存一起上，最后不知道哪一步起了作用。把每一步的结果写下来，比记住「好像试过」可靠。

把四层词汇用进 DeepSeek插件 的日常沟通

说清楚「哪一层」比争论「到底装没装」更能推进问题。

和同事描述问题时，带上层名会省很多来回。说「条目层搜不到这个包」，对方就知道该去查市场索引；说「实例层停在 PENDING」，对方会去看 profile 和加载日志。DeepSeek插件 的排障讨论一旦落到具体层，争点会立刻收窄。

写 issue 或内部记录时也一样，把包名、版本、profile 和状态四样写全，比贴一张截图更有用。截图能说明现象，字段才能复现。四层词汇的作用不是显得专业，而是让每个人指向同一个对象。

还有一个附带好处：当你需要换插件时，层名能帮你判断迁移成本。只换条目就是换一个发现入口，换包才涉及安装和依赖，换实例则要重做配置。提前说清楚要动哪一层，评审时就不会把一次小替换误判成大改造。

最后留一个简单的自检：当你说「这个插件有问题」时，能不能补上包名和 profile。补得上，说明你在描述事实；补不上，说明还停在概念层，需要先把它落到具体的包和实例上。这大概也是四层划分最实际的用处：让模糊的描述变成可以核对的对象。

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