mioku-plugin-help 2.3.0 → 2.3.3

package/help/role.ts

@@ -36,8 +36,14 @@ export function canInvokeCommand(
  *   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.
+ * - Group chat resolves bot admin (mioki `isAdmin` allowlist), group
+ *   owner (群主) and group admin (群管理) all to `admin`. This mirrors
+ *   the admin plugin's execution gating (`isMaster || senderRole ===
+ *   "owner" || senderRole === "admin"`) so the help image only hides
+ *   commands the viewer genuinely can't run. `sender.role` is checked
+ *   first (populated by OneBot on group events), with
+ *   `getGroupMemberInfo` as a fallback when it's missing. Everyone else
+ *   is `member`.
  */
 export async function resolveViewerRole(
   ctx: any,
@@ -54,6 +60,11 @@ export async function resolveViewerRole(
       return "admin";
     }
 
+    const senderRole = event?.sender?.role;
+    if (senderRole === "owner" || senderRole === "admin") {
+      return "admin";
+    }
+
     if (event?.group_id != null && event?.user_id != null) {
       const selfId =
         event?.self_id != null ? Number(event.self_id) : undefined;
@@ -67,8 +78,8 @@ export async function resolveViewerRole(
             event.group_id,
             event.user_id,
           );
-          if (info?.role === "owner") {
-            return "owner";
+          if (info?.role === "owner" || info?.role === "admin") {
+            return "admin";
           }
         } catch {
           // fall through to member

package/index.ts

@@ -1,7 +1,5 @@
-import type { ConfigService } from "mioku";
-import type { HelpService } from "mioku";
-import type { ScreenshotService } from "mioku";
 import { definePlugin, type MiokiContext } from "mioki";
+import { getService, Services } from "mioku";
 import * as path from "path";
 import { HELP_DEMO_CONFIG } from "./demo-config";
 import {
@@ -12,13 +10,13 @@ import {
   resolveViewerRole,
 } from "./help";
 import { getRenderVersions } from "./utils";
-import { resetHelpRuntimeState, setHelpRuntimeState } from "./runtime";
 import {
   generateStatusImage,
   networkSampler,
   perfMonitor,
   resolveStatusIntent,
 } from "./status";
+import { createHelpSkills } from "./skills";
 
 const helpPlugin = definePlugin({
   name: "help",
@@ -30,18 +28,16 @@ const helpPlugin = definePlugin({
     networkSampler.start();
     perfMonitor.start();
 
-    const configService = ctx.services?.config as ConfigService | undefined;
-    const helpService = ctx.services?.help as HelpService | undefined;
-    const screenshotService = ctx.services?.screenshot as
-      | ScreenshotService
-      | undefined;
+    const configService = getService(ctx, Services.Config);
+    const helpService = getService(ctx, Services.Help);
+    const screenshotService = getService(ctx, Services.Screenshot);
+    const aiService = getService(ctx, Services.AI);
 
     if (!helpService) {
       ctx.logger.warn("help-service 未加载，帮助插件无法运行");
       return () => {
         networkSampler.stop();
         perfMonitor.stop();
-        resetHelpRuntimeState();
         ctx.logger.info("帮助插件已卸载");
       };
     }
@@ -69,12 +65,11 @@ const helpPlugin = definePlugin({
 
     const { miokiVersion, miokuVersion } = await getRenderVersions();
 
-    setHelpRuntimeState({
-      miokiVersion,
-      miokuVersion,
-    });
+    if (aiService) {
+      for (const skill of createHelpSkills()) aiService.registerSkill(skill);
+    }
 
-    ctx.handle("message", async (event: any) => {
+    ctx.handle("message", async (event) => {
       const text = ctx.text(event);
       if (!text) {
         return;
@@ -159,7 +154,10 @@ const helpPlugin = definePlugin({
     return () => {
       networkSampler.stop();
       perfMonitor.stop();
-      resetHelpRuntimeState();
+      if (aiService) {
+        aiService.removeSkill("help");
+        aiService.removeSkill("status");
+      }
       ctx.logger.info("帮助插件已卸载");
     };
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-help",
-  "version": "2.3.0",
+  "version": "2.3.3",
   "description": "帮助插件，使用截图服务生成美观的帮助图片，并提供 #状态 指令",
   "main": "index.ts",
   "type": "module",

package/skills/help.ts

@@ -0,0 +1,93 @@
+import type { AISkill, AITool } from "mioku";
+import type { HelpService, ScreenshotService } from "mioku";
+import {
+  buildHelpInfoText,
+  generateHelpImage,
+  resolveHelpBotProfile,
+  resolveViewerRole,
+  sendImageFromSkillContext,
+} from "../help";
+import { getRenderVersions } from "../utils";
+
+export function createHelpSkill(): AISkill {
+  return {
+    name: "help",
+    description: "获取插件帮助信息和发送帮助图片",
+    permission: "member",
+    tools: [
+      {
+        name: "get_help_info",
+        description:
+          "获取所有插件的帮助信息文本，这个仅用于用户向你询问某个功能的具体用法时使用",
+        parameters: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+        handler: async (_args: any, runtimeCtx?: any) => {
+          const ctx = runtimeCtx?.ctx;
+          const helpService = ctx?.services?.help as HelpService | undefined;
+          if (!helpService) {
+            return "help-service 未加载，无法获取帮助信息";
+          }
+
+          return buildHelpInfoText(helpService.getAllHelp());
+        },
+      } as AITool,
+      {
+        name: "send_help_image",
+        description:
+          "生成并发送帮助图片到群聊，如果有人说他想看帮助，优先调用图片发送而不是自己查看帮助。",
+        parameters: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+        handler: async (_args: any, runtimeCtx?: any) => {
+          const ctx = runtimeCtx?.ctx;
+          const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
+          const helpService = ctx?.services?.help as HelpService | undefined;
+          const screenshotService = ctx?.services?.screenshot as
+            | ScreenshotService
+            | undefined;
+          const { miokiVersion, miokuVersion } = await getRenderVersions();
+
+          if (!screenshotService) {
+            return "screenshot 服务未加载，无法生成帮助图片";
+          }
+
+          try {
+            const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+              ctx,
+              event,
+            );
+            const viewerRole = await resolveViewerRole(ctx, event);
+            const imagePath = await generateHelpImage({
+              helpService,
+              screenshotService,
+              miokiVersion,
+              miokuVersion,
+              botNickname,
+              botAvatarUrl,
+              viewerRole,
+            });
+
+            if (!imagePath) {
+              return "生成帮助图片失败";
+            }
+
+            await sendImageFromSkillContext({
+              ctx,
+              event,
+              imagePath,
+              quoteReply: false,
+            });
+            return "已发送帮助图片";
+          } catch (error) {
+            return `生成帮助图片失败: ${error}`;
+          }
+        },
+      } as AITool,
+    ],
+  };
+}

package/skills/index.ts

@@ -0,0 +1,7 @@
+import type { AISkill } from "mioku";
+import { createHelpSkill } from "./help";
+import { createStatusSkill } from "./status";
+
+export function createHelpSkills(): AISkill[] {
+  return [createHelpSkill(), createStatusSkill()];
+}

package/skills/status.ts

@@ -0,0 +1,63 @@
+import type { AISkill, AITool } from "mioku";
+import type { ScreenshotService } from "mioku";
+import {
+  resolveHelpBotProfile,
+  sendImageFromSkillContext,
+} from "../help";
+import { generateStatusImage } from "../status";
+
+export function createStatusSkill(): AISkill {
+  return {
+    name: "status",
+    description:
+      "系统状态查询，生成完整的系统状态图片",
+    permission: "member",
+    tools: [
+      {
+        name: "send_status_image",
+        description:
+          "生成并发送完整的系统状态图片。当用户问「看看状态」「机器人怎么样」「服务器忙吗」「资源还够吗」「看看 AI 用了多少」时优先使用。",
+        parameters: {
+          type: "object",
+          properties: {},
+          required: [],
+        },
+        handler: async (_args: any, runtimeCtx?: any) => {
+          const ctx = runtimeCtx?.ctx;
+          const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
+          const screenshotService = ctx?.services?.screenshot as
+            | ScreenshotService
+            | undefined;
+          if (!screenshotService) {
+            return "screenshot 服务未加载";
+          }
+          try {
+            const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+              ctx,
+              event,
+            );
+            const result = await generateStatusImage({
+              ctx,
+              event,
+              intent: { type: "full" },
+              botNickname,
+              botAvatarUrl,
+            });
+            if (!result.ok || !result.imagePath) {
+              return `生成状态图片失败: ${result.error || "未知错误"}`;
+            }
+            await sendImageFromSkillContext({
+              ctx,
+              event,
+              imagePath: result.imagePath,
+              quoteReply: false,
+            });
+            return "已发送状态图片";
+          } catch (error) {
+            return `生成状态图片失败: ${error}`;
+          }
+        },
+      } as AITool,
+    ],
+  };
+}

package/runtime.ts

@@ -1,25 +0,0 @@
-export interface HelpPluginRuntimeState {
-  miokiVersion?: string;
-  miokuVersion?: string;
-}
-
-const runtimeState: HelpPluginRuntimeState = {};
-
-export function setHelpRuntimeState(
-  nextState: HelpPluginRuntimeState,
-): HelpPluginRuntimeState {
-  Object.assign(runtimeState, nextState);
-  return runtimeState;
-}
-
-export function getHelpRuntimeState(): HelpPluginRuntimeState {
-  return runtimeState;
-}
-
-export function resetHelpRuntimeState(): void {
-  for (const key of Object.keys(runtimeState) as Array<
-    keyof HelpPluginRuntimeState
-  >) {
-    delete runtimeState[key];
-  }
-}

package/skills.ts

@@ -1,149 +0,0 @@
-import type { AISkill, AITool } from "mioku";
-import type { HelpService } from "mioku";
-import type { ScreenshotService } from "mioku";
-import {
-  buildHelpInfoText,
-  generateHelpImage,
-  resolveHelpBotProfile,
-  sendImageFromSkillContext,
-} from "./help";
-import { getRenderVersions } from "./utils";
-import { generateStatusImage } from "./status";
-
-const helpSkill: AISkill = {
-  name: "help",
-  description: "帮助系统，获取插件帮助信息和发送帮助图片",
-  permission: "member",
-  tools: [
-    {
-      name: "get_help_info",
-      description:
-        "获取所有插件的帮助信息文本，这个仅用于用户向你询问某个功能的具体用法时使用",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-      },
-      handler: async (_args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        const helpService = ctx?.services?.help as HelpService | undefined;
-        if (!helpService) {
-          return "help-service 未加载，无法获取帮助信息";
-        }
-
-        return buildHelpInfoText(helpService.getAllHelp());
-      },
-    } as AITool,
-    {
-      name: "send_help_image",
-      description:
-        "生成并发送帮助图片到群聊，如果有人说他想看帮助，优先调用图片发送而不是自己查看帮助。",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-      },
-      handler: async (_args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
-        const helpService = ctx?.services?.help as HelpService | undefined;
-        const screenshotService = ctx?.services?.screenshot as
-          | ScreenshotService
-          | undefined;
-        const { miokiVersion, miokuVersion } = await getRenderVersions();
-
-        if (!screenshotService) {
-          return "screenshot 服务未加载，无法生成帮助图片";
-        }
-
-        try {
-          const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
-            ctx,
-            event,
-          );
-          const imagePath = await generateHelpImage({
-            helpService,
-            screenshotService,
-            miokiVersion,
-            miokuVersion,
-            botNickname,
-            botAvatarUrl,
-          });
-
-          if (!imagePath) {
-            return "生成帮助图片失败";
-          }
-
-          // Help skill defaults to normal send instead of quote-reply.
-          await sendImageFromSkillContext({
-            ctx,
-            event,
-            imagePath,
-            quoteReply: false,
-          });
-          return "已发送帮助图片";
-        } catch (error) {
-          return `生成帮助图片失败: ${error}`;
-        }
-      },
-    } as AITool,
-  ],
-};
-
-const statusSkill: AISkill = {
-  name: "status",
-  description:
-    "系统状态查询，生成完整的系统状态图片（账号、资源、网络、磁盘、AI 统计、运行时、系统信息）",
-  permission: "member",
-  tools: [
-    {
-      name: "send_status_image",
-      description:
-        "生成并发送完整的系统状态图片。当用户问「看看状态」「机器人怎么样」「服务器忙吗」「资源还够吗」「看看 AI 用了多少」时优先使用。",
-      parameters: {
-        type: "object",
-        properties: {},
-        required: [],
-      },
-      handler: async (_args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
-        const screenshotService = ctx?.services?.screenshot as
-          | ScreenshotService
-          | undefined;
-        if (!screenshotService) {
-          return "screenshot 服务未加载";
-        }
-        try {
-          const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
-            ctx,
-            event,
-          );
-          const result = await generateStatusImage({
-            ctx,
-            event,
-            intent: { type: "full" },
-            botNickname,
-            botAvatarUrl,
-          });
-          if (!result.ok || !result.imagePath) {
-            return `生成状态图片失败: ${result.error || "未知错误"}`;
-          }
-          await sendImageFromSkillContext({
-            ctx,
-            event,
-            imagePath: result.imagePath,
-            quoteReply: false,
-          });
-          return "已发送状态图片";
-        } catch (error) {
-          return `生成状态图片失败: ${error}`;
-        }
-      },
-    } as AITool,
-  ],
-};
-
-const helpSkills: AISkill[] = [helpSkill, statusSkill];
-
-export default helpSkills;