插件图谱索引 abcdream-Lary/dsh-atlas

dsh-atlas · DSH 插件图谱

把 awesome-dsh-plugin 收录的社区插件目录，重新整理成 DeepSeek Harness（dsh）插件市场索引（format 1），可以直接在 dsh 的「插件 → 发现 → 自定义插件市场」里添加使用。

名字取「图谱」而不是「市场」：它不做交易也不托管代码，只是把散落的上游清单绘制成一张可安装的地图——每个版本都标注了确切的坐标（npm 版本号或 git commit）。

在 dsh 里显示的名字是 awesome-dsh-plugin，也就是它整理的那份上游清单的名字——浏览插件的人认得这个，比自造一个名字更有用。

索引地址

| | 地址 | 实测 |
| 国内镜像（dsh 实际只能用这个） | https://cdn.jsdmirror.com/gh/abcdream-Lary/dsh-atlas@main/out/index.json | 6.2 MB 约 1–5 秒 |
| 官方（最新） | https://abcdream-lary.github.io/dsh-atlas/index.json | 境内 42–45 秒，偶发中途断开 |

两个地址读的是同一份 out/index.json——镜像就是 jsDelivr 对 GitHub 仓库的缓存，核对过字节一致。

官方地址在国内多半塞不进 dsh。 plugin-market 的 fetchTimeoutMs 默认 15 秒，而这里实测官方地址要 42 秒以上，dsh 会直接判 plugin-market/fetch-failed。所以：

- 日常就用镜像。
- 要官方地址，得把 fetchTimeoutMs 调大（例如 120000），换来的是每次都要等一分多钟。
- 要钉死某一版：把 @main 换成 commit，https://cdn.jsdmirror.com/gh/abcdream-Lary/dsh-atlas@<commit>/out/index.json。

市场名是怎么来的

「索引源」里显示的名字不是本地配置，改不了。 indexes 只存 URL；dsh 列表里显示的是它最近一次成功读取到的索引 title（首次读取前显示主机名）。所以名字只能改索引本身——也就是本仓库 build_index.py 里 compose() 的 title。

这也意味着镜像的缓存滞后会直接表现为名字没更新：索引改了、重建了，镜像还在发上一版，dsh 读到的就还是旧名字。dsh 自己另有 10 分钟的读取缓存，过期或在「发现」页点刷新后会重新读。

网页预览：

- 官方：<https://abcdream-lary.github.io/dsh-atlas/preview.html>
- 国内：<https://cdn.jsdmirror.com/gh/abcdream-Lary/dsh-atlas@main/out/preview.html>

awesome-dsh-plugin 的目录（给人和浏览器看） │ 下载 → 归一化 ▼
npm registry 清单 / GitHub commit + package.json
│ 解析 → 钉住版本 ▼ index.json（format 1，给 dsh 装）

为什么需要这一步

上游目录是给人看的：它记录 owner/repo、描述、star 数，但不记录安装源。而 dsh 的索引格式要求每个版本都钉死到确切来源——npm 版本要精确到 version，git 版本要精确到 40 位 commit——因为发现页安装的是索引里记录的那一个版本，不会跟着 latest 漂。

所以这里不是抓 README，而是一个适配器：

1. 读上游的机器可读目录（站点 plugins.json，失败时退回 npm 上的 dsh-plugin-catalog 包）；
2. 逐条解析出可安装来源：
- 有 npm 包 → 读 registry 清单，取声明了 dsh.bundle 且未弃用的版本；
- 只有仓库 → 用 GitHub GraphQL 批量取默认分支 HEAD 的 commit、提交时间和该目录下的 package.json，并从清单里读真实的包名与版本（仓库名经常和包名不一致，例如 dsh-ATN → dsh-atn）；
3. 组装成 format 1 文档，并按规范自检。

快速开始

python build_index.py build # 全量，输出到 out/
python build_index.py stats out/index.json # 看分布
python build_index.py validate out/index.json
python build_index.py preview out/index.json # 只重画预览页，不重新抓数据

只需要 Python 3.9+，没有第三方依赖。git 来源需要 GitHub token：

export GITHUB_TOKEN=ghp_xxx # 或者本机已登录 gh（自动读取 gh auth token）

产出：

