@ryantest/openclaw-qqbot 0.0.3 → 1.6.6-alpha.0

package/dist/src/utils/ssrf-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 远程 URL 安全校验
+ *
+ * 下载外部资源前，确保目标地址不会命中内部网络或云元数据端点，
+ * 避免模型输出的恶意链接触达内网服务。
+ */
+/**
+ * 检查给定 IP 是否落在不可路由 / 私有网段内。
+ *
+ * 覆盖：
+ * - IPv4: 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, 0.0.0.0
+ * - IPv6: ::1, ::, fe80 (link-local), fc/fd (ULA)
+ */
+export declare function isReservedAddr(ip: string): boolean;
+/**
+ * 校验远程 URL 是否可安全请求。
+ *
+ * 规则：
+ * 1. 仅放行 http / https 协议
+ * 2. 若 URL 直接携带 IP 则即时判定
+ * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ *
+ * @throws {Error} 当 URL 指向受限地址时
+ */
+export declare function validateRemoteUrl(raw: string): Promise<void>;

package/dist/src/utils/ssrf-guard.js

@@ -0,0 +1,91 @@
+/**
+ * 远程 URL 安全校验
+ *
+ * 下载外部资源前，确保目标地址不会命中内部网络或云元数据端点，
+ * 避免模型输出的恶意链接触达内网服务。
+ */
+import net from "node:net";
+import dns from "node:dns/promises";
+/* ---------- 内网 / 保留地址判定 ---------- */
+/** IPv4 保留网段前缀（覆盖 RFC 1918、链路本地、回环等） */
+const RESERVED_V4_PREFIXES = [
+    "127.", // loopback
+    "10.", // class-A private
+    "192.168.", // class-C private
+    "169.254.", // link-local / cloud metadata
+];
+/** 172.16.0.0 – 172.31.255.255 需要单独用正则匹配 */
+const PRIVATE_172_RE = /^172\.(1[6-9]|2\d|3[01])\./;
+/**
+ * 检查给定 IP 是否落在不可路由 / 私有网段内。
+ *
+ * 覆盖：
+ * - IPv4: 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, 0.0.0.0
+ * - IPv6: ::1, ::, fe80 (link-local), fc/fd (ULA)
+ */
+export function isReservedAddr(ip) {
+    // --- IPv4 ---
+    if (ip === "0.0.0.0")
+        return true;
+    for (const pfx of RESERVED_V4_PREFIXES) {
+        if (ip.startsWith(pfx))
+            return true;
+    }
+    if (PRIVATE_172_RE.test(ip))
+        return true;
+    // --- IPv6 ---
+    const lower = ip.toLowerCase();
+    if (lower === "::1" || lower === "::")
+        return true;
+    if (lower.startsWith("fe80:"))
+        return true; // link-local
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true; // unique local
+    return false;
+}
+/* ---------- URL 合法性校验 ---------- */
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+/**
+ * 校验远程 URL 是否可安全请求。
+ *
+ * 规则：
+ * 1. 仅放行 http / https 协议
+ * 2. 若 URL 直接携带 IP 则即时判定
+ * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ *
+ * @throws {Error} 当 URL 指向受限地址时
+ */
+export async function validateRemoteUrl(raw) {
+    const url = new URL(raw);
+    if (!ALLOWED_SCHEMES.has(url.protocol)) {
+        throw new Error(`不支持的协议 "${url.protocol}"，仅允许 http/https（URL: ${raw}）`);
+    }
+    // 去掉 IPv6 方括号
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (net.isIP(host)) {
+        assertPublicAddr(host, raw);
+        return;
+    }
+    // 域名 → 解析后逐条检查
+    try {
+        const ips = await dns.resolve(host);
+        for (const ip of ips) {
+            assertPublicAddr(ip, raw, host);
+        }
+    }
+    catch (err) {
+        // 已经是我们自己抛的安全错误，继续向上传播
+        if (err instanceof Error && err.message.includes("内网"))
+            throw err;
+        // DNS 查询失败不阻塞，后续 fetch 会产生网络错误
+        console.warn(`[url-check] DNS 解析 "${host}" 失败: ${err}`);
+    }
+}
+/* ---------- 内部辅助 ---------- */
+/** 断言 IP 为公网地址，否则抛出错误 */
+function assertPublicAddr(ip, originalUrl, domain) {
+    if (!isReservedAddr(ip))
+        return;
+    const target = domain ? `域名 "${domain}" 解析到内网地址 "${ip}"` : `内网地址 "${ip}"`;
+    throw new Error(`禁止访问${target}，已拦截潜在的 SSRF 请求（URL: ${originalUrl}）`);
+}

