@kira905/dsh-ecosystem-panel 0.4.5 → 0.5.0

package/lib/config.js

@@ -29,10 +29,20 @@
 //                                          四个数据清单的 JSON 文件路径
 //   DSH_ECOSYSTEM_PANEL_WEBSERVER_SERVICE  宿主 web server 服务名（默认 webServer，见 host-protocol.js）
 //   DSH_ECOSYSTEM_PANEL_DISABLED_GROUPS    逗号分隔：把某几类体检整组标为"未启用"
+//
+// 首屏取数三件（SWR / 预热 / 超时预算）的旋钮（缺省值见 DEFAULTS，全部可被 cli > env > 配置文件覆盖）：
+//   DSH_ECOSYSTEM_PANEL_TTL_MS             "过期"阈值（缺省 300000 = 300 s；依据见文档仓 06 篇 §3.2）
+//   DSH_ECOSYSTEM_PANEL_SOURCE_TIMEOUT_MS  单源超时（缺省 2000 ms）
+//   DSH_ECOSYSTEM_PANEL_TOTAL_BUDGET_MS    整页总预算（缺省 6000 ms）
+//   DSH_ECOSYSTEM_PANEL_SOURCE_TIMEOUTS    逐源覆盖单源超时，形如 "boot=1500,skills=500"
+//   DSH_ECOSYSTEM_PANEL_WARMUP             周期预热开关（缺省 0 = 关；开 = 1/true/on）
+//   DSH_ECOSYSTEM_PANEL_WARMUP_MS          预热周期（缺省 300000 ms，下限 5000）
+//   DSH_ECOSYSTEM_PANEL_WARMUP_SOURCES     预热哪些源，逗号分隔；写 * = 全部
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { WARMUP_DEFAULTS } from './warmup.js';
 
 export const PLUGIN_ID = 'dsh-ecosystem-panel';
 export const ENV_PREFIX = 'DSH_ECOSYSTEM_PANEL_';
@@ -58,7 +68,16 @@ export const DEFAULTS = {
   /** 界面文案覆盖：默认**空**（前端有内置中性文案，这里只做覆盖） */
   text: {},
   /** 整组停用的类目（例如不想要补丁体检就写 ["patches"]） */
-  disabledGroups: []
+  disabledGroups: [],
+  /** 首屏取数：TTL（"过期"判据）+ 单源超时 + 整页总预算 + 逐源超时覆盖 */
+  ttlMs: 300000,
+  sourceTimeoutMs: 2000,
+  // 总预算 = 整页的天花板：最慢的那格（升级体检出网查 npm）实测 1.5~3 s，留到 10 s 仍算"有上限"，
+  // 但不会再让一个卡死的源把首屏无限期按住。要更紧就配 TOTAL_BUDGET_MS。
+  totalBudgetMs: 10000,
+  sourceTimeouts: {},
+  /** 周期预热：缺省**关闭**（后台常驻要花资源，不替使用者决定） */
+  warmup: { ...WARMUP_DEFAULTS }
 };
 
 const SCRIPT_KEYS = ['decoupling', 'triageCli', 'registryAudit', 'hostAdapterSync'];
@@ -106,6 +125,120 @@ function dirExists(p) {
   }
 }
 
