mioku-plugin-help 2.0.0 → 2.1.1

package/help/image.ts

@@ -0,0 +1,216 @@
+/**
+ * Help image orchestration.
+ *
+ * `generateHelpImage` is the high-level entry point: it takes a help
+ * service, builds the HTML, and asks the screenshot service to render
+ * the PNG. The lower-level functions cover:
+ *
+ * - Image source normalization (`normalizeImageSource`)
+ * - Bot profile resolution (`resolveHelpBotProfile`)
+ * - Two reply helpers (`replyWithImage`, `sendImageFromSkillContext`)
+ *   that handle the local file → base64 fallback when the network
+ *   adapter can't send a raw path.
+ *
+ * Version detection lives in `../utils#getRenderVersions` so the help
+ * panel and the status panel share the same logic.
+ */
+
+import * as fs from "node:fs/promises";
+import type { HelpService, ScreenshotService } from "mioku";
+import { checkNightMode } from "../utils";
+import { generateHelpHtml } from "./html-generator";
+
+/** POSIX or Windows absolute path → `file://...`; anything else passes through. */
+function isLocalFilePath(value: string): boolean {
+  return value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value);
+}
+
+/** Prefix remote / data-URI / absolute paths so the bot framework can route them. */
+export function normalizeImageSource(file: string): string {
+  const value = String(file || "").trim();
+  if (!value) {
+    return value;
+  }
+
+  if (
+    value.startsWith("file://") ||
+    value.startsWith("base64://") ||
+    value.startsWith("http://") ||
+    value.startsWith("https://")
+  ) {
+    return value;
+  }
+
+  if (isLocalFilePath(value)) {
+    return `file://${value}`;
+  }
+
+  return value;
+}
+
+/**
+ * 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.
+ */
+export async function generateHelpImage(options: {
+  helpService?: HelpService;
+  screenshotService?: ScreenshotService;
+  miokiVersion?: string;
+  miokuVersion?: string;
+  botNickname?: string;
+  botAvatarUrl?: string;
+  targetPluginName?: string;
+}): Promise<string | null> {
+  const {
+    helpService,
+    screenshotService,
+    miokiVersion,
+    miokuVersion,
+    botNickname,
+    botAvatarUrl,
+    targetPluginName,
+  } = options;
+  if (!helpService || !screenshotService) {
+    return null;
+  }
+
+  const allHelp = helpService.getAllHelp();
+  const hasTarget =
+    Boolean(targetPluginName) && allHelp.has(String(targetPluginName));
+
+  const htmlContent = generateHelpHtml(
+    allHelp,
+    checkNightMode(),
+    miokiVersion,
+    miokuVersion,
+    botNickname,
+    botAvatarUrl,
+    hasTarget ? targetPluginName : undefined,
+  );
+
+  return screenshotService.screenshot(htmlContent, {
+    width: 760,
+    height: 120,
+    fullPage: true,
+    type: "png",
+  });
+}
+
+/**
+ * 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(
+  ctx: any,
+  event?: any,
+): { botNickname: string; botAvatarUrl?: string } {
+  const fallbackNickname = "Mioku Bot";
+  const selfId = event?.self_id;
+  const bot =
+    (selfId && typeof ctx?.pickBot === "function"
+      ? ctx.pickBot(selfId)
+      : null) ||
+    (ctx?.bots instanceof Map ? Array.from(ctx.bots.values())[0] : null);
+  const botId = selfId || bot?.uin || bot?.user_id || bot?.self_id;
+  const botNickname = bot?.nickname || bot?.name || fallbackNickname;
+  const botAvatarUrl = botId
+    ? `https://q1.qlogo.cn/g?b=qq&nk=${botId}&s=640`
+    : undefined;
+
+  return { botNickname, botAvatarUrl };
+}
+
+/**
+ * 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.
+ */
+export async function replyWithImage(
+  event: any,
+  segment: { image: (file: string) => any } | undefined,
+  imagePath: string,
+): Promise<void> {
+  if (!event?.reply) {
+    throw new Error("当前上下文不支持发送图片回复");
+  }
+
+  try {
+    if (segment?.image) {
+      await event.reply(segment.image(imagePath));
+    } else {
+      await event.reply([{ type: "image", file: imagePath }]);
+    }
+  } catch {
+    const imageBuffer = await fs.readFile(imagePath);
+    const base64Image = `base64://${imageBuffer.toString("base64")}`;
+
+    if (segment?.image) {
+      await event.reply(segment.image(base64Image));
+    } else {
+      await event.reply([{ type: "image", file: base64Image }]);
+    }
+  }
+}
+
+/**
+ * Send an image from inside an AI skill handler. Picks the right bot via
+ * `ctx.pickBot(selfId)`, supports an optional quote-reply, and falls
+ * back to base64 when the adapter refuses a raw path.
+ */
+export async function sendImageFromSkillContext(options: {
+  ctx: any;
+  event: any;
+  imagePath: string;
+  quoteReply?: boolean;
+}): Promise<void> {
+  const { ctx, event, imagePath, quoteReply = false } = options;
+  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) {
+    throw new Error("当前上下文不支持发送图片");
+  }
+
+  const buildImageSegment = (file: string) => {
+    const normalizedFile = normalizeImageSource(file);
+    if (ctx?.segment?.image) {
+      return ctx.segment.image(normalizedFile);
+    }
+    return { type: "image", file: normalizedFile };
+  };
+
+  const sendPayload = async (file: string) => {
+    const payload: any[] = [];
+    if (quoteReply && event?.message_id != null) {
+      payload.push({ type: "reply", id: String(event.message_id) });
+    }
+    payload.push(buildImageSegment(file));
+
+    if (event?.message_type === "group" && event?.group_id != null) {
+      await bot.sendGroupMsg(event.group_id, payload);
+      return;
+    }
+
+    if (event?.user_id != null) {
+      await bot.sendPrivateMsg(event.user_id, payload);
+      return;
+    }
+
+    throw new Error("当前上下文不支持发送图片");
+  };
+
+  try {
+    await sendPayload(imagePath);
+  } catch (error) {
+    if (!isLocalFilePath(imagePath)) {
+      throw error;
+    }
+
+    const imageBuffer = await fs.readFile(imagePath);
+    const base64Image = `base64://${imageBuffer.toString("base64")}`;
+    await sendPayload(base64Image);
+  }
+}

