dsh-m 0.9.30 → 0.9.32

package/CHANGELOG.md

@@ -8,12 +8,31 @@ 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 报告。
+- **CLI 例外（仅 doctor）**：`dshm doctor --profile desktop` 允许并路由 `desktopProfileDir()`，输出首行加 `[web|desktop]` 标注；HELP 同步；**其余命令对 `--profile desktop` 的拒绝语义逐字不变**（回归钉子测试钉住），desktop 变更管理仍走官方 Desktop 插件页。
+- **空目录提示**：目标 profile 目录不存在时提示「desktop-only 机器请加 --profile desktop」——判据为目录不存在（存在但为空的合法 profile 不误伤）。
+- **宿主 method 零改动**：doctor case 本就 active-profile 无关，desktop 宿主免改生效（新增 desktop-kind 注入钉子测试）；MCP 工具 `dshm_doctor` 维持 ADR-0010 决定 3 缓上；Windows Electron 宿主 runtimeVersion 可能仍降级（物化布局 farm=0，stale 无判定对象，实际影响为零，如实记录）。
+- **farmChecked 语义修订**：「0=遍历空转」判定仅适用于存在符号链农场的形态；物化布局 0 为常态（ADR-0011）。
+- **验证**：新增 8 例（desktop 路由/标注、他命令拒绝、非法值、空提示、正常不提示、显式 desktop 不出矛盾文案、显式 web 路由、method 钉子）+ 改写 1 例旧拒绝样本（净增 8，全量 1079→1087）；全量 1087 pass / 0 fail / 0 skipped；typecheck 零错误。Windows 外机验收清单见实施计划（本机无法执行 Windows E2E）。
+
 ### 0.9.30 变更：修复 bin 符号链接静默 no-op（F2）+ 版本解析 realpath 第三源（F1）
 
 - **根因同源**：pnpm 生态里两类关键入口都是**符号链接**——`node_modules/.bin/dshm`（指向 lib/cli.js）与全局 shim `PNPM_HOME/dsh`（指向真实 bin.js）——而两处代码都在 realpath 之前做了路径身份判定。
 - **F2（自 v0.2.0 bin 入口引入以来潜在，本机 0.9.28 装机形态首次踩中并实证；🔴 bin 入口全命令静默 exit 0）**：cli.ts `invokedDirectly` 比较 `argv[1]`（链接路径）与 `import.meta.url`（node realpath 后的真实路径）永假，`dshm <任何命令>` 无输出直接退出。修复：比较前对 `argv[1]` 同样 realpath。新增 `tests/cli-bin-symlink.test.mjs`（经符号链接调用 --help 与 doctor --json 的复活验证，EPERM 环境照仓内先例 skip）。
 - **F1（0.9.29 装机验收实证）**：dsh-version.ts `readLauncherPackageVersion` 从 shim 位置直接向上三级找 package.json，落在 pnpm home 目录树上空走——宿主内纯 FS 版本解析在本机拓扑（`node PNPM_HOME/dsh web`）不可得，doctor 的 stale 判定降级、ping chip 被迫吃 spawn 回退。修复：判定 entry 形态后先 realpath 再上溯（本机实测解析得 0.2.0-rc.2）。新增 dsh-version.test.mjs shim 形态用例。
-- **验证**：专项 9/9（含两新用例）；全量 1079 pass / 0 fail / 0 skipped；typecheck 零错误。装机后预期：`dshm doctor`（bin 入口）可用；宿主 method 通路 runtimeVersion=0.2.0-rc.2、stale 判定复活（装机时农场 dsh 链接 0.1.7-rc.2 为现成 stale 形态，heal 后归零）。
+- **验证**：专项 9/9（含两新用例）；全量 1079 pass / 0 fail / 0 skipped；typecheck 零错误。装机后预期：`dshm doctor`（bin 入口）可用；宿主 method 通路 runtimeVersion=0.2.0-rc.2、stale 判定复活（装机时农场 dsh 链接 0.1.7-rc.2 为现成 stale 形态，heal 后归零）。**装机实测（2026-10-04）**：预期逐项兑现——`.bin/dshm doctor` 经符号链接复活出报告；宿主 method `runtimeVersion=0.2.0-rc.2 / stale=1（dsh→0.1.7-rc.2 现场点名）`；同日按 know-how 014 heal 该链接并清理 20 项残留后，双通路终验 `farm 236 / dangling 0 / stale 0 / residue 0 / errors 0`。
 
 ### 0.9.29 变更：profile 体检 Doctor——`dshm doctor` 上线（只读：农场测活 / 残留物清点 / 账实一致）
 
