@alpsckr/unitycli 0.4.0 → 0.4.2

package/schemas/init.schema.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://alpsckr.dev/unitycli/schemas/init.schema.json",
+  "title": "UnityCLI init envelope",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": { "const": true },
+        "requestId": { "type": "string", "minLength": 1 },
+        "data": {
+          "oneOf": [
+            { "$ref": "#/$defs/helpData" },
+            { "$ref": "#/$defs/discoverData" },
+            { "$ref": "#/$defs/packageData" },
+            { "$ref": "#/$defs/skillData" }
+          ]
+        }
+      },
+      "required": ["ok", "requestId", "data"],
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": { "const": false },
+        "requestId": { "type": "string", "minLength": 1 },
+        "error": { "$ref": "#/$defs/error" }
+      },
+      "required": ["ok", "requestId", "error"],
+      "additionalProperties": false
+    }
+  ],
+  "$defs": {
+    "nextActions": { "type": "array", "items": { "type": "string" } },
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "nextActions": { "$ref": "#/$defs/nextActions" },
+        "transient": { "type": "boolean" },
+        "retryAfterMs": { "type": "number", "minimum": 0 },
+        "details": { "x-unityCliAnyJson": true }
+      },
+      "required": ["code", "message", "nextActions", "transient", "retryAfterMs"],
+      "additionalProperties": false
+    },
+    "helpData": {
+      "type": "object",
+      "properties": {
+        "action": { "const": "init_help" },
+        "audience": { "const": "ai" },
+        "protocolVersion": { "const": 2 },
+        "aiInstructions": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "commands": { "type": "object", "additionalProperties": { "type": "string" } },
+        "nextCommand": { "type": "string" },
+        "nextActions": { "$ref": "#/$defs/nextActions" }
+      },
+      "required": ["action", "audience", "protocolVersion", "aiInstructions", "commands", "nextCommand", "nextActions"],
+      "additionalProperties": false
+    },
+    "discoverData": {
+      "type": "object",
+      "properties": {
+        "action": { "const": "init_discover" },
+        "cwd": { "type": "string" },
+        "repositoryRoot": { "type": ["string", "null"] },
+        "unityProjects": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "unityVersion": { "type": "string" },
+              "relation": { "enum": ["cwd", "ancestor", "descendant"] },
+              "depth": { "type": "integer", "minimum": 0 },
+              "bridge": {
+                "type": "object",
+                "properties": {
+                  "status": { "enum": ["installed", "missing", "damaged", "drifted", "conflict", "unverifiable", "not-inspected"] },
+                  "installedVersion": { "type": "string" },
+                  "availableVersion": { "type": "string" },
+                  "reasonCode": { "type": "string" },
+                  "message": { "type": "string" }
+                },
+                "required": ["status"],
+                "additionalProperties": false
+              },
+              "editor": {
+                "type": "object",
+                "properties": {
+                  "status": { "enum": ["running", "stopped", "unverifiable", "not-inspected"] },
+                  "processCount": { "type": "integer", "minimum": 0 },
+                  "message": { "type": "string" }
+                },
+                "required": ["status"],
+                "additionalProperties": false
+              }
+            },
+            "required": ["path", "unityVersion", "relation", "depth", "bridge", "editor"],
+            "additionalProperties": false
+          }
+        },
+        "skill": {
+          "type": "object",
+          "properties": {
+            "workspace": { "type": "string" },
+            "recommendedTarget": { "type": "string" },
+            "explicitTargetSupported": { "const": true },
+            "status": { "enum": ["installed", "missing", "drifted", "damaged"] },
+            "targetPath": { "type": "string" },
+            "sourceHash": { "$ref": "#/$defs/sha256" },
+            "hash": { "$ref": "#/$defs/sha256" },
+            "message": { "type": "string" }
+          },
+          "required": ["workspace", "recommendedTarget", "explicitTargetSupported", "status", "targetPath", "sourceHash"],
+          "additionalProperties": false
+        },
+        "requiredDecisions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "enum": ["bridgeProjects", "closeEditor"] },
+              "question": { "type": "string" },
+              "choices": { "type": "array", "items": { "type": "string" } },
+              "projectPath": { "type": "string" },
+              "multiple": { "type": "boolean" }
+            },
+            "required": ["id", "question", "multiple"],
+            "additionalProperties": false
+          }
+        },
+        "scan": {
+          "type": "object",
+          "properties": {
+            "scannedDirectories": { "type": "integer", "minimum": 0, "maximum": 2000 },
+            "truncated": { "type": "boolean" },
+            "maxDescendantDepth": { "const": 4 },
+            "maxScannedDirectories": { "const": 2000 },
+            "maxUnityProjects": { "const": 100 }
+          },
+          "required": ["scannedDirectories", "truncated", "maxDescendantDepth", "maxScannedDirectories", "maxUnityProjects"],
+          "additionalProperties": false
+        },
+        "nextActions": { "$ref": "#/$defs/nextActions" }
+      },
+      "required": ["action", "cwd", "repositoryRoot", "unityProjects", "skill", "requiredDecisions", "nextActions"],
+      "additionalProperties": false
+    },
+    "packageData": {
+      "type": "object",
+      "properties": {
+        "action": { "enum": ["init_package", "init_package_check"] },
+        "projectPath": { "type": "string" },
+        "projectIdentity": { "type": "object" },
+        "editorClose": {
+          "type": "object",
+          "properties": {
+            "status": { "enum": ["not-running", "closed"] },
+            "requested": { "type": "integer", "minimum": 0 }
+          },
+          "required": ["status", "requested"],
+          "additionalProperties": false
+        },
+        "package": {
+          "type": "object",
+          "properties": { "status": { "enum": ["installed", "missing", "damaged", "drifted", "conflict"] } },
+          "required": ["status"]
+        },
+        "nextActions": { "$ref": "#/$defs/nextActions" }
+      },
+      "required": ["action", "projectPath", "package", "nextActions"],
+      "additionalProperties": false
+    },
+    "skillData": {
+      "type": "object",
+      "properties": {
+        "action": { "enum": ["init_skill", "init_skill_check"] },
+        "agent": { "enum": [".agents", "claude"] },
+        "scope": { "enum": ["workspace", "user"] },
+        "workspace": { "type": "string" },
+        "target": { "type": "string" },
+        "changes": { "type": "array" },
+        "skill": {
+          "type": "object",
+          "properties": {
+            "status": { "enum": ["installed", "missing", "drifted", "damaged"] },
+            "targetPath": { "type": "string" },
+            "sourceHash": { "$ref": "#/$defs/sha256" },
+            "hash": { "$ref": "#/$defs/sha256" },
+            "message": { "type": "string" }
+          },
+          "required": ["status", "targetPath", "sourceHash"],
+          "additionalProperties": false
+        },
+        "nextActions": { "$ref": "#/$defs/nextActions" }
+      },
+      "required": ["action", "skill", "nextActions"],
+      "oneOf": [
+        { "type": "object", "required": ["agent", "scope"] },
+        { "type": "object", "required": ["target"] }
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/instances.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://alpsckr.dev/unitycli/schemas/instances.schema.json",
+  "title": "UnityCLI instances envelope",
+  "oneOf": [
+    { "$ref": "#/$defs/listSuccess" },
+    { "$ref": "#/$defs/pruneSuccess" },
+    { "$ref": "#/$defs/errorEnvelope" }
+  ],
+  "$defs": {
+    "instanceSummary": {
+      "type": "object",
+      "properties": {
+        "instanceId": { "type": "string", "pattern": "^unity-[a-f0-9]{64}$" },
+        "canonicalProjectPath": { "type": "string", "minLength": 3 },
+        "displayProjectPath": { "type": "string", "minLength": 3 },
+        "projectName": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["ready", "transitioning", "blocked", "unresponsive", "unverifiable", "offline", "conflict"] },
+        "unityVersion": { "type": "string", "minLength": 1 },
+        "alias": { "type": "string", "minLength": 1 }
+      },
+      "required": ["instanceId", "canonicalProjectPath", "displayProjectPath", "projectName", "status"],
+      "additionalProperties": false
+    },
+    "listData": {
+      "type": "object",
+      "properties": {
+        "instances": { "type": "array", "items": { "$ref": "#/$defs/instanceSummary" } },
+        "hiddenOfflineCount": { "type": "integer", "minimum": 0 },
+        "invalidRecordCount": { "type": "integer", "minimum": 1 }
+      },
+      "required": ["instances"],
+      "additionalProperties": false
+    },
+    "retention": {
+      "type": "object",
+      "properties": {
+        "offlineMax": { "const": 100 },
+        "damagedMax": { "const": 20 },
+        "maxAgeDays": { "const": 30 },
+        "scanLimit": { "const": 2000 },
+        "deleteLimit": { "const": 20 }
+      },
+      "required": ["offlineMax", "damagedMax", "maxAgeDays", "scanLimit", "deleteLimit"],
+      "additionalProperties": false
+    },
+    "pruneData": {
+      "type": "object",
+      "properties": {
+        "removed": { "type": "integer", "minimum": 0 },
+        "remaining": { "type": "integer", "minimum": 0 },
+        "deferred": { "type": "integer", "minimum": 0 },
+        "scanned": { "type": "integer", "minimum": 0, "maximum": 2000 },
+        "truncated": { "type": "boolean" },
+        "retention": { "$ref": "#/$defs/retention" }
+      },
+      "required": ["removed", "remaining", "deferred", "scanned", "truncated", "retention"],
+      "additionalProperties": false
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "nextActions": { "type": "array", "items": { "type": "string" } },
+        "transient": { "type": "boolean" },
+        "retryAfterMs": { "type": "number", "minimum": 0 },
+        "details": { "x-unityCliAnyJson": true }
+      },
+      "required": ["code", "message", "nextActions", "transient", "retryAfterMs"],
+      "additionalProperties": false
+    },
+    "listSuccess": {
+      "type": "object",
+      "properties": {
+        "ok": { "const": true },
+        "requestId": { "type": "string", "minLength": 1 },
+        "data": { "$ref": "#/$defs/listData" }
+      },
+      "required": ["ok", "requestId", "data"],
+      "additionalProperties": false
+    },
+    "pruneSuccess": {
+      "type": "object",
+      "properties": {
+        "ok": { "const": true },
+        "requestId": { "type": "string", "minLength": 1 },
+        "data": { "$ref": "#/$defs/pruneData" }
+      },
+      "required": ["ok", "requestId", "data"],
+      "additionalProperties": false
+    },
+    "errorEnvelope": {
+      "type": "object",
+      "properties": {
+        "ok": { "const": false },
+        "requestId": { "type": "string", "minLength": 1 },
+        "error": { "$ref": "#/$defs/error" }
+      },
+      "required": ["ok", "requestId", "error"],
+      "additionalProperties": false
+    }
+  }
+}

