mioku-plugin-help 2.0.0 → 2.1.1

package/status/image.ts

@@ -0,0 +1,81 @@
+import type { MiokiContext, ScreenshotService } from "mioku";
+import { checkNightMode } from "../utils";
+import { collectSnapshot } from "./data-collector";
+import { renderStatusHtml } from "./html-generator";
+import type { StatusIntent } from "./types";
+
+const FORCE_NIGHT_MODE = false;
+
+const RENDER_TIMEOUT_MS = 12_000;
+
+function withTimeout<T>(p: PromiseLike<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error("status_render_timeout")),
+      ms,
+    );
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v as T);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
+export interface GenerateStatusImageOptions {
+  ctx: MiokiContext;
+  event?: any;
+  intent: StatusIntent;
+  botNickname?: string;
+  botAvatarUrl?: string;
+}
+
+export interface GenerateStatusImageResult {
+  ok: boolean;
+  imagePath?: string;
+  error?: string;
+}
+
+export async function generateStatusImage(
+  options: GenerateStatusImageOptions,
+): Promise<GenerateStatusImageResult> {
+  const { ctx, intent } = options;
+  const screenshotService = ctx?.services?.screenshot as
+    | ScreenshotService
+    | undefined;
+  if (!screenshotService) {
+    return { ok: false, error: "screenshot 服务未加载" };
+  }
+  if (intent.type === "none") {
+    return { ok: false, error: "not a status command" };
+  }
+
+  try {
+    const snapshot = await collectSnapshot(ctx, {
+      isNightMode: FORCE_NIGHT_MODE || checkNightMode(),
+    });
+    const html = renderStatusHtml(snapshot);
+    const imagePath = await withTimeout(
+      Promise.resolve(
+        screenshotService.screenshot(html, {
+          width: 760,
+          height: 200,
+          fullPage: true,
+          type: "png",
+        }),
+      ),
+      RENDER_TIMEOUT_MS,
+    );
+    if (!imagePath) {
+      return { ok: false, error: "screenshot 返回空路径" };
+    }
+    return { ok: true, imagePath };
+  } catch (err: any) {
+    return { ok: false, error: String(err?.message || err) };
+  }
+}

package/status/index.ts

@@ -0,0 +1,28 @@
+export type {
+  AIUsageStatsLite,
+  BotAccountStatus,
+  DiskEntry,
+  DiskStatus,
+  FrameworkStatus,
+  NetworkSample,
+  NetworkStatus,
+  NodeRuntimeStatus,
+  ResourceStatus,
+  StatusIntent,
+  StatusIntentFull,
+  StatusIntentNone,
+  StatusSnapshot,
+  SystemInfo,
+} from "./types";
+
+export { resolveStatusIntent } from "./intent";
+export {
+  collectSnapshot,
+  clearStatusCache,
+  __formatHelpers,
+} from "./data-collector";
+export { networkSampler } from "./network-sampler";
+export { perfMonitor } from "./performance-monitor";
+export { renderStatusHtml } from "./html-generator";
+export { generateStatusImage } from "./image";
+export type { GenerateStatusImageOptions, GenerateStatusImageResult } from "./image";

package/status/intent.ts