| 文件 | 说明 |
| out/index.json | 索引本体，就是这个文件给 dsh 用 |
| out/preview.html | 本地预览页（搜索 / 分类 / 排序），双击即可打开 |
| out/plugins.txt | 纯文本源清单，可直接喂给 dsh 官方 plugin-market-generator 交叉验证 |
| out/report.json | 本次构建的报告：哪些条目没能收录、原因分布、名字冲突 |

接入 dsh

1. dsh → 插件 → 「实验性插件」旁的更多 → 打开「自定义插件市场」；
2. 在「发现」页添加上面的国内镜像地址（官方地址在境内会超过 dsh 的读取超时）；
3. 列表里会显示为 awesome-dsh-plugin，搜索、筛选、点安装即可。

不想用现成的，也可以自己搭一份：python build_index.py build 产出 out/，丢到任意 https 静态托管，再把地址填进去。
仓库里带了 .github/workflows/build-index.yml：每天定时重建、把结果提交回仓库并发布到 Pages。钉住的 commit 和 npm 版本不会自己更新，索引必须定期重跑——这也是为什么需要一个每天跑的 CI，而不是一次性生成。

参数

| 参数 | 默认值 | 说明 |
| --catalog-url | https://awesome-dsh-plugin.com/plugins.json | 上游目录地址 |
| --catalog-file | 无 | 用本地目录文件代替下载 |
| --registry | https://registry.npmmirror.com | 读 npm 清单用的 registry。只用来读元数据，输出的 npm 版本不写 registry 字段，客户端仍用自己的源安装 |
| --github-token | GITHUB_TOKEN / GH_TOKEN / gh auth token | GitHub API token |
| --out | out | 输出目录 |
| --cache-dir / --cache-ttl / --refresh | .cache / 24 小时 / 关 | 上游原始文档缓存，重跑只补增量。--cache-ttl 0 表示不过期 |
| --limit | 无 | 只取前 N 条，调参用 |
| --only | all | npm / git / all |
| --category | 无 | 可重复，只处理指定分类 id |
| --versions | latest | latest 只收录 dist-tags.latest 指向的版本；all 收录全部合格版本（索引会大很多） |
| --max-versions | 0 | 每插件版本数上限，0 不限 |
| --assume-engine | | 清单没声明 engines.dsh 时写入的范围 |
| --title-mode | derived | 从包名推导展示标题（@scope/dsh-j-space → J Space）；none 则不写 title |
| --langs | en,zh | 保留的描述语言 |
| --max-capabilities | 4 | 每插件带的权限标签数，按风险排序取前 N 个 |
| --conflict-policy | best | 多个仓库抢同一个包名时保留谁：best 按 star/下载量，first 按目录顺序 |
| --concurrency | 8 | 并发请求数 |
| --batch-size | 20 | 单次 GraphQL 查询里塞几个仓库 |
| --pretty | 关 | 缩进输出 |
| --no-html | 关 | 不生成预览页 |

输出长什么样

{
"format": 1,
"title": { "en": "Awesome DeepSeek Harness Plugins", "zh": "DeepSeek Harness 插件精选" },
"metadata": {
"categories": { "ui": { "title": { "en": "UI Enhancements", "zh": "UI 增强" } } },
"labels": {
"npm": { "title": { "en": "npm package", "zh": "npm 包" } },
"range-assumed": { "title": { "en": "dsh range assumed", "zh": "dsh 范围未声明" } },
"cap-credentials": { "title": { "en": "Touches credentials", "zh": "接触凭证" } }
},
"sortKeys": { "stars": { "title": { "en": "Stars", "zh": "Star 数" }, "order": "desc" } }
},
"plugins": [
{
"name": "@anonyjcy/dsh-j-space",
"title": "J Space",
"description": { "en": "…", "zh": "…" },
"author": "AnonyJcy",
"homepage": "https://github.com/AnonyJcy/dsh-j-space",
"repository": { "url": "https://github.com/AnonyJcy/dsh-j-space" },
"metadata": { "category": "agi", "labels": ["npm"], "keywords": ["…"], "sortKeys": { "stars": 5 } },
"dist-tags": { "latest": "1.2.4" },
"versions": [
{ "version": "1.2.4", "publishTimestamp": 1792045792,
"source": { "type": "npm" }, "engines": { "dsh": "" } }
]
},
{
"name": "dsh-quality-review",
"repository": { "url": "https://github.com/CAI-MH/dsh-quality-review" },
"versions": [
{ "version": "0.1.0", "publishTimestamp": 1789012601,
"source": { "type": "git", "url": "https://github.com/CAI-MH/dsh-quality-review",
"commit": "7c5a67ddc76e91d2a87725fabb23a04b80370f3b" },
"engines": { "dsh": "^0.1.2-alpha.1" } }
]
}
]
}

