agent-webview 0.1.0__py3-none-any.whl

agent_webview/__init__.py

@@ -0,0 +1,3 @@
+"""Agent 控制的 pywebview 调试服务。"""
+
+__version__ = "0.1.0"

agent_webview/__main__.py

@@ -0,0 +1,4 @@
+from agent_webview.cli import main
+
+if __name__ == "__main__":
+    main()

agent_webview/auth.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import secrets
+from collections.abc import Callable
+
+from fastapi import Header, HTTPException, status
+
+
+def bearer_auth(expected_token: str) -> Callable[..., None]:
+    def authenticate(authorization: str | None = Header(default=None)) -> None:
+        scheme, _, token = (authorization or "").partition(" ")
+        if scheme.lower() != "bearer" or not secrets.compare_digest(token, expected_token):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="令牌缺失或无效",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    return authenticate

agent_webview/bridge.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import Event, Lock
+from typing import Any
+from uuid import uuid4
+
+from agent_webview.errors import (
+    BrowserCommandError,
+    BrowserCommandTimeoutError,
+    BrowserNotReadyError,
+)
+from agent_webview.events import EventBuffer
+from agent_webview.js import command_script
+
+
+@dataclass
+class _PendingResult:
+    event: Event
+    payload: dict[str, Any] | None = None
+
+
+class AgentBridge:
+    def __init__(self, events: EventBuffer) -> None:
+        self.events = events
+        self.window: Any = None
+        self.ready = Event()
+        self._command_lock = Lock()
+        self._pending_lock = Lock()
+        self._pending: dict[str, _PendingResult] = {}
+
+    def attach_window(self, window: Any) -> None:
+        self.window = window
+
+    def execute(self, code: str, *, expression: bool, timeout: float) -> Any:
+        if not self.window or not self.ready.wait(min(timeout, 5)):
+            raise BrowserNotReadyError("页面尚未就绪")
+
+        request_id = uuid4().hex
+        pending = _PendingResult(event=Event())
+        with self._pending_lock:
+            self._pending[request_id] = pending
+
+        try:
+            with self._command_lock:
+                try:
+                    self.window.run_js(
+                        command_script(request_id, code, expression=expression)
+                    )
+                except Exception as error:
+                    raise BrowserCommandError(
+                        "脚本发送失败",
+                        details={"name": type(error).__name__},
+                    ) from error
+                if not pending.event.wait(timeout):
+                    raise BrowserCommandTimeoutError(
+                        f"脚本执行超过 {timeout:g} 秒"
+                    )
+            payload = pending.payload or {}
+            if not payload.get("ok"):
+                error_details = payload.get("error") or {}
+                raise BrowserCommandError(
+                    error_details.get("message", "脚本执行失败"),
+                    details=error_details,
+                )
+            return payload.get("value")
+        finally:
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+
+    def agent_result(self, request_id: str, payload: dict[str, Any]) -> bool:
+        with self._pending_lock:
+            pending = self._pending.get(request_id)
+            if not pending:
+                return False
+            pending.payload = payload
+            pending.event.set()
+            return True
+
+    def agent_event(self, payload: dict[str, Any]) -> bool:
+        kind = str(payload.get("kind") or "page")
+        self.events.append(kind, payload)
+        return True
+
+
+class AgentApi:
+    def __init__(self, bridge: AgentBridge) -> None:
+        self._bridge = bridge
+
+    def agent_result(self, request_id: str, payload: dict[str, Any]) -> bool:
+        return self._bridge.agent_result(request_id, payload)
+
+    def agent_event(self, payload: dict[str, Any]) -> bool:
+        return self._bridge.agent_event(payload)