@@ -0,0 +1,43 @@
+import type { StatusIntent } from "./types";
+
+/**
+ * Parse a user message into a `StatusIntent`.
+ *
+ * Recognized prefixes: `#状态`, `/状态`, `状态`, `菜单 状态` (also the
+ * Latin aliases `zt` / `status`). Anything trailing the leading token is
+ * ignored — the panel always renders the full sheet.
+ *
+ * If the input doesn't look like a status command, returns `{ type: "none" }`
+ * and the help plugin's normal flow takes over.
+ */
+
+function stripStopword(input: string): string {
+  return String(input || "")
+    .trim()
+    .replace(/^[#/\s]+/, "")
+    .replace(/[。.!！?？,，:：；;]+$/g, "");
+}
+
+function normalize(value: string): string {
+  return String(value || "").toLowerCase().trim();
+}
+
+export function resolveStatusIntent(text: string): StatusIntent {
+  const source = stripStopword(text);
+  if (!source) {
+    return { type: "none" };
+  }
+
+  // Match leading tokens: "菜单 状态", "状态", "#状态", etc.
+  const tokens = source.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return { type: "none" };
+  }
+
+  const lead = normalize(tokens[0]);
+  if (lead !== "状态" && lead !== "zt" && lead !== "status") {
+    return { type: "none" };
+  }
+
+  return { type: "full" };
+}

package/status/network-sampler.ts

@@ -0,0 +1,129 @@
+import { systemInfo } from "mioki";
+import type { NetworkSample } from "./types";
+
+/**
+ * Background sampler for network throughput.
+ *
+ * Polls `systeminformation.networkStats()` at a fixed interval, sums the
+ * `rx_sec` / `tx_sec` of all interfaces, and stores the result in a ring
+ * buffer. The first sample is always discarded because macOS reports all
+ * zeros on the first call.
+ */
+class NetworkSampler {
+  private rxBpsRing: number[] = [];
+  private txBpsRing: number[] = [];
+  private tsRing: number[] = [];
+  private rxTotalBytes = 0;
+  private txTotalBytes = 0;
+  private timer: NodeJS.Timeout | null = null;
+  private intervalMs = 5000;
+  private maxSamples = 360;
+  private lastSampleAt: number | null = null;
+  private lastRxPerSec = 0;
+  private lastTxPerSec = 0;
+
+  start(intervalMs = 5000, maxSamples = 360): void {
+    if (this.timer) {
+      return;
+    }
+    this.intervalMs = intervalMs;
+    this.maxSamples = maxSamples;
+    void this.tick();
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, intervalMs);
+    if (typeof this.timer?.unref === "function") {
+      this.timer.unref();
+    }
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.timer !== null;
+  }
+
+  getLastSpeeds(): { rxBps: number; txBps: number } {
+    return { rxBps: this.lastRxPerSec, txBps: this.lastTxPerSec };
+  }
+
+  getTotals(): { rxBytes: number; txBytes: number } {
+    return { rxBytes: this.rxTotalBytes, txBytes: this.txTotalBytes };
+  }
+
+  getRecentSeries(windowMs: number): NetworkSample[] {
+    const cutoff = Date.now() - windowMs;
+    const result: NetworkSample[] = [];
+    for (let i = 0; i < this.tsRing.length; i++) {
+      const ts = this.tsRing[i] ?? 0;
+      if (ts >= cutoff) {
+        result.push({
+          ts,
+          rxBps: this.rxBpsRing[i] ?? 0,
+          txBps: this.txBpsRing[i] ?? 0,
+        });
+      }
+    }
+    return result;
+  }
+
+  private async tick(): Promise<void> {
+    try {
+      const stats = await systemInfo.networkStats();
+      if (!Array.isArray(stats) || stats.length === 0) {
+        return;
+      }
+      let rxPerSec = 0;
+      let txPerSec = 0;
+      let rxBytes = 0;
+      let txBytes = 0;
+      for (const iface of stats) {
+        rxPerSec += Number(iface?.rx_sec || 0);
+        txPerSec += Number(iface?.tx_sec || 0);
+        rxBytes += Number(iface?.rx_bytes || 0);
+        txBytes += Number(iface?.tx_bytes || 0);
+      }
+      const now = Date.now();
+      // macOS returns all zeros on the first call after process start. Drop
+      // the first sample to avoid a giant spike in the chart.
+      if (this.lastSampleAt === null) {
+        this.lastSampleAt = now;
+        this.lastRxPerSec = rxPerSec;
+        this.lastTxPerSec = txPerSec;
+        this.rxTotalBytes = rxBytes;
+        this.txTotalBytes = txBytes;
+        this.pushSample(now, rxPerSec, txPerSec);
+        return;
+      }
+      const deltaSec = Math.max(0.001, (now - this.lastSampleAt) / 1000);
+      // Accumulate bytes based on per-second rates to avoid double-counting
+      // the `rx_bytes` field on systems where it resets on interface bounce.
+      this.rxTotalBytes += rxPerSec * deltaSec;
+      this.txTotalBytes += txPerSec * deltaSec;
+      this.lastSampleAt = now;
+      this.lastRxPerSec = rxPerSec;
+      this.lastTxPerSec = txPerSec;
+      this.pushSample(now, rxPerSec, txPerSec);
+    } catch {
+      // Ignore transient errors; sampler continues.
+    }
+  }
+
+  private pushSample(ts: number, rxBps: number, txBps: number): void {
+    this.tsRing.push(ts);
+    this.rxBpsRing.push(rxBps);
+    this.txBpsRing.push(txBps);
+    if (this.tsRing.length > this.maxSamples) {
+      this.tsRing.shift();
+      this.rxBpsRing.shift();
+      this.txBpsRing.shift();
+    }
+  }
+}
+
+export const networkSampler = new NetworkSampler();

