myagent-ai 1.20.3 → 1.20.5

package/agents/main_agent.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import re
 from typing import Any, Callable, Dict, List, Optional
 
@@ -76,6 +77,18 @@ class MainAgent(BaseAgent):
 - **发送文件给用户**: 用 `file_send` 工具（参数: file_path=文件路径, description=说明），当你生成或处理了文件需要返回给用户时使用
 - **播放音频**: 用 `playaudio` 工具（参数: url=音乐链接或file_path=本地文件路径），在聊天中内嵌播放音频（支持QQ音乐、YouTube音乐、本地MP3/WAV等），播放时自动关闭语音合成
 - **播放视频**: 用 `playvideo` 工具（参数: url=视频链接或file_path=本地文件路径），在聊天中内嵌播放视频（支持抖音、YouTube、B站、本地MP4等），播放时自动关闭语音合成
+- **网页控制**: 用 `web_control` 工具在聊天中打开一个可控制的浏览器面板，可浏览网页、点击元素、填写表单、滚动页面、执行JS、管理Cookie等。
+  - 打开: `{"action": "open", "url": "https://example.com"}` — 首次使用会自动创建会话，后续可传 session_id 复用
+  - 导航: `{"action": "navigate", "url": "https://...", "session_id": "xxx"}`
+  - 获取内容: `{"action": "get_content", "what": "text|html|url|title|links|images|forms|inputs", "session_id": "xxx"}`
+  - 点击元素: `{"action": "click", "selector": "CSS选择器", "session_id": "xxx"}`
+  - 填写输入: `{"action": "fill", "selector": "CSS选择器", "value": "内容", "session_id": "xxx"}`
+  - 滚动页面: `{"action": "scroll", "direction": "up|down|top|bottom", "distance": 300, "session_id": "xxx"}`
+  - 执行JS: `{"action": "evaluate", "script": "JavaScript代码", "session_id": "xxx"}`
+  - 管理Cookie: `{"action": "set_cookies", "cookies": [{"name":"k","value":"v","domain":"example.com"}], "session_id": "xxx"}` 或 `{"action": "get_cookies", "session_id": "xxx"}`
+  - 等待: `{"action": "wait", "time": 1000}` 毫秒 或 `{"action": "wait", "selector": ".result", "timeout": 10}` 秒
+  - 关闭: `{"action": "close", "session_id": "xxx"}`
+  - 注意: 网页通过服务端代理加载，用户可在面板中手动操作。复杂交互建议先用 get_content 查看页面结构再用 click/fill。
 - **主动召回记忆**: 用 `recall_memory` 工具（参数: keyword=关键字, time_point=可选时间点如"2025-01", limit=数量默认5），根据关键字和时间搜索历史记忆
 4. 准备好内容后，最后，再检查输出格式，确保满足以下要求:
 <output>
@@ -1216,6 +1229,7 @@ class MainAgent(BaseAgent):
                 tool_result = await self._execute_v2_tool(
                     tool_name, parms, timeout, context, task_id,
                     stream_callback=stream_callback,
+                    sent_files=_sent_files,
                 )
 
                 # 发送工具结果事件
@@ -1552,6 +1566,7 @@ class MainAgent(BaseAgent):
         context: AgentContext,
         task_id: str,
         stream_callback: Optional[Callable] = None,
+        sent_files: Optional[List[Dict[str, Any]]] = None,
     ) -> Dict[str, Any]:
         """V2 工具执行"""
         result = {"success": False, "output": "", "error": ""}
@@ -1634,18 +1649,14 @@ class MainAgent(BaseAgent):
                     # [v1.16.18] 使用当前作用域的 stream_callback（而非 context._stream_callback）
                     _fresult = await _fskill.execute(_fpath, _fdesc, stream_callback=stream_callback)
                     result = {"success": True, "output": json.dumps(_fresult, ensure_ascii=False, indent=2), "data": _fresult}
-                    # [v1.18.5] 追踪发送的文件，用于持久化到会话记忆
-                    # [v1.18.9] 修复：_sent_files 可能不在作用域内，安全处理
-                    try:
-                        if _fresult.get("success") and _fresult.get("file_id"):
-                            _sent_files.append({
-                                "id": _fresult["file_id"],
-                                "name": _fresult.get("name", ""),
-                                "type": _fresult.get("type", ""),
-                                "size": _fresult.get("size", 0),
-                            })
-                    except NameError:
-                        pass  # _sent_files 不在当前作用域，跳过文件追踪
+                    # [v1.18.5→21.1] 追踪发送的文件，用于持久化到会话记忆
+                    if sent_files is not None and _fresult.get("success") and _fresult.get("file_id"):
+                        sent_files.append({
+                            "id": _fresult["file_id"],
+                            "name": _fresult.get("name", ""),
+                            "type": _fresult.get("type", ""),
+                            "size": _fresult.get("size", 0),
+                        })
                 except Exception as _fse:
                     result = {"success": False, "error": f"文件发送失败: {_fse}"}
                     logger.warning(f"[{task_id}] file_send 工具异常: {_fse}")
@@ -1727,17 +1738,14 @@ class MainAgent(BaseAgent):
                                 # 标记为媒体文件，前端渲染内嵌播放器
                                 _fresult["_media_type"] = _media_type
                                 result = {"success": True, "output": f"已发送{_media_type}文件: {_fpath.name}", "data": _fresult}
-                                try:
-                                    if _fresult.get("file_id"):
-                                        _sent_files.append({
-                                            "id": _fresult["file_id"],
-                                            "name": _fresult.get("name", ""),
-                                            "type": _fresult.get("type", ""),
-                                            "size": _fresult.get("size", 0),
-                                            "_media_type": _media_type,
-                                        })
-                                except NameError:
-                                    pass
+                                if sent_files is not None and _fresult.get("file_id"):
+                                    sent_files.append({
+                                        "id": _fresult["file_id"],
+                                        "name": _fresult.get("name", ""),
+                                        "type": _fresult.get("type", ""),
+                                        "size": _fresult.get("size", 0),
+                                        "_media_type": _media_type,
+                                    })
                             else:
                                 result = {"success": False, "error": _fresult.get("error", "文件发送失败")}
                     else:
@@ -1747,12 +1755,138 @@ class MainAgent(BaseAgent):
                     result = {"success": False, "error": f"播放工具异常: {_me}"}
                     logger.warning(f"[{task_id}] {tool_name} 工具异常: {_me}")
 
+            elif tool_name == "web_control":
+                # [v1.21.0] 网页控制器 — 在聊天中打开可控制的浏览器面板
+                try:
+                    from core.web_control import get_web_control_manager
+                    _wc_mgr = get_web_control_manager()
+                    _wc_action = params.get("action", "open")
+                    _wc_session_id = params.get("session_id", "").strip()
+
+                    # 自动获取或创建会话
+                    _wc_session = None
+                    if _wc_session_id:
+                        _wc_session = _wc_mgr.get_session(_wc_session_id)
+                    if not _wc_session:
+                        _wc_session = _wc_mgr.create_session()
+                        _wc_session_id = _wc_session.session_id
+
+                    if _wc_action == "open":
+                        # 打开面板 — 发送 SSE 事件让前端弹出控制面板
+                        _wc_url = params.get("url", "").strip()
+                        if _wc_url:
+                            _wc_session.current_url = _wc_url
+                        if stream_callback:
+                            stream_callback({
+                                "type": "v2_web_control",
+                                "data": {
+                                    "action": "open",
+                                    "session_id": _wc_session_id,
+                                    "url": _wc_url,
+                                    "panel_url": f"/api/web_control/panel?sid={_wc_session_id}",
+                                }
+                            })
+                        result = {
+                            "success": True,
+                            "output": f"已打开网页控制面板 (session: {_wc_session_id})" + (f"，URL: {_wc_url}" if _wc_url else ""),
+                            "session_id": _wc_session_id,
+                        }
+
+                    elif _wc_action == "close":
+                        _wc_mgr.close_session(_wc_session_id)
+                        if stream_callback:
+                            stream_callback({
+                                "type": "v2_web_control",
+                                "data": {"action": "close", "session_id": _wc_session_id}
+                            })
+                        result = {"success": True, "output": f"已关闭网页控制面板 (session: {_wc_session_id})"}
+
+                    elif _wc_action == "navigate":
+                        _wc_url = params.get("url", "").strip()
+                        if not _wc_url:
+                            result = {"success": False, "error": "请提供 url 参数"}
+                        else:
+                            _wc_session.current_url = _wc_url
+                            if stream_callback:
+                                stream_callback({
+                                    "type": "v2_web_control",
+                                    "data": {"action": "navigate", "session_id": _wc_session_id, "url": _wc_url}
+                                })
+                            result = {"success": True, "output": f"正在导航到: {_wc_url}"}
+
+                    elif _wc_action in ("set_cookies", "get_cookies"):
+                        # Cookie 操作 — 服务端直接处理
+                        if _wc_action == "set_cookies":
+                            _cookies = params.get("cookies", [])
+                            if isinstance(_cookies, str):
+                                import json as _jc
+                                try:
+                                    _cookies = _jc.loads(_cookies)
+                                except:
+                                    _cookies = []
+                            for _c in _cookies:
+                                if isinstance(_c, dict):
+                                    _c_domain = _c.get("domain", "").lstrip(".")
+                                    _c_name = _c.get("name", "")
+                                    _c_value = _c.get("value", "")
+                                    if _c_domain and _c_name:
+                                        _wc_session.cookies[f"{_c_domain}::{_c_name}"] = _c_value
+                            result = {"success": True, "output": f"已设置 {len(_cookies)} 个 cookie", "total_cookies": len(_wc_session.cookies)}
+                        else:
+                            _cookie_list = []
+                            for _ck, _cv in _wc_session.cookies.items():
+                                _parts = _ck.split("::", 1)
+                                if len(_parts) == 2:
+                                    _cookie_list.append({"domain": _parts[0], "name": _parts[1], "value": _cv})
+                            result = {"success": True, "output": json.dumps(_cookie_list, ensure_ascii=False), "cookies": _cookie_list}
+
+                    else:
+                        # 其他操作（click, fill, scroll, evaluate, get_content, wait, screenshot）
+                        # 通过命令队列下发到客户端执行，阻塞等待结果
+                        _wc_params = {k: v for k, v in params.items() if k not in ("action", "session_id")}
+                        _wc_timeout = int(params.get("timeout", timeout))
+                        _wc_result = await _wc_mgr.queue_command(
+                            session_id=_wc_session_id,
+                            action=_wc_action,
+                            params=_wc_params,
+                            timeout=min(_wc_timeout, 60),  # 最大 60 秒
+                        )
+                        result = _wc_result
+
+                except Exception as _wce:
+                    result = {"success": False, "error": f"网页控制器异常: {_wce}"}
+                    logger.warning(f"[{task_id}] web_control 工具异常: {_wce}")
+
             elif self.skills:
                 exec_result = await self.skills.execute(tool_name, **params)
                 if exec_result is None:
                     result["error"] = f"技能 {tool_name} 返回了空结果"
                 else:
                     result = exec_result.to_dict()
