@wenbin_wb/dsh-bridge 2.0.4 → 2.1.1

package/README.md

@@ -18,6 +18,7 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 - **Cloudflare Tunnel**: One-click public internet exposure, connect from anywhere without a public server of your own — keep working even when you're away from home
 - **Custom Tunnel**: Connect to your own tunnel server with a fixed domain ([Setup Guide](docs/custom-tunnel.md))
 - **WeChat Bot (ClawBot / iLink)**: Scan a QR code to log in a WeChat personal account, then chat with, control, and approve your DeepSeek Harness agents right inside WeChat. **Multi-workspace selection, restart-persistent sessions, grouped session listing with titles, media (image/file/voice) transfer, and permission approvals** — over Tencent's official iLink Bot API, no public server or tunnel required ([Usage Guide](docs/wechat-usage.md))
+- **QQ Bot (OpenAPI v2)**: Connect your QQ Bot to receive private/group messages, send Markdown, button keyboards, and rich media. **Full event coverage (C2C / GROUP_AT_MESSAGE_CREATE), auto token refresh, reconnection with backoff, message deduplication** — over Tencent's official QQ Bot OpenAPI v2 ([Usage Guide](docs/qq-usage.md))
 - **IM Integration (More Planned)**: WeChat / QQ / Feishu / OpenClaw direct chat integration
 - **Security Alerts**: URLs and QR codes with access warnings to prevent accidental sharing
 - **Auto Version Check**: Automatic update detection when entering the panel
@@ -35,7 +36,7 @@ Seamlessly extend your local DeepSeek Harness to mobile phones, tablets, public
 |--------|-------------|--------|
 | **Platform Abstraction** | Platform-agnostic core (sessions / approvals / commands / digest) shared across IM channels | ✅ **Completed** (v2.0.0) |
 | **WeChat** | Chat with your Agent directly in WeChat | ✅ Supported (workspaces / persisted sessions / media / approvals) |
-| **QQ Bot** | QQ bot integration for group/private chat | 🚧 Next (platform adapter implementation) |
+| **QQ Bot** | QQ bot integration for group/private chat | ✅ **Completed** (v2.1.0) — Markdown / buttons / rich media |
 | **Feishu** | Feishu message/bot integration for workplace scenarios | Planned |
 | **OpenClaw** | Integration with OpenClaw ecosystem | Planned |
 | **Telegram** | Self-hosted IM channel | Planned |

package/README.zh-CN.md

@@ -18,7 +18,8 @@
 - **Cloudflare 隧道**：一键暴露公网地址，随时随地连接，出差在外、不在家也能接着干，无需自建公网服务器
 - **自建隧道**：连接自己的隧道服务器，获得固定域名（[搭建教程](docs/custom-tunnel.md)）
 - **微信 Bot（ClawBot / iLink）**：扫码登录微信个人号后，直接在微信里对话、控制 DeepSeek Harness 的 agent。**支持多工作区选择、会话跨重启持久化、按工作区分组查看、媒体（图片/文件/语音）收发、权限审批**——走腾讯官方 iLink Bot API，无需公网（[使用说明](docs/wechat-usage.md)）
-- **IM 集成（更多平台规划中）**：QQ / 飞书 / OpenClaw，直接在聊天软件里呼唤你的 Agent
+- **QQ Bot（OpenAPI v2）**：接入 QQ 机器人，私聊/群聊接收消息，发送 Markdown、按钮键盘和富媒体。**完整事件覆盖（C2C / GROUP_AT_MESSAGE_CREATE）、Token 自动刷新、断线重连、消息去重**——走腾讯官方 QQ Bot OpenAPI v2（[使用说明](docs/qq-usage.md)）
+- **IM 集成（更多平台规划中）**：飞书 / OpenClaw，直接在聊天软件里呼唤你的 Agent
 - **安全提示**：URL 和二维码带访问警告，防止误分享
 - **版本检查**：进入面板自动检测是否有新版本
 
@@ -35,7 +36,7 @@
 |------|------|------|
 | **平台抽象层** | 平台无关的核心（会话/审批/命令/digest）跨 IM 渠道复用 | ✅ **已完成**（v2.0.0） |
 | **微信** | 在微信里直接与你的 Agent 对话 | ✅ 已支持（多工作区 / 会话持久化 / 媒体 / 审批） |
-| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent | 🚧 下一步（平台适配器实现） |
+| **QQ Bot** | 接入 QQ 机器人，群聊/私聊唤起 Agent | ✅ **已完成**（v2.1.0）— Markdown / 按钮 / 富媒体 |
 | **飞书** | 飞书消息/机器人集成，办公场景直接调用 | 规划中 |
 | **OpenClaw** | 与 OpenClaw 生态打通 | 规划中 |
 | **Telegram** | 适合自托管的 IM 渠道 | 规划中 |

package/client/client.js

@@ -323,7 +323,10 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
         digestIntervalSec: String(platform.config.digestIntervalSec ?? 300),
         approvalTimeoutSec: String(platform.config.approvalTimeoutSec ?? 600),
         maxMessageChars: String(platform.config.maxMessageChars ?? 2e3),
-        sendChunkDelayMs: String(platform.config.sendChunkDelayMs ?? 1500)
+        sendChunkDelayMs: String(platform.config.sendChunkDelayMs ?? 1500),
+        appId: platform.config.appId ?? "",
+        // Secret 不由后端回传；空值表示沿用已保存密钥
+        clientSecret: ""
       });
     }
   }, [platform?.config]);
@@ -380,14 +383,19 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
   const handleNewId = React.useCallback((e) => setNewId(e.target.value), []);
   const saveConfig = React.useCallback(async () => {
     if (!cfgDraft) return;
-    await act(BRIDGE_ENDPOINTS.platformSetConfig, {
+    const payload = {
       digestIntervalSec: Number(cfgDraft.digestIntervalSec),
       approvalTimeoutSec: Number(cfgDraft.approvalTimeoutSec),
       maxMessageChars: Number(cfgDraft.maxMessageChars),
       sendChunkDelayMs: Number(cfgDraft.sendChunkDelayMs)
-    });
-  }, [act, cfgDraft]);
-  const cfgDirty = cfgDraft && platform?.config && (Number(cfgDraft.digestIntervalSec) !== platform.config.digestIntervalSec || Number(cfgDraft.approvalTimeoutSec) !== platform.config.approvalTimeoutSec || Number(cfgDraft.maxMessageChars) !== platform.config.maxMessageChars || Number(cfgDraft.sendChunkDelayMs) !== platform.config.sendChunkDelayMs);
+    };
+    if (platformId === "qq") {
+      payload.appId = cfgDraft.appId.trim();
+      payload.clientSecret = cfgDraft.clientSecret.trim();
+    }
+    await act(BRIDGE_ENDPOINTS.platformSetConfig, payload);
+  }, [act, cfgDraft, platformId]);
+  const cfgDirty = cfgDraft && platform?.config && (Number(cfgDraft.digestIntervalSec) !== platform.config.digestIntervalSec || Number(cfgDraft.approvalTimeoutSec) !== platform.config.approvalTimeoutSec || Number(cfgDraft.maxMessageChars) !== platform.config.maxMessageChars || Number(cfgDraft.sendChunkDelayMs) !== platform.config.sendChunkDelayMs || platformId === "qq" && (cfgDraft.appId !== (platform.config.appId ?? "") || cfgDraft.clientSecret !== (platform.config.clientSecret ?? "")));
   if (!platform && !err) {
     return React.createElement(
       "div",
@@ -510,7 +518,7 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
         }, "\u89E3\u7ED1\u8D26\u53F7")
       )
     ),