+/** 这些"窗口"类旋钮的硬上限：一天（写成算式而不是一串数字 —— 八位十进制字面量会被脱敏规则当成 id 形态） */
+const MAX_WINDOW_MS = 24 * 3600 * 1000;
+
+/** 值是否"真的给了"（0 / false 也算给了 —— 夹具与使用者会显式关掉某个旋钮） */
+function present(v) {
+  if (v === undefined || v === null) return false;
+  if (typeof v === 'string') return v.trim() !== '';
+  return true;
+}
+function toNum(v, min, max, fallback) {
+  const n = Number(typeof v === 'string' ? v.trim() : v);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+function toBool(v, fallback) {
+  if (typeof v === 'boolean') return v;
+  const s = String(v ?? '').trim().toLowerCase();
+  if (['1', 'true', 'on', 'yes', 'y', '开'].includes(s)) return true;
+  if (['0', 'false', 'off', 'no', 'n', '关'].includes(s)) return false;
+  return fallback;
+}
+/** "a=1,b=200" 或 {a:1,b:200} → { a:1, b:200 }（非数字 / 非正数一律丢弃） */
+function toTimeoutMap(v) {
+  const out = {};
+  const put = (k, val) => {
+    const key = typeof k === 'string' ? k.trim() : '';
+    const n = Number(val);
+    if (key && Number.isFinite(n) && n > 0) out[key] = Math.min(600000, Math.round(n));
+  };
+  if (v && typeof v === 'object' && !Array.isArray(v)) {
+    for (const [k, val] of Object.entries(v)) put(k, val);
+    return out;
+  }
+  for (const part of String(v ?? '').split(/[,;]/)) {
+    const at = part.indexOf('=');
+    if (at > 0) put(part.slice(0, at), part.slice(at + 1));
+  }
+  return out;
+}
+
+/**
+ * 首屏取数策略（TTL / 超时预算 / 预热）：**每个键独立**按 cli > env > 配置文件 > 缺省 解析，
+ * 并把"从哪读到的"一并带出（面板 meta 会原样展示 ⇒ 陌生环境排障不用猜）。
+ * 支持嵌套写法：clí/config 里的 `warmup: { enabled, intervalMs, sources }`。
+ */
+export function resolveFetchPolicy({ cli = {}, env = process.env, file = {} } = {}) {
+  const envVal = (key) => {
+    const v = env?.[ENV_PREFIX + key];
+    return present(v) ? String(v).trim() : undefined;
+  };
+  const cliWarm = cli && typeof cli.warmup === 'object' && cli.warmup !== null ? cli.warmup : {};
+  const fileWarm = file && typeof file.warmup === 'object' && file.warmup !== null ? file.warmup : {};
+  const sources = {};
+
+  const pickRaw = (cliKey, envKey, fileKey, fallback, fromCli = cli[cliKey], fromFile = file[fileKey ?? cliKey]) => {
+    let r;
+    if (present(fromCli)) r = { value: fromCli, from: 'cli' };
+    else if (envKey && envVal(envKey) !== undefined) r = { value: envVal(envKey), from: `env:${ENV_PREFIX}${envKey}` };
+    else if (present(fromFile)) r = { value: fromFile, from: 'config-file' };
+    else r = { value: fallback, from: 'default' };
+    return r;
+  };
+
+  const ttl = pickRaw('ttlMs', 'TTL_MS', 'ttlMs', DEFAULTS.ttlMs);
+  sources.ttlMs = { value: toNum(ttl.value, 0, MAX_WINDOW_MS, DEFAULTS.ttlMs), from: ttl.from };
+  const sto = pickRaw('sourceTimeoutMs', 'SOURCE_TIMEOUT_MS', 'sourceTimeoutMs', DEFAULTS.sourceTimeoutMs);
+  sources.sourceTimeoutMs = { value: toNum(sto.value, 1, 600000, DEFAULTS.sourceTimeoutMs), from: sto.from };
+  const budget = pickRaw('totalBudgetMs', 'TOTAL_BUDGET_MS', 'totalBudgetMs', DEFAULTS.totalBudgetMs);
+  sources.totalBudgetMs = { value: toNum(budget.value, 1, 600000, DEFAULTS.totalBudgetMs), from: budget.from };
+  const perSource = pickRaw('sourceTimeouts', 'SOURCE_TIMEOUTS', 'sourceTimeouts', DEFAULTS.sourceTimeouts);
+  sources.sourceTimeouts = { value: toTimeoutMap(perSource.value), from: perSource.from };
+  sources.sourceTimeouts.value = Object.keys(sources.sourceTimeouts.value).length
+    ? `${Object.keys(sources.sourceTimeouts.value).length} 源`
+    : '（无覆盖）';
+
+  const enabled = pickRaw('warmupEnabled', 'WARMUP', 'warmupEnabled',
+    DEFAULTS.warmup.enabled,
+    present(cliWarm.enabled) ? cliWarm.enabled : undefined,
+    present(fileWarm.enabled) ? fileWarm.enabled : undefined);
+  const interval = pickRaw('warmupIntervalMs', 'WARMUP_MS', 'warmupIntervalMs',
+    DEFAULTS.warmup.intervalMs,
+    present(cliWarm.intervalMs) ? cliWarm.intervalMs : undefined,
+    present(fileWarm.intervalMs) ? fileWarm.intervalMs : undefined);
+  const warmSources = pickRaw('warmupSources', 'WARMUP_SOURCES', 'warmupSources',
+    DEFAULTS.warmup.sources,
+    present(cliWarm.sources) ? cliWarm.sources : undefined,
+    present(fileWarm.sources) ? fileWarm.sources : undefined);
+
+  const toList = (v) => (Array.isArray(v)
+    ? v.map((x) => String(x).trim()).filter(Boolean)
+    : String(v ?? '').split(/[,;\s]+/).map((x) => x.trim()).filter(Boolean));
+
+  const policy = {
+    ttlMs: sources.ttlMs.value,
+    sourceTimeoutMs: sources.sourceTimeoutMs.value,
+    totalBudgetMs: sources.totalBudgetMs.value,
+    sourceTimeouts: toTimeoutMap(perSource.value),
+    warmup: {
+      enabled: toBool(enabled.value, DEFAULTS.warmup.enabled),
+      // 0 / 负数 = 没给（回缺省 300 s）；太密则压到 5 s 下限 —— 两种都不许变成空转
+      intervalMs: (() => {
+        const raw = Number(interval.value);
+        if (!Number.isFinite(raw) || raw <= 0) return DEFAULTS.warmup.intervalMs;
+        return Math.min(MAX_WINDOW_MS, Math.max(5000, Math.round(raw)));
+      })(),
+      sources: toList(warmSources.value)
+    }
+  };
+  sources.warmupEnabled = { value: policy.warmup.enabled ? 'on' : 'off', from: enabled.from };
+  sources.warmupIntervalMs = { value: policy.warmup.intervalMs, from: interval.from };
+  sources.warmupSources = { value: policy.warmup.sources.join(',') || '(缺省)', from: warmSources.from };
+  return { policy, sources };
+}
+
 /** 把配置里的 ${HOME} / ${PROFILE_DIR} / ${PROFILE_NM} / ${SKILLS_DIR} / ${MAIN_NM} 占位符展开成实际路径 */
 export function expandVars(value, cfg) {
   if (typeof value !== 'string' || !value.includes('${')) return value;
@@ -240,6 +373,15 @@ export function resolveConfig(cli = {}, env = process.env) {
     sources
   };
 
+  // ---- 首屏取数策略（TTL / 单源超时 / 总预算 / 预热）------------------------
+  const fetchPolicy = resolveFetchPolicy({ cli, env, file: fileCfg });
+  cfg.ttlMs = fetchPolicy.policy.ttlMs;
+  cfg.sourceTimeoutMs = fetchPolicy.policy.sourceTimeoutMs;
+  cfg.totalBudgetMs = fetchPolicy.policy.totalBudgetMs;
+  cfg.sourceTimeouts = fetchPolicy.policy.sourceTimeouts;
+  cfg.warmup = fetchPolicy.policy.warmup;
+  Object.assign(cfg.sources, fetchPolicy.sources);
+
   // ---- 四个外部脚本（cli > env > 配置文件 > toolsDir 派生 > null）------------
   for (const key of SCRIPT_KEYS) {
     const envKey = { decoupling: 'DECOUPLING_SCRIPT', triageCli: 'TRIAGE_CLI', registryAudit: 'REGISTRY_AUDIT_LIB', hostAdapterSync: 'HOST_ADAPTER_SYNC' }[key];

package/lib/fetch-lane.js

@@ -0,0 +1,399 @@
+// dsh-ecosystem-panel / lib/fetch-lane.js
+//
+// 取数车道：只读面板首屏的四件工程件，一处实现、按源复用。
+//
+//   ① TTL 缓存 + SWR —— 数据块自带 fetchedAt；过期先给旧值（带年龄），后台换新。
+//      冷启动（连旧值都没有）**不许返回空壳**：阻塞取真值，并把这一次记成 coldMiss。
+//   ② 单飞 —— 同一源同一时刻只有一次在途取数；并发请求共享那一次。
+//   ③ 超时预算 —— 每源一个超时，整页一个总预算；慢源不拖死整页。
+//   ④ 局部降级 —— 某源超时 / 报错 / 未配置 ⇒ 只有那一格标「不可探测 + 原因」，其余照出。
+//
+// 计量（SLI）也在这里数：命中 / 未命中 / 冷启动 / 取数耗时 / 降级次数。**每轮读数都是现算的**，
+// 不落盘、不跨进程复用。
+//
+// 这一层只做"取数这件事"，不掺任何业务判定 —— 源的清单与每个源怎么跑，由调用方给
+// （本仓见 lib/state.js 的 SOURCES；下游也可以 registerSource() 追加自己的源）。
+
+/** 缺省 TTL = 300 s（复用体系里既有的五分钟节奏；依据见文档仓《06-只读监控面板的设计纪律》§3.2） */
+export const DEFAULT_TTL_MS = 300000;
+/** 缺省单源超时 */
+export const DEFAULT_SOURCE_TIMEOUT_MS = 2000;
+/** 缺省整页总预算（单源超时之和会远大于它，这里防"十个慢源叠起来"） */
+export const DEFAULT_TOTAL_BUDGET_MS = 6000;
+/** 失败后的冷却：冷却期内不再反复打同一个坏源（避免一个挂掉的源被每屏请求反复捅） */
+export const DEFAULT_RETRY_DELAY_MS = 5000;
+
+/** 降级原因枚举（页面上原样显示，所以只放三种 + 预算一种） */
+export const REASON = Object.freeze({
+  TIMEOUT: '超时',
+  ERROR: '报错',
+  NOT_CONFIGURED: '未配置',
+  BUDGET: '总预算耗尽'
+});
+
+function num(v, fallback) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function timeoutError(ms) {
+  const e = new Error(`取数超时（>${ms} ms）`);
+  e.code = 'LANE_TIMEOUT';
+  return e;
+}
+
+/**
+ * 建一条车道。
+ * @param {object} options
+ * @param {Array<object>} options.sources 源定义：{ id, label, group, deps?, timeoutMs?, requires?(ctx), run(ctx) }
+ * @param {number} [options.ttlMs]
+ * @param {number} [options.defaultTimeoutMs]  每源超时缺省值（源定义里的 timeoutMs 优先）
+ * @param {number} [options.totalBudgetMs]     一次 readAll 的总预算
+ * @param {number} [options.retryDelayMs]      失败冷却窗口
+ * @param {() => number} [options.now]         时钟（夹具注入假时钟测 TTL 用）
+ * @param {() => number} [options.elapsedClock] 真实耗时用的钟（缺省 Date.now；两者故意分开）
+ * @param {object} [options.context]           车道级上下文（paths / cfg / opts）：预热走 lane.prime() 时也要能取数
+ */
+export function createLane(options = {}) {
+  const clock = typeof options.now === 'function' ? options.now : () => Date.now();
+  // 两个钟故意分开：clock 管"数据块什么时候取的"（夹具会注入假时钟测 TTL），
+  // real 管"这次取数花了多久"（假时钟不会随真实等待走动，混用会把耗时读成 0）。
+  const real = typeof options.elapsedClock === 'function' ? options.elapsedClock : () => Date.now();
+  const ttlMs = num(options.ttlMs, DEFAULT_TTL_MS);
+  const defaultTimeoutMs = num(options.defaultTimeoutMs, DEFAULT_SOURCE_TIMEOUT_MS);
+  const totalBudgetMs = num(options.totalBudgetMs, DEFAULT_TOTAL_BUDGET_MS);
+  const retryDelayMs = num(options.retryDelayMs, DEFAULT_RETRY_DELAY_MS);
+
+  /** id -> 源定义 */
+  const defs = new Map();
+  /** id -> { value, fetchedAt, elapsedMs }：已取回的数据块（自带 fetchedAt 就是 SWR 的全部状态） */
+  const cache = new Map();
+  /** id -> { promise, startedAt }：在途表（单飞的唯一凭据） */
+  const inflight = new Map();
+  /** id -> { at, reason, detail }：最近一次失败（冷却窗口用） */
+  const failure = new Map();
+  /** id -> 计数 */
+  const meters = new Map();
+  const totals = { requests: 0, requestMs: 0, lastRequestMs: 0 };
+
+  function addSource(def) {
+    if (!def || typeof def.id !== 'string' || typeof def.run !== 'function') {
+      throw new Error('fetch-lane: 源定义至少要 { id, run }');
+    }
+    defs.set(def.id, def);
+    return def;
+  }
+  for (const def of options.sources ?? []) addSource(def);
+
+  function meter(id) {
+    let m = meters.get(id);
+    if (!m) {
+      m = { hit: 0, miss: 0, coldMiss: 0, fetches: 0, failures: 0, degraded: 0, fetchMs: 0, lastMs: 0 };
+      meters.set(id, m);
+    }
+    return m;
+  }
+
+  const expired = (entry, t) => (t - entry.fetchedAt) > ttlMs;
+
+  /** 一次读取的结果形状（stale/fresh/cold/degraded 四态，页面只认前三个有值） */
+  function freshResult(id, entry, t, status) {
+    return {
+      id,
+      status,
+      value: entry.value,
+      fetchedAt: entry.fetchedAt,
+      ageMs: Math.max(0, t - entry.fetchedAt),
+      elapsedMs: 0,
+      reason: null,
+      detail: null
+    };
+  }
+
+  function degradedResult(id, reason, detail, elapsedMs, extra = {}) {
+    return {
+      id,
+      status: 'degraded',
+      value: undefined,
+      fetchedAt: null,
+      ageMs: null,
+      elapsedMs,
+      reason,
+      detail: detail ?? null,
+      ...extra
+    };
+  }
+
+  function classify(error) {
+    if (error?.code === 'LANE_TIMEOUT') return { reason: REASON.TIMEOUT, detail: String(error?.message ?? error) };
+    return { reason: REASON.ERROR, detail: String(error?.message ?? error) };
+  }
+
+  /** 迟到 / 及时的成功都缓存：成功后清掉失败标记 */
+  function store(id, value, startedAt) {
+    const at = clock();
+    const prev = cache.get(id);
+    if (!prev || prev.fetchedAt <= at) {
+      cache.set(id, { value, fetchedAt: at, elapsedMs: at - startedAt });
+    }
+    failure.delete(id);
+    return at;
+  }
+
+  function withTimeout(promise, ms) {
+    if (!(ms > 0) || !Number.isFinite(ms)) return promise;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(timeoutError(ms)), ms);
+      if (typeof timer.unref === 'function') timer.unref();
+      promise.then(
+        (v) => { clearTimeout(timer); resolve(v); },
+        (e) => { clearTimeout(timer); reject(e); }
+      );
+    });
+  }
+
+  /**
+   * 真正跑一次源（含单飞 / 超时 / 预算 / 降级记账）。
+   * @returns {Promise<{ok:boolean, value?:any, reason?:string, detail?:string, elapsedMs:number}>}
+   */
+  function refresh(def, ctx = {}) {
+    const running = inflight.get(def.id);
+    if (running) return running.promise;   // ← 单飞：后来者共享在途那一次
+
+    const startedAt = clock();
+    const startedReal = real();
+    const budgetLeft = typeof ctx.deadline === 'number' ? ctx.deadline - clock() : Infinity;
+    const ownTimeout = num(ctx?.opts?.sourceTimeouts?.[def.id], num(def.timeoutMs, defaultTimeoutMs));
+    const limit = Math.min(ownTimeout, budgetLeft);
+    // 掐断是"单源超时"还是"整页预算用完了"？—— 页脚上这两个原因必须分得开：
+    // 前者说明这个源慢，后者说明整页的预算该调了（或者某个源在拖后腿）。
+    const budgetBound = budgetLeft < ownTimeout;
+
+    const m = meter(def.id);
+    const promise = (async () => {
+      if (!(limit > 0)) {
+        m.degraded += 1;
+        return { ok: false, reason: REASON.BUDGET, detail: `整页总预算 ${totalBudgetMs} ms 已用完`, elapsedMs: real() - startedReal, noFetch: true };
+      }
+      const gateReason = typeof def.requires === 'function' ? def.requires(ctx) : null;
+      if (gateReason) {
+        m.degraded += 1;
+        return { ok: false, reason: REASON.NOT_CONFIGURED, detail: String(gateReason), elapsedMs: real() - startedReal, noFetch: true };
+      }
+      m.fetches += 1;
+      const startedFetch = clock();
+      const sourcePromise = Promise.resolve().then(() => def.run(ctx));
+      // 迟到的成功也收下：超时只是"这一屏不再等"，不是"这个源的数据作废"
+      sourcePromise.then(
+        (value) => { store(def.id, value, startedFetch); },
+        () => { /* 失败由下面的 catch 记账；这里只吞掉未处理的 rejection */ }
+      );
+      try {
+        const value = await withTimeout(sourcePromise, limit);
+        const elapsed = real() - startedReal;
+        store(def.id, value, startedFetch);
+        m.lastMs = elapsed;
+        m.fetchMs += elapsed;
+        return { ok: true, value, elapsedMs: elapsed };
+      } catch (error) {
+        const elapsed = real() - startedReal;
+        const classified = classify(error);
+        const reason = budgetBound && classified.reason === REASON.TIMEOUT ? REASON.BUDGET : classified.reason;
+        const detail = reason === REASON.BUDGET
+          ? `整页总预算 ${totalBudgetMs} ms 已用完（本源的超时上限是 ${ownTimeout} ms）`
+          : classified.detail;
+        m.failures += 1;
+        m.degraded += 1;
+        m.lastMs = elapsed;
+        failure.set(def.id, { at: clock(), reason, detail });
+        return { ok: false, reason, detail, elapsedMs: elapsed };
+      }
+    })();
+
+    inflight.set(def.id, { promise, startedAt });
+    promise.finally(() => {
+      const cur = inflight.get(def.id);
+      if (cur && cur.promise === promise) inflight.delete(def.id);
+    }).catch(() => {});
+    return promise;
+  }
+
+  /**
+   * 读一个源。
+   *   新鲜 → hit；过期 → 先给旧值（stale）+ 后台刷新（miss）；没有旧值 → 阻塞取真值（coldMiss）。
+   */
+  async function read(target, ctx = {}) {
+    const def = typeof target === 'string' ? defs.get(target) : target;
+    if (!def) throw new Error(`fetch-lane: 未知数据源 ${String(target)}`);
+    const t = clock();
+    const entry = cache.get(def.id);
+    const m = meter(def.id);
+
+    if (entry !== undefined && !expired(entry, t)) {
+      m.hit += 1;
+      return freshResult(def.id, entry, t, 'fresh');
+    }
+    if (entry !== undefined) {
+      m.miss += 1;
+      refresh(def, ctx);                       // 不 await：这一屏用旧值先出
+      return freshResult(def.id, entry, t, 'stale');
+    }
+    const cool = failure.get(def.id);
+    if (cool && (t - cool.at) < retryDelayMs) {
+      // 刚失败过：冷却期内不再捅它，直接如实报「不可探测」+ 上次的原因
+      m.degraded += 1;
+      return degradedResult(def.id, cool.reason, cool.detail, 0, { coolingDown: true });
+    }
+    m.coldMiss += 1;
+    const started = real();
+    const r = await refresh(def, ctx);
+    if (r.ok) {
+      const at = clock();
+      const justStored = cache.get(def.id);
+      const entryNow = justStored ?? { value: r.value, fetchedAt: at };
+      if (!justStored) cache.set(def.id, { value: r.value, fetchedAt: at, elapsedMs: r.elapsedMs });
+      return { ...freshResult(def.id, entryNow, at, 'cold'), elapsedMs: real() - started };
+    }
+    return degradedResult(def.id, r.reason, r.detail, real() - started, { reasonCode: r.reason });
+  }
+
+  /**
+   * 一次取数 pass：按依赖顺序把给定源读出来（同一 pass 内同一源只读一次），
+   * 整页共享一个总预算 deadline。
+   * @param {string[]} ids
+   * @param {{ opts?: object, force?: string[]|boolean }} [ctx]
+   * @returns {Promise<{ results: Map<string, object>, byId: object, startedAt:number, elapsedMs:number, deadline:number }>}
+   */
+  async function readAll(ids, ctx = {}) {
+    const startedAt = clock();
+    const startedReal = real();
+    const deadline = startedAt + totalBudgetMs;
+    const base = options.context ?? {};   // 车道级上下文：路径/配置这类"每条车道都一样"的东西
+    const pass = {
+      opts: ctx.opts ?? base.opts ?? {},
+      deadline,
+      values: new Map(),
+      results: new Map(),
+      pending: new Map()
+    };
+    const force = ctx.force === true ? new Set(ids) : new Set(Array.isArray(ctx.force) ? ctx.force : []);
+
+    const visit = (id) => {
+      if (pass.results.has(id)) return Promise.resolve(pass.results.get(id));
+      if (pass.pending.has(id)) return pass.pending.get(id);
+      const def = defs.get(id);
+      if (!def) return Promise.reject(new Error(`fetch-lane: 未知数据源 ${id}`));
+      const p = (async () => {
+        for (const dep of def.deps ?? []) {
+          if (!defs.has(dep)) continue;
+          await visit(dep);
+        }
+        const one = {
+          ...base,
+          ...ctx,
+          deadline,
+          get: (depId) => pass.values.get(depId),
+          paths: ctx.paths ?? base.paths ?? null,
+          cfg: ctx.cfg ?? base.cfg ?? null
+        };
+        if (force.has(id)) cache.delete(id);     // 显式刷新：丢掉旧值，按冷路径重取
+        const r = await read(def, one);
+        pass.results.set(id, r);
+        pass.values.set(id, r.value);
+        return r;
+      })();
+      pass.pending.set(id, p);
+      return p;
+    };
+
+    await Promise.all(ids.map(visit));
+    const elapsedMs = real() - startedReal;
+    totals.requests += 1;
+    totals.requestMs += elapsedMs;
+    totals.lastRequestMs = elapsedMs;
+    const byId = {};
+    for (const [id, r] of pass.results) byId[id] = r;
+    return { results: pass.results, byId, startedAt, elapsedMs, deadline };
+  }
+
+  /** 预热用：把给定源读一遍（新鲜的就只算命中，不重复取） */
+  async function prime(ids, ctx = {}) {
+    const out = await readAll(ids, ctx);
+    const summary = { at: new Date().toISOString(), elapsedMs: out.elapsedMs, sources: {} };
+    for (const [id, r] of out.results) {
+      summary.sources[id] = { status: r.status, elapsedMs: r.elapsedMs, reason: r.reason ?? null };
+    }
+    return summary;
+  }
+
+  /** 等在途取数全部落定（夹具与"后台刷新完再看一眼"用） */
+  async function settle() {
+    while (inflight.size > 0) {
+      const list = [...inflight.values()].map((v) => v.promise.catch(() => {}));
+      await Promise.all(list);
+    }
+  }
+
+  /** SLI 读数（页脚那三行数的源） */
+  function sli() {
+    const perSource = {};
+    const sums = { hit: 0, miss: 0, coldMiss: 0, fetches: 0, failures: 0, degraded: 0 };
+    for (const [id, m] of meters) {
+      const avgMs = m.fetches > 0 ? Math.round(m.fetchMs / m.fetches) : 0;
+      perSource[id] = {
+        hit: m.hit,
+        miss: m.miss,
+        coldMiss: m.coldMiss,
+        fetches: m.fetches,
+        failures: m.failures,
+        degraded: m.degraded,
+        lastMs: m.lastMs,
+        avgMs,
+        cached: cache.has(id),
+        ageMs: cache.has(id) ? Math.max(0, clock() - cache.get(id).fetchedAt) : null,
+        stale: cache.has(id) ? expired(cache.get(id), clock()) : null,
+        inflight: inflight.has(id)
+      };
+      for (const k of Object.keys(sums)) sums[k] += m[k];
+    }
+    return {
+      ttlMs,
+      defaultTimeoutMs,
+      totalBudgetMs,
+      retryDelayMs,
+      sources: perSource,
+      totals: {
+        ...sums,
+        requests: totals.requests,
+        lastRequestMs: totals.lastRequestMs,
+        avgRequestMs: totals.requests > 0 ? Math.round(totals.requestMs / totals.requests) : 0,
+        inflight: inflight.size
+      }
+    };
+  }
+
+  /** 夹具用：清空缓存/在途/计数（不删源定义） */
+  function reset() {
+    cache.clear();
+    inflight.clear();
+    failure.clear();
+    meters.clear();
+    totals.requests = 0;
+    totals.requestMs = 0;
+    totals.lastRequestMs = 0;
+  }
+
+  return {
+    ids: () => [...defs.keys()],
+    defs,
+    addSource,
+    read,
+    readAll,
+    prime,
+    settle,
+    sli,
+    reset,
+    ttlMs,
+    totalBudgetMs
+  };
+}

