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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.7
+Version: 0.2.9
 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.9}/addons/godot_cli_control/README.md

@@ -114,7 +114,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `1006` | server | Resource transiently unavailable (e.g. screenshot during scene transition). Rare under normal use — GameBridge waits for viewport first-frame before listening, and `screenshot` retries internally. Safe to retry if you do hit it. |
 | `-32600` | server | Malformed JSON-RPC request |
 | `-32601` | server | Unknown method name |
-| `-32602` | server | Invalid params (incl. blocked methods/properties from the security blacklist, or `set` value-type mismatch — e.g. `Vector2` property given an array of wrong length / non-numeric elements) |
+| `-32602` | server | Invalid params (incl. blocked methods/properties from the security blacklist, `set` value-type mismatch — e.g. `Vector2` property given an array of wrong length / non-numeric elements, or `hold` given `duration ≤ 0` — use `press` for an indefinite hold) |
 | `-1001` | client | Connection failure (daemon not running, port wrong, proxy hijacking localhost) |
 | `-1002` | client | Timeout waiting for response |
 | `-1003` | client | CLI usage error (combo missing steps, malformed `--steps-json`, …) |

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/addons/godot_cli_control/bridge/game_bridge.gd

@@ -143,10 +143,7 @@ func _poll_active_peer() -> void:
 	_active_peer.poll()
 	var state: WebSocketPeer.State = _active_peer.get_ready_state()
 	if state == WebSocketPeer.STATE_CLOSED:
-		print("GameBridge: Client disconnected")
-		_input_sim_api.release_all()
-		_active_peer = null
-		_active_stream = null
+		_handle_disconnect(_active_peer.get_close_code())
 		return
 	if state != WebSocketPeer.STATE_OPEN:
 		return
@@ -156,6 +153,25 @@ func _poll_active_peer() -> void:
 		_handle_message(message)
 
 
+func _handle_disconnect(close_code: int) -> void:
+	print("GameBridge: Client disconnected (close_code=%d)" % close_code)
+	# 区分「命令正常结束」与「异常掉线」，决定是否 release_all：
+	#   - CLI 每条子命令都是独立连接、跑完即干净关闭（WebSocket close frame，
+	#     code 1000）。此时**不** release_all —— 否则 `hold <dur>` 的定时器还没
+	#     倒计时就被清掉（只生效一帧），sticky `press` 也无法跨命令存活。持有的
+	#     输入靠各自机制收尾：hold/tap/combo 的 advance_timers 定时器自然结束，
+	#     sticky press 持续到显式 release / release-all。
+	#   - 客户端崩溃 / 被 kill / 网络断开时不会发 close frame，get_close_code()
+	#     返回 -1（< 0）。此时 release_all 兜底，避免卡死键 + 跨会话脏状态残留。
+	#   （daemon 启动期的端口探活连接也可能是 -1，但那时没有任何持有输入，
+	#    release_all 无副作用。）
+	# pytest 的 bridge fixture 仍在 teardown 自己调 release_all() 做清理。
+	if close_code < 0:
+		_input_sim_api.release_all()
+	_active_peer = null
+	_active_stream = null
+
+
 func _register_methods() -> void:
 	# 低层 API（同步）
 	_methods["click"] = {"callable": _low_level_api.handle_click, "kind": "sync"}

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/addons/godot_cli_control/bridge/input_simulation_api.gd

@@ -113,6 +113,14 @@ func handle_hold(params: Dictionary) -> Dictionary:
 	if not InputMap.has_action(action):
 		return _err(CliControlErrorCodes.METHOD_NOT_FOUND, "Unknown action: %s" % action)
 	var duration: float = params.get("duration", 0.0) as float
+	# duration <= 0 是无意义的「按住 0 秒」：advance_timers 下一帧就释放 → 只生效
+	# 一帧。无限按住请用 press（sticky）。CLI preflight 也会拦，这里是防御纵深，
+	# 挡住绕过 CLI 的直连 RPC。
+	if duration <= 0.0:
+		return _err(
+			CliControlErrorCodes.INVALID_PARAMS,
+			"hold duration must be > 0 (got %s); use press for an indefinite hold" % duration,
+		)
 	_do_press(action)
 	_held_actions[action] = duration
 	return {"success": true}

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/addons/godot_cli_control/tests/gut/test_game_bridge.gd

@@ -70,10 +70,17 @@ class StubInputSimulationApi:
 		# _register_methods 之前测试会手动调一次。
 		combo_callback = send_response
 
+	# 断连测试用的 release_all 调用计数（不 override 行为，仅记账后走父类）
+	var release_all_calls: int = 0
+
 	func handle_action_press(params: Dictionary) -> Dictionary:
 		press_calls.append(params)
 		return press_return
 
