mioku-plugin-help 2.0.0 → 2.1.1

package/help/role-config.ts

@@ -0,0 +1,67 @@
+/**
+ * Role badge palette and keyword stop-words.
+ *
+ * Both are referenced from multiple files in the help flow (intent
+ * matching, HTML rendering), so we keep them in one place to avoid
+ * divergent definitions.
+ */
+
+import type { CommandRole } from "mioku";
+
+/** Per-role label + light/dark badge colors. */
+export const ROLE_CONFIG: Record<
+  CommandRole,
+  {
+    label: string;
+    badgeBgLight: string;
+    badgeBorderLight: string;
+    badgeTextLight: string;
+    badgeBgDark: string;
+    badgeBorderDark: string;
+    badgeTextDark: string;
+  }
+> = {
+  master: {
+    label: "主人",
+    badgeBgLight: "rgba(245, 158, 11, 0.14)",
+    badgeBorderLight: "rgba(217, 119, 6, 0.24)",
+    badgeTextLight: "#92400e",
+    badgeBgDark: "rgba(245, 158, 11, 0.18)",
+    badgeBorderDark: "rgba(251, 191, 36, 0.28)",
+    badgeTextDark: "#fcd34d",
+  },
+  admin: {
+    label: "管理",
+    badgeBgLight: "rgba(239, 68, 68, 0.12)",
+    badgeBorderLight: "rgba(220, 38, 38, 0.22)",
+    badgeTextLight: "#b91c1c",
+    badgeBgDark: "rgba(239, 68, 68, 0.16)",
+    badgeBorderDark: "rgba(248, 113, 113, 0.22)",
+    badgeTextDark: "#fca5a5",
+  },
+  owner: {
+    label: "管理",
+    badgeBgLight: "rgba(239, 68, 68, 0.12)",
+    badgeBorderLight: "rgba(220, 38, 38, 0.22)",
+    badgeTextLight: "#b91c1c",
+    badgeBgDark: "rgba(239, 68, 68, 0.16)",
+    badgeBorderDark: "rgba(248, 113, 113, 0.22)",
+    badgeTextDark: "#fca5a5",
+  },
+  member: {
+    label: "成员",
+    badgeBgLight: "rgba(14, 165, 233, 0.12)",
+    badgeBorderLight: "rgba(2, 132, 199, 0.2)",
+    badgeTextLight: "#0369a1",
+    badgeBgDark: "rgba(56, 189, 248, 0.16)",
+    badgeBorderDark: "rgba(103, 232, 249, 0.22)",
+    badgeTextDark: "#67e8f9",
+  },
+};
+
+/**
+ * Words that should never be treated as a plugin name, even if the user
+ * typed something like "help 帮助". Used by both intent matching and
+ * alias extraction.
+ */
+export const STOPWORDS = new Set(["help", "帮助", "菜单"]);

package/help/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Public types for the help image flow.
+ *
+ * Kept in their own module so `intent.ts`, `info.ts`, `html-generator.ts`,
+ * and consumers can all import from a single place without creating cycles.
+ */
+
+import type { PluginHelp } from "mioku";
+
+/** Result of parsing a chat message into a help-image action. */
+export type HelpImageIntent =
+  | { type: "none" }
+  | { type: "overview" }
+  | { type: "detail"; pluginName: string; pluginHelp: PluginHelp }
+  | { type: "unknown"; keyword: string };
+
+/** Internal record used while ranking fuzzy keyword matches. */
+export interface HelpRenderableEntry {
+  pluginName: string;
+  title: string;
+  description: string;
+  commands: PluginHelp["commands"];
+  /** Lower-cased, alphanumeric-only form of `pluginName` for matching. */
+  normalizedPluginName: string;
+  /** Lower-cased, alphanumeric-only form of `title` for matching. */
+  normalizedTitle: string;
+  /** All normalized tokens we treat as equivalent to this entry. */
+  matchKeys: Set<string>;
+}
+
+/** A candidate plugin keyword extracted from a chat message. */
+export interface HelpKeywordCandidate {
+  keyword: string;
+  /**
+   * `true` if the keyword came from a strict help prefix/suffix pattern
+   * (e.g. "插件名 帮助"). A strict unknown should be surfaced to the user
+   * as "没有找到插件 X 的帮助"; loose matches silently fall through.
+   */
+  strictUnknown: boolean;
+}

package/index.ts

@@ -6,19 +6,29 @@ import * as path from "path";
 import { HELP_DEMO_CONFIG } from "./demo-config";
 import {
   generateHelpImage,
-  getPackageVersion,
   replyWithImage,
   resolveHelpBotProfile,
   resolveHelpImageIntent,
-} from "./shared";
+} from "./help";
+import { getRenderVersions } from "./utils";
 import { resetHelpRuntimeState, setHelpRuntimeState } from "./runtime";