package/lib/index.js

@@ -1,10 +1,16 @@
 // dsh-ecosystem-panel / lib/index.js（服务端）
 // 注册 GET /api/dsh-ecosystem-panel/state —— 只读聚合，无副作用，不加请求栅栏。
 // 本 API 只暴露一个只读 GET（没有任何写操作入口），因此不需要控制面栅栏。
-import { API_PREFIX, buildState } from './state.js';
+//
+// 首屏三件（SWR / 周期预热 / 分片取数）的接线都在这里：
+//   · 车道（fetch-lane）按当前配置建一条，route 与预热器**共用同一条** ——
+//     否则预热填的是另一份缓存，首屏照样吃冷启动（"预热开着却没用"最常见的写法错误）；
+//   · 预热器由配置层决定开不开（缺省关），生命周期跟着插件 effect 走，卸载时 timer 一并停掉。
+import { API_PREFIX, buildState, getLane, setWarmupReporter } from './state.js';
+import { startWarmup } from './warmup.js';
 // 宿主服务名常量（自带，不依赖任何外部适配层；服务名可经环境变量覆盖，见 host-protocol.js）
 import { SVC } from './host-protocol.js';
-import { setConfigOverride } from './config.js';
+import { getConfig, setConfigOverride } from './config.js';
 
 export const inject = [SVC.webServer];
 export const name = 'dsh-ecosystem-panel';
