browscreen 0.2.1__py3-none-any.whl

browscreen/__init__.py

@@ -0,0 +1,5 @@
+"""浏览器画面与鼠标指针预览服务。"""
+
+from importlib.metadata import version
+
+__version__ = version(distribution_name="browscreen")

browscreen/adapters/__init__.py

@@ -0,0 +1 @@
+"""浏览器与协议适配器。"""

browscreen/adapters/base.py

@@ -0,0 +1,39 @@
+"""公共浏览器契约，不包含具体协议字段。"""
+
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict, Field, FiniteFloat
+
+
+class BrowserAdapterError(RuntimeError):
+    """连接、页面或截图操作失败的统一错误。"""
+
+
+class BrowserScreenshot(BaseModel):
+    """与 CSS 视口对应的原始 PNG。
+
+    图片有效性由公共合成流程解码验证。
+    """
+
+    model_config = ConfigDict(frozen=True)
+    png_bytes: bytes = Field(min_length=1)
+    css_viewport_width: FiniteFloat = Field(gt=0)
+    css_viewport_height: FiniteFloat = Field(gt=0)
+
+
+class BrowserAdapter(Protocol):
+    """外部浏览器的连接、视口采集和自身资源释放契约。"""
+
+    endpoint_file_name: str
+
+    async def connect(self, *, endpoint: str, timeout_s: float) -> None:
+        """在总预算内连接并选择已有可截图页面。"""
+        ...
+
+    async def capture_viewport(self, *, timeout_s: float) -> BrowserScreenshot:
+        """在总预算内返回未合成指针的当前视口。"""
+        ...
+
+    async def disconnect(self) -> None:
+        """释放自身资源；不关闭外部浏览器或页面。"""
+        ...

browscreen/adapters/chrome_cdp.py

@@ -0,0 +1,132 @@
+"""通过原生 CDP 连接已有 Chrome 页面。"""
+
+import asyncio
+import base64
+import json
+from urllib.parse import urlsplit
+
+import httpx
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import WebSocketException
+
+from browscreen.adapters.base import BrowserAdapterError, BrowserScreenshot
+
+
+def validate_endpoint(*, endpoint: str) -> str:
+    """校验 HTTP 调试根入口或 Chrome WebSocket 地址。
+
+    :returns: 地址类型，http、browser 或 page。
+    :raises BrowserAdapterError: 地址不符合首版协议。
+    """
+    try:
+        parsed = urlsplit(url=endpoint)
+        if not parsed.hostname or any(character.isspace() for character in endpoint):
+            raise ValueError("地址缺少主机或包含空白")
+        if parsed.port is not None and not 1 <= parsed.port <= 65535:
+            raise ValueError("端口无效")
+        if parsed.scheme in {"http", "https"} and parsed.path in {"", "/"} and not parsed.query and not parsed.fragment:
+            return "http"
+        if parsed.scheme in {"ws", "wss"} and not parsed.fragment:
+            for kind in ("browser", "page"):
+                prefix = f"/devtools/{kind}/"
+                if parsed.path.startswith(prefix) and parsed.path[len(prefix):]:
+                    return kind
+        raise ValueError("需要 HTTP(S) 调试根地址或浏览器／页面 WebSocket 地址")
+    except ValueError as error:
+        raise BrowserAdapterError(f"无效 Chrome 端点：{error}") from error
+
+
+class ChromeCdpAdapter:
+    """封装 Chrome 端点发现、会话与顺序命令响应。
+
+    :param client: 应用生命周期拥有的共享 HTTP 客户端。
+    """
+
+    endpoint_file_name = ".cdp"
+
+    def __init__(self, *, client: httpx.AsyncClient) -> None:
+        self.client = client
+        self.websocket: ClientConnection | None = None
+        self.session_id: str | None = None
+        self.command_id = 0
+
+    async def connect(self, *, endpoint: str, timeout_s: float) -> None:
+        """在一个总预算内发现端点、连接并附着首个已有页面。"""
+        try:
+            async with asyncio.timeout(delay=timeout_s):
+                kind = validate_endpoint(endpoint=endpoint)
+                if kind == "http":
+                    response = await self.client.get(url=f"{endpoint.rstrip('/')}/json/version", timeout=timeout_s)
+                    response.raise_for_status()
+                    endpoint = response.json()["webSocketDebuggerUrl"]
+                    kind = validate_endpoint(endpoint=endpoint)
+                    if kind == "http":
+                        raise BrowserAdapterError("发现结果不是 WebSocket 地址")
+                self.websocket = await connect(uri=endpoint, open_timeout=timeout_s, close_timeout=1, max_size=None, proxy=None)
+                if kind == "browser":
+                    targets = await self._command(method="Target.getTargets")
+                    target = next((item for item in targets["targetInfos"] if item.get("type") == "page"), None)
+                    if target is None:
+                        raise BrowserAdapterError("浏览器没有已有页面")
+                    attached = await self._command(method="Target.attachToTarget", params={"targetId": target["targetId"], "flatten": True})
+                    self.session_id = attached["sessionId"]
+        except (httpx.HTTPError, httpx.InvalidURL, WebSocketException, OSError, TimeoutError, ValueError, KeyError, TypeError) as error:
+            raise BrowserAdapterError(f"Chrome 连接失败：{error}") from error
+
+    async def _command(self, *, method: str, params: dict | None = None) -> dict:
+        """顺序发送命令并过滤事件、其他编号与其他会话响应。"""
+        if self.websocket is None:
+            raise BrowserAdapterError("Chrome 尚未连接")
+        self.command_id += 1
+        command = {"id": self.command_id, "method": method, "params": params or {}}
+        if self.session_id is not None:
+            command["sessionId"] = self.session_id
+        await self.websocket.send(message=json.dumps(obj=command))
+        while True:
+            message = json.loads(s=await self.websocket.recv())
+            if not isinstance(message, dict):
+                raise BrowserAdapterError("CDP 响应不是对象")
+            if message.get("method") == "Target.detachedFromTarget" and message.get("params", {}).get("sessionId") == self.session_id:
+                raise BrowserAdapterError("Chrome 页面调试会话已断开")
+            if message.get("method") == "Inspector.detached" and message.get("sessionId") == self.session_id:
+                raise BrowserAdapterError("Chrome 页面已断开")
+            if message.get("id") != self.command_id:
+                continue
+            if message.get("sessionId") != self.session_id and not ("error" in message and "sessionId" not in message):
+                continue
+            if "error" in message:
+                raise BrowserAdapterError(f"CDP {method} 失败：{message['error']}")
+            result = message.get("result", {})
+            if not isinstance(result, dict):
+                raise BrowserAdapterError("CDP 结果不是对象")
+            return result
+
+    async def capture_viewport(self, *, timeout_s: float) -> BrowserScreenshot:
+        """在一个总预算内测量 CSS 视口并抓取当前 PNG。"""
+        try:
+            async with asyncio.timeout(delay=timeout_s):
+                metrics = await self._command(method="Runtime.evaluate", params={
+                    "expression": "({width: window.innerWidth, height: window.innerHeight})",
+                    "returnByValue": True,
+                })
+                viewport = metrics["result"]["value"]
+                screenshot = await self._command(method="Page.captureScreenshot", params={
+                    "format": "png", "fromSurface": True, "captureBeyondViewport": False,
+                })
+                return BrowserScreenshot(
+                    png_bytes=base64.b64decode(s=screenshot["data"], validate=True),
+                    css_viewport_width=viewport["width"],
+                    css_viewport_height=viewport["height"],
+                )
+        except (WebSocketException, OSError, TimeoutError, ValueError, KeyError, TypeError) as error:
+            raise BrowserAdapterError(f"Chrome 截图失败：{error}") from error
+
+    async def disconnect(self) -> None:
+        """关闭自身 WebSocket，保留浏览器和已有页面。"""
+        websocket, self.websocket = self.websocket, None
+        self.session_id = None
+        if websocket is not None:
+            try:
+                await websocket.close()
+            except (WebSocketException, OSError) as error:
+                raise BrowserAdapterError(f"Chrome 连接释放失败：{error}") from error

