godot-cli-control 0.2.12__tar.gz → 0.2.13__tar.gz

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.12
+Version: 0.2.13
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT
@@ -13,6 +13,7 @@ Provides-Extra: test
 Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
 Requires-Dist: pytest-cov>=4; extra == 'test'
 Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: ruff>=0.6; extra == 'test'
 Description-Content-Type: text/markdown
 
 # godot-cli-control

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/addons/godot_cli_control/README.md

@@ -104,6 +104,12 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 | `get_pressed()` | `await client.get_pressed()` |
 | `list_input_actions(include_builtin=False)` | `await client.list_input_actions()` |
 
+> **CLI note**: as a shell subcommand, `screenshot` **requires an output path** — `godot-cli-control screenshot /tmp/shot.png` — and writes the PNG to that file. Returning base64 over stdout is intentionally unsupported, to keep large binary payloads out of an automating agent's context window.
+
+> **`--wait`**: `tap` / `hold` / `combo` return as soon as the input is armed, *before* the motion finishes. Add `--wait` (e.g. `hold run 1.5 --wait`) to block until the action's duration elapses (game-time) so the next read sees the settled state — equivalent to following the command with `wait-time <duration>` on the same connection.
+
+> **No-arg `GameClient()` / `GameBridge()`**: with no `port` argument they auto-discover the daemon's port from `.cli_control/port` (falling back to `9877`), so a single-connection script connects to a running daemon without hardcoding a port.
+
 ### Error codes
 
 Three numeric ranges share `error.code`; they never overlap, so a single field is unambiguous.
@@ -112,7 +118,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 |---|---|---|
 | `1001` | server | Node not found at the given path |
 | `1002` | server | Property not found / shape mismatch |
-| `1003` | server | Method not found on the node (schema error, don't retry) |
+| `1003` | server | 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; run `actions` (or `actions --all`) to list valid actions |
 | `1004` | server | Combo already in progress (call `combo-cancel` to retry) |
 | `1005` | server | Scene tree too large (lower `depth` or pass `--max-nodes`) |
 | `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. |
@@ -121,13 +127,40 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `-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`, …) |
+| `-1003` | client | CLI usage error (combo missing steps, malformed `--steps-json`, a non-numeric `tap`/`wait-time` arg, a `set`/`call` value that fails JSON parsing, …). From an RPC subcommand this always exits **64** (#82); top-level `run`/`daemon` precondition failures also use `-1003` but exit 2. |
 | `-1004` | client | Local file IO error (e.g. screenshot can't write the destination) |
 | `-1005` | client | `run <script>` user script raised an uncaught exception — fix the script |
 | `-1099` | client | Internal CLI bug — please file an issue |
 
 For full retry guidance see the SKILL.md shipped by `godot-cli-control init` (`.claude/skills/godot-cli-control/SKILL.md` in the target project).
 
+## Daemon commands
+
+The daemon is the long-lived Godot process the CLI talks to (one per project root). The CLI auto-starts it where needed; manage it explicitly with:
+
+| Command | What it does |
+|---|---|
+| `daemon start [--headless\|--gui] [--record]` | Launch Godot with the bridge listening. Headless vs GUI is auto-detected from the TTY; `--record` forces GUI (Movie Maker needs a real renderer) and is **rejected with `--headless`** (exit 2). |
+| `daemon stop` | Stop this project's daemon. Exit 2 if it stopped cleanly but the `.avi`→`.mp4` ffmpeg transcode failed (raw `.avi` kept; see `.cli_control/ffmpeg.log`). |
+| `daemon stop --all` | Stop every registered daemon across all projects. **Exit 3** if at least one failed; per-record `rc` (and an `error` field on failures) is in `result.stopped[]`. |
+| `daemon stop --project <path>` | Stop the daemon for one specific project root. |
+| `daemon status` | Exit 0 = running, 1 = stopped. When stopped, the payload may carry `last_log` / `last_exit_code` to diagnose a crash. |
+| `daemon ls` | List every registered daemon (project root, pid, port). |
+
+**Project-level defaults**: drop a `.cli_control/config.json` with `{"idle_timeout": "30m"}` to give `daemon start` / `run` a default idle-timeout without passing `--idle-timeout` each time. It's consulted only when the flag is omitted (default `0`); an explicit `--idle-timeout` always wins. A long-running `wait-time` / `combo` / recording is bounded client-side by a 600s wall-time fail-safe — override it for legitimately long operations with `GODOT_CLI_LONG_OP_TIMEOUT=<seconds>`.
+
+## Exit codes
+
+Semantic exit codes so `if godot-cli-control exists /root/Foo; then …` works in shell:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (or boolean true for `exists` / `visible`, node found for `wait-node`) |
+| 1 | RPC error; also `exists`/`visible`=false, `wait-node` timeout, `daemon status`=stopped |
+| 2 | Connection / IO error, or `daemon stop` ffmpeg-transcode failure |
+| 3 | `daemon stop --all` partial failure (≥1 daemon failed to stop) |
+| 64 | Usage error on an RPC subcommand — bad argparse args, a pre-flight reject (`combo` with no steps / malformed `--steps-json`), a non-numeric `tap`/`wait-time` arg, or a `set`/`call` value that fails JSON parsing. These all carry client code `-1003` and now consistently exit 64 (#82; a few previously exited 2). |
+
 ## Activation Modes
 
 Activation paths (any one triggers the bridge):
@@ -151,7 +184,7 @@ If none triggered, the plugin prints `[Godot CLI Control] inactive — ...` to c
 ## Known Limitations
 
 1. **Headless + Movie Maker is broken** (Godot upstream): `--write-movie` produces empty MP4 in headless mode (no framebuffer). Use GUI mode for recording.
-2. **Godot binary detection** falls back to `GODOT_BIN` env var. `init` writes `.cli_control/godot_bin` after autodetect; daemon reads that file before scanning. Detection covers macOS `/Applications/Godot*.app`, `PATH` (`godot`/`godot4`), and Windows `Program Files\Godot*`.
+2. **Godot binary detection** order: `GODOT_BIN` env var → macOS `/Applications/Godot*.app` → `PATH` (`godot4`/`godot`) → Windows `Program Files\Godot*`. `init` writes the detected path to `.cli_control/godot_bin`; the daemon reads that file before re-scanning. The pytest e2e suite uses this same detection, so a `godot` on `PATH` is enough to run it.
 3. **Python ≥ 3.10** required (websockets>=14 dependency).
 4. **Single-client mode**: only one WebSocket client at a time; second connection rejected.
 5. **Headless plugin auto-register**: in headless mode, `--editor --quit` may not trigger `plugin._enter_tree` to write the autoload. `init` handles this automatically by patching `project.godot` directly.

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/pyproject.toml

@@ -12,9 +12,9 @@ dependencies = [
 
 [project.optional-dependencies]
 pytest = ["pytest>=7"]
-# 全套测试依赖 —— 仅 CI / 开发者本地测试用，包含 pytest-cov 与 pytest-asyncio。
-# 普通用户用 `[pytest]` 已够；不要把 cov 拖到默认安装路径。
-test = ["pytest>=7", "pytest-asyncio>=0.21", "pytest-cov>=4"]
+# 全套测试依赖 —— 仅 CI / 开发者本地测试用，包含 pytest-cov、pytest-asyncio 与
+# ruff（lint 门禁，issue #83）。普通用户用 `[pytest]` 已够；不要把这些拖到默认安装路径。
+test = ["pytest>=7", "pytest-asyncio>=0.21", "pytest-cov>=4", "ruff>=0.6"]
 
 [project.scripts]
 godot-cli-control = "godot_cli_control.cli:main"
@@ -23,14 +23,33 @@ godot-cli-control = "godot_cli_control.cli:main"
 godot-cli-control = "godot_cli_control.pytest_plugin"
 
 [tool.pytest.ini_options]
+# pytest-asyncio：显式钉死 async fixture 的 loop scope 为 function（= 未来版本默认值），
+# 消除 "asyncio_default_fixture_loop_scope is unset" 的 deprecation warning。改这行前
+# 先确认没有 module/session-scope 的 async fixture 依赖跨用例共享 loop。
+asyncio_default_fixture_loop_scope = "function"
 # gui：需要真实显示（开窗）才能跑的端到端测试。普通 unit / headless e2e 不带此
-# marker。本地默认随 GODOT_BIN / GCC_GUI_E2E 未设而 skip；CI 专档（Linux 套
+# marker。本地默认随 godot 检测 / 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）",
 ]
 
+# ── lint（ruff）─────────────────────────────────────────────────────────
+# issue #83：把 lint 从「开发者本机全局 ruff」收编成 CI 门禁 + dev 依赖，趁全仓
+# 基线为 0 锁定收益。规则集刻意只钉 ruff 默认的 pyflakes(F) + pycodestyle 子集
+# (E4/E7/E9)——这正是当前 0-error 基线对应的集合；扩到 E501/I/UP/B 会一次性炸出
+# 几十条历史报错，与「锁定基线、零噪音引入门禁」的目标相悖。要加规则请单开 PR、
+# 连同 autofix 一起 land，别让门禁第一天就红。line-length 仅供 `ruff format`
+# 参考（E501 未纳入 select，不构成门禁）。
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+extend-exclude = ["python/godot_cli_control/_version.py"]  # hatch-vcs 生成物
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/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.12'
-__version_tuple__ = version_tuple = (0, 2, 12)
+__version__ = version = '0.2.13'
+__version_tuple__ = version_tuple = (0, 2, 13)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/python/godot_cli_control/bridge.py

@@ -15,13 +15,16 @@ import asyncio
 from pathlib import Path
 from typing import Any
 
-from .client import DEFAULT_PORT, GameClient
+from .client import GameClient
 
 
 class GameBridge:
     """同步接口，内部通过事件循环调用异步 GameClient。"""
 
-    def __init__(self, port: int = DEFAULT_PORT) -> None:
+    def __init__(self, port: int | None = None) -> None:
+        # port=None → GameClient 从 .cli_control/port auto-discover（issue #91）。
+        # daemon 默认 OS 自动分配端口，所以 ``GameBridge()`` 无参数也能连上正在
+        # 跑的 daemon，与 README 的单连接脚本示例一致。
         self._loop = asyncio.new_event_loop()
         self._client = GameClient(port=port)
         self._loop.run_until_complete(

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/python/godot_cli_control/cli.py

@@ -243,6 +243,39 @@ def _read_combo_steps(ns: argparse.Namespace) -> list[dict]:
     return parsed
 
 
+def _combo_total_duration(steps: list[dict]) -> float:
+    """combo 全部 step 的累计 game-time（给 ``--wait`` 算阻塞时长，issue #90）。
+
+    step schema 与服务端一致：``{"action": ..., "duration": <默认 0.1>}`` 串行
+    按下/释放，``{"wait": <秒>}`` 纯等待。非数字 / 缺字段按默认 0.1 兜底，绝不
+    抛错——``--wait`` 是体验增强，估时偏差远好过让命令崩掉。
+    """
+    total = 0.0
+    for step in steps:
+        if not isinstance(step, dict):
+            continue
+        raw = step.get("wait", step.get("duration", 0.1))
+        try:
+            total += float(raw)
+        except (TypeError, ValueError):
+            total += 0.1
+    return total
+
+
+async def _maybe_block_for_duration(
+    client: GameClient, ns: argparse.Namespace, duration: float
+) -> None:
+    """``--wait``：输入命令发出后，阻塞 ``duration`` 的 game-time 再返回（issue #90）。
+
+    把 SKILL.md 推荐的「读动作完成后状态前先 wait-time <时长>」折叠进同一条命令、
+    复用同一连接：需要同步的 agent 一步到位拿到结算后状态。默认（不传 ``--wait``）
+    保持异步立即返回，sticky + timer 模型不变。``wait_game_time`` 在 ≤0 时本就短路，
+    这里也提前挡掉，省一次 RPC 往返。
+    """
+    if getattr(ns, "wait", False) and duration > 0:
+        await client.wait_game_time(duration)
+
+
 # ── 现有 RPC 命令 handler（迁移到 ns 签名 + 返回数据） ──
 
 
@@ -279,11 +312,16 @@ async def cmd_release(client: GameClient, ns: argparse.Namespace) -> dict:
 
 async def cmd_tap(client: GameClient, ns: argparse.Namespace) -> dict:
     duration = float(ns.duration) if ns.duration else 0.1
-    return await client.action_tap(ns.action, duration)
+    result = await client.action_tap(ns.action, duration)
+    await _maybe_block_for_duration(client, ns, duration)
+    return result
 
 
 async def cmd_hold(client: GameClient, ns: argparse.Namespace) -> dict:
-    return await client.hold(ns.action, float(ns.duration))
+    duration = float(ns.duration)
+    result = await client.hold(ns.action, duration)
+    await _maybe_block_for_duration(client, ns, duration)
+    return result
 
 
 async def cmd_combo(client: GameClient, ns: argparse.Namespace) -> dict:
@@ -291,7 +329,9 @@ async def cmd_combo(client: GameClient, ns: argparse.Namespace) -> dict:
     steps = getattr(ns, "_combo_steps", None)
     if steps is None:
         steps = _read_combo_steps(ns)
-    return await client.combo(steps)
+    result = await client.combo(steps)
+    await _maybe_block_for_duration(client, ns, _combo_total_duration(steps))
+    return result
 
 
 async def cmd_release_all(client: GameClient, ns: argparse.Namespace) -> dict:
@@ -424,8 +464,18 @@ def _exit_from_wait_node(r: dict) -> int:
 # ── extra_args registrators ──
 
 
+def _register_wait_flag(p: argparse.ArgumentParser) -> None:
+    """``--wait``：输入命令阻塞到动作时长（game-time）结束再返回（issue #90）。"""
+    p.add_argument(
+        "--wait",
+        action="store_true",
+        help="阻塞到动作时长（game-time）结束再返回，再读状态即结算后值；"
+        "默认异步立即返回。等价于命令后再跑一次 wait-time <时长>，但复用同一连接。",
+    )
+
+
 def _register_combo_args(p: argparse.ArgumentParser) -> None:
-    """combo 的 args：``json_file`` 位置可选，加 ``--steps-json``。
+    """combo 的 args：``json_file`` 位置可选，加 ``--steps-json`` / ``--wait``。
     互斥校验在 ``_read_combo_steps`` 里做（argparse 里不能同时加 dest 冲突的
     位置参数和可选参数到 mutually_exclusive_group）。"""
     p.add_argument(
@@ -439,6 +489,7 @@ def _register_combo_args(p: argparse.ArgumentParser) -> None:
         default=None,
         help="直接传 JSON 字符串，不需要文件（与位置参数互斥）",
     )
+    _register_wait_flag(p)
 
 
 def _register_tree_args(p: argparse.ArgumentParser) -> None:
@@ -558,23 +609,25 @@ RPC_SPECS: tuple[RpcSpec, ...] = (
     RpcSpec(
         name="tap",
         handler=cmd_tap,
-        description="短按动作（press → 等待 → release）。",
+        description="短按动作（press → 等待 → release）。默认异步立即返回；加 --wait 阻塞到时长结束。",
         positionals=(
             Positional("action", None, "InputMap 动作名"),
             Positional("duration", "?", "按下时长（秒），默认 0.1"),
         ),
         example="tap jump 0.2",
+        extra_args=_register_wait_flag,
         text_formatter=lambda r: f"tapped: {r}",
     ),
     RpcSpec(
         name="hold",
         handler=cmd_hold,
-        description="按住动作指定时长（秒），到点自动释放。",
+        description="按住动作指定时长（秒），到点自动释放。默认命令立即返回（动作在游戏里持续该时长）；要读动作完成后的状态请加 --wait（或命令后先 wait-time <时长>）。",
         positionals=(
             Positional("action", None, "InputMap 动作名"),
             Positional("duration", None, "按住时长（秒，必须 > 0）"),
         ),
         example="hold jump 1.5",
+        extra_args=_register_wait_flag,
         preflight=_preflight_hold,
         text_formatter=lambda r: f"holding: {r}",
     ),
@@ -762,12 +815,37 @@ RPC_BY_NAME: dict[str, RpcSpec] = {s.name: s for s in RPC_SPECS}
 # ── Daemon / run / init 子命令 ──
 
 
+def _resolve_idle_timeout(ns: argparse.Namespace) -> int:
+    """解析 idle-timeout 秒数：显式 ``--idle-timeout`` > 项目级 config > 0（关闭）。
+
+    issue #44：默认值 ``"0"`` 时回退读 ``.cli_control/config.json`` 的 ``idle_timeout``，
+    省得喜欢自动收尾的用户每次手敲 ``--idle-timeout``。config 也没设则仍是 0（关闭）。
+    注意：显式 ``--idle-timeout 0`` 与默认 ``"0"`` 不可区分，两者都会回退 config——
+    config 设了又想单次强制关闭，临时 `unset` 配置即可（YAGNI，未做 opt-out flag）。
+    非法 duration（CLI 或 config 任一）抛 ``ValueError``，由调用方转 EXIT_USAGE。
+    """
+    from ._duration import parse_duration
+
+    raw = getattr(ns, "idle_timeout", "0")
+    if raw == "0":
+        from .daemon import read_project_config
+
+        cfg_val = read_project_config().get("idle_timeout")
+        if cfg_val is not None:
+            try:
+                return parse_duration(str(cfg_val))
+            except ValueError as e:
+                raise ValueError(
+                    f".cli_control/config.json 的 idle_timeout 非法：{e}"
+                ) from e
+    return parse_duration(raw)
+
+
 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"))
+        idle_seconds = _resolve_idle_timeout(ns)
     except ValueError as e:
         _emit_top_error(ns, code=CLIENT_CODE_USAGE, message=str(e))
         return EXIT_USAGE
@@ -965,7 +1043,6 @@ def cmd_run(ns: argparse.Namespace) -> int:
       64 argparse 用法错（idle_timeout 解析失败等"明显参数写错"）
     """
     from .daemon import Daemon, DaemonError
-    from ._duration import parse_duration
 
     fmt = _output_format(ns)
 
@@ -985,7 +1062,7 @@ def cmd_run(ns: argparse.Namespace) -> int:
             return EXIT_INFRA_ERROR
 
         try:
-            idle_seconds = parse_duration(getattr(ns, "idle_timeout", "0"))
+            idle_seconds = _resolve_idle_timeout(ns)
         except ValueError as e:
             if fmt == OUTPUT_JSON:
                 _emit_error_payload(CLIENT_CODE_USAGE, str(e))
@@ -1395,7 +1472,8 @@ def _add_daemon_flags(p: argparse.ArgumentParser) -> None:
         "--idle-timeout",
         type=str,
         default="0",
-        help="空闲超时（如 30m / 2h / 90s / 0=关闭，默认关）。开启后 Godot 端 Timer 自动 quit。",
+        help="空闲超时（如 30m / 2h / 90s / 0=关闭，默认关）。开启后 Godot 端 Timer 自动 quit。"
+        "不传时回退读 .cli_control/config.json 的 idle_timeout（issue #44），省得每次手敲。",
     )
 
 
@@ -1748,9 +1826,12 @@ async def _run_rpc(
         _emit_envelope_error(fmt, code, msg)
         return EXIT_INFRA_ERROR
     except (ValueError, json.JSONDecodeError) as e:
-        # 用法错误：combo 没文件没 inline、set value 解析失败……
+        # 用法错误：set/call 的 value JSON 解析失败等（这些命令无 preflight）。
+        # 统一退 EXIT_USAGE(64)，与 preflight 路径（combo/hold）一致 —— 同一客户端
+        # 码 -1003 必须恒等于 exit 64，否则 agent 拿到 -1003 无法据此推断退出码
+        # （issue #82，破坏「单 code 字段无歧义」契约）。
         _emit_envelope_error(fmt, CLIENT_CODE_USAGE, str(e))
-        return EXIT_INFRA_ERROR
+        return EXIT_USAGE
     except Exception as e:  # noqa: BLE001
         # 兜底：客户端内部 bug（AttributeError、KeyError、协议解析意外等）
         # 也要落进信封，否则 ``--json`` 契约对 AI agent 不再可信。把异常类
@@ -1805,9 +1886,10 @@ def main() -> None:
 
         port = ns.port
         if port is None:
-            from .daemon import Daemon
+            # 与 GameClient()/GameBridge() 共用同一发现入口（issue #91）。
+            from .daemon import discover_port
 
-            port = Daemon(Path.cwd()).current_port() or DEFAULT_PORT
+            port = discover_port() or DEFAULT_PORT
 
         rc = asyncio.run(_run_rpc(spec, ns, port, fmt))
         sys.exit(rc)

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/python/godot_cli_control/client.py

@@ -4,6 +4,7 @@ import asyncio
 import base64
 import json
 import logging
+import os
 import uuid
 from typing import Any
 
@@ -23,7 +24,39 @@ DEFAULT_PORT: int = 9877
 # 改用固定大值后：正常完成时 server 自然回包；server 真死循环时由 600s 兜底
 # （而不是 55s 把还活着的录像炸掉）；死连接由 websockets 库的 ping/pong 心跳
 # 在 ~40s 内独立检测，与本上限无关。
-LONG_OP_CLIENT_TIMEOUT: float = 600.0
+LONG_OP_DEFAULT_TIMEOUT: float = 600.0
+
+
+def _resolve_long_op_timeout() -> float:
+    """长操作生死线，可被 ``GODOT_CLI_LONG_OP_TIMEOUT`` env 覆盖（issue #69）。
+
+    默认 ``LONG_OP_DEFAULT_TIMEOUT``（600s）。合法录像 > 10min 等少数长操作可
+    设环境变量调高（如 ``GODOT_CLI_LONG_OP_TIMEOUT=1800``）。非正数 / 非数字一律
+    忽略并回退默认——这是个兜底生死线，绝不能因 env 写错被设成 0 把正常操作秒杀。
+    """
+    raw = os.environ.get("GODOT_CLI_LONG_OP_TIMEOUT")
+    if not raw:
+        return LONG_OP_DEFAULT_TIMEOUT
+    try:
+        value = float(raw)
+    except ValueError:
+        logger.warning(
+            "GODOT_CLI_LONG_OP_TIMEOUT=%r 不是数字，回退默认 %.0fs",
+            raw, LONG_OP_DEFAULT_TIMEOUT,
+        )
+        return LONG_OP_DEFAULT_TIMEOUT
+    if value <= 0:
+        logger.warning(
+            "GODOT_CLI_LONG_OP_TIMEOUT=%r 必须 > 0，回退默认 %.0fs",
+            raw, LONG_OP_DEFAULT_TIMEOUT,
+        )
+        return LONG_OP_DEFAULT_TIMEOUT
+    return value
+
+
+# 模块级解析一次：进程生命周期内 env 不变；测试需要时改 env 后调
+# ``_resolve_long_op_timeout()`` 拿新值，或直接给 request() 传 timeout。
+LONG_OP_CLIENT_TIMEOUT: float = _resolve_long_op_timeout()
 
 
 class RpcError(RuntimeError):
@@ -43,7 +76,17 @@ class RpcError(RuntimeError):
 class GameClient:
     """WebSocket client that connects to Godot's GameBridge service."""
 
-    def __init__(self, port: int = DEFAULT_PORT) -> None:
+    def __init__(self, port: int | None = None) -> None:
+        # port=None（无显式端口）→ 从 .cli_control/port auto-discover，找不到再回退
+        # DEFAULT_PORT。daemon 默认 OS 自动分配端口，所以照 README 写
+        # ``GameClient()`` 单连接脚本的用户/agent 必须经由这条发现路径才能连上
+        # （issue #91）。发现逻辑收敛在 daemon.discover_port，CLI 走同一入口。
+        # 延迟 import 避免 client 在 package import 时拉起 daemon→registry 这条
+        # 较重的依赖链。
+        if port is None:
+            from .daemon import discover_port
+
+            port = discover_port() or DEFAULT_PORT
         self._port = port
         self._ws: ClientConnection | None = None
         self._pending: dict[str, asyncio.Future[dict]] = {}
@@ -279,17 +322,18 @@ class GameClient:
     async def wait_game_time(self, seconds: float) -> dict:
         """按 Godot game time 等待 N 秒。
 
-        客户端用固定 ``LONG_OP_CLIENT_TIMEOUT`` 生死线（issue #45）：game-time
-        与 wall-time 比值受录像模式 / 分辨率 / 盘速 / fps 影响不可预测，任何
-        seconds-scaled 公式都会在某个组合下假超时。死连接由 ws ping/pong 兜底。
-        seconds <= 0 时客户端短路返回，不发 RPC。
+        客户端用固定的长操作生死线（issue #45）：game-time 与 wall-time 比值受
+        录像模式 / 分辨率 / 盘速 / fps 影响不可预测，任何 seconds-scaled 公式都会
+        在某个组合下假超时。死连接由 ws ping/pong 兜底。生死线默认 600s，可被
+        ``GODOT_CLI_LONG_OP_TIMEOUT`` env 覆盖（issue #69）——每次调用现取，
+        让 env 改动即时生效。seconds <= 0 时客户端短路返回，不发 RPC。
         """
         if seconds <= 0:
             return {"success": True}
         return await self.request(
             "wait_game_time",
             {"seconds": seconds},
-            timeout=LONG_OP_CLIENT_TIMEOUT,
+            timeout=_resolve_long_op_timeout(),
         )
 
     # ---- Input simulation API ----
@@ -311,10 +355,11 @@ class GameClient:
         )
 
     async def combo(self, steps: list[dict]) -> dict:
-        # 客户端用固定 LONG_OP_CLIENT_TIMEOUT 生死线（issue #45）：见
-        # wait_game_time 注释——同样的 game-time / wall-time 不对齐问题。
+        # 长操作生死线（issue #45）：见 wait_game_time 注释——同样的 game-time /
+        # wall-time 不对齐问题。默认 600s，可被 GODOT_CLI_LONG_OP_TIMEOUT 覆盖
+        # （issue #69），每次调用现取。
         return await self.request(
-            "input_combo", {"steps": steps}, timeout=LONG_OP_CLIENT_TIMEOUT
+            "input_combo", {"steps": steps}, timeout=_resolve_long_op_timeout()
         )
 
     async def combo_cancel(self) -> dict:

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/python/godot_cli_control/daemon.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import signal
@@ -363,6 +364,46 @@ class Daemon:
         _reap_if_dead(pid)  # 回收被 SIGKILL 的 zombie 子进程（若它是本进程的孩子）
 
 
+# ── 项目级配置 ──
+
+
+def read_project_config(project_root: Path | None = None) -> dict:
+    """读取项目级 ``<project_root>/.cli_control/config.json``（issue #44）。
+
+    存放无需每次手敲的默认值，目前支持 ``idle_timeout``（如 ``{"idle_timeout":"30m"}``）。
+    ``project_root`` 默认 ``Path.cwd()``。缺文件 / 非法 JSON / 顶层非对象一律返回
+    ``{}``——配置坏掉绝不能让 daemon 起不来，缺省即回到「无配置」行为。
+    """
+    root = Path(project_root) if project_root is not None else Path.cwd()
+    path = root / ".cli_control" / "config.json"
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+# ── 端口发现 ──
+
+
+def discover_port(project_root: Path | None = None) -> int | None:
+    """从 ``<project_root>/.cli_control/port`` 读取 daemon 当前监听端口。
+
+    daemon 默认以 OS 自动分配端口启动（写入 ``.cli_control/port``），所以"无显式
+    端口"的连接方都得先来这里发现实际端口，再回退 ``DEFAULT_PORT``。这是 CLI RPC
+    子命令、``GameClient()`` 与 ``GameBridge()`` 三处无显式 port 时的**唯一共用**
+    发现入口（issue #91）——与 README 承诺的 "auto-discover from ``.cli_control/port``"
+    对齐。
+
+    ``project_root`` 默认 ``Path.cwd()``（与 CLI 的工作目录约定一致）。无 port 文件
+    或解析失败时返回 ``None``，由调用方决定回退值。
+    """
+    root = Path(project_root) if project_root is not None else Path.cwd()
+    return Daemon(root).current_port()
+
+
 # ── Godot 二进制发现 ──
 
 

{godot_cli_control-0.2.12 → godot_cli_control-0.2.13}/python/godot_cli_control/templates/skill/SKILL.md

@@ -14,7 +14,7 @@ WebSocket bridge for headless / scripted control of Godot 4 scenes. A daemon pro
 **Output is JSON by default.** Every RPC subcommand prints a single-line envelope on stdout:
 
 - success: `{"ok": true, "result": <data>}` — exit 0 (or per-command exit code, see *Exit codes* below)
-- error:   `{"ok": false, "error": {"code": <int>, "message": "..."}}` — exit 1 (RPC error) / 2 (connection, timeout, usage)
+- error:   `{"ok": false, "error": {"code": <int>, "message": "..."}}` — exit 1 (RPC error) / 2 (connection, timeout) / 64 (usage)
 
 Pipe straight into `jq` or `json.loads`. Add `--text` (or `--no-json`) to switch back to the legacy human-readable strings if you really want them.
 
@@ -44,9 +44,9 @@ 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, 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. |
+| 2 | Connection / IO error (daemon not running, 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 |
+| 64 | Usage error on an **RPC subcommand** — argparse, a pre-flight reject caught before connecting (`combo` with no steps / malformed `--steps-json` / `combo -` from a TTY, `hold` with a non-positive duration), **and** a bad runtime argument (`tap` / `wait-time` given a non-number, a `set`/`call` value that fails JSON parsing). For RPC subcommands these all carry client code `-1003` and now consistently exit 64 (a few previously exited 2 — fixed in #82). |
 
 Shell-`if` works:
 
@@ -128,7 +128,7 @@ Three numeric ranges cohabit in `error.code`. Knowing which is which lets you de
 |---|---|
 | `-1001` | Connection failure (daemon not running, port wrong, proxy hijacking localhost). Run `daemon status`. |
 | `-1002` | Timeout waiting for a response. Daemon may be hung mid-frame; check Godot stderr. |
-| `-1003` | Usage error (e.g. `combo` got no steps, malformed `--steps-json`, `combo -` from a TTY). Fix the invocation. |
+| `-1003` | Usage error (`combo` got no steps, malformed `--steps-json`, `combo -` from a TTY, a non-numeric `tap`/`wait-time` arg, **or** a `set`/`call` value that fails JSON parsing). From an RPC subcommand this always exits **64**. (Top-level `run`/`daemon` precondition failures — e.g. script path not found, daemon failed to start — also surface `-1003` but exit **2**.) Fix the invocation. |
 | `-1004` | Local file IO error (e.g. `screenshot` can't write the destination — bad path, no write permission). **Not** a daemon problem. |
 | `-1005` | `run <script>` user script raised an uncaught exception. The error message has the exception type + last-line summary; full traceback is on stderr. Fix the script, not the CLI. |
 | `-1099` | Internal client error (unforeseen exception). Bug in this CLI; please file an issue. Stderr has the full traceback. |
@@ -154,12 +154,14 @@ 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 (`duration` must be `> 0`; for an indefinite hold use `press`)
-- `combo --steps-json '[...]'` (or `combo file.json` / `combo -` for stdin) — sequence
+- `tap <action> [duration] [--wait]` — press → wait → release
+- `hold <action> <duration> [--wait]` — auto-release after N seconds (`duration` must be `> 0`; for an indefinite hold use `press`)
+- `combo --steps-json '[...]' [--wait]` (or `combo file.json` / `combo -` for stdin) — sequence
 - `combo-cancel` — abort running combo
 - `release-all` — release everything
 
+`tap` / `hold` / `combo` are **async by default** — they return as soon as the input is armed, *before* the in-game motion finishes (see *Common pitfalls*). Add **`--wait`** to block until the action's duration elapses (game-time) so the next `get` reads the settled state — it folds an implicit `wait-time <duration>` into the same command/connection.
+
 **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`). Server bounds: `0 ≤ seconds ≤ 3600`; passing out-of-range gets `-32602 "seconds must be ..."`. Client short-circuits `seconds <= 0` without an RPC.
