foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/api/routes/task.py

@@ -0,0 +1,281 @@
+"""任务执行 / 流式直答 / 流式任务 路由与多模态护栏。
+
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+晚绑定读取;路由用 `@app` 装饰器在 import 时注册。流式限流器 `_STREAM_LIMITER` 为
+模块级单例,`__init__.py` 会 re-export(测试复位其桶容量)。
+"""
+
+import json
+import asyncio
+import threading as _threading
+
+from fastapi import Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+import foxclaw.api as _api
+from .. import app
+from ...mcp_server import _RateLimiter as _RL
+from ...core import settings
+
+
+# ── 请求模型 ───────────────────────────────────────────────
+
+class TaskRequest(BaseModel):
+    task: str
+    agent_id: str = "supervisor"
+    context: dict = {}
+    images: list = []       # 多模态对话:[{media_type,data(base64)}];仅 /chat/stream 消费
+    history: list = []      # 多轮上下文:[{role:'user'/'assistant',content}];前端带最近几轮,
+                            # 后端拼进 LLM messages,让对话连贯(否则每轮无状态、记不住上一句)
+    session_id: str = ""    # 会话归属:非空则本轮问答落盘到该会话(供"会话历史"回看)
+    attachments: list = []  # 聊天附件:[{name,size,mime,url,text}];text 为提取正文(可为空),
+                            # 仅 /chat/stream 消费;随问题注入 LLM + 落盘会话供回看
+
+
+class GoalRequest(BaseModel):
+    agent_id: str
+    goal: str
+    allowed_tools: list[str] = []
+    entities: list[str] = []
+
+
+# ── 任务执行 ───────────────────────────────────────────────
+
+@app.post("/api/task")
+async def run_task(req: TaskRequest):
+    """执行任务，返回结果 + ThoughtChain 摘要。
+
+    把认知处理 offload 到工作线程:每请求的 CPU 密集同步工作(harness 语义嵌入等)不再
+    阻塞事件循环,并发请求的嵌入计算可真正并行(torch/ST CPU 前向释放 GIL),吞吐随核数扩展。
+    · contextvars 随 to_thread 复制到工作线程 → 每请求会话状态仍隔离(见 base.py);
+    · 内层 LLM 的 to_thread 用各自 asyncio.run 的独立事件循环 executor,不与外层竞争
+      同一线程池,故无嵌套线程池死锁;
+    · harness 累积态已在 harness.py 用 RLock 保护(嵌入在锁外,故并行不受锁影响)。"""
+    def _work():
+        # 经微内核调度器准入(默认无上限=直通;设了 FOXCLAW_MAX_CONCURRENCY 才背压)+ 生命周期事件
+        return _api._os_instance.scheduler.run(
+            lambda: asyncio.run(_api._os_instance.run(req.task, req.agent_id,
+                                                      context=req.context)),
+            agent_id=req.agent_id, task=req.task)
+    return await asyncio.to_thread(_work)
+
+
+# 流式限流 + 并发上限(防刷爆/资源耗尽;env 可配)
+_STREAM_LIMITER = _RL(settings.get_int("FOXCLAW_STREAM_RATE"))                   # 次/分
+_STREAM_SEM = _threading.Semaphore(settings.get_int("FOXCLAW_STREAM_CONCURRENCY"))
+
+
+_MAX_IMAGES = 6
+_MAX_IMG_B64 = 10 * 1024 * 1024        # 单图 base64 上限 ~10MB(≈7.5MB 原图)
+_MAX_IMG_TOTAL = 20 * 1024 * 1024      # 所有图 base64 累计上限(防 6×10MB=60MB 聚合 payload)
+_ALLOWED_IMG_MT = {"image/png", "image/jpeg", "image/webp", "image/gif"}
+
+_MAX_ATTACHMENTS = 6                   # 单次问答最多附件数
+_ATTACH_TEXT_MAX = 20000               # 单附件提取正文上限
+_ATTACH_TEXT_TOTAL = 60000             # 全部附件正文累计上限(≈1.5 万 token,防撑爆上下文)
+
+
+def _sanitize_images(images):
+    """校验/裁剪前端传来的多模态图片:限数量、限单图大小、限累计总量、白名单类型。
+    防超大 payload/OOM(前端已缩放,这是对直连/恶意客户端的后端自保)。"""
+    out = []
+    total = 0
+    if not isinstance(images, list):
+        return out
+    for im in images[:_MAX_IMAGES]:
+        if not isinstance(im, dict):
+            continue
+        mt = str(im.get("media_type", "")).lower()
+        d = im.get("data", "")
+        if mt not in _ALLOWED_IMG_MT:
+            continue
+        if not isinstance(d, str) or not d or len(d) > _MAX_IMG_B64:
+            continue
+        if total + len(d) > _MAX_IMG_TOTAL:    # 累计超总上限 → 停(丢弃其余)
+            break
+        total += len(d)
+        out.append({"media_type": mt, "data": d})
+    return out
+
+
+def _sanitize_attachments(attachments):
+    """校验/裁剪前端传来的聊天附件:限数量、字段清洗、正文长度上限 + 累计上限。
+    附件是前端经 /api/upload 上传后带回的引用({name,size,mime,url,text});这里只做
+    直连/恶意客户端的自保,不信任 text 之外任何字段用于文件系统操作(下载按 url 里的 id 白名单)。"""
+    out = []
+    total = 0
+    if not isinstance(attachments, list):
+        return out
+    for a in attachments[:_MAX_ATTACHMENTS]:
+        if not isinstance(a, dict):
+            continue
+        name = str(a.get("name") or "")[:200]
+        text = str(a.get("text") or "")[:_ATTACH_TEXT_MAX]
+        if not name and not text:
+            continue
+        if total + len(text) > _ATTACH_TEXT_TOTAL:   # 累计正文超总上限 → 截断(丢弃后续正文)
+            text = text[:_ATTACH_TEXT_TOTAL - total]
+        total += len(text)
+        try:                                        # size 可能是脏值("big"/None),护栏绝不因此抛异常
+            size = int(a.get("size")) if a.get("size") else 0
+        except (TypeError, ValueError):
+            size = 0
+        out.append({
+            "name": name,
+            "size": size,
+            "mime": str(a.get("mime") or "")[:100],
+            "url": str(a.get("url") or "")[:500],
+            "text": text,
+        })
+    return out
+
+
+@app.post("/api/chat/stream")
+async def chat_stream(req: TaskRequest, request: Request):
+    """流式直答(方案A):SSE 逐字返回 Agent LLM 输出。用于对话/问答;走完整认知管线的任务执行
+    用 /api/task(阻塞)或 /api/task/stream(流式,D1);此端点不跑 recall/verify/reflect 等 stage。
+    背压:令牌桶限流 + 并发信号量;客户端断连 → stop_event 终止 LLM 流(省 token)。
+    images:多模态对话,随问题发给视觉模型(非视觉模型 router 层报错→降级)。"""
+    if not _STREAM_LIMITER.allow():
+        async def _rl():
+            yield "data: " + json.dumps({"error": "rate limited"}) + "\n\n"
+        return StreamingResponse(_rl(), media_type="text/event-stream")
+
+    agent = _api._os_instance._agents.get(req.agent_id) or _api._os_instance.supervisor
+    imgs = _sanitize_images(req.images)
+    atts = _sanitize_attachments(req.attachments)
+
+    async def async_sse():
+        if not _STREAM_SEM.acquire(blocking=False):   # 超并发上限 → 拒(不排队)
+            yield "data: " + json.dumps({"error": "busy, try again later"}) + "\n\n"
+            return
+        q: asyncio.Queue = asyncio.Queue()
+        stop = _threading.Event()
+        loop = asyncio.get_running_loop()
+
+        def _producer():
+            _parts = []
+
+            def _on_thinking(delta: str) -> None:
+                # 推理走独立事件,不混进正文:前端折叠展示,正文仍只收 {"delta"}。
+                loop.call_soon_threadsafe(q.put_nowait, {"thinking": delta})
+
+            def _on_evidence(evs: list) -> None:
+                # 执行证据(核验结论 + 来源链接/文件)整块送:前端挂在答案下方供核对,
+                # 不进正文(正文是给用户读的答案,证据是给人查的凭据)。
+                loop.call_soon_threadsafe(q.put_nowait, {"evidence": evs})
+
+            try:
+                for chunk in agent.stream_reply(req.task, stop_event=stop, images=imgs,
+                                                history=req.history, attachments=atts,
+                                                on_thinking=_on_thinking,
+                                                on_evidence=_on_evidence):
+                    _parts.append(chunk)
+                    loop.call_soon_threadsafe(q.put_nowait, {"delta": chunk})
+                loop.call_soon_threadsafe(q.put_nowait, {"done": True})
+            except Exception as e:
+                loop.call_soon_threadsafe(q.put_nowait, {"error": str(e)})
+            finally:
+                # 落盘会话历史(问 + 答),供"会话/所有会话"回看。断连中止也保留已生成部分。
+                if req.session_id:
+                    try:
+                        _api._os_instance.sessions.append(req.session_id, "user", req.task, attachments=atts)
+                        _reply = "".join(_parts)
+                        if _reply:
+                            _api._os_instance.sessions.append(req.session_id, "assistant", _reply)
+                    except Exception:
+                        pass
+                loop.call_soon_threadsafe(q.put_nowait, None)   # 结束哨兵
+
+        _threading.Thread(target=_producer, daemon=True, name="chat-stream").start()
+        try:
+            while True:
+                if await request.is_disconnected():
+                    stop.set(); break                 # 断连 → 终止 LLM 流
+                try:
+                    item = await asyncio.wait_for(q.get(), timeout=0.5)
+                except asyncio.TimeoutError:
+                    continue
+                if item is None:
+                    break
+                if "thinking" in item:
+                    # 命名事件(SSE 规范):event: thinking + data。老客户端只认 data: 行也不会被
+                    # 误导成正文(delta 字段不存在);新前端按事件名折叠展示。
+                    yield ("event: thinking\ndata: "
+                           + json.dumps({"thinking": item["thinking"]}, ensure_ascii=False)
+                           + "\n\n")
+                    continue
+                if "evidence" in item:
+                    # 与 thinking 同理走命名事件:老客户端拿不到这个事件名也不会把凭据
+                    # 当成正文拼进回答。
+                    yield ("event: evidence\ndata: "
+                           + json.dumps({"evidence": item["evidence"]}, ensure_ascii=False)
+                           + "\n\n")
+                    continue
+                yield "data: " + json.dumps(item, ensure_ascii=False) + "\n\n"
+        finally:
+            stop.set()
+            _STREAM_SEM.release()
+
+    return StreamingResponse(async_sse(), media_type="text/event-stream",
+                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+@app.post("/api/task/stream")
+async def task_stream(req: TaskRequest, request: Request):
+    """流式任务执行(D1):SSE 逐 stage 进度 + act 逐 token + 最终结果。用于任务/分析等走**完整
+    认知管线**的场景(对话直答走 /api/chat/stream)。事件:`{stage}`/`{plan}`/`{delta}`/`{result}`/`{error}`。
+    【P3-3】主管(P1-1 pipeline 化后)同样可走本端点:stage 事件为主管管线的
+    recall/meta_check/schedule/route/plan/dispatch/aggregate;分发场景下子 Agent 的 act
+    token 随 contextvar 传播一并流出。
+    背压与断连处理与 chat_stream 一致:断连 → stop_event 同时停管线 stage(P3)+ 停 act LLM 生成。"""
+    if not _STREAM_LIMITER.allow():
+        async def _rl():
+            yield "data: " + json.dumps({"error": "rate limited"}) + "\n\n"
+        return StreamingResponse(_rl(), media_type="text/event-stream")
+
+    agent = _api._os_instance._agents.get(req.agent_id)
+    # 【P3-3】P1-1 落地后主管走统一 pipeline(supervisor_stages),支持 run_task_stream,
+    # 不再回落 assistant(助手已下放为技能)。未知 agent_id 仍回落主管兼容旧客户端
+    # (旧前端可能还传 "assistant"/"admin"),但打 warning 不静默。
+    if agent is None:
+        print(f"[Foxclaw API] ⚠ /api/task/stream 收到未知 agent_id={req.agent_id},回落 supervisor")
+        agent = _api._os_instance.supervisor
+
+    async def async_sse():
+        if not _STREAM_SEM.acquire(blocking=False):   # 超并发上限 → 拒(不排队)
+            yield "data: " + json.dumps({"error": "busy, try again later"}) + "\n\n"
+            return
+        q: asyncio.Queue = asyncio.Queue()
+        stop = _threading.Event()
+        loop = asyncio.get_running_loop()
+
+        def _producer():
+            try:
+                for evt in agent.run_task_stream(req.task, context=req.context,
+                                                 stop_event=stop):
+                    loop.call_soon_threadsafe(q.put_nowait, evt)
+            except Exception as e:
+                loop.call_soon_threadsafe(q.put_nowait, {"error": str(e)})
+            finally:
+                loop.call_soon_threadsafe(q.put_nowait, None)   # 结束哨兵
+
+        _threading.Thread(target=_producer, daemon=True, name="task-stream-sse").start()
+        try:
+            while True:
+                if await request.is_disconnected():
+                    stop.set(); break                 # 断连 → 停管线 + 停 act LLM
+                try:
+                    item = await asyncio.wait_for(q.get(), timeout=0.5)
+                except asyncio.TimeoutError:
+                    continue
+                if item is None:
+                    break
+                yield "data: " + json.dumps(item, ensure_ascii=False) + "\n\n"
+        finally:
+            stop.set()
+            _STREAM_SEM.release()
+
+    return StreamingResponse(async_sse(), media_type="text/event-stream",
+                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})

