插件市场索引 REALOIYO/dsh-plugin-market

DSH 插件市场索引（format 1）

一份自建的 DSH 插件市场索引，收录 npm 上可发现的 DSH 组合包（bundle）。

规模：7,123 个插件 / 58,629 个版本，索引文件 9.5 MB。
来源：npm registry 公开元数据（包名、版本、发布时间、dsh.bundle 声明、仓库地址）。
热度：6,349 / 7,123（89.1%）带星数或下载量指标——星数取自 GitHub API，下载量取自 npm API。
更新：GitHub Actions 每 6 小时自动重建一次（UTC 0/6/12/18），也可以手动触发。

标题与描述都是双语对象（{ "en": ..., "zh": ... }），DSH 按界面语言显示：

"title": { "en": "DSH Plugin Index", "zh": "DSH 插件索引" }

格式允许 title 用纯字符串，但那样中英文界面只能显示同一句话。
校验器要求双语对象必须含 en，且语言 id 必须小写。

仓库里的 example-subset.config.json 是示例配置，用于配合
node build-index.mjs --config <文件> 生成只含指定插件的子集索引。
日常构建不读取它。

插件是怎么被收录的

索引不是手工维护的列表，每次重建都会重新发现一遍：

1. 社区目录种子 —— seeds/dsh-so.json 里的已知包名，覆盖社区已有的插件；
2. npm 关键词搜索 —— 用 keywords:dsh-plugin 在 npm 搜索接口翻页，抓取种子之外的新包。

两个来源合并后，逐个拉取 packument，只保留 package.json 里声明了 dsh.bundle 的包。
声明了才算可安装的 DSH 组合包，因此搜到的同名干扰包会被自动丢弃。

每次运行搜索补充约 3,000–3,400 个种子之外的候选，其中约 1,000 个是新增的可安装 bundle （具体数量随 npm 上新包变化，不固定）。

关键词只保留 keywords:dsh-plugin。抽样 750 个包全部带该关键词（精确率 100%）， 250 抽样里 239 个（95.6%）声明了 dsh.bundle。keywords:dsh 总量更大（11,003）但 dsh 三字母在其它语境也常用，会混入大量非插件包并把索引撑大一倍，故未采用。

为什么要按切片搜索

npm 搜索接口有两个硬限制，导致单靠翻页拿不全：

- 翻页会绕回开头 —— from 超过约 5000 后，接口从头重复返回第 0 页（实测 from=5250 与 from=0 返回的 250 条完全重合）。keywords:dsh-plugin 声明有 8,782 个结果，直接翻页最多只能拿到约 5,250 个。
- 连续请求会 429 —— 没有 Retry-After 也没有限流响应头，只能靠失败后退避。

published: 这类过滤器不能用来切片：它只改变排序起点、不做真正的结果过滤（实测 12 个月切片并集仅 560 个）。但把裸词叠加进 text 会真正参与匹配，因此改用「单字母 / 数字 / 常见词」做切片，每片独立翻页，最后取并集。

当前切片：基线 + a–z + 0–9 + dsh- plugin bundle agent skill tool mcp ui web。
基线切片保留是必须的 —— 否则会漏掉不与任何切片词匹配的包。

索引地址

https://realoiyo.github.io/dsh-plugin-market/index.json

填在哪里

DSH → 设置 → 插件 → 发现 → 添加索引源 → 粘贴上面的 URL。

DSH 拒绝重定向，所以不要用短链或会 301 的地址，必须是最终地址。

改了索引但客户端没变？

DSH 把索引缓存在进程内存里，默认 10 分钟（cacheTtlMs = 600000ms），没有任何磁盘缓存。所以：

- 每次重建后，客户端最多滞后 10 分钟；
- 如果插件数、标题看起来还是旧的，重启 DSH 最直接；
- 服务端已更新时，可直接验证： curl -s https://realoiyo.github.io/dsh-plugin-market/index.json | head -c 200 或看文件的 Last-Modified 响应头。

这个格式是什么

DSH 从 URL 拉一份 JSON，用 @deepseek-ai/dsh-plugin-market-index 按「插件市场索引格式 1」严格校验。
任何一条规则违规，整份索引都会被拒绝，错误会带 JSON 路径。

它不是 npm 的 index.json，也不是任何网站的首页 —— 是一份专门描述「有哪些可安装 bundle」的清单。

兼容性是怎么判的