package/help/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public API for the help feature.
+ *
+ * Everything the plugin entry point and the AI skills need from the
+ * help subsystem re-exports from here. Internal modules stay private
+ * to their concerns.
+ */
+
+export {
+  generateHelpImage,
+  resolveHelpBotProfile,
+  replyWithImage,
+  sendImageFromSkillContext,
+  normalizeImageSource,
+} from "./image";
+export {
+  resolveHelpImageIntent,
+  findPluginHelpByKeyword,
+  getRenderableEntries,
+} from "./intent";
+export { buildHelpInfoText } from "./info";
+export { generateHelpHtml } from "./html-generator";
+export type { HelpImageIntent, HelpRenderableEntry } from "./types";
+export { ROLE_CONFIG, STOPWORDS } from "./role-config";

package/help/info.ts

@@ -0,0 +1,41 @@
+/**
+ * Build a plain-text version of the help registry.
+ *
+ * Used by AI skills: when the LLM is asked about a feature, the
+ * `get_help_info` tool returns this text instead of an image, so the
+ * model can read what's available without vision.
+ */
+
+import type { PluginHelp } from "mioku";
+import { ROLE_CONFIG } from "./role-config";
+
+/**
+ * Render the entire help registry as a single string the AI can read.
+ * Format:
+ *
+ *   === Mioku Bot 帮助信息 ===
+ *
+ *   【插件标题】描述
+ *     #cmd [角色] - 描述
+ *     ...
+ */
+export function buildHelpInfoText(
+  helpMap: Map<string, PluginHelp>,
+): string {
+  const info: string[] = ["=== Mioku Bot 帮助信息 ===\n"];
+
+  for (const [pluginName, help] of helpMap) {
+    info.push(`【${help.title || pluginName}】${help.description || ""}`);
+    if (help.commands?.length) {
+      for (const cmd of help.commands) {
+        const roleLabel = cmd.role
+          ? ` [${ROLE_CONFIG[cmd.role]?.label || cmd.role}]`
+          : "";
+        info.push(`  ${cmd.cmd}${roleLabel} - ${cmd.desc}`);
+      }
+    }
+    info.push("");
+  }
+
+  return info.join("\n");
+}

package/help/intent.ts

@@ -0,0 +1,379 @@
+/**
+ * Help intent resolution and keyword matching.
+ *
+ * `resolveHelpImageIntent` parses a chat message into one of four actions:
+ * "show overview", "show detail for plugin X", "we don't recognize this
+ * plugin", or "not a help command at all". Matching is fuzzy: we accept
+ * plugin names, titles, command aliases, and Chinese/English substrings.
+ */
+
+import type { PluginHelp } from "mioku";
+import { STOPWORDS } from "./role-config";
+import type {
+  HelpImageIntent,
+  HelpKeywordCandidate,
+  HelpRenderableEntry,
+} from "./types";
+
+/**
+ * Strip the leading command marker (`#`, `/`) and trailing punctuation,
+ * then collapse to a comparable form. Returns "" for empty input.
+ */
+function sanitizeKeyword(value: string): string {
+  return String(value || "")
+    .trim()
+    .replace(/^[#/\s]+/, "")
+    .replace(/[。.!！?？,，:：；;]+$/g, "");
+}
+
+/** Lowercase + strip everything that isn't a-z, 0-9, or CJK. */
+function normalizeForMatch(value: string): string {
+  const parts = String(value || "")
+    .toLowerCase()
+    .match(/[a-z0-9\u4e00-\u9fa5]+/gi);
+
+  return parts ? parts.join("") : "";
+}
+
+/** Pull every token of length ≥ 2 that isn't a stop-word. */
+function extractMatchTokens(text: string): string[] {
+  const rawTokens = String(text || "")
+    .toLowerCase()
+    .match(/[a-z0-9\u4e00-\u9fa5]+/gi);
+
+  if (!rawTokens) {
+    return [];
+  }
+
+  const tokens = rawTokens
+    .map((token) => normalizeForMatch(token))
+    .filter((token) => token.length >= 2)
+    .filter((token) => !STOPWORDS.has(token));
+
+  return Array.from(new Set(tokens));
+}
+
+/**
+ * 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(/^[#/]+/, "");
+  if (!value) {
+    return null;
+  }
+
+  const firstToken = value.split(/\s+/)[0];
+  if (!firstToken || /[<>]/.test(firstToken)) {
+    return null;
+  }
+
+  if (!/[a-z0-9]/i.test(firstToken)) {
+    return null;
+  }
+
+  const normalized = normalizeForMatch(firstToken);
+  if (!normalized || STOPWORDS.has(normalized)) {
+    return null;
+  }
+
+  return normalized;
+}
+
+/**
+ * Build a sorted list of `HelpRenderableEntry` from a help map. The
+ * 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.
+ */
+export function getRenderableEntries(
+  helpMap: Map<string, PluginHelp>,
+): 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 normalizedPluginName = normalizeForMatch(pluginName);
+      const normalizedTitle = normalizeForMatch(title);
+
+      const keys = new Set<string>();
+      if (normalizedPluginName) {
+        keys.add(normalizedPluginName);
+      }
+      if (normalizedTitle) {
+        keys.add(normalizedTitle);
+      }
+
+      for (const token of extractMatchTokens(title)) {
+        keys.add(token);
+      }
+
+      const commandAliases = commands
+        .map((command) => extractCommandAlias(command.cmd))
+        .filter((value): value is string => Boolean(value));
+      for (const alias of commandAliases) {
+        keys.add(alias);
+      }
+
+      return {
+        pluginName,
+        title,
+        description,
+        commands,
+        normalizedPluginName,
+        normalizedTitle,
+        matchKeys: keys,
+      };
+    })
+    .sort((a, b) => a.pluginName.localeCompare(b.pluginName, "zh-Hans-CN"));
+}
+
+/**
+ * Score a query against an entry. Higher = better match. Used to break
+ * ties between fuzzy candidates.
+ *
+ * - 58: prefix overlap (e.g. "wea" matches "weather")
+ * - 46: title containment
+ * - 34: substring overlap
+ * - 0: no match
+ */
+function scoreKeywordMatch(
+  query: string,
+  entry: HelpRenderableEntry,
+): number {
+  let score = 0;
+
+  if (
+    entry.normalizedTitle.includes(query) ||
+    query.includes(entry.normalizedTitle)
+  ) {
+    score = Math.max(
+      score,
+      46 - Math.abs(entry.normalizedTitle.length - query.length),
+    );
+  }
+
+  for (const key of entry.matchKeys) {
+    if (key.startsWith(query) || query.startsWith(key)) {
+      score = Math.max(score, 58 - Math.abs(key.length - query.length));
+      continue;
+    }
+
+    if (key.includes(query) || query.includes(key)) {
+      score = Math.max(score, 34 - Math.abs(key.length - query.length));
+    }
+  }
+
+  return Math.max(0, score);
+}
+
+/**
+ * Extract every possible plugin keyword from a chat message. Each
+ * candidate carries a `strictUnknown` flag: strict patterns (e.g. the
+ * user clearly asked about a specific plugin) should produce a
+ * "no plugin found" reply, loose patterns should silently fall through.
+ */
+function extractHelpKeywordCandidates(
+  text: string,
+): HelpKeywordCandidate[] {
+  const source = text.trim();
+  const candidates: HelpKeywordCandidate[] = [];
+
+  const addCandidate = (value: string, strictUnknown: boolean) => {
+    const keyword = sanitizeKeyword(value);
+    if (!keyword) {
+      return;
+    }
+    if (
+      !candidates.some(
+        (candidate) =>
+          candidate.keyword === keyword &&
+          candidate.strictUnknown === strictUnknown,
+      )
+    ) {
+      candidates.push({ keyword, strictUnknown });
+    }
+  };
+
+  const helpPrefixSeparated = source.match(
+    /^[#/]?\s*(?:help|帮助)(?:\s+|[:：])\s*(.+)$/i,
+  );
+  if (helpPrefixSeparated?.[1]) {
+    addCandidate(helpPrefixSeparated[1], true);
+  }
+
+  const helpPrefixMerged = source.match(
+    /^[#/]?\s*(?:help|帮助)([a-z0-9\u4e00-\u9fa5]+)$/i,
+  );
+  if (helpPrefixMerged?.[1]) {
+    addCandidate(helpPrefixMerged[1], false);
+  }
+
+  if (/^[#/]/.test(source)) {
+    return candidates;
+  }
+
+  const helpSuffixSeparated = source.match(/^(.+?)\s+(?:help|帮助)\s*$/i);
+  if (helpSuffixSeparated?.[1]) {
+    addCandidate(helpSuffixSeparated[1], true);
+  }
+
+  const helpSuffixMerged = source.match(
+    /^([a-z0-9\u4e00-\u9fa5]+)(?:help|帮助)\s*$/i,
+  );
+  if (helpSuffixMerged?.[1]) {
+    addCandidate(helpSuffixMerged[1], false);
+  }
+
+  const menuPrefix = source.match(
+    /^菜单\s*[:：]?\s*([a-z0-9\u4e00-\u9fa5]+)$/i,
+  );
+  if (menuPrefix?.[1]) {
+    addCandidate(menuPrefix[1], false);
+  }
+
+  const menuSuffix = source.match(/^([a-z0-9\u4e00-\u9fa5]+)\s*菜单\s*$/i);
+  if (menuSuffix?.[1]) {
+    addCandidate(menuSuffix[1], false);
+  }
+
+  return candidates;
+}
+
+/**
+ * Resolve a keyword to a plugin help entry. Tries exact, then
+ * start-substring, then fuzzy. Returns null if the query is too short
+ * (< 2 chars), matches a stop-word, or has ambiguous results.
+ */
+export function findPluginHelpByKeyword(
+  helpMap: Map<string, PluginHelp>,
+  keyword: string,
+): { pluginName: string; help: PluginHelp } | null {
+  const normalizedQuery = normalizeForMatch(sanitizeKeyword(keyword));
+  if (!normalizedQuery || STOPWORDS.has(normalizedQuery)) {
+    return null;
+  }
+
+  const entries = getRenderableEntries(helpMap);
+  if (entries.length === 0) {
+    return null;
+  }
+
+  const directPlugin = entries.find(
+    (entry) => entry.normalizedPluginName === normalizedQuery,
+  );
+  if (directPlugin) {
+    return {
+      pluginName: directPlugin.pluginName,
+      help: helpMap.get(directPlugin.pluginName)!,
+    };
+  }
+
+  const exactMatches = entries.filter((entry) =>
+    entry.matchKeys.has(normalizedQuery),
+  );
+  if (exactMatches.length === 1) {
+    return {
+      pluginName: exactMatches[0].pluginName,
+      help: helpMap.get(exactMatches[0].pluginName)!,
+    };
+  }
+
+  if (normalizedQuery.length < 2) {
+    return null;
+  }
+
+  const fuzzyMatches = entries
+    .map((entry) => ({
+      entry,
+      score: scoreKeywordMatch(normalizedQuery, entry),
+    }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (fuzzyMatches.length === 0) {
+    return null;
+  }
+
+  if (
+    fuzzyMatches.length > 1 &&
+    fuzzyMatches[0].score === fuzzyMatches[1].score
+  ) {
+    return null;
+  }
+
+  const resolved = fuzzyMatches[0].entry;
+  return {
+    pluginName: resolved.pluginName,
+    help: helpMap.get(resolved.pluginName)!,
+  };
+}
+
+/**
+ * Parse a chat message into a help image action.
+ *
+ * Returns:
+ * - `{ type: "overview" }` for plain `#help` / `帮助` / `菜单`
+ * - `{ type: "detail", ... }` when a plugin name is recognized
+ * - `{ type: "unknown", keyword }` when the user clearly named a plugin
+ *   but we couldn't find it (only for "strict" patterns like "X 帮助")
+ * - `{ type: "none" }` for anything else
+ */
+export function resolveHelpImageIntent(
+  text: string,
+  helpMap: Map<string, PluginHelp>,
+): HelpImageIntent {
+  const source = String(text || "").trim();
+  if (!source) {
+    return { type: "none" };
+  }
+
+  if (
+    /^[#/]/.test(source) &&
+    !/^[#/]\s*(?:help|帮助|菜单)/i.test(source)
+  ) {
+    return { type: "none" };
+  }
+
+  if (/^[#/]?\s*(?:help|帮助|菜单)\s*$/i.test(source)) {
+    return { type: "overview" };
+  }
+
+  const candidates = extractHelpKeywordCandidates(source);
+  if (candidates.length === 0) {
+    return { type: "none" };
+  }
+
+  for (const candidate of candidates) {
+    const resolved = findPluginHelpByKeyword(helpMap, candidate.keyword);
+    if (resolved) {
+      return {
+        type: "detail",
+        pluginName: resolved.pluginName,
+        pluginHelp: resolved.help,
+      };
+    }
+  }
+
+  const strictCandidate = candidates.find(
+    (candidate) => candidate.strictUnknown,
+  );
+  if (!strictCandidate) {
+    return { type: "none" };
+  }
+
+  const fallback = sanitizeKeyword(strictCandidate.keyword);
+  if (!fallback) {
+    return { type: "none" };
+  }
+
+  return {
+    type: "unknown",
+    keyword: fallback,
+  };
+}