package/node_modules/ws/index.js

@@ -1,13 +1,22 @@
 '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 = require('./lib/stream');
-WebSocket.Server = require('./lib/websocket-server');
-WebSocket.Receiver = require('./lib/receiver');
-WebSocket.Sender = require('./lib/sender');
-
+WebSocket.createWebSocketStream = createWebSocketStream;
+WebSocket.extension = extension;
+WebSocket.PerMessageDeflate = PerMessageDeflate;
+WebSocket.Receiver = Receiver;
+WebSocket.Sender = Sender;
+WebSocket.Server = WebSocketServer;
+WebSocket.subprotocol = subprotocol;
 WebSocket.WebSocket = WebSocket;
-WebSocket.WebSocketServer = WebSocket.Server;
+WebSocket.WebSocketServer = WebSocketServer;
 
 module.exports = WebSocket;

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

@@ -37,6 +37,9 @@ 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
@@ -47,16 +50,13 @@ 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, isServer, maxPayload) {
-    this._maxPayload = maxPayload | 0;
+  constructor(options) {
     this._options = options || {};
     this._threshold =
       this._options.threshold !== undefined ? this._options.threshold : 1024;
-    this._isServer = !!isServer;
+    this._maxPayload = this._options.maxPayload | 0;
+    this._isServer = !!this._options.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,
-        true,
-        this.options.maxPayload
-      );
+      const perMessageDeflate = new PerMessageDeflate({
+        ...this.options.perMessageDeflate,
+        isServer: true,
+        maxPayload: 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 (e) {
+    } catch {
       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 !== true ? opts.perMessageDeflate : {},
-      false,
-      opts.maxPayload
-    );
+    perMessageDeflate = new PerMessageDeflate({
+      ...opts.perMessageDeflate,
+      isServer: false,
+      maxPayload: 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.19.0",
+  "version": "8.20.0",
   "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
   "keywords": [
     "HyBi",
@@ -55,12 +55,13 @@
     }
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "benchmark": "^2.1.4",
     "bufferutil": "^4.0.1",
-    "eslint": "^9.0.0",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.0.1",
     "eslint-plugin-prettier": "^5.0.0",
-    "globals": "^16.0.0",
+    "globals": "^17.0.0",
     "mocha": "^8.4.0",
     "nyc": "^15.0.0",
     "prettier": "^3.0.0",

package/node_modules/ws/wrapper.mjs

@@ -1,8 +1,21 @@
 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, Receiver, Sender, WebSocket, WebSocketServer };
+export {
+  createWebSocketStream,
+  extension,
+  PerMessageDeflate,
+  Receiver,
+  Sender,
+  subprotocol,
+  WebSocket,
+  WebSocketServer
+};
+
 export default WebSocket;

package/openclaw.plugin.json

@@ -3,6 +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"],
   "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": "0.0.3",
+  "version": "1.6.6-alpha.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,32 +16,23 @@
     "scripts",
     "index.ts",
     "tsconfig.json",
-    "openclaw.plugin.json",
-    "clawdbot.plugin.json",
-    "moltbot.plugin.json"
+    "openclaw.plugin.json"
   ],
-  "clawdbot": {
-    "id": "openclaw-qqbot",
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "moltbot": {
-    "id": "openclaw-qqbot",
-    "extensions": [
-      "./index.ts"
-    ]
-  },
   "openclaw": {
     "id": "openclaw-qqbot",
     "extensions": [
-      "./index.ts"
-    ]
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "qqbot",
+      "label": "QQ Bot"
+    }
   },
   "scripts": {
     "build": "tsc || true",
     "dev": "tsc --watch",
-    "prepack": "npm install --omit=dev"
+    "prepack": "npm install --omit=dev",
+    "postinstall": "node scripts/postinstall-link-sdk.js 2>/dev/null || true"
   },
   "dependencies": {
     "mpg123-decoder": "^1.0.3",
@@ -59,8 +50,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "clawdbot": "*",
-    "moltbot": "*",
     "openclaw": "*"
   },
   "homepage": "https://github.com/tencent-connect/openclaw-qqbot",
@@ -73,4 +62,4 @@
     "silk-wasm",
     "ws"
   ]
-}
+}

