codebee 0.1.76 → 0.1.77

package/app/core/publish/qimao.py

@@ -1,176 +1,176 @@
-# -*- coding: utf-8 -*-
-"""七猫作者后台的发布流程定义（默认表：选择器为合理推测，待实测校准）。
-
-校准方式同番茄：data/publish/flows-qimao.json 覆盖 + 「探测表单」dump。
-URL 依据：tools/qimao_bookmeta.json 的 source 记录 2026-09-17 登录态实抓
-zuozhe.qimao.com/api/pc/v1/book/book-option——作者后台 PC 端在 zuozhe.qimao.com。
-
-七猫建书表单结构（同次实抓）：频道级联（男/女生 → 一级 → 二级）+ 四组标签
-（风格/角色/情节/背景，每组 1-3 个）+ 文本字段。
-"""
-from __future__ import annotations
-
-CONFIG = {
-    "id": "qimao",
-    "label": "七猫",
-    "home": "https://zuozhe.qimao.com/",
-    # 作品管理页：建书入口（「新建小说」按钮所在）；建书向导第二步表单在其下
-    "book_manage": "https://zuozhe.qimao.com/front/book-manage",
-    # 编辑器顶栏明示「正文字数最少 1000 字」——不足时「立即发布」被静默拦截
-    "min_chapter_chars": 1000,
-    "login_url_marks": ["login", "signin", "passport", "sso"],
-    # 章节管理页计数（2026-09-28 实机校准）：Element UI 表格，.el-table__row
-    # 只中数据行（表头在独立的 header-wrapper 表里），与发章流程的等待选择器同源
-    "count_rows_js":
-        "()=>[...document.querySelectorAll('.el-table__row')]"
-        ".map(tr => tr.innerText.replace(/\\s+/g, ' ').trim()).filter(Boolean)",
-}
-
-CREATE_BOOK = [
-    {"do": "navigate", "url": "{home}"},
-    {"do": "url_any", "any": ["qimao.com"]},
-    {"do": "click_text", "text": "创建作品", "contains": True, "scope": "button,a,[role=button],span"},
-    {"do": "probe", "note": "建书表单"},
-    {"do": "wait", "sel": "input[placeholder*='作品'],input[placeholder*='书名'],input[maxlength]", "timeout": 10},
-    {"do": "fill", "sel": "input[placeholder*='作品'],input[placeholder*='书名']", "key": "title"},
-    {"do": "fill", "sel": "textarea[placeholder*='简介'],textarea", "key": "summary"},
-    {"do": "fill", "sel": "input[placeholder*='主角']", "key": "protagonist"},
-    # 频道级联：目标读者 → 一级分类 → 二级分类（值来自 bookmeta 的级联字段）
-    {"do": "click_text", "text": "{target_reader}", "contains": False,
-     "scope": "[class*=channel] label,label,span"},
-    {"do": "click_text", "text": "{category_main}", "contains": False,
-     "scope": "[class*=categor] li,option,span"},
-    {"do": "click_text", "text": "{category_sub}", "contains": False,
-     "scope": "[class*=categor] li,option,span"},
-    {"do": "shot", "name": "create-book-filled"},
-    {"do": "submit", "sel": "button[class*=submit],button[class*=primary],button[class*=confirm]"},
-]
-
-UPLOAD_CHAPTER = [
-    {"do": "navigate", "url": "{home}"},
-    {"do": "url_any", "any": ["qimao.com"]},
-    {"do": "click_text", "text": "{book_name}", "contains": True,
-     "scope": "a,span,div[class*=title],div[class*=book]"},
-    {"do": "click_text", "text": "新建章节", "contains": True, "scope": "button,a,[role=button],span"},
-    {"do": "probe", "note": "章节编辑器"},
-    {"do": "fill", "sel": "input[placeholder*='章节'],input[placeholder*='标题'],input[placeholder*='章名']", "key": "chapter_title"},
-    {"do": "wait", "sel": "[contenteditable=true],textarea[class*=content],iframe", "timeout": 10},
-    {"do": "fill", "sel": "[contenteditable=true],textarea[class*=content]", "key": "chapter_body"},
-    {"do": "shot", "name": "chapter-filled"},
-    {"do": "submit", "sel": "button[class*=publish],button[class*=submit]"},
-]
-
-CHECK_LOGIN = [
-    {"do": "navigate", "url": "{home}"},
-    {"do": "url_any", "any": ["qimao.com"]},
-]
-
-PROBE_FORM = [
-    {"do": "navigate", "url": "{home}"},
-    {"do": "url_any", "any": ["qimao.com"]},
-    {"do": "click_text", "text": "创建作品", "contains": True, "scope": "button,a,[role=button],span"},
-    {"do": "probe", "note": "建书表单"},
-]
-
-FLOWS = {"create_book": CREATE_BOOK, "upload_chapter": UPLOAD_CHAPTER,
-         "check_login": CHECK_LOGIN, "probe_form": PROBE_FORM}
-
-
-# 标签字段名 → 弹层左侧组显示名（tags 步骤按组切换后点选；每组必选 1-3 个）
-TAG_GROUP_LABELS = {"tags_style": "风格", "tags_role": "角色",
-                    "tags_plot": "情节", "tags_bg": "背景"}
-
-
-def values_create_book(meta):
-    from .. import bookmeta_catalog as cat
-    target_reader = (meta.get("target_reader") or "").strip()
-    category_main = (meta.get("category_main") or "").strip()
-    category_sub = (meta.get("category_sub") or "").strip()
-    # 旧数据兜底：二级有值但一级空/与二级不自洽（如女生专属的「现实故事」
-    # 配了男生频道）会让一级 click_text 静默跳过、死在流程中段——按官方
-    # 目录跨频道反查对齐，频道与一级跟着二级走
-    if category_sub and not (category_main and
-                             category_sub in (cat.QIMAO_CATS.get(target_reader)
-                                              or {}).get(category_main, [])):
-        loc = cat.qimao_locate_sub(category_sub)
-        if loc:
-            target_reader, category_main = loc
-        else:
-            category_sub = ""
-    return {
-        "title": (meta.get("book_name") or "").strip(),
-        "summary": (meta.get("summary") or "").strip(),
-        "protagonist": (meta.get("protagonist_1") or "").strip(),
-        "target_reader": target_reader,
-        "category_main": category_main,
-        "category_sub": category_sub,
-        "status": (meta.get("status") or "连载中").strip(),
-    }
-
-
-def tag_groups(meta):
-    out = []
-    for key in ("tags_style", "tags_role", "tags_plot", "tags_bg"):
-        v = meta.get(key)
-        if isinstance(v, list) and v:
-            out.append((key, [str(x) for x in v]))
-    return out
-
-
-def chapter_manage_url(book):
-    """章节管理页（上线验证用）：有 book_id 直达，否则回作品管理页。"""
-    bid = str((book or {}).get("book_id") or "")
-    if bid:                                   # 实测 .../front/book-manage/manage?id=
-        return CONFIG["book_manage"] + "/manage?id=" + bid
-    return CONFIG["book_manage"]
-
-
-def resolve_book_id(page, book):
-    """登记缺 book_id 时按书名在作品管理页找回：点书名卡进详情，从 URL 提取。
-
-    与番茄同款对账通道（fanqie.resolve_book_id）；找不回返回空串不拦死。"""
-    import re
-    import time
-    from . import flow as _flow
-    title = str((book or {}).get("title") or "").strip()
-    if not title:
-        return ""
-    try:
-        page.navigate(CONFIG["book_manage"], timeout=30)
-    except Exception:
-        return ""
-    r = None
-    for _try in range(6):                   # 列表慢渲染
-        r = page.call(_flow._click_match_js(), [title], 300)
-        if (r or {}).get("ok"):
-            break
-        time.sleep(1.0)
-    if not (r or {}).get("ok"):
-        return ""
-    time.sleep(2.5)                         # 跳转收尾
-    m = re.search(r"manage\?id=(\d+)|draft\?id=(\d+)|information\?id=(\d+)",
-                  str(page.url() or ""))
-    if not m:
-        return ""
-    return m.group(1) or m.group(2) or m.group(3) or ""
-
-
-def draft_url(book):
-    """草稿箱页（发章真发布链中转站）。"""
-    bid = str((book or {}).get("book_id") or "")
-    if bid:
-        return CONFIG["book_manage"] + "/draft?id=" + bid
-    return CONFIG["book_manage"]
-
-
-def editor_url(book):
-    """章节编辑器直达（绕开会开新 tab 的「上传章节」点击）。
-
-    缺 title 参数会被平台重定向回首页（真机实测），必须带上。"""
-    bid = str((book or {}).get("book_id") or "")
-    title = str((book or {}).get("title") or "")
-    if bid:
-        from urllib.parse import quote
-        return (CONFIG["book_manage"].rsplit("/", 1)[0]
-                + "/book-upload?id=" + bid + "&title=" + quote(title))
-    return CONFIG["book_manage"]
+# -*- coding: utf-8 -*-
+"""七猫作者后台的发布流程定义（默认表：选择器为合理推测，待实测校准）。
+
+校准方式同番茄：data/publish/flows-qimao.json 覆盖 + 「探测表单」dump。
+URL 依据：tools/qimao_bookmeta.json 的 source 记录 2026-09-17 登录态实抓
+zuozhe.qimao.com/api/pc/v1/book/book-option——作者后台 PC 端在 zuozhe.qimao.com。
+
+七猫建书表单结构（同次实抓）：频道级联（男/女生 → 一级 → 二级）+ 四组标签
+（风格/角色/情节/背景，每组 1-3 个）+ 文本字段。
+"""
+from __future__ import annotations
+
+CONFIG = {
+    "id": "qimao",
+    "label": "七猫",
+    "home": "https://zuozhe.qimao.com/",
+    # 作品管理页：建书入口（「新建小说」按钮所在）；建书向导第二步表单在其下
+    "book_manage": "https://zuozhe.qimao.com/front/book-manage",
+    # 编辑器顶栏明示「正文字数最少 1000 字」——不足时「立即发布」被静默拦截
+    "min_chapter_chars": 1000,
+    "login_url_marks": ["login", "signin", "passport", "sso"],
+    # 章节管理页计数（2026-09-28 实机校准）：Element UI 表格，.el-table__row
+    # 只中数据行（表头在独立的 header-wrapper 表里），与发章流程的等待选择器同源
+    "count_rows_js":
+        "()=>[...document.querySelectorAll('.el-table__row')]"
+        ".map(tr => tr.innerText.replace(/\\s+/g, ' ').trim()).filter(Boolean)",
+}
+
+CREATE_BOOK = [
+    {"do": "navigate", "url": "{home}"},
+    {"do": "url_any", "any": ["qimao.com"]},
+    {"do": "click_text", "text": "创建作品", "contains": True, "scope": "button,a,[role=button],span"},
+    {"do": "probe", "note": "建书表单"},
+    {"do": "wait", "sel": "input[placeholder*='作品'],input[placeholder*='书名'],input[maxlength]", "timeout": 10},
+    {"do": "fill", "sel": "input[placeholder*='作品'],input[placeholder*='书名']", "key": "title"},
+    {"do": "fill", "sel": "textarea[placeholder*='简介'],textarea", "key": "summary"},
+    {"do": "fill", "sel": "input[placeholder*='主角']", "key": "protagonist"},
+    # 频道级联：目标读者 → 一级分类 → 二级分类（值来自 bookmeta 的级联字段）
+    {"do": "click_text", "text": "{target_reader}", "contains": False,
+     "scope": "[class*=channel] label,label,span"},
+    {"do": "click_text", "text": "{category_main}", "contains": False,
+     "scope": "[class*=categor] li,option,span"},
+    {"do": "click_text", "text": "{category_sub}", "contains": False,
+     "scope": "[class*=categor] li,option,span"},
+    {"do": "shot", "name": "create-book-filled"},
+    {"do": "submit", "sel": "button[class*=submit],button[class*=primary],button[class*=confirm]"},
+]
+
+UPLOAD_CHAPTER = [
+    {"do": "navigate", "url": "{home}"},
+    {"do": "url_any", "any": ["qimao.com"]},
+    {"do": "click_text", "text": "{book_name}", "contains": True,
+     "scope": "a,span,div[class*=title],div[class*=book]"},
+    {"do": "click_text", "text": "新建章节", "contains": True, "scope": "button,a,[role=button],span"},
+    {"do": "probe", "note": "章节编辑器"},
+    {"do": "fill", "sel": "input[placeholder*='章节'],input[placeholder*='标题'],input[placeholder*='章名']", "key": "chapter_title"},
+    {"do": "wait", "sel": "[contenteditable=true],textarea[class*=content],iframe", "timeout": 10},
+    {"do": "fill", "sel": "[contenteditable=true],textarea[class*=content]", "key": "chapter_body"},
+    {"do": "shot", "name": "chapter-filled"},
+    {"do": "submit", "sel": "button[class*=publish],button[class*=submit]"},
+]
+
+CHECK_LOGIN = [
+    {"do": "navigate", "url": "{home}"},
+    {"do": "url_any", "any": ["qimao.com"]},
+]
+
+PROBE_FORM = [
+    {"do": "navigate", "url": "{home}"},
+    {"do": "url_any", "any": ["qimao.com"]},
+    {"do": "click_text", "text": "创建作品", "contains": True, "scope": "button,a,[role=button],span"},
+    {"do": "probe", "note": "建书表单"},
+]
+
+FLOWS = {"create_book": CREATE_BOOK, "upload_chapter": UPLOAD_CHAPTER,
+         "check_login": CHECK_LOGIN, "probe_form": PROBE_FORM}
+
+
+# 标签字段名 → 弹层左侧组显示名（tags 步骤按组切换后点选；每组必选 1-3 个）
+TAG_GROUP_LABELS = {"tags_style": "风格", "tags_role": "角色",
+                    "tags_plot": "情节", "tags_bg": "背景"}
+
+
+def values_create_book(meta):
+    from .. import bookmeta_catalog as cat
+    target_reader = (meta.get("target_reader") or "").strip()
+    category_main = (meta.get("category_main") or "").strip()
+    category_sub = (meta.get("category_sub") or "").strip()
+    # 旧数据兜底：二级有值但一级空/与二级不自洽（如女生专属的「现实故事」
+    # 配了男生频道）会让一级 click_text 静默跳过、死在流程中段——按官方
+    # 目录跨频道反查对齐，频道与一级跟着二级走
+    if category_sub and not (category_main and
+                             category_sub in (cat.QIMAO_CATS.get(target_reader)
+                                              or {}).get(category_main, [])):
+        loc = cat.qimao_locate_sub(category_sub)
+        if loc:
+            target_reader, category_main = loc
+        else:
+            category_sub = ""
+    return {
+        "title": (meta.get("book_name") or "").strip(),
+        "summary": (meta.get("summary") or "").strip(),
+        "protagonist": (meta.get("protagonist_1") or "").strip(),
+        "target_reader": target_reader,
+        "category_main": category_main,
+        "category_sub": category_sub,
+        "status": (meta.get("status") or "连载中").strip(),
+    }
+
+
+def tag_groups(meta):
+    out = []
+    for key in ("tags_style", "tags_role", "tags_plot", "tags_bg"):
+        v = meta.get(key)
+        if isinstance(v, list) and v:
+            out.append((key, [str(x) for x in v]))
+    return out
+
+
+def chapter_manage_url(book):
+    """章节管理页（上线验证用）：有 book_id 直达，否则回作品管理页。"""
+    bid = str((book or {}).get("book_id") or "")
+    if bid:                                   # 实测 .../front/book-manage/manage?id=
+        return CONFIG["book_manage"] + "/manage?id=" + bid
+    return CONFIG["book_manage"]
+
+
+def resolve_book_id(page, book):
+    """登记缺 book_id 时按书名在作品管理页找回：点书名卡进详情，从 URL 提取。
+
+    与番茄同款对账通道（fanqie.resolve_book_id）；找不回返回空串不拦死。"""
+    import re
+    import time
+    from . import flow as _flow
+    title = str((book or {}).get("title") or "").strip()
+    if not title:
+        return ""
+    try:
+        page.navigate(CONFIG["book_manage"], timeout=30)
+    except Exception:
+        return ""
+    r = None
+    for _try in range(6):                   # 列表慢渲染
+        r = page.call(_flow._click_match_js(), [title], 300)
+        if (r or {}).get("ok"):
+            break
+        time.sleep(1.0)
+    if not (r or {}).get("ok"):
+        return ""
+    time.sleep(2.5)                         # 跳转收尾
+    m = re.search(r"manage\?id=(\d+)|draft\?id=(\d+)|information\?id=(\d+)",
+                  str(page.url() or ""))
+    if not m:
+        return ""
+    return m.group(1) or m.group(2) or m.group(3) or ""
+
+
+def draft_url(book):
+    """草稿箱页（发章真发布链中转站）。"""
+    bid = str((book or {}).get("book_id") or "")
+    if bid:
+        return CONFIG["book_manage"] + "/draft?id=" + bid
+    return CONFIG["book_manage"]
+
+
+def editor_url(book):
+    """章节编辑器直达（绕开会开新 tab 的「上传章节」点击）。
+
+    缺 title 参数会被平台重定向回首页（真机实测），必须带上。"""
+    bid = str((book or {}).get("book_id") or "")
+    title = str((book or {}).get("title") or "")
+    if bid:
+        from urllib.parse import quote
+        return (CONFIG["book_manage"].rsplit("/", 1)[0]
+                + "/book-upload?id=" + bid + "&title=" + quote(title))
+    return CONFIG["book_manage"]

