screenforge 0.6.1__tar.gz → 0.7.0__tar.gz

{screenforge-0.6.1 → screenforge-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.6.1
+Version: 0.7.0
 Summary: AI-driven cross-platform UI automation engine with test script generation
 License: MIT
 Project-URL: Homepage, https://github.com/jhinzzz/ScreenForge
@@ -119,6 +119,7 @@ Each step: **inspect → decide → act → verify**. The AI decides, ScreenForg
 - **MCP server**: Any MCP-compatible Agent can drive ScreenForge natively
 - **Structured output**: JSON Lines events + `report/runs/<id>/` artifacts for CI integration
 - **Live Mirror playground**: Watch the generated pytest code grow line-by-line beside a live screenshot as the test runs — `screenforge --playground`. See the [Playground Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/playground-guide.md)
+- **Execution-replay review report**: Run any test with `REVIEW_RECORD=1` and get a self-contained, shareable offline `report.html` — a drag-timeline of each step's screenshot + the test source line that triggered it + the DOM tree, plus a `video.gif` filmstrip. Default off, zero overhead. (Web verified; mobile registry/recording seam in place but unverified.)
 
 ## Agent Integration (Claude Code / Cursor / Codex)
 

{screenforge-0.6.1 → screenforge-0.7.0}/README.md

@@ -74,6 +74,7 @@ Each step: **inspect → decide → act → verify**. The AI decides, ScreenForg
 - **MCP server**: Any MCP-compatible Agent can drive ScreenForge natively
 - **Structured output**: JSON Lines events + `report/runs/<id>/` artifacts for CI integration
 - **Live Mirror playground**: Watch the generated pytest code grow line-by-line beside a live screenshot as the test runs — `screenforge --playground`. See the [Playground Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/playground-guide.md)
+- **Execution-replay review report**: Run any test with `REVIEW_RECORD=1` and get a self-contained, shareable offline `report.html` — a drag-timeline of each step's screenshot + the test source line that triggered it + the DOM tree, plus a `video.gif` filmstrip. Default off, zero overhead. (Web verified; mobile registry/recording seam in place but unverified.)
 
 ## Agent Integration (Claude Code / Cursor / Codex)
 

screenforge-0.7.0/cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

{screenforge-0.6.1 → screenforge-0.7.0}/cli/doctor.py

@@ -373,10 +373,6 @@ def _build_doctor_summary(checks: list[dict]) -> dict:
     }
 
 
-def _build_doctor_remediation_items(checks: list[dict]) -> list[str]:
-    return _build_doctor_summary(checks).get("top_items", [])
-
-
 def _build_doctor_check_failure_message(check: dict) -> str:
     details = []
 

{screenforge-0.6.1 → screenforge-0.7.0}/cli/session.py

@@ -18,10 +18,6 @@ def _session_file(session_id: str) -> str:
     return os.path.join(_SESSION_DIR, f"{session_id}.json")
 
 
-def session_exists(session_id: str) -> bool:
-    return os.path.exists(_session_file(session_id))
-
-
 def load_session(session_id: str) -> dict | None:
     path = _session_file(session_id)
     if not os.path.exists(path):
@@ -125,7 +121,7 @@ def stop_session_recording(session_id: str) -> str:
         pgid = os.getpgid(pid)
         os.killpg(pgid, signal.SIGINT)
         os.waitpid(pid, 0)
-    except (OSError, ChildProcessError):
+    except OSError:
         try:
             os.kill(pid, signal.SIGINT)
             time.sleep(2)

{screenforge-0.6.1 → screenforge-0.7.0}/cli/shared.py

@@ -3,12 +3,6 @@
 import base64
 import time
 
-from common.capabilities import (
-    ACTIONS_REQUIRING_EXTRA_VALUE,
-    GLOBAL_ACTIONS,
-    SUPPORTED_ACTIONS,
-)
-
 
 class _LazyProxy:
     def __init__(self, loader):
@@ -62,9 +56,6 @@ load_workflow_file = None
 WorkflowLoadError = None
 parse_workflow_var_overrides = None
 resolve_workflow_definition = None
-SUPPORTED_INLINE_ACTIONS = SUPPORTED_ACTIONS
-GLOBAL_INLINE_ACTIONS = GLOBAL_ACTIONS
-INLINE_ACTIONS_REQUIRING_EXTRA_VALUE = ACTIONS_REQUIRING_EXTRA_VALUE
 
 
 def _slug_to_test_name(label: str) -> str:

{screenforge-0.6.1 → screenforge-0.7.0}/common/adapters/base_adapter.py

@@ -17,6 +17,11 @@ class BasePlatformAdapter(ABC):
     def take_screenshot(self) -> bytes:
         pass
 
+    # 录像 seam（诚实边界）：
+    #   - android/ios：start_record/stop_record_and_get_path 落真视频文件（scrcpy / simctl）。
+    #   - web：start_record 是 no-op（CDP attach 无法用 Playwright 录像）；web 的"录像"
+    #     由 review 层用逐操作截图 ffmpeg 拼胶片（review/render.py make_filmstrip）实现，
+    #     不走本 seam。调用方须把返回 "" / None 当作"无视频"，非错误。
     def start_record(self, video_name: str):
         pass
 

{screenforge-0.6.1 → screenforge-0.7.0}/common/ai.py

@@ -9,6 +9,15 @@ from common.logs import log
 from common.progress import ai_status
 
 
+def _strip_json_fences(text: str) -> str:
+    """Unwrap markdown code fences the model may add despite being told not to."""
+    if "```json" in text:
+        return text.split("```json")[1].split("```")[0].strip()
+    if "```" in text:
+        return text.replace("```", "").strip()
+    return text
+
+
 class AIBrain:
     def __init__(self):
         # 实例化文本专属客户端
@@ -251,6 +260,7 @@ class AIBrain:
         """
         封装底层的 LLM 网络调用
         """
+        result_text = ""
         try:
             with ai_status(f"Thinking ({model_name})..."):
                 response = client.chat.completions.create(
@@ -262,16 +272,11 @@ class AIBrain:
                     temperature=0.1,
                 )
 
-            result_text = response.choices[0].message.content.strip()
-
-            if "```json" in result_text:
-                result_text = result_text.split("```json")[1].split("```")[0].strip()
-            elif "```" in result_text:
-                result_text = result_text.replace("```", "").strip()
-
+            result_text = _strip_json_fences(response.choices[0].message.content.strip())
             parsed_json = json.loads(result_text)
             return parsed_json.get("result", {})
 
         except Exception as e:
-            log.error(f"[Error] Model ({model_name}) request or parse failed: {e}")
+            # {} = "retry without cache" per caller contract; log raw text so parse-fail ≠ network-fail.
+            log.error(f"[Error] Model ({model_name}) request or parse failed: {e}\nRaw response: {result_text}")
             return {}

{screenforge-0.6.1 → screenforge-0.7.0}/common/ai_autonomous.py

@@ -1,7 +1,7 @@
 import json
 
 import config.config as config
-from common.ai import AIBrain
+from common.ai import AIBrain, _strip_json_fences
 from common.logs import log
 from common.progress import ai_status
 
@@ -62,14 +62,10 @@ class AutonomousBrain(AIBrain):
             )
 
         if screenshot_base64:
-            active_client = getattr(self, "vision_client", None) or getattr(
-                self, "text_client", None
-            )
+            active_client = self.vision_client or self.text_client
             active_model = config.VISION_MODEL_NAME
         else:
-            active_client = getattr(self, "text_client", None) or getattr(
-                self, "client", None
-            )
+            active_client = self.text_client
             active_model = config.MODEL_NAME
 
         if not active_client:
@@ -92,13 +88,7 @@ class AutonomousBrain(AIBrain):
                     ],
                     temperature=0.1,
                 )
-            result_text = response.choices[0].message.content.strip()
-
-            if "```json" in result_text:
-                result_text = result_text.split("```json")[1].split("```")[0].strip()
-            elif "```" in result_text:
-                result_text = result_text.replace("```", "").strip()
-
+            result_text = _strip_json_fences(response.choices[0].message.content.strip())
             parsed_json = json.loads(result_text)
             parsed_json.setdefault("current_state_summary", "")
             parsed_json.setdefault("planned_steps", [])
@@ -216,14 +206,10 @@ class AutonomousBrain(AIBrain):
             )
 
         if screenshot_base64:
-            active_client = getattr(self, "vision_client", None) or getattr(
-                self, "text_client", None
-            )  # 兼容配置
+            active_client = self.vision_client or self.text_client  # 兼容配置
             active_model = config.VISION_MODEL_NAME
         else:
