godot-cli-control 0.1.0__tar.gz

godot_cli_control-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+
+# Godot
+.godot/
+*.import
+*.translation
+export.cfg
+export_presets.cfg
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# CLI control runtime
+.cli_control/

godot_cli_control-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kesar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

godot_cli_control-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: godot-cli-control
+Version: 0.1.0
+Summary: WebSocket bridge for headless / scripted control of Godot scenes.
+Author: kesar
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: websockets<16,>=14
+Description-Content-Type: text/markdown
+
+# godot-cli-control
+
+WebSocket bridge for headless / scripted control of Godot 4 scenes — Python client.
+
+## Install
+
+```bash
+pip install godot-cli-control
+```
+
+Requires Python ≥ 3.10. Companion Godot plugin must be installed and enabled in your Godot project (see [the plugin README](https://github.com/kesar/godot-2d-skeleton/blob/main/addons/godot_cli_control/README.md) for setup).
+
+## Usage
+
+```python
+import asyncio
+from godot_cli_control import GameClient
+
+async def main():
+    async with GameClient(port=9877) as client:
+        # Inspect scene
+        tree = await client.get_scene_tree(depth=3)
+        print(tree)
+
+        # Interact
+        await client.click("/root/MyScene/Button")
+        await client.action_press("jump")
+        await client.wait_game_time(0.5)
+        await client.action_release("jump")
+
+        # Capture
+        png_bytes = await client.screenshot()
+        open("frame.png", "wb").write(png_bytes)
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+python -m godot_cli_control tree 3
+python -m godot_cli_control click /root/MyScene/Button
+python -m godot_cli_control screenshot /tmp/frame.png
+```
+
+## Documentation
+
+See the [Godot plugin README](https://github.com/kesar/godot-2d-skeleton/blob/main/addons/godot_cli_control/README.md) for the full RPC reference, activation modes, security model, and known limitations.

godot_cli_control-0.1.0/README.md

@@ -0,0 +1,48 @@
+# godot-cli-control
+
+WebSocket bridge for headless / scripted control of Godot 4 scenes — Python client.
+
+## Install
+
+```bash
+pip install godot-cli-control
+```
+
+Requires Python ≥ 3.10. Companion Godot plugin must be installed and enabled in your Godot project (see [the plugin README](https://github.com/kesar/godot-2d-skeleton/blob/main/addons/godot_cli_control/README.md) for setup).
+
+## Usage
+
+```python
+import asyncio
+from godot_cli_control import GameClient
+
+async def main():
+    async with GameClient(port=9877) as client:
+        # Inspect scene
+        tree = await client.get_scene_tree(depth=3)
+        print(tree)
+
+        # Interact
+        await client.click("/root/MyScene/Button")
+        await client.action_press("jump")
+        await client.wait_game_time(0.5)
+        await client.action_release("jump")
+
+        # Capture
+        png_bytes = await client.screenshot()
+        open("frame.png", "wb").write(png_bytes)
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+python -m godot_cli_control tree 3
+python -m godot_cli_control click /root/MyScene/Button
+python -m godot_cli_control screenshot /tmp/frame.png
+```
+
+## Documentation
+
+See the [Godot plugin README](https://github.com/kesar/godot-2d-skeleton/blob/main/addons/godot_cli_control/README.md) for the full RPC reference, activation modes, security model, and known limitations.

godot_cli_control-0.1.0/godot_cli_control/__init__.py

@@ -0,0 +1,6 @@
+"""Godot CLI Control — WebSocket bridge for headless / scripted control of Godot scenes."""
+
+from godot_cli_control.client import GameClient
+
+__all__ = ["GameClient"]
+__version__ = "0.1.0"

godot_cli_control-0.1.0/godot_cli_control/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python3 -m godot_cli_control <command> [args...]"""
+
+from .cli import main
+
+main()

godot_cli_control-0.1.0/godot_cli_control/bridge.py

@@ -0,0 +1,129 @@
+"""同步 Bridge —— 封装 GameClient，让 Python 脚本只需写操作逻辑。
+
+用法：脚本只需定义 run(bridge) 函数即可。
+
+    def run(bridge):
+        bridge.click("/root/MainMenu/.../NewGameButton")
+        bridge.wait(2)
+        bridge.hold("move_right", 1.5)
+        bridge.press("attack_melee")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from .client import GameClient
+
+
+class GameBridge:
+    """同步接口，内部通过事件循环调用异步 GameClient。"""
+
+    def __init__(self, port: int = 9877) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._client = GameClient(port=port)
+        self._loop.run_until_complete(
+            self._client.connect(retries=15, backoff=1.0)
+        )
+
+    def close(self) -> None:
+        self._loop.run_until_complete(self._client.disconnect())
+        self._loop.close()
+
+    def _run(self, coro: Any) -> Any:
+        return self._loop.run_until_complete(coro)
+
+    # ── 等待 ──
+
+    def wait(self, seconds: float) -> None:
+        """按 Godot game time 等待指定秒数。
+
+        在 --write-movie 模式下，此方法等待的是 game time（录像帧数基准），
+        而非 wall time，确保录像内容与脚本期望对齐。
+        """
+        self._run(self._client.wait_game_time(seconds))
+
+    # ── 场景树 ──
+
+    def tree(self, depth: int = 3) -> dict:
+        """获取场景树。"""
+        return self._run(self._client.get_scene_tree(depth=depth))
+
+    def node_exists(self, path: str) -> bool:
+        """检查节点是否存在。"""
+        return self._run(self._client.node_exists(path))
+
+    def wait_for_node(self, path: str, timeout: float = 5.0) -> bool:
+        """等待节点出现。"""
+        return self._run(self._client.wait_for_node(path, timeout=timeout))
+
+    # ── UI 交互 ──
+
+    def click(self, path: str) -> dict:
+        """点击 UI 节点。"""
+        return self._run(self._client.click(path))
+
+    # ── 输入模拟 ──
+
+    def press(self, action: str) -> None:
+        """按下并释放一个动作。"""
+        self._run(self._client.action_tap(action, 0.1))
+
+    def hold(self, action: str, duration: float) -> None:
+        """按住一个动作指定时长。"""
+        self._run(self._client.hold(action, duration))
+
+    def tap(self, action: str, duration: float = 0.1) -> None:
+        """快速点按。"""
+        self._run(self._client.action_tap(action, duration))
+
+    def move(self, x: float, y: float, duration: float) -> None:
+        """方向移动。"""
+        self._run(self._client.move(x, y, duration))
+
+    def action_press(self, action: str) -> None:
+        """按下动作（不释放，需手动 release）。"""
+        self._run(self._client.action_press(action))
+
+    def action_release(self, action: str) -> None:
+        """释放动作。"""
+        self._run(self._client.action_release(action))
+
+    def release_all(self) -> None:
+        """释放所有按住的动作。"""
+        self._run(self._client.release_all())
+
+    def combo(self, steps: list[dict]) -> dict:
+        """执行连续动作序列。"""
+        return self._run(self._client.combo(steps))
+
+    # ── 截图 ──
+
+    def screenshot(self, path: str | None = None) -> bytes:
+        """截图，返回 PNG 字节。可选保存到文件。"""
+        data = self._run(self._client.screenshot())
+        if path:
+            p = Path(path)
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_bytes(data)
+        return data
+
+    # ── 属性读写 ──
+
+    def get_property(self, path: str, prop: str) -> Any:
+        """获取节点属性。"""
+        return self._run(self._client.get_property(path, prop))
+
+    def set_property(self, path: str, prop: str, value: Any) -> None:
+        """设置节点属性。"""
+        self._run(self._client.set_property(path, prop, value))
+
+    def call_method(self, path: str, method: str, args: list | None = None) -> Any:
+        """调用节点方法。"""
+        return self._run(self._client.call_method(path, method, args))
+
+    def get_children(self, path: str, type_filter: str = "") -> list[dict]:
+        """获取子节点列表。"""
+        return self._run(self._client.get_children(path, type_filter=type_filter))

godot_cli_control-0.1.0/godot_cli_control/cli.py

@@ -0,0 +1,158 @@
+"""CLI commands for one-off GameClient operations.
+
+Usage:
+    python3 -m godot_cli_control click <node_path>
+    python3 -m godot_cli_control screenshot [output.png]
+    python3 -m godot_cli_control tree [depth]
+    python3 -m godot_cli_control press <action_name>
+    python3 -m godot_cli_control hold <action_name> <duration>
+    python3 -m godot_cli_control combo <sequence.json>
+
+<action_name> 依赖目标工程的 InputMap；<node_path> 形如
+/root/<Scene>/... 由 `tree` 查出。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import sys
+from collections.abc import Callable, Coroutine
+from pathlib import Path
+from typing import Any
+
+from .client import GameClient
+
+DEFAULT_PORT: int = 9877
+
+
+async def cmd_click(client: GameClient, args: list[str]) -> None:
+    if not args:
+        print("Usage: click <node_path>", file=sys.stderr)
+        sys.exit(1)
+    result = await client.click(args[0])
+    print(f"clicked: {result}")
+
+
+async def cmd_screenshot(client: GameClient, args: list[str]) -> None:
+    data = await client.screenshot()
+    if args:
+        output = Path(args[0])
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(data)
+        print(f"screenshot saved: {output} ({len(data)} bytes)")
+    else:
+        print(base64.b64encode(data).decode())
+
+
+async def cmd_tree(client: GameClient, args: list[str]) -> None:
+    depth = int(args[0]) if args else 3
+    tree = await client.get_scene_tree(depth=depth)
+    print(json.dumps(tree, indent=2, ensure_ascii=False))
+
+
+async def cmd_press(client: GameClient, args: list[str]) -> None:
+    if not args:
+        print("Usage: press <action>", file=sys.stderr)
+        sys.exit(1)
+    result = await client.action_press(args[0])
+    print(f"pressed: {result}")
+
+
+async def cmd_release(client: GameClient, args: list[str]) -> None:
+    if not args:
+        print("Usage: release <action>", file=sys.stderr)
+        sys.exit(1)
+    result = await client.action_release(args[0])
+    print(f"released: {result}")
+
+
+async def cmd_tap(client: GameClient, args: list[str]) -> None:
+    if not args:
+        print("Usage: tap <action> [duration]", file=sys.stderr)
+        sys.exit(1)
+    duration = float(args[1]) if len(args) > 1 else 0.1
+    result = await client.action_tap(args[0], duration)
+    print(f"tapped: {result}")
+
+
+async def cmd_hold(client: GameClient, args: list[str]) -> None:
+    if len(args) < 2:
+        print("Usage: hold <action> <duration>", file=sys.stderr)
+        sys.exit(1)
+    result = await client.hold(args[0], float(args[1]))
+    print(f"holding: {result}")
+
+
+async def cmd_move(client: GameClient, args: list[str]) -> None:
+    if len(args) < 3:
+        print("Usage: move <x> <y> <duration>", file=sys.stderr)
+        sys.exit(1)
+    result = await client.move(float(args[0]), float(args[1]), float(args[2]))
+    print(f"moving: {result}")
+
+
+async def cmd_combo(client: GameClient, args: list[str]) -> None:
+    if not args:
+        print("Usage: combo <json_file>", file=sys.stderr)
+        sys.exit(1)
+    steps = json.loads(Path(args[0]).read_text())
+    if isinstance(steps, dict):
+        steps = steps.get("steps", [])
+    result = await client.combo(steps)
+    print(f"combo done: {result}")
+
+
+async def cmd_release_all(client: GameClient, _args: list[str]) -> None:
+    result = await client.release_all()
+    print(f"released all: {result}")
+
+
+COMMANDS: dict[
+    str, Callable[[GameClient, list[str]], Coroutine[Any, Any, None]]
+] = {
+    "click": cmd_click,
+    "screenshot": cmd_screenshot,
+    "tree": cmd_tree,
+    "press": cmd_press,
+    "release": cmd_release,
+    "tap": cmd_tap,
+    "hold": cmd_hold,
+    "move": cmd_move,
+    "combo": cmd_combo,
+    "release-all": cmd_release_all,
+}
+
+
+def main() -> None:
+    args: list[str] = sys.argv[1:]
+    port: int = DEFAULT_PORT
+
+    if "--port" in args:
+        idx = args.index("--port")
+        if idx + 1 >= len(args):
+            print("Error: --port requires a value", file=sys.stderr)
+            sys.exit(1)
+        port = int(args[idx + 1])
+        args = args[:idx] + args[idx + 2 :]
+
+    if not args or args[0] not in COMMANDS:
+        cmds = ", ".join(COMMANDS.keys())
+        print(
+            f"Usage: python3 -m godot_cli_control [--port N] <{cmds}> [args...]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    cmd = args[0]
+
+    async def run() -> None:
+        async with GameClient(port=port) as client:
+            await COMMANDS[cmd](client, args[1:])
+
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

godot_cli_control-0.1.0/godot_cli_control/client.py

@@ -0,0 +1,246 @@
+"""GameClient - WebSocket client for connecting to Godot GameBridge."""
+
+import asyncio
+import base64
+import json
+import logging
+import uuid
+from typing import Any
+
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+logger = logging.getLogger(__name__)
+
+
+class GameClient:
+    """WebSocket client that connects to Godot's GameBridge service."""
+
+    def __init__(self, port: int = 9877) -> None:
+        self._port = port
+        self._ws: ClientConnection | None = None
+        self._pending: dict[str, asyncio.Future[dict]] = {}
+        self._listen_task: asyncio.Task | None = None
+
+    async def __aenter__(self) -> "GameClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.disconnect()
+
+    async def connect(
+        self, retries: int = 10, backoff: float = 1.0, max_wait: float = 3.0
+    ) -> None:
+        """Connect to GameBridge with exponential backoff retry.
+
+        显式 ``proxy=None``：GameBridge 永远跑在 localhost，而 websockets>=14
+        会自动读取 ``all_proxy``/``http_proxy``/``https_proxy`` 环境变量并把
+        localhost 连接也塞进 SOCKS/HTTP 代理，导致 TCP 被代理立刻 EOF、
+        抛 ``InvalidMessage: did not receive a valid HTTP response``。用户
+        shell 里的 ``all_proxy=socks5://127.0.0.1:7897`` 就是典型触发点；
+        显式传 ``proxy=None`` 比依赖 ``no_proxy`` 顺序更稳（no_proxy 对
+        localhost 的匹配规则各库不一致）。
+        """
+        for attempt in range(retries):
+            try:
+                self._ws = await websockets.connect(
+                    f"ws://localhost:{self._port}",
+                    proxy=None,
+                )
+                self._listen_task = asyncio.create_task(self._listen())
+                logger.info("Connected to GameBridge on port %d", self._port)
+                return
+            except (
+                ConnectionRefusedError,
+                OSError,
+                websockets.exceptions.InvalidMessage,
+            ) as e:
+                if attempt < retries - 1:
+                    wait = min(backoff * (2**attempt), max_wait)
+                    logger.warning(
+                        "Connection attempt %d failed: %s. Retrying in %.1fs...",
+                        attempt + 1, e, wait,
+                    )
+                    await asyncio.sleep(wait)
+                else:
+                    raise ConnectionError(
+                        f"Failed to connect after {retries} attempts"
+                    ) from e
+
+    async def disconnect(self) -> None:
+        """Disconnect from GameBridge."""
+        if self._listen_task:
+            self._listen_task.cancel()
+            try:
+                await self._listen_task
+            except asyncio.CancelledError:
+                pass
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+        logger.info("Disconnected from GameBridge")
+
+    async def _listen(self) -> None:
+        """Background task that listens for messages from GameBridge.
+
+        finally 里清空所有 pending future —— 涵盖 ConnectionClosed、
+        CancelledError 以及任何其它退出路径，防止调用方的 await 在
+        connection 消失后挂死到超时。
+        """
+        assert self._ws is not None
+        close_reason: str | None = None
+        try:
+            async for raw in self._ws:
+                msg = json.loads(raw)
+                if "id" in msg:
+                    req_id = msg["id"]
+                    if req_id in self._pending:
+                        self._pending[req_id].set_result(msg)
+                        del self._pending[req_id]
+        except websockets.ConnectionClosed:
+            close_reason = "Connection closed by server"
+            logger.info(close_reason)
+        finally:
+            reason = close_reason or "listen task stopped"
+            for future in self._pending.values():
+                if not future.done():
+                    future.set_exception(ConnectionError(reason))
+            self._pending.clear()
+
+    async def request(
+        self, method: str, params: dict | None = None, timeout: float = 30.0
+    ) -> dict:
+        """Send a JSON-RPC request and wait for the response."""
+        assert self._ws is not None, "Not connected"
+        req_id = str(uuid.uuid4())[:8]
+        msg = {"id": req_id, "method": method, "params": params or {}}
+        future: asyncio.Future[dict] = asyncio.get_running_loop().create_future()
+        self._pending[req_id] = future
+        await self._ws.send(json.dumps(msg))
+        try:
+            response = await asyncio.wait_for(future, timeout=timeout)
+        except asyncio.TimeoutError:
+            self._pending.pop(req_id, None)
+            raise
+        if "error" in response:
+            raise RuntimeError(
+                f"GameBridge error: {response['error']['message']}"
+            )
+        return response.get("result", {})
+
+    # ---- Low-level API ----
+
+    async def click(self, path: str) -> dict:
+        return await self.request("click", {"path": path})
+
+    async def get_property(self, path: str, prop: str) -> Any:
+        result = await self.request(
+            "get_property", {"path": path, "property": prop}
+        )
+        return result.get("value")
+
+    async def set_property(self, path: str, prop: str, value: Any) -> dict:
+        return await self.request(
+            "set_property", {"path": path, "property": prop, "value": value}
+        )
+
+    async def call_method(
+        self, path: str, method: str, args: list | None = None
+    ) -> Any:
+        result = await self.request(
+            "call_method",
+            {"path": path, "method": method, "args": args or []},
+        )
+        return result.get("result")
+
+    async def get_text(self, path: str) -> str:
+        result = await self.request("get_text", {"path": path})
+        return result.get("text", "")
+
+    async def node_exists(self, path: str) -> bool:
+        result = await self.request("node_exists", {"path": path})
+        return result.get("exists", False)
+
+    async def is_visible(self, path: str) -> bool:
+        result = await self.request("is_visible", {"path": path})
+        return result.get("visible", False)
+
+    async def get_children(
+        self, path: str, type_filter: str = ""
+    ) -> list[dict]:
+        result = await self.request(
+            "get_children", {"path": path, "type_filter": type_filter}
+        )
+        return result.get("children", [])
+
+    async def screenshot(self) -> bytes:
+        """Take a screenshot and return PNG bytes."""
+        result = await self.request("screenshot")
+        return base64.b64decode(result.get("image", ""))
+
+    async def get_scene_tree(self, depth: int = 5) -> dict:
+        return await self.request("get_scene_tree", {"depth": depth})
+
+    async def wait_for_node(self, path: str, timeout: float = 5.0) -> bool:
+        result = await self.request(
+            "wait_for_node",
+            {"path": path, "timeout": timeout},
+            timeout=timeout + 5.0,
+        )
+        return result.get("found", False)
+
+    async def wait_game_time(self, seconds: float) -> dict:
+        """按 Godot game time 等待 N 秒。
+
+        Movie Maker (--write-movie) 模式下 wall time 比 game time 慢约 2-3×，
+        客户端 timeout 用 seconds * 3 + 10 安全系数，与 combo() 一致。
+        seconds <= 0 时客户端短路返回，不发 RPC。
+        """
+        if seconds <= 0:
+            return {"success": True}
+        return await self.request(
+            "wait_game_time",
+            {"seconds": seconds},
+            timeout=seconds * 3.0 + 10.0,
+        )
+
+    # ---- Input simulation API ----
+
+    async def action_press(self, action: str) -> dict:
+        return await self.request("input_action_press", {"action": action})
+
+    async def action_release(self, action: str) -> dict:
+        return await self.request("input_action_release", {"action": action})
+
+    async def action_tap(self, action: str, duration: float = 0.1) -> dict:
+        return await self.request(
+            "input_action_tap", {"action": action, "duration": duration}
+        )
+
+    async def hold(self, action: str, duration: float) -> dict:
+        return await self.request(
+            "input_hold", {"action": action, "duration": duration}
+        )
+
+    async def move(self, x: float, y: float, duration: float) -> dict:
+        return await self.request(
+            "input_move", {"direction": {"x": x, "y": y}, "duration": duration}
+        )
+
+    async def combo(self, steps: list[dict]) -> dict:
+        total = sum(
+            s.get("duration", 0) or s.get("wait", 0) for s in steps
+        )
+        # movie maker (--write-movie) 模式下 Godot 渲染比实时慢（大分辨率 +
+        # MJPEG 编码开销），客户端墙钟等待需要 3× 安全系数 + 10s base，
+        # 避免 combo 还没在游戏时间跑完就被 TimeoutError 打断。
+        return await self.request(
+            "input_combo", {"steps": steps}, timeout=total * 3.0 + 10.0
+        )
+
+    async def combo_cancel(self) -> dict:
+        return await self.request("input_combo_cancel")
+
+    async def release_all(self) -> dict:
+        return await self.request("input_release_all")

godot_cli_control-0.1.0/godot_cli_control/runner.py

@@ -0,0 +1,61 @@
+"""脚本运行器 —— 加载用户脚本并注入 GameBridge。
+
+用法: python3 -m godot_cli_control.runner <script.py> [args...]
+
+用户脚本只需定义 run(bridge) 函数：
+
+    def run(bridge):
+        bridge.click("/root/MainMenu/.../NewGameButton")
+        bridge.wait(2)
+        bridge.hold("move_right", 1.5)
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+from .bridge import GameBridge
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("用法: python3 -m godot_cli_control.runner <script.py> [args...]", file=sys.stderr)
+        sys.exit(1)
+
+    script_path = Path(sys.argv[1])
+    if not script_path.exists():
+        print(f"错误：找不到脚本: {script_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # 解析 --port 参数
+    port = 9877
+    args = sys.argv[2:]
+    if "--port" in args:
+        idx = args.index("--port")
+        port = int(args[idx + 1])
+        args = args[:idx] + args[idx + 2:]
+
+    # 动态加载用户脚本
+    spec = importlib.util.spec_from_file_location("user_script", script_path)
+    if spec is None or spec.loader is None:
+        print(f"错误：无法加载脚本: {script_path}", file=sys.stderr)
+        sys.exit(1)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    if not hasattr(module, "run"):
+        print(f"错误：脚本 {script_path} 中缺少 run(bridge) 函数", file=sys.stderr)
+        sys.exit(1)
+
+    # 创建 bridge 并执行
+    bridge = GameBridge(port=port)
+    try:
+        module.run(bridge)
+    finally:
+        bridge.close()
+
+
+if __name__ == "__main__":
+    main()

godot_cli_control-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "godot-cli-control"
+version = "0.1.0"
+description = "WebSocket bridge for headless / scripted control of Godot scenes."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "kesar" }]
+dependencies = [
+    "websockets>=14,<16",
+]
+
+[project.scripts]
+godot-cli-control = "godot_cli_control.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["godot_cli_control"]

godot_cli_control-0.1.0/tests/test_client.py

@@ -0,0 +1,162 @@
+"""L2 单元测试：覆盖 GameClient 的网络异常路径（L1 dogfooding 测不到的）。"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from unittest.mock import AsyncMock, patch
+
+import pytest
+import websockets
+
+from godot_cli_control.client import GameClient
+
+
+# ---- Test 1: proxy=None 显式传给 websockets.connect ----
+
+@pytest.mark.asyncio
+async def test_connect_passes_proxy_none_explicitly() -> None:
+    """SOCKS 代理防御：connect() 必须显式传 proxy=None。
+
+    防 regression：未来 maintainer 改回 default 会让 all_proxy=socks5://...
+    用户的 localhost 连接被代理拦截，client.py docstring 写过这个坑。
+    """
+    fake_ws = AsyncMock()
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(return_value=fake_ws),
+    ) as mock_connect:
+        client = GameClient(port=9999)
+        try:
+            await client.connect(retries=1)
+        finally:
+            # 防 listen task 泄漏
+            if client._listen_task:
+                client._listen_task.cancel()
+        # 断言 connect 被调用且 proxy=None 在 kwargs 中
+        assert mock_connect.called
+        _, kwargs = mock_connect.call_args
+        assert kwargs.get("proxy") is None, \
+            "GameClient.connect() must pass proxy=None to websockets.connect"
+
+
+# ---- Test 2: connect retry 行为 ----
+
+@pytest.mark.asyncio
+async def test_connect_retries_on_connection_refused() -> None:
+    """前 N 次 ConnectionRefused 后第 N+1 次成功 → connect() 应该返回成功。"""
+    fake_ws = AsyncMock()
+    side_effects = [ConnectionRefusedError("nope"), ConnectionRefusedError("nope"), fake_ws]
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(side_effect=side_effects),
+    ) as mock_connect:
+        client = GameClient(port=9999)
+        try:
+            await client.connect(retries=5, backoff=0.01, max_wait=0.01)
+        finally:
+            if client._listen_task:
+                client._listen_task.cancel()
+        assert mock_connect.call_count == 3
+
+
+# ---- Test 3: connect retry 全失败 → ConnectionError ----
+
+@pytest.mark.asyncio
+async def test_connect_raises_after_retries_exhausted() -> None:
+    """所有 retry 失败应该抛 ConnectionError（带原异常 from clause）。"""
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(side_effect=ConnectionRefusedError("always nope")),
+    ):
+        client = GameClient(port=9999)
+        with pytest.raises(ConnectionError, match="Failed to connect after"):
+            await client.connect(retries=2, backoff=0.01, max_wait=0.01)
+
+
+# ---- Test 4: _listen 退出时清空 pending futures（避免 await 挂死） ----
+
+@pytest.mark.asyncio
+async def test_listen_clears_pending_on_disconnect() -> None:
+    """_listen 退出（连接关闭）时所有 pending future 必须被 set_exception，
+    否则调用方的 await client.request() 会永久挂死到 timeout。"""
+    fake_ws = AsyncMock()
+
+    async def fake_iter():
+        # iterator 立即结束（模拟连接关闭）
+        return
+        yield  # noqa: unreachable
+
+    fake_ws.__aiter__ = lambda self: fake_iter()
+    fake_ws.close = AsyncMock()
+
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(return_value=fake_ws),
+    ):
+        client = GameClient(port=9999)
+        await client.connect(retries=1)
+
+        # 注入一个 pending future
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future = loop.create_future()
+        client._pending["fake_id"] = future
+
+        # 等 listen task 自然退出（iterator 已空）
+        if client._listen_task:
+            await client._listen_task
+
+        # pending 应该被清空 + future 应该被 set_exception
+        assert "fake_id" not in client._pending
+        assert future.done()
+        with pytest.raises(ConnectionError):
+            future.result()
+
+
+# ---- Test 5: request() timeout 时清理 _pending ----
+
+@pytest.mark.asyncio
+async def test_request_timeout_cleans_pending() -> None:
+    """request() 超时不应该在 _pending 里留垃圾 entry。"""
+    fake_ws = AsyncMock()
+
+    async def hang_iter():
+        # async iterator 永久挂起：不会 yield 也不会结束，
+        # 模拟"连接活着但不回响应"——request() 必定走 timeout 路径。
+        await asyncio.Event().wait()
+        yield  # noqa: unreachable
+
+    fake_ws.__aiter__ = lambda self: hang_iter()
+    fake_ws.send = AsyncMock()
+    fake_ws.close = AsyncMock()
+
+    with patch(
+        "godot_cli_control.client.websockets.connect",
+        new=AsyncMock(return_value=fake_ws),
+    ):
+        client = GameClient(port=9999)
+        await client.connect(retries=1)
+        try:
+            with pytest.raises(asyncio.TimeoutError):
+                await client.request("nonexistent_method", timeout=0.05)
+            # 超时后 _pending 应该不再含这次 request 的 id
+            assert len(client._pending) == 0
+        finally:
+            if client._listen_task:
+                client._listen_task.cancel()
+                try:
+                    await client._listen_task
+                except asyncio.CancelledError:
+                    pass
+
+
+# ---- Test 6（bonus）: websockets.connect 有 proxy kwarg（防版本退化） ----
+
+def test_websockets_connect_supports_proxy_kwarg() -> None:
+    """websockets>=14 才有 proxy= kwarg；如果版本退化测试就 fail。
+
+    spec §7.3 风险表 grounding：mock 写法依赖此 kwarg 存在。
+    """
+    sig = inspect.signature(websockets.connect)
+    assert "proxy" in sig.parameters, \
+        f"websockets.connect missing 'proxy' kwarg; version {websockets.__version__} too old"