@alpsckr/unitycli 0.4.0 → 0.4.2

package/README.md

@@ -1,389 +1,201 @@
 # UnityCLI
 
-CLI-first Unity 自动化工具，不是 MCP server。通过 `unitycli` 二进制命令行直接驱动 Unity Editor，无需额外协议层。
+Windows-first Unity Editor automation CLI for AI agents. The executable is `unitycli`; the npm package is `@alpsckr/unitycli`; the Unity Package is `com.alpsckr.unitycli`.
 
-npm 包名：`@alpsckr/unitycli`
-运行环境：Windows + Node.js 20+  
-当前方向：冻结决策 - 独立 CLI 实现、Windows-only、npm-first 安装；公开 Tool 与 CLI 控制面调用即授权。
+## Requirements
 
-## Project Baseline
+- Windows
+- Node.js 20 or newer
+- Unity 2022.3 or newer
+- A Unity project when installing the Bridge
+- An opened Unity Editor only when using live Unity capabilities; installation may normally close only the exact target Editor after explicit user approval
 
-本节是项目基线，优先级高于本文档其他章节、历史实现、旧示例和当前代码状态。AI 和后续实现不得自行修改本节含义；如需调整，必须由项目所有者明确确认。
+## Install
 
-### 1. Clean Project Semantics
-
-本项目是开发中项目，不承担旧版本兼容义务。
-
-项目代码、文档、命令形态和注释必须表达当前项目规范。发现旧语义、阶段性语义或兼容性语义时，应统一改为当前规范；无法干净迁移时，优先删除，而不是保留多套说法。
-
-### 2. Top-Level CLI Shape
-
-用户可见顶层命令分为两类：能力入口和 CLI 控制面。
-
-能力入口只允许：
-
-- `tools`
-- `command`
-
-CLI控制面只允许：
-
-- `init`
-- `extensions`
-- `target`
-- `instances`
-- `doctor`
-
-Unity项目内容与Editor能力域必须进入唯一Tool catalog，例如scene、asset、game-object、prefab、editor、screenshot、package、docs、reflect、build、test、code、profiler、physics、graphics等。`tools run <tool> --input <json>`与`command <name> <business-args>`只是同一descriptor和dispatcher的两种调用语法。
-
-`target`、`instances`、`doctor` 是 CLI 自身的状态、路由和诊断控制面；它们可以作为顶层命令存在，但不得重新引入 Unity 能力域的顶层入口。
-
-内部 Bridge、协调器和 registry 可以作为实现细节存在，但不得定义超出上述清单的用户可见顶层命令形态。
-
-本产品只吸收必须由已打开 Unity Editor 或 development Player 提供的项目内自动化价值。auth、Unity Hub、Editor 安装或打开、Cloud、License 和 proxy 配置属于外部控制面，必须直接使用系统或官方控制面工具，不进入 Tool catalog，也不新增顶层命令。
-
-### 3. AI-First Tool Interface
-
-本 CLI 主要提供给 AI 使用。项目哲学不是维护一套面向人工记忆的传统命令手册，而是提供可发现、可描述、可审计的工具目录。
-
-AI 的标准流程是：
-
-```text
-unitycli tools group/search
-unitycli tools describe <tool>
-unitycli tools run <tool> --input <json>
-unitycli command
-unitycli command <name> --field <value>
-
-unitycli target alias list/set/unset
-unitycli instances list/prune
-unitycli doctor
-
-unitycli extensions list/install/remove/doctor
-unitycli init
-```
-
-具体有哪些工具、工具参数是什么、风险边界是什么，应由AI通过本CLI内置的`tools group/search/describe`自发现。省略name的`command`只返回同一live catalog的command投影，不是第二份能力目录。
-
-## 快速开始
+Install the CLI once for the current user:
 
 ```powershell
-# 安装
 npm install -g @alpsckr/unitycli
+```
 
-# 初始化项目（安装 Bridge 包；若项目已有 .pi/.claude/.agents，则自动安装 Skill）
-unitycli init --project C:\path\MyProject
+Start your AI in the directory where you normally work and tell it:
 
-# Bridge AutoStart默认开启；项目级开关位于Unity的Project Settings > UnityCLI
-# 修改后从下一次Domain Reload或Editor启动生效
+> 执行 unitycli init help，然后照做。
 
-# 查看帮助
-unitycli --help
-unitycli --version
-```
+`init help` contains the complete AI installation protocol. Read-only discovery uses the unique current Unity project and workspace without asking you to repeat them, reports the installed and available Bridge versions, and accepts any exact Skill directory you already named. It asks only when a real choice remains, including permission to normally close the exact target Unity Editor before replacing an in-use Bridge. It never force-terminates Unity or decides an unsaved-scene prompt.
 
-## 核心使用流程
+## Manual Setup
 
-### 1. 发现目标实例
+Read the same protocol and inspect the current directory:
 
 ```powershell
-# 默认只列非 offline 实例；hiddenOfflineCount 表示被隐藏数量
-# invalidRecordCount 出现时表示旧/坏记录已隔离，合法v3实例仍会返回
-unitycli instances list
-# 需要审计历史/offline 合法记录时显式展开
-unitycli instances list --all
-
-# 已知实例时，在后续每条 Bridge 命令上显式传入
-unitycli tools group --instance <instanceId>
-# 可先创建稳定别名，再继续显式传入
-unitycli target alias set <instanceId> my-project
-unitycli tools group --instance my-project
+unitycli init help
+unitycli init discover
 ```
 
-### 2. 发现工具能力（group-first 路径）
-
-推荐按组逐层发现，避免一次展开全量工具：
+Install or repair the Bridge in one explicit Unity project. Use `--close-editor` only after the user approves normally closing that exact project:
 
 ```powershell
-# 第一步：查看工具分组
-unitycli tools group
-
-# 第二步：按组查看工具摘要
-unitycli tools group list camera
-# 或搜索关键词（使用 | 分隔多关键词，OR 匹配；PowerShell必须单引号包住整段）
-unitycli tools search 'screenshot|camera'
-
-# 第三步：查看工具完整描述（执行前必做）
-unitycli tools describe camera.screenshot
-
-# 第四步：执行工具
-unitycli tools run camera.screenshot --input '{"target":"Main Camera","output":"Artifacts/shot.png"}'
+unitycli init package --project C:\path\UnityProject
+unitycli init package --project C:\path\UnityProject --close-editor
+unitycli init package --project C:\path\UnityProject --check
 ```
 
-### 3. 获取只读项目信息
-
-当前版本通过 `docs.get/search` 查询 Unity API 文档，通过 `reflect.*` 查询类型缓存；这些 Tool 仍从已连接实例的统一 catalog 发现和调用：
+Install or check an exact user-selected Skill directory, including Pi:
 
 ```powershell
-# Unity API 文档
-unitycli tools run docs.get UnityEngine.Camera
-unitycli tools run docs.search "Render Pipeline"
-
-# 类型反射
-unitycli tools run reflect.type UnityEngine.Camera
-unitycli tools run reflect.member UnityEngine.Camera.fieldOfView
+unitycli init skill --target C:\path\Workspace\.pi\skills\unitycli
+unitycli init skill --target C:\path\Workspace\.pi\skills\unitycli --check
 ```
 
-> **注意**：项目与 Editor 状态同样通过 `tools group/search/describe/run` 发现和读取；读取型 Tool 明确声明无副作用。
-
-### 4. 项目注册能力
-
-Unity 项目可通过异步 C# `IUnityCliTool<TReq,TRes>` 注册能力；完成编译后自动进入该实例的完整目录，与 package 内置和 Extension 能力使用同一路径：
+Generic Agent Skills remain available as a preset:
 
 ```powershell
-# 从当前实例目录发现真实 group
-unitycli tools group --instance <id|projectPath|alias>
-
-# 描述并执行项目 Tool
-unitycli tools describe my.custom-tool --instance <id|projectPath|alias>
-unitycli tools run my.custom-tool --input '{"key":"value"}' --instance <id|projectPath|alias>
+unitycli init skill --agent .agents --scope workspace --workspace C:\path\Workspace
+unitycli init skill --agent .agents --scope workspace --workspace C:\path\Workspace --check
 ```
 
-> **注意**：不要假设项目能力位于 `custom` 分组。可通过 `extensions list` 查看已安装扩展，`extensions install <id>` / `extensions remove <id>` 管理扩展，`extensions doctor` 诊断扩展状态。
-
-### 5. 使用command语法
-
-`command`按目标Tool的live `inputSchema`解析named、attached、boolean裸开关和声明顺序positional参数，然后进入与`tools run`相同的dispatcher和JSON envelope：
+Install or check Claude Skills in one workspace:
 
 ```powershell
-# 列出当前实例可调用名称
-unitycli command --project-path C:\path\MyProject
-
-# native Tool使用完整Tool名
-unitycli command editor.compile --refresh true --includeWarnings true
-
-# [CliCommand("test")]在tools中名为UnityPipeline_test，command可用attribute原名
-unitycli command test --mode EditMode
-unitycli command UnityPipeline_test --mode EditMode
+unitycli init skill --agent claude --scope workspace --workspace C:\path\Workspace
+unitycli init skill --agent claude --scope workspace --workspace C:\path\Workspace --check
 ```
 
-命令名和业务字段exact匹配，不做snake_case、camelCase、相似名称或语义映射。native完整精确名优先；重名attribute仍通过`UnityPipeline_`完整名调用。
-
-`com.unity.pipeline` package自身的attribute命令已由native能力矩阵吸收，不进入live目录；项目和其他Package声明的`[CliCommand]`继续正常导入。本package首次检测到Pipeline时只执行一次`AutoStart=false`持久化和当前server停服，成功后不再覆盖用户后续手动操作。
-
-### 6. 诊断与健康检查
+Install or check one user-level Skill:
 
 ```powershell
-# 运行完整诊断
-unitycli doctor
+unitycli init skill --agent .agents --scope user
+unitycli init skill --agent .agents --scope user --check
 
-# 诊断预检（通过 Bridge）
-unitycli tools run diagnose.preflight
+unitycli init skill --agent claude --scope user
+unitycli init skill --agent claude --scope user --check
 ```
 
-## 安全边界
+Preset workspace and user scope are separate choices. An exact `--target` is final user intent and cannot be combined with preset agent/scope options. Bridge and Skill are independently authorized effects; failure of one does not invalidate or block the other.
 
-| 规则 | 说明 |
-|------|------|
-| Tool 可有副作用 | 调用即授权；`destructiveHint`、`sideEffects` 与 `supportsDryRun` 仅描述风险和可选预览 |
-| 读取型 Tool 纯只读 | 读取型 Tool 不触发写入、import、compile、domain reload 或 PlayMode 变化 |
-| Extension 不能绕过 descriptor/envelope | 项目工具必须可描述、可审计、可阻断 |
-| 内部完整性不匹配默认阻止 | 自定义工具的 handler 代码与 descriptor 不一致时，默认阻止执行 |
+## Verify And Diagnose
 
-## 安装与构建
+Package and Skill checks are read-only:
 
 ```powershell
-# 全局安装
-npm install -g @alpsckr/unitycli
-
-# 本地开发
-npm install
-npm run build
-npm test
-npm link
-```
-
-## 输出格式
-
-所有命令输出统一 JSON envelope：
-
-```json
-{
-  "ok": true,
-  "requestId": "req-xxx",
-  "data": { ... }
-}
+unitycli init package --project C:\path\UnityProject --check
+unitycli init skill --target C:\path\Workspace\.pi\skills\unitycli --check
+unitycli init skill --agent .agents --scope workspace --workspace C:\path\Workspace --check
 ```
 
-错误输出：
+After the user opens or refreshes Unity, inspect registered Editor sessions:
 
-```json
-{
-  "ok": false,
-  "requestId": "req-xxx",
-  "error": {
-    "code": "E_INSTANCE_CONFLICT",
-    "message": "...",
-    "transient": false,
-    "nextActions": ["Close duplicate Editor sessions for the selected project."],
-    "retryAfterMs": 0
-  }
-}
+```powershell
+unitycli instances list
+unitycli instances prune --instance C:\path\UnityProject
+unitycli doctor --project C:\path\UnityProject
 ```
 
-## Live Editor 执行
+`instances list`默认隐藏offline记录；`instances list --all`仅用于展开审计。Unity启动、编译或重载时，live命令会在本次timeout内等待当前连接ready。旧格式、损坏或不可读记录会逐文件隔离，不阻断合法实例，并通过`invalidRecordCount`返回数量；当前项目由Unity自动恢复。需要清理历史记录时运行`instances prune --instance <id|projectPath|alias>`并检查`removed`、`remaining`和`deferred`，不要手工读取或删除内部文件。
 
-需要 Unity 执行的 Tool 只连接已打开的 Unity Editor，并在同一次 direct 调用中返回最终业务结果。`build.run`、`test.run`、`editor.refresh`、`code.exec` 以及需要 Editor 刷新的 Package Tool 都会等待终态；它们不创建可查询的后台任务。每个live Editor/Development Player session使用默认5/3任务池，CLI在业务请求前自动等待放行。`--timeout-ms T`分别提供最多`T`的准入等待与放行后最多`T`的执行预算；调用CLI的外层进程必须等待CLI退出，host预算至少为`2 * T + 5000`毫秒。准入`E_UNITY_BUSY`证明业务请求未发送；放行后的`E_EXECUTION_TIMEOUT`仍是outcome unknown。CLI在stdout写完或最多再等待1秒后退出。
+To create a stable selector:
 
-`code.exec`保留完整同步C#执行能力：它不会拒绝死循环、阻塞等待或长期占用Unity主线程的代码。提交这类代码前应先判断是否确有必要；一旦开始执行，timeout只能停止CLI等待，不能中止代码，结果可能未知且Unity可能需要结束进程才能恢复。CLI进程退出也不证明Unity中的C#已停止。完整边界见`tools describe code.exec`和`docs/safety-boundaries.md`。
+```powershell
+unitycli target alias set C:\path\UnityProject my-project
+unitycli target alias list
+```
 
-## 能力发现与执行
+## First Unity Call
 
-公开能力不维护静态命令清单。Tool 的当前输入 schema、可用性、示例与调用边界以 CLI discovery 为准；结果 schema 留在内部 contract 中校验实际业务 data：
+With the selected Unity project open and ready:
 
 ```powershell
-unitycli tools group
-unitycli tools group list <group>
-unitycli tools search <k1|k2|...>
-unitycli tools describe <tool-name>
-unitycli tools run <tool-name> --input '<json>' [--instance <id|projectPath|alias>]
+unitycli tools group --instance C:\path\UnityProject
+unitycli tools search 'editor|state' --instance C:\path\UnityProject
+unitycli tools describe editor.state --instance C:\path\UnityProject
+unitycli tools run editor.state --input '{}' --instance C:\path\UnityProject
 ```
 
-Tool discovery 必须绑定已连接实例；未连接时返回稳定 instance error，不返回静态或空目录。连接后完整显示 package 内置、Extension、项目注册、Editor 与 Runtime 能力，不按 `source` 或当前模式过滤。`source` 只作内部描述/审计。`examples[].input` 是结构化业务 JSON，按需 `examples[].execution` 承载 dryRun/timeoutMs；调用方明确要求的业务值优先于schema default和example值。业务参数全部放入 `--input`、`--input-file` 或 `--stdin`，命令控制项不混入业务 JSON。
-
-Bridge-backed Tool在Unity主线程执行。CLI使用Registry/Health v3与只读内存pulse，在一个不可变deadline内处理compile、import、domain reload和listener generation交接。mutation只允许在同一`editorSessionId`内用完全相同的请求续接；首次POST后session改变时禁止向新session重投，并返回outcome unknown的`E_EXECUTION_TIMEOUT`。`unitycli tools run editor.state --input '{}'`、`editor.dialogs`与`editor.dialog.click`使用exact frozen本地descriptor进入同一dispatcher，因此统一状态观察和弹窗恢复不依赖被阻断的Live catalog；其他Tool仍严格依赖Live catalog。
+Do not guess Tool names or inputs. Discover the current catalog, read one descriptor, then call that exact Tool. `command <name>` is a schema-argument projection of the same live catalog, not a second capability system.
 
-### 实例与目标
+Optional extensions use their dedicated control plane:
 
 ```powershell
-# 默认隐藏 offline，使用 --all 展开完整集合
-unitycli instances list
-unitycli instances list --all
-unitycli instances prune
+unitycli extensions list --project C:\path\UnityProject
+unitycli extensions install <id> --project C:\path\UnityProject
+unitycli extensions remove <id> --project C:\path\UnityProject
+unitycli extensions doctor --project C:\path\UnityProject
 ```
 
-实例文件逐个按Registry v3校验。旧格式、损坏或不可读记录不会阻断其他合法实例，也不会被兼容解析或自动删除；存在时list/prune返回`invalidRecordCount`，`doctor`报告warn。显式选择对应坏记录仍严格失败。
+Discovery lists default to 20 items, allow at most 100, and continue with `pageInfo.nextCursor`:
 
 ```powershell
-# target 只管理 canonical project identity 的别名
-unitycli target alias set <projectPath|instanceId> <alias>
-unitycli target alias unset <alias>
-unitycli target alias list
+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 command --project-path C:\path\UnityProject --page-size 20
 ```
 
-实例与目标属于 CLI 控制面，只使用顶层 `instances` / `target`；不要通过 `tools run` 包装这些控制面状态。
+In PowerShell, quote pipe-separated search keywords with single quotes.
 
-`doctor`、`instances`、`target alias` 和 `extensions` 属于 CLI 控制面。扩展源码以 `extensions/<id>/` 组织，安装后投影到 `Packages/com.alpsckr.unitycli/Extensions/<id>/`；Extension 贡献的 Tool 仍通过统一 discovery 入口发现。
+## Output
 
-## 初始化（init）
+Every command returns one JSON envelope. stdout is compact single-line JSON by default; use `--pretty` only for indented output.
 
-`init` 安装捆绑的 `com.alpsckr.unitycli` Bridge 包到目标 Unity 项目；如果项目根目录已经存在 `.pi`、`.claude` 或 `.agents`，会自动安装对应 AI Agent Skill。也可以用 `--agent` 显式指定目标。Skill 以 `SKILL.md`、`references/**`、`scripts/**` 完整 runtime bundle 安装，`--check` 校验全部 managed 文件；更新会保留已安装 `SKILL.md` 中合法的 `FeedbackMode: off|on`。
+Success:
 
-| 标志 | 含义 |
-|------|------|
-| *(none)* | 安装/更新 Bridge 包（copy 模式），并为已存在的 Agent 目录安装 Skill |
-| `--pkg-only` | 仅安装 Bridge 包，不安装 Skill |
-| `--skill-only [--agent <agent>]` | 仅安装 Skill；未传 `--agent` 时使用已存在的 Agent 目录 |
-| `--check` | 检查安装状态，不修改项目 |
-| `--agent <pi\|claude\|.agents,...>` | 显式指定 Skill 安装目标 |
-
-```powershell
-# 默认安装 Bridge；若项目已有 .pi/.claude/.agents，则自动安装 Skill
-unitycli init --project C:\path\MyProject
-
-# 仅 Bridge 包
-unitycli init --project C:\path\MyProject --pkg-only
-
-# 显式安装 Skill 到 pi
-unitycli init --project C:\path\MyProject --skill-only --agent pi
-
-# 检查安装状态；未传 --agent 时同样会检查已存在的 Agent 目录
-unitycli init --check --project C:\path\MyProject
+```json
+{"ok":true,"requestId":"req-...","data":{}}
 ```
 
-`FeedbackMode` 默认 `off`。改为 `on` 后，使用该 Skill 的 Agent 只在实际遇到失败、歧义、缺失、误导或成功绕过的坑点时，调用 bundle 内 recorder 写入 `%LOCALAPPDATA%\UnityCli\feedback\` 的有界 JSONL；正常调用不记录，也不联网。
-
-## Unity Editor Bridge
+Failure:
 
-`init` 以 copy 模式把 `com.alpsckr.unitycli` 安装到 `Packages/com.alpsckr.unitycli/`。已打开的 Unity Editor 自动注册 canonical project identity 和 Live listener；CLI 通过 `instances list` 与 `--instance` 选择唯一会话，公开接口不接受 endpoint 或 port。
-
-Bridge command、handler、journal、fingerprint、listener generation和completion contract都是内部实现，不构成第二套用户入口。mutation在首个真实effect前持久化effect barrier；effect后只有fresh business readback或artifact proof能完成。同一次调用只在`editorSessionId`不变时续接完全相同的请求；首次POST后session改变则禁止重投。无法证明终态时返回`E_EXECUTION_TIMEOUT`，调用方先观察业务状态，再作全新提交决策。
+```json
+{"ok":false,"requestId":"req-...","error":{"code":"...","message":"...","nextActions":[],"transient":false,"retryAfterMs":0}}
+```
 
-当前能力、Extension 依赖和 Editor/PlayMode 可用性只通过 `tools` discovery 获取，不在 README 冻结能力名清单。
+Follow structured `nextActions`. With `--timeout-ms T`, use a host budget of at least `2 * T + 5000` milliseconds and wait for the unitycli process to exit. `E_EXECUTION_TIMEOUT` means no trusted terminal result; timeout does not stop Unity effects or synchronous C# already running. Inspect business state before deciding whether to submit a new mutation.
 
-## 项目自定义工具（Custom Tools）
+## Update And Remove
 
-Unity 项目 C# 代码可通过异步 `IUnityCliTool<TReq,TRes>` 注册自定义能力。schema 由 DTO 派生；Tool 必须声明完整 direct completion contract，并在全部可预见校验后、首个 mutation 前调用一次 `ctx.CommitEffect()`。当前接口与完整示例见 [Custom Tools](skills/unitycli/references/custom-tools.md)。
+Update the global CLI, then let the AI run the installation protocol again:
 
 ```powershell
-unitycli tools group --instance <id|projectPath|alias>
-unitycli tools group list <real-group> --instance <id|projectPath|alias>
-unitycli tools describe my.editor-tool --instance <id|projectPath|alias>
-unitycli tools run my.editor-tool --input '{"message":"hello"}' --instance <id|projectPath|alias>
+npm install -g @alpsckr/unitycli@latest
+unitycli init help
 ```
 
-### 统一 Tool 与 target
-
-所有能力都以 Tool 呈现。`target: "editor" | "runtime" | "both"` 只是可用性与路由约束，不是两套用户入口。
-
-`runtime` 表示 Unity gameplay/runtime layer；具体 tool 是否需要 Play Mode，由 `availabilityScope` 和 `nextActions` 说明。
+To remove a workspace or user Skill, delete only the selected `unitycli` Skill directory:
 
-### 安全机制
+```text
+<explicit-target>/unitycli
+<workspace>/.agents/skills/unitycli
+<workspace>/.claude/skills/unitycli
+~/.agents/skills/unitycli
+~/.claude/skills/unitycli
+```
 
-- **Descriptor**：公开 describe 提供完整 inputSchema 与调用/风险信息；内部 metadata 保留 outputSchema 并校验业务结果
-- **Envelope**：所有输入输出必须通过统一 envelope 格式
-- **内部完整性校验**：handler 与 descriptor 不一致时默认阻止执行
-- **target-scoped availability**：工具可用性依赖目标实例和 Play Mode 状态
-- **禁止项**：不允许任意方法调用、反射 escape hatch、绕过 registry 直接执行
+To remove the managed Bridge, first inspect the current `package.bridge-remove` descriptor and follow it:
 
-## ProBuilder 扩展
+```powershell
+unitycli tools describe package.bridge-remove --instance C:\path\UnityProject
+```
 
-ProBuilder 工具需要项目先安装精确版本 `com.unity.probuilder@5.2.4`，再安装 CLI 扩展目录；其他版本不执行基于 5.2.4 源码闭合的 mutation proof：
+Remove the global CLI with:
 
 ```powershell
-unitycli extensions install probuilder --project <project>
-unitycli tools group list probuilder --instance <id|projectPath|alias>
-unitycli tools describe probuilder.create-shape --instance <id|projectPath|alias>
-unitycli tools run probuilder.create-shape --input '{"shapeType":"Cube","name":"MyCube"}' --instance <id|projectPath|alias>
+npm uninstall -g @alpsckr/unitycli
 ```
 
-## 风险与副作用
-
-公开 Tool 与 CLI 控制面调用本身即授权。`destructiveHint`、`sideEffects` 和 `supportsDryRun` 让调用方了解效果与可选预览，但不会触发额外确认、预定义按钮列表或意图复核。支持 dry-run 的 Tool 可用 `--dry-run` 返回 `plannedEffects` 而不执行实际 mutation；不使用它不会阻止调用。
-
-## 扩展能力概览
-
-| 扩展类型 | 当前状态 | 发现方式 |
-|----------|---------|---------|
-| 项目自定义 Tool (`target=editor`) | ✅ 已实现 | 当前实例 `tools group/list/describe/run` |
-| 项目自定义 Tool (`target=runtime`) | ✅ 已实现 | 当前实例 `tools group/list/describe/run`；EditMode 仍显示，执行通常需 PlayMode |
-| 扩展包管理 | ✅ 已实现 | `extensions list/install/remove/doctor` |
-| ProBuilder 扩展 | ✅ 已实现 | `tools group/list/describe/run`（需要 `com.unity.probuilder@5.2.4` + `extensions install probuilder`） |
-| Cinemachine/VFX/URP/HDRP 扩展 | ✅ 已实现 | `tools group/list/describe/run`（需要对应 Unity package + `extensions install <id>`） |
-
-## 更多文档
-
-- [文档索引](docs/README.md) — 当前使用、扩展与诊断文档入口
-- [Target 与 Instance](docs/target-and-instance.md) — 目标选择与实例管理
-- [工具发现](docs/tool-discovery.md) — group-first 分层发现详解
-- [工具执行](docs/tool-execution.md) — tools run 执行通道详解
-- [安全边界](docs/safety-boundaries.md) — 调用授权、风险元数据与正确性边界
-- [风险与副作用](docs/risk-and-side-effects.md) — destructive/dry-run 描述与可选预览
-- [错误码](docs/error-codes.md) — 结构化错误与 nextActions
-- [可用性差异](docs/availability-differences.md) — 不同实例的工具有效性
-- [扩展包](docs/extensions.md) — 可选扩展安装、卸载与诊断
-- [自定义 Tool](skills/unitycli/references/custom-tools.md) — 项目侧 Tool 注册开发
-- [AI Agent Skill](skills/unitycli/SKILL.md) — Agent 最小入口卡片
-
-## 本地开发
-
-```bash
-npm install
-npm run build
-npm test
-npm link
-unitycli --help
-```
+## Documentation
+
+- [Documentation index](docs/README.md)
+- [Architecture and public boundaries](docs/architecture.md)
+- [Local development](docs/development.md)
+- [Tool discovery](docs/tool-discovery.md)
+- [Tool execution](docs/tool-execution.md)
+- [Command execution](docs/command-execution.md)
+- [Target and instance selection](docs/target-and-instance.md)
+- [Safety boundaries](docs/safety-boundaries.md)
+- [Errors](docs/error-codes.md)
+- [Extensions](docs/extensions.md)
+- [Public AI Skill](skills/unitycli/SKILL.md)
 
-## 许可证
+## License
 
 MIT

package/contracts/init-contract.json

@@ -0,0 +1,64 @@
+{
+  "version": 2,
+  "topLevel": "init",
+  "schema": "schemas/init.schema.json",
+  "subcommands": {
+    "help": {
+      "options": []
+    },
+    "discover": {
+      "options": []
+    },
+    "package": {
+      "options": [
+        "project",
+        "close-editor",
+        "check",
+        "timeout-ms"
+      ],
+      "required": [
+        "project"
+      ],
+      "checkStatuses": [
+        "installed",
+        "missing",
+        "damaged",
+        "drifted",
+        "conflict"
+      ]
+    },
+    "skill": {
+      "options": [
+        "agent",
+        "scope",
+        "workspace",
+        "target",
+        "check",
+        "timeout-ms"
+      ],
+      "requiredAnyOf": [
+        [
+          "target"
+        ],
+        [
+          "agent",
+          "scope"
+        ]
+      ],
+      "agents": [
+        ".agents",
+        "claude"
+      ],
+      "scopes": [
+        "workspace",
+        "user"
+      ],
+      "checkStatuses": [
+        "installed",
+        "missing",
+        "drifted",
+        "damaged"
+      ]
+    }
+  }
+}

package/contracts/instances-contract.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "topLevel": "instances",
+  "schema": "schemas/instances.schema.json",
+  "registry": {
+    "version": 3,
+    "canonicalizationVersion": 1,
+    "statuses": [
+      "ready",
+      "transitioning",
+      "blocked",
+      "unresponsive",
+      "unverifiable",
+      "offline",
+      "conflict"
+    ],
+    "readerPollMs": 100,
+    "writer": "unity-bridge"
+  },
+  "subcommands": {
+    "list": {
+      "options": ["all"],
+      "readOnly": true
+    },
+    "prune": {
+      "options": ["instance", "timeout-ms"],
+      "privateCommand": "internal.instances.prune",
+      "mutation": true,
+      "retention": {
+        "offlineMax": 100,
+        "damagedMax": 20,
+        "maxAgeDays": 30,
+        "scanLimit": 2000,
+        "deleteLimit": 20
+      }
+    }
+  },
+  "errors": [
+    "E_INSTANCE_NOT_FOUND",
+    "E_INSTANCE_NOT_RUNNING",
+    "E_INSTANCE_UNVERIFIABLE",
+    "E_UNITY_TRANSITION_TIMEOUT",
+    "E_UNITY_BUSY",
+    "E_EXECUTION_TIMEOUT",
+    "E_BRIDGE_RESPONSE_INVALID",
+    "E_SCHEMA_INVALID",
+    "BRIDGE_CONNECTION_FAILED"
+  ]
+}

package/contracts/package-assembly-closure.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "packageName": "com.alpsckr.unitycli",
+  "minimumUnityVersion": "2022.3",
+  "bundledAssemblies": [],
+  "editorProvidedAssemblies": [
+    {
+      "fileName": "Newtonsoft.Json.dll",
+      "assemblyName": "Newtonsoft.Json",
+      "minimumAssemblyVersion": "13.0.0.0",
+      "provider": "Unity Editor/Data/Managed",
+      "referencedBy": "UnityCli.Editor.asmdef"
+    }
+  ],
+  "compiler": {
+    "mode": "editor-bundled-csc-subprocess",
+    "monoRelativePath": "MonoBleedingEdge/bin/mono.exe",
+    "compilerRelativePath": "MonoBleedingEdge/lib/mono/4.5/csc.exe",
+    "packageOwnedRoslyn": false,
+    "temporaryRoot": "Library/UnityCli/code-exec-temp"
+  },
+  "conflictPolicy": {
+    "protectedAssemblyFileNames": [
+      "Newtonsoft.Json.dll"
+    ],
+    "allowedPackageProviders": [
+      "com.unity.nuget.newtonsoft-json"
+    ],
+    "maxDirectories": 4096,
+    "maxFiles": 50000,
+    "maxConflicts": 100
+  }
+}