browscreen/app.py

@@ -0,0 +1,93 @@
+"""FastAPI 生命周期、只读图片预览和 webhook 注册。"""
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from importlib.resources import files
+
+import httpx
+from fastapi import FastAPI, Response
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from browscreen import __version__
+from browscreen.adapters.base import BrowserAdapter
+from browscreen.adapters.chrome_cdp import ChromeCdpAdapter
+from browscreen.capture import CaptureService
+from browscreen.files import clear_mouse
+from browscreen.models import ErrorResponse, Settings, WebhookRegistration
+
+logger = logging.getLogger(__name__)
+ADAPTER_FACTORIES = {"chrome-cdp": ChromeCdpAdapter}
+
+
+def create_app(*, settings: Settings, adapter: BrowserAdapter | None = None, client: httpx.AsyncClient | None = None) -> FastAPI:
+    """创建实例；注入的适配器和客户端也由该实例负责释放。
+
+    :param settings: 经校验的启动配置。
+    :param adapter: 测试或集成可注入符合公共契约的适配器。
+    :param client: 测试可注入 HTTP 客户端；默认直接连接端点和接收器。
+    :returns: 含一个后台采集任务的应用。
+    """
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        http_client = client if client is not None else httpx.AsyncClient(timeout=3, follow_redirects=False, trust_env=False)
+        browser = adapter if adapter is not None else ADAPTER_FACTORIES[settings.adapter](client=http_client)
+        service = CaptureService(settings=settings, adapter=browser, client=http_client)
+        app.state.capture = service
+
+        async def capture() -> None:
+            """立即报告未预期的任务异常，并停止提供旧图。"""
+            try:
+                await service.run()
+            except Exception:
+                service.current_frame = None
+                service.state = "failed"
+                logger.exception("采集任务异常停止")
+                await service.disconnect()
+
+        task = asyncio.create_task(coro=capture(), name="browscreen-capture")
+        try:
+            yield
+        finally:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                logger.exception("采集任务退出时报告错误")
+            await service.disconnect()
+            try:
+                await http_client.aclose()
+            except Exception:
+                logger.exception("HTTP 客户端关闭失败")
+            finally:
+                await asyncio.to_thread(clear_mouse, path=settings.work_dir / ".mouse")
+
+    app = FastAPI(title="browscreen", version=__version__, lifespan=lifespan)
+    preview = files(anchor="browscreen").joinpath("preview.html").read_text(encoding="utf-8").replace("__INTERVAL_MS__", str(settings.interval_ms))
+
+    @app.get("/", response_class=HTMLResponse)
+    async def index() -> HTMLResponse:
+        """返回按配置间隔读取同一最新帧的只读页面。"""
+        return HTMLResponse(content=preview, headers={"Cache-Control": "no-store"})
+
+    @app.get("/api/screenshot", response_class=Response, responses={200: {"content": {"image/png": {}}}, 503: {"model": ErrorResponse}})
+    async def screenshot() -> Response:
+        """读取一次完整帧引用，返回 PNG 或明确的不可用状态。"""
+        service = app.state.capture
+        frame = service.current_frame
+        if frame is None:
+            return JSONResponse(content=service.unavailable_error().model_dump(), status_code=503, headers={"Cache-Control": "no-store"})
+        return Response(content=frame.png_bytes, media_type="image/png", headers={"Cache-Control": "no-store", **frame.headers})
+
+    @app.post("/api/webhooks", status_code=201)
+    async def register(registration: WebhookRegistration, response: Response) -> dict[str, str | bool]:
+        """规范化去重，只参与注册后的新帧。"""
+        url = str(registration.url)
+        urls = app.state.capture.webhooks
+        response.status_code = 200 if url in urls else 201
+        urls.add(url)
+        return {"url": url, "registered": True}
+
+    return app