@@ -298,6 +317,25 @@ 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.
+- **CLI exception (doctor only)**: `dshm doctor --profile desktop` is allowed and routed to `desktopProfileDir()`, with a `[web|desktop]` tag on the first output line; HELP synced; **every other command's rejection of `--profile desktop` stays byte-identical** (pinned by regression tests) — desktop mutation management remains with the official Desktop plugin page.
+- **Missing-dir hint**: when the target profile dir does not exist, suggest `--profile desktop` (an existing-but-empty legit profile is not flagged).
+- **Host method untouched**: the doctor case was already active-profile agnostic — desktop hosts get it for free (new desktop-kind injection pin test); the `dshm_doctor` MCP tool stays deferred per ADR-0010 decision 3; on Windows Electron hosts runtimeVersion may still degrade (materialized layout means farm=0, so stale has nothing to judge — zero practical impact, recorded honestly).
+- **farmCount semantics revision**: "0 = walk short-circuited" applies only to shapes with a symlink farm; 0 is the norm for materialized layouts (ADR-0011).
+- **Verification**: 8 new cases (desktop routing/tag, other-command rejection, invalid value, missing-dir hint, no-hint-on-normal, explicit-desktop no contradictory hint, explicit-web routing, method pin) + 1 rewritten legacy rejection sample (net +8, 1079→1087); full suite 1087 pass / 0 fail / 0 skipped; typecheck clean. The Windows on-machine acceptance checklist ships with the implementation plan (no Windows E2E possible on this machine).
+
 ### Fixed in 0.9.30 — bin symlink silent no-op (F2) + realpath third source for version resolution (F1)
 
 - **Shared root cause**: two critical pnpm-ecosystem entry points are **symlinks** — `node_modules/.bin/dshm` (→ lib/cli.js) and the global shim `PNPM_HOME/dsh` (→ the real bin.js) — while both code sites made path-identity decisions before realpath.

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/docs/DESIGN.md

@@ -175,7 +175,7 @@ npm 安装 / GitHub 安装 / 升级 / 自升级 / 卸载是**同一个事务模
 - 工具前缀 `dshm_`，共 7 个：`dshm_search` / `dshm_list` / `dshm_install` / `dshm_uninstall` / `dshm_outdated` / `dshm_upgrade` / `dshm_restart`。Agent tools 运行于 Host 进程，与 Web GUI **共用 `host` namespace 缓存与 active config**；`dshm_search` 走服务端过滤（metadata-only，`withLatest=false`、limit ≤80），返回不含本地路径的短 summary。
 - 0.5.0：`dshm_search`/`dshm_install` 消费**合并市场**（§2.5）；category 参数接受精选 5 分类 + 任意社区分类 slug；summary 增加社区清单状态（条数/来源/是否 stale）；CLI 默认合并社区清单，`DSHM_COMMUNITY_CATALOG=0` 退出，缓存用 `cli/awesome/` 子目录。
 - CLI bin `dshm`：同名同义命令集（`dshm list|search|install|uninstall|outdated|upgrade|restart`），固定 `cli` namespace。`registry`/`search`/`outdated` 在清单不可用时打印配置/实际生效地址并 **exit 1**；`list` 仍列出已装并标记不可用；本地终端可显示完整路径。
