@alpsckr/unitycli 0.4.0

package/dist/tools/tools/search.d.ts

@@ -0,0 +1,17 @@
+export interface ToolsSearchRequest {
+    keyword: string;
+}
+export interface ToolsSearchItem {
+    name: string;
+    summary: string;
+    group: string;
+    source: string;
+}
+export interface ToolsSearchResult {
+    keyword: string;
+    tokens: string[];
+    count: number;
+    tools: ToolsSearchItem[];
+}
+declare const _default: import("../define.js").ToolDefinition<ToolsSearchRequest, ToolsSearchResult>;
+export default _default;

package/dist/tools/tools/search.js

@@ -0,0 +1,42 @@
+import { loadToolCatalog } from "../catalog.js";
+import { defineTool } from "../define.js";
+import { StructuredToolError } from "../errors.js";
+import { toolSource } from "../metadata/index.js";
+export default defineTool({
+    name: "tools.search",
+    summary: "Search tools by `|`-separated keywords across name, summary, description, and group with OR matching.",
+    description: "Search the complete Tool catalog owned by the connected Unity instance. keyword is split on `|`; a Tool matches when any token appears in its name, summary, description, or group (case-insensitive, OR semantics). Results are routing summaries only — use tools describe for schema, availability, and full details.",
+    group: "tools",
+    handler: "offline",
+    supportStatus: "cli-only",
+    destructiveHint: false,
+    sideEffects: [],
+    playModeSupport: "supported",
+    examples: [
+        { description: "Search for hierarchy tools", argv: ["tools", "run", "tools.search", "--input", "{\"keyword\":\"hierarchy\"}"] },
+        { description: "Search several capability areas in one call", argv: ["tools", "run", "tools.search", "--input", "{\"keyword\":\"editor|console|screenshot\"}"] },
+    ],
+    async execute(request, context) {
+        const tokens = (request.keyword ?? "")
+            .split("|")
+            .map((token) => token.trim().toLowerCase())
+            .filter((token) => token.length > 0);
+        if (tokens.length === 0) {
+            throw new StructuredToolError("TOOLS_SEARCH_KEYWORD_REQUIRED", "Pass one or more `|`-separated keywords: unitycli tools search <k1|k2|...>.", ["Run unitycli tools group to see tool groups."]);
+        }
+        const flags = context.flags ?? {};
+        const catalog = await loadToolCatalog(flags, context, `${context.requestId}_search_execution`);
+        if (catalog.ok === false) {
+            throw StructuredToolError.from(catalog.error ?? { code: "TOOL_DISCOVERY_FAILED", message: "Tool discovery failed." });
+        }
+        const matches = catalog.tools.filter((tool) => tokens.some((token) => [tool.name, tool.summary, tool.description, tool.group].some((value) => value.toLowerCase().includes(token))));
+        const tools = matches.map((tool) => ({
+            name: tool.name,
+            summary: tool.summary,
+            group: tool.group,
+            source: toolSource(tool),
+        }));
+        return { keyword: request.keyword, tokens, count: tools.length, tools };
+    },
+});
+//# sourceMappingURL=search.js.map

package/dist/tools/tools/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/tools/tools/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAMlD,eAAe,UAAU,CAAwC;IAC/D,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,uGAAuG;IAChH,WAAW,EAAE,0TAA0T;IACvU,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,UAAU;IACzB,eAAe,EAAE,KAAK;IACtB,WAAW,EAAE,EAAE;IACf,eAAe,EAAE,WAAW;IAC5B,QAAQ,EAAE;QACR,EAAE,WAAW,EAAE,4BAA4B,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B,CAAC,EAAE;QAC/H,EAAE,WAAW,EAAE,6CAA6C,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,6CAA6C,CAAC,EAAE;KACjK;IACD,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO;QAC5B,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;aACnC,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;aAC1C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,mBAAmB,CAC3B,+BAA+B,EAC/B,6EAA6E,EAC7E,CAAC,8CAA8C,CAAC,CACjD,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,mBAAmB,CAAC,CAAC;QAC/F,IAAI,OAAO,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;YACzB,MAAM,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC,CAAC;QACxH,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5C,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CACpB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAC7G,CACF,CAAC;QACF,MAAM,KAAK,GAAsB,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACtD,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC;SACzB,CAAC,CAAC,CAAC;QACJ,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IAC1E,CAAC;CACF,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+import type { Envelope, ToolError } from "./protocol/envelope.js";
+/** CLI 内部名称仅作为唯一 wire envelope 的类型别名。 */
+export type CliResult<T = unknown, TDetails = unknown> = Envelope<T, TDetails>;
+/** CLI 内部名称仅作为唯一 wire error 的类型别名。 */
+export type CliError<TDetails = unknown> = ToolError<TDetails>;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/unity-project-processes.d.ts

@@ -0,0 +1,12 @@
+export interface UnityProjectProcess {
+    processId: number;
+    processStartedAt: string;
+    executablePath: string;
+    argv: string[];
+    projectPath: string;
+}
+/** 解析带显式 -projectPath、可正向归因的 interactive Unity.exe 命令行观察。 */
+export declare function parseUnityProjectProcessDiscoveryOutput(stdout: string): UnityProjectProcess[];
+/** 枚举可提供显式项目参数的 Unity.exe，并以 CanonicalPath v1 精确归因；不覆盖 Registry 正式会话证明。 */
+export declare function findUnityProjectProcesses(instanceId: string, canonicalProjectPath: string, timeoutMs?: number): Promise<UnityProjectProcess[]>;
+export declare const WINDOWS_UNITY_PROCESS_DISCOVERY_SCRIPT = "$ErrorActionPreference = 'Stop'\nAdd-Type -TypeDefinition @\"\nusing System; using System.Runtime.InteropServices;\npublic static class UnityCliProjectProcessArgv { [DllImport(\"shell32.dll\", CharSet=CharSet.Unicode)] public static extern IntPtr CommandLineToArgvW(string commandLine, out int argc); [DllImport(\"kernel32.dll\")] public static extern IntPtr LocalFree(IntPtr value); public static string[] Parse(string commandLine) { int argc; var memory=CommandLineToArgvW(commandLine,out argc); if(memory==IntPtr.Zero) return null; try { var result=new string[argc]; for(var i=0;i<argc;i++) result[i]=Marshal.PtrToStringUni(Marshal.ReadIntPtr(memory,i*IntPtr.Size)); return result; } finally { LocalFree(memory); } } }\n\"@\n$items=@(Get-CimInstance Win32_Process -Filter \"Name='Unity.exe'\" -ErrorAction Stop | ForEach-Object { $argv=[UnityCliProjectProcessArgv]::Parse($_.CommandLine); if($argv){ @{ processId=[int]$_.ProcessId; processStartedAt=([DateTime]$_.CreationDate).ToUniversalTime().ToString('O'); executablePath=$_.ExecutablePath; argv=@($argv) } } })\nConvertTo-Json -InputObject $items -Compress -Depth 5";

package/dist/unity-project-processes.js

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { resolveProjectIdentityAsync } from "./project-identity.js";
+const execFileAsync = promisify(execFile);
+/** 解析带显式 -projectPath、可正向归因的 interactive Unity.exe 命令行观察。 */
+export function parseUnityProjectProcessDiscoveryOutput(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return [];
+    const parsed = JSON.parse(text);
+    const items = Array.isArray(parsed) ? parsed : [parsed];
+    return items.flatMap((item) => {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            return [];
+        const record = item;
+        if (!Number.isInteger(record.processId) || Number(record.processId) <= 0
+            || typeof record.processStartedAt !== "string" || !Number.isFinite(Date.parse(record.processStartedAt))
+            || typeof record.executablePath !== "string" || basename(record.executablePath).toLowerCase() !== "unity.exe"
+            || !Array.isArray(record.argv) || record.argv.some((value) => typeof value !== "string"))
+            return [];
+        const argv = record.argv;
+        if (argv.some((value) => value.toLowerCase() === "-batchmode"))
+            return [];
+        const projectIndex = argv.findIndex((value) => value.toLowerCase() === "-projectpath");
+        if (projectIndex < 0 || !argv[projectIndex + 1])
+            return [];
+        return [{ processId: Number(record.processId), processStartedAt: new Date(Date.parse(record.processStartedAt)).toISOString(), executablePath: record.executablePath, argv, projectPath: argv[projectIndex + 1] }];
+    });
+}
+/** 枚举可提供显式项目参数的 Unity.exe，并以 CanonicalPath v1 精确归因；不覆盖 Registry 正式会话证明。 */
+export async function findUnityProjectProcesses(instanceId, canonicalProjectPath, timeoutMs = 3_000) {
+    if (process.platform !== "win32" || timeoutMs < 1)
+        return [];
+    const startedAt = Date.now();
+    const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_UNITY_PROCESS_DISCOVERY_SCRIPT], { timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 });
+    const matches = [];
+    for (const candidate of parseUnityProjectProcessDiscoveryOutput(stdout)) {
+        const remainingMs = Math.max(0, timeoutMs - (Date.now() - startedAt));
+        if (remainingMs < 1)
+            break;
+        try {
+            if ((await resolveProjectIdentityAsync(candidate.projectPath, { timeoutMs: remainingMs })).instanceId === instanceId)
+                matches.push(candidate);
+        }
+        catch {
+            // Canonicalization could not prove this candidate; it must not become a project claim.
+        }
+    }
+    return matches.sort((left, right) => left.processId - right.processId);
+}
+export const WINDOWS_UNITY_PROCESS_DISCOVERY_SCRIPT = `$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition @"
+using System; using System.Runtime.InteropServices;
+public static class UnityCliProjectProcessArgv { [DllImport("shell32.dll", CharSet=CharSet.Unicode)] public static extern IntPtr CommandLineToArgvW(string commandLine, out int argc); [DllImport("kernel32.dll")] public static extern IntPtr LocalFree(IntPtr value); public static string[] Parse(string commandLine) { int argc; var memory=CommandLineToArgvW(commandLine,out argc); if(memory==IntPtr.Zero) return null; try { var result=new string[argc]; for(var i=0;i<argc;i++) result[i]=Marshal.PtrToStringUni(Marshal.ReadIntPtr(memory,i*IntPtr.Size)); return result; } finally { LocalFree(memory); } } }
+"@
+$items=@(Get-CimInstance Win32_Process -Filter "Name='Unity.exe'" -ErrorAction Stop | ForEach-Object { $argv=[UnityCliProjectProcessArgv]::Parse($_.CommandLine); if($argv){ @{ processId=[int]$_.ProcessId; processStartedAt=([DateTime]$_.CreationDate).ToUniversalTime().ToString('O'); executablePath=$_.ExecutablePath; argv=@($argv) } } })
+ConvertTo-Json -InputObject $items -Compress -Depth 5`;
+//# sourceMappingURL=unity-project-processes.js.map

package/dist/unity-project-processes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unity-project-processes.js","sourceRoot":"","sources":["../src/unity-project-processes.ts"],"names":[],"mappings":"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"}

package/dist/util.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 通用工具函数：跨模块共享的小型纯函数。
+ * 仅放真正无副作用的通用辅助，避免领域逻辑。
+ */
+/** 去除 UTF-8 BOM (\uFEFF) 前缀。读取用户/Unity 写入的 JSON 文件时统一处理。 */
+export declare function stripBom(text: string): string;
+/**
+ * 关键词搜索打分：完全匹配 > 前缀匹配 > 包含匹配 > 无。
+ * 用于Tool discovery等稳定公开列表的排序。
+ */
+export declare function scoreSearch(text: string, query: string): number;

