dsh-m 0.9.31 → 0.9.32

package/CHANGELOG.md

@@ -8,6 +8,16 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## 中文
 
+### 0.9.32 变更：npm registry 路由自适应——元数据预取换源/镜像自愈（ADR-0012）
+
+- **动机**：2026-10-04 上海 Windows 桌面机实证——元数据预取写死直连 registry.npmjs.org，间歇性超时使升级在委派 pnpm 之前夭折（`fetch failed` / `The operation was aborted due to timeout`，且 `.plugin-manager/logs` 无对应操作日志），而 npmmirror 镜像早已同步目标版本；同期首尔腾讯云机 npmjs 直连良好。两台机器需要零配置各自可用。
+- **读分类路由（L1/L3）**：检测读（`npmLatest` 升级探测 / `npmPackumentTimes` 发布时刻）恒以 npmjs 权威源优先、首腿超时收紧 ≤5s、失败降级生效源；履约读（`npmVersion` 精确版本元数据 / `npmPackument` 预热）走生效源优先。`npmPackument` 的 registry 参数此前被静默忽略，本版修复（显式参数开始生效，测试钉住）。
+- **L0 传输层**：httpx 换 undici 自带 fetch + 自建 dispatcher（`EnvHttpProxyAgent` 显式交接代理解析）——元数据预取开始感知 `HTTP(S)_PROXY` / `npm_config_*` 代理，并规避宿主 undici 全局 dispatcher 污染（dsh-market net.ts #742 同族）；`fetchLimited` 新增 PUT 方法（仅供 sync 原语）；网络失败错误附 `via` 上下文，失败摘要仅在代理路径渲染「（经 <掩码代理>）」。
+- **L2 镜像滞后自愈**：`NO_MATCHING_VERSION` 且 registry 字段指名 npmmirror（分类层结构化识别、完整文本上判定、上层零 regex）→ 按需同步镜像（`registry-direct.npmmirror.com/<pkg>/sync`，PUT）→ 既有退避重试（heal 记 `B3_NPMMIRROR_SYNC`）；`npmVersion` 履约阶梯同步适用（404 → sync → 等待 10s → 同源重试 → npmjs 兜底）；sync 受理后作废 latest 缓存。`DSHM_MIRROR_SYNC=0` 一键关闭。
+- **新模块 `src/core/npm-route.ts`**：`DSHM_NPM_REGISTRY` 源覆盖（最高优先，设了跳过探测）> [.npmrc registry, npmjs, npmmirror]；probe-once（2.5s 共享预算、single-flight、胜者须完整响应带 version）；决策持久化 `<cacheDir>/npm-route.json`（删文件即重探）；全候选失败仅内存回退 npmjs（60s TTL 后重探、不落盘）。生效源切换自动作废 latest / packument 两级缓存。
+- **wire 测试缝隙迁移**：既有 mock `globalThis.fetch` 的测试缝隙迁至 `_setWireFetchForTests`（versions / npm-integrity / registry-check 三文件，断言与计数语义不变）。
+- **测试**：净增 41 例（L0 代理解析/wire 转发/via/PUT、npm-route 12 例、读分类路由、registry 分类字段、B3 sync、L4 摘要、kill-switch 阶梯/集成、尾斜杠归一）；全量 1128 tests，本机 1103 pass / 15 fail——15 项全部为 Windows 平台既有 symlink 语义用例（与改动前基线集合逐项一致，零回归）；typecheck 零错误。真机验收（上海机 scoped 自研包窗口内升级 + 首尔机 `dshm outdated`）随发版执行。
+
 ### 0.9.31 变更：doctor 支持 desktop profile（CLI 例外开口 + farmChecked 语义修订，ADR-0011）
 
 - **动机**：Windows desktop 机实机报告证实 core 引擎本就 profileDir 参数化无 web 硬编码（desktop 物化布局判 hoisted、farm=0 属常态），但 CLI 全命令一刀切拒绝 `--profile desktop` 把只读体检连坐；desktop-only 机器无 flag 体检还会扫不存在的 web 目录得全 0 报告。
@@ -307,6 +317,16 @@ The full release history of dsh-m, maintained bilingually: **Chinese first, Engl
 
 ## English
 
