godot-cli-control 0.2.3__tar.gz → 0.2.4__tar.gz

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/.gitignore

@@ -12,6 +12,8 @@ venv/
 .coverage.*
 coverage.xml
 htmlcov/
+# uv 本地 dev 锁；本项目作为库发布，不入库（避免给下游消费者制造噪音）
+uv.lock
 
 # hatch-vcs generated
 python/godot_cli_control/_version.py

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.3
+Version: 0.2.4
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT
@@ -53,7 +53,8 @@ import asyncio
 from godot_cli_control import GameClient
 
 async def main():
-    async with GameClient(port=9877) as client:
+    # Omitting port lets GameClient auto-discover from .cli_control/port (written by daemon start)
+    async with GameClient() as client:
         tree = await client.get_scene_tree(depth=3)
         await client.click("/root/MyScene/Button")
         await client.action_press("jump")
@@ -101,7 +102,7 @@ def test_jump(godot_daemon, bridge):
 CLI options:
 
 ```
---godot-cli-port=N           # GameBridge port (default 9877)
+--godot-cli-port=N           # GameBridge port (default: read from .cli_control/port)
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
 ```
@@ -113,9 +114,10 @@ The CLI is the canonical surface — every `GameClient` method has a one-line eq
 ```bash
 # Lifecycle
 godot-cli-control init [--path DIR] [--force]
-godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N]
-godot-cli-control daemon stop
+godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N --idle-timeout 30m]
+godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
+godot-cli-control daemon ls                  # list running daemons across all projects
 godot-cli-control run <script.py> [--headless ...]
 
 # Read

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/addons/godot_cli_control/bridge/game_bridge.gd

@@ -11,6 +11,14 @@ var _tcp_server: TCPServer = TCPServer.new()
 var _active_peer: WebSocketPeer = null
 var _active_stream: StreamPeerTCP = null
 var _port: int = DEFAULT_PORT
+var _idle_timeout_secs: int = 0
+var _last_activity_ms: int = 0
+# 正在处理中的请求数。> 0 表示 daemon 没闲着，idle 检查必须放过 —— 否则
+# 一条 wait_game_time(3600) 会被 30m idle-timeout 半路打断，客户端拿不到响应。
+# 入：消息通过参数校验、即将派发到 handler 时 +1。
+# 出：_dispatch_result（sync/async/async_with_id 三条路径的最终响应点）-1。
+# 校验失败的 _send_error 不计数（没进过 handler）。
+var _in_flight: int = 0
 var _outbound_buffer_size: int = DEFAULT_OUTBOUND_BUFFER_MB * 1024 * 1024
 var _low_level_api: LowLevelApi = null
 var _input_sim_api: InputSimulationApi = null
@@ -23,7 +31,12 @@ var _methods: Dictionary = {}
 
 func _ready() -> void:
 	if not _should_activate():
-		print("[Godot CLI Control] inactive — pass --cli-control, set GODOT_CLI_CONTROL=1, or enable %s in Project Settings (debug build only)" % SETTING_AUTO_ENABLE)
+		print(
+			(
+				"[Godot CLI Control] inactive — pass --cli-control, set GODOT_CLI_CONTROL=1, or enable %s in Project Settings (debug build only)"
+				% SETTING_AUTO_ENABLE
+			)
+		)
 		queue_free()
 		return
 	# 即使 SceneTree 暂停也要继续运行
@@ -39,7 +52,9 @@ func _ready() -> void:
 	# 构建统一方法注册表
 	_register_methods()
 	# 缓存 outbound buffer 大小（ProjectSettings 可覆盖默认 10MB，至少 1MB）
-	var mb: int = int(ProjectSettings.get_setting(SETTING_OUTBOUND_BUFFER_MB, DEFAULT_OUTBOUND_BUFFER_MB))
+	var mb: int = int(
+		ProjectSettings.get_setting(SETTING_OUTBOUND_BUFFER_MB, DEFAULT_OUTBOUND_BUFFER_MB)
+	)
 	_outbound_buffer_size = max(1, mb) * 1024 * 1024
 	# 启动 TCP 服务器
 	_port = _parse_port_from_args()
@@ -54,6 +69,16 @@ func _ready() -> void:
 		printerr(msg)
 		return
 	print("GameBridge: Listening on ws://127.0.0.1:%d" % _port)
+	_idle_timeout_secs = _parse_idle_timeout_from_args()
+	_last_activity_ms = Time.get_ticks_msec()
+	if _idle_timeout_secs > 0:
+		var t: Timer = Timer.new()
+		t.wait_time = 1.0
+		t.autostart = true
+		t.process_mode = Node.PROCESS_MODE_ALWAYS
+		t.timeout.connect(_check_idle)
+		add_child(t)
+		print("GameBridge: idle-timeout %ds enabled" % _idle_timeout_secs)
 
 
 func _process(_delta: float) -> void:
@@ -118,14 +143,22 @@ func _register_methods() -> void:
 	_methods["wait_game_time"] = {"callable": _low_level_api.wait_game_time_async, "kind": "async"}
 	_methods["screenshot"] = {"callable": _wrap_screenshot, "kind": "async"}
 	# 输入模拟（同步）
-	_methods["input_action_press"] = {"callable": _input_sim_api.handle_action_press, "kind": "sync"}
-	_methods["input_action_release"] = {"callable": _input_sim_api.handle_action_release, "kind": "sync"}
+	_methods["input_action_press"] = {
+		"callable": _input_sim_api.handle_action_press, "kind": "sync"
+	}
+	_methods["input_action_release"] = {
+		"callable": _input_sim_api.handle_action_release, "kind": "sync"
+	}
 	_methods["input_action_tap"] = {"callable": _input_sim_api.handle_action_tap, "kind": "sync"}
 	_methods["input_get_pressed"] = {"callable": _input_sim_api.handle_get_pressed, "kind": "sync"}
-	_methods["list_input_actions"] = {"callable": _input_sim_api.handle_list_input_actions, "kind": "sync"}
+	_methods["list_input_actions"] = {
+		"callable": _input_sim_api.handle_list_input_actions, "kind": "sync"
+	}
 	_methods["input_hold"] = {"callable": _input_sim_api.handle_hold, "kind": "sync"}
 	_methods["input_release_all"] = {"callable": _input_sim_api.handle_release_all, "kind": "sync"}
-	_methods["input_combo_cancel"] = {"callable": _input_sim_api.handle_combo_cancel, "kind": "sync"}
+	_methods["input_combo_cancel"] = {
+		"callable": _input_sim_api.handle_combo_cancel, "kind": "sync"
+	}
 	# 输入模拟（async_with_id：handler 自行通过 _on_async_response 回响）
 	_methods["input_combo"] = {"callable": _input_sim_api.handle_combo, "kind": "async_with_id"}
 
@@ -136,6 +169,7 @@ func _wrap_screenshot(_params: Dictionary) -> Dictionary:
 
 
 func _handle_message(raw: String) -> void:
+	_last_activity_ms = Time.get_ticks_msec()
 	var parsed: Variant = JSON.parse_string(raw)
 	if parsed == null or not parsed is Dictionary:
 		_send_error("", -32600, "Invalid JSON")
@@ -170,6 +204,7 @@ func _handle_message(raw: String) -> void:
 	var entry: Dictionary = _methods[method] as Dictionary
 	var handler: Callable = entry["callable"] as Callable
 	var kind: String = entry["kind"] as String
+	_in_flight += 1
 	match kind:
 		"sync":
 			var result: Dictionary = handler.call(params)
@@ -186,12 +221,14 @@ func _run_async(id: String, handler: Callable, params: Dictionary) -> void:
 	# 客户端 await 挂死到 timeout。先收原 Variant 自己 type-check。
 	var raw: Variant = await handler.call(params)
 	if not raw is Dictionary:
+		_in_flight = max(0, _in_flight - 1)
 		_send_error(id, -32603, "internal: async handler returned non-dict")
 		return
 	_dispatch_result(id, raw as Dictionary)
 
 
 func _dispatch_result(id: String, result: Dictionary) -> void:
+	_in_flight = max(0, _in_flight - 1)
 	if result.has("error"):
 		var err: Dictionary = result["error"] as Dictionary
 		_send_error(id, err["code"] as int, err["message"] as String)
@@ -253,9 +290,35 @@ func _parse_port_from_args() -> int:
 			var port: int = parts[1].to_int()
 			if port < 1 or port > 65535:
 				push_warning(
-					"GameBridge: Port %d out of range [1, 65535], falling back to %d"
-					% [port, DEFAULT_PORT]
+					(
+						"GameBridge: Port %d out of range [1, 65535], falling back to %d"
+						% [port, DEFAULT_PORT]
+					)
 				)
 				return DEFAULT_PORT
 			return port
 	return DEFAULT_PORT
+
+
+func _parse_idle_timeout_from_args() -> int:
+	for arg: String in OS.get_cmdline_args():
+		if arg.begins_with("--game-bridge-idle-timeout="):
+			var parts: PackedStringArray = arg.split("=", false, 1)
+			if parts.size() != 2 or not parts[1].is_valid_int():
+				push_warning("GameBridge: Invalid idle-timeout %s, disabling" % arg)
+				return 0
+			var secs: int = parts[1].to_int()
+			return secs if secs > 0 else 0
+	return 0
+
+
+func _check_idle() -> void:
+	# 有正在处理的请求 → daemon 没闲着；把活动戳推到现在，等所有请求落地后
+	# 再开始计时。否则一个 wait_game_time(idle_timeout+1) 就会被半路 quit。
+	if _in_flight > 0:
+		_last_activity_ms = Time.get_ticks_msec()
+		return
+	var idle_ms: int = Time.get_ticks_msec() - _last_activity_ms
+	if idle_ms / 1000 >= _idle_timeout_secs:
+		print("GameBridge: idle for %ds, shutting down" % (idle_ms / 1000))
+		get_tree().quit()

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/addons/godot_cli_control/tests/gut/test_game_bridge.gd

@@ -344,3 +344,64 @@ func test_sync_input_action_press_routes_to_input_sim_api() -> void:
 	assert_does_not_have(f, "error")
 	assert_eq(_input.press_calls.size(), 1)
 	assert_eq(str(_input.press_calls[0].action), "jump")
+
+
+# ── idle-timeout / in-flight 计数 ─────────────────────────────────
+# 防止回归：长操作（>idle_timeout 的 wait_game_time / combo）期间 _check_idle
+# 不能 quit，否则客户端拿不到响应。
+
+func test_in_flight_starts_at_zero() -> void:
+	assert_eq(_bridge._in_flight, 0)
+
+
+func test_sync_dispatch_returns_in_flight_to_zero() -> void:
+	_send('{"id": "s1", "method": "click", "params": {}}')
+	assert_eq(_bridge._in_flight, 0, "sync 派发完成后 _in_flight 必须归零")
+
+
+func test_async_dispatch_returns_in_flight_to_zero() -> void:
+	_send('{"id": "a1", "method": "wait_for_node", "params": {"path": "/X", "timeout": 1.0}}')
+	# stub 在 await get_tree().process_frame 期间 _in_flight 应保持 1
+	assert_eq(_bridge._in_flight, 1, "async 等待期间 _in_flight 应为 1")
+	await get_tree().process_frame
+	await get_tree().process_frame
+	assert_eq(_bridge._in_flight, 0, "async 派发完成后 _in_flight 必须归零")
+
+
+func test_async_with_id_keeps_in_flight_until_callback() -> void:
+	# 关键场景：input_combo 长动作（实际可能 5s+）期间，daemon 不能因 idle quit
+	_send('{"id": "c1", "method": "input_combo", "params": {"steps": []}}')
+	assert_eq(_bridge._in_flight, 1, "async_with_id handler 未回响前 _in_flight 应为 1")
+	_input.finish_combo(0, {"success": true})
+	assert_eq(_bridge._in_flight, 0, "回调后 _in_flight 必须归零")
+
+
+func test_async_handler_returning_non_dict_decrements_in_flight() -> void:
+	# type-guard 路径也必须减计数，否则 handler bug 会让 daemon 永远不 idle
+	_bridge._methods["wait_for_node"] = {
+		"callable": _async_returning_null,
+		"kind": "async",
+	}
+	_send('{"id": "wn", "method": "wait_for_node", "params": {}}')
+	await get_tree().process_frame
+	await get_tree().process_frame
+	assert_eq(_bridge._in_flight, 0, "非 dict 错误路径也必须把 _in_flight 减回 0")
+
+
+func test_validation_failure_does_not_increment_in_flight() -> void:
+	# Invalid JSON / 协议错没进过 handler，不应碰计数
+	_send("not json")
+	_send('{"id": 42, "method": "click"}')  # id 非串
+	_send('{"id": "x", "method": "no_such"}')  # 未知方法
+	assert_eq(_bridge._in_flight, 0, "校验失败路径不应增 _in_flight")
+
+
+func test_check_idle_resets_activity_when_busy() -> void:
+	# _check_idle 在 _in_flight > 0 时必须把活动戳推到现在 —— 否则一个跨越
+	# 整个 idle_timeout 的长操作会被 quit。
+	_bridge._idle_timeout_secs = 1
+	_bridge._in_flight = 1
+	_bridge._last_activity_ms = Time.get_ticks_msec() - 60_000  # 装作 60s 前
+	_bridge._check_idle()
+	var now: int = Time.get_ticks_msec()
+	assert_almost_eq(_bridge._last_activity_ms, now, 200, "busy 时 _check_idle 必须把活动戳推到 ~now")

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/python/README.md

@@ -36,7 +36,8 @@ import asyncio
 from godot_cli_control import GameClient
 
 async def main():
-    async with GameClient(port=9877) as client:
+    # Omitting port lets GameClient auto-discover from .cli_control/port (written by daemon start)
+    async with GameClient() as client:
         tree = await client.get_scene_tree(depth=3)
         await client.click("/root/MyScene/Button")
         await client.action_press("jump")
@@ -84,7 +85,7 @@ def test_jump(godot_daemon, bridge):
 CLI options:
 
 ```
