@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/tools/platform.ts

@@ -0,0 +1,149 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds } from '../config.js';
+import { getBotForAccount } from '../bot-instance.js';
+import { getRequestAccountId } from '../request-context.js';
+
+// ========== JSON Schema ==========
+
+const PlatformApiSchema = {
+  type: 'object',
+  properties: {
+    method: {
+      type: 'string',
+      description:
+        'HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE',
+      enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+    },
+    path: {
+      type: 'string',
+      description:
+        'API 路径（不含域名），占位符需替换为实际值。' +
+        '示例：/users/@me/guilds, /guilds/{guild_id}/channels, ' +
+        '/v2/groups/{group_id}/bot_state',
+    },
+    body: {
+      type: 'object',
+      description:
+        '请求体（JSON），用于 POST/PUT/PATCH 请求。' +
+        'GET/DELETE 请求不需要此参数。',
+    },
+    query: {
+      type: 'object',
+      description:
+        'URL 查询参数（键值对），会拼接到路径后面。' +
+        '如 { "limit": "100", "after": "0" } 会拼接为 ?limit=100&after=0',
+      additionalProperties: { type: 'string' },
+    },
+  },
+  required: ['method', 'path'],
+} as const;
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function validatePath(path: string): string | null {
+  if (!path.startsWith('/')) return "path 必须以 / 开头";
+  if (path.includes('..') || path.includes('//')) return "path 不允许包含 .. 或 //";
+  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== '/') {
+    return 'path 包含非法字符';
+  }
+  return null;
+}
+
+// ========== 注册入口 ==========
+
+/**
+ * 注册 QQBot 平台统一 API 网关工具。
+ * 通过 SDK 的 bot.api 网关代理所有 QQ 开放平台 HTTP 接口 — 自动鉴权、重试、结构化错误。
+ *
+ * 覆盖范围：
+ *  - 频道（Guild/Channel/Member/Announce/Forum/Schedule）→ 见 qqbot-channel skill
+ *  - 群（Group/Member）→ 见 qqbot-group skill
+ */
+export function registerPlatformTool(api: OpenClawPluginApi): void {
+  const cfg = api.config;
+  if (!cfg) return;
+
+  const accountIds = listQQBotAccountIds(cfg);
+  if (accountIds.length === 0) return;
+
+  api.registerTool(
+    {
+      name: 'qqbot_platform_api',
+      label: 'QQBot Platform API Gateway',
+      description:
+        'QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。' +
+        '常用接口速查：' +
+        '【频道】GET /users/@me/guilds | /guilds/{guild_id}/channels | /channels/{channel_id} | ' +
+        '【群】GET /v2/groups/{group_id}/bot_state | /v2/groups/{group_id}/members/{member_id} | /v2/groups/{group_id}/info。' +
+        '更多接口和参数详情请阅读 qqbot-channel 和 qqbot-group skill。',
+      parameters: PlatformApiSchema,
+      async execute(_toolCallId, params) {
+        const p = params as {
+          method: string;
+          path: string;
+          body?: Record<string, unknown>;
+          query?: Record<string, string>;
+        };
+
+        if (!p.method) return json({ error: 'method 为必填参数' });
+        if (!p.path) return json({ error: 'path 为必填参数' });
+
+        const method = p.method.toUpperCase();
+        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+          return json({ error: `不支持的 HTTP 方法: ${method}` });
+        }
+
+        const pathError = validatePath(p.path);
+        if (pathError) return json({ error: pathError });
+
+        const accountId = getRequestAccountId();
+        if (!accountId) {
+          return json({ error: '无法获取当前请求的账号信息，此工具仅支持在消息会话中使用' });
+        }
+
+        try {
+          const bot = getBotForAccount(accountId);
+          const apiGateway = bot.api;
+
+          let data: unknown;
+          switch (method) {
+            case 'GET':
+              data = await apiGateway.get(p.path, p.query);
+              break;
+            case 'POST':
+              data = await apiGateway.post(p.path, p.body);
+              break;
+            case 'PUT':
+              data = await apiGateway.put(p.path, p.body);
+              break;
+            case 'PATCH':
+              data = await apiGateway.patch(p.path, p.body);
+              break;
+            case 'DELETE':
+              data = await apiGateway.delete(p.path);
+              break;
+          }
+
+          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 };
+          return json({
+            error: errMsg,
+            status: apiErr.httpStatus,
+            code: apiErr.bizCode,
+            path: p.path,
+          });
+        }
+      },
+    },
+    { name: 'qqbot_platform_api' },
+  );
+}