package/dist/util.js

@@ -0,0 +1,22 @@
+/**
+ * 通用工具函数：跨模块共享的小型纯函数。
+ * 仅放真正无副作用的通用辅助，避免领域逻辑。
+ */
+/** 去除 UTF-8 BOM (\uFEFF) 前缀。读取用户/Unity 写入的 JSON 文件时统一处理。 */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * 关键词搜索打分：完全匹配 > 前缀匹配 > 包含匹配 > 无。
+ * 用于Tool discovery等稳定公开列表的排序。
+ */
+export function scoreSearch(text, query) {
+    if (text === query)
+        return 8;
+    if (text.startsWith(query))
+        return 4;
+    if (text.includes(query))
+        return 2;
+    return 0;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACrC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/windows-editor-state.d.ts

@@ -0,0 +1,31 @@
+export interface WindowsEditorButton {
+    label: string;
+    hwnd: string;
+    enabled: boolean;
+}
+export interface WindowsEditorWindow {
+    hwnd: string;
+    ownerHwnd: string | null;
+    className: string;
+    title: string;
+    message: string;
+    visible: boolean;
+    enabled: boolean;
+    buttons: WindowsEditorButton[];
+    modal: boolean;
+}
+export interface WindowsEditorStateProbe {
+    supported: boolean;
+    outcome: "observed-empty" | "observed-blocked" | "unproven" | "unsupported";
+    windows: WindowsEditorWindow[];
+    reason?: "timeout" | "exit" | "parse";
+}
+export interface WindowsEditorStateOptions {
+    platform?: NodeJS.Platform | string;
+    timeoutMs?: number;
+}
+/** 仅枚举指定 Unity PID 的顶层与 owned Windows，不发送任何窗口消息。 */
+export declare function probeWindowsEditorState(processId: number, options?: WindowsEditorStateOptions): Promise<WindowsEditorStateProbe>;
+export declare function buildWindowsEditorStateScript(processId: number): string;
+export declare function parseWindowsEditorStateOutput(output: string): WindowsEditorStateProbe;
+export declare const WINDOWS_EDITOR_STATE_PS_SCRIPT_TEMPLATE = "\n$ErrorActionPreference = 'Stop'\ntry {\n  Add-Type -TypeDefinition @\"\nusing System; using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text;\npublic static class UnityCliWindowProbeNative {\n  private delegate bool EnumWindowProc(IntPtr hwnd, IntPtr state);\n  [DllImport(\"user32.dll\")] private static extern bool EnumWindows(EnumWindowProc callback, IntPtr state);\n  [DllImport(\"user32.dll\")] private static extern bool EnumChildWindows(IntPtr parent, EnumWindowProc callback, IntPtr state);\n  [DllImport(\"user32.dll\")] private static extern uint GetWindowThreadProcessId(IntPtr hwnd, out uint processId);\n  [DllImport(\"user32.dll\")] private static extern IntPtr GetWindow(IntPtr hwnd, uint command);\n  [DllImport(\"user32.dll\")] [return: MarshalAs(UnmanagedType.Bool)] public static extern bool IsWindowVisible(IntPtr hwnd);\n  [DllImport(\"user32.dll\")] [return: MarshalAs(UnmanagedType.Bool)] public static extern bool IsWindowEnabled(IntPtr hwnd);\n  [DllImport(\"user32.dll\", CharSet = CharSet.Unicode)] private static extern int GetClassNameW(IntPtr hwnd, StringBuilder value, int count);\n  [DllImport(\"user32.dll\", CharSet = CharSet.Unicode)] private static extern int GetWindowTextW(IntPtr hwnd, StringBuilder value, int count);\n  public static long[] TopLevelWindows(uint pid) { var handles=new List<long>(); EnumWindows((h,s)=>{uint p;GetWindowThreadProcessId(h,out p);if(p==pid)handles.Add(h.ToInt64());return true;},IntPtr.Zero); return handles.ToArray(); }\n  public static long Owner(IntPtr hwnd) { return GetWindow(hwnd,4).ToInt64(); }\n  public static string ClassName(IntPtr hwnd) { var value=new StringBuilder(256);GetClassNameW(hwnd,value,value.Capacity);return value.ToString(); }\n  public static string WindowText(IntPtr hwnd) { var value=new StringBuilder(2048);GetWindowTextW(hwnd,value,value.Capacity);return value.ToString(); }\n  public static object[] Buttons(IntPtr parent) { var result=new List<object>();EnumChildWindows(parent,(h,s)=>{if(string.Equals(ClassName(h),\"Button\",StringComparison.Ordinal)){var label=WindowText(h);if(!string.IsNullOrEmpty(label))result.Add(new {label=label,hwnd=\"0x\"+h.ToInt64().ToString(\"X\"),enabled=IsWindowEnabled(h)});}return true;},IntPtr.Zero);return result.ToArray(); }\n  public static string Message(IntPtr parent,string title) { var result=new List<string>();EnumChildWindows(parent,(h,s)=>{var className=ClassName(h);if(string.Equals(className,\"Button\",StringComparison.Ordinal)||string.Equals(className,\"Static\",StringComparison.Ordinal))return true;var text=WindowText(h).Trim();if(!string.IsNullOrEmpty(text)&&!string.Equals(text,\"Static\",StringComparison.Ordinal)&&!string.Equals(text,title,StringComparison.Ordinal)&&!result.Contains(text))result.Add(text);return true;},IntPtr.Zero);return string.Join(\"\\n\",result.ToArray()); }\n}\n\"@\n  Add-Type -AssemblyName UIAutomationClient\n  Add-Type -AssemblyName UIAutomationTypes\n  function Get-UnityCliWindowMessage([IntPtr]$handle, [string]$title) {\n    try {\n      $root=[System.Windows.Automation.AutomationElement]::FromHandle($handle)\n      if($null -eq $root){ throw 'UI Automation did not resolve the window handle.' }\n      $texts=New-Object 'System.Collections.Generic.List[string]'\n      $buttonTexts=@([UnityCliWindowProbeNative]::Buttons($handle) | ForEach-Object { ([string]$_.label).Replace('&','') })\n      foreach($element in $root.FindAll([System.Windows.Automation.TreeScope]::Descendants,[System.Windows.Automation.Condition]::TrueCondition)) {\n        $current=$element.Current\n        if($current.ControlType.ProgrammaticName -eq 'ControlType.Button'){ continue }\n        $ancestor=$element; $insideButton=$false\n        while($null -ne ($ancestor=[System.Windows.Automation.TreeWalker]::RawViewWalker.GetParent($ancestor))) {\n          if($ancestor.Current.ControlType.ProgrammaticName -eq 'ControlType.Button'){ $insideButton=$true; break }\n        }\n        if($insideButton){ continue }\n        $candidates=@($current.Name)\n        try { $pattern=$element.GetCurrentPattern([System.Windows.Automation.TextPattern]::Pattern); if($null -ne $pattern){ $candidates += $pattern.DocumentRange.GetText(-1) } } catch {}\n        foreach($candidate in $candidates) {\n          $text=([string]$candidate).Trim()\n          if(-not [string]::IsNullOrEmpty($text) -and $text -ne 'Static' -and $text -ne $title -and -not ($buttonTexts -contains $text) -and -not $texts.Contains($text)){ [void]$texts.Add($text) }\n        }\n      }\n      return [string]::Join([Environment]::NewLine,$texts.ToArray())\n    } catch { return [UnityCliWindowProbeNative]::Message($handle,$title) }\n  }\n  $targetProcessId=[uint32]__UNITY_CLI_PROCESS_ID__; $items=@()\n  foreach($rawHandle in [UnityCliWindowProbeNative]::TopLevelWindows($targetProcessId)) { try {\n    $handle=[IntPtr]([int64]$rawHandle); $ownerValue=[int64][UnityCliWindowProbeNative]::Owner($handle); $owner=[IntPtr]$ownerValue; $className=[UnityCliWindowProbeNative]::ClassName($handle); $title=[UnityCliWindowProbeNative]::WindowText($handle); $visible=[UnityCliWindowProbeNative]::IsWindowVisible($handle); $enabled=[UnityCliWindowProbeNative]::IsWindowEnabled($handle); $ownerDisabled=$ownerValue -ne 0 -and -not [UnityCliWindowProbeNative]::IsWindowEnabled($owner)\n    $buttonLabels=@([UnityCliWindowProbeNative]::Buttons($handle) | ForEach-Object { $_.label }); $normalizedButtonLabels=@($buttonLabels | ForEach-Object { ([string]$_).Replace('&','') }); $unityProgress=($className -eq 'UnityContainerWndClass' -and $title -match '(busy for [0-9]+s)...$') -or ($normalizedButtonLabels -contains 'Cancel' -and $normalizedButtonLabels -contains 'Skip Transcoding'); $modal=$visible -and -not $unityProgress -and (($ownerValue -ne 0 -and $ownerDisabled) -or $className -eq '#32770')\n    $buttons=[object[]]@(); if($modal){ $buttons=[object[]]@([UnityCliWindowProbeNative]::Buttons($handle)) }\n    $items += @{hwnd='0x'+([int64]$rawHandle).ToString('X');ownerHwnd=if($ownerValue -eq 0){$null}else{'0x'+$ownerValue.ToString('X')};className=$className;title=$title;message=if($modal){Get-UnityCliWindowMessage $handle $title}else{''};visible=[bool]$visible;enabled=[bool]$enabled;buttons=$buttons;modal=[bool]$modal}\n  } catch {} }\n  ConvertTo-Json -InputObject @($items) -Compress -Depth 5\n} catch { exit 1 }";

package/dist/windows-editor-state.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { platform as currentPlatform } from "node:os";
+/** 仅枚举指定 Unity PID 的顶层与 owned Windows，不发送任何窗口消息。 */
+export async function probeWindowsEditorState(processId, options = {}) {
+    if ((options.platform ?? currentPlatform()) !== "win32" || !Number.isInteger(processId) || processId < 1)
+        return { supported: false, outcome: "unsupported", windows: [] };
+    const execution = await runPowerShell(buildWindowsEditorStateScript(processId), Math.max(1, options.timeoutMs ?? 300));
+    if (execution.reason)
+        return { supported: true, outcome: "unproven", windows: [], reason: execution.reason };
+    return parseWindowsEditorStateOutput(execution.stdout);
+}
+export function buildWindowsEditorStateScript(processId) { return WINDOWS_EDITOR_STATE_PS_SCRIPT_TEMPLATE.replace("__UNITY_CLI_PROCESS_ID__", String(processId)); }
+export function parseWindowsEditorStateOutput(output) {
+    const line = output.split(/\r?\n/).map((value) => value.trim()).filter(Boolean).at(-1);
+    if (!line)
+        return { supported: true, outcome: "unproven", windows: [], reason: "parse" };
+    try {
+        const values = Array.isArray(JSON.parse(line)) ? JSON.parse(line) : [JSON.parse(line)];
+        const windows = values.flatMap(normalizeWindow);
+        if (windows.length !== values.length)
+            return { supported: true, outcome: "unproven", windows: [], reason: "parse" };
+        return { supported: true, outcome: windows.some((window) => window.modal) ? "observed-blocked" : "observed-empty", windows };
+    }
+    catch {
+        return { supported: true, outcome: "unproven", windows: [], reason: "parse" };
+    }
+}
+function normalizeWindow(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const raw = value;
+    if (typeof raw.hwnd !== "string" || typeof raw.className !== "string" || typeof raw.title !== "string" || typeof raw.message !== "string" || typeof raw.visible !== "boolean" || typeof raw.enabled !== "boolean" || typeof raw.modal !== "boolean" || !Array.isArray(raw.buttons))
+        return [];
+    const buttons = raw.buttons.flatMap((button) => button && typeof button === "object" && !Array.isArray(button) && typeof button.label === "string" && typeof button.hwnd === "string" && typeof button.enabled === "boolean" ? [{ label: button.label, hwnd: button.hwnd, enabled: button.enabled }] : []);
+    if (buttons.length !== raw.buttons.length)
+        return [];
+    return [{ hwnd: raw.hwnd, ownerHwnd: typeof raw.ownerHwnd === "string" ? raw.ownerHwnd : null, className: raw.className, title: raw.title, message: raw.message, visible: raw.visible, enabled: raw.enabled, buttons, modal: raw.modal }];
+}
+export const WINDOWS_EDITOR_STATE_PS_SCRIPT_TEMPLATE = `
+$ErrorActionPreference = 'Stop'
+try {
+  Add-Type -TypeDefinition @"
+using System; using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text;
+public static class UnityCliWindowProbeNative {
+  private delegate bool EnumWindowProc(IntPtr hwnd, IntPtr state);
+  [DllImport("user32.dll")] private static extern bool EnumWindows(EnumWindowProc callback, IntPtr state);
+  [DllImport("user32.dll")] private static extern bool EnumChildWindows(IntPtr parent, EnumWindowProc callback, IntPtr state);
+  [DllImport("user32.dll")] private static extern uint GetWindowThreadProcessId(IntPtr hwnd, out uint processId);
+  [DllImport("user32.dll")] private static extern IntPtr GetWindow(IntPtr hwnd, uint command);
+  [DllImport("user32.dll")] [return: MarshalAs(UnmanagedType.Bool)] public static extern bool IsWindowVisible(IntPtr hwnd);
+  [DllImport("user32.dll")] [return: MarshalAs(UnmanagedType.Bool)] public static extern bool IsWindowEnabled(IntPtr hwnd);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetClassNameW(IntPtr hwnd, StringBuilder value, int count);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetWindowTextW(IntPtr hwnd, StringBuilder value, int count);
+  public static long[] TopLevelWindows(uint pid) { var handles=new List<long>(); EnumWindows((h,s)=>{uint p;GetWindowThreadProcessId(h,out p);if(p==pid)handles.Add(h.ToInt64());return true;},IntPtr.Zero); return handles.ToArray(); }
+  public static long Owner(IntPtr hwnd) { return GetWindow(hwnd,4).ToInt64(); }
+  public static string ClassName(IntPtr hwnd) { var value=new StringBuilder(256);GetClassNameW(hwnd,value,value.Capacity);return value.ToString(); }
+  public static string WindowText(IntPtr hwnd) { var value=new StringBuilder(2048);GetWindowTextW(hwnd,value,value.Capacity);return value.ToString(); }
+  public static object[] Buttons(IntPtr parent) { var result=new List<object>();EnumChildWindows(parent,(h,s)=>{if(string.Equals(ClassName(h),"Button",StringComparison.Ordinal)){var label=WindowText(h);if(!string.IsNullOrEmpty(label))result.Add(new {label=label,hwnd="0x"+h.ToInt64().ToString("X"),enabled=IsWindowEnabled(h)});}return true;},IntPtr.Zero);return result.ToArray(); }
+  public static string Message(IntPtr parent,string title) { var result=new List<string>();EnumChildWindows(parent,(h,s)=>{var className=ClassName(h);if(string.Equals(className,"Button",StringComparison.Ordinal)||string.Equals(className,"Static",StringComparison.Ordinal))return true;var text=WindowText(h).Trim();if(!string.IsNullOrEmpty(text)&&!string.Equals(text,"Static",StringComparison.Ordinal)&&!string.Equals(text,title,StringComparison.Ordinal)&&!result.Contains(text))result.Add(text);return true;},IntPtr.Zero);return string.Join("\\n",result.ToArray()); }
+}
+"@
+  Add-Type -AssemblyName UIAutomationClient
+  Add-Type -AssemblyName UIAutomationTypes
+  function Get-UnityCliWindowMessage([IntPtr]$handle, [string]$title) {
+    try {
+      $root=[System.Windows.Automation.AutomationElement]::FromHandle($handle)
+      if($null -eq $root){ throw 'UI Automation did not resolve the window handle.' }
+      $texts=New-Object 'System.Collections.Generic.List[string]'
+      $buttonTexts=@([UnityCliWindowProbeNative]::Buttons($handle) | ForEach-Object { ([string]$_.label).Replace('&','') })
+      foreach($element in $root.FindAll([System.Windows.Automation.TreeScope]::Descendants,[System.Windows.Automation.Condition]::TrueCondition)) {
+        $current=$element.Current
+        if($current.ControlType.ProgrammaticName -eq 'ControlType.Button'){ continue }
+        $ancestor=$element; $insideButton=$false
+        while($null -ne ($ancestor=[System.Windows.Automation.TreeWalker]::RawViewWalker.GetParent($ancestor))) {
+          if($ancestor.Current.ControlType.ProgrammaticName -eq 'ControlType.Button'){ $insideButton=$true; break }
+        }
+        if($insideButton){ continue }
+        $candidates=@($current.Name)
+        try { $pattern=$element.GetCurrentPattern([System.Windows.Automation.TextPattern]::Pattern); if($null -ne $pattern){ $candidates += $pattern.DocumentRange.GetText(-1) } } catch {}
+        foreach($candidate in $candidates) {
+          $text=([string]$candidate).Trim()
+          if(-not [string]::IsNullOrEmpty($text) -and $text -ne 'Static' -and $text -ne $title -and -not ($buttonTexts -contains $text) -and -not $texts.Contains($text)){ [void]$texts.Add($text) }
+        }
+      }
+      return [string]::Join([Environment]::NewLine,$texts.ToArray())
+    } catch { return [UnityCliWindowProbeNative]::Message($handle,$title) }
+  }
+  $targetProcessId=[uint32]__UNITY_CLI_PROCESS_ID__; $items=@()
+  foreach($rawHandle in [UnityCliWindowProbeNative]::TopLevelWindows($targetProcessId)) { try {
+    $handle=[IntPtr]([int64]$rawHandle); $ownerValue=[int64][UnityCliWindowProbeNative]::Owner($handle); $owner=[IntPtr]$ownerValue; $className=[UnityCliWindowProbeNative]::ClassName($handle); $title=[UnityCliWindowProbeNative]::WindowText($handle); $visible=[UnityCliWindowProbeNative]::IsWindowVisible($handle); $enabled=[UnityCliWindowProbeNative]::IsWindowEnabled($handle); $ownerDisabled=$ownerValue -ne 0 -and -not [UnityCliWindowProbeNative]::IsWindowEnabled($owner)
+    $buttonLabels=@([UnityCliWindowProbeNative]::Buttons($handle) | ForEach-Object { $_.label }); $normalizedButtonLabels=@($buttonLabels | ForEach-Object { ([string]$_).Replace('&','') }); $unityProgress=($className -eq 'UnityContainerWndClass' -and $title -match '\(busy for [0-9]+s\)\.\.\.$') -or ($normalizedButtonLabels -contains 'Cancel' -and $normalizedButtonLabels -contains 'Skip Transcoding'); $modal=$visible -and -not $unityProgress -and (($ownerValue -ne 0 -and $ownerDisabled) -or $className -eq '#32770')
+    $buttons=[object[]]@(); if($modal){ $buttons=[object[]]@([UnityCliWindowProbeNative]::Buttons($handle)) }
+    $items += @{hwnd='0x'+([int64]$rawHandle).ToString('X');ownerHwnd=if($ownerValue -eq 0){$null}else{'0x'+$ownerValue.ToString('X')};className=$className;title=$title;message=if($modal){Get-UnityCliWindowMessage $handle $title}else{''};visible=[bool]$visible;enabled=[bool]$enabled;buttons=$buttons;modal=[bool]$modal}
+  } catch {} }
+  ConvertTo-Json -InputObject @($items) -Compress -Depth 5
+} catch { exit 1 }`;
+function runPowerShell(script, timeout) { return new Promise((resolve) => execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeout, windowsHide: true }, (error, stdout) => resolve(error ? { stdout, reason: error.killed ? "timeout" : "exit" } : { stdout }))); }
+//# sourceMappingURL=windows-editor-state.js.map

