您可以在 npm、PyPI、NuGet、VS Code Marketplace 以及 Docker Hub 上发布软件包。目前，要了解“我的软件包表现如何？”，您需要查看五个不同的网站。registry-stats 是一个完整的平台：一个 TypeScript 引擎（包含命令行工具、API 和 REST 服务器），一个实时 Web 控制面板，以及一个原生 Windows 桌面应用程序——所有这些都来自一个代码仓库。

没有运行时依赖。使用原生的 fetch() 方法。Node 18+。

内容

| 层 | 功能 | |-------|-------------| | Engine | TypeScript 库 + 命令行工具 + REST 服务器。使用一个界面查询五个注册中心。已发布到 npm，名为 @mcptoolshop/registry-stats。 | | Dashboard | 一个由Astro驱动的Web应用程序，配备Pulse AI智能助手（支持语音流、网页搜索、全屏模式、GitHub数据连接器），包含六个交互式图表，支持实时刷新，并可导出报告（PDF/JSONL/Markdown），以及分Tab的帮助文档。该应用程序每周由CI自动构建，并可按需刷新。 | | Desktop | 一个原生 Windows 应用程序，使用 WinUI 3 + WebView2。将控制面板打包在本地，按需获取实时统计数据。 |

控制面板

一个自动更新的统计信息控制面板位于 /dashboard/。

• 分Tab界面 — 包含“首页”、“分析”、“排行榜”和“帮助”等Tab。
• Pulse AI智能助手 — 基于Ollama的对话式助手，支持语音合成（LLM模型输出时同步语音，提供4种声音，通过mcp-voice-soundboard实现），网页搜索（Wikipedia + 可选的SearXNG），自动语音播报，全屏模式，GitHub组织数据连接器，模型选择器，以及对话记忆功能。
• 关键指标概览 — 健康评分（0–100），多样性指数，每周变化，所有注册表的总下载量。
• 六个交互式图表 — 30天趋势图（聚合/按注册表/前5名切换），注册表份额（极坐标图），投资组合风险（直方图 + Gini系数和P90），前10名增长情况，速度跟踪图（带sparklines），以及30天热力图（带异常值检测，>2σ）。
• 智能增长引擎 — 通过基线阈值、百分比上限和阻尼速度公式，处理小基数偏差问题。
• 可执行的洞察 — 自动生成推荐和关注提醒，用于识别下降的软件包。
• Pulse面板 — 分屏显示已建立的流行软件包（≥ 50次/周下载）和新兴/新软件包，并带有内联7天sparklines，绝对值和百分比变化，基线信息，以及简要的执行摘要。
• 实时刷新 — 客户端按需从npm和PyPI API获取数据，并显示进度指示器；结果缓存在sessionStorage中（5分钟TTL），因此Tab切换速度非常快。
• 导出报告 — 在“刷新”按钮旁边，提供下拉菜单，可以选择三种格式：Exec PDF（通过jsPDF实现），LLM JSONL（用于AI模型输入的结构化记录），以及Dev Markdown（GFM表格）。
• 排行榜 — 按照每周下载量对132个软件包进行排名，并带有内联30天sparklines和智能趋势标识。
• 配置页面 — 包含投资组合编辑器（带验证功能），注册表同步辅助部分，以及流水线概览。
• 帮助Tab — 提供用户友好的指南，涵盖每个Tab，关键概念，AI助手使用技巧，数据流水线，以及有用的链接。
• 深色/浅色主题 — 自动跟随系统偏好设置。

数据在构建时获取，并每周由 CI 自动重建（每周一 06:00 UTC）。实时刷新直接从注册中心 API 获取最新数据。在 site/src/data/packages.json 中配置要跟踪的软件包（5 个注册中心，共 132 个软件包）。

桌面应用程序

一个原生 Windows 应用程序，它将控制面板封装在一个本地 WebView2 容器中：

• 支持离线使用 — 包含打包的 HTML/CSS/JS；无需互联网连接即可使用
• 实时刷新 — 按需从 GitHub Pages 获取 stats.json 文件
• CSV 导出 — 一键导出排行榜数据
• MSIX 软件包 — 通过 desktop-ci.yml 在 CI 中构建和签名

桌面应用程序的源代码位于 desktop/ 目录中。使用 .NET 10 MAUI 构建，目标是 WinUI 3。

安装

npm install @mcptoolshop/registry-stats

命令行界面 (CLI)

# Query a single registry
registry-stats express -r npm
#  npm     | express
#            month: 283,472,710  week: 67,367,773  day: 11,566,113

# Query all registries at once
registry-stats express

# Time series with monthly breakdown + trend
registry-stats express -r npm --range 2025-01-01:2025-06-30

# Raw JSON output
registry-stats express -r npm --json

# Other registries
registry-stats requests -r pypi
registry-stats Newtonsoft.Json -r nuget
registry-stats esbenp.prettier-vscode -r vscode
registry-stats library/node -r docker

# Create a config file
registry-stats --init

# Run with config — fetches all tracked packages
registry-stats

# Compare across registries
registry-stats express --compare

# Export as CSV or chart-friendly JSON
registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart

# Start a REST API server
registry-stats serve --port 3000

配置文件

在您的项目根目录下创建一个 registry-stats.config.json 文件（或者运行 registry-stats --init 命令）：

