@kevlns/u-cli-mod 0.3.0 → 0.3.2
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 +13 -228
- package/LICENSE +2 -2
- package/README.md +37 -134
- package/dist/cli.js +1 -1
- package/docs/SELF_HOSTED_RUNNER.md +100 -0
- package/docs/documentation.md +24 -0
- package/package.json +9 -9
- package/skills/unity/SKILL.md +8 -0
- package/skills/unity/references/project.md +268 -0
- package/v-cli.plugin.json +245 -220
package/AGENTS.md
CHANGED
|
@@ -1,240 +1,25 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Vant Unity 工程开发规范
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## 定位
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
本文件仅指导维护 u-cli-mod 仓库。运行时技能正本为 skills/unity/SKILL.md;命令机器契约为 v-cli.plugin.json。
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- 命令名 `unity`(经 v-cli 路由:`v-cli unity …`;独立安装时为 `u-cli-mod …`)。
|
|
7
|
+
## 调用流程
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
修改前读取相关源文件与 package.json 中的检查命令,保留已有工作区改动。
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
- `u-cli-mod setup <project>` - CLI + 适配包一键就绪(推荐首次入口)
|
|
14
|
-
- `u-cli-mod pipeline install <project> --dry-run` - 安装预览(不写入工程)
|
|
15
|
-
- `u-cli-mod pipeline install <project>` - 事务式安装适配包(自动备份/回滚/receipt)
|
|
16
|
-
- `u-cli-mod exec <project> [--wait <秒>] -- <pipeline-args>` - 执行 Pipeline 命令(工具统一绑定 `--project-path`);长任务(`run_tests`)默认 5s 后让出控制权,结果用对应的 `command <name>_status` 轮询
|
|
17
|
-
- `u-cli-mod routes` / `u-cli-mod cache clean` - 路由表 / 缓存清理
|
|
11
|
+
## 调用规范
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
技能正文与 references 独立维护,不从本文件生成运行规范。修改命令时同步机器清单及生成的命令文档。宿主配置和状态使用 VANT_HOME(默认 ~/.vant),项目数据保留在工程 .vant;安装不扫描其他 Agent 目录。外部宿主仅显式适配。
|
|
20
14
|
|
|
21
|
-
##
|
|
15
|
+
## 结果验证
|
|
22
16
|
|
|
23
|
-
|
|
24
|
-
2. **禁止在 `exec` 参数中传入任何 `--project-path` 变体**(`-projectPath`、`--project_path`、大小写混合、`=` 形式等)——目标工程由工具统一绑定,传入即报错是预期保护,不要尝试绕过。
|
|
25
|
-
3. **运行中的 Unity Editor 是 fail-closed**:安装被阻止时引导用户先关闭目标工程的 Editor;除非用户显式要求,不得使用 `--allow-running-editor` 绕过。
|
|
26
|
-
4. **安装是事务式的**(staging → 校验 → 备份 → 替换 → 再校验 → receipt,失败自动回滚):不要手动清理工程内 `Packages/com.unity.pipeline` 或 `Library/editor-pipeline-cli`。
|
|
27
|
-
5. **版本路由是精确匹配**(`m_EditorVersion` + revision 同时一致),没有"就近版本"回退;工程版本不在路由表内时如实报告支持列表,不得猜测、不得改写 `ProjectVersion.txt`。
|
|
28
|
-
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` 的别名。
|
|
30
|
-
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` 保持原行为(会覆写最近一次状态记录)。
|
|
17
|
+
运行 package.json 中与改动相关的检查;区分单测、真实后端、界面和安装验证。不得将模拟结果报告为真实生图或发布成功。
|
|
32
18
|
|
|
33
|
-
##
|
|
19
|
+
## 参考资料
|
|
34
20
|
|
|
35
|
-
|
|
36
|
-
u-cli-mod doctor <project> # 1. 体检(只读)
|
|
37
|
-
u-cli-mod setup <project> # 2. 就绪(CLI + 适配包)
|
|
38
|
-
u-cli-mod exec <project> -- command editor_status # 3. 执行
|
|
39
|
-
u-cli-mod exec <project> -- command run_tests --mode EditMode --filter <命名空间或类名> # 小范围:同步返回 Summary
|
|
40
|
-
u-cli-mod exec <project> -- command run_tests --mode EditMode --async_tests # 全量:立即返回,轮询 test_status
|
|
41
|
-
u-cli-mod exec <project> -- command read_console --types error,warning --count 100
|
|
42
|
-
```
|
|
21
|
+
[使用说明](README.md) · [运行技能](skills/unity/SKILL.md)
|
|
43
22
|
|
|
44
|
-
|
|
23
|
+
## 许可与版权
|
|
45
24
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
## Pipeline 工具清单
|
|
49
|
-
|
|
50
|
-
> 安装的 `com.unity.pipeline`(适配版 0.5.0-exp.1)共 **154** 个命令,经 `u-cli-mod exec <project> -- command <名> [参数]` 透传执行;参数全集以 `exec <project> -- command <名> --help` 为准。
|
|
51
|
-
|
|
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.
|
|
25
|
+
MIT。Copyright © 2026 Vant。
|
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,60 +1,42 @@
|
|
|
1
|
-
|
|
1
|
+
# Vant Unity 工程工具
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@kevlns/u-cli-mod`
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 功能
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
按 Unity Editor 精确版本定位工具链,校验和安装 com.unity.pipeline,并执行工程命令。
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
[](https://www.npmjs.com/package/@kevlns/u-cli-mod)
|
|
11
|
-
[](https://github.com/kevlns/u-cli-mod/actions/workflows/ci.yml)
|
|
12
|
-
[](./LICENSE)
|
|
9
|
+
## 环境要求
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
Node.js 20 及以上、Windows 10 及以上;支持的 Editor 版本与 revision 由 routes 命令提供。
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
## 安装
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
```sh
|
|
16
|
+
npm install -g @kevlns/u-cli-mod
|
|
17
|
+
```
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
## 快速开始
|
|
21
20
|
|
|
22
|
-
|
|
21
|
+
```sh
|
|
22
|
+
u-cli-mod routes
|
|
23
|
+
u-cli-mod doctor <工程目录>
|
|
24
|
+
u-cli-mod setup <工程目录>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 使用说明
|
|
28
|
+
|
|
29
|
+
### 功能说明
|
|
23
30
|
|
|
24
31
|
Unity 工程自动化通常需要把「编辑器版本」与「CLI 工具链」精确锁定。u-cli-mod 让这件事在 Windows 上**可复现、可校验、可回滚**:
|
|
25
32
|
|
|
26
33
|
- **精确版本路由** - 以 `m_EditorVersion` + revision 双重匹配定位路由,没有“就近版本”回退,版本不在路由表内时如实报告而非猜测
|
|
27
34
|
- **可验证下载** - Unity CLI 固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹;`com.unity.pipeline` 固定 SHA-256(主)+ SHA-1(交叉)
|
|
28
35
|
- **确定性转换** - 在用户缓存中把 `com.unity.pipeline` 适配到 Unity 2022,输出与 `routes/expected-tree/*.json`(385 个文件)逐字节一致
|
|
29
|
-
- **事务式安装** - staging → 校验 → 备份 → 替换 → 再校验 → receipt,任一步失败自动回滚;运行中的 Editor
|
|
36
|
+
- **事务式安装** - staging → 校验 → 备份 → 替换 → 再校验 → receipt,任一步失败自动回滚;运行中的 Editor 校验失败时拒绝执行
|
|
30
37
|
- **工程绑定** - `exec` 每次重新校验 CLI 哈希,并禁止任何 `--project-path` 变体覆盖目标工程
|
|
31
38
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
### Install
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
npm install -g @kevlns/u-cli-mod
|
|
38
|
-
|
|
39
|
-
# 或不安装,直接运行:
|
|
40
|
-
npx --package @kevlns/u-cli-mod u-cli-mod routes
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
要求 Node.js >= 20(Windows 10+)。
|
|
44
|
-
|
|
45
|
-
### Quick start
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
u-cli-mod doctor <project> # 只读体检:路由 / CLI / 适配包状态
|
|
49
|
-
u-cli-mod setup <project> # CLI + 适配包一键就绪(推荐首次入口)
|
|
50
|
-
u-cli-mod routes # 列出支持的 Editor 路由
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
升级 npm 包不会自动替换已有工程的 `Packages/com.unity.pipeline`。检查 `doctor` 的 `pipeline.state`:只有 `current` 且 `installed=true` 才表示当前补丁完整;`outdated`/`invalid` 时关闭目标 Unity Editor 后执行 `u-cli-mod pipeline install <project> --force`(自动备份)。`patchVersion` 是路由要求,`installedPatchVersion` 来自安装 receipt;仅看到上游版本 `0.5.0-exp.1` 或诊断退出码 0 不代表适配包已更新。
|
|
54
|
-
|
|
55
|
-
就绪状态以当前路由的完整文件树为准,旧 receipt、缺失 receipt 或生成缓存未就绪均不会推翻已通过校验的安装。`pipeline.verification` 提供 `mismatches`、`lineEndingDifferences` 和 `error`,可直接定位失效原因。新生成的文本统一 LF;已安装 UTF-8 文本只接受 LF/CRLF 的等价差异,不忽略 BOM、空白、实际内容、缺失或额外文件,二进制保持 SHA-256 严格校验。生成缓存与安装 staging 仍要求精确字节。
|
|
56
|
-
|
|
57
|
-
## Usage
|
|
39
|
+
### 操作流程
|
|
58
40
|
|
|
59
41
|
> 示例中的 `<project>` 指代你的 Unity 工程目录,请替换为实际路径。
|
|
60
42
|
|
|
@@ -97,78 +79,18 @@ u-cli-mod cache clean
|
|
|
97
79
|
|
|
98
80
|
长任务(`run_tests`)默认只等待 5 秒:到点后任务仍在 Unity Editor 内继续执行,工具打印输出日志路径并立即返回(退出码 0);结果用 `command test_status` 轮询,需要同步等待时用 `--wait <秒>`(`0` = 立即返回)。
|
|
99
81
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
1. 读取目标工程 `ProjectSettings/ProjectVersion.txt`,要求 `m_EditorVersion` 与 `m_EditorVersionWithRevision` **同时存在且与路由完全一致**(fail-closed,无通配、无“最近版本”回退)。
|
|
103
|
-
2. 按路由下载固定版本的 Unity CLI:HTTPS 白名单(仅 Unity 官方 CDN),校验固定 SHA-256 + 文件大小 + Authenticode 签名主体与证书指纹,临时文件原子更名为最终文件。
|
|
104
|
-
3. 按路由下载固定版本的 `com.unity.pipeline` tgz:固定 SHA-256(主)+ SHA-1(交叉),安全解包(解包前逐项拒绝绝对路径、`..`、符号/硬链接等非常规条目)。
|
|
105
|
-
4. 在**用户缓存**中确定性转换:`package.json` 最低 Unity 版本、`PhysicsMaterial` 兼容、`rawRenderQueue` 读取兼容、基于 `UnityEditor.LogEntries` 的 `read_console`、Roslyn DLL 的 `.meta` 转为 Unity 2022 格式(保留 GUID)、删除 `Tests` 源码与失效签名文件;输出必须与 `routes/expected-tree/*.json`(含 `Tests.meta` 共 385 个文件)逐字节一致。
|
|
106
|
-
5. 事务式安装到 `Packages/com.unity.pipeline`:staging → 校验 → 备份 → 替换 → 再校验 → receipt;任一步失败自动回滚。运行中的 Unity Editor 会 fail-closed 阻止安装。
|
|
107
|
-
6. `exec` 每次调用前重新校验 CLI 哈希,并**禁止任何 `--project-path` 变体覆盖目标工程**。
|
|
82
|
+
### 工作原理
|
|
108
83
|
|
|
109
|
-
|
|
84
|
+
读取 `ProjectSettings/ProjectVersion.txt` 中的版本和 revision,按精确路由下载并校验工具。安装按暂存、校验、备份、替换、复核、回执顺序执行,失败时回滚。用户缓存位于 `%LOCALAPPDATA%/editor-pipeline-cli`,工程事务记录位于 `Library/editor-pipeline-cli`。缓存生成要求精确字节;已安装文本允许 LF/CRLF 等价,实际内容与二进制仍严格校验。
|
|
110
85
|
|
|
111
|
-
|
|
86
|
+
### 分发边界
|
|
112
87
|
|
|
113
88
|
- ✅ 只包含本工具自己的 TypeScript 代码、版本路由元数据与哈希清单。
|
|
114
89
|
- ✅ Unity CLI 与 `com.unity.pipeline` 在**运行时**从 Unity 官方地址下载到**用户缓存**。
|
|
115
90
|
- ❌ 仓库和 npm 包**不包含**任何 Unity 二进制(`.exe`/`.dll`)、tgz 或 `com.unity.pipeline` 源码。
|
|
116
91
|
- ❌ 无 `postinstall`;安装 npm 包不会下载或修改任何工程。
|
|
117
92
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
### 单元测试与打包守卫
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
npm run check # build + lint + vitest 测试 + pack guard
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
> 发版除 `npm version` 外,还需同步 tests/scripts 中的版本断言(`cli.test.ts`、`vcli-manifest.test.ts`、`pack-guard.mjs`、`test-package-install.mjs`):grep 旧版本号应为零,再打 tag。
|
|
127
|
-
|
|
128
|
-
`pack:guard` 会执行真实 `npm pack`(含文件清单校验),断言发布包:
|
|
129
|
-
|
|
130
|
-
- 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.2.3.tgz`(与 package.json 版本一致);
|
|
131
|
-
- `files` 必须包含 `v-cli.plugin.json`,且清单身份字段(schemaVersion/package/command/bin/platforms)与包一致;
|
|
132
|
-
- 不出现:
|
|
133
|
-
|
|
134
|
-
```text
|
|
135
|
-
*.exe *.dll *.tgz *.pdb
|
|
136
|
-
*.cs *.unity *.asmdef *.prefab *.asset
|
|
137
|
-
完整 com.unity.pipeline 目录树
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### v-cli 插件清单
|
|
141
|
-
|
|
142
|
-
`v-cli.plugin.json` 随包发布(`package.json` 中 `vCli.manifest` 指向),声明 v-cli 命令 `unity`(平台 win32)与全部公共命令路径、参数、选项、输出与副作用元数据。`tests/vcli-manifest.test.ts` 以 `buildProgram()` 为行为源校验清单:命令树、参数、选项(flags 与描述)、usage 逐项一致;同一测试还把 AGENTS.md 的 154 条 Pipeline 命令目录与清单逐条互锁——两处任一未同步都会失败。
|
|
143
|
-
|
|
144
|
-
### 本地 tarball 安装矩阵(三模式验证)
|
|
145
|
-
|
|
146
|
-
```bash
|
|
147
|
-
npm run test:package
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
构建真实 tgz,并在本地验证三种消费方式:工程 devDependency(`node_modules/.bin`)、带临时 `--prefix` 的全局安装、`npx --package <本地tgz>`;每种都执行 `u-cli-mod --version` 与 `u-cli-mod routes`。**不会**向任何 registry 发布。报告:`C:/tmp/u-cli-mod-package-test-report.json`(可用 `EPC_PKG_REPORT` 覆盖)。
|
|
151
|
-
|
|
152
|
-
### 自托管 Runner 与 Unity E2E
|
|
153
|
-
|
|
154
|
-
```bash
|
|
155
|
-
npm run preflight:runner # 注册前环境预检(Node/npm/Git/Unity 版本/revision/许可证探针)
|
|
156
|
-
npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命令/重载/重启/多编辑器)
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
- `preflight:runner` 只读,不下载/注册 Runner;结果 JSON 输出到 stdout。
|
|
160
|
-
- `e2e:windows` 默认使用隔离缓存(设 `EPC_E2E_FRESH_CACHE=0` 可复用真实用户缓存),在 `C:/tmp/u-cli-mod-e2e/` 下创建独立临时工程,全部结束后杀掉它启动的所有 Unity 进程并清理临时工程;报告写入 `C:/tmp/u-cli-mod-e2e-report.json`(分别可用 `EPC_E2E_ROOT`、`EPC_E2E_REPORT` 覆盖)。
|
|
161
|
-
- 验收指标:200 次只读调用 100% 成功并记录 P50/P95、`read_console` 原生 Console 历史读取与统一清理、20 轮资源修改、5 次 Domain Reload 首次恢复、强杀重启恢复、双工程显式路由 60 次无误选、运行中 Editor 防护与 `--project-path` 覆盖拒绝。
|
|
162
|
-
|
|
163
|
-
详细说明见 `docs/SELF_HOSTED_RUNNER.md`。
|
|
164
|
-
|
|
165
|
-
### GitHub Actions
|
|
166
|
-
|
|
167
|
-
- `.github/workflows/ci.yml`:hosted windows runner 上跑 `npm ci` + `npm run check` + `npm audit --omit=dev` + 违禁产物扩展名扫描;push/PR 触发。
|
|
168
|
-
- `.github/workflows/e2e-windows.yml`:**self-hosted** runner(标签 `self-hosted/windows/unity-2022.3.62f3c1`)上跑 Unity E2E;仅 `workflow_dispatch` 与受保护 `v*` tag 触发,不跑 pull_request,不发布;权限最小化(contents: read);产物 `u-cli-mod-e2e-report`。
|
|
169
|
-
- `.github/workflows/publish.yml`:`v*` tag 触发,GitHub 托管 runner 上以 OIDC Trusted Publisher 短期凭证发布到 npm,不保存长期 NPM_TOKEN。
|
|
170
|
-
|
|
171
|
-
## Routes
|
|
93
|
+
### 支持路由
|
|
172
94
|
|
|
173
95
|
| Editor | Revision | CLI | Pipeline | 状态 |
|
|
174
96
|
|---|---|---|---|---|
|
|
@@ -177,51 +99,32 @@ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命
|
|
|
177
99
|
|
|
178
100
|
新增 Editor 版本要求:添加 `routes/<版本>.json` 与 `routes/expected-tree/<版本>.json`、对应转换模板与补丁规则,并在该版本 Unity 上完成编译与回归测试;相近版本不得复用既有路由。
|
|
179
101
|
|
|
180
|
-
|
|
102
|
+
### 目录结构
|
|
181
103
|
|
|
182
104
|
```text
|
|
183
105
|
routes/ 精确版本路由;expected-tree/ 子目录为 385 文件 SHA-256 清单(含 Tests.meta)
|
|
184
106
|
templates/ Unity 生成的 .meta 模板(数据,非 Unity 源码)
|
|
185
|
-
|
|
107
|
+
skills/unity/ Unity 运行技能与操作参考
|
|
186
108
|
src/ TypeScript 实现
|
|
187
109
|
tests/ Vitest 单元测试(自编合成 fixture,不含 Unity 源码)
|
|
188
110
|
scripts/ pack-guard / preflight-runner / e2e-windows / test-package-install
|
|
189
111
|
.github/workflows/ hosted CI + self-hosted E2E
|
|
190
112
|
```
|
|
191
113
|
|
|
192
|
-
##
|
|
193
|
-
|
|
194
|
-
kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
|
|
114
|
+
## 开发与验证
|
|
195
115
|
|
|
196
|
-
|
|
197
|
-
| --- | --- | --- |
|
|
198
|
-
| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.14 |
|
|
199
|
-
| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v2.0.0 |
|
|
200
|
-
| [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first,本仓库) | v0.2.3 |
|
|
201
|
-
| [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.1 |
|
|
202
|
-
|
|
203
|
-
## Compatibility
|
|
204
|
-
|
|
205
|
-
| Runtime | Supported versions |
|
|
206
|
-
| --- | --- |
|
|
207
|
-
| Node.js | `20` and later |
|
|
208
|
-
| Unity Editor | `2022.3.62f3c1` / `2022.3.59f1c1`(精确路由,见 Routes) |
|
|
209
|
-
|
|
210
|
-
## Contributing
|
|
211
|
-
|
|
212
|
-
```bash
|
|
116
|
+
```sh
|
|
213
117
|
npm ci
|
|
214
|
-
npm run check
|
|
118
|
+
npm run check
|
|
119
|
+
npm run test:package
|
|
215
120
|
```
|
|
216
121
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
## License
|
|
122
|
+
命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
|
|
220
123
|
|
|
221
|
-
|
|
124
|
+
## 文档
|
|
222
125
|
|
|
223
|
-
|
|
126
|
+
[Agent 调用规范](skills/unity/SKILL.md) · [文档规范](docs/documentation.md) · [自托管 Unity E2E Runner(本地准备指南)](docs/SELF_HOSTED_RUNNER.md)
|
|
224
127
|
|
|
225
|
-
|
|
128
|
+
## 许可与版权
|
|
226
129
|
|
|
227
|
-
|
|
130
|
+
本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
|
package/dist/cli.js
CHANGED
|
@@ -88,7 +88,7 @@ export function buildProgram() {
|
|
|
88
88
|
});
|
|
89
89
|
program
|
|
90
90
|
.command('setup <project>')
|
|
91
|
-
.description('cli install
|
|
91
|
+
.description('依次执行 cli install 和 pipeline install。')
|
|
92
92
|
.option('--force', '覆盖现有不一致的包')
|
|
93
93
|
.option('--allow-running-editor', '跳过运行中 Editor 的 fail-closed 保护')
|
|
94
94
|
.option('--dry-run', '只校验与预览,不写入工程')
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Vant 自托管 Unity E2E Runner(本地准备指南)
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
自托管 Unity E2E Runner(本地准备指南),适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 操作流程
|
|
12
|
+
|
|
13
|
+
仓库:github.com/kevlns/u-cli-mod(Windows-first,非 Unity 官方项目)。
|
|
14
|
+
本仓库工具链不含发布能力,npm 发布仅由 GitHub Actions 的 publish 工作流完成。以下内容是 **注册前检查清单**。实际注册
|
|
15
|
+
应在 GitHub 仓库 `Settings -> Actions -> Runners` 中完成(需要仓库管理员权限),
|
|
16
|
+
本工具只会做只读预检,**不会下载或注册 Runner**。
|
|
17
|
+
|
|
18
|
+
### 建议机器
|
|
19
|
+
|
|
20
|
+
- 专用 Windows 10/11 或 Windows Server 虚拟机(推荐),或专用物理机。
|
|
21
|
+
- 至少 8 GB 内存、20 GB 空闲磁盘。
|
|
22
|
+
- 不建议长期使用日常开发机,避免执行仓库内不可信任务。
|
|
23
|
+
|
|
24
|
+
### 必须安装
|
|
25
|
+
|
|
26
|
+
| 组件 | 要求 | 验证 |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| Windows | 10/11 x64 | `winver` |
|
|
29
|
+
| Git | >= 2.40 | `git --version` |
|
|
30
|
+
| Node.js | >= 20 LTS | `node --version` |
|
|
31
|
+
| npm | 随 Node | `npm --version` |
|
|
32
|
+
| Unity Hub | 任意近期版本 | - |
|
|
33
|
+
| Unity Editor | `2022.3.62f3c1`,含 Windows build support | 见下方预检 |
|
|
34
|
+
| Unity 许可证 | 可用的个人/专业许可 | 预检中的 license probe |
|
|
35
|
+
|
|
36
|
+
### 预检命令(不注册、不下载、只读)
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
cd u-cli-mod
|
|
40
|
+
npm ci
|
|
41
|
+
npm run build
|
|
42
|
+
npm run preflight:runner
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
输出为 JSON:`pass: true` 且所有 `checks[].ok` 为 true 时,环境即可注册。
|
|
46
|
+
预检包含一个 Unity batchmode 许可证探针(在临时目录创建一次性 scratch
|
|
47
|
+
工程并 `-quit`,结束后删除),耗时约 1–3 分钟;
|
|
48
|
+
可用 `EPC_PREFLIGHT_SKIP_LICENSE=1` 跳过。
|
|
49
|
+
|
|
50
|
+
常用环境变量:
|
|
51
|
+
|
|
52
|
+
- `EPC_UNITY_PATH`:Unity.exe 自定义路径。
|
|
53
|
+
- `EPC_RUNNER_DIR`:建议的 Runner 目录(默认 `C:\unity-runner`)。
|
|
54
|
+
- `EPC_PREFLIGHT_VERSION` / `EPC_PREFLIGHT_REVISION`:期望的 Editor 版本/revision。
|
|
55
|
+
|
|
56
|
+
### 注册后标签
|
|
57
|
+
|
|
58
|
+
Runner 必须带以下标签,E2E 工作流才会路由到它:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
self-hosted
|
|
62
|
+
windows
|
|
63
|
+
unity-2022.3.62f3c1
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
建议注册命令(示例,以仓库页面给出的为准):
|
|
67
|
+
|
|
68
|
+
```powershell
|
|
69
|
+
# 在 C:\unity-runner 下执行 GitHub 给出的注册命令,并追加:
|
|
70
|
+
.\config.cmd --labels self-hosted,windows,unity-2022.3.62f3c1
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 安全策略
|
|
74
|
+
|
|
75
|
+
- E2E 工作流**只**从 `workflow_dispatch` 与受保护 tag(`v*`)触发,
|
|
76
|
+
**不运行 pull_request**,避免不可信 Fork 代码在自托管机器上执行。
|
|
77
|
+
- Runner 机器不放生产密钥;npm 发布由 GitHub 托管 runner 上的 `publish.yml`(OIDC Trusted Publisher 短期凭证)完成,自托管 Runner 不接触发布凭证。
|
|
78
|
+
- 建议在 VM 上启用快照/恢复点;E2E 会在 finally 中清理其生成的 Unity 进程
|
|
79
|
+
与临时工程,但快照仍是兜底。
|
|
80
|
+
- Unity 许可证建议使用专用 CI 授权或浮动许可证环境。
|
|
81
|
+
- 定期更新 Runner 与 Unity Patch;升级 Unity 版本必须在
|
|
82
|
+
`routes/<版本>.json` 新增独立路由并完成回归后才能使用。
|
|
83
|
+
|
|
84
|
+
### 自测(不依赖 GitHub)
|
|
85
|
+
|
|
86
|
+
注册前可在本机完整跑一遍 E2E:
|
|
87
|
+
|
|
88
|
+
```powershell
|
|
89
|
+
npm run e2e:windows
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
报告默认写入 `C:/tmp/u-cli-mod-e2e-report.json`(可用 `EPC_E2E_REPORT` 覆盖)。E2E 默认使用隔离缓存(设 `EPC_E2E_FRESH_CACHE=0` 可复用真实用户缓存)并清理所有它启动的 Unity 进程。
|
|
93
|
+
|
|
94
|
+
## 结果验证
|
|
95
|
+
|
|
96
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
97
|
+
|
|
98
|
+
## 参考资料
|
|
99
|
+
|
|
100
|
+
[使用说明](../README.md)
|