package/dist/windows-editor-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-editor-state.js","sourceRoot":"","sources":["../src/windows-editor-state.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,43 @@
+# 文档索引
+
+本目录只保留当前 `unitycli` 的使用、扩展与诊断文档。
+
+## 快速开始
+
+| 文档 | 内容 |
+|------|------|
+| [Target 与 Instance](target-and-instance.md) | 运行中 Unity Editor 实例发现、目标选择、别名管理 |
+| [工具发现](tool-discovery.md) | `tools group` → `tools group list` → `tools describe` 的自发现流程 |
+| [工具执行](tool-execution.md) | `tools run`的结构化JSON执行、输入与验证方式 |
+| [Command执行](command-execution.md) | 同一Tool catalog的schema参数调用、名称选择与argv绑定 |
+| [可用性差异](availability-differences.md) | 为什么不同 Editor、Package、Play Mode 状态下工具可用性不同 |
+
+## 安全与诊断
+
+| 文档 | 内容 |
+|------|------|
+| [安全边界](safety-boundaries.md) | 调用授权、风险元数据与正确性边界 |
+| [风险与副作用](risk-and-side-effects.md) | `destructiveHint`、`supportsDryRun`、`plannedEffects` 与可选预览 |
+| [错误码](error-codes.md) | 结构化错误、`nextActions` 与恢复建议 |
+
+## 扩展
+
+| 文档 | 内容 |
+|------|------|
+| [扩展包](extensions.md) | bundled optional extensions 的安装、卸载、诊断和依赖边界 |
+| [自定义 Tool](../skills/unitycli/references/custom-tools.md) | 项目侧 `IUnityCliTool<TReq,TRes>` 注册、发现与执行 |
+| [Skill 操作协议](../skills/unitycli/references/operation-protocol.md) | 实例选择、descriptor、envelope、分页、artifact、弹窗与 outcome unknown |
+| [Skill 问题反馈](../skills/unitycli/references/feedback.md) | `FeedbackMode`、受限字段、本地滚动 JSONL 与回复摘要 |
+
+## AI Agent 阅读顺序
+
+1. 先读 `skills/unitycli/SKILL.md` 获取最小入口规则。
+2. 需要命令细节时读`target-and-instance.md`、`tool-discovery.md`、`tool-execution.md`和`command-execution.md`。
+3. 涉及写操作或高风险操作时读 `safety-boundaries.md` 与 `risk-and-side-effects.md`。
+4. 需要项目扩展能力时读 `extensions.md`。
+
+## 相关目录
+
+- `schemas/`：公开 JSON Schema 契约。
+- `examples/`：Editor、runtime、自定义 Tool 示例。
+- `skills/unitycli/`：AI Agent 入口 Skill 与按需引文。