-            active_client = getattr(self, "text_client", None) or getattr(
-                self, "client", None
-            )
+            active_client = self.text_client
             active_model = config.MODEL_NAME
 
         if not active_client:
@@ -248,13 +234,7 @@ class AutonomousBrain(AIBrain):
                     temperature=0.1,
                 )
 
-            result_text = response.choices[0].message.content.strip()
-
-            if "```json" in result_text:
-                result_text = result_text.split("```json")[1].split("```")[0].strip()
-            elif "```" in result_text:
-                result_text = result_text.replace("```", "").strip()
-
+            result_text = _strip_json_fences(response.choices[0].message.content.strip())
             parsed_json = json.loads(result_text)
 
             thought = parsed_json.get("thought", "无")

{screenforge-0.6.1 → screenforge-0.7.0}/common/cache/cache_stats.py

@@ -48,11 +48,6 @@ class CacheStats:
     def last_cache_date(self) -> Optional[str]:
         return self._last_cache_date
 
-    def increment_query(self) -> None:
-        self._total_queries += 1
-        self._update_last_cache_date()
-        self._save_stats()
-
     def increment_hit(self) -> None:
         self._total_queries += 1
         self._cache_hits += 1

{screenforge-0.6.1 → screenforge-0.7.0}/common/executor.py

@@ -1213,8 +1213,6 @@ class DragHandler(ActionHandler):
 
 
 class UIExecutor:
-    _handlers = {}
-
     def __init__(self, device, platform="android"):
         self.d = device
         self.platform = platform
@@ -1223,33 +1221,28 @@ class UIExecutor:
         # and a follow-up `ref @N` action in the same MCP session share this
         # cache while separate sessions/pages can never leak into each other.
         self._cached_ui_elements: list[dict] = []
-        if not self._handlers:
-            self._handlers = {
-                "click": ClickHandler(),
-                "long_click": LongClickHandler(),
-                "hover": HoverHandler(),
-                "input": InputHandler(),
-                "swipe": SwipeHandler(),
-                "press": PressHandler(),
-                "goto": GotoHandler(),
-                "scroll_into_view": ScrollIntoViewHandler(),
-                "select": SelectHandler(),
-                "upload": UploadHandler(),
-                "double_click": DoubleClickHandler(),
-                "right_click": RightClickHandler(),
-                "drag": DragHandler(),
-                "wait_for": WaitForHandler(),
-                "assert_exist": AssertExistHandler(),
-                "assert_not_exist": AssertNotExistHandler(),
-                "assert_text_equals": AssertTextEqualsHandler(),
-                "assert_text_contains": AssertTextContainsHandler(),
-                "assert_value": AssertValueHandler(),
-                "assert_url": AssertUrlHandler(),
-            }
-
-    @classmethod
-    def register_handler(cls, action_type: str, handler: ActionHandler):
-        cls._handlers[action_type] = handler
+        self._handlers = {
+            "click": ClickHandler(),
+            "long_click": LongClickHandler(),
+            "hover": HoverHandler(),
+            "input": InputHandler(),
+            "swipe": SwipeHandler(),
+            "press": PressHandler(),
+            "goto": GotoHandler(),
+            "scroll_into_view": ScrollIntoViewHandler(),
+            "select": SelectHandler(),
+            "upload": UploadHandler(),
+            "double_click": DoubleClickHandler(),
+            "right_click": RightClickHandler(),
+            "drag": DragHandler(),
+            "wait_for": WaitForHandler(),
+            "assert_exist": AssertExistHandler(),
+            "assert_not_exist": AssertNotExistHandler(),
+            "assert_text_equals": AssertTextEqualsHandler(),
+            "assert_text_contains": AssertTextContainsHandler(),
+            "assert_value": AssertValueHandler(),
+            "assert_url": AssertUrlHandler(),
+        }
 
     def set_ui_elements(self, elements: list[dict]) -> None:
         self._cached_ui_elements = list(elements) if elements else []
@@ -1260,6 +1253,114 @@ class UIExecutor:
                 return el
         return None
 