---godot-cli-port=N           # GameBridge port (default 9877)
+--godot-cli-port=N           # GameBridge port (default: read from .cli_control/port)
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
 ```
@@ -96,9 +97,10 @@ The CLI is the canonical surface — every `GameClient` method has a one-line eq
 ```bash
 # Lifecycle
 godot-cli-control init [--path DIR] [--force]
-godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N]
-godot-cli-control daemon stop
+godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N --idle-timeout 30m]
+godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
+godot-cli-control daemon ls                  # list running daemons across all projects
 godot-cli-control run <script.py> [--headless ...]
 
 # Read

godot_cli_control-0.2.4/python/godot_cli_control/_duration.py

@@ -0,0 +1,18 @@
+"""Parse human-friendly duration strings (e.g. "30m", "2h", "90s") to seconds."""
+from __future__ import annotations
+
+import re
+
+# 不允许数字与单位之间留空格 —— 与帮助文本「30m / 2h / 90s」保持一致，避免
+# 既文档教 30m 又静默接受 "30 m" 这种半通不通的输入。两端 \s* 仍保留，方便
+# 用户从 shell 复制带尾换行的字串。
+_PATTERN = re.compile(r"^\s*(\d+)([smh]?)\s*$")
+_UNITS = {"": 1, "s": 1, "m": 60, "h": 3600}
+
+
+def parse_duration(text: str) -> int:
+    """Return total seconds. Bare integer = seconds. 0 means disabled."""
+    m = _PATTERN.match(text)
+    if not m:
+        raise ValueError(f"invalid duration {text!r} (use 30s / 30m / 2h / 0)")
+    return int(m.group(1)) * _UNITS[m.group(2)]

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/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.3'
-__version_tuple__ = version_tuple = (0, 2, 3)
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.3 → godot_cli_control-0.2.4}/python/godot_cli_control/cli.py

