rpa-core-runtime 0.1.0__py3-none-any.whl

rpa_core/__init__.py

@@ -0,0 +1,3 @@
+"""Typed, executor-oriented RPA core."""
+
+__version__ = "0.1.0"

rpa_core/bsk_client.py

@@ -0,0 +1,126 @@
+"""bsk CLI 子进程客户端（能力层，M14）。
+
+`bsk` = BrowserSkill（Tencent/BrowserSkill）Rust CLI/daemon。本模块是 rpa_core
+对 bsk 的唯一子进程入口：devserver 捕获会话与运行期执行器共用，避免协议分叉。
+
+协议：`bsk --json <cmd> ...` → stdout JSON；失败形态 `{"code":..., "message":...}`
+或非零退出码 + stderr。`runner` 可注入（测试无真实浏览器）。
+"""
+
+import json
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+DEFAULT_BSK_BINARY = str(Path.home() / ".local" / "bin" / "bsk.exe")
+
+Runner = Callable[..., dict]
+
+
+class BskError(RuntimeError):
+    """bsk 子协议失败（携带 daemon 返回的 code/message）。"""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(f"{code}: {message}")
+        self.code = code
+
+
+class BskSessionGoneError(BskError):
+    """bsk session 已失效（浏览器被关 / session 被 stop / 浏览器掉线）。"""
+
+
+_GONE_CODES = {"not_found", "session_not_found"}
+
+
+class BskClient:
+    def __init__(self, *, bsk_binary: str | None = None, runner: Runner | None = None):
+        self._bsk_binary = bsk_binary or DEFAULT_BSK_BINARY
+        self._runner = runner
+
+    def run(self, *args: str) -> dict:
+        if self._runner is not None:
+            payload = self._runner(*args)
+            self._raise_for_error(payload, exit_code=0)
+            return payload
+        proc = subprocess.run(
+            [self._bsk_binary, "--json", *args],
+            capture_output=True, text=True, timeout=60, encoding="utf-8",
+        )
+        out = proc.stdout.strip()
+        try:
+            payload = json.loads(out) if out else {}
+        except json.JSONDecodeError:
+            raise BskError("protocol_error", proc.stderr.strip() or out) from None
+        self._raise_for_error(
+            payload, exit_code=proc.returncode, stderr=proc.stderr.strip(), raw=out
+        )
+        return payload
+
+    def _raise_for_error(
+        self, payload: dict, *, exit_code: int, stderr: str = "", raw: str = ""
+    ) -> None:
+        if not isinstance(payload, dict):
+            return  # 数组载荷（如 tab list）无错误通道
+        if exit_code == 0 and not payload.get("code"):
+            return
+        code = str(payload.get("code") or f"exit_{exit_code}")
+        message = str(payload.get("message") or stderr or raw)
+        if code in _GONE_CODES:
+            raise BskSessionGoneError(code, message)
+        raise BskError(code, message)
+
+    # -- 常用命令封装 --------------------------------------------------------
+
+    def session_start(self, browser_instance_id: str | None = None) -> str:
+        args = ["session", "start"]
+        if browser_instance_id:
+            args += ["--browser", browser_instance_id]
+        payload = self.run(*args)
+        session_id = payload.get("session_id")
+        if not session_id:
+            raise BskError("protocol_error", f"no session_id in {payload}")
+        return str(session_id)
+
+    def session_stop(self, session_id: str) -> None:
+        self.run("session", "stop", session_id)
+
+    def evaluate(self, session_id: str, expression: str, *, timeout: str = "30s",
+                 tab_id: str | None = None):
+        args = ["evaluate", "--session", session_id, "--timeout", timeout]
+        if tab_id:
+            args += ["--tab-id", str(tab_id)]
+        payload = self.run(*args, expression)
+        return payload.get("value")
+
+    def navigate(self, session_id: str, url: str) -> str:
+        payload = self.run("navigate", "--session", session_id, url)
+        return str(payload.get("final_url") or payload.get("url") or url)
+
+    def click(self, session_id: str, selector: str, *, modifiers: str = "") -> None:
+        args = ["click", "--session", session_id, "--selector", selector]
+        if modifiers:
+            args += ["--modifiers", modifiers]
+        self.run(*args)
+
+    def fill(self, session_id: str, selector: str, text: str) -> None:
+        self.run(
+            "fill", "--session", session_id, "--selector", selector, "--text", text
+        )
+
+    def browsers(self) -> list[dict]:
+        payload = self.run("browsers")
+        return payload if isinstance(payload, list) else []
+
+    def tab_list(self, session_id: str, *, scope: str = "user") -> list[dict]:
+        payload = self.run("tab", "list", "--session", session_id, "--scope", scope)
+        if isinstance(payload, list):
+            return payload
+        return payload.get("tabs", []) if isinstance(payload, dict) else []
+
+    def tab_borrow(self, session_id: str, tab_id: str) -> dict:
+        """借用用户标签页进 Agent Window（返回含 tab_id/original_window_id）。"""
+        return self.run("tab", "borrow", "--session", session_id, str(tab_id))
+
+    def tab_return(self, session_id: str, tab_id: str) -> None:
+        """归还借用标签页到原窗口原位置。"""
+        self.run("tab", "return", "--session", session_id, str(tab_id))