@@ -288,6 +290,9 @@ Key constraints:
 - `ffmpeg` must be on `PATH` for transcoding. If transcoding fails, the raw `.avi` is kept and `daemon stop` exits with code `2` (transcode log at `.cli_control/ffmpeg.log`).
 - `--fps` controls the **fixed simulation framerate** Godot runs at while recording — set it to your target video framerate.
 - Output path is relative to cwd; use absolute paths if your script changes cwd.
+- Long `wait-time` / `combo` / recording ops are bounded client-side by a fixed **600s** wall-time fail-safe (not a per-call timeout — game-time vs wall-time can't be predicted). A genuinely long operation (e.g. a > 10-minute recording) that trips it can raise the ceiling via `GODOT_CLI_LONG_OP_TIMEOUT=<seconds>` (e.g. `1800`); a non-positive / non-numeric value is ignored and falls back to 600s.
+
+**Project-level defaults** (`.cli_control/config.json`, optional): set `{"idle_timeout": "30m"}` so `daemon start` / `run` auto-quit after idle without re-typing `--idle-timeout` every time. It's read only when you don't pass `--idle-timeout` (default `0`); an explicit flag wins. Bad JSON / a malformed duration there surfaces as a `-1003` usage error (exit 64).
 
 ## CLI reference
 
@@ -299,7 +304,7 @@ Key constraints:
 
 ## Python `GameClient` API
 
-`from godot_cli_control.client import GameClient` — async WebSocket client; use as `async with GameClient(port=...) as client:`. **Every method below has a 1-line CLI equivalent above; only reach for Python when you need to keep a client open across many steps without the connection-per-call overhead.**
+`from godot_cli_control.client import GameClient` — async WebSocket client; use as `async with GameClient() as client:`. **With no `port` argument it auto-discovers from `.cli_control/port`** (the same file the daemon writes and the CLI reads), falling back to `9877` if absent — so a no-arg `GameClient()` connects to a running daemon out of the box. Pass `GameClient(port=N)` only to override. (`GameBridge()` in `run` scripts auto-discovers identically.) **Every method below has a 1-line CLI equivalent above; only reach for Python when you need to keep a client open across many steps without the connection-per-call overhead.**
 
 Errors raise `RpcError(code, message)` (a `RuntimeError` subclass) that preserves the server's error code — useful for retrying `1004 "combo in progress"`.
 
@@ -394,6 +399,7 @@ pytest_plugins = ["godot_cli_control.pytest_plugin"]
   - `daemon start --port N`: the port the daemon itself listens on. This is a local flag of `start`, so — like any other `daemon` flag — its position doesn't matter.
 - **`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.)
+- **`hold` / `tap` / `combo` return *before* the motion finishes — use `--wait` (or `wait-time`) before reading state.** These input commands are asynchronous: `hold move_right 1.0` returns in ~0.4s (it just arms a release-timer in the daemon), but the character keeps moving for the full `1.0` in-game second. If you `get position` immediately you read a *mid-motion* value (e.g. `x=415` instead of the settled `x=540`). Two fixes: ① pass **`--wait`** (`hold move_right 1.0 --wait` blocks until the duration elapses, then `get … position` reads the settled value) — one command, one connection; ② or do it explicitly: `hold move_right 1.0` → `wait-time 1.0` → `get … position`. `--wait` works on `tap` (default `0.1`s) and `combo` (waits the summed step durations) too. Either way, also account for any physics/animation that plays out over extra frames after the input lands.
 - **`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.