@alpsckr/unitycli 0.4.2 → 0.4.4

package/skills/unitycli/SKILL.md

@@ -1,70 +1,63 @@
 ---
 name: unitycli
-description: 所有涉及 Unity 或 Unity Editor 或 UnityPipeline 的任务都优先使用本 Skill，以便发现唯一可用的 `unitycli` 控制入口。适用于 Scene、GameObject、Prefab、Asset、Package、Build、Test、GameView、SceneView、日志、截图、Bridge、instance、Editor/PlayMode 状态和项目自定义能力；纯源码或文本工作可直接处理，但需要观察、操作或验证已打开 Editor 时必须使用 CLI。
+description: 所有涉及 Unity、Unity Editor 或 UnityPipeline 的任务都优先使用本 Skill，用于判断直接处理项目文件，或通过`unitycli` 入口发现当前 Editor 能力。
 ---
-
 # UnityCLI
 
 FeedbackMode: off
 
-`unitycli` 是 AI 操作已打开 Unity Editor 的能力目录。不要记忆或猜能力：先发现，再读 descriptor，最后调用。
+`unitycli` 是 AI 操作已打开 Unity Editor 的运行时导航入口，不是固定工具手册。根据任务发现当前 catalog，读取所选 descriptor，再构造调用。
 
 ## 路由
 
-- 所有Unity动作与观察能力都属于Tool；读取型Tool必须纯只读并准确声明空副作用。
-- 纯 `.cs`、JSON、YAML、manifest 或文档编辑可直接使用文件工具。需要 Unity 内存状态、导入结果、编译、物理、渲染或业务效果证明时使用 CLI。
-- 公开顶层只有`tools`、`command`、`init`、`extensions`、`target`、`instances`、`doctor`；Unity能力域不作为顶层命令。
-- auth、Unity Hub、Editor安装或打开、Cloud、License、proxy配置属于外部控制面；直接使用系统或官方工具，不在catalog中猜测替代Tool。
-- Extension 管理只用 `extensions list`、`extensions install`、`extensions remove`、`extensions doctor`。
-- 已连接实例的目录同时包含 built-in、Extension、project、Editor 和 Runtime 能力，不按 `source` 或当前模式过滤。
-- 完全兼容 Unity 官方 CLI 特性体系：项目与第三方 Package 中以官方 `[CliCommand]`/`[CliArg]`/`IStructuredCommandInput` 声明的命令直接进入同一 catalog，固定投影为 `UnityPipeline_<原名>`、group `UnityPipeline`，用 `command <原名>` 或完整前缀名调用；`com.unity.pipeline` 包自身命令已由 native 能力吸收并按 provider identity 抑制。native 精确重名优先。
-
-## 安装协议
+- 需要 Unity 内存、Editor API、导入/编译、PlayMode 或业务效果证明时使用 CLI。
+- Unity 动作与观察能力都从同一 Tool catalog 发现。公开顶层只有 `tools`、`command`、`init`、`extensions`、`target`、`instances`、`doctor`；不要猜 Unity 能力域是顶层命令。
+- 不知道能力领域时可看 group，已有业务关键词时可 search，得到 exact Tool 名后 describe。返回的 `name` 是调用名，group 和 `source` 不参与名称拼接或 owner 路由。
+- `tools run` 与 `command` 复用同一 descriptor 和 schema。`[CliCommand("name")]` 投影为 `UnityPipeline_name`，也可由 `command name` 选择；native exact name 优先。
 
-当用户要求安装、配置、检查或修复 UnityCLI 时，唯一学习入口是：
+## 发现与调用
 
 ```powershell
-unitycli init help
-```
-
-严格执行返回的版本化`aiInstructions`，不要依赖本Skill记忆安装步骤。先运行`init discover`；当前目录只有一个Unity项目时直接采用，用户已经指定的项目、scope、host或Skill目录都是最终决定，不得重复询问。未指定Skill目录时使用发现结果的当前workspace推荐目标；明确目录使用`init skill --target <SkillDirectory>`。准确目标Unity正在运行时只询问一次是否正常关闭；同意后使用`init package --close-editor`，不得强制终止，也不得替用户决定未保存场景弹窗。Bridge与Skill是独立授权效果，一个失败只阻断自身检查，不阻断另一个；每个成功效果都立即执行对应`--check`并最终汇总全部状态。安装流程不得启动或重启Unity。用户安装请求授权所选效果，除关闭Editor外不增加确认。
-
-## 执行骨架
-
-```powershell
-# 默认隐藏 offline；仅审计完整历史集合时使用 instances list --all
+# 目标未知、需要审计当前连接或错误要求检查实例时
 unitycli instances list
-# 仅需清理历史记录时，授权选定的当前Unity执行有界prune
-unitycli instances prune --instance <id|projectPath|alias>
+
 unitycli tools group --instance <id|projectPath|alias>
-unitycli tools group list <group> --page-size 20 --instance <id|projectPath|alias>
-unitycli tools search '<k1|k2|...>' --page-size 20 --instance <id|projectPath|alias>
+unitycli tools group list <group> --instance <id|projectPath|alias>
+unitycli tools search '<k1|k2|...>' --instance <id|projectPath|alias>
 unitycli tools describe <tool> --instance <id|projectPath|alias>
 unitycli tools run <tool> --input '<json>' --instance <id|projectPath|alias>
+unitycli extensions list
+unitycli extensions install <extension>
+unitycli extensions remove <extension>
+unitycli extensions doctor
 
-# 同一catalog的schema参数调用；省略name时列出command投影
-unitycli command --project-path <projectPath> --page-size 20
+unitycli command --project-path <projectPath>
 unitycli command <name> --field <value> --instance <id|projectPath|alias>
 ```
 
