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

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

@@ -1,10 +1,29 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.12
+Version: 0.2.14
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
+Project-URL: Homepage, https://github.com/ClaymanTwinkle/godot-cli-control
+Project-URL: Repository, https://github.com/ClaymanTwinkle/godot-cli-control
+Project-URL: Documentation, https://github.com/ClaymanTwinkle/godot-cli-control#readme
+Project-URL: Changelog, https://github.com/ClaymanTwinkle/godot-cli-control/blob/main/addons/godot_cli_control/CHANGELOG.md
+Project-URL: Issues, https://github.com/ClaymanTwinkle/godot-cli-control/issues
 Author: kesar
 License: MIT
 License-File: LICENSE
+Keywords: ai-agent,automation,cli,game-testing,gdscript,godot,godot-plugin,godot4,headless,json-rpc,llm,pytest,screenshot,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.10
 Requires-Dist: websockets<16,>=14
 Provides-Extra: pytest
@@ -13,6 +32,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
@@ -25,7 +45,7 @@ WebSocket bridge for headless / scripted control of Godot 4 scenes — Python cl
 pipx install godot-cli-control
 
 # or, for unreleased main:
-pipx install "git+https://github.com/ClaymanTwinkle/godot-cli-control.git#subdirectory=python"
+pipx install "git+https://github.com/ClaymanTwinkle/godot-cli-control.git"
 ```
 
 The wheel ships the Godot plugin source so the `init` command can drop it into your project.

{godot_cli_control-0.2.12 → godot_cli_control-0.2.14}/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.14/pyproject.toml

@@ -0,0 +1,151 @@
+[project]
+name = "godot-cli-control"
+dynamic = ["version"]
+description = "WebSocket bridge for headless / scripted control of Godot scenes."
+readme = "python/README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "kesar" }]
+# keywords / classifiers 仅供 PyPI 搜索与分类筛选；与 GitHub repo topics 对齐。
+# 改这里时顺手对一眼 README 顶部徽章 + repo About 的 topics，别让三处漂移。
+keywords = [
+    "godot",
+    "godot4",
+    "godot-plugin",
+    "gdscript",
+    "automation",
+    "game-testing",
+    "pytest",
+    "websocket",
+    "json-rpc",
+    "ai-agent",
+    "llm",
+    "screenshot",
+    "headless",
+    "cli",
+]
+classifiers = [
+    # README 自称 Alpha；升 Beta/Stable 时记得同步这里与 README 的 Status 段。
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    # Python 版本与 CI matrix（.github/workflows/ci.yml）保持一致：实测 3.10–3.13。
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Games/Entertainment",
+    # pytest11 entry-point 让它成为一个 pytest 插件 —— 这条 classifier 能把包
+    # 收进 PyPI 的 pytest-plugin 分类列表，是面向 pytest 用户的关键发现入口。
+    "Framework :: Pytest",
+]
+dependencies = [
+    "websockets>=14,<16",
+]
+
+[project.optional-dependencies]
+pytest = ["pytest>=7"]
+# 全套测试依赖 —— 仅 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"
+
+[project.entry-points.pytest11]
+godot-cli-control = "godot_cli_control.pytest_plugin"
+
+# PyPI 项目页侧栏的链接全靠这张表（现在为空 = 侧栏只有一个 PyPI 自身链接）。
+# Changelog 指向 addon 内的 CHANGELOG（README「Status」段也引这份），别改成根目录。
+[project.urls]
+Homepage = "https://github.com/ClaymanTwinkle/godot-cli-control"
+Repository = "https://github.com/ClaymanTwinkle/godot-cli-control"
+Documentation = "https://github.com/ClaymanTwinkle/godot-cli-control#readme"
+Changelog = "https://github.com/ClaymanTwinkle/godot-cli-control/blob/main/addons/godot_cli_control/CHANGELOG.md"
+Issues = "https://github.com/ClaymanTwinkle/godot-cli-control/issues"
+
+[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 检测 / 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"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "python/godot_cli_control/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/godot_cli_control"]
+
+# 把 GDScript 插件嵌进 wheel，让 `godot-cli-control init` 能从安装包里把 plugin
+# 复制到目标 Godot 项目。位置 _plugin/ 与 init_cmd.locate_plugin_source() 的查找逻辑约定。
+[tool.hatch.build.targets.wheel.force-include]
+"addons/godot_cli_control" = "godot_cli_control/_plugin"
+
+# sdist 只装构建 wheel 必需的物料；docs/、仓库根 README 不进 sdist。
+[tool.hatch.build.targets.sdist]
+include = [
+    "/python/godot_cli_control",
+    "/python/tests",
+    "/python/README.md",
+    "/addons/godot_cli_control",
+    "/LICENSE",
+]
+
+# ── 覆盖率 ──────────────────────────────────────────────────────────────
+# 用 `coverage run -m pytest` 启动（不是 `pytest --cov`）—— pytest 启动时
+# pytest11 entry-point 会自动加载 godot_cli_control.pytest_plugin，进而 import
+# bridge/daemon/client；如果用 pytest-cov 那是先 pytest 后 cov，import-time 语句
+# 全部 miss。`coverage run` 在 Python 启动时就开 trace，避开这个时序坑。
+[tool.coverage.run]
+source = ["godot_cli_control"]
+branch = true
+omit = [
+    "*/_version.py",            # hatch-vcs 生成的版本字符串，无逻辑
+    "*/__main__.py",             # `python -m godot_cli_control` 入口，靠 walkthrough 覆盖
+    "*/templates/*",             # init 命令复制出去的模板，由 walkthrough 测
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]
+# 80% 是当前 Python 源码大致能稳定到的水准（cli.py 很大但既有测试良好）。
+# 调高的话先在本地 `coverage report --fail-under=N` 验过再改。
+fail_under = 80

{godot_cli_control-0.2.12 → godot_cli_control-0.2.14}/python/README.md

@@ -8,7 +8,7 @@ WebSocket bridge for headless / scripted control of Godot 4 scenes — Python cl
 pipx install godot-cli-control
 
 # or, for unreleased main:
-pipx install "git+https://github.com/ClaymanTwinkle/godot-cli-control.git#subdirectory=python"
+pipx install "git+https://github.com/ClaymanTwinkle/godot-cli-control.git"
 ```
 
 The wheel ships the Godot plugin source so the `init` command can drop it into your project.

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

{godot_cli_control-0.2.12 → godot_cli_control-0.2.14}/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.14}/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.14}/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: