foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/browser/action/url_policy.py

@@ -0,0 +1,143 @@
+"""浏览器导航与请求的 URL 准入策略。
+
+背景:ActionExecutor 原本「只做翻译不做判断」,`navigate` 直接把模型给的字符串
+喂给 driver → 可被用来打 `file://`(读本机文件)、`javascript:`(在页面上下文执行)、
+`http://169.254.169.254`(云元数据)或内网地址(SSRF 探测)。
+
+两层,缺一不可:
+- `validate_navigate_url` —— 模型显式要求的导航目标(动作层)。
+- `validate_request_url`  —— 页面上**任何**网络请求:3xx 跳转后的新地址、iframe、
+  子资源(img/script/fetch)。只校验导航目标时,一个公网页面跳一次转、或塞一个
+  `<img src="http://169.254.169.254/latest/meta-data/">` 就绕过去了。
+
+默认 deny-by-default,允许内网时用 FOXCLAW_BROWSER_ALLOW_PRIVATE=1 显式放开。
+
+【残余风险 · DNS TOCTOU】本层校验时解析一次域名,浏览器之后会**自己再解析一次**。
+DNS rebinding 可以让第一次返回公网、第二次返回 127.0.0.1。彻底消除得在启动参数里
+把域名钉成 IP(Chromium `--host-resolver-rules`)或下沉到 CDP 层 —— Playwright 的
+route 回调拿不到「浏览器将要连接哪个 IP」。本层把风险从「整个会话不校验」收窄到
+「每次请求校验一次」,不声称消除。
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+import threading
+import time
+from urllib.parse import urlparse
+
+ALLOWED_SCHEMES = ("http", "https")
+
+INTERNAL_SCHEMES = ("data", "blob", "about")
+
+_RESOLVE_TTL = 60.0
+_MAX_CACHE = 512
+_resolve_cache: dict[str, tuple[bool, float]] = {}
+_resolve_lock = threading.Lock()
+
+
+def _allow_private() -> bool:
+    return os.environ.get("FOXCLAW_BROWSER_ALLOW_PRIVATE", "").strip() in ("1", "true", "yes")
+
+
+def _is_internal_ip(ip) -> bool:
+    return (ip.is_loopback or ip.is_private or ip.is_link_local
+            or ip.is_reserved or ip.is_multicast or ip.is_unspecified)
+
+
+def _resolve_internal(host: str) -> bool:
+    """域名是否解析到内网地址。解析失败按「未知」处理 → False(交给浏览器失败)。
+
+    不缓存失败结果:离线/瞬时 DNS 故障后恢复,没必要让页面一分钟内都起不来。
+    """
+    now = time.monotonic()
+    with _resolve_lock:
+        hit = _resolve_cache.get(host)
+        if hit is not None and hit[1] > now:
+            return hit[0]
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except OSError:
+        return False
+    internal = False
+    for info in infos:
+        addr = str(info[4][0]).split("%", 1)[0]
+        try:
+            parsed = ipaddress.ip_address(addr)
+        except ValueError:
+            continue
+        if _is_internal_ip(parsed):
+            internal = True
+            break
+    with _resolve_lock:
+        if len(_resolve_cache) >= _MAX_CACHE:
+            _resolve_cache.clear()
+        _resolve_cache[host] = (internal, now + _RESOLVE_TTL)
+    return internal
+
+
+def _deny_reason(host: str) -> str | None:
+    """host 命中本机/内网 → 返回拒绝原因;合法公网主机 → None。"""
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        ip = None
+    if ip is not None:
+        if _is_internal_ip(ip):
+            return (f"已拒绝内网/本机地址 {host}(如确需访问请设 "
+                    f"FOXCLAW_BROWSER_ALLOW_PRIVATE=1)")
+        return None
+
+    lowered = host.lower()
+    if lowered == "localhost" or lowered.endswith(".localhost"):
+        return "已拒绝本机域名 localhost(SSRF 防护)"
+    if _resolve_internal(host):
+        return f"已拒绝域名 {host}(解析到内网地址)"
+    return None
+
+
+def validate_navigate_url(url: str, allow_private: bool | None = None) -> str:
+    """校验并规范化导航目标;不合法抛 ValueError(调用方转成用户可读错误)。
+
+    允许:http/https + 公网主机。
+    拒绝:其它协议(file/javascript/data/blob…)、无主机、以及(默认)回环/私网/
+    链路本地/保留地址。域名会尝试解析一次以拦「域名指向内网」;解析失败不拦
+    (离线场景下页面本来也打不开,不该因此拒掉合法 URL)。
+    """
+    target = (url or "").strip()
+    if not target:
+        raise ValueError("导航目标为空")
+    parsed = urlparse(target)
+    scheme = (parsed.scheme or "").lower()
+    if scheme not in ALLOWED_SCHEMES:
+        raise ValueError(f"只允许 http/https 导航,已拒绝 {scheme or '(无协议)'}://")
+    host = (parsed.hostname or "").strip()
+    if not host:
+        raise ValueError("导航 URL 缺少主机名")
+    if allow_private is None:
+        allow_private = _allow_private()
+    if allow_private:
+        return target
+
+    reason = _deny_reason(host)
+    if reason:
+        raise ValueError(reason)
+    return target
+
+
+def validate_request_url(url: str, allow_private: bool | None = None) -> str:
+    """单个网络请求(子资源 / 跳转 / iframe)的准入。
+
+    与 `validate_navigate_url` 的唯一差别是豁免页面内部 scheme
+    (`data:` / `blob:` / `about:`):它们由页面自身产生、不经过网络栈。
+    其余规则完全一致 —— 跳转后的地址、iframe、img/script 都要过这一关。
+    """
+    target = (url or "").strip()
+    if not target:
+        raise ValueError("请求 URL 为空")
+    scheme = (urlparse(target).scheme or "").lower()
+    if scheme in INTERNAL_SCHEMES:
+        return target
+    return validate_navigate_url(target, allow_private)

package/python/foxclaw/browser/adapter/__init__.py

@@ -0,0 +1 @@
+"""适配器层：与 HIR-Kernel 约定的 WebAdapter 门面（Foxclaw 内改走 BrowserService）。"""

package/python/foxclaw/browser/adapter/base_adapter.py

@@ -0,0 +1,23 @@
+"""
+BaseAdapter —— 与 HIR v1.0 约定的 Adapter 接口保持一致，
+方便直接 `vm.register_adapter(WebAdapter())` 接入 HIR Kernel。
+
+如果你的 HIR Core 里已经有 hir.adapters.base.BaseAdapter，
+直接 import 那一份替换这里的定义即可，这里只是保证
+HIR-Browser 单独运行/测试时不依赖外部 HIR 包。
+"""
+
+from abc import ABC, abstractmethod
+
+
+class BaseAdapter(ABC):
+
+    @abstractmethod
+    def match(self, action: dict) -> bool:
+        """判断这个 Action Graph 节点是否应该由本 adapter 处理"""
+        ...
+
+    @abstractmethod
+    def execute(self, action: dict) -> dict:
+        """执行动作，返回归一化前的原始结果"""
+        ...

package/python/foxclaw/browser/adapter/web_adapter.py

@@ -0,0 +1,46 @@
+"""
+WebAdapter —— HIR-Browser 对外的 HIR-Kernel 门面（match/execute 约定）。
+
+HIR ExecutionVM 只认识这一个类。所有内部的
+perception/action/driver/session 复杂度都被封装在这里，
+不向 HIR Core 泄露任何实现细节。
+
+注意：在 Foxclaw 内，async 路由请走 BrowserService（专用线程 + async 包装），
+不要直接在事件循环线程里调用本类的 execute（Playwright sync API 会报错）。
+本类保留是为了与独立 HIR-Kernel 场景兼容。
+"""
+
+from .base_adapter import BaseAdapter
+from ..session.session_manager import SessionManager
+from ..action.action_types import WebAction, SUPPORTED_ACTIONS
+
+
+class WebAdapter(BaseAdapter):
+
+    def __init__(self, headless: bool = True):
+        self._session: "SessionManager | None" = None
+        self._headless = headless
+
+    def _ensure_session(self):
+        if self._session is None:
+            self._session = SessionManager(headless=self._headless)
+        return self._session
+
+    def match(self, action: dict) -> bool:
+        return action.get("type") in SUPPORTED_ACTIONS
+
+    def execute(self, action: dict) -> dict:
+        session = self._ensure_session()
+        web_action = WebAction.from_dict(action)
+        result = session.execute(web_action)
+
+        return {
+            "type": "web_adapter_result",
+            "action": action,
+            "data": result,
+        }
+
+    def close(self):
+        if self._session is not None:
+            self._session.close()
+            self._session = None

package/python/foxclaw/browser/driver/__init__.py

@@ -0,0 +1 @@
+"""驱动层：抽象 BaseDriver + 默认 PlaywrightDriver。playwright 为可选依赖，惰性导入。"""

package/python/foxclaw/browser/driver/base_driver.py

@@ -0,0 +1,61 @@
+"""
+BaseDriver —— 底层浏览器驱动的抽象接口。
+
+driver 层的职责边界：只负责"怎么操纵一个真实浏览器"，
+不关心语义压缩、不关心动作校验、不关心 Action Graph。
+
+现在提供 PlaywrightDriver 作为默认实现。
+以后如果要换成 CDP 直连或反检测方案，只需要新写一个
+继承 BaseDriver 的类，上层（perception/action）完全不用改。
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Any
+
+
+class BaseDriver(ABC):
+
+    @abstractmethod
+    def navigate(self, url: str) -> None:
+        ...
+
+    @abstractmethod
+    def query_interactive_elements(self, roles: tuple) -> List[Any]:
+        ...
+
+    @abstractmethod
+    def describe_element(self, handle: Any) -> dict:
+        """返回 {"role": str, "text": str, "attrs": dict}"""
+        ...
+
+    @abstractmethod
+    def click(self, handle: Any) -> None:
+        ...
+
+    @abstractmethod
+    def type_text(self, handle: Any, text: str) -> None:
+        ...
+
+    @abstractmethod
+    def scroll(self, direction: str) -> None:
+        ...
+
+    @abstractmethod
+    def wait(self, seconds: float) -> None:
+        ...
+
+    @abstractmethod
+    def get_visible_text(self) -> str:
+        ...
+
+    @abstractmethod
+    def current_url(self) -> str:
+        ...
+
+    @abstractmethod
+    def current_title(self) -> str:
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        ...

