dsh-mcp-connector 0.2.19 → 0.2.20

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 ## [Unreleased]
 
+## [0.2.20] - 2026-08-25
+
+### Changed
+
+- 默认公共 Registry 改用 jsDelivr CDN，并在主源请求失败时按顺序回退到 GitHub Raw，提升不同网络环境下远程市场目录的可用性。
+- DSH Bundle 补丁与插件默认配置统一使用 jsDelivr 主源；用户显式配置的自定义目录地址保持单一来源，不会被公共备用源覆盖。
+
+### Fixed
+
+- 主源与备用源分别处理缓存协商；备用源不会复用或写入主源 ETag，避免跨源缓存标识导致错误的 `304 Not Modified`。
+- 目录主源失败时记录逐源告警，并在备用源成功后继续刷新市场，避免一次网络故障导致远程目录完全不可用。
+
+### Verification
+
+- 插件 98 项自动测试、lint、npm 发布文件白名单/敏感内容扫描和 `git diff --check` 通过。
+- 新增主源失败回退、主源 `304` 不访问备用源、默认配置与 Bundle 配置一致，以及自定义目录不启用公共回退的回归测试。
+
 ## [0.2.19] - 2026-08-24
 
 ### Fixed
@@ -331,7 +348,8 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.19...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.20...HEAD
+[0.2.20]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.19...v0.2.20
 [0.2.19]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.18...v0.2.19
 [0.2.18]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.17...v0.2.18
 [0.2.17]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.16...v0.2.17

package/README.en.md

@@ -71,7 +71,7 @@ The detailed [Chinese user guide](docs/USER-GUIDE.md) covers category browsing,
 
 ## Connector catalog
 
-The package contains a bundled fallback catalog. By default, it refreshes from the public [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry); cached or bundled data remains available if the remote registry cannot be reached.
+The package contains a bundled fallback catalog. By default, it refreshes the public [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry) through jsDelivr, then tries GitHub raw if the primary source fails; cached or bundled data remains available if neither remote source can be reached. jsDelivr branch URLs can lag behind a newly merged registry commit, so new cards may not appear immediately.
 
 The public connector registration process and descriptor requirements are documented in [docs/MARKET-REGISTRATION.md](docs/MARKET-REGISTRATION.md).
 The stdio architecture, passthrough boundary, and security constraints are documented in [docs/STDIO-SUPPORT.md](docs/STDIO-SUPPORT.md).
@@ -84,14 +84,14 @@ The default bundle configuration is in `cordis.patch.yml`:
 - id: mcp-connector
   name: dsh-mcp-connector
   config:
-    catalogUrl: 'https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json'
+    catalogUrl: 'https://cdn.jsdelivr.net/gh/duhu2000/dsh-mcp-connector-registry@main/catalog.json'
     persistSecrets: true
     entryPrefix: mcp
     refreshSkewMs: 300000
     openBrowser: true
 ```
 
-Set `catalogUrl` to an empty string for an explicitly offline/private setup.
+Set `catalogUrl` to an empty string for an explicitly offline/private setup. A custom non-default URL is used as-is and does not fall back to the public registry.
 
 ## Development and release checks
 
@@ -105,7 +105,7 @@ npm run dev:ui
 
 `npm run check` performs syntax checks, automated tests, and an npm package allowlist/sensitive-content audit. `npm run market:check` tracks the external DSH marketplace PR and live directory. Tags matching `v*` trigger GitHub Actions; the tag must match `package.json`. npm releases use Trusted Publishing through GitHub OIDC and do not require a long-lived `NPM_TOKEN`.
 
-The current public version is [`dsh-mcp-connector@0.2.19`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.19](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.19).
+The current public version is [`dsh-mcp-connector@0.2.20`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.20](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.20).
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md) for the Desktop release checklist.
 

package/README.md

@@ -79,14 +79,14 @@ Bundle 默认配置位于 `cordis.patch.yml`：
 - id: mcp-connector
   name: dsh-mcp-connector
   config:
-    catalogUrl: 'https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json'
+    catalogUrl: 'https://cdn.jsdelivr.net/gh/duhu2000/dsh-mcp-connector-registry@main/catalog.json'
     persistSecrets: true
     entryPrefix: mcp
     refreshSkewMs: 300000
     openBrowser: true
 ```
 
