godot-cli-control 0.2.7__tar.gz → 0.2.8__tar.gz

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.7
+Version: 0.2.8
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/godot_cli_control/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.7'
-__version_tuple__ = version_tuple = (0, 2, 7)
+__version__ = version = '0.2.8'
+__version_tuple__ = version_tuple = (0, 2, 8)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/godot_cli_control/cli.py

@@ -60,17 +60,26 @@ CLIENT_CODE_SCRIPT_ERROR = -1005  # `run <script>` 用户脚本抛出未捕获
 CLIENT_CODE_INTERNAL = -1099  # 兜底：客户端内部异常（理论上不该到这里，但兜住契约）
 
 
-def _resolve_headless(ns: argparse.Namespace) -> bool:
+def _resolve_headless(
+    ns: argparse.Namespace, *, force_gui_hint: bool = False
+) -> bool:
     """决定本次 daemon start 是否走 --headless。
 
-    优先级：显式 --headless > 显式 --gui > stdout.isatty() 自动判。
+    优先级：显式 --headless > 显式 --gui > force_gui_hint > stdout.isatty() 自动判。
     isatty=False（pipe / redirect / 非 TTY agent shell）默认 headless；
     isatty=True（开发者交互终端）默认开窗。
+
+    ``force_gui_hint``：调用方（``cmd_run``）静态检测脚本含 ``screenshot`` 时传
+    True，让没显式指定 ``--headless`` / ``--gui`` 的非 TTY 场景（subagent / pipe）
+    自动改走 GUI —— headless 下 dummy renderer 拿不到 viewport texture，screenshot
+    永远 1006 fail（issue #65）。
     """
     if getattr(ns, "headless", False):
         return True
     if getattr(ns, "gui", False):
         return False
+    if force_gui_hint:
+        return False
     try:
         return not sys.stdout.isatty()
     except (OSError, ValueError):
@@ -79,6 +88,24 @@ def _resolve_headless(ns: argparse.Namespace) -> bool:
         return True  # 安全默认
 
 
+def _script_likely_uses_screenshot(script_path: Path) -> bool:
+    """启发式：脚本源码是否含 ``screenshot`` 子串。
+
+    保守策略 —— 误报（多开一次窗）成本远低于漏报（截图静默 1006 fail）。
+    简单子串足以覆盖 ``bridge.screenshot(...)`` / ``client.screenshot()`` /
+    间接 ``getattr(bridge, "screenshot")``；comment / docstring 命中也无所谓，
+    最坏只是 subagent 多看到一个窗口。
+
+    读不到（OSError / decode 失败）时返回 False —— 让 cmd_run 走原来的 isatty
+    默认，至少不会把"脚本不存在"的报错被本检测吞掉。
+    """
+    try:
+        text = script_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    return "screenshot" in text
+
+
 # ── RpcSpec：声明一个 RPC 子命令 ──
 
 
@@ -944,11 +971,17 @@ def cmd_run(ns: argparse.Namespace) -> int:
         daemon = Daemon(Path.cwd())
         auto_started = False
         if not daemon.is_running():
+            # 静态检测脚本含 screenshot 时，非 TTY 默认从 headless 翻转到 GUI
+            # （issue #65）。显式 --headless / --gui / --no-gui-auto 都能 opt-out。
+            force_gui_hint = (
+                not getattr(ns, "no_gui_auto", False)
+                and _script_likely_uses_screenshot(script_path)
+            )
             try:
                 daemon.start(
                     record=ns.record,
                     movie_path=ns.movie_path,
-                    headless=_resolve_headless(ns),
+                    headless=_resolve_headless(ns, force_gui_hint=force_gui_hint),
                     fps=ns.fps,
                     port=ns.port,
                     idle_timeout=idle_seconds,
@@ -1491,6 +1524,15 @@ def build_parser() -> argparse.ArgumentParser:
     )
     run_p.add_argument("script", help="用户脚本路径，需定义 run(bridge)")
     _add_daemon_flags(run_p)
+    run_p.add_argument(
+        "--no-gui-auto",
+        action="store_true",
+        help=(
+            "禁用脚本静态检测自动 GUI。默认含 screenshot 调用的脚本在非 TTY "
+            "（subagent / pipe / CI）下也强制开窗 —— headless dummy renderer "
+            "拿不到 viewport texture，截图会 1006 fail。"
+        ),
+    )
     _add_output_format_flags(run_p)
 
     # init：一键接入

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/godot_cli_control/client.py