package/python/foxclaw/api/routes/ws.py

@@ -0,0 +1,68 @@
+"""WebSocket:实时 Harness 事件流(连接管理 + 端点)。
+
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。manager 由 api/__init__.py re-export
+给后台广播任务 _drain_event_queue 使用。
+"""
+
+import os
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+from ..middleware import _constant_time_eq, _loopback_bypass_on, _is_loopback_client
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.connections: list[WebSocket] = []
+
+    async def connect(self, ws: WebSocket):
+        await ws.accept()
+        self.connections.append(ws)
+
+    def disconnect(self, ws: WebSocket):
+        self.connections.remove(ws)
+
+    async def broadcast(self, data: dict):
+        for ws in self.connections[:]:
+            try:
+                await ws.send_json(data)
+            except Exception:
+                self.connections.remove(ws)
+
+
+manager = ConnectionManager()
+
+
+async def harness_websocket(websocket: WebSocket):
+    """
+    实时 Harness 事件流。
+    事件转发器在启动时已注册到线程安全队列,这里只负责接受连接并保活。
+
+    鉴权:HTTP 中间件管不到 websocket scope,故 WS 的鉴权必须在端点内做。
+    浏览器无法给 WS 握手设请求头,因此接受 ?key= 查询参数(也兼容能设头的非浏览器
+    客户端的 X-API-Key 头)。未设 FOXCLAW_API_KEY 时开放;设了时本机(127.0.0.1/::1)
+    客户端也免 ?key=(与 HTTP 中间件同口径的 loopback bypass)。
+    """
+    api_key = os.environ.get("FOXCLAW_API_KEY", "").strip()
+    if api_key:
+        # 【P3-loopback】与 HTTP 中间件同口径:本机(127.0.0.1 / ::1)WS 客户端免 ?key=
+        # 设 FOXCLAW_LOOPBACK_BYPASS=0 可关。详见 foxclaw.api.middleware._loopback_bypass_on
+        ws_host = websocket.client.host if websocket.client else ""
+        if not (_loopback_bypass_on() and _is_loopback_client(ws_host)):
+            provided = (websocket.query_params.get("key")
+                        or websocket.headers.get("x-api-key"))
+            # 【P3-1】常量时间比较(与 HTTP 中间件同一辅助函数);None 由 or "" 兜底——
+            # api_key 非空时 not eq("", api_key) 必为 True,与原 None != api_key 行为一致
+            if not _constant_time_eq(provided or "", api_key):
+                await websocket.close(code=1008)   # policy violation
+                return
+    await manager.connect(websocket)
+    try:
+        while True:
+            await websocket.receive_text()  # 保持连接
+    except WebSocketDisconnect:
+        manager.disconnect(websocket)
+
+
+def register(app):
+    app.add_api_websocket_route("/ws/harness", harness_websocket)