package/python/foxclaw/browser/driver/playwright_driver.py

@@ -0,0 +1,170 @@
+"""
+PlaywrightDriver —— 默认底层驱动实现。
+
+用 Playwright 的 sync API，因为 HIR v1.0 Kernel 的执行流程本身是
+顺序同步的（详见 HIR ExecutionVM 设计：v1 不做并发调度）。
+如果以后要支持并发多会话，再切换到 async API 或换 CDP driver。
+
+注意：这里刻意用 role 相关的 CSS/属性选择器组合来找"可交互元素"，
+没有依赖 accessibility tree API（虽然更准确，但部分 headless 场景下
+获取成本更高），这是 v1 的工程妥协，标注在这里方便后续替换。
+
+【融合适配 A1/A2】
+- playwright 在 Foxclaw 里是**可选依赖**（extra `browser`），所以 import
+  刻意放进 __init__ 而非模块顶层：仅"真正构造 driver"时才需要 playwright，
+  `import foxclaw.browser` 本身不拖 playwright，缺失时子系统优雅降级而非崩溃。
+- Playwright sync API **不能在 asyncio 事件循环线程里跑**，且其对象有线程亲和性；
+  故本 driver 必须由 BrowserService 的专用工作线程独占构造与调用（见 service.py）。
+"""
+
+import os
+import time
+from typing import List, Any
+
+from .base_driver import BaseDriver
+
+
+_MAX_BLOCKED = 50
+
+
+ROLE_SELECTOR_MAP = {
+    "button": "button, [role=button], input[type=button], input[type=submit]",
+    "link": "a[href]",
+    "textbox": "input[type=text], input[type=search], input[type=email], "
+               "input[type=password], input:not([type]), textarea",
+    "checkbox": "input[type=checkbox]",
+    "radio": "input[type=radio]",
+    "combobox": "select",
+    "menuitem": "[role=menuitem]",
+}
+
+
+class PlaywrightDriver(BaseDriver):
+
+    def __init__(self, headless: bool = True, guard_requests: bool | None = None):
+        from playwright.sync_api import sync_playwright
+
+        self._pw = None
+        self._browser = None
+        self._page = None
+        self.blocked_requests: list[tuple[str, str]] = []
+        try:
+            self._pw = sync_playwright().start()
+            self._browser = self._pw.chromium.launch(headless=headless)
+            self._page = self._browser.new_page()
+            if guard_requests is None:
+                guard_requests = os.environ.get(
+                    "FOXCLAW_BROWSER_GUARD_REQUESTS", "1").strip() not in ("0", "false", "no")
+            if guard_requests:
+                self._page.route("**/*", self._on_route)
+        except Exception:
+            self._safe_teardown()
+            raise
+
+    def _on_route(self, route) -> None:
+        """路由层准入:放行公网 http(s),拦下内网 / 非 http(s) 请求。
+
+        Playwright 的 sync 回调在浏览器真正发请求**之前**执行,所以 abort 能挡住
+        连接建立,而不是等响应回来才后悔。DNS 层面的 TOCTOU 见 url_policy 的说明。
+        """
+        from ..action.url_policy import validate_request_url
+
+        try:
+            url = route.request.url or ""
+        except Exception:
+            url = ""
+        try:
+            validate_request_url(url)
+        except ValueError as e:
+            self.blocked_requests.append((url[:512], str(e)))
+            if len(self.blocked_requests) > _MAX_BLOCKED:
+                del self.blocked_requests[:-_MAX_BLOCKED]
+            try:
+                route.abort("blockedbyclient")
+            except Exception:
+                pass
+            return
+        try:
+            route.continue_()
+        except Exception:
+            pass
+
+    def _safe_teardown(self):
+        """尽力释放已创建的资源，任一步失败都不影响其余步骤。"""
+        for closer in (
+            lambda: self._browser.close() if self._browser else None,
+            lambda: self._pw.stop() if self._pw else None,
+        ):
+            try:
+                closer()
+            except Exception:
+                pass
+        self._page = None
+        self._browser = None
+        self._pw = None
+
+    def _require_page(self):
+        """取当前页面；未打开或已拆卸时立刻报错，而不是等 None 属性访问炸。
+
+        `_page` 的静态类型是 `Page | None`（初始化与拆卸都会置 None）。下面几个
+        方法原先直接 `self._page.xxx`：正常流程里 close() 之后没人再调，所以一直
+        没出事；一旦有人在拆卸后调用，得到的是 `'NoneType' object has no attribute
+        'goto'`，看不出「会话已关闭」这层意思。集中在这里判一次，报错即意图。
+        """
+        if self._page is None:
+            raise RuntimeError(
+                "browser session is not open: driver was closed or failed to launch"
+            )
+        return self._page
+
+    def navigate(self, url: str) -> None:
+        self._require_page().goto(url, wait_until="domcontentloaded")
+
+    def query_interactive_elements(self, roles: tuple) -> List[Any]:
+        selectors = [ROLE_SELECTOR_MAP[r] for r in roles if r in ROLE_SELECTOR_MAP]
+        combined = ", ".join(selectors)
+        elements = self._require_page().query_selector_all(combined)
+        return [el for el in elements if el.is_visible()]
+
+    def describe_element(self, handle) -> dict:
+        role = handle.evaluate(
+            "el => el.getAttribute('role') || el.tagName.toLowerCase()"
+        )
+        text = handle.evaluate(
+            "el => (el.innerText || el.value || el.placeholder || '').trim()"
+        )
+        attrs = handle.evaluate(
+            """el => {
+                const out = {};
+                for (const attr of ['href', 'name', 'type', 'aria-label']) {
+                    if (el.getAttribute(attr)) out[attr] = el.getAttribute(attr);
+                }
+                return out;
+            }"""
+        )
+        return {"role": role, "text": text, "attrs": attrs}
+
+    def click(self, handle) -> None:
+        handle.click()
+
+    def type_text(self, handle, text: str) -> None:
+        handle.fill(text)
+
+    def scroll(self, direction: str) -> None:
+        delta = 600 if direction == "down" else -600
+        self._require_page().mouse.wheel(0, delta)
+
+    def wait(self, seconds: float) -> None:
+        time.sleep(seconds)
+
+    def get_visible_text(self) -> str:
+        return self._require_page().inner_text("body")
+
+    def current_url(self) -> str:
+        return self._require_page().url
+
+    def current_title(self) -> str:
+        return self._require_page().title()
+
+    def close(self) -> None:
+        self._safe_teardown()