package/docs/availability-differences.md

@@ -0,0 +1,97 @@
+# 可用性差异（Availability Differences）
+
+## 核心原则
+
+能力目录和可用性都是per-instance。`tools`读取一个已连接Unity实例的完整catalog；省略name的`command`只是该catalog的command-name投影。不同项目、Package、Extension、项目注册和Editor状态会产生不同descriptor集合与`available`状态。
+
+完整显示不等于无条件执行。目录不按 source 或 Edit/Play 状态过滤，执行仍按 schema、Package、PlayMode、安全、deadline 和 completion contract fail closed。
+
+## 外部控制面排除
+
+catalog只包含必须由已打开Unity Editor或development Player提供的项目内自动化。auth、Unity Hub、Editor安装或打开、Cloud、License和proxy配置由系统或官方控制面工具负责；`unitycli`不会把这些操作包装成Tool、相似名称映射或额外顶层命令。
+
+## 实例状态
+
+| 状态 | Discovery 与执行 |
+|------|------------------|
+| `ready` | 返回当前实例完整Tool catalog；session/listener与近期主线程pulse均已证明 |
+| `transitioning` | supervisor在同一deadline内等待lifecycle与listener generation交接 |
+| `blocked` | 返回blocker error；`editor.state` / `editor.dialogs`提供独立只读恢复路径 |
+| `unresponsive` | transport存在但主线程不可响应；返回`E_UNITY_UNRESPONSIVE` |
+| `unverifiable` | ownership证据不完整；返回`E_INSTANCE_UNVERIFIABLE`，不得误报duplicate |
+| `offline` | 不返回capability catalog；返回`E_INSTANCE_NOT_RUNNING` |
+| `conflict` | 至少两个verified live claim；返回`E_INSTANCE_CONFLICT` |
+
+没有 selector 且 CWD 不在 Unity 项目中时返回 `E_INSTANCE_REQUIRED`。静态 snapshot 不作为公开 fallback。
+
+## Package 与 Extension
+
+依赖特定 Unity Package 的能力仍出现在实例目录中。descriptor 使用以下字段表达当前可执行性：
+
+```json
+{
+  "name": "probuilder.create-shape",
+  "source": "extension",
+  "requiresPackages": ["com.unity.probuilder"],
+  "available": false,
+  "unavailableReason": "E_EXTENSION_DEPENDENCY_MISSING: ..."
+}
+```
+
+`source` 只用于说明和审计，不影响 visibility、describe、execution 或公开路由。安装 Package/Extension 后重新运行原 discovery 命令。
+
+## 项目注册能力
+
+项目通过 `IUnityCliTool<TReq,TRes>` 注册的能力，与 package 内置和 Extension 能力使用相同入口：
+
+```powershell
+unitycli tools group
+unitycli tools group list <group>
+unitycli tools describe <tool>
+unitycli tools run <tool> --input '<json>'
+```
+
+不同实例可以注册不同名称和分组；不需要额外来源参数，也不存在来源专用能力入口。official attribute Tool固定使用`UnityPipeline_<原名>`和`UnityPipeline`group，可由`command <原名>`选择。
+
+## EditMode 与 PlayMode
+
+Editor 与 Runtime 能力在两种模式中都保持可发现。`available`、`unavailableReason`、`target`、`availabilityScope` 和 `playModeSupport` 表达当前状态：
+
+| 当前模式 | `target: editor` | `target: runtime` |
+|---------|------------------|-------------------|
+| EditMode | 通常可执行 | 显示但通常 `available:false`；执行返回 `E_RUNTIME_NOT_READY` |
+| PlayMode | 依据 `playModeSupport` 执行或拒绝 | 可执行；结果通常限于当前 PlayMode session |
+
+进入 PlayMode 的标准步骤：
+
+1. `unitycli tools run editor.play --input '{}'`
+2. `unitycli tools run editor.state --input '{}'`
+3. 重新 `tools describe <runtime-tool>` 或直接按 `nextActions` 调用
+
+Editor-only Tool 在 PlayMode 中同样保持可见，但执行继续返回准确错误。
+
+## Unity 版本差异
+
+Unity API版本门禁不从major版本猜测。Tool仍在当前实例catalog中，`available:false`与`unavailableReason`说明当前编译API surface。
+
+`screenshot.editor-element`只在Unity6000.7+可执行，因为它唯一使用该版本公开的UI Toolkit `VisualElement.CaptureToRenderTexture`。更早版本仍可discover/describe，但actual与framework dry-run都在render、artifact write和effect barrier之前返回`E_EDITOR_ELEMENT_CAPTURE_UNAVAILABLE`。
+
+`editor.autotick.set`会在当前Editor没有可调用的`EditorApplication.SignalTick`时返回`E_EDITOR_AUTOTICK_UNAVAILABLE`，不会注册替代update owner或持久化fallback。
+
+## Domain Reload
+
+Domain reload期间，Registry v3 lifecycle将实例归约为`transitioning`，listener generation随后交接；Health v3中该generation的首个Unity主线程pulse才允许归约为`ready`。系统不读取固定三分钟或其他deadline marker。session supervisor只在同一`editorSessionId`内续接完全相同的请求；首次mutation POST后若session改变，不向新session重投，并返回`E_EXECUTION_TIMEOUT`与outcome unknown。调用方先读取业务状态，再决定是否提交全新请求。
+
+## AI Agent 处理方式
+
+1. 显式传 `--instance <id|projectPath|alias>`，或从目标 Unity 项目 CWD 调用。
+2. 先 discovery，再 describe；不要从 source 或工具名推断参数。
+3. 对 `available:false` 读取 `unavailableReason`、`requiresPackages` 和 `nextActions`。
+4. Package、Extension、项目代码、domain reload 或 PlayMode 变化后重新 discovery。
+5. 即时状态使用 `tools run editor.state --input '{}'`。
+
+## 交叉引用
+
+- [Target 与 Instance](./target-and-instance.md)
+- [工具发现](./tool-discovery.md)
+- [错误码](./error-codes.md)

package/docs/command-execution.md

@@ -0,0 +1,89 @@
+# Command执行
+
+`command`是唯一Tool catalog的schema参数调用入口。它不复制descriptor、registry、dispatcher、security、completion或JSON envelope；同一Tool也可由`tools run <tool> --input <json>`调用。
+
+## 发现与选择
+
+省略name时读取选定实例的完整live catalog，并返回command-name投影：
+
+```powershell
+unitycli command --project-path C:\path\MyProject
+unitycli command --instance <id|projectPath|alias>
+```
+
+名称选择是exact且确定的：
+
+1. native Tool完整精确名优先。
+2. 没有native精确名时，`command <name>`可选择实际注册的`UnityPipeline_<name>` official attribute Tool。
+3. `command UnityPipeline_<name>`显式选择该attribute Tool。
+4. 不做snake_case、camelCase、dotted name、相似能力或语义映射；未注册名称返回`E_TOOL_NOT_FOUND_FOR_TARGET`。
+
+`[CliCommand("test")]`在`tools`目录中只显示为`UnityPipeline_test`，group固定为`UnityPipeline`。两个attribute方法使用同一原名，或native Tool占用`UnityPipeline_`前缀/`UnityPipeline` group，会使整个live registry fail closed。
+
+## Official Attribute Profile
+
+registry按完整类型名识别Unity官方`[CliCommand]`、`[CliArg]`和`IStructuredCommandInput`，core package不建立对`com.unity.pipeline`的编译依赖。method声明assembly属于exact Package ID `com.unity.pipeline`时，该provider已由native能力吸收并在注册前整体抑制；项目与其他Package中的attribute方法不受影响。过滤不使用命令名、namespace、assembly名称或attribute定义assembly。attributed method必须是static、非泛型，并且只接受以下返回形态：
+
+- 同步`void`或同步结果值。
+- `Task`或`Task<T>`；`async void`和其他自定义awaitable使整个registry fail closed。
+- `RuntimeOnly=true`固定投影为runtime-only；其余attribute Tool投影为editor target。
+
+每个method参数按`[CliArg]`名称、描述、`Required`和CLR默认值生成schema。schema default和生成example表示合法默认行为与调用形状，不代表调用方当前任务意图；任务明确指定业务值时，第一次执行必须使用任务值，不能先以default/example做连通性或probe调用。实现`IStructuredCommandInput`的具体DTO按public writable member递归生成封闭object schema，未知字段、缺少required member、递归类型和重复投影名在effect前失败。scalar、enum、date-time、UUID、dictionary和array保持typed schema；`object`、Json.NET `JToken`族与其他无法静态派生的值显式使用`x-unityCliAnyJson`，不会猜测字符串格式或静默套用默认值。
+
+attribute Tool统一声明保守的`official-attribute` contract profile、`arbitrary-method-invocation` side effect、`execute-user-code` permission和`supportsDryRun:false`。调用在参数转换完成后只跨一次effect barrier；`Task`超时不声称取消底层method，只有可信method return才能形成成功terminal。
+
+## 业务参数
+
+command name确定后，CLI按该Tool当前`inputSchema.properties`逐字匹配字段并构造typed input：
+
+```powershell
+# named value
+unitycli command UnityPipeline_test --mode EditMode --category Editor
+
+# attached value与boolean裸开关
+unitycli command UnityPipeline_project_reload_data --path Assets/GameData.json --force --timeout_ms=30000
+
+# positional按live schema的声明顺序绑定
+unitycli command eval "return 2 + 2;"
+```
+
+支持：
+
+- `--field value`
+- `--field=value`
+- boolean裸开关`--field`，等价于该业务字段为`true`
+- boolean显式`true`/`false`
+- 按`properties`声明顺序绑定的positional
+- string、boolean、integer、number、object、array、null和`x-unityCliAnyJson`
+
+object、array和任意JSON值必须是有效JSON。字段大小写和下划线原样匹配；未知字段、缺值、重复字段、类型错误和positional溢出都在effect前失败。业务值本身以`--`开头时，使用attached形式或`--`结束option解析。
+
+## Command级控制项
+
+```powershell
+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。
+- `--timeout <seconds>`位于name前；`--timeout-ms <milliseconds>`使用本项目执行控制语义。
+- `--dry-run`、`--runtime`、`--artifact-dir`和`--instance`仍是执行/选择控制项，不进入Tool business input。
+- `--raw`只改变同一JSON envelope的排版。
+
+## 等价性
+
+以下两种调用在typed input相同的前提下选择同一实际Tool并返回同一业务结果：
+
+```powershell
+unitycli tools run UnityPipeline_test --input '{"mode":"EditMode"}'
+unitycli command test --mode EditMode
+```
+
+两种语法共享instance选择、availability、schema终检、risk metadata、dry-run、timeout、descriptor fingerprint、completion contract、Bridge执行和错误码。command语法兼容不承诺补齐当前catalog中不存在的官方命令，也不改变本项目JSON输出格式。
+
+## Pipeline与Bridge启动
+
+本package首次在项目中检测到`com.unity.pipeline`时，会把Pipeline Editor `AutoStart`持久设为false、停止其当前server并清理由该server启用的autotick。只有全部结果验证成功后才写入项目级一次性接管标记；此后reload、Editor重启、package更新以及用户手动重新开启Pipeline都不会再次覆盖或停服。
+
+本Bridge使用`Project Settings > UnityCLI > Bridge Auto Start`项目级开关，默认开启。该值只在下一次Domain Reload或Editor启动时读取：关闭不会现场中断已接受请求，生效后不启动listener也不写instance registry。该设置不控制development Player runtime server。