dsh-plugin-health-monitor

ORBIT · DSH 插件观测站

用真实 GitHub、npm 与 OSV 数据观察 DeepSeek Harness 插件生态。

一个独立 Web 数据分析站，面向 DSH 插件使用者、程序员与计算机专业学生。它不是 DSH 宿主插件，而是对公开插件生态进行数据采集、信息检索、指标计算与可视化的本科《信息检索》课程项目。

• 真实数据：20 个经人工核验的 DSH 插件仓库
• 四个独立维度：关注度、维护活跃度、关注事项、数据完整度
• 导航：概览、插件库、生态分布、插件对比、数据与方法；插件详情从内容进入
• 自动化：GitHub Actions 仅手动采集，独立 data 分支保留历史，构建并部署 GitHub Pages
• 缺失数据不当 0：无法核验时明确显示原因，而不是伪精确评分

界面截图来自本仓库真实快照。ORBIT 版本使用和验收说明见 ORBIT 交付说明，评分评估见 修订规范。

快速开始

要求 Node.js ≥ 22.19（推荐 24）与 npm。

npm install
npm run data:pull   # 从 data 分支拉取最新真实快照
npm run dev         # http://127.0.0.1:5173

如果远端还没有 data 分支，或你需要重新采集：

# 方式一：环境变量（推荐细粒度只读或采集用 Token）
export GITHUB_TOKEN=...

# 方式二：显式允许采集器读取本机 `gh auth token`
npm run collect -- --gh-cli-token

npm run dev

Windows PowerShell 示例：

$env:GITHUB_TOKEN = "github_pat_..."
npm.cmd run collect
npm.cmd run dev

采集结果写入 public/data/，该目录被 .gitignore 排除；正式数据历史保存在独立的 data 分支。

常用命令

页面与功能

概览 /

品牌首屏、快捷检索、真实二维生态图、关键统计、社区关注与持续维护榜单、关注事项和近期变化。桌面有延迟加载的轻量 3D 轨道装置；移动端、减少动态效果与 WebGL 失败时保留静态 SVG。

插件库 /plugins

名称、功能、描述、仓库与分类搜索；维护、关注状态、完整度、下载可用性筛选；排序与分页保存在网址。勾选最多两个候选，从浮动入口开始对比。桌面表格、手机卡片，筛选不跳回页首。

生态分布 /ecosystem

关注度 × 维护活跃度，固定 0–100 轴。图与列表联动，选择插件后读取摘要、进入详情。筛选状态写入 URL，未定位插件列出原因；旧 /quadrant 与旧首页检索链接保留参数跳转。

插件详情 /plugins/:id

先说明用途、维护活动与需要核查的事项，再展示原始指标、趋势和可展开的评分依据。关注事项分为维护提醒、公开漏洞与数据缺口；保留来源、时间、安装命令复制和数据缺失说明。

插件对比 /compare

选择、交换两个不同插件。原始指标对齐展示，桌面矩阵表头吸顶；缺失不补零。方法版本、参与分项、有效权重或采集时间不同，不计算评分差值，并解释原因。

数据与方法 /method

用目录、简短摘要和展开内容说明来源、公式、权重、窗口、更新策略与局限。核心数据不可用时方法页仍能阅读。

技术架构

config/plugins.json
        │
        ├──→ scripts/collect.ts
        │       ├── GitHub REST API：分页 / 超时 / 重试 / 限额错误
        │       ├── npm registry + downloads API：repository 字段核验
        │       └── OSV API：精确 npm 包 + latest 版本
        │
        ├──→ scripts/lib/clean.ts + src/lib/contracts.ts（清洗 / 契约校验）
        │
        ├──→ src/lib/scoring.ts（关注度 / 维护活动 / 关注事项 / 完整度）
        │
        ├──→ data 分支：latest.json + history.json + status.json + snapshots/
        │
        └──→ public/data → Vite 构建 → GitHub Pages