索引里每个版本都带一个 engines.dsh SemVer 范围，DSH 用它决定是否允许安装。
判断规则必须与 DSH 自身一致（dsh-app-boot 的 unmetRequirements）：

1. 包里有 engines.dsh → 只认它，peerDependencies 被忽略；
2. 没有 engines.dsh → 逐个检查 @deepseek-ai/dsh 和 @deepseek-ai/dsh- 的 peerDependencies，全部满足才算兼容。

比较时使用 semver.satisfies(runtime, range, { includePrerelease: true })—— 预发布版本参与范围比较，这一点很容易踩错：不加 includePrerelease 时，"" 对 0.2.1-rc.2 会返回 false，导致几乎所有插件都被误判为不兼容。

生成器把多个 peer 范围取交集合并成一个范围（索引格式只允许一个 engines.dsh 字段）。
实测同一版本的多个 dsh peer 范围几乎总是一致的，所以取交集在实践中等同取任意一个。

2026-10-18 修复：生成器此前只读 engines.dsh、完全不读 peerDependencies，导致 3,603 个插件的兼容声明缺失，其中 1,760 个被错误地显示为「兼容」而实际不支持当时的运行时。修复后 engines.dsh 覆盖从 10.1% 提升到 60.5%。
这就是「从索引点安装几乎没成功过」的主要原因之一。

为什么不能在线更新

这不是索引的问题，是 DSH 的限制。官方 plugin-manager 只暴露 installBundle 和 removeBundle，没有 updateBundle；官方 README 也写明「不支持升级 —— 升级仍需先卸载再安装」。

dshmarket 这类第三方市场通过别的路子绕过了：它不用 installBundle，而是直接跑 dsh plugin update <name>（底层是 pnpm update），从而原地升级。本索引是纯静态 JSON，不跑任何命令，因此无法提供更新按钮。

排序

索引声明了两个排序键，界面里「排序」菜单会出现：

| 排序键 | 含义 | 默认方向 |
| stars | GitHub 星数 | 降序 |
| downloads | npm 周下载量 | 降序 |

值来自两部分：星数取自 GitHub API（stargazers_count）并按仓库 URL 匹配到包，下载量取自 npm 官方 downloads API。

热度指标是怎么来的

索引里只有 stars 和 downloads 两个数值，DSH 用它们排序，并折成卡片上的标签（★ 100+、↓ 1k/wk 之类）。采集分两步：

1. 星数 —— tools/fill-stars.mjs 读每个包的 repository.url，取 owner/repo 调 GET /repos/{owner}/{repo}，只取 stargazers_count。
同一个仓库被多个包引用时只查一次；只处理尚无指标或尚无星数的包。
2. 下载量 —— tools/fill-downloads.mjs 调 npm 的 GET /downloads/point/last-week/{package}。

为什么要认证

GitHub 未认证的 API 限额是 60 次/小时，补几千个仓库会立刻用尽并返回 403。认证后提升到 5,000 次/小时。实际需要查询的是去重后的仓库数（通常在 1,000–1,300 之间，随插件增减变化），并发 8 时约 1–2 分钟跑完。

脚本只从环境变量 GITHUB_TOKEN 读取令牌，不接受命令行参数，也不写入任何文件：

本地：从本机 git 凭证管理器取（Windows）
GITHUB_TOKEN=$(printf 'protocol=https\nhost=github.com\n\n' \
| git-credential-manager get | grep '^password=' | cut -d= -f2-) \
node tools/fill-stars.mjs index.json metrics.json metrics-out.json

Actions：用内置令牌，无需创建任何 secret
- env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: node tools/fill-stars.mjs index.json metrics.json metrics-out.json

Actions 的 GITHUB_TOKEN 限额是每仓库 1,000 次/小时，按当前规模够用。

隐私

- 不写入任何本机信息：脚本只读到仓库 slug 和星数，输出里没有路径、用户名或令牌。
- 令牌不落盘：只存在于进程环境变量中，不写日志、不写中间文件。
- 索引可公开：tools/audit.mjs 会扫描结构字段，确认没有本机路径、内网地址或凭据。
剩余 788 个插件没有指标，原因是作者没填 repository.url（623 个）或仓库已删除/私有（165 个），这些缺口无法通过 API 补上。

两者都是生成时的快照，随每次重建更新。

没有某个值的插件会排在所有有值的插件之后（这是 format 1 的规则，不是本仓库的选择）。

三条命令的工作流

node build-index.mjs # 从 npm 生成（首次约 10 分钟）
node tools/check.mjs index.json # 用 DSH 原版校验器验
node tools/audit.mjs index.json # 查本机路径/内网地址/凭据