package/skills/unitycli/SKILL.md

@@ -19,25 +19,37 @@ FeedbackMode: off
 - 已连接实例的目录同时包含 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 精确重名优先。
 
+## 安装协议
+
+当用户要求安装、配置、检查或修复 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> --instance <id|projectPath|alias>
-unitycli tools search '<k1|k2|...>' --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 describe <tool> --instance <id|projectPath|alias>
 unitycli tools run <tool> --input '<json>' --instance <id|projectPath|alias>
 
 # 同一catalog的schema参数调用；省略name时列出command投影
-unitycli command --project-path <projectPath>
+unitycli command --project-path <projectPath> --page-size 20
 unitycli command <name> --field <value> --instance <id|projectPath|alias>
 ```
 
-显式`--instance`优先；`command --project-path <path>`绑定同一canonical项目实例；未传时只能从当前Unity项目CWD解析。没有连接实例时discovery返回稳定instance error，不返回静态或空目录。`instances list`逐文件隔离旧格式、损坏或不可读记录，合法Registry v3实例继续返回；`invalidRecordCount`出现时先运行`doctor`，不得读取、转换、移动或删除内部记录。显式选择对应坏instanceId仍会严格失败。
+显式`--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`，不得读取、转换、移动或手工删除内部记录。
 
-执行不了解的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`返回的Tool `name`就是exact调用名；group只用于筛选，不能拼到name前。
+执行不了解的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`才缩进。
 
 `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。
 