{
  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
  "packages": {
    "mcpt": {
      "npm": "mcpt",
      "pypi": "mcpt"
    },
    "tool-compass": {
      "npm": "@mcptoolshop/tool-compass",
      "vscode": "mcp-tool-shop.tool-compass"
    }
  },
  "cache": true,
  "cacheTtlMs": 300000,
  "concurrency": 5
}

运行 registry-stats 命令，不带任何参数，即可获取所有配置软件包的统计数据。命令行界面会从当前工作目录向上查找最近的配置文件。

配置文件也可以通过编程方式访问：

import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';

const config = loadConfig();          // finds nearest config file, or null
const defaults = defaultConfig();     // returns default Config object
const template = starterConfig();     // returns starter JSON string

编程 API

import { stats, calc, createCache } from '@mcptoolshop/registry-stats';

// Single registry
const npm = await stats('npm', 'express');
const pypi = await stats('pypi', 'requests');
const nuget = await stats('nuget', 'Newtonsoft.Json');
const vscode = await stats('vscode', 'esbenp.prettier-vscode');
const docker = await stats('docker', 'library/node');

// All registries at once (uses Promise.allSettled — never throws)
const all = await stats.all('express');

// Bulk — multiple packages, concurrency-limited (default: 5)
const bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);

// Time series (npm + pypi only)
const daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');

// Calculations
calc.total(daily);                         // sum of all downloads
calc.avg(daily);                           // daily average
calc.groupTotals(calc.monthly(daily));     // { '2025-01': 134982, ... }
calc.trend(daily);                         // { direction: 'up', changePercent: 8.3 }
calc.movingAvg(daily, 7);                  // 7-day moving average
calc.popularity(daily);                    // 0-100 log-scale score

// Export formats
calc.toCSV(daily);                         // "date,downloads\n2025-01-01,1234\n..."
calc.toChartData(daily, 'express');        // { labels: [...], datasets: [{ label, data }] }

// Comparison — same package across registries
const comparison = await stats.compare('express');
await stats.compare('express', ['npm', 'pypi']);  // specific registries only

// Caching (5 min TTL, in-memory)
const cache = createCache();
await stats('npm', 'express', { cache });  // fetches
await stats('npm', 'express', { cache });  // cache hit

仓库支持

| 仓库 | 软件包格式 | 时间序列 | 可用数据 | |----------|---------------|-------------|----------------| | npm | express, @scope/pkg | 是 (549 天) | 最近一天、最近一周、最近一个月 | | pypi | requests | 是 (180 天) | 最近一天、最近一周、最近一个月、总数 | | nuget | Newtonsoft.Json | No | 总数 | | vscode | publisher.extension | No | 总数（安装量）、评分、趋势 | | docker | namespace/repo | No | 总数（拉取次数）、星级 |

内置可靠性

• 自动重试，并在遇到 429/5xx 错误时采用指数退避策略
• 尊重 Retry-After 头部信息
• 批量请求的并发限制
• 可选的 TTL 缓存（可插拔，通过 StatsCache 接口，您可以自定义 Redis 或文件后端）

REST API 服务器

可以作为微服务运行，也可以嵌入到您自己的服务器中：

registry-stats serve --port 3000

GET /stats/:package              # all registries
GET /stats/:registry/:package    # single registry
GET /compare/:package?registries=npm,pypi
GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart

用于自定义服务器或无服务器环境的编程用法：

import { createHandler, serve } from '@mcptoolshop/registry-stats';

// Option 1: Quick start
serve({ port: 3000 });

// Option 2: Bring your own server
import { createServer } from 'node:http';
const handler = createHandler();
createServer(handler).listen(3000);

自定义仓库

import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';

const cargo: RegistryProvider = {
  name: 'cargo',
  async getStats(pkg) {
    const res = await fetch(`https://crates.io/api/v1/crates/${pkg}`);
    const json = await res.json();
    return {
      registry: 'cargo' as any,
      package: pkg,
      downloads: { total: json.crate.downloads },
      fetchedAt: new Date().toISOString(),
    };
  },
};

registerProvider(cargo);
await stats('cargo', 'serde');

代码仓库结构

registry-stats/
├── src/        # TypeScript engine (published to npm)
├── site/       # Astro dashboard + landing page (deployed to GitHub Pages)
├── desktop/    # WinUI 3 desktop app (.NET 10 MAUI)
└── test/       # Library tests (vitest)

开发

# Engine
npm install && npm run build && npm test

# Dashboard (dev server)
npm run site:dev

# Dashboard (production build)
npm run site:build

安全与数据范围

| 方面 | 详细信息 | |--------|--------| | Data touched | 从 npm、PyPI、NuGet、VS Code Marketplace、Docker Hub 获取的公开下载统计数据。可选的内存缓存。 | | Data NOT touched | 无遥测。无分析。无凭证存储。无用户数据。无文件写入。 | | Permissions | 读取：通过 HTTPS 访问公共注册表 API。写入：仅限于标准输出/标准错误输出。 | | Network | 通过 HTTPS 访问公共注册表 API。可选的本地 REST 服务器。 | | Telemetry | 未收集或发送任何数据。 |

请参阅 SECURITY.md 以报告漏洞。

评分卡

| 类别 | 评分 | |----------|-------| | A. 安全性 | 10 | | B. 错误处理 | 10 | | C. 操作文档 | 10 | | D. 发布规范 | 10 | | E. 身份验证（软性） | 10 | | Overall | 50/50 |

完整审计：SHIP_GATE.md · SCORECARD.md

许可证

MIT

由 MCP Tool Shop 构建。