+    def _recover_web_ref(self, handler, action, l_value, extra_value, result: dict) -> dict:
+        """Web @N ref that get_actual_element couldn't resolve. Try, in order:
+        a recovered stable locator (re-driven through the action's own handler),
+        then a live coordinate click for `click` only (persisted as a skip, never
+        a rotting coordinate). Always terminal — returns the result dict."""
+        el_data = self.resolve_ref(l_value)
+        # The id→text chain in get_actual_element missed this ref, but the
+        # element dict may still carry name/role/desc/placeholder. Recover
+        # the SAME stable locator we'd emit (build_fallback_locator) as a
+        # LIVE handle and re-drive the action's own handler on it — so an
+        # input stays an input, a hover stays a hover, etc. The handler's
+        # execute() validates the locator resolves (discharges the "locator
+        # points at a different element than the pixel" trap) and its
+        # generate_code() persists that stable locator — never a pixel.
+        fb_element = get_fallback_element(self.d, el_data) if el_data else None
+        if fb_element is not None and build_fallback_locator(el_data):
+            try:
+                if handler.execute(self.d, fb_element, self.platform, extra_value):
+                    # generate_code with u2_key="ref" + the live resolve_ref
+                    # rebuilds the SAME stable fragment build_fallback_locator
+                    # produced (build_code's ref branch calls it) — so the
+                    # persisted locator exactly matches the handle we just
+                    # acted on. Then humanize the [@N] labels to readable.
+                    code_lines = handler.generate_code(
+                        self.platform, "ref", l_value, extra_value,
+                        config.DEFAULT_TIMEOUT, resolve_ref=self.resolve_ref,
+                    )
+                    readable = readable_ref_target(el_data)
+                    if readable and readable != l_value:
+                        code_lines = humanize_step_labels(code_lines, l_value, readable)
+                    result["success"] = True
+                    result["code_lines"] = code_lines
+                    result["action_description"] = (
+                        f"🔁 [Ref] {action} {l_value} via recovered locator"
+                    )
+                    return result
+                log.warning(f"⚠️ [Ref] Recovered locator did not satisfy {action}")
+            except Exception as e:
+                log.warning(f"⚠️ [Ref] Recovered locator failed to act: {e}")
+        # No stable locator. Act LIVE via coordinate ONLY for click (the
+        # sole action a bare coordinate can perform) so a recording session
+        # still advances; persist an honest, non-passing skip rather than a
+        # silently-rotting coordinate. For non-click actions there is
+        # nothing a coordinate can do — report a real engine failure.
+        if action == "click" and el_data and el_data.get("w", 0) > 0:
+            cx = el_data["x"] + el_data["w"] // 2
+            cy = el_data["y"] + el_data["h"] // 2
+            try:
+                self.d.mouse.click(cx, cy)
+                log.info(f"🎯 [Ref] {l_value} clicked at ({cx}, {cy}) live (not persisted)")
+            except Exception as e:
+                log.error(f"❌ [Error] Coordinate click failed: {e}")
+                return result
+            log.warning(
+                f"[E036] Ref {l_value} has no stable locator (only coordinates). "
+                f"Emitting pytest.skip so the test isn't silently green."
+            )
+            code_lines = [
+                f"    with allure.step('Click: [{l_value}] (UNREPLAYABLE)'):\n",
+                "        import pytest\n",
+                f"        # Ref {l_value} could only be located by coordinate at record time;\n",
+                "        # no durable selector exists. Provide one before treating this as real.\n",
+                f"        pytest.skip('Ref {l_value} has no durable locator (coordinate-only at record time)')\n",
+            ]
+            result["success"] = True
+            result["code_lines"] = code_lines
+            result["action_description"] = f"⏭️ [Ref] {l_value} unreplayable — skip emitted"
+            return result
+        log.error(format_log("E037") + f" (ref={l_value}, action='{action}')")
+        result["error_code"] = "E037"
+        return result
+
+    def _try_visual_fallback(self, l_type, l_value, result: dict) -> dict | None:
+        """VLM screenshot-coordinate click recovery (web click only). Returns the
+        result dict on a hit (persisted as a skip — a VLM point has no durable
+        locator), or None to fall through to the standard not-found path."""
+        try:
+            from common.visual_fallback import visual_locate
+            screenshot_bytes = self.d.screenshot()
+            coords = visual_locate(
+                screenshot_bytes,
+                f"{l_type}={l_value}",
+            )
+            if coords:
+                cx, cy = coords
+                log.info(f"👁️ [Visual Fallback] Using VLM coordinates: ({cx}, {cy})")
+                # Click live so the session advances, but the visual
+                # fallback has NO DOM node — only a VLM screenshot hit —
+                # so there is no durable locator to emit. Persist a skip
+                # (with the coordinate kept as a comment hint) rather than
+                # a coordinate that will rot and pass green against the
+                # wrong pixel later.
+                self.d.mouse.click(cx, cy)
+                code_lines = [
+                    f"    with allure.step('Click: [{l_value}] (UNREPLAYABLE: visual)'):\n",
+                    "        import pytest\n",
+                    f"        # Located only via VLM screenshot at ({cx}, {cy}); no DOM locator exists.\n",
+                    f"        # d.mouse.click({cx}, {cy})  # original visual hit, reference only\n",
+                    f"        pytest.skip('Visual-fallback step for [{l_value}] has no durable locator; add a selector to make it replayable')\n",
+                ]
+                result["success"] = True
+                result["code_lines"] = code_lines
+                result["action_description"] = f"⏭️ [Visual Fallback] {l_value} unreplayable — skip emitted"
+                return result
+        except Exception as e:
+            log.warning(f"⚠️ [Visual Fallback] Attempt failed: {e}")
+        return None
+
     def execute_and_record(self, action_data: dict, file_obj=None) -> dict:
         action = action_data.get("action")
         l_type = action_data.get("locator_type", "global")
