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

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

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

{godot_cli_control-0.2.6 → godot_cli_control-0.2.8}/addons/godot_cli_control/README.md

@@ -93,11 +93,12 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 | `action_press(action)` | `await client.action_press("jump")` |
 | `action_release(action)` | `await client.action_release("jump")` |
 | `action_tap(action, duration)` | `await client.action_tap("attack", 0.1)` |
-| `input_get_pressed` (raw RPC) | `await client.request("input_get_pressed")` |
 | `hold(action, duration)` | `await client.hold("run", 1.5)` |
 | `combo(steps)` | `await client.combo([{"action": "jump", "duration": 0.1}])` |
 | `combo_cancel()` | `await client.combo_cancel()` |
 | `release_all()` | `await client.release_all()` |
+| `get_pressed()` | `await client.get_pressed()` |
+| `list_input_actions(include_builtin=False)` | `await client.list_input_actions()` |
 
 ### Error codes
 

{godot_cli_control-0.2.6 → 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.6'
-__version_tuple__ = version_tuple = (0, 2, 6)
+__version__ = version = '0.2.8'
+__version_tuple__ = version_tuple = (0, 2, 8)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.6 → 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 子命令 ──
 
 
@@ -670,7 +697,7 @@ RPC_SPECS: tuple[RpcSpec, ...] = (
         handler=cmd_wait_time,
         description="按 game time 等待 N 秒（在 --write-movie 模式下与录像帧对齐）。",
         positionals=(
-            Positional("seconds", None, "等待秒数（>0）"),
+            Positional("seconds", None, "等待秒数（服务端范围 0 ≤ seconds ≤ 3600；client 在 ≤0 时短路返回成功）"),
         ),
         example="wait-time 0.5",
         text_formatter=_fmt_wait_time_text,
@@ -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.6 → 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.6 → 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
 
@@ -42,7 +44,8 @@ godot-cli-control daemon stop
 |---|---|
 | 0 | Success (or, for `exists` / `visible` / `wait-node`, the boolean was true / found) |
 | 1 | RPC error (server returned `{"error":...}`); also `exists`/`visible`=false, `wait-node`=timeout, `daemon status`=stopped |
-| 2 | Connection / IO / usage error (daemon not running, malformed `combo` input, etc.) |
+| 2 | Connection / IO / usage error (daemon not running, malformed `combo` input, script path not found). Also: **`daemon stop` returns 2** when the daemon stopped cleanly but `ffmpeg` transcode of the recorded `.avi`→`.mp4` failed — the raw `.avi` is kept and `.cli_control/ffmpeg.log` has the details. `run <script>` propagates this: a successful script + failed transcode still exits 2. |
+| 3 | `daemon stop --all` partial failure: at least one daemon in the registry failed to stop. Per-record `rc` is in the JSON `result.stopped[]`. |
 | 64 | Argparse usage error |
 
 Shell-`if` works:
@@ -53,6 +56,22 @@ if godot-cli-control exists /root/Main/Boss; then
 fi
 ```
 
+## Daemon management
+
+```bash
+godot-cli-control daemon start             # boot daemon for cwd project
+godot-cli-control daemon status            # exit 0 = running, 1 = stopped
+godot-cli-control daemon stop              # stop cwd-project daemon (rc 0; rc 2 = ffmpeg transcode failed)
+godot-cli-control daemon stop --project /path/to/other/godot/project
+godot-cli-control daemon stop --all        # stop every registered daemon; exit 3 if any failed
+godot-cli-control daemon ls                # list all running daemons (cross-project, walks the registry)
+```
+
+- **`daemon status` payload when running**: `{"state": "running", "pid": N, "port": M}`.
+- **`daemon status` payload when stopped**: `{"state": "stopped"}`. If the previous launch wrote `.cli_control/godot.log` or recorded an exit code, the envelope also includes `"last_log": "<path>"` and/or `"last_exit_code": <int>` — use these to diagnose why the daemon died without manually grepping under `.cli_control/`.
+- **`daemon ls` payload**: `{"daemons": [{"project_root", "pid", "port", "started_at", "godot_bin", "log_path"}, ...]}`. Dead records (PID gone) are auto-pruned on each call, so this is the canonical list of *actually-alive* daemons across all projects on the machine.
+- **`daemon stop --all` payload**: `{"stopped": [{"project_root","pid","port","rc"[, "error"]}, ...], "rc": 0|3}`. Each entry's `rc` is the per-project stop result; the top-level `rc` is the aggregate exit code.
+
 ## JSON envelope examples
 
 ```bash
@@ -90,10 +109,10 @@ Three numeric ranges cohabit in `error.code`. Knowing which is which lets you de
 |---|---|
 | `1001` | Node not found at the given path. Most common — usually the agent passed a wrong / not-yet-loaded path. Retry after `wait-node`. |
 | `1002` | Property not found on the node, or shape mismatch (e.g. `text` on a node that doesn't have it). Don't retry; inspect with `tree`. |
-| `1003` | Method not found on the node. Schema error — don't retry, inspect with `tree`. |
+| `1003` | Method not found on the node, **or** unknown InputMap action passed to `press`/`release`/`tap`/`hold`/`combo` (`"Unknown action: <name>"`). Schema error — don't retry. For node methods inspect with `tree`; for missing actions run `actions` (or `actions --all`). |
 | `1004` | Combo already in progress. Call `combo-cancel` (or `release-all`) and re-issue. Safe to retry after that. |
 | `1005` | Scene tree too large to serialize (default safety limit). Pass `--max-nodes` or query a subtree with `children` / `tree <subpath>`. Don't retry as-is. |
-| `1006` | Resource transiently unavailable (e.g. screenshot during scene transition / window resize). Rare under normal use: GameBridge waits for viewport first-frame before accepting connections, and `screenshot` retries internally up to ~500ms. If you still see this, retry after `wait-time 0.05` or similar. |
+| `1006` | Resource transiently unavailable (e.g. screenshot during scene transition / window resize). Rare under normal use: GameBridge waits for viewport first-frame before accepting connections, and `screenshot` retries internally up to ~30 frames (~500ms at 60 fps, ~1s at 30 fps, longer when `--write-movie` lowers the fixed fps). If you still see this, retry after `wait-time 0.05` or similar. |
 
 **JSON-RPC standard — negative integers `-32xxx`:**
 
@@ -143,7 +162,7 @@ Server vs client ranges never overlap, so a single `code` field is unambiguous.
 
 **Wait:**
 - `wait-node <path> [timeout]` — block until node appears (exit 0=found, 1=timeout)
-- `wait-time <seconds>` — wait N in-game seconds (matters for `--write-movie`)
+- `wait-time <seconds>` — wait N in-game seconds (matters for `--write-movie`). Server bounds: `0 ≤ seconds ≤ 3600`; passing out-of-range gets `-32602 "seconds must be ..."`. Client short-circuits `seconds <= 0` without an RPC.
 
 **Render:**
 - `screenshot <path>` — write PNG (path is **required** as of 0.2.0)
@@ -190,7 +209,7 @@ godot-cli-control call /root/Game start_game 1 '"easy"'    # int 1, string "easy
 
 So `position '[100, 200]'` → `Vector2(100, 200)`, `transform '[1,0,0, 0,1,0, 0,0,1, 10,20,30]'` → `Transform3D(IDENTITY, (10,20,30))`. Wrong length or non-numeric elements fail loud with `-32602 "value type mismatch ..."` instead of silently setting `(0, 0)` like pre-0.2.5 versions did.
 
-**Sub-path + Array also fails loud.** `set <node> transform:origin '[10, 20, 30]'` is rejected with `-32602 "sub-path + Array is not supported"`: Godot's `Object.set("transform:origin", Array)` silently drops the Array (origin stays at `(0,0,0)`) — same footgun class as #52, so the server pre-empts it. Sub-paths are scalar-only (`set <node> position:x 1.8`); to write a whole compound Variant use the top-level Array form above.
+**Sub-path + Array also fails loud.** `set <node> transform:origin '[10, 20, 30]'` is rejected with `-32602 "sub-path + Array is not supported"`: Godot's `Object.set("transform:origin", Array)` silently drops the Array (origin stays at `(0,0,0)`) — same class of footgun as the strict Variant checks above, so the server pre-empts it. Sub-paths are scalar-only (`set <node> position:x 1.8`); to write a whole compound Variant use the top-level Array form above.
 
 **Footgun**: bare `null` / `true` / `false` / numeric strings parse as JSON literals first, **not** as strings. If you actually mean the string `"null"`, wrap it explicitly:
 
@@ -294,7 +313,7 @@ Errors raise `RpcError(code, message)` (a `RuntimeError` subclass) that preserve
 | `await client.is_visible(path)` | `visible <path>` |
 | `await client.get_children(path)` | `children <path>` |
 | `await client.screenshot()` | `screenshot <path>` |
-| `await client.get_scene_tree(depth)` | `tree [depth]` |
+| `await client.get_scene_tree(depth, max_nodes=None)` | `tree [depth] [--max-nodes N]` |
 | `await client.wait_for_node(path, timeout)` | `wait-node <path> [timeout]` |
 | `await client.wait_game_time(seconds)` | `wait-time <seconds>` |
 | `await client.action_press(action)` | `press <action>` |
@@ -321,6 +340,12 @@ def run(bridge):
 
 `bridge` is a synchronous wrapper around `GameClient` — same method names, no `await`. Sibling-imports work (the script's directory is on `sys.path`).
 
+**Exit code (when `run` started the daemon itself):**
+- `0` — script succeeded and daemon stopped cleanly.
+- `1` — script raised (envelope carries `code: -1005` with the exception summary; full traceback on stderr).
+- `2` — script-path / daemon-start failed, **or** the script succeeded but the auto-`daemon stop` afterwards hit an ffmpeg transcode failure (success envelope still emits, with `daemon_stop_warning` populated; raw `.avi` is preserved).
+- `64` — argparse usage error (e.g. malformed `--idle-timeout`).
+
 ## pytest plugin (preferred for end-to-end test suites)
 
 `pip install godot-cli-control[pytest]` registers a `pytest11` entry-point that exposes two fixtures, so a Godot e2e test is a one-liner:
@@ -367,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.6 → 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.6 → 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)"