@alpsckr/unitycli 0.4.3 → 0.4.5

package/skills/unitycli/references/operation-protocol.md

@@ -48,11 +48,11 @@ Tool descriptor 常用字段：
 
 每个live Editor或Development Player session拥有独立任务池，默认达到5个active root时关闭准入，降到4仍关闭，降到3才重开。CLI在业务请求前自动等待；AI不手工轮询、不读取active count，也不管理内部token。统一catalog在Editor和Runtime同时在线时，会分别经过两个session的准入后才返回完整结果。
 
-`--timeout-ms T`先提供一份最多`T`的准入预算。CLI在其中等待首次ready记录、当前编译/导入/重载和任务池；证明Unity未运行时立即返回。准入deadline的`E_UNITY_BUSY`明确证明业务Bridge请求未发送、effect未开始，可以稍后提交新root。获得grant后再创建一份完整`T`的execution预算；token重取、status、rebind、reload和terminal recovery都只能消费该预算，不能刷新第三份预算。
+`--timeout-ms T`先提供一份最多`T`的准入预算。CLI在其中等待首次ready记录、当前编译/导入/重载和任务池；证明Unity未运行时立即返回。准入deadline的`E_UNITY_BUSY`明确证明业务Bridge请求未发送、effect未开始，可以稍后提交新root。获得grant后再创建一份完整`T`的execution预算；token重取、status、rebind、reload、terminal recovery和blocker诊断都只能消费该预算，不能刷新第三份预算。blocker补充最多把现有deadline缩短到10秒；没有剩余时间或没有proof时保持主错误不变。
 
 `E_EXECUTION_TIMEOUT`、放行后的transport丢失、进程中断或没有可信terminal envelope时，只能确定本次调用没有返回可信终态，不能据此判断mutation是否发生。先读取对象、场景、Package、build/test状态或artifact manifest；只有形成新的业务决策后才提交新请求，不把outcome unknown自动重放。
 
-调用公开CLI的命令host必须等待进程退出；传入`--timeout-ms T`时至少等待`2 * T + 5000`毫秒，不得后台分离。CLI在stdout写完或最多1秒后退出。CLI timeout不会强停Unity中已开始的effect，host提前退出也不能作为停止证明。
+调用公开CLI的命令host必须等待进程退出；传入`--timeout-ms T`时至少等待`2 * T + 5000`毫秒，不得后台分离。CLI只输出一个terminal envelope，并在stdout完成且已注册的local owner都settle后退出，或在唯一的1000ms宽限期到达时退出；local settlement cleanup只处理仍未消费的lease，永不settle的本地Promise不能延长该宽限。CLI timeout不会强停Unity中已开始的effect，host提前退出也不能作为停止证明。
 
 compile、import、domain reload和listener generation交接由session supervisor在同一execution absolute deadline内处理。同一次调用仅在`editorSessionId`未改变时，才能用完全相同的request bytes续接durable terminal；首次mutation POST后若session改变，CLI禁止向新session再次POST并返回`E_EXECUTION_TIMEOUT`。
 
@@ -67,7 +67,7 @@ compile、import、domain reload和listener generation交接由session superviso
 
 ## 弹窗与长操作
 