• 前端：React 18 + TypeScript + Vite 6 + Tailwind CSS 3 + Apache ECharts + Lucide Icons + Three.js + Zod
• 采集：Node.js 24 + TypeScript + tsx
• 数据：结构化 JSON；源码在 main，历史在 data 分支
• 部署：GitHub Actions → GitHub Pages（VITE_BASE=/<repo>/）
• 测试：Vitest + Playwright

目录

config/        已核验插件清单
docs/          数据口径、评分规则、截图
scripts/       采集、评分辅助、数据准备、构建检查
src/           React 前端、类型、评分模块、图表
tests/unit/    评分、筛选、HTTP、快照单元测试
tests/e2e/     Playwright 浏览器验收
.github/       CI、部署、定时更新工作流

数据采集口径

详细字段、端点与统计窗口见 docs/DATA_SOURCES.md。

• 插件发现：不以名称含 DSH 作为判定依据；必须核验为可安装的 DSH Web 插件。
• 最近代码提交：使用 commits 中非合并提交的 committer.date，不用仓库 updated_at / pushed_at。
• 近 30 天提交：只统计非合并提交；分页达到上限时按已取得的下限计分。
• Issue 与 PR：Issues API 中包含 PR，统计时通过 pull_request 字段排除；两者分页预算独立，最多 20 页，截断时页面标注“下限样本”。
• Issue / PR 窗口：近 90 天创建；同时显示分母与样本量，小样本降权并提示。
• npm 下载：只有 registry 的 repository 字段与 GitHub 仓库一致时才采信；不把 Star / Fork / Release 下载冒充 npm 下载。7 日/前 7 日窗口按日期对齐，遇到平台性缺数日时显示“不可用”，不把缺口当真实 0。
• OSV：只有 npm 包名与精确版本匹配时才认为检查完成；空结果显示“未发现公开记录”，不显示“安全”。
• 容错：分页上限、404、PR 功能禁用、超时、429、5xx 均有明确降级路径；所有 GitHub 仓库失败时保留上一次成功快照。

评分和关注规则

当前规则为 2.0.0，实际快照版本以页面为准；已有 1.1.0 历史保留。详见 评分规则 和 同快照修订评估。旧版评估 留作对照，数据质量说明 记录清洗契约。

• 关注度：log10(1+x) 后 min-max 归一化；Stars 45% + npm 下载 55%；缺下载时仅用 Star，评分依据覆盖降为 45%、依据等级为一般。
• 维护：最近提交、近 30 天非合并提交、Issue 关闭率、PR 合并率、稳定 Release 按 30:15:20:15:10 归一化；缺失分项重新归一化，覆盖 < 45% 时输出“信息不足”。
• 关注事项：将维护提示、公开漏洞和数据缺口分开展示，帮助选用；不以整体“高低风险”概括插件。开放 Issue 比率不重复计分；比例提醒需新开与开放 Issue 均不少于 5 条，且数据完整。
• 数据完整度：7 个数据域中的可用比例，不是插件质量。
• 生态分布只纳入同时具备维护分与经核验下载量的插件。

数据更新控制

顶栏“数据更新”用于维护者手动采集，已删除六小时定时计划：

• 重新采集一次：保存本次收录目标和预算，再采集并发布。
• 保存采集设置：只保存下次手动操作的设置，不开始采集。

前往GitHub后点Run workflow，分支选main，action选refresh，按页面表格填写参数并执行。需要仓库写入权限；网站不保存Token。

“刷新已发布数据”只重新读取网站快照，不会调用采集 API。控制细节见 数据采集控制。展开“采集范围与预算”可准备 configure 操作，分别设置每轮插件上限、请求上限、GitHub 预留额度；configure只保存设置；refresh可一次保存并采集。旧设置兼容为目标20，每轮上限100、600次请求、GitHub预留100。目标与上限分别可改。

每次真实 HTTP 请求（含分页、重试和 304）计入本轮预算；达到边界时保留整份旧快照并发布采集记录。跨轮缓存只保存核实为公开的 GitHub 仓库响应，不保存 Token；下轮先通过 ETag / Last-Modified 验证。缓存不进入 data 分支或网页产物。