@@ -42,6 +42,10 @@ OUTPUT_TEXT = "text"
 EXIT_OK = 0
 EXIT_RPC_ERROR = 1
 EXIT_INFRA_ERROR = 2  # 连接 / 超时 / 用户输入解析失败
+# `daemon stop --all` 专用：至少一条 stop 失败。不复用 EXIT_INFRA_ERROR(=2) —— 单个项目
+# stop rc=2 是「daemon 已停但 ffmpeg 转码失败」的合法成功旁路；--all 聚合若也用 2，
+# 调用方分不清「全停成功只是某个 transcode 失败」与「真有 daemon 没停掉」。
+EXIT_PARTIAL = 3
 EXIT_USAGE = 64  # 命令组合无效（如 combo 既无文件又无 --steps-json）
 
 # RPC 错误统一信封（无论 --json 还是 --text）的连接/超时占位 code。GD 端
@@ -641,6 +645,13 @@ RPC_BY_NAME: dict[str, RpcSpec] = {s.name: s for s in RPC_SPECS}
 
 def cmd_daemon_start(ns: argparse.Namespace) -> int:
     from .daemon import Daemon, DaemonError
+    from ._duration import parse_duration
+
+    try:
+        idle_seconds = parse_duration(getattr(ns, "idle_timeout", "0"))
+    except ValueError as e:
+        _emit_top_error(ns, code=CLIENT_CODE_USAGE, message=str(e))
+        return EXIT_USAGE
 
     daemon = Daemon(Path.cwd())
     try:
@@ -650,6 +661,7 @@ def cmd_daemon_start(ns: argparse.Namespace) -> int:
             headless=ns.headless,
             fps=ns.fps,
             port=ns.port,
+            idle_timeout=idle_seconds,
         )
     except DaemonError as e:
         _emit_top_error(ns, code=CLIENT_CODE_USAGE, message=str(e))
@@ -670,17 +682,64 @@ def cmd_daemon_start(ns: argparse.Namespace) -> int:
 
 def cmd_daemon_stop(ns: argparse.Namespace) -> int:
     from .daemon import Daemon, DaemonError
+    from . import registry
 
-    daemon = Daemon(Path.cwd())
+    fmt = _output_format(ns)
+
+    if getattr(ns, "all", False):
+        records = registry.list_all()
+        if not records:
+            if fmt == OUTPUT_JSON:
+                _emit_success_payload({"stopped": [], "rc": 0})
+            else:
+                print("(no running daemons)")
+            return EXIT_OK
+        results: list[dict[str, Any]] = []
+        had_failure = False
+        for r in records:
+            entry: dict[str, Any] = {
+                "project_root": r.project_root,
+                "pid": r.pid,
+                "port": r.port,
+            }
+            try:
+                rc = Daemon(Path(r.project_root)).stop()
+                entry["rc"] = rc
+                if fmt != OUTPUT_JSON:
+                    suffix = f" (rc={rc})" if rc != 0 else ""
+                    print(f"stopped pid={r.pid} port={r.port} {r.project_root}{suffix}")
+            except DaemonError as e:
+                entry["rc"] = EXIT_INFRA_ERROR
+                entry["error"] = str(e)
+                had_failure = True
+                # 单条失败不能阻止其余 daemon 收尾
+                print(f"[{r.project_root}] {e}", file=sys.stderr)
+            results.append(entry)
+        # rc 含义：0 = 全部成功；EXIT_PARTIAL = 至少一条 DaemonError。注意单条 stop
+        # 返回 2（ffmpeg 转码失败但 daemon 已停）不算"失败"，按成功汇总；调用方
+        # 想要逐条状态请看 JSON 输出 / 文本里的每行 rc=N 标记。
+        rc_total = EXIT_PARTIAL if had_failure else EXIT_OK
+        if fmt == OUTPUT_JSON:
+            _emit_success_payload({"stopped": results, "rc": rc_total})
+        else:
+            failed = sum(1 for x in results if "error" in x)
+            print(
+                f"summary: {len(results) - failed}/{len(results)} stopped"
+                + (f", {failed} failed" if failed else "")
+            )
+        return rc_total
+
+    target = (ns.project.resolve() if getattr(ns, "project", None) else Path.cwd())
+    daemon = Daemon(target)
     try:
         rc = daemon.stop()
     except DaemonError as e:
         _emit_top_error(ns, code=CLIENT_CODE_USAGE, message=str(e))
         return EXIT_INFRA_ERROR
