foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/browser/service.py

@@ -0,0 +1,148 @@
+"""
+BrowserService —— HIR-Browser 在 Foxclaw 内的 async 安全接入层。
+
+它解决把"同步 Playwright 浏览器"塞进"async FastAPI"的三个硬约束：
+
+  A1 可选依赖：playwright（及 chromium 内核）是可选 extra。未安装时
+     available()=False，perceive/act 返回结构化"不可用"而非崩溃，
+     与 search 子系统的优雅降级一致。
+
+  A2 线程亲和 + 事件循环禁区：Playwright sync API 不能在 asyncio 事件
+     循环线程里运行，且其对象绑定创建它的线程。故本 Service 用一条
+     max_workers=1 的**专用工作线程**独占持有会话——所有浏览器操作都
+     被 run_in_executor 派发到这同一条线程，既满足线程亲和，也天然把
+     单会话（v1 只支持单会话）的访问串行化。
+
+  A3 感知入口：额外暴露 perceive()（只感知、不动作），供 agent/前端在
+     决策前读取页面语义结构；原 WebAdapter 只有 execute。
+
+对外方法都是 async，直接 await 即可；内部 _*_sync 方法只在工作线程上跑。
+"""
+
+import asyncio
+import importlib.util
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional
+
+
+class BrowserService:
+
+    def __init__(self, headless: bool = True):
+        self._headless = headless
+        self._session = None
+        self._executor: Optional[ThreadPoolExecutor] = None
+        self._closed = False
+        self._launch_error: Optional[str] = None
+        # 保护 executor/session 的创建与关闭（仅协调，不进浏览器调用）
+        self._guard = threading.Lock()
+
+    # ── 能力探测 ────────────────────────────────────────────────
+    @staticmethod
+    def available() -> bool:
+        """playwright 包是否可导入。注意：这不保证 chromium 内核已 install，
+        内核缺失会在首次 launch 时暴露，由 _launch_error 记录并透出。"""
+        return importlib.util.find_spec("playwright") is not None
+
+    def status(self) -> dict:
+        return {
+            "available": self.available(),
+            "headless": self._headless,
+            "session_active": self._session is not None,
+            "closed": self._closed,
+            "launch_error": self._launch_error,
+        }
+
+    # ── 工作线程上运行的同步实现 ──────────────────────────────────
+    def _get_executor(self) -> ThreadPoolExecutor:
+        with self._guard:
+            if self._closed:
+                raise RuntimeError("BrowserService 已关闭")
+            if self._executor is None:
+                self._executor = ThreadPoolExecutor(
+                    max_workers=1, thread_name_prefix="foxclaw-browser")
+            return self._executor
+
+    def _ensure_session_sync(self):
+        """在工作线程上惰性构造会话（首次 launch chromium）。"""
+        if self._session is None:
+            from .session.session_manager import SessionManager
+            self._session = SessionManager(headless=self._headless)
+        return self._session
+
+    def _perceive_sync(self) -> dict:
+        return self._ensure_session_sync().snapshot().to_dict()
+
+    def _act_sync(self, action_dict: dict) -> dict:
+        from .action.action_types import WebAction
+        session = self._ensure_session_sync()
+        return session.execute(WebAction.from_dict(action_dict))
+
+    def _close_sync(self):
+        if self._session is not None:
+            try:
+                self._session.close()
+            finally:
+                self._session = None
+
+    async def _run(self, fn, *args):
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self._get_executor(), fn, *args)
+
+    # ── 对外 async API ─────────────────────────────────────────
+    async def perceive(self) -> dict:
+        """只感知当前页面语义结构，不改变页面状态。"""
+        if not self.available():
+            return self._unavailable()
+        try:
+            return {"ok": True, "semantic_state": await self._run(self._perceive_sync)}
+        except Exception as e:
+            return self._handle_error(e)
+
+    async def act(self, action: dict) -> dict:
+        """执行一个 Web 动作（navigate/click/type/scroll/extract/wait），返回校验后最新语义结构。"""
+        if not self.available():
+            return self._unavailable()
+        if not isinstance(action, dict) or "type" not in action:
+            return {"ok": False, "error": "非法动作：需 {type, target?, value?}"}
+        try:
+            return {"ok": True, **await self._run(self._act_sync, action)}
+        except ValueError as e:  # 不支持的动作类型 / 非法编号
+            return {"ok": False, "error": str(e)}
+        except KeyError as e:    # 元素编号过期
+            return {"ok": False, "error": str(e).strip('"')}
+        except Exception as e:
+            return self._handle_error(e)
+
+    async def close(self):
+        """释放浏览器会话并关停专用工作线程（幂等）。挂到 Foxclaw teardown。"""
+        with self._guard:
+            if self._closed:
+                return
+            self._closed = True
+            executor = self._executor
+        if executor is not None:
+            try:
+                # 会话的 close 必须回到工作线程执行（Playwright 对象线程亲和）
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(executor, self._close_sync)
+            finally:
+                executor.shutdown(wait=True)
+
+    # ── 错误/降级处理 ──────────────────────────────────────────
+    def _unavailable(self) -> dict:
+        return {
+            "ok": False,
+            "available": False,
+            "error": "浏览器子系统不可用：未安装 playwright（可选依赖）。"
+                     "安装：pip install 'foxclaw[browser]' 且 playwright install chromium",
+        }
+
+    def _handle_error(self, e: Exception) -> dict:
+        msg = str(e)
+        # chromium 内核未安装是最常见的 launch 失败，给出可操作提示
+        if "playwright install" in msg or "Executable doesn't exist" in msg:
+            self._launch_error = msg
+            return {"ok": False, "available": False,
+                    "error": "playwright 已装但缺 chromium 内核，请运行：playwright install chromium"}
+        return {"ok": False, "error": f"{type(e).__name__}: {msg}"}

