mioku-plugin-help 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-help",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "帮助插件，使用截图服务生成美观的帮助图片，并提供 #状态 指令",
   "main": "index.ts",
   "type": "module",
@@ -17,6 +17,18 @@
       "screenshot",
       "config",
       "ai"
+    ],
+    "accessHooks": [
+      {
+        "id": "帮助菜单",
+        "match": "/(?:[#/]\\s*(?:帮助|菜单|help)|^(?:帮助|菜单|help)(?:\\s|$))/",
+        "description": "匹配 #help / 帮助 / 菜单 等帮助指令"
+      },
+      {
+        "id": "状态",
+        "match": "/(?:[#/]\\s*(?:状态|zt|status)|^(?:状态|zt|status)(?:\\s|$))/",
+        "description": "匹配 #状态 / 状态 / zt / status 等系统状态指令"
+      }
     ]
   },
   "peerDependencies": {

package/status/data-collector.ts

@@ -67,6 +67,71 @@ function safeNumber(value: unknown, fallback = 0): number {
   return Number.isFinite(n) ? n : fallback;
 }
 
+/**
+ * Snapshot of the system's CPU tick counters at a point in time. The
+ * sum covers every core, so a 4-core box that's fully loaded registers
+ * `total = 4 * elapsed_in_ticks`. `idle` is the slice spent idle.
+ */
+interface CpuTickSample {
+  idle: number;
+  total: number;
+  ts: number;
+}
+
+function sampleCpuTicks(): CpuTickSample {
+  let idle = 0;
+  let total = 0;
+  for (const cpu of os.cpus()) {
+    const t = cpu.times;
+    idle += t.idle;
+    total += t.user + t.nice + t.sys + t.idle + t.irq;
+  }
+  return { idle, total, ts: Date.now() };
+}
+
+/**
+ * Baseline sample taken at module load. We seed the cache eagerly so the
+ * first `#状态` call (whenever it happens) already has a comparison
+ * point — without this, the first call after a long idle period would
+ * show 0% even if the system is under load.
+ */
+let prevCpuTicks: CpuTickSample = sampleCpuTicks();
+
+/**
+ * If the gap between two samples is larger than this, the previous
+ * sample is too stale to produce a meaningful delta (e.g. the user
+ * called `#状态` once, then came back an hour later). Discard and
+ * start a fresh baseline.
+ */
+const CPU_SAMPLE_MAX_GAP_MS = 30_000;
+
+/**
+ * System-wide average CPU utilization between the previous sample and
+ * now. Returns 0 on the first call after a baseline reset, and a value
+ * in [0, 100] on subsequent calls.
+ *
+ * `os.cpus()` already sums ticks across all cores, so the result is
+ * the per-core average — no need to divide by `cpuCores` (the old
+ * `process.cpuUsage()` math did that because it summed its own usage
+ * across cores; same destination, different source).
+ */
+function computeSystemCpuPercent(): number {
+  const current = sampleCpuTicks();
+  const gap = current.ts - prevCpuTicks.ts;
+  if (gap > CPU_SAMPLE_MAX_GAP_MS || gap <= 0) {
+    prevCpuTicks = current;
+    return 0;
+  }
+  const idleDiff = current.idle - prevCpuTicks.idle;
+  const totalDiff = current.total - prevCpuTicks.total;
+  prevCpuTicks = current;
+  if (totalDiff <= 0) {
+    return 0;
+  }
+  const percent = 100 - (idleDiff / totalDiff) * 100;
+  return Math.max(0, Math.min(100, percent));
+}
+
 /** Detect the active JS runtime and its version. */
 function detectRuntime(): { name: string; version: string } {
   if (process.versions.bun) {
@@ -160,7 +225,6 @@ async function collectBotStatuses(
 
     // 并行拿 OneBot API 的 status / group / friend / version
     let online = true;
-    let onlineDurationMs = 0;
     let groupCount = 0;
     let friendCount = 0;
     let appVersion = "unknown";
@@ -183,20 +247,7 @@ async function collectBotStatuses(
         ).catch(() => null),
       ]);
     if (statusResult.status === "fulfilled" && statusResult.value) {
-      const status = statusResult.value;
-      // napcat-sdk 的 api() 已经把 OneBot v11 响应的 data 字段解包出来，
-      const startTs = safeNumber(status?.stat?.start_time);
-      if (startTs > 0) {
-        // OneBot 约定：start_time 是 unix 秒；> 1e12 视为毫秒
-        const startMs = startTs > 1e12 ? startTs : startTs * 1000;
-        onlineDurationMs = Math.max(0, Date.now() - startMs);
-      }
-      if (typeof status?.online === "boolean") {
-        online = status.online;
-      } else if (typeof status?.good === "boolean") {
-        // go-cqhttp / LLOneBot 用 good 表示总体健康
-        online = status.good;
-      }
+      online = statusResult.value.online;
     }
     if (versionResult.status === "fulfilled" && versionResult.value) {
       const v = versionResult.value;
@@ -232,7 +283,6 @@ async function collectBotStatuses(
       online,
       groupCount,
       friendCount,
-      onlineDurationMs,
       send: counts.send,
       receive: counts.receive,
     });
@@ -315,16 +365,11 @@ async function collectResources(): Promise<ResourceStatus> {
     speedMhz >= 1000
       ? `${(speedMhz / 1000).toFixed(1)} GHz`
       : `${Math.round(speedMhz)} MHz`;
-  // CPU% requires a 2nd sample; we compute the delta from a previous tick.
-  // Keep it simple here: estimate from process.cpuUsage() relative to
-  // wall-clock since start. The webui module re-samples with sleep; for the
-  // status panel we accept a less precise reading.
-  const cpuUser = process.cpuUsage();
-  const cpuTotalUsec = cpuUser.user + cpuUser.system;
-  const cpuPercent = Math.min(
-    100,
-    ((cpuTotalUsec / 1e6 / Math.max(1, process.uptime())) * 100) / cpuCores,
-  );
+  // System-wide CPU% from a 2-sample delta. `collectSnapshot` has a 2s
+  // TTL, so under normal use we'll have a fresh reading each call. The
+  // first call after a baseline reset returns 0 (sentinel) — see
+  // `computeSystemCpuPercent` for the gap-discard policy.
+  const cpuPercent = computeSystemCpuPercent();
 
   // systeminformation.mem() gives buffcache and swap fields that os can't.
   // Wrap in withTimeout so a single slow call doesn't stall the snapshot.

package/status/html-generator.ts

@@ -71,23 +71,6 @@ function fmtBps(bps: number): string {
   return `${fmtBytes(bps)}/s`;
 }
 
-function fmtUptime(ms: number): string {
-  if (!Number.isFinite(ms) || ms <= 0) {
-    return "—";
-  }
-  const sec = Math.floor(ms / 1000);
-  const days = Math.floor(sec / 86400);
-  const hours = Math.floor((sec % 86400) / 3600);
-  const minutes = Math.floor((sec % 3600) / 60);
-  if (days > 0) {
-    return `${days}天${String(hours).padStart(2, "0")}时${String(minutes).padStart(2, "0")}分`;
-  }
-  if (hours > 0) {
-    return `${hours}时${String(minutes).padStart(2, "0")}分`;
-  }
-  return `${minutes}分`;
-}
-
 function progressBar(percent: number, color: string): string {
   const clamped = Math.max(0, Math.min(100, percent));
   return `<div class="status-bar"><div class="status-bar__fill" style="width:${clamped}%;background:${color};"></div></div>`;
@@ -162,7 +145,6 @@ function renderHero(
             { text: statusText, kind: bot.online ? "ok" : "danger" },
             { text: `好友 ${fmtNumber(bot.friendCount)}`, kind: "data" },
             { text: `群聊 ${fmtNumber(bot.groupCount)}`, kind: "data" },
-            { text: `运行时长 ${fmtUptime(bot.onlineDurationMs)}`, kind: "data" },
             { text: `收 ${fmtNumber(bot.receive)}`, kind: "data" },
             { text: `发 ${fmtNumber(bot.send)}`, kind: "data" },
             { text: frameworkText, kind: "data" },

package/status/types.ts

@@ -19,8 +19,6 @@ export interface BotAccountStatus {
   online: boolean;
   groupCount: number;
   friendCount: number;
-  /** Computed from `bot.api("get_status").stat.start_time`. 0 if unavailable. */
-  onlineDurationMs: number;
   send: number;
   receive: number;
 }
@@ -37,18 +35,13 @@ export interface OneBotVersionInfoData {
 
 /**
  * OneBot v11 `get_status` payload (already unwrapped by napcat-sdk).
- * Different implementations expose different subsets:
- * - NapCat / go-cqhttp: `online`, `good`, `stat.start_time`
- * - LLOneBot: same shape
+ * Per napcat 官方文档: `{ online, good, stat }` —— `stat` 是空对象，
+ * 不包含 `start_time` 或任何统计字段。本接口只声明文档承诺的字段。
  */
 export interface OneBotStatusData {
-  online?: boolean;
-  good?: boolean;
-  stat?: {
-    start_time?: number;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
+  online: boolean;
+  good: boolean;
+  stat: Record<string, never>;
 }
 
 /** Subset of mioku's `AIService.getUsageSummary` payload that we actually render. */