codebee 0.1.10 → 0.1.11

package/app/core/publish/manager.py

@@ -0,0 +1,427 @@
+# -*- coding: utf-8 -*-
+"""发布管理：平台会话（attach-or-launch）、登录状态机、建书/发章后台线程。
+
+状态机（data/publish/state.json 的 platforms.<id>.status）：
+  none           从未连接
+  waiting_login  浏览器已开等用户扫码（connect 后，轮询 15 分钟）
+  connected      登录检测通过
+  busy           发布动作进行中（结束回 connected / error）
+  error          最后一次动作失败（error 字段带人话原因，可重试）
+
+浏览器生命周期：每平台一个持久化 profile（data/publish/profiles/<id>），
+登录态落在 profile 里。服务重启后按 state.json 记住的调试端口 attach
+旧实例；实例已死才重新 launch——用户登录一次，之后无感。
+
+与 bookmeta.generate_async 同款线程纪律：动作起后台线程即返回，前端靠
+view()（SSE/轮询）看进度；线程内任何异常都落终态，绝不悬挂。
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+
+from .. import paths
+from . import fanqie, flow, ledger, qimao
+from .browser import Browser, BrowserError, Page
+
+PLATFORMS = {"fanqie": fanqie, "qimao": qimao}
+LOGIN_WAIT_S = 15 * 60          # 扫码等待窗口
+STATUS_FILE = paths.PUBLISH_DIR / "state.json"
+
+LOCK = threading.RLock()
+_state = {"platforms": {}}      # {plat: {status, port, at, error, last_login, last_action}}
+_browsers = {}                  # plat → Browser（进程内缓存，alive 校验兜底）
+
+
+# ---------------------------------------------------------------- 状态
+def _load():
+    global _state
+    try:
+        d = json.loads(STATUS_FILE.read_text(encoding="utf-8"))
+        if isinstance(d, dict) and isinstance(d.get("platforms"), dict):
+            _state = d
+            return
+    except Exception:
+        pass
+    _state = {"platforms": {}}
+
+
+def _save():
+    with LOCK:
+        try:
+            paths.PUBLISH_DIR.mkdir(parents=True, exist_ok=True)
+            tmp = STATUS_FILE.with_suffix(".tmp")
+            tmp.write_text(json.dumps(_state, ensure_ascii=False, indent=1),
+                           encoding="utf-8")
+            tmp.replace(STATUS_FILE)
+        except Exception:
+            pass
+
+
+def _set(plat, **kv):
+    with LOCK:
+        ent = _state["platforms"].setdefault(plat, {})
+        ent.update(kv)
+        ent["at"] = time.strftime("%Y-%m-%d %H:%M:%S")
+        _save()
+
+
+def _st(plat):
+    return (_state.get("platforms") or {}).get(plat) or {}
+
+
+def view():
+    """前端状态视图：平台状态 + 是否找到浏览器 + 作品登记。"""
+    from .browser import find_browser
+    out = {}
+    for pid, mod in PLATFORMS.items():
+        s = _st(pid)
+        out[pid] = {"label": mod.CONFIG["label"], "status": s.get("status") or "none",
+                    "at": s.get("at") or "", "error": s.get("error") or "",
+                    "last_action": s.get("last_action") or "",
+                    "profile": str(paths.PUBLISH_DIR / "profiles" / pid)}
+    return {"platforms": out, "browser_found": bool(find_browser())}
+
+
+def recover_orphans():
+    """启动收尸：waiting_login / busy 的线程随进程重启死掉，统一改判 error。"""
+    _load()
+    n = 0
+    for plat in PLATFORMS:
+        if _st(plat).get("status") in ("waiting_login", "busy"):
+            _set(plat, status="error", error="上次操作随服务重启中断，请重试")
+            n += 1
+    return n
+
+
+# ---------------------------------------------------------------- 浏览器会话
+def _profile_dir(plat):
+    return paths.PUBLISH_DIR / "profiles" / plat
+
+
+def _ensure_browser(plat):
+    """attach-or-launch：进程内缓存 → 记住的端口 → 全新 launch。"""
+    with LOCK:
+        b = _browsers.get(plat)
+        if b and b.alive():
+            return b
+        port = _st(plat).get("port") or 0
+        if port:
+            try:
+                b = Browser.attach(int(port))
+                _browsers[plat] = b
+                return b
+            except BrowserError:
+                pass                        # 旧实例已死：走 launch
+        b = Browser(_profile_dir(plat))     # 有窗口：用户要扫码/人工确认
+        _browsers[plat] = b
+        _set(plat, port=b.port)
+        return b
+
+
+def _open_page(plat):
+    b = _ensure_browser(plat)
+    return b, b.first_page(create=True)
+
+
+def _check_login(plat, page):
+    """打开后台首页看 URL 是否被踢到登录页。返回 (ok, 当前url)。
+
+    导航失败页（chrome-error://）不含登录标记，曾把「域名打不开」误判成
+    已登录——假 connected 的来源，先排除。"""
+    mod = PLATFORMS[plat]
+    try:
+        page.navigate(mod.CONFIG["home"], timeout=30)
+    except BrowserError as e:
+        return False, str(e)
+    url = str(page.url() or "")
+    if url.startswith("chrome-error://") or url.startswith("about:"):
+        return False, url                      # 页面没打开：网络/域名问题，不是登录态
+    if any(m in url for m in mod.CONFIG["login_url_marks"]):
+        return False, url
+    return True, url
+
+
+# ---------------------------------------------------------------- 流程加载
+def load_flow(plat, action):
+    """流程表：data/publish/flows-<plat>.json 覆盖内置默认（校准不改代码）。"""
+    fp = paths.PUBLISH_DIR / ("flows-%s.json" % plat)
+    try:
+        data = json.loads(fp.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and isinstance(data.get(action), list):
+            return data[action]
+    except Exception:
+        pass
+    return PLATFORMS[plat].FLOWS[action]
+
+
+# ---------------------------------------------------------------- 动作：连接
+def connect(plat):
+    """开浏览器到平台首页，起后台线程轮询登录态（等扫码）。"""
+    if plat not in PLATFORMS:
+        return False, "未知平台"
+    try:
+        b, page = _open_page(plat)
+    except BrowserError as e:
+        _set(plat, status="error", error=str(e))
+        return False, str(e)
+    page.navigate(PLATFORMS[plat].CONFIG["home"])
+    _set(plat, status="waiting_login", error="")
+
+    def wait_login():
+        mod = PLATFORMS[plat]
+        deadline = time.time() + LOGIN_WAIT_S
+        while time.time() < deadline:
+            try:
+                url = str(page.url() or "")
+                if url and not any(m in url for m in mod.CONFIG["login_url_marks"]) \
+                        and "about:blank" not in url and "chrome-error" not in url:
+                    # 用户登录完成（离开登录页）。再主动开一次首页做复核，
+                    # 复核被踢回登录页说明只是中间跳转，继续等。
+                    ok, _u = _check_login(plat, page)
+                    if ok:
+                        _set(plat, status="connected", last_login=time.strftime("%m-%d %H:%M"))
+                        ledger.record(plat, "connect", ok=True)
+                        return
+            except (BrowserError, Exception):
+                pass                        # 页面被用户关掉等：继续等到超时
+            time.sleep(5)
+        _set(plat, status="error", error="等待登录超时（15 分钟），请重新点连接")
+
+    threading.Thread(target=wait_login, daemon=True,
+                     name="pub-login-%s" % plat).start()
+    return True, ""
+
+
+def disconnect(plat):
+    b = _browsers.pop(plat, None)
+    if b:
+        b.close()
+    _set(plat, status="none", error="")
+    return True
+
+
+# ---------------------------------------------------------------- 动作：探测
+def probe_form_async(plat):
+    """「探测表单」：跑 probe 流程把页面真实可交互元素 dump 进台账 log。"""
+    if plat not in PLATFORMS:
+        return False, "未知平台"
+    if _st(plat).get("status") not in ("connected", "error"):
+        return False, "请先连接并登录平台"
+    _set(plat, status="busy", last_action="probe", error="")
+
+    logs = []
+
+    def run():
+        try:
+            b, page = _open_page(plat)
+            flow.run_flow(page, load_flow(plat, "probe_form"),
+                          values={}, config=PLATFORMS[plat].CONFIG,
+                          shot=lambda n: page.screenshot(ledger.shot_path(plat, "probe", n)),
+                          log=logs.append)
+            _set(plat, status="connected")
+            ledger.record(plat, "probe", ok=True,
+                          error="\n".join(logs)[:2000])
+        except Exception as e:
+            _set(plat, status="error", error="探测失败：%s" % e)
+            ledger.record(plat, "probe", ok=False, error=str(e)[:300])
+        finally:
+            _save()
+
+    threading.Thread(target=run, daemon=True, name="pub-probe-%s" % plat).start()
+    return True, ""
+
+
+# ---------------------------------------------------------------- 动作：建书
+def create_book_async(task_id, plat, auto_submit=False):
+    """按任务 book_meta 的资料在平台建书。返回 (ok, err)。"""
+    from .. import store
+    if plat not in PLATFORMS:
+        return False, "未知平台"
+    task = store.get_task(task_id)
+    if not task:
+        return False, "任务不存在"
+    meta = ((task.get("book_meta") or {}).get(plat) or {})
+    if meta.get("status") != "done" or not meta.get("data"):
+        return False, "请先生成该平台的作品信息"
+    if _st(plat).get("status") == "busy":
+        return False, "该平台有操作正在进行中"
+    if ledger.book_for(task_id, plat):
+        return False, "该任务已在此平台登记过作品，请直接发章"
+    ok_login, why = _login_guard(plat)
+    if not ok_login:
+        return False, why
+    _set(plat, status="busy", last_action="create_book", error="")
+
+    data = meta["data"]
+    mod = PLATFORMS[plat]
+    logs = []
+
+    def run():
+        book_name = (data.get("book_name") or "").strip()
+        try:
+            b, page = _open_page(plat)
+            values = mod.values_create_book(data)
+            steps = _with_tag_steps(load_flow(plat, "create_book"),
+                                    mod.tag_groups(data), values)
+            flow.run_flow(page, steps, values=values, config=mod.CONFIG,
+                          auto_submit=auto_submit,
+                          shot=lambda n: page.screenshot(ledger.shot_path(plat, task_id, n)),
+                          log=logs.append)
+            ledger.record(plat, "create_book", task_id=task_id, title=book_name,
+                          ok=True, shot=str(ledger.shot_path(plat, task_id, "")))
+            # book_id 拿不到（DOM 深链未知）：先用书名登记，发章按书名找书
+            ledger.save_book(task_id, plat, {"book_id": "", "title": book_name})
+            _set(plat, status="connected", error="")
+        except Exception as e:
+            _set(plat, status="error", error="建书失败：%s" % e)
+            ledger.record(plat, "create_book", task_id=task_id, title=book_name,
+                          ok=False, error=str(e)[:300],
+                          shot=str(ledger.shot_path(plat, task_id, "")))
+        finally:
+            _save()
+
+    threading.Thread(target=run, daemon=True,
+                     name="pub-book-%s" % plat).start()
+    return True, ""
+
+
+def _with_tag_steps(steps, groups, values):
+    """标签走数据驱动：清单进 values["_tags"]（[组名, 标签] 对），由 flow 的
+    "tags" 步骤按组切换点选。组显示名映射来自平台模块 TAG_GROUP_LABELS
+    （缺省平台无映射时退化为纯标签）。兼容旧流程表（无 tags 步骤时插桩）。"""
+    from . import qimao as _qm
+    flat = []
+    for key, tags in groups or []:
+        grp = getattr(_qm, "TAG_GROUP_LABELS", {}).get(key, "")
+        flat.extend([grp, str(t)] if grp and str(t).strip() else str(t)
+                    for t in tags if str(t).strip())
+    if not flat:
+        return steps
+    if any(st.get("do") == "tags" for st in steps):
+        values["_tags"] = flat
+        return steps
+    tag_steps = [{"do": "click_text", "text": str(t), "contains": False,
+                  "scope": "[class*=tag] li,span,label,[class*=label]"}
+                 for t in flat]
+    out, inserted = list(steps), False
+    for i, st in enumerate(out):
+        if st.get("do") in ("submit", "shot") and not inserted:
+            out[i:i] = tag_steps
+            inserted = True
+    if not inserted:
+        out += tag_steps
+    return out
+
+
+def _login_guard(plat):
+    """动作前的登录前置：状态 connected 放行；否则现场复核一次。"""
+    s = _st(plat)
+    if s.get("status") == "connected":
+        return True, ""
+    try:
+        _b, page = _open_page(plat)
+        ok, url = _check_login(plat, page)
+        if ok:
+            _set(plat, status="connected")
+            return True, ""
+        return False, "平台未登录（当前页面 %s），请先点「连接平台」扫码" % url[:80]
+    except BrowserError as e:
+        return False, "浏览器不可用：%s" % e
+
+
+# ---------------------------------------------------------------- 动作：发章
+def read_chapter(fp):
+    """读章节文件 → (章号, 标题, 正文, 错误)。UTF-8→GBK 回退（章稿乱码教训）。
+
+    标题取首个「# 」标题行，没有则用文件名；章号从标题/文件名的
+    「第X章」解析，解析不出记 0（台账不按章号幂等，只按标题留痕）。"""
+    from pathlib import Path
+    from .. import runner
+    p = Path(fp)
+    if not p.is_file():
+        return 0, "", "", "章节文件不存在：%s" % p
+    try:
+        text = runner.read_text_any_enc(p)
+    except Exception as e:
+        return 0, "", "", "读章节文件失败：%s" % e
+    lines = text.strip().splitlines()
+    title = ""
+    body_start = 0
+    for i, ln in enumerate(lines[:5]):
+        s = ln.strip()
+        if s.startswith("#"):                 # 只认 markdown 标题行
+            s = s.lstrip("#").strip()
+            if s:
+                title, body_start = s, i + 1
+                break
+    if not title:
+        title = p.stem
+    body = "\n".join(lines[body_start:]).strip()
+    ch_no = ledger.parse_chapter_no(title) or ledger.parse_chapter_no(p.name)
+    return ch_no, title, body, ""
+
+
+def upload_chapter_async(task_id, plat, chapter_file, auto_submit=False):
+    """把一章发到平台（或填好待人工确认）。幂等：已成功发布的章号拒绝重发。"""
+    from .. import store
+    if plat not in PLATFORMS:
+        return False, "未知平台"
+    task = store.get_task(task_id)
+    if not task:
+        return False, "任务不存在"
+    book = ledger.book_for(task_id, plat)
+    if not book:
+        return False, "该任务尚未在此平台建书，请先「创建作品」"
+    if _st(plat).get("status") == "busy":
+        return False, "该平台有操作正在进行中"
+    ch_no, title, body, err = read_chapter(chapter_file)
+    if err:
+        return False, err
+    n_chars = len(body.replace("\n", "").replace(" ", ""))
+    if n_chars < 100:
+        return False, "正文过短（%d 字），疑似未完成章节" % n_chars
+    if n_chars > 30000:
+        return False, "正文超长（%d 字），平台单章上限一般 2 万字" % n_chars
+    done = ledger.published_chapters(task_id, plat)
+    if ch_no and ch_no in done:
+        return False, "第 %d 章已成功发布过（台账幂等拦截）；确需重发请手工处理" % ch_no
+    ok_login, why = _login_guard(plat)
+    if not ok_login:
+        return False, why
+    _set(plat, status="busy", last_action="upload_chapter", error="")
+
+    mod = PLATFORMS[plat]
+    values = {"chapter_title": title, "chapter_body": body,
+              "book_name": book.get("title") or ""}
+    logs = []
+
+    def run():
+        try:
+            b, page = _open_page(plat)
+            flow.run_flow(page, load_flow(plat, "upload_chapter"), values=values,
+                          config=mod.CONFIG, auto_submit=auto_submit,
+                          shot=lambda n: page.screenshot(ledger.shot_path(plat, task_id, n)),
+                          log=logs.append)
+            ledger.record(plat, "upload_chapter", task_id=task_id, chapter_no=ch_no,
+                          book_id=book.get("book_id") or "", title=title, ok=True)
+            _set(plat, status="connected", error="")
+        except Exception as e:
+            _set(plat, status="error", error="发章失败：%s" % e)
+            ledger.record(plat, "upload_chapter", task_id=task_id, chapter_no=ch_no,
+                          book_id=book.get("book_id") or "", title=title,
+                          ok=False, error=str(e)[:300])
+        finally:
+            _save()
+
+    threading.Thread(target=run, daemon=True,
+                     name="pub-ch-%s" % plat).start()
+    return True, ""
+
+
+def history(task_id=None, plat=None, limit=50):
+    return ledger.recent(task_id=task_id, platform=plat, limit=limit)
+
+
+_load()

package/app/core/publish/qimao.py

@@ -0,0 +1,97 @@
+# -*- 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"],
+}
+
+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):
+    return {
+        "title": (meta.get("book_name") or "").strip(),
+        "summary": (meta.get("summary") or "").strip(),
+        "protagonist": (meta.get("protagonist_1") or "").strip(),
+        "target_reader": (meta.get("target_reader") or "").strip(),
+        "category_main": (meta.get("category_main") or "").strip(),
+        "category_sub": (meta.get("category_sub") or "").strip(),
+        "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

package/app/core/publish/ws.py

@@ -0,0 +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()