package/app/core/publish/ws.py

@@ -1,139 +1,139 @@
-# -*- coding: utf-8 -*-
-"""最小 WebSocket 客户端（RFC 6455 子集）——CDP 驱动专用。
-
-只实现客户端角色：HTTP Upgrade 握手 → 文本帧收发。CDP 的用法非常受限，
-所以刻意不做完整协议：
-- 客户端只发文本帧（JSON 命令），服务端回文本帧（响应/事件）+ 偶尔 ping；
-- 截图等大响应可能分片（continuation 帧），必须重组；
-- 不协商 permessage-deflate 等扩展，服务端帧按规范不带掩码（仍兼容读取）。
-
-不引第三方 websocket 库：32 位 Python + npm 分发是零依赖策略，
-标准库 socket 手写两百行即可覆盖上述用法，行为对着真 Edge 验证。
-"""
-from __future__ import annotations
-
-import base64
-import os
-import socket
-import struct
-
-OP_CONT, OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG = 0x0, 0x1, 0x2, 0x8, 0x9, 0xA
-
-
-class WebSocketError(Exception):
-    """连接层错误（握手失败/对端关闭/帧损坏）。业务超时抛 socket.timeout。"""
-
-
-class MiniWS:
-    """一次性连接：不做重连（CDP 页面会话由上层 browser.py 决定重开）。"""
-
-    def __init__(self, host, port, path, timeout=30.0):
-        self._timeout = timeout
-        self._sock = socket.create_connection((host, int(port)), timeout=timeout)
-        self._buf = b""
-        self._handshake(host, int(port), path)
-
-    # ------------------------------------------------------------ 握手
-    def _handshake(self, host, port, path):
-        key = base64.b64encode(os.urandom(16)).decode("ascii")
-        req = ("GET %s HTTP/1.1\r\nHost: %s:%d\r\nUpgrade: websocket\r\n"
-               "Connection: Upgrade\r\nSec-WebSocket-Key: %s\r\n"
-               "Sec-WebSocket-Version: 13\r\n\r\n") % (path, host, port, key)
-        self._sock.sendall(req.encode("ascii"))
-        while b"\r\n\r\n" not in self._buf:
-            chunk = self._sock.recv(4096)
-            if not chunk:
-                raise WebSocketError("握手失败：连接被关闭")
-            self._buf += chunk
-        head, _, self._buf = self._buf.partition(b"\r\n\r\n")
-        status = head.split(b"\r\n", 1)[0].decode("latin-1", "replace")
-        if " 101 " not in status and not status.endswith(" 101"):
-            raise WebSocketError("握手失败：%s" % status[:120])
-
-    # ------------------------------------------------------------ 发送
-    def _send_frame(self, opcode, payload):
-        mask = os.urandom(4)                       # 客户端→服务端必须掩码
-        n = len(payload)
-        header = bytearray([0x80 | opcode])        # FIN + opcode
-        if n < 126:
-            header.append(0x80 | n)
-        elif n < 65536:
-            header.append(0x80 | 126)
-            header += struct.pack(">H", n)
-        else:
-            header.append(0x80 | 127)
-            header += struct.pack(">Q", n)
-        header += mask
-        masked = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
-        self._sock.sendall(bytes(header) + masked)
-
-    def send_text(self, text):
-        self._send_frame(OP_TEXT, text.encode("utf-8"))
-
-    # ------------------------------------------------------------ 接收
-    def _recv_exact(self, n):
-        while len(self._buf) < n:
-            chunk = self._sock.recv(max(4096, n - len(self._buf)))
-            if not chunk:
-                raise WebSocketError("连接被关闭")
-            self._buf += chunk
-        out, self._buf = self._buf[:n], self._buf[n:]
-        return out
-
-    def recv_message(self, timeout=None):
-        """收一条完整消息：自动应答 ping、重组分片。
-
-        返回 str（文本帧）或 bytes（二进制帧）。超时抛 socket.timeout，
-        对端关闭抛 WebSocketError。"""
-        if timeout is not None:
-            self._sock.settimeout(timeout)
-        elif self._timeout:
-            self._sock.settimeout(self._timeout)
-        opcode_msg = None
-        payload = bytearray()
-        while True:
-            b1, b2 = self._recv_exact(2)
-            fin, opcode, masked = b1 & 0x80, b1 & 0x0F, b2 & 0x80
-            n = b2 & 0x7F
-            if n == 126:
-                (n,) = struct.unpack(">H", self._recv_exact(2))
-            elif n == 127:
-                (n,) = struct.unpack(">Q", self._recv_exact(8))
-            data = self._recv_exact(n)
-            if masked:
-                mkey = self._recv_exact(4)
-                data = bytes(b ^ mkey[i % 4] for i, b in enumerate(data))
-            if opcode == OP_CLOSE:
-                raise WebSocketError("对端发送关闭帧")
-            if opcode == OP_PING:
-                self._send_frame(OP_PONG, data)
-                continue
-            if opcode == OP_PONG:
-                continue
-            if opcode in (OP_TEXT, OP_BINARY):
-                opcode_msg, payload = opcode, bytearray(data)
-            elif opcode == OP_CONT:
-                if opcode_msg is None:
-                    raise WebSocketError("收到无起始帧的续帧")
-                payload += data
-            else:
-                raise WebSocketError("未知 opcode：%d" % opcode)
-            if fin:
-                return bytes(payload) if opcode_msg == OP_BINARY else \
-                    payload.decode("utf-8", "replace")
-
-    def close(self):
-        try:
-            self._send_frame(OP_CLOSE, b"")
-        except Exception:
-            pass
-        try:
-            self._sock.close()
-        except Exception:
-            pass
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *exc):
-        self.close()
+# -*- coding: utf-8 -*-
+"""最小 WebSocket 客户端（RFC 6455 子集）——CDP 驱动专用。
+
+只实现客户端角色：HTTP Upgrade 握手 → 文本帧收发。CDP 的用法非常受限，
+所以刻意不做完整协议：
+- 客户端只发文本帧（JSON 命令），服务端回文本帧（响应/事件）+ 偶尔 ping；
+- 截图等大响应可能分片（continuation 帧），必须重组；
+- 不协商 permessage-deflate 等扩展，服务端帧按规范不带掩码（仍兼容读取）。
+
+不引第三方 websocket 库：32 位 Python + npm 分发是零依赖策略，
+标准库 socket 手写两百行即可覆盖上述用法，行为对着真 Edge 验证。
+"""
+from __future__ import annotations
+
+import base64
+import os
+import socket
+import struct
+
+OP_CONT, OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG = 0x0, 0x1, 0x2, 0x8, 0x9, 0xA
+
+
+class WebSocketError(Exception):
+    """连接层错误（握手失败/对端关闭/帧损坏）。业务超时抛 socket.timeout。"""
+
+
+class MiniWS:
+    """一次性连接：不做重连（CDP 页面会话由上层 browser.py 决定重开）。"""
+
+    def __init__(self, host, port, path, timeout=30.0):
+        self._timeout = timeout
+        self._sock = socket.create_connection((host, int(port)), timeout=timeout)
+        self._buf = b""
+        self._handshake(host, int(port), path)
+
+    # ------------------------------------------------------------ 握手
+    def _handshake(self, host, port, path):
+        key = base64.b64encode(os.urandom(16)).decode("ascii")
+        req = ("GET %s HTTP/1.1\r\nHost: %s:%d\r\nUpgrade: websocket\r\n"
+               "Connection: Upgrade\r\nSec-WebSocket-Key: %s\r\n"
+               "Sec-WebSocket-Version: 13\r\n\r\n") % (path, host, port, key)
+        self._sock.sendall(req.encode("ascii"))
+        while b"\r\n\r\n" not in self._buf:
+            chunk = self._sock.recv(4096)
+            if not chunk:
+                raise WebSocketError("握手失败：连接被关闭")
+            self._buf += chunk
+        head, _, self._buf = self._buf.partition(b"\r\n\r\n")
+        status = head.split(b"\r\n", 1)[0].decode("latin-1", "replace")
+        if " 101 " not in status and not status.endswith(" 101"):
+            raise WebSocketError("握手失败：%s" % status[:120])
+
+    # ------------------------------------------------------------ 发送
+    def _send_frame(self, opcode, payload):
+        mask = os.urandom(4)                       # 客户端→服务端必须掩码
+        n = len(payload)
+        header = bytearray([0x80 | opcode])        # FIN + opcode
+        if n < 126:
+            header.append(0x80 | n)
+        elif n < 65536:
+            header.append(0x80 | 126)
+            header += struct.pack(">H", n)
+        else:
+            header.append(0x80 | 127)
+            header += struct.pack(">Q", n)
+        header += mask
+        masked = bytes(b ^ mask[i % 4] for i, b in enumerate(payload))
+        self._sock.sendall(bytes(header) + masked)
+
+    def send_text(self, text):
+        self._send_frame(OP_TEXT, text.encode("utf-8"))
+
+    # ------------------------------------------------------------ 接收
+    def _recv_exact(self, n):
+        while len(self._buf) < n:
+            chunk = self._sock.recv(max(4096, n - len(self._buf)))
+            if not chunk:
+                raise WebSocketError("连接被关闭")
+            self._buf += chunk
+        out, self._buf = self._buf[:n], self._buf[n:]
+        return out
+
+    def recv_message(self, timeout=None):
+        """收一条完整消息：自动应答 ping、重组分片。
+
+        返回 str（文本帧）或 bytes（二进制帧）。超时抛 socket.timeout，
+        对端关闭抛 WebSocketError。"""
+        if timeout is not None:
+            self._sock.settimeout(timeout)
+        elif self._timeout:
+            self._sock.settimeout(self._timeout)
+        opcode_msg = None
+        payload = bytearray()
+        while True:
+            b1, b2 = self._recv_exact(2)
+            fin, opcode, masked = b1 & 0x80, b1 & 0x0F, b2 & 0x80
+            n = b2 & 0x7F
+            if n == 126:
+                (n,) = struct.unpack(">H", self._recv_exact(2))
+            elif n == 127:
+                (n,) = struct.unpack(">Q", self._recv_exact(8))
+            data = self._recv_exact(n)
+            if masked:
+                mkey = self._recv_exact(4)
+                data = bytes(b ^ mkey[i % 4] for i, b in enumerate(data))
+            if opcode == OP_CLOSE:
+                raise WebSocketError("对端发送关闭帧")
+            if opcode == OP_PING:
+                self._send_frame(OP_PONG, data)
+                continue
+            if opcode == OP_PONG:
+                continue
+            if opcode in (OP_TEXT, OP_BINARY):
+                opcode_msg, payload = opcode, bytearray(data)
+            elif opcode == OP_CONT:
+                if opcode_msg is None:
+                    raise WebSocketError("收到无起始帧的续帧")
+                payload += data
+            else:
+                raise WebSocketError("未知 opcode：%d" % opcode)
+            if fin:
+                return bytes(payload) if opcode_msg == OP_BINARY else \
+                    payload.decode("utf-8", "replace")
+
+    def close(self):
+        try:
+            self._send_frame(OP_CLOSE, b"")
+        except Exception:
+            pass
+        try:
+            self._sock.close()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()