@kevlns/u-cli-mod 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -1,13 +1,29 @@
1
- # u-cli-mod Agent 使用规范
1
+ # Vant Unity 工程工具 Agent 规范
2
+
3
+ ## 定位
4
+
5
+ 按 Unity Editor 精确版本定位工具链,校验和安装 com.unity.pipeline,并执行工程命令。
6
+
7
+ ## 调用流程
8
+
9
+ ```sh
10
+ u-cli-mod routes
11
+ u-cli-mod doctor <工程目录>
12
+ u-cli-mod setup <工程目录>
13
+ ```
14
+
15
+ 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
16
+
17
+ ## 调用规范
2
18
 
3
19
  > 本文件是 AI Agent 调用本工具的规范正本。参数全集以 `u-cli-mod <命令> --help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe unity`)为准;本文件只锁定使用场景、调用规范与典型流程。
4
20
 
5
- ## 何时使用
21
+ ### 何时使用
6
22
 
7
23
  - Windows 主机上,需要按**精确 Unity Editor 版本**(版本号 + revision 双重匹配)对 Unity 工程执行:体检诊断、下载固定版本 Unity CLI、事务式安装适配版 `com.unity.pipeline`、执行 Unity Pipeline 命令。
8
- - 命令名 `unity`(经 v-cli 路由:`v-cli unity …`;独立安装时为 `u-cli-mod …`)。
24
+ - 命令名 `unity`(经 v-cli 路由:`v-cli unity …`;直接安装时为 `u-cli-mod …`)。
9
25
 
10
- ## 核心命令速览
26
+ ### 核心命令速览
11
27
 
12
28
  - `u-cli-mod doctor <project>` - 只读体检:路由匹配 / CLI 状态 / 适配包状态
13
29
  - `u-cli-mod setup <project>` - CLI + 适配包一键就绪(推荐首次入口)
@@ -18,19 +34,19 @@
18
34
 
19
35
  Pipeline 命令全集见文末「Pipeline 工具清单」(适配版 `com.unity.pipeline`,按领域分组)。
20
36
 
21
- ## 使用规范(Agent 必须遵守)
37
+ ### 使用规范(Agent 必须遵守)
22
38
 
23
39
  1. **首次对某工程执行 `exec` 前**,必须检查 `doctor` 的 `cli.state="valid"`、`pipeline.state="current"` 且 `pipeline.installed=true`。`doctor` 退出成功仅表示诊断完成,不代表工程已就绪;`pipeline.present=true` 也只表示包存在。`missing` 时先跑 `setup`;`outdated`/`invalid` 时先关闭目标 Editor,再通过 `pipeline install <project> --force` 备份并更新。升级 npm 包不会自动更新工程内适配包,不要直接 `exec`。
24
40
  2. **禁止在 `exec` 参数中传入任何 `--project-path` 变体**(`-projectPath`、`--project_path`、大小写混合、`=` 形式等)——目标工程由工具统一绑定,传入即报错是预期保护,不要尝试绕过。
25
- 3. **运行中的 Unity Editor 是 fail-closed**:安装被阻止时引导用户先关闭目标工程的 Editor;除非用户显式要求,不得使用 `--allow-running-editor` 绕过。
41
+ 3. **运行中的 Unity Editor 是 校验失败时拒绝执行**:安装被阻止时引导用户先关闭目标工程的 Editor;除非用户显式要求,不得使用 `--allow-running-editor` 绕过。
26
42
  4. **安装是事务式的**(staging → 校验 → 备份 → 替换 → 再校验 → receipt,失败自动回滚):不要手动清理工程内 `Packages/com.unity.pipeline` 或 `Library/editor-pipeline-cli`。
27
43
  5. **版本路由是精确匹配**(`m_EditorVersion` + revision 同时一致),没有"就近版本"回退;工程版本不在路由表内时如实报告支持列表,不得猜测、不得改写 `ProjectVersion.txt`。
28
44
  6. `exec` 每次调用前都会重新校验 CLI 哈希(防篡改),属正常行为;校验失败按提示跑 `u-cli-mod cli install --force` 修复即可。
29
- 7. **读取 Editor 当前 Console 首选 `command read_console`**,`get_console_logs` 是兼容别名;`command console` 读取回调捕获流,适合 `since`/cursor 跟随,但不能代替原生 Console 快照。工具必须经 `command <名>` 调用。若实际 schema 中缺少 `read_console`,先检查 `doctor` 的 `patchVersion`/`installedPatchVersion` 和 `state`,不要将其误认成 `console` 的别名。
45
+ 7. **读取 Editor 当前 Console 首选 `command read_console`**,`command console` 读取回调捕获流,适合 `since`/cursor 跟随,但不能代替原生 Console 快照。工具必须经 `command <名>` 调用。若实际 schema 中缺少 `read_console`,先检查 `doctor` 的 `patchVersion`/`installedPatchVersion` 和 `state`,不要将其误认成 `console` 的别名。
30
46
  8. **全量测试必须走 `--async_tests`**:Unity CLI 对同步命令有 30 秒硬性等待上限(`--timeout` 无法延长),同步 `run_tests` 全量必然超时且不入 `test_status` 跟踪。用法:`run_tests --mode EditMode --async_tests`(立即返回)→ 轮询 `test_status` 至 `completed` 拿完整 Summary;小范围用 `--filter` 缩到单命名空间/类,可直接同步等待拿 Summary。