@@ -14,6 +14,17 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_PORT: int = 9877
 
+# 长操作（wait_game_time / combo）的客户端 wall-time 生死线。
+#
+# 这类操作的「完成」是 game-time 维度（Godot 帧数推进），与 wall time 关系不可
+# 预测：Movie Maker (--write-movie) 模式下 wall ≈ 4-5× game，且随分辨率/fps/盘速
+# 漂移。任何 seconds-scaled 公式都会在某个组合下假超时（issue #45）。
+#
+# 改用固定大值后：正常完成时 server 自然回包；server 真死循环时由 600s 兜底
+# （而不是 55s 把还活着的录像炸掉）；死连接由 websockets 库的 ping/pong 心跳
+# 在 ~40s 内独立检测，与本上限无关。
+LONG_OP_CLIENT_TIMEOUT: float = 600.0
+
 
 class RpcError(RuntimeError):
     """Raised when GameBridge returns a JSON-RPC error response.
@@ -100,6 +111,11 @@ class GameClient:
                     f"ws://127.0.0.1:{self._port}",
                     proxy=None,
                     open_timeout=open_timeout,
+                    # 显式锁住 ws 心跳——issue #45 治本依赖：long ops 去掉
+                    # seconds-scaled wall 上限后，死连接靠这层独立检测。
+                    # 与 websockets 当前默认对齐，防库升级悄悄改默认。
+                    ping_interval=20,  # 每 20s 无流量发一次 ping
+                    ping_timeout=20,   # pong 20s 未回 → 关连接（≈40s 内可发现死链）
                 )
                 self._listen_task = asyncio.create_task(self._listen())
                 logger.info("Connected to GameBridge on port %d", self._port)
@@ -263,8 +279,9 @@ class GameClient:
     async def wait_game_time(self, seconds: float) -> dict:
         """按 Godot game time 等待 N 秒。
 
