zipcalm 0.0.0-stage → 1.0.2

package/server/core/hardlink/executor.js

@@ -0,0 +1,106 @@
+// 硬链接去重 · 执行器（docs/15 §三.执行：替换顺序是安全核心）
+//
+// 替换顺序（每个副本，三步，绝不能"先删后建"）：
+//   1. rename(副本, 副本 + '.hl-tmp-<随机>')   // 旧副本挪走，原名腾出
+//   2. link(主文件, 副本)                       // 硬链接占住原名
+//   3. unlink(临时名)                           // 删掉旧副本
+// 最坏情况只留一个 .hl-tmp-* 临时文件，**数据始终有一份可达**（崩溃在任意一步都不会丢）。
+//
+// 错误捕获（docs/15）：EXDEV（跨 fs）/ EEXIST（目标已存在）/ EPERM（权限）/ ENOSPC。
+// 失败单条隔离（不整批崩），全部落日志 storage/logs/hardlink-<yyyymmdd>.jsonl。
+//
+// 主文件选择：scan 结果里的 master（组内第一个）——execute 只信任 scan 产出的分组，
+// 且执行前逐对复核「主副内容仍一致」（文件可能自扫描后被改动：复核走全量哈希，
+// 失败该组跳过——判定信息过期绝不硬链）。
+
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { fullHash } from './scanner.js';
+
+/** 单条执行日志（jsonl 一行） */
+async function recordLog(ctx, entry) {
+  const now = new Date();
+  const name = `hardlink-${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}.jsonl`;
+  const file = path.join(ctx.logDir, name);
+  try {
+    await fsp.mkdir(ctx.logDir, { recursive: true });
+    await fsp.appendFile(file, `${JSON.stringify({ at: Date.now(), ...entry })}\n`, 'utf8');
+  } catch (error) {
+    ctx.logger.error('硬链接日志写入失败', { error: error.message });
+  }
+}
+
+/** 执行前复核：主副全量哈希仍一致（扫描到执行之间文件可能变化） */
+async function verifyPairStillIdentical(masterAbs, duplicateAbs) {
+  const [masterHash, duplicateHash] = await Promise.all([fullHash(masterAbs), fullHash(duplicateAbs)]);
+  return masterHash === duplicateHash;
+}
+
+/** 对单个副本执行三步替换；抛错由调用方按单条隔离 */
+async function replaceWithLink(masterAbs, duplicateAbs) {
+  const tmpPath = `${duplicateAbs}.hl-tmp-${crypto.randomBytes(4).toString('hex')}`;
+  // 1. 旧副本挪走（原名腾出）
+  await fsp.rename(duplicateAbs, tmpPath);
+  try {
+    // 2. 硬链接占住原名（此刻起原名与主文件同一份数据）
+    await fsp.link(masterAbs, duplicateAbs);
+  } catch (error) {
+    // 链接失败：把旧副本挪回原位（回滚第 1 步），数据无损
+    await fsp.rename(tmpPath, duplicateAbs).catch(() => {});
+    throw error;
+  }
+  // 3. 删掉旧副本（此刻安全：原名已由链接保证可达）
+  await fsp.unlink(tmpPath);
+}
+
+/**
+ * 执行硬链接去重。
+ * @param {object} ctx {logDir, logger, dryRunGuard}
+ * @param {Array<{size, master: string(absPath), duplicates: string[](absPath)}> } groups 已复核的分组（absPath 坐标系，调用方负责白名单）
+ * @param {object} options {confirmed: boolean} 必须显式 true
+ * @returns {Promise<{executed: number, failed: Array<{duplicate, code}>, skippedGroups: Array<{master, reason}>, savedBytes: number}>}
+ */
+export async function executeHardlinkGroups(ctx, groups, options = {}) {
+  if (options.confirmed !== true) {
+    const error = new Error('执行需要显式确认（confirmed=true）');
+    error.code = 'INVALID_STATE';
+    throw error;
+  }
+
+  const execReport = { executed: 0, failed: [], skippedGroups: [], savedBytes: 0 };
+
+  for (const group of groups || []) {
+    const { master, duplicates, size } = group;
+    // 执行前逐对复核：扫描后文件可能已改动，判定信息过期绝不硬链
+    let allStillIdentical = true;
+    for (const duplicate of duplicates) {
+      const identical = await verifyPairStillIdentical(master, duplicate).catch(() => false);
+      if (!identical) {
+        allStillIdentical = false;
+        execReport.skippedGroups.push({ master, reason: 'content_changed_since_scan' });
+        await recordLog(ctx, { action: 'skipped', master, duplicate, reason: 'content_changed_since_scan' });
+        break;
+      }
+    }
+    if (!allStillIdentical) continue;
+
+    for (const duplicate of duplicates) {
+      try {
+        await replaceWithLink(master, duplicate);
+        execReport.executed += 1;
+        execReport.savedBytes += size;
+        await recordLog(ctx, { action: 'linked', master, duplicate, sizeBytes: size, result: 'ok' });
+        ctx.logger.info('硬链接替换完成', { master, duplicate });
+      } catch (error) {
+        const code = error && error.code ? error.code : 'INTERNAL_ERROR';
+        execReport.failed.push({ duplicate, code });
+        await recordLog(ctx, { action: 'failed', master, duplicate, result: 'failed', errorCode: code });
+        ctx.logger.error('硬链接替换失败', { master, duplicate, code });
+      }
+    }
+  }
+
+  return execReport;
+}

