@ryantest/openclaw-qqbot 1.6.6-alpha.1 → 1.6.6-alpha.3

package/dist/src/channel.d.ts

@@ -1,4 +1,4 @@
-import { type ChannelPlugin } from "openclaw/plugin-sdk";
+import { type ChannelPlugin } from "openclaw/plugin-sdk/core";
 import type { ResolvedQQBotAccount } from "./types.js";
 /** QQ Bot 单条消息文本长度上限 */
 export declare const TEXT_CHUNK_LIMIT = 5000;

package/dist/src/channel.js

@@ -1,4 +1,4 @@
-import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk";
+import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId } from "./config.js";
 import { sendText, sendMedia } from "./outbound.js";
 import { startGateway } from "./gateway.js";
@@ -40,6 +40,7 @@ export const qqbotPlugin = {
     },
     reload: { configPrefixes: ["channels.qqbot"] },
     // CLI onboarding wizard
+    // @ts-expect-error onboarding removed from ChannelPlugin type in 2026.3.23 but still supported at runtime
     onboarding: qqbotOnboardingAdapter,
     config: {
         listAccountIds: (cfg) => listQQBotAccountIds(cfg),
@@ -76,7 +77,7 @@ export const qqbotPlugin = {
         }),
         // 关键：解析 allowFrom 配置，用于命令授权
         resolveAllowFrom: ({ cfg, accountId }) => {
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             const allowFrom = account.config?.allowFrom ?? [];
             console.log(`[qqbot] resolveAllowFrom: accountId=${accountId}, allowFrom=${JSON.stringify(allowFrom)}`);
             return allowFrom.map((entry) => String(entry));
@@ -201,20 +202,21 @@ export const qqbotPlugin = {
         sendText: async ({ to, text, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendText({ to, text, accountId, replyToId, account });
             console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
+            if (result.error)
+                throw new Error(result.error);
             return {
                 channel: "qqbot",
-                messageId: result.messageId,
-                error: result.error ? new Error(result.error) : undefined,
+                messageId: result.messageId ?? "",
             };
         },
         sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
-            const account = resolveQQBotAccount(cfg, accountId);
+            const account = resolveQQBotAccount(cfg, accountId ?? undefined);
             initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
@@ -231,11 +233,11 @@ export const qqbotPlugin = {
                 catch (fallbackErr) {
                     console.error(`[qqbot:channel] sendMedia fallback text failed: ${fallbackErr}`);
                 }
+                throw new Error(result.error);
             }
             return {
                 channel: "qqbot",
-                messageId: result.messageId,
-                error: result.error ? new Error(result.error) : undefined,
+                messageId: result.messageId ?? "",
             };
         },
     },
@@ -356,8 +358,8 @@ export const qqbotPlugin = {
             enabled: account?.enabled ?? false,
             configured: Boolean(account?.appId && account?.clientSecret),
             tokenSource: account?.secretSource,
-            running: runtime?.running ?? false,
-            connected: runtime?.connected ?? false,
+            running: Boolean(runtime?.running ?? false),
+            connected: Boolean(runtime?.connected ?? false),
             lastConnectedAt: runtime?.lastConnectedAt ?? null,
             lastError: runtime?.lastError ?? null,
             lastInboundAt: runtime?.lastInboundAt ?? null,

package/dist/src/slash-commands.js

@@ -586,6 +586,38 @@ function copyScriptToTemp(scriptPath) {
         return null;
     }
 }
+const REMOTE_UPGRADE_SCRIPT_URL = "https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh";
+const REMOTE_UPGRADE_SCRIPT_URL_WIN = "https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.ps1";
+/**
+ * 从远端下载升级脚本到临时目录，返回临时脚本路径，失败返回 null。
+ */
+function downloadRemoteUpgradeScript() {
+    try {
+        const url = isWindows() ? REMOTE_UPGRADE_SCRIPT_URL_WIN : REMOTE_UPGRADE_SCRIPT_URL;
+        const ext = isWindows() ? ".ps1" : ".sh";
+        const tmpDir = path.join(getHomeDir(), ".openclaw", ".qqbot-upgrade-tmp");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        const tmpScript = path.join(tmpDir, `upgrade-via-npm${ext}`);
+        // 使用 curl 同步下载（macOS/Linux/Windows 均内置 curl）
+        execFileSync("curl", ["-fsSL", "--max-time", "15", "-o", tmpScript, url], {
+            timeout: 20_000,
+            stdio: "pipe",
+        });
+        if (!fs.existsSync(tmpScript) || fs.statSync(tmpScript).size < 100) {
+            console.error(`[qqbot] downloadRemoteUpgradeScript: downloaded file too small or missing`);
+            return null;
+        }
+        if (!isWindows()) {
+            fs.chmodSync(tmpScript, 0o755);
+        }
+        console.log(`[qqbot] downloadRemoteUpgradeScript: fetched from ${url} → ${tmpScript}`);
+        return tmpScript;
+    }
+    catch (e) {
+        console.error(`[qqbot] downloadRemoteUpgradeScript: failed: ${e.message}`);
+        return null;
+    }
+}
 /**
  * 清理临时升级脚本目录
  */
@@ -611,11 +643,16 @@ function cleanupTempScript() {
  * 安全机制：脚本会被复制到临时目录再执行，避免升级过程中插件目录被操作导致脚本自身丢失。
  */
 function fireHotUpgrade(targetVersion) {
-    const originalScriptPath = getUpgradeScriptPath();
-    if (!originalScriptPath)
+    // 优先从远端下载升级脚本，避免使用本地可能过时的版本
+    const scriptPath = downloadRemoteUpgradeScript() || (() => {
+        const local = getUpgradeScriptPath();
+        if (!local)
+            return null;
+        console.log(`[qqbot] fireHotUpgrade: remote download failed, falling back to local script: ${local}`);
+        return copyScriptToTemp(local) || local;
+    })();
+    if (!scriptPath)
         return { ok: false, reason: "no-script" };
-    // 将脚本复制到临时位置，避免升级过程中脚本被删除
-    const scriptPath = copyScriptToTemp(originalScriptPath) || originalScriptPath;
     const cli = findCli();
     if (!cli)
         return { ok: false, reason: "no-cli" };
@@ -642,7 +679,7 @@ function fireHotUpgrade(targetVersion) {
         shell = bash;
         shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])];
     }