@@ -45,7 +57,7 @@ unitycli command <name> --field <value> --instance <id|projectPath|alias>
 
 - 调用即授权。`destructiveHint`、`sideEffects`、`supportsDryRun`只描述效果；仅在确需预览时使用`--dry-run`。Skill不增加确认、意图复核或预定义操作范围；产品的cross-session mutation fence仍必须遵守。
 - 建议通过 `instances`、`doctor`、`tools run editor.state` 观察状态，不读取内部 Bridge 注册文件、端口或 URL，也不直接 ping transport。
-- CLI会在发送Unity业务请求前自行等待target session任务池放行；不得手工每100毫秒循环调用，也不得读取或操作内部准入identity。`--timeout-ms T`分别提供最多`T`的准入等待与放行后最多`T`的业务执行。
+- 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已经停止。

package/skills/unitycli/manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "unitycli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "owner": "alps-unity-cli maintainers",
-  "updated_at": "2026-08-13",
+  "updated_at": "2026-08-27",
   "status": "active",
   "maturity_tier": "governed",
   "lifecycle_stage": "governed",

package/skills/unitycli/references/custom-tools.md

@@ -96,16 +96,16 @@ AI 使用当前实例的统一公开目录自发现和执行：
 
 ```powershell
 unitycli tools group --instance <id|projectPath|alias>
-unitycli tools group list <group> --instance <id|projectPath|alias>
+unitycli tools group list <group> --page-size 20 --instance <id|projectPath|alias>
 unitycli tools describe <custom-tool> --instance <id|projectPath|alias>
 unitycli tools run <custom-tool> --input '<json>' --instance <id|projectPath|alias>
 ```
 
