dsh-recommend

一句话定位

为 DSH 插件生态提供透明的排行与推荐：每 5 小时从 GitHub 抓取所有 dsh-plugin 话题仓库，按公开的评分公式排序，并通过模型工具与设置页让你随时查榜、按目标推荐、一键安装或检查更新。

核心能力

• 模型工具 rank_plugins：按综合分 / star 数 / 最近更新时间维度查询榜单，支持分类筛选（默认 10 条、上限 50）
• 模型工具 search_plugins：按名称 / 描述 / 分类 / 主题标签全文检索，被排除条目也会出现并附原因
• 模型工具 recommend_plugins：基于用户目标的中英同义词扩展推荐，融合匹配度与综合分（21 组硬编码同义词：记忆/搜索/UI/MCP/工具/视觉/语音 等）
• 模型工具 trend_plugins：查询发展榜（star 7/30/90 天增长、排名上升、npm 月下载量、本周新上榜、精选认证）
• 模型工具 sync_registry：刷新本地缓存（registry/history/trends），输出 hub 目录与深扫健康度
• 设置页「插件排行」标签：紧凑榜单 + 搜索 / 分类 / 排序 / 分页 + 一键刷新 + 一键安装 + 已装检测 + 插件更新检查 + 🏅 认证徽章，zh/en 双语随 DSH 主题适配

技术实现

• 语言: TypeScript（ESM，构建产物 lib/ 随仓库提交，git 安装免构建）
• 关键依赖: @deepseek-ai/cordis（插件注入）、@deepseek-ai/dsh-tools（defineTool 注册工具）、@deepseek-ai/dsh-host-webserver（同源路由注册）、@deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-runtime + @deepseek-ai/dsh-client-locale（设置页标签）
• 架构模式: 单包双半 bundle —— cordis patch 插入两行 host 半（工具半 dsh-recommend 依赖 tools，路由半 dsh-recommend-web 依赖 webServer，仅 web profile 激活）+ 浏览器半由 dsh.client 声明自动装载，三半共用同一份本地缓存；数据消费与数据生产解耦（详见 docs/decisions/0003）
• 入口文件: src/host/index.ts（host 工具半，注册 5 个模型工具）、src/host/web.ts（host 路由半，注册同源 HTTP 端点）、src/client/index.ts（browser 半注册设置页「插件排行」标签）

适用场景

• 你想在 DSH 里直接问「推荐一个能做 XXX 的插件」而不用手动翻 GitHub，模型通过同义词扩展 + 评分融合给你 Top 5 推荐。
• 你想知道某个插件维护是否活跃、综合质量如何，或者对比多个类似插件的分数；设置页排行榜直接给你紧凑列表 + 安装命令 + 详情展开（主题标签、许可证、发布时间、深扫状态、走势 sparkline）。
• 你装了多个第三方插件想统一管理更新；设置页「插件排行」标签内置「更新」按钮，检查当前 profile 直接依赖的 Git commit / npm 版本并执行官方 dsh plugin update。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:zp-home/dsh-recommend

配置项

以上默认值由 cordis.patch.yml 写入；要修改请编辑 node_modules/dsh-recommend/cordis.patch.yml 后重启 DSH。

常见问题

Q: 安装后需要重启 DSH 吗？

A: 需要。本插件含两行 host 半（工具半 dsh-recommend、路由半 dsh-recommend-web）和一个浏览器半（设置页「插件排行」），都属于永久（bundle）插件，安装 / 更新 / 卸载后必须重启 DSH harness，新装或变更的插件才会被 Loader 实际加载。

Q: 数据多久更新一次？怎么手动刷新？

A: GitHub Actions 每 5 小时自动重算 registry / history / trends 并提交到本仓库 data/。插件侧默认缓存 TTL 是 6 小时，可调用模型工具 sync_registry 或在设置页点「刷新数据」立即拉新；强制刷新走 POST /dsh-recommend/sync?force=1，跳过 TTL 重新下载完整快照。