agent_webview/cli.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import argparse
+import ipaddress
+import os
+import secrets
+import signal
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import structlog
+import uvicorn
+from filelock import FileLock, Timeout
+from platformdirs import PlatformDirs
+
+from agent_webview.controller_api import create_controller_app
+from agent_webview.cookies import SnapshotStore
+from agent_webview.files import (
+    ensure_private_parent,
+    restrict_file_permissions,
+    write_private_json,
+)
+from agent_webview.logging import configure_logging
+from agent_webview.sessions import SessionManager
+
+log = structlog.get_logger(__name__)
+
+
+class RuntimeFileInUseError(RuntimeError):
+    """运行信息文件已被其他控制器占用。"""
+
+
+def _port(value: str) -> int:
+    try:
+        port = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("端口必须是整数") from error
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("端口必须在 1 到 65535 之间")
+    return port
+
+
+def _is_loopback_host(host: str) -> bool:
+    normalized = host.strip().strip("[]").rstrip(".").lower()
+    if normalized == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(normalized).is_loopback
+    except ValueError:
+        return False
+
+
+def _base_url(host: str, port: int) -> str:
+    normalized = host.strip().strip("[]")
+    try:
+        address = ipaddress.ip_address(normalized)
+        formatted = f"[{normalized}]" if address.version == 6 else normalized
+    except ValueError:
+        formatted = normalized
+    return f"http://{formatted}:{port}"
+
+
+@contextmanager
+def _claim_runtime_file(path: Path) -> Iterator[None]:
+    ensure_private_parent(path.parent)
+    lock = FileLock(f"{path}.lock")
+    try:
+        lock.acquire(timeout=0)
+    except Timeout as error:
+        raise RuntimeFileInUseError("运行信息文件已被其他服务占用") from error
+    restrict_file_permissions(Path(lock.lock_file))
+    try:
+        yield
+    finally:
+        lock.release()
+
+
+def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    directories = PlatformDirs("agent-webview", appauthor=False)
+    runtime_path = directories.user_runtime_path
+    parser = argparse.ArgumentParser(description="Agent Webview 调试服务")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=_port, default=8765)
+    parser.add_argument("--token", default=os.getenv("AGENT_WEBVIEW_TOKEN"))
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        default=directories.user_data_path,
+    )
+    parser.add_argument(
+        "--runtime-dir",
+        type=Path,
+        default=runtime_path / "sessions",
+    )
+    parser.add_argument(
+        "--runtime-file",
+        type=Path,
+        default=runtime_path / "controller.json",
+    )
+    parser.add_argument(
+        "--print-runtime-file",
+        action="store_true",
+        help="输出运行信息文件路径后退出",
+    )
+    parser.add_argument(
+        "--allow-remote",
+        action="store_true",
+        help="允许监听非本机地址",
+    )
+    parser.add_argument("--log-level", default="INFO")
+    parser.add_argument("--json-logs", action="store_true")
+    args = parser.parse_args(argv)
+    if not _is_loopback_host(args.host) and not args.allow_remote:
+        parser.error("监听非本机地址时必须显式指定 --allow-remote")
+    return args
+
+
+def _write_runtime_file(
+    path: Path,
+    *,
+    host: str,
+    port: int,
+    token: str,
+) -> None:
+    write_private_json(
+        path,
+        {
+            "pid": os.getpid(),
+            "base_url": _base_url(host, port),
+            "token": token,
+            "docs_url": f"{_base_url(host, port)}/docs",
+        },
+    )
+
+
+def _serve(args: argparse.Namespace, token: str, runtime_file: Path) -> None:
+    data_dir = args.data_dir.resolve()
+    manager = SessionManager(
+        runtime_dir=args.runtime_dir.resolve(),
+        snapshot_store=SnapshotStore(data_dir / "cookie-snapshots"),
+        log_level=args.log_level,
+        json_logs=args.json_logs,
+    )
+    original_handlers: dict[int, Any] = {}
+    try:
+        app = create_controller_app(manager, token)
+        _write_runtime_file(
+            runtime_file,
+            host=args.host,
+            port=args.port,
+            token=token,
+        )
+        log.info(
+            "服务已启动",
+            url=_base_url(args.host, args.port),
+            runtime_file=str(runtime_file),
+        )
+        server = uvicorn.Server(
+            uvicorn.Config(
+                app,
+                host=args.host,
+                port=args.port,
+                log_config=None,
+                log_level="critical",
+                access_log=False,
+            )
+        )
+
+        def defer_exit(signum: int, _: Any) -> None:
+            # 让 Uvicorn 返回后再清理敏感运行文件。
+            server.should_exit = True
+
+        handled_signals: list[int] = [int(signal.SIGINT), int(signal.SIGTERM)]
+        if hasattr(signal, "SIGBREAK"):
+            handled_signals.append(int(signal.SIGBREAK))
+        for handled_signal in handled_signals:
+            original_handlers[handled_signal] = signal.signal(
+                handled_signal,
+                defer_exit,
+            )
+        server.run()
+    finally:
+        try:
+            manager.close()
+        finally:
+            runtime_file.unlink(missing_ok=True)
+            for handled_signal, handler in original_handlers.items():
+                signal.signal(handled_signal, handler)
+            log.info("服务已停止")
+
+
+def main() -> None:
+    args = _parse_args()
+    if args.print_runtime_file:
+        print(args.runtime_file.resolve())
+        return
+    configure_logging(args.log_level, json_logs=args.json_logs)
+    token = args.token or secrets.token_urlsafe(32)
+    runtime_file = args.runtime_file.resolve()
+    try:
+        with _claim_runtime_file(runtime_file):
+            _serve(args, token, runtime_file)
+    except RuntimeFileInUseError:
+        log.error("运行信息文件已被其他服务占用", runtime_file=str(runtime_file))
+        raise SystemExit(2) from None
+
+
+if __name__ == "__main__":
+    main()