-`<group>` 必须来自当前实例 `tools group` 的真实输出；不要假设项目 Tool 位于 `custom` 组。`source` 只作描述/审计，不改变发现或执行路径。
+`<group>` 必须来自当前实例 `tools group` 的真实输出；不要假设项目 Tool 位于 `custom` 组。存在`pageInfo.nextCursor`时必须继续读取所需页面。`source` 只作内部描述/审计，不改变发现或执行路径。
 
 ## 最小验证
 
 1. Unity 编译无错误。
-2. `tools group` 与 `tools group list <group>` 能从同一实例完整目录发现 Tool。
+2. `tools group` 与 `tools group list <group>` 的分页结果能从同一实例完整目录发现 Tool。
 3. `tools describe <tool>` 的 schema、风险、target、Play Mode 语义足以让陌生 AI 一次调用成功。
 4. `tools run <tool> --input '<json>' --instance <id|projectPath|alias>` 覆盖默认正向、代表性可选参数和错误路径。

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

@@ -6,9 +6,11 @@
 
 `--instance <full-id|canonical-project-path|alias>`是通用显式实例选择器；`command --project-path <path>`是同一canonical identity选择语法。显式空值必须失败；业务`input.instance`不是selector。未传selector时只从当前Unity项目CWD解析；无法确定实例即稳定失败，`--project`和Tool input都不能选实例。
 
-`target alias` 只维护 canonical project identity alias。`source` 只供说明和审计，不影响显示、describe、owner 路由或执行。连接实例的 Tool 目录是权威目录；离线静态 catalog 不能替代它。PowerShell中执行多token搜索时使用`tools search '<k1|k2|...>'`；单引号必须包住完整关键词，避免`|`被解释为shell管道。
+`target alias` 只维护 canonical project identity alias。`source` 只供说明和审计，不影响显示、describe、owner 路由或执行，也不进入搜索结果。连接实例的 Tool 目录是权威目录；离线静态 catalog 不能替代它。PowerShell中执行多token搜索时使用`tools search '<k1|k2|...>'`；单引号必须包住完整关键词，避免`|`被解释为shell管道。
 
