@alpsckr/unitycli 0.4.1 → 0.4.3

package/docs/extensions.md

@@ -16,6 +16,8 @@ Bridge 与 AI Skill 是两个独立安装对象。先用安装协议发现并选
 unitycli init help
 unitycli init discover
 unitycli init package --project C:\path\UnityProject
+# 仅在用户批准正常关闭这个准确项目后使用
+unitycli init package --project C:\path\UnityProject --close-editor
 unitycli init package --project C:\path\UnityProject --check
 ```
 
@@ -24,7 +26,7 @@ Bridge 安装内容：
 - `Packages/unitycli.install.json` — 安装元数据（项目 hash、source hash、managed-file hash、版本与支持范围）
 - `Packages/com.alpsckr.unitycli/unitycli.files.json` — 受管文件路径清单
 
-Skill 使用`init skill`安装到用户选择的`.agents`或Claude workspace/user目标，不属于Unity项目Package安装。
+Skill 使用`init skill --target <SkillDirectory>`安装到用户明确目录，或使用`.agents`/Claude workspace/user预设；它不属于Unity项目Package安装，Bridge失败也不阻止这个独立效果。
 
 ### 项目能力发现
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpsckr/unitycli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Windows-first CLI for UnityCLI automation.",
   "type": "module",
   "bin": {

package/schemas/init.schema.json

@@ -52,7 +52,7 @@
       "properties": {
         "action": { "const": "init_help" },
         "audience": { "const": "ai" },
-        "protocolVersion": { "type": "integer", "minimum": 1 },
+        "protocolVersion": { "const": 2 },
         "aiInstructions": { "type": "array", "minItems": 1, "items": { "type": "string" } },
         "commands": { "type": "object", "additionalProperties": { "type": "string" } },
         "nextCommand": { "type": "string" },
@@ -67,16 +67,87 @@
         "action": { "const": "init_discover" },
         "cwd": { "type": "string" },
         "repositoryRoot": { "type": ["string", "null"] },
-        "limits": { "type": "object" },
-        "scan": { "type": "object" },
-        "unityProjects": { "type": "array" },
-        "skillWorkspaces": { "type": "array" },
-        "skillCopies": { "type": "array" },
-        "shadowingRisks": { "type": "array" },
-        "requiredDecisions": { "type": "array", "minItems": 4 },
+        "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", "limits", "scan", "unityProjects", "skillWorkspaces", "skillCopies", "shadowingRisks", "requiredDecisions", "nextActions"],
+      "required": ["action", "cwd", "repositoryRoot", "unityProjects", "skill", "requiredDecisions", "nextActions"],
       "additionalProperties": false
     },
     "packageData": {
@@ -85,6 +156,15 @@
         "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"] } },
@@ -102,6 +182,7 @@
         "agent": { "enum": [".agents", "claude"] },
         "scope": { "enum": ["workspace", "user"] },
         "workspace": { "type": "string" },
+        "target": { "type": "string" },
         "changes": { "type": "array" },
         "skill": {
           "type": "object",
@@ -117,7 +198,11 @@
         },
         "nextActions": { "$ref": "#/$defs/nextActions" }
       },
-      "required": ["action", "agent", "scope", "skill", "nextActions"],
+      "required": ["action", "skill", "nextActions"],
+      "oneOf": [
+        { "type": "object", "required": ["agent", "scope"] },
+        { "type": "object", "required": ["target"] }
+      ],
       "additionalProperties": false
     }
   }

package/skills/unitycli/SKILL.md

@@ -1,70 +1,54 @@
 ---
 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 精确重名优先。
-
-## 安装协议
-
-当用户要求安装、配置、检查或修复 UnityCLI 时，唯一学习入口是：
-
-```powershell
-unitycli init help
-```
-
-严格执行返回的版本化`aiInstructions`，不要依赖本Skill记忆安装步骤。先运行`init discover`，再向用户询问要安装Bridge的Unity项目，以及Skill的agent、scope和常用workspace；不得静默选择。多个Bridge项目逐个严格串行安装，每次等待terminal并执行对应`--check`后才能继续；Skill通常只安装到用户选择的一个`.agents`或Claude workspace/user目标。第一次非预期CLI失败或业务check失败立即停止，不重试、纠参或继续后续effect。安装流程不得启动、关闭、重启或终止Unity Editor。用户完成选择后的明确安装调用即授权，不增加第二次确认。
+- 需要 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 优先。
 
-## 执行骨架
+## 发现与调用
 
 ```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>
 
-# 同一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 只说明合法形状，不作为 probe。分页、artifact、大输出、弹窗和 host 等待按需读取 `references/operation-protocol.md`。
+
+## 通用规则
 
-执行不了解的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只表示没有可信终态。先用只读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.1",
+  "version": "0.4.3",
   "owner": "alps-unity-cli maintainers",
   "updated_at": "2026-08-27",
   "status": "active",

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

@@ -82,4 +82,4 @@ unitycli extensions remove <id> --project <path>
 unitycli extensions doctor --project <path>
 ```
 
-安装协议先使用`unitycli init help`学习，再由`init discover`只读发现现场。Bridge只用`init package --project <UnityProject>`安装，并用同命令加`--check`校验；Skill只用`init skill --agent <.agents|claude> --scope <workspace|user>`，workspace scope还必须传`--workspace <path>`，同命令加`--check`校验。不得使用裸`init`或混装Bridge与Skill。Unity project文件投影完成后，如任务要求Editor效果，仍需在已连接实例中完成import/compile和业务readback；安装协议本身不得管理Unity进程。
+安装协议先使用`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 workspace/user install, drifted-update, check, and recorder smoke for `.agents` and Claude | Verified with isolated filesystem targets |
+| 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 `.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.alpsckr.unitycli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "displayName": "UnityCLI",
   "description": "Editor package used by UnityCLI commands.",
   "unity": "2022.3",