tools/check.mjs 里的校验器是从你本机 DSH 的 app.asar 现场解出来的，判定结果与 DSH 完全一致，又不必把第三方代码提交进仓库。

node build-index.mjs --from-cache 可复用 .cache/digest.json 秒出结果。

数据是怎么来的

1. 候选包名：两部分合成 —— seeds/.json（当前 seeds/dsh-so.json 共 4,868 个包名），加上 npm 搜索接口按切片翻页补到的包（见上文「为什么要按切片搜索」）。
2. 逐个抓 packument：拿完整版本历史、发布时间、dsh 字段。
3. 立刻压缩：抓到一个就抽成索引条目（几百字节），原文立即丢弃。
因此内存占用与插件数量无关 —— 早期版本把 1.8 万个 packument 全攒在内存里会 OOM。
4. 只保留真能装的：必须有至少一个版本声明了 dsh.bundle，否则装了也不生效。

覆盖与可信度

与 dsh.so 的独立安全扫描交叉比对（tools/cross-check.mjs index.json dshso.json）：

| 指标 | 数值 |
| 本地索引插件 | 7,123 |
| dsh.so 可匹配 | 4,833（67.9%） |
| 其中已安全扫描 | 4,755 |
| 风险 low | 4,706 |
| 风险 medium | 49 |
| 风险 high / critical | 0 |
| 无安全扫描结论 | 2,290（32.1%） |

也就是说：

- 每个收录的包在 npm 上都真实存在（抓取时已验证）；
- 但第三方安全扫描只覆盖 67.9%。另外 2,290 个插件是后来通过 npm 关键词搜索新发现的， dsh.so 的目录里还没有它们，因此没有任何安全结论。

这个缺口不是缺陷，是两份目录的收录范围不同：dsh.so 是人工维护的白名单，本索引是无差别的全量抓取。安全结论缺失不等于有风险，但也不等于安全。

字段说明

根字段

| 字段 | 必填 | 规则 |
| format | ✅ | 必须是整数 1 |
| title | ✅ | 字符串，或含 en 的本地化对象 |
| description | | 同上 |
| metadata.categories / labels / sortKeys | | 声明后插件才能引用 |
| plugins | ✅ | 数组，顺序即默认排序 |

插件字段

| 字段 | 必填 | 规则 |
| name | ✅ | 合法 npm 包名，索引内唯一 |
| title / description | | 字符串或含 en 的对象 |
| icon | | 相对路径、https: URL，或 data: (≤32 KiB) |
| author / homepage | | 非空字符串 / 绝对 http(s) URL |
| repository | | { url, directory? }，仅展示用；directory 只能是 [A-Za-z0-9._@+-] 段，不能是 . 或 .. |
| metadata.keywords | | 自由字符串数组，无需根声明 |
| dist-tags | | 目标必须是已列出的版本 |
| versions | ✅ | 非空数组 |

版本字段

| 字段 | 必填 | 规则 |
| version | ✅ | 精确 SemVer，不可重复 |
| publishTimestamp | ✅ | 整数 Unix 秒（写毫秒会被拒） |
| source | ✅ | { "type": "npm" } 或 { "type": "git", url, commit, path? } |
| engines.dsh | | SemVer 范围，禁止 workspace: 前缀 |

git 来源的 commit 必须是 40 位小写十六进制 SHA。

安装行为

| 来源 | 给 pnpm 的 spec |
| npm | <name>@<version> |
| git | git+<url>.git#<commit>，有 path 时加 &path:/<path> |

默认版本 = 最高兼容版本（优先非预发布）。dist-tags.latest 只影响渠道显示， 绝不会装 name@latest，每次安装都固定到具体版本。

常见报错

| 报错 | 原因 |
| $.format must be 1 | 漏写 format: 1 或写成了 "1" |
| $.title must contain en | 用了对象但没写 en |
| must be an integer number of Unix seconds | publishTimestamp 单位错了 |
| must not be a workspace: range | engines.dsh 写了 workspace: |
| references undeclared id | 用了没在根 metadata 声明的分类/标签/排序键 |
| must be a valid npm package name | 包名有大写/空格 |
| directory must be a relative directory | repository.directory 是 . 或含非法字符 |
| Could not fetch / HTTP 4xx | URL 错、需登录、或被重定向 |

安全说明（重要）