@@ -1339,106 +1440,14 @@ class UIExecutor:
                 return result
 
             if element is None and u2_key == "ref" and self.platform == "web":
-                el_data = self.resolve_ref(l_value)
-                # The id→text chain in get_actual_element missed this ref, but the
-                # element dict may still carry name/role/desc/placeholder. Recover
-                # the SAME stable locator we'd emit (build_fallback_locator) as a
-                # LIVE handle and re-drive the action's own handler on it — so an
-                # input stays an input, a hover stays a hover, etc. The handler's
-                # execute() validates the locator resolves (discharges the "locator
-                # points at a different element than the pixel" trap) and its
-                # generate_code() persists that stable locator — never a pixel.
-                fb_element = get_fallback_element(self.d, el_data) if el_data else None
-                if fb_element is not None and build_fallback_locator(el_data):
-                    try:
-                        if handler.execute(self.d, fb_element, self.platform, extra_value):
-                            # generate_code with u2_key="ref" + the live resolve_ref
-                            # rebuilds the SAME stable fragment build_fallback_locator
-                            # produced (build_code's ref branch calls it) — so the
-                            # persisted locator exactly matches the handle we just
-                            # acted on. Then humanize the [@N] labels to readable.
-                            code_lines = handler.generate_code(
-                                self.platform, "ref", l_value, extra_value,
-                                config.DEFAULT_TIMEOUT, resolve_ref=self.resolve_ref,
-                            )
-                            readable = readable_ref_target(el_data)
-                            if readable and readable != l_value:
-                                code_lines = humanize_step_labels(code_lines, l_value, readable)
-                            result["success"] = True
-                            result["code_lines"] = code_lines
-                            result["action_description"] = (
-                                f"🔁 [Ref] {action} {l_value} via recovered locator"
-                            )
-                            return result
-                        log.warning(f"⚠️ [Ref] Recovered locator did not satisfy {action}")
-                    except Exception as e:
-                        log.warning(f"⚠️ [Ref] Recovered locator failed to act: {e}")
-                # No stable locator. Act LIVE via coordinate ONLY for click (the
-                # sole action a bare coordinate can perform) so a recording session
-                # still advances; persist an honest, non-passing skip rather than a
-                # silently-rotting coordinate. For non-click actions there is
-                # nothing a coordinate can do — report a real engine failure.
-                if action == "click" and el_data and el_data.get("w", 0) > 0:
-                    cx = el_data["x"] + el_data["w"] // 2
-                    cy = el_data["y"] + el_data["h"] // 2
-                    try:
-                        self.d.mouse.click(cx, cy)
-                        log.info(f"🎯 [Ref] {l_value} clicked at ({cx}, {cy}) live (not persisted)")
-                    except Exception as e:
-                        log.error(f"❌ [Error] Coordinate click failed: {e}")
-                        return result
-                    log.warning(
-                        f"[E036] Ref {l_value} has no stable locator (only coordinates). "
-                        f"Emitting pytest.skip so the test isn't silently green."
-                    )
-                    code_lines = [
-                        f"    with allure.step('Click: [{l_value}] (UNREPLAYABLE)'):\n",
-                        "        import pytest\n",
-                        f"        # Ref {l_value} could only be located by coordinate at record time;\n",
-                        "        # no durable selector exists. Provide one before treating this as real.\n",
-                        f"        pytest.skip('Ref {l_value} has no durable locator (coordinate-only at record time)')\n",
-                    ]
-                    result["success"] = True
-                    result["code_lines"] = code_lines
-                    result["action_description"] = f"⏭️ [Ref] {l_value} unreplayable — skip emitted"
-                    return result
-                log.error(format_log("E037") + f" (ref={l_value}, action='{action}')")
-                result["error_code"] = "E037"
-                return result
+                return self._recover_web_ref(handler, action, l_value, extra_value, result)
 
             # Visual fallback can only CLICK (a VLM returns a point, nothing
             # else) — never engage it for input/hover/assert/etc.
             if element is None and self.platform == "web" and action == "click":