插件库支持排序、筛选及前 N 项展示，数量写入 URL。展示数量不增加 API 请求，实际采集上限独立设置，按最久未更新优先轮换。新增“收录目标”，超出当前目录时会搜索并核验DSH插件，目录跨轮保存；不足目标如实显示数量和原因，不宣称覆盖整个GitHub。

手动采集与部署

工作流：

• .github/workflows/ci.yml：TypeScript、Vitest、生产构建、Token 扫描、Playwright
• .github/workflows/deploy.yml：main 更新后先跑 TypeScript/单测，再从 data 分支取数据构建并部署 Pages
• .github/workflows/update-data.yml：仅维护者手动采集，构建校验成功后才提交 data 分支并部署 Pages

数据隔离原则：

1. 源码与用户修改留在 main；自动生成的 JSON 只提交到 data 分支。
2. 采集器只在 GitHub Actions 或本地运行，GitHub Token 不进入 Vite 构建。
3. 采集全部 GitHub 失败时只更新 status.json，不覆盖 latest.json / history.json。
4. 历史保留 90 天、单插件最多 400 个点，完整快照最多 120 份。
5. 往 data 分支提交不会触发 main 部署，避免工作流循环。
6. update-data.yml 将采集（只读 Token）与写数据（不安装依赖）拆成独立 job；persist 等构建校验成功后才推送；deploy.yml 和 update-data.yml 使用最小权限与 concurrency 互斥部署。
7. 官方 Actions 固定到 commit SHA，并由 Dependabot 跟踪更新。

首次部署

1. 仓库 Settings → Pages → Source 选择 GitHub Actions。
2. 确保存在 data 分支（本仓库已包含初始快照）。
3. 合并 PR 后 deploy.yml 会自动运行，或在 Actions 手动运行。
4. 项目站地址：https://albert404s.github.io/dsh-plugin-health-monitor/（Pages 已启用，合并后由工作流发布）。

测试结果

截至 2026-10-22，本地 codex/data-controls；数据仍为 2026-10-20 18:57（UTC+8）的 20 个插件快照：

• TypeScript 检查通过；13 个文件、173 个单元测试通过。
• Chromium 48 个浏览器测试通过，包含筛选/分页/返回/刷新、旧链接、双选对比、坏数据隔离、局部历史降级及 WebGL 正常与失败路径。
• 生产构建与产物检查通过；当前预览无控制台错误。
• 390、768、1024、1366×768、1440×900、1920×1080 检查无页面横向溢出。
• 必要 JS/CSS gzip 为 约 349 KB；独立 3D 为 136,283 字节，低于必要首屏 450 KB 目标。
• 同一快照重放评分不一致记录为 0。当前未运行新一轮完整真实 API 采集；采集衔接由模拟 API、存储回退测试和真实快照重放验证。
• 此前 ORBIT 已发布到 main；采集控制、预算缓存、榜单与评分修订已发布；本次进一步修复数量口径并补充真实插件发现。

截图位于 docs/screenshots/；本机完整验收记录还保存在项目父目录“ORBIT-验收”。

局限

这不是软件质量评估，也不是安全审计。 它不查看源码质量、测试覆盖率、用户体验或运行时漏洞；不安装、不执行被检测插件。详细边界见 docs/SCORING.md。

贡献插件

编辑 config/plugins.json，补充：

{
  "id": "owner-repo",
  "repo": "owner/repo",
  "npm": "@scope/package-or-null",
  "category": "interface",
  "installCommand": "dsh plugin --profile web add ...",
  "note": "核验依据"
}

提交前请确认：仓库公开可访问、确实是 DSH 插件、npm 映射可在 registry 中核对；无法核验 npm 时使用 null，不要猜测包名。

License

MIT

数量联动与插件扩充

首页统计、生态图及列表来自实际快照；插件库分别显示全库、匹配、展示数量。页面前台每60秒读取已发布数据，后台暂停；不会每分钟调用采集API。手动更新和“为什么100仍只有20”的原因见 数量与更新。