Q: 国内访问 raw.githubusercontent.com 失败怎么办？

A: 编辑已安装包中的 cordis.patch.yml（node_modules/dsh-recommend/cordis.patch.yml），把 dsh-recommend 和 dsh-recommend-web 两行的 dataUrl 改成 https://cdn.jsdelivr.net/gh/zp-home/dsh-recommend@main/data/registry.json（jsDelivr CDN，国内一般可达，但有数小时缓存延迟），保存后重启 DSH。

Q: 一键安装按钮会被恶意网页利用吗？

A: 不会。设置页的「⬇ 安装」走 POST /dsh-recommend/install，服务端只接受同源或空 Origin 请求（CSRF 防护），并按客户端传来的 fullName 从本地缓存 registry 构造 spec（不接受客户端自传 spec），避免恶意网页让你装任意插件。命令最终交给官方 dsh plugin --profile <name> add <spec> 执行，超时 10 分钟自动终止。

Q: 「上榜 / 收录」等于安全背书吗？

A: 不等于。本插件只读取 GitHub 元数据（stars、描述、license、更新时间等），从不执行被收录插件的代码；上榜反映的是维护性、热度、文档质量与精选收录等信号，不包含代码审计、供应链审计或运行时行为评估。安装第三方插件前请自行审查源码、权限和许可证，详见 SECURITY.md。

Q: 怎么卸载这个插件？

A: 用官方命令 dsh plugin --profile web remove dsh-recommend（或对应 npm / GitHub spec）卸载，然后重启 DSH harness。本插件不写 profile manifest 之外的副作用，卸载后 $DSH_HOME/dsh-recommend/ 下的本地缓存可手动删除。

上手难度

入门 — 一行命令即可安装，无需任何额外配置（默认数据源开箱可用），设置页和模型工具均按 DSH 习惯布局；想自定义数据源或安装目标 profile 才需要编辑 cordis.patch.yml。

已知问题与限制

• 全量抓取受 GitHub Search API 单查询 1000 条上限影响，本地全量复算需配 GITHUB_TOKEN，CI 已自动注入（CHANGELOG.md:16）
• 默认 dataUrl 指向 raw.githubusercontent.com，国内网络可能不可达，需手动改为 jsDelivr CDN（README.zh.md:68）
• 评分模型 v2 以元数据信号为主，stars 可刷、不等于真实使用量；真实使用量信号（npm 下载量、安装上报）尚未引入热度权重（docs/scoring.md:43）
• 安装 / 更新操作依赖 spawn dsh 子进程，最长 10 分钟超时；超时会被强杀进程树（src/host/web.ts:35）
• 设置页的「本机兼容检测」按钮依赖官方 dsh-dev-sandbox 服务可用，不可用时会报错（src/client/index.ts:107）
• 模型工具 recommend_plugins 的同义词组是硬编码 21 组（中英对照），新增场景需改源码重新构建（src/host/index.ts:434）
• 历史快照按天幂等写入，但保留 366 天后会自动截断，更老的趋势数据无法查询（AGENTS.md:7）

DSH 插件生态的透明排行与推荐：每 5 小时自动抓取全 GitHub 的 dsh-plugin 话题仓库，按公开的评分模型打分排序；DSH 插件与静态站消费同一份数据。

设计文档 · 评分模型 · 路线图 · 数据 · 中文

✨ 特性