+### Added in 0.9.32 — npm registry route adaptation: metadata prefetch source switching / mirror self-heal (ADR-0012)
+
+- **Motivation**: on 2026-10-04 a Shanghai Windows desktop machine proved the metadata prefetch is hardcoded to registry.npmjs.org; intermittent timeouts aborted upgrades before pnpm was ever invoked (`fetch failed` / `The operation was aborted due to timeout`, with no operation log under `.plugin-manager/logs`), while npmmirror had already synced the target version. A Seoul (Tencent Cloud) box enjoys fast direct npmjs. Both machines must work with zero configuration.
+- **Read-class routing (L1/L3)**: detection reads (`npmLatest` upgrade probe / `npmPackumentTimes` publish times) prefer the authoritative npmjs (first leg timeout tightened to ≤5s) and degrade to the effective source; fulfillment reads (`npmVersion` exact metadata / `npmPackument` warm) prefer the effective source. `npmPackument` previously ignored its registry parameter — fixed this release (explicit parameter now takes effect, pinned by tests).
+- **L0 transport**: httpx now uses undici's own fetch with a self-built dispatcher (`EnvHttpProxyAgent` handed the resolved proxies explicitly) — metadata prefetch honours `HTTP(S)_PROXY` / `npm_config_*` proxies and is immune to host undici global-dispatcher pollution (dsh-market net.ts #742 family); `fetchLimited` gains a PUT method (sync primitive only); network failures carry a `via` context, and the failure digest renders 「(via <masked proxy>)」 only on proxy paths.
+- **L2 mirror-lag self-heal**: on `NO_MATCHING_VERSION` whose registry field names npmmirror (structured recognition in the classification layer, judged on the full text — upper layers never regex) → on-demand mirror sync (`registry-direct.npmmirror.com/<pkg>/sync`, PUT) → the existing backoff retry (heal `B3_NPMMIRROR_SYNC`); the same ladder applies to `npmVersion` (404 → sync → wait 10s → same-source retry → npmjs fallback); latest cache is invalidated after a sync. `DSHM_MIRROR_SYNC=0` switches it all off.
+- **New module `src/core/npm-route.ts`**: `DSHM_NPM_REGISTRY` override (highest priority, skips probing) > [.npmrc registry, npmjs, npmmirror]; probe-once (2.5s shared budget, single-flight, winner must return a complete body with version); decision persisted at `<cacheDir>/npm-route.json` (delete to re-probe); total failure falls back to npmjs in memory only (60s TTL then re-probe, never persisted). Effective-source switches invalidate both latest and packument caches.
+- **Wire test seam migration**: the existing mock-`globalThis.fetch` seam moved to `_setWireFetchForTests` (versions / npm-integrity / registry-check; assertion and counting semantics unchanged).
+- **Tests**: 41 new cases (L0 proxy parsing/wire forwarding/via/PUT, npm-route ×12, read-class routing, registry classification field, B3 sync, L4 digest, kill-switch ladder/integration, trailing-slash normalization); full suite 1128 tests — 1103 pass / 15 fail on this machine, all 15 being pre-existing Windows symlink-semantics cases (item-for-item identical to the pre-change baseline: zero regression); typecheck clean. Real-machine acceptance (in-window scoped self-published upgrade on the Shanghai box, `dshm outdated` on Seoul) ships with the release.
+
 ### Added in 0.9.31 — doctor desktop profile support (CLI exception + farmChecked semantics revision, ADR-0011)
 
 - **Motivation**: a Windows desktop machine's report confirmed the core engine is profileDir-parameterized with no web hardcoding (materialized desktop layout detects as hoisted with farm=0 — the norm, not a short-circuit), yet the CLI's blanket `--profile desktop` rejection swept up the read-only doctor; desktop-only machines scanning a nonexistent web dir got an all-zero report.

package/README.md

@@ -121,6 +121,7 @@ dshm restart --yes
 
 - **数据获取**：dist-tags 探测最新版本 → jsDelivr 按精确版本直取 → npmmirror → unpkg 三线路兜底；版本未变不重拉正文，TTL 内跳过探测。「最新版本」探测结果为纯内存缓存：**重启 DSH 即失效**（发版后重启即可看到新版本），经 dsh-m 安装/升级/卸载成功后该条目缓存立即作废。失败回落 `<缓存目录>/awesome/` 运行时缓存先展示（先回缓存、后台自愈）——过期数据绝不冒充最新；缓存状态（缓存快照/目录版本/获取线路/更新时间）在**设置页**可见，浏览页不打扰。
 - **开关与锁定**：设置页 `communityCatalog` 开关（默认开，live 生效）、`communityCatalogPin` 可锁定目录版本（精确 semver）；CLI 用 `DSHM_COMMUNITY_CATALOG=0` 退出、`DSHM_COMMUNITY_CATALOG_PIN` 锁版本。
+- **npm 元数据路由（0.9.32，ADR-0012）**：安装/升级前的元数据预取按机器网络自适应选源——probe-once（2.5s 预算）探测 npmjs 与镜像谁先应答，决策持久化于 `<缓存目录>/npm-route.json`（删除即重探）；检测读（升级探测/发布时刻）恒以 npmjs 权威源优先、镜像降级，履约读（精确版本元数据）走生效源、镜像未同步时自动按需同步后重试。环境变量：`DSHM_NPM_REGISTRY` 强制元数据读取源（最高优先，设了跳过探测）；`DSHM_MIRROR_SYNC=0` 关闭镜像滞后自愈。**与 `DSHM_REGISTRY_URL`（收录清单源覆盖）是两回事**。调试回环 registry 时若本机开着系统代理，请配 `NO_PROXY=127.0.0.1,localhost`（代理语义跟随标准 env/npm config，不自动豁免 loopback）。
 - **分类与搜索**：社区分类是开放集（已知 23 个分类带中英双语标签：中文由包内单一事实源维护、英文取上游目录，按界面语言下发）；搜索走相关性加权管线（中英文双匹配），且为**跨区全局**——任一分区的搜索框同时命中社区与精选（浏览保持分区，摘要行报两分区精确命中数、精选命中置顶分组）；社区区排序可切（下载量/Star/收录日期 × 升降，默认下载量降序，无下载量 ≠ 0 下载）。
 - **安装语义**：社区条目与精选条目走同一安装链路（npm 锁精确版本 / GitHub 锁 commit SHA）；市场浏览页只对 npm 条目做更新探测，GitHub 条目不做页面级探测（匿名配额 60 次/小时不可控）。
 - **已装页预算（best-effort）**：已装页对 GitHub 来源插件做更新检查，单次请求 ≤25 个、宿主进程滚动 1 小时 ≤50 个（仅被动检查；主动安装/升级不受限）；超限条目如实标注「检查未完成」而不冒充「全部最新」。独立 CLI 进程不共享宿主内预算，并发场景不承诺 60 次/小时绝不耗尽。

package/lib/cli.js