package/python/foxclaw/browser/session/__init__.py

@@ -0,0 +1 @@
+"""会话层：单浏览器会话的生命周期与组件组装（感知/执行/校验的统一入口）。"""

package/python/foxclaw/browser/session/session_manager.py

@@ -0,0 +1,57 @@
+"""
+SessionManager —— 单浏览器会话的生命周期管理与组件组装。
+
+v1.0 明确只支持单会话（对应审计里"v1不做分布式/多浏览器集群"的边界）。
+多会话池、并发调度属于 Infrastructure Plane，v2 再做。
+
+【融合注记 A2】本类构造即 launch chromium（有线程亲和性），
+必须始终在 BrowserService 的同一条专用工作线程上构造与调用。
+"""
+
+from ..driver.playwright_driver import PlaywrightDriver
+from ..perception.dom_extractor import DomExtractor
+from ..perception.element_indexer import ElementIndexer
+from ..perception.semantic_reducer import SemanticReducer
+from ..action.action_executor import ActionExecutor
+from ..action.action_verifier import ActionVerifier
+from ..action.action_types import WebAction
+
+
+class SessionManager:
+
+    def __init__(self, headless: bool = True):
+        self.driver = PlaywrightDriver(headless=headless)
+        self.indexer = ElementIndexer()
+        self.dom_extractor = DomExtractor(self.driver)
+        self.reducer = SemanticReducer(self.dom_extractor, self.indexer)
+        self.executor = ActionExecutor(self.driver, self.indexer)
+        self.verifier = ActionVerifier()
+
+    def snapshot(self):
+        """对外暴露的唯一"感知"入口"""
+        return self.reducer.reduce()
+
+    def execute(self, action: WebAction) -> dict:
+        """
+        对外暴露的唯一"执行"入口：
+        执行前拍快照 -> 执行 -> 执行后拍快照 -> 校验 -> 返回最新语义结构
+
+        注：执行前的 before 快照会重建元素编号表——这既服务于 diff 校验，
+        也顺带刷新了可能已 detach 的旧句柄（页面在两次调用间可能已变化）。
+        因此上层引用的编号应来自"上一次 execute/perceive 返回的 semantic_state"，
+        且假定两次调用之间页面结构稳定（编号按 DOM 顺序稳定复现）。
+        """
+        before = self.snapshot()
+        raw_result = self.executor.run(action)
+        after = self.snapshot()
+
+        verification = self.verifier.verify(before, after, action)
+
+        return {
+            "raw": raw_result,
+            "semantic_state": after.to_dict(),
+            "verified": verification,
+        }
+
+    def close(self):
+        self.driver.close()

package/python/foxclaw/capability/__init__.py

