@alpsckr/unitycli 0.4.0 → 0.4.1

package/docs/command-execution.md

@@ -61,15 +61,20 @@ object、array和任意JSON值必须是有效JSON。字段大小写和下划线
 ## Command级控制项
 
 ```powershell
+# 省略name时只返回有界路由摘要；参数在单命令help中读取
+unitycli command --project-path C:\path\MyProject --page-size 20
+unitycli command --project-path C:\path\MyProject --page-size 20 --cursor 20
+
 unitycli command --project-path C:\path\MyProject <name> ...
 unitycli command --timeout 120 <name> ...
 unitycli command <name> ... --timeout-ms 120000 --dry-run
 ```
 
 - `--project-path <path>`绑定现有canonical项目实例，不直连endpoint，也不写入active target。
+- 省略name时，`--page-size`默认20、最大100；存在`pageInfo.nextCursor`时将其原值传回`--cursor`。列表项不展开parameters，使用`command <name> --help`读取参数。
 - `--timeout <seconds>`位于name前；`--timeout-ms <milliseconds>`使用本项目执行控制语义。
 - `--dry-run`、`--runtime`、`--artifact-dir`和`--instance`仍是执行/选择控制项，不进入Tool business input。
-- `--raw`只改变同一JSON envelope的排版。
+- stdout默认是单行紧凑JSON；`--pretty`只增加缩进，不改变envelope字段。
 
 ## 等价性
 

package/docs/development.md

@@ -0,0 +1,91 @@
+# Local Development
+
+## Requirements
+
+- Windows
+- Node.js 20 or newer
+- PowerShell 7
+- Unity 2022.3 for the Dev validation project
+
+## Build And Test
+
+```powershell
+npm install
+npm run build:test
+npm test
+npm run architecture:validate
+```
+
+`build:test` regenerates extension projections, TypeScript registries, completion contracts, command contracts, protocol output, Tool schemas, and the canonical Package file manifest before compiling production and test code.
+
+Package integrity checks can be run directly:
+
+```powershell
+npm run package-closure:validate
+npm run init-contract:validate
+```
+
+The Package closure audit enforces:
+
+- exact canonical `unitypkg` file paths, sizes, per-file SHA-256, and tree hash;
+- zero package-owned Roslyn DLLs;
+- Unity-provided precompiled references;
+- the Unity Editor compiler path used by `code.exec`;
+- bounded assembly-conflict policy.
+
+## Run The Source CLI
+
+```powershell
+node dist/cli.js --help
+node dist/cli.js init help
+node dist/cli.js init discover
+```
+
+For global local development:
+
+```powershell
+npm link
+unitycli --version
+```
+
+## Dev Unity Isolation
+
+Only `Dev/UnityProject` is controlled by automated validation. Launch both Unity and the source CLI with the process-local environment variable:
+
+```powershell
+$env:UNITYCLI_DATA_DIR = Join-Path $env:LOCALAPPDATA 'UnityCli-Dev'
+```
+
+Do not set this variable globally. Before and after validation, record:
+
+- the formal `%LOCALAPPDATA%\UnityCli` file set;
+- existing Unity process IDs and project command lines;
+- Dev registry and temporary files;
+- every changed Dev fixture and its restoration state.
+
+Use the current source installation route before Unity validation:
+
+```powershell
+$project = (Resolve-Path 'Dev/UnityProject').Path
+node dist/cli.js init package --project $project
+node dist/cli.js init package --project $project --check
+```
+
+## Validation Order
+
+1. Finish source, tests, contracts, generated outputs, public Skill, and docs.
+2. Run focused build, type checks, tests, and contract audits.
+3. Run the affected isolated Dev Unity matrix.
+4. Audit the final diff and npm artifact.
+
+A failed validation step stops the current validation stage. Classify it as product, harness, environment, specification, or test-scope failure; fix the owner and rerun every affected check fresh.
+
+## Packaging
+
+Inspect the npm artifact without publishing:
+
+```powershell
+npm pack --dry-run --json
+```
+
+The artifact must contain the canonical `unitypkg`, contracts, schemas, public Skill source, docs, and README. Publishing, tagging, pushing, installing a release artifact, or changing versions requires the repository release procedure and explicit user authorization.

package/docs/error-codes.md