-- 体检（Doctor，0.9.29）：`/dshm` method `doctor` + CLI `dshm doctor [--json]`（**不新增第 9 个 agent 工具**——工具描述是宿主 agent 常驻上下文，行为面代价大于收益）。纯 FS 只读（无进程/无网络/无写入，清单不可用照常工作），三项检查（农场测活/残留物清点/账实一致）+ 三级严重度 + unknown≠broken + 双市场信息级；runtimeVersion 仅 `readLauncherPackageVersion` 纯 FS 通路（CLI 下降级 unknown，禁 spawn 回退）。决策全记载见 [ADR-0010](./adr/0010-doctor-read-only-diagnostics.md)。
+- 体检（Doctor，0.9.29；desktop 支持与 CLI 例外开口 0.9.31 / [ADR-0011](./adr/0011-doctor-desktop-profile.md)）：`/dshm` method `doctor` + CLI `dshm doctor [--json] [--profile web|desktop]`（**不新增第 9 个 agent 工具**——工具描述是宿主 agent 常驻上下文，行为面代价大于收益）。纯 FS 只读（无进程/无网络/无写入，清单不可用照常工作），三项检查（农场测活/残留物清点/账实一致）+ 三级严重度 + unknown≠broken + 双市场信息级；runtimeVersion 仅 `readLauncherPackageVersion` 纯 FS 通路（CLI 下降级 unknown，禁 spawn 回退）。决策全记载见 [ADR-0010](./adr/0010-doctor-read-only-diagnostics.md)。
 - 本地 API：`POST /dshm` 单路由 method 分发；除 `ping` 外全部要求 JSON Content-Type + `trustedRestartRequest` host 等价同源防护；typed 错误映射 400/403/404/405/413/415/422/500；`registry-config-apply` 校验失败 422；清单不可用的 `registry`/`market` 仍返回 200 + 结构化状态。
 - 实现顺序：**GUI 先行，CLI 收尾**（核心逻辑同一层，CLI 是薄封装）。
 

package/lib/cli.js