package/python/foxclaw/browser/perception/__init__.py

@@ -0,0 +1 @@
+"""感知层：DOM 抽取 → 编号 → 语义压缩 → 快照。不依赖任何具体 driver。"""

package/python/foxclaw/browser/perception/dom_extractor.py

@@ -0,0 +1,42 @@
+"""
+DOM 提取器。
+
+职责边界很窄：只负责"从底层 driver 拿原始数据"，
+不做任何压缩/裁剪——压缩是 SemanticReducer 的事。
+这样分层是为了让"取数方式"和"压缩策略"可以独立演化
+（比如以后换成 CDP driver，只需要改这一层）。
+"""
+
+INTERACTIVE_ROLES = ("button", "link", "textbox", "checkbox", "radio", "combobox", "menuitem")
+
+
+class DomExtractor:
+
+    def __init__(self, driver):
+        self.driver = driver
+
+    def extract_interactive_elements(self):
+        """
+        返回底层元素句柄列表（具体类型由 driver 决定，Playwright 下是 ElementHandle）。
+        只取可见 + 可交互的元素，不可见的直接丢弃，避免 LLM 尝试点击看不见的东西。
+        """
+        return self.driver.query_interactive_elements(INTERACTIVE_ROLES)
+
+    def describe_element(self, handle) -> dict:
+        """把一个元素句柄转成 role/text/attrs 的原始描述，交给 indexer 二次加工"""
+        return self.driver.describe_element(handle)
+
+    def extract_visible_text(self, max_chars: int = 2000) -> str:
+        """
+        提取页面主要可见文本，做长度上限控制。
+        这不是给 LLM 做阅读理解用的全文，只是辅助上下文，
+        真正结构化的信息应该来自 elements 列表。
+        """
+        text = self.driver.get_visible_text()
+        return text[:max_chars]
+
+    def current_url(self) -> str:
+        return self.driver.current_url()
+
+    def current_title(self) -> str:
+        return self.driver.current_title()

