@tencent-connect/openclaw-qqbot 1.6.4-alpha.qqchannel → 1.6.4

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.5.7`
+### 🚀 Current Version: `v1.6.4`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -25,7 +25,7 @@
 
 Scan to join the QQ group chat
 
-<img width="300" height="540" alt="Clipboard_Screenshot_1773047715" src="https://github.com/user-attachments/assets/4d2d2337-229a-42ad-97ab-8a6d0607f296" />
+<img width="400" alt="QQ QR Code" src="./docs/images/developer_group.png" />
 
 
 </div>
@@ -36,13 +36,13 @@ Scan to join the QQ group chat
 
 | Feature | Description |
 |---------|-------------|
-| 🔒 **Multi-Scene** | C2C private chat, group @messages, channel messages, channel DMs |
+| 🔒 **Multi-Scene** | C2C private chat, group @messages |
 | 🖼️ **Rich Media** | Send & receive images, voice, video, and files |
 | 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |
+| 🔥 **One-Click Hot Upgrade** | Send `/bot-upgrade` in private chat to upgrade — no server login needed |
 | ⏰ **Scheduled Push** | Proactive message delivery via scheduled tasks |
 | 🔗 **URL Support** | Direct URL sending in private chat (no restrictions) |
 | ⌨️ **Typing Indicator** | "Bot is typing..." status shown in real-time |
-| 🔄 **Hot Reload** | Install via npm with seamless hot updates |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
@@ -99,7 +99,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 >
 > **QQBot**: Here you go! 🐱
 
-AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
+AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
 
@@ -109,7 +109,7 @@ AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Format
 >
 > **QQBot**: *(sends a voice message)*
 
-AI sends voice via `<qqvoice>path</qqvoice>`. Formats: mp3/wav/silk/ogg. No ffmpeg required.
+AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
 
@@ -129,7 +129,7 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
+AI can send files directly. Any format, up to 20MB.
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
 
@@ -139,21 +139,80 @@ AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
 >
 > **QQBot**: *(sends a video)*
 
-AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. Large files (>5MB) auto-show upload progress.
+AI can send videos directly. Supports local files and URLs.
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
 
-### Rich Media Tag Reference
+> **Under the hood:** Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
 
-| Tag | Direction | Notes |
-|-----|-----------|-------|
-| `<qqimg>path</qqimg>` | Send | jpg/png/gif/webp/bmp, local path or URL |
-| `<qqvoice>path</qqvoice>` | Send | mp3/wav/silk/ogg, no ffmpeg required |
-| `<qqfile>path</qqfile>` | Send | Any format, up to 20MB |
-| `<qqvideo>path</qqvideo>` | Send | Local path or URL |
-| Voice / File / Image | Receive | Auto-transcribe (STT), auto-download, or vision analysis |
+### 🛠️ Slash Commands
 
-> **Under the hood:** 30+ tag variant auto-correction, upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
+The plugin provides built-in slash commands that are intercepted before reaching the AI queue, giving instant responses for diagnostics and management.
+
+#### `/bot-ping` — Latency Test
+
+> **You**: `/bot-ping`
+>
+> **QQBot**: ✅ pong！⏱ Latency: 602ms (network: 602ms, plugin: 0ms)
+
+Measures end-to-end latency from QQ server push to plugin response, broken down into network transport and plugin processing time.
+
+<img width="360" src="docs/images/slash-ping.jpg" alt="Ping Demo" />
+
+#### `/bot-version` — Version Info
+
+> **You**: `/bot-version`
+>
+> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.3 / 🌟 GitHub repo
+
+Shows framework version, plugin version, and a direct link to the official repository.
+
+<img width="360" src="docs/images/slash-version.jpg" alt="Version Demo" />
+
+#### `/bot-help` — Command List
+
+> **You**: `/bot-help`
+>
+> **QQBot**: Lists all available slash commands with clickable shortcuts.
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
+
+#### `/bot-upgrade` — One-Click Hot Upgrade
+
+> **You**: `/bot-upgrade`
+>
+> **QQBot**: 📌 Current: v1.6.3 / ✅ New version v1.6.4 available / Click button below to confirm
+
+Send in private chat to upgrade the plugin without server login. Supported usage:
+
+| Command | Description |
+|---------|-------------|
+| `/bot-upgrade` | Check for updates, show confirmation button |
+| `/bot-upgrade --latest` | Confirm upgrade to the latest version |
+| `/bot-upgrade --version 1.6.4` | Upgrade to a specific version |
+| `/bot-upgrade --force` | Force reinstall current version |
+
+Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.
+
+<!-- TODO: add /bot-upgrade screenshot -->
+
+#### `/bot-logs` — Log Export
+
+> **You**: `/bot-logs`
+>
+> **QQBot**: 📋 Logs packaged (~2000 lines), sending file... *(sends a .txt file)*
+
+Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting.
+
+<img width="360" src="docs/images/slash-logs.jpg" alt="Logs Demo" />
+
+#### Usage Help
+
+All commands support a `?` suffix to show usage:
+
+> **You**: `/bot-upgrade ?`
+>
+> **QQBot**: 📖 /bot-upgrade usage: …
 
 ---
 
@@ -379,7 +438,7 @@ STT supports two-level configuration with priority fallback:
 - `provider` — references a key in `models.providers` to inherit `baseUrl` and `apiKey`
 - `voice` — voice variant
 - Set `enabled: false` to disable (default: `true`)
-- When configured, AI can use `<qqvoice>` tags to generate and send voice messages
+- When configured, AI can generate and send voice messages
 
 ---
 
@@ -389,6 +448,26 @@ STT supports two-level configuration with priority fallback:
 - [Command Reference](docs/commands.md) — OpenClaw CLI commands
 - [Changelog](CHANGELOG.md) — release notes
 
+## 🤝 Contributors
+
+Thanks to all the developers who have contributed to this project!
+
+<a href="https://github.com/tencent-connect/openclaw-qqbot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=tencent-connect/openclaw-qqbot" />
+</a>
+
+## 💖 Acknowledgements
+
+Special thanks to [@sliverp](https://github.com/sliverp) for outstanding contributions to the project!
+
+<a href="https://github.com/sliverp"><img src="https://avatars.githubusercontent.com/u/38134380?v=4" width="48" height="48" alt="sliverp" title="sliverp"/></a>
+
+Thanks to [Tencent Cloud Lighthouse](https://cloud.tencent.com/product/lighthouse) for the deep collaboration. For raising crawfish, choose Tencent Cloud Lighthouse!
+
+<a href="https://cloud.tencent.com/product/lighthouse">
+  <img alt="Tencent Cloud Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+</a>
+
 ## ⭐ Star History
 
 <div align="center">

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.5.7`
+### 🚀 当前版本： `v1.6.4`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -21,7 +21,7 @@
 
 扫描二维码加入群聊，一起交流
 