package/python/foxclaw/api/spine.py

@@ -0,0 +1,55 @@
+"""事件脊柱辅助:WS payload 净化 + HKC 后台预热。
+
+从 `foxclaw/api/__init__.py` 搬移出来的纯辅助函数。`_register_spine_projection`
+因 `_WS_MUTED` 受测试源码级断言约束(需留在主文件 `__init__.py` 源码内)而未搬移。
+"""
+import json
+import threading
+import time as _t
+
+import foxclaw.api as _api
+
+
+def _ws_safe_payload(payload, _maxlen: int = 4000):
+    """把任意事件 payload 收敛成 **JSON 安全且有界** 的形式,供 WS 广播。
+    统一投影会把系统事件(execution.completed 等含原始 result/任意对象)也推给 WS,
+    必须防两类真实故障:
+      · 非 JSON 可序列化对象 → ws.send_json 抛异常 → broadcast 静默丢弃该连接;
+      · 超大 payload(整段 LLM 回复 / 大 result,且随真值链被广播多次)→ 向所有 WS 泛洪。
+    脊柱本身仍保留全保真事件(供 history / 审计 / 其它投影),净化只发生在 WS 出口。"""
+    try:
+        raw = json.dumps(payload, default=str, ensure_ascii=False)
+    except Exception:
+        return {"_repr": str(payload)[:_maxlen]}
+    if len(raw) > _maxlen:
+        return {"_truncated": True, "_preview": raw[:_maxlen]}
+    return json.loads(raw)
+
+
+def _prewarm_hkc(osi):
+    """后台预热 HKC:装配容器 + 建搜索索引(bm25+faiss over 全量 KU,顺带加载 HKC
+    多语言 embedding 模型)+ 载入 learning。把"首次知识查询"的一次性冷成本(~几十秒到
+    1 分钟)挪到开机后台完成,之后所有知识查询都不再冷。守护线程、失败静默,绝不影响主应用。
+    索引重建与查询共用 HybridSearch 锁 → 预热期间若有查询会短暂等待,预热完即快。"""
+
+    def _run():
+        t0 = _t.time()
+        try:
+            svc = getattr(osi, "hkc", None)      # 访问即触发 HKC 惰性装配
+            if not svc or not getattr(svc, "available", False):
+                return
+            # 搜索索引已在 assemble() 内构建(向量索引持久化加载优先,避免每次启动全量
+            # embedding 把 CPU 打满、启动卡几分钟),这里不再重复 build_index。
+            try:
+                lr = getattr(osi, "learning_runtime", None)
+                if lr is not None:
+                    lr._ensure_hkc_loaded()
+            except Exception:
+                pass
+            print(f"[Foxclaw API] ✓ HKC 预热完成（{_t.time()-t0:.1f}s）: 首次知识查询不再冷装配")
+        except Exception as e:
+            print(f"[Foxclaw API] · HKC 预热未启用(可选): {e}")
+
+    # 晚绑定:把守护线程挂到主模块 `__init__.py` 的 `_prewarm_thread`(lifespan 关闭前需 join)。
+    _api._prewarm_thread = threading.Thread(target=_run, name="hkc-prewarm", daemon=True)
+    _api._prewarm_thread.start()