package/src/tools/remind.ts

@@ -303,4 +303,6 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
     },
     { name: "qqbot_remind" },
   );
+
 }
+

package/src/types-augment.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SDK MiddlewareState 类型扩展
+ *
+ * 通过 TypeScript module augmentation 为 SDK 的 MiddlewareState 添加
+ * 中间件填充的 well-known keys 类型声明。
+ *
+ * 这些字段由 SDK 内置中间件 / 项目自定义中间件填充：
+ * - envelope:              envelopeFormatter 中间件 → 组装后的 agentBody（字符串）
+ * - assembledBody:         envelopeFormatter format 注入函数 → 完整 AssembledBody 缓存
+ * - history:               historyBuffer 中间件 → 群历史消息列表
+ * - quote:                 quoteRef 中间件 → 引用消息信息
+ * - mention:               mentionGate 中间件 → @bot 判定结果
+ * - command:               slashCommand 中间件 → 解析的命令
+ * - processedAttachments:  attachmentProcessor 中间件 → 语音 STT、图片 URL
+ */
+import '@tencent-connect/qqbot-nodejs';
+import type { AssembledBody } from './dispatch/body-assembler.js';
+import type { ProcessedAttachments } from './middleware/attachment.js';
+
+declare module '@tencent-connect/qqbot-nodejs' {
+  interface MiddlewareState {
+    /** envelopeFormatter 输出的字符串（默认 = AssembledBody.agentBody） */
+    envelope?: string;
+    /** 项目自定义 format 注入的完整组装结果（dispatch 阶段直接消费） */
+    assembledBody?: AssembledBody;
+    /** historyBuffer 填充的群历史 */
+    history?: Array<{
+      role: string;
+      content: string;
+      senderId?: string;
+      senderName?: string;
+      timestamp?: number;
+    }>;
+    /** quoteRef 解析的引用信息 */
+    quote?: {
+      content: string;
+      senderId: string;
+      attachments?: unknown[];
+      messageId?: string;
+    };
+    /** mentionGate 判定结果 */
+    mention?: {
+      wasMentioned: boolean;
+      stripped?: string;
+    };
+    /** slashCommand 解析的命令（命令被匹配时存在） */
+    command?: {
+      name: string;
+      args: string;
+    };
+    /** attachmentProcessor 处理的附件结果 */
+    processedAttachments?: ProcessedAttachments;
+  }
+}

package/src/types.ts

@@ -25,12 +25,15 @@ export interface ResolvedQQBotAccount {
   secretSource: "config" | "file" | "env" | "none";
   /** 系统提示词 */
   systemPrompt?: string;
-  /** 图床服务器公网地址 */
-  imageServerBaseUrl?: string;
   /** 是否支持 markdown 消息（默认 true） */
   markdownSupport: boolean;
-  /** User-Agent 追加后缀（从通道级配置 channels.qqbot.userAgentSuffix 解析） */
-  userAgentSuffix?: string;
+  /** User-Agent 尾部追加内容 */
+  userAgentSuffix: string;
+  /**
+   * 单条消息最大处理时间（ms）。超时后 concurrencyGuard 会 abort 处理链，
+   * 释放锁并排空缓冲消息。0 表示不限制。默认 0（不限制）。
+   */
+  processingTimeoutMs: number;
   config: QQBotAccountConfig;
 }
 