-`instances list`逐个验证当前Registry v3正式文件。旧格式、损坏或不可读文件不参与路由，也不阻断其他合法实例；存在时结果包含`invalidRecordCount`，应使用`doctor`读取计数告警。不得读取、兼容解析、转换、移动或删除内部文件。显式选择对应坏instanceId仍严格失败。
+`tools group list`、`tools search`和省略name的`command`列表按名称稳定分页，默认20项、最大100项。存在`pageInfo.nextCursor`时，将其原值传回同一查询的`--cursor`；不要重新解释或递增cursor。stdout默认是单行紧凑JSON，`--pretty`只增加缩进。
+
+`instances list`逐个验证当前正式实例记录。旧格式、损坏或不可读文件不参与路由，也不阻断其他合法实例；存在时结果包含`invalidRecordCount`。当前项目由Unity在ready时自动重建。需要清理历史记录时调用`instances prune --instance <id|projectPath|alias>`并检查`removed`、`remaining`、`deferred`、`scanned`和`truncated`；不得读取、兼容解析、转换、移动或手工删除内部文件。
 
 ## Descriptor
 
@@ -46,7 +48,7 @@ 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`的准入预算。准入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都只能消费该预算，不能刷新第三份预算。
 
 `E_EXECUTION_TIMEOUT`、放行后的transport丢失、进程中断或没有可信terminal envelope时，只能确定本次调用没有返回可信终态，不能据此判断mutation是否发生。先读取对象、场景、Package、build/test状态或artifact manifest；只有形成新的业务决策后才提交新请求，不把outcome unknown自动重放。
 
@@ -80,4 +82,4 @@ unitycli extensions remove <id> --project <path>
 unitycli extensions doctor --project <path>
 ```
 
-Skill/runtime bundle 安装使用 `init`；`init --check` 只读校验。Unity project 文件投影完成后，如任务要求 Editor 效果，仍需在已连接实例中完成 import/compile 和业务 readback。
+安装协议先使用`unitycli init help`学习，再由`init discover`只读返回当前项目计划。Bridge使用`init package --project <UnityProject>`安装；准确目标Unity正在运行且用户同意正常关闭时增加`--close-editor`，不得强制终止或替用户处理未保存场景。Skill明确目录使用`init skill --target <SkillDirectory>`，预设目标仍可使用`init skill --agent <.agents|claude> --scope <workspace|user>`，workspace scope同时传`--workspace <path>`；每种形式都用原命令加`--check`校验。用户已指定的目标不得重复询问。Bridge与Skill是独立效果，一个失败不阻断另一个。不得使用裸`init`或把两种效果合并为一个命令。Unity project文件投影完成后，如任务要求Editor效果，仍需在已连接实例中完成import/compile和业务readback。

package/skills/unitycli/reports/output_quality_scorecard.md

@@ -24,7 +24,7 @@ The feedback output contract requires category, concise issue summary, optional
 | Feedback privacy negatives | PASS | Secret/endpoint/path negative matrix | Novel secret formats can still exist |
 | Concurrent JSONL validity | PASS | 16 parallel Windows PowerShell writers | Cross-session Windows desktop contention not measured |
 | Rolling bound | PASS | Main + 3 archives, each <= 64 KiB | Longitudinal retention utility not measured |
-| Installed bundle reachability | PASS | Public init/drifted-update/check/recorder smoke for all three agents | Verified on the selected Dev project only |
+| Installed bundle reachability | PASS | Public exact-target and preset workspace/user install, drifted-update, check, and recorder smoke | Verified with isolated filesystem targets |
 | Clean Agent interpretation | PASS | Black-box runtime discovery transcript and main-agent audit | Human adjudication unavailable |
 
 ## Rollback Boundary

package/skills/unitycli/reports/trust-report.md

