@jerryliang122/openclaw-qqbot 1.0.0 → 1.0.2

package/src/gateway/lifecycle.ts

@@ -22,7 +22,6 @@ import { createPluginLogger } from '../utils/plugin-logger.js';
 import type { PluginLogger } from '../utils/plugin-logger.js';
 import { registerGateway, unregisterGateway, getGateway } from '../outbound/outbound-service.js';
 import { saveCredentialBackup, loadCredentialBackup } from '../features/credential-backup.js';
-import { triggerUpdateCheck } from '../features/update-checker.js';
 import { syncCommandPanels } from '../features/command-panel.js';
 import { CHANNEL_APPROVAL_NATIVE_RUNTIME_CONTEXT_CAPABILITY } from '../features/approval-capability.js';
 import { cleanupTypingByAccount } from '../typing-lifecycle.js';
@@ -74,6 +73,14 @@ export async function startAccountWithCredentialRecovery(ctx: StartAccountContex
     }
   }
 
+  // 账号启动留痕：哪个账号、以什么凭证来源、什么传输模式启动了
+  // （secret 只打来源不打值）——多账号排障时定位配置实际生效形态
+  log.info(
+    `account starting accountId=${account.accountId} appId=${account.appId || '(none)'}`
+    + ` enabled=${account.enabled ?? true} secretSource=${account.secretSource ?? '?'}`
+    + ` transport=${account.config.transport}${account.config.transport === 'webhook' ? ` path=${account.config.webhook?.path ?? '(default)'}` : ''}`,
+  );
+
   // 创建 gateway 实例并注册
   const gw = new QQBotGateway(account, runtime, log);
   registerGateway(account.accountId, gw);