-`editor.state`公开状态固定为`ready|transitioning|blocked|unresponsive|unverifiable|offline|conflict`。它与`editor.dialogs`、`editor.dialog.click`使用exact本地descriptor进入统一dispatcher，不依赖可能被阻断的Live catalog；其他Tool不使用静态fallback。`conflict`只表示至少两个verified live claim；身份读取失败使用`unverifiable`，transport存在但主线程不推进使用`unresponsive`。原错误包含`details.blockers`时，先`tools run editor.dialogs`。点击前使用当前返回的dialogId和规范化button label；只能选择当前可见且enabled的按钮。点击后必须证明弹窗消失或状态改变。
+`editor.state`公开状态固定为`ready|transitioning|blocked|unresponsive|unverifiable|offline|conflict`。它与`editor.dialogs`、`editor.dialog.click`是仅有的三个exact观察名称：使用冻结本地descriptor进入统一dispatcher，不依赖可能被阻断的Live catalog或普通业务admission；alias、group、handler和其他offline Tool不继承该路径。`tools describe`可精确学习这三个descriptor。三者仍执行schema、availability、completion和结果校验，共用从dispatch开始的一份absolute deadline；`editor.state`只可发出一次private snapshot观察，dialogs仅Windows可用。`conflict`只表示至少两个verified live claim；身份读取失败使用`unverifiable`，transport存在但主线程不推进使用`unresponsive`。原错误包含`details.blockers`时，先`tools run editor.dialogs`。点击前使用当前返回的dialogId和规范化button label；只能选择当前可见且enabled的按钮。点击会保留最小pre-effect预算，deadline先到会关闭首次effect barrier；点击后必须证明弹窗消失或状态改变。
 
 `build.run`、`test.run`、`editor.refresh`、`code.exec` 和需要刷新 Editor 的 Package Tool 在一次调用内等待最终业务结果。超时只表示该次调用没有可信终态，后续动作由调用方决定。`code.exec`的同步C#一旦在Unity主线程开始，timeout不能中止它；死循环、阻塞等待或长期Unity API调用可继续占用Editor。调用方应先判断这类代码是否确有必要；决定执行后应把timeout视为outcome unknown并在重试前观察业务状态。
 

package/unitypkg/Editor/AssemblyInfo.cs

@@ -0,0 +1,5 @@
+#if UNITY_EDITOR
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("UnityCli.Editor.Tests")]
+#endif

package/unitypkg/Editor/Bridge/BridgeCommandRegistry.cs

@@ -1,7 +1,6 @@
 #if UNITY_EDITOR
 using System;
 using System.Collections.Generic;
-using System.Reflection;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -18,17 +17,34 @@ namespace UnityCli
                 string domain,
                 bool destructive,
                 int timeoutMs,
-                Func<TInput, CancellationToken, ValueTask<object>> handler)
+                Func<TInput, CancellationToken, ValueTask<object>> handler,
+                UnityCliBridgeQueuePolicy.WorkClass? queueClass = null)
             {
                 if (string.IsNullOrWhiteSpace(command)) throw new ArgumentException("Bridge command registration requires a command name.", "command");
                 if (handler == null) throw new ArgumentNullException("handler");
                 if (commands.ContainsKey(command)) throw new InvalidOperationException("Duplicate bridge command registration: " + command);
+                var registeredQueueClass = queueClass;
+                if (!registeredQueueClass.HasValue && command.StartsWith("internal.", StringComparison.Ordinal))
+                    registeredQueueClass = UnityCliBridgeQueuePolicy.IsSafeStatusCommand(command)
+                        ? UnityCliBridgeQueuePolicy.WorkClass.SafeStatus
+                        : UnityCliBridgeQueuePolicy.WorkClass.Mutation;
+                if (registeredQueueClass == UnityCliBridgeQueuePolicy.WorkClass.SafeStatus && !UnityCliBridgeQueuePolicy.IsSafeStatusCommand(command))
+                    throw new InvalidOperationException("Only exact SafeStatus commands may use SafeStatus classification: " + command);
+                if (registeredQueueClass == UnityCliBridgeQueuePolicy.WorkClass.Control && !UnityCliBridgeQueuePolicy.IsDurableControlCommand(command))
+                    throw new InvalidOperationException("Only exact durable control commands may use Control classification: " + command);
+                if (UnityCliBridgeQueuePolicy.IsDurableControlCommand(command) && registeredQueueClass != UnityCliBridgeQueuePolicy.WorkClass.Control)
+                    throw new InvalidOperationException("Durable control command must use Control classification: " + command);
+                if (command.StartsWith("internal.", StringComparison.Ordinal)
+                    && registeredQueueClass == UnityCliBridgeQueuePolicy.WorkClass.OrdinaryRead
+                    && !UnityCliBridgeQueuePolicy.IsOrdinaryReadInternalCommand(command))
+                    throw new InvalidOperationException("Only exact observation commands may use OrdinaryRead classification: " + command);
                 commands.Add(command, new BridgeCommandDefinition(
                     command,
                     domain,
                     destructive,
                     timeoutMs,
                     typeof(TInput),
+                    registeredQueueClass,
                     async (input, cancellationToken) => await handler((TInput)input, cancellationToken)));
             }
 