@@ -0,0 +1,12 @@
+"""
+foxclaw.capability —— 全系统共享的能力层(Capability Plane)。
+
+把"重、且应当全进程共享一份"的能力收敛到这里,避免各模块各自加载:
+  · EmbeddingService:sentence-transformers 文本向量,按模型名缓存,全进程只加载一次
+    (此前 5 个 Harness 各建一个 SemanticDrift → 各自 load 一次模型,启动 6×→现 1×)
+
+(后续 v2 的 LLMRouter 也应上浮到这一层,与 EmbeddingService 并列。)
+"""
+from .embedding_service import get_text_embedder, embedding_stats
+
+__all__ = ["get_text_embedder", "embedding_stats"]

package/python/foxclaw/capability/embedding_service.py

@@ -0,0 +1,67 @@
+"""
+EmbeddingService —— 进程内共享的文本向量能力(P0 性能修复)。
+
+问题:此前每个 Harness 各建一个 SemanticDrift → 各自 `SentenceTransformer(model)`。
+     5 个 Agent = 5 份同名模型驻留内存 + 5 次加载(启动慢的主因,run_all 实测 44s→7s
+     还是靠离线缓存,加载次数没减)。
+
+方案:按模型名进程内缓存,同名模型只加载一次,全系统共享同一个只读实例。
+     · sentence-transformers 的 encode 是无梯度前向,多线程对同一只读模型并发 encode
+       是安全的(标准的"一个模型服务多请求"模式),故共享比每 Agent 各持一份更优:
+       内存 5×→1×,加载 5×→1×。
+     · 缺库/加载失败 → 返回 None,调用方(SemanticDrift)自动降级 n-gram 哈希嵌入。
+
+【P2·单 embedding 入口·share-bge-m3】
+  ★ 改用 HKC 进程缓存(hkc_search.embedding_backends.get_st_model)取模型 instance,
+    与 HKC 检索 / HMR VectorStore / Harness SemanticDrift 全部走同一份 instance,
+    全 Foxclaw 真正只 load bge-m3 **1 次**。之前这里自己 `SentenceTransformer(name)`,
+    导致 Harness 启动期独立 Loading 第 2 次(浪费 ~1GB 内存)。
+"""
+from __future__ import annotations
+import os
+import threading
+
+_lock = threading.Lock()
+_cache: dict[str, object] = {}     # model_name -> model 实例 或 None(加载失败/缺库)
+_load_attempts = 0                  # 实际发起过多少次"加载尝试"(缓存命中不计),用于验证收敛
+
+
+def get_text_embedder(model_name: str | None = None):
+    """返回按 model_name 缓存的共享文本向量模型(sentence-transformers)。
+    走 HKC 进程缓存(hkc_search.embedding_backends.get_st_model),同名只加载一次,
+    与 HKC / HMR 共用同一 instance(share-bge-m3)。缺库/失败返回 None。线程安全。
+
+    model_name 解析链(【P2·单 embedding 入口】)——
+      显式传参 > EMBEDDING_MODEL(系统唯一本地入口) > HKC_EMBEDDING_MODEL > FOXCLAW_EMBEDDING_MODEL
+      > all-MiniLM-L6-v2(兜底)。与 HKC init / HMR VectorStore / harness.py 完全一致,
+      保证 get_st_model 缓存 key 命中同一份 instance。"""
+    global _load_attempts
+    name = (model_name
+            or os.environ.get("EMBEDDING_MODEL")
+            or os.environ.get("HKC_EMBEDDING_MODEL")
+            or os.environ.get("FOXCLAW_EMBEDDING_MODEL")
+            or "all-MiniLM-L6-v2").strip()
+    with _lock:
+        if name in _cache:                 # 本服务缓存命中(不重复走 HKC):绝不重复加载
+            return _cache[name]
+        _load_attempts += 1
+        model = None
+        try:
+            # 【P2·share-bge-m3】走 HKC 共享进程缓存 —— 同名 model 全 Foxclaw 只 load 1 次
+            # (HKC 检索 / HMR VectorStore / Harness SemanticDrift 共用同一份 instance)
+            from hkc_search.embedding_backends import get_st_model as _hk_get
+            model = _hk_get(name)
+        except Exception:
+            model = None                   # HKC 不可用 / 缺库 / 离线 → 降级哈希嵌入
+        _cache[name] = model
+        return model
+
+
+def embedding_stats() -> dict:
+    """可观测:当前缓存了哪些模型、发起过多少次加载。用于证明"同名只加载一次"。"""
+    with _lock:
+        return {
+            "cached_models": {n: (m is not None) for n, m in _cache.items()},
+            "distinct_models": len(_cache),
+            "load_attempts": _load_attempts,
+        }

