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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.8
+Version: 0.2.10
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT
@@ -176,7 +176,10 @@ coverage run -m pytest python/tests/
 coverage report
 
 # GUT tests for the Godot plugin (needs GODOT_BIN env var)
+# bash (Linux/macOS):
 GODOT_BIN=/path/to/godot ./addons/godot_cli_control/tests/run_gut.sh
+# cross-platform (Linux/macOS/Windows) — what CI runs:
+GODOT_BIN=/path/to/godot python addons/godot_cli_control/tests/run_gut.py
 ```
 
 ## Documentation

{godot_cli_control-0.2.8 → godot_cli_control-0.2.10}/addons/godot_cli_control/CHANGELOG.md

@@ -60,7 +60,7 @@
 - **Error code 1004 collision**: `low_level_api.gd` 的 scene tree 超限改用新业务码 `1005 "scene tree too large"`，与 input_simulation `1004 "combo in progress"` 解耦。新增 `error_codes.gd` 集中常量。
 - **pytest fixture default port**: `--godot-cli-port` 默认从 9877 改为 0（OS-assigned），与 `daemon start` 默认对齐；多项目并行测试不再撞端口。
 - **Addon README error-code table**: 之前只列到 1003，补全 1004 / 1005 / 客户端 -1xxx 段。
-- **Scene tree hard limit bypass (DoS fix)**: `handle_get_scene_tree` 入口现在把 `max_nodes` clamp 到硬墙 `_BUILD_TREE_NODE_LIMIT` (5000)。修复前客户端传 `max_nodes=999999` 会让服务端先把整棵超大树构造成 Dictionary 再被 1005 错误丢弃（内存浪费 / OOM 路径）。
+- **Scene tree hard limit bypass (DoS fix)**: `handle_get_scene_tree` 入口现在把 `max_nodes` clamp 到硬墙 `_BUILD_TREE_MAX_NODES` (5000)。修复前客户端传 `max_nodes=999999` 会让服务端先把整棵超大树构造成 Dictionary 再被 1005 错误丢弃（内存浪费 / OOM 路径）。
 - **Error code 1003 semantic split**: screenshot 在 viewport texture 为 null 时不再借用 `1003 METHOD_NOT_FOUND`，改用新业务码 `1006 RESOURCE_UNAVAILABLE`。1003 现在是纯 schema 错（不应 retry），1006 是 transient 错（短重试可能成功），agent 据此分别处置。
 
 #### Added

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

@@ -65,7 +65,11 @@ Compatibility shims are also kept at `addons/godot_cli_control/bin/run_cli_contr
 ## Running the GUT unit tests
 
 ```bash
+# Linux / macOS (bash):
 GODOT_BIN=/path/to/godot ./addons/godot_cli_control/tests/run_gut.sh
+
+# Cross-platform (Linux / macOS / Windows) — this is what CI runs:
+GODOT_BIN=/path/to/godot python addons/godot_cli_control/tests/run_gut.py
 ```
 
 The runner builds a throwaway Godot project, `git clone`s a pinned [GUT](https://github.com/bitwes/Gut) release into `addons/gut/`, copies this plugin in, and runs the test files under `addons/godot_cli_control/tests/gut/`. Coverage today is `LowLevelApi` handler boundaries (blacklist, missing-property, node-not-found) and `InputSimulationApi` state machine (combo / press / release / tap / release_all).
@@ -114,7 +118,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.8 → godot_cli_control-0.2.10}/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.8 → godot_cli_control-0.2.10}/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.8 → godot_cli_control-0.2.10}/addons/godot_cli_control/bridge/low_level_api.gd

@@ -7,11 +7,12 @@ extends Node
 ## 若冷启动或 GUT 跑前遇到 "Class 'CliControlErrorCodes' not found"，先跑一次
 ## 完整 import（`godot --editor --quit --path .`）让 .godot/global_script_class_cache.cfg 建立。
 