@@ -77,7 +80,7 @@ export interface QQBotAccountConfig {
   appId?: string;
   clientSecret?: string;
   clientSecretFile?: string;
-  dmPolicy?: "open" | "pairing" | "allowlist";
+  dmPolicy?: "open" | "pairing" | "allowlist" | "disabled";
   allowFrom?: string[];
   /** 消息接收传输方式：websocket（默认）| webhook */
   transport?: TransportMode;
@@ -91,8 +94,6 @@ export interface QQBotAccountConfig {
   groups?: Record<string, GroupConfig>;
   /** 系统提示词，会添加在用户消息前面 */
   systemPrompt?: string;
-  /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
-  imageServerBaseUrl?: string;
   /** 是否支持 markdown 消息（默认 true，设为 false 可禁用） */
   markdownSupport?: boolean;
   /**
@@ -144,11 +145,36 @@ export interface QQBotAccountConfig {
    * 是否启用流式消息（默认 false）
    * 启用后，AI 的回复会以流式形式逐步显示在 QQ 聊天中，
    * 用户可以看到文字逐字出现的打字机效果。
-   * 设置为 true 可开启流式消息。
+   *
+   * 兼容布尔值和对象格式，对齐框架 schema：
+   *   - true / false         旧版布尔格式（自动转换为对象）
+   *   - { mode: "partial" }  开启（对齐 StreamingMode.partial）
+   *   - { mode: "off" }      关闭
    *
    * 注意：仅 C2C（私聊）支持流式消息 API。
    */
-  streaming?: boolean;
+  streaming?: boolean | { mode: 'partial' | 'off' };
+  /**
+   * STT (语音转文字) 配置
+   * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
+   */
+  stt?: STTChannelConfig;
+  /**
+   * 单条消息最大处理时间（毫秒）。
+   * 超时后 concurrencyGuard 会 abort 处理链（取消 LLM 调用、工具执行等），
+   * 释放并发锁并排空缓冲消息。
+   *
+   * 设为 0 表示不限制超时。默认 0（不限制）。
+   *
+   * 可通过环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS 覆盖全局默认值，
+   * 账户级配置优先级高于环境变量。
+   */
+  processingTimeoutMs?: number;
+  /**
+   * User-Agent 尾部追加内容（用于私有化部署标识等场景）
+   * 追加在 `QQBotPlugin/{version} (Node/{nodeVersion}; {os}; OpenClaw/{version})` 之后
+   */
+  userAgentSuffix?: string;
 }
 
 /**
@@ -202,6 +228,22 @@ export interface AudioFormatPolicy {
   transcodeEnabled?: boolean;
 }
 
+/**
+ * STT (语音转文字) 配置
+ */
+export interface STTChannelConfig {
+  /** 是否启用 STT（默认 true，配置了 baseUrl+apiKey 即自动启用） */
+  enabled?: boolean;
+  /** STT 服务提供商 ID（对应 models.providers 中的 key，默认 "openai"） */
+  provider?: string;
+  /** STT API 地址（如 https://api.openai.com/v1） */
+  baseUrl?: string;
+  /** STT API 密钥 */
+  apiKey?: string;
+  /** STT 模型名称（默认 "whisper-1"） */
+  model?: string;
+}
+
 /**
  * 富媒体附件
  */

package/src/utils/mention.ts

@@ -0,0 +1,52 @@
+/**
+ * Mention 工具函数
+ *
+ * @mention 检测与清理，供 channel.ts 和 gateway 层使用。
+ */
+
+export interface MentionEntry {
+  member_openid?: string;
+  id?: string;
+  user_openid?: string;
+  is_you?: boolean;
+  nickname?: string;
+  username?: string;
+}
+
+/** 清理 @mention：替换 <@openid> 为 @用户名，去除 @机器人自身 */
+export function stripMentionText(text: string, mentions?: MentionEntry[]): string {
+  if (!text || !mentions?.length) return text;
+  let cleaned = text;
+  for (const m of mentions) {
+    const openid = m.member_openid ?? m.id ?? m.user_openid;
+    if (!openid) continue;
+    if (m.is_you) {
+      cleaned = cleaned.replace(new RegExp(`<@!?${openid}>`, 'g'), '').trim();
+    } else {
+      const displayName = m.nickname ?? m.username;
+      if (displayName) {
+        cleaned = cleaned.replace(new RegExp(`<@!?${openid}>`, 'g'), `@${displayName}`);
+      }
+    }
+  }
+  return cleaned;
+}
+
+/** 检测消息是否 @了机器人 */
+export function detectWasMentioned({ eventType, mentions, content, mentionPatterns }: {
+  eventType?: string;
+  mentions?: Array<{ is_you?: boolean }>;
+  content?: string;
+  mentionPatterns?: string[];
+}): boolean {
+  if (mentions?.some((m) => m.is_you)) return true;
+  if (eventType === 'GROUP_AT_MESSAGE_CREATE') return true;
+  if (mentionPatterns?.length && content) {
+    for (const pattern of mentionPatterns) {
+      try {
+        if (new RegExp(pattern, 'i').test(content)) return true;
+      } catch { /* 无效正则，跳过 */ }
+    }
+  }
+  return false;
+}

package/src/utils/pkg-version.ts

@@ -1,64 +1,101 @@
 /**
- * 从 import.meta.url 向上遍历目录树查找 package.json 并读取 version。
- * 不依赖硬编码的 "../" 层级，无论编译输出结构如何变化都能可靠找到。
+ * 版本号获取工具。
+ *
+ * - getPackageVersion(): 插件自身版本（@tencent-connect/openclaw-qqbot）
+ * - getOpenclawVersion():  OpenClaw 框架版本降级链
+ *
+ * 兼容 CJS（tsup bundle）环境，不依赖 require.resolve。
  */
 
-import { fileURLToPath } from "node:url";
-import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
 
-/** 已定位到的 package.json 路径，避免重复遍历目录树 */
-let _resolvedPkgPath: string | null = null;
+/** OpenClaw 框架版本缓存（一次查完不再重复 io） */
+let _cachedOpenclawVersion: string | undefined;
 
-export function getPackageVersion(metaUrl?: string): string {
-  // 如果之前已定位到 package.json 路径，直接重新读取（快速路径）
-  if (_resolvedPkgPath) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(_resolvedPkgPath, "utf8"));
-      if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-        return pkg.version as string;
-      }
-    } catch {
-      // 文件可能已被删除（升级过程中），清除路径缓存，走完整查找
-      _resolvedPkgPath = null;
-    }
-  }
+declare const __PLUGIN_VERSION__: string;
 
