Improve Unity command discovery and preflight

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 .pkg-cache.json
 .catalog-cache.json
 skills/unity-cli-command/dynamic-commands.md
+skills/*-workspace/
 docs
 tests/
 cc-codex-discussion-history/

AGENTS.md

@@ -50,8 +50,17 @@ cache the resolved package lazily, so setup is a convenience rather than a gate.
 ### Command-first principle
 
 Prefer `cs command` whenever a built-in framework command covers the task. Use
-`cs list-commands --json` to discover commands, then check the snippet library
-(`cs snippets`) before falling back to ad-hoc `cs exec`.
+`cs list-commands --offline --domain <domain> --tier core --json` to discover a
+small committed contract set without connecting to Unity. Query the matching
+advanced tier only when needed; remove `--offline` to verify the installed
+package's live registry. Then check the snippet library (`cs snippets`) before
+falling back to ad-hoc `cs exec`.
+
+Recognized built-in requests are preflighted from the committed manifest before
+HTTP dispatch. Unknown arguments, missing requirements, invalid types/ranges,
+ambiguous selectors, empty mutations, blocked actions, and missing explicit
+session ids fail without executing Unity. Project-defined custom commands pass
+through because their contracts are project-specific.
 
 ### Command map
 
@@ -64,7 +73,8 @@ Prefer `cs command` whenever a built-in framework command covers the task. Use
 | `cs batch --input FILE --json` | post | Run multiple commands in one request |
 | `cs health` | post | Check service health |
 | `cs refresh [--wait TIMEOUT] [--exit-playmode]` | post | Refresh assets and compile |
-| `cs list-commands --json` | post | Discover available commands |
+| `cs list-commands --offline … --json` | pre/post | Discover committed contracts by domain/tier/id |
+| `cs list-commands … --json` | post | Inspect the installed package's live registry |
 | `cs catalog sync` / `cs catalog list` | post | Maintain the custom-command catalog |
 | `cs snippets …` | post | Browse, run, and maintain reusable snippets |
 
@@ -85,8 +95,10 @@ package so client and service versions stay aligned:
 2. `Library/PackageCache/com.zh1zh1.csharpconsole@*/Editor/ExternalTool~/console-client/`.
 
 `ConsoleSession` wires the core client, command protocol, configuration, output,
-response parser, and HTTP transport into the CLI operations. Transport failures are
-retried once after one second to tolerate Unity domain reloads.
+response parser, and HTTP transport into the CLI operations. Clearly refused
+connections are retried once after one second to tolerate Unity domain reloads.
+Timeouts, HTTP errors, and connection resets are not retried because a mutation may
+already have executed.
 
 ### Version and machine-local state
 
@@ -108,6 +120,8 @@ retried once after one second to tolerate Unity domain reloads.
 skills/unity-cli/SKILL.md                 Skill entry and routing
 skills/unity-cli/references/*.md          Topic-specific operating guidance
 skills/unity-cli/scripts/cli/cs.py        CLI dispatcher
+skills/unity-cli/scripts/cli/command_index.py
+skills/unity-cli/scripts/cli/command_manifest.json
 skills/unity-cli/scripts/cli/core_bridge.py
 skills/unity-cli/scripts/cli/paths.py     Per-project cache paths
 skills/unity-cli/scripts/cli/VERSION      Release version

README.md

@@ -6,10 +6,10 @@
 **Powered by [unity-csharpconsole](https://github.com/niqibiao/unity-csharpconsole)**
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Unity](https://img.shields.io/badge/Unity-2022.3%2B-black.svg?logo=unity)](https://unity.com/)
+[![Unity](https://img.shields.io/badge/Unity-2022-black.svg?logo=unity)](https://unity.com/)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-blueviolet.svg?logo=anthropic)](https://claude.ai/code)
 
-40+ commands for scene editing, components, assets, screenshots, profiling, and more.<br/>
+59 built-in command contracts; 57 are routable for scene editing, components, assets, screenshots, profiling, and more.<br/>
 Depends on **[unity-csharpconsole](https://github.com/niqibiao/unity-csharpconsole)** — a Roslyn-powered interactive C# REPL for Unity.
 
 [Quick Start](#-quick-start) · [Usage](#-usage) · [Commands](#-commands) · [Custom Commands](#-custom-commands) · [Architecture](#️-architecture)
@@ -57,7 +57,7 @@ npx skills add niqibiao/unity-cli-skill --copy
 
 In your AI agent, run **`unity-cli setup`**.
 
-**Prerequisites:** a skills-compatible agent (e.g. [Claude Code](https://claude.ai/code) or [Codex CLI](https://github.com/openai/codex) 0.139+), Node.js (for `npx`), Unity 2022.3+, Python 3.7+
+**Prerequisites:** a skills-compatible agent (e.g. [Claude Code](https://claude.ai/code) or [Codex CLI](https://github.com/openai/codex) 0.139+), Node.js (for `npx`), Unity 2022, Python 3.7+
 
 ### 💬 Usage
 
@@ -91,7 +91,10 @@ operation, and the agent triggers it automatically (in any skills-compatible age
 
 ### 📦 Commands
 
-50 built-in commands across 13 namespaces. All commands support `--json` output.
+59 built-in contracts across 13 wire namespaces. 57 are routable by default;
+`editor/menu.open` and `editor/window.open` are retained but blocked because their
+noninteractive UI effects cannot be verified reliably. Structured command results
+are available through `cs command --json`.
 
 #### gameobject
 
@@ -143,6 +146,9 @@ operation, and the agent triggers it automatically (in any skills-compatible age
 | `create`      | Create a prefab asset from a scene GameObject |
 | `instantiate` | Instantiate a prefab into the active scene    |
 | `unpack`      | Unpack a prefab instance                      |
+| `asset_get` / `asset_hierarchy` | Inspect GameObjects and hierarchy inside a prefab asset |
+| `asset_add_component` / `asset_get_component` / `asset_modify_component` / `asset_remove_component` | Read and edit components directly in a prefab asset |
+| `asset_add_gameobject` / `asset_modify_gameobject` / `asset_remove_gameobject` | Add, edit, or remove GameObjects directly in a prefab asset |
 
 
 #### material
@@ -184,8 +190,8 @@ operation, and the agent triggers it automatically (in any skills-compatible age
 | `playmode.status` | Get current play mode state         |
 | `playmode.enter`  | Enter play mode                     |
 | `playmode.exit`   | Exit play mode                      |
-| `menu.open`       | Execute a menu item by path         |
-| `window.open`     | Open an editor window by type name  |
+| `menu.open`       | Retained contract; blocked for agent execution (noninteractive UI) |
+| `window.open`     | Retained contract; blocked for agent execution (noninteractive UI) |
 | `console.clear`   | Clear the editor console            |
 | `console.mark`    | Write a searchable marker to the editor log |
 
@@ -269,9 +275,9 @@ AI Agent                         Unity Editor
 │                  │            │  │  └─ REPL Executor  │  │
 │  Python CLI      │            │  └────────────────────┘  │
 │  ┌────────────┐  │            │                          │
-│  │ cs.py      │  │            │  40+ CommandActions      │
+│  │ cs.py      │  │            │  59 command contracts    │
 │  │ core_bridge│  │            │  (GameObject, Component, │
-│  └────────────┘  │            │   Prefab, Material, ...) │
+│  └────────────┘  │            │   57 routable by agents) │
 └──────────────────┘            └──────────────────────────┘
 ```
 
@@ -301,4 +307,4 @@ Auto-detects project root and service port. No manual configuration.
 
 ---
 
-If this skill saves you time, consider giving it a star. It helps others find it.
+If this skill saves you time, consider giving it a star. It helps others find it.

README_zh.md

@@ -6,10 +6,10 @@
 **基于 [unity-csharpconsole](https://github.com/niqibiao/unity-csharpconsole)**
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Unity](https://img.shields.io/badge/Unity-2022.3%2B-black.svg?logo=unity)](https://unity.com/)
+[![Unity](https://img.shields.io/badge/Unity-2022-black.svg?logo=unity)](https://unity.com/)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-blueviolet.svg?logo=anthropic)](https://claude.ai/code)
 
-40+ 命令覆盖场景编辑、组件、资产、截图、性能分析等。<br/>
+内置 59 份命令契约，其中 57 份可供 Agent 路由，覆盖场景编辑、组件、资产、截图、性能分析等。<br/>
 依赖 **[unity-csharpconsole](https://github.com/niqibiao/unity-csharpconsole)** — 基于 Roslyn 的 Unity 交互式 C# REPL。
 
 [快速开始](#-快速开始) · [使用方式](#-使用方式) · [命令](#-命令) · [自定义命令](#-自定义命令) · [架构](#️-架构)
@@ -56,7 +56,7 @@ npx skills add niqibiao/unity-cli-skill --copy
 
 在 AI Agent 里运行 **`unity-cli setup`**。
 
-**前置条件：** 一个兼容 skills 的 Agent（如 [Claude Code](https://claude.ai/code) 或 [Codex CLI](https://github.com/openai/codex) 0.139+）、Node.js（用于 `npx`）、Unity 2022.3+、Python 3.7+
+**前置条件：** 一个兼容 skills 的 Agent（如 [Claude Code](https://claude.ai/code) 或 [Codex CLI](https://github.com/openai/codex) 0.139+）、Node.js（用于 `npx`）、Unity 2022、Python 3.7+
 
 ### 💬 使用方式
 
@@ -90,7 +90,9 @@ Claude 会自动选择合适的命令，或在需要时编写 C# 代码。
 
 ### 📦 命令
 
-13 个命名空间、50 个内置命令。所有命令支持 `--json` 输出。
+13 个协议命名空间、59 份内置命令契约。其中 57 份默认可路由；
+`editor/menu.open` 与 `editor/window.open` 因非交互式 UI 效果无法可靠验证而保留但禁用。
+结构化命令结果通过 `cs command --json` 返回。
 
 #### gameobject
 
@@ -142,6 +144,9 @@ Claude 会自动选择合适的命令，或在需要时编写 C# 代码。
 | `create`      | 从场景中的 GameObject 创建 Prefab 资产 |
 | `instantiate` | 将 Prefab 实例化到当前场景             |
 | `unpack`      | 解包 Prefab 实例                  |
+| `asset_get` / `asset_hierarchy` | 检查 Prefab 资产内的 GameObject 与层级 |
+| `asset_add_component` / `asset_get_component` / `asset_modify_component` / `asset_remove_component` | 直接读取和编辑 Prefab 资产中的组件 |
+| `asset_add_gameobject` / `asset_modify_gameobject` / `asset_remove_gameobject` | 直接添加、编辑或移除 Prefab 资产中的 GameObject |
 
 
 #### material
@@ -183,8 +188,8 @@ Claude 会自动选择合适的命令，或在需要时编写 C# 代码。
 | `playmode.status` | 获取当前 Play Mode 状态     |
 | `playmode.enter`  | 进入 Play Mode          |
 | `playmode.exit`   | 退出 Play Mode          |
-| `menu.open`       | 按路径执行菜单项              |
-| `window.open`     | 按类型名打开编辑器窗口           |
+| `menu.open`       | 保留契约；Agent 执行已禁用（非交互式 UI） |
+| `window.open`     | 保留契约；Agent 执行已禁用（非交互式 UI） |
 | `console.clear`   | 清空编辑器控制台              |
 | `console.mark`    | 向编辑器日志写入可搜索标记         |
 
@@ -268,9 +273,9 @@ AI Agent                         Unity Editor
 │                  │            │  │  └─ REPL 执行器     │  │
 │  Python CLI      │            │  └────────────────────┘  │
 │  ┌────────────┐  │            │                          │
-│  │ cs.py      │  │            │  40+ CommandActions      │
+│  │ cs.py      │  │            │  59 command contracts    │
 │  │ core_bridge│  │            │  (GameObject, Component, │
-│  └────────────┘  │            │   Prefab, Material, ...) │
+│  └────────────┘  │            │   Agent 可路由 57 份)     │
 └──────────────────┘            └──────────────────────────┘
 ```
 
@@ -300,4 +305,4 @@ AI Agent                         Unity Editor
 
 ---
 
-如果这个 skill 对你有帮助，请给个 Star，让更多人发现它。
+如果这个 skill 对你有帮助，请给个 Star，让更多人发现它。