agent_webview/controller_api.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+import structlog
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Query
+from fastapi.responses import JSONResponse
+
+from agent_webview import __version__
+from agent_webview.auth import bearer_auth
+from agent_webview.http_errors import install_validation_handler
+from agent_webview.models import (
+    CookieRestoreRequest,
+    CookieSnapshot,
+    CookieSnapshotCreateRequest,
+    CookieSnapshotDeleteResponse,
+    CookieSnapshotListResponse,
+    DomClickRequest,
+    DomDispatchRequest,
+    DomInputRequest,
+    DomListenerRequest,
+    DomQueryRequest,
+    HealthResponse,
+    InstrumentationRequest,
+    JavaScriptRequest,
+    NavigateRequest,
+    SessionCreateRequest,
+    SessionDescription,
+    SessionDestroyResponse,
+    SessionListResponse,
+    WindowStatus,
+)
+from agent_webview.sessions import SessionManager, WorkerResponseError
+
+log = structlog.get_logger(__name__)
+
+
+def create_controller_app(manager: SessionManager, token: str) -> FastAPI:
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        yield
+        manager.close()
+
+    app = FastAPI(
+        title="Agent Webview",
+        version=__version__,
+        description="为 Agent 提供隔离的 pywebview 调试会话。",
+        lifespan=lifespan,
+    )
+    install_validation_handler(app)
+    router = APIRouter(prefix="/v1", dependencies=[Depends(bearer_auth(token))])
+
+    @app.get("/health", response_model=HealthResponse)
+    def health() -> dict[str, bool]:
+        return {"ok": True}
+
+    @app.exception_handler(KeyError)
+    async def missing_handler(_, __: KeyError) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": "会话不存在"})
+
+    @app.exception_handler(FileNotFoundError)
+    async def snapshot_handler(_, __: FileNotFoundError) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": "快照不存在"})
+
+    @app.exception_handler(ProcessLookupError)
+    async def process_handler(_, error: ProcessLookupError) -> JSONResponse:
+        return JSONResponse(status_code=410, content={"detail": str(error)})
+
+    @app.exception_handler(WorkerResponseError)
+    async def worker_handler(_, error: WorkerResponseError) -> JSONResponse:
+        return JSONResponse(status_code=error.status_code, content=error.detail)
+
+    @app.exception_handler(httpx.HTTPError)
+    async def network_handler(_, __: httpx.HTTPError) -> JSONResponse:
+        return JSONResponse(status_code=502, content={"detail": "子进程接口不可用"})
+
+    @app.exception_handler(Exception)
+    async def unknown_handler(_, error: Exception) -> JSONResponse:
+        log.error("接口执行失败", error_type=type(error).__name__)
+        return JSONResponse(status_code=500, content={"detail": "接口执行失败"})
+
+    def call(
+        session_id: str,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        body: Any = None,
+        timeout: float | None = None,
+    ) -> Any:
+        return manager.request(
+            manager.get(session_id),
+            method,
+            path,
+            params=params,
+            json_body=body,
+            timeout=timeout,
+        )
+
+    @router.get("/sessions", response_model=SessionListResponse)
+    def list_sessions() -> dict[str, Any]:
+        return {"sessions": manager.list()}
+
+    @router.post("/sessions", status_code=201, response_model=SessionDescription)
+    def create_session(request: SessionCreateRequest) -> dict[str, Any]:
+        return manager.create(request)
+
+    @router.get("/sessions/{session_id}", response_model=SessionDescription)
+    def get_session(session_id: str) -> dict[str, Any]:
+        return manager.describe(manager.get(session_id))
+
+    @router.delete("/sessions/{session_id}", response_model=SessionDestroyResponse)
+    def destroy_session(session_id: str) -> dict[str, Any]:
+        return manager.destroy(session_id)
+
+    @router.post("/sessions/{session_id}/window/show", response_model=WindowStatus)
+    def show_window(session_id: str) -> dict[str, Any]:
+        return call(session_id, "POST", "/v1/window/show")
+
+    @router.post("/sessions/{session_id}/window/hide", response_model=WindowStatus)
+    def hide_window(session_id: str) -> dict[str, Any]:
+        return call(session_id, "POST", "/v1/window/hide")
+
+    @router.post("/sessions/{session_id}/navigate")
+    def navigate(session_id: str, request: NavigateRequest) -> dict[str, Any]:
+        return call(session_id, "POST", "/v1/navigate", body=request.model_dump())
+
+    @router.post("/sessions/{session_id}/javascript/evaluate")
+    def evaluate(
+        session_id: str,
+        request: JavaScriptRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/javascript/evaluate",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post("/sessions/{session_id}/javascript/execute")
+    def execute(
+        session_id: str,
+        request: JavaScriptRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/javascript/execute",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post("/sessions/{session_id}/dom/query")
+    def dom_query(session_id: str, request: DomQueryRequest) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/dom/query",
+            body=request.model_dump(),
+        )
+
+    @router.post("/sessions/{session_id}/dom/click")
+    def dom_click(session_id: str, request: DomClickRequest) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/dom/click",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post("/sessions/{session_id}/dom/input")
+    def dom_input(session_id: str, request: DomInputRequest) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/dom/input",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post("/sessions/{session_id}/dom/dispatch")
+    def dom_dispatch(
+        session_id: str,
+        request: DomDispatchRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/dom/dispatch",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post("/sessions/{session_id}/dom/listeners")
+    def add_listener(
+        session_id: str,
+        request: DomListenerRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/dom/listeners",
+            body=request.model_dump(),
+        )
+
+    @router.delete("/sessions/{session_id}/dom/listeners/{listener_id}")
+    def remove_listener(session_id: str, listener_id: str) -> dict[str, Any]:
+        return call(
+            session_id,
+            "DELETE",
+            f"/v1/dom/listeners/{listener_id}",
+        )
+
+    @router.put("/sessions/{session_id}/instrumentation")
+    def instrumentation(
+        session_id: str,
+        request: InstrumentationRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "PUT",
+            "/v1/instrumentation",
+            body=request.model_dump(),
+        )
+
+    @router.get("/sessions/{session_id}/events")
+    def events(
+        session_id: str,
+        after: int = Query(default=0, ge=0),
+        limit: int = Query(default=200, ge=1, le=1000),
+        kinds: str | None = None,
+        timeout: float = Query(default=0, ge=0, le=30),
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "GET",
+            "/v1/events",
+            params={
+                "after": after,
+                "limit": limit,
+                "kinds": kinds,
+                "timeout": timeout,
+            },
+            timeout=timeout + 5,
+        )
+
+    @router.delete("/sessions/{session_id}/events")
+    def clear_events(session_id: str) -> dict[str, Any]:
+        return call(session_id, "DELETE", "/v1/events")
+
+    @router.get("/sessions/{session_id}/cookies")
+    def get_cookies(session_id: str) -> dict[str, Any]:
+        return call(session_id, "GET", "/v1/cookies")
+
+    @router.delete("/sessions/{session_id}/cookies")
+    def clear_cookies(session_id: str) -> dict[str, Any]:
+        return call(session_id, "DELETE", "/v1/cookies")
+
+    @router.post("/sessions/{session_id}/cookies/restore")
+    def restore_cookies(
+        session_id: str,
+        request: CookieRestoreRequest,
+    ) -> dict[str, Any]:
+        return call(
+            session_id,
+            "POST",
+            "/v1/cookies/restore",
+            body=request.model_dump(),
+            timeout=request.timeout + 5,
+        )
+
+    @router.post(
+        "/sessions/{session_id}/cookie-snapshots",
+        status_code=201,
+        response_model=CookieSnapshot,
+    )
+    def create_snapshot(
+        session_id: str,
+        request: CookieSnapshotCreateRequest,
+    ) -> dict[str, Any]:
+        result = call(session_id, "GET", "/v1/cookies")
+        return manager.snapshot_store.save(
+            session_id=session_id,
+            url=result.get("url"),
+            cookies=result.get("cookies", []),
+            name=request.name,
+        )
+
+    @router.get("/cookie-snapshots", response_model=CookieSnapshotListResponse)
+    def list_snapshots() -> dict[str, Any]:
+        return {"snapshots": manager.snapshot_store.list()}
+
+    @router.get(
+        "/cookie-snapshots/{snapshot_id}",
+        response_model=CookieSnapshot,
+    )
+    def get_snapshot(snapshot_id: str) -> dict[str, Any]:
+        try:
+            return manager.snapshot_store.get(snapshot_id)
+        except FileNotFoundError as error:
+            raise HTTPException(status_code=404, detail="快照不存在") from error
+
+    @router.delete(
+        "/cookie-snapshots/{snapshot_id}",
+        response_model=CookieSnapshotDeleteResponse,
+    )
+    def delete_snapshot(snapshot_id: str) -> dict[str, Any]:
+        try:
+            manager.snapshot_store.delete(snapshot_id)
+        except FileNotFoundError as error:
+            raise HTTPException(status_code=404, detail="快照不存在") from error
+        return {"deleted": True, "snapshot_id": snapshot_id}
+
+    app.include_router(router)
+    return app