-    // 未配置 / 登录中：二维码
+    // 未配置 / 登录中：二维码（QQ 无二维码，显示凭证表单）
     (!platform?.configured || showQr) && React.createElement(
       "div",
       { style: s.block },
@@ -524,6 +532,51 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
           login.phase === "scaned" ? "\u5DF2\u626B\u7801\uFF0C\u8BF7\u5728\u624B\u673A\u4E0A\u786E\u8BA4\u2026" : platformId === "wechat" ? "\u8BF7\u4F7F\u7528\u5FAE\u4FE1\u626B\u7801\u767B\u5F55\uFF08ClawBot\uFF09" : "\u8BF7\u626B\u7801\u767B\u5F55"
         ),
         login.error && React.createElement("div", { style: { ...s.muted, marginTop: 4, color: "var(--dsw-alias-state-warn-primary,#92400e)" } }, login.error)
+      ) : platformId === "qq" ? React.createElement(
+        "div",
+        { style: { display: "flex", flexDirection: "column", gap: 10, marginTop: 4 } },
+        React.createElement(
+          "div",
+          null,
+          React.createElement("div", { style: { ...s.muted, marginBottom: 4 } }, "AppID \u2014 QQ \u5F00\u653E\u5E73\u53F0\u673A\u5668\u4EBA\u5E94\u7528 ID"),
+          React.createElement("input", {
+            style: { ...s.input, width: "100%" },
+            placeholder: "\u8BF7\u8F93\u5165 AppID",
+            value: cfgDraft?.appId ?? "",
+            onChange: (e) => setCfgDraft((d) => ({ ...d, appId: e.target.value }))
+          })
+        ),
+        React.createElement(
+          "div",
+          null,
+          React.createElement("div", { style: { ...s.muted, marginBottom: 4 } }, "ClientSecret \u2014 QQ \u5F00\u653E\u5E73\u53F0\u673A\u5668\u4EBA\u5BC6\u94A5"),
+          React.createElement("input", {
+            style: { ...s.input, width: "100%" },
+            placeholder: "\u8BF7\u8F93\u5165 ClientSecret",
+            value: cfgDraft?.clientSecret ?? "",
+            onChange: (e) => setCfgDraft((d) => ({ ...d, clientSecret: e.target.value }))
+          })
+        ),
+        React.createElement(
+          "div",
+          null,
+          React.createElement("a", {
+            href: "https://bot.q.qq.com/wiki/develop/api-v2/",
+            target: "_blank",
+            rel: "noopener noreferrer",
+            style: s.btnLink
+          }, "\u{1F4D6} \u524D\u5F80 QQ \u5F00\u653E\u5E73\u53F0\u7533\u8BF7\u673A\u5668\u4EBA")
+        ),
+        React.createElement(
+          "div",
+          { style: { display: "flex", gap: 8, flexWrap: "wrap", alignItems: "center" } },
+          React.createElement("button", {
+            style: { ...s.btnPri, opacity: busy ? 0.5 : 1 },
+            onClick: saveConfig,
+            disabled: busy || !cfgDraft?.appId?.trim() || !cfgDraft?.clientSecret?.trim()
+          }, busy ? "\u4FDD\u5B58\u4E2D\u2026" : "\u4FDD\u5B58\u5E76\u8FDE\u63A5"),
+          login.phase === "error" && React.createElement("div", { style: { ...s.muted, fontSize: 12 } }, login.error ?? "\u8FDE\u63A5\u5931\u8D25")
+        )
       ) : React.createElement(
         "div",
         { style: { display: "flex", gap: 8, marginTop: 4, flexWrap: "wrap", alignItems: "center" } },
@@ -602,6 +655,33 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
             onChange: (e) => setCfgDraft((d) => ({ ...d, sendChunkDelayMs: e.target.value }))
           })
         ),
+        // QQ 平台凭证
+        platformId === "qq" && React.createElement(
+          "div",
+          { style: { display: "flex", flexDirection: "column", gap: 10 } },
+          React.createElement(
+            "div",
+            null,
+            React.createElement("div", { style: { ...s.muted, marginBottom: 4 } }, "AppID \u2014 QQ \u5F00\u653E\u5E73\u53F0\u673A\u5668\u4EBA\u5E94\u7528 ID"),
+            React.createElement("input", {
+              style: { ...s.input, width: 220 },
+              placeholder: "\u8BF7\u8F93\u5165 AppID",
+              value: cfgDraft.appId,
+              onChange: (e) => setCfgDraft((d) => ({ ...d, appId: e.target.value }))
+            })
+          ),
+          React.createElement(
+            "div",
+            null,
+            React.createElement("div", { style: { ...s.muted, marginBottom: 4 } }, "ClientSecret \u2014 QQ \u5F00\u653E\u5E73\u53F0\u673A\u5668\u4EBA\u5BC6\u94A5"),
+            React.createElement("input", {
+              style: { ...s.input, width: 220 },
+              placeholder: "\u8BF7\u8F93\u5165 ClientSecret",
+              value: cfgDraft.clientSecret,
+              onChange: (e) => setCfgDraft((d) => ({ ...d, clientSecret: e.target.value }))
+            })
+          )
+        ),
         React.createElement("button", {
           style: { ...s.btnPri, alignSelf: "flex-start", opacity: cfgDirty && !busy ? 1 : 0.5 },
           disabled: !cfgDirty || busy,
@@ -615,7 +695,7 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       React.createElement(
         "div",
         { style: { ...s.tip, fontSize: 12 } },
-        platformId === "wechat" ? "\u8BF4\u660E: \u626B\u7801\u6210\u529F\u540E\uFF0C\u5411\u8BE5\u5FAE\u4FE1 Bot \u53D1\u9001\u7B2C\u4E00\u6761\u6D88\u606F\u5373\u81EA\u52A8\u5B8C\u6210\u767D\u540D\u5355\u6388\u6743\u3002\u4EC5\u767D\u540D\u5355\u5185\u7684\u5FAE\u4FE1\u7528\u6237\u80FD\u9A71\u52A8 agent\uFF0C\u5176\u4ED6\u4EBA\u6D88\u606F\u4F1A\u88AB\u5FFD\u7565\u3002\u4F7F\u7528\u4E13\u7528\u5FAE\u4FE1\u53F7\uFF0C\u907F\u514D\u5F71\u54CD\u4E3B\u53F7\u3002" : "\u8BF4\u660E: \u767B\u5F55\u6210\u529F\u540E\uFF0C\u53D1\u9001\u7B2C\u4E00\u6761\u6D88\u606F\u5373\u81EA\u52A8\u5B8C\u6210\u767D\u540D\u5355\u6388\u6743\u3002\u4EC5\u767D\u540D\u5355\u5185\u7684\u7528\u6237\u80FD\u9A71\u52A8 agent\uFF0C\u5176\u4ED6\u4EBA\u6D88\u606F\u4F1A\u88AB\u5FFD\u7565\u3002"
+        platformId === "wechat" ? "\u8BF4\u660E: \u626B\u7801\u6210\u529F\u540E\uFF0C\u5411\u8BE5\u5FAE\u4FE1 Bot \u53D1\u9001\u7B2C\u4E00\u6761\u6D88\u606F\u5373\u81EA\u52A8\u5B8C\u6210\u767D\u540D\u5355\u6388\u6743\u3002\u4EC5\u767D\u540D\u5355\u5185\u7684\u5FAE\u4FE1\u7528\u6237\u80FD\u9A71\u52A8 agent\uFF0C\u5176\u4ED6\u4EBA\u6D88\u606F\u4F1A\u88AB\u5FFD\u7565\u3002\u4F7F\u7528\u4E13\u7528\u5FAE\u4FE1\u53F7\uFF0C\u907F\u514D\u5F71\u54CD\u4E3B\u53F7\u3002" : platformId === "qq" ? "\u8BF4\u660E: \u586B\u5165 QQ \u5F00\u653E\u5E73\u53F0\u673A\u5668\u4EBA\u7684 AppID \u4E0E ClientSecret \u540E\u4FDD\u5B58\u5373\u81EA\u52A8\u8FDE\u63A5\u3002\u7528\u6237\u5411 Bot \u53D1\u9001\u7B2C\u4E00\u6761\u6D88\u606F\u5373\u81EA\u52A8\u5B8C\u6210\u767D\u540D\u5355\u6388\u6743\u3002\u4EC5\u767D\u540D\u5355\u5185\u7684 QQ \u7528\u6237\u80FD\u9A71\u52A8 agent\uFF0C\u5176\u4ED6\u4EBA\u6D88\u606F\u4F1A\u88AB\u5FFD\u7565\u3002" : "\u8BF4\u660E: \u767B\u5F55\u6210\u529F\u540E\uFF0C\u53D1\u9001\u7B2C\u4E00\u6761\u6D88\u606F\u5373\u81EA\u52A8\u5B8C\u6210\u767D\u540D\u5355\u6388\u6743\u3002\u4EC5\u767D\u540D\u5355\u5185\u7684\u7528\u6237\u80FD\u9A71\u52A8 agent\uFF0C\u5176\u4ED6\u4EBA\u6D88\u606F\u4F1A\u88AB\u5FFD\u7565\u3002"
       )
     )
   );
