@tencent-connect/openclaw-qqbot 1.6.4 → 1.6.5-alpha.0

package/dist/src/request-context.d.ts

@@ -0,0 +1,18 @@
+export interface RequestContext {
+    /** 投递目标地址，如 qqbot:c2c:xxx 或 qqbot:group:xxx */
+    target: string;
+}
+/**
+ * 在请求级作用域中执行回调。
+ * 作用域内所有同步/异步代码都能通过 getRequestContext() 获取上下文。
+ */
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+/**
+ * 获取当前请求的上下文，不存在时返回 undefined。
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * 获取当前请求的投递目标地址。
+ * 便捷方法，等价于 getRequestContext()?.target。
+ */
+export declare function getRequestTarget(): string | undefined;

package/dist/src/request-context.js

@@ -0,0 +1,30 @@
+/**
+ * 请求级上下文（基于 AsyncLocalStorage）
+ *
+ * 解决并发消息下工具获取当前会话信息的竞态问题。
+ * gateway 在处理每条入站消息时通过 runWithRequestContext() 建立作用域，
+ * 作用域内的所有异步代码（包括 AI agent 调用、tool execute）
+ * 都能通过 getRequestContext() 安全地拿到当前请求的上下文。
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const asyncLocalStorage = new AsyncLocalStorage();
+/**
+ * 在请求级作用域中执行回调。
+ * 作用域内所有同步/异步代码都能通过 getRequestContext() 获取上下文。
+ */
+export function runWithRequestContext(ctx, fn) {
+    return asyncLocalStorage.run(ctx, fn);
+}
+/**
+ * 获取当前请求的上下文，不存在时返回 undefined。
+ */
+export function getRequestContext() {
+    return asyncLocalStorage.getStore();
+}
+/**
+ * 获取当前请求的投递目标地址。
+ * 便捷方法，等价于 getRequestContext()?.target。
+ */
+export function getRequestTarget() {
+    return asyncLocalStorage.getStore()?.target;
+}

package/dist/src/startup-greeting.d.ts

@@ -11,8 +11,8 @@ export type StartupMarkerData = {
     lastFailureReason?: string;
     lastFailureVersion?: string;
 };
-export declare function readStartupMarker(): StartupMarkerData;
-export declare function writeStartupMarker(data: StartupMarkerData): void;
+export declare function readStartupMarker(accountId: string, appId: string): StartupMarkerData;
+export declare function writeStartupMarker(accountId: string, appId: string, data: StartupMarkerData): void;
 /**
  * 判断是否需要发送启动问候：
  * - 首次启动（无 marker）→ "灵魂已上线"
@@ -20,11 +20,11 @@ export declare function writeStartupMarker(data: StartupMarkerData): void;
  * - 同版本 → 不发送
  * - 同版本近期失败 → 冷却期内不重试
  */
