mioku-plugin-help 2.2.0 → 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.2.0",
+  "version": "2.3.0",
   "description": "帮助插件，使用截图服务生成美观的帮助图片，并提供 #状态 指令",
   "main": "index.ts",
   "type": "module",