package/python/foxclaw/channels/__init__.py

@@ -0,0 +1,140 @@
+"""
+Foxclaw Channels — 渠道抽象层 (Channel Abstraction)
+
+借鉴 OpenClaw 的渠道架构:适配器模式 + 消息标准化。
+每个 IM 平台(Telegram/Slack/飞书…)一个适配器,封装该平台官方 API;
+入站消息统一标准化成 InboundMessage,出站统一从 OutboundMessage 分派。
+上层(主管 Agent)只跟标准消息打交道,不关心是哪个平台。
+
+接入流程(对称):
+  平台原始消息 → adapter.normalize() → InboundMessage → on_message 回调
+  OutboundMessage → adapter.send() → 平台官方 API
+"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+import time
+
+
+@dataclass
+class InboundMessage:
+    """标准化的入站消息(各平台 normalize 后的统一格式)。"""
+    channel: str                       # 来源渠道(telegram/slack/...)
+    message_id: str
+    text: str
+    sender_id: str                     # 发送者唯一 ID(平台内)
+    sender_name: str = ""
+    conversation_id: str = ""          # 会话 ID(群=群ID,私聊=对方ID)
+    is_group: bool = False
+    timestamp: float = field(default_factory=time.time)
+    raw: dict = field(default_factory=dict)   # 平台原始数据(留底,便于调试)
+
+    def to_dict(self) -> dict:
+        return {"channel": self.channel, "message_id": self.message_id,
+                "text": self.text, "sender_id": self.sender_id,
+                "sender_name": self.sender_name,
+                "conversation_id": self.conversation_id,
+                "is_group": self.is_group, "timestamp": self.timestamp}
+
+
+@dataclass
+class OutboundMessage:
+    """标准化的出站消息(上层产出,各适配器转成平台格式发送)。"""
+    conversation_id: str               # 发往哪个会话
+    text: str
+    reply_to: str = ""                 # 可选:回复某条消息
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass
+class SendResult:
+    ok: bool
+    message_id: str = ""
+    error: str = ""
+
+
+class ChannelAdapter(ABC):
+    """渠道适配器基类。每个平台实现 normalize/send/start。
+
+    设计原则(借鉴 OpenClaw):
+    - 适配器只负责"翻译"(平台格式 ↔ 标准格式)和"收发",不含业务逻辑
+    - 凭证由宿主注入(token 等),适配器不硬编码任何密钥
+    - 入站统一回调 on_message,上层无需关心平台差异
+    """
+
+    # 子类覆盖:渠道名
+    CHANNEL = "base"
+
+    def __init__(self, on_message: Callable[[InboundMessage], None] = None):
+        self.on_message = on_message
+        self._running = False
+        self.last_error = ""       # 最近一次处理错误(便于排查,不抛断轮询)
+
+    @abstractmethod
+    def normalize(self, raw: dict) -> Optional[InboundMessage]:
+        """把平台原始消息转成标准 InboundMessage。非消息事件返回 None。"""
+        ...
+
+    @abstractmethod
+    def send(self, msg: OutboundMessage) -> SendResult:
+        """把标准 OutboundMessage 通过平台官方 API 发出。"""
+        ...
+
+    def handle_raw(self, raw: dict):
+        """收到平台原始消息时调用:标准化 → 触发 on_message 回调。
+
+        全程异常隔离:单条消息处理失败不会抛出(否则会中断整批轮询,
+        且已推进的游标不回滚 → 后续消息全部丢失)。失败记录在 last_error。
+        """
+        try:
+            inbound = self.normalize(raw)
+        except Exception as e:
+            self.last_error = f"normalize 失败: {e}"
+            return None
+        if inbound is None:
+            return None       # 非消息事件(如已读回执),忽略
+        if self.on_message:
+            try:
+                self.on_message(inbound)
+            except Exception as e:
+                # on_message(主管处理)失败:记录但不抛,保证整批轮询不中断
+                self.last_error = f"on_message 失败: {e}"
+        return inbound
+
+    def reply(self, inbound: InboundMessage, text: str) -> SendResult:
+        """便捷回复:回到消息来源的会话。"""
+        return self.send(OutboundMessage(
+            conversation_id=inbound.conversation_id, text=text,
+            reply_to=inbound.message_id))
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+
+class ChannelRegistry:
+    """渠道注册表。管理多个已接入的适配器,统一分派。"""
+
+    def __init__(self):
+        self._adapters: dict[str, ChannelAdapter] = {}
+
+    def register(self, adapter: ChannelAdapter):
+        self._adapters[adapter.CHANNEL] = adapter
+        return adapter
+
+    def get(self, channel: str) -> Optional[ChannelAdapter]:
+        return self._adapters.get(channel)
+
+    def all(self) -> list:
+        return list(self._adapters.values())
+
+    def send(self, channel: str, msg: OutboundMessage) -> SendResult:
+        adapter = self.get(channel)
+        if adapter is None:
+            return SendResult(False, error=f"渠道未接入: {channel}")
+        return adapter.send(msg)
+
+    def status(self) -> dict:
+        return {ch: {"running": a.running, "channel": a.CHANNEL}
+                for ch, a in self._adapters.items()}

package/python/foxclaw/channels/discord.py

@@ -0,0 +1,184 @@
+"""
+Foxclaw Channels — Discord 适配器
+
+用 Discord 官方 API v10。接入模型和前三个又不同(不套同一模子):
+  · 收消息:Gateway WebSocket 长连接 —— Discord 主动推事件(MESSAGE_CREATE 等)
+    - 连接后要 IDENTIFY(带 bot token + intents)
+    - 要按 Discord 指定的间隔发心跳(HEARTBEAT)维持连接
+    - intents 决定能收哪些事件(收消息内容需 MESSAGE_CONTENT intent)
+  · 发消息:REST API POST /channels/{id}/messages(带 Bot token)
+
+凭证:bot token(Discord Developer Portal 创建应用 → Bot),由宿主注入。
+
+说明:完整 Gateway 长连接(心跳/重连/分片)较重,本适配器提供:
+  - send():REST 发送(完整可用)
+  - normalize():把 Discord MESSAGE_CREATE 事件标准化
+  - gateway 连接循环骨架(connect_gateway),宿主可在异步环境跑
+对收消息,推荐宿主用成熟的 discord.py/WebSocket 接 on_message,再喂给 normalize。
+"""
+from __future__ import annotations
+import json
+from typing import Optional
+from . import ChannelAdapter, InboundMessage, OutboundMessage, SendResult
+
+DISCORD_API_BASE = "https://discord.com/api/v10"
+DISCORD_GATEWAY = "wss://gateway.discord.gg/?v=10&encoding=json"
+
+# Gateway opcodes
+OP_DISPATCH = 0
+OP_HEARTBEAT = 1
+OP_IDENTIFY = 2
+OP_HELLO = 10
+OP_HEARTBEAT_ACK = 11
+
+# Intents(收消息内容需要 GUILD_MESSAGES + MESSAGE_CONTENT)
+INTENT_GUILD_MESSAGES = 1 << 9
+INTENT_DIRECT_MESSAGES = 1 << 12
+INTENT_MESSAGE_CONTENT = 1 << 15
+DEFAULT_INTENTS = INTENT_GUILD_MESSAGES | INTENT_DIRECT_MESSAGES | INTENT_MESSAGE_CONTENT
+
+
+class DiscordAdapter(ChannelAdapter):
+    CHANNEL = "discord"
+
+    def __init__(self, bot_token: str, intents: int = DEFAULT_INTENTS,
+                 on_message=None, timeout: float = 30.0):
+        super().__init__(on_message=on_message)
+        self.bot_token = bot_token
+        self.intents = intents
+        self.timeout = timeout
+        self._bot_user_id = ""     # 自己的 bot user id(用于忽略自己的消息)
+
+    def _headers(self) -> dict:
+        return {"Authorization": f"Bot {self.bot_token}",
+                "Content-Type": "application/json",
+                "User-Agent": "Foxclaw (https://github.com, 1.0)"}
+
+    # ── 入站:标准化 Gateway MESSAGE_CREATE 事件 ───────────
+    def normalize(self, raw: dict) -> Optional[InboundMessage]:
+        """Discord Gateway 事件 → 标准 InboundMessage。
+
+        raw 可以是完整 Gateway 帧({op,t,d})或直接是 MESSAGE_CREATE 的 data。
+        """
+        # 取出 data 部分
+        if "op" in raw:
+            if raw.get("op") != OP_DISPATCH or raw.get("t") != "MESSAGE_CREATE":
+                return None
+            data = raw.get("d", {})
+        else:
+            data = raw
+        if not data:
+            return None
+        author = data.get("author", {})
+        # 忽略机器人消息(含自己),避免自循环
+        if author.get("bot"):
+            return None
+        if self._bot_user_id and str(author.get("id")) == self._bot_user_id:
+            return None
+        text = data.get("content", "")
+        if not text:
+            return None       # 非文本(纯附件/嵌入)暂忽略
+        # 有 guild_id = 服务器频道(群),无 = 私信
+        is_group = bool(data.get("guild_id"))
+        return InboundMessage(
+            channel=self.CHANNEL,
+            message_id=str(data.get("id", "")),
+            text=text,
+            sender_id=str(author.get("id", "")),
+            sender_name=author.get("username", ""),
+            conversation_id=str(data.get("channel_id", "")),
+            is_group=is_group,
+            raw=data)
+
+    # ── 出站:REST 发送 ────────────────────────────────────
+    def send(self, msg: OutboundMessage) -> SendResult:
+        """POST /channels/{channel_id}/messages 发文本。"""
+        try:
+            import httpx
+        except ImportError:
+            return SendResult(False, error="缺少 httpx 依赖")
+        if not self.bot_token:
+            return SendResult(False, error="未配置 Discord bot token")
+        payload = {"content": msg.text}
+        if msg.reply_to:
+            payload["message_reference"] = {"message_id": msg.reply_to}
+        url = f"{DISCORD_API_BASE}/channels/{msg.conversation_id}/messages"
+        try:
+            with httpx.Client() as client:
+                resp = client.post(url, json=payload, headers=self._headers(),
+                                   timeout=self.timeout)
+        except Exception as e:
+            return SendResult(False, error=f"Discord 发送失败: {e}")
+        if resp.status_code == 429:
+            return SendResult(False, error="Discord 限流(429),请降低发送频率")
+        if resp.status_code >= 400:
+            return SendResult(False, error=f"Discord API HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        return SendResult(True, message_id=str(data.get("id", "")))
+
+    def verify_token(self) -> SendResult:
+        """GET /users/@me 验证 bot token,并记录自己的 user id。"""
+        try:
+            import httpx
+            with httpx.Client() as client:
+                resp = client.get(f"{DISCORD_API_BASE}/users/@me",
+                                  headers=self._headers(), timeout=self.timeout)
+            if resp.status_code == 200:
+                me = resp.json()
+                self._bot_user_id = str(me.get("id", ""))
+                return SendResult(True, message_id=me.get("username", ""))
+            return SendResult(False, error=f"token 无效 (HTTP {resp.status_code})")
+        except Exception as e:
+            return SendResult(False, error=str(e))
+
+    def build_identify(self) -> dict:
+        """构造 Gateway IDENTIFY 帧(连接后发送)。"""
+        return {
+            "op": OP_IDENTIFY,
+            "d": {
+                "token": self.bot_token,
+                "intents": self.intents,
+                "properties": {"os": "linux", "browser": "foxclaw", "device": "foxclaw"},
+            },
+        }
+
+    async def connect_gateway(self):
+        """Gateway WebSocket 接收循环(异步)。需要 websockets 库。
+
+        实现 HELLO→IDENTIFY→心跳→DISPATCH 的最小闭环。生产可换 discord.py。
+        """
+        try:
+            import websockets
+        except ImportError:
+            raise RuntimeError("需要 websockets 库:pip install websockets")
+        import asyncio
+        async with websockets.connect(DISCORD_GATEWAY, max_size=None) as ws:
+            # 1. HELLO:拿心跳间隔
+            hello = json.loads(await ws.recv())
+            heartbeat_ms = hello["d"]["heartbeat_interval"]
+            # 2. IDENTIFY
+            await ws.send(json.dumps(self.build_identify()))
+            self._running = True
+
+            async def heartbeat():
+                while self._running:
+                    await asyncio.sleep(heartbeat_ms / 1000)
+                    try:
+                        await ws.send(json.dumps({"op": OP_HEARTBEAT, "d": None}))
+                    except Exception:
+                        break
+
+            hb_task = asyncio.create_task(heartbeat())
+            try:
+                async for raw in ws:
+                    frame = json.loads(raw)
+                    if frame.get("op") == OP_DISPATCH and frame.get("t") == "MESSAGE_CREATE":
+                        inbound = self.normalize(frame)
+                        if inbound and self.on_message:
+                            self.on_message(inbound)
+            finally:
+                self._running = False
+                hb_task.cancel()