package/python/foxclaw/browser/perception/element_indexer.py

@@ -0,0 +1,56 @@
+"""
+元素编号器。
+
+核心思路：LLM 不应该猜 CSS selector 或坐标，只需要输出一个数字 ID。
+这里负责：给页面里当前可交互的元素分配编号，并维护
+"编号 -> 底层浏览器句柄"的映射，供 action_executor 使用。
+
+编号在同一个 Snapshot 生命周期内稳定；页面一旦发生导航或大幅刷新，
+编号需要重新分配（旧编号即失效，这是有意为之——避免"过期编号"
+被误用去点击一个已经不存在的元素）。
+"""
+
+from typing import List, Dict, Any
+
+
+class ElementIndexer:
+
+    def __init__(self):
+        self._registry: Dict[str, Any] = {}
+        self._counter = 0
+
+    def reset(self):
+        self._registry.clear()
+        self._counter = 0
+
+    def assign(self, handles: List[Any], describe_fn) -> List[Dict[str, Any]]:
+        """
+        handles: 底层 driver 返回的可交互元素句柄列表
+        describe_fn: 把单个句柄转成 {"role":..., "text":..., "attrs":...} 的函数，
+                     由具体 driver 实现（不同 driver 取属性的方式不同）
+        """
+        self.reset()
+        indexed = []
+
+        for handle in handles:
+            self._counter += 1
+            eid = str(self._counter)
+            self._registry[eid] = handle
+
+            desc = describe_fn(handle)
+            indexed.append({
+                "id": eid,
+                "role": desc.get("role", "unknown"),
+                "text": desc.get("text", "")[:80],
+                "attrs": desc.get("attrs", {}),
+            })
+
+        return indexed
+
+    def resolve(self, element_id: str):
+        """把编号还原为底层句柄，供 action_executor 执行真实操作"""
+        if element_id not in self._registry:
+            raise KeyError(
+                f"元素编号 {element_id} 不存在或已过期（页面可能已刷新，需要重新提取语义结构）"
+            )
+        return self._registry[element_id]