package/status/performance-monitor.ts

@@ -0,0 +1,102 @@
+import { monitorEventLoopDelay, PerformanceObserver } from "node:perf_hooks";
+
+/**
+ * Captures Node event-loop delay and (best-effort) GC events.
+ *
+ * `monitorEventLoopDelay` returns a histogram that must be `reset()` after
+ * each read; otherwise values accumulate forever. The GC observer requires
+ * Node to be started with `--expose-gc`, otherwise the `gc` entry type is
+ * unavailable and we degrade gracefully.
+ */
+class PerfMonitor {
+  private loopHist: ReturnType<typeof monitorEventLoopDelay> | null = null;
+  private gcObserver: PerformanceObserver | null = null;
+  private lastSnapshot: { mean: number; p99: number } = { mean: 0, p99: 0 };
+  private gcCount = 0;
+  private lastGCDurationMs = 0;
+  private readTimer: NodeJS.Timeout | null = null;
+
+  start(): void {
+    if (this.loopHist) {
+      return;
+    }
+    try {
+      this.loopHist = monitorEventLoopDelay({ resolution: 20 });
+      this.loopHist.enable();
+      this.readTimer = setInterval(() => {
+        if (!this.loopHist) {
+          return;
+        }
+        // nanoseconds → milliseconds
+        this.lastSnapshot = {
+          mean: this.loopHist.mean / 1e6,
+          p99: this.loopHist.percentile(99) / 1e6,
+        };
+        this.loopHist.reset();
+      }, 1000);
+      if (typeof this.readTimer.unref === "function") {
+        this.readTimer.unref();
+      }
+    } catch {
+      this.loopHist = null;
+    }
+
+    try {
+      this.gcObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          this.gcCount += 1;
+          this.lastGCDurationMs = entry.duration;
+        }
+      });
+      this.gcObserver.observe({ entryTypes: ["gc"] });
+    } catch {
+      this.gcObserver = null;
+    }
+  }
+
+  stop(): void {
+    if (this.readTimer) {
+      clearInterval(this.readTimer);
+      this.readTimer = null;
+    }
+    if (this.loopHist) {
+      try {
+        this.loopHist.disable();
+      } catch {
+        // ignore
+      }
+      this.loopHist = null;
+    }
+    if (this.gcObserver) {
+      try {
+        this.gcObserver.disconnect();
+      } catch {
+        // ignore
+      }
+      this.gcObserver = null;
+    }
+  }
+
+  isRunning(): boolean {
+    return this.loopHist !== null;
+  }
+
+  getEventLoop(): { mean: number; p99: number } {
+    return this.lastSnapshot;
+  }
+
+  getGC():
+    | { available: boolean; count: number; lastDurationMs?: number }
+    | null {
+    if (!this.gcObserver) {
+      return { available: false, count: 0 };
+    }
+    return {
+      available: true,
+      count: this.gcCount,
+      lastDurationMs: this.lastGCDurationMs,
+    };
+  }
+}
+
+export const perfMonitor = new PerfMonitor();

package/status/types.ts