+	func release_all() -> void:
+		release_all_calls += 1
+		super()
+
 	func handle_combo(params: Dictionary, request_id: String) -> void:
 		# 不立刻回响 —— 把 (params, request_id) 记下来；测试通过 finish_combo
 		# 显式触发 callback，模拟真实 combo 完成路径。
@@ -122,6 +129,49 @@ func _last_frame() -> Dictionary:
 	return _bridge.captured_frames[-1]
 
 
+# ── 断连按 close code 区分清/不清 ───────────────────────────────────
+# 回归：CLI 每条子命令都是独立连接、跑完即「干净关闭」（close frame，code
+# 1000）。干净关闭不能 release_all，否则 `hold <dur>` 定时器没倒计时就被清掉
+# （只生效一帧），sticky `press` 也无法跨命令存活。只有「异常掉线」（崩溃 /
+# kill / 网络断，get_close_code() == -1）才 release_all 兜底卡死键。
+# handle_hold 是真实逻辑（桩未 override），用它验证 held 状态。
+# 用足够长的 duration，避免测试期间 _process 的 advance_timers 提前释放。
+
+func test_clean_disconnect_preserves_inputs() -> void:
+	var hold_action := "__test_clean_disc__"
+	if not InputMap.has_action(hold_action):
+		InputMap.add_action(hold_action)
+	_input.handle_hold({"action": hold_action, "duration": 999.0})
+	assert_true(hold_action in _input.get_pressed_actions(), "前置：hold 应在持有列表")
+
+	# 1000 = 正常 WebSocket close frame（CLI 命令跑完）
+	_bridge._handle_disconnect(1000)
+
+	assert_eq(_input.release_all_calls, 0, "干净关闭不应调用 release_all（hold/press 须跨命令存活）")
+	assert_true(hold_action in _input.get_pressed_actions(), "干净关闭后 hold 应仍存活")
+	assert_eq(_bridge._active_peer, null, "断连应清掉 _active_peer")
+
+	_input.release_all()
+	InputMap.erase_action(hold_action)
+
+
+func test_abnormal_disconnect_releases_inputs() -> void:
+	var hold_action := "__test_abnormal_disc__"
+	if not InputMap.has_action(hold_action):
+		InputMap.add_action(hold_action)
+	_input.handle_hold({"action": hold_action, "duration": 999.0})
+	assert_true(hold_action in _input.get_pressed_actions(), "前置：hold 应在持有列表")
+
+	# -1 = 异常掉线（无 close frame：崩溃 / kill / 网络断）
+	_bridge._handle_disconnect(-1)
+
+	assert_eq(_input.release_all_calls, 1, "异常掉线应调用 release_all 兜底卡死键")
+	assert_false(hold_action in _input.get_pressed_actions(), "异常掉线后 hold 应被释放")
+	assert_eq(_bridge._active_peer, null, "断连应清掉 _active_peer")
+
+	InputMap.erase_action(hold_action)
+
+
 # ── JSON / 协议层校验：-32600 ──────────────────────────────────────
 
 func test_invalid_json_emits_minus_32600_with_empty_id() -> void:

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/addons/godot_cli_control/tests/gut/test_input_simulation_api.gd

@@ -83,6 +83,22 @@ func test_hold_unknown_action_returns_1003() -> void:
 	assert_false(_api.has_active_holds())
 
 
+func test_hold_zero_duration_returns_invalid_params() -> void:
+	# duration <= 0 是无意义的「按住 0 秒」；防御纵深拦在服务端（CLI preflight 也拦）。
+	var result: Dictionary = _api.handle_hold({"action": "a", "duration": 0.0})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602, "duration=0 应回 INVALID_PARAMS(-32602)")
+	assert_false(_api.has_active_holds(), "非法 duration 不应进 held 列表")
+	assert_false("a" in _api.get_pressed_actions())
+
+
+func test_hold_negative_duration_returns_invalid_params() -> void:
+	var result: Dictionary = _api.handle_hold({"action": "a", "duration": -1.5})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+	assert_false(_api.has_active_holds())
+
+
 func test_combo_unknown_action_aborts_with_1003() -> void:
 	# combo step 引用未注册 action：必须 abort 整盘并通过 request_id 回 1003，
 	# 否则 _combo_active 卡 true 后续全 1004。

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/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.9'
+__version_tuple__ = version_tuple = (0, 2, 9)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.7 → godot_cli_control-0.2.9}/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 子命令 ──
 
 
@@ -148,6 +175,22 @@ def _resolve_args_for_call(ns: argparse.Namespace) -> list:
     return [_parse_json_arg(a) for a in raw_args]
 
 