-<img width="316" height="410" alt="QQ 群二维码" src="https://github.com/user-attachments/assets/d079ba89-ecd0-437f-9e66-92319801a325" />
+<img width="400" alt="QQ 群二维码" src="./docs/images/developer_group.png" />
 
 </div>
 
@@ -31,13 +31,13 @@
 
 | 功能 | 说明 |
 |------|------|
-| 🔒 **多场景支持** | C2C 私聊、群聊 @消息、频道消息、频道私信 |
+| 🔒 **多场景支持** | C2C 私聊、群聊 @消息 |
 | 🖼️ **富媒体消息** | 支持图片、语音、视频、文件的收发 |
 | 🎙️ **语音能力 (STT/TTS)** | 语音转文字自动转录 & 文字转语音回复 |
+| 🔥 **一键热更新** | 私聊发送 `/bot-upgrade` 即可完成版本升级，无需登录服务器 |
 | ⏰ **定时推送** | 支持定时任务触发后主动推送消息 |
 | 🔗 **URL 无限制** | 私聊可直接发送 URL |
 | ⌨️ **输入状态** | 实时显示"Bot 正在输入中…"状态 |
-| 🔄 **热更新** | 支持 npm 方式安装和无缝热更新 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
@@ -94,7 +94,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：画好啦！一只可爱的简笔小猫咪🐱🎨
 
-AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
+AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
@@ -104,7 +104,7 @@ AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网
 >
 > **QQBot**：*（发送一条语音消息）*
 
-AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
+AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
 
@@ -124,7 +124,7 @@ AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
+AI 可直接发送文件。任意格式，最大 20MB。
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
 
