godot-cli-control 0.4.2__tar.gz → 0.5.0__tar.gz

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.4.2
+Version: 0.5.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
@@ -62,9 +62,9 @@ godot-cli-control tree 3
 godot-cli-control daemon stop
 ```
 
-Re-running `init` refreshes both `addons/godot_cli_control/` and the SKILL.md files to match the installed CLI version (the plugin directory is wiped and re-copied; `project.godot` patching stays idempotent). Pass `--keep-addon` to keep an existing `addons/godot_cli_control/` untouched.
+Re-running `init` refreshes both `addons/godot_cli_control/` and the skill files to match the installed CLI version (the plugin directory is wiped and re-copied; `project.godot` patching stays idempotent). Pass `--keep-addon` to keep an existing `addons/godot_cli_control/` untouched.
 
-`init` also writes `.claude/skills/godot-cli-control/SKILL.md` and `.codex/skills/godot-cli-control/SKILL.md` so AI agents working in your Godot project can pick up this CLI surface automatically. Use `--no-skills` to skip, or `--skills-only` to refresh just those files after a CLI upgrade. See the [top-level README](../README.md#agent-integration) for details.
+`init` also writes `.claude/skills/godot-cli-control/` and `.codex/skills/godot-cli-control/` (a lean `SKILL.md` core + `references/*.md` detail files) so AI agents working in your Godot project can pick up this CLI surface automatically without flooding their context. Use `--no-skills` to skip, or `--skills-only` to refresh just those files after a CLI upgrade. See the [top-level README](../README.md#agent-integration) for details.
 
 ## Async API
 

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/CHANGELOG.md

@@ -6,7 +6,16 @@
 
 ## [Unreleased]
 
-## [0.4.2] - 2026-06-14
+## [0.5.0] - 2026-07-08
+
+### Added
+- **`daemon restart`——改启动 flags 一步到位**：容忍未运行的 stop + 以本次给出的 flags 启动（与 `daemon start` 同一套参数，共享注册函数防漂移；**不记忆**上次 start 的 flags）。选靶走 stop 的自动语义（0 个在跑 → default；1 个 → 它；≥2 → 须 `--name`）。stop 硬失败（进程在但停不掉）中止不起新实例（exit 2）；仅 ffmpeg 转码失败（AVI 保留）不阻断重启、最终 exit 4 透出（对齐 `run` 语义）。信封 `{"restarted", "was_running", "stop_rc", "instance", "port", "pid"}`。
+
+### Changed
+- **顶层 `--help` 换成分组命令总览，从 130 行降到 ~87 行**：40+ 子命令原先平铺全量描述；现按 Daemon/读/写/输入/等待/场景时间/渲染诊断 7 组展示、每命令一句话摘要（取自各命令描述首句，自动生成）。旧的手维护清单曾静默漂移掉 `find`/`wait-prop`/`scene-*`/`drag` 等十余条——新版由 `RPC_SPECS` 生成并有测试锁「每个命令必须归入恰好一组」，不再漂移。各命令完整参数照旧 `<cmd> -h`。
+- **`click` 支持 find 同款过滤器定位——「点击文案为 X 的按钮」一条命令原子完成**：`click --contains 开始 [--type BaseButton] [--exact/--name-pattern/--from]`（Python：`client.click(text_contains=...)` / `bridge.click(...)` 同参）。服务端同帧内 find+click，替代 `find` → 解析 `matches[0].path` → `click` 三步两次 RPC，并消灭两步之间的 stale-path 竞态。过滤器必须恰好命中 1 个节点：0 个报 `1001`；≥2 个报**新错误码 `1017 AMBIGUOUS_MATCH`**（message 列出候选路径，收窄过滤器再试——BFS 序不可预期，宁可 fail-loud 也不静默点第一个）。成功信封带 `path`（实际点到的节点）。path 与过滤器互斥（CLI preflight `-1003`/64，服务端 `-32602` 兜裸 RPC）。需要新 addon 行为——老项目跑一次 `init` 同步。
+- **错误信封新增可选 `error.hint` 字段——错误发生点当场给「下一步怎么办」**：此前「拿到 1009 该先 `pause`」「拿到 1004 该 `combo-cancel`」这类指引只存在于 SKILL.md 错误码表里，没读过表的 agent 只能瞎重试。现服务端业务码（`1xxx` 全部 16 个 + `-32601`）由 addon 侧 `CliControlErrorCodes.hint_for` 随响应下发（GUT 锁「新增业务码必须登记 hint」），客户端码（`-1001`/`-1002`/`-1004`/`-1006`/`-1099`）由 CLI 在发射点补齐；服务端下发的 hint 优先于客户端映射。message 已足够具体的码（`-32602`/`-1003`/`-1005`）不带 hint，无 hint 的错误不带空字段。`--text` 模式在 stderr 尾部追加「（提示：...）」；`--instance all` 广播的 per-entry error 同样带 hint；`RpcError` 新增 `.hint` 属性供 Python 调用方使用。服务端 hint 需要新 addon——老项目跑一次 `init` 同步（未同步只是没有 hint，无兼容问题）。
+- **SKILL.md 拆成多文件渐进披露结构，触发时上下文占用从 ~1850 行降到 ~160 行**：旧版单文件 SKILL.md 渲染后 1854 行 / ~142KB（其中 1195 行是 `{{cli_help}}` argparse 全量帮助注入），agent 每次触发 skill 都整体灌进上下文——违背本项目「不让大 payload 撑爆 agent 上下文」的 AI 友好契约。现拆为：核心 `SKILL.md`（quickstart / 退出码 / 单行命令目录 / 高频 pitfalls / 路由表，≤400 行有测试锁）+ `references/*.md` 六个主题文件（commands / error-codes / daemon-multi-instance / recording / python-and-pytest / pitfalls，agent 按需 Read）。`{{cli_help}}` 注入删除——agent 现场跑 `godot-cli-control <cmd> -h` 拿永远最新的帮助，顺带消灭「重渲染必须 COLUMNS=80 + Python 3.12」的 argparse 折行漂移坑（CI skill-render-drift 改整目录 diff，新增 `python -m godot_cli_control.skills_install` 一键重渲染入口）。`init` / `init --skills-only` 现在写整个 skill 目录；`--skills-no-clobber` 逐文件跳过已存在的（老单文件安装升级时缺失的 references/ 仍会补上）。旧项目跑一次 `godot-cli-control init --skills-only` 即升级。API 变更：`skills_install.render_skill(version)` 不再收 `cli_help` 参数，新增 `skills_install.skill_files(version)`。
 
 ### Fixed
 - **`call` 对错类型「标量」实参不再假成功（#167 的标量侧补集）**：#167 只关了 `call` 的 **JSON Array → 复合 Variant** 侧假成功；错类型的标量实参（`set_name 42` 数字→StringName、`set_z_index '"abc"'` String→int 等）此前仍直接喂 `callv`，引擎喷 `Cannot convert argument` 返回 `null`，RPC 却假 `ok:true`/`result:null`——调用方以为方法生效实则没跑（与 #164/#167 同级数据风险，且 README/SKILL 已宣称「typed 方法假成功不再可能」，文档与实现脱节）。现连 daemon 前按方法声明签名对非 Array 实参也做类型守卫：镜像 Godot `Variant::can_convert_strict`，命中安全互转组（数值组 `bool`/`int`/`float`、字符串组 `String`/`StringName`/`NodePath`）透传，跨组（必 `Cannot convert`）`-32602` fail-loud。数值宽化（`float`→`int`）、`bool`→`int`、`String`→`String` 等合法调用零回归；`null` 实参保守透传（不在本 issue 新增拦截）。纯 addon 服务端行为改动，老项目跑一次 `init` 同步。

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/README.md

@@ -82,7 +82,7 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 
 | Method | Example |
 |---|---|
-| `click(path)` | `await client.click("/root/MyScene/Button")` |
+| `click(path=None, node_type=None, text=None, text_contains=None, name_pattern=None, from_path=None)` | `await client.click("/root/MyScene/Button")`, or locate-and-click atomically with find-style filters: `await client.click(text_contains="开始", node_type="BaseButton")` — must match exactly one node (0 → `1001`, ≥ 2 → `1017` listing candidates); success envelope carries the clicked `path`. `path` and filters are mutually exclusive (`-32602`). CLI: `click <path>` \| `click --contains <substr> [--exact/--type/--name-pattern/--from]` |
 | `click_at(x, y, node=None, button="left", double=False)` | `await client.click_at(320, 240)` or `client.click_at(node="/root/Slot", button="right")` — coordinate-level mouse click via the real event pipeline (viewport physical px); CLI: `click-at <x> <y> \| --node <path> [--button] [--double]` |
 | `mouse_move(x, y, node=None)` | `await client.mouse_move(400, 300)` — inject one mouse-motion event (with `relative`); CLI: `mouse-move <x> <y> \| --node <path>` |
 | `drag(x1, y1, x2, y2, from_node=None, to_node=None, button="left", duration=0.3, steps=10)` | `await client.drag(100, 100, 300, 200)` — press→interpolated move→release (slider/drag-and-drop/swipe); each end may use `from_node`/`to_node` for a node center; game-time `duration`, one drag at a time (`1014` otherwise); CLI: `drag <x1> <y1> <x2> <y2> \| --from-node/--to-node <path> [--button] [--duration] [--steps]` |
@@ -137,6 +137,8 @@ All methods callable via `godot-cli-control <method>` or `from godot_cli_control
 
 Three numeric ranges share `error.code`; they never overlap, so a single field is unambiguous.
 
+Most errors also carry an optional **`error.hint`** field — a one-line "what to do next" pointer (e.g. `1009` hints "call `pause` first, then `step-frames`"). Server-side hints (`1xxx` / `-32601`) come from the addon (`CliControlErrorCodes.hint_for`) and require a synced addon (re-run `init` on old projects); client-side hints (`-1xxx`) are added by the CLI itself. Codes whose `message` is already case-specific (`-32602`, `-1003`, `-1005`) carry no hint. Follow the hint before consulting the table below.
+
 | Code | Source | Meaning |
 |---|---|---|
 | `1001` | server | Node not found at the given path |
@@ -155,6 +157,7 @@ Three numeric ranges share `error.code`; they never overlap, so a single field i
 | `1014` | server | DRAG_IN_PROGRESS: a `drag` was issued while another is still interpolating. One mouse drag in flight at a time — wait for it (or `release-all` to cancel) before the next. State-class (like `1004`). |
 | `1015` | server | EMIT_SIGNAL_DISABLED: `emit-signal` called but daemon was not started with `--allow-emit-signal`. Restart the daemon with that flag (debug-build + localhost + explicit opt-in). `emit_signal` remains in the method blacklist — `call <node> emit_signal` is always rejected regardless of this flag. |
 | `1016` | server | RESPONSE_TOO_LARGE: a single response exceeded the outbound WebSocket buffer (default 10 MB, `godot_cli_control/outbound_buffer_mb`) and was replaced with this error instead of hanging the call to a `-1002` timeout. Usually a bytes-API `screenshot` of a hiDPI frame — pass a path (daemon writes to disk) or raise the buffer. |
+| `1017` | server | AMBIGUOUS_MATCH: `click` with finder filters matched ≥ 2 nodes (message lists candidates). Narrow the filters (`--exact`/`--type`/`--from`/`--name-pattern`) until exactly one matches, or `find` and click the path directly. |
 | `-32600` | server | Malformed JSON-RPC request |
 | `-32601` | server | Unknown method name |
 | `-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; `call` typed-arg coercion failure / argument-count mismatch — wrong array length, non-numeric element, a JSON array given to a scalar/Object parameter, a scalar of the wrong type (a string for an `int` param, a number for a `String`/`StringName`), or wrong arg count (#167/#183); 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`, and `find_nodes` called with no filter at all or with both `text` and `text_contains`) |
@@ -175,6 +178,7 @@ 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] [--name <inst>] [--allow-emit-signal]` | 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]`). `--allow-emit-signal` unlocks the `emit-signal` subcommand (debug-build + localhost + explicit opt-in three gates); without it any `emit-signal` call returns `1015`. |
+| `daemon restart [same flags as start]` | Tolerant stop (a stopped daemon is fine) + start with the flags you pass **now** — it does not remember the previous start's flags. The one-step way to change daemon flags (e.g. add `--allow-emit-signal`). Hard stop failure aborts before starting (exit 2); a transcode-only stop failure still restarts and exits `4`. |
 | `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 --all --project <path>` | Stop all instances of one specific project. |

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/bridge/error_codes.gd

@@ -62,7 +62,94 @@ const EMIT_SIGNAL_DISABLED: int = 1015
 # 容量/资源类永久错——同一响应重试必再超；agent 应改用 path 落盘（screenshot）
 # 或调大 buffer。daemon 用它替换发不出去的大响应，避免 client 干等到 -1002 假超时。
 const RESPONSE_TOO_LARGE: int = 1016
+# click 过滤器定位命中多于一个节点（find+click 原子化）：BFS 序对 agent 不可
+# 预期，静默点第一个可能点错按钮（比报错贵得多）——宁可 fail-loud 列出候选
+# 让 agent 收窄。状态类错（与 1004/1014 同族）：过滤器本身合法，是场景里
+# 恰好有多个匹配。
+const AMBIGUOUS_MATCH: int = 1017
 
 const INVALID_PARAMS: int = -32602
 const INVALID_REQUEST: int = -32600
 const METHOD_UNKNOWN: int = -32601
+
+
+## 错误码 → 「下一步怎么办」提示。空串 = 无提示（该码的 message 已足够具体，
+## 如 -32602 每个 case 有专属文案）。唯一注入点是 GameBridge._send_error：
+## 响应 error 对象带上可选 "hint" 字段，CLI 信封原样透传给 agent——让 agent
+## 在错误发生点当场拿到指引，不依赖它读过 SKILL.md 错误码表。
+## 客户端 -1xxx 的提示在 Python 侧 cli.py 的 _CLIENT_HINTS，两段各管各的
+## （与错误码三段制同构）。hint 只补「下一步动作」，不复述错误本身。
+static func hint_for(code: int) -> String:
+	match code:
+		NODE_NOT_FOUND:
+			return (
+				"path must start with /root; locate by text/type with `find`,"
+				+ " or `wait-node <path>` if it may not be loaded yet"
+			)
+		PROPERTY_NOT_FOUND:
+			return "inspect the node's properties with `tree <path> 1`"
+		METHOD_NOT_FOUND:
+			return (
+				"inspect node methods with `tree`; for input actions run"
+				+ " `actions` (or `actions --all`)"
+			)
+		COMBO_IN_PROGRESS:
+			return "run `combo-cancel` (or `release-all`), then retry"
+		SCENE_TREE_TOO_LARGE:
+			return (
+				"pass --max-nodes N, or query a subtree:"
+				+ " `tree <path>` / `children <path>`"
+			)
+		RESOURCE_UNAVAILABLE:
+			return (
+				"usually transient - retry after `wait-time 0.05`; on a"
+				+ " headless daemon screenshots never work (restart with --gui)"
+			)
+		SIGNAL_NOT_FOUND:
+			return "list the node's signals with `tree`; check the spelling"
+		SCENE_UNAVAILABLE:
+			return (
+				"check the res:// path; if loading hangs, inspect"
+				+ " `daemon logs --tail 50`"
+			)
+		NOT_PAUSED:
+			return "call `pause` first, then `step-frames`"
+		UNSUPPORTED_NODE_TYPE:
+			return (
+				"aim at a drawable node (often the child sprite),"
+				+ " or use another command"
+			)
+		NODE_NOT_ON_SCREEN:
+			return "move the camera/node into view (or wait for it), then retry"
+		FEATURE_UNAVAILABLE:
+			return (
+				"requires a newer Godot (errors capture needs 4.5+);"
+				+ " upgrade the engine or drop this call"
+			)
+		WRITE_FAILED:
+			return "fix the destination path/permissions (daemon-side), then retry"
+		DRAG_IN_PROGRESS:
+			return (
+				"wait for the in-flight drag to finish,"
+				+ " or `release-all` to cancel it"
+			)
+		EMIT_SIGNAL_DISABLED:
+			return "restart the daemon with --allow-emit-signal"
+		RESPONSE_TOO_LARGE:
+			return (
+				"pass a file path so the daemon writes to disk,"
+				+ " or raise godot_cli_control/outbound_buffer_mb"
+			)
+		AMBIGUOUS_MATCH:
+			return (
+				"narrow the filters (--exact / --type / --from / --name-pattern)"
+				+ " until exactly one node matches, or run `find` and click"
+				+ " the path directly"
+			)
+		METHOD_UNKNOWN:
+			return (
+				"client and addon versions drifted - re-run"
+				+ " `godot-cli-control init` to sync the addon"
+			)
+		_:
+			return ""

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/bridge/game_bridge.gd

@@ -388,7 +388,13 @@ func _send_response(id: String, result: Dictionary) -> void:
 
 
 func _send_error(id: String, code: int, message: String) -> void:
-	var response: Dictionary = {"id": id, "error": {"code": code, "message": message}}
+	# 所有服务端错误响应的唯一出口：按码附加可选 "hint"（下一步指引），
+	# 让 agent 在错误发生点当场拿到动作建议（hint 表在 CliControlErrorCodes）。
+	var err: Dictionary = {"code": code, "message": message}
+	var hint: String = CliControlErrorCodes.hint_for(code)
+	if not hint.is_empty():
+		err["hint"] = hint
+	var response: Dictionary = {"id": id, "error": err}
 	_send_json(response)
 
 

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/bridge/low_level_api.gd

@@ -146,9 +146,57 @@ func _merge_extra(base: PackedStringArray, setting_key: String) -> PackedStringA
 
 
 func handle_click(params: Dictionary) -> Dictionary:
+	# 两种定位方式：绝对 path（原始形态），或 find 同款过滤器（type / text /
+	# text_contains / name_pattern / from）——「点击文案为 X 的按钮」此前要
+	# find → 解析 matches[0].path → click 三步两次 RPC，中间还有 stale-path
+	# 竞态窗口；现在服务端同帧内 find+click 原子完成。
+	if _has_find_filters(params):
+		var path_given: String = params.get("path", "") as String
+		if not path_given.is_empty():
+			return _err(
+				CliControlErrorCodes.INVALID_PARAMS,
+				"click: give either a node path or finder filters, not both",
+			)
+		return _click_by_filters(params)
 	var node: Node = _get_node_or_error(params)
 	if node == null:
 		return _node_not_found(params.get("path", "") as String)
+	return _click_node(node)
+
+
+## 过滤器定位 + 点击。恰好 1 个匹配才点：0 个 → 1001；≥2 个 → 1017 列出
+## 匹配路径让 agent 收窄（宁可 fail-loud 也不静默点第一个——BFS 序对 agent
+## 不可预期，点错按钮比报错贵得多）。成功信封带 "path"（实际点到的节点）。
+func _click_by_filters(params: Dictionary) -> Dictionary:
+	# 取 1 个足以点击、多取 4 个用于歧义报错时展示候选（够收窄用）
+	var found: Dictionary = _collect_find_matches(params, 5)
+	if found.has("error"):
+		return found
+	var nodes: Array = found["nodes"] as Array
+	if nodes.is_empty():
+		return _err(
+			CliControlErrorCodes.NODE_NOT_FOUND,
+			"click: no node matches the given filters",
+		)
+	if nodes.size() > 1:
+		var paths: PackedStringArray = PackedStringArray()
+		for entry: Dictionary in found["matches"] as Array:
+			paths.append(str(entry["path"]))
+		var more: String = ", ..." if (found.get("truncated", false) as bool) else ""
+		return _err(
+			CliControlErrorCodes.AMBIGUOUS_MATCH,
+			"click: %d nodes match the filters: %s%s"
+			% [nodes.size(), ", ".join(paths), more],
+		)
+	var result: Dictionary = _click_node(nodes[0] as Node)
+	if not result.has("error"):
+		var entry: Dictionary = (found["matches"] as Array)[0] as Dictionary
+		result["path"] = str(entry["path"])
+	return result
+
+
+## click 的实际派发（path 定位与过滤器定位共用）。
+func _click_node(node: Node) -> Dictionary:
 	if node is BaseButton:
 		(node as BaseButton).emit_signal("pressed")
 		return {"success": true}
@@ -694,9 +742,39 @@ func handle_find_nodes(params: Dictionary) -> Dictionary:
 	# 服务端节点搜索（issue #153）：程序化匿名 UI（@Button@12，编号跨运行不稳定）
 	# 只能按文本/类型定位，客户端 children+get_text 逐层 BFS 在录制模式下
 	# 每个 RPC 等帧渲染（50-150ms/次），一次全树遍历曾拖出 57s 死时间——
-	# 这里把几十次往返折成一次。不用 Node.find_children：它先建全量匹配数组
-	# 没法 limit 短路，且手写 BFS 才有「浅层优先」的稳定排序（UI 搜索友好）。
-	# 空字符串 = 过滤器未启用（与 get_children 的 type_filter 约定一致）。
+	# 这里把几十次往返折成一次。遍历本体抽在 _collect_find_matches，与
+	# click 的过滤器定位（原子 find+click）共用。
+	var limit: int = params.get("limit", 20) as int
+	if limit <= 0:
+		limit = 20
+	limit = mini(limit, _FIND_MAX_MATCHES)
+	var found: Dictionary = _collect_find_matches(params, limit)
+	if found.has("error"):
+		return found
+	var response: Dictionary = {"matches": found["matches"]}
+	if found.get("truncated", false) as bool:
+		response["truncated"] = true
+	return response
+
+
+## params 里是否带任一 find 过滤器（click 用它区分 path 定位 / 过滤器定位）。
+## 空字符串 = 过滤器未启用（与 get_children 的 type_filter 约定一致）。
+func _has_find_filters(params: Dictionary) -> bool:
+	return (
+		not (params.get("type", "") as String).is_empty()
+		or not (params.get("name_pattern", "") as String).is_empty()
+		or not (params.get("text", "") as String).is_empty()
+		or not (params.get("text_contains", "") as String).is_empty()
+		or not (params.get("from", "") as String).is_empty()
+	)
+
+
+## find 遍历本体（handle_find_nodes 与 click 过滤器定位共用）：校验过滤器 →
+## 解析 from 子树 → 迭代 BFS。返回 {"matches": Array[Dictionary]（序列化 entry）,
+## "nodes": Array[Node]（与 matches 一一对应，供 click 直接派发）, "truncated"?}
+## 或 {"error": ...}。不用 Node.find_children：它先建全量匹配数组没法 limit
+## 短路，且手写 BFS 才有「浅层优先」的稳定排序（UI 搜索友好）。
+func _collect_find_matches(params: Dictionary, limit: int) -> Dictionary:
 	var type_filter: String = params.get("type", "") as String
 	var name_pattern: String = params.get("name_pattern", "") as String
 	var text_exact: String = params.get("text", "") as String
@@ -714,10 +792,6 @@ func handle_find_nodes(params: Dictionary) -> Dictionary:
 			CliControlErrorCodes.INVALID_PARAMS,
 			"find_nodes: 'text' (exact) and 'text_contains' (substring) are mutually exclusive",
 		)
-	var limit: int = params.get("limit", 20) as int
-	if limit <= 0:
-		limit = 20
-	limit = mini(limit, _FIND_MAX_MATCHES)
 	# 默认搜全树（root 而非 current_scene）：弹窗 / autoload 常直接挂 root，
 	# 「按文本找按钮」必须能命中它们。
 	var start: Node = get_tree().root
@@ -729,6 +803,7 @@ func handle_find_nodes(params: Dictionary) -> Dictionary:
 	# 迭代 BFS（数组 + 头指针）：浅层匹配排前；不递归 → 深树不爆栈；
 	# 与 find_children(owned=true) 不同，代码创建的无 owner 节点照常命中。
 	var matches: Array[Dictionary] = []
+	var match_nodes: Array[Node] = []
 	var truncated: bool = false
 	var queue: Array[Node] = []
 	for child: Node in start.get_children():
@@ -743,12 +818,13 @@ func handle_find_nodes(params: Dictionary) -> Dictionary:
 				truncated = true
 				break
 			matches.append(_node_entry(node))
+			match_nodes.append(node)
 		for child: Node in node.get_children():
 			queue.append(child)
-	var response: Dictionary = {"matches": matches}
+	var result: Dictionary = {"matches": matches, "nodes": match_nodes}
 	if truncated:
-		response["truncated"] = true
-	return response
+		result["truncated"] = true
+	return result
 
 
 ## find_nodes 的过滤判定（AND 语义）。text 两档共享前置：节点必须有 text 属性。

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/plugin.cfg

@@ -3,5 +3,5 @@
 name="Godot CLI Control"
 description="WebSocket bridge for headless / scripted control of Godot scenes (click / property / input simulation / screenshot / record)."
 author="kesar"
-version="0.4.2"
+version="0.5.0"
 script="plugin.gd"

godot_cli_control-0.5.0/addons/godot_cli_control/tests/gut/test_error_codes.gd

@@ -0,0 +1,38 @@
+## GUT 单元测试：CliControlErrorCodes.hint_for —— 错误码 → 下一步提示。
+##
+## 契约：每个 1xxx 业务码都必须登记 hint（agent 在错误发生点当场拿到指引，
+## 相当于把 SKILL.md 错误码表的「下一步」列下沉到运行时）。新增业务码忘
+## 登记 → test_every_business_code_has_hint 红，与 error_codes.gd 头注释的
+## 「新加业务码必须在这里登记」同一守护思路。
+extends GutTest
+
+const ErrorCodes := preload("res://addons/godot_cli_control/bridge/error_codes.gd")
+
+
+func test_every_business_code_has_hint() -> void:
+	# get_script_constant_map 是 Script 的实例方法：经 preload 常量（类命名空间）
+	# 直呼会被 4.7 解析器判「对类调非静态函数」拒载，先落到 Script 类型变量再调。
+	var script_res: Script = ErrorCodes
+	var consts: Dictionary = script_res.get_script_constant_map()
+	for key: String in consts:
+		var value: Variant = consts[key]
+		if value is int and int(value) >= 1000 and int(value) < 2000:
+			assert_ne(
+				ErrorCodes.hint_for(int(value)),
+				"",
+				"业务码 %s(%d) 未登记 hint —— 新码必须同时登记下一步提示" % [key, value]
+			)
+
+
+func test_unknown_code_returns_empty() -> void:
+	assert_eq(ErrorCodes.hint_for(4242), "")
+
+
+func test_method_unknown_hints_init_resync() -> void:
+	# -32601 = client/addon 版本漂移，指引重跑 init 同步
+	assert_string_contains(ErrorCodes.hint_for(-32601), "init")
+
+
+func test_invalid_params_has_no_hint() -> void:
+	# -32602 每个 case 的 message 已带专属文案，不加统一 hint（避免复述）
+	assert_eq(ErrorCodes.hint_for(-32602), "")

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/tests/gut/test_game_bridge.gd

@@ -338,6 +338,23 @@ func test_sync_handler_error_dict_emits_error_frame() -> void:
 	assert_eq(str(f.error.message), "Node not found")
 
 
+func test_error_frame_carries_hint_for_registered_code() -> void:
+	# _send_error 是所有错误响应的唯一出口：已登记的码必须带 "hint"（下一步指引）
+	_low.click_return = {"error": {"code": 1001, "message": "Node not found"}}
+	_send('{"id": "x", "method": "click", "params": {"path": "/missing"}}')
+	var f: Dictionary = _last_frame()
+	assert_has(f.error, "hint")
+	assert_string_contains(str(f.error.hint), "find")
+
+
+func test_error_frame_omits_hint_for_unregistered_code() -> void:
+	# -32600 未登记 hint —— 不带空字段占位（信封字段有值才出现）
+	_send('not json at all')
+	var f: Dictionary = _last_frame()
+	assert_eq(int(f.error.code), -32600)
+	assert_does_not_have(f.error, "hint")
+
+
 # ── async 路径 ────────────────────────────────────────────────────
 
 func test_async_handler_success_emits_result_frame() -> void:

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/addons/godot_cli_control/tests/gut/test_low_level_api.gd

@@ -1395,6 +1395,72 @@ func test_find_nodes_from_scopes_search_to_subtree() -> void:
 	assert_string_contains(str((matches[0] as Dictionary).get("name")), "@Button@")
 
 
+# ── handle_click 过滤器定位（原子 find+click） ────────────────────
+
+
+func _find_fixture_button(text: String) -> Button:
+	for child: Node in (_target.get_node("Panel") as Node).get_children():
+		if child is Button and (child as Button).text == text:
+			return child as Button
+	return null
+
+
+func test_click_by_text_clicks_unique_match() -> void:
+	_build_find_fixture()
+	var btn: Button = _find_fixture_button("开始游戏")
+	assert_not_null(btn)
+	watch_signals(btn)
+	var result: Dictionary = _api.handle_click({
+		"from": str(_target.get_path()), "text": "开始游戏",
+	})
+	assert_does_not_have(result, "error")
+	assert_eq(result.get("success"), true)
+	assert_eq(
+		str(result.get("path")), str(btn.get_path()),
+		"信封应带实际点到的节点路径（agent 可缓存复用）"
+	)
+	assert_signal_emitted(btn, "pressed")
+
+
+func test_click_by_filters_zero_matches_is_1001() -> void:
+	_build_find_fixture()
+	var result: Dictionary = _api.handle_click({
+		"from": str(_target.get_path()), "text": "不存在的按钮文案",
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1001)
+
+
+func test_click_by_filters_multiple_matches_is_1017_listing_paths() -> void:
+	_build_find_fixture()
+	# type=BaseButton 命中两个按钮 → 歧义必须 fail-loud（BFS 序不可预期，
+	# 静默点第一个可能点错），message 列出候选路径供 agent 收窄
+	var result: Dictionary = _api.handle_click({
+		"from": str(_target.get_path()), "type": "BaseButton",
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), 1017)
+	assert_string_contains(str(result.error.message), "@Button@")
+
+
+func test_click_path_plus_filters_is_invalid_params() -> void:
+	_build_find_fixture()
+	var result: Dictionary = _api.handle_click({
+		"path": str(_target.get_path()), "text": "开始游戏",
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+
+
+func test_click_by_filters_invalid_combo_propagates_find_validation() -> void:
+	# 过滤器校验复用 find 侧：text 与 text_contains 互斥（-32602）
+	var result: Dictionary = _api.handle_click({
+		"text": "a", "text_contains": "b",
+	})
+	assert_has(result, "error")
+	assert_eq(int(result.error.code), -32602)
+
+
 # ── _mark_screenshot_stale_check (#156 子问题 B / B3) ────────────────
 
 func test_stale_check_first_call_not_stale() -> void:

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/python/README.md

@@ -25,9 +25,9 @@ godot-cli-control tree 3
 godot-cli-control daemon stop
 ```
 
-Re-running `init` refreshes both `addons/godot_cli_control/` and the SKILL.md files to match the installed CLI version (the plugin directory is wiped and re-copied; `project.godot` patching stays idempotent). Pass `--keep-addon` to keep an existing `addons/godot_cli_control/` untouched.
+Re-running `init` refreshes both `addons/godot_cli_control/` and the skill files to match the installed CLI version (the plugin directory is wiped and re-copied; `project.godot` patching stays idempotent). Pass `--keep-addon` to keep an existing `addons/godot_cli_control/` untouched.
 
-`init` also writes `.claude/skills/godot-cli-control/SKILL.md` and `.codex/skills/godot-cli-control/SKILL.md` so AI agents working in your Godot project can pick up this CLI surface automatically. Use `--no-skills` to skip, or `--skills-only` to refresh just those files after a CLI upgrade. See the [top-level README](../README.md#agent-integration) for details.
+`init` also writes `.claude/skills/godot-cli-control/` and `.codex/skills/godot-cli-control/` (a lean `SKILL.md` core + `references/*.md` detail files) so AI agents working in your Godot project can pick up this CLI surface automatically without flooding their context. Use `--no-skills` to skip, or `--skills-only` to refresh just those files after a CLI upgrade. See the [top-level README](../README.md#agent-integration) for details.
 
 ## Async API
 

{godot_cli_control-0.4.2 → godot_cli_control-0.5.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.4.2'
-__version_tuple__ = version_tuple = (0, 4, 2)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.4.2 → godot_cli_control-0.5.0}/python/godot_cli_control/bridge.py

@@ -139,9 +139,28 @@ class GameBridge:
 
     # ── UI 交互 ──
 
-    def click(self, path: str) -> dict:
-        """点击 UI 节点。"""
-        return self._run(self._client.click(path))
+    def click(
+        self,
+        path: str | None = None,
+        *,
+        node_type: str | None = None,
+        text: str | None = None,
+        text_contains: str | None = None,
+        name_pattern: str | None = None,
+        from_path: str | None = None,
+    ) -> dict:
+        """点击 UI 节点：给 ``path`` 直接定位，或给 find 同款过滤器由服务端
+        同帧原子 find+click（恰好 1 个匹配才点：0 个 → 1001，≥2 个 → 1017）。"""
+        return self._run(
+            self._client.click(
+                path,
+                node_type=node_type,
+                text=text,
+                text_contains=text_contains,
+                name_pattern=name_pattern,
+                from_path=from_path,
+            )
+        )
 
     def click_at(
         self,