@alpsckr/unitycli 0.4.0

package/docs/tool-discovery.md

@@ -0,0 +1,104 @@
+# 工具发现（Tool Discovery）
+
+`unitycli` 的 Tool 目录属于一个已连接 Unity 实例。没有连接实例时，discovery 返回稳定 instance error，不返回静态或空目录。
+
+## 实例绑定
+
+每次调用可选传入 `--instance <full-instance-id|project-path|alias>`；显式 selector 优先于 CWD。未传时，CLI 只从当前 Unity 项目 CWD 解析目标，不保存 active target，也不猜测唯一存活实例。
+
+```powershell
+unitycli instances list
+unitycli tools group --instance <id|projectPath|alias>
+```
+
+本文示例省略 `--instance` 时，默认命令运行在目标 Unity 项目 CWD。
+
+## 推荐流程
+
+```text
+tools group
+    -> tools group list <group>
+    -> tools describe <tool>
+    -> tools run <tool> --input '<json>'
+```
+
+不确定分组时使用 `unitycli tools search '<k1|k2|...>'`，多个关键词用 `|` 分隔按 OR 匹配。在PowerShell中必须用单引号包住整段关键词，否则`|`会被解释为shell管道。
+
+### `tools group`
+
+列出当前实例完整 Tool 目录中的分组与计数：
+
+```powershell
+unitycli tools group
+unitycli tools group --instance my-project
+```
+
+### `tools group list`
+
+列出一个真实分组中的全部 Tool 摘要：
+
+```powershell
+unitycli tools group list camera
+unitycli tools group list probuilder --instance my-project
+```
+
+分组名称必须来自当前实例的`tools group`输出，不要假设项目能力都位于`custom`分组。`tools group list`返回`nameSemantics.exact=true`与`groupPrefix=false`：每个`tools[].name`已经是完整精确调用名，group只用于筛选，绝不能拼到name前。
+
+### `tools search`
+
+按名称、summary、description 和 group 搜索当前实例完整目录：
+
+```powershell
+unitycli tools search 'screenshot|camera'
+unitycli tools search 'project-summary|scene' --instance my-project
+```
+
+### `tools describe`
+
+执行前读取单个 Tool 的完整 descriptor：
+
+```powershell
+unitycli tools describe camera.screenshot
+```
+
+公开字段：
+
+| 字段 | 说明 |
+|------|------|
+| `name` / `description` | 精确名称、调用边界、默认行为与主要结果 |
+| `inputSchema` | 完整输入 JSON Schema；结果 schema 由内部 contract 校验，不进入 describe |
+| `destructiveHint` / `sideEffects` | 效果说明，不构成执行门；空 sideEffects 省略 |
+| `supportsDryRun` | 是否支持可选 `--dry-run` |
+| `target` / `playModeSupport` | Editor、Runtime 路由与 PlayMode 语义 |
+| `available:false` / `unavailableReason` | 仅当前不可执行时返回；字段缺失表示当前可用 |
+| `requiresPackages` | 非空 Unity Package 依赖 |
+| `examples` | `description`、结构化业务 `input` 与按需 `execution` |
+
+`group`、`summary` 和 `source` 已在发现层使用，不在单 Tool describe 重复；`outputSchema`、`permissions`、fingerprint、completion 和 handler 只保留在内部 metadata。
+
+## 完整目录语义
+
+一个已连接实例的 catalog 同时包含 package 内置能力、已安装 Extension 能力、项目 `IUnityCliTool<TReq,TRes>` 能力，以及 Editor、Runtime 和 package-local Tool。动作与读取能力都使用同一 `tools group/list/search/describe/run` 路径；读取型 Tool 通过无副作用 descriptor 明确其边界。
+
+目录不按 source、EditMode/PlayMode 或当前可执行性过滤。当前不可执行的能力仍显示，由 descriptor 和执行错误说明原因。静态 capability snapshot 只供 package 生成、contract 和审计，不进入公开 discovery。
+
+## AI Agent 工作流
+
+1. 用 `instances list` 确认 canonical project identity，或切换到目标 Unity 项目 CWD。
+2. 用 `tools group` 读取当前实例目录。
+3. 用 `tools group list`、`tools search '<k1|k2|...>'` 缩小范围。
+4. 用 `tools describe` 获取 schema、状态约束、副作用和示例。
+5. 用 `tools run` 调用同一名称。
+6. 安装 Package、安装 Extension、domain reload 或切换 PlayMode 后重新 discovery。
+
+## 错误处理
+
+- `E_INSTANCE_REQUIRED`：未传 selector，CWD 也不在 Unity 项目中。
+- `E_INSTANCE_NOT_FOUND`：显式 selector 无法解析。
+- `E_INSTANCE_NOT_RUNNING`：目标 identity 已确定，但 Unity Editor 未连接。
+- `E_INSTANCE_CONFLICT`：同一项目存在至少两个已验证live Editor claim。
+- `E_INSTANCE_UNVERIFIABLE`：PID/start或project ownership证据不完整，不能安全选定session。
+- `E_UNITY_UNRESPONSIVE`：transport identity存在，但近期Unity主线程pulse无法证明。
+- `E_TOOL_REGISTRY_UNHEALTHY`：实例 catalog 有 malformed、重复或 ownership 冲突；修复 registry 后重新发现。
+- `E_TOOL_NOT_FOUND_FOR_TARGET`：名称不属于当前实例目录；运行 `tools search <k1|k2|...>` 重新发现相关能力。
+- `E_RUNTIME_NOT_READY`：Runtime Tool 已显示，但执行需要稳定 PlayMode。