@@ -134,21 +134,80 @@ AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
 >
 > **QQBot**：*（发送视频）*
 
-AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示上传进度。
+AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
 
-### 富媒体标签参考
+> **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
 
-| 标签 | 方向 | 说明 |
-|------|------|------|
-| `<qqimg>路径</qqimg>` | 发送 | jpg/png/gif/webp/bmp，本地路径或 URL |
-| `<qqvoice>路径</qqvoice>` | 发送 | mp3/wav/silk/ogg，无需 ffmpeg |
-| `<qqfile>路径</qqfile>` | 发送 | 任意格式，最大 20MB |
-| `<qqvideo>路径</qqvideo>` | 发送 | 本地路径或 URL |
-| 语音 / 文件 / 图片 | 接收 | 自动转录(STT)、自动下载、或视觉分析 |
+### 🛠️ 斜杠指令
 
-> **底层细节：** 30+ 种标签变体自动纠正、上传去重缓存、有序队列发送、音频格式多层降级。
+插件内置一组斜杠指令，在消息进入 AI 队列前拦截处理，即时响应，用于诊断和管理。
+
+#### `/bot-ping` — 延迟测试
+
+> **你**：`/bot-ping`
+>
+> **QQBot**：✅ pong！⏱ 延迟: 602ms（网络传输: 602ms，插件处理: 0ms）
+
+测量从 QQ 服务器推送到插件响应的端到端延迟，细分网络传输和插件处理两段耗时。
+
+<img width="360" src="docs/images/slash-ping.jpg" alt="Ping 演示" />
+
+#### `/bot-version` — 版本信息
+
+> **你**：`/bot-version`
+>
+> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.3 / 🌟官方 GitHub 仓库
+
+一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
+
+<img width="360" src="docs/images/slash-version.jpg" alt="Version 演示" />
+
+#### `/bot-help` — 指令列表
+
+> **你**：`/bot-help`
+>
+> **QQBot**：列出所有可用的斜杠指令及说明，指令可点击快速输入。
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
+
+#### `/bot-upgrade` — 一键热更新
+
+> **你**：`/bot-upgrade`
+>
+> **QQBot**：📌当前版本 v1.6.3 / ✅发现新版本 v1.6.4 / 点击下方按钮确认升级
+
+在私聊中发送即可完成版本升级，全程无需登录服务器。支持的用法：
+
+| 命令 | 说明 |
+|------|------|
+| `/bot-upgrade` | 检查是否有新版本，展示确认按钮 |
+| `/bot-upgrade --latest` | 确认升级到最新版本 |
+| `/bot-upgrade --version 1.6.4` | 升级到指定版本 |
+| `/bot-upgrade --force` | 强制重新安装当前版本 |
+
+升级流程自动备份凭证，升级前校验版本是否存在于 npm，升级失败自动恢复。
+
+<!-- TODO: 补充 /bot-upgrade 截图 -->
+
+#### `/bot-logs` — 日志导出
+
+> **你**：`/bot-logs`
+>
+> **QQBot**：📋 日志已打包（约 2000 行），正在发送文件… *（发送 .txt 文件）*
+
+导出最近约 2000 行网关日志为文件，方便快速排查问题。
+
+<img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
+
+#### 用法查询
+
+所有指令都支持 `?` 后缀查看用法说明：
+
+> **你**：`/bot-upgrade ?`
+>
+> **QQBot**：📖 /bot-upgrade 用法：…
 
 ---
 