-  // Strategy 1: 从调用者的 import.meta.url（或本模块）向上遍历找 package.json
-  const startFile = metaUrl ? fileURLToPath(metaUrl) : fileURLToPath(import.meta.url);
-  let dir = path.dirname(startFile);
-  const root = path.parse(dir).root;
+/**
+ * 获取插件自身版本号。
+ * 编译时由 tsup define 注入，零运行时 IO。
+ */
+export function getPackageVersion(): string {
+  return typeof __PLUGIN_VERSION__ !== 'undefined' ? __PLUGIN_VERSION__ : 'unknown';
+}
 
-  while (dir !== root) {
-    const candidate = path.join(dir, "package.json");
-    try {
-      if (fs.existsSync(candidate)) {
-        const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
-        // 确认是我们自己的包（避免找到其他 package.json）
-        if (pkg.name === "@tencent-connect/openclaw-qqbot" && pkg.version) {
-          _resolvedPkgPath = candidate;
-          return pkg.version as string;
-        }
-      }
-    } catch {
-      // ignore and try parent
-    }
-    dir = path.dirname(dir);
+// ── OpenClaw 框架版本 ──
+
+/**
+ * OpenClaw 框架版本降级链（优先后）。
+ *   1. PluginRuntime.version（3.31+，非 "unknown"）
+ *   2. OPENCLAW_VERSION / OPENCLAW_SERVICE_VERSION 环境变量
+ *   3. 文件系统搜索 openclaw/package.json
+ *   4. 兜底 "unknown"
+ */
+export function getOpenclawVersion(runtimeVersion?: string): string {
+  if (_cachedOpenclawVersion) return _cachedOpenclawVersion;
+
+  // 1. runtime.version（排除兜底值）
+  if (runtimeVersion && runtimeVersion !== "unknown") {
+    return _cachedOpenclawVersion = runtimeVersion;
   }
+  // 2. 环境变量
+  if (process.env.OPENCLAW_VERSION) {
+    return _cachedOpenclawVersion = process.env.OPENCLAW_VERSION;
+  }
+  if (process.env.OPENCLAW_SERVICE_VERSION) {
+    return _cachedOpenclawVersion = process.env.OPENCLAW_SERVICE_VERSION;
+  }
+  // 3. 文件系统
+  const pkgVer = readOpenclawPackageVersion();
+  if (pkgVer) return _cachedOpenclawVersion = pkgVer;
+
+  return "unknown";
+}
 
-  // Strategy 2: fallback 用 createRequire 尝试常见相对路径
+function readOpenclawPackageVersion(): string | undefined {
   try {
-    const require = createRequire(metaUrl ?? import.meta.url);
-    for (const rel of ["../../package.json", "../package.json", "./package.json"]) {
+    const dirs = searchRoots();
+    for (const dir of dirs) {
+      const pkgPath = path.join(dir, "package.json");
       try {
-        const pkg = require(rel);
-        if (pkg?.version) {
-          return pkg.version as string;
-        }
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as { name?: string; version?: string };
+        if (pkg.name === "openclaw" && pkg.version) return pkg.version;
       } catch { /* next */ }
     }
-  } catch { /* fallback */ }
+  } catch { /* fallthrough */ }
+  return undefined;
+}
 
-  return "unknown";
+function searchRoots(): string[] {
+  const roots: string[] = [];
+
+  // 从插件自身路径向上查找
+  if (typeof __filename === "string") {
+    let dir = path.dirname(__filename);
+    for (let i = 0; i < 10; i++) {
+      roots.push(dir);
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+
+  // STATE_DIR 指向的 openclaw 安装目录附近
+  for (const key of ["OPENCLAW_STATE_DIR", "CLAWDBOT_STATE_DIR", "MOLTBOT_STATE_DIR"]) {
+    const v = process.env[key];
+    if (v) {
+      roots.push(path.dirname(v));
+      roots.push(path.resolve(v, ".."));
+    }
+  }
+
+  // 常见安装路径
+  const home = process.env.HOME || process.env.USERPROFILE || "/tmp";
+  for (const name of ["openclaw", "clawdbot", "moltbot"]) {
+    roots.push(path.join(home, `.${name}`));
+  }
+  roots.push(process.cwd());
+
+  return [...new Set(roots.filter((r) => typeof r === "string" && r.length > 0))];
 }

package/src/utils/platform.ts

@@ -13,7 +13,6 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { execFile } from "node:child_process";
 
 // ============ 基础平台信息 ============
 
@@ -299,12 +298,35 @@ export function detectFfmpeg(): Promise<string | null> {
   return _ffmpegCheckPromise;
 }
 
-/** 测试可执行文件是否能正常运行 */
-function testExecutable(cmd: string, args: string[]): Promise<boolean> {
+/** 测试可执行文件是否在系统 PATH 中可访问 */
+function testExecutable(cmd: string, _args: string[]): Promise<boolean> {
   return new Promise((resolve) => {
-    execFile(cmd, args, { timeout: 5000 }, (err) => {
-      resolve(!err);
-    });
+    // 直接路径检查
+    if (path.isAbsolute(cmd) || cmd.includes("/") || cmd.includes("\\")) {
+      try {
+        fs.accessSync(cmd, fs.constants.X_OK);
+        resolve(true);
+        return;
+      } catch {
+        resolve(false);
+        return;
+      }
+    }
+
+    // PATH 查找
+    const pathEnv = process.env.PATH || "";
+    const paths = pathEnv.split(path.delimiter);
+    for (const p of paths) {
+      const cmdPath = path.join(p, cmd);
+      try {
+        fs.accessSync(cmdPath, fs.constants.X_OK);
+        resolve(true);
+        return;
+      } catch {
+        // 继续搜索
+      }
+    }
+    resolve(false);
   });
 }
 
@@ -328,7 +350,9 @@ export async function checkSilkWasmAvailable(): Promise<boolean> {
   if (_silkWasmAvailable !== null) return _silkWasmAvailable;
 
   try {
-    const { isSilk } = await import("silk-wasm");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const silkWasm = await import("silk-wasm" as string) as any;
+    const isSilk = silkWasm.isSilk;
     // 用一个空 buffer 快速测试 WASM 是否能加载
     isSilk(new Uint8Array(0));
     _silkWasmAvailable = true;

package/src/utils/plugin-logger.ts

@@ -0,0 +1,104 @@
+/**
+ * PluginLogger — 统一日志接口
+ *
+ * 默认后端为 OpenClaw 框架 logger（`runtime.logging.getChildLogger`），
+ * 运行时不可用时临时降级 console，就绪后自动切换缓存。
+ */
+
+import { getRequestContext } from "../request-context.js";
+import { tryGetQQBotRuntime } from "../runtime.js";
+
+export interface PluginLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  child(tag: string): PluginLogger;
+}
+
+export interface PluginLoggerOpts {
+  prefix?: string;
+  output?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>;
+  /** 强制 console 输出，忽略 runtime.logging（register 阶段使用） */
+  forceConsole?: boolean;
+}
+
+// ─── Console fallback ───────────────────────────────────────────────────────
+
+function consoleSink(): Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'> {
+  const C = '\x1b[36m', Y = '\x1b[33m', R = '\x1b[31m', G = '\x1b[90m', X = '\x1b[0m';
+  return {
+    debug: (m) => console.debug(`${G}[qqbot]${X}`, m),
+    info: (m) => console.log(`${C}[qqbot]${X}`, m),
+    warn: (m) => console.warn(`${Y}[qqbot]${X}`, m),
+    error: (m) => console.error(`${R}[qqbot]${X}`, m),
+  };
+}
+
+// ─── Trace metadata ─────────────────────────────────────────────────────────
+
+function enrichMeta(meta?: Record<string, unknown>): Record<string, unknown> | undefined {
+  const ctx = getRequestContext();
+  if (!ctx) return meta;
+  const trace: Record<string, unknown> = {};
+  if (ctx.accountId) trace.accountId = ctx.accountId;
+  if (ctx.messageId) trace.messageId = ctx.messageId;
+  if (ctx.openId) trace.openId = ctx.openId;
+  if (Object.keys(trace).length === 0) return meta;
+  return meta ? { ...trace, ...meta } : trace;
+}
+
+// ─── Framework bridge ───────────────────────────────────────────────────────
+
+type Sink = Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>;
+
+function frameworkSink(): Sink {
+  // 不缓存——register() 阶段 getChildLogger 可行但输出未接好。
+  // 每次使用时重新 resolve，gateway 启动后自然拿到正确 logger。
+  const resolve = (): Sink => {
+    try {
+      const r = tryGetQQBotRuntime();
+      if (r?.logging) {
+        const child = r.logging.getChildLogger({ subsystem: 'qqbot/core' }) as any;
+        return {
+          debug: child.debug?.bind(child),
+          info: child.info.bind(child),
+          warn: child.warn.bind(child),
+          error: child.error.bind(child),
+        };
+      }
+    } catch {}
+    return consoleSink();
+  };
+
+  return {
+    debug: (msg, meta) => resolve().debug?.(msg, meta),
+    info: (msg, meta) => resolve().info(msg, meta),
+    warn: (msg, meta) => resolve().warn(msg, meta),
+    error: (msg, meta) => resolve().error(msg, meta),
+  };
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+export function createPluginLogger(opts: PluginLoggerOpts = {}): PluginLogger {
+  const output = opts.output ?? (opts.forceConsole ? consoleSink() : frameworkSink());
+  const prefix = opts.prefix ?? '';
+
+  const fmt = (msg: string): string =>
+    prefix ? `${prefix} ${msg}` : msg;
+
+  const buildChild = (parentPrefix: string, tag: string): PluginLogger =>
+    createPluginLogger({
+      output,
+      prefix: parentPrefix ? `${parentPrefix}[${tag}]` : `[${tag}]`,
+    });
+
+  return {
+    info: (msg, meta) => output.info(fmt(msg), enrichMeta(meta)),
+    warn: (msg, meta) => output.warn(fmt(msg), enrichMeta(meta)),
+    error: (msg, meta) => output.error(fmt(msg), enrichMeta(meta)),
+    debug: (msg, meta) => output.debug(fmt(msg), enrichMeta(meta)),
+    child: (tag: string) => buildChild(prefix, tag),
+  };
+}