+def _preflight_hold(ns: argparse.Namespace) -> None:
+    """连 daemon 前校验 hold 的 duration：必须是 > 0 的数字。
+
+    duration <= 0 会让动作下一帧就释放（只生效一帧），是无意义用法；
+    要无限按住应该用 ``press``。preflight 拦住，避免 agent 干等连接重试。
+    """
+    try:
+        duration = float(ns.duration)
+    except (TypeError, ValueError):
+        raise ValueError(f"hold: duration 必须是数字，收到 {ns.duration!r}")
+    if duration <= 0:
+        raise ValueError(
+            f"hold: duration 必须 > 0（秒），收到 {duration}；要无限按住请用 `press`"
+        )
+
+
 def _preflight_combo(ns: argparse.Namespace) -> None:
     """连 daemon 前用同一份解析逻辑校验 combo 输入；抛 ValueError 即用法错。
 
@@ -522,9 +565,10 @@ RPC_SPECS: tuple[RpcSpec, ...] = (
         description="按住动作指定时长（秒），到点自动释放。",
         positionals=(
             Positional("action", None, "InputMap 动作名"),
-            Positional("duration", None, "按住时长（秒）"),
+            Positional("duration", None, "按住时长（秒，必须 > 0）"),
         ),
         example="hold jump 1.5",
+        preflight=_preflight_hold,
         text_formatter=lambda r: f"holding: {r}",
     ),
     RpcSpec(
@@ -944,11 +988,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 +1541,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.9}/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.9}/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
 
@@ -118,7 +120,7 @@ Three numeric ranges cohabit in `error.code`. Knowing which is which lets you de
 |---|---|
 | `-32600` | Malformed request (missing / non-string `method`). Bug in client; should never reach an agent. |
 | `-32601` | Unknown method name. Bug; means client + plugin versions drifted. |
-| `-32602` | Invalid params: missing required field, blocked property/method (security blacklist), out-of-range value, value-type mismatch on `set` (e.g. `Vector2` property given an array of wrong length / non-numeric elements), or node-isn't-clickable (e.g. you `click`'d a `Node2D`). Don't retry; the request shape is wrong. |
+| `-32602` | Invalid params: missing required field, blocked property/method (security blacklist), out-of-range value, value-type mismatch on `set` (e.g. `Vector2` property given an array of wrong length / non-numeric elements), node-isn't-clickable (e.g. you `click`'d a `Node2D`), or `hold` given `duration ≤ 0` (use `press` for an indefinite hold). Don't retry; the request shape is wrong. |
 
 **Client-side (CLI / GameClient) — `-1xxx`:**
 
@@ -153,7 +155,7 @@ Server vs client ranges never overlap, so a single `code` field is unambiguous.
 **Input simulation:**
 - `press <action>` / `release <action>` — sticky press
 - `tap <action> [duration]` — press → wait → release
-- `hold <action> <duration>` — auto-release after N seconds
+- `hold <action> <duration>` — auto-release after N seconds (`duration` must be `> 0`; for an indefinite hold use `press`)
 - `combo --steps-json '[...]'` (or `combo file.json` / `combo -` for stdin) — sequence
 - `combo-cancel` — abort running combo
 - `release-all` — release everything
@@ -387,9 +389,11 @@ pytest_plugins = ["godot_cli_control.pytest_plugin"]
 - **Daemon won't start** — check `.cli_control/godot_bin` exists and points at a real Godot 4 binary, or `export GODOT_BIN=/path/to/godot`. See `godot-cli-control init -h` for the full lookup chain.
 - **Output flags work in any position** — `--json` / `--text` / `--no-json` are accepted both before and after subcommands as of this fix. `--port N` is still top-level only; pass it before the subcommand.
 - **`combo` rejects everything with `1004`** — a combo is already running. Call `combo-cancel` (or `release-all`) to abort.
+- **`hold` / `press` persist after the command returns** — by design. Each CLI command is its own short-lived connection that closes *cleanly*, and a clean close does **not** release inputs. `hold <action> <dur>` auto-releases after `<dur>` seconds (its timer keeps running in the daemon); a sticky `press <action>` stays held until you call `release <action>` / `release-all` (or the daemon's idle-timeout shuts it down). If a character looks stuck moving, you probably left a `press` dangling — run `release-all`. (An *abnormal* drop — your client crashing or being killed mid-session — does trigger a safety `release-all`, so stuck keys can't outlive a dead client.)
 - **`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.9}/python/tests/test_cli.py

@@ -1140,6 +1140,47 @@ def test_combo_preflight_rejects_no_steps_before_connecting(
     assert "必须提供" in payload["error"]["message"]
 
 
+@pytest.mark.parametrize("bad_duration", ["0", "-1.5", "abc"])
+def test_hold_preflight_rejects_bad_duration_before_connecting(
+    bad_duration: str,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """``hold`` 的 duration <= 0 或非数字必须在连 daemon **之前**报 EXIT_USAGE。
+
+    duration<=0 会让动作下一帧就释放（只生效一帧）；无限按住该用 ``press``。
+    见 issue #71。"""
+    import json as _json
+
+    from godot_cli_control.cli import EXIT_USAGE, main
+
+    class _ShouldNotConnect:
+        def __init__(self, *_: Any, **__: Any) -> None:
+            raise AssertionError("preflight 失效：hold duration 非法时不应连 daemon")
+
+    import godot_cli_control.cli as cli_mod
+
+    monkeypatch.setattr(cli_mod, "GameClient", _ShouldNotConnect)
+    monkeypatch.setattr(sys, "argv", ["godot-cli-control", "hold", "jump", bad_duration])
+
+    with pytest.raises(SystemExit) as exc:
+        main()
+    assert exc.value.code == EXIT_USAGE
+    payload = _json.loads(capsys.readouterr().out.strip())
+    assert payload["ok"] is False
+    assert "duration" in payload["error"]["message"]
+
+
+def test_hold_preflight_accepts_positive_duration() -> None:
+    """合法 duration > 0 不应被 preflight 拦下（让它进到连接环节）。"""
+    import argparse
+
+    from godot_cli_control.cli import _preflight_hold
+
+    ns = argparse.Namespace(duration="1.5")
+    _preflight_hold(ns)  # 不抛即通过
+
+
 def test_combo_preflight_caches_steps_to_avoid_stdin_double_read(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -1733,6 +1774,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.9}/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)"