+import {
+  generateStatusImage,
+  networkSampler,
+  perfMonitor,
+  resolveStatusIntent,
+} from "./status";
 
 const helpPlugin = definePlugin({
   name: "help",
-  version: "1.0.0",
-  description: "帮助插件，生成帮助图片",
+  version: "2.1.0",
+  description: "帮助插件，生成帮助图片，并提供 #状态 指令",
 
   async setup(ctx: MiokiContext) {
+    // 启动后台采样器
+    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
@@ -27,7 +37,12 @@ const helpPlugin = definePlugin({
 
     if (!helpService) {
       ctx.logger.warn("help-service 未加载，帮助插件无法运行");
-      return;
+      return () => {
+        networkSampler.stop();
+        perfMonitor.stop();
+        resetHelpRuntimeState();
+        ctx.logger.info("帮助插件已卸载");
+      };
     }
 
     if (!screenshotService) {
@@ -38,12 +53,20 @@ const helpPlugin = definePlugin({
       await configService.registerConfig("help", "demo", HELP_DEMO_CONFIG.demo);
     }
 
-    const miokiVersion = await getPackageVersion(
-      path.join(process.cwd(), "node_modules/mioku/node_modules/mioki/package.json"),
-    );
-    const miokuVersion = await getPackageVersion(
-      path.join(process.cwd(), "node_modules/mioku/package.json"),
-    );
+    // 注册 help manifest，让 `#help 状态` 能命中
+    helpService.registerHelp("help", {
+      title: "帮助与系统状态",
+      description: "生成帮助图片与系统状态图片",
+      commands: [
+        { cmd: "#help", desc: "查看帮助图片" },
+        {
+          cmd: "#状态",
+          desc: "查看完整系统状态图片（账号、资源、网络、磁盘、AI 统计、运行时、系统信息）",
+        },
+      ],
+    });
+
+    const { miokiVersion, miokuVersion } = await getRenderVersions();
 
     setHelpRuntimeState({
       miokiVersion,
@@ -56,6 +79,39 @@ const helpPlugin = definePlugin({
         return;
       }
 
+      // 状态指令拦截（优先级高于 help 匹配）
+      const statusIntent = resolveStatusIntent(text);
+      if (statusIntent.type !== "none") {
+        if (!screenshotService) {
+          await event.reply("screenshot 服务未加载，无法生成状态图片");
+          return;
+        }
+        try {
+          const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+            ctx,
+            event,
+          );
+          const result = await generateStatusImage({
+            ctx,
+            event,
+            intent: statusIntent,
+            botNickname,
+            botAvatarUrl,
+          });
+          if (result.ok && result.imagePath) {
+            await replyWithImage(event, ctx.segment, result.imagePath);
+          } else {
+            await event.reply(
+              `生成状态图片失败: ${result.error || "未知错误"}`,
+            );
+          }
+        } catch (error) {
+          ctx.logger.error(`生成状态图片失败: ${error}`);
+          await event.reply(`生成状态图片失败: ${error}`);
+        }
+        return;
+      }
+
       const allHelp = helpService.getAllHelp();
       const intent = resolveHelpImageIntent(text, allHelp);
       if (intent.type === "none") {
@@ -98,6 +154,8 @@ const helpPlugin = definePlugin({
     });
 
     return () => {
+      networkSampler.stop();
+      perfMonitor.stop();
       resetHelpRuntimeState();
       ctx.logger.info("帮助插件已卸载");
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mioku-plugin-help",
-  "version": "2.0.0",
-  "description": "帮助插件，使用截图服务生成美观的帮助图片",
+  "version": "2.1.1",
+  "description": "帮助插件，使用截图服务生成美观的帮助图片，并提供 #状态 指令",
   "main": "index.ts",
   "type": "module",
   "keywords": [
@@ -15,7 +15,8 @@
     "services": [
       "help",
       "screenshot",
-      "config"
+      "config",
+      "ai"
     ]
   },
   "peerDependencies": {

package/skills.ts

@@ -4,91 +4,146 @@ import type { ScreenshotService } from "mioku";
 import {
   buildHelpInfoText,
   generateHelpImage,
-  getHelpRenderVersions,
   resolveHelpBotProfile,
   sendImageFromSkillContext,
-} from "./shared";
+} from "./help";
+import { getRenderVersions } from "./utils";
+import { generateStatusImage } from "./status";
 
-const helpSkills: 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 未加载，无法获取帮助信息";
-          }
+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 getHelpRenderVersions();
+        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 服务未加载，无法生成帮助图片";
-          }
+        if (!screenshotService) {
+          return "screenshot 服务未加载，无法生成帮助图片";
+        }
 
-          try {
-            const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
-              ctx,
-              event,
-            );
-            const imagePath = await generateHelpImage({
-              helpService,
-              screenshotService,
-              miokiVersion,
-              miokuVersion,
-              botNickname,
-              botAvatarUrl,
-            });
+        try {
+          const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+            ctx,
+            event,
+          );
+          const imagePath = await generateHelpImage({
+            helpService,
+            screenshotService,
+            miokiVersion,
+            miokuVersion,
+            botNickname,
+            botAvatarUrl,
+          });
 
-            if (!imagePath) {
-              return "生成帮助图片失败";
-            }
+          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}`;
+          // 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 || "未知错误"}`;
           }
-        },
-      } as AITool,
-    ],
-  },
-];
+          await sendImageFromSkillContext({
+            ctx,
+            event,
+            imagePath: result.imagePath,
+            quoteReply: false,
+          });
+          return "已发送状态图片";
+        } catch (error) {
+          return `生成状态图片失败: ${error}`;
+        }
+      },
+    } as AITool,
+  ],
+};
+
+const helpSkills: AISkill[] = [helpSkill, statusSkill];
 
 export default helpSkills;