@@ -58,17 +74,39 @@ namespace UnityCli
                 BridgeCommandDefinition definition;
                 return command != null && commands.TryGetValue(command, out definition) && definition.Destructive;
             }
+
+            public bool TryGetQueueClass(string command, out UnityCliBridgeQueuePolicy.WorkClass workClass)
+            {
+                BridgeCommandDefinition definition;
+                if (command != null && commands.TryGetValue(command, out definition) && definition.QueueClass.HasValue)
+                {
+                    workClass = definition.QueueClass.Value;
+                    return true;
+                }
+                workClass = default(UnityCliBridgeQueuePolicy.WorkClass);
+                return false;
+            }
+
+            internal IReadOnlyDictionary<string, UnityCliBridgeQueuePolicy.WorkClass> InternalQueueClasses()
+            {
+                var result = new Dictionary<string, UnityCliBridgeQueuePolicy.WorkClass>(StringComparer.Ordinal);
+                foreach (var pair in commands)
+                    if (pair.Key.StartsWith("internal.", StringComparison.Ordinal) && pair.Value.QueueClass.HasValue)
+                        result.Add(pair.Key, pair.Value.QueueClass.Value);
+                return result;
+            }
         }
 
         private sealed class BridgeCommandDefinition
         {
-            public BridgeCommandDefinition(string command, string domain, bool destructive, int timeoutMs, Type inputType, Func<object, CancellationToken, ValueTask<object>> handler)
+            public BridgeCommandDefinition(string command, string domain, bool destructive, int timeoutMs, Type inputType, UnityCliBridgeQueuePolicy.WorkClass? queueClass, Func<object, CancellationToken, ValueTask<object>> handler)
             {
                 Command = command;
                 Domain = domain;
                 Destructive = destructive;
                 TimeoutMs = timeoutMs;
                 InputType = inputType;
+                QueueClass = queueClass;
                 Handler = handler;
             }
 
@@ -77,16 +115,23 @@ namespace UnityCli
             public bool Destructive { get; private set; }
             public int TimeoutMs { get; private set; }
             public Type InputType { get; private set; }
+            public UnityCliBridgeQueuePolicy.WorkClass? QueueClass { get; private set; }
             public Func<object, CancellationToken, ValueTask<object>> Handler { get; private set; }
         }
 
+        internal static IReadOnlyDictionary<string, UnityCliBridgeQueuePolicy.WorkClass> InternalQueueClassesForTests()
+        {
+            return CommandRegistry.InternalQueueClasses();
+        }
+
         private static BridgeCommandRegistry CreateCommandRegistry()
         {
             var registry = new BridgeCommandRegistry();
-            RegisterInstalledExtensionCommands(registry);
             RegisterCodeExecCommand(registry);
             RegisterEditorStateSnapshotCommand(registry);
+            RegisterDoctorDiagnosticCommands(registry);
             RegisterInstanceCleanupCommand(registry);
+            UnityCliDurableStatusCoordinator.Register(registry);
             UnityCliCompileCoordinator.Register(registry);
             UnityCliLiveBuildCoordinator.Register(registry);
             UnityCliLiveRefreshCoordinator.Register(registry);
@@ -158,16 +203,6 @@ namespace UnityCli
             return result;
         }
 
-        private static void RegisterInstalledExtensionCommands(BridgeCommandRegistry registry)
-        {
-            var methodNames = Array.Empty<string>();
-            foreach (var methodName in methodNames)
-            {
-                var method = typeof(UnityCliBridge).GetMethod(methodName, BindingFlags.Static | BindingFlags.NonPublic);
-                if (method == null) throw new InvalidOperationException("Installed extension bridge registration method is missing: " + methodName);
-                method.Invoke(null, new object[] { registry });
-            }
-        }
     }
 }
 #endif

package/unitypkg/Editor/Bridge/BridgeHttpServer.cs

@@ -403,24 +403,15 @@ namespace UnityCli
                     nextActions: new[] { "Inspect editor.state and retry only after Unity is responsive." })), 200);
                 return;
             }