@@ -36,7 +36,7 @@ The Skill does not add confirmation, intent review, or a predefined operation ra
 
 - Full repository tests: 876/876 PASS; targeted Skill/installer/docs regression: 61/61 PASS.
 - Recorder concurrency, rotation, privacy negatives, PowerShell 5.1 BOM, and non-ASCII stdout: PASS.
-- Public runtime install, drifted update, check, marker preservation, and installed-recorder smoke across `.pi`, `.claude`, and `.agents`: PASS.
+- Public exact-target and preset runtime install, drifted update, check, marker preservation, and installed-recorder smoke: PASS.
 - Resource boundary: 963 estimated initial-load tokens (691 Skill body tokens), limit 1300.
 - Trigger fixture gate: 29/29 classifications.
 - Output assertion gate: 5/5 with-skill cases, 100% pass rate.

package/unitypkg/Editor/Bridge/BridgeCommandRegistry.cs

@@ -86,6 +86,7 @@ namespace UnityCli
             RegisterInstalledExtensionCommands(registry);
             RegisterCodeExecCommand(registry);
             RegisterEditorStateSnapshotCommand(registry);
+            RegisterInstanceCleanupCommand(registry);
             UnityCliCompileCoordinator.Register(registry);
             UnityCliLiveBuildCoordinator.Register(registry);
             UnityCliLiveRefreshCoordinator.Register(registry);

package/unitypkg/Editor/Bridge/BridgeWorkQueue.cs

@@ -60,22 +60,34 @@ namespace UnityCli
             // pulse只证明EditorApplication.update最近推进；具体请求仍由TryStart证明开始。
             Volatile.Write(ref mainThreadPulseTimestamp, System.Diagnostics.Stopwatch.GetTimestamp());
             Interlocked.Increment(ref mainThreadPulseSequence);
-            cachedIsCompiling = EditorApplication.isCompiling;
-            cachedIsUpdating = EditorApplication.isUpdating;
+            var listenerWasStarted = started;
+            var isCompiling = EditorApplication.isCompiling;
+            var isUpdating = EditorApplication.isUpdating;
+            var isBuilding = BuildPipeline.isBuildingPlayer;
+            var isPlayModeChanging = IsPlayModeChanging();
+            var lifecycleChanged = cachedIsCompiling != isCompiling
+                || cachedIsUpdating != isUpdating
+                || cachedIsBuilding != isBuilding
+                || cachedIsPlayModeChanging != isPlayModeChanging;
+            cachedIsCompiling = isCompiling;
+            cachedIsUpdating = isUpdating;
             cachedIsPlayingOrWillChangePlaymode = EditorApplication.isPlayingOrWillChangePlaymode;
             cachedIsPlaying = EditorApplication.isPlaying;
-            cachedIsBuilding = BuildPipeline.isBuildingPlayer;
-            cachedIsPlayModeChanging = IsPlayModeChanging();
+            cachedIsBuilding = isBuilding;
+            cachedIsPlayModeChanging = isPlayModeChanging;
             AdvanceBridgeStartup();
             UnityCliSessionMutationLease.TryFinalizeOwnedPlayModeRoot();
             UnityCliWaitScheduler.Tick();
 
-            // 生命周期变化会即时登记；这里仅低频刷新，修复漏事件并更新诊断快照。
-            if (started && EditorApplication.timeSinceStartup >= nextRegistryRefreshAt)
+            // 新listener先保留至少一个主线程update的transitioning状态；后续生命周期变化即时发布，30秒刷新只修复漏事件。
+            if (listenerWasStarted && started
+                && (readyPublicationPending || lifecycleChanged || EditorApplication.timeSinceStartup >= nextRegistryRefreshAt))
             {
+                readyPublicationPending = false;
                 RegisterInstance("ready");
                 nextRegistryRefreshAt = EditorApplication.timeSinceStartup + RegistryRefreshSeconds;
             }
+            TickInstancePublicationRetry();
             var startedThisTick = 0;
             while (startedThisTick < MaxWorkStartsPerTick)
             {