@@ -28,6 +34,15 @@ function apply(ctx, pluginConfig) {
   if (pluginConfig && typeof pluginConfig === 'object') setConfigOverride(pluginConfig);
   ctx.effect(() => {
     const disposers = [];
+    const cfg = getConfig();
+    const lane = getLane(cfg);
+    const warm = startWarmup({
+      lane,
+      cfg,
+      log: (m) => console.log('[ecosystem-panel] ' + m)
+    });
+    // 预热状态进 SLI（页脚与 /state 都能看到"开没开、跑过几次、上次多久"）
+    setWarmupReporter(() => warm.status());
     try {
       disposers.push(ctx.webServer.register({
         kind: 'exact',
@@ -37,9 +52,12 @@ function apply(ctx, pluginConfig) {
             return writeJson(res, 405, { ok: false, error: 'method-not-allowed' }, { 'cache-control': 'no-store' });
           }
           try {
-            // ?refresh=1 强制重查 npm latest（默认走 24h 文件缓存，面板打开不卡）
-            const refresh = /(?:\?|&)refresh=1(?:&|$)/.test(req.url ?? '');
-            const state = await buildState({ refreshUpgrades: refresh });
+            // ?refresh=1 只强制重查升级体检（默认走 TTL 缓存，面板打开不卡）；
+            // ?refresh=all 则整屏丢缓存重取（排障用，别日常按）
+            const url = req.url ?? '';
+            const refresh = /(?:\?|&)refresh=1(?:&|$)/.test(url);
+            const forceAll = /(?:\?|&)refresh=all(?:&|$)/.test(url);
+            const state = await buildState({ lane, refreshUpgrades: refresh, ...(forceAll ? { force: true } : {}) });
             writeJson(res, 200, state, { 'cache-control': 'no-store' });
           } catch (error) {
             writeJson(res, 500, { ok: false, error: String(error?.message ?? error) }, { 'cache-control': 'no-store' });
@@ -48,9 +66,13 @@ function apply(ctx, pluginConfig) {
       }));
     } catch (error) {
       for (const dispose of disposers) dispose();
+      warm.stop();
+      setWarmupReporter(null);
       throw error;
     }
     return () => {
+      warm.stop();
+      setWarmupReporter(null);
       for (const dispose of disposers) dispose();
     };
   }, 'ecosystem-panel: state route');