package/python/foxclaw/browser/__init__.py

@@ -0,0 +1,13 @@
+"""
+foxclaw.browser —— HIR-Browser 融入 Foxclaw 的浏览器子系统（"AI 用的浏览器"）。
+
+只做一件事：感知网页 → 压缩成 LLM 可读的语义结构 → 把动作翻译成真实浏览器
+操作 → 校验执行结果。不做规划、不做决策——那是 Agent/Foxclaw 控制面的职责。
+
+对外入口是 BrowserService（async 安全、可选依赖优雅降级、专用工作线程）。
+`import foxclaw.browser` 不会拉入 playwright；只有真正开会话时才需要。
+"""
+
+from .service import BrowserService
+
+__all__ = ["BrowserService"]

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

@@ -0,0 +1 @@
+"""动作层：WebAction 数据形状 + 执行器（翻译成真实操作）+ 校验器（快照 diff 判定生效）。"""

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

@@ -0,0 +1,54 @@
+"""
+ActionExecutor —— 把 WebAction 翻译成真实浏览器操作。
+
+只做翻译和调用，不做判断（判断动作是否该执行、是否合理，
+不属于这一层，也不属于 HIR-Browser 整体，那是 Foxclaw/HAR 的职责）。
+"""
+
+from .action_types import WebAction
+
+
+class ActionExecutor:
+
+    def __init__(self, driver, element_indexer):
+        self.driver = driver
+        self.indexer = element_indexer
+
+    def run(self, action: WebAction):
+        handler = getattr(self, f"_do_{action.type}", None)
+        if handler is None:
+            raise NotImplementedError(f"未实现的动作类型: {action.type}")
+        return handler(action)
+
+    def _do_navigate(self, action: WebAction):
+        # URL 准入:此前直接把模型给的字符串交给 driver → file:// 读本机文件、
+        # javascript: 执行脚本、内网/云元数据 SSRF。ValueError 由 service.act 转成错误返回。
+        from .url_policy import validate_navigate_url
+        target = validate_navigate_url(action.target)
+        self.driver.navigate(target)
+        return {"navigated_to": target}
+
+    def _do_click(self, action: WebAction):
+        handle = self.indexer.resolve(action.target)
+        self.driver.click(handle)
+        return {"clicked": action.target}
+
+    def _do_type(self, action: WebAction):
+        handle = self.indexer.resolve(action.target)
+        self.driver.type_text(handle, action.value or "")
+        return {"typed": action.value, "into": action.target}
+
+    def _do_scroll(self, action: WebAction):
+        direction = action.value or "down"
+        self.driver.scroll(direction)
+        return {"scrolled": direction}
+
+    def _do_extract(self, action: WebAction):
+        # extract 本身不改变页面状态，只是触发一次重新语义化，
+        # 具体的语义化交给上层 WebAdapter 统一处理，这里返回空占位即可
+        return {"extract_requested": True}
+
+    def _do_wait(self, action: WebAction):
+        seconds = float(action.value or 1.0)
+        self.driver.wait(seconds)
+        return {"waited": seconds}

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