package/docs/tool-execution.md

@@ -0,0 +1,178 @@
+# 工具执行（Tool Execution）
+
+`tools run`是统一Tool dispatcher的结构化JSON入口。package内置、Extension、项目注册、Editor、Runtime和package-local Tool也可通过[`command`](command-execution.md)按同一live schema调用；二者不建立第二套catalog或执行路径。
+
+## 基本用法
+
+```powershell
+# 通过 --input 传参（JSON 字符串）
+unitycli tools run camera.list --input '{}'
+
+# 通过 --input-file 传参（JSON 文件）
+unitycli tools run camera.screenshot --input-file params.json
+
+# 通过 --stdin 传参
+echo '{"target":"Main Camera"}' | unitycli tools run camera.screenshot --stdin
+```
+
+## 执行路由
+
+`tools run` 先绑定一个已连接 Unity 实例并从其完整 catalog 解析名称，再根据公开 descriptor 的 `target` 和内部 owner 执行。package-local CLI Tool 可在 CLI 进程内产生业务结果，但同样不能绕过实例绑定和统一 discovery。Unity Tool 只连接用户已打开并由 `--instance` 或 CWD 唯一选中的 Editor，在同一次 direct 调用中返回已证明的终态业务结果。内部 listener 和 transport 由 CLI 管理，不是用户可调用接口。
+
+### Target 路由
+
+| target 值 | 路由行为 |
+|-----------|---------|
+| `editor` | 直接 Bridge 执行 |
+| `runtime` | 检查 Play Mode 状态，非 Play Mode 返回 `E_RUNTIME_NOT_READY` |
+| `both` | 默认走 editor 通道；`--runtime` 标志强制走 runtime 通道 |
+
+## 输入校验
+
+`tools run` 会用 `inputSchema.required` 做执行前必填字段校验。TS 工具的 schema 来自 `defineTool`，C# 工具的 schema 来自 Request DTO 和 `[UnityCliRequired]`。校验失败返回 `E_SCHEMA_INVALID`，`nextActions` 指向 `tools describe <tool>`。
+
+```powershell
+# 正确：提供 inputSchema 要求的字段
+unitycli tools run camera.screenshot --input '{"target":"Main Camera","output":"shot.png"}'
+
+# 错误：缺少必需字段
+unitycli tools run camera.screenshot --input '{}'
+# → E_SCHEMA_INVALID, nextActions 指向 tools describe
+```
+
+## Descriptor 示例
+
+`tools describe <name>` 的每个示例把业务 `input` 与命令层 `execution` 分开。`input` 只包含 `inputSchema` 定义的 Request 字段；dry-run 与 timeout 分别表示为 `execution.dryRun` 和 `execution.timeoutMs`，不能混入业务 JSON。实际调用仍使用固定入口 `tools run <name> --input <json>`，并把 execution 控制映射为 `--dry-run`、`--timeout-ms <n>`；PowerShell内联JSON与`tools search`的pipe-separated关键词都使用单引号，例如`tools search 'camera|screenshot'`，复杂输入优先使用 `--input-file`。
+
+## 调用进程预算
+
+外层命令host必须等待`unitycli`进程退出，不能在CLI仍运行时把调用报告为完成。`--timeout-ms T`分别提供最多`T`的Unity任务池准入等待，以及放行后最多`T`的业务执行；因此host等待预算至少为`2 * T + 5000`毫秒。未显式传timeout时，先从`tools describe`的example execution或Tool边界选择`T`。CLI在任一内部deadline到达后输出一个完整JSON envelope；stdout完成后立即退出，stdout未完成时最多再等待1秒。CLI timeout只结束调用方等待，不会强停Unity中已经开始的effect；host提前退出同样不能作为effect停止证明。
+
+## Unity 任务池准入
+
+每个运行中的Editor或Development Player session拥有独立任务池，默认最多5个active root；达到5后关闭准入，降到4仍保持关闭，只有降到3才重新开放。CLI在发送业务请求前自动等待和轮询，调用方不得手工按100毫秒循环，也不需要管理内部准入identity。
+
+准入等待超过`T`时返回`E_UNITY_BUSY`、`transient:true`和`retryAfterMs:100`。该错误明确证明本次业务Bridge请求未发送、effect未开始，可以稍后提交一个新root。放行后的timeout、断连或终态不明仍返回`E_EXECUTION_TIMEOUT`，表示outcome unknown，必须先观察业务状态。
+
+统一catalog在Editor和Runtime同时在线时，会在每个参与公开结果的target session分别准入；任一在线target未获准时不返回跨池的部分catalog。
+
+## 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。
+
+首次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。
+
+### `editor.compile`
+
+`editor.compile` 是唯一公开编译 Tool。一次调用在同一 root request 下等待 pre-existing import/compile、触发 owned compilation cycle、跨 domain reload 恢复、收集本次 `CompilationPipeline` diagnostics，并等待 Editor 与 listener 重新稳定。公开成功要求 `compile.completed=true`、`errorCount=0`、`editorState.status=ready`；warning 可作为 diagnostics 返回。compiler error 返回 `E_UNITY_COMPILE_FAILED`，不会用旧 Console 历史判断本次结果。
+
+```powershell
+unitycli tools run editor.compile --input '{"refresh":true,"includeWarnings":true}' --timeout-ms 120000
+```
+
+accepted、queued、phase、run ID 和 listener 字段仅属于内部 coordinator，不会成为公开成功。稳定 Play Mode 调用返回 `E_UNITY_COMPILE_REQUIRES_EDIT_MODE`；dry-run 只返回 planned effects，不触发 refresh 或 compile。
+
+## 实例 Tool 完整性
+
+实例 registry 中的 Tool 在 discovery 时整体校验 descriptor 完整性和名称 ownership；malformed、重复或冲突目录返回 `E_TOOL_REGISTRY_UNHEALTHY`，不会静默形成部分 catalog。项目注册 Tool 在执行前继续经过内部完整性校验。正常 descriptor 与成功 envelope 只提供调用所需信息；校验不匹配时，结构化错误会提供恢复步骤。
+
+## 风险元数据与可选预览
+
+公开 Tool 与 CLI 控制面调用本身即授权。`destructiveHint`、`sideEffects` 和 `supportsDryRun` 只描述效果，不引入额外确认、预定义按钮列表或意图复核。
+
+```powershell
+# 可选：支持时预览 plannedEffects，不执行 mutation
+unitycli tools run asset.delete --input '{"path":"Assets/Temp.mat"}' --dry-run
+
+# 公开调用即授权并执行
+unitycli tools run asset.delete --input '{"path":"Assets/Temp.mat"}'
+```
+
+不支持 `--dry-run` 的 Tool 使用该选项时返回 `E_DRY_RUN_UNSUPPORTED`；直接调用不受影响。
+
+## 大响应治理
+
+可能返回大量数据的工具默认应先返回小摘要，AI 调用时也应优先使用过滤、分页和精确读取，避免一次性展开场景、Prefab、序列化对象、Shader 源码或图片 base64。
+
+通用规则：
+
+- 列表/层级工具优先传 `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 路径。
+
+示例：
+
+```powershell
+# 先读场景小页，再用 nextCursor 续页
+unitycli tools run scene.hierarchy --input '{"pageSize":50,"query":"Camera"}'
+
+# 深读时只读需要的字段，并限制数组项
+unitycli tools run component.get --input '{"path":"Player","component":"Inventory","paths":["items"],"maxArrayItems":20}'
+
+# Shader 源码分段读取
+unitycli tools run shader.read --input '{"path":"Assets/Shaders/Probe.shader","maxBytes":65536}'
+```
+
+## 验证策略
+
+执行后应验证结果：
+
+| 工具类型 | 验证方式 |
+|----------|---------|
+| 只读工具 | 检查输出数据是否符合预期 |
+| 修改工具 | 重新调用只读工具确认变更 |
+| Live Editor Tool | 读取能力自己的终态业务数据，必要时用读取型Tool验证 |
+| 诊断工具 | 检查 doctor 或 preflight |
+
+## 错误处理
+
+| 错误码 | 原因 | 恢复方式 |
+|--------|------|---------|
+| `E_TOOL_NOT_FOUND_FOR_TARGET` | 名称不属于当前实例完整 Tool 目录 | 运行 `tools search <k1|k2|...>` 发现相关 Tool，再用 `tools describe` 检查 requiresPackages 和 available |
+| `E_RUNTIME_NOT_READY` | Runtime 工具但非 Play Mode | 先执行 `tools run editor.play`，transient 可重试 |
+| `E_SCHEMA_INVALID` | 输入缺少 inputSchema.required 字段 | 查看 `tools describe` 的 inputSchema |
+| `E_DRY_RUN_UNSUPPORTED` | 工具不支持 dry-run | 去除可选 `--dry-run` 后直接调用 |
+| `E_INSTANCE_CONFLICT` | 至少两个verified live process claim属于同一canonical project | 关闭重复Editor，只保留目标session |
+| `E_INSTANCE_UNVERIFIABLE` | PID/start、project claim或状态文件证据无法证明 | 重新观察；不得把未知mutation自动重投 |
+| `E_INSTANCE_NOT_RUNNING` | 选定项目已证明没有运行中Editor | 检查`instances list`并打开该项目 |
+| `E_UNITY_UNRESPONSIVE` | transport存在，但近期Unity主线程pulse或Bridge响应不可证明 | 读取`editor.state`和`editor.dialogs` |
+| `E_UNITY_BLOCKED` | effect前已确认Unity/UI blocker | 读取同一响应的`details.blockers`并处理对应窗口 |
+| `E_EXECUTION_TIMEOUT` | 调用在终态前超时、断连或触发cross-session mutation fence | 没有可信终态；先观察业务状态，再作全新提交决策 |
+| `E_UNITY_TRANSITION_TIMEOUT` | lifecycle transition 未在 absolute deadline 内稳定 | 检查 `editor.state` 的 progress/blockers |
+
+弹窗 blocker 在原错误的 `details.blockers` 中结构化返回。其 DTO 包含 `type`、`dialogId`、`title`、`message`、`buttons`、`requiresUserAction`、`source` 和 `confidence`。使用只读 `tools run editor.dialogs` 获取当前 dialogId、`observedAt`、modal 状态和按钮；无弹窗时返回空数组，Windows 读取失败返回 `E_DIALOG_OBSERVATION_FAILED`。再以 `tools run editor.dialog.click` 精确传入 dialogId 与规范化 button label。该 Tool 会重新验证选中 Unity 的 PID/processStartedAt、dialogId 和唯一 enabled button，并证明原 dialog 已消失或不再 modal；不匹配分别返回 stale、not-found 或 ambiguous 错误，无法证明点击结果返回 `E_DIALOG_CLICK_UNPROVEN`。任意当前可见 modal 的任意 enabled button 都可点击，不设预定义按钮列表、确认或人工处理门。
+
+## Object 与 Component 修改
+
+`object.modify` 和 `component.modify` 只接受非空 `pathPatches`。每一项必须是可由 Unity `SerializedObject.FindProperty` 定位并 fresh readback 的 direct `replace`；不提供 merge、add、remove、reflection member path 或 diff 旁路。支持的值类型以当前 `inputSchema` 和错误 `nextActions` 为准。
+
+`path` 使用 Unity serialized property path，例如 `m_Name`、`m_LocalPosition.x` 或数组的 `Array.data[0]`。它不是 `/` 分隔的 C# member path。`asset.modify` 是独立的文本资产覆写 Tool，不使用 ObjectPatch。
+
+```powershell
+# 先读后改
+unitycli tools run component.get --input '{"path":"Player","component":"Rigidbody"}'
+unitycli tools run component.modify --input '{"path":"Player","component":"Rigidbody","pathPatches":[{"path":"m_Mass","op":"replace","value":10}]}'
+
+unitycli tools run object.modify --input '{"path":"Player","pathPatches":[{"path":"m_Name","op":"replace","value":"PlayerModified"}]}'
+```
+
+## reflection.method.call
+
+`reflection.method.call` 不做调用范围限制（public/private/static/instance、任意 namespace/assembly、Editor/Runtime），且 `destructiveHint: true`。先用 `reflection.method.find` 获取签名；存在同名 overload 时，将选中签名的 `parameterType` 数组作为 `parameterTypes`。公开调用即授权：
+
+```powershell
+unitycli tools run reflection.method.call --input '{
+  "typeName":"UnityEngine.Transform",
+  "methodName":"Translate",
+  "parameterTypes":["UnityEngine.Vector3","UnityEngine.Space"],
+  "args":[{"x":1,"y":0,"z":0},0],
+  "instanceRef":{"instanceId":123}
+}'
+```
+
+`--dry-run` 返回 `plannedEffects` 且不执行方法；它是可选预览。无法唯一选择 overload 时返回 `E_METHOD_AMBIGUOUS` 和候选签名。调用后只返回方法调用的业务结果和已声明 completion readback；内部审计不进入公开成功响应。
+
+## asset.get-data 复用 serializer
+
+`asset.get-data` 是 asset-friendly wrapper，底层复用 `object.get-data` 的 `ObjectSerializer`，不重复实现序列化。`object.get-data` 是任意 `UnityEngine.Object` 深序列化主入口，`asset.get-data` 提供按 assetPath 解析的便捷入口。

package/extensions/cinemachine/bridge/domains/cinemachine.ts

@@ -0,0 +1,115 @@
+import { boolFlag, compactArgs, floatFlag, numberFlag, stringFlag, targetArgs } from "../args.js";
+import type { BridgeCommandSpec } from "../types.js";
+
+export const cinemachineBridgeSpecs: BridgeCommandSpec[] = markToolsOnly([
+  { group: "cinemachine", command: "ping", bridgeCommand: "project-tool.run", toolName: "cinemachine.ping", buildArgs: cinemachinePingArgs },
+  { group: "cinemachine", command: "create", bridgeCommand: "project-tool.run", toolName: "cinemachine.create", buildArgs: cinemachineCreateArgs },
+  { group: "cinemachine", command: "target", bridgeCommand: "project-tool.run", toolName: "cinemachine.target", buildArgs: cinemachineTargetArgs },
+  { group: "cinemachine", command: "lens", bridgeCommand: "project-tool.run", toolName: "cinemachine.lens", buildArgs: cinemachineLensArgs },
+  { group: "cinemachine", command: "priority", bridgeCommand: "project-tool.run", toolName: "cinemachine.priority", buildArgs: cinemachinePriorityArgs },
+  { group: "cinemachine", command: "blend", bridgeCommand: "project-tool.run", toolName: "cinemachine.blend", buildArgs: cinemachineBlendArgs },
+  { group: "cinemachine", command: "body", bridgeCommand: "project-tool.run", toolName: "cinemachine.body", buildArgs: cinemachineBodyArgs },
+  { group: "cinemachine", command: "aim", bridgeCommand: "project-tool.run", toolName: "cinemachine.aim", buildArgs: cinemachineAimArgs },
+  { group: "cinemachine", command: "noise", bridgeCommand: "project-tool.run", toolName: "cinemachine.noise", buildArgs: cinemachineNoiseArgs },
+  { group: "cinemachine", command: "brain.ensure", bridgeCommand: "project-tool.run", toolName: "cinemachine.brain.ensure", buildArgs: cinemachineTargetOnlyArgs },
+  { group: "cinemachine", command: "brain.status", bridgeCommand: "project-tool.run", toolName: "cinemachine.brain.status", buildArgs: cinemachineTargetOnlyArgs },
+  { group: "cinemachine", command: "extension.list", bridgeCommand: "project-tool.run", toolName: "cinemachine.extension.list", buildArgs: cinemachineTargetOnlyArgs },
+  { group: "cinemachine", command: "extension.add", bridgeCommand: "project-tool.run", toolName: "cinemachine.extension.add", buildArgs: cinemachineExtensionTypeArgs },
+  { group: "cinemachine", command: "extension.remove", bridgeCommand: "project-tool.run", toolName: "cinemachine.extension.remove", buildArgs: cinemachineExtensionTypeArgs }
+]);
+
+function markToolsOnly(specs: BridgeCommandSpec[]): BridgeCommandSpec[] {
+  return specs.map((spec) => ({ ...spec, toolsOnly: true }));
+}
+
+function cinemachinePingArgs({ flags }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({});
+}
+
+function cinemachineCreateArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    preset: positionalTarget ?? stringFlag(flags, "preset") ?? stringFlag(flags, "type"),
+    name: stringFlag(flags, "name"),
+    parent: stringFlag(flags, "parent"),
+    follow: stringFlag(flags, "follow"),
+    lookAt: stringFlag(flags, "look-at"),
+    x: floatFlag(flags, "x"),
+    y: floatFlag(flags, "y"),
+    z: floatFlag(flags, "z"),
+    priority: numberFlag(flags, "priority")
+  });
+}
+
+function cinemachineTargetArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    follow: stringFlag(flags, "follow"),
+    lookAt: stringFlag(flags, "look-at")
+  });
+}
+
+function cinemachineLensArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    fieldOfView: floatFlag(flags, "field-of-view") ?? floatFlag(flags, "fov"),
+    nearClipPlane: floatFlag(flags, "near-clip-plane") ?? floatFlag(flags, "near"),
+    farClipPlane: floatFlag(flags, "far-clip-plane") ?? floatFlag(flags, "far"),
+    orthographicSize: floatFlag(flags, "orthographic-size"),
+    dutch: floatFlag(flags, "dutch")
+  });
+}
+
+function cinemachinePriorityArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    priority: numberFlag(flags, "priority"),
+    enabled: boolFlag(flags, "enabled")
+  });
+}
+
+function cinemachineBlendArgs({ flags }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    style: stringFlag(flags, "style"),
+    duration: floatFlag(flags, "duration"),
+    target: stringFlag(flags, "target")
+  });
+}
+
+function cinemachineBodyArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    body: stringFlag(flags, "body") ?? stringFlag(flags, "type"),
+    property: stringFlag(flags, "property"),
+    value: stringFlag(flags, "value")
+  });
+}
+
+function cinemachineAimArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    aim: stringFlag(flags, "aim") ?? stringFlag(flags, "type"),
+    property: stringFlag(flags, "property"),
+    value: stringFlag(flags, "value")
+  });
+}
+
+function cinemachineNoiseArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    noiseProfile: stringFlag(flags, "noise-profile"),
+    amplitude: floatFlag(flags, "amplitude"),
+    frequency: floatFlag(flags, "frequency"),
+    remove: boolFlag(flags, "remove")
+  });
+}
+
+function cinemachineTargetOnlyArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs(targetArgs(flags, positionalTarget));
+}
+
+function cinemachineExtensionTypeArgs({ flags, positionalTarget }: Parameters<BridgeCommandSpec["buildArgs"]>[0]): Record<string, unknown> {
+  return compactArgs({
+    ...targetArgs(flags, positionalTarget),
+    extensionType: stringFlag(flags, "extension-type") ?? stringFlag(flags, "type")
+  });
+}

package/extensions/cinemachine/docs/cinemachine.md

@@ -0,0 +1,50 @@
+# Cinemachine 工具
+
+Unity Cinemachine 智能相机系统的 CLI 工具集。支持 Cinemachine CM2 与 CM3 的公开相机、管线和扩展 API，提供可用性检测、虚拟相机创建、目标跟踪、镜头控制、优先级管理、混合配置、Body/Aim 管线组件、噪声和扩展组件管理。
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `cinemachine.ping` | 只读检测 Cinemachine 包和关键反射 API 可用性 |
+| `cinemachine.create` | 创建虚拟相机，支持预设（follow, third_person, freelook, dolly, static, top_down, side_scroller） |
+| `cinemachine.target` | 设置 Follow / LookAt 目标 |
+| `cinemachine.lens` | 读写镜头属性（FOV、近远裁面、正交尺寸、Dutch 角） |
+| `cinemachine.priority` | 读写优先级及启用状态 |
+| `cinemachine.blend` | 读写 CinemachineBrain 的 DefaultBlend（风格 + 时长） |
+| `cinemachine.body` | 切换或配置 Body 管线组件（CinemachineFollow, CinemachinePositionComposer 等） |
+| `cinemachine.aim` | 切换或配置 Aim 管线组件（CinemachineRotationComposer, CinemachineHardLookAt 等） |
+| `cinemachine.noise` | 添加、配置或移除多通道 Perlin 噪声组件 |
+| `cinemachine.brain.ensure` | 确保目标相机挂载 CinemachineBrain |
+| `cinemachine.brain.status` | 读取 Brain 及当前活动虚拟相机状态 |
+| `cinemachine.extension.list` | 列出目标上的 CinemachineExtension 派生组件 |
+| `cinemachine.extension.add` | 添加 CinemachineExtension 派生组件，并重新枚举相机扩展确认存在 |
+| `cinemachine.extension.remove` | 移除 CinemachineExtension 派生组件，并重新枚举相机扩展确认不存在 |
+
+## 前置条件
+
+- Unity 项目需安装 `com.unity.cinemachine` 包
+- 缺少依赖时工具返回 `unavailable` + `nextActions`
+
+## 发现与使用
+
+```bash
+# 列出 Cinemachine 工具
+unitycli tools group list cinemachine --project <project-path>
+
+# 调用前读取完整 schema、preset 集合和 examples
+unitycli tools describe cinemachine.create --project <project-path>
+
+# 检测 Cinemachine 可用性
+unitycli tools run cinemachine.ping --project <project-path> --input '{}'
+
+# 创建跟随相机；非法 preset 返回 E_CINEMACHINE_PRESET_INVALID，且不会创建对象
+unitycli tools run cinemachine.create --project <project-path> --input '{"preset":"follow","name":"PlayerCam","follow":"Player"}'
+```
+
+## 依赖缺失时的行为
+
+当目标 Unity 项目未安装 Cinemachine 包时：
+- 工具标记为 `unavailable`
+- 返回 `E_CINEMACHINE_PACKAGE_NOT_FOUND` 错误码
+- `nextActions` 提示安装 `com.unity.cinemachine`

package/extensions/cinemachine/extension.json

@@ -0,0 +1,129 @@
+{
+  "id": "cinemachine",
+  "name": "Cinemachine",
+  "version": "1.0.0",
+  "description": "Cinemachine CM2 and CM3 camera tools: virtual camera creation, targets, lens, priority, blends, body/aim/noise, brain configuration, and extensions.",
+  "unityPackages": [
+    {
+      "packageId": "com.unity.cinemachine",
+      "displayName": "Cinemachine"
+    }
+  ],
+  "contributions": {
+    "tools": [
+      {
+        "name": "cinemachine.ping"
+      },
+      {
+        "name": "cinemachine.create"
+      },
+      {
+        "name": "cinemachine.target"
+      },
+      {
+        "name": "cinemachine.lens"
+      },
+      {
+        "name": "cinemachine.priority"
+      },
+      {
+        "name": "cinemachine.blend"
+      },
+      {
+        "name": "cinemachine.body"
+      },
+      {
+        "name": "cinemachine.aim"
+      },
+      {
+        "name": "cinemachine.noise"
+      },
+      {
+        "name": "cinemachine.brain.ensure"
+      },
+      {
+        "name": "cinemachine.brain.status"
+      },
+      {
+        "name": "cinemachine.extension.list"
+      },
+      {
+        "name": "cinemachine.extension.add"
+      },
+      {
+        "name": "cinemachine.extension.remove"
+      }
+    ],
+    "csharpEntries": [
+      {
+        "type": "UnityCli.Cinemachine.AimTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.BlendTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.BodyTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.BrainEnsureTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.BrainStatusTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.CreateTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.ExtensionListTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.ExtensionAddTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.ExtensionRemoveTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.LensTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.NoiseTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.PingTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.PriorityTool",
+        "description": "Live capability implementation."
+      },
+      {
+        "type": "UnityCli.Cinemachine.TargetTool",
+        "description": "Live capability implementation."
+      }
+    ]
+  },
+  "unityInstall": {
+    "layout": "directory",
+    "include": [
+      "extension.json",
+      "unitypkg/",
+      "docs/"
+    ]
+  },
+  "tags": [
+    "camera",
+    "cinematography",
+    "animation"
+  ]
+}

package/extensions/cinemachine/unitypkg/Editor/Cinemachine/CinemachineExtensionToolSupport.cs

@@ -0,0 +1,15 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+namespace UnityCli.Cinemachine
+{
+    /// <summary>扩展组件 Tool 的共享目标与类型解析。</summary>
+    internal static class CinemachineExtensionToolSupport
+    {
+        public static UnityEngine.GameObject Target(string target, string tool) { CinemachineToolSupport.EnsureEditorReady(tool); CinemachineToolSupport.EnsureCinemachineAvailable(); var value = CinemachineToolSupport.ResolveRequiredTarget(target, tool + " requires target."); CinemachineToolSupport.RequireCameraComponent(value); return value; }
+        public static System.Type Type(string name) { var value = CinemachineToolSupport.ResolveComponentType(name) ?? GameObjectToolSupport.FindType(name); if (value == null || CinemachineToolSupport.ExtensionBaseType == null || !CinemachineToolSupport.ExtensionBaseType.IsAssignableFrom(value)) throw new UnityCliBridge.BridgeCommandException("E_CINEMACHINE_COMPONENT_TYPE_NOT_FOUND", "CinemachineExtension type not found: " + name, "Pass a CinemachineExtension-derived type name."); return value; }
+        public static List<string> List(UnityEngine.GameObject target) { var result = new List<string>(); foreach (var item in target.GetComponents(CinemachineToolSupport.ExtensionBaseType)) result.Add(item.GetType().Name); return result; }
+        // 每次变更后按 owner ID 重新解析相机扩展，不能依赖 AddComponent/DestroyObject 的请求回显。
+        public static bool Contains(long targetId, System.Type type, out UnityEngine.GameObject observedTarget) { observedTarget = CinemachineToolSupport.ResolveRequiredTarget(targetId.ToString(System.Globalization.CultureInfo.InvariantCulture), "Cinemachine extension target could not be resolved after mutation."); foreach (var item in observedTarget.GetComponents(CinemachineToolSupport.ExtensionBaseType)) if (item != null && type.IsInstanceOfType(item)) return true; return false; }
+    }
+}
+#endif