![\"registry-stats](\"https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png\")
\r\n\n 日本語 | English | Español | Français | हिन्दी | Italiano | Português (BR)\n
\n\n\r\n \r\n
\r\n Five registries. One engine. Dashboard included.\r\n
\r\n\n\r\n ![\"CI\"](\"https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg\"){kind=icon}
\r\n ![\"MIT](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\r\n ![\"npm](\"https://img.shields.io/npm/v/@mcptoolshop/registry-stats\")
![\"Dashboard\"](\"https://img.shields.io/badge/Dashboard-live-green\"){kind=icon}
![\"Landing](\"https://img.shields.io/badge/Landing_Page-live-blue\"){kind=icon}
\r\n Dashboard ·\r\n Desktop App ·\r\n Install ·\r\n CLI ·\r\n API ·\r\n REST Server ·\r\n Config ·\r\n License\r\n
\r\n\n---\r\n\n您可以在 npm、PyPI、NuGet、VS Code Marketplace 以及 Docker Hub 上发布软件包。目前，要了解“我的软件包表现如何？”，您需要查看五个不同的网站。**registry-stats** 是一个完整的平台：一个 TypeScript 引擎（包含命令行工具、API 和 REST 服务器），一个实时 Web 控制面板，以及一个原生 Windows 桌面应用程序——所有这些都来自一个代码仓库。\n\n没有运行时依赖。使用原生的 `fetch()` 方法。Node 18+。\n\n## 内容\n\n| 层 | 功能 |\n|-------|-------------|\n| **Engine** | TypeScript 库 + 命令行工具 + REST 服务器。使用一个界面查询五个注册中心。已发布到 npm，名为 `@mcptoolshop/registry-stats`。 |\n| **Dashboard** | 一个由Astro驱动的Web应用程序，配备Pulse AI智能助手（支持语音流、网页搜索、全屏模式、GitHub数据连接器），包含六个交互式图表，支持实时刷新，并可导出报告（PDF/JSONL/Markdown），以及分Tab的帮助文档。该应用程序每周由CI自动构建，并可按需刷新。 |\n| **Desktop** | 一个原生 Windows 应用程序，使用 WinUI 3 + WebView2。将控制面板打包在本地，按需获取实时统计数据。 |\n\n## 控制面板\n\n一个自动更新的统计信息控制面板位于 [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/)。\n\n- **分Tab界面** — 包含“首页”、“分析”、“排行榜”和“帮助”等Tab。\n- **Pulse AI智能助手** — 基于Ollama的对话式助手，支持语音合成（LLM模型输出时同步语音，提供4种声音，通过[mcp-voice-soundboard](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard)实现），网页搜索（Wikipedia + 可选的SearXNG），自动语音播报，全屏模式，GitHub组织数据连接器，模型选择器，以及对话记忆功能。\n- **关键指标概览** — 健康评分（0–100），多样性指数，每周变化，所有注册表的总下载量。\n- **六个交互式图表** — 30天趋势图（聚合/按注册表/前5名切换），注册表份额（极坐标图），投资组合风险（直方图 + Gini系数和P90），前10名增长情况，速度跟踪图（带sparklines），以及30天热力图（带异常值检测，>2σ）。\n- **智能增长引擎** — 通过基线阈值、百分比上限和阻尼速度公式，处理小基数偏差问题。\n- **可执行的洞察** — 自动生成推荐和关注提醒，用于识别下降的软件包。\n- **Pulse面板** — 分屏显示已建立的流行软件包（≥ 50次/周下载）和新兴/新软件包，并带有内联7天sparklines，绝对值和百分比变化，基线信息，以及简要的执行摘要。\n- **实时刷新** — 客户端按需从npm和PyPI API获取数据，并显示进度指示器；结果缓存在sessionStorage中（5分钟TTL），因此Tab切换速度非常快。\n- **导出报告** — 在“刷新”按钮旁边，提供下拉菜单，可以选择三种格式：**Exec PDF**（通过jsPDF实现），**LLM JSONL**（用于AI模型输入的结构化记录），以及**Dev Markdown**（GFM表格）。\n- **排行榜** — 按照每周下载量对132个软件包进行排名，并带有内联30天sparklines和智能趋势标识。\n- **配置页面** — 包含投资组合编辑器（带验证功能），注册表同步辅助部分，以及流水线概览。\n- **帮助Tab** — 提供用户友好的指南，涵盖每个Tab，关键概念，AI助手使用技巧，数据流水线，以及有用的链接。\n- **深色/浅色主题** — 自动跟随系统偏好设置。\n\n数据在构建时获取，并每周由 CI 自动重建（每周一 06:00 UTC）。实时刷新直接从注册中心 API 获取最新数据。在 `site/src/data/packages.json` 中配置要跟踪的软件包（5 个注册中心，共 132 个软件包）。\n\n## 桌面应用程序\n\n一个原生 Windows 应用程序，它将控制面板封装在一个本地 WebView2 容器中：\n\n- **支持离线使用** — 包含打包的 HTML/CSS/JS；无需互联网连接即可使用\n- **实时刷新** — 按需从 GitHub Pages 获取 `stats.json` 文件\n- **CSV 导出** — 一键导出排行榜数据\n- **MSIX 软件包** — 通过 `desktop-ci.yml` 在 CI 中构建和签名\n\n桌面应用程序的源代码位于 `desktop/` 目录中。使用 .NET 10 MAUI 构建，目标是 WinUI 3。\n\n## 安装\n\n```bash\r\nnpm install @mcptoolshop/registry-stats\r\n```\r\n\n## 命令行界面 (CLI)\n\n```bash\r\n# Query a single registry\r\nregistry-stats express -r npm\r\n# npm | express\r\n# month: 283,472,710 week: 67,367,773 day: 11,566,113\r\n\r\n# Query all registries at once\r\nregistry-stats express\r\n\r\n# Time series with monthly breakdown + trend\r\nregistry-stats express -r npm --range 2025-01-01:2025-06-30\r\n\r\n# Raw JSON output\r\nregistry-stats express -r npm --json\r\n\r\n# Other registries\r\nregistry-stats requests -r pypi\r\nregistry-stats Newtonsoft.Json -r nuget\r\nregistry-stats esbenp.prettier-vscode -r vscode\r\nregistry-stats library/node -r docker\r\n\r\n# Create a config file\r\nregistry-stats --init\r\n\r\n# Run with config — fetches all tracked packages\r\nregistry-stats\r\n\r\n# Compare across registries\r\nregistry-stats express --compare\r\n\r\n# Export as CSV or chart-friendly JSON\r\nregistry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv\r\nregistry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart\r\n\r\n# Start a REST API server\r\nregistry-stats serve --port 3000\r\n```\r\n\n## 配置文件\n\n在您的项目根目录下创建一个 `registry-stats.config.json` 文件（或者运行 `registry-stats --init` 命令）：\n\n```json\r\n{\r\n \"registries\": [\"npm\", \"pypi\", \"nuget\", \"vscode\", \"docker\"],\r\n \"packages\": {\r\n \"mcpt\": {\r\n \"npm\": \"mcpt\",\r\n \"pypi\": \"mcpt\"\r\n },\r\n \"tool-compass\": {\r\n \"npm\": \"@mcptoolshop/tool-compass\",\r\n \"vscode\": \"mcp-tool-shop.tool-compass\"\r\n }\r\n },\r\n \"cache\": true,\r\n \"cacheTtlMs\": 300000,\r\n \"concurrency\": 5\r\n}\r\n```\r\n\n运行 `registry-stats` 命令，不带任何参数，即可获取所有配置软件包的统计数据。命令行界面会从当前工作目录向上查找最近的配置文件。\n\n配置文件也可以通过编程方式访问：\n\n```typescript\r\nimport { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';\r\n\r\nconst config = loadConfig(); // finds nearest config file, or null\r\nconst defaults = defaultConfig(); // returns default Config object\r\nconst template = starterConfig(); // returns starter JSON string\r\n```\r\n\n## 编程 API\n\n```typescript\r\nimport { stats, calc, createCache } from '@mcptoolshop/registry-stats';\r\n\r\n// Single registry\r\nconst npm = await stats('npm', 'express');\r\nconst pypi = await stats('pypi', 'requests');\r\nconst nuget = await stats('nuget', 'Newtonsoft.Json');\r\nconst vscode = await stats('vscode', 'esbenp.prettier-vscode');\r\nconst docker = await stats('docker', 'library/node');\r\n\r\n// All registries at once (uses Promise.allSettled — never throws)\r\nconst all = await stats.all('express');\r\n\r\n// Bulk — multiple packages, concurrency-limited (default: 5)\r\nconst bulk = await stats.bulk('npm', ['express', 'koa', 'fastify']);\r\n\r\n// Time series (npm + pypi only)\r\nconst daily = await stats.range('npm', 'express', '2025-01-01', '2025-06-30');\r\n\r\n// Calculations\r\ncalc.total(daily); // sum of all downloads\r\ncalc.avg(daily); // daily average\r\ncalc.groupTotals(calc.monthly(daily)); // { '2025-01': 134982, ... }\r\ncalc.trend(daily); // { direction: 'up', changePercent: 8.3 }\r\ncalc.movingAvg(daily, 7); // 7-day moving average\r\ncalc.popularity(daily); // 0-100 log-scale score\r\n\r\n// Export formats\r\ncalc.toCSV(daily); // \"date,downloads\\n2025-01-01,1234\\n...\"\r\ncalc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ label, data }] }\r\n\r\n// Comparison — same package across registries\r\nconst comparison = await stats.compare('express');\r\nawait stats.compare('express', ['npm', 'pypi']); // specific registries only\r\n\r\n// Caching (5 min TTL, in-memory)\r\nconst cache = createCache();\r\nawait stats('npm', 'express', { cache }); // fetches\r\nawait stats('npm', 'express', { cache }); // cache hit\r\n```\r\n\n## 仓库支持\n\n| 仓库 | 软件包格式 | 时间序列 | 可用数据 |\n|----------|---------------|-------------|----------------|\n| `npm` | `express`, `@scope/pkg` | 是 (549 天) | 最近一天、最近一周、最近一个月 |\n| `pypi` | `requests` | 是 (180 天) | 最近一天、最近一周、最近一个月、总数 |\n| `nuget` | `Newtonsoft.Json` | No | 总数 |\n| `vscode` | `publisher.extension` | No | 总数（安装量）、评分、趋势 |\n| `docker` | `namespace/repo` | No | 总数（拉取次数）、星级 |\n\n## 内置可靠性\n\n- 自动重试，并在遇到 429/5xx 错误时采用指数退避策略\n- 尊重 `Retry-After` 头部信息\n- 批量请求的并发限制\n- 可选的 TTL 缓存（可插拔，通过 `StatsCache` 接口，您可以自定义 Redis 或文件后端）\n\n## REST API 服务器\n\n可以作为微服务运行，也可以嵌入到您自己的服务器中：\n\n```bash\r\nregistry-stats serve --port 3000\r\n```\r\n\n```\r\nGET /stats/:package # all registries\r\nGET /stats/:registry/:package # single registry\r\nGET /compare/:package?registries=npm,pypi\r\nGET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart\r\n```\r\n\n用于自定义服务器或无服务器环境的编程用法：\n\n```typescript\r\nimport { createHandler, serve } from '@mcptoolshop/registry-stats';\r\n\r\n// Option 1: Quick start\r\nserve({ port: 3000 });\r\n\r\n// Option 2: Bring your own server\r\nimport { createServer } from 'node:http';\r\nconst handler = createHandler();\r\ncreateServer(handler).listen(3000);\r\n```\r\n\n## 自定义仓库\n\n```typescript\r\nimport { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';\r\n\r\nconst cargo: RegistryProvider = {\r\n name: 'cargo',\r\n async getStats(pkg) {\r\n const res = await fetch(`https://crates.io/api/v1/crates/${pkg}`);\r\n const json = await res.json();\r\n return {\r\n registry: 'cargo' as any,\r\n package: pkg,\r\n downloads: { total: json.crate.downloads },\r\n fetchedAt: new Date().toISOString(),\r\n };\r\n },\r\n};\r\n\r\nregisterProvider(cargo);\r\nawait stats('cargo', 'serde');\r\n```\r\n\n## 代码仓库结构\n\n```\r\nregistry-stats/\r\n├── src/ # TypeScript engine (published to npm)\r\n├── site/ # Astro dashboard + landing page (deployed to GitHub Pages)\r\n├── desktop/ # WinUI 3 desktop app (.NET 10 MAUI)\r\n└── test/ # Library tests (vitest)\r\n```\r\n\n## 开发\n\n```bash\r\n# Engine\r\nnpm install && npm run build && npm test\r\n\r\n# Dashboard (dev server)\r\nnpm run site:dev\r\n\r\n# Dashboard (production build)\r\nnpm run site:build\r\n```\r\n\n## 安全与数据范围\n\n| 方面 | 详细信息 |\n|--------|--------|\n| **Data touched** | 从 npm、PyPI、NuGet、VS Code Marketplace、Docker Hub 获取的公开下载统计数据。可选的内存缓存。 |\n| **Data NOT touched** | 无遥测。无分析。无凭证存储。无用户数据。无文件写入。 |\n| **Permissions** | 读取：通过 HTTPS 访问公共注册表 API。写入：仅限于标准输出/标准错误输出。 |\n| **Network** | 通过 HTTPS 访问公共注册表 API。可选的本地 REST 服务器。 |\n| **Telemetry** | 未收集或发送任何数据。 |\n\n请参阅 [SECURITY.md](SECURITY.md) 以报告漏洞。\n\n## 评分卡\n\n| 类别 | 评分 |\n|----------|-------|\n| A. 安全性 | 10 |\n| B. 错误处理 | 10 |\n| C. 操作文档 | 10 |\n| D. 发布规范 | 10 |\n| E. 身份验证（软性） | 10 |\n| **Overall** | **50/50** |\n\n> 完整审计：[SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)\n\n## 许可证\n\nMIT\n\n---\r\n\n由 MCP Tool Shop 构建。\n","readmeFilename":"README.zh.md"}