-`catalogUrl` 默认指向公共 [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry)，支持 ETag/TTL 缓存；拉取失败时继续使用上次缓存或随包内置目录。需要离线/私有模式时可将其显式设为空字符串。
+`catalogUrl` 默认通过 jsDelivr CDN 读取公共 [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry)，支持 ETag/TTL 缓存；主源失败时自动尝试 GitHub raw 备用源，再回退到上次缓存或随包内置目录。jsDelivr 的分支 URL 可能存在缓存延迟，因此 Registry 合并后的新卡片不保证秒级出现。需要离线/私有模式时可将 `catalogUrl` 显式设为空字符串；显式配置其他目录 URL 时不会自动切换到公共备用源。
 
 ## 开发与发布门禁
 
@@ -100,7 +100,7 @@ npm run dev:ui
 
 `check` 执行语法检查、自动测试和 npm 发布包白名单校验；`market:check` 检查外部 DSH 市场 PR 与线上目录；`dev:ui` 启动不含真实凭据的本地 mock 市场。CI 使用 `--legacy-peer-deps` 安装显式测试依赖，DSH 运行期 peer 仍由 Host 提供。`v*` Tag 会触发 GitHub Actions；Tag 必须与 `package.json` 版本一致。Release 通过 npm Trusted Publishing (GitHub OIDC) 发布，不依赖长期 `NPM_TOKEN`。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.19`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.19](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.19)。
+当前公开版本为 [`dsh-mcp-connector@0.2.20`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.20](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.20)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/cordis.patch.yml

@@ -5,7 +5,7 @@
     - id: mcp-connector
       name: 'dsh-mcp-connector'
       config:
-        catalogUrl: 'https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json'
+        catalogUrl: 'https://cdn.jsdelivr.net/gh/duhu2000/dsh-mcp-connector-registry@main/catalog.json'
         persistSecrets: true
         entryPrefix: 'mcp'
         refreshSkewMs: 300000

package/docs/MARKET-REGISTRATION.md

@@ -25,7 +25,7 @@ Bearer/API Key 型连接器可在卡片上点「配置」，一次填写凭据
 3. 提交 PR。CI 会检查 Schema、重复 id/serverName、密钥、URL、MCP initialize、OAuth 元数据和图标。
 4. 合并后 CI 重建根目录 `catalog.json`；客户端点击“刷新”后可见，无需重新发布 `dsh-mcp-connector` npm 包。
 
-插件默认读取 `https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json`；远程不可用时自动回退上次缓存或随包内置目录。
+插件默认通过 `https://cdn.jsdelivr.net/gh/duhu2000/dsh-mcp-connector-registry@main/catalog.json` 读取目录；主源失败时依次尝试 GitHub raw 备用源、上次缓存和随包内置目录。jsDelivr 的分支 URL 存在缓存延迟，合并后的新卡片可能不会秒级出现。
 
 ## 4. DSH 外部插件市场验收
 

package/lib/catalog.js

@@ -134,6 +134,28 @@ export async function fetchRemoteCatalog(catalogUrl, { requestTimeoutMs, etag }
   }
 }
 
