@alpsckr/unitycli 0.4.0

package/skills/unitycli/scripts/record-feedback.ps1

@@ -0,0 +1,210 @@
+[CmdletBinding()]
+# 保留 UTF-8 BOM，确保 Windows PowerShell 5.1 正确解析中文注释。
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet("failure", "ambiguity", "missing", "misleading", "workaround")]
+    [string]$Category,
+
+    [Parameter(Mandatory = $true)]
+    [ValidateLength(1, 512)]
+    [string]$Summary,
+
+    [ValidateLength(0, 512)]
+    [string]$Workaround = "",
+
+    [ValidatePattern('^$|^[A-Za-z0-9._-]{1,128}$')]
+    [string]$Capability = "",
+
+    [ValidatePattern('^$|^[A-Z][A-Z0-9_]{1,63}$')]
+    [string]$ErrorCode = "",
+
+    [ValidateSet("discovery", "describe", "execute", "verify", "install", "other")]
+    [string]$Phase = "other"
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$maxFileBytes = 64KB
+$archiveCount = 3
+$mutex = $null
+$mutexHeld = $false
+
+function Assert-SafeFeedbackText {
+    param(
+        [Parameter(Mandatory = $true)][string]$Name,
+        [AllowEmptyString()][string]$Value
+    )
+
+    # 反馈只接受单行摘要，并拒绝常见路径、网络地址和凭据形态。
+    if ($Name -eq "Summary" -and [string]::IsNullOrWhiteSpace($Value)) {
+        throw "Summary must contain non-whitespace text."
+    }
+    if ($Value -match '[\r\n]') {
+        throw "$Name must be a single line."
+    }
+    $containsNetworkAddress = $Value -match '(?i)\b(?:https?|wss?|file)://'
+    $containsEndpointLabel = $Value -match '(?i)\bendpoint\s*[:=]'
+    # 只拒绝明显 hostname：localhost 或已知公共/保留 TLD 结尾，避免误伤三段式工具名。
+    $containsHostName = $Value -match '(?i)\b(?:localhost|(?:[A-Za-z0-9-]+\.)+(?:com|org|net|edu|gov|mil|info|biz|io|dev|app|ai|co|me|tv|cc|gg|sh|xyz|top|tech|cloud|site|online|store|shop|club|live|news|media|world|email|blog|wiki|page|link|fun|run|one|pro|plus|space|host|cn|uk|us|jp|de|fr|ru|in|br|au|ca|it|es|nl|se|ch|kr|tw|hk|sg|example|test|invalid))\b'
+    $containsIpAddress = $Value -match '\b(?:\d{1,3}\.){3}\d{1,3}\b'
+    $containsHostPort = $Value -match '(?i)\b(?:localhost|(?:\d{1,3}\.){3}\d{1,3}|[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*):\d{2,5}\b'
+    $containsAbsolutePath = $Value -match '(?i)(?:[A-Z]:[\\/]|(?:^|\s)/(?:[^/\s]+/)*[^/\s]+)'
+    $containsUncPath = $Value -match '\\\\[^\\\s]+\\'
+    $containsRelativePath = $Value -match '(?i)(?:^|\s)(?:\.{1,2}[\\/]|[^\s<>:"|?*]+[\\/][^\s<>:"|?*]+)'
+    if ($containsNetworkAddress -or $containsEndpointLabel -or $containsHostName -or $containsIpAddress -or $containsHostPort -or $containsAbsolutePath -or $containsUncPath -or $containsRelativePath) {
+        throw "$Name must not contain a URL, endpoint, or path."
+    }
+    $containsCredentialLabel = $Value -match '(?i)\b(?:authorization|api[-_ ]?key|access[-_ ]?token|token|password|secret)(?:\s*[:=]\s*|\s+)[^\s]{4,}'
+    $containsBearer = $Value -match '(?i)\bBearer\s+[A-Za-z0-9._~+/=-]{8,}'
+    $containsJwt = $Value -match '\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b'
+    $containsTokenShape = $Value -match '(?i)\b(?:sk|ghp|xox[baprs])-[A-Za-z0-9_-]{10,}\b' -or $Value -match '\bAKIA[0-9A-Z]{16}\b'
+    $containsOpaqueSecret = $Value -match '\b[A-Fa-f0-9]{32,}\b'
+    if ($containsCredentialLabel -or $containsBearer -or $containsJwt -or $containsTokenShape -or $containsOpaqueSecret) {
+        throw "$Name must not contain credentials or secrets."
+    }
+}
+
+function Move-FeedbackArchive {
+    param(
+        [Parameter(Mandatory = $true)][string]$Source,
+        [Parameter(Mandatory = $true)][string]$Destination
+    )
+
+    # 目标 archive 固定覆盖，保证文件数量不会随调用次数增长。
+    if (Test-Path -LiteralPath $Destination) {
+        Remove-Item -LiteralPath $Destination -Force
+    }
+    if (Test-Path -LiteralPath $Source) {
+        Move-Item -LiteralPath $Source -Destination $Destination
+    }
+}
+
+function Assert-NoReparsePath {
+    param([Parameter(Mandatory = $true)][string]$Path)
+
+    # 逐段检查已存在组件；缺失尾段由调用方创建后再次检查。
+    $fullPath = [System.IO.Path]::GetFullPath($Path)
+    $pathRoot = [System.IO.Path]::GetPathRoot($fullPath)
+    $current = $pathRoot
+    $relativePath = $fullPath.Substring($pathRoot.Length)
+    foreach ($segment in $relativePath.Split([char[]]@('\', '/'), [System.StringSplitOptions]::RemoveEmptyEntries)) {
+        $current = Join-Path $current $segment
+        try {
+            $attributes = [System.IO.File]::GetAttributes($current)
+        } catch {
+            $cause = $_.Exception.InnerException
+            if ($_.Exception -is [System.IO.FileNotFoundException] -or
+                $_.Exception -is [System.IO.DirectoryNotFoundException] -or
+                $cause -is [System.IO.FileNotFoundException] -or
+                $cause -is [System.IO.DirectoryNotFoundException]) {
+                break
+            }
+            throw
+        }
+        if (($attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) {
+            throw "LOCALAPPDATA and feedback paths must not contain reparse points."
+        }
+    }
+}
+
+Assert-SafeFeedbackText -Name "Summary" -Value $Summary
+Assert-SafeFeedbackText -Name "Workaround" -Value $Workaround
+if ($Category -eq "workaround" -and [string]::IsNullOrWhiteSpace($Workaround)) {
+    throw "Workaround is required when Category is workaround."
+}
+if ([string]::IsNullOrWhiteSpace($env:LOCALAPPDATA)) {
+    throw "LOCALAPPDATA is required to store local unitycli feedback."
+}
+# UNC、映射盘和其他远端 provider 会绕过本机 mutex，因此仅接受固定本地盘。
+try {
+    $localAppDataRoot = [System.IO.Path]::GetFullPath($env:LOCALAPPDATA)
+    $driveRoot = [System.IO.Path]::GetPathRoot($localAppDataRoot)
+    if ($driveRoot -notmatch '^[A-Za-z]:\\$') {
+        throw "LOCALAPPDATA must use a local drive path."
+    }
+    $driveInfo = New-Object System.IO.DriveInfo($driveRoot)
+    if ($driveInfo.DriveType -ne [System.IO.DriveType]::Fixed) {
+        throw "LOCALAPPDATA must use a fixed local drive."
+    }
+} catch {
+    throw "LOCALAPPDATA must resolve to a fixed local drive."
+}
+
+$feedbackRoot = Join-Path $localAppDataRoot "UnityCli\feedback"
+$mainPath = Join-Path $feedbackRoot "feedback.jsonl"
+$recordId = "fb_" + [Guid]::NewGuid().ToString("N")
+$capabilityValue = $null
+$errorCodeValue = $null
+$workaroundValue = $null
+if (-not [string]::IsNullOrWhiteSpace($Capability)) { $capabilityValue = $Capability }
+if (-not [string]::IsNullOrWhiteSpace($ErrorCode)) { $errorCodeValue = $ErrorCode }
+if (-not [string]::IsNullOrWhiteSpace($Workaround)) { $workaroundValue = $Workaround }
+$record = [ordered]@{
+    schemaVersion = 1
+    recordId = $recordId
+    createdAtUtc = [DateTime]::UtcNow.ToString("o")
+    category = $Category
+    phase = $Phase
+    capability = $capabilityValue
+    errorCode = $errorCodeValue
+    summary = $Summary
+    workaround = $workaroundValue
+    resolved = -not [string]::IsNullOrWhiteSpace($Workaround)
+}
+$jsonLine = $record | ConvertTo-Json -Compress -Depth 4
+$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+$lineBytes = $utf8NoBom.GetByteCount($jsonLine + [Environment]::NewLine)
+if ($lineBytes -gt $maxFileBytes) {
+    throw "Feedback record exceeds the per-file byte limit."
+}
+
+try {
+    # named mutex 只保护本机同一用户反馈目录；进程退出后由 Windows 自动释放。
+    $mutex = New-Object System.Threading.Mutex($false, "Local\UnityCliFeedback_v1")
+    try {
+        $mutexHeld = $mutex.WaitOne(10000)
+    } catch [System.Threading.AbandonedMutexException] {
+        $mutexHeld = $true
+    }
+    if (-not $mutexHeld) {
+        throw "Timed out waiting for the unitycli feedback writer."
+    }
+
+    Assert-NoReparsePath -Path $feedbackRoot
+    [System.IO.Directory]::CreateDirectory($feedbackRoot) | Out-Null
+    Assert-NoReparsePath -Path $feedbackRoot
+    $candidatePaths = @($mainPath)
+    $candidatePaths += @(1..$archiveCount | ForEach-Object { Join-Path $feedbackRoot ("feedback.{0}.jsonl" -f $_) })
+    foreach ($candidatePath in $candidatePaths) {
+        Assert-NoReparsePath -Path $candidatePath
+    }
+    $rotated = $false
+    if (Test-Path -LiteralPath $mainPath) {
+        $currentBytes = (Get-Item -LiteralPath $mainPath).Length
+        if ($currentBytes + $lineBytes -gt $maxFileBytes) {
+            for ($index = $archiveCount; $index -ge 2; $index--) {
+                Move-FeedbackArchive `
+                    -Source (Join-Path $feedbackRoot ("feedback.{0}.jsonl" -f ($index - 1))) `
+                    -Destination (Join-Path $feedbackRoot ("feedback.{0}.jsonl" -f $index))
+            }
+            Move-FeedbackArchive -Source $mainPath -Destination (Join-Path $feedbackRoot "feedback.1.jsonl")
+            $rotated = $true
+        }
+    }
+
+    [System.IO.File]::AppendAllText($mainPath, $jsonLine + [Environment]::NewLine, $utf8NoBom)
+    [ordered]@{
+        ok = $true
+        recordId = $recordId
+        path = $mainPath
+        rotated = $rotated
+    } | ConvertTo-Json -Compress
+} finally {
+    if ($mutexHeld -and $null -ne $mutex) {
+        try { $mutex.ReleaseMutex() } catch { }
+    }
+    if ($null -ne $mutex) {
+        $mutex.Dispose()
+    }
+}

package/skills/unitycli/security/network_policy.json

@@ -0,0 +1,18 @@
+{
+  "schema_version": "1.0",
+  "default_policy": {
+    "decision": "deny",
+    "reason": "The runtime Skill and feedback recorder do not require network access."
+  },
+  "scripts": {
+    "scripts/record-feedback.ps1": {
+      "decision": "deny",
+      "allowed_hosts": [],
+      "observed_network_apis": [],
+      "evidence": [
+        "tests/unity-cli-skill-feedback.test.ts static network API scan",
+        "DIR-002 runtime-contract-scan.json"
+      ]
+    }
+  }
+}

package/skills/unitycli/security/permission_policy.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "1.0",
+  "reviewed_at": "2026-08-05",
+  "capabilities": {
+    "file_write": {
+      "decision": "approved",
+      "reviewer": "project owner",
+      "reason": "The owner explicitly selected bounded local rolling JSONL as the feedback persistence mechanism.",
+      "scope": "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback.jsonl plus feedback.1.jsonl through feedback.3.jsonl; LOCALAPPDATA must resolve to a fixed local drive and contain no existing reparse path component",
+      "expires_at": "2027-08-05",
+      "evidence": [
+        "Owner decision D008",
+        "tests/unity-cli-skill-feedback.test.ts"
+      ],
+      "target_enforcement": {
+        "openai": "FeedbackMode and runtime recorder contract",
+        "claude": "FeedbackMode and runtime recorder contract",
+        "generic": "FeedbackMode and runtime recorder contract",
+        "vscode": "FeedbackMode and runtime recorder contract"
+      }
+    },
+    "subprocess": {
+      "decision": "approved",
+      "reviewer": "project owner",
+      "reason": "The installed Skill invokes only the bundled PowerShell feedback recorder when feedback is enabled and friction occurred.",
+      "scope": "powershell.exe executing scripts/record-feedback.ps1",
+      "expires_at": "2027-08-05",
+      "evidence": [
+        "Owner decision D008",
+        "skills/unitycli/references/feedback.md"
+      ],
+      "target_enforcement": {
+        "openai": "Bundled runtime script path",
+        "claude": "Bundled runtime script path",
+        "generic": "Bundled runtime script path",
+        "vscode": "Bundled runtime script path"
+      }
+    }
+  }
+}

package/unitypkg/Editor/Bridge/BridgeCommandContext.cs

@@ -0,0 +1,64 @@
+#if UNITY_EDITOR
+using System;
+using System.CodeDom.Compiler;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Net;
+using System.Reflection;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.CSharp;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.Rendering;
+using UnityEngine.SceneManagement;
+using UnityEngine.UIElements;
+using UiButton = UnityEngine.UI.Button;
+using UiCanvasScaler = UnityEngine.UI.CanvasScaler;
+using UiGraphicRaycaster = UnityEngine.UI.GraphicRaycaster;
+using UiImage = UnityEngine.UI.Image;
+using UiText = UnityEngine.UI.Text;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        private sealed class TargetResolution
+        {
+            public readonly GameObject Target;
+            public readonly List<GameObject> Matches;
+
+            private TargetResolution(List<GameObject> matches)
+            {
+                Matches = matches;
+                Target = matches.Count == 1 ? matches[0] : null;
+            }
+
+            public bool Ambiguous
+            {
+                get { return Matches.Count > 1; }
+            }
+
+            public static TargetResolution Single(GameObject target)
+            {
+                var matches = new List<GameObject>();
+                if (target != null)
+                {
+                    matches.Add(target);
+                }
+                return new TargetResolution(matches);
+            }
+
+            public static TargetResolution FromMatches(List<GameObject> matches)
+            {
+                return new TargetResolution(matches);
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Bridge/BridgeCommandException.cs

@@ -0,0 +1,39 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>
+        /// 供 core 与独立 Extension assembly 统一返回结构化 Bridge 错误。
+        /// </summary>
+        public sealed class BridgeCommandException : Exception
+        {
+            public BridgeCommandException(string code, string message, string nextAction = null, bool transient = false, int retryAfterMs = 0)
+                : this(code, message, null, string.IsNullOrEmpty(nextAction) ? Array.Empty<string>() : new[] { nextAction }, transient, retryAfterMs)
+            {
+            }
+
+            public BridgeCommandException(string code, string message, object details, IEnumerable<string> nextActions, bool transient = false, int retryAfterMs = 0)
+                : base(message)
+            {
+                if (string.IsNullOrWhiteSpace(code)) throw new ArgumentException("Bridge error code is required.", "code");
+                Code = code;
+                Details = details;
+                NextActions = (nextActions ?? Array.Empty<string>()).Where(action => !string.IsNullOrWhiteSpace(action)).ToArray();
+                Transient = transient;
+                RetryAfterMs = retryAfterMs;
+            }
+
+            public string Code { get; private set; }
+            public object Details { get; private set; }
+            public IReadOnlyList<string> NextActions { get; private set; }
+            public bool Transient { get; private set; }
+            public int RetryAfterMs { get; private set; }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Bridge/BridgeCommandRegistry.cs

@@ -0,0 +1,172 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        internal sealed class BridgeCommandRegistry
+        {
+            private readonly Dictionary<string, BridgeCommandDefinition> commands = new Dictionary<string, BridgeCommandDefinition>(StringComparer.Ordinal);
+
+            public void Register<TInput>(
+                string command,
+                string domain,
+                bool destructive,
+                int timeoutMs,
+                Func<TInput, CancellationToken, ValueTask<object>> handler)
+            {
+                if (string.IsNullOrWhiteSpace(command)) throw new ArgumentException("Bridge command registration requires a command name.", "command");
+                if (handler == null) throw new ArgumentNullException("handler");
+                if (commands.ContainsKey(command)) throw new InvalidOperationException("Duplicate bridge command registration: " + command);
+                commands.Add(command, new BridgeCommandDefinition(
+                    command,
+                    domain,
+                    destructive,
+                    timeoutMs,
+                    typeof(TInput),
+                    async (input, cancellationToken) => await handler((TInput)input, cancellationToken)));
+            }
+
+            public async ValueTask<object> ExecuteAsync(UnityCli.Protocol.BridgeRequest request, CancellationToken cancellationToken)
+            {
+                BridgeCommandDefinition definition;
+                if (request == null || !commands.TryGetValue(request.Command, out definition))
+                    throw new BridgeCommandException("E_BRIDGE_COMMAND_UNSUPPORTED", "Unsupported bridge command: " + (request == null ? string.Empty : request.Command), "Upgrade the UnityCLI Bridge package or use a registered CLI command.");
+                cancellationToken.ThrowIfCancellationRequested();
+                object input;
+                if (definition.InputType == typeof(UnityCli.Protocol.BridgeRequest))
+                {
+                    input = request;
+                }
+                else
+                {
+                    var inputJson = UnityCliSerializer.Serialize(request.Input ?? new Dictionary<string, object>());
+                    var schemaError = ValidateTypedInput(definition.InputType, inputJson);
+                    if (schemaError != null) throw SchemaValidationException(schemaError);
+                    input = UnityCliSerializer.Deserialize(inputJson, definition.InputType);
+                }
+                return await definition.Handler(input, cancellationToken);
+            }
+
+            public bool IsMutating(string command)
+            {
+                BridgeCommandDefinition definition;
+                return command != null && commands.TryGetValue(command, out definition) && definition.Destructive;
+            }
+        }
+
+        private sealed class BridgeCommandDefinition
+        {
+            public BridgeCommandDefinition(string command, string domain, bool destructive, int timeoutMs, Type inputType, Func<object, CancellationToken, ValueTask<object>> handler)
+            {
+                Command = command;
+                Domain = domain;
+                Destructive = destructive;
+                TimeoutMs = timeoutMs;
+                InputType = inputType;
+                Handler = handler;
+            }
+
+            public string Command { get; private set; }
+            public string Domain { get; private set; }
+            public bool Destructive { get; private set; }
+            public int TimeoutMs { get; private set; }
+            public Type InputType { get; private set; }
+            public Func<object, CancellationToken, ValueTask<object>> Handler { get; private set; }
+        }
+
+        private static BridgeCommandRegistry CreateCommandRegistry()
+        {
+            var registry = new BridgeCommandRegistry();
+            RegisterInstalledExtensionCommands(registry);
+            RegisterCodeExecCommand(registry);
+            RegisterEditorStateSnapshotCommand(registry);
+            UnityCliCompileCoordinator.Register(registry);
+            UnityCliLiveBuildCoordinator.Register(registry);
+            UnityCliLiveRefreshCoordinator.Register(registry);
+            UnityCliAssetRefreshCoordinator.Register(registry);
+            UnityCliPackageEmbedCoordinator.Register(registry);
+            UnityCliPackageResolveCoordinator.Register(registry);
+            UnityCliTestRunCoordinator.Register(registry);
+            UnityCliNavMeshBakeCoordinator.Register(registry);
+            UnityCliOcclusionBakeCoordinator.Register(registry);
+            RegisterProjectToolCommands(registry);
+            RegisterRuntimeToolCommands(registry);
+            return registry;
+        }
+
+        private static void RegisterCommand(BridgeCommandRegistry registry, string command, string domain, bool destructive, Func<UnityCli.Protocol.BridgeRequest, object> handler)
+        {
+            registry.Register<UnityCli.Protocol.BridgeRequest>(
+                command,
+                domain,
+                destructive,
+                destructive ? 60000 : 30000,
+                (request, cancellationToken) =>
+                {
+                    cancellationToken.ThrowIfCancellationRequested();
+                    return new ValueTask<object>(NormalizeCommandResult(handler(request)));
+                });
+        }
+
+        private static object NormalizeCommandResult(object result)
+        {
+            var serialized = result as string;
+            if (serialized == null) return result;
+            var envelope = UnityCliSerializer.Parse(serialized) as IDictionary<string, object>;
+            object okValue;
+            if (envelope == null || !envelope.TryGetValue("ok", out okValue) || !(okValue is bool)) return UnityCliSerializer.Parse(serialized);
+            if ((bool)okValue)
+            {
+                object data;
+                return envelope.TryGetValue("data", out data) ? data : null;
+            }
+            object errorValue;
+            var error = envelope.TryGetValue("error", out errorValue) ? errorValue as IDictionary<string, object> : null;
+            if (error == null) throw new BridgeCommandException("E_BRIDGE_COMMAND_FAILED", "Bridge command returned an invalid error envelope.");
+            object code;
+            object message;
+            object details;
+            object actions;
+            error.TryGetValue("code", out code);
+            error.TryGetValue("message", out message);
+            error.TryGetValue("details", out details);
+            error.TryGetValue("nextActions", out actions);
+            throw new BridgeCommandException(
+                Convert.ToString(code),
+                Convert.ToString(message),
+                details,
+                StringValues(actions));
+        }
+
+        private static IEnumerable<string> StringValues(object value)
+        {
+            var items = value as System.Collections.IEnumerable;
+            if (items == null) return Array.Empty<string>();
+            var result = new List<string>();
+            foreach (var item in items)
+            {
+                var text = Convert.ToString(item);
+                if (!string.IsNullOrWhiteSpace(text)) result.Add(text);
+            }
+            return result;
+        }
+
+        private static void RegisterInstalledExtensionCommands(BridgeCommandRegistry registry)
+        {
+            var methodNames = Array.Empty<string>();
+            foreach (var methodName in methodNames)
+            {
+                var method = typeof(UnityCliBridge).GetMethod(methodName, BindingFlags.Static | BindingFlags.NonPublic);
+                if (method == null) throw new InvalidOperationException("Installed extension bridge registration method is missing: " + methodName);
+                method.Invoke(null, new object[] { registry });
+            }
+        }
+    }
+}
+#endif