@@ -147,7 +147,9 @@ profile 目标（0.9.0）：CLI 恒作用于 web profile；--profile web 为显
   --profile desktop 会被拒绝——Desktop profile 的插件管理走官方 Desktop 插件管理页。
 
 环境变量：DSHM_REGISTRY_URL（registry 源覆盖）、DSHM_TIMEOUT_MS、DSHM_CACHE_TTL_MIN、DSHM_CACHE_DIR、
-  DSHM_COMMUNITY_CATALOG=0（退出社区清单）、DSHM_COMMUNITY_CATALOG_PIN（锁定社区目录版本）
+  DSHM_COMMUNITY_CATALOG=0（退出社区清单）、DSHM_COMMUNITY_CATALOG_PIN（锁定社区目录版本）、
+  DSHM_NPM_REGISTRY（npm 元数据读取源覆盖，ADR-0012；与 DSHM_REGISTRY_URL 是两回事）、
+  DSHM_MIRROR_SYNC=0（关闭 npmmirror 按需同步自愈）
 `;
 export async function runCli(argv, deps = {}, io = {}) {
     const out = io.out ?? ((line) => console.log(line));

package/lib/core/dsh-cli.js

@@ -215,25 +215,32 @@ export const PNPM_OUTCOME_CODES = {
 /**
  * 对 pnpm/dsh 原始输出文本做六类归一解释。分类发生在任何文案改写之前；
  * 上层（事务/market）只消费 class + code 常量，永不 regex 原始输出。
+ * registry 识别（ADR-0012 L2）同样只在此处发生：tail-800 截断可能吃掉特征串，
+ * 因此必须在完整文本上判定后随结构化结果上交。
  */
 export function classifyPnpmError(text) {
     const raw = String(text ?? '');
+    const registry = raw.includes('registry-direct.npmmirror.com') || raw.includes('registry.npmmirror.com')
+        ? 'npmmirror'
+        : raw.includes('registry.npmjs.org')
+            ? 'npmjs'
+            : null;
     if (raw.includes(PNPM_OUTCOME_CODES.NO_MATCHING_VERSION)) {
-        return { class: 'retryable-lag', code: PNPM_OUTCOME_CODES.NO_MATCHING_VERSION };
+        return { class: 'retryable-lag', code: PNPM_OUTCOME_CODES.NO_MATCHING_VERSION, registry };
     }
     if (raw.includes(PNPM_OUTCOME_CODES.CONFIG_MISMATCH)) {
-        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.CONFIG_MISMATCH };
+        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.CONFIG_MISMATCH, registry };
     }
     if (raw.includes(PNPM_OUTCOME_CODES.OUTDATED_LOCKFILE)) {
-        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.OUTDATED_LOCKFILE };
+        return { class: 'config-drift', code: PNPM_OUTCOME_CODES.OUTDATED_LOCKFILE, registry };
     }
     if (raw.includes(PNPM_OUTCOME_CODES.UNUSED_PATCH)) {
-        return { class: 'unused-patch', code: PNPM_OUTCOME_CODES.UNUSED_PATCH };
+        return { class: 'unused-patch', code: PNPM_OUTCOME_CODES.UNUSED_PATCH, registry };
     }
     if (isPrepareBlocked(raw))
-        return { class: 'needs-builds' };
+        return { class: 'needs-builds', registry };
     const m = /(ERR_PNPM_[A-Z0-9_]+)/.exec(raw);
-    return { class: 'hard-fail', code: m?.[1] };
+    return { class: 'hard-fail', code: m?.[1], registry };
 }
 /** 统一的命令取消错误形态（runCommand 调用前已取消与运行中取消同款）。 */
 function commandAbortError() {

package/lib/core/httpx.js

@@ -4,6 +4,7 @@
  * 循环检测、signal 传播、返回最终 URL；registry/homepage/icon 诊断不得另起一套。
  */
 import { Buffer } from 'node:buffer';
+import { Agent, EnvHttpProxyAgent, fetch as undiciFetch } from 'undici';
 export class HttpError extends Error {
     status;
     /** 非 2xx 响应的 headers（供上层识别限流等场景）；body-cap/协议类错误无 headers */
@@ -18,6 +19,54 @@ const MAX_DEFAULT = 2 * 1024 * 1024; // 2MB：registry/npm metadata 足够
 const MAX_REDIRECTS = 3;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const USER_AGENT = 'dsh-m (personal marketplace)';
+/**
+ * L0（ADR-0012）：undici 自带 fetch + 自建 dispatcher——全局 fetch 不吃代理 env
+ * 且暴露于宿主 undici 全局 dispatcher 污染（dsh-market net.ts #742 实录）。
+ * 代理解析：标准 env 小写优先，npm_config_* 兜底——EnvHttpProxyAgent 自身只读
+ * http(s)_proxy，npm 命名空间的代理必须显式交接，否则静默直连而报错却声称走过代理。
+ */
+export function resolveProxyConfig() {
+    const pick = (raw) => {
+        const value = raw?.trim();
+        if (value === undefined || value === '')
+            return null;
+        return /^[a-z][a-z\d+.-]*:\/\//iu.test(value) ? value : `http://${value}`;
+    };
+    const https = pick(process.env.https_proxy ?? process.env.HTTPS_PROXY) ?? pick(process.env.npm_config_https_proxy);
+    const http = pick(process.env.http_proxy ?? process.env.HTTP_PROXY) ?? pick(process.env.npm_config_proxy);
+    return { http, https };
+}
+/** 代理 URL 凭据掩码（via 附着与 describeFetchFailure 共用）。 */
+export function maskProxy(url) {
+    return url.replace(/\/\/[^@]*@/u, '//***@');
+}
+let directAgent = null;
+let proxyAgent = null;
+/** 仅测试：env 变更后重建单例（单例只为连接复用，不承载语义）。 */
+export function resetProxyAgentsForTests() {
+    directAgent = null;
+    proxyAgent = null;
+}
+function dispatcherFor() {
+    const { http, https } = resolveProxyConfig();
+    if (http === null && https === null) {
+        directAgent ??= new Agent();
+        return directAgent;
+    }
+    proxyAgent ??= new EnvHttpProxyAgent({ httpProxy: http ?? undefined, httpsProxy: https ?? undefined });
+    return proxyAgent;
+}
+/** wire 层出网引用：默认 undici 包自带 fetch（带 dispatcher）。 */
+let wireFetch = (url, init) => undiciFetch(url, init);
+/**
+ * 仅测试：替换 wire 层 fetch（本仓库既有 mock globalThis.fetch 测试缝隙的迁移口，
+ * 首参收字符串 url；传 null 恢复 undici 默认）。生产路径永不调用。
+ */
+export function _setWireFetchForTests(fn) {
+    wireFetch = fn
+        ? (url, init) => fn(url.toString(), init)
+        : (url, init) => undiciFetch(url, init);
+}
 export function assertSafeUrl(raw) {
     let url;
     try {
@@ -72,12 +121,26 @@ export async function fetchLimited(url, opts = {}) {
     const seen = new Set([current.toString()]);
     for (let hop = 0;; hop++) {
         opts.onRequest?.(current.toString());
-        const res = await fetch(current, {
-            redirect: 'manual',
-            signal,
-            method: opts.method ?? 'GET',
-            headers: { 'user-agent': USER_AGENT, ...opts.headers },
-        });
+        let res;
+        try {
+            // 实证（undici 7.30）：redirect:'manual' 返回真实 3xx + Location（type=basic），
+            // 现有手动跳循环原样保留；每跳 assertSafeUrl / 上限 / 循环检测不动。
+            res = await wireFetch(current, {
+                redirect: 'manual',
+                signal,
+                method: opts.method ?? 'GET',
+                headers: { 'user-agent': USER_AGENT, ...opts.headers },
+                dispatcher: dispatcherFor(),
+            });
+        }
+        catch (err) {
+            if (!(err instanceof HttpError)) {
+                const { http, https } = resolveProxyConfig();
+                const proxyUrl = https ?? http;
+                err.via = proxyUrl === null ? 'direct' : maskProxy(proxyUrl);
+            }
+            throw err;
+        }
         if (REDIRECT_STATUSES.has(res.status)) {
             await res.body?.cancel().catch(() => undefined);
             if (hop >= MAX_REDIRECTS)
@@ -172,13 +235,18 @@ export function describeFetchFailure({ label, err, attempts, elapsedMs }) {
     else {
         reason = String(err);
     }
+    // L4（ADR-0012）：仅代理路径渲染「（经 …）」；direct/缺失不渲染（无代理机器零噪音）。
+    const via = err instanceof Error && typeof err.via === 'string'
+        ? err.via
+        : null;
+    const viaText = via && via !== 'direct' ? `（经 ${maskProxy(via)}）` : '';
     const cost = [];
     if (typeof attempts === 'number' && attempts > 0)
         cost.push(`${attempts} 次尝试`);
     if (typeof elapsedMs === 'number' && elapsedMs > 0)
         cost.push(`耗时 ${(elapsedMs / 1000).toFixed(1)}s`);
     const costText = cost.length > 0 ? `（${cost.join('，')}）` : '';
-    return `${label} 失败：${reason}${costText}；可稍后重试或检查网络后重试`;
+    return `${label} 失败：${reason}${viaText}${costText}；可稍后重试或检查网络后重试`;
 }
 /** 字节下载（社区目录正文用）：非 2xx 抛 HttpError；bytes = 完整响应体。 */
 export async function fetchBytesLimited(url, opts = {}) {

package/lib/core/latest-cache.js

@@ -14,6 +14,7 @@
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { WEB_PROFILE, cacheRoot } from './env.js';
+import { onRouteSwitch } from './npm-route.js';
 const latestCache = new Map();
 const LATEST_CACHE_MAX = 5000;
 /** 缓存键第三段（itemId）：浏览页键 / 已装页 matched 键 / npm-only 键共用同一尾段，定向失效按它匹配。 */
@@ -79,3 +80,8 @@ export function resetLatestCacheForTest() {
     latestCache.clear();
     swept.clear();
 }
+/** L1（ADR-0012）：npm 生效源切换 → 整体作废 latest 探测缓存（镜像的答案不是官方源的答案）。 */
+export function clearAllLatestCache() {
+    latestCache.clear();
+}
+onRouteSwitch(() => clearAllLatestCache());

package/lib/core/npm-route.js

@@ -0,0 +1,201 @@
+/**
+ * L1/L2（ADR-0012）：npm registry 路由自适应。
+ * 候选 = `DSHM_NPM_REGISTRY` env（最高优先，设了跳过探测）> [.npmrc registry, npmjs, npmmirror] 去重；
+ * probe-once（Promise.any 探 `semver/latest`，2.5s 共享预算，胜者须合法 JSON 带 version）+ single-flight；
+ * 决策持久化 `<cacheDir()>/npm-route.json`；**全候选失败仅内存回退 npmjs（TTL 60s 过期重探，不落盘）**——
+ * 对官方 region-probe「持久化回退值」立场的显式偏离：GUI 长驻进程里坏决策不可见、恢复口不可发现。
+ * sync 原语：npmmirror 按需同步（know-how 020 §2.2/§3.1），`DSHM_MIRROR_SYNC=0` 全关。
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { cacheDir } from './env.js';
+import { fetchJsonLimited, fetchLimited } from './httpx.js';
+export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
+export const NPM_MIRROR = 'https://registry.npmmirror.com';
+const PROBE_BUDGET_MS = 2_500;
+const FALLBACK_TTL_MS = 60_000;
+const DECISION_FILE = 'npm-route.json';
+/** 用户级 .npmrc 顶层 `registry=` 键（ini-lite；scope 键 v1 忽略；缺失/损坏 = null）。 */
+export function readNpmrcRegistry(path = join(homedir(), '.npmrc')) {
+    try {
+        const text = readFileSync(path, 'utf8');
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line === '' || line.startsWith('#') || line.startsWith(';'))
+                continue;
+            const m = /^registry\s*=\s*(.+)$/.exec(line);
+            if (m) {
+                const base = m[1].trim().replace(/\/+$/, '');
+                return base === '' ? null : base;
+            }
+        }
+    }
+    catch {
+        // 文件缺失/不可读 = 无 .npmrc 源
+    }
+    return null;
+}
+/** 候选源（env 直采时恒单元素；否则 .npmrc 优先、官方源与镜像兜底，去重保序）。 */
+export function candidates() {
+    const override = process.env.DSHM_NPM_REGISTRY?.trim();
+    if (override)
+        return [override.replace(/\/+$/, '')];
+    const out = [];
+    for (const c of [readNpmrcRegistry(), DEFAULT_NPM_REGISTRY, NPM_MIRROR]) {
+        if (c && !out.includes(c))
+            out.push(c);
+    }
+    return out;
+}
+const listeners = [];
+export function onRouteSwitch(fn) {
+    listeners.push(fn);
+}
+/** 生效值变化才广播（含首次决议；listener 异常不阻断路由）。 */
+let effective = null;
+function setEffective(base) {
+    if (effective === base)
+        return;
+    effective = base;
+    for (const fn of listeners) {
+        try {
+            fn(base);
+        }
+        catch {
+            // listener 自身问题不阻断
+        }
+    }
+}
+function decisionPath() {
+    return join(cacheDir(), DECISION_FILE);
+}
+function readDecisionFile() {
+    try {
+        const doc = JSON.parse(readFileSync(decisionPath(), 'utf8'));
+        if (typeof doc.base === 'string' && /^https?:\/\//.test(doc.base))
+            return doc.base.replace(/\/+$/, '');
+    }
+    catch {
+        // 缺失/损坏 = 无决策（下次重探）
+    }
+    return null;
+}
+async function writeDecisionFile(base, cands) {
+    try {
+        const doc = { base, decidedAt: new Date().toISOString(), candidates: cands };
+        await writeFileAtomic(decisionPath(), JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch {
+        // 落盘失败不影响本次生效（内存已有）
+    }
+}
+async function defaultProbeFetch(base, signal) {
+    const doc = await fetchJsonLimited(`${base}/semver/latest`, { timeoutMs: PROBE_BUDGET_MS, signal });
+    return typeof doc?.version === 'string' ? doc.version : '';
+}
+let memBase = null;
+let memIsFallback = false;
+let fallbackAt = 0;
+let inflight = null;
+export function resetNpmRouteForTests() {
+    memBase = null;
+    memIsFallback = false;
+    fallbackAt = 0;
+    inflight = null;
+    effective = null;
+}
+/** 共享预算 + 读完整个响应才算赢（captive portal 只回 header 就挂的场景选不出赢家）。 */
+async function probeOnce(cands, probeFetch) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(new Error('路由探测超时')), PROBE_BUDGET_MS);
+    try {
+        const ask = async (base) => {
+            const version = await probeFetch(base, ac.signal);
+            if (typeof version !== 'string' || version === '')
+                throw new Error(`${base} 探测无有效 version`);
+            return base;
+        };
+        return await Promise.any(cands.map(ask));
+    }
+    finally {
+        clearTimeout(timer);
+        ac.abort(); // 停止败者：其答案已不能改变任何决定
+    }
+}
+export async function decideNpmRoute(deps) {
+    if (inflight)
+        return inflight;
+    inflight = (async () => {
+        // 1) env 最高优先：直采、不探测、不落盘（去尾斜杠，与镜像/官方源等值判断对齐——评审 R1-3）
+        const override = process.env.DSHM_NPM_REGISTRY?.trim();
+        if (override) {
+            const normalized = override.replace(/\/+$/, '');
+            setEffective(normalized);
+            return normalized;
+        }
+        // 2) 成功探测的内存决策稳定复用（决策文件才是持久真相）
+        if (memBase !== null && !memIsFallback)
+            return memBase;
+        // 3) 回退态：TTL 内复用，过期重探（R2-3）
+        if (memBase !== null && memIsFallback) {
+            if (Date.now() - fallbackAt < (deps?.fallbackTtlMs ?? FALLBACK_TTL_MS))
+                return memBase;
+            memBase = null;
+            memIsFallback = false;
+        }
+        // 4) 决策文件（机器级事实，跨重启稳定）
+        const fromFile = readDecisionFile();
+        if (fromFile) {
+            memBase = fromFile;
+            memIsFallback = false;
+            setEffective(fromFile);
+            return fromFile;
+        }
+        // 5) probe-once；全败 → 内存回退 DEFAULT（不落盘，R1-8 决策 a）
+        const cands = candidates();
+        try {
+            const winner = await probeOnce(cands, deps?.probeFetch ?? defaultProbeFetch);
+            memBase = winner;
+            memIsFallback = false;
+            setEffective(winner);
+            await writeDecisionFile(winner, cands);
+            return winner;
+        }
+        catch {
+            memBase = DEFAULT_NPM_REGISTRY;
+            memIsFallback = true;
+            fallbackAt = Date.now();
+            setEffective(DEFAULT_NPM_REGISTRY);
+            return DEFAULT_NPM_REGISTRY;
+        }
+    })();
+    try {
+        return await inflight;
+    }
+    finally {
+        inflight = null;
+    }
+}
+/** 当前生效 npm registry（decideNpmRoute 语义名）。 */
+export async function activeNpmRegistry(deps) {
+    return decideNpmRoute(deps);
+}
+/**
+ * npmmirror 按需同步（know-how 020 §2.2/§3.1）；2xx=受理。任何失败返回 false、不抛；
+ * `DSHM_MIRROR_SYNC=0` 一键关闭（不发请求）。
+ */
+export async function syncNpmmirrorPackage(pkg, deps) {
+    if (process.env.DSHM_MIRROR_SYNC === '0')
+        return false;
+    const fetcher = deps?.fetcher ?? fetchLimited;
+    const url = `https://registry-direct.npmmirror.com/${encodeURIComponent(pkg)}/sync?sync_upstream=true`;
+    try {
+        const res = await fetcher(url, { method: 'PUT', timeoutMs: deps?.timeoutMs ?? 8_000 });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/core/profile-transaction.js

@@ -38,12 +38,14 @@ import { webProfileDir } from './env.js';
 import { isSafePkgName, resolvePluginDir } from './installed.js';
 import { setLivePluginDisabled } from './live-plugin.js';
 import { npmPackument } from './versions.js';
+import { syncNpmmirrorPackage } from './npm-route.js';
+import { clearAllLatestCache } from './latest-cache.js';
 import { assertNpmIntegrity, atomicWriteFile, readPnpmLockIntegrity, readPnpmLockOverrides, restoreSnapshots, snapshotFiles, verifySnapshots, } from './npm-integrity.js';
 import { isSafePluginTarget, makeDshRunner, removePatchedDependencyEntries, PNPM_OUTCOME_CODES, } from './dsh-cli.js';
 export const TX_HEAL_CODES = [
     'RANGE_ANCHOR_ACCEPTED', 'B1_MANIFEST_KEYS_RESTORED', 'B1_FROZEN_REVERIFY_FAILED',
     'B2_OVERRIDES_ALIGNED', 'B2_FROZEN_REVERIFY_OK', 'B2_LOCKFILE_REBUILT',
-    'B3_LAG_RETRY', 'B3_PACKUMENT_WARMED', 'BUILDS_ALLOWED',
+    'B3_LAG_RETRY', 'B3_NPMMIRROR_SYNC', 'B3_PACKUMENT_WARMED', 'BUILDS_ALLOWED',
     'ROLLBACK_BYTES_RESTORED', 'ROLLBACK_CONVERGED_FROZEN', 'ROLLBACK_FALLBACK_REMOVED',
     'ROLLBACK_VERIFY_FAILED', 'LIVE_DISABLED', 'LIVE_REENABLED', 'LIVE_REENABLE_FAILED',
     'PATCH_ENTRIES_STRIPPED', 'PATCH_MAPPING_RESTORED',
@@ -461,6 +463,8 @@ function resolveDeps(deps) {
     return {
         profileDir,
         warmPackument: deps?.warmPackument,
+        syncNpmmirror: deps?.syncNpmmirror ?? syncNpmmirrorPackage,
+        clearLatestCache: deps?.clearLatestCache ?? clearAllLatestCache,
         setLiveDisabled: deps?.setLiveDisabled ?? setLivePluginDisabled,
         stripPatchedEntries: deps?.stripPatchedEntries ?? removePatchedDependencyEntries,
         retryDelaysMs: deps?.retryDelaysMs ?? [5_000, 15_000],
@@ -479,6 +483,15 @@ async function addWithLagRetry(req, spec, d, heal) {
         const out = await d.runner.add(spec, req.signal);
         if (out.class !== 'retryable-lag')
             return out;
+        // L2②（ADR-0012）：NO_MATCHING_VERSION 且 registry 字段指名 npmmirror → 按需同步镜像后重试；
+        // sync 失败静默（false = 回到既有退避语义）；kill switch（DSHM_MIRROR_SYNC=0）在缺省实现内。
+        if (out.code === PNPM_OUTCOME_CODES.NO_MATCHING_VERSION && out.registry === 'npmmirror') {
+            const synced = await d.syncNpmmirror(req.pkg);
+            if (synced) {
+                d.clearLatestCache();
+                heal.push({ code: 'B3_NPMMIRROR_SYNC', note: 'NO_MATCHING_VERSION 来自 npmmirror，已按需同步镜像后重试（+npmmirror sync）' });
+            }
+        }
         if (attempt >= d.retryDelaysMs.length)
             return out;
         const delay = d.retryDelaysMs[attempt] ?? 0;

package/lib/core/release-age.js

@@ -27,6 +27,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
 import { fetchJsonLimited } from './httpx.js';
+import { DEFAULT_NPM_REGISTRY, activeNpmRegistry, onRouteSwitch } from './npm-route.js';
 /** pnpm 11.7 实机测得的策略窗口：24h（operation-l5fXEd 的 cutoff = 检查时刻 − 1440min）。 */
 export const DEFAULT_MINIMUM_RELEASE_AGE_MIN = 1440;
 function scalarNumber(value) {
@@ -147,20 +148,42 @@ export function describeReleaseAgeFailure(input) {
     lines.push(`预计 ${fmtLocal(maxDeadline)} 后可重试；等待期内也可由操作员把 pnpm-workspace.yaml 中对应的独立精确排除条目改为包名级或复合条目以解除拦截`);
     return { message: lines.join('\n'), violations, targetViolating: targetViol !== undefined };
 }
-/** registry packument 的 time 映射（与 npmPackument 同源；失败返回 null，不抛）。 */
-export async function npmPackumentTimes(pkg, timeoutMs = 20_000, signal) {
+async function fetchPackumentTimes(base, pkg, timeoutMs, signal, fetcher) {
+    const data = await fetcher(`${base}/${encodeURIComponent(pkg)}`, {
+        timeoutMs,
+        signal,
+        maxBytes: 8 * 1024 * 1024,
+    });
+    if (!data || typeof data !== 'object' || data.time === null || typeof data.time !== 'object')
+        return null;
+    const out = {};
+    for (const [k, v] of Object.entries(data.time)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * registry packument 的 time 映射（与 npmPackument 同源；失败返回 null，不抛）。
+ * L3 权威链（ADR-0012）：发布时刻是完整性敏感读——npmjs 权威源优先（首腿超时收紧
+ * `Math.min(timeoutMs, 5_000)`），失败降级生效源；两腿皆败 → null（fail-open 口径不变）。
+ */
+export async function npmPackumentTimes(pkg, timeoutMs = 20_000, signal, deps) {
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         return null;
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const firstLegMs = Math.min(timeoutMs, 5_000);
     try {
-        const data = await fetchJsonLimited(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`, { timeoutMs, signal, maxBytes: 8 * 1024 * 1024 });
-        if (!data || typeof data !== 'object' || data.time === null || typeof data.time !== 'object')
-            return null;
-        const out = {};
-        for (const [k, v] of Object.entries(data.time)) {
-            if (typeof v === 'string')
-                out[k] = v;
-        }
-        return out;
+        return await fetchPackumentTimes(DEFAULT_NPM_REGISTRY, pkg, firstLegMs, signal, fetcher);
+    }
+    catch {
+        // 权威源不可达 → 生效源降级
+    }
+    const alt = await activeNpmRegistry();
+    if (alt === DEFAULT_NPM_REGISTRY)
+        return null;
+    try {
+        return await fetchPackumentTimes(alt, pkg, timeoutMs, signal, fetcher);
     }
     catch {
         return null;
@@ -179,15 +202,20 @@ export async function readWorkspacePolicy(profileDir) {
 }
 const packumentCache = new Map();
 const PACKUMENT_CACHE_TTL_MS = 5 * 60_000;
+/** L1（ADR-0012）：npm 生效源切换 → 作废 packument 缓存（镜像的答案不是官方源的答案）。 */
+export function clearPackumentCache() {
+    packumentCache.clear();
+}
+onRouteSwitch(() => clearPackumentCache());
 /**
  * 带进程内缓存的 packument time 探测（TTL 5min）：预检与登记（exclude-governance）
  * 共用——同一操作里预检刚拉过的 packument 不二次拉取（8MiB 级全量）。
  */
-export async function cachedPackumentTimes(pkg, timeoutMs = 12_000, signal) {
+export async function cachedPackumentTimes(pkg, timeoutMs = 12_000, signal, deps) {
     const hit = packumentCache.get(pkg);
     if (hit && Date.now() - hit.at < PACKUMENT_CACHE_TTL_MS)
         return hit.times;
-    const times = await npmPackumentTimes(pkg, timeoutMs, signal);
+    const times = await npmPackumentTimes(pkg, timeoutMs, signal, deps);
     packumentCache.set(pkg, { at: Date.now(), times });
     return times;
 }

package/lib/core/versions.js

@@ -6,6 +6,7 @@
  */
 import { gt } from 'semver';
 import { fetchJsonLimited, HttpError } from './httpx.js';
+import { DEFAULT_NPM_REGISTRY, NPM_MIRROR, activeNpmRegistry, syncNpmmirrorPackage } from './npm-route.js';
 /** GitHub 匿名限额（60 次/小时/IP）用尽时返回可读提示（含重置等待分钟数），否则 null。 */
 function githubRateLimitMessage(err) {
     if (err instanceof HttpError && err.status === 403 && err.headers?.get('x-ratelimit-remaining') === '0') {
@@ -29,54 +30,123 @@ const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(
 export function isExactVersion(version) {
     return EXACT_VERSION_RE.test(version);
 }
-/** 读取该精确版本的 dist metadata（不使用 /latest endpoint）；integrity 缺失由调用方拒绝安装。 */
-export async function npmVersion(pkg, version, timeoutMs = 20_000, signal, registry) {
+function sleepAbortable(ms, signal) {
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(t);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const t = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+/**
+ * 精确版本元数据（兼容预检/integrity 锚定）。L2① 履约阶梯（ADR-0012）：
+ * 显式 registry 参数 > 生效源 → 失败且生效源为镜像 → sync → 有界等待 10s → 同源重试一次
+ * → 仍败 → npmjs 兜底（sync+重试为尽力而为，npmjs 兜底是主安全网）；
+ * 主源即 npmjs 时失败直接抛（权威源无镜像滞后可言）。
+ */
+export async function npmVersion(pkg, version, timeoutMs = 20_000, signal, registry, deps) {
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
     if (!isExactVersion(version))
         throw new Error(`不是精确版本（拒绝 range/tag/前缀）: ${version}`);
-    const data = await fetchJsonLimited(`${registryBase(registry)}/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
-    const resolved = typeof data.version === 'string' ? data.version : '';
-    if (!resolved)
-        throw new Error(`npm 未返回版本: ${pkg}@${version}`);
-    const peers = {};
-    if (data.peerDependencies !== null && typeof data.peerDependencies === 'object') {
-        for (const [name, range] of Object.entries(data.peerDependencies)) {
-            if (typeof range === 'string')
-                peers[name] = range;
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const sync = deps?.syncNpmmirror ?? syncNpmmirrorPackage;
+    const wait = deps?.wait ?? sleepAbortable;
+    const leg = async (base) => {
+        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/${version}`, { timeoutMs, signal });
+        const resolved = typeof data.version === 'string' ? data.version : '';
+        if (!resolved)
+            throw new Error(`npm 未返回版本: ${pkg}@${version}`);
+        const peers = {};
+        if (data.peerDependencies !== null && typeof data.peerDependencies === 'object') {
+            for (const [name, range] of Object.entries(data.peerDependencies)) {
+                if (typeof range === 'string')
+                    peers[name] = range;
+            }
         }
-    }
-    return {
-        version: resolved,
-        integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
-        tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
-        peers,
+        return {
+            version: resolved,
+            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
+            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+            peers,
+        };
     };
+    const primary = registry?.trim() ? registry.trim() : await activeNpmRegistry();
+    try {
+        return await leg(primary);
+    }
+    catch (firstErr) {
+        // L2①（ADR-0012）：仅 sync 真正受理（评审 R1-2：kill switch / 同步失败返回 false 时
+        // 不付 10s 等待成本、不发必 404 的同源重试——「风险与回退」承诺的行为回到现状）才重试镜像。
+        if (primary === NPM_MIRROR && (await sync(pkg))) {
+            await wait(10_000, signal);
+            try {
+                return await leg(primary);
+            }
+            catch {
+                // 同源重试仍败 → npmjs 兜底
+            }
+        }
+        if (primary !== DEFAULT_NPM_REGISTRY)
+            return leg(DEFAULT_NPM_REGISTRY);
+        throw firstErr;
+    }
 }
 /**
  * 拉取完整 packument（NO_MATCHING_VERSION 退避重试前的预热/校验原语）。
  * 返回该包已知的全部版本号；解析不出 versions 时返回空列表（不抛）。
+ * L1（ADR-0012/R1-6）：registry 参数曾被忽略——现「显式参数 > 生效源」。
  */
-export async function npmPackument(pkg, timeoutMs = 20_000, signal, registry) {
+export async function npmPackument(pkg, timeoutMs = 20_000, signal, registry, deps) {
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
-    const data = await fetchJsonLimited(`https://registry.npmjs.org/${encodeURIComponent(pkg)}`, { timeoutMs, signal, maxBytes: 8 * 1024 * 1024 });
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const base = registry?.trim() ? registry.trim() : await activeNpmRegistry();
+    const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}`, {
+        timeoutMs,
+        signal,
+        maxBytes: 8 * 1024 * 1024,
+    });
     const versions = data?.versions !== null && typeof data?.versions === 'object' ? Object.keys(data.versions) : [];
     return { versions };
 }
-export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry) {
+/**
+ * 升级探测（检测读）。L3 权威链（ADR-0012）：新鲜度敏感——npmjs 权威源优先
+ * （首腿超时收紧 `Math.min(timeoutMs, 5_000)`），失败降级生效源（≠npmjs 时）；
+ * 不设 sync 腿（两腿全败属网络型失败，sync 只救镜像滞后）。显式 registry 参数优先。
+ */
+export async function npmLatest(pkg, timeoutMs = 20_000, signal, registry, deps) {
     // 允许 scoped 包名：@scope/name（isSafePkgName 同款字符集）
     if (!/^@?[A-Za-z0-9-._~]+(\/[A-Za-z0-9-._~]+)?$/.test(pkg))
         throw new Error(`无效 npm 包名: ${pkg}`);
-    const data = await fetchJsonLimited(`${registryBase(registry)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs, signal });
-    const version = typeof data.version === 'string' ? data.version : '';
-    if (!version)
-        throw new Error(`npm 未返回版本: ${pkg}`);
-    return {
-        version,
-        integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
-        tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+    const fetcher = deps?.fetchJsonLimited ?? fetchJsonLimited;
+    const leg = async (base, ms) => {
+        const data = await fetcher(`${registryBase(base)}/${encodeURIComponent(pkg)}/latest`, { timeoutMs: ms, signal });
+        const version = typeof data.version === 'string' ? data.version : '';
+        if (!version)
+            throw new Error(`npm 未返回版本: ${pkg}`);
+        return {
+            version,
+            integrity: typeof data.dist?.integrity === 'string' ? data.dist.integrity : undefined,
+            tarball: typeof data.dist?.tarball === 'string' ? data.dist.tarball : undefined,
+        };
     };
+    const explicit = registry?.trim();
+    if (explicit)
+        return leg(explicit, timeoutMs);
+    const firstLegMs = Math.min(timeoutMs, 5_000);
+    try {
+        return await leg(DEFAULT_NPM_REGISTRY, firstLegMs);
+    }
+    catch (firstErr) {
+        const alt = await activeNpmRegistry();
+        if (alt === DEFAULT_NPM_REGISTRY)
+            throw firstErr;
+        return leg(alt, timeoutMs);
+    }
 }
 export async function githubTagSha(repo, tag, timeoutMs = 20_000, signal, budget, apiBase = 'https://api.github.com') {
     // commits/{ref} 会自动解引用 annotated tag，返回的才是可用于 #sha 锁定的 commit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-m",
-  "version": "0.9.31",
+  "version": "0.9.32",
   "description": "可自定义收录清单的 DSH 插件市场：收录、安装、卸载、升级一站完成，附 agent 工具与 dshm CLI。",
   "license": "MIT",
   "type": "module",
@@ -84,6 +84,7 @@
   "dependencies": {
     "@deepseek-ai/dsh-atomic-write": "0.1.7-rc.2",
     "semver": "7.8.5",
+    "undici": "7.30.0",
     "yaml": "2.9.1"
   }
 }