+/**
+ * 按顺序拉取远程 registry。仅主源使用缓存 ETag；备用源总是全量拉取，
+ * 且不返回备用源 ETag，避免下一次请求把它误发给主源。
+ */
+export async function fetchRemoteCatalogWithFallback(catalogUrl, fallbackUrls = [], opts = {}) {
+  const urls = [catalogUrl, ...fallbackUrls].filter(Boolean);
+  let lastError;
+  for (let index = 0; index < urls.length; index += 1) {
+    try {
+      const fetched = await fetchRemoteCatalog(urls[index], {
+        requestTimeoutMs: opts.requestTimeoutMs,
+        etag: index === 0 ? opts.etag : undefined,
+      });
+      return index === 0 ? fetched : { ...fetched, etag: undefined };
+    } catch (error) {
+      lastError = error;
+      opts.onSourceError?.({ index, error });
+    }
+  }
+  throw lastError ?? new Error('catalog fetch failed for all sources');
+}
+
 /** 合并多层来源（sources 为低→高优先级的 descriptor 数组），再应用本地覆盖。 */
 export function mergeCatalog(sources, overrides = new Map()) {
   const merged = new Map();

package/lib/constants.js

@@ -16,9 +16,16 @@ export const JSON_CONNECTOR_ID = '__json__';
 /** 保留 id 前缀：社区 PR 注册表拒绝占用 */
 export const RESERVED_ID_PREFIXES = ['qcc-', 'dsh-', 'mcp-connector-'];
 
-/** 请求 / 刷新默认值 */
+/** 远程 registry 主目录源（jsDelivr CDN，国内网络更稳定） */
 export const DEFAULT_CATALOG_URL =
-  'https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json';
+  'https://cdn.jsdelivr.net/gh/duhu2000/dsh-mcp-connector-registry@main/catalog.json';
+
+/** 默认目录源失败时依次尝试；仅用于未自定义 catalogUrl 的配置。 */
+export const DEFAULT_CATALOG_FALLBACK_URLS = [
+  'https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector-registry/main/catalog.json',
+];
+
+/** 请求 / 刷新默认值 */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 export const DEFAULT_REFRESH_SKEW_MS = 300_000;
 export const DEFAULT_CATALOG_TTL_MS = 3_600_000;

package/lib/index.js

@@ -13,13 +13,14 @@ import z from '@deepseek-ai/schemastery';
 import {
   DEFAULT_ACCOUNT,
   DEFAULT_CATALOG_URL,
+  DEFAULT_CATALOG_FALLBACK_URLS,
   DEFAULT_REQUEST_TIMEOUT_MS,
   DEFAULT_REFRESH_SKEW_MS,
   DEFAULT_CATALOG_TTL_MS,
 } from './constants.js';
 import { defineConnectorDomain, ConnectionStore, GrantStore, CatalogStore } from './stores.js';
 import { normalizeConnectorDescriptor, normalizeConnectionRecord } from './schema.js';
-import { loadBundledCatalog, fetchRemoteCatalog, mergeCatalog, listCatalog, auditDescriptor, auditRawDescriptor, readLimitedJson } from './catalog.js';
+import { loadBundledCatalog, fetchRemoteCatalogWithFallback, mergeCatalog, listCatalog, auditDescriptor, auditRawDescriptor, readLimitedJson } from './catalog.js';
 import { oauthAuthorize } from './connectors/oauth-connector.js';
 import { buildManualRecord } from './connectors/manual-connector.js';
 import { normalizeJsonImport } from './connectors/json-connector.js';
@@ -91,6 +92,15 @@ export async function apply(ctx, config) {
     state.merged = mergeCatalog(sources, state.overrides);
   }
 
+  function catalogFallbackUrls() {
+    return config.catalogUrl === DEFAULT_CATALOG_URL ? DEFAULT_CATALOG_FALLBACK_URLS : [];
+  }
+
+  function warnCatalogSourceFailure({ index, error }) {
+    const source = index === 0 ? 'primary' : `fallback ${index}`;
+    logger.warn(`catalog fetch ${source} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
   async function loadCatalog() {
     const dynamicRec = await catalogStore.getDynamic().catch(() => null);
     if (dynamicRec?.connectors) {
@@ -116,10 +126,15 @@ export async function apply(ctx, config) {
     if (config.catalogUrl) {
       const cached = await catalogStore.getRemote().catch(() => null);
       try {
-        const fetched = await fetchRemoteCatalog(config.catalogUrl, {
-          requestTimeoutMs: config.requestTimeoutMs,
-          etag: cached?.etag,
-        });
+        const fetched = await fetchRemoteCatalogWithFallback(
+          config.catalogUrl,
+          catalogFallbackUrls(),
+          {
+            requestTimeoutMs: config.requestTimeoutMs,
+            etag: cached?.etag,
+            onSourceError: warnCatalogSourceFailure,
+          },
+        );
         if (fetched.notModified) {
           state.remoteConnectors = cached?.connectors ?? [];
         } else {
@@ -816,7 +831,14 @@ export async function apply(ctx, config) {
         return { ok: true, message: `市场已刷新，共 ${visibleCount} 个连接器` };
       }
       try {
-        const fetched = await fetchRemoteCatalog(config.catalogUrl, { requestTimeoutMs: config.requestTimeoutMs });
+        const fetched = await fetchRemoteCatalogWithFallback(
+          config.catalogUrl,
+          catalogFallbackUrls(),
+          {
+            requestTimeoutMs: config.requestTimeoutMs,
+            onSourceError: warnCatalogSourceFailure,
+          },
+        );
         state.remoteConnectors = fetched.connectors;
         await catalogStore.putRemote({ etag: fetched.etag, connectors: fetched.connectors }).catch(() => {});
         await recomputeMerged();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "General-purpose MCP connector, connection manager, plugin extension, and integration marketplace for DeepSeek Harness, initiated and maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",