本次产出

上游 2026-10-17 版目录共 5786 条，构建结果：

| | 数量 |
| 收录进索引 | 5528（npm 源 2923 / git 源 2605） |
| 目录内重名（只保留信号最强的一条） | 201 |
| 丢弃 | 58（仓库已删或转私有 38、包名不合规 8、package.json 损坏 6、没有清单 2、未声明 dsh.bundle 3、子目录名无法表达 1） |
| 索引大小 | 6.2 MB（每插件 1 个版本、双语描述） |
| 构建耗时 | CI 上约 1.5 分钟；本机走镜像约 11 分钟 |

npm 源的条数取决于用哪个 registry：官方 npmjs 能解析 2923 个，国内镜像少 378 个（镜像同步有延迟），差的这些会自动回退到仓库的 git 源，最终总数不变。

收录规则（以及为什么这样选）

- 必须有 dsh.bundle。规范里安装端会拒绝没有 bundle patch 的包，列进去只会让人装失败。因此解析不到 bundle 的条目会被丢弃，并在 report.json 里记明原因。
- 版本必须可钉：npm 版本要能在 registry 里查到发布时间；git 版本要拿到 40 位 commit 和该 commit 上的 package.json。
- engines.dsh 三级回退：先用清单自带的 engines.dsh；没有就用 @deepseek-ai/dsh 的 peer 范围（与官方生成器一致）；仍然没有就写 ，并打上 range-assumed 标签，让读者知道这是假设而非作者声明。
- 名字唯一。上游按 owner/repo 区分，但索引按包名区分；同一个包名常常被好几个仓库（复刻、改名）同时声明，重名时默认保留 star / 下载量更高的那条，其余记进 nameConflicts。
- monorepo 子目录：上游用 /tree/<branch>/<path> 或 name#subpath 表达子包，两种都会转成 git source 的 path。

与上游目录的差异

| | 上游目录 | 这个索引 |
| 单位 | 仓库 | npm 包名 |
| 安装源 | 只给 dsh plugin add 命令文本 | 结构化 source，精确到 version / commit |
| 版本 | 一个 version 字段 | versions[] + dist-tags |
| 分类 | 分类 id | 分类 id + 双语标题 |
| 权限 | capabilities[] | 转成 cap-* 标签（按风险排序，默认取 4 个） |

已知限制

- npm 源的元数据走镜像。registry.npmjs.org 在部分网络下不可达，默认用 registry.npmmirror.com 读清单。镜像可能比官方晚几分钟同步，刚发布的版本偶尔查不到。
- git 走 GitHub GraphQL。非 github.com 的仓库（GitLab 等）目前会被跳过并记为 git:not-github；要支持得补对应 API。
- 不做安全审计。权限标签来自上游的能力扫描结果，是描述不是背书。索引本身是未签名的，标题和作者都是市场方的声明。
- 索引会过期。钉住的 commit 和 npm 版本在重新生成之前不会自己更新，建议定时重建（例如每天一次 CI）。
- 国内线路依赖第三方 CDN。眼下用的是 jsDelivr 的镜像，够快但有缓存滞后。想要更彻底的第一方线路，可以把索引发布成一个 npm 包——registry.npmmirror.com 的 /<包>/latest/files/index.json 接口能直接吐出包里的文件（已验证可用），代价是多维护一个 npm token 和一条发布步骤。

目录结构

build_index.py 工具本体（单文件，标准库） out/index.json 生成的索引 out/report.json 构建报告 out/plugins.txt 源清单（给官方生成器） out/preview.html 预览页 .cache/ 上游原始文档缓存，可随时删（全量约 110 MB）

License

代码 MIT（见 LICENSE）。out/ 里的索引数据派生自 awesome-dsh-plugin，沿用上游的 CC0-1.0。