在插件市场里搜到了目标插件,版本兼容检查也通过了,可安装完成后,对应能力却没有出现。 这通常不是插件坏了,而是把三个独立关卡混成了一件事:索引能否解析、插件能否安装、能力能否在运行时被调用。三道检查各自都可能失败。
本文沿着实际链路依次排查:市场索引是什么、为什么看不到 发现 标签、确认框里要核对什么、安装后如何判断是否生效,以及哪些结论超出了现有证据能支持的范围。
一、市场索引只是「可发现的候选项清单」
官方插件市场指南把市场定义得很窄:一份列出可安装 DSH 组合包、版本和展示信息的 JSON 索引。
这会带来三个直接结论:
- 它提供的是发现和安装路径,不是安全结论;
- 标题、作者、描述、图标和来源声明都由市场提供,DSH 只检查索引格式,不验证这些声明;
- 索引里的一条记录存在,只说明「某个索引声称有这样一份产物」,不说明它可用、可信或与描述相符。
因此,严格地说,「市场里有」只是某个索引源声称有。要进一步确认自己能不能安装,还得检查当前 profile 是否配置了这个索引源。
二、发现 标签默认不存在,索引源按 profile 保存
DSH 默认不内置任何索引源。要看到 发现 标签,得先启用实验性的自定义插件市场组合包;关掉这个组合包,标签会一起消失。
还要注意:索引源属于当前 profile。这一点很容易被忽略——
在 A profile 里加过的索引源,不会自动出现在 B profile 里。
所以在动手排查之前,先把三个问题分开问:
- 这个 profile 装了自定义插件市场组合包吗?
- 这个 profile 的
发现里,加了包含目标插件的索引源吗? - 这个 profile 的运行时里,插件真的被加载并注册能力了吗?
三问里任何一问是「否」,后面的现象都会长得一模一样。
添加索引源时的两条硬性要求
文档要求索引 URL 使用 http: 或 https:,且不能包含用户名、密码或片段。
在不受控制的网络上优先用 HTTPS:HTTP 索引以及它给出的安装 spec,都可能在传输中被修改。这不是「建议」,而是一条你能自己验证的边界——索引和安装来源一旦能被中间人改写,「我审过这个包」这句话就不成立了。
另外,指南没有提供通用索引 URL。除非发布者明确说明仓库首页本身就是索引文件,否则不要把首页地址当索引填进去。填错的表现通常是「加了源但搜不到」,很容易被误当成索引内容问题。
三、发现页在替你做什么,以及它不做什么
搜索会匹配名称、作者、关键词,以及各语言的标题、描述、分类和标签;筛选和排序则依据市场声明的元数据。
版本选择的规则是确定的:卡片推荐与当前 DSH 兼容的最高非预发布版本;如果插件没有任何非预发布版本,则推荐最高的兼容预发布版本。打开插件页可以看到完整的列出清单,包括 DSH 接受的旧版和预发布版本。
这里容易产生误解:「推荐了这个版本」只表示兼容性检查通过。这不代表版本经过审计,也不代表市场作者的描述属实。
四、确认框才是唯一的凭据
点安装后先弹确认框,里面列的是:
- npm 来源:包名 + 注册表
- Git 来源:仓库 + 提交 + 目录
确认之后才进入常规安装流程,包括兼容性和注册表检查。未经确认不会安装任何东西。
确认框的关键作用是:它是整条链路上唯一给出「确切产物身份」的地方。卡片标题、描述和图标都可以由市场控制;只有确认框里的包名/提交,才指向你真正将要运行的代码。
因此,审查要落在确认框上:把这些确切标识与你准备信任的代码和发布者逐一核对;不一致或无法判断时取消,不要抱着「先装上再说」的想法继续。
一张对照表:哪些证据能证明什么
| 证据 | 可以用于 | 不能证明 |
|---|---|---|
| 索引格式通过 | DSH 能解析列出的结构 | 插件身份或安全性 |
| 版本兼容 | 版本满足 DSH 兼容性检查 | 代码可信 |
| Git 提交和目录 | 定位要审查的确切来源 | 其他分支或发布版内容相同 |
| Registry 收录 | 寻找候选仓库 | 背书或安全审计 |
这张表建议在排查时直接拿出来用:多数「以为装的是另一个东西」的问题,都能找到一行对上。
五、按顺序走完的五步
- 打开插件,在实验性插件旁点更多,启用自定义插件市场。此时出现
发现标签;关闭组合包后该标签会移除。 - 在发现里选添加索引源,输入你要信任的索引 URL(
http:/https:,不带用户名、密码、片段)。不受控网络上优先 HTTPS。 - 搜索目标能力并打开候选项,核对版本列表与当前 DSH 的兼容性。发现失败时,在管理索引源里查看各来源最近一次的错误。
- 检查确认框里的 npm 注册表与包名,或 Git 仓库、提交与目录,和你要信任的代码、发布者对照。不一致就取消。
- 确认安装,然后在合适的测试环境里验证目标功能,记下来源和版本,供升级时重新审查。
第 4 步不要跳。跳过它的代价不是「多装了一个插件」,而是你的审查笔记和实际运行的产物对不上,后续所有判断都建在错误的前提上。
顺带区分一条容易混的路径:第一个插件教程讲的是从源码加载本地插件,那是开发路径,不是市场安装路径。两者装完的观感相似,出问题的排查方向完全不同。
六、装完没生效:按运行时而不是按市场排查
前面五步都过了,能力还是不出现,这时候问题大概率不在市场,在运行时。
DSH 插件通过上下文注册能力。第一个插件教程展示了 apply(ctx),Cordis 入门说明了服务、依赖、事件和生命周期副作用如何挂上去。这意味着一个插件的影响范围可能远超卡片上的那句话——要看它注册了什么,以及它请求的服务是否被满足。
先确认加载、依赖和能力名称
排查时先回答三个问题:
- 插件是否被加载(而不是仅仅出现在已安装列表里)?
- 它依赖的服务在这个 profile 里存在吗?
- 它注册的能力名称,和你实际调用的名称一致吗?
一个常见的混淆是把「已安装」当成「已加载」。装在磁盘上和注册进运行时是两件事,中间还隔着依赖解析和加载顺序。
七、安装后评估变化:记录什么才有用
一次审查建议记录以下四项:
- 需要的功能(你为什么装它);
- 确切来源与版本(确认框里那串标识);
- 检查过的能力(文件、网络、凭据、命令等);
- 最小测试结果(用了什么输入,看到什么)。
还没查清的问题也要记下来。 这比只写「安装成功」更有用:后来的人可以对照新的提交或包版本,判断哪些结论仍然成立、哪些需要重新检查。
测试要先用非敏感输入。功能正常只能说明被测试的路径正常,不能证明未测试的依赖或操作安全。如果插件要求了意料之外的访问,应当停下来重新评估来源与配置,而不是「反正已经装上了」。
八、升级时必须重做的一件事
出现更新时,要重新检查新版本的确切来源,不能假定此前对旧版的审查覆盖新版本。
理由是具体的:新版本可能改变依赖或行为;Git 来源换了提交,默认分支的代码也可能已经不是你当初审的那份;npm 来源换了包版本,即使包名和注册表一致,选中的产物也变了。
市场版本列表可能提供兼容的旧版或预发布版,方便你留在已审过的版本上——但「兼容」不是「安全」,它只说明 DSH 接受这个版本在当前环境运行。
索引报错时,通过来源管理界面排查,不要把另一个未审查的索引当成等价替代。
九、边界说明
- HTTPS 索引只保护到指定主机的传输,不能证明主机或内容可信。
- 结构有效、兼容性通过、被 Registry 收录,都不是恶意代码扫描。
- 沙箱或审批预设不等于插件行为审计;两者的区别见权限预设。
- 市场元数据属于第三方内容;名字相似不代表两个确认框指向同一产物。
- 索引不可用时,先查错误和来源 URL,不要为了让发现页工作而关闭安全控制。
- 审查笔记和求助日志要排除密钥;评估陌生插件时,用满足需求的最小测试环境。
- 本文依据官方插件市场指南与公开的插件开发文档整理,不是官方支持文档;示例行为可能随版本变化,动手前以你所在版本的官方文档为准。
十、相关术语
- 市场索引:描述插件及可安装版本的 JSON 文档,格式由 DSH 检查,内容由市场提供。
- 组合包:市场列出的可安装 DSH 包;也是启用
发现标签的那个实验性单元。 - Profile:索引源所属的配置作用域;索引源不跨 profile 共享。
- 兼容性:DSH 是否接受该版本在当前环境运行,不是安全背书。
- Cordis:Harness 底层管理插件服务、依赖与生命周期副作用的框架。
理解「确认框」和「运行时」这两个节点很关键——它们是两次责任转移:确认框之前,你能改变的是选哪份产物;确认框之后、运行时之前,决定成败的是依赖与加载;运行时之后,才轮到功能本身是否如描述。
相关阅读
本文依据 DeepSeek Harness 官方插件市场指南与插件开发参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog