@kira905/dsh-ecosystem-panel 0.4.5 → 0.5.0

package/lib/warmup.js

@@ -0,0 +1,131 @@
+// dsh-ecosystem-panel / lib/warmup.js
+//
+// 周期预热：让首屏别再"每次都从零算"。
+//
+// 三条纪律（缺一条都会变成"悄悄后台常驻"）：
+//   ① **缺省关闭** —— 预热是要花资源的后台动作，默认不替使用者决定。
+//   ② 开了就有自证 —— 开启 / 周期 / 预热哪些源（三个环境变量口 + 配置文件同名键），
+//      以及"跑过几次、上次多久、上次每个源什么状态"全部进 SLI，页脚跟状态接口都看得到。
+//   ③ 周期缺省 = 300 s，与 TTL 同源（文档仓《06-只读监控面板的设计纪律》§3.2：
+//      复用体系里既有的五分钟节奏，**不新增定时作业**）—— 预热只是把同一个 TTL 提前填好，
+//      频率比 TTL 更密是白烧 CPU，更疏则首屏照样吃冷启动。
+//
+// 预热**不联网做额外的事**：它只调用面板本来就会调的那几个源（lane.prime），所以"预热改了行为"
+// 这种风险不存在；最坏情况是它把某个慢源多读了几遍 —— 而读幂等、只读、无副作用。
+
+/** 缺省预热周期 = 300 s（与 TTL 同源，见文件头） */
+export const DEFAULT_WARMUP_INTERVAL_MS = 300000;
+/** 预热周期下限：再密就纯属烧 CPU（一屏数据 300 s 才旧一次） */
+export const MIN_WARMUP_INTERVAL_MS = 5000;
+/**
+ * 缺省预热哪些源：**只挑纯本地、零网络的轻片**。
+ * boot / bundles / inserts / patches / skills 都是"读几个文件 + 抓一次本机 HTML"；
+ * decoupling / upgrades / registry 要跑外部脚本或查 npm，**不进缺省预热**（要就自己点名）。
+ */
+export const DEFAULT_WARMUP_SOURCES = ['boot', 'bundles', 'inserts', 'patches', 'skills'];
+
+export const WARMUP_DEFAULTS = Object.freeze({
+  enabled: false,
+  intervalMs: DEFAULT_WARMUP_INTERVAL_MS,
+  sources: DEFAULT_WARMUP_SOURCES
+});
+
+function clampInterval(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_WARMUP_INTERVAL_MS;
+  return Math.max(MIN_WARMUP_INTERVAL_MS, Math.round(n));
+}
+
+/**
+ * 起一个预热器。
+ * @param {object} opts
+ * @param {object} opts.lane                     fetch-lane 实例
+ * @param {object} [opts.cfg]                    配置层解析结果（读 cfg.warmup）
+ * @param {(m:string)=>void} [opts.log]
+ * @returns {{ enabled:boolean, config:object, status:()=>object, primeNow:()=>Promise<object>,
+ *            whenReady:()=>Promise<object|undefined>, stop:()=>void }}
+ */
+export function startWarmup(opts = {}) {
+  const lane = opts.lane;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+  const conf = { ...WARMUP_DEFAULTS, ...(opts.cfg?.warmup ?? {}) };
+  const enabled = conf.enabled === true;
+  const intervalMs = clampInterval(conf.intervalMs);
+  const sources = Array.isArray(conf.sources) && conf.sources.length ? conf.sources.slice() : DEFAULT_WARMUP_SOURCES.slice();
+
+  const state = {
+    enabled,
+    intervalMs,
+    sources,
+    runs: 0,
+    lastRunAt: null,
+    lastElapsedMs: null,
+    lastSources: null,
+    errors: 0,
+    lastError: null,
+    nextRunAt: null
+  };
+
+  if (!lane || !enabled) {
+    return {
+      enabled: false,
+      config: { enabled, intervalMs, sources },
+      status: () => ({ ...state, reason: lane ? `未开启（缺省关闭；开法：环境变量 WARMUP=1，见 README）` : '未接车道' }),
+      primeNow: async () => ({ skipped: true, reason: '预热未开启' }),
+      whenReady: async () => undefined,
+      stop: () => {}
+    };
+  }
+
+  const knownIds = typeof lane.ids === 'function' ? new Set(lane.ids()) : null;
+  const asked = sources.includes('*') ? (knownIds ? [...knownIds] : []) : sources;
+  const targets = knownIds ? asked.filter((id) => knownIds.has(id)) : asked;
+  state.sources = targets;
+
+  let timer = null;
+  let running = null;
+
+  const runOnce = async () => {
+    const startedAt = Date.now();
+    try {
+      const summary = await lane.prime(targets);
+      state.runs += 1;
+      state.lastRunAt = new Date().toISOString();
+      state.lastElapsedMs = Date.now() - startedAt;
+      state.lastSources = summary.sources;
+      log(`warmup #${state.runs}: ${targets.length} 源 / ${state.lastElapsedMs} ms`);
+      return summary;
+    } catch (error) {
+      state.errors += 1;
+      state.lastError = String(error?.message ?? error);
+      log(`warmup 失败：${state.lastError}`);
+      return { error: state.lastError };
+    } finally {
+      state.nextRunAt = new Date(Date.now() + intervalMs).toISOString();
+    }
+  };
+
+  const primeNow = () => {
+    if (running) return running;              // 上一次还没回来就别叠着跑
+    running = runOnce().finally(() => { running = null; });
+    return running;
+  };
+
+  // 先填一次（"预热生效"的证据就在这里：首屏请求到达时缓存已经热了），然后按周期续。
+  const first = primeNow();
+  timer = setInterval(() => { primeNow(); }, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  return {
+    enabled: true,
+    config: { enabled, intervalMs, sources: targets },
+    status: () => ({ ...state, inFlight: running !== null }),
+    primeNow,
+    whenReady: () => first,
+    stop: () => {
+      if (timer) clearInterval(timer);
+      timer = null;
+      state.enabled = false;
+    }
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kira905/dsh-ecosystem-panel",
   "description": "Read-only ecosystem overview panel for a DSH instance: plugin bundles, cordis.patch inserts, patch health, skills, upgrade health and decoupling health. One tab per category. Zero runtime npm dependencies.",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -31,6 +31,12 @@
   "scripts": {
     "verify": "node scripts/verify-source.mjs .",
     "test": "node scripts/test-fixture.mjs",
+    "test:swr": "node scripts/test-swr.mjs",
+    "test:warmup": "node scripts/test-warmup-negctl.mjs",
+    "test:singleflight": "node scripts/test-singleflight.mjs",
+    "test:degrade": "node scripts/test-degrade.mjs",
+    "test:all": "node scripts/test-fixture.mjs && node scripts/test-swr.mjs && node scripts/test-warmup-negctl.mjs && node scripts/test-singleflight.mjs && node scripts/test-degrade.mjs",
+    "sim": "node scripts/sim-selfcheck.mjs",
     "state": "node scripts/verify-state.mjs"
   },
   "peerDependencies": {

package/scripts/sim-selfcheck.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// scripts/sim-selfcheck.mjs —— 新文件「行级同源度」自查（本仓 K8 的硬约束判据）
+//
+// 干什么：对本仓**新增**的 .js/.mjs 逐个算「行级同源度」——
+//   分子 = 这个新文件里有多少条非空行，能在参照件里找到（多重集扣减，重复行按次数算）
+//   分母 = 这个新文件自己的非空行数
+//   参照件 = ① 生产源里**同名**的文件（有就算，这是最直接的"近源"判据）
+//            ② 本仓既有的**其它** .js/.mjs（本仓既有件本身就是生产件的近源副本 ⇒ 拿它当参照
+//               是**更严**的口径：新文件连自家老件都不能像）
+//   主结论 = 取所有参照件里最高的那个比值。**< 50% 才算通过**。
+//
+// 一键跑（示例）：
+//   node scripts/sim-selfcheck.mjs --since d069a79          # 自某个 commit 起新增的文件
+//   node scripts/sim-selfcheck.mjs --files lib/fetch-lane.js,lib/warmup.js
+//   node scripts/sim-selfcheck.mjs --since d069a79 --json   # 机器可读
+//
+// 为什么不用"逐字节相同"：删几行注释就判"不同源"，会低估同源度 ⇒ 主结论用行级。
+// 退出码：0 = 全部 < 50%；1 = 有文件 ≥ 50%（= 这条硬约束没过）；2 = 用法错误。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(process.argv.includes('--repo')
+  ? process.argv[process.argv.indexOf('--repo') + 1]
+  : path.join(HERE, '..'));
+
+const arg = (name, fallback = null) => {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? (process.argv[i + 1] ?? fallback) : fallback;
+};
+const asJson = process.argv.includes('--json');
+const since = arg('--since');
+const filesArg = arg('--files');
+const prodRoot = path.resolve(arg('--prod-root') ?? process.env.DSH_ROOT ?? path.join(os.homedir(), 'DSH'));
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts']);
+
+if (!since && !filesArg) {
+  console.error('用法：node scripts/sim-selfcheck.mjs --since <commit> | --files <a.js,b.js> [--repo <dir>] [--prod-root <dir>] [--json]');
+  process.exit(2);
+}
+
+const kebab = (p) => p.replace(/\\/g, '/');
+
+/** 取新增文件清单（相对仓根） */
+function newFiles() {
+  if (filesArg) {
+    return filesArg.split(',').map((s) => s.trim()).filter(Boolean).map((p) => path.resolve(REPO, p));
+  }
+  const r = spawnSync('git', ['-C', REPO, 'diff', '--name-only', '--diff-filter=A', `${since}..HEAD`, '--', '*.js', '*.mjs', '*.cjs'], { encoding: 'utf8' });
+  if (r.status !== 0) {
+    console.error('git diff 失败：' + (r.stderr || '').trim());
+    process.exit(2);
+  }
+  return r.stdout.split(/\r?\n/).filter(Boolean).map((p) => path.join(REPO, p));
+}
+
+/** 非空行（去掉首尾空白；纯分隔符行不算内容 —— 否则 `}` / `);` 会把同源度凭空抬上去） */
+function codeLines(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  return text.split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !/^[{}()[\];,]+$/.test(l));
+}
+
+/** 多重集扣减：返回 ref 里有多少条能在 target 里找到 */
+function matchedCount(refLines, targetCounts) {
+  const pool = new Map(targetCounts);
+  let hit = 0;
+  for (const line of refLines) {
+    const left = pool.get(line) ?? 0;
+    if (left > 0) { pool.set(line, left - 1); hit += 1; }
+  }
+  return hit;
+}
+
+function countsOf(lines) {
+  const m = new Map();
+  for (const l of lines) m.set(l, (m.get(l) ?? 0) + 1);
+  return m;
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '_archive', 'logs', 'backups', 'snapshots', 'generated', '_tmp', 'docs', 'dist']);
+/** 受限遍历：生产源只找同名件，所以按 basename 索引即可（跳过重目录） */
+function indexByBasename(root, wantedNames) {
+  const found = new Map();
+  const stack = [[root, 0]];
+  while (stack.length) {
+    const [dir, depth] = stack.pop();
+    if (depth > 7) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+        stack.push([full, depth + 1]);
+      } else if (e.isFile() && wantedNames.has(e.name)) {
+        if (!found.has(e.name)) found.set(e.name, []);
+        found.get(e.name).push(full);
+      }
+    }
+  }
+  return found;
+}
+
+const targets = newFiles().filter((f) => fs.existsSync(f) && CODE_EXT.has(path.extname(f)));
+if (targets.length === 0) {
+  console.error('没有找到新增的代码文件（--since 给的 commit 之后没有新增 .js/.mjs？）');
+  process.exit(2);
+}
+
+// 参照件：生产源同名件 + 本仓其它已有件
+const wanted = new Set(targets.map((f) => path.basename(f)));
+const prodIndex = fs.existsSync(prodRoot) ? indexByBasename(prodRoot, wanted) : new Map();
+const repoRefs = [];
+{
+  const stack = [[REPO, 0]];
+  while (stack.length) {
+    const [dir, depth] = stack.pop();
+    if (depth > 5) continue;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (['node_modules', '.git', '_archive', '_tmp'].includes(e.name) || e.name.startsWith('.')) continue;
+        stack.push([full, depth + 1]);
+      } else if (e.isFile() && CODE_EXT.has(path.extname(e.name)) && !targets.includes(full)) {
+        repoRefs.push(full);
+      }
+    }
+  }
+}
+
+const refLinesCache = new Map();
+const linesOf = (p) => {
+  if (!refLinesCache.has(p)) refLinesCache.set(p, codeLines(p));
+  return refLinesCache.get(p);
+};
+
+const results = targets.map((file) => {
+  const lines = codeLines(file);
+  const own = countsOf(lines);
+  const candidates = [];
+  for (const p of prodIndex.get(path.basename(file)) ?? []) {
+    candidates.push({ file: p, kind: 'prod-same-name', label: kebab(path.relative(prodRoot, p)) });
+  }
+  for (const p of repoRefs) {
+    candidates.push({ file: p, kind: 'repo-existing', label: kebab(path.relative(REPO, p)) });
+  }
+  let best = { file: null, kind: null, label: '-', ratio: 0, matched: 0 };
+  for (const c of candidates) {
+    const ref = linesOf(c.file);
+    const matched = matchedCount(ref, own);
+    const ratio = lines.length === 0 ? 0 : matched / lines.length;
+    if (ratio > best.ratio) best = { ...c, ratio, matched };
+  }
+  return {
+    file: kebab(path.relative(REPO, file)),
+    lines: lines.length,
+    matched: best.matched,
+    ratio: Math.round(best.ratio * 1000) / 1000,
+    percent: Math.round(best.ratio * 1000) / 10,
+    bestRef: best.label,
+    bestRefKind: best.kind,
+    hasProdSameName: (prodIndex.get(path.basename(file)) ?? []).length > 0,
+    pass: best.ratio < 0.5
+  };
+});
+
+if (asJson) {
+  console.log(JSON.stringify({ repo: REPO, prodRoot, caliber: '非空行多重集扣减 / 每文件取最高参照件', results }, null, 2));
+} else {
+  console.log('同源度自查（行级）：' + kebab(REPO));
+  console.log('  口径：分子 = 新文件里能在参照件（生产同名件 ∪ 本仓既有件）找到的非空行数；分母 = 新文件非空行数');
+  console.log('  判据：< 50% 通过（新文件不许拿本仓既有近源件当模板）\n');
+  const pad = (s, n) => String(s).padEnd(n);
+  console.log('  ' + pad('文件', 30) + pad('行数', 7) + pad('同源行', 8) + pad('同源度', 9) + pad('参照', 34) + '结论');
+  for (const r of results) {
+    console.log('  ' + pad(r.file, 30) + pad(r.lines, 7) + pad(r.matched, 8) + pad(r.percent + '%', 9)
+      + pad((r.bestRefKind === 'prod-same-name' ? '[生产同名] ' : '[仓内既有] ') + (r.bestRef ?? '-'), 34)
+      + (r.pass ? 'OK' : '🔴 超线'));
+  }
+  const bad = results.filter((r) => !r.pass);
+  console.log('\n  主结论：' + results.length + ' 个新文件，' + (results.length - bad.length) + ' 个 < 50%'
+    + (bad.length ? '，' + bad.length + ' 个 ≥ 50%（这条硬约束没过）' : '（全部通过）'));
+}
+
+process.exitCode = results.every((r) => r.pass) ? 0 : 1;

package/scripts/test-degrade.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// scripts/test-degrade.mjs —— 夹具④：分片 + 超时预算 + 局部降级
+//
+// 一键跑：node scripts/test-degrade.mjs
+// 退出码：0 = 全通过；1 = 有失败项。
+//
+// 三段：
+//   [A] 车道：快源 / 慢源（超时）/ 抛错源 / 未配置源 同时读 ⇒ 只有坏的降级，总耗时不被慢源拖爆
+//   [B] 总预算：整页预算比单源超时更小时 ⇒ 报「总预算耗尽」，而不是无限等
+//   [C] 面板整屏：坏源只坏那一格（那一组多一行「不可探测 + 原因」），其余组照常出、state.ok 仍为 true
+//
+// ⚠️ 夹具隔离三件套：USERPROFILE + HOME + DSH_HOME（另加本插件自己的 HOME 覆盖）。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+let pass = 0;
+let fail = 0;
+const ok = (name, cond, detail = '') => {
+  if (cond) { pass += 1; console.log('[OK]   ' + name + (detail ? ' :: ' + detail : '')); }
+  else { fail += 1; console.log('[FAIL] ' + name + (detail ? ' :: ' + detail : '')); }
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------- 沙箱 + 三件套隔离
+const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'panel-degrade-'));
+const home = path.join(sandbox, 'home');
+fs.mkdirSync(path.join(home, 'profiles', 'web'), { recursive: true });
+for (const name of ['skill-a', 'skill-b']) {
+  fs.mkdirSync(path.join(home, 'skills', name), { recursive: true });
+  fs.writeFileSync(path.join(home, 'skills', name, 'SKILL.md'), `---\n{"name":"${name}","description":"夹具技能"}\n---\n`, 'utf8');
+}
+fs.writeFileSync(path.join(home, 'profiles', 'web', 'package.json'), JSON.stringify({ name: 'fixture-profile', dsh: { profile: { bundles: [] } } }), 'utf8');
+
+process.env.USERPROFILE = home;
+process.env.HOME = home;
+process.env.DSH_HOME = home;
+process.env.DSH_ECOSYSTEM_PANEL_HOME = home;
+
+const { createLane, REASON } = await import(pathToFileURL(path.join(ROOT, 'lib', 'fetch-lane.js')).href);
+const stateMod = await import(pathToFileURL(path.join(ROOT, 'lib', 'state.js')).href);
+
+console.log('=== [A] 车道：一个快、一个慢、一个抛错、一个未配置 ===');
+const lane = createLane({
+  totalBudgetMs: 600,
+  sources: [
+    { id: 'fast', label: '快源', run: async () => ({ ok: 1 }) },
+    { id: 'slow', label: '慢源', timeoutMs: 60, run: async () => { await sleep(400); return { ok: 'late' }; } },
+    { id: 'boom', label: '抛错源', run: async () => { throw new Error('上游 503'); } },
+    { id: 'gate', label: '未配置源', requires: () => '夹具：这个源没配置（示范第三种原因）', run: async () => ({ ok: 'nope' }) }
+  ]
+});
+const t0 = Date.now();
+const readAll = await lane.readAll(['fast', 'slow', 'boom', 'gate'], {});
+const wall = Date.now() - t0;
+const r = readAll.byId;
+ok('快源照常出', r.fast.status === 'cold' && r.fast.value?.ok === 1, `${r.fast.status}`);
+ok('慢源超时 ⇒ 降级，原因写「超时」', r.slow.status === 'degraded' && r.slow.reason === REASON.TIMEOUT,
+  `${r.slow.status}/${r.slow.reason}（${r.slow.detail}）`);
+ok('抛错源 ⇒ 降级，原因写「报错」+ 上游原话', r.boom.status === 'degraded' && r.boom.reason === REASON.ERROR
+  && /上游 503/.test(String(r.boom.detail)), `${r.boom.reason}（${r.boom.detail}）`);
+ok('未配置源 ⇒ 降级，原因写「未配置」，且根本没发生取数',
+  r.gate.status === 'degraded' && r.gate.reason === REASON.NOT_CONFIGURED
+  && lane.sli().sources.gate.fetches === 0, `${r.gate.reason}（${r.gate.detail}）`);
+ok('整页总耗时没被慢源拖爆（慢源要 400 ms，实际 < 150 ms）', wall < 150, `${wall} ms`);
+ok('降级计数按源分开记', lane.sli().sources.slow.degraded === 1 && lane.sli().sources.fast.degraded === 0,
+  JSON.stringify({ slow: lane.sli().sources.slow.degraded, fast: lane.sli().sources.fast.degraded }));
+ok('降级不影响下一次读（快源仍是真值）', (await lane.read('fast')).status === 'fresh');
+
+console.log('\n=== [B] 总预算：预算比单源超时还紧时，报「总预算耗尽」而不是无限等 ===');
+const tight = createLane({
+  totalBudgetMs: 40,
+  sources: [{ id: 'slowpoke', label: '超慢源', timeoutMs: 5000, run: async () => { await sleep(300); return { ok: 1 }; } }]
+});
+const t1 = Date.now();
+const tiny = await tight.readAll(['slowpoke'], {});
+const tightWall = Date.now() - t1;
+ok('预算耗尽 ⇒ 降级，原因写「总预算耗尽」', tiny.byId.slowpoke.status === 'degraded'
+  && tiny.byId.slowpoke.reason === REASON.BUDGET, `${tiny.byId.slowpoke.reason}`);
+ok('确实按预算掐断（< 120 ms 就返回）', tightWall < 120, `${tightWall} ms`);
+
+console.log('\n=== [C] 面板整屏：坏的只坏那一格，其余照出 ===');
+// 现场注册两个坏源：一个抛错、一个超时（都落在「补丁健康」这一组里）
+stateMod.registerSource({
+  id: 'probe-boom',
+  label: '夹具抛错源',
+  group: 'patches',
+  run: async () => { throw new Error('夹具：读不到上游'); },
+  describe: () => ({ rows: [] })
+});
+stateMod.registerSource({
+  id: 'probe-slow',
+  label: '夹具超时源',
+  group: 'patches',
+  timeoutMs: 60,
+  run: async () => { await sleep(500); return { ok: 1 }; },
+  describe: () => ({ rows: [] })
+});
+stateMod.resetLanes();
+const st = await stateMod.buildState({ config: { home, profile: 'web', webUrl: 'http://127.0.0.1:1' } });
+const patchRows = st.groups.patches;
+const boomRow = patchRows.find((x) => x.name === '夹具抛错源');
+const slowRow = patchRows.find((x) => x.name === '夹具超时源');
+ok('整页仍然成功返回（state.ok=true）', st.ok === true);
+ok('坏源只在自己的组里多一行「不可探测」', patchRows.length >= 3 && !!boomRow && !!slowRow,
+  `${patchRows.length} 行`);
+ok('抛错那一格：不可探测 + 报错原因', /不可探测：报错/.test(boomRow.problems.join(' ')), boomRow.problems.join(' '));
+ok('超时那一格：不可探测 + 超时原因', /不可探测：超时/.test(slowRow.problems.join(' ')), slowRow.problems.join(' '));
+ok('其它组照常出（技能两条照出、跨表准入那格仍在）',
+  st.groups.skills.length === 2 && st.groups.registry.length === 1,
+  `skills=${st.groups.skills.length} registry=${st.groups.registry.length}`);
+ok('正常源没被连坐（技能两条都是真值不是降级行）',
+  st.groups.skills.every((s) => s.kind === 'skill' && !/不可探测/.test((s.problems ?? []).join(' '))));
+ok('页脚 SLI 里降级事件逐条可点（id + 原因）',
+  st.sli.degradeEvents.length === 2 && st.sli.degradeEvents.every((e) => e.id && e.reason),
+  JSON.stringify(st.sli.degradeEvents));
+ok('坏源没有让整页多等：超时那格按 60 ms 掐断（不是等满 500 ms）',
+  (st.sli.request.sources.find((s) => s.id === 'probe-slow')?.elapsedMs ?? 9999) < 200,
+  `probe-slow elapsed=${st.sli.request.sources.find((s) => s.id === 'probe-slow')?.elapsedMs} ms`);
+ok('每一步都留了单源耗时（降级那格也有）',
+  st.sli.request.sources.filter((s) => s.status === 'degraded').every((s) => typeof s.elapsedMs === 'number'));
+
+stateMod.resetSources();
+fs.rmSync(sandbox, { recursive: true, force: true });
+console.log(`\n=== 结果：通过 ${pass} / 失败 ${fail} ===`);
+console.log(fail === 0 ? 'DEGRADE FIXTURE PASSED' : 'DEGRADE FIXTURE FAILED');
+process.exitCode = fail === 0 ? 0 : 1;

package/scripts/test-fixture.mjs

@@ -127,6 +127,10 @@ process.stdin.on('end', () => {
 // ---------------------------------------------------------------- 载入被测模块
 // ⚠️ 必须在 import 之前设好数据根：lib/state.js 的 YAML 依赖是在**模块加载期**经
 //    createRequire(<数据根>/profiles/<profile>/package.json) 解析的。
+// ⚠️ 夹具隔离三件套：USERPROFILE + HOME + DSH_HOME 一起指向沙箱（少一个就可能"写沙箱、发生产"）。
+process.env.USERPROFILE = sandbox;
+process.env.HOME = sandbox;
+process.env.DSH_HOME = sandbox;
 process.env.DSH_ECOSYSTEM_PANEL_HOME = home;
 const stateMod = await import(pathToFileURL(path.join(ROOT, 'lib', 'state.js')).href);
 ok('YAML 依赖在夹具数据根上解析成功（模块加载期）', stateMod.YAML_AVAILABLE === true, String(stateMod.YAML_ERROR ?? ''));
@@ -242,7 +246,28 @@ ok('停用组显示为「已按配置停用」提示项', s3.groups.patches.leng
 ok('停用组不计入 summary.total', s3.summary.total === s1.summary.total - 3, `${s3.summary.total} vs ${s1.summary.total}`);
 ok('停用组仍如实报出配置值', JSON.stringify(s3.meta.disabledGroups) === '["patches"]', JSON.stringify(s3.meta.disabledGroups));
 
-// ---------------------------------------------------------------- [4] 沙箱清理
+// ---------------------------------------------------------------- [4] boot 清单 401 ⇒ 判"未知"
+// 需要 token 的实例（`/?token=…`）会对服务端的无 cookie 抓取回 401，正文是 "authentication required"。
+// 这类响应**必须**当成"抓不到"（ids=null = 未知），不许当成"清单里 0 条"——后者会让每一行插件
+// 都报「boot 无 client 条目（疑似未加载/崩溃）」，纯属误报（隔离实例上实测踩到）。
+console.log('\n=== [4] boot 清单 HTTP 401 ⇒ 判「未知」，不许当成「未加载」 ===');
+const http = await import('node:http');
+const stub = http.createServer((req, res) => {
+  res.writeHead(401, { 'content-type': 'text/plain; charset=utf-8' });
+  res.end('dsh web authentication required: reopen the URL printed by dsh web.');
+});
+await new Promise((resolve) => stub.listen(0, '127.0.0.1', resolve));
+const stubUrl = `http://127.0.0.1:${stub.address().port}`;
+const s4 = await stateMod.buildState({ config: { ...baseCfg, webUrl: stubUrl } });
+await new Promise((resolve) => stub.close(resolve));
+ok('401 时 bootEntries = null（未知，不是「0 条」）', s4.meta.bootEntries === null, String(s4.meta.bootEntries));
+ok('401 被如实记进 bootError', /HTTP 401/.test(String(s4.meta.bootError)), String(s4.meta.bootError));
+const exRow4 = s4.groups.bundles.find((b) => b.name === 'example-plugin');
+ok('插件行退为「加载状态未知」（黄），不是「无 boot 条目」误报',
+  exRow4?.bootLoaded === null && /加载状态未知/.test((exRow4?.problems ?? []).join(' ')),
+  JSON.stringify(exRow4?.problems));
+
+// ---------------------------------------------------------------- [5] 沙箱清理
 try { fs.rmSync(sandbox, { recursive: true, force: true }); } catch { /* ignore */ }
 ok('夹具沙箱已清理', !fs.existsSync(sandbox));
 

package/scripts/test-singleflight.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// scripts/test-singleflight.mjs —— 夹具③：单飞（同一源同一时刻只有一次在途取数）
+//
+// 一键跑：node scripts/test-singleflight.mjs
+// 退出码：0 = 全通过；1 = 有失败项。
+//
+// 要证明的两件事：
+//   [A] 冷启动时 N 个并发请求打同一个源 ⇒ 源侧只被调用 **1 次**，N 个请求共享同一次结果
+//   [B] 过期（旧值在手）时 N 个并发请求 ⇒ 后台刷新也只发 **1 次**，不是每个请求各刷一遍
+// 反例（如果不做单飞）：10 个页面同时打开 = 源被打 10 次 —— 这正是"面板把源打爆"的现场。
+//
+// ⚠️ 夹具隔离三件套：USERPROFILE + HOME + DSH_HOME。
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+let pass = 0;
+let fail = 0;
+const ok = (name, cond, detail = '') => {
+  if (cond) { pass += 1; console.log('[OK]   ' + name + (detail ? ' :: ' + detail : '')); }
+  else { fail += 1; console.log('[FAIL] ' + name + (detail ? ' :: ' + detail : '')); }
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'panel-singleflight-'));
+process.env.USERPROFILE = sandbox;
+process.env.HOME = sandbox;
+process.env.DSH_HOME = sandbox;
+process.env.DSH_ECOSYSTEM_PANEL_HOME = sandbox;
+
+const { createLane } = await import(pathToFileURL(path.join(ROOT, 'lib', 'fetch-lane.js')).href);
+
+let clock = Date.now();
+let calls = 0;
+const RTT = 80;
+const lane = createLane({
+  ttlMs: 500,
+  totalBudgetMs: 3000,
+  now: () => clock,
+  sources: [{
+    id: 'one-source',
+    label: '单飞探针',
+    async run() {
+      calls += 1;
+      const n = calls;
+      await sleep(RTT);          // 模拟一次真实的慢取数
+      return { n };
+    }
+  }]
+});
+
+console.log('=== [A] 冷启动：10 个并发请求打同一个源 ===');
+const t0 = Date.now();
+const burst = await Promise.all(Array.from({ length: 10 }, () => lane.read('one-source')));
+const wall = Date.now() - t0;
+ok('10 个请求全部拿到值', burst.every((r) => r.value?.n === 1), JSON.stringify(burst.map((r) => r.value?.n)));
+ok('源侧只被调用 1 次（单飞生效）', calls === 1, `calls=${calls}`);
+ok('10 个请求共享同一次取数（耗时 ≈ 一次 RTT，不是 10 次）', wall >= RTT && wall < RTT * 3, `${wall} ms / RTT=${RTT} ms`);
+ok('SLI 里也只有 1 次外部取数', lane.sli().sources['one-source'].fetches === 1,
+  String(lane.sli().sources['one-source'].fetches));
+ok('计数口径如实：10 个冷启动请求各记一次 coldMiss，但外部只取 1 次（不拿"命中"骗读数）',
+  lane.sli().totals.coldMiss === 10 && lane.sli().sources['one-source'].fetches === 1,
+  JSON.stringify({ coldMiss: lane.sli().totals.coldMiss, fetches: lane.sli().sources['one-source'].fetches }));
+
+console.log('\n=== [B] 过期：手持旧值时 8 个并发请求 ===');
+clock += 520;                    // 让缓存过期（ttlMs=500）
+const t1 = Date.now();
+const staleBurst = await Promise.all(Array.from({ length: 8 }, () => lane.read('one-source')));
+const staleWall = Date.now() - t1;
+ok('8 个请求都先拿到旧值（stale，不阻塞）', staleBurst.every((r) => r.status === 'stale' && r.value?.n === 1),
+  staleBurst.map((r) => r.status).join(','));
+ok('过期那一屏几乎不花时间（没等后台刷新）', staleWall < 40, `${staleWall} ms`);
+await sleep(RTT + 60);
+await lane.settle();
+ok('后台刷新只发了 1 次（8 个请求共享同一次刷新）', calls === 2, `calls=${calls}`);
+ok('SLI：过期读记成 8 次未命中，但外部取数只多 1 次',
+  lane.sli().totals.miss === 8 && lane.sli().sources['one-source'].fetches === 2,
+  JSON.stringify({ miss: lane.sli().totals.miss, fetches: lane.sli().sources['one-source'].fetches }));
+const after = await lane.read('one-source');
+ok('刷完后新值就位', after.status === 'fresh' && after.value?.n === 2, `${after.status} / n=${after.value?.n}`);
+
+fs.rmSync(sandbox, { recursive: true, force: true });
+console.log(`\n=== 结果：通过 ${pass} / 失败 ${fail} ===`);
+console.log(fail === 0 ? 'SINGLE-FLIGHT FIXTURE PASSED' : 'SINGLE-FLIGHT FIXTURE FAILED');
+process.exitCode = fail === 0 ? 0 : 1;