@@ -932,7 +1012,7 @@ function BridgePanel({ rpcCall }) {
   } else if (activeTab === "im") {
     const IM_PLATFORMS = [
       { id: "wechat", label: "\u5FAE\u4FE1", desc: "iLink Bot API\uFF08ClawBot\uFF09" },
-      { id: "qq", label: "QQ", desc: "NapCat / Mirai" },
+      { id: "qq", label: "QQ", desc: "QQ Bot OpenAPI v2\uFF08\u79C1\u804A/\u7FA4\u804A/\u6309\u94AE\uFF09" },
       { id: "feishu", label: "\u98DE\u4E66", desc: "\u5B98\u65B9\u4E8B\u4EF6\u56DE\u8C03 API" }
     ];
     tabContent = React.createElement(

package/client/index.js

@@ -270,6 +270,9 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
         approvalTimeoutSec: String(platform.config.approvalTimeoutSec ?? 600),
         maxMessageChars:    String(platform.config.maxMessageChars    ?? 2000),
         sendChunkDelayMs:   String(platform.config.sendChunkDelayMs   ?? 1500),
+        appId: platform.config.appId ?? '',
+        // Secret 不由后端回传；空值表示沿用已保存密钥
+        clientSecret: '',
       });
     }
   }, [platform?.config]);
@@ -338,18 +341,28 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
   // 高级设置保存
   const saveConfig = React.useCallback(async () => {
     if (!cfgDraft) return;
-    await act(BRIDGE_ENDPOINTS.platformSetConfig, {
+    const payload = {
       digestIntervalSec:  Number(cfgDraft.digestIntervalSec),
       approvalTimeoutSec: Number(cfgDraft.approvalTimeoutSec),
       maxMessageChars:    Number(cfgDraft.maxMessageChars),
       sendChunkDelayMs:   Number(cfgDraft.sendChunkDelayMs),
-    });
-  }, [act, cfgDraft]);
+    };
+    // QQ 平台额外携带凭证
+    if (platformId === 'qq') {
+      payload.appId = cfgDraft.appId.trim();
+      payload.clientSecret = cfgDraft.clientSecret.trim();
+    }
+    await act(BRIDGE_ENDPOINTS.platformSetConfig, payload);
+  }, [act, cfgDraft, platformId]);
   const cfgDirty = cfgDraft && platform?.config && (
     Number(cfgDraft.digestIntervalSec)  !== platform.config.digestIntervalSec  ||
     Number(cfgDraft.approvalTimeoutSec) !== platform.config.approvalTimeoutSec ||
     Number(cfgDraft.maxMessageChars)    !== platform.config.maxMessageChars    ||
-    Number(cfgDraft.sendChunkDelayMs)   !== platform.config.sendChunkDelayMs
+    Number(cfgDraft.sendChunkDelayMs)   !== platform.config.sendChunkDelayMs   ||
+    (platformId === 'qq' && (
+      cfgDraft.appId !== (platform.config.appId ?? '') ||
+      cfgDraft.clientSecret !== (platform.config.clientSecret ?? '')
+    ))
   );
 
   if (!platform && !err) {
@@ -459,7 +472,7 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       ),
     ),
 
-    // 未配置 / 登录中：二维码
+    // 未配置 / 登录中：二维码（QQ 无二维码，显示凭证表单）
     (!platform?.configured || showQr) && React.createElement('div', { style: s.block },
       showQr && login.qr
         ? React.createElement('div', null,
@@ -471,13 +484,48 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
             ),
             login.error && React.createElement('div', { style: { ...s.muted, marginTop: 4, color: 'var(--dsw-alias-state-warn-primary,#92400e)' } }, login.error),
           )
-        : React.createElement('div', { style: { display: 'flex', gap: 8, marginTop: 4, flexWrap: 'wrap', alignItems: 'center' } },
-            React.createElement('button', {
-              style: { ...s.btnPri, opacity: busy ? 0.5 : 1 },
-              onClick: onLogin, disabled: busy,
-            }, busy ? '处理中…' : '扫码登录'),
-            login.phase === 'error' && React.createElement('div', { style: { ...s.muted, fontSize: 12 } }, login.error ?? '登录失败'),
-          ),
+        : platformId === 'qq'
+          ? React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 10, marginTop: 4 } },
+              React.createElement('div', null,
+                React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, 'AppID — QQ 开放平台机器人应用 ID'),
+                React.createElement('input', {
+                  style: { ...s.input, width: '100%' },
+                  placeholder: '请输入 AppID',
+                  value: cfgDraft?.appId ?? '',
+                  onChange: (e) => setCfgDraft(d => ({ ...d, appId: e.target.value })),
+                }),
+              ),
+              React.createElement('div', null,
+                React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, 'ClientSecret — QQ 开放平台机器人密钥'),
+                React.createElement('input', {
+                  style: { ...s.input, width: '100%' },
+                  placeholder: '请输入 ClientSecret',
+                  value: cfgDraft?.clientSecret ?? '',
+                  onChange: (e) => setCfgDraft(d => ({ ...d, clientSecret: e.target.value })),
+                }),
+              ),
+              React.createElement('div', null,
+                React.createElement('a', {
+                  href: 'https://bot.q.qq.com/wiki/develop/api-v2/',
+                  target: '_blank', rel: 'noopener noreferrer',
+                  style: s.btnLink,
+                }, '📖 前往 QQ 开放平台申请机器人'),
+              ),
+              React.createElement('div', { style: { display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' } },
+                React.createElement('button', {
+                  style: { ...s.btnPri, opacity: busy ? 0.5 : 1 },
+                  onClick: saveConfig, disabled: busy || !cfgDraft?.appId?.trim() || !cfgDraft?.clientSecret?.trim(),
+                }, busy ? '保存中…' : '保存并连接'),
+                login.phase === 'error' && React.createElement('div', { style: { ...s.muted, fontSize: 12 } }, login.error ?? '连接失败'),
+              ),
+            )
+          : React.createElement('div', { style: { display: 'flex', gap: 8, marginTop: 4, flexWrap: 'wrap', alignItems: 'center' } },
+              React.createElement('button', {
+                style: { ...s.btnPri, opacity: busy ? 0.5 : 1 },
+                onClick: onLogin, disabled: busy,
+              }, busy ? '处理中…' : '扫码登录'),
+              login.phase === 'error' && React.createElement('div', { style: { ...s.muted, fontSize: 12 } }, login.error ?? '登录失败'),
+            ),
     ),
 
     // 高级设置（可折叠）
@@ -527,6 +575,27 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
             onChange: (e) => setCfgDraft(d => ({ ...d, sendChunkDelayMs: e.target.value })),
           }),
         ),