-                try:
-                    from common.visual_fallback import visual_locate
-                    screenshot_bytes = self.d.screenshot()
-                    coords = visual_locate(
-                        screenshot_bytes,
-                        f"{l_type}={l_value}",
-                    )
-                    if coords:
-                        cx, cy = coords
-                        log.info(f"👁️ [Visual Fallback] Using VLM coordinates: ({cx}, {cy})")
-                        # Click live so the session advances, but the visual
-                        # fallback has NO DOM node — only a VLM screenshot hit —
-                        # so there is no durable locator to emit. Persist a skip
-                        # (with the coordinate kept as a comment hint) rather than
-                        # a coordinate that will rot and pass green against the
-                        # wrong pixel later.
-                        self.d.mouse.click(cx, cy)
-                        code_lines = [
-                            f"    with allure.step('Click: [{l_value}] (UNREPLAYABLE: visual)'):\n",
-                            "        import pytest\n",
-                            f"        # Located only via VLM screenshot at ({cx}, {cy}); no DOM locator exists.\n",
-                            f"        # d.mouse.click({cx}, {cy})  # original visual hit, reference only\n",
-                            f"        pytest.skip('Visual-fallback step for [{l_value}] has no durable locator; add a selector to make it replayable')\n",
-                        ]
-                        result["success"] = True
-                        result["code_lines"] = code_lines
-                        result["action_description"] = f"⏭️ [Visual Fallback] {l_value} unreplayable — skip emitted"
-                        return result
-                except Exception as e:
-                    log.warning(f"⚠️ [Visual Fallback] Attempt failed: {e}")
+                recovered = self._try_visual_fallback(l_type, l_value, result)
+                if recovered is not None:
+                    return recovered
 
             if element is None:
                 log.error(format_log("E033"))

{screenforge-0.6.1 → screenforge-0.7.0}/config/config.py

@@ -43,15 +43,14 @@ AUTO_HEAL_MIN_CONFIDENCE = float(os.getenv("AUTO_HEAL_MIN_CONFIDENCE", 0.7))
 # ==========================================
 # 5. 自动化测试框架配置
 # ==========================================
-# 使用绝对路径，彻底杜绝不同命令路径下生成文件夹位置错乱的问题
-OUTPUT_SCRIPT_FILE = str(BASE_DIR / "test_cases" / "test_auto_generated.py")
-
 # 全局隐式等待时间，强转为 float 确保安全
 DEFAULT_TIMEOUT = float(os.getenv("DEFAULT_TIMEOUT", 30.0))
 
 # ==========================================
 # 6. App 环境配置
 # ==========================================