godot_cli_control-0.2.9/python/tests/test_e2e_input.py

@@ -0,0 +1,175 @@
+"""端到端回归：真实 Godot daemon 下的输入持续性（issue #70）。
+
+拦的回归：CLI 每条子命令都是独立连接、跑完即「干净关闭」。曾经 GameBridge
+在断连时无条件 release_all，导致 ``hold`` 的定时器没倒计时就被清掉（只生效
+一帧）、sticky ``press`` 也无法跨命令存活。这个 bug 当时 GUT（mock socket）
+和 pytest（mock subprocess）都没逮到 —— 只有真实 daemon 端到端能复现。
+
+覆盖三条链路：
+  1. 干净关闭后 ``hold`` 仍持续，duration 到点由定时器自动释放（不是断连释放）。
+  2. sticky ``press`` 跨命令存活，直到 ``release-all``。
+  3. 异常掉线（无 WebSocket close frame，close_code == -1）触发 release_all 兜底。
+
+需要真实 Godot 4：设置 ``GODOT_BIN`` 指向可执行文件，否则整文件 skip。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+_GODOT_BIN = os.environ.get("GODOT_BIN")
+_ADDON_SRC = Path(__file__).resolve().parents[2] / "addons" / "godot_cli_control"
+
+pytestmark = pytest.mark.skipif(
+    not _GODOT_BIN or not Path(_GODOT_BIN).exists(),
+    reason="需要真实 Godot 4：设置 GODOT_BIN 指向可执行文件",
+)
+
+# 用 `python -m godot_cli_control` 调 CLI：与 PATH 无关，always 命中当前环境。
+_CLI = [sys.executable, "-m", "godot_cli_control"]
+
+_PROJECT_GODOT = """\
+config_version=5
+
+[application]
+config/name="gcc_e2e"
+run/main_scene="res://main.tscn"
+
+[autoload]
+GameBridgeNode="*res://addons/godot_cli_control/bridge/game_bridge.gd"
+
+[debug]
+settings/stdout/print_fps=false
+
+[editor_plugins]
+enabled=PackedStringArray("res://addons/godot_cli_control/plugin.cfg")
+
+[input]
+move_right={"deadzone":0.5,"events":[]}
+jump={"deadzone":0.5,"events":[]}
+"""
+
+_MAIN_TSCN = """\
+[gd_scene format=3]
+
+[node name="Main" type="Node"]
+"""
+
+
+def _run_cli(project: Path, *args: str, timeout: float = 60.0) -> dict[str, Any]:
+    """跑一条 CLI 子命令（独立进程 = 独立连接），解析最后一行 JSON 信封。"""
+    proc = subprocess.run(
+        _CLI + list(args),
+        cwd=project,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    # 信封是 stdout 单行 JSON；daemon start 等可能先打 stderr 进度，取最后的 JSON 行。
+    json_lines = [ln for ln in proc.stdout.splitlines() if ln.strip().startswith("{")]
+    assert json_lines, f"无 JSON 输出：args={args} stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    return json.loads(json_lines[-1])
+
+
+def _pressed(project: Path) -> list[str]:
+    payload = _run_cli(project, "pressed")
+    assert payload["ok"] is True, payload
+    return payload["result"]
+
+
+@pytest.fixture(scope="module")
+def godot_project(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """搭一个最小真实 Godot 工程（addon + autoload + 两个 InputMap 动作）并导入一次。"""
+    proj = tmp_path_factory.mktemp("gcc_e2e")
+    (proj / "addons").mkdir()
+    shutil.copytree(_ADDON_SRC, proj / "addons" / "godot_cli_control")
+    (proj / "project.godot").write_text(_PROJECT_GODOT)
+    (proj / "main.tscn").write_text(_MAIN_TSCN)
+
+    # 先跑一次编辑器导入，注册全局 class（CliControlErrorCodes）+ 资源 .import。
+    imp = subprocess.run(
+        [_GODOT_BIN, "--headless", "--editor", "--quit", "--path", str(proj)],
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    assert imp.returncode == 0, f"Godot 导入失败：{imp.stdout}\n{imp.stderr}"
+    return proj
+
+
+@pytest.fixture
+def daemon(godot_project: Path) -> Any:
+    """每个用例起/停一个真实 headless daemon；teardown 兜底 release-all + stop。"""
+    start = _run_cli(godot_project, "daemon", "start", "--headless", timeout=90)
+    assert start["ok"] is True and start["result"]["started"], start
+    port = start["result"]["port"]
+    try:
+        yield godot_project, port
+    finally:
+        _run_cli(godot_project, "release-all")
+        _run_cli(godot_project, "daemon", "stop", timeout=30)
+
+
+def test_hold_persists_across_clean_disconnect_then_auto_releases(daemon: Any) -> None:
+    project, _ = daemon
+    # hold 1s：命令拿到响应后干净关闭连接 —— 断连不应清掉它。
+    held = _run_cli(project, "hold", "move_right", "1.0")
+    assert held["ok"] is True, held
+
+    # 紧跟一条独立命令：若断连清了，这里就空了（旧 bug：只生效一帧）。
+    assert "move_right" in _pressed(project), "干净关闭后 hold 应跨命令存活"
+
+    # 等过 duration：应由 advance_timers 定时器自动释放（不是断连释放）。
+    time.sleep(2.0)
+    assert _pressed(project) == [], "duration 到点后 hold 应被定时器自动释放"
+
+
+def test_press_persists_until_release_all(daemon: Any) -> None:
+    project, _ = daemon
+    pressed = _run_cli(project, "press", "jump")
+    assert pressed["ok"] is True, pressed
+
+    # sticky press 没有定时器：跨多条独立命令仍应保持按下。
+    assert "jump" in _pressed(project), "sticky press 应跨命令存活"
+    time.sleep(1.0)
+    assert "jump" in _pressed(project), "press 不该自己释放"
+
+    rel = _run_cli(project, "release-all")
+    assert rel["ok"] is True, rel
+    assert _pressed(project) == [], "release-all 后应清空"
+
+
+def test_abnormal_disconnect_releases_held_inputs(daemon: Any) -> None:
+    project, port = daemon
+    # 子进程：连上 → 发 hold → 硬退出（不发 close frame）→ daemon 侧 close_code = -1。
+    drop_script = (
+        "import asyncio, json, os, websockets\n"
+        "async def main():\n"
+        f"    ws = await websockets.connect('ws://127.0.0.1:{port}')\n"
+        "    await ws.send(json.dumps({'id':'1','method':'input_hold',"
+        "'params':{'action':'move_right','duration':30.0}}))\n"
+        "    await ws.recv()\n"
+        "    os._exit(0)\n"
+        "asyncio.run(main())\n"
+    )
+    drop = subprocess.run(
+        [sys.executable, "-c", drop_script], capture_output=True, text=True, timeout=30
+    )
+    assert drop.returncode == 0, f"abrupt-drop 客户端异常：{drop.stderr}"
+
+    # 异常掉线应触发 release_all 兜底（即便 hold 还剩 ~30s）。给 daemon 几帧检测断连。
+    deadline = time.time() + 5.0
+    while time.time() < deadline:
+        if _pressed(project) == []:
+            break
+        time.sleep(0.2)
+    assert _pressed(project) == [], "异常掉线应触发 release_all 清掉持有输入"