@@ -0,0 +1,264 @@
+/**
+ * Status panel data types.
+ *
+ * The status panel is rendered from a single `StatusSnapshot` aggregated by
+ * `data-collector.ts`. Every field is plain data; rendering logic lives in
+ * `html-generator.ts`.
+ */
+
+export interface BotAccountStatus {
+  uin: number;
+  nickname: string;
+  avatarUrl: string;
+  /** Underlying bot framework identifier, e.g. "QQBot" / "NapCat" / "LLOneBot". */
+  framework: string;
+  /** Adapter app version, e.g. "5.0.6" — from OneBot `get_version_info.app_version`. */
+  appVersion: string;
+  /** OneBot protocol version, e.g. "v11" — from OneBot `get_version_info.protocol_version`. */
+  protocolVersion: string;
+  online: boolean;
+  groupCount: number;
+  friendCount: number;
+  /** Computed from `bot.api("get_status").stat.start_time`. 0 if unavailable. */
+  onlineDurationMs: number;
+  send: number;
+  receive: number;
+}
+
+/**
+ * OneBot v11 `get_version_info` payload (already unwrapped from the
+ * `{ status, retcode, data, ... }` envelope by napcat-sdk's `bot.api`).
+ */
+export interface OneBotVersionInfoData {
+  app_name: string;
+  protocol_version: string;
+  app_version: string;
+}
+
+/**
+ * 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
+ */
+export interface OneBotStatusData {
+  online?: boolean;
+  good?: boolean;
+  stat?: {
+    start_time?: number;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/** Subset of mioku's `AIService.getUsageSummary` payload that we actually render. */
+export interface AIUsageSummary {
+  totals?: {
+    requests?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+  };
+  rates?: {
+    errorRate?: number;
+    cacheHitRate?: number;
+  };
+  groupRanking?: Array<{
+    groupId?: number | string;
+    groupName?: string;
+    requests?: number;
+    totalTokens?: number;
+  }>;
+  toolRanking?: Array<{
+    name?: string;
+    count?: number;
+  }>;
+}
+
+/** Subset of `systeminformation.graphics()` payload that we actually render. */
+export interface GraphicsData {
+  controllers?: Array<{
+    model?: string;
+    vendor?: string;
+    [key: string]: unknown;
+  }>;
+  [key: string]: unknown;
+}
+
+export interface FrameworkStatus {
+  miokuVersion: string;
+  miokiVersion: string;
+  napcatVersion: string;
+  /** Total discovered plugins (enabled + disabled). */
+  pluginCount: number;
+  /** Currently enabled plugins. */
+  pluginEnabled: number;
+  /** Number of distinct bot frameworks (deduplicated by app_name). */
+  adapterCount: number;
+  onlineBotCount: number;
+  uptimeMs: number;
+  /** Detected JS runtime name: "Bun" / "Node" / "Deno". */
+  runtime: string;
+  /** Detected JS runtime version. */
+  runtimeVersion: string;
+}
+
+export interface ResourceStatus {
+  cpuPercent: number;
+  cpuModel: string;
+  /** CPU brand truncated to ~22 chars with ellipsis. */
+  cpuModelShort: string;
+  /** Human-readable clock, e.g. "2.9 GHz" / "900 MHz". */
+  cpuSpeedGHz: string;
+  cpuCores: number;
+  memPercent: number;
+  memUsedGB: number;
+  memTotalGB: number;
+  /** Buffers + cache as reported by `systeminformation.mem().buffcache`. 0 if unavailable. */
+  memBuffCacheGB: number;
+  /** 0..100, or 0 if no swap configured. */
+  swapPercent: number;
+  swapUsedGB: number;
+  swapTotalGB: number;
+}
+
+export interface NodeRuntimeStatus {
+  heapUsedMB: number;
+  heapTotalMB: number;
+  rssMB: number;
+  externalMB: number;
+  arrayBuffersMB: number;
+  eventLoopDelayMs: { mean: number; p99: number };
+  /** null when `--expose-gc` is not enabled. */
+  gc:
+    | {
+        available: boolean;
+        count: number;
+        lastDurationMs?: number;
+      }
+    | null;
+}
+
+export interface NetworkSample {
+  ts: number;
+  rxBps: number;
+  txBps: number;
+}
+
+export interface NetworkStatus {
+  rxBps: number;
+  txBps: number;
+  rxTotalBytes: number;
+  txTotalBytes: number;
+  /** Last 30 minutes of samples, oldest first. */
+  history: NetworkSample[];
+}
+
+export interface DiskEntry {
+  mount: string;
+  usedGB: number;
+  totalGB: number;
+  percent: number;
+}
+
+export interface DiskStatus {
+  entries: DiskEntry[];
+  readMBps?: number;
+  writeMBps?: number;
+  iops?: number;
+}
+
+/** One GPU as reported by `systeminformation.graphics().controllers`. */
+export interface GpuInfo {
+  vendor: string;
+  model: string;
+  /** VRAM in GB. 0 if unknown / integrated. */
+  vramGB: number;
+}
+
+/** One physical memory module as reported by `systeminformation.memLayout()`. */
+export interface MemoryStick {
+  bank: string;
+  sizeGB: number;
+  /** "DDR4" / "DDR5" / "LPDDR5" / "Unknown". */
+  type: string;
+  /** Transfer rate in MT/s, e.g. 3200 / 4800. 0 if unknown. */
+  speedMTs: number;
+  manufacturer: string;
+  partNum: string;
+}
+
+/** BIOS / UEFI firmware info from `systeminformation.bios()`. */
+export interface BiosInfo {
+  vendor: string;
+  version: string;
+  releaseDate: string;
+}
+
+/** One physical disk drive from `systeminformation.diskLayout()`. */
+export interface DiskInfo {
+  vendor: string;
+  name: string;
+  /** "HDD" / "SSD" / "NVMe" / unknown. */
+  type: string;
+  /** "SATA" / "NVMe" / "USB" / unknown. */
+  interfaceType: string;
+  sizeGB: number;
+}
+
+export interface SystemInfo {
+  /** "macOS Sequoia 15.5 (arm64)" / "Ubuntu 24.04 LTS (x86_64)". */
+  os: string;
+  /** Kernel string, e.g. "Darwin 25.5.0" / "Linux 6.8.0-31-generic". */
+  kernel: string;
+  /** Full CPU brand from `systeminformation.cpu().brand`. */
+  cpu: string;
+  /** All GPUs detected, integrated + discrete. Empty if none. */
+  gpus: GpuInfo[];
+  /** All physical RAM modules. Empty if `memLayout()` not supported (e.g. macOS). */
+  memSticks: MemoryStick[];
+  /** BIOS / UEFI. vendor "N/A" if not supported. */
+  bios: BiosInfo;
+  /** System manufacturer + model, e.g. "Supermicro H12SSL-NT". "N/A" on macOS. */
+  chassis: string;
+  /** All physical disk drives. Empty on systems where `diskLayout()` is
+   * not supported (rare) or no drives are detected. */
+  disks: DiskInfo[];
+}
+
+export interface AIUsageStatsLite {
+  available: boolean;
+  totalRequests: number;
+  errorRate: number;
+  cacheHitRate: number;
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  topGroups: Array<{ name: string; requests: number; totalTokens: number }>;
+  topTools: Array<{ name: string; count: number }>;
+}
+
+export interface StatusSnapshot {
+  generatedAt: number;
+  isNightMode: boolean;
+  bots: BotAccountStatus[];
+  framework: FrameworkStatus;
+  resources: ResourceStatus;
+  runtime: NodeRuntimeStatus;
+  network: NetworkStatus;
+  disk: DiskStatus;
+  system: SystemInfo;
+  ai: AIUsageStatsLite;
+}
+
+/** Intent returned by `resolveStatusIntent`. Only "full" or "none" — the panel
+ * always renders the complete status; sub-section shortcuts were removed. */
+export interface StatusIntentFull {
+  type: "full";
+}
+
+export interface StatusIntentNone {
+  type: "none";
+}
+
+export type StatusIntent = StatusIntentFull | StatusIntentNone;