dscli-agent 0.1.0__py3-none-any.whl

dscli/browser.py

@@ -0,0 +1,1354 @@
+from __future__ import annotations
+
+import ctypes
+import json
+import logging
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from playwright.sync_api import (
+    BrowserContext,
+    Error as PlaywrightError,
+    Page,
+    TimeoutError as PlaywrightTimeoutError,
+    sync_playwright,
+)
+
+from .config import Config, debug_dir
+from .scraper import (
+    DIAGNOSTICS_JS,
+    EXTRACT_LAST_ANSWER_JS,
+    MARK_JS,
+    SCROLL_TO_BOTTOM_JS,
+    SNAPSHOT_JS,
+    TOASTS_JS,
+)
+
+log = logging.getLogger("dscli")
+
+
+class BrowserError(RuntimeError):
+    pass
+
+
+class LoginRequired(BrowserError):
+    pass
+
+
+class HumanCheckRequired(BrowserError):
+    pass
+
+
+class ChatError(BrowserError):
+    def __init__(self, message: str, *, screenshot: str | None = None) -> None:
+        super().__init__(message)
+        self.screenshot = screenshot
+
+
+class UploadError(BrowserError):
+    pass
+
+
+class _VS_FIXEDFILEINFO(ctypes.Structure):
+    _fields_ = [
+        ("dwSignature", ctypes.c_uint32),
+        ("dwStrucVersion", ctypes.c_uint32),
+        ("dwFileVersionMS", ctypes.c_uint32),
+        ("dwFileVersionLS", ctypes.c_uint32),
+        ("dwProductVersionMS", ctypes.c_uint32),
+        ("dwProductVersionLS", ctypes.c_uint32),
+        ("dwFileFlagsMask", ctypes.c_uint32),
+        ("dwFileFlags", ctypes.c_uint32),
+        ("dwFileOS", ctypes.c_uint32),
+        ("dwFileType", ctypes.c_uint32),
+        ("dwFileSubtype", ctypes.c_uint32),
+        ("dwFileDateMS", ctypes.c_uint32),
+        ("dwFileDateLS", ctypes.c_uint32),
+    ]
+
+
+def _file_version(path: Path) -> str | None:
+    """Read a Windows executable's product version without launching it."""
+    if os.name != "nt":
+        return None
+    try:
+        size = ctypes.windll.version.GetFileVersionInfoSizeW(str(path), None)
+        if not size:
+            return None
+        data = ctypes.create_string_buffer(size)
+        if not ctypes.windll.version.GetFileVersionInfoW(str(path), 0, size, data):
+            return None
+        ptr = ctypes.c_void_p()
+        length = ctypes.c_uint()
+        if not ctypes.windll.version.VerQueryValueW(
+            data, ctypes.c_wchar_p("\\"), ctypes.byref(ptr), ctypes.byref(length)
+        ):
+            return None
+        info = ctypes.cast(ptr, ctypes.POINTER(_VS_FIXEDFILEINFO)).contents
+        ms, ls = info.dwProductVersionMS, info.dwProductVersionLS
+        if not ms and not ls:
+            ms, ls = info.dwFileVersionMS, info.dwFileVersionLS
+        if not ms and not ls:
+            return None
+        return f"{ms >> 16}.{ms & 0xFFFF}.{ls >> 16}.{ls & 0xFFFF}"
+    except (AttributeError, OSError, ValueError):
+        return None
+
+
+def _version_from_registry(channel: str | None) -> str | None:
+    if os.name != "nt":
+        return None
+    try:
+        import winreg
+    except ImportError:
+        return None
+
+    if channel == "msedge":
+        keys = [
+            (winreg.HKEY_CURRENT_USER, r"Software\Microsoft\Edge\BLBeacon", "version"),
+        ]
+    else:
+        keys = [
+            (winreg.HKEY_CURRENT_USER, r"Software\Google\Chrome\BLBeacon", "version"),
+            (
+                winreg.HKEY_LOCAL_MACHINE,
+                r"SOFTWARE\WOW6432Node\Google\Update\Clients"
+                r"\{8A69D345-D564-463c-AFF1-A69D9E530F96}",
+                "pv",
+            ),
+            (
+                winreg.HKEY_LOCAL_MACHINE,
+                r"SOFTWARE\Google\Update\Clients"
+                r"\{8A69D345-D564-463c-AFF1-A69D9E530F96}",
+                "pv",
+            ),
+        ]
+    for root, key_path, value_name in keys:
+        try:
+            with winreg.OpenKey(root, key_path) as key:
+                value, _ = winreg.QueryValueEx(key, value_name)
+        except OSError:
+            continue
+        if isinstance(value, str) and re.match(r"^\d+\.", value):
+            return value
+    return None
+
+
+def _candidate_executables(channel: str | None) -> list[Path]:
+    env = os.environ
+    candidates: list[Path] = []
+    if os.name == "nt":
+        if channel == "msedge":
+            bases = [env.get("PROGRAMFILES(X86)"), env.get("PROGRAMFILES"), env.get("LOCALAPPDATA")]
+            for base in bases:
+                if base:
+                    candidates.append(Path(base) / "Microsoft" / "Edge" / "Application" / "msedge.exe")
+        else:
+            bases = [env.get("PROGRAMFILES"), env.get("PROGRAMFILES(X86)"), env.get("LOCALAPPDATA")]
+            for base in bases:
+                if base:
+                    candidates.append(Path(base) / "Google" / "Chrome" / "Application" / "chrome.exe")
+    elif sys.platform == "darwin":
+        names = (
+            "Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+            if channel == "msedge"
+            else "Google Chrome.app/Contents/MacOS/Google Chrome"
+        )
+        candidates.append(Path("/Applications") / names)
+    else:
+        if channel == "msedge":
+            names = ("microsoft-edge", "microsoft-edge-stable")
+        else:
+            names = ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser")
+        import shutil
+
+        for name in names:
+            found = shutil.which(name)
+            if found:
+                candidates.append(Path(found))
+    return candidates
+
+
+def _version_from_executable(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    if os.name == "nt":
+        return _file_version(path)
+    try:
+        proc = subprocess.run(
+            [str(path), "--version"],
+            capture_output=True,
+            text=True,
+            timeout=8,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    match = re.search(r"(\d+\.\d+\.\d+\.\d+)", (proc.stdout or "") + (proc.stderr or ""))
+    return match.group(1) if match else None
+
+
+def _installed_version(channel: str | None) -> str | None:
+    version = _version_from_registry(channel)
+    if version:
+        return version
+    for candidate in _candidate_executables(channel):
+        version = _version_from_executable(candidate)
+        if version:
+            return version
+    return None
+
+
+def _browser_user_agent(major: str, channel: str | None) -> str:
+    if platform.system() == "Darwin":
+        system = "Macintosh; Intel Mac OS X 10_15_7"
+    elif platform.system() == "Linux":
+        system = "X11; Linux x86_64"
+    else:
+        system = "Windows NT 10.0; Win64; x64"
+    ua = (
+        f"Mozilla/5.0 ({system}) AppleWebKit/537.36 (KHTML, like Gecko) "
+        f"Chrome/{major}.0.0.0 Safari/537.36"
+    )
+    if channel == "msedge":
+        ua += f" Edg/{major}.0.0.0"
+    return ua
+
+
+@dataclass
+class SendReceipt:
+    prev_key: str | None
+    prev_count: int
+    prev_preview: str
+    sent_at: float
+    url: str
+
+
+_ERROR_RE = re.compile(
+    r"\b(error|failed|failure|busy|try again|too large|unsupported|network|"
+    r"something went wrong|rate limit|quota)\b|"
+    r"upload (?:failed|error)|failed to (?:upload|read)|"
+    r"解析失败|上传失败|服务器",
+    re.IGNORECASE,
+)
+
+
+class ChatSession:
+    def __init__(self, config: Config, *, headless: bool | None = None) -> None:
+        self.cfg = config
+        self.headless = config.headless if headless is None else headless
+        self.selectors = config.merged_selectors()
+        self._pw = None
+        self.context: BrowserContext | None = None
+        self.page: Page | None = None
+        self._chrome_session: str | None = None
+        self._chrome_login_token: str | None = None
+
+    # ------------------------------------------------------------------ setup
+    def _chrome_profile_name(self, source: Path) -> str:
+        name = self.cfg.chrome_profile.strip()
+        if not name:
+            name = "Default"
+            try:
+                local_state = json.loads((source / "Local State").read_text(encoding="utf-8"))
+                last_used = local_state.get("profile", {}).get("last_used")
+                if isinstance(last_used, str) and last_used.strip():
+                    name = last_used.strip()
+            except (OSError, json.JSONDecodeError):
+                pass
+        if name in {".", ".."} or Path(name).name != name:
+            raise BrowserError("chrome_profile must be a directory name, such as Default or Profile 1.")
+        return name
+
+    def _chrome_session_files(self, source: Path, profile: str) -> list[Path]:
+        network = source / profile / "Network"
+        return [
+            path
+            for path in (
+                source / "Local State",
+                network / "Cookies",
+                network / "Cookies-journal",
+                network / "Cookies-wal",
+                network / "Cookies-shm",
+            )
+            if path.is_file()
+        ]
+
+    @staticmethod
+    def _extract_user_token(data: bytes) -> str | None:
+        """Read DeepSeek's JSON-wrapped userToken from raw Chrome LevelDB bytes."""
+        marker = b"userToken"
+        prefix = b'{"value":"'
+        suffix = b'","__version"'
+        token = None
+        position = 0
+        while True:
+            key = data.find(marker, position)
+            if key < 0:
+                break
+            start = data.find(prefix, key + len(marker), key + len(marker) + 256)
+            if start >= 0:
+                begin = start + len(prefix)
+                end = data.find(suffix, begin, begin + 4096)
+                if end > begin:
+                    candidate = data[begin:end]
+                    if 16 <= len(candidate) <= 4096 and all(
+                        32 <= byte < 127 for byte in candidate
+                    ):
+                        token = candidate.decode("ascii")
+            position = key + len(marker)
+        return token
+
+    def _read_chrome_user_token(self, source: Path, profile: str) -> str | None:
+        directory = source / profile / "Local Storage" / "leveldb"
+        files: list[tuple[int, str, Path]] = []
+        try:
+            for path in directory.iterdir():
+                if path.is_file() and path.suffix.lower() in {".ldb", ".log"}:
+                    try:
+                        files.append((path.stat().st_mtime_ns, path.name, path))
+                    except OSError:
+                        continue
+        except OSError:
+            return None
+
+        token = None
+        for _, _, path in sorted(files):
+            try:
+                data = path.read_bytes()
+            except OSError:
+                continue
+            found = self._extract_user_token(data)
+            if found is not None:
+                token = found
+        return token
+
+    def _sync_chrome_session(self) -> str | None:
+        self._chrome_login_token = None
+        configured = self.cfg.chrome_user_data_dir.strip()
+        if not configured:
+            return None
+        source = Path(configured).expanduser()
+        if not source.is_dir():
+            return None
+        profile = self._chrome_profile_name(source)
+        if not (source / profile).is_dir():
+            return None
+        target = Path(self.cfg.profile_dir)
+        if source.resolve() == target.resolve():
+            raise BrowserError(
+                "profile_dir must be separate from chrome_user_data_dir; dscli uses an "
+                "isolated copy instead of automating Chrome's live profile."
+            )
+
+        # Chrome 136+ blocks DevTools automation on its live default profile.
+        self._chrome_login_token = self._read_chrome_user_token(source, profile)
+        try:
+            candidates = self._chrome_session_files(source, profile)
+        except OSError as exc:
+            raise BrowserError(f"Could not read Chrome's session files: {exc}") from exc
+        files: list[Path] = []
+        signature: list[list[Any]] = []
+        for path in candidates:
+            try:
+                stat = path.stat()
+            except OSError:
+                continue
+            files.append(path)
+            signature.append([str(path.relative_to(source)), stat.st_size, stat.st_mtime_ns])
+        state = {"source": str(source), "profile": profile, "files": signature}
+        self._chrome_session = f"{profile} ({source})"
+        marker = target / ".chrome-session.json"
+        try:
+            previous = json.loads(marker.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            previous = None
+        previous_files = {}
+        already_copied = set()
+        if (
+            isinstance(previous, dict)
+            and previous.get("source") == str(source)
+            and previous.get("profile") == profile
+        ):
+            previous_files = {
+                entry[0]: entry[1:]
+                for entry in previous.get("files", [])
+                if isinstance(entry, list) and len(entry) == 3
+            }
+            copied_value = previous.get("copied", [])
+            if isinstance(copied_value, list):
+                already_copied = {entry for entry in copied_value if isinstance(entry, str)}
+
+        copied: set[str] = set()
+        pending: list[tuple[Path, str]] = []
+        for path, entry in zip(files, signature):
+            relative = entry[0]
+            if relative in already_copied and previous_files.get(relative) == entry[1:]:
+                copied.add(relative)
+            else:
+                pending.append((path, relative))
+        if not pending:
+            return profile
+
+        imported = False
+        try:
+            for path, relative in pending:
+                destination = target / relative
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                try:
+                    shutil.copy2(path, destination)
+                    copied.add(relative)
+                    imported = True
+                except PermissionError:
+                    log.debug("Chrome has this session file open; skipping it: %s", path)
+            state["copied"] = sorted(copied)
+            state["complete"] = len(copied) == len(files)
+            temporary = marker.with_suffix(".tmp")
+            temporary.write_text(json.dumps(state), encoding="utf-8")
+            os.replace(temporary, marker)
+        except OSError as exc:
+            raise BrowserError(
+                f"Could not copy Chrome's session into dscli's profile: {exc}. "
+                "Close other dscli browser windows and try again."
+            ) from exc
+        if imported:
+            log.debug("Reusing the saved DeepSeek session from Chrome's %s profile.", profile)
+        return profile
+
+    def _resolve_user_agent(self, channel: str | None, *, bundled: bool = False) -> str | None:
+        """Return a normal Chrome UA for headless runs.
+
+        CloudFront rejects the ``HeadlessChrome/...`` user agent with a 403
+        before the DeepSeek app even loads. Swap in the installed browser's
+        real major version so headless runs look like a regular Chrome window.
+        """
+        if self.cfg.user_agent.strip():
+            return self.cfg.user_agent.strip()
+        if not self.headless:
+            return None
+        version: str | None = None
+        if not bundled:
+            version = _installed_version(channel)
+        if not version and self._pw is not None:
+            try:
+                exe = self._pw.chromium.executable_path
+            except (AttributeError, PlaywrightError):
+                exe = None
+            if exe:
+                version = _version_from_executable(Path(exe))
+        match = re.match(r"(\d+)", version or "")
+        major = match.group(1) if match else "131"
+        ua = _browser_user_agent(major, channel)
+        log.debug("Using headless user agent: %s", ua)
+        return ua
+
+    def start(self) -> None:
+        if self.context is not None:
+            return
+        Path(self.cfg.profile_dir).mkdir(parents=True, exist_ok=True)
+        debug_dir().mkdir(parents=True, exist_ok=True)
+        chrome_profile = self._sync_chrome_session()
+        self._pw = sync_playwright().start()
+
+        args = [
+            "--disable-blink-features=AutomationControlled",
+            "--no-first-run",
+            "--no-default-browser-check",
+        ]
+        if chrome_profile:
+            args.append(f"--profile-directory={chrome_profile}")
+        launch_kwargs: dict[str, Any] = {
+            "user_data_dir": self.cfg.profile_dir,
+            "headless": self.headless,
+            "locale": self.cfg.locale,
+            "viewport": {"width": 1440, "height": 960},
+            "args": args,
+            "ignore_default_args": ["--enable-automation"],
+        }
+        context: BrowserContext | None = None
+        try:
+            if self.cfg.channel:
+                try:
+                    ua = self._resolve_user_agent(self.cfg.channel)
+                    if ua:
+                        launch_kwargs["user_agent"] = ua
+                    context = self._pw.chromium.launch_persistent_context(
+                        channel=self.cfg.channel, **launch_kwargs
+                    )
+                except PlaywrightError as exc:
+                    log.debug("Could not launch channel %s: %s", self.cfg.channel, exc)
+                    log.debug(
+                        "Could not launch installed Chrome; falling back to Playwright Chromium."
+                    )
+                    launch_kwargs.pop("user_agent", None)
+            if context is None:
+                ua = self._resolve_user_agent(None, bundled=True)
+                if ua:
+                    launch_kwargs["user_agent"] = ua
+                context = self._pw.chromium.launch_persistent_context(**launch_kwargs)
+        except PlaywrightError as exc:
+            self._stop_pw()
+            message = str(exc)
+            if "ProcessSingleton" in message or "already in use" in message.lower():
+                raise BrowserError(
+                    "The dscli browser profile is already in use. Close any other dscli "
+                    "browser window and try again."
+                ) from exc
+            if "Executable doesn't exist" in message or "playwright install" in message:
+                raise BrowserError(
+                    "Playwright's browser is not installed. Run: python -m playwright install chromium"
+                ) from exc
+            raise BrowserError(f"Could not start the browser: {message}") from exc
+
+        self.context = context
+        context.set_default_timeout(self.cfg.page_timeout_ms)
+        context.add_init_script(
+            "Object.defineProperty(navigator, 'webdriver', {get: () => undefined});"
+        )
+        if self._chrome_login_token:
+            stored_value = json.dumps(
+                {"value": self._chrome_login_token, "__version": "0"},
+                separators=(",", ":"),
+            )
+            context.add_init_script(
+                """
+                (() => {
+                  try {
+                    if (location.hostname !== "chat.deepseek.com") return;
+                    const current = localStorage.getItem("userToken");
+                    if (!current || current === "null") {
+                      localStorage.setItem("userToken", %s);
+                    }
+                  } catch (e) {}
+                })();
+                """
+                % json.dumps(stored_value)
+            )
+        self.page = context.new_page()
+        self.page.set_default_navigation_timeout(60_000)
+        self.page.on("dialog", self._dismiss_dialog)
+        try:
+            self.page.goto(self.cfg.url, wait_until="domcontentloaded", timeout=60_000)
+        except PlaywrightTimeoutError:
+            log.debug("The DeepSeek page took a long time to load; continuing.")
+        self.page.wait_for_timeout(1200)
+
+    def _dismiss_dialog(self, dialog) -> None:
+        try:
+            dialog.dismiss()
+        except PlaywrightError:
+            pass
+
+    def _stop_pw(self) -> None:
+        if self._pw is not None:
+            try:
+                self._pw.stop()
+            except Exception:
+                pass
+            self._pw = None
+
+    def close(self) -> None:
+        context = self.context
+        self.context = None
+        self.page = None
+        if context is not None:
+            try:
+                context.close()
+            except Exception:
+                pass
+        self._stop_pw()
+
+    # --------------------------------------------------------------- selectors
+    def _locator_visible(self, page: Page, selector: str) -> bool:
+        try:
+            loc = page.locator(selector)
+            if loc.count() == 0:
+                return False
+            return loc.first.is_visible()
+        except PlaywrightError:
+            return False
+
+    def _find_composer(self, *, pages: list[Page] | None = None) -> Any | None:
+        if self.context is None:
+            return None
+        candidates = pages or [p for p in self.context.pages if not p.is_closed()]
+        # Prefer pages already showing the chat app.
+        candidates = sorted(
+            candidates,
+            key=lambda p: (self.cfg.url.split("//")[-1].split("/")[0] not in (p.url or ""),),
+        )
+        for page in candidates:
+            if page.is_closed():
+                continue
+            for selector in (self.selectors["composer"], self.selectors["composer_fallback"]):
+                try:
+                    loc = page.locator(selector)
+                    count = min(loc.count(), 5)
+                    for i in range(count):
+                        item = loc.nth(i)
+                        if item.is_visible():
+                            self.page = page
+                            return item
+                except PlaywrightError:
+                    continue
+        return None
+
+    def _composer_css(self) -> str:
+        return f"{self.selectors['composer']}, {self.selectors['composer_fallback']}"
+
+    def _send_button(self) -> Any | None:
+        if self.page is None:
+            return None
+        try:
+            loc = self.page.locator(self.selectors["send_button"])
+            for i in range(min(loc.count(), 5)):
+                item = loc.nth(i)
+                if item.is_visible():
+                    return item
+        except PlaywrightError:
+            pass
+        return None
+
+    def _assistant_count(self) -> int:
+        if self.page is None:
+            return 0
+        try:
+            return self.page.locator(self.selectors["assistant_message"]).count()
+        except PlaywrightError:
+            return 0
+
+    def _cloudflare_visible(self) -> bool:
+        if self.context is None:
+            return False
+        for page in [p for p in self.context.pages if not p.is_closed()]:
+            if self._locator_visible(page, self.selectors["cloudflare"]):
+                return True
+        return False
+
+    # ------------------------------------------------------------------- login
+    def wait_for_composer(
+        self, timeout_sec: float = 15, *, interactive: bool = False
+    ) -> None:
+        start = time.monotonic()
+        announced_login = False
+        announced_cf = False
+        modal_checked = False
+        while time.monotonic() - start < timeout_sec:
+            if self.context is None:
+                raise BrowserError("The browser is not running.")
+            if self._find_composer() is not None:
+                return
+            if self._cloudflare_visible():
+                if self.headless:
+                    raise HumanCheckRequired(
+                        "DeepSeek is showing a Cloudflare human check. Rerun with --headed, "
+                        "complete the check once, then retry. The login profile is preserved."
+                    )
+                if not announced_cf:
+                    log.warning(
+                        "DeepSeek is showing a Cloudflare / human check. Complete it in the "
+                        "browser window; waiting..."
+                    )
+                    announced_cf = True
+            else:
+                if interactive and not announced_login:
+                    log.info(
+                        "Log in to DeepSeek in the browser window (including any Cloudflare "
+                        "check). Waiting for the chat composer..."
+                    )
+                    announced_login = True
+                if not modal_checked and self.page is not None:
+                    modal_checked = True
+                    self._dismiss_common_modals()
+            time.sleep(0.5)
+
+        if self.headless:
+            raise LoginRequired(
+                "Not logged in to DeepSeek. Run `dscli login` once, or rerun with --headed. "
+                f"Profile: {self.cfg.profile_dir}"
+            )
+        raise LoginRequired(
+            "The DeepSeek chat composer did not appear. Make sure you are logged in and have "
+            "passed any Cloudflare check, then try again."
+        )
+
+    def import_chrome_login(self, timeout_sec: float = 30.0) -> bool:
+        configured = self.cfg.chrome_user_data_dir.strip()
+        if not configured:
+            return False
+        source = Path(configured).expanduser()
+        if not source.is_dir():
+            return False
+        try:
+            profile = self._chrome_profile_name(source)
+        except BrowserError:
+            return False
+        if not (source / profile).is_dir():
+            return False
+        token = self._read_chrome_user_token(source, profile)
+        self._chrome_login_token = token
+        page = self.page
+        if token is None or page is None or page.is_closed():
+            return False
+
+        value = json.dumps({"value": token, "__version": "0"}, separators=(",", ":"))
+        try:
+            if "chat.deepseek.com" not in (page.url or ""):
+                page.goto(self.cfg.url, wait_until="domcontentloaded", timeout=60_000)
+            page.evaluate(
+                "(value) => localStorage.setItem('userToken', value)", value
+            )
+            page.goto(self.cfg.url, wait_until="domcontentloaded", timeout=60_000)
+            page.wait_for_timeout(1000)
+            self.wait_for_composer(timeout_sec, interactive=False)
+        except (PlaywrightError, LoginRequired, HumanCheckRequired) as exc:
+            log.debug("Could not use Chrome's DeepSeek login: %s", exc)
+            return False
+        log.debug("Using the DeepSeek login from Chrome's %s profile.", profile)
+        return True
+
+    def _dismiss_common_modals(self) -> None:
+        if self.page is None or self.page.is_closed():
+            return
+        for name in ("Accept all", "Accept", "I agree", "Got it"):
+            try:
+                btn = self.page.get_by_role("button", name=name, exact=True)
+                if btn.count() and btn.first.is_visible():
+                    btn.first.click(timeout=1500)
+                    self.page.wait_for_timeout(250)
+                    return
+            except PlaywrightError:
+                continue
+
+    def login(self) -> None:
+        self.headless = False
+        self.start()
+        self.wait_for_composer(self.cfg.login_timeout_sec, interactive=True)
+        log.info("Logged in. Profile saved at %s", self.cfg.profile_dir)
+
+    # ------------------------------------------------------------------ chats
+    def new_chat(self) -> None:
+        if self.context is None:
+            raise BrowserError("Browser not started.")
+        self._find_composer()
+        if self.page is None:
+            raise LoginRequired("No DeepSeek page is available.")
+        if self._cloudflare_visible():
+            raise HumanCheckRequired(
+                "Cloudflare check is blocking the chat. Rerun with --headed and complete it."
+            )
+
+        before_url = self.page.url
+        self.page.goto(self.cfg.url, wait_until="domcontentloaded", timeout=60_000)
+        self.page.wait_for_timeout(1500)
+        self._dismiss_common_modals()
+        if self._find_composer() is None:
+            raise LoginRequired(
+                "The DeepSeek composer is not visible. Run `dscli login` and try again."
+            )
+
+        if self._assistant_count() > 0 or "/a/chat/s/" in (self.page.url or ""):
+            clicked = self._click_new_chat()
+            if not clicked:
+                log.debug("New chat control not found by text; reloading the home page.")
+            deadline = time.monotonic() + 12
+            while time.monotonic() < deadline:
+                if self._assistant_count() == 0:
+                    break
+                time.sleep(0.4)
+            if self._assistant_count() > 0:
+                # One more attempt: click rather than reload, so we do not land
+                # back on the previous conversation.
+                self._click_new_chat()
+                deadline = time.monotonic() + 8
+                while time.monotonic() < deadline:
+                    if self._assistant_count() == 0:
+                        break
+                    time.sleep(0.4)
+        if self._assistant_count() > 0:
+            raise BrowserError(
+                "Could not start a new chat; the previous conversation is still visible. "
+                "Run `dscli doctor --headed` to inspect the UI."
+            )
+        log.debug("New chat ready at %s (was %s)", self.page.url, before_url)
+
+    def _click_new_chat(self) -> bool:
+        if self.page is None:
+            return False
+        # The button is a div[tabindex] with a span child; conversation links
+        # are <a> elements and must not be clicked by mistake.
+        labels = ("New chat", "New Chat", "新对话")
+        pattern = re.compile(r"^\s*(?:" + "|".join(re.escape(x) for x in labels) + r")\s*$")
+        try:
+            loc = self.page.locator('div[tabindex="0"]').filter(has_text=pattern)
+            for i in range(min(loc.count(), 4)):
+                item = loc.nth(i)
+                if item.is_visible():
+                    item.click(timeout=3000)
+                    self.page.wait_for_timeout(700)
+                    return True
+        except PlaywrightError:
+            pass
+        for label in labels:
+            try:
+                loc = self.page.get_by_text(label, exact=True)
+                for i in range(min(loc.count(), 4)):
+                    item = loc.nth(i)
+                    if item.is_visible():
+                        item.click(timeout=3000)
+                        self.page.wait_for_timeout(700)
+                        return True
+            except PlaywrightError:
+                continue
+        # A JS fallback for a control that Playwright considers covered.
+        try:
+            return bool(
+                self.page.evaluate(
+                    """(labels) => {
+                        const wanted = labels.map(s => s.trim().toUpperCase());
+                        const nodes = Array.from(document.querySelectorAll('div[tabindex],button'));
+                        const node = nodes.find(n => {
+                            if (!n || !n.innerText) return false;
+                            const t = n.innerText.trim().toUpperCase();
+                            if (!wanted.includes(t)) return false;
+                            const r = n.getBoundingClientRect();
+                            return r.width > 0 && r.height > 0;
+                        });
+                        if (!node) return false;
+                        node.click();
+                        return true;
+                    }""",
+                    list(labels),
+                )
+            )
+        except PlaywrightError:
+            return False
+
+    def set_modes(self) -> None:
+        if self.page is None:
+            return
+        for label, desired in (("DeepThink", self.cfg.deepthink), ("Search", self.cfg.search)):
+            try:
+                loc = self.page.locator(self.selectors["toggle"], has_text=label)
+                if loc.count() == 0:
+                    log.debug("Toggle %s not found; leaving it as-is.", label)
+                    continue
+                toggle = loc.first
+                if not toggle.is_visible():
+                    continue
+                current = (toggle.get_attribute("aria-pressed") or "").lower() == "true"
+                if current != desired:
+                    toggle.click(timeout=3000)
+                    self.page.wait_for_timeout(300)
+                    log.debug("%s -> %s", label, "on" if desired else "off")
+            except PlaywrightError as exc:
+                log.debug("Could not set %s: %s", label, exc)
+
+    # -------------------------------------------------------------- attachments
+    def attach_files(self, paths: list[Path]) -> None:
+        if not paths:
+            return
+        if self.page is None:
+            raise UploadError("Browser page is not available.")
+        try:
+            input_loc = self.page.locator(self.selectors["file_input"]).first
+            input_loc.wait_for(state="attached", timeout=10_000)
+        except PlaywrightTimeoutError as exc:
+            raise UploadError(
+                "The chat file-upload input is not present. DeepSeek may have changed its UI."
+            ) from exc
+
+        accept = (input_loc.get_attribute("accept") or "").lower()
+        tokens = {t.strip() for t in accept.split(",") if t.strip()}
+        for path in paths:
+            if tokens and path.suffix.lower() and path.suffix.lower() not in tokens:
+                log.warning(
+                    "%s may not be an accepted attachment type by the chat UI; trying anyway.",
+                    path.name,
+                )
+        try:
+            input_loc.set_input_files([str(p) for p in paths])
+        except PlaywrightError as exc:
+            raise UploadError(f"Could not attach files: {exc}") from exc
+
+        settle = max(2.0, self.cfg.upload_settle_seconds)
+        if sum(p.stat().st_size for p in paths) > 5 * 1024 * 1024:
+            settle += 3.0
+        deadline = time.monotonic() + settle
+        while time.monotonic() < deadline:
+            error = self._error_toast()
+            if error:
+                raise UploadError(f"The chat UI rejected an attachment: {error}")
+            time.sleep(0.4)
+        log.debug("Attached %d file(s)", len(paths))
+
+    # ------------------------------------------------------------------- send
+    def _wait_until_idle(self, timeout_sec: float = 6) -> None:
+        deadline = time.monotonic() + timeout_sec
+        while time.monotonic() < deadline:
+            try:
+                snap = self._snapshot()
+            except PlaywrightError:
+                return
+            generating = snap.get("stop") or (
+                snap.get("composerEmpty") and snap.get("sendPresent") and not snap.get("sendDisabled")
+            )
+            if not generating:
+                return
+            time.sleep(0.3)
+        raise ChatError(
+            "DeepSeek is still generating a response. Wait for it to finish before sending "
+            "another message."
+        )
+
+    def _fill_composer(self, composer, text: str) -> None:
+        composer.click()
+        composer.fill("")
+        composer.fill(text)
+        try:
+            value = composer.input_value()
+        except PlaywrightError:
+            value = ""
+        if value != text:
+            if self.page is None:
+                raise ChatError("Browser page is not available.")
+            self.page.evaluate(
+                """(args) => {
+                    const el = document.querySelector(args.sel);
+                    if (!el) return;
+                    const proto = el instanceof HTMLTextAreaElement
+                        ? HTMLTextAreaElement.prototype : el.constructor.prototype;
+                    const setter = Object.getOwnPropertyDescriptor(proto, 'value');
+                    if (setter && setter.set) setter.set.call(el, args.text);
+                    else el.value = args.text;
+                    el.dispatchEvent(new Event('input', {bubbles: true}));
+                    el.dispatchEvent(new Event('change', {bubbles: true}));
+                }""",
+                {"sel": self._composer_css(), "text": text},
+            )
+            composer.click()
+            value = composer.input_value()
+        if value != text:
+            raise ChatError(
+                f"The composer did not accept the full message "
+                f"({len(value)} of {len(text)} characters). It may exceed the UI limit."
+            )
+
+    def send(self, text: str, files: list[Path] | None = None) -> SendReceipt:
+        if self.context is None:
+            raise BrowserError("Browser not started.")
+        composer = self._find_composer()
+        if composer is None:
+            raise LoginRequired("The DeepSeek composer disappeared; the session may have expired.")
+        if self._cloudflare_visible():
+            raise HumanCheckRequired(
+                "Cloudflare is blocking the chat. Rerun with --headed to complete the check."
+            )
+        self._wait_until_idle()
+        if files:
+            self.attach_files(files)
+
+        composer = self._find_composer()
+        if composer is None:
+            raise LoginRequired("The DeepSeek composer disappeared before sending.")
+        self._fill_composer(composer, text)
+
+        snapshot = self._snapshot()
+        page = self.page
+        if page is None:
+            raise ChatError("Browser page is not available.")
+        page.evaluate(MARK_JS, {"assistant": self.selectors["assistant_message"]})
+        receipt = SendReceipt(
+            prev_key=snapshot.get("key"),
+            prev_count=int(snapshot.get("count") or 0),
+            prev_preview=snapshot.get("preview") or "",
+            sent_at=time.monotonic(),
+            url=page.url,
+        )
+
+        deadline = time.monotonic() + 20
+        button = self._send_button()
+        while time.monotonic() < deadline:
+            button = self._send_button()
+            if button is not None:
+                try:
+                    disabled = "ds-button--disabled" in (button.get_attribute("class") or "")
+                except PlaywrightError:
+                    disabled = True
+                if not disabled:
+                    break
+            error = self._error_toast()
+            if error:
+                raise ChatError(f"DeepSeek reported an error before sending: {error}")
+            time.sleep(0.2)
+        else:
+            raise ChatError(
+                "The send button did not become enabled. The attachment may still be uploading, "
+                "or the chat UI has changed."
+            )
+
+        try:
+            button.click(timeout=5000)
+        except PlaywrightError:
+            try:
+                composer.press("Enter")
+            except PlaywrightError as exc:
+                raise ChatError(f"Could not send the message: {exc}") from exc
+
+        cleared = False
+        end = time.monotonic() + 12
+        while time.monotonic() < end:
+            try:
+                if not (composer.input_value() or "").strip():
+                    cleared = True
+                    break
+            except PlaywrightError:
+                break
+            error = self._error_toast()
+            if error:
+                raise ChatError(f"DeepSeek reported an error while sending: {error}")
+            time.sleep(0.2)
+        if not cleared:
+            try:
+                composer.click()
+                composer.press("Enter")
+                end = time.monotonic() + 6
+                while time.monotonic() < end:
+                    if not (composer.input_value() or "").strip():
+                        cleared = True
+                        break
+                    time.sleep(0.2)
+            except PlaywrightError:
+                pass
+        if not cleared:
+            raise ChatError(
+                "The message did not send. The composer still contains text; check the chat UI "
+                "with `dscli doctor`."
+            )
+        log.debug("Sent %d characters (new answer key was %s)", len(text), receipt.prev_key)
+        return receipt
+
+    # --------------------------------------------------------------- responses
+    def _snapshot(self) -> dict[str, Any]:
+        if self.page is None:
+            raise ChatError("Browser page is not available.")
+        return self.page.evaluate(
+            SNAPSHOT_JS,
+            {
+                "assistant": self.selectors["assistant_message"],
+                "item": self.selectors["chat_item"],
+                "send": self.selectors["send_button"],
+                "stop": self.selectors["stop"],
+                "composer": self._composer_css(),
+            },
+        )
+
+    def _extract_last_answer(self) -> str:
+        if self.page is None:
+            raise ChatError("Browser page is not available.")
+        data = self.page.evaluate(
+            EXTRACT_LAST_ANSWER_JS, self.selectors["assistant_message"]
+        )
+        if not data:
+            return ""
+        return (data.get("text") or "").strip()
+
+    def scroll_to_bottom(self) -> None:
+        if self.page is None:
+            return
+        try:
+            self.page.evaluate(SCROLL_TO_BOTTOM_JS)
+        except PlaywrightError:
+            pass
+
+    def _toasts(self) -> list[str]:
+        if self.page is None:
+            return []
+        try:
+            return list(self.page.evaluate(TOASTS_JS, self.selectors["notification"]) or [])
+        except PlaywrightError:
+            return []
+
+    def _error_toast(self) -> str | None:
+        for text in self._toasts():
+            if _ERROR_RE.search(text):
+                return text
+        return None
+
+    def wait_for_response(
+        self,
+        receipt: SendReceipt,
+        timeout_sec: float | None = None,
+        *,
+        on_reply_snapshot: Callable[[str], None] | None = None,
+    ) -> str:
+        timeout = float(timeout_sec or self.cfg.response_timeout_sec)
+        start = time.monotonic()
+        started = False
+        detected_key: str | None = None
+        started_at = start
+        last_text = ""
+        last_change = start
+        next_extract = 0.0
+        last_notice = start
+        scroll_at = 0.0
+        first_phase_deadline = start + min(
+            float(self.cfg.first_response_timeout_sec), timeout
+        )
+
+        while True:
+            now = time.monotonic()
+            elapsed = now - start
+            if elapsed > timeout:
+                message = (
+                    f"DeepSeek did not finish a response within {int(timeout)}s "
+                    f"(url: {self.page.url if self.page else '?'})."
+                )
+                raise ChatError(message, screenshot=self.save_screenshot("timeout"))
+
+            try:
+                if now >= scroll_at:
+                    self.scroll_to_bottom()
+                    scroll_at = now + 1.5
+                snap = self._snapshot()
+            except PlaywrightError as exc:
+                raise ChatError(f"The DeepSeek page became unavailable: {exc}") from exc
+
+            if not started:
+                new_answer = False
+                if receipt.prev_key is not None:
+                    new_answer = (
+                        snap.get("key") is not None
+                        and snap.get("key") != receipt.prev_key
+                    )
+                if (
+                    not new_answer
+                    and receipt.prev_key is not None
+                    and int(snap.get("count") or 0) > receipt.prev_count
+                    and not snap.get("seen")
+                ):
+                    new_answer = True
+                if receipt.prev_key is None:
+                    new_answer = int(snap.get("count") or 0) > receipt.prev_count
+                    if not new_answer and int(snap.get("count") or 0) > 0:
+                        new_answer = (
+                            not snap.get("seen")
+                            and (snap.get("preview") or "") != receipt.prev_preview
+                        )
+                if new_answer:
+                    started = True
+                    detected_key = snap.get("key")
+                    started_at = now
+                    last_change = now
+                    next_extract = 0.0
+                    log.debug("Response started (key=%s)", detected_key)
+                else:
+                    toast = self._error_toast()
+                    if toast:
+                        raise ChatError(
+                            f"DeepSeek reported an error: {toast}",
+                            screenshot=self.save_screenshot("error-toast"),
+                        )
+                    if now > first_phase_deadline:
+                        toasts = " | ".join(self._toasts())
+                        message = (
+                            "No assistant response appeared within "
+                            f"{int(self.cfg.first_response_timeout_sec)}s."
+                        )
+                        if toasts:
+                            message += f" Chat notices: {toasts}"
+                        raise ChatError(message, screenshot=self.save_screenshot("no-response"))
+
+            if started:
+                if (
+                    detected_key is not None
+                    and snap.get("key") is not None
+                    and snap.get("key") != detected_key
+                ):
+                    # A second assistant item for this turn appeared (for
+                    # example, reasoning followed by the final answer).
+                    log.debug(
+                        "Assistant item changed %s -> %s; waiting on the newer one.",
+                        detected_key,
+                        snap.get("key"),
+                    )
+                    detected_key = snap.get("key")
+                    started_at = now
+                    last_text = ""
+                    last_change = now
+                    next_extract = 0.0
+
+                if now >= next_extract:
+                    text = self._extract_last_answer()
+                    next_extract = now + 0.55
+                    if text != last_text:
+                        last_text = text
+                        last_change = now
+                        if on_reply_snapshot is not None:
+                            on_reply_snapshot(text)
+
+                if started and not last_text and now - started_at > 60:
+                    raise ChatError(
+                        "An assistant message appeared but contained no text after 60s.",
+                        screenshot=self.save_screenshot("empty-response"),
+                    )
+
+                if last_text:
+                    stable_for = now - last_change
+                    generating = bool(snap.get("stop")) or (
+                        snap.get("composerEmpty")
+                        and snap.get("sendPresent")
+                        and not snap.get("sendDisabled")
+                    )
+                    # The Read aloud / copy toolbar appears when DeepSeek has
+                    # finished a message. Requiring it (plus a stable stop
+                    # button) avoids treating a streaming pause as the end.
+                    complete = (
+                        stable_for >= self.cfg.stable_seconds
+                        and not generating
+                        and bool(snap.get("hasActions"))
+                    )
+                    if complete or stable_for >= self.cfg.fallback_stable_seconds:
+                        log.debug(
+                            "Response complete: %d chars, stable %.1fs, actions=%s, generating=%s",
+                            len(last_text),
+                            stable_for,
+                            snap.get("hasActions"),
+                            generating,
+                        )
+                        return last_text
+
+            if on_reply_snapshot is None and now - last_notice >= 25:
+                log.info("Still working... (%ds)", int(elapsed))
+                last_notice = now
+            if self.page is not None and self.page.is_closed():
+                raise ChatError("The DeepSeek tab was closed.")
+            time.sleep(0.35)
+
+    def send_and_wait(
+        self,
+        text: str,
+        *,
+        files: list[Path] | None = None,
+        timeout_sec: float | None = None,
+        on_reply_snapshot: Callable[[str], None] | None = None,
+    ) -> str:
+        receipt = self.send(text, files=files)
+        return self.wait_for_response(
+            receipt, timeout_sec, on_reply_snapshot=on_reply_snapshot
+        )
+
+    def stop_generation(self, timeout_ms: int = 2000) -> bool:
+        """Best-effort click on DeepSeek's stop control; never touches send."""
+        if self.page is None or self.page.is_closed():
+            return False
+        try:
+            locator = self.page.locator(self.selectors["stop"])
+            for index in range(min(locator.count(), 5)):
+                item = locator.nth(index)
+                try:
+                    if not item.is_visible():
+                        continue
+                    label = " ".join(
+                        filter(
+                            None,
+                            (
+                                item.get_attribute("aria-label"),
+                                item.get_attribute("data-testid"),
+                                item.get_attribute("title"),
+                            ),
+                        )
+                    )
+                    if not re.search(r"\bstop\b|停止", label, re.IGNORECASE):
+                        continue
+                    item.click(timeout=timeout_ms)
+                    log.debug("Stopped DeepSeek generation.")
+                    return True
+                except PlaywrightError:
+                    continue
+        except Exception:
+            return False
+        return False
+
+    # --------------------------------------------------------------- debugging
+    def save_screenshot(self, tag: str) -> str | None:
+        if self.page is None:
+            return None
+        try:
+            target = debug_dir() / f"{time.strftime('%Y%m%d-%H%M%S')}-{tag}.png"
+            self.page.screenshot(path=str(target), full_page=False)
+            log.warning("Saved screenshot: %s", target)
+            return str(target)
+        except Exception:
+            return None
+
+    def save_last_response(self, text: str, tag: str = "response") -> str | None:
+        try:
+            target = debug_dir() / f"{time.strftime('%Y%m%d-%H%M%S')}-{tag}.txt"
+            target.write_text(text, encoding="utf-8")
+            log.debug("Saved raw output: %s", target)
+            return str(target)
+        except OSError:
+            return None
+
+    def diagnostics(self) -> dict[str, Any]:
+        if self.context is None:
+            raise BrowserError("Browser not started.")
+        self._find_composer()
+        if self.page is None:
+            raise BrowserError("No page available.")
+        result = self.page.evaluate(
+            DIAGNOSTICS_JS,
+            {
+                "composer": self._composer_css(),
+                "send": self.selectors["send_button"],
+                "assistant": self.selectors["assistant_message"],
+                "fileInput": self.selectors["file_input"],
+                "cloudflare": self.selectors["cloudflare"],
+                "notification": self.selectors["notification"],
+                "toggle": self.selectors["toggle"],
+            },
+        )
+        toggles = []
+        try:
+            loc = self.page.locator(self.selectors["toggle"])
+            for i in range(loc.count()):
+                item = loc.nth(i)
+                toggles.append(
+                    {
+                        "text": (item.inner_text() or "").strip(),
+                        "pressed": (item.get_attribute("aria-pressed") or "") == "true",
+                    }
+                )
+        except PlaywrightError:
+            pass
+        result["toggles"] = toggles
+        result["newChatMatches"] = [
+            label
+            for label in ("New chat", "New Chat", "新对话")
+            if self.page.get_by_text(label, exact=True).count() > 0
+        ]
+        result["profile"] = self.cfg.profile_dir
+        result["chrome_session"] = self._chrome_session
+        result["headless"] = self.headless
+        return result
+
+    def test_roundtrip(self) -> str:
+        self.new_chat()
+        self.set_modes()
+        prompt = (
+            "[CONNECTIVITY TEST]\n"
+            "This is a test from the local dscli harness. Reply with exactly one word: pong"
+        )
+        return self.send_and_wait(prompt, timeout_sec=120)
+
+
+# Keep a reference so type checkers do not complain about the unused import.
+_ = Page