@tencent-connect/openclaw-qqbot 1.0.0-alpha.0 → 1.0.2-alpha.0

package/README.md

@@ -97,6 +97,16 @@ AI sends voice via `<qqvoice>path</qqvoice>`. Formats: mp3/wav/silk/ogg. No ffmp
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
 
+### ⏰ Scheduled Reminder (Proactive Message)
+
+> **You**: Remind me to eat in 5 minutes
+>
+> **QQBot**: confirms the reminder first, then proactively sends a voice + text reminder when time is up
+
+This capability depends on OpenClaw cron scheduling and proactive messaging. If no reminder arrives, a common reason is QQ-side interception of bot proactive messages.
+
+<img width="360" src="docs/images/reminder.jpg" alt="Scheduled Reminder Demo" />
+
 ### 📎 File Sending
 
 > **You**: Extract chapter 1 of War and Peace and send it as a file
@@ -142,65 +152,74 @@ AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. La
 2. After scanning, tap **Agree** on your phone — you'll land on the bot configuration page.
 3. Click **Create Bot** to create a new QQ bot.
 
-<img width="1982" height="1316" alt="Clipboard_Screenshot_1772980440" src="https://github.com/user-attachments/assets/3ccb494d-6e4d-462c-9218-b4dfd43a254f" />
+<img width="720" alt="Create Bot" src="docs/images/create_robot.png" />
+
+> ⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.
+
+<img width="400" alt="Bot Say Hello" src="docs/images/bot_say_hello.jpg" />
 
 4. Find **AppID** and **AppSecret** on the bot's page, click **Copy** for each, and save them somewhere safe (e.g., a notepad). **AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.**
 
-<img width="1670" height="1036" alt="Clipboard_Screenshot_1772980413" src="https://github.com/user-attachments/assets/b898d171-5711-4d42-bc07-2de967b119ec" />
+<img width="720" alt="Find AppID and AppSecret" src="docs/images/find_appid_secret.png" />
 
 > For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
 
-> ⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.
+### Step 2 — Install / Upgrade the Plugin
 