-            AdmissionOwnerIdentity admissionOwner;
-            try { admissionOwner = AuthorizeAdmission(context.Request, request, rawBody); }
-            catch (BridgeCommandException exception)
-            {
-                WriteJson(context, SerializeBridgeExceptionEnvelope(request.RequestId, exception), 200);
-                return;
-            }
             WriteLog("bridge_request_body_read requestId=" + request.RequestId + " command=" + request.Command + " bytes=" + rawBody.Length.ToString(CultureInfo.InvariantCulture));
 
-            // Check for transient Unity state before queuing the request.
-            // During compile/import/domain reload, immediately return a transient error
-            // so the CLI can retry-after instead of waiting 60s for a timeout.
+            // 所有瞬态Editor gate必须在token消费前完成，拒绝路径对active pool零影响。
             if (domainReloading)
             {
                 WriteJson(context, SerializeTransientErrorEnvelope(request.RequestId, "E_UNITY_DOMAIN_RELOAD", "Unity Editor is reloading assemblies (domain reload).", "Wait for domain reload to complete and retry.", 10000), 200);
                 return;
             }
-            var allowedDuringCompileOrImport = UnityCliCompileCoordinator.IsCommand(request.Command) || UnityCliLiveRefreshCoordinator.IsCommand(request.Command) || UnityCliAssetRefreshCoordinator.IsCommand(request.Command) || UnityCliPackageEmbedCoordinator.IsCommand(request.Command) || UnityCliPackageResolveCoordinator.IsCommand(request.Command) || UnityCliTestRunCoordinator.IsCommand(request.Command) || UnityCliNavMeshBakeCoordinator.IsCommand(request.Command) || UnityCliOcclusionBakeCoordinator.IsCommand(request.Command) || IsEditorStateSnapshotCommand(request.Command);
+            var allowedDuringCompileOrImport = UnityCliDurableStatusCoordinator.IsCommand(request.Command) || UnityCliCompileCoordinator.IsCommand(request.Command) || UnityCliLiveRefreshCoordinator.IsCommand(request.Command) || UnityCliAssetRefreshCoordinator.IsCommand(request.Command) || UnityCliPackageEmbedCoordinator.IsCommand(request.Command) || UnityCliPackageResolveCoordinator.IsCommand(request.Command) || UnityCliTestRunCoordinator.IsCommand(request.Command) || UnityCliNavMeshBakeCoordinator.IsCommand(request.Command) || UnityCliOcclusionBakeCoordinator.IsCommand(request.Command) || IsEditorStateSnapshotCommand(request.Command) || IsProjectToolCatalogReadCommand(request.Command) || IsDoctorAdmissionBypassCommand(request.Command);
             if (cachedIsCompiling && !allowedDuringCompileOrImport)
             {
                 WriteJson(context, SerializeTransientErrorEnvelope(request.RequestId, "E_UNITY_COMPILING", "Unity Editor is compiling scripts.", "Wait for Unity to finish compiling and retry.", 5000), 200);
@@ -435,16 +426,13 @@ namespace UnityCli
             {
                 // 只在 PlayMode 切换期限制高风险命令；稳定运行态允许 CLI 工具继续入队执行。
                 // 这里必须与 UnityCliBridge.Execute() 的切换期 allowlist 保持一致。
-                var allowedDuringPlayModeTransition = UnityCliCompileCoordinator.IsCommand(request.Command) || UnityCliLiveRefreshCoordinator.IsCommand(request.Command) || UnityCliAssetRefreshCoordinator.IsCommand(request.Command) || UnityCliPackageEmbedCoordinator.IsCommand(request.Command) || UnityCliPackageResolveCoordinator.IsCommand(request.Command) || UnityCliTestRunCoordinator.IsCommand(request.Command) || UnityCliNavMeshBakeCoordinator.IsCommand(request.Command) || UnityCliOcclusionBakeCoordinator.IsCommand(request.Command)
+                var allowedDuringPlayModeTransition = UnityCliDurableStatusCoordinator.IsCommand(request.Command) || UnityCliCompileCoordinator.IsCommand(request.Command) || UnityCliLiveRefreshCoordinator.IsCommand(request.Command) || UnityCliAssetRefreshCoordinator.IsCommand(request.Command) || UnityCliPackageEmbedCoordinator.IsCommand(request.Command) || UnityCliPackageResolveCoordinator.IsCommand(request.Command) || UnityCliTestRunCoordinator.IsCommand(request.Command) || UnityCliNavMeshBakeCoordinator.IsCommand(request.Command) || UnityCliOcclusionBakeCoordinator.IsCommand(request.Command)
                     || IsEditorStateSnapshotCommand(request.Command)
-                    || request.Command == "editor.console"
                     || request.Command == "editor.pause"
                     || request.Command == "editor.stop"
-                    || request.Command == "runtime-tool.list"
+                    || IsProjectToolCatalogReadCommand(request.Command)
                     || request.Command == "runtime-tool.run"
-                    || request.Command == "project-tool.list"
-                    || request.Command == "diagnose.preflight"
-                    || request.Command == "extension.status";
+                    || IsDoctorAdmissionBypassCommand(request.Command);
 
                 WriteLog("http_play_mode_guard requestId=" + request.RequestId + " command=" + request.Command + " cachedIsPlayingOrWillChange=" + Bool(cachedIsPlayingOrWillChangePlaymode) + " cachedIsPlaying=" + Bool(cachedIsPlaying) + " transitionAllowed=" + Bool(allowedDuringPlayModeTransition));
 
@@ -460,10 +448,7 @@ namespace UnityCli
             BridgeWorkItem item;
             bool created;
             int queueDepth;
-            try
-            {
-                item = EnqueueOrAttach(request, rawBody, ListenerId, CurrentListenerGeneration(), admissionOwner, out created, out queueDepth);
-            }
+            try { item = EnqueueOrAttach(context.Request, request, rawBody, ListenerId, CurrentListenerGeneration(), out created, out queueDepth); }
             catch (BridgeCommandException exception)
             {
                 WriteJson(context, SerializeBridgeExceptionEnvelope(request.RequestId, exception), 200);
@@ -477,19 +462,10 @@ namespace UnityCli
             var queueSignal = WaitHandle.WaitAny(new[] { item.Started.WaitHandle, item.Completed.WaitHandle }, queueRemainingMs);
             if (queueSignal == WaitHandle.WaitTimeout)
             {
-                if (item.CancelBeforeStart())
-                {
-                    WriteLog("bridge_queue_start_timeout requestId=" + request.RequestId + " command=" + request.Command);
-                    WriteJson(context, UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(
-                        request.RequestId,
-                        "E_EXECUTION_TIMEOUT",
-                        "Unity Editor did not start the bridge request before the immutable deadline.",
-                        nextActions: new[] { "Inspect editor.state and retry only after Unity is responsive." })), 200);
-                    return;
-                }
+                // HTTP deadline只结束当前响应；WorkItem identity继续留在map，由主线程统一裁决是否开始或收敛。
                 WriteLog("bridge_queue_start_timeout requestId=" + request.RequestId + " command=" + request.Command);
                 WriteJson(context, ResolveStartedTimeoutResponse(item, request,
-                    "The immutable deadline elapsed after Unity started the request."), 200);
+                    "The immutable deadline elapsed before Unity confirmed the request start."), 200);
                 return;
             }
             if (queueSignal == 1)
@@ -502,7 +478,6 @@ namespace UnityCli
             if (!request.TryDeadlineRemainingMs(out executionRemainingMs)) executionRemainingMs = 0;
             if (!item.Completed.Wait(TimeSpan.FromMilliseconds(executionRemainingMs)))
             {
-                item.Cancel();
                 WriteLog("bridge_execution_timeout requestId=" + request.RequestId + " command=" + request.Command);
                 WriteJson(context, ResolveStartedTimeoutResponse(item, request,
                     "The immutable deadline elapsed after Unity started the request."), 200);
@@ -521,8 +496,7 @@ namespace UnityCli
             // CompleteWorkItem/Response 可能恰好在上述读取后发生；再读一次避免丢失已完成结果。
             if (item.Completed.Wait(0) && item.Response != null) return item.Response;
 
-            // 接受后的请求继续执行；只有 timeout 在接受前获胜时才取消执行 token。
-            item.CancelBeforeAcceptance();
+            // HTTP timeout不改变WorkItem acceptance、Completed或map；同identity attach仍返回同一个对象。
             return UnityCliSerializer.Serialize(UnityCli.Protocol.ProtocolEnvelopeFactory.Error(
                 request.RequestId,
                 "E_EXECUTION_TIMEOUT",