+# 用户填入各环境/平台的 App 包名或 URL 后，launch_app 会自动拉起；默认留空=不自动启动。
+# 这是文档化的用户旋钮（见 docs/capability-matrix.md），不是死代码。
 APP_ENV_CONFIG = {
     "dev": {
         "android": "",
@@ -68,7 +67,6 @@ CACHE_ENABLED = str(os.getenv("CACHE_ENABLED", "True")).lower() in ('true', '1',
 CACHE_DIR = str(BASE_DIR / '.cache')
 CACHE_TTL_DAYS = int(os.getenv("CACHE_TTL_DAYS", 7))
 CACHE_MAX_SIZE_MB = int(os.getenv("CACHE_MAX_SIZE_MB", 100))
-CACHE_COMPRESSION = str(os.getenv("CACHE_COMPRESSION", "False")).lower() in ('true', '1', 't', 'yes')
 
 CACHE_SIMILARITY_THRESHOLD = float(os.getenv("CACHE_SIMILARITY_THRESHOLD", "0.90"))
 CACHE_EXACT_MATCH_THRESHOLD = float(os.getenv("CACHE_EXACT_MATCH_THRESHOLD", "0.98"))

screenforge-0.7.0/config/env_loader.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+
+def resolve_dotenv_path(project_root: Path):
+    project_root = Path(project_root).resolve()
+    for candidate_root in [project_root, *project_root.parents]:
+        try:
+            entries = {path.name.lower(): path for path in candidate_root.iterdir()}
+        except OSError:
+            continue
+        for file_name in (".env", ".ENV"):
+            candidate = entries.get(file_name.lower())
+            if candidate and candidate.is_file():
+                return candidate
+    return project_root / ".env"
+
+
+def safe_load_dotenv(dotenv_path: Path, override: bool = False) -> bool:
+    # python-dotenv is a hard core dependency (pyproject.toml), so import it
+    # directly — the old hand-rolled fallback parser could never run.
+    from dotenv import load_dotenv
+
+    return bool(load_dotenv(dotenv_path=dotenv_path, override=override))

{screenforge-0.6.1 → screenforge-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "screenforge"
-version = "0.6.1"
+version = "0.7.0"
 description = "AI-driven cross-platform UI automation engine with test script generation"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -71,6 +71,15 @@ ignore_missing_imports = true
 no_implicit_optional = false
 exclude = ["test_cases/", "scripts/", "\\.worktrees/"]
 
+# numpy 2.4+ ships PEP 695 `type X = ...` in its bundled stubs, which mypy rejects
+# under our 3.11 target (requires-python >=3.11, CI matrix tests 3.11). We don't
+# type-check against numpy (cache_manager.py array math only) — skip its stubs so a
+# third-party stub's syntax can't break the whole run. Treats numpy as Any.
+[[tool.mypy.overrides]]
+module = ["numpy.*"]
+follow_imports = "skip"
+follow_imports_for_stubs = true
+
 [[tool.mypy.overrides]]
 module = [
     "common.runtime_modes",

{screenforge-0.6.1 → screenforge-0.7.0}/screenforge.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: screenforge
-Version: 0.6.1
+Version: 0.7.0
 Summary: AI-driven cross-platform UI automation engine with test script generation
 License: MIT
 Project-URL: Homepage, https://github.com/jhinzzz/ScreenForge
@@ -119,6 +119,7 @@ Each step: **inspect → decide → act → verify**. The AI decides, ScreenForg
 - **MCP server**: Any MCP-compatible Agent can drive ScreenForge natively
 - **Structured output**: JSON Lines events + `report/runs/<id>/` artifacts for CI integration
 - **Live Mirror playground**: Watch the generated pytest code grow line-by-line beside a live screenshot as the test runs — `screenforge --playground`. See the [Playground Guide](https://github.com/jhinzzz/ScreenForge/blob/main/docs/playground-guide.md)
+- **Execution-replay review report**: Run any test with `REVIEW_RECORD=1` and get a self-contained, shareable offline `report.html` — a drag-timeline of each step's screenshot + the test source line that triggered it + the DOM tree, plus a `video.gif` filmstrip. Default off, zero overhead. (Web verified; mobile registry/recording seam in place but unverified.)
 
 ## Agent Integration (Claude Code / Cursor / Codex)
 

{screenforge-0.6.1 → screenforge-0.7.0}/screenforge.egg-info/SOURCES.txt

@@ -66,6 +66,7 @@ tests/test_ai_autonomous.py
 tests/test_ai_brain.py
 tests/test_ai_heal.py
 tests/test_android_smoke_live.py
+tests/test_cache_hash.py
 tests/test_cache_manager.py
 tests/test_capabilities.py
 tests/test_cli_action_json.py
@@ -87,6 +88,16 @@ tests/test_parser.py
 tests/test_playground_app.py
 tests/test_playground_sink.py
 tests/test_playground_sink_integration.py
+tests/test_review_cases.py
+tests/test_review_conftest_gating.py
+tests/test_review_filmstrip.py
+tests/test_review_html.py
+tests/test_review_json.py
+tests/test_review_locate_frame.py
+tests/test_review_patching.py
+tests/test_review_recorder.py
+tests/test_review_screenshot.py
+tests/test_review_smoke_live.py
 tests/test_run_reporter.py
 tests/test_run_resume.py
 tests/test_runtime_modes.py