- 索引没有签名。title、author、标签全是「声明」，不等于 DSH 验证过。
- 索引内容未经审核就会显示给你，并通过 plugin_market 工具传给模型。
- 插件安装后以你的权限运行，可能含构建脚本。
- 每次安装都会重新检查源 manifest，装的是包自己声明的东西 —— 索引只是目录，不是担保。
- 本索引只固定「包名 + 版本」，不镜像任何插件代码。

目录结构

index.json 生成的索引（提交进仓库） build-index.mjs 生成器 market.config.json 标题/分类等配置 seeds/ 候选包名来源 tools/check.mjs 用 DSH 原版校验器验证 tools/audit.mjs 发布前隐私自检 tools/cross-check.mjs 与 dsh.so 安全扫描交叉比对 tools/e2e.mjs 本地起 HTTP，走 Host 同款抓取路径 tools/dsh-validator.mjs 从 app.asar 解出校验器 .cache/ 抓取结果缓存（不提交）

官方格式说明： https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.zh.md

已知未解决 / Known limitations

以下问题在实测中确认存在，目前没有修复。列出来是为了让你知道边界在哪，而不是假装完整。

| 问题 | 现状 | 实际影响 |
| 定时任务会延迟 | cron 每 6 小时（0 0,6,12,18 * * * UTC）；实测首次定时构建延迟约 2h22m | GitHub 排队属正常现象。6 小时窗口即使延迟，实际间隔仍在 4–10 小时之间；最坏情况可能被跳过一整轮 |
| 缓存是固定 key | key: packuments-v2（此前误用 ${{ github.run_id }}） | 固定 key 让每次运行复用同一份约 9.5 MB 的缓存；若改用 run_id，每个 run 都新建一份永久缓存，约 1,076 次运行即可填满 10 GB 配额并触发淘汰。抓取逻辑变化时手动提升 vN 作废旧缓存 |
| 热度标签覆盖偏低 | 435 / 7,123，阈值 stars ≥ 100 或 downloads ≥ 1000 | 大多数插件卡片上不显示任何热度：DSH 的标签只有数值档位，没有「低于阈值」的表达方式 |
| 没有生成时间戳 | 索引内无 generatedAt 字段 | 无法判断这份数据是几点生成的，排查「插件为什么没出现」时很痛苦 |
| 构建失败无人知道 | Actions 失败只在网页和默认邮件里 | 索引可能静默停止更新，客户端只会看到越来越旧的数据 |
| 社区目录下载无重试 | curl --max-time 120 + continue-on-error: true | 一旦失败就直接跳过 metrics，当天所有星数归零，且被 continue-on-error 掩盖 |
| 不能按更新时间排序 | sortKeys 只有 stars / downloads | 无法按「最近发布/最近更新」筛选新插件 |
| 兼容声明会滞后 | 索引只转述各包 peerDependencies 里的版本范围 | 插件作者未及时跟进 DSH 新版本时（例如 DSH 已发 0.2.1-rc.2，而插件仍声明只支持 rc.1），市场 UI 会误报「不兼容」，实际往往能跑 |
| 索引是静态快照 | 每 6 小时重建一次 | 新发布的插件最多延迟约 6–10 小时出现（含 GitHub 排队）；已被删除的包也可能残留一个周期 |
| 搜索发现可能被限流 | npm 搜索连续请求会 429，且 from>5000 会绕回第 0 页 | 已用切片 + 指数退避缓解，但仍无法保证覆盖 8,782 个声明结果的全部；实际收录以命中 dsh.bundle 为准 |
| 指标覆盖 89%，仍有 774 个缺口 | 6,349 / 7,123 有指标 | 623 个插件作者没填 repository.url；另 151 个仓库已删除或转为私有（API 返回 404）。这两类都无法通过 API 补齐 |
| 32% 插件没有第三方安全结论 | 7,123 个里 2,290 个不在 dsh.so 目录中 | 这些是通过 npm 搜索新发现的包，没有任何独立安全扫描结果。缺结论不等于有风险，但也不等于安全——安装前请自行判断来源 |

为什么这些没修

- 缓存键和失败告警属于流水线卫生，改动小但需要一次完整运行来验证；
- 标签阈值是产品判断：放宽会让卡片变杂，收窄会让更多人没有标签，没有明显占优的答案；
- 兼容声明滞后不是本索引能解决的 —— 它只是转述 npm 上的声明，真正的修复在插件作者侧；
- 静态快照是 GitHub Pages 托管方式的固有限制，要做增量更新就得换一套服务端。