mioku-plugin-help 2.1.1 → 2.3.0

package/help/html-generator.ts

@@ -12,12 +12,21 @@
  */
 
 import type { CommandRole, PluginHelp } from "mioku";
+import { botConfig } from "mioki";
 import { escapeHtml } from "../utils";
 import { getHelpTheme, HELP_BACKGROUND_IMAGE_URL } from "../theme";
 import { getRenderableEntries } from "./intent";
 import { ROLE_CONFIG } from "./role-config";
 import type { HelpRenderableEntry } from "./types";
 
+function resolvePrefixPlaceholder(cmd: string): string {
+  const value = String(cmd || "");
+  if (value.startsWith("?")) {
+    return `${botConfig.prefix ?? "#"}${value.slice(1)}`;
+  }
+  return value;
+}
+
 function renderRoleBadge(
   role: CommandRole,
   isNightMode: boolean,
@@ -38,7 +47,7 @@ function renderPluginOverview(entry: HelpRenderableEntry): string {
   const commandTags = entry.commands
     .map(
       (command) =>
-        `<span class="help-command-tag" title="${escapeHtml(command.desc || "")}" >${escapeHtml(command.cmd)}</span>`,
+        `<span class="help-command-tag" title="${escapeHtml(command.desc || "")}" >${escapeHtml(resolvePrefixPlaceholder(command.cmd))}</span>`,
     )
     .join("");
 
@@ -73,7 +82,7 @@ function renderPluginDetail(
       return `
         <div class="help-command">
           <div class="help-command__top">
-            <div class="help-command__name">${escapeHtml(command.cmd)}</div>
+            <div class="help-command__name">${escapeHtml(resolvePrefixPlaceholder(command.cmd))}</div>
             ${roleBadge}
           </div>
           <div class="help-command__desc">${escapeHtml(command.desc || "")}</div>
@@ -109,6 +118,9 @@ function renderPluginDetail(
  * Build the full help image HTML. `targetPluginName` switches the
  * renderer to detail mode for that plugin (no-op if the name doesn't
  * match anything in `helpMap`).
+ *
+ * `viewerRole` filters out commands the requesting user can't invoke,
+ * so the image only surfaces what they can actually run.
  */
 export function generateHelpHtml(
   helpMap: Map<string, PluginHelp>,
@@ -118,8 +130,9 @@ export function generateHelpHtml(
   botNickname: string = "Mioku Bot",
   botAvatarUrl?: string,
   targetPluginName?: string,
+  viewerRole: CommandRole = "master",
 ): string {
-  const entries = getRenderableEntries(helpMap);
+  const entries = getRenderableEntries(helpMap, viewerRole);
   const selectedEntry = targetPluginName
     ? entries.find((entry) => entry.pluginName === targetPluginName)
     : undefined;

package/help/image.ts

@@ -16,7 +16,7 @@
  */
 
 import * as fs from "node:fs/promises";
-import type { HelpService, ScreenshotService } from "mioku";
+import type { CommandRole, HelpService, ScreenshotService } from "mioku";
 import { checkNightMode } from "../utils";
 import { generateHelpHtml } from "./html-generator";
 
@@ -52,6 +52,10 @@ export function normalizeImageSource(file: string): string {
  * Build the help image and write it to disk via the screenshot service.
  * Returns the resulting file path, or `null` if any required service is
  * missing.
+ *
+ * `viewerRole` controls which commands are rendered — the image only
+ * shows commands the requester is allowed to invoke, so members don't
+ * see admin/master-only commands cluttering the panel.
  */
 export async function generateHelpImage(options: {
   helpService?: HelpService;
@@ -61,6 +65,7 @@ export async function generateHelpImage(options: {
   botNickname?: string;
   botAvatarUrl?: string;
   targetPluginName?: string;
+  viewerRole?: CommandRole;
 }): Promise<string | null> {
   const {
     helpService,
@@ -70,6 +75,7 @@ export async function generateHelpImage(options: {
     botNickname,
     botAvatarUrl,
     targetPluginName,
+    viewerRole,
   } = options;
   if (!helpService || !screenshotService) {
     return null;
@@ -87,6 +93,7 @@ export async function generateHelpImage(options: {
     botNickname,
     botAvatarUrl,
     hasTarget ? targetPluginName : undefined,
+    viewerRole,
   );
 
   return screenshotService.screenshot(htmlContent, {

package/help/index.ts

@@ -20,5 +20,6 @@ export {
 } from "./intent";
 export { buildHelpInfoText } from "./info";
 export { generateHelpHtml } from "./html-generator";
+export { canInvokeCommand, resolveViewerRole } from "./role";
 export type { HelpImageIntent, HelpRenderableEntry } from "./types";
 export { ROLE_CONFIG, STOPWORDS } from "./role-config";

package/help/intent.ts

@@ -7,7 +7,8 @@
  * plugin names, titles, command aliases, and Chinese/English substrings.
  */
 
-import type { PluginHelp } from "mioku";
+import type { CommandRole, PluginHelp } from "mioku";
+import { canInvokeCommand } from "./role";
 import { STOPWORDS } from "./role-config";
 import type {
   HelpImageIntent,
@@ -89,15 +90,27 @@ function extractCommandAlias(command: string): string | null {
  * rendered entries are the source of truth for both keyword scoring
  * (in this file) and the HTML renderer's overview list. Exported so
  * `html-generator.ts` can reuse it instead of duplicating the logic.
+ *
+ * `viewerRole` filters out commands above the requester's permission
+ * level so the overview/detail views don't show commands they can't
+ * invoke. Defaults to `"master"` so callers that don't yet know the
+ * viewer (e.g. AI skill listings) keep the full registry.
  */
 export function getRenderableEntries(
   helpMap: Map<string, PluginHelp>,
+  viewerRole: CommandRole = "master",
 ): HelpRenderableEntry[] {
   return Array.from(helpMap.entries())
     .map(([pluginName, help]) => {
       const title = String(help.title || pluginName).trim() || pluginName;
       const description = String(help.description || "").trim();
-      const commands = Array.isArray(help.commands) ? help.commands : [];
+      const allCommands = Array.isArray(help.commands) ? help.commands : [];
+      const commands = allCommands.filter((command) =>
+        canInvokeCommand(
+          viewerRole,
+          command.role as CommandRole | undefined,
+        ),
+      );
       const normalizedPluginName = normalizeForMatch(pluginName);
       const normalizedTitle = normalizeForMatch(title);
 
@@ -113,7 +126,7 @@ export function getRenderableEntries(
         keys.add(token);
       }
 
-      const commandAliases = commands
+      const commandAliases = allCommands
         .map((command) => extractCommandAlias(command.cmd))
         .filter((value): value is string => Boolean(value));
       for (const alias of commandAliases) {

package/help/role.ts

@@ -0,0 +1,83 @@
+/**
+ * Viewer role resolution for the help image.
+ *
+ * Decides which commands a given user is allowed to see based on the
+ * event's sender and the bot's owner/admin allowlists. The result is
+ * used to filter `getRenderableEntries` so the rendered help image
+ * matches what the requester can actually invoke.
+ */
+
+import type { CommandRole } from "mioku";
+
+const ROLE_RANK: Record<CommandRole, number> = {
+  master: 4,
+  admin: 3,
+  owner: 2,
+  member: 1,
+};
+
+/**
+ * Whether the given viewer can invoke a command gated at `commandRole`.
+ * A command without a `role` field is treated as member-level (visible
+ * to everyone).
+ */
+export function canInvokeCommand(
+  viewerRole: CommandRole,
+  commandRole: CommandRole | undefined,
+): boolean {
+  const required: CommandRole = commandRole || "member";
+  return ROLE_RANK[viewerRole] >= ROLE_RANK[required];
+}
+
+/**
+ * Resolve the requesting user's effective role for help filtering.
+ *
+ * - `master` is honored everywhere (private or group) — it comes from
+ *   mioki's `isOwner` allowlist.
+ * - Private chat skips the `isAdmin` check and defaults to `admin`,
+ *   so anyone DM-ing the bot can see admin-level commands.
+ * - Group chat keeps the full hierarchy: admin (mioki allowlist) →
+ *   owner (group owner via `getGroupMemberInfo`) → member.
+ */
+export async function resolveViewerRole(
+  ctx: any,
+  event: any,
+): Promise<CommandRole> {
+  if (ctx?.isOwner?.(event)) {
+    return "master";
+  }
+
+  const isGroup = event?.message_type === "group";
+
+  if (isGroup) {
+    if (ctx?.isAdmin?.(event)) {
+      return "admin";
+    }
+
+    if (event?.group_id != null && event?.user_id != null) {
+      const selfId =
+        event?.self_id != null ? Number(event.self_id) : undefined;
+      const bot =
+        selfId != null && typeof ctx?.pickBot === "function"
+          ? ctx.pickBot(selfId)
+          : undefined;
+      if (bot && typeof bot.getGroupMemberInfo === "function") {
+        try {
+          const info = await bot.getGroupMemberInfo(
+            event.group_id,
+            event.user_id,
+          );
+          if (info?.role === "owner") {
+            return "owner";
+          }
+        } catch {
+          // fall through to member
+        }
+      }
+    }
+
+    return "member";
+  }
+
+  return "admin";
+}

package/index.ts

@@ -9,6 +9,7 @@ import {
   replyWithImage,
   resolveHelpBotProfile,
   resolveHelpImageIntent,
+  resolveViewerRole,
 } from "./help";
 import { getRenderVersions } from "./utils";
 import { resetHelpRuntimeState, setHelpRuntimeState } from "./runtime";
@@ -130,6 +131,7 @@ const helpPlugin = definePlugin({
 
       try {
         const { botNickname, botAvatarUrl } = resolveHelpBotProfile(ctx, event);
+        const viewerRole = await resolveViewerRole(ctx, event);
         const imagePath = await generateHelpImage({
           helpService,
           screenshotService,
@@ -139,6 +141,7 @@ const helpPlugin = definePlugin({
           botAvatarUrl,
           targetPluginName:
             intent.type === "detail" ? intent.pluginName : undefined,
+          viewerRole,
         });
 
         if (!imagePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-help",
-  "version": "2.1.1",
+  "version": "2.3.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

@@ -225,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";
@@ -248,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;
@@ -297,7 +283,6 @@ async function collectBotStatuses(
       online,
       groupCount,
       friendCount,
-      onlineDurationMs,
       send: counts.send,
       receive: counts.receive,
     });

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. */