-显式`--instance`优先；`command --project-path <path>`绑定同一canonical项目实例；未传时只能从当前Unity项目CWD解析。没有连接实例时discovery返回稳定instance error，不返回静态或空目录。`instances list`逐文件隔离旧格式、损坏或不可读记录，合法实例继续返回，并用`invalidRecordCount`报告隔离数量；当前项目由Unity在ready时自动重建。需要清理历史记录时调用`instances prune --instance <id|projectPath|alias>`并检查`removed`、`remaining`、`deferred`，不得读取、转换、移动或手工删除内部记录。
+用户已给出目标或当前 Unity 项目 CWD 能唯一解析时可以直接使用；需要 selector 时优先只传一种，冲突的 `--instance` 与 `command --project-path` 会失败。不了解能力领域时可先看 group，已有业务关键词时可直接 search，第一次执行不了解的 Tool 前先 describe。
+
+PowerShell 中以单引号包住内联 JSON 和 `tools search '<k1|k2|...>'`。任务明确要求的业务值优先于 schema default 和 example；default/example只说明合法形状，不能把default/example当作连通性或probe调用，也不作为 smoke 调用。分页、artifact、大输出、弹窗和 host 等待按需读取 `references/operation-protocol.md`。
+
+- 等待 CLI 进程退出；`--timeout-ms` 应为 host 保留至少 5000 ms 的进程退出时间。不得手工每100毫秒循环轮询；超时不会停止 Unity、已开始的 effect 或 C# 工作。
+- `instances list` 默认过滤 offline 实例并只列出可用实例；需要完整盘点时使用 `instances list --all`，并读取 `invalidRecordCount`。旧、损坏或不可读记录由 CLI 隔离，不要读取、删除或改写内部记录文件；需要清理时使用 `instances prune --instance <id>`，依据返回的 `removed`、`deferred`、`remaining` 计数。启动、编译或 reload 后只等待有界 readiness。
+- `extensions list` 查看浅状态，`extensions install/remove` 管理安装，`extensions doctor` 执行完整检查；不要把 extension 文件系统检查当成普通 Tool 执行的隐式 probe。
+- `auth`、Unity Hub、Cloud、License 和 proxy 属于外部控制面，不由 `unitycli` 代管。
+
+## 通用规则
 
-执行不了解的Tool前必须`tools describe`，输入和行为以当前descriptor为准。PowerShell中必须用单引号包住`tools search '<k1|k2|...>'`的整个关键词，否则`|`会被shell解释为管道。schema default 与 `examples[].input` 描述合法默认业务值，按需 `examples[].execution` 描述 dry-run/timeout 控制；任务明确要求的业务值优先，不能把default/example当作连通性或probe调用。`tools group list`、`tools search`和省略name的`command`列表默认20项、最大100项；需要更多时把`pageInfo.nextCursor`原值传回`--cursor`。返回的Tool `name`就是exact调用名；group只用于筛选，不能拼到name前。stdout默认是单行紧凑JSON，只有显式`--pretty`才缩进。
+- descriptor 是输入、风险、availability、PlayMode 和依赖的当前契约；根据任务决定是否切换状态、预览或改用其他能力。
+- 调用公开 Tool 或 CLI 控制面即为授权。风险 metadata 只描述效果与可选 dry-run；Skill 不增加确认或预定义操作范围。
+- 等待 CLI 进程退出。`ok:true` 后检查任务相关的关键业务字段；返回结果不足或任务明确要求验证时，再使用只读 Tool 或业务 readback。
+- 失败时根据结构化 error 和 `nextActions` 形成恢复决策。`transient:true` 与 `nextActions` 仍是建议，不构成额外授权门。
+- `E_EXECUTION_TIMEOUT`、放行后连接丢失或缺少可信 terminal envelope只表示没有可信终态。对于`asset.refresh`、player build、Play Mode、Package install/remove/update和`test.run`，先按需发现对应域的`.status` Tool并只传原root `requestId`读取同一Editor session的active phase或exact terminal；status不重放effect。其他能力使用只读Tool或业务readback形成新的业务决策；CLI不自动重放，首次mutation POST后Editor session改变时也不会向新session重投。
+- 状态观察使用 `instances`、`doctor` 或 `editor.state`，不操作内部 registry 或 transport。
 