@@ -9,13 +9,13 @@ import { installFromRegistry, listInstalledWithMeta, listMarket, uninstallPlugin
 import { togglePlugin as coreTogglePlugin } from './core/toggle.js';
 import { runDoctor } from './core/doctor.js';
 import { readLauncherPackageVersion } from './core/dsh-version.js';
-import { webProfileDir } from './core/env.js';
+import { webProfileDir, desktopProfileDir } from './core/env.js';
 import { loadRegistry } from './core/registry.js';
 import { COMMUNITY_CATEGORY_LABELS } from './core/community.js';
 import { scheduleRestart } from './core/restart.js';
 import { upgradeEffectLine } from './core/activation.js';
 import { pathToFileURL } from 'node:url';
-import { realpathSync } from 'node:fs';
+import { realpathSync, existsSync } from 'node:fs';
 /** 分类中文标签（0.7.0 Task 6；0.9.16 策展五桶）：精选策展桶本地表 + 社区已知标签单一事实源；未知 slug 原样。 */
 const CLI_CATEGORY_LABELS = {
     essentials: '装机必备',
@@ -133,7 +133,7 @@ const HELP = `dshm — DSH Marketplace（DSH 插件市场：精选策展 + 社
   dshm list                          列出 web profile 已装插件（含市场标注/可升级）
   dshm outdated                      检查已装插件的最新版本
   dshm registry                      查看收录清单来源与条目
-  dshm doctor [--json]               profile 体检（只读：农场测活 / 残留物清点 / 账实一致；error 级发现 exit 1）
+  dshm doctor [--json] [--profile web|desktop]  profile 体检（只读：农场测活 / 残留物清点 / 账实一致；error 级发现 exit 1；--profile desktop 为 doctor 专属例外）
 
 变更命令（必须 --yes）：
   dshm install --id <收录id> [--version 1.2.3] [--force]   （--force：确认兼容风险后跳过预检拦截）
@@ -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));
@@ -178,7 +180,10 @@ async function runCliDispatch(argv, deps, io) {
     // 目标恒为 web profile）；--profile desktop / 其他非 web 值显式拒绝并指引官方入口，
     // 绝不隐式回落 web（报告 §5.3「不能从不存在的 Desktop 模式推断」）。
     const profileFlag = typeof flags.profile === 'string' ? flags.profile.trim() : '';
-    if (profileFlag !== '' && profileFlag !== 'web') {
+    // 0.9.31（ADR-0011）：doctor 是纯 FS 只读体检——CLI 上唯一例外允许 --profile desktop；
+    // 其余命令维持「CLI 恒 web profile」拒绝（desktop 的变更类管理仍走官方 Desktop 插件页）。
+    const doctorDesktop = cmd === 'doctor' && profileFlag === 'desktop';
+    if (profileFlag !== '' && profileFlag !== 'web' && !doctorDesktop) {
         err(`错误：dshm CLI 仅作用于 web profile，不支持 --profile ${profileFlag}。`);
         err('Desktop profile 的插件管理请使用官方 Desktop 的插件管理页（Settings → Plugins），或回到 DSH Web 端使用 dsh-m。');
         return 1;
@@ -409,13 +414,16 @@ async function runCliDispatch(argv, deps, io) {
             // 体检（ADR-0010）：纯 FS 只读、不依赖 registry（清单不可用照常工作）。
             // runtimeVersion 仅用 readLauncherPackageVersion 纯 FS 通路（CLI 进程下通常为 null
             // → stale 判定降级 unknown，绝不 spawn）；errors>0 → exit 1。
-            const report = await runDoctor(webProfileDir(), readLauncherPackageVersion());
+            // 0.9.31（ADR-0011）：--profile desktop 例外开口（只读，不与「desktop 管理走官方页」冲突）。
+            const profileName = profileFlag === 'desktop' ? 'desktop' : 'web';
+            const targetDir = profileName === 'desktop' ? desktopProfileDir() : webProfileDir();
+            const report = await runDoctor(targetDir, readLauncherPackageVersion());
             if (flags.json === true) {
                 out(JSON.stringify(report, null, 2));
                 return report.summary.errors > 0 ? 1 : 0;
             }
             const s = report.summary;
-            out(`profile 体检 · ${report.profileDir}`);
+            out(`profile 体检 · [${profileName}] · ${report.profileDir}`);
             out(`布局 ${report.layout} · 运行时 ${report.runtimeVersion ?? '未解析（stale 判定降级 unknown，绝不 spawn）'} · 扫描于 ${report.scannedAt}`);
             out(`农场 ${s.farmChecked}（悬空 ${s.farmDangling} · 指旧 ${s.farmStale}${report.runtimeVersion === null ? '（降级：未判定）' : ''}）` +
                 ` · 残留 ${s.residueCount} · 账实 ${s.accountChecked}（不一致 ${s.accountMismatched}） · errors ${s.errors} · warnings ${s.warnings}`);
@@ -455,6 +463,10 @@ async function runCliDispatch(argv, deps, io) {
             }
             for (const u of s.unknowns)
                 out(`ℹ️  ${u}`);
+            if (!existsSync(targetDir)) {
+                // 第二子句只对默认/显式 web 目标出现——显式 --profile desktop 时再建议加 desktop 自相矛盾（评审 G5.2）
+                out(`ℹ️  目标 profile 目录不存在（${targetDir}）${profileName === 'web' ? '；desktop-only 机器请加 --profile desktop' : ''}。`);
+            }
             if (report.dualMarket)
                 out(`ℹ️  双市场并存：${report.dualMarket.join(' + ')} 同时在装（写侧互不知晓，排查时留意）。`);
             if (errs.length === 0)

package/lib/core/doctor.js

@@ -90,7 +90,8 @@ async function readTargetPkgVersion(targetDir) {
  *
  * - 遍历规则（评审 R1.2 定案）：从 profileDir 逐级向上至 DSH_HOME 边界，扫描每级
  *   `node_modules/@deepseek-ai`——本机实况农场在 profile **父目录**的共享 hoisted 店，
- *   不得以「工作区根」为限（否则 0 命中空转，farmChecked=0 是验收失败信号）。
+ *   不得以「工作区根」为限（否则 0 命中空转——该「farmChecked=0 回炉」判定仅适用于
+ *   存在符号链农场的形态；物化布局（典型 desktop）0 为常态，ADR-0011）。
  * - stale 判定只对 dsh 伞包生效：lockstep 店内各核心包（cordis 4.x、dsh-tools 0.1.x…）
  *   与运行时版本**不在同一命名空间**，逐包比较会把 cordis@4.0.1 误标 stale——误报纪律
  *   （健康档误报代价 > 漏报）禁止；其余包 targetVersion 仅作信息呈现。stale-target 只进

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/env.js

@@ -2,12 +2,17 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const WEB_PROFILE = 'web';
+export const DESKTOP_PROFILE = 'desktop';
 export function dshHome() {
     return process.env.DSH_HOME || join(homedir(), '.dsh');
 }
 export function webProfileDir() {
     return join(dshHome(), 'profiles', WEB_PROFILE);
 }
+/** 0.9.31（ADR-0011）：doctor 只读体检的 desktop 目录解析（其余 CLI 命令仍恒 web）。 */
+export function desktopProfileDir() {
+    return join(dshHome(), 'profiles', DESKTOP_PROFILE);
+}
 /**
  * 缓存根（0.9.0 双 profile，ADR-0005）：web 恒走旧路径（DSHM_CACHE_DIR 或
  * `$DSH_HOME/dshm/cache`）——不迁移不清空；非 web profile 加同名段

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.30",
+  "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"
   }
 }