-const _BUILD_TREE_HARD_LIMIT: int = 50
+# depth=0（"无限深度"）时的递归深度兜底，防无限递归 / 病态深树。
+const _BUILD_TREE_DEFAULT_MAX_DEPTH: int = 50
 # 总节点数上限：宽场景（1000+ 子项的 Grid/Container）会构造极大 JSON，
 # 超 outbound buffer（默认 10 MB）后客户端拿到截断包 → STATE_CLOSED 断连。
 # 5000 节点对应 ~500 KB JSON，留足余量。
-const _BUILD_TREE_NODE_LIMIT: int = 5000
+const _BUILD_TREE_MAX_NODES: int = 5000
 # wait_game_time_async 防呆上限：防止误传 1e9 之类的数值挂死 session
 const _MAX_WAIT_SECONDS: float = 3600.0
 # take_screenshot_async 循环上限：常态下 GameBridge 启动 gate 已保证 viewport
@@ -370,14 +371,14 @@ func handle_get_children(params: Dictionary) -> Dictionary:
 func handle_get_scene_tree(params: Dictionary) -> Dictionary:
 	var max_depth: int = params.get("depth", 5) as int
 	# max_nodes 是客户端控制的软上限。**入口处 clamp 到硬墙
-	# _BUILD_TREE_NODE_LIMIT (5000)**：防止恶意 / 失误调用传 max_nodes=999999
+	# _BUILD_TREE_MAX_NODES (5000)**：防止恶意 / 失误调用传 max_nodes=999999
 	# 时让 _build_tree 真把整棵超大树构造成 Dictionary 后才被外层错误返回丢弃
 	# （DoS / OOM 路径）。clamp 后 _build_tree 内部的短路单一来源，
 	# 同时承担软上限（agent truncated 信号）与硬墙（防爆 outbound buffer）。
 	# 不传时也用硬墙做默认，兼容旧客户端。
-	var max_nodes: int = params.get("max_nodes", _BUILD_TREE_NODE_LIMIT) as int
-	if max_nodes <= 0 or max_nodes > _BUILD_TREE_NODE_LIMIT:
-		max_nodes = _BUILD_TREE_NODE_LIMIT
+	var max_nodes: int = params.get("max_nodes", _BUILD_TREE_MAX_NODES) as int
+	if max_nodes <= 0 or max_nodes > _BUILD_TREE_MAX_NODES:
+		max_nodes = _BUILD_TREE_MAX_NODES
 	var root: Node = get_tree().current_scene
 	if root == null:
 		root = get_tree().root
@@ -389,10 +390,10 @@ func handle_get_scene_tree(params: Dictionary) -> Dictionary:
 	# 因为 max_nodes 已 clamp 到 ≤ LIMIT，counter 最多比 LIMIT 多 ~1，
 	# 所以这条分支只在 max_nodes==LIMIT（客户端没传或传了 ≥LIMIT）时被触发。
 	# max_nodes < LIMIT 的客户端永远走 truncated 软信号路径，不会撞 1005。
-	if counter[0] > _BUILD_TREE_NODE_LIMIT:
+	if counter[0] > _BUILD_TREE_MAX_NODES:
 		return _err(
 			CliControlErrorCodes.SCENE_TREE_TOO_LARGE,
-			"scene tree too large (>%d nodes); lower 'depth' or query a subtree" % _BUILD_TREE_NODE_LIMIT,
+			"scene tree too large (>%d nodes); lower 'depth' or query a subtree" % _BUILD_TREE_MAX_NODES,
 		)
 	# 软上限：硬墙内但超过 max_nodes 时附加 truncated 信号让 agent 决定分子树。
 	var response: Dictionary = {"tree": tree}
@@ -479,10 +480,10 @@ func _has_property(node: Node, property: String) -> bool:
 	return false
 
 
