@ryantest/openclaw-qqbot 0.0.1

package/skills/qqbot-remind/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: qqbot-remind
+description: QQBot 定时提醒。支持一次性和周期性提醒的创建、查询、取消。当通过 QQ 通道通信且涉及提醒/定时任务时使用。
+metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
+---
+
+# QQ Bot 定时提醒
+
+## ⚠️ 强制规则
+
+**当用户提到「提醒」「闹钟」「定时」「X分钟/小时后」「每天X点」「叫我」等任何涉及延时或定时的请求时，你必须调用工具，绝对不能只用自然语言回复说"好的，我会提醒你"！**
+
+你没有内存或后台线程，口头承诺"到时候提醒"是无效的——只有调用工具才能真正注册定时任务。
+
+---
+
+## 推荐流程（优先使用 `qqbot_remind` 工具）
+
+**第一步**：调用 `qqbot_remind` 工具，传入简单参数：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `action` | 操作类型 | `"add"` / `"list"` / `"remove"` |
+| `content` | 提醒内容 | `"喝水"` |
+| `to` | 目标地址（取自上下文 `[QQBot] to=` 的值） | `"user_openid_xxx"` 或 `"group:group_openid_xxx"` |
+| `time` | 时间（相对时间或 cron 表达式） | `"5m"` / `"1h30m"` / `"0 8 * * *"` |
+| `jobId` | 任务 ID（仅 remove） | `"xxx"` |
+
+**第二步**：`qqbot_remind` 会返回 `cronParams`，你必须**立即**将 `cronParams` 的值作为参数调用 `cron` 工具。
+
+**第三步**：根据 `cron` 工具的返回结果，回复用户。
+
+### 示例
+
+用户说："5分钟后提醒我喝水"
+
+1. 调用 `qqbot_remind`：`{ "action": "add", "content": "喝水", "to": "xxx", "time": "5m" }`
+2. 收到返回的 `cronParams` → 立即调用 `cron` 工具，参数为该 `cronParams`
+3. 回复用户：`⏰ 好的，5分钟后提醒你喝水~`
+
+---
+
+## 备用方案（直接使用 `cron` 工具）
+
+> 仅当 `qqbot_remind` 工具不可用时使用以下方式。
+
+### 核心规则
+
+> **payload.kind 必须是 `"agentTurn"`，绝对不能用 `"systemEvent"`！**
+> `systemEvent` 只在 AI 会话内部注入文本，用户收不到 QQ 消息。
+
+**5 个不可更改字段**：
+
+| 字段 | 固定值 | 原因 |
+|------|--------|------|
+| `payload.kind` | `"agentTurn"` | `systemEvent` 不会发 QQ 消息 |
+| `payload.deliver` | `true` | 否则不投递 |
+| `payload.channel` | `"qqbot"` | QQ 通道标识 |
+| `payload.to` | 用户 openid | 从上下文获取 |
+| `sessionTarget` | `"isolated"` | 隔离会话避免污染 |
+
+> `schedule.atMs` 必须是**绝对毫秒时间戳**（如 `1770733800000`），不支持 `"5m"` 等相对字符串。
+> 计算方式：`当前时间戳ms + 延迟毫秒`。
+
+### 一次性提醒（schedule.kind = "at"）
+
+```json
+{
+  "action": "add",
+  "job": {
+    "name": "{任务名}",
+    "schedule": { "kind": "at", "atMs": "{当前时间戳ms + N*60000}" },
+    "sessionTarget": "isolated",
+    "wakeMode": "now",
+    "deleteAfterRun": true,
+    "payload": {
+      "kind": "agentTurn",
+      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
+      "deliver": true,
+      "channel": "qqbot",
+      "to": "{openid}"
+    }
+  }
+}
+```
+
+### 周期提醒（schedule.kind = "cron"）
+
+```json
+{
+  "action": "add",
+  "job": {
+    "name": "{任务名}",
+    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "Asia/Shanghai" },
+    "sessionTarget": "isolated",
+    "wakeMode": "now",
+    "payload": {
+      "kind": "agentTurn",
+      "message": "你是一个暖心的提醒助手。请用温暖、有趣的方式提醒用户：{提醒内容}。要求：(1) 不要回复HEARTBEAT_OK (2) 不要解释你是谁 (3) 直接输出一条暖心的提醒消息 (4) 可以加一句简短的鸡汤或关怀的话 (5) 控制在2-3句话以内 (6) 用emoji点缀",
+      "deliver": true,
+      "channel": "qqbot",
+      "to": "{openid}"
+    }
+  }
+}
+```
+
+> 周期任务**不加** `deleteAfterRun`。群聊 `to` 格式为 `"group:{group_openid}"`。
+
+---
+
+## cron 表达式速查
+
+| 场景 | expr |
+|------|------|
+| 每天早上8点 | `"0 8 * * *"` |
+| 每天晚上10点 | `"0 22 * * *"` |
+| 工作日早上9点 | `"0 9 * * 1-5"` |
+| 每周一早上9点 | `"0 9 * * 1"` |
+| 每周末上午10点 | `"0 10 * * 0,6"` |
+| 每小时整点 | `"0 * * * *"` |
+
+> 周期提醒必须加 `"tz": "Asia/Shanghai"`。
+
+---
+
+## AI 决策指南
+
+| 用户说法 | action | time 格式 |
+|----------|--------|-----------|
+| "5分钟后提醒我喝水" | `add` | `"5m"` |
+| "1小时后提醒开会" | `add` | `"1h"` |
+| "每天8点提醒我打卡" | `add` | `"0 8 * * *"` |
+| "工作日早上9点提醒" | `add` | `"0 9 * * 1-5"` |
+| "我有哪些提醒" | `list` | — |
+| "取消喝水提醒" | `remove` | — |
+| "修改提醒时间" | `remove` → `add` | — |
+| "提醒我"（无时间） | **需追问** | — |
+
+纯相对时间（"5分钟后"、"1小时后"）可直接计算，无需确认。时间模糊或缺失时需追问。
+
+---
+
+## 回复模板
+
+- 一次性：`⏰ 好的，{时间}后提醒你{内容}~`
+- 周期：`⏰ 收到，{周期}提醒你{内容}~`
+- 查询无结果：`📋 目前没有提醒哦~ 说"5分钟后提醒我xxx"试试？`
+- 删除成功：`✅ 已取消"{名称}"`

