dsh-plugin-shop 是 DeepSeek Harness 的插件商店，除了每天采集 npm 包，它还开通了一条github: 直装通道：没有发布 npm 包的插件，只要把 GitHub 仓库配置好，就能被收录进目录，用户点击安装时由商店拼出github:owner/repo#commit这样的地址直接装好。本文用大白话讲清这条通道的收录条件、commit 钉住原理和安全设计，也教你一步步让仓库插件成功上架。

为什么需要 github: 直装通道？

很多插件作者只把代码放在 GitHub 上，不会发布到 npm。对这类插件，商店如果只盯着 npm 采集，就永远看不见它们。于是商店在每日构建时并行跑两条采集线：一条扫 npm 关键字，另一条扫带dsh-plugin或deepseek-harness主题标签（topic）的 GitHub 仓库。

但"能采集"不等于"能安装"。团队曾抽查 90 个带 topic 的仓库，发现一个危险的数字：42% 的仓库连dsh.bundle都没声明——pnpm 安装会"成功"退出，但 dsh 注册不到任何插件，用户重启后看到一片空白。商店的做法是把这类仓库在采集阶段就拦下来，只把真正可安装的那 20% 放上货架。

上架条件：你的仓库要满足什么？

想让 GitHub 仓库插件进入目录，需要满足几个硬性条件（详见 docs/schema.zh.md）：

1. 加 topic：给仓库添加dsh-plugin或deepseek-harness主题标签；
2. 根目录package.json声明name和dsh.bundle：缺了dsh.bundle会被判为no-bundle拒绝——这是防止"静默安装失败"最关键的一条规则；
3. 不能需要构建脚本：声明了prepare/prepack脚本的仓库会装不上，因为商店绝不放开构建脚本执行；
4. 有许可证，且有可展示的描述（仓库描述或dsh.catalog简介均可）。

全部检查逻辑集中在 registry/scripts/src/repo-gate.ts 这个纯函数模块里：每个被拒的仓库都会记录名称和一份"作者可读"的具体原因，写进每日构建报告，方便排查。

monorepo 也可以上架：把dsh.bundle写在实际提供插件的子包里，商店会以github:owner/repo#commit&path:子目录的形式安装。

commit 钉住：GitHub 插件的"版本"是什么？

npm 包用语义化版本号，GitHub 条目则把默认分支的一个具体 commit（40 位哈希）钉住作为版本，卡片上只显示前 7 位短 commit。这样做的好处是：

• 精确且永存在：commit 不会因为分支重写而消失，装到的内容和你看到的就是同一份；
• 每日可更新：仓库有新提交后，下次构建重新钉住新 commit，商店里的"更新"按钮会驱动你装上更新的 commit。

安装后，宿主端（Host）会在本地缓存里记下这个仓库当时装了哪个 commit，见 packages/dsh-plugin-shop/src/host/repo-pins.ts——这样即使仓库后续更新了，商店也能如实告诉你"已安装版本落后"。

安装流程：github:地址是怎么拼出来的？

这是这条通道最有安全价值的设计。商店的界面端（Client）没有任何网络和文件系统权限，它只把"条目名 + 版本"发给本地宿主端；真正的安装命令永远由宿主端自己拼装：

• npm 条目拼成name@version；
• GitHub 条目拼成github:owner/slug#<40位commit>（子包再加&path:<dir>），所有字段都来自刚校验过的目录快照，客户端传入的任何字符串都不会被直接拼进命令行。

也就是说，商店不存在"从任意 URL 安装"的入口，你点安装时能装到的地址只有一个，且经过校验。相关实现位于 packages/dsh-plugin-shop/src/host/index.ts。

还有一个反直觉的细节：安装不需要本机装有 git。pnpm 解析github:地址时走的是 GitHub 的 tarball 接口，而不是git clone。团队曾专门测试：把 git 命令故意弄坏后，pnpm 9、10、11 三个版本都能顺利装好github:owner/repo#commit。这也解释了为什么仓库条目不需要"git 缺失"预检。

安装完成后，商店还会做"装后确认"：如果仓库在快照和安装之间改掉了dsh.bundle，安装会明确失败并给出证据，而不是像 42% 那种仓库一样悄无声息地什么都不做。

安全细节：信任等级与确认弹窗

• 信任等级不继承：人工评审只绑定"某个仓库 + 某个 commit"，换任何 commit 都会降级，防止作者拿一次评审为后续恶意版本背书；
• 每次安装前确认：所有条目默认属于社区级别，安装前都会弹出权限说明弹窗（见上图），明确告知插件可访问文件系统、shell 和发往模型的请求——商店不提供沙箱隔离；
• 防仿冒拦截：与已收录包名过于相似（编辑距离过近）的仓库名会被拦截，等待人工裁定。

如何让你的 GitHub 仓库插件上架？

三步操作，无需向本项目提交任何申请：

1. 给仓库添加dsh-plugin或deepseek-harnesstopic；
2. 在根目录（或 monorepo 子包）的package.json中声明name和dsh.bundle，例如{ "patch": "./cordis.patch.yml" }；
3. 注意：bundle 要加载的文件必须真实存在于被钉住的 commit 中——被.gitignore排除的dist/目录会直接导致拒绝。

第二天早上构建跑完后，插件就会出现在商店货架上；如果没有出现，去每日构建报告里查一下被拒的具体原因即可。完整的字段说明和常见问题可参考 docs/schema.zh.md，通道的完整设计决策（包括为什么选 commit 而不是 tag 钉住）记录在 docs/design/2026-08-30-github-install-channel.md。

💡 一句话总结：github: 直装通道让"只有仓库、没有 npm 包"的插件也能被安全地发现、筛查和安装——商店替你钉住 commit、替你拼好地址，你在确认弹窗前看清单即可。