+                    # [v1.21.1] Skill 生成文件后自动通过 file_send 发送给前端
+                    if exec_result.success and exec_result.files:
+                        try:
+                            from skills.file_send import FileSendSkill
+                            _auto_fsend = FileSendSkill()
+                            for _auto_fpath in exec_result.files:
+                                if _auto_fpath and os.path.isfile(_auto_fpath):
+                                    _auto_fres = await _auto_fsend.execute(
+                                        _auto_fpath, stream_callback=stream_callback)
+                                    if _auto_fres.get("success") and _auto_fres.get("file_id"):
+                                        # 记录发送的 file_id
+                                        if not result.get("_sent_file_ids"):
+                                            result["_sent_file_ids"] = []
+                                        result["_sent_file_ids"].append(_auto_fres["file_id"])
+                                        # 追踪到 sent_files（持久化到会话记忆）
+                                        if sent_files is not None:
+                                            sent_files.append({
+                                                "id": _auto_fres["file_id"],
+                                                "name": _auto_fres.get("name", ""),
+                                                "type": _auto_fres.get("type", ""),
+                                                "size": _auto_fres.get("size", 0),
+                                            })
+                        except Exception as _afe:
+                            logger.warning(f"[{task_id}] 自动 file_send 失败: {_afe}")
             else:
                 result["error"] = f"未知工具: {tool_name}"
 

package/chatbot/manager.py

@@ -37,6 +37,10 @@ class ChatBotManager:
         self._bots: Dict[str, BaseChatBot] = {}
         self._session_map: Dict[str, str] = {}  # session_id -> last_message
 
