mioku-plugin-help 3.0.3 → 3.1.0

package/help/image.ts

@@ -108,24 +108,40 @@ export async function generateHelpImage(options: {
  * Pick a bot's nickname + avatar URL. Used so the help card can greet
  * the user with their bot's identity rather than a generic string.
  */
-export function resolveHelpBotProfile(
+export async function resolveHelpBotProfile(
   ctx: any,
   event?: any,
-): { botNickname: string; botAvatarUrl?: string } {
+): Promise<{ botNickname: string; botAvatarUrl?: string }> {
   const fallbackNickname = "Mioku Bot";
   const selfId = event?.self_id;
   const bot =
     event?.bot ??
     (ctx?.bots instanceof Map ? Array.from(ctx.bots.values())[0] : null);
-  const botId = selfId || bot?.bot_id;
+  const botId = String(selfId ?? bot?.bot_id ?? "").trim();
   const botNickname = bot?.nickname || bot?.name || fallbackNickname;
-  const botAvatarUrl = botId
-    ? `https://q1.qlogo.cn/g?b=qq&nk=${botId}&s=640`
-    : undefined;
+  const botAvatarUrl = await resolveBotAvatar(bot, botId);
 
   return { botNickname, botAvatarUrl };
 }
 
+/** QQ 系的 qlogo 头像服务只认数字 QQ 号,openid/AppID 一律走平台接口 */
+export async function resolveBotAvatar(
+  bot: any,
+  botId: string,
+): Promise<string | undefined> {
+  try {
+    const avatar = await bot?.getAvatar?.();
+    if (typeof avatar === "string" && avatar) return avatar;
+  } catch {
+    // 平台不支持时回退
+  }
+  const adapter = String(bot?.adapter ?? "");
+  if ((adapter === "onebotv11" || adapter === "icqq") && /^\d+$/.test(botId)) {
+    return `https://q1.qlogo.cn/g?b=qq&nk=${botId}&s=640`;
+  }
+  return undefined;
+}
+
 /**
  * Reply to a chat event with a local image file. Falls back to base64
  * encoding if the network adapter can't send a raw file path.

package/help/intent.ts

@@ -23,7 +23,7 @@ import type {
 function sanitizeKeyword(value: string): string {
   return String(value || "")
     .trim()
-    .replace(/^[#/\s]+/, "")
+    .replace(/^[#/.\s]+/, "")
     .replace(/[。.!！?？,，:：；);]+$/g, "");
 }
 
@@ -55,15 +55,15 @@ function extractMatchTokens(text: string): string[] {
 }
 
 /**
- * The first whitespace-separated token of a command, with the `#` / `/`
- * prefix removed. Used as an additional alias when matching plugin
+ * The first whitespace-separated token of a command, with the `.` / `#` /
+ * `/` prefix removed. Used as an additional alias when matching plugin
  * commands. Returns null if the first token is empty, contains `<>` (a
  * placeholder), or has no alphanumeric characters.
  */
 function extractCommandAlias(command: string): string | null {
   const value = String(command || "")
     .trim()
-    .replace(/^[#/]+/, "");
+    .replace(/^[#/.]+/, "");
   if (!value) {
     return null;
   }

package/help/role.ts

@@ -33,7 +33,7 @@ export function canInvokeCommand(
  * Resolve the requesting user's effective role for help filtering.
  *
  * - `master` is honored everywhere (private or group) — it comes from
- *   mioki's `isOwner` allowlist.
+ *   mioki's `isMaster` allowlist (the bot `owners` list).
  * - Private chat skips the `isAdmin` check and defaults to `admin`,
  *   so anyone DM-ing the bot can see admin-level commands.
  * - Group chat resolves bot admin (mioki `isAdmin` allowlist), group
@@ -49,7 +49,7 @@ export async function resolveViewerRole(
   ctx: any,
   event: any,
 ): Promise<CommandRole> {
-  if (ctx?.isOwner?.(event)) {
+  if (ctx?.isMaster?.(event)) {
     return "master";
   }
 
@@ -65,19 +65,20 @@ export async function resolveViewerRole(
       return "admin";
     }
 
-    if (event?.group_id != null && event?.user_id != null) {
+    const groupId = String(event?.group_id ?? "").trim();
+    const userId = String(event?.user_id ?? "").trim();
+    if (groupId && userId) {
       const bot = event?.bot;
       if (bot) {
         try {
-          const info = await bot.getMemberInfo(
-            event.group_id,
-            event.user_id,
-          );
+          const info = await bot.getMemberInfo(groupId, userId);
           if (info?.role === "owner" || info?.role === "admin") {
             return "admin";
           }
+          // 拿不到成员信息(null/空)时不能断言对方是普通成员,保守给 admin
+          if (!info?.role) return "admin";
         } catch {
-          // fall through to member
+          return "admin";
         }
       }
     }

package/index.ts

@@ -21,8 +21,6 @@ import { createHelpSkills } from "./skills";
 
 const helpPlugin = definePlugin({
   name: "help",
-  version: "2.1.0",
-  description: "帮助插件，生成帮助图片，并提供 #状态 指令",
 
   async setup(ctx: MiokuContext) {
     // 启动后台采样器
@@ -75,7 +73,7 @@ const helpPlugin = definePlugin({
       for (const skill of createHelpSkills()) aiService.registerSkill(skill);
     }
 
-    ctx.handle("message", async (event) => {
+    const handleHelpMessage = async (event: import("mioku").MessageEvent) => {
       const text = ctx.text(event);
       if (!text) {
         return;
@@ -89,7 +87,7 @@ const helpPlugin = definePlugin({
           return;
         }
         try {
-          const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+          const { botNickname, botAvatarUrl } = await resolveHelpBotProfile(
             ctx,
             event,
           );
@@ -131,7 +129,7 @@ const helpPlugin = definePlugin({
       }
 
       try {
-        const { botNickname, botAvatarUrl } = resolveHelpBotProfile(ctx, event);
+        const { botNickname, botAvatarUrl } = await resolveHelpBotProfile(ctx, event);
         const viewerRole = await resolveViewerRole(ctx, event);
         const imagePath = await generateHelpImage({
           helpService,
@@ -155,6 +153,25 @@ const helpPlugin = definePlugin({
         ctx.logger.error(`生成帮助图片失败: ${error}`);
         await event.reply(`生成帮助图片失败: ${error}`);
       }
+    };
+
+    ctx.command({
+      id: "帮助菜单",
+      name: "help",
+      aliases: ["帮助", "菜单"],
+      match: /^(?:help|帮助|菜单)(?:\s|$)/i,
+      prefixes: [".", "#", "/", ""],
+      description: "生成帮助图片",
+      handler: ({ event }) => handleHelpMessage(event),
+    });
+    ctx.command({
+      id: "status",
+      name: "status",
+      aliases: ["状态", "zt"],
+      match: /^(?:status|状态|zt)(?:\s|$)/i,
+      prefixes: [".", "#", "/", ""],
+      description: "生成系统状态图片",
+      handler: ({ event }) => handleHelpMessage(event),
     });
 
     return () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-help",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "帮助插件，使用截图服务生成美观的帮助图片，并提供 #状态 指令",
   "main": "index.ts",
   "type": "module",
@@ -17,18 +17,6 @@
       "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/skills/help.ts

@@ -57,7 +57,7 @@ export function createHelpSkill(): AISkill {
           }
 
           try {
-            const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+            const { botNickname, botAvatarUrl } = await resolveHelpBotProfile(
               ctx,
               event,
             );

package/skills/status.ts

@@ -32,7 +32,7 @@ export function createStatusSkill(): AISkill {
             return "screenshot 服务未加载";
           }
           try {
-            const { botNickname, botAvatarUrl } = resolveHelpBotProfile(
+            const { botNickname, botAvatarUrl } = await resolveHelpBotProfile(
               ctx,
               event,
             );

package/status/data-collector.ts

@@ -205,6 +205,14 @@ async function collectBots(
   return collectBotStatuses(sorted, ctx, stdinAvatar);
 }
 
+/** QQ 系适配器的 bot_id 才是数字 QQ 号,qlogo 服务对 openid/AppID 无效 */
+function qlogoAvatarUrl(adapter: string, botId: string): string {
+  if ((adapter === "onebotv11" || adapter === "icqq") && /^\d+$/.test(botId)) {
+    return `https://q1.qlogo.cn/g?b=qq&nk=${botId}&s=160`;
+  }
+  return "";
+}
+
 /** 把本地绝对路径 / http(s) / file:// 统一成可被截图服务加载的图片地址 */
 function toImageSrc(value: string): string {
   if (/^(https?:|file:|data:)/i.test(value)) return value;
@@ -274,7 +282,7 @@ async function collectBotStatuses(
           ? toImageSrc(stdinAvatar || "")
           : avatarFromBot
             ? toImageSrc(avatarFromBot)
-            : `https://q1.qlogo.cn/g?b=qq&nk=${uin}&s=160`,
+            : qlogoAvatarUrl(adapter, uin),
         adapter,
         implLabel,
         framework: isStdin ? adapter : framework,

package/status/intent.ts

@@ -3,7 +3,7 @@ import type { StatusIntent } from "./types";
 /**
  * Parse a user message into a `StatusIntent`.
  *
- * Recognized prefixes: `#状态`, `/状态`, `状态`, `菜单 状态` (also the
+ * Recognized prefixes: `.状态` / `/状态` / `#状态` / 裸 `状态` (also the
  * Latin aliases `zt` / `status`). Anything trailing the leading token is
  * ignored — the panel always renders the full sheet.
  *
@@ -14,7 +14,7 @@ import type { StatusIntent } from "./types";
 function stripStopword(input: string): string {
   return String(input || "")
     .trim()
-    .replace(/^[#/\s]+/, "")
+    .replace(/^[#/.\s]+/, "")
     .replace(/[。.!！?？,，:：；);]+$/g, "");
 }