-    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath} (original: ${originalScriptPath}), cli=${cli}, target=${targetVersion || "latest"}`);
+    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
     // 异步执行升级脚本
     execFile(shell, shellArgs, {
         timeout: 120_000,

package/dist/src/utils/chunked-upload.d.ts

@@ -28,7 +28,7 @@ export interface ChunkedUploadProgress {
 export interface ChunkedUploadOptions {
     /** 进度回调 */
     onProgress?: (progress: ChunkedUploadProgress) => void;
-    /** 最大并发数（默认 5） */
+    /** 最大并发数（默认 2） */
     maxConcurrent?: number;
     /** 日志前缀 */
     logPrefix?: string;

package/dist/src/utils/chunked-upload.js

@@ -17,7 +17,7 @@ import * as fs from "node:fs";
 import { c2cUploadPrepare, c2cUploadPartFinish, c2cCompleteUpload, groupUploadPrepare, groupUploadPartFinish, groupCompleteUpload, getAccessToken, } from "../api.js";
 import { formatFileSize } from "./file-utils.js";
 /** 分片上传并发控制：最多同时上传 N 个分片 */
-const MAX_CONCURRENT_PARTS = 5;
+const MAX_CONCURRENT_PARTS = 1;
 /** 单个分片上传超时（毫秒）— 5 分钟，兼容低带宽场景 */
 const PART_UPLOAD_TIMEOUT = 300_000;
 /** 单个分片上传最大重试次数 */

package/dist/src/utils/file-utils.d.ts

@@ -5,7 +5,7 @@
 export declare const UPLOAD_SIZE_LIMITS: Record<number, number>;
 /** 获取文件类型的中文名称；未知类型返回 "文件" */
 export declare function getFileTypeName(fileType: number): string;
-/** 获取指定文件类型的上传大小限制；未知类型默认 200MB */
+/** 获取指定文件类型的上传大小限制；未知类型默认 100MB */
 export declare function getMaxUploadSize(fileType: number): number;
 /** @deprecated 使用 getMaxUploadSize(fileType) 代替 */
 export declare const MAX_UPLOAD_SIZE: number;

package/dist/src/utils/file-utils.js

@@ -7,9 +7,9 @@ import crypto from "node:crypto";
 /** QQ Bot API 各类型文件上传大小限制（QQ 机器人上行） */
 export const UPLOAD_SIZE_LIMITS = {
     1: 30 * 1024 * 1024, // IMAGE:  30MB
-    2: 200 * 1024 * 1024, // VIDEO:  200MB
+    2: 100 * 1024 * 1024, // VIDEO:  100MB
     3: 20 * 1024 * 1024, // VOICE:  20MB
-    4: 200 * 1024 * 1024, // FILE:   200MB
+    4: 100 * 1024 * 1024, // FILE:   100MB
 };
 /** 文件类型中文名映射 */
 const FILE_TYPE_NAMES = {
@@ -22,12 +22,12 @@ const FILE_TYPE_NAMES = {
 export function getFileTypeName(fileType) {
     return FILE_TYPE_NAMES[fileType] ?? "文件";
 }
-/** 获取指定文件类型的上传大小限制；未知类型默认 200MB */
+/** 获取指定文件类型的上传大小限制；未知类型默认 100MB */
 export function getMaxUploadSize(fileType) {
-    return UPLOAD_SIZE_LIMITS[fileType] ?? 200 * 1024 * 1024;
+    return UPLOAD_SIZE_LIMITS[fileType] ?? 100 * 1024 * 1024;
 }
 /** @deprecated 使用 getMaxUploadSize(fileType) 代替 */
-export const MAX_UPLOAD_SIZE = 200 * 1024 * 1024;
+export const MAX_UPLOAD_SIZE = 100 * 1024 * 1024;
 /** 大文件阈值（超过此值发送进度提示）：5MB */
 export const LARGE_FILE_THRESHOLD = 5 * 1024 * 1024;
 /**

package/index.ts

@@ -13,7 +13,7 @@ const plugin = {
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi) {
     setQQBotRuntime(api.runtime);
-    api.registerChannel({ plugin: qqbotPlugin });
+    api.registerChannel({ plugin: qqbotPlugin as any });
     registerChannelTool(api);
     registerRemindTool(api);
   },

package/node_modules/ws/index.js

@@ -1,22 +1,13 @@
 'use strict';
 
-const createWebSocketStream = require('./lib/stream');
-const extension = require('./lib/extension');
-const PerMessageDeflate = require('./lib/permessage-deflate');
-const Receiver = require('./lib/receiver');
-const Sender = require('./lib/sender');
-const subprotocol = require('./lib/subprotocol');
 const WebSocket = require('./lib/websocket');
-const WebSocketServer = require('./lib/websocket-server');
 
-WebSocket.createWebSocketStream = createWebSocketStream;
-WebSocket.extension = extension;
-WebSocket.PerMessageDeflate = PerMessageDeflate;
-WebSocket.Receiver = Receiver;
-WebSocket.Sender = Sender;
-WebSocket.Server = WebSocketServer;
-WebSocket.subprotocol = subprotocol;
+WebSocket.createWebSocketStream = require('./lib/stream');
+WebSocket.Server = require('./lib/websocket-server');
+WebSocket.Receiver = require('./lib/receiver');
+WebSocket.Sender = require('./lib/sender');
+
 WebSocket.WebSocket = WebSocket;
-WebSocket.WebSocketServer = WebSocketServer;
+WebSocket.WebSocketServer = WebSocket.Server;
 
 module.exports = WebSocket;

package/node_modules/ws/lib/permessage-deflate.js

@@ -37,9 +37,6 @@ class PerMessageDeflate {
    *     acknowledge disabling of client context takeover
    * @param {Number} [options.concurrencyLimit=10] The number of concurrent
    *     calls to zlib
-   * @param {Boolean} [options.isServer=false] Create the instance in either
-   *     server or client mode
-   * @param {Number} [options.maxPayload=0] The maximum allowed message length
    * @param {(Boolean|Number)} [options.serverMaxWindowBits] Request/confirm the
    *     use of a custom server window size
    * @param {Boolean} [options.serverNoContextTakeover=false] Request/accept
@@ -50,13 +47,16 @@ class PerMessageDeflate {
    *     deflate
    * @param {Object} [options.zlibInflateOptions] Options to pass to zlib on
    *     inflate
+   * @param {Boolean} [isServer=false] Create the instance in either server or
+   *     client mode
+   * @param {Number} [maxPayload=0] The maximum allowed message length
    */
-  constructor(options) {
+  constructor(options, isServer, maxPayload) {
+    this._maxPayload = maxPayload | 0;
     this._options = options || {};
     this._threshold =
       this._options.threshold !== undefined ? this._options.threshold : 1024;
-    this._maxPayload = this._options.maxPayload | 0;
-    this._isServer = !!this._options.isServer;
+    this._isServer = !!isServer;
     this._deflate = null;
     this._inflate = null;
 

package/node_modules/ws/lib/websocket-server.js

@@ -293,11 +293,11 @@ class WebSocketServer extends EventEmitter {
       this.options.perMessageDeflate &&
       secWebSocketExtensions !== undefined
     ) {
-      const perMessageDeflate = new PerMessageDeflate({
-        ...this.options.perMessageDeflate,
-        isServer: true,
-        maxPayload: this.options.maxPayload
-      });
+      const perMessageDeflate = new PerMessageDeflate(
+        this.options.perMessageDeflate,
+        true,
+        this.options.maxPayload
+      );
 
       try {
         const offers = extension.parse(secWebSocketExtensions);

package/node_modules/ws/lib/websocket.js

@@ -693,7 +693,7 @@ function initAsClient(websocket, address, protocols, options) {
   } else {
     try {
       parsedUrl = new URL(address);
-    } catch {
+    } catch (e) {
       throw new SyntaxError(`Invalid URL: ${address}`);
     }
   }
@@ -755,11 +755,11 @@ function initAsClient(websocket, address, protocols, options) {
   opts.timeout = opts.handshakeTimeout;
 
   if (opts.perMessageDeflate) {
-    perMessageDeflate = new PerMessageDeflate({
-      ...opts.perMessageDeflate,
-      isServer: false,
-      maxPayload: opts.maxPayload
-    });
+    perMessageDeflate = new PerMessageDeflate(
+      opts.perMessageDeflate !== true ? opts.perMessageDeflate : {},
+      false,
+      opts.maxPayload
+    );
     opts.headers['Sec-WebSocket-Extensions'] = format({
       [PerMessageDeflate.extensionName]: perMessageDeflate.offer()
     });

package/node_modules/ws/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ws",
-  "version": "8.20.0",
+  "version": "8.19.0",
   "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
   "keywords": [
     "HyBi",
@@ -55,13 +55,12 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
     "benchmark": "^2.1.4",
     "bufferutil": "^4.0.1",
-    "eslint": "^10.0.1",
+    "eslint": "^9.0.0",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.0.0",
-    "globals": "^17.0.0",
+    "globals": "^16.0.0",
     "mocha": "^8.4.0",
     "nyc": "^15.0.0",
     "prettier": "^3.0.0",

package/node_modules/ws/wrapper.mjs

@@ -1,21 +1,8 @@
 import createWebSocketStream from './lib/stream.js';
-import extension from './lib/extension.js';
-import PerMessageDeflate from './lib/permessage-deflate.js';
 import Receiver from './lib/receiver.js';
 import Sender from './lib/sender.js';
-import subprotocol from './lib/subprotocol.js';
 import WebSocket from './lib/websocket.js';
 import WebSocketServer from './lib/websocket-server.js';
 
-export {
-  createWebSocketStream,
-  extension,
-  PerMessageDeflate,
-  Receiver,
-  Sender,
-  subprotocol,
-  WebSocket,
-  WebSocketServer
-};
-
+export { createWebSocketStream, Receiver, Sender, WebSocket, WebSocketServer };
 export default WebSocket;

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "extensions": ["./dist/index.js"],
+  "extensions": ["./preload.cjs"],
   "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryantest/openclaw-qqbot",
-  "version": "1.6.6-alpha.1",
+  "version": "1.6.6-alpha.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,13 +15,14 @@
     "skills",
     "scripts",
     "index.ts",
+    "preload.cjs",
     "tsconfig.json",
     "openclaw.plugin.json"
   ],
   "openclaw": {
     "id": "openclaw-qqbot",
     "extensions": [
-      "./dist/index.js"
+      "./preload.cjs"
     ],
     "channel": {
       "id": "qqbot",
@@ -30,6 +31,7 @@
   },
   "scripts": {
     "build": "tsc || true",
+    "postbuild": "node -e \"const fs=require('fs'),p=require('path'),ext=p.join(require('os').homedir(),'.openclaw/extensions/openclaw-qqbot');if(fs.existsSync(ext)&&!fs.lstatSync(ext).isSymbolicLink()){const d=p.join(ext,'dist'),pr=p.join(ext,'preload.cjs');fs.cpSync('dist',d,{recursive:true});fs.copyFileSync('preload.cjs',pr);console.log('[postbuild] synced to',ext)}\"",
     "dev": "tsc --watch",
     "prepack": "npm install --omit=dev",
     "postinstall": "node scripts/postinstall-link-sdk.js 2>/dev/null || true"

package/preload.cjs

@@ -0,0 +1,33 @@
+/**
+ * 插件预加载入口（CJS 格式）。
+ *
+ * openclaw 框架通过 require() 加载插件，因此需要 .cjs 后缀
+ * 确保在 "type": "module" 的 package 中也能被正确 require()。
+ *
+ * 在 require 真正的插件代码（依赖 openclaw/plugin-sdk）之前，
+ * 先同步确保 node_modules/openclaw symlink 存在。
+ */
+"use strict";
+
+const { ensurePluginSdkSymlink } = require("./scripts/link-sdk-core.cjs");
+
+// 1) 同步创建 symlink
+ensurePluginSdkSymlink(__dirname, "[preload]");
+
+// 2) Node 22 原生支持 CJS require() 加载 ESM 模块
+//    同步加载插件入口，确保框架同步检查 register/activate 时能找到
+const _pluginModule = require("./dist/index.js");
+
+// 3) 展平 default export：框架检查 register/activate 在顶级属性
+//    ESM 的 export default 在 require() 后变成 { default: plugin, ... }
+const _default = _pluginModule.default;
+const merged = Object.assign({}, _pluginModule);
+if (_default && typeof _default === "object") {
+  for (const key of Object.keys(_default)) {
+    if (!(key in merged)) {
+      merged[key] = _default[key];
+    }
+  }
+}
+
+module.exports = merged;

package/scripts/link-sdk-core.cjs

@@ -0,0 +1,185 @@
+/**
+ * 公共模块：openclaw plugin-sdk symlink 创建逻辑。
+ *
+ * 被 preload.cjs 和 postinstall-link-sdk.js 共同使用，避免代码重复。
+ * 必须是 CJS 格式，因为 preload.cjs 需要同步 require()。
+ */
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { execSync } = require("node:child_process");
+
+const CLI_NAMES = ["openclaw", "clawdbot", "moltbot"];
+
+/**
+ * 比较版本号是否 >= target
+ * Strip pre-release suffix (e.g. "2026.3.23-2" → "2026.3.23")
+ */
+function compareVersionGte(version, target) {
+  const parts = version.replace(/-.*$/, "").split(".").map(Number);
+  for (let i = 0; i < target.length; i++) {
+    const v = parts[i] || 0;
+    const t = target[i];
+    if (v > t) return true;
+    if (v < t) return false;
+  }
+  return true;
+}
+
+/**
+ * 检查 openclaw 版本是否 >= 2026.3.22（需要 symlink 的最低版本）。
+ * 如果无法检测版本，返回 true（保守策略：宁可多创建也不遗漏）。
+ */
+function isOpenclawVersionRequiresSymlink() {
+  const REQUIRED = [2026, 3, 22];
+
+  // Strategy 1: 从全局 openclaw 的 package.json 读取版本
+  try {
+    const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+    for (const name of CLI_NAMES) {
+      const pkgPath = path.join(globalRoot, name, "package.json");
+      if (fs.existsSync(pkgPath)) {
+        const v = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
+        if (v) return compareVersionGte(v, REQUIRED);
+      }
+    }
+  } catch {}
+
+  // Strategy 2: 从 CLI 命令获取版本
+  for (const name of CLI_NAMES) {
+    try {
+      const out = execSync(`${name} --version`, {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      const m = out.match(/(\d+\.\d+\.\d+)/);
+      if (m) return compareVersionGte(m[1], REQUIRED);
+    } catch {}
+  }
+
+  return true;
+}
+
+/**
+ * 查找全局 openclaw 安装路径。
+ * 三种策略依次尝试：npm root -g、which <cli>、从 extensions 目录推断。
+ */
+function findOpenclawRoot(pluginRoot) {
+  // Strategy 1: npm root -g
+  try {
+    const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+    for (const name of CLI_NAMES) {
+      const candidate = path.join(globalRoot, name);
+      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    }
+  } catch {}
+
+  // Strategy 2: which <cli>
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  for (const name of CLI_NAMES) {
+    try {
+      const bin = execSync(`${whichCmd} ${name}`, {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim().split("\n")[0];
+      if (!bin) continue;
+      const realBin = fs.realpathSync(bin);
+      const c1 = path.resolve(path.dirname(realBin), "..", "lib", "node_modules", name);
+      if (fs.existsSync(path.join(c1, "package.json"))) return c1;
+      const c2 = path.resolve(path.dirname(realBin), "..");
+      if (fs.existsSync(path.join(c2, "package.json")) && fs.existsSync(path.join(c2, "plugin-sdk"))) return c2;
+    } catch {}
+  }
+
+  // Strategy 3: 从 extensions 目录推断
+  const extensionsDir = path.dirname(pluginRoot);
+  const dataDir = path.dirname(extensionsDir);
+  const dataDirName = path.basename(dataDir);
+  const cliName = dataDirName.replace(/^\./, "");
+  if (cliName) {
+    try {
+      const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
+      const candidate = path.join(globalRoot, cliName);
+      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
+    } catch {}
+  }
+
+  return null;
+}
+
+/**
+ * 验证现有 node_modules/openclaw 是否完整可用。
+ *
+ * openclaw plugins install 可能安装了不完整的 peerDep 副本
+ * （只有 dist/plugin-sdk/index.js，缺少 core.js 等子模块），覆盖了之前的 symlink。
+ *
+ * 判断标准：
+ * - symlink → 只需确认 dist/plugin-sdk 目录存在（target 有完整文件树）
+ * - 真实目录 → 必须检查 dist/plugin-sdk/core.js 是否存在
+ */
+function isLinkValid(linkTarget) {
+  try {
+    const stat = fs.lstatSync(linkTarget);
+    if (stat.isSymbolicLink()) {
+      return fs.existsSync(path.join(linkTarget, "dist", "plugin-sdk"))
+        || fs.existsSync(path.join(linkTarget, "plugin-sdk"));
+    }
+    // 真实目录
+    return fs.existsSync(path.join(linkTarget, "dist", "plugin-sdk", "core.js"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 确保 plugin-sdk symlink 存在。
+ *
+ * @param {string} pluginRoot - 插件根目录路径
+ * @param {string} [tag="[link-sdk]"] - 日志前缀
+ * @returns {boolean} true 如果 symlink 已存在或成功创建
+ */
+function ensurePluginSdkSymlink(pluginRoot, tag) {
+  tag = tag || "[link-sdk]";
+  try {
+    if (!pluginRoot.includes("extensions")) return true;
+
+    const linkTarget = path.join(pluginRoot, "node_modules", "openclaw");
+
+    if (fs.existsSync(linkTarget)) {
+      if (isLinkValid(linkTarget)) return true;
+      // 无效/不完整 → 删除后重建
+      try {
+        fs.rmSync(linkTarget, { recursive: true, force: true });
+        console.log(`${tag} removed incomplete node_modules/openclaw`);
+      } catch {}
+    }
+
+    if (!isOpenclawVersionRequiresSymlink()) return true;
+
+    const openclawRoot = findOpenclawRoot(pluginRoot);
+    if (!openclawRoot) {
+      console.error(`${tag} WARNING: could not find openclaw global installation, symlink not created`);
+      return false;
+    }
+
+    fs.mkdirSync(path.join(pluginRoot, "node_modules"), { recursive: true });
+    fs.symlinkSync(openclawRoot, linkTarget, "junction");
+    console.log(`${tag} symlink created: node_modules/openclaw -> ${openclawRoot}`);
+    return true;
+  } catch (e) {
+    console.error(`${tag} WARNING: symlink check failed: ${e.message || e}`);
+    return false;
+  }
+}
+
+module.exports = {
+  CLI_NAMES,
+  compareVersionGte,
+  isOpenclawVersionRequiresSymlink,
+  findOpenclawRoot,
+  isLinkValid,
+  ensurePluginSdkSymlink,
+};