@@ -0,0 +1,45 @@
+"""
+Action Graph 节点在 Web 场景下的具体形态。
+
+这里只定义"数据形状"，不含任何执行逻辑，也不含任何"该不该执行"的判断——
+那是 HAR / Foxclaw 的职责。
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any
+
+
+# HIR-Browser 支持的动作类型，故意保持极简，不做扩展性设计
+SUPPORTED_ACTIONS = ("navigate", "click", "type", "scroll", "extract", "wait")
+
+
+@dataclass
+class WebAction:
+    """
+    一个标准化的 Web 动作节点。
+
+    type: navigate | click | type | scroll | extract | wait
+    target: 元素编号（由 SemanticReducer 分配的 id），navigate 时为 URL
+    value: type 动作的输入文本；scroll 的方向/距离
+    meta: 透传字段，供上层（HAR/Foxclaw）附加调试信息，Web Adapter 不解析它
+    """
+
+    type: str
+    target: Optional[str] = None
+    value: Optional[Any] = None
+    meta: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.type not in SUPPORTED_ACTIONS:
+            raise ValueError(
+                f"不支持的动作类型: {self.type}，仅支持 {SUPPORTED_ACTIONS}"
+            )
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "WebAction":
+        return cls(
+            type=d["type"],
+            target=d.get("target"),
+            value=d.get("value"),
+            meta=d.get("meta", {}),
+        )

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

@@ -0,0 +1,68 @@
+"""
+ActionVerifier —— HIR-Browser 的第二个核心壁垒。
+
+问题：LLM 不知道自己的操作有没有生效。selector 没报错 ≠ 操作成功。
+方案：执行前后各拍一次语义快照，做 diff，用 diff 结果去校验
+     "这次动作是否符合预期"，而不是简单地"没抛异常就算成功"。
+
+这里的判断规则刻意保持简单、可解释，不引入模型推理——
+"是否成功"这个判断本身应该是确定性的、可复现的。
+"""
+
+from ..perception.snapshot import Snapshot
+from .action_types import WebAction
+
+
+class ActionVerifier:
+
+    def verify(self, before: Snapshot, after: Snapshot, action: WebAction) -> dict:
+        diff = self._diff(before, after)
+
+        success = self._matches_expectation(diff, action)
+
+        return {
+            "success": success,
+            "diff": diff,
+            "url_changed": before.url != after.url,
+        }
+
+    def _diff(self, before: Snapshot, after: Snapshot) -> dict:
+        before_ids = before.element_ids()
+        after_ids = after.element_ids()
+
+        return {
+            "url_before": before.url,
+            "url_after": after.url,
+            "elements_added": len(after_ids - before_ids),
+            "elements_removed": len(before_ids - after_ids),
+            "title_before": before.title,
+            "title_after": after.title,
+        }
+
+    def _matches_expectation(self, diff: dict, action: WebAction) -> bool:
+        """
+        按动作类型给出最基本的"是否生效"判断：
+
+        - navigate: URL 必须变化
+        - click: URL 变化，或页面元素结构发生变化（新增/移除元素），
+                 或标题变化——三者任一即视为"页面对点击有反应"
+        - type: 无法通过快照diff直接验证输入内容是否写入（需要额外读取
+                目标元素的 value），这里保守返回 True，交由上层结合
+                extract 结果自行判断
+        - scroll / wait / extract: 不强制要求页面发生变化
+        """
+        if action.type == "navigate":
+            return diff["url_before"] != diff["url_after"]
+
+        if action.type == "click":
+            return (
+                diff["url_before"] != diff["url_after"]
+                or diff["elements_added"] > 0
+                or diff["elements_removed"] > 0
+                or diff["title_before"] != diff["title_after"]
+            )
+
+        if action.type in ("type", "scroll", "wait", "extract"):
+            return True
+
+        return True