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

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.0`
 
 [![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/)
@@ -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,63 @@ 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.
+
+#### `/qqbot-ping` — Latency Test
+
+> **You**: `/qqbot-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" />
+
+#### `/qqbot-version` — Version Info
+
+> **You**: `/qqbot-version`
+>
+> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.0 / 🌟 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" />
+
+#### `/qqbot-help` — Command List
+
+> **You**: `/qqbot-help`
+>
+> **QQBot**: Lists all available slash commands with clickable shortcuts.
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
+
+#### `/qqbot-upgrade` — Upgrade Guide
+
+> **You**: `/qqbot-upgrade`
+>
+> **QQBot**: 📌 Current version / ✅ Up to date / ⬆️ Upgrade guide / 🌟 GitHub repo
+
+Shows current version, update status, upgrade guide link, and official repository.
+
+<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade Demo" /> 
+
+#### `/qqbot-logs` — Log Export
+
+> **You**: `/qqbot-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" />
 
 ---
 
@@ -379,7 +421,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
 
 ---
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.5.7`
+### 🚀 当前版本： `v1.6.0`
 
 [![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/)
@@ -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,63 @@ 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 队列前拦截处理，即时响应，用于诊断和管理。
+
+#### `/qqbot-ping` — 延迟测试
+
+> **你**：`/qqbot-ping`
+>
+> **QQBot**：✅ pong！⏱ 延迟: 602ms（网络传输: 602ms，插件处理: 0ms）
+
+测量从 QQ 服务器推送到插件响应的端到端延迟，细分网络传输和插件处理两段耗时。
+
+<img width="360" src="docs/images/slash-ping.jpg" alt="Ping 演示" />
+
+#### `/qqbot-version` — 版本信息
+
+> **你**：`/qqbot-version`
+>
+> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.0 / 🌟官方 GitHub 仓库
+
+一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
+
+<img width="360" src="docs/images/slash-version.jpg" alt="Version 演示" />
+
+#### `/qqbot-help` — 指令列表
+
+> **你**：`/qqbot-help`
+>
+> **QQBot**：列出所有可用的斜杠指令及说明，指令可点击快速输入。
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
+
+#### `/qqbot-upgrade` — 升级指引
+
+> **你**：`/qqbot-upgrade`
+>
+> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
+
+显示当前版本、更新状态、升级文档链接及官方仓库入口。
+
+<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade 演示" /> 
+
+#### `/qqbot-logs` — 日志导出
+
+> **你**：`/qqbot-logs`
+>
+> **QQBot**：📋 日志已打包（约 2000 行），正在发送文件… *（发送 .txt 文件）*
+
+导出最近约 2000 行网关日志为文件，方便快速排查问题。
+
+<img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
 
 ---
 
@@ -374,7 +416,7 @@ STT 支持两级配置，按优先级查找：
 - `provider` — 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`
 - `voice` — 语音音色
 - 设置 `enabled: false` 可禁用（默认：`true`）
-- 配置后，AI 可使用 `<qqvoice>` 标签生成并发送语音消息
+- 配置后，AI 可生成并发送语音消息
 
 ---
 

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-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -1,7 +1,6 @@
 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";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -10,7 +9,6 @@ const plugin = {
     register(api) {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
-        registerChannelTool(api);
     },
 };
 export default plugin;

package/dist/src/api.d.ts

@@ -81,15 +81,6 @@ export declare function sendChannelMessage(accessToken: string, channelId: strin
     id: string;
     timestamp: string;
 }>;
-/**
- * 发送频道私信消息
- * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
- * @param msgId - 被动回复时必填
- */
-export declare function sendDmMessage(accessToken: string, guildId: string, content: string, msgId?: string): Promise<{
-    id: string;
-    timestamp: string;
-}>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{

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 };
 }
 /**
@@ -335,17 +340,6 @@ export async function sendChannelMessage(accessToken, channelId, content, msgId)
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
-/**
- * 发送频道私信消息
- * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
- * @param msgId - 被动回复时必填
- */
-export async function sendDmMessage(accessToken, guildId, content, msgId) {
-    return apiRequest(accessToken, "POST", `/dms/${guildId}/messages`, {
-        content,
-        ...(msgId ? { msg_id: msgId } : {}),
-    });
-}
 export async function sendGroupMessage(accessToken, groupOpenid, content, msgId) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
     const body = buildMessageBody(content, msgId, msgSeq);

package/dist/src/gateway.js

@@ -1,13 +1,13 @@
 import WebSocket from "ws";
 import path from "node:path";
 import * as fs from "node:fs";
-import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage, sendProactiveGroupMessage } from "./api.js";
+import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage } from "./api.js";
 import { loadSession, saveSession, clearSession } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.js";
 import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex } from "./ref-index-store.js";
-import { matchSlashCommand } from "./slash-commands.js";
-import { triggerUpdateCheck } from "./update-checker.js";
+import { matchSlashCommand, getPluginVersion } from "./slash-commands.js";
+import { triggerUpdateCheck, onUpdateFound, formatUpdateNotice } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, downloadFile } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload } from "./utils/payload.js";
@@ -258,6 +258,47 @@ async function ensureImageServer(log, publicBaseUrl) {
         return null;
     }
 }
+// ============ 启动问候语（首次安装/版本更新 vs 普通重启） ============
+// 模块级变量：进程生命周期内只有首次为 true
+// 区分 gateway restart（进程重启）和 health-monitor 断线重连
+let isFirstReadyGlobal = true;
+const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
+/**
+ * 判断是否为首次安装或版本更新，返回对应的问候语。
+ * - 首次安装 / 版本变更 → "Haha，我的'灵魂'已上线，随时等你吩咐。"
+ * - 普通重启（同版本） → null（不发送）
+ */
+function getStartupGreeting() {
+    const currentVersion = getPluginVersion();
+    let isFirstOrUpdated = true;
+    try {
+        if (fs.existsSync(STARTUP_MARKER_FILE)) {
+            const data = JSON.parse(fs.readFileSync(STARTUP_MARKER_FILE, "utf8"));
+            if (data.version === currentVersion) {
+                isFirstOrUpdated = false;
+            }
+        }
+    }
+    catch {
+        // 文件损坏或不存在，视为首次
+    }
+    // 普通重启（同版本）不发送问候语
+    if (!isFirstOrUpdated) {
+        return null;
+    }
+    // 更新 marker 文件
+    try {
+        fs.writeFileSync(STARTUP_MARKER_FILE, JSON.stringify({
+            version: currentVersion,
+            startedAt: new Date().toISOString(),
+            greetedAt: new Date().toISOString(),
+        }) + "\n");
+    }
+    catch {
+        // ignore
+    }
+    return `Haha，我的'灵魂'已上线，随时等你吩咐。`;
+}
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
  * 支持流式消息发送
@@ -276,6 +317,34 @@ export async function startGateway(ctx) {
     }
     // 后台版本检查（detached 子进程，零阻塞）
     triggerUpdateCheck(log);
+    // 注册新版本通知回调：仅发给管理员，带防抖
+    let lastUpdateNotifyAt = 0;
+    const UPDATE_NOTIFY_DEBOUNCE_MS = 5 * 60 * 1000; // 5 分钟内不重复通知
+    onUpdateFound(async (info) => {
+        try {
+            // 防抖：避免短时间内重复推送
+            const now = Date.now();
+            if (now - lastUpdateNotifyAt < UPDATE_NOTIFY_DEBOUNCE_MS) {
+                log?.debug?.(`[qqbot:${account.accountId}] Update notification debounced`);
+                return;
+            }
+            const notice = formatUpdateNotice(info);
+            if (!notice)
+                return;
+            const adminId = resolveAdminOpenId();
+            if (!adminId) {
+                log?.debug?.(`[qqbot:${account.accountId}] No admin or known user to send update notification`);
+                return;
+            }
+            const token = await getAccessToken(account.appId, account.clientSecret);
+            await sendProactiveC2CMessage(token, adminId, notice);
+            lastUpdateNotifyAt = Date.now();
+            log?.info(`[qqbot:${account.accountId}] Sent update notification to admin: ${adminId}`);
+        }
+        catch (err) {
+            log?.debug?.(`[qqbot:${account.accountId}] Failed to send update notification to admin: ${err}`);
+        }
+    });
     // 初始化 API 配置（markdown 支持）
     initApiConfig({
         markdownSupport: account.markdownSupport,
@@ -348,7 +417,76 @@ export async function startGateway(ctx) {
     let isConnecting = false; // 防止并发连接
     let reconnectTimer = null; // 重连定时器
     let shouldRefreshToken = false; // 下次连接是否需要刷新 token
-    let isFirstReady = true; // 仅 startGateway 后首次 READY 才发送上线通知
+    // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
+    // health-monitor 重连不会重新初始化为 true
+    const ADMIN_MARKER_FILE = path.join(getQQBotDataDir("data"), `admin-${account.accountId}.json`);
+    /**
+     * 读取已持久化的管理员 openid
+     */
+    const loadAdminOpenId = () => {
+        try {
+            if (fs.existsSync(ADMIN_MARKER_FILE)) {
+                const data = JSON.parse(fs.readFileSync(ADMIN_MARKER_FILE, "utf8"));
+                if (data.openid)
+                    return data.openid;
+            }
+        }
+        catch { /* 文件损坏视为无 */ }
+        return undefined;
+    };
+    /**
+     * 将管理员 openid 持久化到文件
+     */
+    const saveAdminOpenId = (openid) => {
+        try {
+            fs.writeFileSync(ADMIN_MARKER_FILE, JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+        }
+        catch { /* ignore */ }
+    };
+    /**
+     * 解析管理员 openid：
+     * 1. 优先读持久化文件（稳定）
+     * 2. fallback 取第一个私聊用户，并写入文件锁定
+     */
+    const resolveAdminOpenId = () => {
+        const saved = loadAdminOpenId();
+        if (saved)
+            return saved;
+        const first = listKnownUsers({ accountId: account.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+        if (first) {
+            saveAdminOpenId(first);
+            log?.info(`[qqbot:${account.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+        }
+        return first;
+    };
+    /** 异步发送启动问候语（仅发给管理员） */
+    const sendStartupGreetings = (trigger) => {
+        (async () => {
+            try {
+                const greeting = getStartupGreeting();
+                if (!greeting) {
+                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (debounced, trigger=${trigger})`);
+                    return;
+                }
+                const adminId = resolveAdminOpenId();
+                if (!adminId) {
+                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (no admin or known user)`);
+                    return;
+                }
+                log?.info(`[qqbot:${account.accountId}] Sending startup greeting to admin (trigger=${trigger}): "${greeting}"`);
+                const token = await getAccessToken(account.appId, account.clientSecret);
+                const GREETING_TIMEOUT_MS = 10_000;
+                await Promise.race([
+                    sendProactiveC2CMessage(token, adminId, greeting),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+                ]);
+                log?.info(`[qqbot:${account.accountId}] Sent startup greeting to admin: ${adminId}`);
+            }
+            catch (err) {
+                log?.error(`[qqbot:${account.accountId}] Failed to send startup greeting: ${err}`);
+            }
+        })();
+    };
     // ============ P1-2: 尝试从持久化存储恢复 Session ============
     // 传入当前 appId，如果 appId 已变更（换了机器人），旧 session 自动失效
     const savedSession = loadSession(account.accountId, account.appId);
