@jerryliang122/openclaw-qqbot 1.0.0

package/src/tools/remind.ts

@@ -0,0 +1,308 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { getRequestTarget, getRequestAccountId } from "../request-context.js";
+
+// ========== 类型定义 ==========
+
+interface RemindParams {
+  action: "add" | "list" | "remove";
+  /** 提醒内容（action=add 时必填） */
+  content?: string;
+  /**
+   * 投递目标地址（可选，系统会自动从当前会话上下文获取）。
+   * 仅在需要手动指定时填写。
+   */
+  to?: string;
+  /**
+   * 时间描述（action=add 时必填）
+   * - 一次性：相对时间如 "5m"、"1h30m"、"2h"，或绝对毫秒时间戳
+   * - 周期性：cron 表达式如 "0 8 * * *"
+   */
+  time?: string;
+  /** 时区（周期提醒时使用，默认 Asia/Shanghai） */
+  timezone?: string;
+  /** 提醒名称（可选，默认自动生成） */
+  name?: string;
+  /** jobId（action=remove 时必填） */
+  jobId?: string;
+}
+
+// ========== JSON Schema ==========
+
+const RemindSchema = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      description:
+        "操作类型。add=创建提醒, list=查看已有提醒, remove=删除提醒",
+      enum: ["add", "list", "remove"],
+    },
+    content: {
+      type: "string",
+      description: '提醒内容，如"喝水"、"开会"。action=add 时必填。',
+    },
+    to: {
+      type: "string",
+      description:
+        "投递目标地址（可选）。系统会自动从当前会话获取，通常无需手动填写。" +
+        "私聊格式：qqbot:c2c:user_openid，群聊格式：qqbot:group:group_openid。",
+    },
+    time: {
+      type: "string",
+      description:
+        "时间描述。支持两种格式：\n" +
+        "1. 相对时间：如 \"5m\"(5分钟后)、\"1h\"(1小时后)、\"1h30m\"(1.5小时后)、\"2d\"(2天后)\n" +
+        "2. cron 表达式：如 \"0 8 * * *\"(每天8点)、\"0 9 * * 1-5\"(工作日9点)\n" +
+        "系统会自动判断：包含空格的视为 cron 表达式（周期提醒），否则视为相对时间（一次性提醒）。\n" +
+        "action=add 时必填。",
+    },
+    timezone: {
+      type: "string",
+      description:
+        "时区，仅周期提醒(cron)时需要。默认 \"Asia/Shanghai\"。",
+    },
+    name: {
+      type: "string",
+      description: "提醒任务名称（可选）。默认自动从 content 截取前 20 字。",
+    },
+    jobId: {
+      type: "string",
+      description: "要删除的任务 ID。action=remove 时必填，先用 list 获取。",
+    },
+  },
+  required: ["action"],
+} as const;
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+/**
+ * 解析相对时间字符串为毫秒数
+ * 支持格式：5m, 1h, 1h30m, 2d, 30s, 1d2h30m 等
+ */
+function parseRelativeTime(timeStr: string): number | null {
+  const s = timeStr.trim().toLowerCase();
+
+  // 纯数字 → 视为分钟
+  if (/^\d+$/.test(s)) {
+    return parseInt(s, 10) * 60_000;
+  }
+
+  let totalMs = 0;
+  let matched = false;
+  const regex = /(\d+(?:\.\d+)?)\s*(d|h|m|s)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(s)) !== null) {
+    matched = true;
+    const value = parseFloat(match[1]);
+    const unit = match[2];
+    switch (unit) {
+      case "d": totalMs += value * 86_400_000; break;
+      case "h": totalMs += value * 3_600_000; break;
+      case "m": totalMs += value * 60_000; break;
+      case "s": totalMs += value * 1_000; break;
+    }
+  }
+
+  return matched ? Math.round(totalMs) : null;
+}
+
+/**
+ * 判断是否为 cron 表达式（包含空格且有 3~6 段）
+ */
+function isCronExpression(timeStr: string): boolean {
+  const parts = timeStr.trim().split(/\s+/);
+  return parts.length >= 3 && parts.length <= 6;
+}
+
+/**
+ * 自动生成任务名称
+ */
+function generateJobName(content: string): string {
+  const trimmed = content.trim();
+  const short = trimmed.length > 20 ? trimmed.slice(0, 20) + "…" : trimmed;
+  return `提醒: ${short}`;
+}
+
+/**
+ * 构建一次性提醒的 cron 工具参数
+ */
+function buildOnceJob(params: RemindParams, delayMs: number, to: string, accountId: string) {
+  const atMs = Date.now() + delayMs;
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+
+  return {
+    action: "add",
+    job: {
+      name,
+      schedule: { kind: "at", atMs },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      deleteAfterRun: true,
+      payload: {
+        kind: "agentTurn",
+        message: buildReminderPrompt(content),
+      },
+      delivery: {
+        mode: "announce",
+        channel: "qqbot",
+        to,
+        accountId,
+      },
+    },
+  };
+}
+
+/**
+ * 构建周期提醒的 cron 工具参数
+ */
+function buildCronJob(params: RemindParams, to: string, accountId: string) {
+  const content = params.content!;
+  const name = params.name || generateJobName(content);
+  const tz = params.timezone || "Asia/Shanghai";
+
+  return {
+    action: "add",
+    job: {
+      name,
+      schedule: { kind: "cron", expr: params.time!.trim(), tz },
+      sessionTarget: "isolated",
+      wakeMode: "now",
+      payload: {
+        kind: "agentTurn",
+        message: buildReminderPrompt(content),
+      },
+      delivery: {
+        mode: "announce",
+        channel: "qqbot",
+        to,
+        accountId,
+      },
+    },
+  };
+}
+
+/**
+ * 构建提醒 payload 中的 AI prompt
+ */
+function buildReminderPrompt(content: string): string {
+  return (
+    `你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：${content}。` +
+    `要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 ` +
+    `(3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 ` +
+    `(5) 控制在2-3句话以内 (6) 用emoji点缀`
+  );
+}
+
+/**
+ * 格式化延迟时间为人类可读文本
+ */
+function formatDelay(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}秒`;
+  const totalMinutes = Math.round(ms / 60_000);
+  if (totalMinutes < 60) return `${totalMinutes}分钟`;
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (minutes === 0) return `${hours}小时`;
+  return `${hours}小时${minutes}分钟`;
+}
+
+// ========== 注册入口 ==========
+
+export function registerRemindTool(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: "qqbot_remind",
+      label: "QQBot 定时提醒",
+      description:
+        "创建、查询、删除 QQ 定时提醒。" +
+        "使用简单参数即可，无需手动构造 cron JSON。\n" +
+        "创建提醒：action=add, content=提醒内容, to=目标地址, time=时间\n" +
+        "查看提醒：action=list\n" +
+        "删除提醒：action=remove, jobId=任务ID（先 list 获取）\n" +
+        "时间格式示例：\"5m\"(5分钟后) \"1h\"(1小时后) \"0 8 * * *\"(每天8点)",
+      parameters: RemindSchema,
+      execute(_toolCallId, params) {
+        const p = params as RemindParams;
+
+        // ===== list =====
+        if (p.action === "list") {
+          return json({
+            _instruction: "请立即使用 cron 工具执行以下参数",
+            cronParams: { action: "list" },
+          });
+        }
+
+        // ===== remove =====
+        if (p.action === "remove") {
+          if (!p.jobId) {
+            return json({ error: "action=remove 时 jobId 为必填参数。请先用 action=list 获取 jobId。" });
+          }
+          return json({
+            _instruction: "请立即使用 cron 工具执行以下参数",
+            cronParams: { action: "remove", jobId: p.jobId },
+          });
+        }
+
+        // ===== add =====
+        if (!p.content) {
+          return json({ error: "action=add 时 content（提醒内容）为必填参数" });
+        }
+        // 优先使用 AI 传入的 to，否则自动从请求级上下文获取（AsyncLocalStorage）
+        const resolvedTo = p.to || getRequestTarget();
+        if (!resolvedTo) {
+          return json({ error: "action=add 时无法确定投递目标地址。请稍后重试。" });
+        }
+        // 从请求上下文获取当前账户 ID（多账户场景），fallback 到 "default"
+        const resolvedAccountId = getRequestAccountId() || "default";
+        if (!p.time) {
+          return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
+        }
+
+        // 判断是 cron 表达式还是相对时间
+        if (isCronExpression(p.time)) {
+          // 周期提醒
+          const cronJob = buildCronJob(p, resolvedTo, resolvedAccountId);
+          return json({
+            _instruction: "请立即使用 cron 工具，将 cronParams 的值原样作为参数传入（不要修改或省略任何字段，特别是 delivery.accountId），然后回复用户提醒已设置",
+            cronParams: cronJob,
+            summary: `⏰ 周期提醒: "${p.content}" (${p.time}, tz=${p.timezone || "Asia/Shanghai"})`,
+          });
+        }
+
+        // 一次性提醒
+        const delayMs = parseRelativeTime(p.time);
+        if (!delayMs || delayMs <= 0) {
+          return json({
+            error: `无法解析时间 "${p.time}"。支持格式：` +
+              `相对时间如 "5m"、"1h"、"1h30m"、"2d"；` +
+              `cron 表达式如 "0 8 * * *"（每天8点）`,
+          });
+        }
+
+        if (delayMs < 30_000) {
+          return json({ error: "提醒时间不能少于 30 秒" });
+        }
+
+        const onceJob = buildOnceJob(p, delayMs, resolvedTo, resolvedAccountId);
+        return json({
+          _instruction: "请立即使用 cron 工具，将 cronParams 的值原样作为参数传入（不要修改或省略任何字段，特别是 delivery.accountId），然后回复用户提醒已设置",
+          cronParams: onceJob,
+          summary: `⏰ ${formatDelay(delayMs)}后提醒: "${p.content}"`,
+        });
+      },
+    },
+    { name: "qqbot_remind" },
+  );
+
+}
+

package/src/tools/secret-input.ts

@@ -0,0 +1,185 @@
+/**
+ * qqbot_secret_input 工具 — 聊天内密钥输入卡片
+ *
+ * 用户想交给 AI 一个新密钥/凭据时，host AI 调用本工具（而非让用户把
+ * 密钥粘贴进对话）。工具给当前 c2c 用户发一张输入卡片并登记 pending，
+ * 用户下一条消息由 secretCapture 中间件拦截，插件就地执行
+ * `openclaw secrets store set <NAME> --kind env --value ...` 并直接回执。
+ *
+ * kind 恒为 env（代理可读环境变量）：聊天卡片收来的值本就落在 QQ 聊天
+ * 记录里，且 AI 随后要读取使用；secret kind 是「受保护的机密」
+ * （write-only，代理不可读），存进去 AI 反而用不了（2026-08-30 用户反馈）。
+ *
+ * 非阻塞：工具发卡后立即返回，AI 应结束本轮；执行与回执完全由插件自治。
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import { tryGetBotForAccount } from '../bot-instance.js';
+import { isValidSecretName } from '../features/secret-store-cli.js';
+import {
+  DEFAULT_SECRET_INPUT_TTL_MS,
+  cancelPendingSecretInput,
+  registerPendingSecretInput,
+} from '../features/secret-input-store.js';
+import { getRequestAccountId, getRequestTarget } from '../request-context.js';
+import { parseTarget } from '../outbound/target.js';
+import type { InlineKeyboard, KeyboardButton } from '../types.js';
+
+// ========== JSON Schema ==========
+
+const SecretInputSchema = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description:
+        '环境变量名。命名规则：以大写字母开头，仅含大写字母/数字/下划线，' +
+        '最长 128 字符。推荐语义化命名，如 GITHUB_TOKEN、OPENWEATHER_API_KEY、' +
+        'DEEPSEEK_API_KEY。值将以代理可读环境变量（kind=env）保存，AI 之后可直接读取使用。',
+    },
+    description: {
+      type: 'string',
+      description: '该密钥的用途说明（可选），会展示在输入卡片上，帮助用户确认。',
+    },
+  },
+  required: ['name'],
+} as const;
+
+// ========== 卡片构建 ==========
+
+function buildSecretInputCard(
+  name: string,
+  description: string | undefined,
+  ttlMinutes: number,
+): string {
+  const lines = [`**🔒 密钥输入 · ${name}**`];
+  if (description) lines.push('', `用途：${description}`);
+  lines.push(
+    '',
+    `请在下方输入框直接粘贴并发送 **${name}** 的值：`,
+    '',
+    '- 将保存为**代理可读环境变量**（AI 之后可直接读取使用），' +
+      `写入方式：\`openclaw secrets store set ${name} --kind env\``,
+    '- 你发送的消息会被插件直接拦截执行，**不会进入 AI 对话**',
+    '- 密钥会留存在你的聊天记录中，请留意所在环境安全',
+    `- ${ttlMinutes} 分钟内有效；发送「取消」可退出`,
+  );
+  return lines.join('\n');
+}
+
+/** 「取消」指令按钮：action.type=2 + enter=true，客户端点击后以真实用户消息发出「取消」 */
+function buildSecretInputKeyboard(): InlineKeyboard {
+  const buttons: KeyboardButton[] = [
+    {
+      id: 'secret_input_cancel',
+      render_data: {
+        label: '❌ 取消',
+        visited_label: '已取消',
+        style: 1 as const,
+      },
+      action: {
+        type: 2 as const,
+        data: '取消',
+        enter: true,
+        permission: { type: 2 as const },
+        unsupport_tips: '当前客户端不支持，请手动发送 取消',
+      },
+    },
+  ];
+  return { content: { rows: [{ buttons }] } };
+}
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+// ========== 注册入口 ==========
+
+export function registerSecretInputTool(api: OpenClawPluginApi): void {
+  api.registerTool(
+    {
+      name: 'qqbot_secret_input',
+      label: 'QQBot Secret Input Card',
+      description:
+        '当用户要交付一个新密钥/凭据（API Key、Token 等）给系统保存时调用：' +
+        '向用户私聊发送一张密钥输入卡片，用户把密钥粘贴在输入框发送后，' +
+        '插件会自动拦截该消息并执行 openclaw secrets store set 完成保存，' +
+        '结果由插件直接回复用户。密钥内容不会进入对话。' +
+        '必须由用户提供 name 参数（环境变量名）。',
+      parameters: SecretInputSchema,
+      async execute(_toolCallId, params) {
+        const p = params as { name?: string; description?: string };
+        const name = (p.name ?? '').trim();
+        if (!name) return json({ error: 'name 为必填参数（环境变量名）' });
+        if (!isValidSecretName(name)) {
+          return json({
+            error:
+              '环境变量名不合法：必须以大写字母开头，仅含大写字母/数字/下划线，最长 128 字符' +
+              `（收到 "${name}"）。示例：OPENWEATHER_API_KEY。请修正后重试。`,
+          });
+        }
+        // 恒为 env：见文件头注释（卡片值 = 代理可读环境，secret 是 write-only 代理不可读）
+        const kind = 'env' as const;
+
+        const target = getRequestTarget();
+        const accountId = getRequestAccountId() ?? 'default';
+        if (!target) {
+          return json({ error: '无法获取当前会话目标，此工具仅支持在 QQ Bot 消息会话中使用' });
+        }
+        const parsed = parseTarget(target);
+        if (parsed.scope !== 'c2c' || !parsed.targetId) {
+          return json({
+            error:
+              `密钥输入卡片仅支持私聊（c2c）会话，当前目标 ${target} 不适用` +
+              '——密钥不应出现在群聊中。请引导用户在私聊中发起。',
+          });
+        }
+
+        const bot = tryGetBotForAccount(accountId);
+        if (!bot) {
+          return json({ error: `账户 ${accountId} 的 gateway 尚未启动，无法发送密钥输入卡片` });
+        }
+
+        const description = p.description?.trim() || undefined;
+        // 先登记后发卡（避免「先发后登」竞态，同 multi-question 约定）
+        registerPendingSecretInput({
+          accountId,
+          senderOpenid: parsed.targetId,
+          name,
+          kind,
+          description,
+          createdAt: Date.now(),
+        });
+        try {
+          await bot.sendTextWithKeyboard(
+            { scope: 'c2c', targetId: parsed.targetId },
+            buildSecretInputCard(name, description, DEFAULT_SECRET_INPUT_TTL_MS / 60_000),
+            buildSecretInputKeyboard() as never,
+          );
+        } catch (err) {
+          cancelPendingSecretInput(accountId, parsed.targetId);
+          return json({
+            error: `密钥输入卡片发送失败：${err instanceof Error ? err.message : String(err)}`,
+          });
+        }
+
+        return json({
+          ok: true,
+          name,
+          kind,
+          command: `openclaw secrets store set ${name} --kind env --value <用户输入>`,
+          instruction:
+            '卡片已发送给用户。用户下一条私聊消息将被插件自动拦截（不会进入对话），' +
+            `执行上述命令保存密钥，成功/失败由插件直接回复用户。` +
+            '请直接结束本轮（可告知用户按卡片提示发送密钥），不要等待用户输入，' +
+            '也不要让用户把密钥内容发到对话里。',
+        });
+      },
+    },
+    { name: 'qqbot_secret_input' },
+  );
+}

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-plugin.ts

