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

package/src/request-context.ts

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

package/src/startup-greeting.ts

@@ -7,9 +7,20 @@ 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: string): string {
+  return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+/** 按 accountId+appId 区分的 marker 文件路径 */
+function getMarkerFile(accountId: string, appId: string): string {
+  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(): string {
   return `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 }
@@ -27,21 +38,32 @@ export type StartupMarkerData = {
   lastFailureVersion?: string;
 };
 
-export function readStartupMarker(): StartupMarkerData {
+export function readStartupMarker(accountId: string, appId: string): StartupMarkerData {
   try {
-    if (fs.existsSync(STARTUP_MARKER_FILE)) {
-      const data = JSON.parse(fs.readFileSync(STARTUP_MARKER_FILE, "utf8")) as StartupMarkerData;
+    // 1. 新版 per-bot 路径优先
+    const file = getMarkerFile(accountId, appId);
+    if (fs.existsSync(file)) {
+      const data = JSON.parse(fs.readFileSync(file, "utf8")) as StartupMarkerData;
       return data || {};
     }
+    // 2. fallback 旧版全局 marker（兼容迁移）
+    if (fs.existsSync(LEGACY_MARKER_FILE)) {
+      const data = JSON.parse(fs.readFileSync(LEGACY_MARKER_FILE, "utf8")) as StartupMarkerData;
+      if (data) {
+        // 自动迁移：写到新路径
+        writeStartupMarker(accountId, appId, data);
+        return data;
+      }
+    }
   } catch {
     // 文件损坏或不存在，视为无 marker
   }
   return {};
 }
 
-export function writeStartupMarker(data: StartupMarkerData): void {
+export function writeStartupMarker(accountId: string, appId: string, data: StartupMarkerData): void {
   try {
-    fs.writeFileSync(STARTUP_MARKER_FILE, JSON.stringify(data) + "\n");
+    fs.writeFileSync(getMarkerFile(accountId, appId), JSON.stringify(data) + "\n");
   } catch {
     // ignore
   }
@@ -54,9 +76,9 @@ export function writeStartupMarker(data: StartupMarkerData): void {
  * - 同版本 → 不发送
  * - 同版本近期失败 → 冷却期内不重试
  */
-export function getStartupGreetingPlan(): { shouldSend: boolean; greeting?: string; version: string; reason?: string } {
+export function getStartupGreetingPlan(accountId: string, appId: string): { shouldSend: boolean; greeting?: string; version: string; reason?: string } {
   const currentVersion = getPluginVersion();
-  const marker = readStartupMarker();
+  const marker = readStartupMarker(accountId, appId);
 
   if (marker.version === currentVersion) {
     return { shouldSend: false, version: currentVersion, reason: "same-version" };
@@ -77,19 +99,19 @@ export function getStartupGreetingPlan(): { shouldSend: boolean; greeting?: stri
   return { shouldSend: true, greeting, version: currentVersion };
 }
 
-export function markStartupGreetingSent(version: string): void {
-  writeStartupMarker({
+export function markStartupGreetingSent(accountId: string, appId: string, version: string): void {
+  writeStartupMarker(accountId, appId, {
     version,
     startedAt: new Date().toISOString(),
     greetedAt: new Date().toISOString(),
   });
 }
 
-export function markStartupGreetingFailed(version: string, reason: string): void {
-  const marker = readStartupMarker();
+export function markStartupGreetingFailed(accountId: string, appId: string, version: string, reason: string): void {
+  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/src/tools/remind.ts

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { getRequestTarget } from "../request-context.js";
 
 // ========== 类型定义 ==========
 
@@ -6,7 +7,10 @@ interface RemindParams {
   action: "add" | "list" | "remove";
   /** 提醒内容（action=add 时必填） */
   content?: string;
-  /** 目标地址，格式为上下文中的 to= 值（action=add 时必填） */
+  /**
+   * 投递目标地址（可选，系统会自动从当前会话上下文获取）。
+   * 仅在需要手动指定时填写。
+   */
   to?: string;
   /**
    * 时间描述（action=add 时必填）
@@ -40,8 +44,8 @@ const RemindSchema = {
     to: {
       type: "string",
       description:
-        "投递目标地址，取自上下文中 [QQBot] to= 的值。" +
-        "私聊格式：user_openid，群聊格式：group:group_openid。action=add 时必填。",
+        "投递目标地址（可选）。系统会自动从当前会话获取，通常无需手动填写。" +
+        "私聊格式：qqbot:c2c:user_openid，群聊格式：qqbot:group:group_openid。",
     },
     time: {
       type: "string",
@@ -130,9 +134,8 @@ function generateJobName(content: string): string {
 /**
  * 构建一次性提醒的 cron 工具参数
  */
-function buildOnceJob(params: RemindParams, delayMs: number) {
+function buildOnceJob(params: RemindParams, delayMs: number, to: string) {
   const atMs = Date.now() + delayMs;
-  const to = params.to!;
   const content = params.content!;
   const name = params.name || generateJobName(content);
 
@@ -158,8 +161,7 @@ function buildOnceJob(params: RemindParams, delayMs: number) {
 /**
  * 构建周期提醒的 cron 工具参数
  */
-function buildCronJob(params: RemindParams) {
-  const to = params.to!;
+function buildCronJob(params: RemindParams, to: string) {
   const content = params.content!;
   const name = params.name || generateJobName(content);
   const tz = params.timezone || "Asia/Shanghai";
@@ -249,8 +251,10 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
         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 * * *\"" });
@@ -259,7 +263,7 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
         // 判断是 cron 表达式还是相对时间
         if (isCronExpression(p.time)) {
           // 周期提醒
-          const cronJob = buildCronJob(p);
+          const cronJob = buildCronJob(p, resolvedTo);
           return json({
             _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
             cronParams: cronJob,
@@ -281,7 +285,7 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
           return json({ error: "提醒时间不能少于 30 秒" });
         }
 
-        const onceJob = buildOnceJob(p, delayMs);
+        const onceJob = buildOnceJob(p, delayMs, resolvedTo);
         return json({
           _instruction: "请立即使用 cron 工具执行以下参数，然后回复用户提醒已设置",
           cronParams: onceJob,

package/src/types.ts

@@ -70,6 +70,37 @@ 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;
 }
 
 /**