-## depth=0 表示"无限深度"，使用硬限制 _BUILD_TREE_HARD_LIMIT (50) 防止无限递归。
+## depth=0 表示"无限深度"，使用硬限制 _BUILD_TREE_DEFAULT_MAX_DEPTH (50) 防止无限递归。
 ## counter 是 by-ref 计数器：超过 max_nodes 时短路（不再递归子节点），
 ## 调用方读 counter[0] > max_nodes 决定是否附加 truncated 信号，
-## 读 counter[0] > _BUILD_TREE_NODE_LIMIT 决定是否走 1005 (SCENE_TREE_TOO_LARGE) 错误路径。
+## 读 counter[0] > _BUILD_TREE_MAX_NODES 决定是否走 1005 (SCENE_TREE_TOO_LARGE) 错误路径。
 func _build_tree(node: Node, max_depth: int, current_depth: int, counter: Array[int], max_nodes: int) -> Dictionary:
 	counter[0] += 1
 	var entry: Dictionary = {
@@ -497,7 +498,7 @@ func _build_tree(node: Node, max_depth: int, current_depth: int, counter: Array[
 	if counter[0] > max_nodes:
 		# 超软上限：不再下递归，但当前 entry 已计入；调用方附加 truncated 信号
 		return entry
-	var effective_max: int = _BUILD_TREE_HARD_LIMIT if max_depth == 0 else max_depth
+	var effective_max: int = _BUILD_TREE_DEFAULT_MAX_DEPTH if max_depth == 0 else max_depth
 	if current_depth < effective_max:
 		var children: Array[Dictionary] = []
 		for child: Node in node.get_children():

{godot_cli_control-0.2.8 → godot_cli_control-0.2.10}/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.8 → godot_cli_control-0.2.10}/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.8 → godot_cli_control-0.2.10}/addons/godot_cli_control/tests/gut/test_low_level_api.gd

@@ -631,11 +631,11 @@ func test_build_tree_short_circuits_above_node_limit() -> void:
 	var leaf: Node = Node.new()
 	leaf.name = "Leaf"
 	add_child_autofree(leaf)
-	var counter: Array[int] = [LowLevelApiScript._BUILD_TREE_NODE_LIMIT]
+	var counter: Array[int] = [LowLevelApiScript._BUILD_TREE_MAX_NODES]
 	# 第 5 参数 max_nodes = LIMIT（5000）；leaf 计入后 counter == LIMIT+1 > max_nodes，触发短路
-	var entry: Dictionary = _api._build_tree(leaf, 5, 0, counter, LowLevelApiScript._BUILD_TREE_NODE_LIMIT)
+	var entry: Dictionary = _api._build_tree(leaf, 5, 0, counter, LowLevelApiScript._BUILD_TREE_MAX_NODES)
 	# leaf 自身被计入 → counter 变成 LIMIT+1
-	assert_eq(int(counter[0]), LowLevelApiScript._BUILD_TREE_NODE_LIMIT + 1)
+	assert_eq(int(counter[0]), LowLevelApiScript._BUILD_TREE_MAX_NODES + 1)
 	# 超 limit 后立刻 return，不下递归 children
 	assert_does_not_have(entry, "children")
 
@@ -650,14 +650,14 @@ func test_build_tree_under_limit_includes_children() -> void:
 	parent.add_child(c1)
 	var counter: Array[int] = [0]
 	# 第 5 参数 max_nodes 给硬墙 5000，远超 2 个节点，不会触发软截断
-	var entry: Dictionary = _api._build_tree(parent, 5, 0, counter, LowLevelApiScript._BUILD_TREE_NODE_LIMIT)
+	var entry: Dictionary = _api._build_tree(parent, 5, 0, counter, LowLevelApiScript._BUILD_TREE_MAX_NODES)
 	assert_has(entry, "children")
 	assert_eq((entry.children as Array).size(), 1)
 
 
 func test_handle_get_scene_tree_clamps_oversized_max_nodes() -> void:
 	# P1 回归：恶意/失误客户端传 max_nodes=999999 时，
-	# 入口必须 clamp 到 _BUILD_TREE_NODE_LIMIT，
+	# 入口必须 clamp 到 _BUILD_TREE_MAX_NODES，
 	# 否则 _build_tree 会构造完整大字典再被外层 1005 丢弃（DoS 风险）。
 	# 这里 happy path 验证 clamp 不破坏正常调用——简单场景下无 1005 报错、无 truncated 信号。
 	var result: Dictionary = _api.handle_get_scene_tree({

godot_cli_control-0.2.10/addons/godot_cli_control/tests/run_gut.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""跨平台 GUT runner —— run_gut.sh 的 Python 等价物（issue #36）。
+
+run_gut.sh 是 bash，Windows runner 用不了；macOS 上 GUT cmdln 的 stdout buffering
+历史上偶发丢字。改用 Python stdlib（tempfile / shutil / subprocess）抹平
+mktemp / cp -r / 路径分隔符这些平台差异，让 CI 能在 ubuntu / macOS / windows
+三格统一跑 GDScript 单测。
+
+逻辑与 run_gut.sh 一致：
+  1. 找 Godot 二进制（GODOT_BIN > macOS 默认 .app > PATH 中的 godot[.exe]）。
+  2. 临时目录搭最小 Godot 工程 + 复制本 plugin。
+  3. clone GUT 固定 tag，搬运 addons/gut。
+  4. headless 预热 import（填 .godot/ 缓存）。
+  5. headless 跑 gut_cmdln.gd，实时透传输出并缓冲。
+  6. 断言 GUT 的 "All tests passed!" marker（cmdln 加载失败时 Godot 仍可能 exit 0，
+     所以不能只看 returncode）。
+
+用法：
+    GODOT_BIN=/path/to/godot python3 run_gut.py
+    python3 run_gut.py            # 未设 GODOT_BIN 时尝试 macOS 默认 / PATH
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+# Windows 默认 stdout/stderr 编码是 cp1252，编不了中文日志或 Godot 输出里的非 ASCII
+# 字符（issue #36：Windows CI 格曾因 `_log("使用 Godot…")` 在第一行就 UnicodeEncodeError
+# 崩掉，GUT 根本没跑起来）。强制 UTF-8，macOS/Linux 本就默认 UTF-8 不受影响。
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+    except (AttributeError, ValueError):  # 非 TextIOWrapper（被重定向）时静默跳过
+        pass
+
+GUT_REF = "v9.4.0"  # bumping：检查 https://github.com/bitwes/Gut/releases
+
+# 仓库根：本脚本在 addons/godot_cli_control/tests/，往上 3 级。
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+_PROJECT_GODOT = """\
+config_version=5
+
+[application]
+config/name="gut-tests"
+config/features=PackedStringArray("4.4", "GL Compatibility")
+
+[rendering]
+renderer/rendering_method="gl_compatibility"
+renderer/rendering_method.mobile="gl_compatibility"
+"""
+
+_SUCCESS_MARKER = "All tests passed!"
+
+
+def _log(msg: str) -> None:
+    print(f"==> {msg}", flush=True)
+
+
+def _fail(msg: str) -> "None":
+    print(f"FAIL: {msg}", file=sys.stderr, flush=True)
+    raise SystemExit(1)
+
+
+def _find_godot() -> str:
+    """GODOT_BIN > macOS 默认 .app > PATH 中的 godot/godot.exe。"""
+    env_bin = os.environ.get("GODOT_BIN")
+    if env_bin:
+        if not (Path(env_bin).is_file() and os.access(env_bin, os.X_OK)):
+            _fail(f"GODOT_BIN 指向的不是可执行文件：{env_bin}")
+        return env_bin
+
+    mac_default = Path("/Applications/Godot.app/Contents/MacOS/Godot")
+    if mac_default.is_file() and os.access(mac_default, os.X_OK):
+        return str(mac_default)
+
+    for name in ("godot", "godot.exe", "Godot"):
+        found = shutil.which(name)
+        if found:
+            return found
+
+    _fail("找不到 Godot 二进制（设置 GODOT_BIN 或加入 PATH）")
+    raise AssertionError("unreachable")  # 给类型检查器：_fail 永远 raise
+
+
+def _run_godot(godot: str, *args: str, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [godot, *args],
+        capture_output=capture,
+        text=True,
+    )
+
+
+def _clone_gut(dest_parent: Path) -> Path:
+    """clone GUT 到临时目录，返回其 addons/gut 路径。"""
+    _log(f"下载 GUT {GUT_REF}")
+    gut_src = dest_parent / "gut-src"
+    res = subprocess.run(
+        [
+            "git", "clone", "--depth", "1", "--branch", GUT_REF,
+            "https://github.com/bitwes/Gut.git", str(gut_src),
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if res.returncode != 0:
+        _fail(f"git clone GUT 失败：\n{res.stderr}")
+    gut_addon = gut_src / "addons" / "gut"
+    if not (gut_addon / "gut_cmdln.gd").is_file():
+        _fail(f"GUT {GUT_REF} 内未找到 addons/gut/gut_cmdln.gd（GUT 目录结构变了？）")
+    return gut_addon
+
+
+def _run_gut_cmdln(godot: str, proj: Path) -> str:
+    """实时透传 gut_cmdln 输出并缓冲返回（等价 bash 的 `| tee`）。"""
+    _log("跑 GUT")
+    proc = subprocess.Popen(
+        [
+            godot, "--headless", "--path", str(proj),
+            "-s", "res://addons/gut/gut_cmdln.gd",
+            "-gdir=res://addons/godot_cli_control/tests/gut",
+            "-gexit",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    buf: list[str] = []
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+        buf.append(line)
+    proc.wait()
+    return "".join(buf)
+
+
+def main() -> int:
+    godot = _find_godot()
+    _log(f"使用 Godot: {godot}")
+    _run_godot(godot, "--version")
+
+    # 一个临时父目录装 工程 + GUT clone；with 块退出自动清理（跨平台、无 trap）。
+    with tempfile.TemporaryDirectory(prefix="godot-cli-control-gut-") as tmp:
+        tmp_path = Path(tmp)
+        proj = tmp_path / "proj"
+        proj.mkdir()
+        _log(f"临时项目: {proj}")
+
+        # 1) 最小 Godot 工程
+        (proj / "project.godot").write_text(_PROJECT_GODOT, encoding="utf-8")
+
+        # 2) 被测 plugin
+        (proj / "addons").mkdir()
+        shutil.copytree(
+            REPO_ROOT / "addons" / "godot_cli_control",
+            proj / "addons" / "godot_cli_control",
+        )
+
+        # 3) GUT
+        gut_addon = _clone_gut(tmp_path)
+        shutil.copytree(gut_addon, proj / "addons" / "gut")
+
+        # 4) headless 预热 import（失败不致命，与 .sh 一致：用 || true 语义）
+        _log("import 资源")
+        _run_godot(godot, "--headless", "--path", str(proj), "--editor", "--quit",
+                   capture=True)
+
+        # 5) 跑 GUT
+        output = _run_gut_cmdln(godot, proj)
+
+    # 6) Godot 在 cmdln 脚本加载失败时仍可能 exit 0 —— 额外断言 GUT 成功 marker。
+    if _SUCCESS_MARKER in output:
+        _log("GUT PASS")
+        return 0
+    _fail(f"没看到 GUT 的 '{_SUCCESS_MARKER}' marker —— 看上面输出排查")
+    return 1  # unreachable（_fail raise）
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{godot_cli_control-0.2.8 → godot_cli_control-0.2.10}/addons/godot_cli_control/tests/run_gut.sh

@@ -4,6 +4,10 @@
 # 没有把 GUT vendor 进仓库（它是开发依赖，不该跟 plugin 一起发布到 PyPI/AssetLib）；
 # 临时项目从头建，避免污染仓库的 .godot/ import 缓存。
 #
+# 跨平台：CI（ubuntu / macOS / windows 三格）跑的是同目录的 run_gut.py
+# （bash 在 Windows 用不了）。本 .sh 保留给 Linux / macOS 本地开发者方便用；
+# 两者逻辑等价，改一个记得对齐另一个。
+#
 # 用法：
 #   GODOT_BIN=/path/to/godot ./run_gut.sh
 #   （未设置 GODOT_BIN 时尝试 macOS 默认路径或 PATH 中的 godot）

{godot_cli_control-0.2.8 → godot_cli_control-0.2.10}/pyproject.toml

@@ -22,6 +22,15 @@ godot-cli-control = "godot_cli_control.cli:main"
 [project.entry-points.pytest11]
 godot-cli-control = "godot_cli_control.pytest_plugin"
 
+[tool.pytest.ini_options]
+# gui：需要真实显示（开窗）才能跑的端到端测试。普通 unit / headless e2e 不带此
+# marker。本地默认随 GODOT_BIN / GCC_GUI_E2E 未设而 skip；CI 专档（Linux 套
+# xvfb 或 macOS runner）设 GCC_GUI_E2E=1 开启。注册在此避免 unknown-marker 警告，
+# 也让 `pytest -m "not gui"` 能稳定剔除。
+markers = [
+    "gui: 需要真实显示的 windowed e2e（screenshot frame_post_draw 路径，issue #64）",
+]
+
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"

{godot_cli_control-0.2.8 → godot_cli_control-0.2.10}/python/README.md

@@ -159,7 +159,10 @@ coverage run -m pytest python/tests/
 coverage report
 
 # GUT tests for the Godot plugin (needs GODOT_BIN env var)
+# bash (Linux/macOS):
 GODOT_BIN=/path/to/godot ./addons/godot_cli_control/tests/run_gut.sh
+# cross-platform (Linux/macOS/Windows) — what CI runs:
+GODOT_BIN=/path/to/godot python addons/godot_cli_control/tests/run_gut.py
 ```
 
 ## Documentation

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

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

@@ -175,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 即用法错。
 
@@ -549,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(
@@ -893,7 +910,8 @@ def cmd_daemon_status(ns: argparse.Namespace) -> int:
 def cmd_daemon_ls(ns: argparse.Namespace) -> int:
     """跨项目列出运行中的 daemon。
 
-    扫全局注册表 ~/.local/state/godot-cli-control/daemons/，对每条记录探活。
+    扫全局注册表（POSIX `~/.local/state/godot-cli-control/daemons/`；Windows
+    `%LOCALAPPDATA%\\godot-cli-control\\daemons\\`），对每条记录探活。
     死记录会被 list_all 自动清理（连同对应项目的 .cli_control/godot.pid 与 port）。
     JSON 模式：{"ok": true, "result": {"daemons": [...]}}（信封一致）。
     Text 模式：每条一行 `<pid>\t<port>\t<project_root>\t<started_at>`；空时 (no running daemons)。
@@ -1494,7 +1512,8 @@ def build_parser() -> argparse.ArgumentParser:
         "ls",
         help="列出所有正在运行的 daemon（跨项目）",
         description=(
-            "扫描全局注册表 ~/.local/state/godot-cli-control/daemons/，"
+            "扫描全局注册表（POSIX ~/.local/state/godot-cli-control/daemons/；"
+            "Windows %LOCALAPPDATA%\\godot-cli-control\\daemons\\），"
             "列出所有探活通过的 daemon。死记录会被自动清理。"
         ),
     )