package/python/foxclaw/browser/perception/semantic_reducer.py

@@ -0,0 +1,33 @@
+"""
+SemanticReducer —— HIR-Browser 的第一个核心壁垒。
+
+问题：不能把整个 DOM 丢给 LLM（token 爆炸 + 噪音太多）。
+方案：只保留"可交互元素 + 编号 + 简短文本"，用数字 ID 代替 selector/坐标，
+     LLM 输出 click(3) 而不是猜 CSS path。
+
+这一层不关心底层用什么 driver，只依赖 DomExtractor 和 ElementIndexer 的接口。
+"""
+
+from .snapshot import Snapshot
+
+
+class SemanticReducer:
+
+    def __init__(self, dom_extractor, element_indexer):
+        self.dom_extractor = dom_extractor
+        self.indexer = element_indexer
+
+    def reduce(self) -> Snapshot:
+        handles = self.dom_extractor.extract_interactive_elements()
+
+        indexed_elements = self.indexer.assign(
+            handles,
+            describe_fn=self.dom_extractor.describe_element,
+        )
+
+        return Snapshot(
+            url=self.dom_extractor.current_url(),
+            title=self.dom_extractor.current_title(),
+            elements=indexed_elements,
+            text_summary=self.dom_extractor.extract_visible_text(),
+        )

package/python/foxclaw/browser/perception/snapshot.py

@@ -0,0 +1,29 @@
+"""
+页面状态快照。
+
+Snapshot 只存"语义化之后"的轻量结构，不存原始 DOM——
+原始 DOM 只在 dom_extractor 里短暂存在，绝不向上层传递，
+否则又会掉回"把整个 DOM 喂给 LLM"的老问题。
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+
+
+@dataclass
+class Snapshot:
+    url: str
+    title: str
+    elements: List[Dict[str, Any]] = field(default_factory=list)
+    text_summary: str = ""
+
+    def element_ids(self) -> set:
+        return {el["id"] for el in self.elements}
+
+    def to_dict(self) -> dict:
+        return {
+            "url": self.url,
+            "title": self.title,
+            "elements": self.elements,
+            "text_summary": self.text_summary,
+        }