-    if _output_format(ns) == OUTPUT_JSON:
+    if fmt == OUTPUT_JSON:
         # rc 0=正常停 / 2=ffmpeg 转码失败但 daemon 已停。两种都算"stopped"，
         # 把 rc 透出让 agent 决定要不要 retry transcode。
-        _emit_success_payload({"stopped": True, "rc": rc})
+        _emit_success_payload({"stopped": True, "rc": rc, "project_root": str(target)})
     return rc
 
 
@@ -712,22 +771,82 @@ def cmd_daemon_status(ns: argparse.Namespace) -> int:
                 f"running pid={pid} port={port if port is not None else '?'}"
             )
         return EXIT_OK
+    # Stopped：若上一轮启动留下了 godot.log / last_exit_code，把诊断信息透出来。
+    # issue #38 要求 daemon 已退出时直接告诉用户「last exit: <code>, see ...log」，
+    # 不让用户再手摸 .cli_control/ 翻文件。
+    stopped_payload: dict[str, Any] = {"state": "stopped"}
+    if daemon.log_file.exists():
+        stopped_payload["last_log"] = str(daemon.log_file)
+    last_rc = daemon.read_last_exit_code()
+    if last_rc is not None:
+        stopped_payload["last_exit_code"] = last_rc
     if fmt == OUTPUT_JSON:
-        _emit_success_payload({"state": "stopped"})
+        _emit_success_payload(stopped_payload)
     else:
-        print("stopped")
+        hints: list[str] = []
+        if "last_exit_code" in stopped_payload:
+            hints.append(f"last exit: {stopped_payload['last_exit_code']}")
+        if "last_log" in stopped_payload:
+            hints.append(f"see {stopped_payload['last_log']}")
+        if hints:
+            print(f"stopped ({', '.join(hints)})")
+        else:
+            print("stopped")
     return EXIT_RPC_ERROR
 
 
+def cmd_daemon_ls(ns: argparse.Namespace) -> int:
+    """跨项目列出运行中的 daemon。
+
+    扫全局注册表 ~/.local/state/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)。
+    """
+    from . import registry
+
+    fmt = _output_format(ns)
+    records = registry.list_all()
+    payload = {
+        "daemons": [
+            {
+                "project_root": r.project_root,
+                "pid": r.pid,
+                "port": r.port,
+                "started_at": r.started_at,
+                "godot_bin": r.godot_bin,
+                "log_path": r.log_path,
+            }
+            for r in records
+        ]
+    }
+    if fmt == OUTPUT_JSON:
+        _emit_success_payload(payload)
+    else:
+        if not records:
+            print("(no running daemons)")
+        else:
+            for r in records:
+                print(f"{r.pid}\t{r.port}\t{r.project_root}\t{r.started_at}")
+    return EXIT_OK
+
+
 def cmd_run(ns: argparse.Namespace) -> int:
     """加载用户脚本（要求定义 ``run(bridge)``），自动启停 daemon。"""
     from .daemon import Daemon, DaemonError
+    from ._duration import parse_duration
 
     script_path = Path(ns.script)
     if not script_path.exists():
         print(f"错误：找不到脚本: {script_path}", file=sys.stderr)
         return 1
 
+    try:
+        idle_seconds = parse_duration(getattr(ns, "idle_timeout", "0"))
+    except ValueError as e:
+        print(f"错误：{e}", file=sys.stderr)
+        return EXIT_USAGE
+
     daemon = Daemon(Path.cwd())
     auto_started = False
     if not daemon.is_running():
@@ -738,6 +857,7 @@ def cmd_run(ns: argparse.Namespace) -> int:
                 headless=ns.headless,
                 fps=ns.fps,
                 port=ns.port,
+                idle_timeout=idle_seconds,
             )
         except DaemonError as e:
             print(f"错误：{e}", file=sys.stderr)
@@ -935,8 +1055,14 @@ def _add_daemon_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument(
         "--port",
         type=int,
-        default=DEFAULT_PORT,
-        help=f"GameBridge 监听端口（默认 {DEFAULT_PORT}）",
+        default=0,
+        help="GameBridge 监听端口（默认 0 = OS 自动分配；写入 .cli_control/port）",
+    )
+    p.add_argument(
+        "--idle-timeout",
+        type=str,
+        default="0",
+        help="空闲超时（如 30m / 2h / 90s / 0=关闭，默认关）。开启后 Godot 端 Timer 自动 quit。",
     )
 
 
@@ -1015,10 +1141,22 @@ def build_parser() -> argparse.ArgumentParser:
     )
     _add_daemon_flags(start_p)
 
-    daemon_subs.add_parser(
+    stop_p = daemon_subs.add_parser(
         "stop",
         help="停止 daemon",
-        description="停止 .cli_control/godot.pid 记录的 daemon。",
+        description=(
+            "停止 daemon。无 flag 时停 cwd 项目；--all 停所有注册的 daemon；"
+            "--project <path> 停指定项目。"
+        ),
+    )
+    stop_grp = stop_p.add_mutually_exclusive_group()
+    stop_grp.add_argument(
+        "--all", action="store_true",
+        help="停止注册表中所有运行中的 daemon"
+    )
+    stop_grp.add_argument(
+        "--project", type=Path, default=None,
+        help="停止指定项目根的 daemon（绝对/相对路径均可）"
     )
 
     daemon_subs.add_parser(
@@ -1032,6 +1170,16 @@ def build_parser() -> argparse.ArgumentParser:
         ),
     )
 
+    ls_p = daemon_subs.add_parser(
+        "ls",
+        help="列出所有正在运行的 daemon（跨项目）",
+        description=(
+            "扫描全局注册表 ~/.local/state/godot-cli-control/daemons/，"
+            "列出所有探活通过的 daemon。死记录会被自动清理。"
+        ),
+    )
+    _add_output_format_flags(ls_p)
+
     # run：自动启停 + 跑用户脚本
     run_p = subs.add_parser(
         "run",
@@ -1261,6 +1409,8 @@ def main() -> None:
             sys.exit(cmd_daemon_stop(ns))
         if ns.action == "status":
             sys.exit(cmd_daemon_status(ns))
+        if ns.action == "ls":
+            sys.exit(cmd_daemon_ls(ns))
         parser.error(f"unknown daemon action: {ns.action}")
     if ns.cmd == "run":
         sys.exit(cmd_run(ns))