koishi-plugin-chatluna-toolbox 0.0.12 → 0.0.15

package/README.md

@@ -13,10 +13,14 @@
 ### 1) 原生工具
 - 戳一戳
 - 设置自身资料
+- 设置 QQ 头像
 - 设置群名片
+- 设置群成员专属头衔
 - 给消息添加表情
 - 撤回消息
 
+QQ 头像工具会把 HTTP/HTTPS 图片先转为 OneBot `base64://` 文件再提交，避免 OneBot 端无法访问 Koishi 临时图片地址。
+
 ### 2) XML 工具
 支持从模型输出中解析 XML 动作标签并执行：
 

package/lib/index.js

@@ -201,6 +201,10 @@ var require_lib = __commonJS({
         writable: true
       });
     }
+    function createMessageFingerprint(message, response) {
+      const type = String(message.type ?? message.role ?? "").trim().toLowerCase();
+      return `${type}:${response}`;
+    }
     function restoreDispatcher(key, dispatcher) {
       if (dispatcher.messages.push === dispatcher.patchedPush) {
         dispatcher.messages.push = dispatcher.originalPush;
@@ -212,17 +216,22 @@ var require_lib = __commonJS({
       let dispatcher = getDispatcher(messages, key);
       if (!dispatcher) {
         const listeners = /* @__PURE__ */ new Set();
-        const processedMessages = /* @__PURE__ */ new WeakSet();
+        const processedMessages = /* @__PURE__ */ new WeakMap();
         const originalPush = messages.push;
         const patchedPush = function patchedPush2(...items) {
           const result = originalPush.apply(this, items);
           for (const item of items) {
             if (!item || typeof item !== "object") continue;
-            if (processedMessages.has(item)) continue;
-            processedMessages.add(item);
             const message = item;
             const response = extractAssistantText(message);
             if (!response) continue;
+            const fingerprint = createMessageFingerprint(
+              item,
+              response
+            );
+            const previousFingerprint = processedMessages.get(item);
+            if (previousFingerprint === fingerprint) continue;
+            processedMessages.set(item, fingerprint);
             for (const listener2 of Array.from(listeners)) {
               try {
                 listener2(message);
@@ -414,8 +423,10 @@ __export(index_exports, {
   createRandomProvider: () => createRandomProvider,
   createSetGroupBanTool: () => createSetGroupBanTool,
   createSetGroupCardTool: () => createSetGroupCardTool,
+  createSetGroupSpecialTitleTool: () => createSetGroupSpecialTitleTool,
   createSetMsgEmojiTool: () => createSetMsgEmojiTool,
   createSetProfileTool: () => createSetProfileTool,
+  createSetQQAvatarTool: () => createSetQQAvatarTool,
   createUserInfoProvider: () => createUserInfoProvider,
   createXmlProcessor: () => createXmlProcessor,
   ensureOneBotSession: () => ensureOneBotSession,
@@ -434,7 +445,9 @@ __export(index_exports, {
   sendMsgEmoji: () => sendMsgEmoji,
   sendPoke: () => sendPoke,
   sendSetGroupCard: () => sendSetGroupCard,
-  sendSetProfile: () => sendSetProfile
+  sendSetGroupSpecialTitle: () => sendSetGroupSpecialTitle,
+  sendSetProfile: () => sendSetProfile,
+  sendSetQQAvatar: () => sendSetQQAvatar
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -454,8 +467,10 @@ var import_koishi2 = require("koishi");
 // src/features/native-tools/defaults.ts
 var DEFAULT_POKE_TOOL_DESCRIPTION = "\u5BF9\u6307\u5B9A\u7528\u6237\u6267\u884C\u6233\u4E00\u6233\u3002";
 var DEFAULT_SET_SELF_PROFILE_TOOL_DESCRIPTION = "\u4FEE\u6539\u81EA\u5DF1\u7684 QQ \u8D44\u6599\uFF0C\u53EF\u8BBE\u7F6E\u6635\u79F0\u3001\u7B7E\u540D\u548C\u6027\u522B\u3002";
+var DEFAULT_SET_QQ_AVATAR_TOOL_DESCRIPTION = "\u4FEE\u6539\u673A\u5668\u4EBA QQ \u5934\u50CF\u3002\u63D0\u4F9B imageUrl\uFF1BHTTP/HTTPS \u56FE\u7247\u4F1A\u5148\u7531 Koishi \u8BFB\u53D6\u5E76\u8F6C\u4E3A OneBot base64 \u6587\u4EF6\uFF0C\u907F\u514D\u4E34\u65F6 URL \u8FC7\u671F\u6216 OneBot \u7AEF\u65E0\u6CD5\u8BBF\u95EE\u3002";
 var DEFAULT_SET_GROUP_CARD_TOOL_DESCRIPTION = "\u4FEE\u6539\u7FA4\u6210\u5458\u7684\u7FA4\u6635\u79F0\u3002";
 var DEFAULT_SET_GROUP_BAN_TOOL_DESCRIPTION = "\u7528\u4E8E\u7BA1\u7406\u7FA4\u6210\u5458\u7981\u8A00\u72B6\u6001\uFF0C\u53EF\u8BBE\u7F6E\u7981\u8A00\u65F6\u957F\u6216\u89E3\u9664\u7981\u8A00\u3002";
+var DEFAULT_SET_GROUP_SPECIAL_TITLE_TOOL_DESCRIPTION = "\u4FEE\u6539\u6216\u6E05\u9664\u7FA4\u6210\u5458\u7684 QQ \u7FA4\u4E13\u5C5E\u5934\u8854\u3002";
 var DEFAULT_SET_MSG_EMOJI_TOOL_DESCRIPTION = "\u5BF9\u6307\u5B9A\u6D88\u606F\u6DFB\u52A0\u8868\u60C5\u56DE\u5E94\u3002";
 var DEFAULT_DELETE_MESSAGE_TOOL_DESCRIPTION = "\u6839\u636E\u6D88\u606F ID \u64A4\u56DE\u6307\u5B9A\u6D88\u606F\u3002";
 
@@ -473,6 +488,11 @@ var NativeToolsSchema = import_koishi2.Schema.object({
     toolName: import_koishi2.Schema.string().default("set_self_profile").description("\u5DE5\u5177\u540D\u79F0"),
     description: import_koishi2.Schema.string().default(DEFAULT_SET_SELF_PROFILE_TOOL_DESCRIPTION).description("\u5DE5\u5177\u63CF\u8FF0")
   }).description("\u4FEE\u6539\u81EA\u8EAB\u8D26\u6237\u4FE1\u606F\u5DE5\u5177").collapse(),
+  setQQAvatar: import_koishi2.Schema.object({
+    enabled: import_koishi2.Schema.boolean().default(false).description("\u6CE8\u518C ChatLuna \u5DE5\u5177\uFF1A\u4FEE\u6539\u673A\u5668\u4EBA QQ \u5934\u50CF"),
+    toolName: import_koishi2.Schema.string().default("set_qq_avatar").description("\u5DE5\u5177\u540D\u79F0"),
+    description: import_koishi2.Schema.string().default(DEFAULT_SET_QQ_AVATAR_TOOL_DESCRIPTION).description("\u5DE5\u5177\u63CF\u8FF0")
+  }).description("\u4FEE\u6539 QQ \u5934\u50CF\u5DE5\u5177").collapse(),
   setGroupCard: import_koishi2.Schema.object({
     enabled: import_koishi2.Schema.boolean().default(false).description("\u6CE8\u518C ChatLuna \u5DE5\u5177\uFF1A\u4FEE\u6539\u7FA4\u6210\u5458\u6635\u79F0"),
     toolName: import_koishi2.Schema.string().default("set_group_card").description("\u5DE5\u5177\u540D\u79F0"),
@@ -483,6 +503,11 @@ var NativeToolsSchema = import_koishi2.Schema.object({
     toolName: import_koishi2.Schema.string().default("set_group_ban").description("\u5DE5\u5177\u540D\u79F0"),
     description: import_koishi2.Schema.string().default(DEFAULT_SET_GROUP_BAN_TOOL_DESCRIPTION).description("\u5DE5\u5177\u63CF\u8FF0")
   }).description("\u7981\u8A00\u5DE5\u5177").collapse(),
+  setGroupSpecialTitle: import_koishi2.Schema.object({
+    enabled: import_koishi2.Schema.boolean().default(false).description("\u6CE8\u518C ChatLuna \u5DE5\u5177\uFF1A\u4FEE\u6539\u7FA4\u6210\u5458\u4E13\u5C5E\u5934\u8854"),
+    toolName: import_koishi2.Schema.string().default("set_group_special_title").description("\u5DE5\u5177\u540D\u79F0"),
+    description: import_koishi2.Schema.string().default(DEFAULT_SET_GROUP_SPECIAL_TITLE_TOOL_DESCRIPTION).description("\u5DE5\u5177\u63CF\u8FF0")
+  }).description("\u4FEE\u6539\u7FA4\u6210\u5458\u4E13\u5C5E\u5934\u8854\u5DE5\u5177").collapse(),
   setMsgEmoji: import_koishi2.Schema.object({
     enabled: import_koishi2.Schema.boolean().default(false).description(
       "\u6CE8\u518C ChatLuna \u5DE5\u5177\uFF1A\u7ED9\u6D88\u606F\u6DFB\u52A0\u8868\u60C5\uFF08\u9700 chatluna-character \u5F00\u542F enableMessageId\uFF0C\u4E0E XML\u5DE5\u5177 \u4E8C\u9009\u4E00\uFF0C\u8868\u60C5\u5BF9\u7167\u8868\uFF1Ahttps://bot.q.qq.com/wiki/develop/pythonsdk/model/emoji.html \uFF09"
@@ -508,6 +533,11 @@ var NativeToolsSchema = import_koishi2.Schema.object({
     toolName: "set_self_profile",
     description: DEFAULT_SET_SELF_PROFILE_TOOL_DESCRIPTION
   },
+  setQQAvatar: {
+    enabled: false,
+    toolName: "set_qq_avatar",
+    description: DEFAULT_SET_QQ_AVATAR_TOOL_DESCRIPTION
+  },
   setGroupCard: {
     enabled: false,
     toolName: "set_group_card",
@@ -518,6 +548,11 @@ var NativeToolsSchema = import_koishi2.Schema.object({
     toolName: "set_group_ban",
     description: DEFAULT_SET_GROUP_BAN_TOOL_DESCRIPTION
   },
+  setGroupSpecialTitle: {
+    enabled: false,
+    toolName: "set_group_special_title",
+    description: DEFAULT_SET_GROUP_SPECIAL_TITLE_TOOL_DESCRIPTION
+  },
   setMsgEmoji: {
     enabled: false,
     toolName: "set_msg_emoji",
@@ -706,7 +741,15 @@ var path = __toESM(require("path"));
 function createLogger(ctx, config) {
   const logger = ctx.logger("chatluna-toolbox");
   return (level, message, meta) => {
-    if (level === "debug" && !config.debugLogging) return;
+    if (level === "debug") {
+      if (!config.debugLogging) return;
+      if (meta === void 0) {
+        logger.info(message);
+        return;
+      }
+      logger.info(message, meta);
+      return;
+    }
     if (meta === void 0) {
       logger[level](message);
       return;
@@ -997,9 +1040,73 @@ function createSetGroupCardTool(deps) {
   }();
 }
 
-// src/features/native-tools/tools/set-msg-emoji.ts
+// src/features/native-tools/tools/set-group-special-title.ts
 var import_zod5 = require("zod");
 var import_tools4 = require("@langchain/core/tools");
+function resolveGroupId2(session, groupId) {
+  return groupId?.trim() || (session.guildId || "").trim() || (session.channelId || "").trim() || (session.roomId || "").trim();
+}
+async function sendSetGroupSpecialTitle(params) {
+  try {
+    const { session, userId, groupId, title, log } = params;
+    const {
+      error,
+      internal,
+      session: validatedSession
+    } = ensureOneBotSession(session);
+    if (error) return error;
+    const resolvedGroupId = resolveGroupId2(validatedSession, groupId);
+    if (!resolvedGroupId) {
+      return "Missing groupId. Provide groupId explicitly or run inside a group session.";
+    }
+    const userIdRaw = userId.trim();
+    if (!userIdRaw) return "userId is required.";
+    const titleRaw = title.trim();
+    await callOneBotAPI(
+      internal,
+      "set_group_special_title",
+      {
+        group_id: resolvedGroupId,
+        user_id: userIdRaw,
+        special_title: titleRaw
+      },
+      ["setGroupSpecialTitle"]
+    );
+    const message = titleRaw ? `\u7FA4\u4E13\u5C5E\u5934\u8854\u5DF2\u66F4\u65B0\uFF1A${userIdRaw} -> ${titleRaw}` : `\u7FA4\u4E13\u5C5E\u5934\u8854\u5DF2\u6E05\u9664\uFF1A${userIdRaw}`;
+    log?.("info", message);
+    return message;
+  } catch (error) {
+    params.log?.("warn", "set_group_special_title failed", error);
+    return `set_group_special_title failed: ${error.message}`;
+  }
+}
+function createSetGroupSpecialTitleTool(deps) {
+  const { toolName, description, protocol, log } = deps;
+  return new class extends import_tools4.StructuredTool {
+    name = toolName || "set_group_special_title";
+    description = description || DEFAULT_SET_GROUP_SPECIAL_TITLE_TOOL_DESCRIPTION;
+    schema = import_zod5.z.object({
+      groupId: import_zod5.z.string().optional().describe("Target group ID. Defaults to current session group."),
+      userId: import_zod5.z.string().min(1, "userId is required").describe("Target member user ID."),
+      title: import_zod5.z.string().describe("New special title. Use an empty string to clear it.")
+    });
+    async _call(input, _manager, runnable) {
+      const session = getSession(runnable);
+      return sendSetGroupSpecialTitle({
+        session,
+        userId: input.userId,
+        title: input.title,
+        groupId: input.groupId,
+        protocol,
+        log
+      });
+    }
+  }();
+}
+
+// src/features/native-tools/tools/set-msg-emoji.ts
+var import_zod6 = require("zod");
+var import_tools5 = require("@langchain/core/tools");
 async function sendMsgEmoji(params) {
   try {
     const { session, messageId, emojiId, log, protocol } = params;
@@ -1030,12 +1137,12 @@ async function sendMsgEmoji(params) {
 }
 function createSetMsgEmojiTool(deps) {
   const { toolName, description, log, protocol } = deps;
-  return new class extends import_tools4.StructuredTool {
+  return new class extends import_tools5.StructuredTool {
     name = toolName || "set_msg_emoji";
     description = description || DEFAULT_SET_MSG_EMOJI_TOOL_DESCRIPTION;
-    schema = import_zod5.z.object({
-      messageId: import_zod5.z.string().min(1, "message_id is required").describe("Target message ID."),
-      emojiId: import_zod5.z.string().min(1, "emoji_id is required").describe("Emoji ID to send.")
+    schema = import_zod6.z.object({
+      messageId: import_zod6.z.string().min(1, "message_id is required").describe("Target message ID."),
+      emojiId: import_zod6.z.string().min(1, "emoji_id is required").describe("Emoji ID to send.")
     });
     async _call(input, _manager, runnable) {
       const session = getSession(runnable);
@@ -1051,8 +1158,8 @@ function createSetMsgEmojiTool(deps) {
 }
 
 // src/features/native-tools/tools/profile.ts
-var import_zod6 = require("zod");
-var import_tools5 = require("@langchain/core/tools");
+var import_zod7 = require("zod");
+var import_tools6 = require("@langchain/core/tools");
 var genders = {
   unknown: "0",
   male: "1",
@@ -1079,13 +1186,13 @@ async function sendSetProfile(params) {
 }
 function createSetProfileTool(deps) {
   const { toolName, description, log, protocol } = deps;
-  return new class extends import_tools5.StructuredTool {
+  return new class extends import_tools6.StructuredTool {
     name = toolName || "set_self_profile";
     description = description || DEFAULT_SET_SELF_PROFILE_TOOL_DESCRIPTION;
-    schema = import_zod6.z.object({
-      nickname: import_zod6.z.string().min(1, "nickname is required").describe("The new nickname for the bot."),
-      signature: import_zod6.z.string().optional().describe("Optional: the new personal signature."),
-      gender: import_zod6.z.enum(["unknown", "male", "female"]).optional().describe("Optional: the new gender.")
+    schema = import_zod7.z.object({
+      nickname: import_zod7.z.string().min(1, "nickname is required").describe("The new nickname for the bot."),
+      signature: import_zod7.z.string().optional().describe("Optional: the new personal signature."),
+      gender: import_zod7.z.enum(["unknown", "male", "female"]).optional().describe("Optional: the new gender.")
     });
     async _call(input, _manager, runnable) {
       return sendSetProfile({
@@ -1100,6 +1207,84 @@ function createSetProfileTool(deps) {
   }();
 }
 
+// src/features/native-tools/tools/set-qq-avatar.ts
+var import_zod8 = require("zod");
+var import_tools7 = require("@langchain/core/tools");
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(value);
+}
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  }
+  if (typeof data === "string") return Buffer.from(data);
+  throw new Error("unsupported image response body.");
+}
+async function fetchImageAsOneBotFile(ctx, imageUrl) {
+  if (!isHttpUrl(imageUrl)) return imageUrl;
+  try {
+    const http = ctx?.http;
+    const data = typeof http?.get === "function" ? await http.get(imageUrl, { responseType: "arraybuffer" }) : await fetch(imageUrl).then(async (response) => {
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return response.arrayBuffer();
+    });
+    return `base64://${toBuffer(data).toString("base64")}`;
+  } catch (error) {
+    throw new Error(`\u65E0\u6CD5\u8BFB\u53D6\u5934\u50CF\u56FE\u7247\uFF1A${error.message}`);
+  }
+}
+function assertOneBotSuccess(result) {
+  const response = result;
+  if (!response || typeof response !== "object") return;
+  const failed = response.status === "failed" || typeof response.retcode === "number" && response.retcode !== 0;
+  if (!failed) return;
+  const reason = response.wording || response.message || response.status;
+  const retcode = typeof response.retcode === "number" ? ` (retcode: ${response.retcode})` : "";
+  throw new Error(`${reason || "OneBot returned failed"}${retcode}`);
+}
+async function sendSetQQAvatar(params) {
+  const { ctx, session, log } = params;
+  try {
+    const imageUrl = params.imageUrl.trim();
+    if (!imageUrl) return "imageUrl is required.";
+    const { error, internal } = ensureOneBotSession(session);
+    if (error) return error;
+    const file = await fetchImageAsOneBotFile(ctx, imageUrl);
+    const result = await callOneBotAPI(internal, "set_qq_avatar", { file }, [
+      "setQQAvatar"
+    ]);
+    assertOneBotSuccess(result);
+    const message = "QQ \u5934\u50CF\u5DF2\u66F4\u65B0\u3002";
+    log?.("info", message);
+    return message;
+  } catch (error) {
+    log?.("warn", "set_qq_avatar failed", error);
+    return `set_qq_avatar failed: ${error.message}`;
+  }
+}
+function createSetQQAvatarTool(deps) {
+  const { ctx, toolName, description, log } = deps;
+  return new class extends import_tools7.StructuredTool {
+    name = toolName || "set_qq_avatar";
+    description = description || DEFAULT_SET_QQ_AVATAR_TOOL_DESCRIPTION;
+    schema = import_zod8.z.object({
+      imageUrl: import_zod8.z.string().min(1, "imageUrl is required").describe("Image URL or local file path readable by the OneBot side.")
+    });
+    async _call(input, _manager, runnable) {
+      return sendSetQQAvatar({
+        session: getSession(runnable),
+        imageUrl: input.imageUrl,
+        ctx,
+        log
+      });
+    }
+  }();
+}
+
 // src/features/native-tools/register.ts
 var NATIVE_TOOL_DEFAULT_AVAILABILITY = {
   enabled: true,
@@ -1168,6 +1353,24 @@ function registerNativeTools(deps) {
     });
     log?.("info", `\u8BBE\u7F6E\u8D44\u6599\u5DE5\u5177\u5DF2\u6CE8\u518C: ${toolName}`);
   }
+  if (config.setQQAvatar.enabled) {
+    const toolName = resolveToolName(
+      config.setQQAvatar.toolName,
+      "set_qq_avatar"
+    );
+    const description = resolveToolDescription(
+      config.setQQAvatar.description,
+      DEFAULT_SET_QQ_AVATAR_TOOL_DESCRIPTION
+    );
+    plugin.registerTool(toolName, {
+      selector: () => true,
+      authorization: (session) => session?.platform === "onebot",
+      description,
+      createTool: () => createSetQQAvatarTool({ ctx, toolName, description, log }),
+      meta: createNativeToolMeta("onebot", ["profile"])
+    });
+    log?.("info", `QQ \u5934\u50CF\u5DE5\u5177\u5DF2\u6CE8\u518C: ${toolName}`);
+  }
   if (config.setGroupCard.enabled) {
     const toolName = resolveToolName(
       config.setGroupCard.toolName,
@@ -1204,6 +1407,29 @@ function registerNativeTools(deps) {
     });
     log?.("info", `\u7FA4\u6210\u5458\u7981\u8A00\u5DE5\u5177\u5DF2\u6CE8\u518C: ${toolName}`);
   }
+  if (config.setGroupSpecialTitle.enabled) {
+    const toolName = resolveToolName(
+      config.setGroupSpecialTitle.toolName,
+      "set_group_special_title"
+    );
+    const description = resolveToolDescription(
+      config.setGroupSpecialTitle.description,
+      DEFAULT_SET_GROUP_SPECIAL_TITLE_TOOL_DESCRIPTION
+    );
+    plugin.registerTool(toolName, {
+      selector: () => true,
+      authorization: (session) => session?.platform === "onebot",
+      description,
+      createTool: () => createSetGroupSpecialTitleTool({
+        toolName,
+        description,
+        log,
+        protocol
+      }),
+      meta: createNativeToolMeta("onebot", ["group"])
+    });
+    log?.("info", `\u7FA4\u4E13\u5C5E\u5934\u8854\u5DE5\u5177\u5DF2\u6CE8\u518C: ${toolName}`);
+  }
   if (config.setMsgEmoji.enabled) {
     const toolName = resolveToolName(
       config.setMsgEmoji.toolName,
@@ -1980,6 +2206,9 @@ function createGroupInfoProvider(deps) {
 }
 
 // src/features/variables/providers/group-shut-list.ts
+var GROUP_SHUT_LIST_TIMEOUT_MS = 200;
+var GROUP_SHUT_LIST_TIMEOUT_ERROR = "\u8BF7\u6C42\u7FA4\u7981\u8A00\u5217\u8868\u8D85\u65F6\u3002";
+var GROUP_SHUT_LIST_CACHE_TTL_MS = 15e3;
 function normalizeTimestamp2(raw) {
   if (raw === null || raw === void 0 || raw === "" || Number(raw) === 0)
     return null;
@@ -2001,13 +2230,6 @@ function pickFirst2(...values) {
   }
   return "";
 }
-function extractList(result) {
-  if (Array.isArray(result)) return result;
-  if (result && typeof result === "object" && Array.isArray(result.data)) {
-    return result.data;
-  }
-  return [];
-}
 function normalizeShutItem(item) {
   const userId = pickFirst2(
     item.uin,
@@ -2035,32 +2257,227 @@ function normalizeShutItem(item) {
     shutUpTimeText
   };
 }
-async function fetchGroupShutList(session, config) {
+function previewText(text, max = 180) {
+  const raw = String(text ?? "").trim();
+  if (!raw) return "";
+  return raw.length > max ? `${raw.slice(0, max)}...` : raw;
+}
+function getDataKind(data) {
+  if (Array.isArray(data)) return "array";
+  if (data === null) return "null";
+  if (data === void 0) return "undefined";
+  return typeof data;
+}
+function debug(log, message, meta) {
+  log?.("debug", message, meta);
+}
+function debugErrorMessage(error) {
+  if (error instanceof Error) return previewText(error.message);
+  return previewText(error);
+}
+function withTiming(promise) {
+  const startedAt = Date.now();
+  return promise.then((value) => ({
+    value,
+    elapsedMs: Date.now() - startedAt
+  }));
+}
+function withTimeout(promise, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(GROUP_SHUT_LIST_TIMEOUT_ERROR));
+    }, timeoutMs);
+    promise.then((value) => {
+      clearTimeout(timer);
+      resolve2(value);
+    }).catch((error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+function isOneBotEnvelope(result) {
+  return !!result && typeof result === "object" && !Array.isArray(result);
+}
+function isTimeoutError(error) {
+  return error instanceof Error && error.message === GROUP_SHUT_LIST_TIMEOUT_ERROR;
+}
+function normalizeErrorMessage(error) {
+  if (!(error instanceof Error)) return "";
+  return error.message.toLowerCase();
+}
+function shouldFallbackByError(error) {
+  if (isTimeoutError(error)) return false;
+  const message = normalizeErrorMessage(error);
+  if (!message) return false;
+  return message.includes("string required") || message.includes("number required") || message.includes("invalid") || message.includes("type") || message.includes("\u53C2\u6570");
+}
+function shouldFallbackByEnvelope(envelope) {
+  const message = `${envelope.message || ""} ${envelope.wording || ""}`.toLowerCase().trim();
+  if (!message) return false;
+  return message.includes("string") || message.includes("number") || message.includes("type") || message.includes("\u53C2\u6570");
+}
+function debugEnvelopeMeta(result) {
+  if (!isOneBotEnvelope(result)) {
+    return {
+      resultKind: Array.isArray(result) ? "array" : typeof result
+    };
+  }
+  return {
+    resultKind: "envelope",
+    status: previewText(result.status),
+    retcode: typeof result.retcode === "number" ? result.retcode : void 0,
+    dataKind: getDataKind(result.data),
+    dataLength: Array.isArray(result.data) ? result.data.length : void 0,
+    errorMessage: previewText(result.message || result.wording)
+  };
+}
+function parseShutListResult(result) {
+  if (Array.isArray(result)) {
+    return { list: result, shouldFallback: false };
+  }
+  if (!isOneBotEnvelope(result)) {
+    return { list: [], shouldFallback: false };
+  }
+  const status = String(result.status || "").toLowerCase();
+  const hasRetcode = typeof result.retcode === "number";
+  const failedByRetcode = hasRetcode && result.retcode !== 0;
+  const failedByStatus = !!status && status !== "ok";
+  if (failedByRetcode || failedByStatus) {
+    if (shouldFallbackByEnvelope(result)) {
+      return { list: [], shouldFallback: true };
+    }
+    const errorText = String(result.message || result.wording || "\u63A5\u53E3\u8C03\u7528\u5931\u8D25\u3002");
+    throw new Error(errorText);
+  }
+  if (Array.isArray(result.data)) {
+    return {
+      list: result.data,
+      shouldFallback: false
+    };
+  }
+  if (result.data == null) {
+    return { list: [], shouldFallback: false };
+  }
+  return { list: [], shouldFallback: false };
+}
+async function callGroupShutList(internal, groupId, log, preferredProtocol) {
+  debug(log, "groupShutList: request start", {
+    stage: "request.start",
+    preferredProtocol,
+    groupId,
+    groupIdType: typeof groupId
+  });
+  const { value: result, elapsedMs } = await withTiming(
+    withTimeout(
+      callOneBotAPI(
+        internal,
+        "get_group_shut_list",
+        { group_id: groupId },
+        ["getGroupShutList"]
+      ),
+      GROUP_SHUT_LIST_TIMEOUT_MS
+    )
+  );
+  debug(log, "groupShutList: request resolved", {
+    stage: "request.resolved",
+    preferredProtocol,
+    groupId,
+    groupIdType: typeof groupId,
+    elapsedMs,
+    ...debugEnvelopeMeta(result)
+  });
+  const parsed = parseShutListResult(result);
+  debug(log, "groupShutList: response parsed", {
+    stage: "response.parsed",
+    preferredProtocol,
+    groupId,
+    groupIdType: typeof groupId,
+    elapsedMs,
+    shouldFallback: parsed.shouldFallback,
+    dataLength: parsed.list.length
+  });
+  return parsed;
+}
+async function fetchGroupShutList(session, config, log) {
   const { error, internal } = ensureOneBotSession(session);
   if (error || !internal)
     throw new Error(error || "\u7F3A\u5C11 OneBot internal \u63A5\u53E3\u3002");
   const preferredProtocol = resolveOneBotProtocol(config);
   const preferredGroupId = preferredProtocol === "llbot" ? String(session.guildId) : Number(session.guildId);
   const fallbackGroupId = preferredProtocol === "llbot" ? Number(session.guildId) : String(session.guildId);
+  const canFallback = preferredGroupId !== fallbackGroupId;
+  debug(log, "groupShutList: fetch start", {
+    stage: "fetch.start",
+    preferredProtocol,
+    canFallback,
+    groupId: preferredGroupId,
+    groupIdType: typeof preferredGroupId
+  });
   try {
-    const result = await callOneBotAPI(
+    const primary = await callGroupShutList(
       internal,
-      "get_group_shut_list",
-      { group_id: preferredGroupId },
-      ["getGroupShutList"]
+      preferredGroupId,
+      log,
+      preferredProtocol
     );
-    return extractList(result);
+    if (!canFallback || !primary.shouldFallback) return primary.list;
+    debug(log, "groupShutList: trigger fallback by envelope", {
+      stage: "fallback.envelope",
+      preferredProtocol,
+      canFallback,
+      groupId: fallbackGroupId,
+      groupIdType: typeof fallbackGroupId,
+      shouldFallback: primary.shouldFallback
+    });
+    const fallback = await callGroupShutList(
+      internal,
+      fallbackGroupId,
+      log,
+      preferredProtocol
+    );
+    return fallback.list;
   } catch (error2) {
-    if (preferredGroupId === fallbackGroupId) throw error2;
-    const result = await callOneBotAPI(
+    const fallbackByError = shouldFallbackByError(error2);
+    debug(log, "groupShutList: request failed", {
+      stage: "request.error",
+      preferredProtocol,
+      canFallback,
+      errorMessage: debugErrorMessage(error2),
+      shouldFallback: fallbackByError
+    });
+    if (!canFallback || !fallbackByError) throw error2;
+    debug(log, "groupShutList: trigger fallback by error", {
+      stage: "fallback.error",
+      preferredProtocol,
+      groupId: fallbackGroupId,
+      groupIdType: typeof fallbackGroupId,
+      errorMessage: debugErrorMessage(error2)
+    });
+    const fallback = await callGroupShutList(
       internal,
-      "get_group_shut_list",
-      { group_id: fallbackGroupId },
-      ["getGroupShutList"]
+      fallbackGroupId,
+      log,
+      preferredProtocol
     );
-    return extractList(result);
+    return fallback.list;
   }
 }
+function readCache(cache, guildId, now) {
+  const entry = cache.get(guildId);
+  if (!entry) return null;
+  if (entry.expiresAt <= now) {
+    cache.delete(guildId);
+    return null;
+  }
+  return entry.value;
+}
+function writeCache(cache, guildId, value, now) {
+  cache.set(guildId, {
+    value,
+    expiresAt: now + GROUP_SHUT_LIST_CACHE_TTL_MS
+  });
+}
 function renderShutList(items) {
   if (items.length === 0) return "\u5F53\u524D\u7FA4\u6682\u65E0\u7981\u8A00\u6210\u5458\u3002";
   return items.map(
@@ -2069,18 +2486,47 @@ function renderShutList(items) {
 }
 function createGroupShutListProvider(deps) {
   const { config, log } = deps;
+  const cache = /* @__PURE__ */ new Map();
   return async (_args, _variables, configurable) => {
     const session = configurable?.session;
     if (!session) return "\u6682\u65E0\u7FA4\u7981\u8A00\u5217\u8868\u3002";
     if (!session.guildId) return "";
     if (session.platform !== "onebot")
       return "\u5F53\u524D\u5E73\u53F0\u6682\u4E0D\u652F\u6301\u67E5\u8BE2\u7FA4\u7981\u8A00\u5217\u8868\u3002";
+    const guildId = String(session.guildId);
+    const cached = readCache(cache, guildId, Date.now());
+    if (cached !== null) {
+      debug(log, "groupShutList: cache hit", {
+        stage: "cache.hit",
+        groupId: guildId,
+        groupIdType: typeof guildId
+      });
+      return cached;
+    }
+    debug(log, "groupShutList: cache miss", {
+      stage: "cache.miss",
+      groupId: guildId,
+      groupIdType: typeof guildId
+    });
     try {
-      const list = await fetchGroupShutList(session, config);
+      const list = await fetchGroupShutList(session, config, log);
       const normalized = list.map(normalizeShutItem).filter(Boolean);
-      return renderShutList(normalized);
+      const result = renderShutList(normalized);
+      writeCache(cache, guildId, result, Date.now());
+      debug(log, "groupShutList: provider success", {
+        stage: "provider.success",
+        groupId: guildId,
+        dataLength: list.length
+      });
+      return result;
     } catch (error) {
+      debug(log, "groupShutList: provider failed", {
+        stage: "provider.error",
+        groupId: guildId,
+        errorMessage: debugErrorMessage(error)
+      });
       log?.("debug", "\u7FA4\u7981\u8A00\u5217\u8868\u53D8\u91CF\u89E3\u6790\u5931\u8D25", error);
+      if (isTimeoutError(error)) return "\u5F53\u524D\u7FA4\u6682\u65E0\u7981\u8A00\u6210\u5458\u3002";
       return "\u83B7\u53D6\u7FA4\u7981\u8A00\u5217\u8868\u5931\u8D25\u3002";
     }
   };
@@ -2432,8 +2878,10 @@ function apply(ctx, config) {
   createRandomProvider,
   createSetGroupBanTool,
   createSetGroupCardTool,
+  createSetGroupSpecialTitleTool,
   createSetMsgEmojiTool,
   createSetProfileTool,
+  createSetQQAvatarTool,
   createUserInfoProvider,
   createXmlProcessor,
   ensureOneBotSession,
@@ -2452,5 +2900,7 @@ function apply(ctx, config) {
   sendMsgEmoji,
   sendPoke,
   sendSetGroupCard,
-  sendSetProfile
+  sendSetGroupSpecialTitle,
+  sendSetProfile,
+  sendSetQQAvatar
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-chatluna-toolbox",
   "description": "为 ChatLuna 提供更多原生工具、XML 工具与变量，仅支持 onebot 平台。",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
@@ -10,10 +10,10 @@
     "client"
   ],
   "license": "MIT",
-  "homepage": "https://github.com/Sor85/koishi-plugins",
+  "homepage": "https://github.com/Sor85/AAAAACAT-chatluna-plugins",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Sor85/koishi-plugins.git"
+    "url": "https://github.com/Sor85/AAAAACAT-chatluna-plugins.git"
   },
   "keywords": [
     "chatbot",
@@ -54,7 +54,7 @@
   "scripts": {
     "build": "tsup && vite build",
     "watch": "tsup --watch",
-    "typecheck": "NODE_OPTIONS=--max-old-space-size=8192 tsc --noEmit",
+    "typecheck": "NODE_OPTIONS=--max-old-space-size=8192 tsc -p tsconfig.test.json",
     "test": "vitest run"
   }
 }