-### Step 2 — Install the Plugin
-
-**Option A: One-Click Install & Run (Recommended)**
+**Option A: Remote One-Liner (Easiest, no clone required)**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
+  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-The script handles everything: cleanup old plugins → install deps → register plugin → configure channel → start service. Once done, skip to [Step 4](#step-4--start--test).
+One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!
+
+> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
 
-**Option B: Manual Step-by-Step**
+**Option B: Local Script (if you've cloned the repo)**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-npm install --omit=dev
-openclaw plugins install .
+# Via npm
+bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET
+
+# Or via source
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-### Step 3 — Configure OpenClaw
+**Common flags:**
 
-**Option 1: CLI Wizard (Recommended)**
+| Flag | Description |
+|------|-------------|
+| `--appid <id> --secret <secret>` | Configure channel (required for first install, or to change credentials) |
+| `--version <version>` | Install a specific version (npm script only) |
+| `--self-version` | Install the version from local `package.json` (npm script only) |
+| `-h` / `--help` | Show full usage |
 
-```bash
-openclaw channels add --channel qqbot --token "AppID:AppSecret"
-```
+> Environment variables `QQBOT_APPID` / `QQBOT_SECRET` are also supported.
 
-**Option 2: Edit Config File**
+**Option C: Manual Install / Upgrade**
 
-Edit `~/.openclaw/openclaw.json`:
+```bash
+# Uninstall old plugins (skip if first install)
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "enabled": true,
-      "appId": "Your AppID",
-      "clientSecret": "Your AppSecret"
-    }
-  }
-}
-```
+# Install latest
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
 
-### Step 4 — Start & Test
+# Configure channel (first install only)
+openclaw channels add --channel qqbot --token "AppID:AppSecret"
 
-```bash
-openclaw gateway
+# Start / restart
+openclaw gateway restart
 ```
 
+### Step 3 — Test
+
 Open QQ, find your bot, and send a message!
 
 <div align="center">
@@ -348,39 +367,9 @@ STT supports two-level configuration with priority fallback:
 
 ---
 
-## 🔄 Upgrade
-
-Run the one-click script to upgrade and restart:
-
-```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-When no `--appid` / `--secret` is provided, the script reads existing config from `~/.openclaw/openclaw.json` automatically.
-
-```bash
-# First-time or override credentials
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>Full Options</summary>
-
-| Option | Description |
-|--------|-------------|
-| `--appid <id>` | QQ Bot AppID |
-| `--secret <secret>` | QQ Bot AppSecret |
-| `--markdown <yes\|no>` | Enable Markdown format (default: no) |
-| `-h, --help` | Show help |
-
-Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret) are also supported.
-
-</details>
-
----
-
 ## 📚 Documentation & Links
 
+- [Upgrade Guide](docs/UPGRADE_GUIDE.md) — full upgrade paths and migration notes
 - [Command Reference](docs/commands.md) — OpenClaw CLI commands
 - [Changelog](CHANGELOG.md) — release notes
 

package/README.zh.md

@@ -94,6 +94,16 @@ AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
 
+### ⏰ 定时提醒（主动消息）
+
+> **你**：5分钟后提醒我吃饭
+>
+> **QQBot**：先确认已创建提醒，到点后再主动推送语音 + 文本提醒
+
+该能力依赖 OpenClaw cron 调度与主动消息能力。若未收到提醒，常见原因是 QQ 侧拦截了机器人主动消息。
+
+<img width="360" src="docs/images/reminder.jpg" alt="定时提醒演示" />
+
 ### 📎 文件发送
 
 > **你**：战争与和平的第一章截取一下发文件给我
@@ -139,65 +149,74 @@ AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网
 2. 手机 QQ 扫码后选择**同意**，即完成注册，进入 QQ 机器人配置页。
 3. 点击**创建机器人**，即可直接新建一个 QQ 机器人。
 
-<img width="1982" height="1316" alt="Clipboard_Screenshot_1772980440" src="https://github.com/user-attachments/assets/3ccb494d-6e4d-462c-9218-b4dfd43a254f" />
+<img width="720" alt="创建机器人" src="docs/images/create_robot.png" />
+
+> ⚠️ 机器人创建后会自动出现在你的 QQ 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。
+
+<img width="400" alt="机器人打招呼" src="docs/images/bot_say_hello.jpg" />
 
 4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**
 
-<img width="1670" height="1036" alt="Clipboard_Screenshot_1772980413" src="https://github.com/user-attachments/assets/b898d171-5711-4d42-bc07-2de967b119ec" />
+<img width="720" alt="找到 AppID 和 AppSecret" src="docs/images/find_appid_secret.png" />
 
 > 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
 
-> ⚠️ 机器人创建后会自动出现在你的 QQ 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。
-
-### 第二步 — 安装插件
+### 第二步 — 安装 / 升级插件
 
-**方式一：一键安装并启动（推荐）**
+**方式一：远程一键执行（最简单，无需 clone 仓库）**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
+  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。
+一行命令搞定：下载脚本 → 清理旧插件 → 安装 → 配置通道 → 启动服务。完成后打开 QQ 即可开始聊天！
+
+> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级如已有配置：
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
 
-**方式二：手动分步安装**
+**方式二：本地脚本（已 clone 仓库时使用）**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-npm install --omit=dev
-openclaw plugins install .
+# 通过 npm 安装
+bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET
+
+# 或通过源码安装
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-### 第三步 — 配置 OpenClaw
+**常用参数：**
 
-**方式一：通过 Wizard 配置（推荐）**
+| 参数 | 说明 |
+|------|------|
+| `--appid <id> --secret <secret>` | 配置通道（首次安装必填，或更换凭证时使用） |
+| `--version <版本号>` | 安装指定版本（仅 npm 脚本） |
+| `--self-version` | 安装本地 `package.json` 中的版本（仅 npm 脚本） |
+| `-h` / `--help` | 查看完整用法 |
 
-```bash
-openclaw channels add --channel qqbot --token "AppID:AppSecret"
-```
+> 也可通过环境变量 `QQBOT_APPID` / `QQBOT_SECRET` 设置。
 
-**方式二：编辑配置文件**
+**方式三：手动安装 / 升级**
 
-编辑 `~/.openclaw/openclaw.json`：
+```bash
+# 卸载旧插件（首次安装可跳过）
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "enabled": true,
-      "appId": "你的 AppID",
-      "clientSecret": "你的 AppSecret"
-    }
-  }
-}
-```
+# 安装最新版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
 
-### 第四步 — 启动与测试
+# 配置通道（首次安装必做）
+openclaw channels add --channel qqbot --token "AppID:AppSecret"
 
-```bash
-openclaw gateway
+# 启动 / 重启
+openclaw gateway restart
 ```
 
+### 第三步 — 测试
+
 打开 QQ，找到你的机器人，发条消息试试！
 
 <div align="center">
@@ -345,39 +364,9 @@ STT 支持两级配置，按优先级查找：
 
 ---
 
-## 🔄 升级
-
-运行一键脚本即可升级并重启：
-
-```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-不传 `--appid` / `--secret` 参数时，脚本会自动读取 `~/.openclaw/openclaw.json` 中已有的配置。
-
-```bash
-# 首次配置或需要覆盖时
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>完整选项</summary>
-
-| 选项 | 说明 |
-|------|------|
-| `--appid <id>` | QQ 机器人 AppID |
-| `--secret <secret>` | QQ 机器人 AppSecret |
-| `--markdown <yes\|no>` | 是否启用 Markdown 消息格式（默认: no） |
-| `-h, --help` | 显示帮助 |
-
-也支持环境变量：`QQBOT_APPID`、`QQBOT_SECRET`、`QQBOT_TOKEN`（AppID:Secret）。
-
-</details>
-
----
-
 ## 📚 文档与链接
 
+- [升级指南](docs/UPGRADE_GUIDE.zh.md) — 完整升级路径与迁移说明
 - [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
 - [更新日志](CHANGELOG.md) — 各版本变更记录
 

package/bin/qqbot-cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * QQBot CLI - 用于升级和管理 QQBot 插件
+ * qqbot CLI - 用于升级和管理 qqbot 插件
  * 
  * 用法:
  *   npx openclaw-qqbot upgrade    # 升级插件
@@ -131,7 +131,7 @@ function runCommand(cmd, args = []) {
 
 // 升级命令
 function upgrade() {
-  console.log('=== QQBot 插件升级脚本 ===');
+  console.log('=== qqbot 插件升级脚本 ===');
 
   let foundInstallation = null;
   let savedConfig = null;
@@ -175,7 +175,7 @@ function upgrade() {
     }
   } else {
     console.log('未找到已保存的 qqbot 配置，请手动配置:');
-    console.log(`  ${foundInstallation} channels add --channel qqbot --token "AppID:AppSecret"`);
+    console.log(`  ${foundInstallation} channels add --channel qqbot --token "appid:appsecret"`);
     return;
   }
 
@@ -186,7 +186,7 @@ function upgrade() {
 
 // 安装命令
 function install() {
-  console.log('=== QQBot 插件安装 ===');
+  console.log('=== qqbot 插件安装 ===');
 
   const cmd = detectInstallation();
   if (!cmd) {
@@ -200,13 +200,13 @@ function install() {
 
   console.log('\n=== 安装完成 ===');
   console.log('\n请配置机器人通道:');
-  console.log(`  ${cmd} channels add --channel qqbot --token "AppID:AppSecret"`);
+  console.log(`  ${cmd} channels add --channel qqbot --token "appid:appsecret"`);
 }
 
 // 显示帮助
 function showHelp() {
   console.log(`
-QQBot CLI - QQ机器人插件管理工具
+qqbot CLI - QQ机器人插件管理工具
 
 用法:
   npx openclaw-qqbot <命令>

package/dist/index.js

@@ -1,6 +1,12 @@
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
+import { registerGuildTools } from "./src/tools/guild-list.js";
+import { registerChannelTools } from "./src/tools/channel-list.js";
+import { registerGuildAnnouncesTool } from "./src/tools/guild-announces.js";
+import { registerGuildMemberTools } from "./src/tools/guild-member.js";
+// import { registerScheduleTools } from "./src/tools/schedule.js";
+import { registerForumThreadTools } from "./src/tools/forum-thread.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -9,6 +15,12 @@ const plugin = {
     register(api) {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
+        registerGuildTools(api);
+        registerChannelTools(api);
+        registerGuildAnnouncesTool(api);
+        registerGuildMemberTools(api);
+        // registerScheduleTools(api);
+        registerForumThreadTools(api);
     },
 };
 export default plugin;

package/dist/src/api.d.ts

@@ -2,6 +2,7 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
+import { type StreamConfig } from "./types.js";
 /**
  * 初始化 API 配置
  * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
@@ -47,13 +48,24 @@ export declare function getGatewayUrl(accessToken: string): Promise<string>;
 export interface MessageResponse {
     id: string;
     timestamp: number | string;
+    /** 流式消息ID，用于后续分片 */
+    stream_id?: string;
 }
-export declare function sendC2CMessage(accessToken: string, openid: string, content: string, msgId?: string): Promise<MessageResponse>;
+export declare function sendC2CMessage(accessToken: string, openid: string, content: string, msgId?: string, stream?: StreamConfig): Promise<MessageResponse>;
 export declare function sendC2CInputNotify(accessToken: string, openid: string, msgId?: string, inputSecond?: number): Promise<void>;
 export declare function sendChannelMessage(accessToken: string, channelId: string, content: string, msgId?: string): Promise<{
     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<{
     id: string;

package/dist/src/api.js

@@ -35,28 +35,29 @@ const tokenFetchPromises = new Map();
  * 按 appId 隔离，支持多机器人并发请求。
  */
 export async function getAccessToken(appId, clientSecret) {
-    const cachedToken = tokenCacheMap.get(appId);
+    const normalizedAppId = String(appId).trim();
+    const cachedToken = tokenCacheMap.get(normalizedAppId);
     // 检查缓存：未过期 且 appId 未变化 时复用
     if (cachedToken && Date.now() < cachedToken.expiresAt - 5 * 60 * 1000) {
         return cachedToken.token;
     }
     // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
-    let fetchPromise = tokenFetchPromises.get(appId);
+    let fetchPromise = tokenFetchPromises.get(normalizedAppId);
     if (fetchPromise) {
-        console.log(`[qqbot-api:${appId}] Token fetch in progress, waiting for existing request...`);
+        console.log(`[qqbot-api:${normalizedAppId}] Token fetch in progress, waiting for existing request...`);
         return fetchPromise;
     }
     // 创建新的 Token 获取 Promise（singleflight 入口）
     fetchPromise = (async () => {
         try {
-            return await doFetchToken(appId, clientSecret);
+            return await doFetchToken(normalizedAppId, clientSecret);
         }
         finally {
             // 无论成功失败，都清除 Promise 缓存
-            tokenFetchPromises.delete(appId);
+            tokenFetchPromises.delete(normalizedAppId);
         }
     })();
-    tokenFetchPromises.set(appId, fetchPromise);
+    tokenFetchPromises.set(normalizedAppId, fetchPromise);
     return fetchPromise;
 }
 /**
@@ -116,8 +117,9 @@ async function doFetchToken(appId, clientSecret) {
  */
 export function clearTokenCache(appId) {
     if (appId) {
-        tokenCacheMap.delete(appId);
-        console.log(`[qqbot-api:${appId}] Token cache cleared manually.`);
+        const normalizedAppId = String(appId).trim();
+        tokenCacheMap.delete(normalizedAppId);
+        console.log(`[qqbot-api:${normalizedAppId}] Token cache cleared manually.`);
     }
     else {
         tokenCacheMap.clear();
@@ -246,7 +248,7 @@ export async function getGatewayUrl(accessToken) {
     const data = await apiRequest(accessToken, "GET", "/gateway");
     return data.url;
 }
-function buildMessageBody(content, msgId, msgSeq) {
+function buildMessageBody(content, msgId, msgSeq, stream) {
     const body = currentMarkdownSupport
         ? {
             markdown: { content },
@@ -261,11 +263,18 @@ function buildMessageBody(content, msgId, msgSeq) {
     if (msgId) {
         body.msg_id = msgId;
     }
+    if (stream) {
+        body.stream = {
+            state: stream.state,
+            index: stream.index,
+            ...(stream.id ? { id: stream.id } : {}),
+        };
+    }
     return body;
 }
-export async function sendC2CMessage(accessToken, openid, content, msgId) {
+export async function sendC2CMessage(accessToken, openid, content, msgId, stream) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
-    const body = buildMessageBody(content, msgId, msgSeq);
+    const body = buildMessageBody(content, msgId, msgSeq, stream);
     return apiRequest(accessToken, "POST", `/v2/users/${openid}/messages`, body);
 }
 export async function sendC2CInputNotify(accessToken, openid, msgId, inputSecond = 60) {
@@ -287,6 +296,17 @@ 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/channel.d.ts

@@ -1,3 +1,8 @@
 import { type ChannelPlugin } from "openclaw/plugin-sdk";
 import type { ResolvedQQBotAccount } from "./types.js";
+import { createStreamSender, StreamSender } from "./outbound.js";
 export declare const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount>;
+/**
+ * 导出流式消息工具函数，供外部使用（仅 C2C 私聊支持）
+ */
+export { createStreamSender, StreamSender };

package/dist/src/channel.js

@@ -1,6 +1,6 @@
 import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId } from "./config.js";
-import { sendText, sendMedia } from "./outbound.js";
+import { sendText, sendMedia, createStreamSender, StreamSender } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
@@ -48,11 +48,21 @@ export const qqbotPlugin = {
         media: true,
         reactions: false,
         threads: false,
-        /**
-         * blockStreaming: true 表示该 Channel 支持块流式
-         * 框架会收集流式响应，然后通过 deliver 回调发送
-         */
-        blockStreaming: false,
+        blockStreaming: true,
+    },
+    /**
+     * 流式配置
+     * blockStreamingCoalesceDefaults: 控制 block streaming 的合并策略
+     *   - minChars: 至少累积多少字符后才触发 block deliver
+     *   - idleMs: 空闲多少毫秒后强制 flush 当前 block
+     *
+     * 对于 QQ Bot：
+     *   - C2C 私聊（streamSupport=true）通过 deliver 回调中的 StreamSender 实现增量流式
+     *     disableBlockStreaming=true，不走 coalesce
+     *   - 群聊/频道（或 C2C streamSupport=false）走框架的 block streaming pipeline，使用此 coalesce 配置
+     */
+    streaming: {
+        blockStreamingCoalesceDefaults: { minChars: 800, idleMs: 800 },
     },
     reload: { configPrefixes: ["channels.qqbot"] },
     // CLI onboarding wizard
@@ -335,3 +345,7 @@ export const qqbotPlugin = {
         }),
     },
 };
+/**
+ * 导出流式消息工具函数，供外部使用（仅 C2C 私聊支持）
+ */
+export { createStreamSender, StreamSender };

package/dist/src/config.js

@@ -1,4 +1,9 @@
 export const DEFAULT_ACCOUNT_ID = "default";
+function normalizeAppId(raw) {
+    if (raw === null || raw === undefined)
+        return "";
+    return String(raw).trim();
+}
 /**
  * 列出所有 QQBot 账户 ID
  */
@@ -59,14 +64,15 @@ export function resolveQQBotAccount(cfg, accountId) {
             systemPrompt: qqbot?.systemPrompt,
             imageServerBaseUrl: qqbot?.imageServerBaseUrl,
             markdownSupport: qqbot?.markdownSupport ?? true,
+            streamSupport: qqbot?.streamSupport,
         };
-        appId = qqbot?.appId ?? "";
+        appId = normalizeAppId(qqbot?.appId);
     }
     else {
         // 命名账户从 accounts 读取
         const account = qqbot?.accounts?.[resolvedAccountId];
         accountConfig = account ?? {};
-        appId = account?.appId ?? "";
+        appId = normalizeAppId(account?.appId);
     }
     // 解析 clientSecret
     if (accountConfig.clientSecret) {
@@ -83,7 +89,7 @@ export function resolveQQBotAccount(cfg, accountId) {
     }
     // AppId 也可以从环境变量读取
     if (!appId && process.env.QQBOT_APP_ID && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
-        appId = process.env.QQBOT_APP_ID;
+        appId = normalizeAppId(process.env.QQBOT_APP_ID);
     }
     return {
         accountId: resolvedAccountId,
@@ -95,6 +101,7 @@ export function resolveQQBotAccount(cfg, accountId) {
         systemPrompt: accountConfig.systemPrompt,
         imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
         markdownSupport: accountConfig.markdownSupport !== false,
+        streamSupport: accountConfig.streamSupport === true,
         config: accountConfig,
     };
 }

package/dist/src/constants.d.ts

@@ -0,0 +1,10 @@
+/** C2C 私聊消息 */
+export declare const MSG_TYPE_C2C: "c2c";
+/** 频道公开消息 */
+export declare const MSG_TYPE_GUILD: "guild";
+/** 频道私信 */
+export declare const MSG_TYPE_DM: "dm";
+/** 群聊消息 */
+export declare const MSG_TYPE_GROUP: "group";
+/** 消息类型联合类型 */
+export type MessageType = typeof MSG_TYPE_C2C | typeof MSG_TYPE_GUILD | typeof MSG_TYPE_DM | typeof MSG_TYPE_GROUP;

package/dist/src/constants.js

@@ -0,0 +1,9 @@
+// ============ 消息类型常量 ============
+/** C2C 私聊消息 */
+export const MSG_TYPE_C2C = "c2c";
+/** 频道公开消息 */
+export const MSG_TYPE_GUILD = "guild";
+/** 频道私信 */
+export const MSG_TYPE_DM = "dm";
+/** 群聊消息 */
+export const MSG_TYPE_GROUP = "group";