-export declare function getStartupGreetingPlan(): {
+export declare function getStartupGreetingPlan(accountId: string, appId: string): {
     shouldSend: boolean;
     greeting?: string;
     version: string;
     reason?: string;
 };
-export declare function markStartupGreetingSent(version: string): void;
-export declare function markStartupGreetingFailed(version: string, reason: string): void;
+export declare function markStartupGreetingSent(accountId: string, appId: string, version: string): void;
+export declare function markStartupGreetingFailed(accountId: string, appId: string, version: string, reason: string): void;

package/dist/src/startup-greeting.js

@@ -5,29 +5,48 @@ import * as fs from "node:fs";
 import path from "node:path";
 import { getQQBotDataDir } from "./utils/platform.js";
 import { getPluginVersion } from "./slash-commands.js";
-const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
 const STARTUP_GREETING_RETRY_COOLDOWN_MS = 10 * 60 * 1000;
+function safeName(id) {
+    return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+/** 按 accountId+appId 区分的 marker 文件路径 */
+function getMarkerFile(accountId, appId) {
+    return path.join(getQQBotDataDir("data"), `startup-marker-${safeName(accountId)}-${safeName(appId)}.json`);
+}
+/** 旧版全局 marker 路径（兼容迁移） */
+const LEGACY_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
 export function getFirstLaunchGreetingText() {
     return `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 }
 export function getUpgradeGreetingText(version) {
     return `🎉 QQBot 插件已更新至 v${version}，在线等候你的吩咐。`;
 }
-export function readStartupMarker() {
+export function readStartupMarker(accountId, appId) {
     try {
-        if (fs.existsSync(STARTUP_MARKER_FILE)) {
-            const data = JSON.parse(fs.readFileSync(STARTUP_MARKER_FILE, "utf8"));
+        // 1. 新版 per-bot 路径优先
+        const file = getMarkerFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
             return data || {};
         }
+        // 2. fallback 旧版全局 marker（兼容迁移）
+        if (fs.existsSync(LEGACY_MARKER_FILE)) {
+            const data = JSON.parse(fs.readFileSync(LEGACY_MARKER_FILE, "utf8"));
+            if (data) {
+                // 自动迁移：写到新路径
+                writeStartupMarker(accountId, appId, data);
+                return data;
+            }
+        }
     }
     catch {
         // 文件损坏或不存在，视为无 marker
     }
     return {};
 }
-export function writeStartupMarker(data) {
+export function writeStartupMarker(accountId, appId, data) {
     try {
-        fs.writeFileSync(STARTUP_MARKER_FILE, JSON.stringify(data) + "\n");
+        fs.writeFileSync(getMarkerFile(accountId, appId), JSON.stringify(data) + "\n");
     }
     catch {
         // ignore
@@ -40,9 +59,9 @@ export function writeStartupMarker(data) {
  * - 同版本 → 不发送
  * - 同版本近期失败 → 冷却期内不重试
  */
-export function getStartupGreetingPlan() {
+export function getStartupGreetingPlan(accountId, appId) {
     const currentVersion = getPluginVersion();
-    const marker = readStartupMarker();
+    const marker = readStartupMarker(accountId, appId);
     if (marker.version === currentVersion) {
         return { shouldSend: false, version: currentVersion, reason: "same-version" };
     }
@@ -58,18 +77,18 @@ export function getStartupGreetingPlan() {
         : getUpgradeGreetingText(currentVersion);
     return { shouldSend: true, greeting, version: currentVersion };
 }
-export function markStartupGreetingSent(version) {
-    writeStartupMarker({
+export function markStartupGreetingSent(accountId, appId, version) {
+    writeStartupMarker(accountId, appId, {
         version,
         startedAt: new Date().toISOString(),
         greetedAt: new Date().toISOString(),
     });
 }
-export function markStartupGreetingFailed(version, reason) {
-    const marker = readStartupMarker();
+export function markStartupGreetingFailed(accountId, appId, version, reason) {
+    const marker = readStartupMarker(accountId, appId);
     // 同版本已有失败记录时，不覆盖 lastFailureAt，避免冷却期被无限续期
     const shouldPreserveTimestamp = marker.lastFailureVersion === version && marker.lastFailureAt;
-    writeStartupMarker({
+    writeStartupMarker(accountId, appId, {
         ...marker,
         lastFailureVersion: version,
         lastFailureAt: shouldPreserveTimestamp ? marker.lastFailureAt : new Date().toISOString(),

package/dist/src/tools/remind.js

@@ -1,3 +1,4 @@
+import { getRequestTarget } from "../request-context.js";
 // ========== JSON Schema ==========
 const RemindSchema = {
     type: "object",
@@ -13,8 +14,8 @@ const RemindSchema = {
         },
         to: {
             type: "string",
-            description: "投递目标地址，取自上下文中 [QQBot] to= 的值。" +
-                "私聊格式：user_openid，群聊格式：group:group_openid。action=add 时必填。",
+            description: "投递目标地址（可选）。系统会自动从当前会话获取，通常无需手动填写。" +
+                "私聊格式：qqbot:c2c:user_openid，群聊格式：qqbot:group:group_openid。",
         },
         time: {
             type: "string",
@@ -99,9 +100,8 @@ function generateJobName(content) {
 /**
  * 构建一次性提醒的 cron 工具参数
  */
-function buildOnceJob(params, delayMs) {
+function buildOnceJob(params, delayMs, to) {
     const atMs = Date.now() + delayMs;
-    const to = params.to;
     const content = params.content;
     const name = params.name || generateJobName(content);
     return {
@@ -125,8 +125,7 @@ function buildOnceJob(params, delayMs) {
 /**
  * 构建周期提醒的 cron 工具参数
  */
-function buildCronJob(params) {
-    const to = params.to;
+function buildCronJob(params, to) {
     const content = params.content;
     const name = params.name || generateJobName(content);
     const tz = params.timezone || "Asia/Shanghai";
@@ -207,8 +206,10 @@ export function registerRemindTool(api) {
             if (!p.content) {
                 return json({ error: "action=add 时 content（提醒内容）为必填参数" });
             }
-            if (!p.to) {
-                return json({ error: "action=add 时 to（目标地址）为必填参数，取自上下文 [QQBot] to= 的值" });
+            // 优先使用 AI 传入的 to，否则自动从请求级上下文获取（AsyncLocalStorage）
+            const resolvedTo = p.to || getRequestTarget();
+            if (!resolvedTo) {
+                return json({ error: "action=add 时无法确定投递目标地址。请稍后重试。" });
             }
             if (!p.time) {
                 return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
@@ -216,7 +217,7 @@ export function registerRemindTool(api) {
             // 判断是 cron 表达式还是相对时间
             if (isCronExpression(p.time)) {
                 // 周期提醒
-                const cronJob = buildCronJob(p);
+                const cronJob = buildCronJob(p, resolvedTo);
                 return json({
                     _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
                     cronParams: cronJob,
@@ -235,7 +236,7 @@ export function registerRemindTool(api) {
             if (delayMs < 30_000) {
                 return json({ error: "提醒时间不能少于 30 秒" });
             }
-            const onceJob = buildOnceJob(p, delayMs);
+            const onceJob = buildOnceJob(p, delayMs, resolvedTo);
             return json({
                 _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
                 cronParams: onceJob,

package/dist/src/types.d.ts

@@ -68,6 +68,36 @@ export interface QQBotAccountConfig {
      * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
      */
     upgradeMode?: "doc" | "hot-reload";
+    /**
+     * 出站消息合并回复（debounce）配置
+     * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸
+     */
+    deliverDebounce?: DeliverDebounceConfig;
+}
+/**
+ * 出站消息合并回复配置
+ */
+export interface DeliverDebounceConfig {
+    /**
+     * 是否启用合并回复（默认 true）
+     */
+    enabled?: boolean;
+    /**
+     * 合并窗口时长（毫秒），在此时间内的连续 deliver 会被合并
+     * 默认 1500ms
+     */
+    windowMs?: number;
+    /**
+     * 最大等待时长（毫秒），从第一条 deliver 开始计算，超过此时间强制发送
+     * 防止持续有新 deliver 导致一直不发送
+     * 默认 8000ms
+     */
+    maxWaitMs?: number;
+    /**
+     * 合并文本之间的分隔符
+     * 默认 "\n\n---\n\n"
+     */
+    separator?: string;
 }
 /**
  * 音频格式策略：控制哪些格式可跳过转换

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.4",
+  "version": "1.6.5-alpha.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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,107 @@ 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", "undici")) {
+        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..."
 $TARGET_DIR = Join-Path $EXTENSIONS_DIR "openclaw-qqbot"
 
 if (-not (Test-Path $TARGET_DIR)) {
@@ -217,9 +315,9 @@ foreach ($legacyName in @("qqbot", "openclaw-qq")) {
 }
 Write-Host "  Installed to: $TARGET_DIR"
 
-# [3/3] Verify installation
+# [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 +347,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 +383,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

package/scripts/upgrade-via-npm.sh

@@ -114,8 +114,8 @@ echo "  qqbot npm 升级: $INSTALL_SRC"
 echo "==========================================="
 echo ""
 
-# [1/3] 下载并安装新版本到临时目录
-echo "[1/3] 下载新版本..."
+# [1/5] 下载并安装新版本到临时目录
+echo "[1/5] 下载新版本..."
 TMPDIR_PACK=$(mktemp -d)
 EXTRACT_DIR=$(mktemp -d)
 trap "rm -rf '$TMPDIR_PACK' '$EXTRACT_DIR'" EXIT
@@ -166,10 +166,108 @@ fi
 rm -rf "$TMPDIR_PACK" "$EXTRACT_DIR"
 cd "$HOME"
 
-# [2/3] 原子替换：使用 mv -T/rename 确保目录切换尽可能原子
+# ── Preflight 检查：在写入 extensions 之前确保新包完整有效 ──
+echo ""
+echo "[2/5] Preflight 检查..."
+PREFLIGHT_OK=true
+
+# (a) package.json 存在且可解析，且包含 version 字段
+STAGING_PKG="$STAGING_DIR/package.json"
+if [ ! -f "$STAGING_PKG" ]; then
+    echo "  ❌ 新包缺少 package.json"
+    PREFLIGHT_OK=false
+else
+    STAGING_VERSION="$(node -e "
+      try {
+        const v = JSON.parse(require('fs').readFileSync('$STAGING_PKG', 'utf8')).version;
+        if (v) process.stdout.write(String(v));
+      } catch {}
+    " 2>/dev/null || true)"
+    if [ -z "$STAGING_VERSION" ]; then
+        echo "  ❌ package.json 无法解析或缺少 version 字段"
+        PREFLIGHT_OK=false
+    else
+        echo "  ✅ 版本号: $STAGING_VERSION"
+    fi
+fi
+
+# (b) 入口文件存在（dist/index.js 或 index.js）
+ENTRY_FILE=""
+for candidate in "dist/index.js" "index.js"; do
+    if [ -f "$STAGING_DIR/$candidate" ]; then
+        ENTRY_FILE="$candidate"
+        break
+    fi
+done
+if [ -z "$ENTRY_FILE" ]; then
+    echo "  ❌ 缺少入口文件（dist/index.js 或 index.js）"
+    PREFLIGHT_OK=false
+else
+    echo "  ✅ 入口文件: $ENTRY_FILE"
+fi
+
+# (c) 核心目录 dist/src 存在
+if [ ! -d "$STAGING_DIR/dist/src" ]; then
+    echo "  ❌ 缺少核心目录 dist/src/"
+    PREFLIGHT_OK=false
+else
+    CORE_JS_COUNT=$(find "$STAGING_DIR/dist/src" -name "*.js" -type f 2>/dev/null | wc -l | tr -d ' ')
+    echo "  ✅ dist/src/ 包含 ${CORE_JS_COUNT} 个 JS 文件"
+    if [ "$CORE_JS_COUNT" -lt 5 ]; then
+        echo "  ❌ JS 文件数量异常偏少（预期 ≥ 5，实际 ${CORE_JS_COUNT}）"
+        PREFLIGHT_OK=false
+    fi
+fi
+
+# (d) 关键模块文件存在
+MISSING_MODULES=""
+for module in "dist/src/gateway.js" "dist/src/api.js" "dist/src/admin-resolver.js"; do
+    if [ ! -f "$STAGING_DIR/$module" ]; then
+        MISSING_MODULES="$MISSING_MODULES $module"
+    fi
+done
+if [ -n "$MISSING_MODULES" ]; then
+    echo "  ❌ 缺少关键模块:$MISSING_MODULES"
+    PREFLIGHT_OK=false
+else
+    echo "  ✅ 关键模块完整"
+fi
+
+# (e) bundled node_modules 健康检查
+if [ -d "$STAGING_DIR/node_modules" ]; then
+    BUNDLED_OK=true
+    for dep in "ws" "undici"; do
+        if [ ! -d "$STAGING_DIR/node_modules/$dep" ]; then
+            echo "  ⚠️  bundled 依赖缺失: $dep"
+            BUNDLED_OK=false
+        fi
+    done
+    if $BUNDLED_OK; then
+        echo "  ✅ 核心 bundled 依赖完整"
+    fi
+fi
+
+# (f) 如果有旧版本，检查新版本是否合理（不允许降级到 0.x 等异常版本）
+if [ -n "$STAGING_VERSION" ]; then
+    STAGING_MAJOR="$(echo "$STAGING_VERSION" | cut -d. -f1)"
+    if [ "$STAGING_MAJOR" = "0" ]; then
+        echo "  ⚠️  新版本主版本号为 0（$STAGING_VERSION），可能不是正式发布版"
+    fi
+fi
+
+# 检查结果
+if [ "$PREFLIGHT_OK" != "true" ]; then
+    echo ""
+    echo "❌ Preflight 检查未通过，中止升级（旧版本未受影响）"
+    rm -rf "$STAGING_DIR"
+    exit 1
+fi
+echo "  ✅ Preflight 检查全部通过"
+
+# [3/5] 原子替换：使用 mv -T/rename 确保目录切换尽可能原子
 # 策略：先把 staging 放到 extensions/ 同级的临时名，再做单次 mv 替换
 echo ""
-echo "[2/3] 原子替换插件目录..."
+echo "[3/5] 原子替换插件目录..."
 TARGET_DIR="$EXTENSIONS_DIR/openclaw-qqbot"
 OLD_DIR="$(dirname "$EXTENSIONS_DIR")/.qqbot-upgrade-old"
 
@@ -199,9 +297,9 @@ for dir_name in qqbot openclaw-qq; do
 done
 echo "  已安装到: $TARGET_DIR"
 
-# [3/3] 输出新版本号和升级报告（供调用方解析）
+# [4/5] 输出新版本号和升级报告（供调用方解析）
 echo ""
-echo "[3/3] 验证安装..."
+echo "[4/5] 验证安装..."
 NEW_VERSION="$(node -e "
   try {
     const fs = require('fs');
@@ -239,7 +337,7 @@ fi
 
 # 以下步骤仅在非热更新（手动执行）场景中执行
 
-# [4/4] 配置 appid/secret（仅在提供了参数时执行）
+# [配置] appid/secret（仅在提供了参数时执行）
 if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
     echo ""
     echo "[配置] 写入 qqbot 通道配置..."
@@ -293,9 +391,25 @@ fi
 
 # [5/5] 重启 gateway 使新版本生效
 echo ""
+
+# 手动升级场景：提前写入 startup-marker，阻止重启后 bot 重复推送升级通知
+# （控制台已打印同款提示语，无需 bot 再发一次）
+if [ -n "$NEW_VERSION" ] && [ "$NEW_VERSION" != "unknown" ]; then
+    MARKER_DIR="$HOME/.openclaw/qqbot/data"
+    mkdir -p "$MARKER_DIR"
+    MARKER_FILE="$MARKER_DIR/startup-marker.json"
+    NOW="$(date -u +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || date +%Y-%m-%dT%H:%M:%SZ)"
+    echo "{\"version\":\"$NEW_VERSION\",\"startedAt\":\"$NOW\",\"greetedAt\":\"$NOW\"}" > "$MARKER_FILE"
+fi
+
 echo "[重启] 重启 gateway 使新版本生效..."
 if $CMD gateway restart 2>&1; then
     echo "  ✅ gateway 已重启"
+    # 打印与 bot 通知同款的更新提示语（手动升级场景无需通过 bot 推送）
+    echo ""
+    if [ -n "$NEW_VERSION" ] && [ "$NEW_VERSION" != "unknown" ]; then
+        echo "🎉 QQBot 插件已更新至 v${NEW_VERSION}，在线等候你的吩咐。"
+    fi
 else
     echo "  ⚠️  gateway 重启失败，请手动执行: $CMD gateway restart"
 fi

package/skills/qqbot-remind/SKILL.md

@@ -22,7 +22,7 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 |------|------|------|
 | `action` | 操作类型 | `"add"` / `"list"` / `"remove"` |
 | `content` | 提醒内容 | `"喝水"` |
-| `to` | 目标地址（取自上下文 `[QQBot] to=` 的值） | `"user_openid_xxx"` 或 `"group:group_openid_xxx"` |
+| `to` | 目标地址（可选，系统自动获取，通常无需填写） | — |
 | `time` | 时间（相对时间或 cron 表达式） | `"5m"` / `"1h30m"` / `"0 8 * * *"` |
 | `jobId` | 任务 ID（仅 remove） | `"xxx"` |
 
@@ -34,7 +34,7 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 
 用户说："5分钟后提醒我喝水"
 
-1. 调用 `qqbot_remind`：`{ "action": "add", "content": "喝水", "to": "xxx", "time": "5m" }`
+1. 调用 `qqbot_remind`：`{ "action": "add", "content": "喝水", "time": "5m" }`
 2. 收到返回的 `cronParams` → 立即调用 `cron` 工具，参数为该 `cronParams`
 3. 回复用户：`⏰ 好的，5分钟后提醒你喝水~`
 
@@ -56,7 +56,7 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 | `payload.kind` | `"agentTurn"` | `systemEvent` 不会发 QQ 消息 |
 | `payload.deliver` | `true` | 否则不投递 |
 | `payload.channel` | `"qqbot"` | QQ 通道标识 |
-| `payload.to` | 用户 openid | 从上下文获取 |
+| `payload.to` | 用户 openid | 从 `To` 字段获取 |
 | `sessionTarget` | `"isolated"` | 隔离会话避免污染 |
 
 > `schedule.atMs` 必须是**绝对毫秒时间戳**（如 `1770733800000`），不支持 `"5m"` 等相对字符串。