@alpsckr/unitycli 0.4.0

package/docs/error-codes.md

@@ -0,0 +1,204 @@
+# 错误码（Error Codes）
+
+alps-unity-cli 使用结构化错误码，包含机器可读的 `code`、`transient` 标记、`retryAfterMs` 和 `nextActions` 自动恢复指引。
+
+## 错误格式
+
+```json
+{
+  "ok": false,
+  "requestId": "req-xxx",
+  "error": {
+    "code": "E_INSTANCE_CONFLICT",
+    "message": "Multiple Unity Editor sessions claim the selected project.",
+    "details": { "instanceId": "unity-...", "status": "conflict" },
+    "nextActions": [
+      "Close every duplicate Editor process except the intended session.",
+      "Run unitycli instances list to verify one session remains."
+    ],
+    "transient": false,
+    "retryAfterMs": 0
+  }
+}
+```
+
+`error` 只允许上述协议字段；`details` 仅承载业务诊断，不公开内部日志、审计、endpoint、port、listener/process identity、native window handle 或 Windows command line。blocker 使用固定公开 DTO。
+
+普通Tool在业务effect前确认阻断时返回`E_UNITY_BLOCKED`，同一响应的`details.blockers`包含已清洗blocker。同一次调用只在`editorSessionId`未改变时续接完全相同的请求；首次mutation POST后若session改变，禁止向新session再次POST。超时或断连统一返回`E_EXECUTION_TIMEOUT`与outcome unknown；调用方先观察业务状态，再作新的提交决策。
+
+## 错误分类
+
+### CLI 参数错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `UNKNOWN_COMMAND` | 顶层命令不在冻结的公开命令集合中 | 运行 `unitycli --help` |
+| `E_UNKNOWN_OPTION` | option 未在 CLI arity 表中声明，或不属于当前命令 | 删除该 option 并查看 help |
+| `E_OPTION_VALUE_REQUIRED` | 带值 option 缺少值；命令 token 不会被当作值消费 | 传 `--option <value>` 或 `--option=<value>` |
+| `E_OPTION_VALUE_INVALID` | boolean option 的 attached value 不是 `true` 或 `false` | 使用 `--option`、`--option=true` 或 `--option=false` |
+| `E_OBSOLETE_OPTION` | option 已从当前公开语义删除 | 按 `nextActions` 删除旧 option |
+
+### Project Identity / Instance 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `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_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_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 配置 |
+| `E_INSTANCE_REMOTE_PATH_UNSUPPORTED` | 项目位于不支持的远程路径 | 使用本机可验证项目路径 |
+
+### Runtime / Play Mode 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_RUNTIME_NOT_READY` | Runtime 工具需 Play Mode | 先 `tools run editor.play`，transient 可重试 |
+| `E_RUNTIME_SESSION_STALE` | 运行时会话过期 | 重新进入 Play Mode |
+| `E_RUNTIME_TIMEOUT` | 运行时操作超时 | 增加 `--timeout-ms` 或重试 |
+
+### Tool / Discovery 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_TOOL_NOT_FOUND_FOR_TARGET` | 名称不属于当前实例完整 Tool 目录 | 重新运行 `tools group` / `tools search <k1|k2|...>` |
+| `E_TOOL_REGISTRY_UNHEALTHY` | 当前实例 Tool catalog 含 malformed descriptor、重复名称或 ownership 冲突 | 修复实例 registry 后重新 discovery |
+| `E_SCHEMA_INVALID` | 输入不符合 schema | 查看对应 `tools describe` 的 inputSchema |
+
+### 可选预览错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_DRY_RUN_UNSUPPORTED` | 工具不支持 dry-run | 去除可选 `--dry-run` 后直接调用 |
+
+### Scene / Asset / Prefab 错误
+
+| 错误码 | 含义 |
+|--------|------|
+| `E_ASSET_PATH_REQUIRED` | 资产路径缺失 |
+| `E_ASSET_NOT_FOUND` | 资产未找到 |
+| `E_ASSET_OUTPUT_EXISTS` | 输出已存在（用 `--overwrite`） |
+| `E_PREFAB_NOT_FOUND` | Prefab 未找到 |
+| `E_PREFAB_STAGE_NOT_OPEN` | Prefab Stage 未打开 |
+| `E_CAMERA_NOT_FOUND` | 相机未找到 |
+| `E_SCENE_NOT_FOUND` | 场景 path 或唯一场景资产名未找到 |
+| `E_SCENE_AMBIGUOUS` | 场景资产名匹配多个 `.unity` 文件；改传精确 `Assets/*.unity` path |
+| `E_SCENE_VIEW_NOT_AVAILABLE` | Scene 视图不可用 |
+| `E_GAMEOBJECT_DELETE_FAILED` | GameObject 在同步删除后仍存在；按 `nextActions` 检查目标与 Unity Console |
+
+### Occlusion 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_OCCLUSION_BAKE_ACTIVE` | 已存在原生或本CLI拥有的Occlusion bake | 读取`occlusion.bake-status`，等待或精确取消当前operation |
+| `E_OCCLUSION_SCENE_REQUIRED` | 没有loaded saved scene，或scene文件/GUID不可证明 | 保存并加载明确的目标scene后重试 |
+| `E_OCCLUSION_SCENE_DIRTY` | effect前目标scene已有未保存改动 | 先保存或丢弃该scene的既存改动 |
+| `E_OCCLUSION_SETTINGS_VALUE_INVALID` | bake setting不是有限正数，或backface threshold不在`[1,100]` | 按`tools describe occlusion.bake`修正输入 |
+| `E_OCCLUSION_TARGET_CHANGED` | frozen scene集合、GUID、文件或Umbra状态在dispatch前漂移 | 检查当前scene和status后提交全新请求 |
+| `E_OCCLUSION_OPERATION_MISMATCH` | cancel的operationId不是当前active Occlusion operation | 重新读取`occlusion.bake-status`，只对exact operation调用cancel |
+| `E_OCCLUSION_BAKE_CANCELLED` | exact queued Occlusion operation已到达cancelled terminal | 这是effect前已证明的取消终态，不应把原bake调用重试为同一effect；running operation因无native identity返回cancelled=false |
+
+### Project Settings 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_PROJECT_SETTINGS_UNAVAILABLE` | 对应ProjectSettings asset不存在或Unity无法加载 | 检查目标项目和Unity版本后重试 |
+| `E_PROJECT_SETTINGS_VERSION_UNAVAILABLE` | 当前Unity版本、active build target或serialized字段surface未经过支持验证 | 使用descriptor声明的Unity版本；不要猜测字段fallback |
+| `E_PROJECT_SETTINGS_NO_FIELDS` | setter没有提供任何批准字段 | 按`tools describe project.*-settings.set`提供至少一个字段 |
+| `E_PROJECT_SETTINGS_INVALID` | 数值边界、分页、axis或Player enum输入非法 | 按错误中的精确字段约束修正输入 |
+| `E_PROJECT_SETTINGS_LIMIT_EXCEEDED` | legacy Input Manager超过4096个axis，无法在公开有界读取内安全扫描 | 减少Input Manager axis数量后重试 |
+| `E_PROJECT_INPUT_AXIS_NOT_FOUND` | 没有完全同名的legacy Input Manager axis | 先分页读取`project.input-settings`并传精确名称 |
+| `E_PROJECT_SETTINGS_TARGET_CHANGED` | 冻结的Input axis index/name在effect前漂移 | fresh读取Input设置后提交新请求 |
+| `E_PROJECT_SETTINGS_VERIFY_FAILED` | typed readback或ProjectSettings文件SHA未证明持久化终态 | 读取对应`project.*-settings`后再决定是否重试 |
+
+### Editor Utility 错误
+
+| 错误码 | 含义 | 建议 |
+|--------|------|------|
+| `E_EDITOR_AUTOTICK_UNAVAILABLE` | 当前Unity没有可调用的`EditorApplication.SignalTick` | 保持autotick disabled，使用支持该API的Editor |
+| `E_EDITOR_AUTOTICK_INTERVAL_INVALID` | `intervalMs`不在`0..60000` | 按`tools describe editor.autotick.set`修正输入 |
+| `E_EDITOR_FOCUS_UNAVAILABLE` | 当前平台不支持Win32 exact foreground proof | 在Windows Unity Editor执行 |
+| `E_EDITOR_FOCUS_WINDOW_NOT_FOUND` | selected Unity process没有visible top-level main window | 打开该实例主窗口后重试 |
+| `E_EDITOR_FOCUS_TARGET_CHANGED` | frozen HWND不再属于selected process | fresh读取`editor.state`后重试 |
+| `E_EDITOR_FOCUS_UNPROVEN` | frozen HWND未成为稳定native foreground window | 检查OS foreground限制和selected instance |
+| `E_EDITOR_SEARCH_QUERY_REQUIRED` | Unity Search query为空 | 提供非空query |
+| `E_EDITOR_SEARCH_QUERY_TOO_LONG` | query超过2048字符 | 缩短query |
+| `E_EDITOR_SEARCH_PAGE_INVALID` | offset不在`0..10000`或limit不在`1..200` | 使用bounded分页参数 |
+| `E_EDITOR_SEARCH_PROVIDER_INVALID` | providers不是1..16个unique exact ID | 使用descriptor与result返回的provider ID |
+| `E_EDITOR_SEARCH_PROVIDER_NOT_FOUND` | exact provider当前未active | 删除该ID或在Unity Search启用provider |
+| `E_EDITOR_SEARCH_FAILED` | Unity Search同步请求未产生有效页 | 检查query/provider后重试 |
+| `E_EDITOR_ELEMENT_CAPTURE_UNAVAILABLE` | 当前Unity早于6000.7，没有`CaptureToRenderTexture` | 使用Unity6000.7+实例 |
+| `E_EDITOR_ELEMENT_WINDOW_REQUIRED` | 没有提供window type/title | 提供exact EditorWindow type或title |
+| `E_EDITOR_ELEMENT_WINDOW_NOT_FOUND` | 没有attached EditorWindow匹配 | 打开对应Editor window后重试 |
+| `E_EDITOR_ELEMENT_SELECTOR_INVALID` | selector为空、过长或超过16段 | 使用bounded type/#id/.class链 |
+| `E_EDITOR_ELEMENT_NOT_FOUND` | frozen window中没有匹配元素 | 收紧或修正selector |
+| `E_EDITOR_ELEMENT_LIMIT_INVALID` | dimension或byte ceiling超出公开上限 | 使用1..4096尺寸与1024..33554432 bytes |
+| `E_EDITOR_ELEMENT_LIMIT_EXCEEDED` | window/element scan、resolved尺寸或PNG超过上限 | 缩小selector、元素或上限内的capture目标 |
+| `E_EDITOR_ELEMENT_TARGET_CHANGED` | element detach或尺寸在effect后漂移 | fresh解析window/selector后重试 |
+| `E_EDITOR_ELEMENT_CAPTURE_FAILED` | UI Toolkit render未产生有效texture | 检查元素attached/layout状态 |
+| `E_EDITOR_ELEMENT_ARTIFACT_UNAVAILABLE` | request artifact目录不可用 | 检查CLI临时目录权限 |
+| `E_EDITOR_ELEMENT_ARTIFACT_INVALID` | 落盘PNG与encoded size/hash proof不一致 | 检查磁盘后再决定是否重试 |
+| `E_TEST_RUN_NOT_ACTIVE` | 没有本CLI跟踪的active`test.run` | 先启动`test.run` |
+| `E_TEST_CANCEL_NOT_OWNED` | active Test Framework run不属于当前coordinator root | 不控制该run；等待其自然终态 |
+| `E_TEST_CANCEL_IDENTITY_UNPROVEN` | root/run GUID/native TestJobData无法唯一匹配 | 等待running identity或检查原`test.run` |
+| `E_TEST_RUN_CANCELLED` | exact tracked run已取消且GUID不再active | 这是原`test.run`的已证明取消终态，不应重放 |
+
+### Package 错误
+
+| 错误码 | 含义 |
+|--------|------|
+| `E_PACKAGE_NOT_FOUND` | 包未安装 |
+| `E_VFX_PACKAGE_MISSING` | VFX Graph 包未安装 |
+| `E_CINEMACHINE_PRESET_INVALID` | `cinemachine.create` 的 preset 不在 descriptor 声明的集合中 |
+
+### Reflection 错误
+
+| 错误码 | 含义 | 恢复 |
+|--------|------|------|
+| `E_METHOD_NOT_FOUND` | 方法名或显式参数签名不存在 | 运行 `reflection.method.find` 并核对 `parameterType` |
+| `E_METHOD_AMBIGUOUS` | 多个 overload 与参数数量匹配 | 将选中签名的 `parameterType` 数组作为 `parameterTypes` 重试 |
+| `E_TYPE_NOT_FOUND` | 目标类型或参数类型不存在 | 使用完整 C# type name |
+
+### 执行错误
+
+| 错误码 | 含义 |
+|--------|------|
+| `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_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 校验 |
+| `E_UNITY_COMPILE_REQUIRES_EDIT_MODE` | `editor.compile` 在稳定 Play Mode 或 queued-before-effect PlayMode 中被拒绝 |
+| `E_UNITY_COMPILE_FAILED` | owned compilation cycle 完成且包含 compiler error；details 带本次 diagnostics |
+| `E_CODE_COMPILE_FAILED` | Runtime Code 编译失败 |
+| `E_CODE_RUNTIME_EXCEPTION` | Runtime Code 执行异常 |
+| `E_IO_ERROR` | IO 错误 |
+
+## AI Agent 错误处理流程
+
+1. 读取 `error.code` 确定错误类别
+2. 将 `transient`、`retryAfterMs` 和 `nextActions` 作为恢复建议，不把它们当成权限门
+3. 任务池准入`E_UNITY_BUSY`且message证明`no business request was sent`时，可以稍后提交新root；mutation lease busy不得声称effect未开始
+4. `E_EXECUTION_TIMEOUT`只说明没有可信终态；先观察业务状态，再形成全新提交决策
+5. 同session的compile/import/reload/listener transition由supervisor在放行后的同一execution deadline内处理；cross-session mutation禁止自动重投
+
+### nextActions 规则
+
+- Instance 错误的 `nextActions` 必须指向 `instances list`、显式 `--instance`、项目路径或关闭重复 Editor
+- Runtime 错误的 `nextActions` 必须指向 `tools run editor.play` 或 Play Mode 相关操作
+- Discovery 错误的 `nextActions` 必须指向 `tools group`、`tools group list`、`tools search <k1|k2|...>` 或 `tools describe`
+- 弹窗 blocker 的 `nextActions` 必须指向先 `tools run editor.dialogs`，再 `tools run editor.dialog.click`；不得要求人工处理、预定义按钮列表、launch-only 入口或额外确认
+- 诊断错误的 `nextActions` 必须指向 `doctor` 或 `tools run diagnose.preflight`
+
+## JSON 字段命名
+
+所有错误响应使用 camelCase：
+- `nextActions`
+- `retryAfterMs`
+
+错误恢复逻辑必须读取上述 camelCase 字段。

package/docs/extensions.md

@@ -0,0 +1,132 @@
+# 扩展包（Extensions）
+
+扩展包使用与开发指南。
+
+## 当前状态：已实现
+
+扩展包系统已完成，包括 Bridge 包安装、项目工具发现、内部完整性校验、可选包可用性检测，以及独立的 `extensions` 命令组。当前准源是 package-local `defineTool` registry、连接实例中的 typed Tool registry 与目录扩展包 `extensions/<id>/`；公开 discovery 只返回选定实例合并后的完整目录。
+
+## 当前扩展能力
+
+### Bridge 包安装
+
+通过 `init` 命令安装 Unity Editor 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
+```
+
+安装内容：
+- `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 包安装并连接 Unity Editor 后，项目可以通过 `IUnityCliTool<TReq,TRes>` 注册能力。它们自动进入该实例的完整目录，与 package 内置和 Extension 能力使用相同入口：
+
+```powershell
+unitycli tools group
+unitycli tools group list <group>
+unitycli tools describe my.custom-tool
+unitycli tools run my.custom-tool --input '{}'
+```
+
+分组名称来自实际 discovery 输出，不假设项目能力位于 `custom` 分组。
+
+### 诊断
+
+```powershell
+# 检查 CLI 控制面、Bridge 连接和项目工具完整性
+unitycli doctor
+
+# 诊断预检（Unity Bridge 工具）
+unitycli tools run diagnose.preflight
+```
+
+## 扩展包命令
+
+`extensions` 命令组负责扩展包状态、复制和诊断：
+
+```powershell
+unitycli extensions list --project <path>          # 列出扩展状态
+unitycli extensions install <name> --project <path> # 安装已满足依赖的 Unity 侧扩展目录
+unitycli extensions remove <name> --project <path>  # 只移除 manifest 管理的 bundle 文件
+unitycli extensions doctor --project <path>         # 扩展诊断
+```
+
+### init 自动检测
+
+`init` 会根据 Unity 项目已安装的 Package 自动匹配并安装对应的 Unity 侧扩展目录；不会自动安装 Unity Package：
+
+```
+项目检测到 com.unity.probuilder@5.2.4 → 复制 ProBuilder bundle → `tools run probuilder.*` 可用
+项目检测到 com.unity.visualeffectgraph → 复制 VFX Graph bundle → `tools run vfx.*` 可用
+项目检测到 com.unity.cinemachine → 复制 Cinemachine bundle → `tools run cinemachine.*` 可用
+项目检测到 com.unity.render-pipelines.universal → 复制 URP bundle → `tools run urp.*` 可用
+项目检测到 com.unity.render-pipelines.high-definition → 复制 HDRP bundle → `tools run hdrp.*` 可用
+```
+
+## 扩展开发
+
+### 扩展包组成
+
+一个完整的 CLI 扩展包包含：
+
+| 组件 | 说明 |
+|------|------|
+| Manifest | 扩展元数据（名称、版本、依赖） |
+| Descriptor | Tool descriptor 与派生 JSON Schema |
+| C# Bridge 实现 | `unitypkg/Editor` 下的 `IUnityCliTool<TReq,TRes>` 实现，安装后位于 `Packages/com.alpsckr.unitycli/Extensions/<id>/Editor` |
+| 测试 | 单元测试和集成测试 |
+| 文档片段 | 扩展使用说明 |
+
+### 缺依赖行为
+
+当扩展依赖的 Unity Package 未安装或不满足 manifest 的精确版本时：
+
+- 扩展工具通过 `tools group/list/describe/run` 暴露；缺依赖时 `tools describe` 返回 `available: false`、`unavailableReason` 和 `requiresPackages`
+- 执行时返回错误，`error.nextActions` 指向手动安装 Unity Package 与随后运行 `extensions install <id>`
+- 不自动安装 Unity Package，不产生静默失败
+
+```json
+{
+  "name": "probuilder.create-shape",
+  "requiresPackages": ["com.unity.probuilder"],
+  "available": false,
+  "unavailableReason": "E_EXTENSION_DEPENDENCY_MISSING: required Unity package profile com.unity.probuilder@5.2.4 is unavailable for the selected project."
+}
+```
+
+## 已实现的扩展
+
+| 扩展 | 状态 | 说明 |
+|------|------|------|
+| ProBuilder | ✅ 已实现 | 36 个扩展工具（create-shape/extrude-faces/delete-faces 等），只接受 `com.unity.probuilder@5.2.4` |
+| Cinemachine | ✅ 已实现 | Cinemachine camera/target/lens/shot 等工具，需要 `com.unity.cinemachine` |
+| VFX Graph | ✅ 已实现 | VFX Graph、ParticleSystem、LineRenderer、TrailRenderer 相关工具；VFX Graph 子集需要 `com.unity.visualeffectgraph` |
+| URP | ✅ 已实现 | URP renderer feature、volume、settings 等工具，需要 `com.unity.render-pipelines.universal` |
+| HDRP | ✅ 已实现 | HDRP volume、settings 等工具，需要 `com.unity.render-pipelines.high-definition` |
+
+## 安全边界
+
+| 规则 | 说明 |
+|------|------|
+| 扩展不能绕过 descriptor/envelope | 必须通过统一注册和执行流程 |
+| 扩展不能提供任意反射 | 不允许 escape hatch |
+| 内部完整性校验 | handler 代码变更时默认阻止 |
+| 缺依赖不可用 | unavailable + nextActions，不静默失败 |
+
+## 取证与依赖
+
+- 扩展基础设施：`extensions list/install/remove/doctor`、`init --auto-detect`、缺依赖 descriptor 的 `available:false` / `unavailableReason` 与执行错误的 `nextActions`。
+- ProBuilder：源码位于 `extensions/probuilder/`，安装后位于 `Packages/com.alpsckr.unitycli/Extensions/probuilder/`，通过 project-tool bridge 路由提供扩展工具；所有 operation replay 固定于 `com.unity.probuilder@5.2.4`，版本不匹配时在 effect 前拒绝。
+- Cinemachine/VFX/URP/HDRP：源码位于对应 `extensions/<id>/` 目录，安装后位于 `Packages/com.alpsckr.unitycli/Extensions/<id>/`，通过 metadata、bridge domain 和 C# command handler 提供 live Bridge 工具。
+- 验证入口：`npm test`、`npm run contracts:validate`、extension availability tests。

package/docs/risk-and-side-effects.md

@@ -0,0 +1,93 @@
+# Risk and Side Effects
+
+> **How the unified tool descriptor expresses risk, effects, and optional preview**
+
+## The Risk Model
+
+Every tool carries risk hints in its descriptor. Public Tool and CLI control-plane invocation is authorization: there is no separate risk gate, confirmation prompt, predefined button list, or intent review.
+
+| Descriptor Field | Meaning | How AI Should Handle |
+|-----------------|---------|---------------------|
+| `destructiveHint: true` | Tool may irreversibly modify or delete data | Assess the effect; the hint does not block execution |
+| `supportsDryRun: true` | Tool accepts `--dry-run` for a safe preview | Use preview when useful; it is optional |
+| `permissions` | Permission tokens required (e.g. `["executes_code"]`) | Ensure the context allows the required permissions |
+| `target` / `availabilityScope` | Editor target and availability boundary | Execute against the selected open Unity Editor |
+
+## Destructive Commands
+
+`destructiveHint: true` documents a potentially irreversible effect. It does not add an authorization requirement or alter normal execution. Key destructive commands include:
+
+| Command | Title | Supports `--dry-run`? |
+|---------|-------|----------------------|
+| `tools run asset.delete` | Delete Asset | ✅ |
+| `tools run scene.save` | Save Scene | ✅ |
+| `tools run code.exec` | Execute Live Code | ✅ |
+| `tools run scriptable-object.create` | Create ScriptableObject Asset | ✅ |
+| `tools run scriptable-object.modify` | Modify ScriptableObject Asset | ✅ |
+| `tools run texture.modify` | Modify Texture Asset | ✅ |
+| `tools run texture.delete` | Delete Texture Asset | ✅ |
+| `tools run shader.delete` | Delete Shader Asset | ✅ |
+| `tools run object.modify` | Modify Object (deep patch) | ✅ |
+| `tools run reflection.method.call` | Call Method via Reflection | ✅ |
+| `tools run graphics.bake-clear` | Clear Baked Lighting | ❌ |
+| `tools run graphics.bake-start` | Start Light Bake | ❌ |
+| `tools run graphics.bake-reflection-probe` | Bake Reflection Probe | ❌ |
+| `tools run controller.remove-layer` | Remove Animator Controller Layer | ❌ |
+| `tools run editor.menu` | Execute Editor Menu | ❌ |
+| `tools run package.embed` | Embed Package | ✅ |
+| `tools run package.install` | Package Install | ❌ |
+| `tools run package.remove` | Package Remove | ❌ |
+| `tools run package.deploy` | Package Deploy | ✅ |
+| `tools run package.restore` | Package Restore | ✅ |
+| `tools run package.bridge-remove` | Package Bridge Remove | ✅ |
+
+`code.exec` keeps unrestricted synchronous C# execution. It does not reject infinite loops, long sleeps, blocking waits, lock contention, synchronous I/O, or long-running Unity API calls. Before submitting such code, the caller must decide whether it is necessary for the requested result and consider a bounded implementation or an existing Tool; necessary code may still be executed unchanged. After `Run` starts on the Unity Editor main thread, `--timeout-ms` can stop the CLI from waiting but cannot stop the C# code. The Editor can remain unresponsive, the mutation owner can remain active, Unity state can be partial or unknown, and recovery can require terminating the Editor process. A timeout is not proof that the code stopped, so inspect business state before retrying. Dry-run only previews the source hash and planned effect; it does not compile, execute, or prove termination.
+
+The `reflection.method.call` tool performs no scope restriction on the invoked method (public/private/static/instance, any namespace/assembly, Editor/Runtime). Its risk metadata describes that effect; invoking the public Tool authorizes execution. When a method name has overloads, pass the selected signature's `parameterType` values as `parameterTypes`.
+
+### Optional Preview
+
+When `supportsDryRun: true`, pass `--dry-run` to obtain planned effects without executing the mutation. The caller may invoke the Tool directly instead; neither dry-run nor a separate confirmation is required.
+
+## Planned Effects Preview
+
+Mutating tools (both destructive and non-destructive) often return a `plannedEffects` summary in their response. This tells you what the tool intends to change before or after execution:
+
+```json
+{
+  "plannedEffects": {
+    "assetCreated": ["Assets/Materials/New.mat"],
+    "assetModified": ["Assets/Scenes/Main.unity"],
+    "requiresReimport": true
+  }
+}
+```
+
+For tools with `supportsDryRun`, `--dry-run` returns the same `plannedEffects` without executing the actual mutation.
+
+## Project Tool Integrity
+
+Project tools are checked internally before execution. A descriptor mismatch returns a structured error with the next action needed to restore a verified project tool; implementation proof is not included in normal descriptor or success output.
+
+## How to Assess Risk as an AI Agent
+
+1. **Always `tools describe` first.** Read `destructiveHint`, `supportsDryRun`, `target`, `availabilityScope`, permissions, and schemas.
+2. **For destructive tools**: Assess the declared effects and invoke directly when authorized by the public call; use `--dry-run` only when a preview is useful.
+3. **For runtime tools**: Verify Play Mode state before calling `target: "runtime"` tools.
+4. **For direct-final tools**: Set an appropriate `--timeout-ms` when the operation may take time, then use the returned business data as the terminal result.
+5. **For project tools**: Follow any structured mismatch error and use `doctor` for diagnostics.
+
+## Known Limitations
+
+| Limitation | Risk Level | Mitigation |
+|-----------|-----------|------------|
+| Dry-run is not available for every destructive tool | Medium | Invoke directly with declared effects; use preview only where supported |
+| Project tool registration can change during domain reload | Low | Re-discover the selected target and follow structured availability errors |
+
+## Cross-Reference
+
+- Runtime and execution errors: [error-codes](./error-codes.md)
+- Tool descriptor field coverage: [tool-discovery](./tool-discovery.md) §Descriptor field coverage
+- Tool metadata schema: [../schemas/tool-metadata.schema.json](../schemas/tool-metadata.schema.json)
+- Security policy source: `src/security-policy.ts` and `src/security.ts`
+- AI skill (compact version): [/skills/unitycli/SKILL.md](../skills/unitycli/SKILL.md)

package/docs/safety-boundaries.md

@@ -0,0 +1,103 @@
+# 安全边界（Safety Boundaries）
+
+alps-unity-cli的安全模型围绕三个核心原则：Tool副作用必须准确声明、读取型Tool必须纯只读、Extension和command入口不能绕过descriptor/envelope。
+
+## 风险标记体系
+
+每个工具 descriptor 包含以下安全相关字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `destructiveHint` | boolean | true = 可能有不可逆效果的描述信息，不构成执行门 |
+| `supportsDryRun` | boolean | true = 支持可选的 `--dry-run` 预览 |
+| `permissions` | string[] | 执行所需权限 |
+| `target` | string | Tool 可执行的 Editor 目标 |
+| `availabilityScope` | string | Tool 的可用性范围 |
+| `playModeSupport` | string | Play Mode 行为：`supported` / `runtime-only` / `session-affecting` / `editor-only` / `unknown` |
+
+## Tool 安全规则
+
+### 破坏性工具
+
+公开 Tool 与 CLI 控制面调用本身即授权。`destructiveHint`、`sideEffects` 与 `supportsDryRun` 准确描述风险、效果和可选预览，但不得触发额外确认、预定义按钮列表或意图复核，也不得阻止执行。
+
+当前标记为破坏性的工具包括：
+
+| 工具 | 说明 |
+|------|------|
+| `tools run scene.save` | 保存场景 |
+| `tools run asset.delete` | 删除资产 |
+| `tools run scriptable-object.create` | 创建 ScriptableObject 资产 |
+| `tools run scriptable-object.modify` | 修改 ScriptableObject 资产 |
+| `tools run texture.modify` | 修改 Texture 资产 |
+| `tools run texture.delete` | 删除 Texture 资产 |
+| `tools run shader.delete` | 删除 Shader 资产 |
+| `tools run object.modify` | 修改场景对象或持久资产数据 |
+| `tools run component.modify` | 修改场景组件或持久 Prefab/资产组件 |
+| `tools run texture.import-settings` | 持久化 TextureImporter 设置 |
+| `tools run texture.sprite` | 持久化 Sprite importer 与切片设置 |
+| `tools run graphics.settings` | 持久化 GraphicsSettings/QualitySettings |
+| `tools run graphics.bake-settings` | 持久化 LightingSettings 与场景绑定 |
+| `tools run build.platform.set` | 持久切换 active BuildTarget |
+| `tools run build.profile.switch` | 持久切换 active Build Profile |
+| `tools run editor.menu` | 执行编辑器菜单项 |
+| `tools run package.install` | 安装包 |
+| `tools run package.remove` | 移除包 |
+| `tools run package.deploy` | 复制本地 package 源到项目 Packages 目录 |
+| `tools run package.restore` | 从 package.deploy 备份恢复或移除部署目录 |
+| `tools run package.bridge-remove` | 移除 init 复制的 Bridge 包 |
+| `tools run code.exec` | 在已打开的 Unity Editor 中执行代码 |
+
+`code.exec`保留完整的同步C#执行能力，不按代码内容拒绝死循环、长时间sleep、阻塞等待、锁等待、同步I/O或长期占用Unity API。调用方在提交这类代码前必须先判断它对当前结果是否确有必要，并考虑有界写法或现有Tool能否达到同一结果；确有必要时仍可原样执行。代码一旦在Unity Editor主线程开始，`--timeout-ms`和取消只能停止CLI等待，不能强制中止正在运行的C#。Unity可能无响应，mutation owner可能无法收尾，业务状态可能部分改变或无法证明，恢复可能需要结束Editor进程。此时timeout不表示代码已经停止，不能据此直接重试。`--dry-run`只返回source hash和planned effect，不编译、不执行，也不验证代码能够结束。
+
+### 可选预览
+
+```text
+tools describe <tool>        -> 了解 destructiveHint、sideEffects 和 supportsDryRun
+       ↓
+--dry-run（如支持且需要预览） -> 查看 plannedEffects
+       ↓
+tools run <tool>             -> 公开调用即授权并执行
+```
+
+未使用 dry-run 不会产生确认错误。
+
+### Play Mode 支持
+
+- `supported`：Play Mode 下可正常执行，语义基本不变。
+- `runtime-only`：Play Mode 下可执行，但只影响当前运行会话，退出 Play Mode 后不持久。
+- `session-affecting`：允许执行，但可能触发 asset import、compile、domain reload 或 Play Mode 状态变化。
+- `editor-only`：没有合理运行态语义，Play Mode 下返回 `E_TOOL_PLAYMODE_UNAVAILABLE`。
+- `unknown`：当前安装无法证明该状态，调用方必须先重新发现或检查可用性。
+
+## 读取型Tool硬边界
+
+读取型Tool不得：
+- 修改Unity状态（场景、资产、GameObject、Component）
+- 修改文件系统
+- 修改Package依赖
+- 触发import、compile、domain reload或PlayMode变化
+- 产生任何副作用
+
+`tools run`与`command`调用同一Tool时共享该风险分类、安全检查和completion contract。
+
+
+## Extension 安全边界
+
+项目自定义工具不能绕过 descriptor/envelope 安全模型：
+
+| 规则 | 说明 |
+|------|------|
+| 必须有 descriptor | 通过 `IUnityCliTool<TReq,TRes>.Describe()` 提供人工字段，schema 由 Request/Result 派生，不可省略 |
+| 必须通过 envelope | 输入输出必须遵循统一 JSON envelope 格式 |
+| 内部完整性校验 | handler 代码变更时默认阻止执行 |
+| 不可绕过 registry | 不允许直接调用未注册的方法 |
+| 不可提供反射 escape hatch | 不允许通过自定义工具绕过安全检查 |
+
+## 项目 Tool 完整性
+
+项目自定义 Tool 在 `tools run` 前经过内部完整性校验。正常 descriptor 和成功 envelope 不公开校验材料；不匹配时返回结构化错误及恢复步骤。`unitycli doctor` 可用于诊断项目 Tool 状态。
+
+## 正确性边界
+
+schema、目标 instance、canonical project identity、PID/processStartedAt、session、deadline、stale identity、terminal proof、mutation lease 和审计用于确保调用落到正确对象并返回真实结果。它们是正确性约束，不是授权门。

package/docs/target-and-instance.md

@@ -0,0 +1,83 @@
+# Target 与 Instance
+
+> 发现路径：`instances list` -> 显式传`--instance`、`command --project-path`或从Unity项目CWD解析 -> discovery / describe / run
+
+## 稳定项目身份
+
+一个 Unity instance 表示由 **CanonicalPath v1** 确定的项目身份，不表示某个端口或进程。`instanceId` 是 canonical project path 的稳定 SHA-256 identity，格式为 `unity-<64 hex>`；Unity Editor 重启、domain reload 或 listener 换端口不会改变它。PID 只属于当前 Editor session，不参与 `instanceId`。
+
+CLI 只接受本机可证明的 Unity 项目目录。目录大小写、尾分隔符、子目录、junction、directory symlink 和 SUBST 会先归约到同一物理项目根；broken link、reparse loop、不可访问目录或无法证明 case 语义时 fail closed。
+
+## 查看实例
+
+```powershell
+unitycli instances list
+unitycli instances list --all
+unitycli instances prune
+```
+
+`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，而不是绕过校验。
+
+实例状态：
+
+| 状态 | 含义 |
+|------|------|
+| `ready` | 唯一session、listener identity与近期Unity主线程pulse均已证明 |
+| `transitioning` | compile、import、domain reload、listener交接或其他转换正在进行 |
+| `blocked` | 已证明存在需要外部处理的精确modal blocker |
+| `unresponsive` | transport identity存在，但近期Unity主线程pulse或Bridge响应无法证明 |
+| `unverifiable` | PID/start、project claim或文件观察不完整，无法安全证明唯一ownership |
+| `offline` | 该项目没有已证明存活的Editor session |
+| `conflict` | 至少两个已验证live process claim同属该project identity |
+
+`instances prune` 不直接删除进程、无效记录或伪造状态；PID/start-time 无效 claim 和过期 offline record 只由 Unity Bridge registry writer 清理。`invalidRecordCount`只报告本次被隔离的文件数量。
+
+不要读取 registry 文件、listener ID、端口或 URL，也不要直接调用 Bridge HTTP。transport binding 是 session supervisor 的内部职责。
+
+## 选择规则
+
+Tool discovery、describe、`tools run`与`command`使用同一严格选择规则：
+
+1. 显式 `--instance <full-instance-id|canonical-project-path|alias>`。
+2. 未传 selector 时，从 CWD 向上寻找最近的 Unity project root，并解析其 canonical identity。
+3. 无法得到唯一项目身份时返回结构化 instance error。
+
+不存在按PID、短hash、单个存活Editor或任意健康实例自动选取的路径。只有至少两个已验证live process claim才返回`E_INSTANCE_CONFLICT`；权限失败、超时或PID/start/project identity无法证明时返回`E_INSTANCE_UNVERIFIABLE`。选定项目已证明无运行进程时返回`E_INSTANCE_NOT_RUNNING`。
+
+```powershell
+unitycli tools describe editor.compile --instance <project-path>
+unitycli tools run editor.compile --instance my-project --timeout-ms 120000
+unitycli tools run editor.state --instance unity-<64-hex> --input '{}'
+```
+
+## Alias
+
+`target` 只管理 canonical project identity alias，不保存全局活动目标：
+
+```powershell
+unitycli target alias set <projectPath|instanceId> <alias>
+unitycli target alias list
+unitycli target alias unset <alias>
+```
+
+alias 绑定完整 `instanceId`、canonical project path 和 canonicalization version。Editor offline 时 alias 仍可解析 identity，但 Tool discovery 要求运行中的 Editor 并返回 `E_INSTANCE_NOT_RUNNING`。`--instance` 或 CWD 始终决定本次调用的目标。
+
+## Session Supervisor
+
+普通 `tools run` 不直接绑定某个 endpoint。session supervisor 先在准入deadline内选择唯一project identity和已验证session，并等待该target session的任务池放行；放行后创建一份新的execution absolute deadline：
+
+- 每个Editor或Development Player session独立维护默认5/3高低水位，不跨进程共享计数；
+- 对一次transport尝试绑定listener generation；
+- 在compile、import、domain reload或listener restart后重新验证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`并证明业务请求未发送；
+- 放行后的超时或终态前断连返回`E_EXECUTION_TIMEOUT`，调用方必须先观察业务状态，再作新的提交决策。
+
+普通读取型Tool的成功结果来自同一validated generation的完整读取。`editor.state`是唯一即时观察例外：它使用frozen本地descriptor进入同一dispatcher，不依赖可能被transition/modal阻断的Live catalog；随后在固定预算内合并Registry v3、Health v3内存主线程pulse、Bridge、PID/start、project claim和Windows modal证据，返回七态与freshness。`editor.dialogs`与`editor.dialog.click`同样保持catalog-independent recovery。其他Tool与catalog listing仍严格依赖Live实例。Domain Reload只由Registry lifecycle、新listener generation和该generation首个主线程pulse证明，不读取固定时长marker文件。
+
+## Development Player Sidecar
+
+Development Player只接受构建时注入的严格`runtime-config.json` version 2。sidecar包含canonical project/build identity和`taskPoolMaxActive`、`taskPoolReopenAt`；字段缺失、多余、非法，旧version，非development build或identity校验失败时，Runtime Bridge fail closed且不发布runtime session。Player每次重启创建新的runtime session和任务池generation，旧session的未消费grant与consumed identity不得进入新进程。