package/scripts/postinstall-link-sdk.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+// When installed as an openclaw extension under ~/.openclaw/extensions/,
+// the plugin needs access to `openclaw/plugin-sdk` at runtime.
+// openclaw's jiti loader resolves this via alias by walking up from the plugin
+// path to find the openclaw package root — but ~/.openclaw/extensions/ is not
+// under the openclaw package tree, so the alias lookup fails.
+//
+// This script creates a symlink from the plugin's node_modules/openclaw to the
+// globally installed openclaw package, allowing Node's native ESM resolver
+// (used by jiti with tryNative:true for .js files) to find `openclaw/plugin-sdk`.
+
+import { existsSync, symlinkSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(__dirname, "..");
+
+// Only run when installed under an openclaw-like extensions directory
+// (supports openclaw, clawdbot, moltbot, etc.)
+if (!pluginRoot.includes("extensions")) {
+  process.exit(0);
+}
+
+const linkTarget = join(pluginRoot, "node_modules", "openclaw");
+
+// Already linked or exists
+if (existsSync(linkTarget)) {
+  process.exit(0);
+}
+
+// CLI names to try (openclaw and its aliases)
+const CLI_NAMES = ["openclaw", "clawdbot", "moltbot"];
+
+// Find the global openclaw installation
+let openclawRoot = null;
+
+// Strategy 1: npm root -g → look for any known CLI package name
+if (!openclawRoot) {
+  try {
+    const globalRoot = execSync("npm root -g", { encoding: "utf-8" }).trim();
+    for (const name of CLI_NAMES) {
+      const candidate = join(globalRoot, name);
+      if (existsSync(join(candidate, "package.json"))) {
+        openclawRoot = candidate;
+        break;
+      }
+    }
+  } catch {}
+}
+
+// Strategy 2: resolve from the CLI binary (which openclaw / clawdbot / moltbot)
+if (!openclawRoot) {
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  for (const name of CLI_NAMES) {
+    try {
+      const bin = execSync(`${whichCmd} ${name}`, { encoding: "utf-8" }).trim().split("\n")[0];
+      if (!bin) continue;
+      // Resolve symlinks to get actual binary location
+      const realBin = realpathSync(bin);
+      // bin is typically <prefix>/bin/<name> -> ../lib/node_modules/<name>/...
+      const candidate = resolve(dirname(realBin), "..", "lib", "node_modules", name);
+      if (existsSync(join(candidate, "package.json"))) {
+        openclawRoot = candidate;
+        break;
+      }
+      // Also try: binary might be inside the package itself (e.g. .../node_modules/<name>/bin/<name>)
+      const candidate2 = resolve(dirname(realBin), "..");
+      if (existsSync(join(candidate2, "package.json")) && existsSync(join(candidate2, "plugin-sdk"))) {
+        openclawRoot = candidate2;
+        break;
+      }
+    } catch {}
+  }
+}
+
+// Strategy 3: walk up from the extensions directory to find the CLI's data root,
+// then look for a global node_modules sibling
+if (!openclawRoot) {
+  // pluginRoot is like /home/user/.openclaw/extensions/openclaw-qqbot
+  // The CLI data dir is /home/user/.openclaw (or .clawdbot, .moltbot)
+  const extensionsDir = dirname(pluginRoot);
+  const dataDir = dirname(extensionsDir);
+  const dataDirName = dataDir.split("/").pop() || dataDir.split("\\").pop() || "";
+  // dataDirName is like ".openclaw" → strip the dot to get "openclaw"
+  const cliName = dataDirName.replace(/^\./, "");
+  if (cliName) {
+    try {
+      const globalRoot = execSync("npm root -g", { encoding: "utf-8" }).trim();
+      const candidate = join(globalRoot, cliName);
+      if (existsSync(join(candidate, "package.json"))) {
+        openclawRoot = candidate;
+      }
+    } catch {}
+  }
+}
+
+if (!openclawRoot) {
+  // Not fatal — plugin may work if openclaw loads it with proper alias resolution
+  // But log a warning so upgrade scripts can detect the failure
+  console.error("[postinstall-link-sdk] WARNING: could not find openclaw/clawdbot/moltbot global installation, symlink not created");
+  process.exit(0);
+}
+
+try {
+  mkdirSync(join(pluginRoot, "node_modules"), { recursive: true });
+  symlinkSync(openclawRoot, linkTarget, "junction");
+  console.log(`[postinstall-link-sdk] symlink created: node_modules/openclaw -> ${openclawRoot}`);
+} catch (e) {
+  console.error(`[postinstall-link-sdk] WARNING: symlink creation failed: ${e.message}`);
+}

package/scripts/upgrade-via-npm.ps1

@@ -95,7 +95,7 @@ Write-Host "==========================================="
 Write-Host ""
 
 # [1/3] Download and extract new version
-Write-Host "[1/3] Downloading new version..."
+Write-Host "[1/5] Downloading new version..."
 $TMPDIR_PACK = Join-Path ([System.IO.Path]::GetTempPath()) "qqbot-pack-$([guid]::NewGuid().ToString('N').Substring(0,8))"
 $EXTRACT_DIR = Join-Path ([System.IO.Path]::GetTempPath()) "qqbot-extract-$([guid]::NewGuid().ToString('N').Substring(0,8))"
 New-Item -ItemType Directory -Path $TMPDIR_PACK -Force | Out-Null
@@ -172,9 +172,108 @@ try {
     if (Test-Path $EXTRACT_DIR) { Remove-Item -Recurse -Force $EXTRACT_DIR -ErrorAction SilentlyContinue }
 }
 
-# [2/3] Replace plugin directory (in-place overwrite to avoid file-lock issues)
+# ── Preflight: validate new package before writing to extensions ──
 Write-Host ""
-Write-Host "[2/3] Replacing plugin directory..."
+Write-Host "[2/5] Preflight checks..."
+$PreflightOK = $true
+
+# (a) package.json exists and has version
+$StagingPkg = Join-Path $STAGING_DIR "package.json"
+$StagingVersion = ""
+if (-not (Test-Path $StagingPkg)) {
+    Write-Host "  [FAIL] New package missing package.json" -ForegroundColor Red
+    $PreflightOK = $false
+} else {
+    try {
+        $spkg = Get-Content $StagingPkg -Raw | ConvertFrom-Json
+        $StagingVersion = $spkg.version
+        if (-not $StagingVersion) { throw "no version" }
+        Write-Host "  [OK] Version: $StagingVersion"
+    } catch {
+        Write-Host "  [FAIL] package.json unreadable or missing version" -ForegroundColor Red
+        $PreflightOK = $false
+    }
+}
+
+# (b) Entry file exists
+$EntryFile = ""
+foreach ($candidate in @("dist\index.js", "index.js")) {
+    if (Test-Path (Join-Path $STAGING_DIR $candidate)) {
+        $EntryFile = $candidate
+        break
+    }
+}
+if (-not $EntryFile) {
+    Write-Host "  [FAIL] Missing entry file (dist\index.js or index.js)" -ForegroundColor Red
+    $PreflightOK = $false
+} else {
+    Write-Host "  [OK] Entry file: $EntryFile"
+}
+
+# (c) Core directory dist/src
+$CoreSrcDir = Join-Path $STAGING_DIR "dist" "src"
+if (-not (Test-Path $CoreSrcDir)) {
+    Write-Host "  [FAIL] Missing core directory dist\src\" -ForegroundColor Red
+    $PreflightOK = $false
+} else {
+    $CoreJsCount = (Get-ChildItem -Path $CoreSrcDir -Filter "*.js" -File -Recurse -ErrorAction SilentlyContinue | Measure-Object).Count
+    Write-Host "  [OK] dist\src\ contains $CoreJsCount JS files"
+    if ($CoreJsCount -lt 5) {
+        Write-Host "  [FAIL] JS file count too low (expected >= 5, got $CoreJsCount)" -ForegroundColor Red
+        $PreflightOK = $false
+    }
+}
+
+# (d) Critical module files
+$MissingModules = @()
+foreach ($mod in @("dist\src\gateway.js", "dist\src\api.js", "dist\src\admin-resolver.js")) {
+    if (-not (Test-Path (Join-Path $STAGING_DIR $mod))) {
+        $MissingModules += $mod
+    }
+}
+if ($MissingModules.Count -gt 0) {
+    Write-Host "  [FAIL] Missing critical modules: $($MissingModules -join ', ')" -ForegroundColor Red
+    $PreflightOK = $false
+} else {
+    Write-Host "  [OK] Critical modules intact"
+}
+
+# (e) Bundled node_modules health check
+$nmDir = Join-Path $STAGING_DIR "node_modules"
+if (Test-Path $nmDir) {
+    $BundledOK = $true
+    foreach ($dep in @("ws", "silk-wasm")) {
+        if (-not (Test-Path (Join-Path $nmDir $dep))) {
+            Write-Host "  [WARN] Bundled dependency missing: $dep" -ForegroundColor Yellow
+            $BundledOK = $false
+        }
+    }
+    if ($BundledOK) {
+        Write-Host "  [OK] Core bundled dependencies intact"
+    }
+}
+
+# (f) Version sanity check
+if ($StagingVersion) {
+    $StagingMajor = ($StagingVersion -split "\.")[0]
+    if ($StagingMajor -eq "0") {
+        Write-Host "  [WARN] Major version is 0 ($StagingVersion), may not be a production release" -ForegroundColor Yellow
+    }
+}
+
+# Preflight result
+if (-not $PreflightOK) {
+    Write-Host ""
+    Write-Host "[ABORT] Preflight checks failed, upgrade cancelled (old version unaffected)" -ForegroundColor Red
+    Remove-Item -Recurse -Force $STAGING_DIR -ErrorAction SilentlyContinue
+    exit 1
+}
+Write-Host "  [OK] All preflight checks passed"
+
+# [3/5] Replace plugin directory (in-place overwrite to avoid file-lock issues)
+Write-Host ""
+Write-Host "[3/5] Replacing plugin directory..."
+if (-not (Test-Path $EXTENSIONS_DIR)) { New-Item -ItemType Directory -Path $EXTENSIONS_DIR -Force | Out-Null }
 $TARGET_DIR = Join-Path $EXTENSIONS_DIR "openclaw-qqbot"
 
 if (-not (Test-Path $TARGET_DIR)) {
@@ -217,9 +316,50 @@ foreach ($legacyName in @("qqbot", "openclaw-qq")) {
 }
 Write-Host "  Installed to: $TARGET_DIR"
 
-# [3/3] Verify installation
+# Execute postinstall script to create openclaw SDK symlink
+# (upgrade-via-npm is pure file operation, npm install is not run, so postinstall won't trigger automatically)
+$PostinstallScript = Join-Path $TARGET_DIR "scripts" "postinstall-link-sdk.js"
+if (Test-Path $PostinstallScript) {
+    Write-Host "  Running postinstall: creating openclaw SDK symlink..."
+    try {
+        Push-Location $TARGET_DIR
+        $postOutput = & node $PostinstallScript 2>&1
+        Pop-Location
+        if ($postOutput) { Write-Host "  $postOutput" }
+    } catch {
+        Write-Host "  [WARN] postinstall script failed (non-fatal)" -ForegroundColor Yellow
+        try { Pop-Location } catch {}
+    }
+    # Verify symlink creation
+    $symlinkPath = Join-Path $TARGET_DIR "node_modules" "openclaw"
+    if (Test-Path $symlinkPath) {
+        Write-Host "  [OK] openclaw SDK symlink ready"
+    } else {
+        Write-Host "  [WARN] openclaw SDK symlink not created, attempting manual fallback..." -ForegroundColor Yellow
+        $cliDataDir = Split-Path $EXTENSIONS_DIR -Parent
+        $cliName = (Split-Path $cliDataDir -Leaf) -replace '^\.',''
+        try {
+            $globalRoot = (& npm root -g 2>$null).Trim()
+            $globalPkg = Join-Path $globalRoot $cliName
+            if ($globalRoot -and (Test-Path $globalPkg)) {
+                $nmDir = Join-Path $TARGET_DIR "node_modules"
+                if (-not (Test-Path $nmDir)) { New-Item -ItemType Directory -Path $nmDir -Force | Out-Null }
+                New-Item -ItemType Junction -Path $symlinkPath -Target $globalPkg -Force | Out-Null
+                Write-Host "  [OK] Manual symlink created: -> $globalPkg"
+            } else {
+                Write-Host "  [ERROR] Cannot locate global $cliName installation (npm root -g: $globalRoot)" -ForegroundColor Red
+            }
+        } catch {
+            Write-Host "  [ERROR] Manual symlink creation also failed: $($_.Exception.Message)" -ForegroundColor Red
+        }
+    }
+} else {
+    Write-Host "  [WARN] postinstall script not found, skipping symlink creation" -ForegroundColor Yellow
+}
+
+# [4/5] Verify installation
 Write-Host ""
-Write-Host "[3/3] Verifying installation..."
+Write-Host "[4/5] Verifying installation..."
 $NEW_VERSION = "unknown"
 try {
     $newPkgPath = Join-Path $TARGET_DIR "package.json"
@@ -249,7 +389,7 @@ if ($NoRestart) {
     exit 0
 }
 
-# [4/4] Configure appid/secret
+# [配置] Configure appid/secret
 if ($AppId -and $Secret) {
     Write-Host ""
     Write-Host "[Config] Writing qqbot channel config..."
@@ -285,11 +425,26 @@ if ($AppId -and $Secret) {
 
 # [5/5] Restart gateway
 Write-Host ""
+
+# Manual upgrade: write startup-marker before restart to prevent bot from sending duplicate notification
+if ($NEW_VERSION -and $NEW_VERSION -ne "unknown") {
+    $MarkerDir = Join-Path $HOME_DIR ".openclaw" "qqbot" "data"
+    if (-not (Test-Path $MarkerDir)) { New-Item -ItemType Directory -Path $MarkerDir -Force | Out-Null }
+    $MarkerFile = Join-Path $MarkerDir "startup-marker.json"
+    $Now = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
+    @{ version = $NEW_VERSION; startedAt = $Now; greetedAt = $Now } | ConvertTo-Json -Compress | Set-Content $MarkerFile -Encoding UTF8
+}
+
 Write-Host "[Restart] Restarting gateway..."
 try {
     & $CMD gateway restart 2>&1 | Out-Null
     if ($LASTEXITCODE -eq 0) {
         Write-Host "  Gateway restarted"
+        # Print the same upgrade greeting as bot notification (no need to push via bot in manual upgrade)
+        if ($NEW_VERSION -and $NEW_VERSION -ne "unknown") {
+            Write-Host ""
+            Write-Host "🎉 QQBot 插件已更新至 v${NEW_VERSION}，在线等候你的吩咐。"
+        }
     } else { throw "restart failed" }
 } catch {
     Write-Host "  [WARN] Gateway restart failed, please run manually: $CMD gateway restart" -ForegroundColor Yellow