-        Movie Maker (--write-movie) 模式下 wall time 比 game time 慢约 2-3×，
-        客户端 timeout 用 seconds * 3 + 10 安全系数，与 combo() 一致。
+        客户端用固定 ``LONG_OP_CLIENT_TIMEOUT`` 生死线（issue #45）：game-time
+        与 wall-time 比值受录像模式 / 分辨率 / 盘速 / fps 影响不可预测，任何
+        seconds-scaled 公式都会在某个组合下假超时。死连接由 ws ping/pong 兜底。
         seconds <= 0 时客户端短路返回，不发 RPC。
         """
         if seconds <= 0:
@@ -272,7 +289,7 @@ class GameClient:
         return await self.request(
             "wait_game_time",
             {"seconds": seconds},
-            timeout=seconds * 3.0 + 10.0,
+            timeout=LONG_OP_CLIENT_TIMEOUT,
         )
 
     # ---- Input simulation API ----
@@ -294,14 +311,10 @@ class GameClient:
         )
 
     async def combo(self, steps: list[dict]) -> dict:
-        total = sum(
-            s.get("duration", 0) or s.get("wait", 0) for s in steps
-        )
-        # movie maker (--write-movie) 模式下 Godot 渲染比实时慢（大分辨率 +
-        # MJPEG 编码开销），客户端墙钟等待需要 3× 安全系数 + 10s base，
-        # 避免 combo 还没在游戏时间跑完就被 TimeoutError 打断。
+        # 客户端用固定 LONG_OP_CLIENT_TIMEOUT 生死线（issue #45）：见
+        # wait_game_time 注释——同样的 game-time / wall-time 不对齐问题。
         return await self.request(
-            "input_combo", {"steps": steps}, timeout=total * 3.0 + 10.0
+            "input_combo", {"steps": steps}, timeout=LONG_OP_CLIENT_TIMEOUT
         )
 
     async def combo_cancel(self) -> dict:

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/godot_cli_control/templates/skill/SKILL.md

@@ -35,6 +35,8 @@ godot-cli-control daemon stop
 ```
 
 > As of this version, `daemon start` autodetects headless mode by checking `stdout.isatty()`. Pipes, CI, and agent shell-outs run headless by default; an interactive terminal still gets a window. The explicit flags below are only needed to override: `--headless` forces headless even in a TTY; `--gui` forces a window even when stdout is piped.
+>
+> **`run <script>` adds one more layer**: it grep's the script source for `screenshot`. If found, headless is force-flipped to GUI even on non-TTY shells — headless dummy renderer can't read viewport texture, so `bridge.screenshot(...)` would otherwise hard-fail with code `1006`. Pass `--no-gui-auto` to disable this detection; explicit `--headless` / `--gui` still win.
 
 ## Exit codes
 
@@ -390,6 +392,7 @@ pytest_plugins = ["godot_cli_control.pytest_plugin"]
 - **`tree` returns `1005 "scene tree too large"`** — your scene has more than 5000 visible nodes (a Grid / spawned-bullets situation). Pass `--max-nodes 200` to cap, or `children <path>` for one specific subtree.
 - **`set` with a string that *looks* like JSON** — value parser parses JSON first. To force a literal `"42"` string, pass `'"42"'`; to set a literal hash sign or array text, JSON-encode it.
 - **`daemon start` opens a window when I expected headless** — your stdout is a TTY (interactive terminal). Pass `--headless` explicitly, or shell out from a context where stdout is piped.
+- **`run <script>` opens a window even though stdout is piped** — by design. `run` grep's the script for `screenshot` and force-flips to GUI when found, so `bridge.screenshot(...)` doesn't 1006-fail under the dummy renderer. Pass `--no-gui-auto` to disable detection; explicit `--headless` always wins. See issue #65.
 - **`screenshot` used to fail with `1006` on the first call** — fixed. GameBridge now waits for the viewport's first frame before opening the port, so `connect succeeded` implies `viewport has rendered ≥ once`. The magic `bridge.wait(1.5)` before the first screenshot in older example scripts is no longer needed.
 
 ---

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/tests/test_cli.py

@@ -1733,6 +1733,191 @@ class TestDaemonHeadlessAutodetect:
         with pytest.raises(SystemExit):
             parser.parse_args(["daemon", "start", "--headless", "--gui"])
 
+    def test_force_gui_hint_flips_pipe_to_gui(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """脚本含 screenshot 时 cmd_run 传 force_gui_hint=True，
+        非 TTY 默认从 headless 翻成 GUI（issue #65）。"""
+        from godot_cli_control.cli import _resolve_headless
+
+        monkeypatch.setattr("sys.stdout.isatty", lambda: False)
+        ns = type("NS", (), {"headless": False, "gui": False})()
+        assert _resolve_headless(ns, force_gui_hint=True) is False
+
+    def test_explicit_headless_still_wins_over_force_gui_hint(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """用户显式 --headless 永远赢 —— 即使脚本含 screenshot，
+        用户也可能就是想跑 headless（CI 不需要截图的子集等）。"""
+        from godot_cli_control.cli import _resolve_headless
+
+        monkeypatch.setattr("sys.stdout.isatty", lambda: False)
+        ns = type("NS", (), {"headless": True, "gui": False})()
+        assert _resolve_headless(ns, force_gui_hint=True) is True
+
+
+class TestScriptLikelyUsesScreenshot:
+    def test_detects_method_call(self, tmp_path: Path) -> None:
+        from godot_cli_control.cli import _script_likely_uses_screenshot
+
+        script = tmp_path / "s.py"
+        script.write_text(
+            "def run(bridge):\n    bridge.screenshot('/tmp/x.png')\n",
+            encoding="utf-8",
+        )
+        assert _script_likely_uses_screenshot(script) is True
+
+    def test_no_match_when_script_clean(self, tmp_path: Path) -> None:
+        from godot_cli_control.cli import _script_likely_uses_screenshot
+
+        script = tmp_path / "s.py"
+        script.write_text("def run(bridge):\n    bridge.click('/root/A')\n", "utf-8")
+        assert _script_likely_uses_screenshot(script) is False
+
+    def test_missing_file_returns_false_not_raises(self, tmp_path: Path) -> None:
+        """读不到不抛 —— 让 cmd_run 走原 isatty 默认，"脚本不存在"
+        由后续 script_path.exists() 检查统一报错。"""
+        from godot_cli_control.cli import _script_likely_uses_screenshot
+
+        assert _script_likely_uses_screenshot(tmp_path / "missing.py") is False
+
+
+class TestCmdRunGuiAutoDetect:
+    """issue #65：cli run 静态检测脚本含 screenshot 时，非 TTY 也强制开窗。"""
+
+    @staticmethod
+    def _mock_run_pipeline(
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> dict[str, Any]:
+        """拦截 daemon.start / is_running / current_port / stop +
+        _exec_user_script，让 cmd_run 跑完整路径但不真起进程。
+        返回 dict 记录 daemon.start kwargs，测试断言用。"""
+        import godot_cli_control.cli as cli_mod
+        import godot_cli_control.daemon as daemon_mod
+
+        captured: dict[str, Any] = {}
+
+        def _is_running(self: Any) -> bool:
+            return False
+
+        def _start(self: Any, **kw: Any) -> None:
+            captured["start_kwargs"] = kw
+
+        def _current_port(self: Any) -> int:
+            return 12345
+
+        def _stop(self: Any) -> int:
+            return 0
+
+        monkeypatch.setattr(daemon_mod.Daemon, "is_running", _is_running)
+        monkeypatch.setattr(daemon_mod.Daemon, "start", _start)
+        monkeypatch.setattr(daemon_mod.Daemon, "current_port", _current_port)
+        monkeypatch.setattr(daemon_mod.Daemon, "stop", _stop)
+        monkeypatch.setattr(
+            cli_mod,
+            "_exec_user_script",
+            lambda *a, **kw: 0,
+        )
+        # 非 TTY ── 模拟 subagent / pipe / CI
+        monkeypatch.setattr("sys.stdout.isatty", lambda: False)
+        return captured
+
+    def test_script_with_screenshot_forces_gui_under_pipe(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        import argparse
+
+        from godot_cli_control.cli import OUTPUT_JSON, cmd_run
+
+        captured = self._mock_run_pipeline(monkeypatch)
+        script = tmp_path / "s.py"
+        script.write_text(
+            "def run(bridge):\n    bridge.screenshot('/tmp/x.png')\n",
+            encoding="utf-8",
+        )
+        ns = argparse.Namespace(
+            script=str(script),
+            record=False,
+            movie_path=None,
+            headless=False,
+            gui=False,
+            no_gui_auto=False,
+            fps=30,
+            port=0,
+            idle_timeout="0",
+            output_format=OUTPUT_JSON,
+        )
+        rc = cmd_run(ns)
+        assert rc == 0
+        # 非 TTY 默认 headless=True，但脚本含 screenshot → 翻转到 False
+        assert captured["start_kwargs"]["headless"] is False
+
+    def test_no_gui_auto_disables_detection(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        import argparse
+
+        from godot_cli_control.cli import OUTPUT_JSON, cmd_run
+
+        captured = self._mock_run_pipeline(monkeypatch)
+        script = tmp_path / "s.py"
+        script.write_text(
+            "def run(bridge):\n    bridge.screenshot('/tmp/x.png')\n",
+            encoding="utf-8",
+        )
+        ns = argparse.Namespace(
+            script=str(script),
+            record=False,
+            movie_path=None,
+            headless=False,
+            gui=False,
+            no_gui_auto=True,  # ← opt-out
+            fps=30,
+            port=0,
+            idle_timeout="0",
+            output_format=OUTPUT_JSON,
+        )
+        rc = cmd_run(ns)
+        assert rc == 0
+        # opt-out → 回到 isatty 默认（非 TTY = headless）
+        assert captured["start_kwargs"]["headless"] is True
+
+    def test_script_without_screenshot_keeps_headless_default(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        import argparse
+
+        from godot_cli_control.cli import OUTPUT_JSON, cmd_run
+
+        captured = self._mock_run_pipeline(monkeypatch)
+        script = tmp_path / "s.py"
+        script.write_text(
+            "def run(bridge):\n    bridge.click('/root/A')\n",
+            encoding="utf-8",
+        )
+        ns = argparse.Namespace(
+            script=str(script),
+            record=False,
+            movie_path=None,
+            headless=False,
+            gui=False,
+            no_gui_auto=False,
+            fps=30,
+            port=0,
+            idle_timeout="0",
+            output_format=OUTPUT_JSON,
+        )
+        rc = cmd_run(ns)
+        assert rc == 0
+        # 脚本无 screenshot → 不触发翻转，按 isatty=False 走 headless
+        assert captured["start_kwargs"]["headless"] is True
+
 
 def test_run_rpc_tree_truncated_envelope(
     capsys: pytest.CaptureFixture[str],

{godot_cli_control-0.2.7 → godot_cli_control-0.2.8}/python/tests/test_client.py

@@ -9,7 +9,7 @@ from unittest.mock import AsyncMock, patch
 import pytest
 import websockets
 
-from godot_cli_control.client import GameClient
+from godot_cli_control.client import LONG_OP_CLIENT_TIMEOUT, GameClient
 
 
 # ---- Test 1: proxy=None 显式传给 websockets.connect ----
@@ -465,3 +465,85 @@ async def test_get_scene_tree_omits_max_nodes_when_none() -> None:
         client_mod.GameClient.request = monkeypatch_target
     assert captured["params"] == {"depth": 2}
     assert "max_nodes" not in captured["params"]
+
+
+# ---- issue #45: wait_game_time / combo 不能给 game-time 操作设 wall-time 上限 ----
+#
+# 旧公式 seconds*3+10 假设 wall ≤ 3× game，在 Movie Maker (--write-movie) 模式下
+# 实测 wall ≈ 4-5× game，必假超时（bridge.wait(15) → 55s timeout < 60s+ wall）。
+# 治本：去掉 seconds-scaled wall 上限，固定一个生死线，死连接靠 ws ping/pong。
+#
+# 测试用「两次差距大的 seconds 拿到同一 timeout」直接证明 decoupling，
+# 比单点等值断言更稳——后者跟「巧合 == 常量」的假阳性形态无法区分。
+
+
+@pytest.mark.asyncio
+async def test_wait_game_time_client_timeout_decoupled_from_seconds() -> None:
+    """issue #45: wait_game_time 客户端 timeout 必须与 seconds 解耦。"""
+    import godot_cli_control.client as client_mod
+
+    captured: list = []
+
+    async def fake_request(self, method, params=None, timeout=30.0):
+        captured.append(timeout)
+        return {"success": True}
+
+    client = client_mod.GameClient(port=1)
+    monkeypatch_target = client_mod.GameClient.request
+    client_mod.GameClient.request = fake_request  # type: ignore
+    try:
+        await client.wait_game_time(1.0)
+        await client.wait_game_time(120.0)
+    finally:
+        client_mod.GameClient.request = monkeypatch_target
+    assert captured == [LONG_OP_CLIENT_TIMEOUT, LONG_OP_CLIENT_TIMEOUT], (
+        f"wait_game_time 应固定使用 {LONG_OP_CLIENT_TIMEOUT}s 生死线、与 seconds 无关，"
+        f"实际 {captured}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_combo_client_timeout_decoupled_from_steps_total() -> None:
+    """issue #45: combo() 与 wait_game_time 同源问题，client timeout 同样与 total 解耦。"""
+    import godot_cli_control.client as client_mod
+
+    captured: list = []
+
+    async def fake_request(self, method, params=None, timeout=30.0):
+        captured.append(timeout)
+        return {"success": True}
+
+    client = client_mod.GameClient(port=1)
+    monkeypatch_target = client_mod.GameClient.request
+    client_mod.GameClient.request = fake_request  # type: ignore
+    try:
+        await client.combo([{"action": "x", "duration": 0.5}])
+        await client.combo([{"action": "x", "duration": 60.0}])
+    finally:
+        client_mod.GameClient.request = monkeypatch_target
+    assert captured == [LONG_OP_CLIENT_TIMEOUT, LONG_OP_CLIENT_TIMEOUT]
+
+
+@pytest.mark.asyncio
+async def test_connect_locks_ws_ping_keepalive() -> None:
+    """issue #45 治本依赖：去掉 wall 上限后，死连接靠 ws ping/pong 检测。
+
+    显式锁住 ping_interval / ping_timeout（与 websockets 默认对齐），
+    防库升级把默认改了导致死连接卡 600s。
+    """
+    fake_ws = AsyncMock()
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(return_value=fake_ws),
+    ) as mock_connect:
+        client = GameClient(port=9999)
+        try:
+            await client.connect(retries=1)
+        finally:
+            if client._listen_task:
+                client._listen_task.cancel()
+        _, kwargs = mock_connect.call_args
+        assert kwargs.get("ping_interval") == 20, \
+            "GameClient.connect() must lock ping_interval (ws keepalive)"
+        assert kwargs.get("ping_timeout") == 20, \
+            "GameClient.connect() must lock ping_timeout (ws keepalive)"