package/server/core/hardlink/scanner.js

@@ -0,0 +1,193 @@
+// 硬链接去重 · 扫描器（docs/15 §三：size 分组 → 抽样快筛 → 全量哈希终判）
+//
+// 评审教训（docs/15 §二.①，本模块的实现红线）：
+//   **抽样哈希不能判定重复**——同系列视频（S01E01/S01E02）容器头一致、索引尾也常一致，
+//   中间内容完全不同。抽样若被当终判，合并后其中一集内容永久消失。
+//   所以抽样只做「快速筛」（排除明显不同的，减少全量哈希的量），**终判必须全量 SHA-256**。
+//
+// 跳过规则（docs/15 §三.扫描）：
+//   - 符号链接（lstat 不跟随）
+//   - 已有硬链接的文件（nlink > 1：已是链接副本，再链无收益且语义混乱）
+//   - 跨文件系统条目（dev 与扫描根不同：硬链接的硬限制，链不起来）
+//   - 非白名单扩展名
+//
+// 结果：只报告组内 ≥ 2 的分组；每组带 master（组内第一个）与 duplicates；dry-run 不动任何文件。
+
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/** 抽样快筛的段配置：头 / 尾各 4KB + 中间随机 2 段（docs/15 §二.① 正确做法 2） */
+const SAMPLE_CHUNK = 4096;
+const SAMPLE_MID_SEGMENTS = 2;
+
+/** 全量哈希的块大小（流式读，4MB 平衡内存与 syscalls） */
+const HASH_CHUNK = 4 * 1024 * 1024;
+
+/** 判断扩展名是否在白名单（大小写不敏感；extensions 形如 ['mp4','mkv'] 不带点） */
+export function isAllowedExtension(fileName, extensions) {
+  const ext = path.extname(fileName).replace(/^\./, '').toLowerCase();
+  return extensions.includes(ext);
+}
+
+/** 递归遍历（自写不复用 sourceWalk：这里要带 dev/nlink 跳过规则与扩展名过滤） */
+export async function walkCandidates(rootAbs, extensions, options = {}) {
+  const { onProgress } = options;
+  const rootStat = await fsp.stat(rootAbs); // stat：扫描根自身允许是链接后的目录
+  const candidates = [];
+  let scanned = 0;
+
+  const walk = async (dirAbs) => {
+    let dirents;
+    try {
+      dirents = await fsp.readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return; // 读不到的子树跳过（权限），与项目其他遍历的容错口径一致
+    }
+    for (const dirent of dirents) {
+      const childAbs = path.join(dirAbs, dirent.name);
+      // 只用 lstat 信息判断目录（不跟随链接目录，防环）；isSymbolicLink 一律跳过
+      if (dirent.isDirectory()) {
+        await walk(childAbs);
+        continue;
+      }
+      if (!dirent.isFile()) continue; // symlink / 设备 / fifo：不进候选
+      if (!isAllowedExtension(dirent.name, extensions)) continue;
+      const stat = await fsp.lstat(childAbs).catch(() => null);
+      if (!stat || !stat.isFile()) continue;
+      // 已有硬链接的文件跳过（nlink > 1：已经是某个"去重"的产物或副本）
+      if (stat.nlink > 1) continue;
+      // 跨文件系统跳过（dev 不同：link() 会 EXDEV，链不起来）
+      if (stat.dev !== rootStat.dev) continue;
+      scanned += 1; // 语义 = 通过全部跳过规则、进入候选清单的数量（过滤前计数会虚高，实测踩过）
+      candidates.push({ absPath: childAbs, size: stat.size, dev: stat.dev, ino: stat.ino });
+      if (onProgress && scanned % 100 === 0) onProgress({ scanned, currentFile: childAbs });
+    }
+  };
+
+  await walk(rootAbs);
+  return { candidates, scanned, rootDev: rootStat.dev };
+}
+
+/** 按 size 分组，只留 ≥2 的组（零成本先砍掉绝大部分候选） */
+export function groupBySize(candidates) {
+  const bySize = new Map();
+  for (const candidate of candidates) {
+    if (!bySize.has(candidate.size)) bySize.set(candidate.size, []);
+    bySize.get(candidate.size).push(candidate);
+  }
+  return [...bySize.entries()]
+    .filter(([, group]) => group.length >= 2)
+    .map(([size, group]) => ({ size, group }));
+}
+
+/**
+ * 流式读取文件的抽样段：头 4KB + 尾 4KB + 中间随机 2 段（各 4KB）。
+ * 返回这些段的 sha256 串联指纹——**仅用于快速筛**，不是重复判定。
+ */
+async function sampleFingerprint(absPath, size) {
+  const hash = crypto.createHash('sha256');
+  const handle = await fsp.open(absPath, 'r');
+  try {
+    const read = async (position) => {
+      const buffer = Buffer.alloc(SAMPLE_CHUNK);
+      const { bytesRead } = await handle.read(buffer, 0, SAMPLE_CHUNK, position);
+      hash.update(buffer.subarray(0, bytesRead));
+    };
+    await read(0);
+    if (size > SAMPLE_CHUNK) await read(size - SAMPLE_CHUNK);
+    if (size > SAMPLE_CHUNK * 3) {
+      // 中间段偏移必须**确定性**（从 size 派生，禁止 Math.random）——
+      // 抽样快筛的指纹只在「同一位置读出的段」之间可比：相同文件必须读相同段才能同指纹。
+      // 实测踩过：随机偏移让两个内容相同的文件读到不同位置 → 指纹必不同 → 真重复被快筛
+      // 排除（端到端冒烟抓到：real1/real2 全同却 skippedBySample）。确定性偏移同样满足
+      // docs/15 的"防恰好都取到相同结构区"意图（位置由 size 变化，不同 size 组内不重叠）。
+      const span = size - SAMPLE_CHUNK * 3;
+      for (let i = 0; i < SAMPLE_MID_SEGMENTS; i += 1) {
+        const pos = SAMPLE_CHUNK + Math.floor((span / (SAMPLE_MID_SEGMENTS + 1)) * (i + 1)) + i * 1024;
+        await read(Math.min(pos, size - SAMPLE_CHUNK));
+      }
+    }
+  } finally {
+    await handle.close();
+  }
+  return hash.digest('hex');
+}
+
+/** 全量 SHA-256（终判）：流式读，4MB 块 */
+export async function fullHash(absPath) {
+  const hash = crypto.createHash('sha256');
+  const handle = await fsp.open(absPath, 'r');
+  try {
+    const buffer = Buffer.alloc(HASH_CHUNK);
+    for (;;) {
+      const { bytesRead } = await handle.read(buffer, 0, HASH_CHUNK, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+  } finally {
+    await handle.close();
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * 扫描主流程：walk → size 分组 → 抽样快筛 → 全量哈希终判。
+ *
+ * @param {string} rootAbs 扫描根（绝对路径，调用方已过白名单）
+ * @param {string[]} extensions 白名单扩展名（不带点）
+ * @param {object} [options] { onProgress({stage, scanned, hashed, total}) }
+ * @returns {Promise<{groups: Array<{size, hash, master, duplicates, savedBytes}>, stats: {...}}>}
+ */
+export async function scanHardlinkDuplicates(rootAbs, extensions, options = {}) {
+  const { onProgress } = options;
+  const { candidates, scanned, rootDev } = await walkCandidates(rootAbs, extensions, { onProgress });
+
+  const groups = [];
+  let hashed = 0;
+  let skippedBySample = 0;
+
+  for (const { size, group } of groupBySize(candidates)) {
+    // 抽样快筛：指纹相同的才进全量哈希（不同 → 直接排除，省全量读）
+    const fingerprints = new Map();
+    for (const candidate of group) {
+      const fp = await sampleFingerprint(candidate.absPath, size);
+      if (!fingerprints.has(fp)) fingerprints.set(fp, []);
+      fingerprints.get(fp).push(candidate);
+      hashed += 1;
+    }
+    for (const fpGroup of fingerprints.values()) {
+      if (fpGroup.length < 2) {
+        skippedBySample += fpGroup.length;
+        continue;
+      }
+      // 全量哈希终判（评审红线：抽样不能判重复）
+      const hashes = new Map();
+      for (const candidate of fpGroup) {
+        const digest = await fullHash(candidate.absPath);
+        if (!hashes.has(digest)) hashes.set(digest, []);
+        hashes.get(digest).push(candidate);
+      }
+      for (const [digest, digestGroup] of hashes.entries()) {
+        if (digestGroup.length < 2) continue; // 抽样同但全量不同：终判正确排除（伪造重复守门人覆盖此路径）
+        // 主文件确定规则：**absPath 字典序最小**（docs/15 执行前评审补充）——同一批数据
+        // 重扫时组内顺序稳定，master 可复现；不按 mtime（会因访问/复制变化不可复现）
+        digestGroup.sort((a, b) => (a.absPath < b.absPath ? -1 : a.absPath > b.absPath ? 1 : 0));
+        const [master, ...duplicates] = digestGroup;
+        groups.push({
+          size,
+          hash: digest,
+          master: master.absPath,
+          duplicates: duplicates.map((d) => d.absPath),
+          savedBytes: size * duplicates.length,
+        });
+      }
+    }
+    if (onProgress) onProgress({ stage: 'group-done', scanned, hashed });
+  }
+
+  return {
+    groups,
+    stats: { scanned, hashed, skippedBySample, rootDev, groupCount: groups.length, savedBytes: groups.reduce((sum, g) => sum + g.savedBytes, 0) },
+  };
+}

package/server/core/metrics/collector.js

@@ -0,0 +1,279 @@
+// 性能指标采集（M7）：/proc 系统指标 5s + 进程指标 1s → 5 分钟环形缓冲
+//
+// 契约：
+// - docs/M0/API规范.md §4.6：snapshot 的字段集合（system / process / tasks），history 的 window/step
+// - docs/07 §二 采集频率：系统 5s、进程 1s、前端 2s 轮询；§四 只允许这 6 张卡片对应的字段
+// - 依赖策略（lead 拍板）：**不引 systeminformation**，全部 Node 内置 + /proc（见 procfs.js 头部）
+//
+// 三条硬约束（lead 验收项，改代码时别丢）：
+// 1. 定时器必须 unref()，并在 stop() 里清掉 —— 否则优雅关闭会被这两个定时器拖住；
+// 2. 任何采集失败都降级为 null/0，**绝不向外抛**（定时器里的未捕获异常会把整个服务带走）；
+// 3. 环形缓冲只保留最近 5 分钟，不做持久化。
+
+import os from 'node:os';
+import { performance } from 'node:perf_hooks';
+
+import { readProcSnapshot, sectorsToBytes } from './procfs.js';
+
+/** 采集频率（契约 docs/07 §二，不开放配置 —— 契约写死，避免"配了但没人读"的死配置） */
+const SYSTEM_INTERVAL_MS = 5000;
+/** 进程指标节奏，同时也是环形缓冲的帧间隔 */
+const PROCESS_INTERVAL_MS = 1000;
+/** 环形缓冲覆盖的时长与上限帧数（5 分钟 / 1s） */
+const HISTORY_WINDOW_MS = 5 * 60 * 1000;
+const HISTORY_MAX_FRAMES = Math.ceil(HISTORY_WINDOW_MS / PROCESS_INTERVAL_MS);
+/** 事件循环延迟取最近多少个 tick 的均值（单帧尖刺不该立刻变成"服务很卡"） */
+const LAG_SAMPLE_COUNT = 5;
+
+/**
+ * 事件循环延迟（毫秒）——**定时器漂移法**，不用 `perf_hooks.monitorEventLoopDelay`。
+ *
+ * 为什么不用内置直方图：实测 `monitorEventLoopDelay({ resolution: 20 })` 在**空载**下
+ * `mean` 就是 20.95ms ≈ 分辨率本身（分辨率 20ms 时它把量化误差当成了延迟）。用它报"卡不卡"
+ * 会把每个部署都显示成"延迟 20ms"。漂移法的原理是"期望时刻 vs 实际时刻"的差，没有量化偏差。
+ */
+export function createLagMeter(intervalMs = PROCESS_INTERVAL_MS) {
+  let lastScheduledAt = null;
+  const samples = [];
+
+  return {
+    /** 在每个 tick 开头调用：返回本次漂移（ms），并记录最近 N 个样本 */
+    tick(nowMs = Date.now()) {
+      const drift = lastScheduledAt === null ? 0 : Math.max(0, nowMs - lastScheduledAt - intervalMs);
+      lastScheduledAt = nowMs;
+      samples.push(drift);
+      if (samples.length > LAG_SAMPLE_COUNT) samples.shift();
+      return drift;
+    },
+    /** 最近 N 个样本的均值（没有样本时 null） */
+    average() {
+      if (samples.length === 0) return null;
+      return samples.reduce((sum, value) => sum + value, 0) / samples.length;
+    },
+    reset() {
+      lastScheduledAt = null;
+      samples.length = 0;
+    },
+  };
+}
+
+/**
+ * 采集器：start() 起两个定时器，stop() 清掉；snapshot()/history() 给路由用。
+ * @param {{ logger?: object, taskStats?: () => object }} options
+ */
+export function createMetricsCollector({ logger, taskStats } = {}) {
+  const cpuCount = Math.max(1, os.cpus().length);
+  const frames = [];
+  const lagMeter = createLagMeter(PROCESS_INTERVAL_MS);
+
+  /** /proc 累计值快照（用于算两次采样之间的差值） */
+  let prevCpuTimes = null;
+  let prevDisk = null;
+  let prevCpuUsage = null;
+  let prevTickAt = null;
+  let prevElu = performance.eventLoopUtilization();
+
+  /** 最近一帧（system 部分单独缓存：它 5s 才采一次，1s 的帧复用最近值） */
+  let latestSystem = { cpuPercent: null, memUsedBytes: null, memTotalBytes: null, diskReadBps: null, diskWriteBps: null };
+
+  let systemTimer = null;
+  let processTimer = null;
+  let running = false;
+
+  /** 百分比夹取（null 透传） */
+  function clampPercent(value) {
+    if (value === null || !Number.isFinite(value)) return null;
+    return Math.min(100, Math.max(0, Number(value.toFixed(1))));
+  }
+
+  /** 系统指标（含 CPU 差值、内存、磁盘 Bps）——失败字段一律 null */
+  async function collectSystem() {
+    let snapshot = null;
+    try {
+      snapshot = await readProcSnapshot();
+    } catch {
+      snapshot = null;
+    }
+    const nowMs = Date.now();
+    const cpuPercent = computeSystemCpu(snapshot && snapshot.cpuTimes);
+    const disk = computeDiskRates(snapshot && snapshot.disk, nowMs);
+    latestSystem = {
+      cpuPercent: cpuPercent === null ? latestSystem.cpuPercent : cpuPercent,
+      memUsedBytes: snapshot && snapshot.memory ? snapshot.memory.usedBytes : latestSystem.memUsedBytes,
+      memTotalBytes: snapshot && snapshot.memory ? snapshot.memory.totalBytes : latestSystem.memTotalBytes,
+      diskReadBps: disk ? disk.readBps : null,
+      diskWriteBps: disk ? disk.writeBps : null,
+    };
+    prevDisk = snapshot && snapshot.disk ? { ...snapshot.disk, atMs: nowMs } : prevDisk;
+    return latestSystem;
+  }
+
+  /** 系统 CPU 使用率：1 − 空闲增量/总增量（/proc/stat 累计值） */
+  function computeSystemCpu(cpuTimes) {
+    if (!cpuTimes) return null;
+    const previous = prevCpuTimes;
+    prevCpuTimes = cpuTimes;
+    if (!previous) return null;
+    const totalDelta = cpuTimes.total - previous.total;
+    const idleDelta = cpuTimes.idle - previous.idle;
+    if (!(totalDelta > 0)) return null;
+    return clampPercent((1 - idleDelta / totalDelta) * 100);
+  }
+
+  /** 磁盘读写速率（Bps）：扇区差值 × 512 / 实际经过时间 */
+  function computeDiskRates(disk, nowMs) {
+    if (!disk || !prevDisk) return null;
+    const elapsedMs = nowMs - prevDisk.atMs;
+    if (!(elapsedMs > 0)) return null;
+    const readBytes = sectorsToBytes(disk.readSectors - prevDisk.readSectors);
+    const writeBytes = sectorsToBytes(disk.writeSectors - prevDisk.writeSectors);
+    return {
+      readBps: Math.max(0, Math.round((readBytes * 1000) / elapsedMs)),
+      writeBps: Math.max(0, Math.round((writeBytes * 1000) / elapsedMs)),
+    };
+  }
+
+  /** 进程指标：CPU（相对全部核，便于和 system.cpuPercent 直接比较）+ 内存 + 事件循环 */
+  function collectProcess() {
+    const nowMs = Date.now();
+    const lagMs = lagMeter.tick(nowMs);
+
+    let cpuPercent = null;
+    const usage = process.cpuUsage();
+    if (prevCpuUsage) {
+      const elapsedMs = prevTickAt === null ? PROCESS_INTERVAL_MS : Math.max(1, nowMs - prevTickAt);
+      const usedUs = (usage.user - prevCpuUsage.user) + (usage.system - prevCpuUsage.system);
+      // 除以核数：与系统 CPU 同口径（0~100 表示"整机占比"），否则 4 核机器上进程跑满会显示 400%
+      cpuPercent = clampPercent((usedUs / 1000 / elapsedMs / cpuCount) * 100);
+    }
+    prevCpuUsage = usage;
+    prevTickAt = nowMs;
+
+    const memory = process.memoryUsage();
+    let utilization = null;
+    try {
+      const elu = performance.eventLoopUtilization(prevElu);
+      prevElu = performance.eventLoopUtilization();
+      utilization = Number.isFinite(elu.utilization) ? Number(elu.utilization.toFixed(3)) : null;
+    } catch {
+      utilization = null;
+    }
+
+    return {
+      cpuPercent,
+      rssBytes: memory.rss,
+      heapUsedBytes: memory.heapUsed,
+      eventLoopDelayMs: Number((lagMeter.average() === null ? lagMs : lagMeter.average()).toFixed(2)),
+      eventLoopUtilization: utilization,
+      uptimeMs: Math.round(process.uptime() * 1000),
+    };
+  }
+
+  /** 任务三件套（契约 §4.6 的 tasks）；manager.stats().active 是 taskId，这里转成计数 */
+  function collectTasks() {
+    if (typeof taskStats !== 'function') return { active: 0, queued: 0, parallel: false };
+    try {
+      const stats = taskStats() || {};
+      return {
+        active: stats.active ? 1 : 0,
+        queued: Number(stats.waiting) || 0,
+        parallel: false, // v1 强制串行（docs/05 §二）
+      };
+    } catch {
+      return { active: 0, queued: 0, parallel: false };
+    }
+  }
+
+  /** 采一帧（1s 节奏）；同步部分不抛异常 */
+  function collectFrame() {
+    const processStats = collectProcess();
+    const frame = {
+      ts: Date.now(),
+      system: { ...latestSystem },
+      process: processStats,
+      tasks: collectTasks(),
+    };
+    frames.push(frame);
+    pruneFrames();
+    return frame;
+  }
+
+  /** 环形缓冲：按时间窗裁剪（时间窗比帧数更稳：偶尔掉帧也不会提前丢历史） */
+  function pruneFrames() {
+    const deadline = Date.now() - HISTORY_WINDOW_MS;
+    while (frames.length > 0 && (frames[0].ts < deadline || frames.length > HISTORY_MAX_FRAMES)) frames.shift();
+  }
+
+  function start() {
+    if (running) return;
+    running = true;
+    lagMeter.reset();
+    prevElu = performance.eventLoopUtilization();
+    // 先采一次系统指标，保证第一个请求不是全 null（否则前端首帧会显示"—"）
+    void collectSystem().catch(() => {});
+    void collectProcess();
+    frames.length = 0;
+    collectFrame();
+
+    systemTimer = setInterval(() => {
+      void collectSystem().catch((error) => logger && logger.warn && logger.warn('metrics 系统指标采集失败', { error: error.message }));
+    }, SYSTEM_INTERVAL_MS);
+    processTimer = setInterval(() => {
+      try {
+        collectFrame();
+      } catch (error) {
+        // 定时器里的异常绝不能逃逸（未捕获异常会带走整个服务）
+        if (logger && logger.warn) logger.warn('metrics 进程指标采集失败', { error: error.message });
+      }
+    }, PROCESS_INTERVAL_MS);
+    // 两个定时器都不该阻止进程退出
+    if (typeof systemTimer.unref === 'function') systemTimer.unref();
+    if (typeof processTimer.unref === 'function') processTimer.unref();
+  }
+
+  function stop() {
+    if (systemTimer) clearInterval(systemTimer);
+    if (processTimer) clearInterval(processTimer);
+    systemTimer = null;
+    processTimer = null;
+    running = false;
+  }
+
+  /** 最新一帧（还没采到时按需采一帧，保证接口可用） */
+  function snapshot() {
+    if (frames.length === 0) collectFrame();
+    return frames[frames.length - 1];
+  }
+
+  /**
+   * 历史样本：window 秒内、每 step 秒取一帧（契约 §4.6 `?window=300&step=5`）。
+   * @param {{window?: number, step?: number}} options
+   */
+  function history({ window = 300, step = 5 } = {}) {
+    const windowMs = Math.min(HISTORY_WINDOW_MS, Math.max(1, window) * 1000);
+    const stepMs = Math.max(1, step) * 1000;
+    const deadline = Date.now() - windowMs;
+    // 用"时间桶内取最后一帧"而不是按 deadline 取模：deadline 随每次调用漂移，取模会让样本数抖动，
+    // 桶对齐才是"每 step 秒一个点"的确定语义。
+    const lastByBucket = new Map();
+    for (const frame of frames) {
+      if (frame.ts < deadline) continue;
+      lastByBucket.set(Math.floor(frame.ts / stepMs), frame);
+    }
+    return [...lastByBucket.values()].sort((left, right) => left.ts - right.ts);
+  }
+
+  return {
+    start,
+    stop,
+    snapshot,
+    history,
+    get running() {
+      return running;
+    },
+    /** 供测试/自检：当前缓冲帧数 */
+    get frameCount() {
+      return frames.length;
+    },
+  };
+}

package/server/core/metrics/procfs.js

@@ -0,0 +1,107 @@
+// /proc 解析（Linux 专用；读不到一律返回 null，**绝不抛**）
+//
+// 为什么用 /proc 而不是引 systeminformation：
+//   契约（docs/M0/API规范.md §4.6）要的字段全部可由 Node 内置 + /proc 得到；
+//   systeminformation 多出来的（温度/风扇/网络/进程列表）恰是 docs/07 §四 明确不做的，
+//   而且它不少方法靠 spawn 系统命令实现 —— 一个"开销必须 <1%"的监控不该在底层 spawn 进程。
+//
+// 降级策略：容器/非 Linux 环境下 /proc 文件可能不存在或格式不同 → 每个解析函数都返回 null，
+// 由上层把对应字段填 null（接口仍然活着，前端显示"—"），**不允许 500**。
+
+import fsp from 'node:fs/promises';
+
+const SECTOR_BYTES = 512;
+
+/**
+ * 只统计物理盘（sd* / nvme*），**刻意排除** md* / dm-* / loop*：
+ * 同一份物理 IO 会在 md（软 RAID 成员）与 dm（LVM/加密）上被重复上报，
+ * 全都加进来就是双倍甚至三倍的虚高。NAS 上这个差别非常明显。
+ */
+const PHYSICAL_DISK = /^(sd[a-z]+|nvme\d+n\d+)$/;
+
+/** 读文件；不存在/无权限返回 null（不抛） */
+async function readProc(filePath) {
+  try {
+    return await fsp.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 系统 CPU 累计时间（jiffies）。解析 /proc/stat 首行 `cpu user nice system idle iowait irq softirq steal`。
+ * @returns {{idle: number, total: number} | null}
+ */
+export function parseProcStat(text) {
+  if (typeof text !== 'string') return null;
+  const line = text.split('\n').find((row) => row.startsWith('cpu '));
+  if (!line) return null;
+  const values = line.trim().split(/\s+/).slice(1).map((value) => Number.parseInt(value, 10));
+  if (values.length < 4 || values.some((value) => !Number.isFinite(value))) return null;
+  // idle + iowait 都算"空转"（iowait 时 CPU 没在干活，对"卡不卡"的观感与 idle 一致）
+  const idle = (values[3] || 0) + (values[4] || 0);
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return { idle, total };
+}
+
+/**
+ * 内存（字节）。用 MemAvailable 而不是 MemFree：
+ * NAS 上页缓存会吃掉大量内存，MemFree 常年很低 → 会显示"内存快满了"的假警报；
+ * MemAvailable 才是内核估计的"还能给新程序用多少"。
+ * @returns {{usedBytes: number, totalBytes: number} | null}
+ */
+export function parseMemInfo(text) {
+  if (typeof text !== 'string') return null;
+  const readKb = (key) => {
+    const match = text.match(new RegExp(`^${key}:\\s+(\\d+) kB`, 'm'));
+    return match ? Number.parseInt(match[1], 10) * 1024 : null;
+  };
+  const total = readKb('MemTotal');
+  const available = readKb('MemAvailable');
+  if (!Number.isFinite(total) || !Number.isFinite(available)) return null;
+  return { usedBytes: Math.max(0, total - available), totalBytes: total };
+}
+
+/**
+ * 磁盘累计扇区数（只汇总物理盘）。字段顺序见 proc(5) diskstats：
+ * `major minor name reads readsMerged sectorsRead msRead writes writesMerged sectorsWritten ...`
+ * @returns {{readSectors: number, writeSectors: number} | null}
+ */
+export function parseDiskStats(text) {
+  if (typeof text !== 'string') return null;
+  let readSectors = 0;
+  let writeSectors = 0;
+  let matched = 0;
+  for (const line of text.split('\n')) {
+    const fields = line.trim().split(/\s+/);
+    if (fields.length < 10) continue;
+    const device = fields[2];
+    if (!PHYSICAL_DISK.test(device)) continue;
+    const sectorsRead = Number.parseInt(fields[5], 10);
+    const sectorsWritten = Number.parseInt(fields[9], 10);
+    if (!Number.isFinite(sectorsRead) || !Number.isFinite(sectorsWritten)) continue;
+    readSectors += sectorsRead;
+    writeSectors += sectorsWritten;
+    matched += 1;
+  }
+  return matched > 0 ? { readSectors, writeSectors } : null;
+}
+
+/** 读一次全量原始值（三个来源各自独立降级） */
+export async function readProcSnapshot() {
+  const [statText, memText, diskText] = await Promise.all([
+    readProc('/proc/stat'),
+    readProc('/proc/meminfo'),
+    readProc('/proc/diskstats'),
+  ]);
+  return {
+    cpuTimes: parseProcStat(statText),
+    memory: parseMemInfo(memText),
+    disk: parseDiskStats(diskText),
+  };
+}
+
+/** 扇区数 → 字节（供采集器算 Bps） */
+export function sectorsToBytes(sectors) {
+  return Number(sectors) * SECTOR_BYTES;
+}