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

package/README.md

@@ -164,61 +164,62 @@ AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. La
 
 > For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
 
-### Step 2 — Install the Plugin
+### Step 2 — Install / Upgrade the Plugin
 
-**Option A: Install via npm (Recommended)**
+**Option A: Remote One-Liner (Easiest, no clone required)**
 
 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
+  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-**Option B: One-Click Install & Run**
+One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!
 
-```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
-```
-
-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).
+> `--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 C: 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">
@@ -366,119 +367,9 @@ STT supports two-level configuration with priority fallback:
 
 ---
 
-## 🔄 Upgrade
-
-### Option 1: Upgrade via npm (Recommended)
-
-Current latest npm version: `1.5.6`
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-The script automatically backs up channel config → uninstalls old plugins → installs new version → restores config → restarts gateway.
-
-```bash
-# Specify exact version
-bash ./scripts/npm-upgrade.sh --version 1.5.6
-```
-
-### Option 2: Upgrade via Source
-
-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>
-
----
-
-## 🔀 Migrating from Legacy Plugins
-
-If you previously installed `qqbot`, `@sliverp/qqbot`, `@tencent-connect/qqbot`, or other related legacy plugins, you need to uninstall the old plugin before installing the new version.
-
-### Recommended: Use npm-upgrade Script (Automatic)
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-The script automatically uninstalls all legacy plugin variants (`qqbot`, `@sliverp/qqbot`, `openclaw-qq`, etc.), cleans up residual directories, and backs up/restores channel config.
-
-### Manual Migration
-
-**1. Back up your channel config**
-
-Save the `channels.qqbot` section from `~/.openclaw/openclaw.json` (including `appId`, `clientSecret`, `allowFrom`, etc.) — you'll need to restore it later.
-
-**2. Uninstall old plugins**
-
-Run the appropriate uninstall command(s) based on what you had installed:
-
-```bash
-# Uninstall legacy plugin variants (pick the ones that apply)
-openclaw plugins uninstall qqbot
-openclaw plugins uninstall @sliverp/qqbot
-openclaw plugins uninstall @tencent-connect/qqbot
-openclaw plugins uninstall openclaw-qqbot
-openclaw plugins uninstall openclaw-qq
-```
-
-If `plugins uninstall` doesn't fully clean up, manually remove residual directories:
-
-```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
-```
-
-**3. Temporarily remove channel config**
-
-> ⚠️ Important: `openclaw plugins install` validates the config file. If `channels.qqbot` exists but no plugin provides that channel, it will fail with `unknown channel id: qqbot`.
-
-Before installing, temporarily remove the `channels.qqbot` section from `~/.openclaw/openclaw.json`.
-
-**4. Install the new version**
-
-```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
-```
-
-**5. Restore channel config**
-
-Write back the previously saved `channels.qqbot` config to `~/.openclaw/openclaw.json`.
-
-**6. Restart the gateway**
-
-```bash
-openclaw gateway restart
-```
-
----
-
 ## 📚 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

@@ -161,61 +161,62 @@ AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网
 
 > 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
 
-### 第二步 — 安装插件
+### 第二步 — 安装 / 升级插件
 
-**方式一：通过 npm 安装（推荐）**
+**方式一：远程一键执行（最简单，无需 clone 仓库）**
 
 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+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 即可开始聊天！
 
-```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
-```
-
-脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。
+> 首次安装**必须**传 `--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">
@@ -363,119 +364,9 @@ STT 支持两级配置，按优先级查找：
 
 ---
 
-## 🔄 升级
-
-### 方式一：通过 npm 升级（推荐）
-
-当前最新 npm 版本：`1.5.6`
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-脚本会自动备份通道配置 → 卸载旧插件 → 安装新版本 → 恢复配置 → 重启网关。
-
-```bash
-# 指定版本号
-bash ./scripts/npm-upgrade.sh --version 1.5.6
-```
-
-### 方式二：通过源码升级
-
-运行一键脚本即可升级并重启：
-
-```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>
-
----
-
-## 🔀 从旧版插件迁移
-
-如果你之前安装的是 `qqbot`、`@sliverp/qqbot`、`@tencent-connect/qqbot` 等关联插件，需要先卸载旧插件再安装新版本。
-
-### 推荐：使用 npm-upgrade 脚本（自动处理）
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-脚本会自动卸载所有历史版本的插件（`qqbot`、`@sliverp/qqbot`、`openclaw-qq` 等）、清理残留目录、备份恢复通道配置。
-
-### 手动迁移
-
-**1. 备份你的通道配置**
-
-先记录 `~/.openclaw/openclaw.json` 中 `channels.qqbot` 的内容（`appId`、`clientSecret`、`allowFrom` 等），后续需要恢复。
-
-**2. 卸载旧插件**
-
-根据你之前安装的插件名，执行对应的卸载命令：
-
-```bash
-# 卸载可能存在的旧版插件（按实际情况选择）
-openclaw plugins uninstall qqbot
-openclaw plugins uninstall @sliverp/qqbot
-openclaw plugins uninstall @tencent-connect/qqbot
-openclaw plugins uninstall openclaw-qqbot
-openclaw plugins uninstall openclaw-qq
-```
-
-如果 `plugins uninstall` 未能完全清理，手动删除残留目录：
-
-```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
-```
-
-**3. 临时移除通道配置**
-
-> ⚠️ 重要：`openclaw plugins install` 会校验配置文件。如果配置中存在 `channels.qqbot` 但对应插件尚未安装，会报 `unknown channel id: qqbot` 错误并拒绝安装。
-
-安装前需要临时从 `~/.openclaw/openclaw.json` 中移除 `channels.qqbot` 配置段。
-
-**4. 安装新版本**
-
-```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
-```
-
-**5. 恢复通道配置**
-
-将之前备份的 `channels.qqbot` 配置写回 `~/.openclaw/openclaw.json`。
-
-**6. 重启网关**
-
-```bash
-openclaw gateway restart
-```
-
----
-
 ## 📚 文档与链接
 
+- [升级指南](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

@@ -248,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 },
@@ -263,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) {
@@ -289,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

@@ -64,6 +64,7 @@ export function resolveQQBotAccount(cfg, accountId) {
             systemPrompt: qqbot?.systemPrompt,
             imageServerBaseUrl: qqbot?.imageServerBaseUrl,
             markdownSupport: qqbot?.markdownSupport ?? true,
+            streamSupport: qqbot?.streamSupport,
         };
         appId = normalizeAppId(qqbot?.appId);
     }
@@ -100,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;