+        // QQ 平台凭证
+        platformId === 'qq' && React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 10 } },
+          React.createElement('div', null,
+            React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, 'AppID — QQ 开放平台机器人应用 ID'),
+            React.createElement('input', {
+              style: { ...s.input, width: 220 },
+              placeholder: '请输入 AppID',
+              value: cfgDraft.appId,
+              onChange: (e) => setCfgDraft(d => ({ ...d, appId: e.target.value })),
+            }),
+          ),
+          React.createElement('div', null,
+            React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, 'ClientSecret — QQ 开放平台机器人密钥'),
+            React.createElement('input', {
+              style: { ...s.input, width: 220 },
+              placeholder: '请输入 ClientSecret',
+              value: cfgDraft.clientSecret,
+              onChange: (e) => setCfgDraft(d => ({ ...d, clientSecret: e.target.value })),
+            }),
+          ),
+        ),
         React.createElement('button', {
           style: { ...s.btnPri, alignSelf: 'flex-start', opacity: (cfgDirty && !busy) ? 1 : 0.5 },
           disabled: !cfgDirty || busy,
@@ -539,7 +608,9 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       React.createElement('div', { style: { ...s.tip, fontSize: 12 } },
         platformId === 'wechat'
           ? '说明: 扫码成功后，向该微信 Bot 发送第一条消息即自动完成白名单授权。仅白名单内的微信用户能驱动 agent，其他人消息会被忽略。使用专用微信号，避免影响主号。'
-          : '说明: 登录成功后，发送第一条消息即自动完成白名单授权。仅白名单内的用户能驱动 agent，其他人消息会被忽略。'
+          : platformId === 'qq'
+            ? '说明: 填入 QQ 开放平台机器人的 AppID 与 ClientSecret 后保存即自动连接。用户向 Bot 发送第一条消息即自动完成白名单授权。仅白名单内的 QQ 用户能驱动 agent，其他人消息会被忽略。'
+            : '说明: 登录成功后，发送第一条消息即自动完成白名单授权。仅白名单内的用户能驱动 agent，其他人消息会被忽略。'
       ),
     ),
   );
@@ -844,7 +915,7 @@ function BridgePanel({ rpcCall }) {
     // 从 listPlatforms 动态生成平台列表
     const IM_PLATFORMS = [
       { id: 'wechat', label: '微信', desc: 'iLink Bot API（ClawBot）' },
-      { id: 'qq',     label: 'QQ',   desc: 'NapCat / Mirai' },
+      { id: 'qq',     label: 'QQ',   desc: 'QQ Bot OpenAPI v2（私聊/群聊/按钮）' },
       { id: 'feishu', label: '飞书', desc: '官方事件回调 API' },
     ];
     

package/lib/index.js

@@ -18,6 +18,7 @@ import { CustomTunnelClient } from './tunnel-client.mjs';
 import { CloudflaredManager } from './cloudflared-manager.mjs';
 import { PlatformManager } from './platform/manager.js';
 import { WechatService } from './wechat/index.js';
+import { QqService } from './qq/index.js';
 
 const name = 'dsh-bridge';
 // 微信 Bot 会话桥依赖 DSH 提供的会话/agent/审批/工作区/持久化服务，需显式 inject
@@ -500,37 +501,50 @@ function apply(ctx, config = {}) {
   });
   platformManager.register(wechat);
 
