dsh-armory 2.2.1 → 2.3.1

package/lib/loadout.js

@@ -0,0 +1,178 @@
+// 装备清单（loadout）：把「这台机器装了什么」变成一份可分享、可对比的清单。
+//
+// 边界（决定了这里为什么只做投影，不做安装）：
+//   - 只记录名称 / 类型 / 来源 / 版本这类**身份信息**，绝不写入 env、header、
+//     token、authorization 或任何配置值；MCP 最多保留 env/header 的**键名**。
+//   - 导入只做解析与差异计算，不写盘、不安装、不调用任何市场写链。
+//   - 清单是用户主动导出、主动分享的文件；没有后端、没有账号、没有遥测。
+//
+// 数据层保持纯函数：宿主只负责收集本机条目，校验与 diff 都在这里，可独立测试。
+export const LOADOUT_SCHEMA = "dsh-armory/loadout@1";
+export const LOADOUT_MAX_ITEMS = 200;
+export const LOADOUT_MAX_BYTES = 256 * 1024;
+export const LOADOUT_DEFAULT_NAME = "我的 DSH 装备清单";
+
+const KINDS = new Set(["mcp", "skill", "expert", "plugin"]);
+const TRANSPORTS = new Set(["http", "stdio", "local", "?"]);
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]+/g;
+
+function text(value, limit) {
+  return String(value ?? "").replace(CONTROL_CHARS, " ").trim().slice(0, limit);
+}
+
+function keyOf(item) {
+  return `${item.kind}\u0000${item.name}`;
+}
+
+/** 单条投影：只放行白名单字段，其余（含任何看起来像密钥的键）一律丢弃。 */
+function normalizeItem(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const kind = text(raw.kind, 20).toLowerCase();
+  if (!KINDS.has(kind)) return null;
+  const name = text(raw.name, 120);
+  if (!name) return null;
+
+  const item = { kind, name };
+  const source = text(raw.source, 200);
+  if (source) item.source = source;
+  const version = text(raw.version, 100);
+  if (version) item.version = version;
+  const updatedAt = text(raw.updatedAt, 60);
+  if (updatedAt) item.updatedAt = updatedAt;
+
+  if (kind === "mcp") {
+    const transport = text(raw.transport, 12).toLowerCase();
+    if (TRANSPORTS.has(transport)) item.transport = transport;
+    const endpointHost = text(raw.endpointHost, 200);
+    if (endpointHost) item.endpointHost = endpointHost;
+    if (Array.isArray(raw.configKeys)) {
+      const keys = [];
+      for (const value of raw.configKeys) {
+        const key = text(value, 80);
+        if (!key || keys.includes(key)) continue;
+        keys.push(key);
+        if (keys.length >= 20) break;
+      }
+      if (keys.length) item.configKeys = keys;
+    }
+    if (typeof raw.enabled === "boolean") item.enabled = raw.enabled;
+  } else if (kind === "expert") {
+    const plugin = text(raw.plugin, 160);
+    if (plugin) item.plugin = plugin;
+  } else if (kind === "plugin") {
+    const key = text(raw.key, 160);
+    if (key) item.key = key;
+  }
+  return item;
+}
+
+function countItems(items) {
+  const counts = { total: items.length, mcp: 0, skill: 0, expert: 0, plugin: 0 };
+  for (const item of items) counts[item.kind] += 1;
+  return counts;
+}
+
+function countStatuses(rows) {
+  const counts = { total: rows.length, installed: 0, update: 0, missing: 0 };
+  for (const row of rows) counts[row.status] += 1;
+  return counts;
+}
+
+/**
+ * 解析并校验一份清单（对象或 JSON 文本）。
+ * 非法结构直接抛错；单条非法 / 重复静默丢弃，避免一个坏行毁掉整份清单。
+ */
+export function normalizeLoadout(input) {
+  let raw = input;
+  if (typeof input === "string") {
+    if (input.length > LOADOUT_MAX_BYTES) throw new Error("装备清单文件过大（上限 256KB）");
+    try {
+      raw = JSON.parse(input);
+    } catch {
+      throw new Error("不是有效的 JSON");
+    }
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("装备清单必须是一个对象");
+  if (raw.schema !== LOADOUT_SCHEMA) throw new Error("不是 dsh-armory 装备清单（schema 不匹配）");
+  if (!Array.isArray(raw.items)) throw new Error("装备清单缺少 items 数组");
+
+  const items = [];
+  const seen = new Set();
+  for (const row of raw.items) {
+    const item = normalizeItem(row);
+    if (!item) continue;
+    const key = keyOf(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push(item);
+    if (items.length >= LOADOUT_MAX_ITEMS) break;
+  }
+
+  const loadout = {
+    schema: LOADOUT_SCHEMA,
+    name: text(raw.name, 120) || LOADOUT_DEFAULT_NAME,
+    generatedAt: text(raw.generatedAt, 60),
+    items,
+    counts: countItems(items),
+  };
+  if (raw.app && typeof raw.app === "object") {
+    const name = text(raw.app.name, 80);
+    const version = text(raw.app.version, 40);
+    if (name) loadout.app = { name, ...(version ? { version } : {}) };
+  }
+  if (raw.truncated === true) loadout.truncated = true;
+  return loadout;
+}
+
+/** 由本机收集到的条目构建一份可导出的清单。 */
+export function buildLoadout({ name, items, generatedAt, appVersion } = {}) {
+  const sourceItems = Array.isArray(items) ? items : [];
+  const loadout = normalizeLoadout({
+    schema: LOADOUT_SCHEMA,
+    name: text(name, 120) || LOADOUT_DEFAULT_NAME,
+    generatedAt: text(generatedAt, 60) || new Date().toISOString(),
+    app: { name: "dsh-armory", version: text(appVersion, 40) },
+    items: sourceItems,
+  });
+  if (sourceItems.length > LOADOUT_MAX_ITEMS) loadout.truncated = true;
+  return loadout;
+}
+
+/**
+ * 与清单做本机差异对比。
+ * 只按 kind + name 匹配；双方都有版本且不同才算「可更新」，避免把缺版本的条目误判。
+ */
+export function diffLoadout(remoteInput, localItems) {
+  const remote = normalizeLoadout(remoteInput);
+  const local = new Map();
+  for (const row of Array.isArray(localItems) ? localItems : []) {
+    const item = normalizeItem(row);
+    if (item && !local.has(keyOf(item))) local.set(keyOf(item), item);
+  }
+  const rows = remote.items.map((item) => {
+    const hit = local.get(keyOf(item));
+    const status = !hit ? "missing" : item.version && hit.version && item.version !== hit.version ? "update" : "installed";
+    return { ...item, status, localVersion: hit?.version || "" };
+  });
+  return {
+    loadout: {
+      schema: remote.schema,
+      name: remote.name,
+      generatedAt: remote.generatedAt,
+      counts: remote.counts,
+    },
+    rows,
+    counts: countStatuses(rows),
+  };
+}
+
+/** 稳定、人类可读的导出文本。 */
+export function stringifyLoadout(input) {
+  return JSON.stringify(normalizeLoadout(input), null, 2);
+}
+
+/** 下载文件名：保留中文，只清理 Windows / URL 不接受的字符。 */
+export function loadoutFileName(name) {
+  const base = text(name, 80).replace(/[\\/:*?"<>|\s]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${base || "dsh-loadout"}.json`;
+}

package/lib/mcp-config.js

@@ -1,79 +1,14 @@
 import { parseDocument, Scalar, YAMLMap, YAMLSeq, isMap, isSeq } from 'yaml'
 import { isSafeExpression, makeEnvExpression, makeExpression } from './env-expression.js'
-import { MCP_CATALOG, CATEGORY_ORDER, CATEGORY_LABELS, catalogById } from './mcp-catalog.js'
-import { MCP_CATALOG_EN, CATEGORY_LABELS_EN, CATALOG_LABELS_EN } from './mcp-catalog-en.js'
 
 export const MCP_PLUGIN_NAME = '@deepseek-ai/dsh-mcp-client'
 const JS_TAG = 'tag:yaml.org,2002:js'
 const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
 const MAX_TIMER_DELAY_MS = 2147483647
 const MANAGED_CONFIG_FIELDS = ['transport', 'command', 'args', 'env', 'cwd', 'url', 'headers', 'toolCallTimeoutMs', 'failOnStartupError', 'reconnect']
-// 分类取值域与标签都来自生成的目录文件：那里是唯一真相源，顺序由生成器的 CATEGORY_ORDER
-// 决定（生成器会按它重排 MCP_CATALOG，面板的 chips 因此取到的首次出现序就是它）。
-// 再抄一份到这里就会漂移（加了分类忘了改第二处，市场的 chips 会缺一个分组）。
-export const MCP_CATEGORIES = CATEGORY_ORDER
-export const MCP_CATEGORY_LABELS = CATEGORY_LABELS
 const INTERPOLATION = /\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g
 const UNSUPPORTED_TEMPLATE = '不支持的变量表达式（只允许 ${VAR}、${VAR:-fallback} 与 ${env:VAR}）'
 
-// 内置目录 = 市场目录的投影。以前这里是硬编码的 5 条，现在是 `lib/mcp-catalog.js`
-// 的派生视图：目录加一条，内置清单与身份识别表同时跟上，不需要在两处各改一遍。
-//
-// `name`（写进配置的 serverName）取 id，是刻意的：id 一旦发布就不能改，而 serverName
-// 决定工具名 `mcp__<serverName>__<tool>`，让两者同源就不会出现「目录改名导致老配置变孤儿」。
-export const BUILTIN_MCP_SERVERS = MCP_CATALOG.map((entry) => {
-  // P1：英文覆盖与生成目录分开维护（lib/mcp-catalog-en.js）。生成器没有随本仓库
-  // 分发，直接改 mcp-catalog.js 会在下次生成时被冲掉；覆盖表缺失时逐字段回落中文。
-  const en = MCP_CATALOG_EN[entry.id] || {}
-  const server = {
-    id: entry.id,
-    label: entry.label,
-    labelEn: CATALOG_LABELS_EN[entry.id] || entry.label,
-    summary: entry.summary,
-    summaryEn: en.summary || entry.summary,
-    access: entry.access,
-    accessEn: en.access || entry.access,
-    // OPT-24：`auth` 是给面板判断「当前宿主装不装得上」的展示元数据，不是配置字段——
-    // `builtinSpec()` 只挑 MANAGED_CONFIG_FIELDS、`makeEntry()` 只挑固定字段表，两者都
-    // 不会带它，所以它和 authNote 落不进用户配置文件，mcp-client 收不到不认识的键。
-    auth: entry.auth,
-    // authNoteEn 与 authNote 同生同灭：`none` 条目没有说明，补空串会让面板分不清
-    // 「没有说明」和「说明是空的」。
-    ...(entry.authNote !== undefined ? { authNoteEn: en.authNote || entry.authNote } : {}),
-    name: entry.id,
-    transport: entry.transport,
-  }
-  for (const field of ['url', 'headers', 'command', 'args', 'authNote']) {
-    if (entry[field] !== undefined) server[field] = structuredClone(entry[field])
-  }
-  return server
-})
-
-/**
- * 「这个已配置的 server 是不是目录里的某一条」——按 endpoint / 包名认，不只看名字。
- *
- * 从目录派生而不是手工维护：以前这张表只有 5 条、和上面的硬编码清单两处同步，加一条就得
- * 记得改两个地方。现在 hosts 取自 url、packages 取自目录的 `packages`（stdio 型可从 args
- * 推导），新增条目自动生效。
- *
- * 为什么需要它：用户可能把 Exa 配成了 `my-exa`。安装时靠它识别「已经装过」而跳过，
- * 而不是再插入一条重复的。
- */
-const BUILTIN_MCP_IDENTITIES = Object.fromEntries(MCP_CATALOG.map((entry) => {
-  const hosts = []
-  if (typeof entry.url === 'string') {
-    try {
-      hosts.push(new URL(entry.url).hostname.toLowerCase())
-    } catch { /* url 不是合法 URL 时没有可认领的 host，交给 packages 兜底 */ }
-  }
-  // 包名优先取目录里显式写的（HTTP 型也可能有对应的本地 npx 包，那层知识推不出来），
-  // 没有才从 args 推导：只认非开关的参数，`-y`、`--flag` 这类不是包名。
-  const packages = entry.packages ?? (entry.args || []).filter((arg) => typeof arg === 'string'
-    && !arg.startsWith('-')
-    && /^[@a-z0-9]/i.test(arg))
-  return [entry.id, { hosts, packages }]
-}))
-
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -517,109 +452,3 @@ export function updateManagedMcpPatch(content, specs, { replace = false, removeN
   }
   return String(doc)
 }
-
-function packageTokenMatches(value, packageName) {
-  if (typeof value !== 'string') return false
-  return value.split(/\s+/).some((token) => token === packageName || token.startsWith(`${packageName}@`))
-}
-
-function matchesBuiltinIdentity(server, builtin) {
-  const name = server?.name ?? server?.serverName
-  if (name === builtin.name) return true
-  const identity = BUILTIN_MCP_IDENTITIES[builtin.id]
-  const invocation = [server?.url, server?.command, ...(Array.isArray(server?.args) ? server.args : [])].filter((value) => typeof value === 'string')
-  if (identity.hosts?.some((host) => invocation.some((value) => {
-    try {
-      return new URL(value).hostname.toLowerCase() === host
-    } catch {
-      return value.includes(`://${host}/`) || value.includes(`://${host}?`)
-    }
-  }))) return true
-  return identity.packages?.some((packageName) => invocation.some((value) => packageTokenMatches(value, packageName))) === true
-}
-
-function builtinSpec(builtin) {
-  const spec = { name: builtin.name }
-  for (const field of MANAGED_CONFIG_FIELDS) {
-    if (builtin[field] !== undefined) spec[field] = structuredClone(builtin[field])
-  }
-  return spec
-}
-
-/**
- * 目录 → 面板要的形状。
- *
- * 浏览器那半是预构建 bundle，**拿不到本模块的常量**（不 import Host 侧代码），所以市场的
- * 展示字段（分类、提供方、主页、需要哪些密钥）必须随这次 RPC 一起过去。少带一个字段的
- * 后果是面板侧只能显示 undefined，而那是 jsdom 看不出来的。
- *
- * @param {ReadonlyArray<object>} effectiveServers - 当前生效的 MCP 配置（用来判「已配置」）。
- * @returns {object[]} 面板用的目录条目。
- */
-export function builtinMcpCatalog(effectiveServers) {
-  return BUILTIN_MCP_SERVERS.map((builtin) => {
-    const matches = effectiveServers.filter((server) => matchesBuiltinIdentity(server, builtin))
-    const installedAs = [...new Set(matches.map((server) => server?.name ?? server?.serverName).filter(Boolean))]
-    const source = catalogById().get(builtin.id) || {}
-    return {
-      id: builtin.id,
-      label: builtin.label,
-      labelEn: builtin.labelEn || builtin.label,
-      summary: builtin.summary,
-      summaryEn: builtin.summaryEn || builtin.summary,
-      access: builtin.access,
-      accessEn: builtin.accessEn || builtin.access,
-      // OPT-24：`auth` 走 builtin（BUILTIN_MCP_SERVERS 已投影），面板据此降级提示
-      // oauth 条目；`authNote` 只在存在时挂键——`none` 条目根本没有这个字段，补成空串
-      // 会让面板分不清「没有说明」和「说明是空的」。
-      auth: builtin.auth,
-      ...(builtin.authNote !== undefined ? { authNote: builtin.authNote } : {}),
-      ...(builtin.authNoteEn !== undefined ? { authNoteEn: builtin.authNoteEn } : {}),
-      name: builtin.name,
-      transport: builtin.transport,
-      configuration: builtinSpec(builtin),
-      installed: installedAs.length > 0,
-      installedAs,
-      // —— 市场展示字段（bundle 侧读不到常量，只能这里带过去）——
-      category: source.category,
-      categoryLabel: MCP_CATEGORY_LABELS[source.category],
-      categoryLabelEn: CATEGORY_LABELS_EN[source.category] || MCP_CATEGORY_LABELS[source.category],
-      vendor: source.vendor,
-      homepage: source.homepage,
-      envKeys: source.envKeys || [],
-      // 连接参数（HOST/PORT/USER）与凭据分开：市场对前者显示「需填连接信息」而不是
-      // 「需密钥」——Redis / ClickHouse 是本机服务，说成要申请 Key 是误导。
-      configKeys: source.configKeys || [],
-      // 含 `<占位符>` 的条目（如 filesystem 的 `<允许访问的目录>`）装完**不能直接用**：
-      // 拿占位符当真实参数启动会失败。市场要据此提示用户先编辑，而不是显示「安装成功」。
-      placeholders: source.placeholders || [],
-    }
-  })
-}
-
-function selectedBuiltins(ids) {
-  if (!Array.isArray(ids) || !ids.length || !ids.every((id) => typeof id === 'string')) {
-    throw new Error('内置 MCP ids 必须是非空字符串数组')
-  }
-  const selectedIds = new Set(ids)
-  const knownIds = new Set(BUILTIN_MCP_SERVERS.map((builtin) => builtin.id))
-  const unknown = [...selectedIds].filter((id) => !knownIds.has(id))
-  if (unknown.length) throw new Error(`未知的内置 MCP：${unknown.join(', ')}`)
-  return BUILTIN_MCP_SERVERS.filter((builtin) => selectedIds.has(builtin.id))
-}
-
-export function appendSelectedBuiltinMcpServers(content, effectiveServers, ids, { reservedIds = [] } = {}) {
-  const selected = selectedBuiltins(ids)
-  const skipped = selected.filter((builtin) => effectiveServers.some((server) => matchesBuiltinIdentity(server, builtin)))
-  const skippedIds = new Set(skipped.map((builtin) => builtin.id))
-  const additions = selected.filter((builtin) => !skippedIds.has(builtin.id))
-  const updated = additions.length
-    ? updateManagedMcpPatch(content, additions.map(builtinSpec), { replace: false, reservedIds })
-    : content
-
-  return {
-    content: updated,
-    added: additions.map((builtin) => builtin.id),
-    skipped: skipped.map((builtin) => builtin.id),
-  }
-}

package/lib/mcp-oauth.js

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /** 插件版本：DCR 的 clientInfo 与 UA 共用一处，避免两边各自漂移。 */
-const PLUGIN_VERSION = "2.2.1";
+const PLUGIN_VERSION = "2.3.1";
 const USER_AGENT = `dsh-armory/${PLUGIN_VERSION} (+mcp-oauth)`;
 const NET_TIMEOUT_MS = 15_000;
 /** 授权流程整体存活时间：超过就判过期，避免会话表无限增长。 */
@@ -801,6 +801,4 @@ export async function authorizationOverview(serverUrl) {
     refreshable: Boolean(str(record.refreshToken)),
     savedAt: str(record.savedAt)
   };
-}
-
-export const __testing = { sessions, recordPathFor, buildAuthorizeUrl, tokenRecordPatch };
+}

package/lib/npm-downloads.js

@@ -0,0 +1,262 @@
+// npm 下载量（只读）：插件卡片底栏那个「↓N」的唯一真实来源。
+//
+// 为什么单独一层：
+//   - 社区目录（awesome-dsh-plugins 的 slim.json）每条只带 11 个字段，**没有任何下载量**，
+//     也没有插件自身的更新时间。技能卡上的 ↓8.5M 来自 SkillHub 上游，插件这边对应的
+//     真实信号只有 npm 的下载统计 —— 所以去 npm 取，绝不为让卡片"看起来丰富"而造数。
+//   - 一页 50 张卡片，全量拉取就是 50 次外网请求；因此采集必须**按可见卡片懒加载**，
+//     缓存与限流收在这一层（口径照 lib/community-meta.js：命中缓存不联网、失败回落旧数据）。
+//
+// 边界：
+//   - 只读公开接口 https://api.npmjs.org/downloads/point/last-month/<pkg>，不带任何凭据。
+//   - 单次最多 12 个包；进程内并发 2 + 每次请求起手间隔 ≥220ms；单请求 8 秒超时。
+//     这两个数是**实测出来的**（2026-10-24，本机出口）：12 个请求并发打过去 429 占一半以上，
+//     而 3 req/s 连发 15 个全绿 —— 所以宁可慢一点，也不要把公开接口打到限流。
+//   - 数字是**近 30 天窗口**，不是累计（SkillHub 那个 ↓ 是累计）—— 所以 UI 必须带
+//     tooltip 说明区间，不能让它被读成"总下载量"。
+//   - 缓存落在 ~/.dsh/armory/npm-downloads.json，staging + rename 原子写；测试可注入
+//     rootDir / fetchImpl / paceMs（paceMs 只是把节奏调快，逻辑与生产同一条路）。
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const NPM_DOWNLOADS_VERSION = 1;
+// npm 的下载统计本身按天更新，7 天缓存在"数字够新"和"少打外网"之间取值。
+export const NPM_DOWNLOADS_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const NPM_DOWNLOADS_MAX_PACKAGES = 12;
+// 429 之后冷却 60 秒（不是 10 分钟）：实测这个限流是**速率型**的，一分钟内就回血；
+// 冷却太长会让整页卡片在用户来回翻看时一直空着。
+export const NPM_DOWNLOADS_COOLDOWN_MS = 60_000;
+const NPM_DOWNLOADS_CONCURRENCY = 2;
+const NPM_DOWNLOADS_PACE_MS = 220;
+const NPM_DOWNLOADS_TIMEOUT_MS = 8_000;
+const NPM_DOWNLOADS_RETRY_MS = 900;
+
+const NPM_STATS_API = "https://api.npmjs.org/downloads/point/last-month/";
+const USER_AGENT = "@2026heshao/dsh-armory (+https://github.com/2026heshao/dsh-armory)";
+
+/** 存储根目录：显式 rootDir > 环境变量 > 真实 ~/.dsh/armory（与 community-meta 同一解析序）。 */
+function armoryRoot(options = {}) {
+  return options.rootDir || process.env.DSH_ARMORY_HOME || join(homedir(), ".dsh", "armory");
+}
+
+export function npmDownloadsPath(options = {}) {
+  return join(armoryRoot(options), "npm-downloads.json");
+}
+
+/**
+ * npm 包名合法性：unscoped `foo`、scoped `@scope/foo`，可带 . _ - 数字。
+ * 返回规范化后的名字，不合法返回 ""（脏数据绝不发进外网请求）。
+ */
+export function normalizePackageName(raw) {
+  const text = String(raw || "").trim();
+  if (!text) return "";
+  if (/^@[a-z0-9][a-z0-9._-]{0,39}\/[a-z0-9][a-z0-9._~!()'*-]{0,214}$/i.test(text)) return text;
+  if (/^[a-z0-9][a-z0-9._~!()'*-]{0,214}$/i.test(text)) return text;
+  return "";
+}
+
+/** 入参归一：字符串 / 数组 / {npm|package} 对象都收，去重、去空、最多 12 条。 */
+export function normalizePackageList(value) {
+  const rows = Array.isArray(value) ? value : [value];
+  const seen = new Set();
+  const out = [];
+  for (const row of rows) {
+    const raw = row && typeof row === "object" ? row.npm || row.package || row.name || "" : row;
+    const name = normalizePackageName(raw);
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(name);
+    if (out.length >= NPM_DOWNLOADS_MAX_PACKAGES) break;
+  }
+  return out;
+}
+
+/** npm 统计响应 → 窄投影（不落全量 JSON，缓存小且字段稳定）。 */
+export function projectDownloads(pkg, data) {
+  const downloads = typeof data?.downloads === "number" && Number.isFinite(data.downloads) ? data.downloads : null;
+  return {
+    package: String(data?.package || pkg),
+    downloads,
+    start: typeof data?.start === "string" ? data.start : "",
+    end: typeof data?.end === "string" ? data.end : "",
+    period: "last-month",
+  };
+}
+
+async function readCache(options = {}) {
+  try {
+    const raw = JSON.parse(await readFile(npmDownloadsPath(options), "utf8"));
+    const packages = raw && typeof raw.packages === "object" && raw.packages !== null && !Array.isArray(raw.packages) ? raw.packages : {};
+    return {
+      version: raw && typeof raw.version === "number" ? raw.version : NPM_DOWNLOADS_VERSION,
+      packages,
+      unavailableUntil: typeof raw?.unavailableUntil === "number" ? raw.unavailableUntil : 0,
+    };
+  } catch {
+    return { version: NPM_DOWNLOADS_VERSION, packages: {}, unavailableUntil: 0 };
+  }
+}
+
+function dirnameOf(path) {
+  const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return cut > 0 ? path.slice(0, cut) : path;
+}
+
+async function writeCache(cache, options = {}) {
+  const path = npmDownloadsPath(options);
+  await mkdir(dirnameOf(path), { recursive: true });
+  // 唯一临时名 + rename：固定 `.staging` 在并发写（refresh 与懒加载两条路同时回来）时
+  // 会互相踩踏出撕坏的文件。rename 覆盖目标，不再需要先 rm（那一步还会留出空窗）。
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(cache, null, 2));
+    await rename(tmp, path);
+  } catch (error) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function errorText(error) {
+  return String(error?.message || error || "读取失败").slice(0, 200);
+}
+
+/** scoped 名要把斜杠转义成 %2F，前导 @ 保留 —— npm 统计接口认这个写法。 */
+function statsUrl(pkg) {
+  return `${NPM_STATS_API}${pkg.replace("/", "%2F")}`;
+}
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+
+/** retry-after 可能是秒数，也可能是 HTTP-date；只认秒数，其它一律按 0（回落到默认退避）。 */
+function retryAfterMs(res) {
+  const raw = Number(res?.headers?.get?.("retry-after"));
+  return Number.isFinite(raw) && raw > 0 ? Math.min(raw * 1000, 30_000) : 0;
+}
+
+/**
+ * 全局节流闸门：所有请求（含 429 重试）都排这一个队，保证**起手间隔 ≥paceMs**。
+ * 并发数管不住速率——两个 worker 各自连发照样能冲到 9 req/s，实测那就是 429 的成因。
+ * 单次调用内共享一个 gater，调用之间不跨批持有（每批重新起算，缓存命中根本不进这里）。
+ */
+function createPacer(paceMs) {
+  let next = 0;
+  let chain = Promise.resolve();
+  return () => {
+    const run = () => {
+      const now = Date.now();
+      const at = Math.max(now, next);
+      next = at + paceMs;
+      return at > now ? wait(at - now) : undefined;
+    };
+    chain = chain.then(run, run);
+    return chain;
+  };
+}
+
+/** 取一个包的下载量；调用方已保证并发与节流，这里只管单次请求、一次退避重试与失败口径。 */
+async function fetchOne(pkg, cache, options, now, fetchImpl, pace) {
+  const key = pkg.toLowerCase();
+  const entry = cache.packages[key];
+  const send = async () => fetchImpl(statsUrl(pkg), {
+    headers: { "user-agent": USER_AGENT, accept: "application/json" },
+    signal: AbortSignal.timeout(NPM_DOWNLOADS_TIMEOUT_MS),
+  });
+  try {
+    await pace();
+    let response = await send();
+    // 429 是速率限流、不是「这个包没有」：等一会儿再试一次，很多数字就是这么救回来的。
+    if (response.status === 429) {
+      const backoff = Math.min(retryAfterMs(response) || NPM_DOWNLOADS_RETRY_MS, 5_000);
+      await wait(backoff);
+      await pace();
+      response = await send();
+    }
+    if (response.status === 404) {
+      // 包下架 / 改名 / 从未被统计：这一条没有下载量，卡片就少这一枚，绝不显示 0 冒充"没人下"。
+      cache.packages[key] = { fetchedAt: now, missing: true, data: null };
+      return { ok: false, missing: true, package: pkg };
+    }
+    if (response.status === 429 || response.status === 500 || response.status === 502 || response.status === 503) {
+      cache.unavailableUntil = now + NPM_DOWNLOADS_COOLDOWN_MS;
+      throw new Error(`npm 统计接口暂时不可用（HTTP ${response.status}）`);
+    }
+    if (!response.ok) throw new Error(`npm 统计接口返回 HTTP ${response.status}`);
+    const data = projectDownloads(pkg, await response.json());
+    if (data.downloads === null) {
+      cache.packages[key] = { fetchedAt: now, missing: true, data: null };
+      return { ok: false, missing: true, package: pkg };
+    }
+    cache.packages[key] = { fetchedAt: now, missing: false, data };
+    return { ok: true, cached: false, ...data };
+  } catch (error) {
+    const message = errorText(error);
+    // 有旧值就继续显示旧值（stale），网络抖动绝不能把卡片上的数字打没。
+    if (entry?.data) return { ok: true, cached: true, stale: true, ...entry.data, error: message };
+    return { ok: false, error: message, package: pkg };
+  }
+}
+
+/**
+ * 批量读取 npm 包近 30 天下载量。
+ *
+ * 入参：`{ packages: string[] | {npm}[] | string, refresh?: boolean }`
+ * 返回：`{ packages: { "<pkg>": { ok, downloads?, start?, end?, cached?, stale?, missing?, error? } }, fetchedAt }`
+ *
+ * 单条失败不抛整体错误：UI 要能区分「这个包查不到」和「整个接口挂了」。
+ * 失败的包**不写缓存**（下次翻页/重载会再试），确认没有的包才粘住 7 天。
+ */
+export async function wbNpmDownloads(payload = {}, options = {}) {
+  const packages = normalizePackageList(payload?.packages ?? payload?.package ?? payload?.npm);
+  const now = Date.now();
+  if (!packages.length) return { packages: {}, fetchedAt: now };
+  const cache = await readCache(options);
+  const fetchImpl = typeof options.fetchImpl === "function" ? options.fetchImpl : fetch;
+  const pace = createPacer(Number.isFinite(Number(options.paceMs)) ? Math.max(0, Number(options.paceMs)) : NPM_DOWNLOADS_PACE_MS);
+  const results = {};
+  const pending = [];
+
+  for (const pkg of packages) {
+    const entry = cache.packages[pkg.toLowerCase()];
+    const fresh = entry && entry.data && now - Number(entry.fetchedAt || 0) < NPM_DOWNLOADS_TTL_MS;
+    if (entry && entry.missing && now - Number(entry.fetchedAt || 0) < NPM_DOWNLOADS_TTL_MS && payload?.refresh !== true) {
+      // 7 天内查过且确认没有（下架 / 未统计）：不重复打外网。
+      results[pkg] = { ok: false, missing: true, cached: true, package: pkg };
+      continue;
+    }
+    if (fresh && payload?.refresh !== true) {
+      results[pkg] = { ok: true, cached: true, ...entry.data };
+      continue;
+    }
+    if (cache.unavailableUntil && now < cache.unavailableUntil) {
+      results[pkg] = entry?.data
+        ? { ok: true, cached: true, stale: true, ...entry.data, error: "npm 统计接口冷却中，显示的是缓存" }
+        : { ok: false, error: "npm 统计接口冷却中，稍后再试", package: pkg };
+      continue;
+    }
+    pending.push(pkg);
+  }
+
+  // 并发 2 + 起手节流：并发只是别把连接数堆起来，真正决定 429 的是**速率**。
+  const cursor = { i: 0 };
+  const workers = Array.from({ length: Math.min(NPM_DOWNLOADS_CONCURRENCY, pending.length) }, async () => {
+    for (;;) {
+      const index = cursor.i;
+      cursor.i += 1;
+      if (index >= pending.length) return;
+      const pkg = pending[index];
+      results[pkg] = await fetchOne(pkg, cache, options, now, fetchImpl, pace);
+    }
+  });
+  await Promise.all(workers);
+
+  try {
+    await writeCache(cache, options);
+  } catch {
+    // 缓存写失败不影响本次结果；下次只是多打一次网络。
+  }
+  return { packages: results, fetchedAt: now };
+}

package/lib/suites-registry.js

@@ -111,12 +111,18 @@ function dirnameOf(path) {
   return cut > 0 ? path.slice(0, cut) : path;
 }
 
-/** staging + rename 原子写（与 wb-registry.writeAtomic 同一模式；Windows rename 不覆盖）。 */
+/** 唯一临时名 + rename 原子写（与 wb-registry.writeAtomic 同一模式）：rename 覆盖已存在
+ *  文件（Windows 实测），固定 `.staging` 反而在并发保存时互相消费对方的临时文件。 */
 async function writeAtomic(path, doc) {
   await mkdir(dirnameOf(path), { recursive: true });
-  await writeFile(`${path}.staging`, JSON.stringify(doc, null, 2));
-  await rm(path, { force: true });
-  await rename(`${path}.staging`, path);
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(doc, null, 2));
+    await rename(tmp, path);
+  } catch (error) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 /** 读取时同样过一遍 normalize：手改坏的条目在读侧就被拉回合法形状。 */