godot-cli-control 0.2.17__tar.gz → 0.3.0__tar.gz

{godot_cli_control-0.2.17 → godot_cli_control-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.17
+Version: 0.3.0
 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
@@ -117,7 +117,19 @@ def test_jump(godot_daemon, bridge):
 ```
 
 - `godot_daemon` (session-scoped) starts headless Godot once and stops it after all tests; if a daemon is already running it's reused (and not stopped at teardown — keeps your IDE workflow alive).
-- `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it calls `release_all()` so a `hold` left behind by one case can't bleed into the next, then closes the connection.
+- `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it best-effort restores global engine state — `unpause()`, `time_scale` back to its setup-time snapshot, `release_all()` — so a `hold`/`pause`/speed-up left behind by one case can't bleed into the next, then closes the connection.
+- `fresh_scene` (function-scoped, opt-in) calls `scene_reload()` at setup so the case starts on a pristine scene. Node references cached before the reload are invalid afterwards.
+- `no_push_errors` (function-scoped, opt-in) records an `errors` marker at setup and fails the case if any new `push_error` was emitted during it (warnings don't fail). Requires Godot 4.5+ (Logger API) — older engines raise `RpcError` 1012 at setup, loudly.
+- `godot_instances` (scope configurable, default function) is a multi-instance factory for multiplayer e2e — start a named server **and** clients inside one test and get connected `GameBridge` objects back; teardown stops everything the fixture started (and only that):
+
+  ```python
+  def test_join(godot_instances):
+      server = godot_instances.start("server")
+      client = godot_instances.start("client1")
+  ```
+
+  `start(name)` is idempotent get-or-start (`headless`/`time_scale` follow the global options, overridable per call; `port` always defaults to 0 = OS-assigned); `stop(name)` stops one instance mid-test (restartable); `daemon(name)` exposes the underlying `Daemon`. `--godot-cli-instances-scope session` shares one set of instances across the whole suite (faster, no state isolation between tests).
+- On a test failure (non-headless daemon only) a best-effort screenshot is saved to `.cli_control/failures/<nodeid>.png` and the path is attached to the pytest report.
 
 CLI options:
 
@@ -125,6 +137,8 @@ CLI options:
 --godot-cli-port=N           # GameBridge port (default: read from .cli_control/port)
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
+--godot-cli-time-scale=X     # Engine.time_scale applied at daemon startup (e.g. 5 to speed up the suite)
+--godot-cli-instances-scope=function|session  # godot_instances fixture scope (default: function)
 ```
 
 ## CLI
@@ -139,17 +153,20 @@ godot-cli-control daemon start --record --movie-path X [--fps N]   # 录制需
 godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
 godot-cli-control daemon ls                  # list running daemons across all projects
+godot-cli-control daemon logs [--tail N]     # last N lines of .cli_control/godot.log (works post-mortem)
 godot-cli-control run <script.py> [--headless ...]
 
 # Read
 godot-cli-control tree [depth]
-godot-cli-control get      <node_path> <prop>
+godot-cli-control get      <node_path> <prop> [prop2 ...]   # multi-prop = atomic same-frame read
 godot-cli-control text     <node_path>
 godot-cli-control exists   <node_path>      # exit 0=true, 1=false, 2=infra
 godot-cli-control visible  <node_path>      # exit 0=true, 1=false, 2=infra
 godot-cli-control children <node_path> [type-filter]
 godot-cli-control pressed
 godot-cli-control actions [--all]
+godot-cli-control sprite-info <node_path>   # Sprite2D/AnimatedSprite2D/TextureRect render state in one call
+godot-cli-control errors [--since MARKER] [--limit N]   # structured push_error/push_warning log (Godot 4.5+)
 
 # Write / call
 godot-cli-control set   <node_path> <prop>   <json-value>
@@ -164,21 +181,33 @@ godot-cli-control combo --steps-json '[...]'   # or `combo file.json` / `combo -
 godot-cli-control combo-cancel
 godot-cli-control release-all
 
-# Wait
-godot-cli-control wait-node <node_path> [timeout]   # exit 0=found, 1=timeout
-godot-cli-control wait-time <seconds>
+# Wait (exit 0=hit, 1=timeout)
+godot-cli-control wait-node   <node_path> [timeout]
+godot-cli-control wait-prop   <node_path> <prop> <value> [--op gt|lt|ge|le|ne] [--timeout S] [--tolerance T]
+godot-cli-control wait-signal <node_path> <signal> [timeout]   # arm BEFORE triggering the action
+godot-cli-control wait-frames <n> [--physics]
+godot-cli-control wait-time <seconds>        # game time — scales with time-scale
+
+# Scene isolation
+godot-cli-control scene-reload [--timeout S]            # reload current scene, block until ready
+godot-cli-control scene-change <res://path.tscn>        # switch scene, block until ready
+
+# Time control
+godot-cli-control time-scale [value]         # read (no arg) or set Engine.time_scale, (0, 100]
+godot-cli-control pause | unpause
+godot-cli-control step-frames <n> [--physics]   # deterministic stepping while paused
 
 # Render (path is required as of 0.2.0)
-godot-cli-control screenshot <output.png>
+godot-cli-control screenshot <output.png> [--node <node_path>]   # --node crops to that node's screen rect
 ```
 
 ### Output contract
 
 - success: `{"ok": true, "result": <data>}` on stdout, exit 0
-- error:   `{"ok": false, "error": {"code": N, "message": "..."}}` on stdout, exit 1 (RPC) or 2 (connection / usage)
+- error:   `{"ok": false, "error": {"code": N, "message": "..."}}` on stdout, exit 1 (RPC), 2 (connection / infra), or 64 (usage)
 - `--text` / `--no-json` switches back to the legacy human-readable strings; errors then go to stderr.
 
-`exists` / `visible` / `wait-node` propagate their boolean result to the exit code, so shell `if` works:
+`exists` / `visible` and the `wait-*` commands propagate their boolean / hit-or-timeout result to the exit code, so shell `if` works:
 
 ```bash
 if godot-cli-control exists /root/Main/Boss; then

{godot_cli_control-0.2.17 → godot_cli_control-0.3.0}/addons/godot_cli_control/CHANGELOG.md

@@ -1,35 +1,167 @@
 # Changelog
 
+只记用户可感知的变更（feature / BREAKING / 行为修复）；纯 CI、内部重构、文档微调不入账，明细见 git log。
+版本由 git tag 派生（hatch-vcs）。发版时 `release.sh` 会校验本文件：`[Unreleased]` 非空时拒绝打 tag，
+加 `--roll-changelog` 自动把 `[Unreleased]` 滚动为新版本段（issue #140）。
+
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-07
+
+### Added
+- **同项目多实例（命名实例）**：`daemon start --name <inst>`（默认 `default`）可在同一项目下并行启动多个 Godot daemon；顶层 `--instance <name>` 对所有 RPC / run / daemon 子命令通用，daemon 子命令的 `--name` 是等价写法。
+- **状态布局迁移 `.cli_control/instances/<name>/`**：daemon 的 pid / port / log 文件从项目根平铺改为按实例子目录存放。legacy 平铺路径（旧格式 `<hash>.json` 注册记录 + `.cli_control/port` 等）仅作只读 fallback 兼容，升级期间无需手工迁移；停掉旧 daemon 后文件自动收敛。硬编码读 `.cli_control/port` 的脚本应改读 `.cli_control/instances/default/port`，或改用 `GameClient()`/`GameBridge()` 自动发现（支持 `instance=` 参数）以免再次硬编码。
+- **`daemon ls` 新增 instance 列**：JSON 每条 `result.daemons[]` 含 `"instance"` 字段；text 输出格式改为 `pid\tport\tinstance\tproject_root\tstarted_at`。
+- **`daemon stop --all --project <path>`**：限定停某个项目下的全部实例（原 `--all` 不带 `--project` 仍停全局所有项目的所有实例）。
+- **daemon 各子命令的 JSON envelope result 带 `"instance"` 字段**：`start` / `stop` / `status` / `logs` 均在 result 中增加 `"instance"` 键，便于 agent 确认操作目标。
+- **`GameBridge(instance=...)` / `GameClient(instance=...)`**：`port=None` 时 `instance` 参数生效，自动查找对应命名实例的端口；显式 `port` 优先（向后兼容）。
+- **pytest 多实例工厂 fixture `godot_instances`**（#143）：联机 e2e 在单测里同时拿 server / client bridge——`godot_instances.start("server")` 幂等启动命名实例并返回已连接 `GameBridge`，teardown 自动停掉本 fixture 起的全部实例（已在跑的只连不杀）；`stop(name)` 支持中途显式停（掉线场景）后重启，`daemon(name)` 暴露底层 `Daemon`。新增 pytest 选项 `--godot-cli-instances-scope=function|session`（默认 function 每用例隔离；session 整套共享省启动时间）。
+- **`--instance all` 一条命令广播全部活实例**（#145）：任一 RPC 子命令对 cwd 项目全部活实例并发执行，聚合信封 `{"instances":[{instance, ok, result|error, rc}...], "rc": 0|3}`（entry 复刻单命令信封）；退出码全 0→0、任一非 0→3（沿 `daemon stop --all` 先例）。字符串参数中的 `{instance}` 逐实例替换；广播 `screenshot` 的路径缺 `{instance}` 时 preflight 报 -1003/64。`all` 成为保留实例名（`daemon start --name all` 拒绝）；`run`/`daemon` 子命令不支持广播。
+
+### Changed
+- **多实例选靶语义（处处一致）**：0 个在跑 → 选 default（legacy fallback）；1 个在跑 → 自动选中；≥2 个在跑且未指定 `--instance` / `--name` → `-1003` / exit 64，message 列出在跑实例名（`"multiple instances running: ... — pass --instance <name>"`）。显式 `--instance nope` 但该实例未在跑 → `-1003` / exit 64，message 附当前在跑实例列表。`--instance` 与 `--port` 互斥。
+- **选中实例 live 但 port 文件尚不可读（daemon 启动中的瞬态）→ `-1003` / exit 64 并提示稍后重试**（#144）：此前静默回退默认端口、连接失败干等 30s，agent 拿不到「正在启动，请重试」的信号。
+
+### Fixed
+- **`daemon stop --all --project <path>` 对没有任何 daemon 在跑的项目不再伪造 `default` 条目**（#144）：text 输出 `(no running daemons)`、JSON `{"stopped": [], "rc": 0}`，与 `--all` 全局空注册表的形状一致。
+- **旧版本 CLI 启动的录像 daemon 用新版 `daemon stop` 停止时录像正常转码**（#144）：此前 legacy 平铺路径的 `movie_path` 无人消费，录像静默残留；legacy `last_exit_code` 死文件也一并清理。
+- **kill -9 留下的死实例目录 `.cli_control/instances/<name>/` 在状态文件清空后自动回收**（#144）：`godot.log` 等诊断文件在场时目录保留不动。
+
+## [0.2.17] - 2026-06-06
+
+### Fixed
+- **#137 `screenshot --node` 在 hiDPI / viewport stretch 下裁剪错位**（PR #138）：`compute_node_screen_rect` 漏乘 viewport final transform——rect 算在画布（逻辑设计分辨率）坐标系，而取图侧 `get_image()` 是窗口物理像素系；平窗（scale=1）两系重合所以长期未暴露。Retina / `canvas_items` stretch 下裁出的区域偏移或截半。
+
+## [0.2.16] - 2026-06-06
+
 ### Added
+- **`find_godot_binary` PATH 候选名补 .NET/mono 版别名**（PR #134）：`godot4-mono` / `godot-mono` / `godot_mono` / `Godot_mono`，排标准名之后（双版并存优先轻量标准版）。macOS `/Applications` 与 Windows Program Files 的 glob 天然覆盖 mono 包名，零改动。
+- **#135 macOS 检测兜底扫描 `~/Applications`**（PR #136）：`/Applications` 优先、用户级目录兜底，覆盖无管理员权限安装的场景。
+
+## [0.2.15] - 2026-06-05
+
+### Added
+- **feat(wait): `wait-prop` / `wait-signal` / `wait-frames` 条件等待原语 + 错误码 1007（#96）**: 三个新 CLI 子命令。`wait-prop <path> <prop> <value> [--op eq|ne|gt|lt|ge|le] [--timeout] [--tolerance]` 等属性满足条件（exit 0=matched, 1=timeout）；`wait-signal <path> <signal> [--timeout]` 等信号发射（exit 0=emitted, 1=timeout）；`wait-frames <N> [--physics]` 推进 N 帧。服务端错误码 1007 SIGNAL_NOT_FOUND（wait-signal 传未知信号名，永久性 schema 错，不应 retry）。Python `GameClient` 对应方法：`wait_property` / `wait_signal` / `wait_frames`。
 - **#110 `wait_signal` 超时与节点释放可区分**：未命中时返回体新增 `reason` 字段，值为 `"timeout"`（信号在超时前未发射）或 `"node_freed"`（等待期间目标节点被释放）。命中路径（`emitted: true`）不含 `reason`，对齐 `wait_property` matched 时无 reason 的约定。非 BREAKING（新增可选字段）。
+- **feat: `get_properties` 多属性同帧原子读 + `get` 多属性形式（#100）**：`get <path> <prop1> <prop2>` 一次 RPC 同帧读取多个属性，不存在部分新鲜/部分旧数据的竞态；任一属性缺失整体失败（1002，message 点名所有缺失项）。sub-path 形式（`position:x`）在多属性列表中也支持。
+- **feat(input): press/tap/hold/combo 注入 InputEventAction 进事件管线，_input/_unhandled_input 可见（#97）**：之前的实现只调 `Input.action_press/release`，仅翻轮询状态位，事件回调收不到。现改为 `Input.parse_input_event(InputEventAction)`，轮询（`is_action_pressed`/`get_vector`）与事件回调（`_input`/`_unhandled_input`）两种游戏写法均可感知注入输入。边界：`InputEventAction` 不携带鼠标坐标，依赖位置的 `_gui_input` 控件仍需用 `click`。
+- **feat(scene): `scene-reload` / `scene-change` + pytest `fresh_scene` fixture + 错误码 1008（#98，PR #121）**：重载当前场景 / 切换到指定场景并阻塞到新场景 ready（per-test 隔离原语）；无 current scene、路径不存在、超时报 1008。`fresh_scene` fixture 让用例从干净场景开始；reload 后此前缓存的节点路径全部失效。
+- **feat(time): `time-scale` / `pause` / `unpause` / `step-frames` + 错误码 1009（#102，PR #125）**：读写 `Engine.time_scale`（合法域 (0, 100]，`wait-time` 按 game time 计、倍速后语义不变）、暂停/恢复 SceneTree、paused 下确定性推进 N 帧（物理断言原语）。未 pause 调 `step-frames` 报 1009。
+- **feat(render): `sprite-info` + `screenshot --node` + 错误码 1010/1011（#101，PR #130）**：`sprite-info` 一次拿齐 Sprite2D / AnimatedSprite2D / TextureRect 的 texture、实际图集区域（effective_region / frame_texture）、翻转、帧号、modulate、visible（纯属性读，headless 可用）；`screenshot --node` 按节点屏幕 AABB 裁剪小图供像素级断言。非 sprite 类 → 1010，屏幕外/零尺寸 → 1011。
+- **feat(diag): `errors` 结构化查询 + `daemon logs --tail` + pytest 失败配套 + 错误码 1012（#103，PR #131)**：Logger 拦截 push_error / push_warning，seq 游标增量查询（`--since` 实现「本用例期间零错误」断言；需 Godot 4.5+，老引擎报 1012）；`daemon logs --tail N` 直接读 `.cli_control/godot.log`（daemon 已退出也可用，post-mortem 排查）；pytest 新增 `no_push_errors` fixture（用例期间出现新 push_error 即失败）与失败自动截图（非 headless 时存 `.cli_control/failures/<nodeid>.png`）。
+- **feat(init): 默认覆盖 addon 目录 + `--keep-addon` 逃生口（PR #133）**：重跑 `init` 即同步 `addons/godot_cli_control/` 与 SKILL.md 到当前 CLI 版本（插件目录 wipe 后重拷，`project.godot` patch 保持幂等）。`--force` 降级为兼容 no-op（与 `--keep-addon` 互斥）。
 
-### Fixed (BREAKING — exit code changes)
+### Changed
+- **BREAKING** `get` 复合 Variant 返回从旧版 `"(x, y)"` 字符串改为 set-schema 数组 + type 字段；信封 result 从裸值变 `{"value": <array-or-scalar>, "type"?: "<GodotType>"}` 对象（#99）。写侧 `set` 接受的 Array layout 完全一致，get→set round-trip 无需转换。Python API `get_property` / `get_properties` 只返回裸 value（type 已剥离），要拿 type 字段走 CLI `get` 或底层 `client.request("get_property", ...)`。
+- **pytest `bridge` fixture teardown 兜底还原全局态（#124，PR #126）**：unpause + 把 `time_scale` 还原到 setup 时快照值（非盲写 1.0，不打断 `--godot-cli-time-scale` 整套加速）+ `release_all()`。上个用例崩溃残留的 pause / 倍速不再污染下一个。
 
+### Fixed (BREAKING — exit code changes)
 - **#111 argparse 用法错 exit 2 → exit 64**: 所有 argparse 层错误（缺位置参数、非法 choices、未知子命令等）现在统一输出 `-1003` 信封并以 exit 64 退出。之前是 exit 2（argparse 默认）。影响：脚本若用 `[ $? -eq 2 ]` 判 argparse 错需改为 `[ $? -eq 64 ]`。
 - **#92 `run <script>` 前置错误拆分**:
   - 脚本路径不存在 / 脚本缺 `run(bridge)` 函数：由旧的 exit 2（或 exit 1）改为 exit 64，错误码由 `-1003` 保持不变。这是用法错，应修正调用而非重试。
   - `daemon start`（`run` 自动启停 / `daemon start` 命令）/ `daemon stop` 系统级失败（端口冲突、找不到 Godot binary、PID 文件丢失等）：错误码由 `-1003` 改为 **新码 `-1006` (PRECONDITION)**，exit code 保持 exit 2。影响：`run`/`daemon` 失败时，通过 `error.code` 区分用法错（`-1003` → 修调用）与基础设施错（`-1006` → 修环境）现在变得无歧义。
 
+### Performance
+- **#109 `wait_property` 免物化直比 + 属性存在性 memo（PR #132）**：逐帧轮询不再每帧物化编码整个属性值；顺手修了 GDScript 跨类型 `==` 是运行期脚本错误（中止函数抛 Nil、非静默 false）的存量雷（`_safe_eq` 守卫）。
+
+## [0.2.14] - 2026-06-03
+
+仅打包元数据 / 文档：PyPI keywords / classifiers / urls、社区健康文件（CONTRIBUTING / SECURITY / issue & PR 模板）、修复失效的 git 安装命令。无代码行为变更。
+
+## [0.2.13] - 2026-06-02
+
 ### Added
-- **feat(wait): `wait-prop` / `wait-signal` / `wait-frames` 条件等待原语 + 错误码 1007（#96）**: 三个新 CLI 子命令。`wait-prop <path> <prop> <value> [--op eq|ne|gt|lt|ge|le] [--timeout] [--tolerance]` 等属性满足条件（exit 0=matched, 1=timeout）；`wait-signal <path> <signal> [--timeout]` 等信号发射（exit 0=emitted, 1=timeout）；`wait-frames <N> [--physics]` 推进 N 帧。服务端错误码 1007 SIGNAL_NOT_FOUND（wait-signal 传未知信号名，永久性 schema 错，不应 retry）。Python `GameClient` 对应方法：`wait_property` / `wait_signal` / `wait_frames`。
+- **examples/platformer-demo 可跑示例（#89）**：自带 Start 按钮 + 跳跃角色场景与 `drive.sh` 全链路演示，CI 下真 Godot 驱动防腐。
 
-### Changed
-- **BREAKING** `get` 复合 Variant 返回从旧版 `"(x, y)"` 字符串改为 set-schema 数组 + type 字段；信封 result 从裸值变 `{"value": <array-or-scalar>, "type"?: "<GodotType>"}` 对象（#99）。写侧 `set` 接受的 Array layout 完全一致，get→set round-trip 无需转换。Python API `get_property` / `get_properties` 只返回裸 value（type 已剥离），要拿 type 字段走 CLI `get` 或底层 `client.request("get_property", ...)`。
+### Fixed
+- **批量修复 10 个 issue**：CLI 子命令端口从 `.cli_control/port` 自动发现、`-1003` 用法错退出码统一为 64（#82）、`tap`/`hold` 加 `--wait` 阻塞选项、ruff 进 CI 门禁等。
+
+## [0.2.12] - 2026-06-01
 
 ### Added
-- **feat: `get_properties` 多属性同帧原子读 + `get` 多属性形式（#100）**：`get <path> <prop1> <prop2>` 一次 RPC 同帧读取多个属性，不存在部分新鲜/部分旧数据的竞态；任一属性缺失整体失败（1002，message 点名所有缺失项）。sub-path 形式（`position:x`）在多属性列表中也支持。
+- **#80 `init` 把 `.cli_control/` 写进目标项目 `.gitignore`**，避免提交机器本地状态（port / pid / log）。
+
+## [0.2.11] - 2026-05-31
+
+### Fixed
+- **#79 拒绝 `--record` + `--headless` 组合**：Godot Movie Maker 在 headless 下 SIGSEGV（上游问题），preflight 直接报用法错（下游 CultivationWorld #180 根因）。
+
+## [0.2.10] - 2026-05-24
+
+### Fixed
+- Windows / 测试修补批次：`run_gut.py` 强制 UTF-8 stdout/stderr（#36 Windows GUT 中文崩溃）、Windows 注册表目录（#43）、`run` 收尾 SIGTERM 噪音消除（#67）、`_build_tree` LIMIT 常量消歧（#48）。
+
+## [0.2.9] - 2026-05-23
+
+### Fixed
+- **输入持续性**：断连按 WebSocket close code 区分「清 / 不清」持有中的输入；`hold` duration 加校验。崩断的客户端不再把按住的方向键永久遗留在游戏里。
+
+## [0.2.8] - 2026-05-16
+
+### Added
+- **`GODOT_CLI_LONG_OP_TIMEOUT=<seconds>`** 环境变量抬高 600s 客户端长操作上限（超 10 分钟的录制）；`wait_game_time` / `combo` 去掉 wall-clock 上限，靠 ws 心跳兜底（#45）。
+- **`run` 静态检测脚本里的 `screenshot` 自动 force GUI（#65）**：headless 截图必失败，提前规避。
+
+## [0.2.7] - 2026-05-16
+
+仅文档：SKILL.md / `-h` / 旁路文档以代码为标准对齐（11 处缺漏与不准确）。无代码行为变更。
+
+## [0.2.6] - 2026-05-16
+
+### Fixed
+- **#61 `screenshot` 首帧 transient 失败根因消除 + 兜底**：viewport texture 未就绪时不再偶发 1006。
+
+## [0.2.5] - 2026-05-16
 
 ### Fixed
 - **#52 `set` 走 JSON Array 喂 Vector/Color/Rect 时静默失败**：`set zoom '[1.8, 1.8]'` 等价于 `node.set("zoom", [1.8, 1.8])`，Godot 隐式构造失败 → 实际值是 `Vector2(0,0)` 或被 clamp 到 `0.00001`，但服务端仍返 `{success: true}`。`handle_set_property` 现在查 `get_property_list()` 拿声明类型，把 numeric Array 转成对应 Variant。长度不匹配或元素非数字时 fail-loud 返 `-32602 "value type mismatch ..."`，不再 silent corruption。
 - **sub-path 标量赋值现在真的会写入**：之前 `set <node> position:x 1.8` 调的是 `Object.set("position:x", 1.8)`，Godot 4 的 `Object.set` 把整串当字面属性名找不到就 silent no-op（依旧返 `{success: true}` 但 `position.x` 不变）。改用 `Object.set_indexed(NodePath, value)` 才会按 sub-path 写入。是 #54 review 阶段被新加的 `test_set_subpath_scalar_still_works` 捕获的隐藏 silent-fail。
+- **CLI flag position**: `--json` / `--text` / `--no-json` 现在在 RPC 子命令尾部也接受（之前只能写最前面）。argparse 子 parser 用 `default=argparse.SUPPRESS` + 顶层 `set_defaults` 兜底，避免子 parser 默认值覆盖父 parser 解析结果。
+- **Error code 1004 collision**: `low_level_api.gd` 的 scene tree 超限改用新业务码 `1005 "scene tree too large"`，与 input_simulation `1004 "combo in progress"` 解耦。新增 `error_codes.gd` 集中常量。
+- **pytest fixture default port**: `--godot-cli-port` 默认从 9877 改为 0（OS-assigned），与 `daemon start` 默认对齐；多项目并行测试不再撞端口。
+- **Addon README error-code table**: 之前只列到 1003，补全 1004 / 1005 / 客户端 -1xxx 段。
+- **Scene tree hard limit bypass (DoS fix)**: `handle_get_scene_tree` 入口现在把 `max_nodes` clamp 到硬墙 `_BUILD_TREE_MAX_NODES` (5000)。修复前客户端传 `max_nodes=999999` 会让服务端先把整棵超大树构造成 Dictionary 再被 1005 错误丢弃（内存浪费 / OOM 路径）。
+- **Error code 1003 semantic split**: screenshot 在 viewport texture 为 null 时不再借用 `1003 METHOD_NOT_FOUND`，改用新业务码 `1006 RESOURCE_UNAVAILABLE`。1003 现在是纯 schema 错（不应 retry），1006 是 transient 错（短重试可能成功），agent 据此分别处置。
+- **`cmd_run` / `cmd_init` 真正输出 JSON envelope（#50）**；`GameBridge` 补 `get_scene_tree` / `wait_game_time` / `action_tap` alias 兑现「方法名一致」承诺（#58 #60）。
 
 ### Added
-- **feat(input): press/tap/hold/combo 注入 InputEventAction 进事件管线，_input/_unhandled_input 可见（#97）**：之前的实现只调 `Input.action_press/release`，仅翻轮询状态位，事件回调收不到。现改为 `Input.parse_input_event(InputEventAction)`，轮询（`is_action_pressed`/`get_vector`）与事件回调（`_input`/`_unhandled_input`）两种游戏写法均可感知注入输入。边界：`InputEventAction` 不携带鼠标坐标，依赖位置的 `_gui_input` 控件仍需用 `click`。
 - **#54 全部复合 Variant 都支持 Array → Variant coerce**：从 4-float 简单类型到 16-float 矩阵，全部按 axis-vector 顺序的 flat numeric Array 写入（每 N 元素 = 一个 Vector 轴）。覆盖：`Vector2/2i/3/3i/4/4i`、`Rect2/2i`、`Color`（3-element=RGB / 4-element=RGBA）、`Plane(a,b,c,d)`、`Quaternion(x,y,z,w)`、`AABB(pos 3, size 3)`、`Basis(9 axis-vector)`、`Transform2D(xaxis 2, yaxis 2, origin 2)`、`Transform3D(basis 9, origin 3)`、`Projection(16 axis-vector)`。具体 layout 见 SKILL.md。`Plane.normal` 和 `Quaternion` 不会自动归一化（与 Godot ctor 一致）。
 - **#54 防御性 fallback**：未在 coerce 名单也不在 `_ARRAY_PASSTHROUGH_SAFE_TYPES`（基本类型 / Object / 集合 / Packed*Array）白名单的声明类型 + Array 输入会 fail-loud，避免未来 Godot 加新 compound Variant 时 silent-corrupt 回归。
 - **#54 sub-path + Array 现在 fail-loud**：`set <node> transform:origin '[10, 20, 30]'` 在 Godot 里会 silent-corrupt（Vector3 leaf 不会从 Array 隐式构造，origin 仍是 (0,0,0)），server 现在主动返 `-32602 "sub-path + Array is not supported"` 提示走 top-level 形式（如 `set <node> transform '[basis 9, origin 3]'`）。sub-path 标量赋值（`position:x 1.8`）不变。
+- `tree --max-nodes <N>`（默认 200）：节点数软上限；超出时响应含 `truncated: true` + `total_nodes`，agent 据此决定分子树。硬墙仍是 5000 节点 → `1005`。
+- `set` / `call --text-value`：禁用 JSON 解析、把 value/args 强制按字符串处理，避开 `null` / `true` / `42` 这类字面量被解析成 Variant 类型的 footgun。
+
+### Changed
+- **BREAKING (轻微)**：`daemon start` / `run` 默认 headless 行为改为基于 `sys.stdout.isatty()` 自动判定 —— pipe / CI / agent shell 默认 headless；交互终端默认开窗。新增 `--gui` 强制开窗 flag。`--headless` 仍可显式传，覆盖自动判。脚本里依赖 "默认会开窗" 的需要加 `--gui`。
+
+## [0.2.4] - 2026-05-01
+
+### Changed
+- **BREAKING (轻微)：默认 daemon 端口从 9877 改为 OS-assigned**。实际端口写入 `.cli_control/port`，CLI 子命令与 `GameClient()`（不传 port）自动发现。硬编码 `127.0.0.1:9877` 的外部脚本要么读 `.cli_control/port`，要么显式传 `--port 9877`。
+
+### Added
+- **`daemon ls`**：跨项目列出运行中的 daemon（全局注册表 + 死记录自动清理）。
+- **`daemon stop --all` / `--project <path>`**：批量 / 跨项目停止。
+- **`daemon start --idle-timeout 30m`**：opt-in 空闲自动 shutdown；项目级默认可写 `.cli_control/config.json`（`{"idle_timeout": "30m"}`），显式 flag 优先。
+- `daemon start` 前先 bind 校验端口空闲，被占立即报错。
+
+## [0.2.3] - 2026-05-01
+
+### Added
+- **`GODOT_CLI_CONTROL=0` 强制禁用逃生口**：env var 一票否决，覆盖其它激活方式。
+
+## [0.2.2] - 2026-04-29
+
+### Security / Hardening
+- **封堵 `set_property` 黑名单 NodePath sub-property 旁路**（`script:source_code` 类路径绕过黑名单）。
+- handler 加固：async type-check、action 名校验、scene-tree 节点数上限。
+- Python 测试覆盖率接入 80% 门禁。
+
+## [0.2.1] - 2026-04-29
+
+与 v0.2.0 同代码（发布管线重跑），无变更。
+
+## [0.2.0] - 2026-04-29
 
 ### AI-friendly CLI 改造（多个 BREAKING change）
 
@@ -73,24 +205,14 @@
 #### Out of scope (intentional)
 - `run <script.py>` 子命令保留旧的人类可读 stderr 输出。它是交互式脚本宿主，不是 RPC，新的 JSON 信封契约只覆盖 RPC 子命令 + daemon 三命令。
 
-### AI-friendliness review fixes (2026-05-11)
-
-#### Fixed
-- **CLI flag position**: `--json` / `--text` / `--no-json` 现在在 RPC 子命令尾部也接受（之前只能写最前面）。argparse 子 parser 用 `default=argparse.SUPPRESS` + 顶层 `set_defaults` 兜底，避免子 parser 默认值覆盖父 parser 解析结果。
-- **Error code 1004 collision**: `low_level_api.gd` 的 scene tree 超限改用新业务码 `1005 "scene tree too large"`，与 input_simulation `1004 "combo in progress"` 解耦。新增 `error_codes.gd` 集中常量。
-- **pytest fixture default port**: `--godot-cli-port` 默认从 9877 改为 0（OS-assigned），与 `daemon start` 默认对齐；多项目并行测试不再撞端口。
-- **Addon README error-code table**: 之前只列到 1003，补全 1004 / 1005 / 客户端 -1xxx 段。
-- **Scene tree hard limit bypass (DoS fix)**: `handle_get_scene_tree` 入口现在把 `max_nodes` clamp 到硬墙 `_BUILD_TREE_MAX_NODES` (5000)。修复前客户端传 `max_nodes=999999` 会让服务端先把整棵超大树构造成 Dictionary 再被 1005 错误丢弃（内存浪费 / OOM 路径）。
-- **Error code 1003 semantic split**: screenshot 在 viewport texture 为 null 时不再借用 `1003 METHOD_NOT_FOUND`，改用新业务码 `1006 RESOURCE_UNAVAILABLE`。1003 现在是纯 schema 错（不应 retry），1006 是 transient 错（短重试可能成功），agent 据此分别处置。
+## [0.1.7] – [0.1.10] - 2026-04-29
 
-#### Added
-- `tree --max-nodes <N>`（默认 200）：节点数软上限；超出时响应含 `truncated: true` + `total_nodes`，agent 据此决定分子树。硬墙仍是 5000 节点 → `1005`。
-- `set` / `call --text-value`：禁用 JSON 解析、把 value/args 强制按字符串处理，避开 `null` / `true` / `42` 这类字面量被解析成 Variant 类型的 footgun。
+发布管线 / 打包修复批次：`pyproject.toml` 提升到仓库根（0.1.7）、`init` 重新导入项目以刷新 `global_script_class_cache`（0.1.9）。
 
-#### Changed
-- **BREAKING (轻微)**：`daemon start` / `run` 默认 headless 行为改为基于 `sys.stdout.isatty()` 自动判定 —— pipe / CI / agent shell 默认 headless；交互终端默认开窗。新增 `--gui` 强制开窗 flag。`--headless` 仍可显式传，覆盖自动判。脚本里依赖 "默认会开窗" 的需要加 `--gui`。
+### Changed
+- **`auto_enable_in_debug` 默认改为 true**（0.1.10）：编辑器 F5 直接生效，不再需要手动激活（release build 仍无条件禁用）。
 
-## [0.1.6] - Unreleased
+## [0.1.6] - 2026-04-29
 
 ### Added
 - `godot-cli-control init`: 一键 onboarding 子命令 + 跨平台 Python daemon (取代手写 wrapper)。

{godot_cli_control-0.2.17 → godot_cli_control-0.3.0}/addons/godot_cli_control/README.md

@@ -122,7 +122,7 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 
 > **Event pipeline**: `press` / `tap` / `hold` / `combo` inject an `InputEventAction` through the engine's event pipeline — both polling (`is_action_pressed`, `get_vector`) **and** event callbacks (`_input`, `_unhandled_input`) see the input. `InputEventAction` carries no mouse coordinates; position-dependent `_gui_input` widgets need `click` instead.
 
-> **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.
+> **No-arg `GameClient()` / `GameBridge()`**: with no `port` argument they auto-discover the daemon's port from `.cli_control/instances/<name>/port` (falling back to `9877`). Pass `instance="server"` to target a named instance when multiple are running (explicit `port` always wins over `instance`). A no-arg call in a single-instance environment still works as before.
 
 ### Variant encoding depth limit
 
@@ -151,7 +151,7 @@ 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; also out-of-range values like a scene `timeout` outside `(0, 3600]` sent directly via `GameClient`) |
 | `-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`, a non-numeric `tap`/`wait-time` arg, a `scene-change` path not starting with `res://`/`uid://`, a `scene-reload`/`scene-change` `--timeout` outside `(0, 3600]`, a `set`/`call` value that fails JSON parsing, script path not found, or script missing `run(bridge)`). Always exits **64** (#82 / #111). |
+| `-1003` | client | CLI usage error (combo missing steps, malformed `--steps-json`, a non-numeric `tap`/`wait-time` arg, a `scene-change` path not starting with `res://`/`uid://`, a `scene-reload`/`scene-change` `--timeout` outside `(0, 3600]`, a `set`/`call` value that fails JSON parsing, script path not found, script missing `run(bridge)`, **multi-instance ambiguity** (≥2 instances running and no `--instance`/`--name` given), **named instance not running** (explicit `--instance nope` but that instance isn't up), **instance port not readable yet** (alive but mid-startup — transient, retry), or `--instance` / `--name` conflict). Always exits **64** (#82 / #111). |
 | `-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 |
 | `-1006` | client | Infra pre-condition failure (`daemon start`/`stop`/`run` auto-start failed at OS level — port conflict, Godot binary not found, etc.). Always exits **2** (#92). |
@@ -165,12 +165,14 @@ The daemon is the long-lived Godot process the CLI talks to (one per project roo
 
 | Command | What it does |
 |---|---|
-| `daemon start [--headless\|--gui] [--record] [--time-scale N]` | 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). `--time-scale N` sets `Engine.time_scale` from frame 0 (range `(0, 100]`). |
-| `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 start [--headless\|--gui] [--record] [--time-scale N] [--name <inst>]` | Launch Godot with the bridge listening. `--name` sets the instance name (default `default`); use different names to run multiple Godot daemons for the same project in parallel. 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). `--time-scale N` sets `Engine.time_scale` from frame 0 (range `(0, 100]`). |
+| `daemon stop [--name <inst>]` | Stop this project's daemon. With `--name`, stop the named instance. 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). |
+| `daemon stop --all --project <path>` | Stop all instances of one specific project. |
+| `daemon stop --project <path>` | Stop the daemon for one specific project root (single-instance shorthand). |
+| `daemon status [--name <inst>]` | Exit 0 = running, 1 = stopped. Response includes `"instance"` field. 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, **instance**). Text columns: `pid\tport\tinstance\tproject_root\tstarted_at`. |
+| `daemon logs [--name <inst>] [--tail N]` | Print last N lines of godot.log for the given instance. |
 
 **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>`.
 

{godot_cli_control-0.2.17 → godot_cli_control-0.3.0}/python/README.md

@@ -80,7 +80,19 @@ def test_jump(godot_daemon, bridge):
 ```
 
 - `godot_daemon` (session-scoped) starts headless Godot once and stops it after all tests; if a daemon is already running it's reused (and not stopped at teardown — keeps your IDE workflow alive).
-- `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it calls `release_all()` so a `hold` left behind by one case can't bleed into the next, then closes the connection.
+- `bridge` (function-scoped) gives a fresh `GameBridge`; on teardown it best-effort restores global engine state — `unpause()`, `time_scale` back to its setup-time snapshot, `release_all()` — so a `hold`/`pause`/speed-up left behind by one case can't bleed into the next, then closes the connection.
+- `fresh_scene` (function-scoped, opt-in) calls `scene_reload()` at setup so the case starts on a pristine scene. Node references cached before the reload are invalid afterwards.
+- `no_push_errors` (function-scoped, opt-in) records an `errors` marker at setup and fails the case if any new `push_error` was emitted during it (warnings don't fail). Requires Godot 4.5+ (Logger API) — older engines raise `RpcError` 1012 at setup, loudly.
+- `godot_instances` (scope configurable, default function) is a multi-instance factory for multiplayer e2e — start a named server **and** clients inside one test and get connected `GameBridge` objects back; teardown stops everything the fixture started (and only that):
+
+  ```python
+  def test_join(godot_instances):
+      server = godot_instances.start("server")
+      client = godot_instances.start("client1")
+  ```
+
+  `start(name)` is idempotent get-or-start (`headless`/`time_scale` follow the global options, overridable per call; `port` always defaults to 0 = OS-assigned); `stop(name)` stops one instance mid-test (restartable); `daemon(name)` exposes the underlying `Daemon`. `--godot-cli-instances-scope session` shares one set of instances across the whole suite (faster, no state isolation between tests).
+- On a test failure (non-headless daemon only) a best-effort screenshot is saved to `.cli_control/failures/<nodeid>.png` and the path is attached to the pytest report.
 
 CLI options:
 
@@ -88,6 +100,8 @@ CLI options:
 --godot-cli-port=N           # GameBridge port (default: read from .cli_control/port)
 --godot-cli-no-headless      # open a real Godot window
 --godot-cli-project-root=DIR # default: pytest rootdir
+--godot-cli-time-scale=X     # Engine.time_scale applied at daemon startup (e.g. 5 to speed up the suite)
+--godot-cli-instances-scope=function|session  # godot_instances fixture scope (default: function)
 ```
 
 ## CLI
@@ -102,17 +116,20 @@ godot-cli-control daemon start --record --movie-path X [--fps N]   # 录制需
 godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
 godot-cli-control daemon ls                  # list running daemons across all projects
+godot-cli-control daemon logs [--tail N]     # last N lines of .cli_control/godot.log (works post-mortem)
 godot-cli-control run <script.py> [--headless ...]
 
 # Read
 godot-cli-control tree [depth]
-godot-cli-control get      <node_path> <prop>
+godot-cli-control get      <node_path> <prop> [prop2 ...]   # multi-prop = atomic same-frame read
 godot-cli-control text     <node_path>
 godot-cli-control exists   <node_path>      # exit 0=true, 1=false, 2=infra
 godot-cli-control visible  <node_path>      # exit 0=true, 1=false, 2=infra
 godot-cli-control children <node_path> [type-filter]
 godot-cli-control pressed
 godot-cli-control actions [--all]
+godot-cli-control sprite-info <node_path>   # Sprite2D/AnimatedSprite2D/TextureRect render state in one call
+godot-cli-control errors [--since MARKER] [--limit N]   # structured push_error/push_warning log (Godot 4.5+)
 
 # Write / call
 godot-cli-control set   <node_path> <prop>   <json-value>
@@ -127,21 +144,33 @@ godot-cli-control combo --steps-json '[...]'   # or `combo file.json` / `combo -
 godot-cli-control combo-cancel
 godot-cli-control release-all
 
-# Wait
-godot-cli-control wait-node <node_path> [timeout]   # exit 0=found, 1=timeout
-godot-cli-control wait-time <seconds>
+# Wait (exit 0=hit, 1=timeout)
+godot-cli-control wait-node   <node_path> [timeout]
+godot-cli-control wait-prop   <node_path> <prop> <value> [--op gt|lt|ge|le|ne] [--timeout S] [--tolerance T]
+godot-cli-control wait-signal <node_path> <signal> [timeout]   # arm BEFORE triggering the action
+godot-cli-control wait-frames <n> [--physics]
+godot-cli-control wait-time <seconds>        # game time — scales with time-scale
+
+# Scene isolation
+godot-cli-control scene-reload [--timeout S]            # reload current scene, block until ready
+godot-cli-control scene-change <res://path.tscn>        # switch scene, block until ready
+
+# Time control
+godot-cli-control time-scale [value]         # read (no arg) or set Engine.time_scale, (0, 100]
+godot-cli-control pause | unpause
+godot-cli-control step-frames <n> [--physics]   # deterministic stepping while paused
 
 # Render (path is required as of 0.2.0)
-godot-cli-control screenshot <output.png>
+godot-cli-control screenshot <output.png> [--node <node_path>]   # --node crops to that node's screen rect
 ```
 
 ### Output contract
 
 - success: `{"ok": true, "result": <data>}` on stdout, exit 0
-- error:   `{"ok": false, "error": {"code": N, "message": "..."}}` on stdout, exit 1 (RPC) or 2 (connection / usage)
+- error:   `{"ok": false, "error": {"code": N, "message": "..."}}` on stdout, exit 1 (RPC), 2 (connection / infra), or 64 (usage)
 - `--text` / `--no-json` switches back to the legacy human-readable strings; errors then go to stderr.
 
-`exists` / `visible` / `wait-node` propagate their boolean result to the exit code, so shell `if` works:
+`exists` / `visible` and the `wait-*` commands propagate their boolean / hit-or-timeout result to the exit code, so shell `if` works:
 
 ```bash
 if godot-cli-control exists /root/Main/Boss; then

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

{godot_cli_control-0.2.17 → godot_cli_control-0.3.0}/python/godot_cli_control/bridge.py

@@ -21,15 +21,23 @@ from .client import GameClient
 class GameBridge:
     """同步接口，内部通过事件循环调用异步 GameClient。"""
 
-    def __init__(self, port: int | None = None) -> None:
-        # port=None → GameClient 从 .cli_control/port auto-discover（issue #91）。
+    def __init__(self, port: int | None = None, instance: str | None = None) -> None:
+        # port=None → GameClient 从 .cli_control/ auto-discover（issue #91）。
         # daemon 默认 OS 自动分配端口，所以 ``GameBridge()`` 无参数也能连上正在
         # 跑的 daemon，与 README 的单连接脚本示例一致。
+        # instance：命名实例名（如 "server"），透传给 GameClient.instance；
+        # 显式 port 优先，instance 仅在 port=None 时生效（见 client.py）。
         self._loop = asyncio.new_event_loop()
-        self._client = GameClient(port=port)
-        self._loop.run_until_complete(
-            self._client.connect(retries=15, backoff=1.0, total_timeout=60.0)
-        )
+        # 构造/连接失败时回收 loop —— 多实例歧义（InstanceAmbiguityError）在
+        # __init__ 抛出是预期用法路径，不能让每次报错都泄漏一个 event loop。
+        try:
+            self._client = GameClient(port=port, instance=instance)
+            self._loop.run_until_complete(
+                self._client.connect(retries=15, backoff=1.0, total_timeout=60.0)
+            )
+        except BaseException:
+            self._loop.close()
+            raise
 
     def close(self) -> None:
         self._loop.run_until_complete(self._client.disconnect())