31
- 9. **任务身份(patchVersion 3)**:`run_tests --async_tests` 的响应含 `RunId`;`test_status --run_id <id>` 只返回该次运行的记录(不存在/被顶替时返回 `unknown_run`,**绝不回退最近一次**);`cancel_tests --run_id <id>` 定向取消(不匹配或无活动运行返回 `unknown_run`/`no_active_run` 且零副作用)。`recompile` 响应含 `runId`,`recompile_status --run_id <id>` 同语义(引擎自发编译的终态 `runId` 为 null,按 id 查询即 `unknown_run`)。连续两次 `run_tests` 会顶替旧运行的追踪槽位——旧 id 的查询会得到 `unknown_run` 而不是新运行的报告。已知限制:`recompile` 连发时后发 runId 会覆盖 pending id,前一编译批次的引擎事件终态记在后发 id 名下(旧 id 查询 `unknown_run` 正确拒绝);legacy 无参 `cancel_tests` 保持原行为(会覆写最近一次状态记录)。
47
+ 9. **任务身份**:`run_tests --async_tests` 的响应含 `RunId`;`test_status --run_id <id>` 只返回该次运行的记录(不存在/被顶替时返回 `unknown_run`,**绝不回退最近一次**);`cancel_tests --run_id <id>` 定向取消(不匹配或无活动运行返回 `unknown_run`/`no_active_run` 且零副作用)。`recompile` 响应含 `runId`,`recompile_status --run_id <id>` 同语义(引擎自发编译的终态 `runId` 为 null,按 id 查询即 `unknown_run`)。连续启动会替换当前追踪槽位;无法关联的 run_id 返回 unknown_run,不能当作其他运行的结果。已知限制:`recompile` 连发时后发 runId 会覆盖 pending id,前一编译批次的引擎事件终态记在后发 id 名下(旧 id 查询 `unknown_run` 正确拒绝)。
32
48
 
33
- ## 典型流程
49
+ ### 典型流程
34
50
 
35
51
  ```bash
36
52
  u-cli-mod doctor <project> # 1. 体检(只读)
@@ -43,198 +59,210 @@ u-cli-mod exec <project> -- command read_console --types error,warning --count 1
43
59
 
44
60
  ### doctor 输出要点
45
61
 
46
- `doctor.pipeline` 的 `patchVersion` 为当前路由要求的补丁版本,`installedPatchVersion` 为 receipt 记录的版本(缺失或未知为 null);`state` 为 `missing | outdated | invalid | current`。完整 expected-tree 校验通过即返回 `installed=true` / `current`,receipt 缺失或陈旧不触发重装。`verification` 列出内容不匹配、校验错误及仅行尾差异的文件。已安装 UTF-8 文本允许 LF/CRLF 等价,其他内容及二进制仍严格校验;生成源与 staging 保持字节级校验,新生成文本统一 LF。`sourceReady=false` 仅表示生成缓存需重建,不代表已安装包失效。
62
+ `doctor.pipeline` 的 `patchVersion` 为当前路由要求的补丁版本,`installedPatchVersion` 为 receipt 记录的版本(缺失或未知为 null);`state` 为 `missing | outdated | invalid | current`。完整 expected-tree 校验通过即返回 `installed=true` / `current`,receipt 缺失或过期不触发重装。`verification` 列出内容不匹配、校验错误及仅行尾差异的文件。已安装 UTF-8 文本允许 LF/CRLF 等价,其他内容及二进制仍严格校验;生成源与 staging 保持字节级校验,新生成文本统一 LF。`sourceReady=false` 仅表示生成缓存需重建,不代表已安装包失效。
47
63
 
48
- ## Pipeline 工具清单
64
+ ### Pipeline 工具清单
49
65
 
50
66
  > 安装的 `com.unity.pipeline`(适配版 0.5.0-exp.1)共 **154** 个命令,经 `u-cli-mod exec <project> -- command <名> [参数]` 透传执行;参数全集以 `exec <project> -- command <名> --help` 为准。
51
67
 
52
- ### GameObject / 组件
53
- - `add_component` — Add a component (by type name) to a GameObject.
54
- - `create_gameobject` — Create an empty GameObject or a built-in primitive (cube/sphere/capsule/cylinder/plane/quad) in the active scene.
55
- - `create_gameobjects` — Batch-create N empty GameObjects or primitives in one call. Optional positions/rotations/scales are arrays of [x,y,z] (length must equal count). Returns the created identities.
56
- - `delete_gameobject` — Delete a GameObject from the scene (reversible via Undo).
57
- - `find_gameobjects` — Find GameObjects in loaded scenes by name, tag, component type, and/or hierarchy path (filters are combined). Returns structured identities.
58
- - `get_component_properties` — Get a component's serialized properties as a JSON map. Address the component by handle, or by GameObject handle + type.
59
- - `remove_component` — Remove a component from a GameObject. Provide either a component handle (target) or a GameObject handle (target) plus a type name.
60
- - `rename_gameobject` — Rename a GameObject.
61
- - `set_active` — Set a GameObject's active self-state (activeSelf).
62
- - `set_component_properties` — Set serialized properties on a component (one Undo step). 'properties' maps property name -> value; object references accept an ObjectRef handle.
63
- - `set_layer` — Set a GameObject's layer by name or numeric index (0-31).
64
- - `set_parent` — Reparent a GameObject under a new parent, or detach it to scene root when no parent is given.
65
- - `set_tag` — Set a GameObject's tag (the tag must already exist in the project).
66
- - `set_transform` — Set a GameObject's local position/rotation(euler)/scale. Omitted channels are left unchanged.
67
-
68
- ### 场景
69
- - `add_scene_to_build` — Add a scene to the Build Settings scene list (idempotent). Optionally enable it.
70
- - `create_scene` — Create a new scene and save it to the given path under the authoring root.
71
- - `get_scene_hierarchy` — Return the GameObject tree of an open scene (or the active scene). Each node carries instanceId + hierarchyPath usable by GameObject commands.
72
- - `list_open_scenes` — List all currently open scenes with their load/active/dirty state.
73
- - `open_scene` — Open an existing scene from the given path.
74
- - `remove_scene_from_build` — Remove a scene from the Build Settings scene list (idempotent).
75
- - `save_all` — Save all open scenes that have unsaved changes.
76
- - `save_scene` — Save an open scene. Saves the active scene when no path is given.
77
- - `set_active_scene` — Set which open scene is the active scene (new objects are created in the active scene).
78
-
79
- ### 资源 / 文件
80
- - `copy_asset` — Copy an asset to a new path under the authoring root. The copy gets a fresh GUID.
81
- - `create_asset` — Create a new ScriptableObject (or other UnityEngine.Object) asset of the given type at a path under the authoring root.
82
- - `create_folder` — Create a folder under the authoring root (creates intermediate folders).
83
- - `delete_asset` — Delete an asset from the project. Destructive: requires confirm=true.
84
- - `find_assets` — Find assets by type and/or name and/or label, returning their path, GUID and type. At least one filter is required.
85
- - `get_import_settings` — Read an asset's import settings, structured by importer type (texture/model/audio), including the default-platform fields and (for textures/audio) one platform override block.
86
- - `import_asset` — Import an external file (e.g. a texture, model, audio clip) into the project by copying it to a path under the authoring root, then importing it.
87
- - `move_asset` — Move (or rename via a new path) an asset to a new location under the authoring root. Preserves the asset's GUID.
88
- - `read_text_file` — Read a UTF-8 text file under the authoring root and return its contents.
89
- - `rename_asset` — Rename an asset in place (keeps it in the same folder, keeps its GUID).
90
- - `set_import_settings` — Set import settings on an asset's AssetImporter (default platform top-level properties, or a texture/audio per-platform override) and re-import it.
91
- - `write_text_file` — Write UTF-8 text to a file under the authoring root, then import it. Overwriting an existing file requires confirm=true.
92
-
93
- ### 预制体
94
- - `apply_prefab_overrides` — Apply a prefab instance's overrides back to its source prefab asset.
95
- - `create_prefab` — Save a GameObject as a prefab asset at a project path; the source becomes a connected instance.
96
- - `create_prefab_variant` — Create a prefab variant asset that inherits from a base prefab.
97
- - `instantiate_prefab` — Instantiate a prefab asset into a loaded scene and return the created instance.
98
- - `revert_prefab_overrides` — Revert a prefab instance's overrides so it matches its source prefab asset.
99
- - `save_prefab_contents` — Open a prefab asset in an isolated prefab stage, apply a declarative edit, and save it back (nested-prefab safe).
100
- - `unpack_prefab` — Unpack a prefab instance into plain GameObjects (outermost level or completely).
101
-
102
- ### 材质 / 着色器
103
- - `get_material_properties` — Read a material's shader, render queue, enabled keywords, and all shader properties with their current values (Color as [r,g,b,a], Vector as [x,y,z,w], Texture as an object reference).
104
- - `get_shader_properties` — Introspect a shader's declared property list (name, description, type Color|Vector|Float|Range|TexEnv|Int, range, textureDimension, flags). Provide 'shader' (by name) OR 'material' (read the shader off that material).
105
- - `list_shaders` — Discover available shaders so an agent can pick a valid name for set_material_properties / create_asset. Returns [{ name, assetPath|null, isBuiltin, isSupported }].
106
- - `set_material_properties` — Set shader properties on a material (Float/Range/Int=number; Color=[r,g,b,a] or "#RRGGBBAA" hex; Vector=[x,y,z,w]; Texture=an object reference or null to clear), optionally reassign the shader, set the render queue, and toggle keywords. Unknown names / type mismatches are reported in unknown[].
107
-
108
- ### 脚本 / 编译 / 求值
109
- - `attach_script` — Add a MonoBehaviour to a GameObject by its (compiled) type name OR by its script asset path. Provide exactly one of 'type' or 'script'. If the type isn't compiled yet, returns a recoverable error: recompile, poll recompile_status, then retry.
110
- - `cleanup_hotreload` — Remove old hot reload DLL versions and clear registry
111
- - `create_script` — Create a new C# script (default base class MonoBehaviour) from a template under the authoring root. NOTE: the type does not exist until a recompile completes — to attach it, call recompile, poll recompile_status, then attach_script.
112
- - `eval` — Evaluate C# code dynamically using Roslyn compiler
113
- - `eval_file` — Evaluate C# code read from a .cs file on disk
114
- - `get_serialized_fields` — Read serialized fields of a component/asset. Returns each top-level field's name, type and value (object references are returned as re-usable handles). Pass 'field' to read a single SerializedProperty path.
115
- - `hotreload_status` — Show current hot reload registry status and statistics
116
- - `recompile` — Force a script recompile (works while unfocused/minimized). Poll recompile_status for completion.
117
- - `recompile_status` — Get the status of the last recompile: idle | triggered | compiling | completed | up_to_date (optional run_id for correlated query).
118
- - `reload_file` — Compile and apply in-place [HotReload] edits from a source file
119
- - `reload_file_override` — Compile and apply hot reload file changes immediately
120
- - `set_serialized_field` — Set a serialized field on a component/asset. Supports primitives, enums, Vector/Color/Rect/Bounds, object references (value = an ObjectRef: asset by guid/fileId/path or scene object by instanceId/hierarchyPath), and array elements via 'name.Array.data[i]' (or 'name.Array.size' to resize).
121
-
122
- ### 动画 / Timeline
123
- - `add_animator_layer` — Add a layer to an AnimatorController.
124
- - `add_animator_parameter` — Add a parameter (Float | Int | Bool | Trigger) to an AnimatorController. A duplicate name returns code 'duplicate_parameter'.
125
- - `add_animator_state` — Add a state to a layer, optionally with a motion (AnimationClip or BlendTree) and as the layer default. A layer name with no match returns code 'layer_not_found'.
126
- - `add_animator_transition` — Add a transition between two states (or from AnyState/Entry, to Exit) on a layer, with optional conditions. Validates that the states exist and each condition's parameter exists and its mode matches the parameter type.
127
- - `add_timeline_clip` — Add a clip to a named track on a TimelineAsset. For Animation tracks pass an AnimationClip asset; for Audio tracks an AudioClip. Requires the com.unity.timeline package.
128
- - `add_timeline_track` — Add a track (Animation | Audio | Activation | Control | Playable | Signal | Marker) to a TimelineAsset, optionally nested under a parent group/track. Requires the com.unity.timeline package.
129
- - `create_animation_clip` — Create an empty .anim AnimationClip asset under the authoring root, with an optional frame rate and loop flag.
130
- - `create_animator_controller` — Create an .controller AnimatorController asset (with a default Base Layer) under the authoring root.
131
- - `create_timeline` — Create a .playable TimelineAsset under the authoring root (optional frame rate). Requires the com.unity.timeline package.
132
- - `get_animation_clip` — Read an AnimationClip's metadata and all float curve bindings (optionally with keyframes).
133
- - `get_animator_controller` — Read an AnimatorController's full structure: parameters, layers, states (with motion / default), and transitions (with conditions).
134
- - `get_timeline` — Read a TimelineAsset's structure: frame rate, duration, and its tracks with their clips. Requires the com.unity.timeline package.
135
- - `remove_animation_curve` — Remove a float curve binding from an AnimationClip (SetEditorCurve(clip, binding, null)). Destructive: requires confirm=true.
136
- - `set_animation_curve` — Add or replace a single float curve binding on an AnimationClip (via AnimationUtility.SetEditorCurve). Replacing an existing binding overwrites it rather than duplicating.
137
-
138
- ### 构建
139
- - `build` — Trigger an async Player build and report the full BuildReport. Returns immediately (queued); poll build_status until status is 'completed'. DetailedBuildReport is included by default unless 'options' is supplied. Use dry_run to validate without building.
140
- - `build_status` — Status of the current/most recent build: idle | queued | building | completed, with the full BuildReport (files, packedAssets, buildSteps, errors, warnings) once completed. Retained until the next build.
141
- - `get_build_settings` — Read the current build configuration from EditorUserBuildSettings / EditorBuildSettings.
142
- - `list_build_profiles` — List Build Profile assets in the project (Unity 6 only). Returns feature_unavailable on earlier versions.
143
- - `list_build_targets` — List the known BuildTarget values with their group and whether build support is installed.
144
- - `set_build_settings` — Set mutable EditorUserBuildSettings fields. Does NOT manage scenes (use add_scene_to_build / remove_scene_from_build) or switch target (use switch_build_target). Use dry_run to preview.
145
- - `switch_build_target` — Switch the active build target (destructive, long-running: triggers a full reimport + domain reload). Requires confirm=true. Returns immediately; poll switch_build_target_status.
146
- - `switch_build_target_status` — Status of the last target switch: idle | switching | completed (with success + activeBuildTarget).
147
-
148
- ### 包管理
149
- - `package_add` — Add a UPM package by name@version, git URL, or 'file:' local path. Async by default (returns in_progress; poll package_status); pass wait=true to block until added. A recompile/domain reload follows — poll recompile_status. Requires confirm=true; use dry_run to preview.
150
- - `package_list` — List packages by scope: installed (default) | available (registry) | all (both). Returns the full result synchronously — available/all block until the registry query completes.
151
- - `package_remove` — Remove a UPM package by name. Async by default (returns in_progress; poll package_status); pass wait=true to block until removed. A recompile/domain reload follows — poll recompile_status. Requires confirm=true; use dry_run to preview.
152
- - `package_resolve` — Resolve/refresh packages from the manifest (re-fetch and re-link). May trigger a recompile/domain reload — poll recompile_status. Its outcome is recorded for package_status.
153
- - `package_search` — Search packages available in the registry. Provide a name (e.g. com.unity.foo) or omit to list all. Returns the full result synchronously (blocks until the registry query completes).
154
- - `package_status` — Status of the last async package operation (add/remove/resolve): idle | in_progress | completed | failed, with the added package, manifest, and any error.
155
-
156
- ### 测试
157
- - `cancel_tests` — Cancel running test execution (optional run_id for directed cancel; mismatch = no side effects)
158
- - `list_tests` — List all available tests (EditMode and/or PlayMode) without running them
159
- - `run_tests` — Execute Unity tests with filtering options
160
- - `test_status` — Get status of running async test execution (optional run_id for correlated query; unknown_run otherwise)
161
-
162
- ### 烘焙(光照 / NavMesh / 遮挡)
163
- - `bake_lighting` — Trigger an async lightmap bake of the open scene(s) via Lightmapping.BakeAsync(). Returns immediately; poll lighting_bake_status until completed.
164
- - `bake_navmesh` — Trigger an async legacy NavMesh bake of the open scene(s) via UnityEditor.AI.NavMeshBuilder. Returns immediately; poll navmesh_bake_status until completed.
165
- - `bake_navmesh_surfaces` — Bake NavMeshSurface components (AI Navigation package). v1 stub: returns package_not_found when the package is absent.
166
- - `bake_occlusion_culling` — Trigger an async occlusion-culling bake of the open scene(s) via StaticOcclusionCulling.GenerateInBackground(). Returns immediately; poll occlusion_bake_status until completed.
167
- - `cancel_lighting_bake` — Cancel an in-progress lighting bake (Lightmapping.Cancel()).
168
- - `cancel_navmesh_bake` — Cancel an in-progress NavMesh bake (NavMeshBuilder.Cancel()).
169
- - `cancel_occlusion_bake` — Cancel an in-progress occlusion bake (StaticOcclusionCulling.Cancel()).
170
- - `clear_baked_lighting` — Clear baked lightmap data for the open scene(s). Destructive: requires confirm=true.
171
- - `clear_navmesh` — Clear the baked NavMesh for the open scene(s). Destructive: requires confirm=true.
172
- - `clear_occlusion_culling` — Clear baked occlusion-culling data for the open scene(s). Destructive: requires confirm=true.
173
- - `get_lighting_settings` — Read the active LightingSettings (lightmapper, bounces, resolution, directional mode, AO, etc.).
174
- - `get_navmesh_settings` — Read the default agent's legacy NavMesh bake settings (agentRadius/Height/Slope/Climb, minRegionArea, voxelSize).
175
- - `lighting_bake_status` — Get the status of the last lighting bake: idle | baking | completed.
176
- - `navmesh_bake_status` — Get the status of the last NavMesh bake: idle | baking | completed.
177
- - `occlusion_bake_status` — Get the status of the last occlusion bake: idle | baking | completed.
178
- - `set_lighting_settings` — Apply a subset of lighting settings to the active LightingSettings. Returns { applied[], unknown[] }.
179
- - `set_navmesh_settings` — Apply a subset of legacy NavMesh bake settings to the default agent. Returns { applied[], unknown[] }.
180
-
181
- ### 截图 / 捕获
182
- - `capture_editor_element` — Capture a UI Toolkit VisualElement (by selector) from an EditorWindow to a PNG; returns path + base64.
183
- - `capture_game_view` — Render the game view to a PNG. source=camera (default) renders a camera and misses Screen Space - Overlay UI; source=screen captures the composited backbuffer incl. overlay canvases (Play Mode only). Returns it inline as base64, unless save_path is set (path-only result; pass include_inline_image=true to get both).
184
- - `capture_runtime_element` — Capture a UI Toolkit VisualElement (by selector) from a live runtime panel (UIDocument or PanelRenderer) to a PNG; returns path + base64.
185
- - `capture_scene_view` — Render the active Scene View to a PNG. Returns it inline as base64, unless save_path is set (path-only result; pass include_inline_image=true to get both).
186
- - `screenshot` — Capture the Scene or Game view as a PNG and return its file path
187
-
188
- ### 编辑器控制
189
- - `editor_focus` — Bring the Unity Editor window to the foreground
190
- - `editor_pause` — Toggle pause state of Unity Editor play mode
191
- - `editor_play` — Enter Unity Editor play mode
192
- - `editor_status` — Get detailed Unity Editor status and state information
193
- - `editor_stop` — Exit Unity Editor play mode
194
- - `menu` — Execute an Editor menu item by path, or list available items when no path is given
195
- - `set_autotick` — Keep the editor ticking while unfocused by forcing EditorApplication.SignalTick at a throttled rate
196
-
197
- ### 可观测性 / 审计
198
- - `audit` — Run a Project Auditor static-analysis scan. Returns immediately; poll audit_status until status is 'completed', then read the CSV.
199
- - `audit_status` — Get the status of the last audit: idle | scanning | completed | failed | interrupted | unavailable.
200
- - `clear_console` — Clear the Unity Editor Console and all captured pipeline console buffers.
201
- - `console` — Get captured Unity console output (Editor or Player; supports tail, level filtering, and follow via a cursor)
202
- - `get_console_logs` — Read the current Unity Editor Console (compatibility alias for read_console).
203
- - `read_console` — Read or clear the current Unity Editor Console, including entries emitted before command initialization; supports type/text filtering, paging, formatting, and stack traces.
204
- - `get_performance_stats` — Read render, memory, and frame-timing stats (structured, read-only).
205
- - `log` — Write a message to Unity console
206
-
207
- ### 项目设置
208
- - `get_audio_settings` — Read project Audio settings (volume, rolloff scale, doppler factor).
209
- - `get_graphics_settings` — Read GraphicsSettings (default render pipeline).
210
- - `get_input_settings` — Read the legacy Input Manager axes (names and count).
211
- - `get_physics_settings` — Read Physics settings (gravity, solver iterations, bounce threshold).
212
- - `get_player_settings` — Read PlayerSettings (company/product/version, scripting backend, API level).
213
- - `get_quality_settings` — Read QualitySettings (current level, level names, vSync, anti-aliasing).
214
- - `get_tags_layers` — Read the project's tags and (named) layers.
215
- - `get_time_settings` — Read Time settings (fixedDeltaTime, maximumDeltaTime, timeScale).
216
- - `set_audio_settings` — Change project Audio settings. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
217
- - `set_graphics_settings` — Set the default render pipeline asset. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
218
- - `set_input_settings` — Tune a legacy Input Manager axis (sensitivity/gravity/dead) by name. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
219
- - `set_physics_settings` — Change Physics settings. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
220
- - `set_player_settings` — Change PlayerSettings. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z. Scripting backend / API level changes trigger a domain reload.
221
- - `set_quality_settings` — Change QualitySettings. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
222
- - `set_tags_layers` — Add/remove tags and assign user layer names (index 8-31). Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
223
- - `set_time_settings` — Change Time settings. Requires confirm=true; use dry_run to preview. Not undoable via Ctrl+Z.
224
-
225
- ### 运行时 / 输入模拟
226
- - `quit` — Gracefully quit the Unity application
227
- - `runtime_status` — Get comprehensive runtime application status
228
- - `set_target_framerate` — Set the target frame rate for the application
229
- - `set_timescale` — Set the time scale for the application
230
- - `simulate_key` — Simulate a keyboard key event (Input System). Drives the running app.
231
- - `simulate_pointer` — Simulate a mouse/pointer event at screen coordinates (Input System).
232
-
233
- ### 选择 / 搜索
234
- - `get_selection` — Read the current Editor selection as structured object identities.
235
- - `search` — Run a Unity Search query and return structured results.
236
- - `set_selection` — Set the Editor selection to the given assets/scene objects.
237
-
238
- ### Authoring 根路径
239
- - `get_authoring_root` — Get the base folder (under Assets/) that bare authoring paths resolve against.
240
- - `set_authoring_root` — Set the base folder (under Assets/) that bare authoring paths resolve against and are confined to. Use 'Assets' for full project access.
68
+ #### GameObject / 组件
69
+ - `add_component` — 添加组件。
70
+ - `create_gameobject` — 创建场景对象。
71
+ - `create_gameobjects` — 批量创建场景对象。
72
+ - `delete_gameobject` — 删除场景对象,支持撤销。
73
+ - `find_gameobjects` — 按名称、标签、组件或层级路径查找场景对象。
74
+ - `get_component_properties` — 读取组件序列化属性。
75
+ - `remove_component` — 移除指定组件。
76
+ - `rename_gameobject` — 重命名场景对象。
77
+ - `set_active` — 设置对象激活状态。
78
+ - `set_component_properties` — 设置组件序列化属性,支持 ObjectRef 引用。
79
+ - `set_layer` — 设置对象层,编号范围 0–31。
80
+ - `set_parent` — 设置父对象;未指定父对象时移至场景根。
81
+ - `set_tag` — 设置工程中已存在的标签。
82
+ - `set_transform` — 设置局部坐标、欧拉旋转和缩放,省略项不变。
83
+
84
+ #### 场景
85
+ - `add_scene_to_build` — 将场景加入构建列表。
86
+ - `create_scene` — 创建并保存场景。
87
+ - `get_scene_hierarchy` — 读取场景层级及 instanceId、hierarchyPath。
88
+ - `list_open_scenes` — 列出已打开场景及加载、激活、未保存状态。
89
+ - `open_scene` — 打开场景。
90
+ - `remove_scene_from_build` — 从构建列表移除场景。
91
+ - `save_all` — 保存所有已修改场景和资源。
92
+ - `save_scene` — 保存场景。
93
+ - `set_active_scene` — 设置活动场景。
94
+
95
+ #### 资源 / 文件
96
+ - `copy_asset` — 复制资源。
97
+ - `create_asset` — 创建指定类型的资源。
98
+ - `create_folder` — 创建目录。
99
+ - `delete_asset` — 删除资源。需要 confirm=true。
100
+ - `find_assets` — 查找资源。
101
+ - `get_import_settings` — 读取资源导入设置。
102
+ - `import_asset` — 导入或重新导入资源。
103
+ - `move_asset` — 移动资源。
104
+ - `read_text_file` — 读取文本文件。
105
+ - `rename_asset` — 重命名资源。
106
+ - `set_import_settings` — 设置资源导入参数。
107
+ - `write_text_file` — 写入文本文件。需要 confirm=true。
108
+
109
+ #### 预制体
110
+ - `apply_prefab_overrides` — 将实例覆盖应用到预制体。
111
+ - `create_prefab` — 从场景对象创建预制体。
112
+ - `create_prefab_variant` — 创建预制体变体。
113
+ - `instantiate_prefab` — 将预制体实例化到场景。
114
+ - `revert_prefab_overrides` — 还原预制体实例覆盖。
115
+ - `save_prefab_contents` — 保存预制体内容。
116
+ - `unpack_prefab` — 解包预制体实例。
117
+
118
+ #### 材质 / 着色器
119
+ - `get_material_properties` — 读取材质属性。
120
+ - `get_shader_properties` — 读取着色器属性。
121
+ - `list_shaders` — 列出着色器。
122
+ - `set_material_properties` — 设置材质属性。
123
+
124
+ #### 脚本 / 编译 / 求值
125
+ - `attach_script` — 将脚本组件添加到对象。
126
+ - `cleanup_hotreload` — 清理热重载资源。
127
+ - `create_script` — 创建脚本文件。
128
+ - `eval` — 执行 C# 表达式或代码。
129
+ - `eval_file` — 执行文件中的 C# 代码。
130
+ - `get_serialized_fields` — 读取序列化字段。
131
+ - `hotreload_status` — 查询热重载状态。
132
+ - `recompile` — 触发编译并返回运行身份。
133
+ - `recompile_status` — 按 run_id 查询编译;无法关联时返回 unknown_run。
134
+ - `reload_file` — 重载脚本文件。
135
+ - `reload_file_override` — 重载脚本并明确应用覆盖。
136
+ - `set_serialized_field` — 设置序列化字段。
137
+
138
+ #### 动画 / Timeline
139
+ - `add_animator_layer` — 添加动画控制器层。
140
+ - `add_animator_parameter` — 添加动画参数。
141
+ - `add_animator_state` — 添加动画状态。
142
+ - `add_animator_transition` — 添加动画过渡。
143
+ - `add_timeline_clip` — 添加 Timeline 片段。
144
+ - `add_timeline_track` — 添加 Timeline 轨道。
145
+ - `create_animation_clip` — 创建动画片段。
146
+ - `create_animator_controller` — 创建动画控制器。
147
+ - `create_timeline` — 创建 Timeline。
148
+ - `get_animation_clip` — 读取动画片段。
149
+ - `get_animator_controller` — 读取动画控制器。
150
+ - `get_timeline` — 读取 Timeline。
151
+ - `remove_animation_curve` — 移除动画曲线。需要 confirm=true。
152
+ - `set_animation_curve` — 设置动画曲线。
153
+
154
+ #### 构建
155
+ - `build` — 执行构建。可用 dry_run 预演。
156
+ - `build_status` — 查询构建状态。
157
+ - `get_build_settings` — 读取构建设置。
158
+ - `list_build_profiles` — 列出构建配置。
159
+ - `list_build_targets` — 列出构建目标。
160
+ - `set_build_settings` — 设置构建参数。可用 dry_run 预演。
161
+ - `switch_build_target` — 切换构建目标。需要 confirm=true。
162
+ - `switch_build_target_status` — 查询构建目标切换结果。
163
+
164
+ #### 包管理
165
+ - `package_add` — 添加 UPM 包。需要 confirm=true。可用 dry_run 预演。异步操作查询 package_status;涉及编译时继续查询 recompile_status。
166
+ - `package_list` — 列出已安装或注册表中的 UPM 包。
167
+ - `package_remove` — 移除 UPM 包。需要 confirm=true。可用 dry_run 预演。异步操作查询 package_status;涉及编译时继续查询 recompile_status。
168
+ - `package_resolve` — 解析工程包依赖。异步操作查询 package_status;涉及编译时继续查询 recompile_status。
169
+ - `package_search` — 搜索注册表包。
170
+ - `package_status` — 查询包操作状态。
171
+
172
+ #### 测试
173
+ - `cancel_tests` — 按 run_id 取消测试;不匹配时不产生副作用。
174
+ - `list_tests` — 列出 EditMode 或 PlayMode 测试。
175
+ - `run_tests` — 按过滤条件执行测试;全量使用 --async_tests。
176
+ - `test_status` — 按 run_id 查询测试;无法关联时返回 unknown_run。
177
+
178
+ #### 烘焙(光照 / NavMesh / 遮挡)
179
+ - `bake_lighting` — 异步烘焙光照。
180
+ - `bake_navmesh` — 异步烘焙导航网格。
181
+ - `bake_navmesh_surfaces` — 烘焙 NavMeshSurface;缺少 AI Navigation 包时返回 package_not_found。
182
+ - `bake_occlusion_culling` — 异步烘焙遮挡剔除。
183
+ - `cancel_lighting_bake` — 取消光照烘焙。
184
+ - `cancel_navmesh_bake` — 取消导航网格烘焙。
185
+ - `cancel_occlusion_bake` — 取消遮挡剔除烘焙。
186
+ - `clear_baked_lighting` — 清理烘焙光照数据。需要 confirm=true。
187
+ - `clear_navmesh` — 清理导航网格。需要 confirm=true。
188
+ - `clear_occlusion_culling` — 清理遮挡剔除数据。需要 confirm=true。
189
+ - `get_lighting_settings` — 读取光照烘焙设置。
190
+ - `get_navmesh_settings` — 读取导航网格设置。
191
+ - `lighting_bake_status` — 查询光照烘焙状态。
192
+ - `navmesh_bake_status` — 查询导航网格烘焙状态。
193
+ - `occlusion_bake_status` — 查询遮挡剔除烘焙状态。
194
+ - `set_lighting_settings` — 设置光照烘焙参数,返回 applied 和 unknown。
195
+ - `set_navmesh_settings` — 设置导航网格参数。
196
+
197
+ #### 截图 / 捕获
198
+ - `capture_editor_element` — 截取编辑器 UI Toolkit 元素。
199
+ - `capture_game_view` — 截取游戏视图;source=screen 需要运行模式并包含叠加画布,source=camera 按相机渲染。设置 save_path 时默认只返回路径,include_inline_image=true 可同时返回图片。
200
+ - `capture_runtime_element` — 截取运行时 UI Toolkit 元素。
201
+ - `capture_scene_view` — 截取当前场景视图。设置 save_path 时默认只返回路径,include_inline_image=true 可同时返回图片。
202
+ - `screenshot` — 截取场景或游戏视图并返回文件路径。
203
+
204
+ #### 编辑器控制
205
+ - `editor_focus` — 激活 Unity Editor 窗口。
206
+ - `editor_pause` — 切换运行模式的暂停状态。
207
+ - `editor_play` — 进入运行模式。
208
+ - `editor_status` — 读取编辑器状态。
209
+ - `editor_stop` — 退出运行模式。
210
+ - `menu` — 执行或列出菜单项。
211
+ - `set_autotick` — 在窗口失焦时保持编辑器周期更新。
212
+
213
+ #### 可观测性 / 审计
214
+ - `audit` — 记录或查询编辑器审计信息。
215
+ - `audit_status` — 查询审计状态。
216
+ - `clear_console` — 清空 Console。
217
+ - `console` — 读取回调捕获的日志流,支持游标跟随。
218
+ - `get_console_logs` — 读取原生 Console 日志。
219
+ - `read_console` — 读取原生 Console 日志,按类型和数量过滤。
220
+ - `get_performance_stats` — 读取性能统计。
221
+ - `log` — 写入 Console 日志。
222
+
223
+ #### 项目设置
224
+ - `get_audio_settings` — 读取音频设置。
225
+ - `get_graphics_settings` — 读取图形设置。
226
+ - `get_input_settings` — 读取输入设置。
227
+ - `get_physics_settings` — 读取物理设置。
228
+ - `get_player_settings` — 读取应用设置。
229
+ - `get_quality_settings` — 读取质量设置。
230
+ - `get_tags_layers` — 读取标签与层。
231
+ - `get_time_settings` — 读取时间设置。
232
+ - `set_audio_settings` — 修改音频设置。需要 confirm=true。可用 dry_run 预演。
233
+ - `set_graphics_settings` — 修改图形设置。需要 confirm=true。可用 dry_run 预演。
234
+ - `set_input_settings` — 修改输入设置。需要 confirm=true。可用 dry_run 预演。
235
+ - `set_physics_settings` — 修改物理设置。需要 confirm=true。可用 dry_run 预演。
236
+ - `set_player_settings` — 修改应用设置。需要 confirm=true。可用 dry_run 预演。
237
+ - `set_quality_settings` — 修改质量设置。需要 confirm=true。可用 dry_run 预演。
238
+ - `set_tags_layers` — 修改标签与层。需要 confirm=true。可用 dry_run 预演。
239
+ - `set_time_settings` — 修改时间设置。需要 confirm=true。可用 dry_run 预演。
240
+
241
+ #### 运行时 / 输入模拟
242
+ - `quit` — 正常退出 Unity 应用。
243
+ - `runtime_status` — 读取运行时状态。
244
+ - `set_target_framerate` — 设置目标帧率。
245
+ - `set_timescale` — 设置时间缩放。
246
+ - `simulate_key` — 模拟键盘事件。
247
+ - `simulate_pointer` — 模拟指针事件。
248
+
249
+ #### 选择 / 搜索
250
+ - `get_selection` — 读取当前选择的对象身份。
251
+ - `search` — 执行 Unity Search 查询。
252
+ - `set_selection` — 设置当前选择。
253
+
254
+ #### Authoring 根路径
255
+ - `get_authoring_root` — 读取资源编辑根目录。
256
+ - `set_authoring_root` — 设置并约束资源编辑根目录。
257
+
258
+ ## 结果验证
259
+
260
+ 核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
261
+
262
+ ## 参考资料
263
+
264
+ [使用说明](README.md) · [文档规范](docs/documentation.md) · v-cli.plugin.json
265
+
266
+ ## 许可与版权
267
+
268
+ MIT。Copyright © 2026 Vant。
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 kevlns
3
+ Copyright © 2026 Vant
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -27,4 +27,4 @@ com.unity.pipeline package from Unity's official endpoints at runtime and
27
27
  applies compatibility patches locally. Those downloaded assets are governed by
28
28
  their own license terms (Unity Package Distribution License and Unity CLI
29
29
  terms). They are NOT distributed with this package and never land in this
30
- repository. This MIT license covers only the tool code in this repository.
30
+ repository. This MIT license covers only the tool code in this repository.