@@ -43,11 +43,11 @@ alps-unity-cli 使用结构化错误码，包含机器可读的 `code`、`transi
 | 错误码 | 含义 | 恢复 |
 |--------|------|------|
 | `E_INSTANCE_REQUIRED` | 没有显式 selector，CWD 也不在 Unity 项目中 | 传完整 `--instance <id|projectPath|alias>` 或从项目目录调用 |
-| `E_INSTANCE_NOT_FOUND` | selector 无法解析到 canonical project identity | 运行 `instances list` 或核对项目路径/alias |
-| `E_INSTANCE_NOT_RUNNING` | 项目 identity 已确定，但没有可验证的运行中 Editor | 打开该项目并等待 Bridge 注册 |
+| `E_INSTANCE_NOT_FOUND` | selector 在当前截止时间内没有对应项目记录 | 核对项目路径/alias；完整instance ID在目标Unity启动时会等待首次记录 |
+| `E_INSTANCE_NOT_RUNNING` | 项目 identity 已确定，且没有可验证的运行中 Editor | 打开该项目；CLI会在本次调用内等待首次ready记录 |
 | `E_INSTANCE_CONFLICT` | 至少两个已验证live process claim声明同一项目 | 关闭重复Editor，只保留目标session |
 | `E_INSTANCE_UNVERIFIABLE` | PID/start、project claim、Registry读取或权限证据不完整 | 重新观察identity；不得把未知mutation自动重投 |
-| `E_INSTANCE_IDENTITY_MISMATCH` | Registry、Health或请求中的canonical identity不一致 | 停止调用并检查项目移动、Registry claim或Bridge安装 |
+| `E_INSTANCE_IDENTITY_MISMATCH` | 当前Unity无法在截止时间内重建并证明一致的项目身份 | 更新匹配的CLI/Package，打开该项目并重新观察；不要手工修改内部记录 |
 | `E_UNITY_UNRESPONSIVE` | transport identity存在，但近期Unity主线程pulse或Bridge响应不可证明 | 读取`editor.state`与`editor.dialogs`后处理transition/modal |
 | `E_INSTANCE_PROJECT_MISMATCH` | 显式项目约束与 selector 指向不同 identity | 统一 `--project` 和 `--instance` |
 | `E_INSTANCE_PATH_UNAVAILABLE` | 无法取得可证明的物理 canonical path | 修复不可访问路径、broken link 或 reparse 配置 |
@@ -168,8 +168,8 @@ alps-unity-cli 使用结构化错误码，包含机器可读的 `code`、`transi
 | 错误码 | 含义 |
 |--------|------|
 | `E_UNITY_BLOCKED` | effect 前已证明 Unity/UI blocker；原错误的 `details.blockers` 含结构化弹窗摘要 |
-| `E_UNITY_BUSY` | 两种可区分语义：任务池准入deadline到达时message明确`no business request was sent`，effect未开始且可稍后提交新root；已进入池后mutation lease竞争则业务请求已经发送，等待当前mutation terminal后再决策 |
-| `E_UNITY_TRANSITION_TIMEOUT` | 可恢复 lifecycle transition 未在当前阶段的 absolute deadline 内稳定 |
+| `E_UNITY_BUSY` | 任务池、修改owner或实例清理owner正在工作；按message与`nextActions`区分是否尚未发送业务请求，`instances prune`可按`retryAfterMs`稍后重试 |
+| `E_UNITY_TRANSITION_TIMEOUT` | 首次ready记录或可恢复状态变化未在原命令截止时间内稳定；确认Unity仍在推进后才使用更大的timeout重试 |
 | `E_EXECUTION_TIMEOUT` | 已放行调用未在execution deadline内返回终态、连接提前断开，或首次mutation POST后Editor session改变；outcome unknown，CLI不向新session自动重投 |
 | `E_REQUEST_ID_REUSED` | 同一 root request ID 被不同 exact request bytes 使用 |
 | `E_TOOL_COMPLETION_PROOF_INVALID` | Tool 返回值不满足其 completion contract 或 proof 校验 |

package/docs/extensions.md

@@ -10,23 +10,21 @@
 
 ### Bridge 包安装
 
-通过 `init` 命令安装 Unity Editor Bridge 包：
+Bridge 与 AI Skill 是两个独立安装对象。先用安装协议发现并选择项目，再单独安装或检查 Bridge：
 
 ```powershell
-# 默认安装 Bridge；若项目已有 .pi/.claude/.agents，则自动安装 Skill
-unitycli init --project C:\path\MyProject
-
-# 仅安装 Bridge 包
-unitycli init --project C:\path\MyProject --pkg-only
-
-# 检查安装状态
-unitycli init --check --project C:\path\MyProject
+unitycli init help
+unitycli init discover
+unitycli init package --project C:\path\UnityProject
+unitycli init package --project C:\path\UnityProject --check
 ```
 
-安装内容：
-- `Packages/com.alpsckr.unitycli/` — Bridge 包（copy 模式）
-- `Packages/unitycli.install.json` — 安装元数据（项目 hash、版本、支持范围）
-- `.pi/skills/unitycli/`、`.claude/skills/unitycli/` 或 `.agents/skills/unitycli/` — 仅当对应 Agent 目录已存在，或显式传入 `--agent` 时安装完整 runtime bundle（`SKILL.md`、`references/**`、`scripts/**`）
+Bridge 安装内容：
+- `Packages/com.alpsckr.unitycli/` — canonical Bridge 包（copy 模式）
+- `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安装。
 
 ### 项目能力发现
 

package/docs/target-and-instance.md

@@ -13,12 +13,12 @@ CLI 只接受本机可证明的 Unity 项目目录。目录大小写、尾分隔
 ```powershell
 unitycli instances list
 unitycli instances list --all
-unitycli instances prune
+unitycli instances prune --instance <id|projectPath|alias>
 ```
 
 `instances list` 默认排除 `status="offline"` 的记录；存在隐藏项时返回 `hiddenOfflineCount`。只有需要审计历史/offline identity 时使用 `--all`，此时返回完整合法集合并省略 `hiddenOfflineCount`。每项公开字段固定为 `instanceId`、可选 `alias`、`canonicalProjectPath`、`displayProjectPath`、`projectName`、`status` 和可选 `unityVersion`；`--all` 不会恢复内部 session、快照、进程 claim 或诊断字段。
 
-实例目录按文件独立验证。旧格式、损坏、不可读或identity不匹配的记录不参与列表和路由，也不阻断其他合法Registry v3实例；存在时`instances list`和`instances prune`增加`invalidRecordCount`。CLI不会兼容解析、转换、移动或删除这些记录，`doctor`以warn报告合法和无效数量。显式选择无效记录对应的instanceId仍严格失败；应更新或重启该项目使用的匹配Unity Package，而不是绕过校验。
+实例目录按文件独立验证。旧格式、损坏、不可读或identity不匹配的记录不参与列表和路由，也不阻断其他合法Registry v3实例；`instances list`存在这类文件时返回`invalidRecordCount`。当前项目的Unity在启动或重载完成后会使用当前进程和连接重建自己的记录；CLI在能够证明目标Unity正在运行时等待该结果。不要兼容解析、转换、移动或手工删除内部记录。
 
 实例状态：
 
@@ -32,7 +32,7 @@ unitycli instances prune
 | `offline` | 该项目没有已证明存活的Editor session |
 | `conflict` | 至少两个已验证live process claim同属该project identity |
 
-`instances prune` 不直接删除进程、无效记录或伪造状态；PID/start-time 无效 claim 和过期 offline record 只由 Unity Bridge registry writer 清理。`invalidRecordCount`只报告本次被隔离的文件数量。
+`instances prune --instance <id|projectPath|alias>`只授权选定的当前Unity执行有界历史清理，CLI本身不删除记录。Unity保留当前、存活、无法确认、链接或被占用的记录；关闭记录最多保留最近100个，损坏记录最多保留最近20个，30天前的记录优先清理。每次最多检查2000个、删除20个。结果中的`removed`、`remaining`、`deferred`、`scanned`和`truncated`描述本次真实结果；`deferred>0`时可在当前清理完成后再次调用。
 
 不要读取 registry 文件、listener ID、端口或 URL，也不要直接调用 Bridge HTTP。transport binding 是 session supervisor 的内部职责。
 
@@ -44,6 +44,8 @@ Tool discovery、describe、`tools run`与`command`使用同一严格选择规
 2. 未传 selector 时，从 CWD 向上寻找最近的 Unity project root，并解析其 canonical identity。
 3. 无法得到唯一项目身份时返回结构化 instance error。
 
+目标项目已有唯一Unity进程但尚未发布记录、正在编译/导入/重载或正在更换连接时，CLI会在原命令截止时间内等待；Unity没有运行时不会进行无意义的完整等待。完整instance ID无法反推出项目路径，因此显式ID会直接等待其固定记录直到截止时间。
+
 不存在按PID、短hash、单个存活Editor或任意健康实例自动选取的路径。只有至少两个已验证live process claim才返回`E_INSTANCE_CONFLICT`；权限失败、超时或PID/start/project identity无法证明时返回`E_INSTANCE_UNVERIFIABLE`。选定项目已证明无运行进程时返回`E_INSTANCE_NOT_RUNNING`。
 
 ```powershell
@@ -70,7 +72,7 @@ alias 绑定完整 `instanceId`、canonical project path 和 canonicalization ve
 
 - 每个Editor或Development Player session独立维护默认5/3高低水位，不跨进程共享计数；
 - 对一次transport尝试绑定listener generation；
-- 在compile、import、domain reload或listener restart后重新验证generation，但不刷新execution deadline；
+- 首次记录尚未出现或在compile、import、domain reload、listener restart期间，等待当前ready generation，但不刷新execution deadline；
 - 同一次mutation调用只在`editorSessionId`未改变时，使用完全相同的root request ID与request bytes续接durable canonical terminal；
 - 首次mutation POST后若`editorSessionId`改变，禁止向新session再次POST，返回`E_EXECUTION_TIMEOUT`与outcome unknown；
 - 准入deadline到达返回effect-before `E_UNITY_BUSY`并证明业务请求未发送；

package/docs/tool-discovery.md

@@ -17,7 +17,7 @@ unitycli tools group --instance <id|projectPath|alias>
 
 ```text
 tools group
-    -> tools group list <group>
+    -> tools group list <group> [--page-size <n>] [--cursor <n>]
     -> tools describe <tool>
     -> tools run <tool> --input '<json>'
 ```
@@ -35,24 +35,26 @@ unitycli tools group --instance my-project
 
 ### `tools group list`
 
-列出一个真实分组中的全部 Tool 摘要：
+按名称稳定排序并返回一个真实分组中的 Tool 摘要页。默认 `pageSize=20`，最大 100：
 
 ```powershell
-unitycli tools group list camera
-unitycli tools group list probuilder --instance my-project
+unitycli tools group list camera --page-size 20
+unitycli tools group list probuilder --page-size 20 --cursor 20 --instance my-project
 ```
 
-分组名称必须来自当前实例的`tools group`输出，不要假设项目能力都位于`custom`分组。`tools group list`返回`nameSemantics.exact=true`与`groupPrefix=false`：每个`tools[].name`已经是完整精确调用名，group只用于筛选，绝不能拼到name前。
+分组名称必须来自当前实例的`tools group`输出，不要假设项目能力都位于`custom`分组。每个`tools[].name`已经是完整精确调用名，group只用于筛选，绝不能拼到name前；`available`仅在不可用时以`false`出现。存在`pageInfo.nextCursor`时，将其原值传回`--cursor`继续读取。
 
 ### `tools search`
 
-按名称、summary、description 和 group 搜索当前实例完整目录：
+按名称、summary、description 和 group 搜索当前实例完整目录，并只返回名称、summary、group组成的有界页。默认 `pageSize=20`，最大 100：
 
 ```powershell
-unitycli tools search 'screenshot|camera'
-unitycli tools search 'project-summary|scene' --instance my-project
+unitycli tools search 'screenshot|camera' --page-size 20
+unitycli tools search 'project-summary|scene' --page-size 20 --cursor 20 --instance my-project
 ```
 
+结果按精确 Tool name 排序；存在`pageInfo.nextCursor`时，将其原值传回同一关键词查询的`--cursor`。
+
 ### `tools describe`
 
 执行前读取单个 Tool 的完整 descriptor：
@@ -74,7 +76,7 @@ unitycli tools describe camera.screenshot
 | `requiresPackages` | 非空 Unity Package 依赖 |
 | `examples` | `description`、结构化业务 `input` 与按需 `execution` |
 
-`group`、`summary` 和 `source` 已在发现层使用，不在单 Tool describe 重复；`outputSchema`、`permissions`、fingerprint、completion 和 handler 只保留在内部 metadata。
+`group`和`summary`已在发现层使用，不在单 Tool describe重复；`source`、`outputSchema`、`permissions`、fingerprint、completion 和 handler 只保留在内部 metadata。
 
 ## 完整目录语义
 
@@ -86,7 +88,7 @@ unitycli tools describe camera.screenshot
 
 1. 用 `instances list` 确认 canonical project identity，或切换到目标 Unity 项目 CWD。
 2. 用 `tools group` 读取当前实例目录。
-3. 用 `tools group list`、`tools search '<k1|k2|...>'` 缩小范围。
+3. 用 `tools group list`、`tools search '<k1|k2|...>'` 缩小范围，并消费完所需的`pageInfo.nextCursor`页面。
 4. 用 `tools describe` 获取 schema、状态约束、副作用和示例。
 5. 用 `tools run` 调用同一名称。
 6. 安装 Package、安装 Extension、domain reload 或切换 PlayMode 后重新 discovery。

package/docs/tool-execution.md

@@ -58,7 +58,7 @@ unitycli tools run camera.screenshot --input '{}'
 
 ## Bridge 执行约束
 
-Bridge-backed Tool由Unity Editor主线程执行。准入放行后，session supervisor只创建一次execution absolute deadline，并在该deadline内处理compile、import、domain reload和listener generation交接；token重取、status、rebind和terminal recovery不得刷新预算。读取可在新generation重新执行完整读取；mutation只有在`editorSessionId`未改变时才可用完全相同的request bytes续接durable terminal。
+Bridge-backed Tool由Unity Editor主线程执行。业务请求发送前，session supervisor会在准入deadline内等待首次ready记录、compile、import、domain reload和listener generation交接；只有能证明目标Unity正在运行时才等待，证明未运行时立即返回。准入放行后只创建一次execution absolute deadline，token重取、status、rebind和terminal recovery不得刷新预算。读取可在新generation重新执行完整读取；mutation只有在`editorSessionId`未改变时才可用完全相同的request bytes续接durable terminal。
 
 首次mutation POST后若Editor session改变，CLI禁止向新session再次POST，并返回`E_EXECUTION_TIMEOUT`、`outcome:unknown`。其他超时或终态前断连同样表示没有可信终态；调用方应先用业务读取或`editor.state`收集证据，再决定是否提交全新请求。`editor.state`使用frozen本地descriptor绕过被阻断的Live catalog，再读取Registry/Health v3、内存主线程pulse、Bridge和Windows modal证据；两个dialog recovery Tool保持同一例外，其他Tool不建立静态fallback。
 
@@ -96,7 +96,8 @@ unitycli tools run asset.delete --input '{"path":"Assets/Temp.mat"}'
 
 通用规则：
 
-- 列表/层级工具优先传 `pageSize`、`cursor`、`parent`、`query`、`componentType` 或 `className`。继续读取时将输出里的 `pageInfo.nextCursor` 原值传回 `cursor`；两者保持相同 JSON 类型。`hasMore`、`truncated` 或 `childrenTruncated` 表示还有更深或更多内容。
+- discovery 的 `tools group list`、`tools search` 和省略name的`command`列表默认每页20项、最大100项；继续读取时将`pageInfo.nextCursor`原值传回CLI `--cursor`。
+- 业务列表/层级工具优先传 JSON `pageSize`、`cursor`、`parent`、`query`、`componentType` 或 `className`。继续读取时将输出里的 `pageInfo.nextCursor` 原值传回 `cursor`；两者保持相同 JSON 类型。`hasMore`、`truncated` 或 `childrenTruncated` 表示还有更深或更多内容。
 - 深度序列化工具（`object.get-data`、`asset.get-data`、`component.get`）优先传 `paths` 或 `viewQuery`，并保持 `maxDepth` 较低。数组、列表和字典受 `maxArrayItems` 限制；输出里的 `totalCount`、`returnedCount`、`truncated`、`nextPath` 用于判断是否需要继续按路径读取。CLR 的 `NaN`、正无穷和负无穷无法作为 JSON number，会在 AnyJson 值节点中分别表示为字符串 `"NaN"`、`"Infinity"`、`"-Infinity"`。
 - 文本源码工具（如 `shader.read`）使用 `offset` 和 `maxBytes` 分段读取。输出 `truncated=true` 时，下一次把 `nextOffset` 作为新的 `offset`。
 - 截图和相机工具默认返回 artifact 路径。只有确实需要内联图片时才传 `inlineBase64:true`；图片超过 Bridge 内联上限时会省略 `imageBase64` 并返回 warning，继续使用 artifact 路径。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpsckr/unitycli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Windows-first CLI for UnityCLI automation.",
   "type": "module",
   "bin": {
@@ -20,8 +20,9 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "generate:extensions": "node scripts/gen-extension-projections.mjs",
     "generate:registries": "node scripts/gen-ts-registries.mjs && node scripts/gen-tool-completion-registry.mjs",
-    "build": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.json",
-    "build:test": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/copy-test-resources.cjs && tsc -p tsconfig.json",
+    "generate:package-files": "node scripts/gen-package-files.mjs",
+    "build": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && npm run generate:package-files && npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && tsc -p tsconfig.json",
+    "build:test": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && npm run generate:package-files && npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && tsc -p tsconfig.test.json && node scripts/copy-test-resources.cjs && tsc -p tsconfig.json",
     "test": "node --test \"dist/tests/**/*.test.js\"",
     "pretest": "npm run build:test",
     "prepack": "npm run build",
@@ -29,7 +30,12 @@
     "architecture:audit": "node scripts/audit-final-architecture.mjs",
     "static-catalog:audit": "node scripts/audit-static-capability-catalog.mjs",
     "static-catalog:capture": "node scripts/capture-static-capability-catalog.mjs",
-    "architecture:validate": "node scripts/audit-final-architecture.mjs --strict && node scripts/audit-tool-completion-contract.mjs --strict && node scripts/audit-static-capability-catalog.mjs",
+    "architecture:validate": "npm run package-closure:validate && npm run init-contract:validate && npm run instances-contract:validate && node scripts/audit-final-architecture.mjs --strict && node scripts/audit-tool-completion-contract.mjs --strict && node scripts/audit-static-capability-catalog.mjs",
+    "init-contract:validate": "node scripts/audit-init-contract.mjs",
+    "instances-contract:validate": "node scripts/audit-instances-contract.mjs",
+    "instances-live:validate": "node scripts/validation/validate-instance-concurrent-readers.mjs && node scripts/validation/validate-instance-dual-writer.mjs && node scripts/validation/validate-instance-multi-cli.mjs && node scripts/validation/validate-instance-multi-prune.mjs",
+    "package-files:validate": "node scripts/audit-package-files.mjs",
+    "package-closure:validate": "node scripts/audit-package-assembly-closure.mjs && npm run package-files:validate",
     "completion:audit": "node scripts/audit-tool-completion-contract.mjs --strict",
     "matrix:live": "node scripts/run-final-live-matrix.mjs",
     "test:matrix-runner": "node --test scripts/run-final-live-matrix.test.mjs",

package/schemas/init.schema.json

@@ -0,0 +1,124 @@
+{
+  "$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": { "type": "integer", "minimum": 1 },
+        "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"] },
+        "limits": { "type": "object" },
+        "scan": { "type": "object" },
+        "unityProjects": { "type": "array" },
+        "skillWorkspaces": { "type": "array" },
+        "skillCopies": { "type": "array" },
+        "shadowingRisks": { "type": "array" },
+        "requiredDecisions": { "type": "array", "minItems": 4 },
+        "nextActions": { "$ref": "#/$defs/nextActions" }
+      },
+      "required": ["action", "cwd", "repositoryRoot", "limits", "scan", "unityProjects", "skillWorkspaces", "skillCopies", "shadowingRisks", "requiredDecisions", "nextActions"],
+      "additionalProperties": false
+    },
+    "packageData": {
+      "type": "object",
+      "properties": {
+        "action": { "enum": ["init_package", "init_package_check"] },
+        "projectPath": { "type": "string" },
+        "projectIdentity": { "type": "object" },
+        "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" },
+        "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", "agent", "scope", "skill", "nextActions"],
+      "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`，再向用户询问要安装Bridge的Unity项目，以及Skill的agent、scope和常用workspace；不得静默选择。多个Bridge项目逐个严格串行安装，每次等待terminal并执行对应`--check`后才能继续；Skill通常只安装到用户选择的一个`.agents`或Claude workspace/user目标。第一次非预期CLI失败或业务check失败立即停止，不重试、纠参或继续后续effect。安装流程不得启动、关闭、重启或终止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已经停止。