• 透明：评分公式、权重、全部原始数据都公开在这个仓库里，任何人 clone 后跑一遍 node scripts/sync.mjs 即可复算——这是排行类项目信任的基石
• 可信：官方本体/非插件 denylist（scripts/exclude-list.json）+ 榜单前 200 名深扫插件性验证（scripts/scan.mjs 检测 dsh 声明 / @deepseek-ai/* 依赖 / cordis 配置 / skills 特征），未检出特征的仓库排除出榜并透明标注；hub 目录抓取失败会让 CI 红，信号源健康度随时可见
• 安全提示（仅供参考）：市场 GitHub Actions 以公开的只读规则扫描源码和发布 bundle，规则、版本、上限与已知盲区见 静态安全扫描算法。未命中规则不等于安全，提示不构成安全认证，也不影响评分或安装资格
• 可审计全量：GitHub Search 单查询超过 1000 条时，采集器按创建日期、仓库大小与 Star 的无重叠闭区间递归分片；topic-coverage.json 记录每个叶子查询的 total_count、去重数、重试与溢出。任一叶子不完整即终止全量发布，不以部分数据更新榜单
• 自动化：GitHub Actions 每 5 小时全量重算并提交 data/（含深扫、历史快照、徽章、月度报告），数据永不人工维护
• 一份数据，多个消费端：data/registry.json 是唯一事实源，静态排行站、DSH 插件（模型工具 + 设置页标签）、外部工具共用；data/history.json 提供每日趋势

🚀 快速开始

1️⃣ 网页版排行（不用安装）

👉 打开 https://zp-home.github.io/dsh-recommend/site/ —— Neo-Brutalism 高对比排行榜：醒目的前三名奖牌、四维信号分数与 🏅 精选认证，支持搜索 / 分类筛选 / 四种排序（综合分 / 热度 / 最近更新 / 最新发布）、分页浏览、详情展开（主题标签 / 许可证 / 发布时间 / 深扫状态）、近 N 天综合分走势图，以及一键复制安装命令。

🏆 发展排行榜（独立页面）：https://zp-home.github.io/dsh-recommend/site/rankings.html —— star 增长最快（7/30/90 天）、排名上升最快、npm 下载量最多、本周新上榜、精选认证，每条带增长曲线 sparkline。

📸 效果预览：

也可以直接看原始数据：data/rankings.json（每 5 小时自动更新）、data/history.json（每日趋势快照）、data/trends.json（派生发展榜）。

2️⃣ 在 DSH 里安装插件（✅ 已真机验证）

方式 A：npm 安装（国内用户推荐，走 npmmirror 镜像）

dsh plugin --profile web add dsh-recommend
# 重启 dsh web 后生效

方式 B：GitHub 直装

dsh plugin --profile web add github:zp-home/dsh-recommend
dsh --profile web --dump-config   # 应出现 "# == dsh-recommend" 层
# 重启 dsh web 后生效

方式 C：本地目录安装（完全离线，拷文件夹即可）

dsh plugin --profile web add D:\路径\dsh-recommend

💡 国内网络提示：插件榜单数据默认从 raw.githubusercontent.com 拉取（sync_registry 工具）。无法访问该域名时，可编辑已安装插件包中的 cordis.patch.yml（node_modules/dsh-recommend/cordis.patch.yml），把 dsh-recommend 的 dataUrl 改为 https://cdn.jsdelivr.net/gh/zp-home/dsh-recommend@main/data/registry.json（jsDelivr CDN，国内一般可达，数据可能有数小时缓存延迟），改后重启 DSH。

安装后获得：

仓库根目录即插件包（dsh.bundle + dsh.client 双声明，构建产物 lib/ 随库提交，git 安装无需构建）。

3️⃣ 自己重跑数据管道

# 需要 Node 18+（深扫需 GITHUB_TOKEN，CI 自动注入）
node scripts/sync.mjs            # fetch → score → scan（深扫）→ score → history → trends → badge → validate
node scripts/validate.mjs        # 只校验
node scripts/smoke.mjs           # 管道纯函数冒烟测试

未设置 GITHUB_TOKEN 时使用未认证限额（够跑一轮，自动跳过深扫）；CI 中自动注入 token。

🛡 插件作者：挂一个分数徽章

所有上榜项目每 5 小时自动生成 shields 徽章（data/badges/<owner>__<name>.json）。将下面这行中的 <owner>__<name> 替换为你的 GitHub 仓库路径；静态站和设置页也可直接复制链接：

[![dsh score](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fzp-home%2Fdsh-recommend%2Fmain%2Fdata%2Fbadges%2F<owner>__<name>.json)](https://github.com/zp-home/dsh-recommend)

🏅 精选认证（给优质插件作者的激励）

想让你的插件获得官方「🏅 精选认证」？两步：

1. 提交 收录/认证 Issue，勾选「申请精选认证」，可选填 npm 包名（用于下载量榜）；
2. 审核通过后，你的插件在榜单与设置页显示 🏅，并进入精选认证榜。

认证是展示层激励，不改变评分（评分公式始终保持透明可复算）。审核标准：可正常安装（dsh.bundle 或 repository-plugin）、有实际功能、README 完善、维护活跃。

📨 针对性邀请开发者（维护者运营工具）

生态里大量优质插件已被自动收录但从未主动提交认证。scripts/invite.mjs 从 registry 自动筛出高价值未认证插件，分层生成邀请清单与个性化话术：

node scripts/invite.mjs              # 生成 docs/invites.md（全部目标）
node scripts/invite.mjs --tier 1     # 只生成 Tier 1（头部标杆 ★≥800）

分层：Tier 1 头部标杆（★≥800）· Tier 2 优质活跃（★≥100 且 30 天活跃）· Tier 3 潜力新星（★≥30 且 score≥0.6 且活跃）。清单含每个插件的真实数据（星级/分数/分类/活跃度）与已预填数据的邀请话术，复制即用——在作者仓库的 issue / discussion 留言，或邮件联系。

📊 当前数据

• 全量抓取 2200+ 个 dsh-plugin 话题仓库；排除占位/空仓库/官方本体/非插件后 1900+ 个上榜（具体见 data/meta.json）
• 评分 = 0.35×维护性 + 0.30×热度 + 0.20×质量 + 0.15×生态（公式与权重全公开，改版走评审，详见 docs/scoring.md）
• 排除条目保留在 data/registry.json 并附原因（fork / 已归档 / 空仓库 / 无描述 / 占位特征 / 官方本体 / 深扫未检出插件特征）

📁 仓库结构

data/           每 5 小时生成的 registry.json / rankings.json / meta.json / history.json / badges/（Git 即数据库）
scripts/        fetch（采集）→ score（过滤+评分）→ scan（深扫）→ history（快照）→ badge（徽章）→ report（月报）→ validate（门禁）→ sync（总入口）
src/            插件源码（host 工具半 + web 数据路由半 + browser 设置页半）
lib/            构建产物（随库提交，git 安装免构建）
cordis.patch.yml 插件配置层（bundle patch）
site/           静态排行站（零构建，直接吃 data/registry.json + history.json）
docs/           设计 / 评分模型 / 路线图 / 决策记录 / 月度报告
.github/        Actions（每 5 小时 cron + PR 校验）与提交插件表单

数据源

🧩 插件架构（简要）

• 三行配置：dsh-recommend（工具半，任何 profile 可用）/ dsh-recommend/web（同源数据路由，仅 web profile）/ 浏览器排行标签半（由官方 client-modules 扫描 dsh.client 自动供给，无需独立配置行）
• 数据安全：插件只读 registry.json 并展示，从不执行任何被收录插件的代码
• 真机验证记录与踩坑（window is not defined、github: 安装取根 package.json 等）见 ADR-0003

开发

npm install        # 开发依赖（react/typescript/tsdown）
npm run typecheck  # tsc --noEmit
npm run bundle     # tsdown 构建 lib/
npm run sync       # 重跑数据管道

收录与免责

收录 ≠ 安全背书。 本仓库只做只读元数据分析，从不 clone、从不执行被收录插件的代码。安装任何第三方插件前请自行审查源码、权限与许可证。详见 SECURITY.md。

路线图

社区与贡献

• 提交插件收录：Issue 表单（或直接打 dsh-plugin 话题，每日同步自动收录）
• 贡献指南：CONTRIBUTING.md
• 上游生态：DeepSeek Harness · dsh-plugin 话题 · WhaleHub

License

MIT