@@ -0,0 +1,82 @@
+/**
+ * QQBot Channel Plugin 类型定义
+ */
+
+import type { ResolvedQQBotAccount } from './types.js';
+
+/**
+ * QQBot 探测结果
+ */
+export interface QQBotProbe {
+  ok: boolean;
+  bot?: {
+    id?: string;
+    username?: string;
+  };
+  status?: number;
+}
+
+/**
+ * QQBot 审计结果
+ */
+export interface QQBotAudit {
+  ok: boolean;
+  checkedGroups: number;
+  unresolvedGroups: number;
+}
+
+/**
+ * QQBot 会话路由
+ */
+export interface QQBotSessionRoute {
+  to: string;
+  threadId?: string | number;
+  chatType: 'direct' | 'group';
+  sessionKey: string;
+  baseSessionKey: string;
+}
+
+/**
+ * 配额状态
+ */
+export interface QuotaState {
+  count: number;
+  expiresAt: number;
+}
+
+/**
+ * 配额管理参数
+ */
+export interface QuotaCheckParams {
+  accountId: string;
+  msgId?: string;
+  scope: 'c2c' | 'group';
+}
+
+export interface QuotaConsumeParams extends QuotaCheckParams {
+  msgId: string;
+  log?: {
+    debug?: (message: string) => void;
+  };
+}
+
+/**
+ * Typing 续期参数
+ */
+export interface TypingParams {
+  accountId: string;
+  to: string;
+  replyToId: string;
+  log?: {
+    debug?: (message: string) => void;
+  };
+}
+
+/**
+ * Typing 状态
+ */
+export interface TypingState {
+  timer: NodeJS.Timeout;
+  startedAt: number;
+  renewalCount: number;
+}