@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Infrastructure/UnityCliAssetRefreshCoordinator.cs

@@ -0,0 +1,106 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Security.Cryptography;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityCli.Protocol;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>asset.refresh 的跨 domain reload 重导入协调器。</summary>
+        internal static class UnityCliAssetRefreshCoordinator
+        {
+            private static readonly Coordinator Instance = new Coordinator();
+            internal static bool IsCommand(string command) { return Instance.IsCommand(command); }
+            internal static void Register(BridgeCommandRegistry registry) { Instance.Register(registry); }
+            internal static Task<string> Execute(BridgeRequest request, byte[] raw, Func<bool> accept, CancellationToken ct) { return Instance.Execute(request, raw, accept, ct); }
+            internal static void Initialize() { }
+            internal static void Shutdown() { }
+            internal static void BeforeReload() { Instance.Update(root => root["reloadObserved"] = true); }
+            internal static void Tick() { Instance.Tick(); }
+
+            private sealed class Coordinator : UnityCliReloadOperation
+            {
+                protected override string Scope { get { return "asset-refresh"; } }
+                protected override string StartCommand { get { return "internal.asset.refresh.start"; } }
+                protected override string StatusCommand { get { return "internal.asset.refresh.status"; } }
+                protected override string OperationDisplayName { get { return "Asset refresh"; } }
+                protected override object DeserializeStartArgs(BridgeRequest request) { return request.DeserializeArgs<Args>(); }
+                protected override void ValidateStart(object value)
+                {
+                    var args = (Args)value;
+                    if (args == null || string.IsNullOrEmpty(args.Path ?? args.AssetPath ?? args.Target))
+                        throw new BridgeCommandException("E_ASSET_REFRESH_PROOF_MISSING", "asset.refresh requires one asset path because whole-database refresh has no attributable completion proof.", "Pass an Assets/* path to reimport one observable asset.");
+                    if (EditorApplication.isPlaying || IsPlayModeChanging()) throw new BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "asset.refresh is editor-only and requires stable Edit Mode.");
+                }
+                protected override void ValidateLoadedRoot(Dictionary<string, object> root)
+                {
+                    ValidateRootContract(root, new[] { "path", "options", "beforeHash", "reloadObserved", "rootContractDigest" }, "queued", "dispatched", "waiting_stable");
+                    var path = Text(root, "path");
+                    ImportAssetOptions options;
+                    object beforeHash;
+                    if (string.IsNullOrWhiteSpace(path) || !path.StartsWith("Assets/", StringComparison.Ordinal)
+                        || !Enum.TryParse(Text(root, "options"), out options)
+                        || !root.TryGetValue("beforeHash", out beforeHash)
+                        || beforeHash != null && !IsSha256(beforeHash as string))
+                        throw new InvalidDataException("Asset refresh active root fields are invalid.");
+                    if (!string.Equals(Text(root, "rootContractDigest"), AssetRefreshRootContractDigest(root), StringComparison.Ordinal))
+                        throw new InvalidDataException("Asset refresh immutable root contract changed.");
+                    var phase = Text(root, "phase");
+                    var fenced = HasExactEffectFence("asset-refresh", root, "asset-import");
+                    if ((phase == "queued" || phase == "dispatched") == fenced)
+                        throw new InvalidDataException("Asset refresh effect fence is inconsistent with phase.");
+                }
+
+                private static string AssetRefreshRootContractDigest(Dictionary<string, object> root)
+                {
+                    return UnityCliSerializer.Sha256Canonical(new Dictionary<string, object> { { "path", root["path"] }, { "options", root["options"] }, { "beforeHash", root["beforeHash"] } });
+                }
+
+                protected override object Planned(object value)
+                {
+                    var args = (Args)value; var path = args.Path ?? args.AssetPath ?? args.Target; var options = Options(args);
+                    return new Result { DryRun = true, Path = path, Options = options.ToString(), PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.import", Path = path, SideEffects = options.ToString() } } };
+                }
+                protected override Dictionary<string, object> CreateRoot(BridgeRequest request, string digest, object value)
+                {
+                    var args = (Args)value; var path = AssetToolSupport.RequireAssetPath(args.Path ?? args.AssetPath ?? args.Target); var fullPath = AssetToolSupport.AssetFullPath(path);
+                    var root = new Dictionary<string, object> { { "requestId", request.RequestId }, { "editorSessionId", EditorSessionId() }, { "requestDigest", digest }, { "deadline", request.Execution.AbsoluteDeadlineUtc }, { "phase", "queued" }, { "path", path }, { "options", Options(args).ToString() }, { "beforeHash", File.Exists(fullPath) ? FileSha256(fullPath) : null } };
+                    root["rootContractDigest"] = AssetRefreshRootContractDigest(root);
+                    return root;
+                }
+                protected override void OnTick(Dictionary<string, object> root)
+                {
+                    var phase = Text(root, "phase");
+                    if (phase == "queued") { if (BusyEditor()) return; Update(x => x["phase"] = "dispatched"); return; }
+                    if (phase == "dispatched")
+                    {
+                        // ImportAsset 可能在返回前触发 domain reload；fence与post phase确认后才调用effect。
+                        root = CrossEffectFence(root, "asset-import", "waiting_stable");
+                        try { AssetDatabase.ImportAsset(Text(root, "path"), (ImportAssetOptions)Enum.Parse(typeof(ImportAssetOptions), Text(root, "options"))); }
+                        catch (Exception exception) { Fail(root, "E_ASSET_REFRESH_PROOF_MISSING", "The reimported asset could not be dispatched: " + exception.Message); }
+                        return;
+                    }
+                    if (phase != "waiting_stable" || BusyEditor()) return;
+                    var fullPath = AssetToolSupport.AssetFullPath(Text(root, "path"));
+                    if (File.Exists(fullPath) && string.Equals(FileSha256(fullPath), Text(root, "beforeHash"), StringComparison.Ordinal) && !string.IsNullOrEmpty(AssetDatabase.AssetPathToGUID(Text(root, "path")))) Succeed(root);
+                }
+                protected override object BuildSuccessData(Dictionary<string, object> root)
+                {
+                    return new Result { Path = Text(root, "path"), Options = Text(root, "options"), Refreshed = true, PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.import", Path = Text(root, "path") } } };
+                }
+                private static ImportAssetOptions Options(Args args) { var options = ImportAssetOptions.Default; if (args.ForceUpdate ?? false) options |= ImportAssetOptions.ForceUpdate; if (args.ImportRecursive ?? false) options |= ImportAssetOptions.ImportRecursive; return options; }
+                private static bool BusyEditor() { return EditorApplication.isUpdating || EditorApplication.isCompiling || BuildPipeline.isBuildingPlayer || IsPlayModeChanging(); }
+                private static string FileSha256(string path) { using (var stream = File.OpenRead(path)) using (var sha = SHA256.Create()) return string.Concat(Array.ConvertAll(sha.ComputeHash(stream), value => value.ToString("x2"))); }
+            }
+            private sealed class Args { public string Path { get; set; } public string AssetPath { get; set; } public string Target { get; set; } public bool? ForceUpdate { get; set; } public bool? ImportRecursive { get; set; } }
+            private sealed class Result { public string Path { get; set; } public string Options { get; set; } public bool? DryRun { get; set; } public bool Refreshed { get; set; } public List<AssetPlannedEffect> PlannedEffects { get; set; } }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliBridgeHelpers.cs

@@ -0,0 +1,155 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        // 为 Infrastructure、Context 和 Tool partial 实现提供共享 Bridge helper。
+        private static string NormalizeAssetPath(string rawPath) => AssetToolSupport.NormalizeAssetPath(rawPath);
+        private static Type ResolveComponentType(string componentName) => GameObjectToolSupport.ResolveComponentType(componentName);
+        private static Vector2 ParseVector2(string value) => GameObjectToolSupport.ParseVector2(value);
+        private static Vector3 ParseVector3(string value) => GameObjectToolSupport.ParseVector3(value);
+
+        // 构造组件名称和摘要数据，缺失脚本保持原有 MissingScript 语义。
+        private static List<object> ComponentNamesData(GameObject gameObject)
+        {
+            var result = new List<object>();
+            foreach (var component in gameObject.GetComponents<Component>()) result.Add(component == null ? "MissingScript" : component.GetType().Name);
+            return result;
+        }
+
+        private static Dictionary<string, object> ComponentSummaryData(Component component)
+        {
+            if (component == null) return new Dictionary<string, object> { { "type", "MissingScript" }, { "enabled", false } };
+            return new Dictionary<string, object> { { "type", component.GetType().Name }, { "fullName", component.GetType().FullName }, { "enabled", ComponentEnabled(component) } };
+        }
+
+        private static List<object> ComponentsData(GameObject gameObject)
+        {
+            var result = new List<object>();
+            foreach (var component in gameObject.GetComponents<Component>()) result.Add(ComponentSummaryData(component));
+            return result;
+        }
+
+        private static bool ComponentEnabled(Component component)
+        {
+            var property = component.GetType().GetProperty("enabled", BindingFlags.Instance | BindingFlags.Public);
+            return property == null || (bool)property.GetValue(component, null);
+        }
+
+        private static Dictionary<string, object> Vector3Data(Vector3 value) => new Dictionary<string, object> { { "x", (double)value.x }, { "y", (double)value.y }, { "z", (double)value.z } };
+        private static Dictionary<string, object> TransformData(Transform transform) => new Dictionary<string, object> { { "position", Vector3Data(transform.position) }, { "rotation", Vector3Data(transform.eulerAngles) }, { "scale", Vector3Data(transform.localScale) } };
+        private static Dictionary<string, object> GameObjectTargetData(GameObject gameObject) => new Dictionary<string, object> { { "id", (long)gameObject.GetInstanceID() }, { "name", gameObject.name }, { "path", HierarchyPath(gameObject) } };
+
+        private static Dictionary<string, object> GameObjectDetailData(GameObject gameObject)
+        {
+            var children = new List<object>();
+            foreach (Transform child in gameObject.transform) children.Add(GameObjectTargetData(child.gameObject));
+            return new Dictionary<string, object> { { "id", (long)gameObject.GetInstanceID() }, { "name", gameObject.name }, { "path", HierarchyPath(gameObject) }, { "active", gameObject.activeSelf }, { "tag", gameObject.tag }, { "layer", (long)gameObject.layer }, { "transform", TransformData(gameObject.transform) }, { "components", ComponentsData(gameObject) }, { "children", children } };
+        }
+
+        private sealed class Counter { public int Value; }
+
+        private static int CountHierarchy(Transform transform)
+        {
+            var count = 1;
+            foreach (Transform child in transform) count += CountHierarchy(child);
+            return count;
+        }
+
+        private static Dictionary<string, object> HierarchyItemData(Transform transform) => HierarchyItemData(transform, -1, true);
+        private static Dictionary<string, object> HierarchyItemData(Transform transform, int depth, bool includeComponents)
+        {
+            var componentNames = ComponentNamesData(transform.gameObject);
+            var gameObject = transform.gameObject;
+            var result = new Dictionary<string, object> { { "id", (long)gameObject.GetInstanceID() }, { "name", gameObject.name }, { "path", HierarchyPath(gameObject) }, { "active", gameObject.activeSelf }, { "activeInHierarchy", gameObject.activeInHierarchy }, { "tag", gameObject.tag }, { "layer", (long)gameObject.layer }, { "childCount", (long)transform.childCount }, { "childrenTruncated", transform.childCount > 0 }, { "componentCount", (long)componentNames.Count }, { "componentTypes", componentNames } };
+            if (depth >= 0) result["depth"] = (long)depth;
+            if (includeComponents) result["components"] = componentNames;
+            return result;
+        }
+
+        // prefab/hierarchy 调用的分页收集保持 cursor/pageSize 截断语义。
+        private static void CollectHierarchy(Transform transform, List<object> items, int cursor, int pageSize, Counter counter)
+        {
+            if (counter.Value >= cursor && items.Count < pageSize) items.Add(HierarchyItemData(transform));
+            counter.Value++;
+            foreach (Transform child in transform) { if (items.Count >= pageSize) return; CollectHierarchy(child, items, cursor, pageSize, counter); }
+        }
+
+        private static TargetResolution ResolveGameObjectTarget(string target)
+        {
+            var matches = new List<GameObject>();
+            if (string.IsNullOrEmpty(target)) return TargetResolution.FromMatches(matches);
+            foreach (var gameObject in UnityEngine.Object.FindObjectsOfType<GameObject>(true))
+                if (gameObject.name == target || gameObject.GetInstanceID().ToString(CultureInfo.InvariantCulture) == target || HierarchyPath(gameObject) == target) matches.Add(gameObject);
+            return TargetResolution.FromMatches(matches);
+        }
+
+        private static Component ResolveComponent(GameObject gameObject, string componentName) => ResolveComponent(gameObject, componentName, null);
+        private static Component ResolveComponent(GameObject gameObject, string componentName, int? componentIndex)
+        {
+            var type = ResolveComponentType(componentName);
+            if (!componentIndex.HasValue) return gameObject.GetComponent(type);
+            var components = gameObject.GetComponents(type);
+            if (componentIndex.Value < 0 || componentIndex.Value >= components.Length) throw new BridgeCommandException("E_COMPONENT_INDEX_OUT_OF_RANGE", "componentIndex " + componentIndex.Value + " is out of range for " + componentName + ".", "Run tools run scene.gameobject.components to discover component indices.");
+            return components[componentIndex.Value];
+        }
+
+        private static List<object> GraphicsVolumesData(string target)
+        {
+            var components = new List<Component>();
+            var volumeType = FindType("UnityEngine.Rendering.Volume");
+            if (volumeType == null) return new List<object>();
+            foreach (var component in Resources.FindObjectsOfTypeAll(volumeType))
+            {
+                var typed = component as Component;
+                if (typed == null || typed.gameObject == null || EditorUtility.IsPersistent(typed.gameObject)) continue;
+                if (!string.IsNullOrEmpty(target) && !HierarchyPath(typed.gameObject).Equals(target, StringComparison.OrdinalIgnoreCase) && !typed.gameObject.name.Equals(target, StringComparison.OrdinalIgnoreCase)) continue;
+                components.Add(typed);
+            }
+            components.Sort((left, right) => string.Compare(HierarchyPath(left.gameObject), HierarchyPath(right.gameObject), StringComparison.OrdinalIgnoreCase));
+            var result = new List<object>(); foreach (var component in components) result.Add(GraphicsVolumeData(component)); return result;
+        }
+
+        private static Dictionary<string, object> GraphicsVolumeData(Component component)
+        {
+            var type = component.GetType();
+            var enabledProperty = type.GetProperty("enabled", BindingFlags.Instance | BindingFlags.Public);
+            var isGlobalField = type.GetField("isGlobal", BindingFlags.Instance | BindingFlags.Public);
+            var priorityField = type.GetField("priority", BindingFlags.Instance | BindingFlags.Public);
+            var weightField = type.GetField("weight", BindingFlags.Instance | BindingFlags.Public);
+            var profile = MemberValue(type, component, "profile") as UnityEngine.Object;
+            var sharedProfile = MemberValue(type, component, "sharedProfile") as UnityEngine.Object;
+            return new Dictionary<string, object> { { "target", GameObjectTargetData(component.gameObject) }, { "enabled", enabledProperty == null || Convert.ToBoolean(enabledProperty.GetValue(component, null), CultureInfo.InvariantCulture) }, { "isGlobal", isGlobalField != null && Convert.ToBoolean(isGlobalField.GetValue(component), CultureInfo.InvariantCulture) }, { "priority", priorityField == null ? 0f : Convert.ToSingle(priorityField.GetValue(component), CultureInfo.InvariantCulture) }, { "weight", weightField == null ? 0f : Convert.ToSingle(weightField.GetValue(component), CultureInfo.InvariantCulture) }, { "profile", AssetReference(profile ?? sharedProfile) } };
+        }
+
+        private static string RequirePrefabPath(string rawPath)
+        {
+            var path = NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path)) throw new BridgeCommandException("E_PREFAB_PATH_REQUIRED", "Pass an Assets/*.prefab path.", "Pass a concrete Assets/*.prefab path discovered from project assets.");
+            if (!path.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase) || !path.EndsWith(".prefab", StringComparison.OrdinalIgnoreCase)) throw new BridgeCommandException("E_PREFAB_PATH_INVALID", "Prefab path must be under Assets/ and end with .prefab: " + path, "Pass a Unity asset path such as Assets/Prefabs/Player.prefab.");
+            return path;
+        }
+
+        private static GameObject LoadPrefabAsset(string path)
+        {
+            var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
+            if (prefab == null) throw new BridgeCommandException("E_PREFAB_NOT_FOUND", "Prefab asset not found: " + path, "Check the path or discover existing Prefab assets before retrying.");
+            if (PrefabUtility.GetPrefabAssetType(prefab) == PrefabAssetType.NotAPrefab) throw new BridgeCommandException("E_ASSET_NOT_PREFAB", "Asset is not a Prefab: " + path, "Pass an Assets/*.prefab asset path.");
+            return prefab;
+        }
+
+        private static Dictionary<string, object> PrefabVariantData(GameObject prefab)
+        {
+            var source = PrefabUtility.GetCorrespondingObjectFromSource(prefab); var sourcePath = source == null ? null : NormalizeAssetPath(AssetDatabase.GetAssetPath(source)); var sourceGuid = string.IsNullOrEmpty(sourcePath) ? null : AssetDatabase.AssetPathToGUID(sourcePath);
+            return new Dictionary<string, object> { { "isVariant", PrefabUtility.GetPrefabAssetType(prefab) == PrefabAssetType.Variant }, { "basePath", sourcePath }, { "baseGuid", sourceGuid }, { "sourcePath", sourcePath }, { "sourceGuid", sourceGuid } };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Infrastructure/UnityCliCanonicalProjectPath.cs

@@ -0,0 +1,325 @@
+using System;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Security.Cryptography;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// CanonicalPath v1 的唯一 Win32 实现。Unity Bridge 与 TS CLI helper 必须复用本类，禁止分别近似规范化。
+    /// </summary>
+    public static class UnityCliCanonicalProjectPath
+    {
+        public const int CanonicalizationVersion = 1;
+        private const uint FileReadAttributes = 0x80;
+        private const uint FileShareRead = 0x1;
+        private const uint FileShareWrite = 0x2;
+        private const uint FileShareDelete = 0x4;
+        private const uint OpenExisting = 3;
+        private const uint FileFlagBackupSemantics = 0x02000000;
+        private const uint LcmapLowercase = 0x00000100;
+        private const uint FileCsFlagCaseSensitiveDir = 0x00000001;
+        private const int FileCaseSensitiveInfo = 23;
+        private const uint DriveUnknown = 0;
+        private const uint DriveNoRootDir = 1;
+        private const uint DriveRemote = 4;
+
+        [StructLayout(LayoutKind.Sequential)]
+        private struct FileCaseSensitiveInformation
+        {
+            public uint Flags;
+        }
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        private static extern SafeFileHandle CreateFileW(
+            string fileName,
+            uint desiredAccess,
+            uint shareMode,
+            IntPtr securityAttributes,
+            uint creationDisposition,
+            uint flagsAndAttributes,
+            IntPtr templateFile);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        private static extern uint GetFinalPathNameByHandleW(
+            SafeFileHandle file,
+            [Out] char[] filePath,
+            uint filePathLength,
+            uint flags);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        private static extern bool GetFileInformationByHandleEx(
+            SafeFileHandle file,
+            int fileInformationClass,
+            out FileCaseSensitiveInformation fileInformation,
+            uint bufferSize);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode)]
+        private static extern uint GetDriveTypeW(string rootPathName);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        private static extern bool GetVolumeInformationW(
+            string rootPathName,
+            StringBuilder volumeNameBuffer,
+            int volumeNameSize,
+            out uint volumeSerialNumber,
+            out uint maximumComponentLength,
+            out uint fileSystemFlags,
+            StringBuilder fileSystemNameBuffer,
+            int fileSystemNameSize);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        private static extern int LCMapStringEx(
+            string localeName,
+            uint mapFlags,
+            string source,
+            int sourceLength,
+            [Out] char[] destination,
+            int destinationLength,
+            IntPtr versionInformation,
+            IntPtr reserved,
+            IntPtr sortHandle);
+
+        /// <summary>
+        /// 从任意项目子路径解析物理 Unity project root，并生成跨进程稳定 identity。
+        /// 任何不能证明为本机、case-insensitive、可访问物理目录的输入都 fail closed。
+        /// </summary>
+        public static CanonicalProjectPathResult Resolve(string inputPath)
+        {
+            try
+            {
+                if (string.IsNullOrWhiteSpace(inputPath))
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_REQUIRED", "A Unity project path is required.");
+
+                var lexicalPath = Path.GetFullPath(inputPath.Trim());
+                var existingDirectory = FindNearestExistingDirectory(lexicalPath);
+                if (existingDirectory == null)
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", "No accessible directory exists for the requested path.");
+
+                if (ContainsBrokenReparsePoint(lexicalPath, existingDirectory))
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", "The requested path contains a broken or inaccessible reparse point.");
+
+                var physicalInput = FinalDirectoryPath(existingDirectory);
+                var projectRoot = FindUnityProjectRoot(physicalInput);
+                if (projectRoot == null)
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_REQUIRED", "The requested path is not inside a Unity project.");
+
+                var displayProjectPath = NormalizeDosPath(FinalDirectoryPath(projectRoot));
+                var rootPath = Path.GetPathRoot(displayProjectPath);
+                if (string.IsNullOrEmpty(rootPath) || IsUncPath(displayProjectPath))
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_REMOTE_PATH_UNSUPPORTED", "UNC and non-DOS-volume Unity project paths are not supported.");
+
+                var driveType = GetDriveTypeW(EnsureTrailingSeparator(rootPath));
+                if (driveType == DriveRemote)
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_REMOTE_PATH_UNSUPPORTED", "Remote Unity project volumes are not supported.");
+                if (driveType == DriveUnknown || driveType == DriveNoRootDir || !CanReadVolumeInformation(rootPath))
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", "The Unity project volume cannot be verified as a local volume.");
+
+                if (HasCaseSensitiveDirectoryInChain(displayProjectPath, rootPath))
+                    return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_CASE_SENSITIVE_UNSUPPORTED", "Case-sensitive Windows directories are not supported for Unity project identity.");
+
+                var canonicalProjectPath = InvariantLowercase(displayProjectPath);
+                var identityHash = Sha256Utf8(canonicalProjectPath);
+                return new CanonicalProjectPathResult
+                {
+                    Success = true,
+                    CanonicalizationVersion = CanonicalizationVersion,
+                    CanonicalProjectPath = canonicalProjectPath,
+                    DisplayProjectPath = displayProjectPath,
+                    IdentityHash = identityHash,
+                    InstanceId = "unity-" + identityHash
+                };
+            }
+            catch (UnauthorizedAccessException exception)
+            {
+                return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", exception.Message);
+            }
+            catch (IOException exception)
+            {
+                return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", exception.Message);
+            }
+            catch (Exception exception)
+            {
+                return CanonicalProjectPathResult.Fail("E_INSTANCE_PATH_UNAVAILABLE", exception.Message);
+            }
+        }
+
+        /// <summary>查找最近的已存在目录；文件输入从其父目录开始。</summary>
+        private static string FindNearestExistingDirectory(string path)
+        {
+            var current = File.Exists(path) ? Path.GetDirectoryName(path) : path;
+            while (!string.IsNullOrEmpty(current))
+            {
+                if (Directory.Exists(current)) return current;
+                var parent = Path.GetDirectoryName(current);
+                if (string.IsNullOrEmpty(parent) || string.Equals(parent, current, StringComparison.Ordinal)) break;
+                current = parent;
+            }
+            return null;
+        }
+
+        /// <summary>检测未解析尾部中的 broken junction/symlink，禁止退回父目录身份。</summary>
+        private static bool ContainsBrokenReparsePoint(string lexicalPath, string existingDirectory)
+        {
+            var current = lexicalPath;
+            while (!string.IsNullOrEmpty(current) && !string.Equals(current, existingDirectory, StringComparison.OrdinalIgnoreCase))
+            {
+                try
+                {
+                    var attributes = File.GetAttributes(current);
+                    if ((attributes & FileAttributes.ReparsePoint) != 0 && !Directory.Exists(current) && !File.Exists(current)) return true;
+                }
+                catch (FileNotFoundException) { }
+                catch (DirectoryNotFoundException) { }
+                var parent = Path.GetDirectoryName(current);
+                if (string.IsNullOrEmpty(parent) || string.Equals(parent, current, StringComparison.Ordinal)) break;
+                current = parent;
+            }
+            return false;
+        }
+
+        /// <summary>从物理输入路径向上发现最近 Unity project root。</summary>
+        private static string FindUnityProjectRoot(string startDirectory)
+        {
+            var current = startDirectory;
+            while (!string.IsNullOrEmpty(current))
+            {
+                if (Directory.Exists(Path.Combine(current, "Assets"))
+                    && File.Exists(Path.Combine(current, "Packages", "manifest.json"))
+                    && File.Exists(Path.Combine(current, "ProjectSettings", "ProjectVersion.txt")))
+                    return current;
+                var parent = Path.GetDirectoryName(current);
+                if (string.IsNullOrEmpty(parent) || string.Equals(parent, current, StringComparison.Ordinal)) break;
+                current = parent;
+            }
+            return null;
+        }
+
+        /// <summary>通过 directory handle 获取 Win32 final DOS path。</summary>
+        private static string FinalDirectoryPath(string directory)
+        {
+            using (var handle = CreateFileW(directory, FileReadAttributes, FileShareRead | FileShareWrite | FileShareDelete, IntPtr.Zero, OpenExisting, FileFlagBackupSemantics, IntPtr.Zero))
+            {
+                if (handle == null || handle.IsInvalid)
+                    throw new IOException("CreateFileW failed for directory path. Win32=" + Marshal.GetLastWin32Error());
+
+                var buffer = new char[512];
+                while (true)
+                {
+                    var length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Length, 0);
+                    if (length == 0) throw new IOException("GetFinalPathNameByHandleW failed. Win32=" + Marshal.GetLastWin32Error());
+                    if (length < buffer.Length) return NormalizeDosPath(new string(buffer, 0, (int)length));
+                    buffer = new char[length + 1];
+                }
+            }
+        }
+
+        /// <summary>检查 volume root 到 project root 的每一级目录 case-sensitive flag。</summary>
+        private static bool HasCaseSensitiveDirectoryInChain(string projectRoot, string volumeRoot)
+        {
+            var current = projectRoot;
+            while (!string.IsNullOrEmpty(current))
+            {
+                using (var handle = CreateFileW(current, FileReadAttributes, FileShareRead | FileShareWrite | FileShareDelete, IntPtr.Zero, OpenExisting, FileFlagBackupSemantics, IntPtr.Zero))
+                {
+                    if (handle == null || handle.IsInvalid)
+                        throw new IOException("CreateFileW failed while checking case sensitivity. Win32=" + Marshal.GetLastWin32Error());
+                    FileCaseSensitiveInformation information;
+                    if (!GetFileInformationByHandleEx(handle, FileCaseSensitiveInfo, out information, (uint)Marshal.SizeOf(typeof(FileCaseSensitiveInformation))))
+                        throw new IOException("GetFileInformationByHandleEx(FileCaseSensitiveInfo) failed. Win32=" + Marshal.GetLastWin32Error());
+                    if ((information.Flags & FileCsFlagCaseSensitiveDir) != 0) return true;
+                }
+
+                if (string.Equals(EnsureTrailingSeparator(current), EnsureTrailingSeparator(volumeRoot), StringComparison.OrdinalIgnoreCase)) break;
+                var parent = Path.GetDirectoryName(current);
+                if (string.IsNullOrEmpty(parent) || string.Equals(parent, current, StringComparison.Ordinal)) break;
+                current = parent;
+            }
+            return false;
+        }
+
+        /// <summary>读取 volume information，拒绝无法证明为可访问本机卷的路径。</summary>
+        private static bool CanReadVolumeInformation(string rootPath)
+        {
+            uint serial;
+            uint maximumComponentLength;
+            uint flags;
+            return GetVolumeInformationW(EnsureTrailingSeparator(rootPath), new StringBuilder(261), 261, out serial, out maximumComponentLength, out flags, new StringBuilder(261), 261);
+        }
+
+        /// <summary>调用 Win32 invariant locale lowercase，禁止使用 .NET ToLowerInvariant。</summary>
+        private static string InvariantLowercase(string value)
+        {
+            var required = LCMapStringEx(string.Empty, LcmapLowercase, value, value.Length, null, 0, IntPtr.Zero, IntPtr.Zero, IntPtr.Zero);
+            if (required <= 0) throw new IOException("LCMapStringEx length query failed. Win32=" + Marshal.GetLastWin32Error());
+            var buffer = new char[required];
+            var written = LCMapStringEx(string.Empty, LcmapLowercase, value, value.Length, buffer, buffer.Length, IntPtr.Zero, IntPtr.Zero, IntPtr.Zero);
+            if (written <= 0) throw new IOException("LCMapStringEx failed. Win32=" + Marshal.GetLastWin32Error());
+            return new string(buffer, 0, written);
+        }
+
+        /// <summary>规范化 Win32 extended path 表示，不改变 Unicode normalization。</summary>
+        private static string NormalizeDosPath(string value)
+        {
+            var normalized = value.Replace('/', '\\');
+            if (normalized.StartsWith("\\\\?\\UNC\\", StringComparison.OrdinalIgnoreCase))
+                normalized = "\\\\" + normalized.Substring(8);
+            else if (normalized.StartsWith("\\\\?\\", StringComparison.OrdinalIgnoreCase))
+                normalized = normalized.Substring(4);
+            else if (normalized.StartsWith("\\??\\", StringComparison.OrdinalIgnoreCase))
+                normalized = normalized.Substring(4);
+
+            var root = Path.GetPathRoot(normalized);
+            while (normalized.Length > (root == null ? 0 : root.Length) && normalized.EndsWith("\\", StringComparison.Ordinal))
+                normalized = normalized.Substring(0, normalized.Length - 1);
+            return normalized;
+        }
+
+        private static bool IsUncPath(string value)
+        {
+            return value.StartsWith("\\\\", StringComparison.Ordinal);
+        }
+
+        private static string EnsureTrailingSeparator(string value)
+        {
+            return value.EndsWith("\\", StringComparison.Ordinal) ? value : value + "\\";
+        }
+
+        private static string Sha256Utf8(string value)
+        {
+            using (var sha = SHA256.Create())
+            {
+                var bytes = sha.ComputeHash(new UTF8Encoding(false).GetBytes(value));
+                var builder = new StringBuilder(bytes.Length * 2);
+                foreach (var item in bytes) builder.Append(item.ToString("x2"));
+                return builder.ToString();
+            }
+        }
+    }
+
+    /// <summary>PowerShell 与 Unity Bridge 共享的 CanonicalPath v1 DTO。</summary>
+    public sealed class CanonicalProjectPathResult
+    {
+        public bool Success { get; set; }
+        public int CanonicalizationVersion { get; set; }
+        public string CanonicalProjectPath { get; set; }
+        public string DisplayProjectPath { get; set; }
+        public string IdentityHash { get; set; }
+        public string InstanceId { get; set; }
+        public string ErrorCode { get; set; }
+        public string ErrorMessage { get; set; }
+
+        public static CanonicalProjectPathResult Fail(string code, string message)
+        {
+            return new CanonicalProjectPathResult
+            {
+                Success = false,
+                CanonicalizationVersion = UnityCliCanonicalProjectPath.CanonicalizationVersion,
+                ErrorCode = code,
+                ErrorMessage = message
+            };
+        }
+    }
+}