@@ -111,16 +118,13 @@ async function initFeatures(
   ctx: StartAccountContext,
   log: PluginLogger,
 ): Promise<void> {
-  // 1. 版本更新检测（后台预热，fire-and-forget）
-  triggerUpdateCheck(log);
-
-  // 2. 注册 "approval.native" 运行时上下文。框架的 approval bootstrap 监听此上下文，
+  // 1. 注册 "approval.native" 运行时上下文。框架的 approval bootstrap 监听此上下文，
   //    据此为该账户自动 spawn native 审批 handler（消费 exec/plugin approval 事件，
   //    回调 qqbotPlugin.approvalCapability.nativeRuntime 的 availability/presentation/transport）。
   //    账户停止时 abortSignal 触发，上下文自动注销。
   registerApprovalNativeContext(account.accountId, ctx);
 
-  // 3. 指令面板同步：把 openclaw essential 原生指令注册到 QQ Bot 指令面板（/v2/panels）。
+  // 2. 指令面板同步：把 openclaw essential 原生指令注册到 QQ Bot 指令面板（/v2/panels）。
   //    每进程每账号仅一次；失败只记日志并由 once-guard 释放等待重连重试，不影响消息收发。
   syncCommandPanels(account, ctx.cfg, log).catch((e) => {
     log?.error(`[qqbot:${account.accountId}] command panel sync error: ${e}`);

package/src/gateway/qqbot-gateway.ts

@@ -306,6 +306,25 @@ export class QQBotGateway {
     const { accountId, appId } = this.account;
     const senderName = this.account.config.name ?? appId;
 
+    // 出站成功的统一 INFO 痕迹：gateway 的 sendText/sendMedia/sendVoice/sendVideo/
+    // sendFile 与中间件对 bot.sendText 的直调全部落到这两个被包装的方法上。
+    // 此前成功发送在插件层零日志，只能靠 SDK 的 `<<< Status` 状态行倒推。
+    const MEDIA_KIND_BY_TYPE = new Map<number, string>([
+      [1, 'image'], [2, 'video'], [3, 'voice'], [4, 'file'],
+    ]);
+    const logTx = (
+      kind: string,
+      target: { scope?: string; targetId?: string; msgId?: string },
+      msg: { id?: string },
+      contentLen?: number,
+    ): void => {
+      this.log.info(
+        `[tx] sent kind=${kind} scope=${target.scope ?? '?'} target=${target.targetId ?? '?'}`
+        + ` msgId=${msg.id || '-'} passive=${target.msgId ? 'true' : 'false'}`
+        + (contentLen !== undefined ? ` contentLen=${contentLen}` : ''),
+      );
+    };
+
     const storeEntry = (msg: MessageResponse, content: string, target: { scope: string; targetId?: string }, mediaKind?: string): void => {
       // 出站 id 先登记回声表（不依赖 ext_info.ref_idx 是否返回），
       // 供 inboundGuard 识别平台回投的 bot 自身消息
@@ -352,6 +371,7 @@ export class QQBotGateway {
     const origSendText = this.bot.sendText.bind(this.bot);
     this.bot.sendText = async (target, text, ...rest) => {
       const result = await origSendText(target, text, ...rest);
+      logTx('text', target, result, text.length);
       storeEntry(result, text, target);
       return result;
     };
@@ -361,7 +381,10 @@ export class QQBotGateway {
     this.bot.sendMedia = async (params: any) => {
       const result = await origSendMedia(params);
       const msg = (result as any).message as MessageResponse | undefined;
-      if (msg) storeEntry(msg, '', params.target ?? { scope: '' }, params.mediaKind);
+      if (msg) {
+        logTx(MEDIA_KIND_BY_TYPE.get(params.fileType) ?? 'media', params.target ?? {}, msg);
+        storeEntry(msg, '', params.target ?? { scope: '' }, params.mediaKind);
+      }
       return result;
     };
 

package/src/middleware/access-control.ts

@@ -116,7 +116,9 @@ async function checkPairingMode(
     ].join('\n');
 
     ctx.log?.info?.(`[access] pairing required for ${opts.senderId}`);
-    await ctx.bot.sendText(ctx.replyTarget, reply).catch(() => {/* ignore */});
+    await ctx.bot.sendText(ctx.replyTarget, reply).catch((err: unknown) => {
+      ctx.log?.warn?.(`[access] pairing challenge send failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
     ctx.stop('access:pairing_required');
   } catch (err) {
     ctx.log?.error?.(`[access] pairing error: ${(err as Error).message}`);

package/src/middleware/secret-capture.ts

@@ -49,14 +49,16 @@ async function replyToUser(
       try {
         await ctx.bot.sendText(ctx.replyTarget, text);
         return;
-      } catch {
+      } catch (err) {
         rollback();
-        // 落到主动降级
+        ctx.log?.warn?.(`[secret] passive reply failed, falling back to proactive: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
   }
   const proactiveTarget = { scope: 'c2c' as const, targetId: ctx.message.senderId as string };
-  await ctx.bot.sendText(proactiveTarget, text).catch(() => {/* 尽力而为 */});
+  await ctx.bot.sendText(proactiveTarget, text).catch((err: unknown) => {
+    ctx.log?.warn?.(`[secret] proactive reply failed: ${err instanceof Error ? err.message : String(err)}`);
+  });
 }
 
 function formatSetFailure(name: string, result: SecretsStoreSetResult): string {

package/src/outbound/debounce.ts

@@ -13,6 +13,9 @@ const DEFAULT_WINDOW_MS = 1500;
 const DEFAULT_MAX_WAIT_MS = 8000;
 const DEFAULT_SEPARATOR = '\n\n---\n\n';
 
+// 最小结构类型：兼容 PluginLogger 与 SDK Logger（与 config-util 同款）
+type WarnSink = { warn?: (msg: string, meta?: Record<string, unknown>) => void };
+
 interface PendingDeliver {
   texts: string[];
   firstAt: number;
@@ -26,15 +29,18 @@ export class DeliverDebouncer {
   private readonly maxWaitMs: number;
   private readonly separator: string;
   private readonly flush: (targetId: string, mergedText: string) => Promise<void>;
+  private readonly log?: WarnSink;
 
   constructor(
     config: DeliverDebounceConfig | undefined,
     flush: (targetId: string, mergedText: string) => Promise<void>,
+    log?: WarnSink,
   ) {
     this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
     this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
     this.separator = config?.separator ?? DEFAULT_SEPARATOR;
     this.flush = flush;
+    this.log = log;
   }
 
   get enabled(): boolean {
@@ -60,7 +66,7 @@ export class DeliverDebouncer {
       if (Date.now() - existing.firstAt >= this.maxWaitMs) {
         await this.doFlush(targetId);
       } else {
-        existing.timer = setTimeout(() => this.doFlush(targetId), this.windowMs);
+        existing.timer = setTimeout(() => this.scheduledFlush(targetId), this.windowMs);
       }
       return;
     }
@@ -70,13 +76,24 @@ export class DeliverDebouncer {
       const pending: PendingDeliver = {
         texts: [text],
         firstAt: Date.now(),
-        timer: setTimeout(() => this.doFlush(targetId), this.windowMs),
+        timer: setTimeout(() => this.scheduledFlush(targetId), this.windowMs),
         resolve,
       };
       this.pending.set(targetId, pending);
     });
   }
 
+  /**
+   * 定时器触发的 flush：promise 被 setTimeout 回调丢弃，失败若不就地
+   * 捕获会成为 unhandledRejection——记 WARN 封口（pending.resolve 在
+   * doFlush 的 finally 中仍会执行，入队方不会被悬挂）。
+   */
+  private scheduledFlush(targetId: string): void {
+    void this.doFlush(targetId).catch((err: unknown) => {
+      this.log?.warn?.(`[debounce] timer flush failed target=${targetId}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  }
+
   private async doFlush(targetId: string): Promise<void> {
     const pending = this.pending.get(targetId);
     if (!pending) return;

package/src/outbound-adapter.ts

@@ -28,6 +28,11 @@ import { isApprovalPayload } from './features/approval-utils.js';
 import { TEXT_CHUNK_LIMIT } from './constants.js';
 import { tryGetQQBotRuntime } from './runtime.js';
 import { getAdapters } from './adapter/resolve.js';
+import { createPluginLogger } from './utils/plugin-logger.js';
+
+// 契约入口（框架直发 / message 工具 / cron announce）无调用方 logger 可传，
+// 用模块级 logger 兜底——frameworkSink 每次调用时 resolve，register 早期自动降级 console
+const alog = createPluginLogger({ prefix: '[outbound]' });
 
 export type SendTextFn = (params: {
   to: string;
@@ -178,6 +183,8 @@ export function createQQBotOutboundAdapter(params: QQBotOutboundAdapterParams):
       if (canReply && replyToId && result.error) {
         rollback();
         log?.debug?.(`[${resolvedAccountId}] rollback quota: send failed`);
+      } else if (!canReply) {
+        log?.info?.(`[${resolvedAccountId}] [quota] fallback to proactive media send: quota exhausted or no msgId`);
       }
 
       return result;
@@ -287,6 +294,7 @@ export function createQQBotChannelOutbound(params: QQBotOutboundAdapterParams =
         accountId: ctx.accountId ?? undefined,
         replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
         account,
+        log: alog,
       });
       if (result.error) throw new Error(result.error);
       return { channel: 'qqbot', messageId: result.messageId ?? '' };
@@ -302,7 +310,8 @@ export function createQQBotChannelOutbound(params: QQBotOutboundAdapterParams =
         accountId: resolvedAccountId,
         replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
         account,
-        agentId: resolveMCPAgentId(ctx.to, resolvedAccountId, ctx.cfg),
+        agentId: resolveMCPAgentId(ctx.to, resolvedAccountId, ctx.cfg, alog),
+        log: alog,
       });
       if (result.error) throw new Error(result.error);
       return { channel: 'qqbot', messageId: result.messageId ?? '' };

package/src/setup/finalize.ts

@@ -49,13 +49,14 @@ async function linkViaQrCode(cfg: OpenClawConfig, _accountId: string, prompter:
   }
 }
 
-async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter): Promise<OpenClawConfig> {
+async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
   const appIdInput = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
   const secret = await prompter.text({ message: '请输入 QQ Bot AppSecret', validate: (v) => v.trim() ? undefined : 'AppSecret 不能为空' });
   const appId = appIdInput.trim();
   const key = resolveAccountKey(cfg, appId);
   let next = applyQQBotAccountConfig(cfg, key, { appId, clientSecret: secret.trim() });
   next = applyAccountDefaults(next, key);
+  rt.log(`手动绑定完成！账户: ${key} (AppID: ${appId})`);
   await prompter.note('✔ QQ Bot 配置完成！', 'QQ Bot');
   return next;
 }
@@ -82,7 +83,7 @@ export async function finalizeQQBotSetup(params: {
   if (mode === 'qr') {
     next = await linkViaQrCode(next, accountId, params.prompter, params.runtime);
   } else if (mode === 'manual') {
-    next = await linkViaManual(next, accountId, params.prompter);
+    next = await linkViaManual(next, accountId, params.prompter, params.runtime);
   } else if (!configured) {
     await params.prompter.note('您可以稍后运行以下命令重新配置：\n  openclaw channels add', 'QQ Bot');
   }

package/src/tools/platform.ts

@@ -2,6 +2,11 @@ import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { listQQBotAccountIds } from '../config.js';
 import { getBotForAccount } from '../bot-instance.js';
 import { getRequestAccountId } from '../request-context.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+// 工具 execute 无 logger 参数；request-context 活跃期间 enrichMeta
+// 自动带上 accountId/openId/messageId
+const toolLog = createPluginLogger({ prefix: '[tool:platform]' });
 
 // ========== JSON Schema ==========
 
@@ -111,6 +116,7 @@ export function registerPlatformTool(api: OpenClawPluginApi): void {
         try {
           const bot = getBotForAccount(accountId);
           const apiGateway = bot.api;
+          const startedAt = Date.now();
 
           let data: unknown;
           switch (method) {
@@ -131,10 +137,12 @@ export function registerPlatformTool(api: OpenClawPluginApi): void {
               break;
           }
 
+          toolLog.info(`${method} ${p.path} ok (${Date.now() - startedAt}ms)`, { accountId });
           return json(data);
         } catch (err: unknown) {
           const errMsg = err instanceof Error ? err.message : String(err);
           const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
+          toolLog.warn(`${method} ${p.path} failed status=${apiErr.httpStatus ?? '?'} code=${apiErr.bizCode ?? '?'}: ${errMsg}`, { accountId });
           return json({
             error: errMsg,
             status: apiErr.httpStatus,

package/src/tools/secret-input.ts

@@ -22,8 +22,13 @@ import {
 } from '../features/secret-input-store.js';
 import { getRequestAccountId, getRequestTarget } from '../request-context.js';
 import { parseTarget } from '../outbound/target.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
 import type { InlineKeyboard, KeyboardButton } from '../types.js';
 
+// 工具 execute 无 logger 参数可传；request-context 在工具执行期间处于活跃，
+// 模块级 logger 的 enrichMeta 会自动带上 accountId/openId/messageId
+const toolLog = createPluginLogger({ prefix: '[tool:secret-input]' });
+
 // ========== JSON Schema ==========
 
 const SecretInputSchema = {
@@ -162,11 +167,14 @@ export function registerSecretInputTool(api: OpenClawPluginApi): void {
           );
         } catch (err) {
           cancelPendingSecretInput(accountId, parsed.targetId);
+          toolLog.error(`card send failed: ${err instanceof Error ? err.message : String(err)}`, { name, accountId });
           return json({
             error: `密钥输入卡片发送失败：${err instanceof Error ? err.message : String(err)}`,
           });
         }
 
+        toolLog.info(`card sent, pending registered name=${name} ttlMinutes=${DEFAULT_SECRET_INPUT_TTL_MS / 60_000}`);
+
         return json({
           ok: true,
           name,

package/src/types-plugin.ts

@@ -69,6 +69,7 @@ export interface TypingParams {
   replyToId: string;
   log?: {
     debug?: (message: string) => void;
+    warn?: (message: string) => void;
   };
 }
 

package/src/types.ts

@@ -163,11 +163,6 @@ export interface QQBotAccountConfig {
    * 禁用时：公网 URL 始终由插件先下载到本地，再以 Base64 上传（适用于 QQ 平台无法访问目标 URL 的场景）
    */
   urlDirectUpload?: boolean;
-  /**
-   * /bot-upgrade 指令返回的升级指引网址
-   * 默认: 本仓库 CHANGELOG（含各版本升级说明）
-   */
-  upgradeUrl?: string;
   /**
    * 群消息是否默认需要 @机器人才响应（默认 true）
    * 优先级低于 groups.{groupId}.requireMention 和 groups."*".requireMention

package/src/typing-lifecycle.ts

@@ -59,14 +59,17 @@ export async function startTypingWithRenewal(
 
   log?.debug?.(`[${accountId}] typing started: ${sessionKey}`);
 
-  const timer = setTimeout(async () => {
-    await handleTypingRenewal({
+  const timer = setTimeout(() => {
+    // promise 被 setTimeout 回调丢弃，失败不就地捕获会成为 unhandledRejection
+    void handleTypingRenewal({
       sessionKey,
       accountId,
       to,
       replyToId,
       log,
       sendTyping,
+    }).catch((err: unknown) => {
+      log?.warn?.(`[${accountId}] typing renewal error: ${err instanceof Error ? err.message : String(err)}`);
     });
   }, TYPING_RENEWAL_MS);
 
@@ -120,8 +123,10 @@ async function handleTypingRenewal(
   state.renewalCount += 1;
   log?.debug?.(`[${accountId}] typing renewed #${state.renewalCount}: ${sessionKey}`);
 
-  state.timer = setTimeout(async () => {
-    await handleTypingRenewal(params);
+  state.timer = setTimeout(() => {
+    void handleTypingRenewal(params).catch((err: unknown) => {
+      log?.warn?.(`[${accountId}] typing renewal error: ${err instanceof Error ? err.message : String(err)}`);
+    });
   }, TYPING_RENEWAL_MS);
 
   activeTypingSessions.set(sessionKey, state);

package/skills/qqbot-upgrade/SKILL.md

@@ -1,56 +0,0 @@
----
-name: qqbot-upgrade
-description: 将 openclaw-qqbot 插件（@jerryliang122/openclaw-qqbot）升级到最新版本。当用户要求更新 QQ 机器人插件、升级 qqbot 扩展或同步最新版时使用。
-metadata: {"openclaw":{"emoji":"⬆️","requires":{"config":["channels.qqbot"]}}}
----
-
-# QQBot 插件升级
-
-## 何时使用
-
-用户表达以下意图时，应在**本机终端**执行升级命令（不要只口头说明「去官网升级」）：
-
-- 更新 / 升级 `openclaw-qqbot` / QQBot 插件 / QQ 机器人插件
-- 同步本仓库（jerryliang122/qqbot-openclaw）最新版
-
----
-
-## 标准命令
-
-npm 包（推荐）：
-
-```bash
-openclaw plugins install @jerryliang122/openclaw-qqbot
-```
-
-指定版本：
-
-```bash
-openclaw plugins install @jerryliang122/openclaw-qqbot@<version>
-```
-
-或从 GitHub（无法访问 npm 时）：
-
-```bash
-openclaw plugins install git+https://github.com/jerryliang122/qqbot-openclaw.git
-```
-
-升级完成后重启网关使其生效：
-
-```bash
-openclaw gateway restart
-```
-
----
-
-## 前置条件
-
-- OpenClaw >= 2026.9.2（低版本框架无法加载本插件）
-- 需 **Node.js / npm** 环境可访问 npm registry（或 GitHub）
-- 从 2.x 旧版本升级：先阅读仓库 CHANGELOG 的 Breaking Changes 与配置迁移表
-
----
-
-## 执行后
-
-根据命令退出码与终端输出向用户简要汇报：成功则提示新版本号并确认网关已重启；失败则摘录关键错误并提示检查网络、npm 权限与 OpenClaw 版本。

package/src/commands/bot-upgrade.ts

@@ -1,56 +0,0 @@
-import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
-import type { ResolvedQQBotAccount } from '../types.js';
-import { getPackageVersion } from '../utils/pkg-version.js';
-import { getUpdateInfo } from '../features/update-checker.js';
-import { checkCommandAuth } from './config-util.js';
-
-const PLUGIN_VERSION = getPackageVersion();
-const DEFAULT_UPGRADE_URL = 'https://github.com/jerryliang122/qqbot-openclaw/blob/main/CHANGELOG.md';
-const GITHUB_URL = 'https://github.com/jerryliang122/qqbot-openclaw';
-
-/** /bot-upgrade — 检查更新并查看升级指引 */
-export function botUpgrade(account: ResolvedQQBotAccount): SlashCommand {
-  return {
-    name: 'bot-upgrade',
-    description: '检查更新并查看升级指引',
-    scope: 'c2c',
-    authorized: checkCommandAuth,
-    usage: [
-      '/bot-upgrade              检查是否有新版本',
-    ].join('\n'),
-    handler: async () => {
-      const url = account.config.upgradeUrl ?? DEFAULT_UPGRADE_URL;
-      const info = await getUpdateInfo();
-
-      if (info.checkedAt === 0) {
-        return '⏳ 版本检查中，请稍后再试';
-      }
-
-      if (info.error) {
-        return [
-          '❌ 主机网络访问异常，无法检查更新',
-          '',
-          `查看升级指引：[点击查看](${url})`,
-        ].join('\n');
-      }
-
-      if (!info.hasUpdate) {
-        return [
-          `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
-          '',
-          `项目地址：[GitHub](${GITHUB_URL})`,
-        ].join('\n');
-      }
-
-      return [
-        '🆕 发现新版本',
-        '',
-        `当前版本：**v${PLUGIN_VERSION}**`,
-        `最新版本：**v${info.latest}**`,
-        '',
-        `📖 升级指引：[点击查看](${url})`,
-        `🌟 GitHub 仓库：[点击前往](${GITHUB_URL})`,
-      ].join('\n');
-    },
-  };
-}

package/src/features/update-checker.ts

@@ -1,166 +0,0 @@
-/**
- * 版本检查器
- *
- * - triggerUpdateCheck(): gateway 启动时调用，后台预热缓存
- * - getUpdateInfo(): 每次实时查询 npm registry，返回最新结果
- *
- * 使用 HTTPS 直接请求 npm registry API（不依赖 npm CLI），
- * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
- */
-
-import https from "node:https";
-import { getPackageVersion } from "../utils/pkg-version.js";
-import type { PluginLogger } from '../utils/plugin-logger.js';
-
-const PKG_NAME = "@jerryliang122/openclaw-qqbot";
-const ENCODED_PKG = encodeURIComponent(PKG_NAME);
-
-const REGISTRIES = [
-  `https://registry.npmjs.org/${ENCODED_PKG}`,
-  `https://registry.npmmirror.com/${ENCODED_PKG}`,
-];
-
-let CURRENT_VERSION = getPackageVersion();
-
-export interface UpdateInfo {
-  current: string;
-  latest: string | null;
-  stable: string | null;
-  alpha: string | null;
-  hasUpdate: boolean;
-  checkedAt: number;
-  error?: string;
-}
-
-function fetchJson(url: string, timeoutMs: number): Promise<any> {
-  return new Promise((resolve, reject) => {
-    const req = https.get(url, { timeout: timeoutMs, headers: { Accept: "application/json" } }, (res) => {
-      if (res.statusCode !== 200) {
-        res.resume();
-        reject(new Error(`HTTP ${res.statusCode} from ${url}`));
-        return;
-      }
-      let data = "";
-      res.on("data", (chunk: string) => { data += chunk; });
-      res.on("end", () => {
-        try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
-      });
-    });
-    req.on("error", reject);
-    req.on("timeout", () => { req.destroy(); reject(new Error(`timeout fetching ${url}`)); });
-  });
-}
-
-async function fetchDistTags(log?: PluginLogger): Promise<Record<string, string>> {
-  for (const url of REGISTRIES) {
-    try {
-      const json = await fetchJson(url, 10_000);
-      const tags = json["dist-tags"];
-      if (tags && typeof tags === "object") return tags;
-    } catch (e: any) {
-      log?.debug(`[update-checker] ${url} failed: ${e.message}`);
-    }
-  }
-  throw new Error("all registries failed");
-}
-
-function buildUpdateInfo(tags: Record<string, string>): UpdateInfo {
-  const currentIsPrerelease = CURRENT_VERSION.includes("-");
-  const stableTag = tags.latest || null;
-  const alphaTag = tags.alpha || null;
-
-  const compareTarget = currentIsPrerelease ? alphaTag : stableTag;
-
-  const hasUpdate = typeof compareTarget === "string"
-    && compareTarget !== CURRENT_VERSION
-    && compareVersions(compareTarget, CURRENT_VERSION) > 0;
-
-  return {
-    current: CURRENT_VERSION,
-    latest: compareTarget,
-    stable: stableTag,
-    alpha: alphaTag,
-    hasUpdate,
-    checkedAt: Date.now(),
-  };
-}
-
-/**
- * Gateway 启动时调用，后台预热版本缓存。
- * log 通过闭包传递，避免模块级可变状态。
- */
-export function triggerUpdateCheck(log: PluginLogger): void {
-  getUpdateInfo(log).then((info) => {
-    if (info.hasUpdate) {
-      log.info(`[update-checker] new version available: ${info.latest} (current: ${CURRENT_VERSION})`);
-    }
-  }).catch(() => {});
-}
-
-/** 每次实时查询 npm registry */
-export async function getUpdateInfo(log?: PluginLogger): Promise<UpdateInfo> {
-  try {
-    const tags = await fetchDistTags(log);
-    return buildUpdateInfo(tags);
-  } catch (err: any) {
-    log?.debug(`[update-checker] check failed: ${err.message}`);
-    return { current: CURRENT_VERSION, latest: null, stable: null, alpha: null, hasUpdate: false, checkedAt: Date.now(), error: err.message };
-  }
-}
-
-/**
- * 检查指定版本是否存在于 npm registry
- */
-export async function checkVersionExists(version: string, pkgName?: string): Promise<boolean> {
-  const registries = pkgName ? buildRegistries(pkgName) : REGISTRIES;
-  for (const baseUrl of registries) {
-    try {
-      const url = `${baseUrl}/${version}`;
-      const json = await fetchJson(url, 10_000);
-      if (json && json.version === version) return true;
-    } catch {
-      // try next registry
-    }
-  }
-  return false;
-}
-
-function buildRegistries(pkgName: string): string[] {
-  const encoded = encodeURIComponent(pkgName);
-  return [
-    `https://registry.npmjs.org/${encoded}`,
-    `https://registry.npmmirror.com/${encoded}`,
-  ];
-}
-
-function compareVersions(a: string, b: string): number {
-  const parse = (v: string) => {
-    const clean = v.replace(/^v/, "");
-    const [main, pre] = clean.split("-", 2);
-    return { parts: main.split(".").map(Number), pre: pre || null };
-  };
-  const pa = parse(a);
-  const pb = parse(b);
-  for (let i = 0; i < 3; i++) {
-    const diff = (pa.parts[i] || 0) - (pb.parts[i] || 0);
-    if (diff !== 0) return diff;
-  }
-  if (!pa.pre && pb.pre) return 1;
-  if (pa.pre && !pb.pre) return -1;
-  if (!pa.pre && !pb.pre) return 0;
-  const aParts = pa.pre!.split(".");
-  const bParts = pb.pre!.split(".");
-  for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
-    const aP = aParts[i] ?? "";
-    const bP = bParts[i] ?? "";
-    const aNum = Number(aP);
-    const bNum = Number(bP);
-    if (!isNaN(aNum) && !isNaN(bNum)) {
-      if (aNum !== bNum) return aNum - bNum;
-    } else {
-      if (aP < bP) return -1;
-      if (aP > bP) return 1;
-    }
-  }
-  return 0;
-}