browscreen/capture.py

@@ -0,0 +1,116 @@
+"""公共连接等待、单循环采集和最新帧发布。"""
+
+import asyncio
+import logging
+from asyncio import sleep
+from datetime import UTC, datetime
+from time import monotonic
+
+import httpx
+
+from browscreen.adapters.base import BrowserAdapter, BrowserAdapterError
+from browscreen.files import read_endpoint, read_mouse
+from browscreen.imaging import compose_screenshot
+from browscreen.models import CurrentFrame, ErrorResponse, Settings
+from browscreen.webhooks import push_frame
+
+logger = logging.getLogger(__name__)
+OPERATION_TIMEOUT_S = 5
+
+
+class CaptureService:
+    """驱动任意符合契约的浏览器适配器。
+
+    :param settings: 实例配置。
+    :param adapter: 已由应用选定的适配器。
+    :param client: 应用拥有的共享 HTTP 客户端。
+    """
+
+    def __init__(self, *, settings: Settings, adapter: BrowserAdapter, client: httpx.AsyncClient) -> None:
+        self.settings = settings
+        self.adapter = adapter
+        self.client = client
+        self.state = "waiting"
+        self.current_frame: CurrentFrame | None = None
+        self.frame_id = 0
+        self.webhooks: set[str] = set()
+        self.failed_webhooks: set[str] = set()
+
+    def unavailable_error(self) -> ErrorResponse:
+        """生成当前无图片状态的公共响应。"""
+        if self.state == "failed":
+            return ErrorResponse(code="capture_failed", message="采集任务异常停止，请检查服务日志后重启")
+        if self.state == "timed_out":
+            return ErrorResponse(code="browser_wait_timeout", message="等待浏览器连接超时，请修正端点后重启服务")
+        if self.state == "connected":
+            return ErrorResponse(code="screenshot_not_ready", message="浏览器已连接，正在生成首帧")
+        return ErrorResponse(code="waiting_for_browser", message="正在等待浏览器端点可用")
+
+    async def disconnect(self, *, timeout_s: float = 1) -> None:
+        """限时释放自身连接，清理失败记录日志。"""
+        try:
+            async with asyncio.timeout(delay=timeout_s):
+                await self.adapter.disconnect()
+        except Exception:
+            logger.exception("浏览器适配器连接清理失败")
+
+    async def _wait_for_browser(self, *, deadline: float) -> bool:
+        """沿用本轮恢复截止时间，每次重试重新读文件。"""
+        self.state = "waiting"
+        path = self.settings.work_dir / self.adapter.endpoint_file_name
+        logger.debug(msg=f"等待浏览器端点：{path}，本轮剩余 {max(0, deadline - monotonic()):.3f} 秒")
+        while (remaining := deadline - monotonic()) > 0:
+            try:
+                async with asyncio.timeout(delay=remaining):
+                    endpoint = await asyncio.to_thread(read_endpoint, path=path)
+                remaining = deadline - monotonic()
+                if endpoint and remaining > 0:
+                    budget = min(OPERATION_TIMEOUT_S, remaining)
+                    async with asyncio.timeout(delay=budget):
+                        await self.adapter.connect(endpoint=endpoint, timeout_s=budget)
+                    self.state = "connected"
+                    logger.debug("浏览器已连接")
+                    return True
+            except (BrowserAdapterError, TimeoutError) as error:
+                logger.debug(msg=f"浏览器暂不可用：{error!r}")
+                await self.disconnect(timeout_s=max(0, min(1, deadline - monotonic())))
+            await sleep(delay=min(self.settings.interval_ms / 1000, max(0, deadline - monotonic())))
+        self.state = "timed_out"
+        logger.warning("等待浏览器连接超时，停止采集与端点轮询")
+        return False
+
+    async def run(self) -> None:
+        """顺序采集、发布和发送；失效时清空缓存并重新等待。"""
+        deadline = monotonic() + self.settings.connect_wait_timeout_s
+        logger.info(msg=f"开始等待浏览器画面，等待上限 {self.settings.connect_wait_timeout_s:g} 秒")
+        while await self._wait_for_browser(deadline=deadline):
+            try:
+                while True:
+                    started = monotonic()
+                    timestamp = datetime.now(tz=UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+                    # 首个有效帧产出前，连接、文件读取和图片合成共用恢复预算。
+                    remaining = None if deadline is None else max(0, deadline - monotonic())
+                    async with asyncio.timeout(delay=remaining):
+                        mouse = await asyncio.to_thread(read_mouse, path=self.settings.work_dir / ".mouse")
+                        budget = OPERATION_TIMEOUT_S if deadline is None else max(0, min(OPERATION_TIMEOUT_S, deadline - monotonic()))
+                        async with asyncio.timeout(delay=budget):
+                            screenshot = await self.adapter.capture_viewport(timeout_s=budget)
+                        png = await asyncio.to_thread(compose_screenshot, screenshot=screenshot, mouse=mouse)
+                    if deadline is not None:
+                        logger.info("浏览器画面已就绪" if self.frame_id == 0 else "浏览器画面已恢复")
+                    deadline = None
+                    self.frame_id += 1
+                    frame = CurrentFrame(frame_id=self.frame_id, capture_started_at=timestamp, png_bytes=png)
+                    urls = tuple(self.webhooks)
+                    self.current_frame = frame
+                    await push_frame(client=self.client, urls=urls, frame=frame, failed_urls=self.failed_webhooks)
+                    await sleep(delay=max(0, self.settings.interval_ms / 1000 - (monotonic() - started)))
+            except (BrowserAdapterError, TimeoutError) as error:
+                self.current_frame = None
+                self.state = "waiting"
+                if deadline is None:
+                    logger.warning(msg=f"浏览器采集失效，开始恢复：{error!r}")
+                    deadline = monotonic() + self.settings.connect_wait_timeout_s
+                logger.debug(msg=f"浏览器采集失败：{error!r}")
+                await self.disconnect(timeout_s=max(0, min(1, deadline - monotonic())))
+                await sleep(delay=min(self.settings.interval_ms / 1000, max(0, deadline - monotonic())))

browscreen/files.py

@@ -0,0 +1,54 @@
+"""工作目录文件的读取与退出清理。"""
+
+import logging
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from browscreen.models import MousePosition
+
+logger = logging.getLogger(__name__)
+
+
+def read_endpoint(*, path: Path) -> str | None:
+    """读取固定端点文件中的单行文本。
+
+    :returns: 去除 BOM 与空白的文本；不可读、空值或多行时返回 None。
+    """
+    try:
+        content = path.read_text(encoding="utf-8-sig").strip()
+    except (OSError, UnicodeError):
+        return None
+    if not content or len(content.splitlines()) != 1:
+        return None
+    return content
+
+
+def read_mouse(*, path: Path) -> MousePosition | None:
+    """读取本轮坐标，不保留上一轮的有效值。
+
+    :returns: 有限数值坐标；不可读或格式无效时返回 None。
+    """
+    try:
+        parts = path.read_text(encoding="utf-8-sig").strip().split(",")
+        if len(parts) != 2:
+            return None
+        return MousePosition(x=parts[0].strip(), y=parts[1].strip())
+    except (OSError, UnicodeError, ValidationError):
+        return None
+
+
+def clear_mouse(*, path: Path) -> None:
+    """退出时截断已有坐标文件，缺失时不创建。
+
+    清理失败记录路径与原因，避免影响其他退出清理。
+    """
+    try:
+        with path.open(mode="r+b") as stream:
+            stream.truncate(0)
+    except FileNotFoundError:
+        return
+    except OSError:
+        logger.exception(msg=f"无法清空鼠标坐标文件：{path}")
+    else:
+        logger.debug(msg=f"已清空鼠标坐标文件：{path}")

browscreen/imaging.py

@@ -0,0 +1,46 @@
+"""视口 PNG 校验与透明鼠标指针合成。"""
+
+from functools import cache
+from importlib.resources import files
+from io import BytesIO
+
+from PIL import Image, UnidentifiedImageError
+
+from browscreen.adapters.base import BrowserAdapterError, BrowserScreenshot
+from browscreen.models import MousePosition
+
+# PNG 像素单位；箭头尖端位于资源图的 (1, 1)。
+CURSOR_HOTSPOT = (1, 1)
+
+
+@cache
+def _cursor_image() -> Image.Image:
+    with files(anchor="browscreen").joinpath("assets/cursor.png").open(mode="rb") as stream:
+        with Image.open(fp=stream) as image:
+            return image.convert(mode="RGBA")
+
+
+def compose_screenshot(*, screenshot: BrowserScreenshot, mouse: MousePosition | None) -> bytes:
+    """验证原始 PNG，按实际 PNG／CSS 比例叠加本轮指针。
+
+    :returns: 当前视口 PNG；无有效视口内坐标时保留原始字节。
+    :raises BrowserAdapterError: 原始截图不是可解码的 PNG。
+    """
+    try:
+        with Image.open(fp=BytesIO(initial_bytes=screenshot.png_bytes)) as source:
+            if source.format != "PNG":
+                raise BrowserAdapterError("适配器截图必须为 PNG")
+            source.load()
+            if mouse is None or not (0 <= mouse.x < screenshot.css_viewport_width and 0 <= mouse.y < screenshot.css_viewport_height):
+                return screenshot.png_bytes
+            image = source.convert(mode="RGBA")
+        point = (
+            round(mouse.x * image.width / screenshot.css_viewport_width) - CURSOR_HOTSPOT[0],
+            round(mouse.y * image.height / screenshot.css_viewport_height) - CURSOR_HOTSPOT[1],
+        )
+        image.alpha_composite(im=_cursor_image(), dest=point)
+        output = BytesIO()
+        image.save(fp=output, format="PNG")
+        return output.getvalue()
+    except (UnidentifiedImageError, OSError, ValueError) as error:
+        raise BrowserAdapterError(f"PNG 解码或合成失败：{error}") from error

browscreen/main.py

@@ -0,0 +1,59 @@
+"""命令行参数与单进程服务入口。"""
+
+import argparse
+import logging
+
+import uvicorn
+from pydantic import ValidationError
+
+from browscreen import __version__
+from browscreen.app import create_app
+from browscreen.models import Settings
+
+
+def parse_settings(*, argv: list[str] | None = None) -> Settings:
+    """解析并校验命令行配置。
+
+    :param argv: 参数列表；None 表示读取进程参数。
+    :returns: 已校验的实例配置。
+    """
+    parser = argparse.ArgumentParser(description="browscreen 浏览器画面与鼠标指针预览")
+    parser.add_argument("command", nargs="?", choices=["version"], help="查询版本；省略时启动服务")
+    parser.add_argument("--version", action="version", version=f"browscreen {__version__}", help="显示版本并退出")
+    parser.add_argument("-v", "--verbose", action="store_true", help="开启 DEBUG 日志和 HTTP 访问日志")
+    parser.add_argument("--work-dir", help="启动服务必填：已有的文件交换工作目录")
+    parser.add_argument("--adapter", default="chrome-cdp", help="浏览器适配器（chrome-cdp）")
+    parser.add_argument("--interval-ms", type=int, default=300, help="截图与端点重试间隔（毫秒）")
+    parser.add_argument("--connect-wait-timeout-s", type=float, default=60, help="每轮等待首个有效帧的上限（秒）")
+    parser.add_argument("--host", default="127.0.0.1", help="HTTP 监听地址（默认 127.0.0.1）")
+    parser.add_argument("--port", type=int, default=8000, help="HTTP 端口（默认 8000）")
+    arguments = parser.parse_args(args=argv)
+    if arguments.command == "version":
+        print(f"browscreen {__version__}")
+        parser.exit()
+    if arguments.work_dir is None:
+        parser.error(message="启动服务必须提供 --work-dir")
+    del arguments.command
+    try:
+        return Settings(**vars(arguments))
+    except ValidationError as error:
+        parser.error(message=str(error))
+
+
+def configure_logging(*, verbose: bool) -> None:
+    """配置服务日志，默认省略第三方库的逐请求日志。
+
+    :param verbose: 是否开启 DEBUG 诊断日志。
+    """
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(level=level, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+    for name in ("httpx", "httpcore", "websockets", "PIL"):
+        logging.getLogger(name=name).setLevel(level=level if verbose else logging.WARNING)
+
+
+def main() -> None:
+    """处理命令，或启动一个 worker 和一个采集循环。"""
+    settings = parse_settings()
+    configure_logging(verbose=settings.verbose)
+    uvicorn.run(app=create_app(settings=settings), host=settings.host, port=settings.port, workers=1,
+                log_level="debug" if settings.verbose else "info", access_log=settings.verbose)

browscreen/models.py

@@ -0,0 +1,71 @@
+"""启动配置、文件数据与 HTTP 数据契约。"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, FiniteFloat, HttpUrl, field_validator
+
+
+class Settings(BaseModel):
+    """校验实例的工作目录与启动参数。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    work_dir: Path
+    adapter: Literal["chrome-cdp"] = "chrome-cdp"
+    interval_ms: int = Field(default=300, gt=0)
+    connect_wait_timeout_s: float = Field(default=60, gt=0, allow_inf_nan=False)
+    host: str = Field(default="127.0.0.1", min_length=1)
+    port: int = Field(default=8000, ge=1, le=65535)
+    verbose: bool = False
+
+    @field_validator("work_dir", mode="before")
+    @classmethod
+    def validate_work_dir(cls, value: str | Path) -> Path:
+        """将已有工作目录转换为绝对路径。
+
+        :raises ValueError: 路径不存在或不是目录。
+        """
+        path = Path(value).expanduser().resolve()
+        if not path.is_dir():
+            raise ValueError(f"工作目录不存在或不是目录：{path}")
+        return path
+
+
+class MousePosition(BaseModel):
+    """以当前 CSS 视口左上角为原点的有限坐标。"""
+
+    model_config = ConfigDict(frozen=True)
+    x: FiniteFloat
+    y: FiniteFloat
+
+
+class WebhookRegistration(BaseModel):
+    """注册接收后续 PNG 新帧的 HTTP(S) 地址。"""
+
+    url: HttpUrl
+
+
+class ErrorResponse(BaseModel):
+    """截图不可用时的公共错误响应。"""
+
+    code: Literal["waiting_for_browser", "screenshot_not_ready", "browser_wait_timeout", "capture_failed"]
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentFrame:
+    """一次性发布的完整合成帧，避免图片与元数据交叉。"""
+
+    frame_id: int
+    capture_started_at: str
+    png_bytes: bytes
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """返回图片接口和 webhook 共用的帧元数据。"""
+        return {
+            "X-Frame-Id": str(self.frame_id),
+            "X-Capture-Started-At": self.capture_started_at,
+        }

browscreen/preview.html

@@ -0,0 +1,139 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>browscreen · 浏览器画面预览</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { margin: 0; background: #f3f4f6; color: #202632; font-family: system-ui, sans-serif; }
+    header { max-width: 1320px; margin: auto; padding: 24px 20px 16px; }
+    h1 { margin: 0 0 6px; font-size: 24px; letter-spacing: -.5px; }
+    p { margin: 4px 0; font-size: 14px; color: #5c6575; }
+    #status { color: #303b50; }
+    main { max-width: 1320px; margin: auto; padding: 0 20px 24px; }
+    img { display: block; width: 100%; height: auto; background: white; border-radius: 6px; box-shadow: 0 2px 16px #16233a14; }
+    [hidden] { display: none !important; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>browscreen</h1>
+    <p>浏览器画面预览 · 只读</p>
+    <p id="status" role="status" aria-live="polite">正在等待浏览器端点可用</p>
+    <p id="metadata"></p>
+  </header>
+  <main><img id="preview" alt="浏览器当前视口画面" hidden></main>
+  <script>
+    const intervalMs = __INTERVAL_MS__;
+    const preview = document.getElementById('preview');
+    const status = document.getElementById('status');
+    const metadata = document.getElementById('metadata');
+    const messages = {
+      waiting_for_browser: '正在等待浏览器端点可用',
+      screenshot_not_ready: '浏览器已连接，正在生成首帧',
+      browser_wait_timeout: '等待浏览器连接超时，请修正端点后重启服务',
+      capture_failed: '采集任务异常停止，请检查服务日志后重启'
+    };
+    const requestTimeoutMs = 5000;
+    let currentUrl = null;
+    let currentFrameKey = null;
+    let activeRequest = null;
+    let timer = null;
+    let stopped = false;
+
+    function clearPreview() {
+      preview.hidden = true;
+      preview.removeAttribute('src');
+      if (currentUrl) URL.revokeObjectURL(currentUrl);
+      currentUrl = null;
+      currentFrameKey = null;
+      metadata.textContent = '';
+    }
+
+    function loadImage(url, signal) {
+      return new Promise((resolve, reject) => {
+        const image = new Image();
+        function finish(error) {
+          image.onload = null;
+          image.onerror = null;
+          signal.removeEventListener('abort', abort);
+          if (error) {
+            image.removeAttribute('src');
+            reject(error);
+          } else {
+            resolve();
+          }
+        }
+        function abort() { finish(signal.reason); }
+        image.onload = () => finish();
+        image.onerror = () => finish(new Error('图片加载失败，将自动重试'));
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) abort();
+        else image.src = url;
+      });
+    }
+
+    async function poll() {
+      if (stopped || activeRequest) return;
+      const controller = new AbortController();
+      activeRequest = controller;
+      const timeout = setTimeout(() => {
+        controller.abort(new Error('预览请求超时，将自动重试'));
+      }, requestTimeoutMs);
+      let nextUrl = null;
+      try {
+        const response = await fetch('/api/screenshot', { cache: 'no-store', signal: controller.signal });
+        if (!response.ok) {
+          const error = await response.json();
+          throw new Error(messages[error.code] || '预览暂时不可用，将自动重试');
+        }
+        const frameId = response.headers.get('X-Frame-Id');
+        const startedAt = response.headers.get('X-Capture-Started-At');
+        const frameKey = frameId && startedAt ? `${frameId}/${startedAt}` : null;
+        const blob = await response.blob();
+        controller.signal.throwIfAborted();
+        // 帧号与时间共同判断，服务重启后仍接受较小或重复的帧号。
+        if (frameKey && frameKey === currentFrameKey && currentUrl) return;
+        nextUrl = URL.createObjectURL(blob);
+        await loadImage(nextUrl, controller.signal);
+        controller.signal.throwIfAborted();
+        preview.src = nextUrl;
+        if (currentUrl) URL.revokeObjectURL(currentUrl);
+        currentUrl = nextUrl;
+        currentFrameKey = frameKey;
+        nextUrl = null;
+        preview.hidden = false;
+        status.textContent = '画面持续更新';
+        metadata.textContent = `第 ${frameId} 帧 · 采集开始 ${startedAt}`;
+      } catch (error) {
+        // 离开页面的取消不覆盖恢复后的状态；网络超时仍显示明确提示。
+        const failure = controller.signal.aborted ? controller.signal.reason : error;
+        if (!stopped && failure.name !== 'AbortError') {
+          clearPreview();
+          status.textContent = failure.message;
+        }
+      } finally {
+        clearTimeout(timeout);
+        if (nextUrl) URL.revokeObjectURL(nextUrl);
+        activeRequest = null;
+        if (!stopped) timer = setTimeout(poll, intervalMs);
+      }
+    }
+    window.addEventListener('pagehide', () => {
+      stopped = true;
+      clearTimeout(timer);
+      activeRequest?.abort();
+      clearPreview();
+    });
+    window.addEventListener('pageshow', event => {
+      if (!event.persisted || !stopped) return;
+      stopped = false;
+      status.textContent = '正在恢复预览';
+      // 在途请求先完成取消清理，再由其 finally 调度，避免并行轮询。
+      if (!activeRequest) poll();
+    });
+    poll();
+  </script>
+</body>
+</html>

browscreen/webhooks.py

@@ -0,0 +1,36 @@
+"""逐帧并发发送，无图片队列和历史回放。"""
+
+import asyncio
+import logging
+
+import httpx
+
+from browscreen.models import CurrentFrame
+
+logger = logging.getLogger(__name__)
+WEBHOOK_TIMEOUT_S = 3
+
+
+async def push_frame(*, client: httpx.AsyncClient, urls: tuple[str, ...], frame: CurrentFrame, failed_urls: set[str]) -> None:
+    """向本帧地址快照各尝试发送一次，等待全部尝试结束。
+
+    :param frame: 与图片接口共用的完整 PNG 帧。
+    :param failed_urls: 跨帧保留的失败地址，仅在首次失败和恢复时输出常规日志。
+    """
+    async def send(*, url: str) -> None:
+        try:
+            async with asyncio.timeout(delay=WEBHOOK_TIMEOUT_S):
+                response = await client.post(url=url, content=frame.png_bytes, headers={
+                    "Content-Type": "image/png", **frame.headers,
+                }, timeout=WEBHOOK_TIMEOUT_S, follow_redirects=False)
+                response.raise_for_status()
+        except (httpx.HTTPError, TimeoutError) as error:
+            log = logger.debug if url in failed_urls else logger.warning
+            log(msg=f"webhook 发送失败，帧 {frame.frame_id}，地址 {url}：{error!r}")
+            failed_urls.add(url)
+        else:
+            if url in failed_urls:
+                failed_urls.remove(url)
+                logger.info(msg=f"webhook 发送已恢复，地址 {url}")
+
+    await asyncio.gather(*(send(url=url) for url in urls))

browscreen-0.2.1.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: browscreen
+Version: 0.2.1
+Summary: 浏览器视口截图与鼠标指针预览服务
+Project-URL: Homepage, https://github.com/Pegasus-Yang/Browscreen
+Project-URL: Documentation, https://github.com/Pegasus-Yang/Browscreen/blob/main/doc/README.md
+Project-URL: Repository, https://github.com/Pegasus-Yang/Browscreen
+Project-URL: Issues, https://github.com/Pegasus-Yang/Browscreen/issues
+Author-email: Pegasus-Yang <panesas2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastapi<1,>=0.118
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pillow<13,>=12
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: uvicorn<1,>=0.37
+Requires-Dist: websockets<18,>=15
+Description-Content-Type: text/markdown
+
+# browscreen
+
+[![Python](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+简体中文 | [English](README.en.md)
+
+浏览器画面与鼠标指针预览服务。browscreen（browser＋screen）通过 Chrome DevTools Protocol（CDP）连接已有 Chrome，将当前视口截图和外部提供的指针坐标合成 PNG，用于网页预览、图片接口和 webhook 推送。
+
+## 功能
+
+- 默认每 300 毫秒采集当前视口，网页、图片接口和 webhook 共用最新帧。
+- 读取工作目录的 `.cdp` 连接浏览器，读取 `.mouse` 在 CSS 视口坐标上合成指针。
+- 浏览器失效后清空旧图，在限定时间内重读端点并恢复采集。
+- 正常退出时清空已有 `.mouse`，保留 `.cdp` 和外部浏览器。
+
+服务采用 Python 3.14、FastAPI 和 Pydantic v2，一个进程运行一个采集循环。浏览器启动、页面导航和环境隔离由调用方管理；预览页只读，不转发鼠标或键盘操作。
+
+## 安装
+
+准备 `uv` 和 Python 3.14，从 GitHub 获取源码后安装：
+
+```sh
+git clone https://github.com/Pegasus-Yang/Browscreen.git
+cd Browscreen
+uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/browscreen version
+```
+
+需要安装 Python 时先执行 `uv python install 3.14`。当前安装方式为源码或自行构建的 wheel；详见[安装与运行](doc/deployment/安装与运行.md)。
+
+## 快速开始
+
+准备一个已有工作目录，以及启用了远程调试、包含打开页面的 Chrome。将实际调试地址写入 `.cdp`：
+
+```sh
+work_dir="/absolute/path/to/workspace"
+printf '%s\n' 'http://127.0.0.1:9222' > "$work_dir/.cdp"
+uv run --no-sync browscreen --work-dir "$work_dir"
+```
+
+打开 `http://127.0.0.1:8000/` 查看画面。另一个终端向同一目录的 `.mouse` 写入 `320,180`，即可在下一个新帧显示指针。工作目录和 Chrome 由外部系统准备，示例路径和端口需按实际环境替换。
+
+`.cdp` 尚未可用时 HTTP 保持可访问，默认等待 60 秒，等待预算持续到首个有效 PNG 生成。超时后修正端点并重启服务。
+
+## 命令行
+
+安装后提供一个 `browscreen` 命令。在源码安装环境中，可通过 `.venv/bin/browscreen` 或 `uv run --no-sync browscreen` 调用。
+
+| 命令 | 用途 |
+| --- | --- |
+| `browscreen --help` | 查看全部命令与参数 |
+| `browscreen version` / `browscreen --version` | 查询安装版本并退出，无需工作目录 |
+| `browscreen --work-dir <目录>` | 启动服务，默认 INFO 日志 |
+| `browscreen -v --work-dir <目录>` | 启动服务并开启 DEBUG 和 HTTP 访问日志 |
+
+默认省略网页轮询、HTTPX 请求和重复重试细节；状态变化、超时及异常仍会记录。同一 webhook 连续失败仅首次告警，恢复后记录一次；每帧仍按原规则发送。完整参数与日志说明见[命令行参考](doc/reference/命令行.md)。
+
+## HTTP 接口
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /` | 只读网页预览 |
+| `GET /api/screenshot` | 最新合成 PNG，附带帧编号、UTC 采集开始时间和 `no-store` |
+| `POST /api/webhooks` | 注册 HTTP(S) 接收地址，向后续新帧发送 PNG |
+
+截图与发送顺序执行，每帧向所有接收地址并发尝试一次。慢 webhook 会降低采集频率，每次发送最多等待 3 秒；失败不自动重试、不跟随重定向。注册保留至进程退出。协议与错误码见[使用说明](doc/user-guide/使用说明.md)。
+
+## 文档
+
+- [安装与运行](doc/deployment/安装与运行.md)：环境、安装、启动、退出和构建。
+- [命令行参考](doc/reference/命令行.md)：命令、参数和日志级别。
+- [使用说明](doc/user-guide/使用说明.md)：文件协议、预览、图片和 webhook。
+- [文档导航](doc/README.md)：完整阅读路线和技术设计。
+- [版本变动历史](changelog.md)：各版本的新增、变更和修复。
+
+## 开发与贡献
+
+开发环境需要 Node.js 22 或更高版本，以运行预览脚本回归，无需 npm 依赖：
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+```
+
+默认测试使用模拟浏览器端点；真实 Chrome 验证需要另行执行。缺少 Node.js 时预览测试会跳过，不代表前端验证通过。
+
+问题和建议请提交到 [GitHub Issues](https://github.com/Pegasus-Yang/Browscreen/issues)。提交改动前请阅读[贡献指南](CONTRIBUTING.md)。项目由 [Pegasus-Yang](https://github.com/Pegasus-Yang) 维护。
+
+## 许可证
+
+项目采用 [MIT 许可证](LICENSE)。

browscreen-0.2.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+browscreen/__init__.py,sha256=c9ZjBrjgrPlR-vYDtrZbUbfZdXFSXqwYS51BdQW1EDU,147
+browscreen/app.py,sha256=DNLJCpqucxxzRnWhFhQ_-goULs2xmXN6QA-_n_HcIFE,4210
+browscreen/capture.py,sha256=fftE8taWAp-kiUl0uIPgU6d3I8ti9ZqjFYU-cZm4CRc,6353
+browscreen/files.py,sha256=D2vPKrEQeEMpLTfvRiMLSoiOf49bFtFMv2uPUlpITnA,1608
+browscreen/imaging.py,sha256=o4WzZ9sbk7-29sdoY3welKKqR98qj8jfEzesen_sJ-I,1955
+browscreen/main.py,sha256=g9C8dosRxktol64vgmGxzUyXsd3obgeZQOcHs8XvPk0,2832
+browscreen/models.py,sha256=SCC8mH-UEjcFVR2c4rpsdZB0eQMbGw4SSNZ3Srz8WDs,2113
+browscreen/preview.html,sha256=0t5j94mT1xqNOol8dVWYB7WSZzhOTJurp_Wr9JQOZUw,5481
+browscreen/webhooks.py,sha256=aPre8KK71q9ZCKWF4uiFWoxQYbnTfIyyC1p5ZqP9lfM,1464
+browscreen/adapters/__init__.py,sha256=er4JIFNF9x0jR4Eusol-Ug5L2-3uccvWWUHbsvGquCc,37
+browscreen/adapters/base.py,sha256=uJYxpEZgGw7VJuUtflbZO8Lgo8rlxUiHu9-Ov3pVAwA,1182
+browscreen/adapters/chrome_cdp.py,sha256=NV2Bsq6LcNkzKI_JzwVmZDjUA01JZUNLNlL5W6-BQ5Y,6870
+browscreen/assets/cursor.png,sha256=vKJdVu3DgZvw8O9b3WIhprIQSb-ws6BTFkK3DbMGYnw,237
+browscreen-0.2.1.dist-info/METADATA,sha256=Kxh8L3amfRWN2usqShD-qiyT9XtS0QY6YwOGIGERnZY,5537
+browscreen-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+browscreen-0.2.1.dist-info/entry_points.txt,sha256=wthOnavN86RDgc50wLBoJqfMZ9iqHLwFEp_4KntcVoY,52
+browscreen-0.2.1.dist-info/licenses/LICENSE,sha256=wCZOJAWha2auh_hNgp_oUGgM46r6IShZFiWh-lguKKY,1069
+browscreen-0.2.1.dist-info/RECORD,,

browscreen-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

browscreen-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+browscreen = browscreen.main:main

browscreen-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pegasus-Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.