+    def get_bot(self, key: str):
+        """根据 key (id 或 platform 名) 获取 bot 实例"""
+        return self._bots.get(key)
+
     def setup_platforms(
         self,
         platform_configs: List[ChatPlatformConfig],
@@ -111,6 +115,8 @@ class ChatBotManager:
         elif platform == "wechat":
             from chatbot.wechat_bot import WeChatBot
             return WeChatBot(
+                app_id=config.app_id,
+                app_secret=config.app_secret,
                 token=config.token,
                 allowed_users=config.allowed_users,
                 message_handler=message_handler,

package/chatbot/whatsapp_bot.py

@@ -2,7 +2,7 @@
 chatbot/whatsapp_bot.py - WhatsApp 机器人
 ===========================================
 使用 whatsapp-web.js 或 Baileys 库接入 WhatsApp。
-支持二维码绑定。
+支持二维码绑定（通过 Node.js Baileys bridge）。
 纯 Python 实现，异步运行。
 """
 from __future__ import annotations
@@ -10,6 +10,9 @@ from __future__ import annotations
 import asyncio
 import json
 import time
+import os
+import subprocess
+from pathlib import Path
 from typing import Optional, List
 
 from chatbot.base import BaseChatBot, ChatMessage, ChatResponse
@@ -25,17 +28,19 @@ class WhatsAppBot(BaseChatBot):
     """
     WhatsApp 机器人适配器。
 
-    配置要求:
+    配置要求 (Cloud API 模式):
       - token: Access Token (从 Meta Developer Portal 获取)
-      - app_id: App ID
-      - app_secret: App Secret
-      - webhook_url: Webhook URL (可选，用于接收消息)
       - phone_number_id: Phone Number ID (从 Meta 获取)
       - verify_token: Webhook 验证 Token (自动生成)
 
+    配置要求 (QR 码绑定模式):
+      - 无需 token / phone_number_id
+      - 需要 Node.js 环境 + Baileys 依赖
+      - 首次运行会生成 QR 码，扫码后自动保存会话
+
     支持两种模式:
       1. Cloud API 模式: 使用 Meta WhatsApp Business API
-      2. 二维码绑定模式: 通过 QR Code 绑定（需要 Baileys 库）
+      2. Baileys 模式: 通过 QR Code 绑定 (推荐个人使用)
     """
 
     platform_name = "whatsapp"
@@ -47,35 +52,161 @@ class WhatsAppBot(BaseChatBot):
         self._phone_number_id = self.config.get("phone_number_id", "")
         self._verify_token = self.config.get("verify_token", "")
         self._webhook_base = self.config.get("webhook_base", "")
-        self._qrcode_callback = self.config.get("qrcode_callback", None)
         self._qr_code = ""
         self._connected = False
+        self._bridge_process: Optional[subprocess.Popen] = None
+        self._bridge_mode = not self._phone_number_id  # 没有 phone_number_id 则使用 bridge
+        self._session_dir = str(Path(__file__).parent / "whatsapp_bridge" / "session")
 
     async def start(self):
         """启动 WhatsApp 机器人"""
+        if self._bridge_mode:
+            await self._start_bridge_mode()
+        else:
+            await self._start_cloud_mode()
+
+    async def _start_cloud_mode(self):
+        """Meta Cloud API 模式"""
         if not self.token:
             self.logger.error("WhatsApp Access Token 未配置")
             return
+        if not self._phone_number_id:
+            self.logger.error("Cloud API 模式需要配置 phone_number_id")
+            return
 
-        # Meta Cloud API 模式
-        if self._phone_number_id:
-            self.logger.info("WhatsApp Cloud API 模式启动")
-            self._connected = True
-            # Cloud API 模式通过 Webhook 接收消息，不需要主动轮询
-            # 保持运行
-            while self._running:
-                await asyncio.sleep(1)
-        else:
-            self.logger.warning(
-                "WhatsApp 需要配置 phone_number_id 才能使用 Cloud API 模式。"
-                "请访问 Meta Developer Portal 获取 WhatsApp Business API 凭据。"
+        self.logger.info("WhatsApp Cloud API 模式启动")
+        self._connected = True
+        while self._running:
+            await asyncio.sleep(1)
+
+    async def _start_bridge_mode(self):
+        """Baileys Bridge 模式 (QR 码绑定)"""
+        bridge_dir = Path(__file__).parent / "whatsapp_bridge"
+        bridge_script = bridge_dir / "bridge.mjs"
+
+        if not bridge_script.exists():
+            self.logger.error(f"Bridge 脚本不存在: {bridge_script}")
+            self.logger.error("请运行: cd chatbot/whatsapp_bridge && npm install @whiskeysockets/baileys qrcode-terminal")
+            return
+
+        # 检查是否已安装依赖
+        node_modules = bridge_dir / "node_modules"
+        if not node_modules.exists():
+            self.logger.info("正在安装 Baileys 依赖...")
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    "npm", "install", "--production",
+                    cwd=str(bridge_dir),
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                )
+                stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=120)
+                if proc.returncode != 0:
+                    self.logger.error(f"Baileys 安装失败: {stderr.decode()[:500]}")
+                    return
+                self.logger.info("Baileys 依赖安装完成")
+            except Exception as e:
+                self.logger.error(f"Baileys 安装异常: {e}")
+                return
+
+        env = os.environ.copy()
+        env["SESSION_DIR"] = self._session_dir
+
+        try:
+            self._bridge_process = await asyncio.create_subprocess_exec(
+                "node", str(bridge_script),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+                cwd=str(bridge_dir),
             )
-            self._connected = False
+            self.logger.info("WhatsApp Bridge 进程已启动")
+
+            # 启动消息读取循环
+            asyncio.create_task(self._read_bridge_output())
+        except Exception as e:
+            self.logger.error(f"Bridge 启动失败: {e}")
+
+        while self._running:
+            await asyncio.sleep(1)
+
+    async def _read_bridge_output(self):
+        """读取 Bridge 进程的 stdout (JSON 协议)"""
+        if not self._bridge_process or not self._bridge_process.stdout:
+            return
+
+        try:
+            reader = self._bridge_process.stdout
+            while self._running and self._bridge_process.returncode is None:
+                line = await reader.readline()
+                if not line:
+                    break
+                line = line.decode('utf-8', errors='replace').strip()
+                if not line:
+                    continue
+                try:
+                    msg = json.loads(line)
+                    msg_type = msg.get("type", "")
+
+                    if msg_type == "qr":
+                        self._qr_code = msg.get("qr", "")
+                        self.logger.info("QR 码已生成，等待扫码...")
+
+                    elif msg_type == "connected":
+                        self._connected = True
+                        phone = msg.get("phone", "")
+                        name = msg.get("name", "")
+                        self.logger.info(f"WhatsApp 已连接: {name} ({phone})")
+                        # 更新配置中的连接状态
+                        self.config["connection_status"] = "connected"
+                        self.config["connected_phone"] = phone
+
+                    elif msg_type == "disconnected":
+                        self._connected = False
+                        reason = msg.get("reason", "unknown")
+                        self.logger.warning(f"WhatsApp 已断开: {reason}")
+                        self.config["connection_status"] = "disconnected"
+
+                    elif msg_type == "message":
+                        from_id = msg.get("from", "")
+                        text = msg.get("text", "")
+                        push_name = msg.get("pushName", "")
+                        if from_id and text:
+                            chat_msg = ChatMessage(
+                                platform=self.platform_name,
+                                chat_id=from_id,
+                                user_id=from_id,
+                                username=push_name or from_id.split('@')[0],
+                                text=text,
+                                is_group='@g.us' in from_id,
+                                raw_data=msg,
+                            )
+                            await self._handle_message(chat_msg)
+
+                    elif msg_type == "error":
+                        error = msg.get("error", "")
+                        self.logger.error(f"Bridge 错误: {error}")
+
+                except json.JSONDecodeError:
+                    self.logger.debug(f"非 JSON 输出: {line[:100]}")
+        except Exception as e:
+            self.logger.error(f"Bridge 输出读取异常: {e}")
 
     async def stop(self):
         """停止 WhatsApp 机器人"""
         self._running = False
         self._connected = False
+
+        if self._bridge_process:
+            try:
+                self._bridge_process.terminate()
+                await asyncio.sleep(1)
+                if self._bridge_process.returncode is None:
+                    self._bridge_process.kill()
+            except Exception:
+                pass
+            self._bridge_process = None
+
         self.logger.info("WhatsApp 机器人已停止")
 
     async def send_message(self, response: ChatResponse) -> bool:
@@ -83,36 +214,56 @@ class WhatsAppBot(BaseChatBot):
         if not self._connected or not response.chat_id:
             return False
 
+        if self._bridge_mode:
+            return await self._send_via_bridge(response.chat_id, response.text)
+        else:
+            return await self._send_via_cloud_api(response.chat_id, response.text)
+
+    async def _send_via_bridge(self, chat_id: str, text: str) -> bool:
+        """通过 Bridge 发送消息"""
+        if not self._bridge_process or not self._bridge_process.stdin:
+            return False
         try:
-            if not HAS_AIOHTTP:
-                self.logger.error("请安装 aiohttp: pip install aiohttp")
-                return False
-
-            url = f"https://graph.facebook.com/v18.0/{self._phone_number_id}/messages"
-            headers = {
-                "Authorization": f"Bearer {self.token}",
-                "Content-Type": "application/json",
-            }
-            payload = {
-                "messaging_product": "whatsapp",
-                "to": response.chat_id,
-                "type": "text",
-                "text": {"body": response.text[:4096]},
-            }
+            msg = json.dumps({"action": "send", "to": chat_id, "text": text}) + "\n"
+            self._bridge_process.stdin.write(msg.encode('utf-8'))
+            await self._bridge_process.stdin.drain()
+            return True
+        except Exception as e:
+            self.logger.error(f"Bridge 发送失败: {e}")
+            return False
+
+    async def _send_via_cloud_api(self, chat_id: str, text: str) -> bool:
+        """通过 Cloud API 发送消息"""
+        if not HAS_AIOHTTP:
+            self.logger.error("请安装 aiohttp: pip install aiohttp")
+            return False
+
+        url = f"https://graph.facebook.com/v18.0/{self._phone_number_id}/messages"
+        headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "messaging_product": "whatsapp",
+            "to": chat_id,
+            "type": "text",
+            "text": {"body": text[:4096]},
+        }
 
+        try:
             async with aiohttp.ClientSession() as session:
                 async with session.post(url, headers=headers, json=payload) as resp:
                     if resp.status == 200:
                         return True
                     error_text = await resp.text()
-                    self.logger.error(f"WhatsApp 发送失败 ({resp.status}): {error_text}")
+                    self.logger.error(f"WhatsApp 发送失败 ({resp.status}): {error_text[:200]}")
                     return False
         except Exception as e:
-            self.logger.error(f"发送消息失败: {e}")
+            self.logger.error(f"Cloud API 发送失败: {e}")
             return False
 
     # ==========================================================================
-    # Webhook 处理
+    # Webhook 处理 (Cloud API 模式)
     # ==========================================================================
 
     def verify_webhook(self, mode: str, token: str, challenge: str) -> Optional[str]:
@@ -122,7 +273,7 @@ class WhatsAppBot(BaseChatBot):
         return None
 
     async def handle_webhook_event(self, event_data: dict):
-        """处理 Webhook 事件"""
+        """处理 Webhook 事件 (Cloud API 模式)"""
         try:
             for entry in event_data.get("entry", []):
                 for change in entry.get("changes", []):
@@ -130,7 +281,6 @@ class WhatsAppBot(BaseChatBot):
                     messages = value.get("messages", [])
                     contacts = value.get("contacts", [])
 
-                    # 构建联系人映射
                     contact_map = {}
                     for c in contacts:
                         wa_id = c.get("wa_id", "")
@@ -146,7 +296,6 @@ class WhatsAppBot(BaseChatBot):
                         text_body = msg.get("text", {}).get("body", "")
                         msg_id = msg.get("id", "")
                         timestamp = msg.get("timestamp", "")
-
                         username = contact_map.get(from_id, from_id)
 
                         message = ChatMessage(
@@ -164,16 +313,31 @@ class WhatsAppBot(BaseChatBot):
             self.logger.error(f"处理 Webhook 事件失败: {e}")
 
     # ==========================================================================
-    # 二维码绑定
+    # QR 码绑定
     # ==========================================================================
 
     def get_qr_code(self) -> str:
-        """获取当前 QR Code（用于绑定模式）"""
+        """获取当前 QR Code（base64 PNG 图片）"""
         return self._qr_code
 
     async def generate_qr_code(self) -> str:
-        """生成绑定二维码"""
-        # Cloud API 模式不需要 QR Code
-        # 如需 Baileys 模式，需额外安装 node.js 依赖
-        self.logger.info("WhatsApp Cloud API 模式不需要 QR Code 绑定，使用 Webhook 接收消息")
+        """请求生成 QR 码。Bridge 模式下，首次启动会自动生成。"""
+        if self._bridge_mode:
+            # 如果 bridge 已在运行且有 QR 码，直接返回
+            if self._qr_code:
+                return self._qr_code
+            # 如果 bridge 未运行，尝试启动
+            if not self._bridge_process or self._bridge_process.returncode is not None:
+                asyncio.create_task(self._start_bridge_mode())
+                # 等待 QR 码生成（最多 30 秒）
+                for _ in range(60):
+                    await asyncio.sleep(0.5)
+                    if self._qr_code:
+                        return self._qr_code
+                    if self._connected:
+                        return ""  # 已连接，不需要 QR
+            return self._qr_code
+
+        # Cloud API 模式不需要 QR
+        self.logger.info("Cloud API 模式不需要 QR Code")
         return ""