rpa_core/capture/__init__.py

@@ -0,0 +1,13 @@
+from .browser import BrowserCaptureSession
+from .browser_bsk import BrowserBskCaptureSession
+from .desktop import DesktopCaptureSession
+from .extension import ExtensionCaptureSession
+from .hybrid import HybridCaptureSession
+
+__all__ = [
+    "BrowserCaptureSession",
+    "BrowserBskCaptureSession",
+    "DesktopCaptureSession",
+    "ExtensionCaptureSession",
+    "HybridCaptureSession",
+]

rpa_core/capture/browser.py

@@ -0,0 +1,300 @@
+"""浏览器元素捕获会话（M10）。
+
+两种传输（docs/capture-transport.md §3）：
+- persistent: launch_persistent_context 专用 profile（M10a 主路线）
+- user-browser: chrome-inspect-ws —— 读取日常浏览器 User Data 下的
+  DevToolsActivePort 文件构造 WS URL，connect_over_cdp 挂真实浏览器（M10b，S1 已验证）
+
+捕获交互：注入 picker（hover 高亮 + 点击采集），点击后生成 CSS selector
+并在页面内回验命中数；cancel 会清理注入并结束等待。
+"""
+
+import asyncio
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+_PICKER_JS = r"""
+() => {
+  if (window.__rpaCapture) return true;
+  window.__rpaCaptureResult = undefined;
+  const box = document.createElement('div');
+  box.style.cssText = 'position:fixed;pointer-events:none;border:2px solid #0969da;'
+    + 'background:rgba(9,105,218,.12);z-index:2147483647;border-radius:4px;display:none;';
+  document.documentElement.appendChild(box);
+  function uniqueIn(sel) {
+    try { return document.querySelectorAll(sel).length === 1; } catch (e) { return false; }
+  }
+  function nthOf(el) {
+    const parent = el.parentElement;
+    if (!parent) return '';
+    const same = Array.from(parent.children).filter((c) => c.tagName === el.tagName);
+    return same.length > 1 ? ':nth-of-type(' + (same.indexOf(el) + 1) + ')' : '';
+  }
+  function buildSelector(el) {
+    if (el.id) {
+      const sel = '#' + CSS.escape(el.id);
+      if (uniqueIn(sel)) return sel;
+    }
+    const nameAttr = el.getAttribute && el.getAttribute('name');
+    if (nameAttr) {
+      const sel = el.tagName.toLowerCase() + '[name="' + nameAttr + '"]';
+      if (uniqueIn(sel)) return sel;
+    }
+    const parts = [];
+    let cur = el;
+    let guard = 0;
+    while (cur && cur.nodeType === 1 && cur !== document.documentElement && guard < 12) {
+      if (cur.id) {
+        const withId = '#' + CSS.escape(cur.id)
+          + (parts.length ? ' > ' + parts.join(' > ') : '');
+        if (uniqueIn(withId)) return withId;
+      }
+      parts.unshift(cur.tagName.toLowerCase() + nthOf(cur));
+      const cand = parts.join(' > ');
+      if (parts.length >= 2 && uniqueIn(cand)) return cand;
+      cur = cur.parentElement;
+      guard += 1;
+    }
+    return 'body > ' + parts.join(' > ');
+  }
+  function describe(el) {
+    const selector = buildSelector(el);
+    let count = 0;
+    try { count = document.querySelectorAll(selector).length; } catch (e) { count = 0; }
+    const rect = el.getBoundingClientRect();
+    return {
+      selector: selector,
+      verifyCount: count,
+      tag: el.tagName.toLowerCase(),
+      id: el.id || '',
+      classes: typeof el.className === 'string' ? el.className : '',
+      text: ((el.innerText || el.textContent || '').trim()).slice(0, 120),
+      rect: { x: Math.round(rect.x), y: Math.round(rect.y),
+              w: Math.round(rect.width), h: Math.round(rect.height) },
+    };
+  }
+  function onOver(e) {
+    const rect = e.target.getBoundingClientRect();
+    box.style.display = 'block';
+    box.style.top = rect.top + 'px';
+    box.style.left = rect.left + 'px';
+    box.style.width = rect.width + 'px';
+    box.style.height = rect.height + 'px';
+  }
+  function onClick(e) {
+    e.preventDefault();
+    e.stopPropagation();
+    finish(e.target);
+  }
+  function onKey(e) { if (e.key === 'Escape') finish(null); }
+  function cleanup() {
+    box.remove();
+    document.removeEventListener('mouseover', onOver, true);
+    document.removeEventListener('click', onClick, true);
+    document.removeEventListener('keydown', onKey, true);
+    window.__rpaCaptureCleanup = undefined;
+    window.__rpaCapture = undefined;
+  }
+  function finish(el) {
+    cleanup();
+    window.__rpaCaptureResult = el ? describe(el) : 'cancelled';
+  }
+  document.addEventListener('mouseover', onOver, true);
+  document.addEventListener('click', onClick, true);
+  document.addEventListener('keydown', onKey, true);
+  window.__rpaCaptureCleanup = cleanup;
+  window.__rpaCapture = true;
+  return true;
+}
+"""
+
+_CANCEL_JS = r"""
+() => {
+  if (window.__rpaCaptureCleanup) window.__rpaCaptureCleanup();
+  window.__rpaCaptureResult = 'cancelled';
+}
+"""
+
+_DONE_JS = "() => window.__rpaCaptureResult !== undefined"
+_RESULT_JS = "() => window.__rpaCaptureResult"
+_CLEANUP_JS = "() => { if (window.__rpaCaptureCleanup) window.__rpaCaptureCleanup(); }"
+
+_BROWSER_DATA_DIRS = {
+    "edge": "Microsoft/Edge/User Data",
+    "chrome": "Google/Chrome/User Data",
+}
+
+
+def devtools_active_port_url(browser_type: str = "edge", user_data_dir: str | None = None) -> str:
+    """从 DevToolsActivePort 文件构造 WS URL（S1 结论：无需 UI 交互）。"""
+    if user_data_dir:
+        base = Path(user_data_dir)
+    else:
+        key = browser_type if browser_type in _BROWSER_DATA_DIRS else "edge"
+        base = Path(os.environ.get("LOCALAPPDATA", "")) / _BROWSER_DATA_DIRS[key]
+    port_file = base / "DevToolsActivePort"
+    lines = port_file.read_text(encoding="utf-8").splitlines()
+    if len(lines) < 2:
+        raise RuntimeError(f"DevToolsActivePort file is malformed: {port_file}")
+    return f"ws://127.0.0.1:{lines[0].strip()}{lines[1].strip()}"
+
+
+class BrowserCaptureSession:
+    """带独立事件循环线程的浏览器捕获会话；pick/cancel 从任意线程调用。"""
+
+    def __init__(
+        self,
+        *,
+        transport: str,
+        user_data_dir: str | None = None,
+        headless: bool = False,
+        user_agent: str | None = None,
+        browser_type: str = "edge",
+        page_url: str | None = None,
+        start_url: str | None = None,
+    ):
+        self.transport = transport
+        self._config = {
+            "user_data_dir": user_data_dir,
+            "headless": headless,
+            "user_agent": user_agent,
+            "browser_type": browser_type,
+            "page_url": page_url,
+            "start_url": start_url,
+        }
+        self._cancelled = False
+        self._closed = False
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._loop.run_forever, daemon=True)
+
+    def _run(self, coro):
+        return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+
+    def start(self) -> list[str]:
+        self._thread.start()
+        return self._run(self._start_async())
+
+    async def _start_async(self) -> list[str]:
+        from playwright.async_api import async_playwright
+
+        self._playwright = await async_playwright().start()
+        config = self._config
+        if self.transport == "persistent":
+            user_data_dir = config["user_data_dir"] or str(
+                Path.home() / ".rpa_core" / "capture-profile"
+            )
+            kwargs: dict[str, Any] = {
+                "headless": bool(config["headless"]),
+                "ignore_default_args": ["--enable-automation"],
+            }
+            if config["user_agent"]:
+                kwargs["user_agent"] = config["user_agent"]
+            self._context = await self._playwright.chromium.launch_persistent_context(
+                user_data_dir, **kwargs
+            )
+            self._browser = None
+        else:
+            ws_url = devtools_active_port_url(
+                config["browser_type"], config["user_data_dir"]
+            )
+            self._browser = await self._playwright.chromium.connect_over_cdp(ws_url)
+            contexts = self._browser.contexts
+            self._context = contexts[0] if contexts else await self._browser.new_context()
+
+        pages = self._context.pages
+        page = None
+        if config["page_url"]:
+            for candidate in reversed(pages):
+                if config["page_url"] in candidate.url:
+                    page = candidate
+                    break
+        if page is None:
+            page = pages[-1] if pages else await self._context.new_page()
+        self._page = page
+        if config["start_url"]:
+            await page.goto(config["start_url"], wait_until="domcontentloaded")
+        return [candidate.url for candidate in pages]
+
+    @property
+    def page_url(self) -> str:
+        return self._page.url
+
+    def pick(self, timeout_seconds: float = 60.0, click_css: str | None = None) -> dict:
+        return self._run(self._pick_async(timeout_seconds, click_css))
+
+    async def _pick_async(self, timeout_seconds: float, click_css: str | None) -> dict:
+        await self._page.evaluate(_PICKER_JS)
+        if click_css:
+            async def click_later() -> None:
+                await self._page.wait_for_timeout(300)
+                try:
+                    await self._page.evaluate(
+                        "(sel) => { const el = document.querySelector(sel);"
+                        " if (el) el.dispatchEvent(new MouseEvent('click', {bubbles: true})); }",
+                        click_css,
+                    )
+                except Exception:
+                    pass
+
+            asyncio.ensure_future(click_later())
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            if self._cancelled or self._closed:
+                await self._safe(_CANCEL_JS)
+                return {"cancelled": True}
+            try:
+                await self._page.wait_for_function(_DONE_JS, timeout=500)
+            except Exception:
+                continue
+            data = await self._page.evaluate(_RESULT_JS)
+            await self._safe(_CLEANUP_JS)
+            if data == "cancelled":
+                return {"cancelled": True}
+            if not isinstance(data, dict):
+                continue
+            data["kind"] = "browser"
+            data["selector"] = {"css": data.get("selector")}
+            data["metadata"] = {
+                key: data.pop(key)
+                for key in ("tag", "id", "classes", "text", "rect")
+                if key in data
+            }
+            data["url"] = self._page.url
+            return data
+        await self._safe(_CLEANUP_JS)
+        return {"timeout": True}
+
+    async def _safe(self, expression: str) -> None:
+        try:
+            await self._page.evaluate(expression)
+        except Exception:
+            pass
+
+    def cancel(self) -> None:
+        self._cancelled = True
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._cancelled = True
+
+        async def _close_async() -> None:
+            try:
+                if getattr(self, "_browser", None) is not None:
+                    await self._browser.close()
+                elif getattr(self, "_context", None) is not None:
+                    await self._context.close()
+            except Exception:
+                pass
+            try:
+                await self._playwright.stop()
+            except Exception:
+                pass
+
+        if self._thread.is_alive():
+            self._run(_close_async())
+            self._loop.call_soon_threadsafe(self._loop.stop)