-  // 启动时读取已保存的微信 Bot 配置（凭证 + 白名单 + 活动会话）
+  // QQ Bot（OpenAPI v2）—— 作为 Platform 子类注册进平台管理器
+  const qq = new QqService({
+    ctx,
+    logger,
+    config: config.qq ?? {},
+    onPersist: async (patch) => {
+      const stored = await loadConfig();
+      stored.qq = { ...(stored.qq ?? {}), ...patch };
+      await saveConfig(stored);
+    },
+  });
+  platformManager.register(qq);
+
+  // 启动时读取已保存的 QQ Bot 配置（凭证 + 白名单 + 活动会话）
   loadConfig().then(async (stored) => {
-    if (stored?.wechat) {
-      const cfg = stored.wechat;
-      wechat.node.config.allowFrom = Array.isArray(cfg.allowFrom) ? cfg.allowFrom : [];
-      
-      // 用 Promise 包装配置恢复过程，防止 handleInbound 竞态
-      wechat.node._restoringConfig = (async () => {
+    if (stored?.qq) {
+      const cfg = stored.qq;
+      qq.node.config.allowFrom = Array.isArray(cfg.allowFrom) ? cfg.allowFrom : [];
+
+      qq.node._restoringConfig = (async () => {
         try {
-          // 恢复活动会话 ID（直接覆盖，不判断当前值）
           if (cfg.activeSessionId) {
-            wechat.node.activeSessionId = cfg.activeSessionId;
-            logger.info('dsh-bridge: restored wechat active session: %s', cfg.activeSessionId);
+            qq.node.activeSessionId = cfg.activeSessionId;
+            logger.info('dsh-bridge: restored qq active session: %s', cfg.activeSessionId);
           } else {
-            // 没有持久化的会话时，回退到选第一个
-            await wechat.node._pickDefaultSession().catch(() => {});
+            await qq.node._pickDefaultSession().catch(() => {});
           }
         } finally {
-          wechat.node._configRestored = true;
+          qq.node._configRestored = true;
         }
       })();
-      
-      await wechat.node._restoringConfig;
-      
-      if (cfg.token && cfg.accountId) {
-        wechat.gateway.setCredentials({
-          token: cfg.token,
+
+      await qq.node._restoringConfig;
+
+      if (cfg.appId && cfg.clientSecret) {
+        qq.gateway.setCredentials({
+          appId: cfg.appId,
+          clientSecret: cfg.clientSecret,
+          accessToken: cfg.accessToken,
+          accessTokenExpiresAt: cfg.accessTokenExpiresAt,
+          gatewayUrl: cfg.gatewayUrl,
           accountId: cfg.accountId,
-          baseUrl: cfg.baseUrl,
         });
-        logger.info('dsh-bridge: loaded saved wechat bot config, starting polling');
+        logger.info('dsh-bridge: loaded saved qq bot config, starting gateway');
       }
     }
   }).catch(() => {});
@@ -538,6 +552,7 @@ function apply(ctx, config = {}) {
   const disposeRpc = installBridgeRpc(ctx, {
     service,
     wechat,
+    qq,
     platformManager,
     logger,
     saveCustomTunnelConfig: async (serverUrl, accessToken) => {
@@ -556,9 +571,10 @@ function apply(ctx, config = {}) {
   ctx.effect(() => async () => {
     try { disposeRpc(); } catch {}
     await wechat.destroy();
+    await qq.destroy();
     platformManager.dispose();
     await service.dispose();
-  }, 'dsh-bridge: stop wechat, proxy and tunnels');
+  }, 'dsh-bridge: stop wechat, qq, proxy and tunnels');
 }
 
 export { name, inject, apply };

package/lib/qq/gateway.js

@@ -0,0 +1,387 @@
+// QQ Bot OpenAPI v2 gateway
+// Official API: https://bot.q.qq.com/wiki/develop/api-v2/
+
+import { Service } from '@deepseek-ai/cordis'
+import WebSocket from 'ws'
+
+const TOKEN_URL = 'https://bots.qq.com/app/getAppAccessToken'
+const API_BASE = 'https://api.sgroup.qq.com'
+const DEFAULT_GATEWAY = 'wss://api.sgroup.qq.com/websocket/'
+const MAX_MESSAGE_CHARS = 2000
+const TOKEN_MARGIN_MS = 5 * 60_000
+const REQUEST_TIMEOUT_MS = 15_000
+const RECONNECT_DELAY_MS = 3000
+
+export const QQ_INTENTS = {
+  C2C_MESSAGE_CREATE: 1 << 25,
+  INTERACTION_CREATE: 1 << 26,
+  GROUP_AT_MESSAGE_CREATE: 1 << 30,
+  PUBLIC_GUILD_MESSAGES: 1 << 9,
+  DIRECT_MESSAGE: 1 << 12,
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const stringValue = (value) => value == null ? '' : String(value)
+
+async function requestJson(url, { method = 'GET', token, body, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...(token ? { authorization: `QQBot ${token}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    })
+    const raw = await response.text()
+    let value = {}
+    try { value = raw ? JSON.parse(raw) : {} } catch { value = { message: raw } }
+    if (!response.ok) {
+      const error = new Error(`QQ API ${response.status}: ${value?.message || value?.msg || value?.code || response.statusText}`)
+      error.status = response.status
+      error.payload = value
+      throw error
+    }
+    return value
+  } finally { clearTimeout(timer) }
+}
+
+function normalizeEvent(payload) {
+  const data = payload?.d || {}
+  const event = payload?.t || ''
+  if (event === 'C2C_MESSAGE_CREATE') {
+    return {
+      type: 'message', scope: 'c2c', event,
+      id: data.id || data.msg_id,
+      senderId: data.author?.user_openid || data.user_openid,
+      peerId: data.author?.user_openid || data.user_openid,
+      text: stringValue(data.content).trim(),
+      message: data,
+      messageReference: data.message_reference,
+    }
+  }
+  if (event === 'GROUP_AT_MESSAGE_CREATE') {
+    return {
+      type: 'message', scope: 'group', event,
+      id: data.id || data.msg_id,
+      senderId: data.author?.member_openid || data.author?.id || data.member_openid,
+      peerId: data.group_openid || data.group_id,
+      groupId: data.group_openid || data.group_id,
+      text: stringValue(data.content).trim(),
+      message: data,
+      messageReference: data.message_reference,
+    }
+  }
+  if (event === 'AT_MESSAGE_CREATE') {
+    return {
+      type: 'message', scope: 'guild', event,
+      id: data.id || data.msg_id,
+      senderId: data.author?.id,
+      peerId: data.channel_id,
+      guildId: data.guild_id,
+      text: stringValue(data.content).trim(),
+      message: data,
+      messageReference: data.message_reference,
+    }
+  }
+  if (event === 'INTERACTION_CREATE') {
+    return {
+      type: 'interaction', scope: data.group_openid ? 'group' : 'c2c', event,
+      id: data.id,
+      interactionId: data.id,
+      senderId: data.group_member_openid || data.user_openid,
+      peerId: data.group_openid || data.user_openid,
+      groupId: data.group_openid,
+      data: data.data,
+      message: data,
+    }
+  }
+  return { type: 'event', event, message: data }
+}
+
+export class QqGateway extends Service {
+  constructor({ ctx, logger, config = {}, onPersist } = {}) {
+    super(ctx, 'qq')
+    this.logger = logger
+    this.onPersist = onPersist || (() => {})
+    this.config = {
+      appId: config.appId || '',
+      clientSecret: config.clientSecret || '',
+      accessToken: config.accessToken || '',
+      accessTokenExpiresAt: Number(config.accessTokenExpiresAt || 0),
+      gatewayUrl: config.gatewayUrl || '',
+      intents: Number(config.intents ?? (QQ_INTENTS.C2C_MESSAGE_CREATE | QQ_INTENTS.GROUP_AT_MESSAGE_CREATE | QQ_INTENTS.INTERACTION_CREATE)),
+      reconnectDelayMs: Number(config.reconnectDelayMs ?? RECONNECT_DELAY_MS),
+      apiTimeoutMs: Number(config.apiTimeoutMs ?? REQUEST_TIMEOUT_MS),
+    }
+    this.statusValue = 'idle'
+    this.accountId = config.accountId || ''
+    this.ws = null
+    this.loopTask = null
+    this.stopRequested = false
+    this.heartbeatTimer = null
+    this.heartbeatInterval = 30_000
+    this.sequence = null
+    this.tokenPromise = null
+    this.dedup = new Map()
+  }
+
+  get status() { return this.statusValue }
+  get configured() { return Boolean(this.config.appId && this.config.clientSecret) }
+  get capabilities() {
+    return { supportsGroup: true, supportsMedia: true, supportsVoice: true, supportsTyping: false, maxMessageChars: MAX_MESSAGE_CHARS }
+  }
+
+  setStatus(status) {
+    this.statusValue = status
+    try { this.ctx.emit?.('qq/status', status) } catch {}
+  }
+
+  async dispose() { await this.stop(); super.dispose?.() }
+
+  async stop() {
+    this.stopRequested = true
+    this.clearHeartbeat()
+    const ws = this.ws
+    this.ws = null
+    if (ws) { try { ws.removeAllListeners(); ws.close(); ws.terminate() } catch {} }
+    const task = this.loopTask
+    this.loopTask = null
+    if (task) await task.catch(() => {})
+    this.setStatus('idle')
+  }
+
+  async start() {
+    if (!this.configured) { this.setStatus('idle'); return }
+    if (!this.loopTask) {
+      this.stopRequested = false
+      this.loopTask = this.runLoop().finally(() => { this.loopTask = null })
+    }
+  }
+
+  async persist(patch) {
+    try { await this.onPersist(patch) } catch (error) {
+      this.logger?.warn?.('[dsh-bridge qq] persist failed: %s', error?.message ?? error)
+    }
+  }
+
+  async refreshAccessToken() {
+    if (this.config.accessToken && this.config.accessTokenExpiresAt > Date.now() + TOKEN_MARGIN_MS) {
+      return this.config.accessToken
+    }
+    if (this.tokenPromise) return this.tokenPromise
+    if (!this.configured) throw new Error('QQ Bot 缺少 AppID 或 ClientSecret')
+    this.tokenPromise = (async () => {
+      const result = await requestJson(TOKEN_URL, {
+        method: 'POST',
+        body: { appId: this.config.appId, clientSecret: this.config.clientSecret },
+        timeoutMs: this.config.apiTimeoutMs,
+      })
+      const token = result?.access_token || result?.accessToken
+      if (!token) throw new Error('QQ Bot 未返回 access_token')
+      const expires = Math.max(60, Number(result?.expires_in || 7200))
+      this.config.accessToken = token
+      this.config.accessTokenExpiresAt = Date.now() + expires * 1000
+      await this.persist({ accessToken: token, accessTokenExpiresAt: this.config.accessTokenExpiresAt })
+      return token
+    })().finally(() => { this.tokenPromise = null })
+    return this.tokenPromise
+  }
+
+  async api(path, options = {}) {
+    return requestJson(`${API_BASE}${path}`, {
+      ...options,
+      token: await this.refreshAccessToken(),
+      timeoutMs: this.config.apiTimeoutMs,
+    })
+  }
+
+  async runLoop() {
+    while (!this.stopRequested) {
+      try {
+        this.setStatus('starting')
+        const token = await this.refreshAccessToken()
+        const gateway = this.config.gatewayUrl
+          || ((await requestJson(`${API_BASE}/gateway`, { token, timeoutMs: this.config.apiTimeoutMs })).url)
+          || DEFAULT_GATEWAY
+        await this.connect(gateway, token)
+      } catch (error) {
+        if (this.stopRequested) break
+        this.setStatus('reconnecting')
+        this.logger?.warn?.('[dsh-bridge qq] gateway disconnected: %s', error?.message ?? error)
+        await sleep(this.config.reconnectDelayMs)
+      }
+    }
+    this.setStatus('idle')
+  }
+
+  connect(url, token) {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url)
+      this.ws = ws
+      let settled = false
+      const finish = (error) => {
+        if (settled) return
+        settled = true
+        this.clearHeartbeat()
+        if (this.ws === ws) this.ws = null
+        error ? reject(error) : resolve()
+      }
+      ws.on('open', () => this.logger?.info?.('[dsh-bridge qq] gateway connected'))
+      ws.on('message', (raw) => {
+        let payload
+        try { payload = JSON.parse(String(raw)) } catch { return }
+        void this.handlePayload(payload, token, ws).catch(finish)
+      })
+      ws.on('error', finish)
+      ws.on('close', (code, reason) => finish(new Error(`QQ gateway closed: ${code} ${reason || ''}`)))
+    })
+  }
+
+  async handlePayload(payload, token, ws) {
+    const op = Number(payload?.op)
+    if (payload?.s != null) this.sequence = payload.s
+    if (op === 10) {
+      this.heartbeatInterval = Number(payload?.d?.heartbeat_interval || 30_000)
+      this.startHeartbeat(ws)
+      ws.send(JSON.stringify({
+        op: 2,
+        d: {
+          token: `QQBot ${token}`,
+          intents: this.config.intents,
+          shard: [0, 1],
+          properties: { $os: process.platform, $browser: 'dsh-bridge', $device: 'dsh-bridge' },
+        },
+      }))
+      return
+    }
+    if (op === 0) {
+      if (payload.t === 'READY') {
+        this.accountId = payload.d?.user?.id || payload.d?.user?.username || this.accountId
+        await this.persist({ accountId: this.accountId })
+        this.setStatus('connected')
+      }
+      const event = normalizeEvent(payload)
+      if (event.type === 'message' && event.id && !this.seen(event.id)) {
+        this.ctx.emit?.('qq/message', event)
+      }
+      if (event.type === 'interaction' && event.interactionId) {
+        this.ctx.emit?.('qq/interaction', event)
+      }
+      return
+    }
+    if (op === 7) { try { ws.close() } catch {}; return }
+    if (op === 9) throw new Error('QQ gateway invalid session')
+  }
+
+  startHeartbeat(ws) {
+    this.clearHeartbeat()
+    const beat = () => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ op: 1, d: this.sequence }))
+    }
+    beat()
+    this.heartbeatTimer = setInterval(beat, this.heartbeatInterval)
+  }
+
+  clearHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    this.heartbeatTimer = null
+  }
+
+  seen(id) {
+    const now = Date.now()
+    for (const [key, at] of this.dedup) if (now - at > 300_000) this.dedup.delete(key)
+    if (this.dedup.has(id)) return true
+    this.dedup.set(id, now)
+    return false
+  }
+
+  endpoint(peerId, scope, kind = 'messages') {
+    return scope === 'group'
+      ? `/v2/groups/${encodeURIComponent(peerId)}/${kind}`
+      : `/v2/users/${encodeURIComponent(peerId)}/${kind}`
+  }
+
+  async sendText(peerId, content, opts = {}) {
+    return this.api(this.endpoint(peerId, opts.scope), {
+      method: 'POST',
+      body: {
+        content: stringValue(content).slice(0, MAX_MESSAGE_CHARS),
+        msg_type: 0,
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+      },
+    })
+  }
+
+  async sendMarkdown(peerId, markdown, opts = {}) {
+    return this.api(this.endpoint(peerId, opts.scope), {
+      method: 'POST',
+      body: {
+        markdown: typeof markdown === 'string' ? { content: markdown } : markdown,
+        msg_type: 2,
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+      },
+    })
+  }
+
+  async sendKeyboard(peerId, content, keyboard, opts = {}) {
+    return this.api(this.endpoint(peerId, opts.scope), {
+      method: 'POST',
+      body: {
+        content: stringValue(content),
+        keyboard,
+        msg_type: 2,
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+      },
+    })
+  }
+
+  async sendMedia(peerId, media, opts = {}) {
+    return this.api(this.endpoint(peerId, opts.scope, 'files'), {
+      method: 'POST',
+      body: {
+        file_type: Number(media.fileType || 1),
+        url: media.url,
+        srv_send_msg: media.sendMessage !== false,
+      },
+    })
+  }
+
+  async sendStream(peerId, content, opts = {}) {
+    const endpoint = this.endpoint(peerId, opts.scope, 'stream-messages')
+    return this.api(endpoint, {
+      method: 'POST',
+      body: {
+        content: stringValue(content).slice(0, MAX_MESSAGE_CHARS),
+        msg_type: 0,
+        msg_id: opts.msgId,
+        event_id: opts.eventId,
+      },
+    })
+  }
+
+  async respondInteraction(interactionId, response) {
+    return this.api(`/interactions/${encodeURIComponent(interactionId)}`, {
+      method: 'PUT',
+      body: response,
+    })
+  }
+
+  async sendTyping() { return { ok: false, unsupported: true } }
+
+  setCredentials(values = {}) {
+    for (const key of ['appId', 'clientSecret', 'accessToken', 'accessTokenExpiresAt', 'gatewayUrl', 'intents']) {
+      if (values[key] !== undefined) this.config[key] = values[key]
+    }
+    if (values.accountId !== undefined) this.accountId = values.accountId
+  }
+}
+
+export const gatewayConstants = { API_BASE, TOKEN_URL, DEFAULT_GATEWAY, MAX_MESSAGE_CHARS, QQ_INTENTS }

package/lib/qq/index.js

@@ -0,0 +1,228 @@
+// dsh-bridge QQ platform adapter
+// 编排 QqGateway（OpenAPI v2 网关）+ QqConversationNode（QQ⇄DSH 会话桥）。
+// 作为 Platform 子类，注册进 PlatformManager 统一管理。
+//
+// 对外暴露给 bridge-rpc 的接口（与 wechat 一致）：getStatus / login / stop /
+// setAllowFrom / setConfig / unbind / destroy。
+//
+// 持久化策略：凭证（appId/clientSecret/accessToken/accountId）与配置由主插件
+// 通过回调 `onPersist` 保存在 $DSH_HOME/dsh-bridge/config.json。
+
+import { Platform } from '../platform/base.js'
+import { QqGateway } from './gateway.js'
+import { QqConversationNode } from './node.js'
+
+export class QqService extends Platform {
+  /**
+   * @param {object} opts
+   * @param {object} opts.ctx          Cordis 上下文
+   * @param {object} opts.logger       日志器
+   * @param {object} [opts.config]     已持久化的 qq 配置（凭证 + allowFrom + 间隔）
+   * @param {(patch: object) => (void|Promise<void>)} opts.onPersist  主插件保存回调
+   */
+  constructor({ ctx, logger, config = {}, onPersist }) {
+    super({ ctx, logger, config, onPersist })
+    this.id = 'qq'
+    this.name = 'QQ'
+
+    this.gateway = new QqGateway({
+      ctx,
+      logger,
+      config: {
+        appId: config.appId ?? '',
+        clientSecret: config.clientSecret ?? '',
+        accessToken: config.accessToken ?? '',
+        accessTokenExpiresAt: config.accessTokenExpiresAt ?? 0,
+        gatewayUrl: config.gatewayUrl ?? '',
+        accountId: config.accountId ?? '',
+      },
+      onPersist: (patch) => this.persist(patch),
+    })
+
+    // 挂到 ctx 供会话节点读取
+    try { ctx.qq = this.gateway } catch { /* 挂载失败不致命 */ }
+
+    this.node = new QqConversationNode(ctx, {
+      allowFrom: Array.isArray(config.allowFrom) ? config.allowFrom : [],
+      digestIntervalSec: config.digestIntervalSec,
+      approvalTimeoutSec: config.approvalTimeoutSec,
+      maxMessageChars: config.maxMessageChars,
+      sendChunkDelayMs: config.sendChunkDelayMs,
+      activeSessionId: config.activeSessionId,
+    }, logger, {
+      onFirstSender: (senderId) => this.persist({ allowFrom: [senderId] }),
+      onActiveSessionChange: (sessionId) => this.persist({ activeSessionId: sessionId }),
+    })
+    this.bridge = this.node
+
+    if (this.gateway.configured) {
+      void this.start().catch((err) => {
+        this.logger.error('[dsh-bridge qq] start failed: %s', err?.message ?? err)
+      })
+    }
+  }
+
+  // ---- Platform 接口 ----
+
+  get configured() { return this.gateway.configured }
+  get accountId() { return this.gateway.accountId }
+
+  get capabilities() {
+    return {
+      ...this.gateway.capabilities,
+      maxMessageChars: this.node.config.maxMessageChars ?? gatewayMaxChars(),
+    }
+  }
+
+  /** 消息抽象：委托 gateway（供 PlatformManager/未来多平台统一调用）。 */
+  async sendText(peerId, text, opts = {}) {
+    return this.gateway.sendText(peerId, text, opts)
+  }
+
+  async sendTyping(peerId, state) {
+    return this.gateway.sendTyping(peerId, state)
+  }
+
+  async sendMedia(peerId, media, opts = {}) {
+    return this.gateway.sendMedia(peerId, media, opts)
+  }
+
+  async sendMarkdown(peerId, markdown, opts = {}) {
+    return this.gateway.sendMarkdown(peerId, markdown, opts)
+  }
+
+  async sendKeyboard(peerId, keyboard, opts = {}) {
+    return this.gateway.sendKeyboard(peerId, keyboard, opts)
+  }
+
+  /** 合并展示状态给浏览器 UI。 */
+  getStatus() {
+    const allowFrom = [...(this.node.config.allowFrom ?? [])]
+    return {
+      id: this.id,
+      name: this.name,
+      status: this.gateway.status,
+      configured: this.gateway.configured,
+      accountId: this.gateway.accountId,
+      allowFrom,
+      peerId: this.node.peerId,
+      sessionId: this.node.activeSessionId,
+      login: { ...this.loginState },
+      capabilities: { ...this.capabilities },
+      config: {
+        digestIntervalSec: this.node.config.digestIntervalSec,
+        approvalTimeoutSec: this.node.config.approvalTimeoutSec,
+        maxMessageChars: this.node.config.maxMessageChars,
+        sendChunkDelayMs: this.node.config.sendChunkDelayMs,
+        appId: this.gateway.config.appId,
+        // 密钥不回传到浏览器；设置页留空时保持已保存密钥
+        clientSecret: '',
+        accountId: this.gateway.accountId,
+      },
+    }
+  }
+
+  /** 可编辑配置（供通用 PlatformPanel 读取）。 */
+  getEditableConfig() {
+    return {
+      digestIntervalSec: this.node.config.digestIntervalSec,
+      approvalTimeoutSec: this.node.config.approvalTimeoutSec,
+      maxMessageChars: this.node.config.maxMessageChars,
+      sendChunkDelayMs: this.node.config.sendChunkDelayMs,
+    }
+  }
+
+  /** 启动网关（凭证已配置时生效）。 */
+  async start() {
+    if (!this.gateway.configured) {
+      this.setStatus('idle')
+      return
+    }
+    await this.gateway.start()
+  }
+
+  /** 停止网关（保留凭证与配置）。 */
+  async stop() {
+    await this.gateway.stop()
+  }
+
+  /** 完整关停（dispose 时调用）。 */
+  async dispose() {
+    await this.gateway.stop()
+    this.gateway.dispose()
+    super.dispose()
+  }
+
+  /** 兼容 v1.x 的别名。 */
+  async destroy() {
+    await this.dispose()
+  }
+
+  /**
+   * 发起登录（配置 AppID/Secret 后即视为已连接；后台执行，状态通过 getStatus 轮询读取）。
+   * @returns {Promise<{ok: boolean, error?: string}>}  立即返回（已启动）
+   */
+  async login(opts = {}) {
+    // 无二维码流程：QQ 官方 Bot 用 AppID/Secret 鉴权，登录即配置凭证 + 启动网关
+    if (!this.gateway.configured) {
+      return { ok: false, error: '请先在配置面板填写 QQ 开放平台的 AppID 与 ClientSecret' }
+    }
+    this.loginState = { phase: 'done', qrPayload: null, qrKind: null, error: null }
+    void this.gateway.start().catch((err) => {
+      this.logger.error('[dsh-bridge qq] login start failed: %s', err?.message ?? err)
+    })
+    return { ok: true }
+  }
+
+  /** 解绑：停止网关并清除凭证，下次重启不再自动重连。 */
+  async unbind() {
+    await this.gateway.stop()
+    this.gateway.setCredentials({ appId: '', clientSecret: '', accessToken: '', accessTokenExpiresAt: 0 })
+    await this.persist({ appId: '', clientSecret: '', accessToken: '', accessTokenExpiresAt: 0, accountId: '' })
+    this.logger.info('[dsh-bridge qq] unbound: credentials cleared')
+  }
+
+  /** 更新白名单并发起持久化。 */
+  async setAllowFrom(list) {
+    const clean = Array.isArray(list) ? [...new Set(list.map((x) => String(x).trim()).filter(Boolean))] : []
+    this.node.config.allowFrom = clean
+    await this.persist({ allowFrom: clean })
+  }
+
+  /** 更新运行时配置并持久化。 */
+  async setConfig({ digestIntervalSec, approvalTimeoutSec, maxMessageChars, sendChunkDelayMs, appId, clientSecret } = {}) {
+    if (digestIntervalSec != null)   this.node.config.digestIntervalSec   = Number(digestIntervalSec)
+    if (approvalTimeoutSec != null)  this.node.config.approvalTimeoutSec  = Number(approvalTimeoutSec)
+    if (maxMessageChars != null)     this.node.config.maxMessageChars     = Number(maxMessageChars)
+    if (sendChunkDelayMs != null)    this.node.config.sendChunkDelayMs    = Number(sendChunkDelayMs)
+    if (appId !== undefined || clientSecret !== undefined) {
+      this.gateway.setCredentials({
+        appId: appId !== undefined ? appId : this.gateway.config.appId,
+        // 空字符串表示 UI 未修改密钥，避免误覆盖已保存的 secret
+        clientSecret: clientSecret?.trim() ? clientSecret.trim() : this.gateway.config.clientSecret,
+      })
+    }
+    const patch = {
+      digestIntervalSec:  this.node.config.digestIntervalSec,
+      approvalTimeoutSec: this.node.config.approvalTimeoutSec,
+      maxMessageChars:    this.node.config.maxMessageChars,
+      sendChunkDelayMs:   this.node.config.sendChunkDelayMs,
+    }
+    if (appId !== undefined || clientSecret !== undefined) {
+      patch.appId = this.gateway.config.appId
+      patch.clientSecret = this.gateway.config.clientSecret
+    }
+    await this.persist(patch)
+
+    // 凭证配置完成后自动启动网关（前端「保存并连接」无需二次点击）
+    if (this.gateway.configured && (appId !== undefined || clientSecret !== undefined)) {
+      await this.gateway.start().catch((err) => {
+        this.logger?.warn?.('[dsh-bridge qq] auto-start failed: %s', err?.message ?? err)
+      })
+    }
+  }
+}
+
+function gatewayMaxChars() {
+  return 2000
+}

package/lib/qq/node.js

@@ -0,0 +1,210 @@
+// dsh-bridge QQ conversation node
+// 把 QQ OpenAPI v2 的入站事件（C2C 私聊 / 群聊 @提及）解析后交给平台无关的
+// ConversationBridge 处理，出站通过 QqGateway 发送文本 / Markdown / 按钮。
+// 平台特定部分：
+//   - 入站解析：event.scope 决定 c2c / group / guild，text 直接来自 content
+//   - 出站：sendText 走 gateway.sendText；长文本用 Markdown 分块
+//   - 群聊：@提及消息仅在命中机器人才处理（GROUP_AT_MESSAGE_CREATE 已保证）
+
+import { ConversationBridge, conversationBridgeHelpers } from '../platform/conversation-bridge.js'
+import { gatewayConstants } from './gateway.js'
+
+const MAX_MESSAGE_CHARS = gatewayConstants.MAX_MESSAGE_CHARS
+
+// 把 QqGateway 适配为 ConversationBridge 需要的 Platform 消息接口
+function makePlatform(gateway) {
+  return {
+    id: 'qq',
+    name: 'QQ',
+    get accountId() { return gateway.accountId ?? '' },
+    get capabilities() { return gateway.capabilities },
+    sendText: (peer, text) => gateway.sendText(peer, text, {}),
+    sendTyping: (peer, state) => gateway.sendTyping(peer, state),
+    sendKeyboard: (peer, content, keyboard) => gateway.sendKeyboard(peer, content, keyboard, {}),
+  }
+}
+
+export class QqConversationNode extends ConversationBridge {
+  /**
+   * @param {object} ctx          Cordis 上下文（含 ctx.qq 网关服务）
+   * @param {object} config       已持久化配置（allowFrom/间隔/活动会话等）
+   * @param {object} logger       日志器
+   * @param {object} [opts]
+   * @param {(senderId: string) => void} [opts.onFirstSender]
+   * @param {(sessionId: string) => void} [opts.onActiveSessionChange]
+   */
+  constructor(ctx, config, logger, { onFirstSender, onActiveSessionChange } = {}) {
+    super({
+      ctx,
+      logger,
+      config,
+      platform: makePlatform(ctx.qq),
+      onFirstSender,
+      onActiveSessionChange,
+    })
+    this.gateway = ctx.qq
+    this.lastMessageId = null // 存储最后发送的消息 ID，用于消息引用
+
+    // 订阅网关入站事件
+    this.ctx.on('qq/message', (event) => {
+      void this._handleInbound(event)
+    })
+    this.ctx.on('qq/interaction', (event) => {
+      void this._handleInteraction(event)
+    })
+  }
+
+  // ---- 出站：覆盖 sendText，在提示消息中添加按钮 ----
+
+  async sendText(text) {
+    const peer = this.peerId
+    if (!peer) return
+    
+    // 检测是否是提示用户开始新会话的消息
+    const isPromptMessage = text.includes('没有活动会话') || text.includes('恢复会话失败')
+    
+    if (isPromptMessage) {
+      // 发送带按钮的消息，方便用户快速操作
+      const keyboard = {
+        rows: [
+          {
+            buttons: [
+              { id: 'new_conversation', render_data: { label: '🆕 新建会话', visited_label: '新建会话' }, action: { type: 2, permission: { type: 2 } } },
+              { id: 'list_sessions', render_data: { label: '📋 会话列表', visited_label: '会话列表' }, action: { type: 2, permission: { type: 2 } } },
+            ],
+          },
+          {
+            buttons: [
+              { id: 'help', render_data: { label: '❓ 帮助', visited_label: '帮助' }, action: { type: 2, permission: { type: 2 } } },
+            ],
+          },
+        ],
+      }
+      const result = await this.platform.sendKeyboard(peer, text, keyboard)
+      // 保存消息 ID
+      if (result?.data?.message_id) {
+        this.lastMessageId = result.data.message_id
+      }
+      return result
+    }
+    
+    // 其他消息使用流式发送
+    const content = String(text || '').trim()
+    if (content.length === 0) return { success: true }
+    
+    const STREAM_CHUNK_SIZE = 200
+    
+    // 如果消息较短，直接发送普通消息
+    if (content.length <= STREAM_CHUNK_SIZE) {
+      const result = await this.gateway.sendText(peer, content, {})
+      // 保存消息 ID
+      if (result?.data?.message_id) {
+        this.lastMessageId = result.data.message_id
+      }
+      return result
+    }
+    
+    // 流式发送：把内容切分成多段
+    const chunks = []
+    for (let i = 0; i < content.length; i += STREAM_CHUNK_SIZE) {
+      chunks.push(content.slice(i, i + STREAM_CHUNK_SIZE))
+    }
+    
+    // 逐段发送流式消息
+    let firstMsgId = null
+    for (const chunk of chunks) {
+      const result = await this.gateway.sendStream(peer, chunk, {
+        msgId: firstMsgId, // 后续段关联到第一段
+      })
+      if (!firstMsgId && result?.data?.message_id) {
+        firstMsgId = result.data.message_id
+        this.lastMessageId = firstMsgId // 保存第一段消息 ID
+      }
+      if (result?.error) {
+        return { success: false, error: result.error }
+      }
+      // 流式发送间隔稍短，避免刷屏
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    
+    return { success: true }
+  }
+
+  // ---- 入站 ----
+
+  async _handleInbound(event) {
+    const sender = String(event.senderId ?? '').trim()
+    if (!sender) return
+
+    // 快速预检查：白名单非空时，未授权发件人直接忽略
+    if (!this.isAllowed(sender) && this.config.allowFrom.length > 0) {
+      this.logger?.info?.(`[dsh-bridge qq] ignore message from non-allowlisted sender ${sender}`)
+      return
+    }
+
+    const text = String(event.text ?? '').trim()
+    if (!text) {
+      this.logger?.info?.(`[dsh-bridge qq] ignore empty message from ${sender}`)
+      return
+    }
+
+    // 群聊：仅在群聊 @ 机器人事件中处理（GROUP_AT_MESSAGE_CREATE 已由网关归一化）
+    const isGroup = event.scope === 'group' || event.scope === 'guild'
+
+    // 检测消息引用（文本交互）：如果用户回复了机器人的消息，且当前没有活动会话或消息以 /new 开头，
+    // 则自动创建新会话并发送消息
+    const messageReference = event.messageReference
+    if (messageReference && !this.activeSessionId && !text.startsWith('/')) {
+      this.logger?.info?.(`[dsh-bridge qq] detected message reference from ${sender}, auto-starting conversation`)
+      // 先创建新会话，再处理消息
+      await this.handleInbound({ senderId: sender, text: '/new', isGroup })
+      // 等待一小段时间确保会话创建完成
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+
+    // 交给平台无关核心：白名单/群消息/命令路由/agent 分发
+    await this.handleInbound({ senderId: sender, text, isGroup })
+  }
+
+  // ---- 互动事件 ----
+
+  async _handleInteraction(event) {
+    const sender = String(event.senderId ?? '').trim()
+    if (!sender) return
+
+    // 快速预检查：白名单非空时，未授权发件人直接忽略
+    if (!this.isAllowed(sender) && this.config.allowFrom.length > 0) {
+      this.logger?.info?.(`[dsh-bridge qq] ignore interaction from non-allowlisted sender ${sender}`)
+      return
+    }
+
+    const data = event.data || {}
+    const resolved = data.resolved || {}
+    const buttonId = resolved.button_id || ''
+
+    // 响应互动
+    await this.gateway.respondInteraction(event.interactionId, {
+      code: 0,
+    })
+
+    // 根据按钮 ID 执行对应操作
+    if (buttonId === 'new_conversation') {
+      await this.handleInbound({ senderId: sender, text: '/new', isGroup: event.scope === 'group' })
+    } else if (buttonId === 'list_sessions') {
+      await this.handleInbound({ senderId: sender, text: '/list', isGroup: event.scope === 'group' })
+    } else if (buttonId === 'help') {
+      await this.handleInbound({ senderId: sender, text: '/help', isGroup: event.scope === 'group' })
+    } else {
+      this.logger?.info?.(`[dsh-bridge qq] unknown button interaction: ${buttonId}`)
+    }
+  }
+}
+
+// 导出，便于测试与复用
+export const qqNodeHelpers = {
+  splitForQQ: conversationBridgeHelpers.splitForIM,
+  digestLine: conversationBridgeHelpers.digestLine,
+  textOfAssistantMessage: conversationBridgeHelpers.textOfAssistantMessage,
+  listSessions: conversationBridgeHelpers.listSessions,
+  sessionsInDisplayOrder: conversationBridgeHelpers.sessionsInDisplayOrder,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenbin_wb/dsh-bridge",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "手机扫码即可在移动端/公网继续用 DeepSeek Harness，人不在电脑前也能接着干。一键局域网二维码、Cloudflare 公网隧道、自建隧道与微信 Bot（多工作区/会话持久化/媒体/审批），无需自己搭公网服务器。",
   "type": "module",
   "main": "lib/index.js",