@@ -374,7 +433,7 @@ STT 支持两级配置，按优先级查找：
 - `provider` — 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`
 - `voice` — 语音音色
 - 设置 `enabled: false` 可禁用（默认：`true`）
-- 配置后，AI 可使用 `<qqvoice>` 标签生成并发送语音消息
+- 配置后，AI 可生成并发送语音消息
 
 ---
 
@@ -384,6 +443,26 @@ STT 支持两级配置，按优先级查找：
 - [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
 - [更新日志](CHANGELOG.md) — 各版本变更记录
 
+## 🤝 贡献者
+
+感谢所有为本项目做出贡献的开发者！
+
+<a href="https://github.com/tencent-connect/openclaw-qqbot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=tencent-connect/openclaw-qqbot" />
+</a>
+
+## 💖 致谢
+
+特别感谢 [@sliverp](https://github.com/sliverp) 对项目的核心贡献！
+
+<a href="https://github.com/sliverp"><img src="https://avatars.githubusercontent.com/u/38134380?v=4" width="48" height="48" alt="sliverp" title="sliverp"/></a>
+
+感谢[腾讯云Lighthouse](https://cloud.tencent.com/product/lighthouse)的深度合作，养小龙虾，首选腾讯云Lighthouse！
+
+<a href="https://cloud.tencent.com/product/lighthouse">
+  <img alt="腾讯云 Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+</a>
+
 ## ⭐ Star History
 
 <div align="center">

package/clawdbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -2,6 +2,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
 import { registerChannelTool } from "./src/tools/channel.js";
+import { registerRemindTool } from "./src/tools/remind.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -11,6 +12,7 @@ const plugin = {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
         registerChannelTool(api);
+        registerRemindTool(api);
     },
 };
 export default plugin;

package/dist/src/admin-resolver.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+export interface AdminResolverContext {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+export declare function loadAdminOpenId(accountId: string): string | undefined;
+export declare function saveAdminOpenId(accountId: string, openid: string): void;
+export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string): string | undefined;
+export declare function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void;
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（稳定）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined;
+/** 异步发送启动问候语（仅发给管理员） */
+export declare function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void;

package/dist/src/admin-resolver.js

@@ -0,0 +1,122 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 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";
+// ---- 文件路径 ----
+function getAdminMarkerFile(accountId) {
+    return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
+}
+function getUpgradeGreetingTargetFile(accountId, appId) {
+    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) {
+    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, openid) {
+    try {
+        fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+    }
+    catch { /* ignore */ }
+}
+// ---- 升级问候目标 ----
+export function loadUpgradeGreetingTargetOpenId(accountId, appId) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            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, appId) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            fs.unlinkSync(file);
+        }
+    }
+    catch { /* ignore */ }
+}
+// ---- 解析管理员 ----
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（稳定）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export function resolveAdminOpenId(ctx) {
+    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, trigger) {
+    (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}`);
+        }
+    })();
+}

package/dist/src/api.js

@@ -58,8 +58,12 @@ const tokenFetchPromises = new Map();
 export async function getAccessToken(appId, clientSecret) {
     const normalizedAppId = String(appId).trim();
     const cachedToken = tokenCacheMap.get(normalizedAppId);
-    // 检查缓存：未过期 且 appId 未变化 时复用
-    if (cachedToken && Date.now() < cachedToken.expiresAt - 5 * 60 * 1000) {
+    // 检查缓存：未过期时复用
+    // 提前刷新阈值：取 expiresIn 的 1/3 和 5 分钟的较小值，避免短有效期 token 永远被判定过期
+    const REFRESH_AHEAD_MS = cachedToken
+        ? Math.min(5 * 60 * 1000, (cachedToken.expiresAt - Date.now()) / 3)
+        : 0;
+    if (cachedToken && Date.now() < cachedToken.expiresAt - REFRESH_AHEAD_MS) {
         return cachedToken.token;
     }
     // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
@@ -159,7 +163,8 @@ export function getTokenStatus(appId) {
     if (!cached) {
         return { status: "none", expiresAt: null };
     }
-    const isValid = Date.now() < cached.expiresAt - 5 * 60 * 1000;
+    const remaining = cached.expiresAt - Date.now();
+    const isValid = remaining > Math.min(5 * 60 * 1000, remaining / 3);
     return { status: isValid ? "valid" : "expired", expiresAt: cached.expiresAt };
 }
 /**

package/dist/src/channel.d.ts

@@ -1,3 +1,11 @@
 import { type ChannelPlugin } from "openclaw/plugin-sdk";
 import type { ResolvedQQBotAccount } from "./types.js";
+/** QQ Bot 单条消息文本长度上限 */
+export declare const TEXT_CHUNK_LIMIT = 5000;
+/**
+ * Markdown 感知的文本分块函数
+ * 委托给 SDK 内置的 channel.text.chunkMarkdownText
+ * 支持代码块自动关闭/重开、括号感知等
+ */
+export declare function chunkText(text: string, limit: number): string[];
 export declare const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount>;