package/src/admin-resolver.ts

@@ -0,0 +1,140 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+
+import path from "node:path";
+import * as fs from "node:fs";
+import { getQQBotDataDir } from "./utils/platform.js";
+import { listKnownUsers } from "./known-users.js";
+import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
+import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
+
+// ---- 类型 ----
+
+export interface AdminResolverContext {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+// ---- 文件路径 ----
+
+function getAdminMarkerFile(accountId: string): string {
+  return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
+}
+
+function getUpgradeGreetingTargetFile(accountId: string, appId: string): string {
+  const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const safeAppId = appId.replace(/[^a-zA-Z0-9._-]/g, "_");
+  return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeAccountId}-${safeAppId}.json`);
+}
+
+// ---- 管理员 openid 持久化 ----
+
+export function loadAdminOpenId(accountId: string): string | undefined {
+  try {
+    const file = getAdminMarkerFile(accountId);
+    if (fs.existsSync(file)) {
+      const data = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (data.openid) return data.openid;
+    }
+  } catch { /* 文件损坏视为无 */ }
+  return undefined;
+}
+
+export function saveAdminOpenId(accountId: string, openid: string): void {
+  try {
+    fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+  } catch { /* ignore */ }
+}
+
+// ---- 升级问候目标 ----
+
+export function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string): string | undefined {
+  try {
+    const file = getUpgradeGreetingTargetFile(accountId, appId);
+    if (fs.existsSync(file)) {
+      const data = JSON.parse(fs.readFileSync(file, "utf8")) as { accountId?: string; appId?: string; openid?: string };
+      if (!data.openid) return undefined;
+      if (data.appId && data.appId !== appId) return undefined;
+      if (data.accountId && data.accountId !== accountId) return undefined;
+      return data.openid;
+    }
+  } catch { /* 文件损坏视为无 */ }
+  return undefined;
+}
+
+export function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void {
+  try {
+    const file = getUpgradeGreetingTargetFile(accountId, appId);
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  } catch { /* ignore */ }
+}
+
+// ---- 解析管理员 ----
+
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（稳定）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined {
+  const saved = loadAdminOpenId(ctx.accountId);
+  if (saved) return saved;
+  const first = listKnownUsers({ accountId: ctx.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+  if (first) {
+    saveAdminOpenId(ctx.accountId, first);
+    ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+  }
+  return first;
+}
+
+// ---- 启动问候语 ----
+
+/** 异步发送启动问候语（仅发给管理员） */
+export function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void {
+  (async () => {
+    const plan = getStartupGreetingPlan();
+    if (!plan.shouldSend || !plan.greeting) {
+      ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (${plan.reason ?? "debounced"}, trigger=${trigger})`);
+      return;
+    }
+
+    const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+    const targetOpenId = upgradeTargetOpenId || resolveAdminOpenId(ctx);
+    if (!targetOpenId) {
+      markStartupGreetingFailed(plan.version, "no-admin");
+      ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (no admin or known user)`);
+      return;
+    }
+
+    try {
+      const receiverType = upgradeTargetOpenId ? "upgrade-requester" : "admin";
+      ctx.log?.info(`[qqbot:${ctx.accountId}] Sending startup greeting to ${receiverType} (trigger=${trigger}): "${plan.greeting}"`);
+      const token = await getAccessToken(ctx.appId, ctx.clientSecret);
+      const GREETING_TIMEOUT_MS = 10_000;
+      await Promise.race([
+        sendProactiveC2CMessage(token, targetOpenId, plan.greeting),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+      ]);
+      markStartupGreetingSent(plan.version);
+      if (upgradeTargetOpenId) {
+        clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+      }
+      ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to ${receiverType}: ${targetOpenId}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      markStartupGreetingFailed(plan.version, message);
+      ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
+    }
+  })();
+}