-`command`不建立第二套目录：native Tool使用完整精确名；Unity官方`[CliCommand]`完全兼容，项目或其他Package的`[CliCommand("test")]`在`tools`中固定名为`UnityPipeline_test`、group为`UnityPipeline`，可由`command test`或完整前缀名选择。`com.unity.pipeline` package自身命令已由native能力吸收并按provider identity抑制，不应期待其attribute原名存在。native精确重名优先；不得把不存在的名称映射到相似Tool。业务参数支持`--field value`、`--field=value`、boolean裸开关和按schema声明顺序的positional。
+## 能力扩展
 
-## 使用说明
+现有 Tool 不适合时，先判断是否真的需要 Unity 侧执行。普通源码或文本仍可直接处理；有界的临时 Unity 内存或 Editor API 逻辑可以考虑 `code.exec`。同步 C# 开始后不能由 CLI timeout 中止，复杂等待或不确定终态先读 `references/operation-protocol.md`。
 
-- 调用即授权。`destructiveHint`、`sideEffects`、`supportsDryRun`只描述效果；仅在确需预览时使用`--dry-run`。Skill不增加确认、意图复核或预定义操作范围；产品的cross-session mutation fence仍必须遵守。
-- 建议通过 `instances`、`doctor`、`tools run editor.state` 观察状态，不读取内部 Bridge 注册文件、端口或 URL，也不直接 ping transport。
-- CLI会在发送Unity业务请求前自行等待首次ready记录、编译/导入/重载完成和target session任务池放行；不得手工每100毫秒循环调用，也不得读取或操作内部状态。`--timeout-ms T`分别提供最多`T`的准入等待与放行后最多`T`的业务执行。
-- 准入deadline返回的`E_UNITY_BUSY`会明确证明`no business request was sent`，effect未开始，可以稍后提交新root。已进入池后的mutation lease busy不得解释为effect未开始。
-- `E_EXECUTION_TIMEOUT`、放行后连接丢失或缺少可信terminal envelope只表示没有可信终态。先用只读Tool或业务readback观察并形成新的业务决策；CLI不自动重放，首次mutation POST后Editor session改变时也不会向新session重投。`transient:true`与`nextActions`仍是建议，不构成额外授权门。
-- 运行公开CLI时必须等待该进程退出，不得后台分离。传入`--timeout-ms T`时，命令host至少等待`2 * T + 5000`毫秒；CLI在stdout完成或最多1秒后退出。host提前超时不等于CLI、准入grant或Unity effect已经停止。
-- `available:false`、`unavailableReason` 和 `playModeSupport` 说明当前可执行性；`source` 不参与路由。
-- blocker 在 `error.details.blockers` 时，可先读 `editor.dialogs`，再按返回的 dialogId 与 enabled button 调用 `editor.dialog.click`。
-- 大输出、envelope、artifact、分页、host等待预算和 session 说明见 `references/operation-protocol.md`。
-- 内置能力不足时，一次性操作可使用 `code.exec`；反复需要再读 `references/custom-tools.md`。`code.exec`不限制提交的同步C#，也不会拒绝死循环、长时间sleep、阻塞等待、锁等待或长期占用Unity API的代码。提交这类代码前必须先判断它对当前结果是否确有必要，并考虑有界写法或现有Tool能否达到同一结果；确有必要时可以原样执行。代码一旦在Unity主线程开始，`--timeout-ms`只能停止CLI等待，不能中止代码；Unity可能无响应、mutation owner不能收尾、业务状态部分改变或未知，恢复可能需要结束Editor进程。timeout不证明代码已停止，重试前必须观察业务状态。`--dry-run`只预览source hash，不编译、不执行，也不证明代码会结束。
+当能力需要稳定发现、typed schema、结构化结果、明确副作用、重复使用或团队共享时，读取 `references/custom-tools.md` 并实现项目自定义 `IUnityCliTool<TReq,TRes>`。自定义 Tool 仍从当前 catalog 发现、describe 和调用，不假设名称、group 或输入。
 
 ## 问题反馈
 

package/skills/unitycli/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "unitycli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "owner": "alps-unity-cli maintainers",
   "updated_at": "2026-08-27",
   "status": "active",

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",