@@ -488,18 +626,41 @@ export async function startGateway(ctx) {
             // 命中插件级指令，直接回复
             log?.info(`[qqbot:${account.accountId}] Slash command matched: ${content}, replying directly`);
             const token = await getAccessToken(account.appId, account.clientSecret);
+            // 解析回复：纯文本 or 带文件的结果
+            const isFileResult = typeof reply === "object" && reply !== null && "filePath" in reply;
+            const replyText = isFileResult ? reply.text : reply;
+            const replyFile = isFileResult ? reply.filePath : null;
+            // 先发送文本回复
             if (msg.type === "c2c") {
-                await sendC2CMessage(token, msg.senderId, reply, msg.messageId);
+                await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
             }
             else if (msg.type === "group" && msg.groupOpenid) {
-                await sendGroupMessage(token, msg.groupOpenid, reply, msg.messageId);
+                await sendGroupMessage(token, msg.groupOpenid, replyText, msg.messageId);
             }
             else if (msg.channelId) {
-                await sendChannelMessage(token, msg.channelId, reply, msg.messageId);
+                await sendChannelMessage(token, msg.channelId, replyText, msg.messageId);
             }
             else if (msg.type === "dm") {
-                // 频道私信走 C2C
-                await sendC2CMessage(token, msg.senderId, reply, msg.messageId);
+                await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
+            }
+            // 如果有文件需要发送
+            if (replyFile) {
+                try {
+                    const targetType = msg.type === "group" ? "group" : msg.type === "c2c" || msg.type === "dm" ? "c2c" : "channel";
+                    const targetId = msg.type === "group" ? (msg.groupOpenid || msg.senderId) : msg.type === "c2c" || msg.type === "dm" ? msg.senderId : (msg.channelId || msg.senderId);
+                    const mediaCtx = {
+                        targetType,
+                        targetId,
+                        account,
+                        replyToId: msg.messageId,
+                        logPrefix: `[qqbot:${account.accountId}]`,
+                    };
+                    await sendDocument(mediaCtx, replyFile);
+                    log?.info(`[qqbot:${account.accountId}] Slash command file sent: ${replyFile}`);
+                }
+                catch (fileErr) {
+                    log?.error(`[qqbot:${account.accountId}] Failed to send slash command file: ${fileErr}`);
+                }
             }
         }
         catch (err) {
@@ -924,10 +1085,10 @@ export async function startGateway(ctx) {
                 const staticParts = [
                     `[QQBot] to=${qualifiedTarget}`,
                 ];
-                // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
+                // TTS 能力声明：仅在启用时告知 AI 可以发语音（媒体标签用法由 qqbot-media SKILL.md 提供）
                 // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
                 if (hasTTS)
-                    staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
+                    staticParts.push("语音合成已启用");
                 const staticInstruction = staticParts.join(" | ");
                 // 静态指引作为 systemPrompts 的首项注入
                 systemPrompts.unshift(staticInstruction);
@@ -2196,54 +2357,21 @@ export async function startGateway(ctx) {
                                 onReady?.(d);
                                 // 仅 startGateway 后的首次 READY 才发送上线通知
                                 // ws 断线重连（resume 失败后重新 Identify）产生的 READY 不发送
-                                if (!isFirstReady) {
+                                if (!isFirstReadyGlobal) {
                                     log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (reconnect READY, not first startup)`);
                                 }
                                 else {
-                                    isFirstReady = false;
-                                    (async () => {
-                                        try {
-                                            const greeting = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
-                                            const token = await getAccessToken(account.appId, account.clientSecret);
-                                            const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
-                                            for (const user of users) {
-                                                try {
-                                                    await sendProactiveC2CMessage(token, user.openid, greeting);
-                                                    log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
-                                                }
-                                                catch (err) {
-                                                    log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
-                                                }
-                                                // 避免频率限制
-                                                await new Promise(r => setTimeout(r, 500));
-                                            }
-                                            const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
-                                            // 群组去重（同一群只发一次）
-                                            const sentGroups = new Set();
-                                            for (const user of groups) {
-                                                const gid = user.groupOpenid;
-                                                if (!gid || sentGroups.has(gid))
-                                                    continue;
-                                                sentGroups.add(gid);
-                                                try {
-                                                    await sendProactiveGroupMessage(token, gid, greeting);
-                                                    log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
-                                                }
-                                                catch (err) {
-                                                    log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
-                                                }
-                                                await new Promise(r => setTimeout(r, 500));
-                                            }
-                                            log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
-                                        }
-                                        catch (err) {
-                                            log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
-                                        }
-                                    })();
+                                    isFirstReadyGlobal = false;
+                                    sendStartupGreetings("READY");
                                 } // end isFirstReady
                             }
                             else if (t === "RESUMED") {
                                 log?.info(`[qqbot:${account.accountId}] Session resumed`);
+                                // RESUMED 也属于首次启动（gateway restart 通常走 resume）
+                                if (isFirstReadyGlobal) {
+                                    isFirstReadyGlobal = false;
+                                    sendStartupGreetings("RESUMED");
+                                }
                                 // P1-2: 更新 Session 连接时间
                                 if (sessionId) {
                                     saveSession({

package/dist/src/slash-commands.d.ts

@@ -51,11 +51,19 @@ export interface QueueSnapshot {
     /** 当前发送者在队列中的待处理消息数 */
     senderPending: number;
 }
+/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+/** 带文件的指令结果（先回复文本，再发送文件） */
+export interface SlashCommandFileResult {
+    text: string;
+    /** 要发送的本地文件路径 */
+    filePath: string;
+}
 /**
  * 尝试匹配并执行插件级斜杠指令
  *
  * @returns 回复文本（匹配成功），null（不匹配，应入队正常处理）
  */
-export declare function matchSlashCommand(ctx: SlashCommandContext): Promise<string | null>;
+export declare function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult>;
 /** 获取插件版本号（供外部使用） */
 export declare function getPluginVersion(): string;