@alpsckr/unitycli 0.4.0

package/skills/unitycli/evals/output/fixtures/feedback-scenario.json

@@ -0,0 +1,27 @@
+{
+  "scenario": "descriptor ambiguity resolved through extra discovery",
+  "feedbackMode": "on",
+  "frictionOccurred": true,
+  "category": "workaround",
+  "summary": "Descriptor target wording required an extra discovery step.",
+  "workaround": "Used Tool search and descriptor readback to select the capability.",
+  "capability": "sample.tool",
+  "errorCode": "E_SCHEMA_INVALID",
+  "phase": "describe",
+  "expected": {
+    "writeLocalJsonl": true,
+    "appendFeedbackSummary": true,
+    "normalTaskResultStillRequired": true
+  },
+  "forbiddenInputs": [
+    "raw prompt",
+    "complete CLI input",
+    "complete CLI output",
+    "source code",
+    "logs",
+    "paths",
+    "URLs",
+    "endpoints",
+    "secrets"
+  ]
+}

package/skills/unitycli/evals/output/schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "prompt", "baseline_output", "with_skill_output", "assertions"],
+  "properties": {
+    "id": {"type": "string", "minLength": 1},
+    "prompt": {"type": "string", "minLength": 1},
+    "input_files": {"type": "array", "items": {"type": "string"}},
+    "baseline_output": {"type": "string"},
+    "with_skill_output": {"type": "string"},
+    "assertions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "description"],
+        "properties": {
+          "id": {"type": "string"},
+          "description": {"type": "string"},
+          "required": {"type": "array", "items": {"type": "string"}},
+          "forbidden": {"type": "array", "items": {"type": "string"}},
+          "weight": {"type": "number", "minimum": 0},
+          "failure_type": {"type": "string"}
+        }
+      }
+    },
+    "human_review": {"type": "object"},
+    "execution": {"type": "object"},
+    "metadata": {"type": "object"}
+  }
+}

package/skills/unitycli/evals/semantic_config.json

@@ -0,0 +1,46 @@
+{
+  "optimizer_hints": {
+    "capability": "Discover and operate Unity through unitycli while keeping pure file work direct",
+    "inputs": ["Unity tasks", "opened Unity Editor", "Unity source and project files", "Unity explanations"],
+    "trigger_actions": ["any task involving Unity or Unity Editor"],
+    "exclusions": ["tasks that do not involve Unity"],
+    "artifacts": ["Unity scene", "GameObject", "Prefab", "Asset", "build", "test", "screenshot"]
+  },
+  "fallback_positive_concepts": ["unity_task"],
+  "positive_concepts": {
+    "unity_task": {
+      "weight": 1.0,
+      "phrases": [
+        "unity",
+        "unity editor",
+        "monobehaviour",
+        "gameobject",
+        "prefab",
+        "playmode",
+        "editmode",
+        "gameview",
+        "sceneview",
+        "cinemachine",
+        "probuilder",
+        "unity console",
+        "unity scene",
+        "unity c#",
+        "unity 项目",
+        "unity 场景",
+        "unity editor",
+        "游戏对象"
+      ]
+    }
+  },
+  "negative_concepts": {
+    "different_engine": {
+      "weight": 0.8,
+      "exclusive": true,
+      "phrases": [
+        "unreal engine",
+        "godot",
+        "blender file"
+      ]
+    }
+  }
+}

package/skills/unitycli/evals/trigger_cases.json

@@ -0,0 +1,39 @@
+{
+  "recommended_threshold": 0.5,
+  "negative_patterns": [],
+  "should_trigger": [
+    {"text": "Open the Unity scene and move the Main Camera to frame the player.", "family": "live_editor_action"},
+    {"text": "Check why this GameObject is missing its Rigidbody in the opened Editor.", "family": "live_editor_observation"},
+    {"text": "Run the Unity EditMode tests and report the result.", "family": "test"},
+    {"text": "Build the Unity project for Windows and inspect the artifact.", "family": "build"},
+    {"text": "Take a screenshot of the current Unity GameView.", "family": "screenshot"},
+    {"text": "Install the ProBuilder extension in this Unity project.", "family": "extension"},
+    {"text": "Create a prefab from the selected GameObject.", "family": "prefab"},
+    {"text": "Read the current Unity Console errors.", "family": "console"},
+    {"text": "Explain how MonoBehaviour Awake and Start differ.", "family": "unity_explanation"},
+    {"text": "Review this Unity C# component and fix the null reference.", "family": "unity_source"},
+    {"text": "Only edit this Unity manifest JSON; no Editor state is needed.", "family": "unity_text"},
+    {"text": "Find the Cinemachine virtual camera and inspect its lens settings.", "family": "package_capability"},
+    {"text": "这个 Unity 场景里的灯光为什么没有生效？", "family": "cn_live_observation"},
+    {"text": "帮我修改 Unity 的 PlayerController.cs，不需要打开 Editor。", "family": "cn_unity_source"},
+    {"text": "检查 Prefab、Asset 导入和当前 PlayMode 状态。", "family": "cn_editor_state"},
+    {"text": "用 Unity Editor 运行一次构建并验证输出。", "family": "cn_build"}
+  ],
+  "should_not_trigger": [
+    {"text": "Fix the React state update in this web dashboard.", "family": "web"},
+    {"text": "Explain dependency injection in a plain .NET console app.", "family": "dotnet"},
+    {"text": "Open this Blender file and adjust the mesh normals.", "family": "other_engine"},
+    {"text": "Create an Unreal Engine Blueprint for a door.", "family": "other_engine"},
+    {"text": "Debug this Godot GDScript signal.", "family": "other_engine"},
+    {"text": "Summarize this Jira ticket.", "family": "project_management"},
+    {"text": "Update the Kubernetes deployment manifest.", "family": "infrastructure"},
+    {"text": "Write a SQL query for monthly revenue.", "family": "data"},
+    {"text": "修复这个 Vue 页面里的表单校验。", "family": "cn_web"},
+    {"text": "解释普通 C# 控制台程序的 async await。", "family": "cn_dotnet"}
+  ],
+  "near_neighbor": [
+    {"text": "Compare several 3D game engines without choosing one.", "family": "game_engine_general"},
+    {"text": "Review a generic C# math library used by several applications.", "family": "generic_csharp"},
+    {"text": "Design gameplay rules on paper without using any engine.", "family": "game_design"}
+  ]
+}

package/skills/unitycli/examples/feedback-event.input.json

@@ -0,0 +1,8 @@
+{
+  "Category": "workaround",
+  "Summary": "Descriptor target wording required an extra discovery step.",
+  "Workaround": "Used Tool search and descriptor readback to select the capability.",
+  "Capability": "sample.tool",
+  "ErrorCode": "E_SCHEMA_INVALID",
+  "Phase": "describe"
+}

package/skills/unitycli/examples/feedback-record.output.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "recordId": "fb_fixture0000000000000000000000000000",
+  "createdAtUtc": "2026-08-05T00:00:00.0000000Z",
+  "category": "workaround",
+  "phase": "describe",
+  "capability": "sample.tool",
+  "errorCode": "E_SCHEMA_INVALID",
+  "summary": "Descriptor target wording required an extra discovery step.",
+  "workaround": "Used Tool search and descriptor readback to select the capability.",
+  "resolved": true
+}

package/skills/unitycli/manifest.json

@@ -0,0 +1,112 @@
+{
+  "name": "unitycli",
+  "version": "0.4.0",
+  "owner": "alps-unity-cli maintainers",
+  "updated_at": "2026-08-13",
+  "status": "active",
+  "maturity_tier": "governed",
+  "lifecycle_stage": "governed",
+  "context_budget_tier": "production",
+  "review_cadence": "per-release",
+  "category": "unity-editor-automation",
+  "complexity_tier": "complex",
+  "target_platforms": [
+    "openai",
+    "claude",
+    "generic"
+  ],
+  "factory_components": [
+    "agents",
+    "references",
+    "scripts",
+    "evals",
+    "examples",
+    "security",
+    "reports"
+  ],
+  "runtime_projection": {
+    "include": [
+      "SKILL.md",
+      "references/**",
+      "scripts/**"
+    ],
+    "exclude": [
+      "agents/**",
+      "evals/**",
+      "examples/**",
+      "security/**",
+      "reports/**",
+      "manifest.json"
+    ],
+    "local_override": "SKILL.md:FeedbackMode",
+    "local_override_values": [
+      "off",
+      "on"
+    ]
+  },
+  "input_files": {
+    "required": [
+      "SKILL.md"
+    ],
+    "deferred": [
+      "references/operation-protocol.md",
+      "references/feedback.md",
+      "references/custom-tools.md"
+    ],
+    "file-backed fixture": [
+      "evals/output/fixtures/feedback-scenario.json",
+      "examples/feedback-event.input.json",
+      "examples/feedback-record.output.json"
+    ],
+    "runtime_observation": "Current unitycli JSON envelopes and connected-instance descriptors"
+  },
+  "output_contract": {
+    "normal_task_response": "No additional fixed format is imposed.",
+    "feedback_summary_condition": "FeedbackMode is on, a real friction event occurred, and the recorder returned ok:true.",
+    "feedback_summary_fields": [
+      "category",
+      "summary",
+      "workaround",
+      "recordId",
+      "localPath"
+    ],
+    "recorder_stdout_fields": [
+      "ok",
+      "recordId",
+      "path",
+      "rotated"
+    ],
+    "no_friction_behavior": "No feedback record and no feedback summary."
+  },
+  "rollback_boundary": {
+    "skill_install": "The installer retains one fixed previous projection until the new runtime bundle passes filesystem readback.",
+    "feedback_mode": "Bundle updates preserve the installed legal FeedbackMode value.",
+    "feedback_records": "Append-only user-local records are not automatically rolled back; retention is bounded by one main file and three archives.",
+    "caller_authority": "Timeout and retry decisions remain with the caller; governance metadata does not add an execution gate."
+  },
+  "permissions": {
+    "network": "deny",
+    "runtime_read": [
+      "Installed Skill runtime files",
+      "Public unitycli JSON output"
+    ],
+    "subprocess": [
+      "powershell.exe for scripts/record-feedback.ps1 when FeedbackMode is on and friction occurred"
+    ],
+    "file_write": [
+      "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback.jsonl",
+      "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback.1.jsonl",
+      "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback.2.jsonl",
+      "%LOCALAPPDATA%\\UnityCli\\feedback\\feedback.3.jsonl"
+    ]
+  },
+  "evidence_status": {
+    "automated_tests": "available",
+    "local_install_roundtrip": "available",
+    "clean_agent_review": "available",
+    "native_permission_enforcement": "missing evidence",
+    "longitudinal_feedback_quality": "missing evidence",
+    "human_release_approval": "missing evidence",
+    "production_telemetry": "missing evidence"
+  }
+}

package/skills/unitycli/references/custom-tools.md

@@ -0,0 +1,111 @@
+# 自定义 Tool 引文
+
+只在用户要创建、修改、审计或排查项目自定义 Tool 时读取本文件。
+
+自定义Tool用于让AI执行项目侧动作或观察项目状态。它可以只读，也可以修改Unity状态；因此必须准确声明风险、输入输出和PlayMode语义。只读能力同样实现为Tool，并声明空副作用。
+
+## 何时写 Tool
+
+- 用户要执行动作：生成资源、批量修改场景、修复对象、调用项目逻辑。
+- 能力可能改变场景、资源、ProjectSettings、Package、脚本或 Editor/Play Mode 状态。
+- 需要 dry-run、artifact、长任务或 runtime 执行语义。
+
+## 注册方式
+
+项目 C# Tool 实现 `IUnityCliTool<TReq,TRes>`。C# 文件必须放在项目内名为 `UnityCLI` 的目录下，例如 `Assets/UnityCLI/` 或 `Assets/Editor/UnityCLI/`。
+
+```csharp
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+using UnityCli;
+
+namespace MyProject.UnityCLI
+{
+    public sealed class SampleEchoTool : IUnityCliTool<SampleEchoTool.Request, SampleEchoTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Message { get; set; }
+            public string Note { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string Message { get; set; }
+            public string Note { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new ToolDescriptor
+        {
+            Name = "sample.echo",
+            Summary = "Echo a required message from a project-local Editor tool.",
+            Description = "Echoes a message from a Unity project Editor C# tool. Optional note is returned when present.",
+            Group = "sample",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            Completion = new ToolCompletionDescriptor
+            {
+                ExecutionClass = "atomic",
+                CompletionPredicate = "typed-business-terminal",
+                ProofSource = "typed-result-and-effect-readback",
+                ReloadPolicy = "same-session-proof-recovery",
+                TimeoutError = "E_EXECUTION_TIMEOUT",
+                OutcomeUnknownPolicy = "caller-decides-after-timeout",
+                CompletionDriverId = "atomic-typed-result-v1"
+            },
+            Examples = new[]
+            {
+                new ToolExample { Description = "回显消息", Input = new Request { Message = "hello" } }
+            }
+        };
+
+        /// <summary>
+        /// 执行项目侧回显工具。Request/Result schema 由框架从 DTO 派生。
+        /// </summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default)
+        {
+            ct.ThrowIfCancellationRequested();
+            return new ValueTask<Result>(new Result
+            {
+                Message = request.Message,
+                Note = request.Note
+            });
+        }
+    }
+}
+#endif
+```
+
+## 关键规则
+
+- `Request` / `Result` 嵌套在 Tool 类内，public 属性派生 `inputSchema` / `outputSchema`。
+- `[UnityCliRequired]` 标记必填输入字段；不要手写 schema 字符串。
+- `Describe()` 只写 `Name`、`Summary`、`Description`、`Group`、风险、target、Play Mode、completion 和 examples 等人工字段。
+- 自定义 Tool 必须声明完整 `Completion`；driver 必须使用框架已注册的 execution class/driver 对。`OutcomeUnknownPolicy` 描述 timeout 后没有可信终态且后续由调用方决定，不构成调用限制。
+- `ExecuteAsync(Request, ctx, ct)` 返回 `ValueTask<Result>`；失败交给框架转结构化错误 envelope，不要返回伪造的 `{ ok:false }`。
+- mutation Tool 在全部输入、目标、权限和包前置校验后、紧邻首个真实 effect 前必须恰好调用一次 `ctx.CommitEffect()`。漏调而返回成功会被协调器拒绝为 `E_TOOL_COMPLETION_PROOF_INVALID`；重复调用稳定返回 `E_TOOL_EFFECT_BARRIER_DUPLICATE`。只读 Tool、dry-run 与 proof-only recovery 不得调用。
+- `DestructiveHint = true` 准确描述可能不可逆效果，但公开 Tool 调用本身即授权；不得引入 CLI 确认、预定义按钮列表或意图门。能预览的写操作设置 `SupportsDryRun = true`。
+- runtime Tool 设置 `Target = "runtime"` 和 `PlayModeSupport = "runtime-only"`；非 Play Mode 时让错误 envelope 提供 `transient`、`retryAfterMs`、`nextActions`。
+
+## 执行入口
+
+AI 使用当前实例的统一公开目录自发现和执行：
+
+```powershell
+unitycli tools group --instance <id|projectPath|alias>
+unitycli tools group list <group> --instance <id|projectPath|alias>
+unitycli tools describe <custom-tool> --instance <id|projectPath|alias>
+unitycli tools run <custom-tool> --input '<json>' --instance <id|projectPath|alias>
+```
+
+`<group>` 必须来自当前实例 `tools group` 的真实输出；不要假设项目 Tool 位于 `custom` 组。`source` 只作描述/审计，不改变发现或执行路径。
+
+## 最小验证
+
+1. Unity 编译无错误。
+2. `tools group` 与 `tools group list <group>` 能从同一实例完整目录发现 Tool。
+3. `tools describe <tool>` 的 schema、风险、target、Play Mode 语义足以让陌生 AI 一次调用成功。
+4. `tools run <tool> --input '<json>' --instance <id|projectPath|alias>` 覆盖默认正向、代表性可选参数和错误路径。

package/skills/unitycli/references/feedback.md

@@ -0,0 +1,59 @@
+# UnityCLI 问题反馈
+
+只在 `SKILL.md` 的 `FeedbackMode` 为 `on` 且本次实际出现摩擦时读取。正常成功、常规 discovery 或没有问题的调用不得记录。
+
+## 可记录事件
+
+每个独立问题最多记录一次：
+
+- `failure`：公开 CLI/Tool 调用失败，且失败对完成任务有实际影响。
+- `ambiguity`：descriptor、schema、availability、错误或 nextActions 存在多种合理理解。
+- `missing`：所需能力、字段、说明或可验证业务状态缺失。
+- `misleading`：公开名称、示例或建议把 Agent 引向错误调用。
+- `workaround`：确实遇到坑点，但通过额外 discovery、只读核验或替代公开能力成功绕过；必须说明 workaround。
+
+不要记录普通成功、个人偏好、泛化建议、未实际遇到的风险或同一根因的重复错误。
+
+## 允许字段
+
+- `Category`：以上五类之一。
+- `Summary`：1-512 字符的单行问题摘要。
+- `Workaround`：0-512 字符；`workaround` 类必填。
+- `Capability`：可选Tool或控制面名称，只允许字母、数字、点、下划线和连字符。
+- `ErrorCode`：可选稳定错误码，如 `E_SCHEMA_INVALID`。
+- `Phase`：`discovery`、`describe`、`execute`、`verify`、`install` 或 `other`。
+
+禁止传入原始 prompt、完整输入/output envelope、源码、堆栈、大段日志、绝对路径、URL、endpoint、authorization header、token、password、secret 或 API key。脚本也会拒绝常见路径、URL 和 secret 形态。
+
+## 调用
+
+从已安装 Skill 根目录调用：
+
+```powershell
+powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts/record-feedback.ps1 `
+  -Category ambiguity `
+  -Summary "Descriptor did not distinguish two valid target forms." `
+  -Workaround "Used a read Tool to identify the canonical target." `
+  -Capability "sample.tool" `
+  -ErrorCode "E_SCHEMA_INVALID" `
+  -Phase describe
+```
+
+脚本只接受解析到 fixed local drive 且路径中没有 reparse point 的 `%LOCALAPPDATA%`，并写 `%LOCALAPPDATA%\UnityCli\feedback\`：
+
+- `feedback.jsonl`
+- `feedback.1.jsonl`
+- `feedback.2.jsonl`
+- `feedback.3.jsonl`
+
+每个文件最多 64 KiB，使用 Windows named mutex 串行。脚本不联网。成功 stdout 返回 `ok`、`recordId`、`path`、`rotated`；失败为非零退出且不生成伪记录。
+
+## 回复摘要
+
+脚本成功后，在正常任务回复末尾追加简短段落，例如：
+
+```text
+Skill 反馈：ambiguity - descriptor 未区分两种目标形式；workaround：通过只读 readback 确认 canonical target。recordId=fb_xxx，path=%LOCALAPPDATA%\UnityCli\feedback\feedback.jsonl
+```
+
+只总结实际写入的记录。没有记录时不加该段。脚本失败时仅说明“反馈未写入”及简短原因，不能把 Unity 任务改判为失败。

package/skills/unitycli/references/operation-protocol.md

@@ -0,0 +1,83 @@
+# UnityCLI 操作协议
+
+只在日常入口不足以判断实例、descriptor、输出、分页、availability、弹窗或长操作语义时读取本文件。
+
+## 实例与目录
+
+`--instance <full-id|canonical-project-path|alias>`是通用显式实例选择器；`command --project-path <path>`是同一canonical identity选择语法。显式空值必须失败；业务`input.instance`不是selector。未传selector时只从当前Unity项目CWD解析；无法确定实例即稳定失败，`--project`和Tool input都不能选实例。
+
+`target alias` 只维护 canonical project identity alias。`source` 只供说明和审计，不影响显示、describe、owner 路由或执行。连接实例的 Tool 目录是权威目录；离线静态 catalog 不能替代它。PowerShell中执行多token搜索时使用`tools search '<k1|k2|...>'`；单引号必须包住完整关键词，避免`|`被解释为shell管道。
+
+`instances list`逐个验证当前Registry v3正式文件。旧格式、损坏或不可读文件不参与路由，也不阻断其他合法实例；存在时结果包含`invalidRecordCount`，应使用`doctor`读取计数告警。不得读取、兼容解析、转换、移动或删除内部文件。显式选择对应坏instanceId仍严格失败。
+
+## Descriptor
+
+Tool descriptor 常用字段：
+
+- `inputSchema`：当前输入契约；不要从名称猜字段。结果 schema 由内部 contract 校验，不在公开 describe 展开。
+- `available:false` / `unavailableReason`：仅当前实例不可执行时出现；缺失表示当前可用。
+- `destructiveHint`、`sideEffects`、`supportsDryRun`：效果和可选预览，不是确认门。
+- `playModeSupport`：`supported`、`session-affecting`、`editor-only`、`runtime-only` 或 `unknown`。
+- `target`：Editor、Runtime 或两者。
+- `requiresPackages`：非空 Unity Package 或 Extension 依赖。
+- `examples[].input` / `examples[].execution`：结构化业务输入和按需 dry-run/timeout 控制。
+
+读取型Tool descriptor必须声明纯只读边界、schema、target、availability和PlayMode语义，不得触发import、compile、domain reload、PlayMode变化或文件写入。`command`只按同一`inputSchema`构造typed input，不改变descriptor语义。
+
+## JSON envelope
+
+成功：
+
+- `ok:true`
+- `requestId`
+- `data`：最终业务结果
+
+失败重点：
+
+- `error.code`：稳定错误码
+- `error.message`
+- `error.transient` / `retryAfterMs`
+- `error.nextActions`
+- `error.details.blockers`
+
+`nextActions`、`transient` 和 `retryAfterMs` 都是恢复建议，不构成权限、确认或重放门。`E_SCHEMA_INVALID` 可回到 `describe` 修正输入；`E_RUNTIME_NOT_READY`、Editor/PlayMode availability 错误可结合 descriptor 和当前状态处理。
+
+## Timeout、任务池与调用方决策
+
+每个live Editor或Development Player session拥有独立任务池，默认达到5个active root时关闭准入，降到4仍关闭，降到3才重开。CLI在业务请求前自动等待；AI不手工轮询、不读取active count，也不管理内部token。统一catalog在Editor和Runtime同时在线时，会分别经过两个session的准入后才返回完整结果。
+
+`--timeout-ms T`先提供一份最多`T`的准入预算。准入deadline的`E_UNITY_BUSY`明确证明业务Bridge请求未发送、effect未开始，可以稍后提交新root。获得grant后再创建一份完整`T`的execution预算；token重取、status、rebind、reload和terminal recovery都只能消费该预算，不能刷新第三份预算。
+
+`E_EXECUTION_TIMEOUT`、放行后的transport丢失、进程中断或没有可信terminal envelope时，只能确定本次调用没有返回可信终态，不能据此判断mutation是否发生。先读取对象、场景、Package、build/test状态或artifact manifest；只有形成新的业务决策后才提交新请求，不把outcome unknown自动重放。
+
+调用公开CLI的命令host必须等待进程退出；传入`--timeout-ms T`时至少等待`2 * T + 5000`毫秒，不得后台分离。CLI在stdout写完或最多1秒后退出。CLI timeout不会强停Unity中已开始的effect，host提前退出也不能作为停止证明。
+
+compile、import、domain reload和listener generation交接由session supervisor在同一execution absolute deadline内处理。同一次调用仅在`editorSessionId`未改变时，才能用完全相同的request bytes续接durable terminal；首次mutation POST后若session改变，CLI禁止向新session再次POST并返回`E_EXECUTION_TIMEOUT`。
+
+## 大输出
+
+- 列表/层级：优先 `query`、`nameFilter`、`componentType`、`className`、`parent`、`pageSize`；把 `pageInfo.nextCursor` 原值作为下一次 `cursor`。
+- 深对象：优先 `paths` 或 `viewQuery`，再限制 `maxDepth`、`maxArrayItems`。
+- 文本/源码：使用 `offset`、`maxBytes`，检查 `truncated` 与 `nextOffset`。
+- 数组/深字段：检查 `returnedCount`、`totalCount`、`nextPath`。
+- 截图、相机和大结果默认使用 artifact path；仅确需内联时使用 `inlineBase64:true`。
+- AnyJson 的非有限 CLR 数以字符串 `NaN`、`Infinity`、`-Infinity` 表示。
+
+## 弹窗与长操作
+
+`editor.state`公开状态固定为`ready|transitioning|blocked|unresponsive|unverifiable|offline|conflict`。它与`editor.dialogs`、`editor.dialog.click`使用exact本地descriptor进入统一dispatcher，不依赖可能被阻断的Live catalog；其他Tool不使用静态fallback。`conflict`只表示至少两个verified live claim；身份读取失败使用`unverifiable`，transport存在但主线程不推进使用`unresponsive`。原错误包含`details.blockers`时，先`tools run editor.dialogs`。点击前使用当前返回的dialogId和规范化button label；只能选择当前可见且enabled的按钮。点击后必须证明弹窗消失或状态改变。
+
+`build.run`、`test.run`、`editor.refresh`、`code.exec` 和需要刷新 Editor 的 Package Tool 在一次调用内等待最终业务结果。超时只表示该次调用没有可信终态，后续动作由调用方决定。`code.exec`的同步C#一旦在Unity主线程开始，timeout不能中止它；死循环、阻塞等待或长期Unity API调用可继续占用Editor。调用方应先判断这类代码是否确有必要；决定执行后应把timeout视为outcome unknown并在重试前观察业务状态。
+
+## 扩展与安装
+
+Extension 控制面使用：
+
+```powershell
+unitycli extensions list --project <path>
+unitycli extensions install <id> --project <path>
+unitycli extensions remove <id> --project <path>
+unitycli extensions doctor --project <path>
+```
+
+Skill/runtime bundle 安装使用 `init`；`init --check` 只读校验。Unity project 文件投影完成后，如任务要求 Editor 效果，仍需在已连接实例中完成 import/compile 和业务 readback。

package/skills/unitycli/reports/output_quality_scorecard.md

@@ -0,0 +1,56 @@
+# UnityCLI Output Quality Scorecard
+
+Release: 0.1.10
+Status: governed baseline
+Captured: 2026-08-06
+
+## Output Contract
+
+Normal task responses have no additional fixed format. A feedback summary is appended only when `FeedbackMode` is on, a real friction event occurred, and the recorder returned `ok:true`. With feedback off or no friction, there is no feedback record and no feedback summary.
+
+The feedback output contract requires category, concise issue summary, optional workaround, `recordId`, and local path. It excludes raw prompt, complete CLI I/O, source, logs, paths supplied as content, URLs, endpoints, and secrets. Recorder failure is reported as feedback-not-written and does not replace the task result.
+
+## Scorecard
+
+| Dimension | Result | Evidence | Residual |
+|---|---:|---|---|
+| Initial context budget | PASS: 963 / 1300 (Skill body: 691) | `resource-boundary.json` | Token estimator is heuristic |
+| Broad Unity trigger fixture | PASS: 29 / 29 | `trigger-eval.json` | Deterministic semantic fixture, not production telemetry |
+| Runtime output assertions | PASS: 5 / 5 | `output-eval.json` | Recorded fixtures, not provider execution |
+| Baseline vs with-Skill delta | +100 points | 0% to 100% assertion pass rate | Baseline is a controlled comparison |
+| File-backed fixture coverage | PASS: 2 cases | `evals/output/fixtures/feedback-scenario.json` | More real-world fixtures may be added from feedback |
+| Caller timeout authority | PASS | Runtime tests and clean Agent review | Provider behavior beyond Skill text is not measured |
+| Feedback off silence | PASS | Runtime tests and output eval | Production adoption telemetry unavailable |
+| Feedback privacy negatives | PASS | Secret/endpoint/path negative matrix | Novel secret formats can still exist |
+| Concurrent JSONL validity | PASS | 16 parallel Windows PowerShell writers | Cross-session Windows desktop contention not measured |
+| Rolling bound | PASS | Main + 3 archives, each <= 64 KiB | Longitudinal retention utility not measured |
+| Installed bundle reachability | PASS | Public init/drifted-update/check/recorder smoke for all three agents | Verified on the selected Dev project only |
+| Clean Agent interpretation | PASS | Black-box runtime discovery transcript and main-agent audit | Human adjudication unavailable |
+
+## Rollback Boundary
+
+The runtime bundle rolls back to one fixed previous projection when publish/readback fails. `FeedbackMode` is preserved across updates. Feedback records are append-only and bounded rather than transactionally rolled back. Output evaluation artifacts do not enter the installed runtime bundle.
+
+## Failure Taxonomy
+
+Current file-backed output gate has no with-Skill assertion failures. Future failures are classified as:
+
+- `caller_authority`: Skill invents a caller-side retry or mutation restriction.
+- `off_mode_noise`: feedback is written without opt-in friction.
+- `privacy_leak`: feedback includes prohibited raw content.
+- `missing_recorder`: feedback summary is claimed without a successful local record.
+- `unnecessary_wrapper`: pure file work is routed through Unity.
+- `missing_editor_route`: live Editor proof does not use the connected catalog.
+- `missing_input_files`: governed evaluation lacks a file-backed fixture.
+
+## Missing Evidence
+
+The following are **missing evidence**:
+
+- Provider-backed output eval across OpenAI, Claude, and generic agents.
+- Independent blind human review and adjudication.
+- Native-client telemetry and long-term user feedback quality.
+- Production false-positive/false-negative routing rates.
+- Approval from an external release reviewer.
+
+No missing metric is treated as PASS.

package/skills/unitycli/reports/trust-report.md

@@ -0,0 +1,57 @@
+# UnityCLI Skill Trust Report
+
+Status: governed local package
+Owner: alps-unity-cli maintainers
+Review cadence: per-release
+Reviewed: 2026-08-05
+
+## Scope
+
+This trust report covers the source Skill package, the installed runtime projection (`SKILL.md`, `references/**`, `scripts/**`), and `scripts/record-feedback.ps1`. Governed assets under `agents/**`, `evals/**`, `examples/**`, `security/**`, `reports/**`, and `manifest.json` are not installed into Agent runtime folders.
+
+## Permission Surface
+
+| Capability | Decision | Scope | Evidence |
+|---|---|---|---|
+| Network | deny | Runtime Skill and recorder | `security/network_policy.json`; static network API scan has zero matches |
+| File read | allow | Installed Skill files and public `unitycli` output | Runtime contract |
+| File write | approved by owner | `%LOCALAPPDATA%\UnityCli\feedback\feedback.jsonl` plus three archives | D008; recorder tests |
+| Subprocess | approved by owner | Bundled `record-feedback.ps1` through Windows PowerShell | D008; runtime Skill |
+| Remote inline execution | forbid | All adapters | `agents/interface.yaml` |
+
+The recorder accepts bounded summary fields, rejects common credential, endpoint, URL, and path forms, requires `LOCALAPPDATA` to resolve to a fixed local drive with no existing reparse path component, writes UTF-8 JSONL, and uses a Windows named mutex. Each persistent file is limited to 64 KiB; one main file and three archives are the fixed maximum. It does not upload feedback.
+
+## Caller Authority
+
+The Skill does not add confirmation, intent review, or a predefined operation range. `E_EXECUTION_TIMEOUT`, `transient`, and `nextActions` communicate facts or suggestions; the caller retains authority after observing business state. Same-call recovery may continue exact bytes only while `editorSessionId` is unchanged; after the first mutation POST, a new Editor session forbids automatic redelivery.
+
+## Rollback Boundary
+
+- Skill installation atomically commits one fixed previous runtime projection before update writes, and retains it until the new complete bundle passes readback.
+- A legal installed `FeedbackMode` value is preserved during updates.
+- Feedback JSONL is append-only and not transactionally rolled back; rotation bounds retention.
+- Recorder failure does not change the Unity task result.
+
+## Verified Evidence
+
+- Full repository tests: 876/876 PASS; targeted Skill/installer/docs regression: 61/61 PASS.
+- Recorder concurrency, rotation, privacy negatives, PowerShell 5.1 BOM, and non-ASCII stdout: PASS.
+- Public runtime install, drifted update, check, marker preservation, and installed-recorder smoke across `.pi`, `.claude`, and `.agents`: PASS.
+- Resource boundary: 963 estimated initial-load tokens (691 Skill body tokens), limit 1300.
+- Trigger fixture gate: 29/29 classifications.
+- Output assertion gate: 5/5 with-skill cases, 100% pass rate.
+- Dev Unity compile: 0 errors, 0 warnings; Editor returned live/ready/edit.
+- Clean Agent runtime discovery and read-only business verification: PASS.
+
+## Scanner Limits And Missing Evidence
+
+The current Yao `trust_check.py` inventories Python scripts only; it does not identify the PowerShell recorder. Therefore its generated script count is not accepted as proof for this recorder. PowerShell trust is established by repository tests, source scan, local execution, and the policies above.
+
+The following remain **missing evidence** and must not be presented as verified:
+
+- A cross-process read lease for an Agent that read an old `SKILL.md` and then requests a source-deleted reference during a concurrent update; the installer guarantees target continuity and entrypoint-last publication, not a multi-file snapshot for already-started readers.
+- OS-native sandbox enforcement of the declared file-write and network permissions.
+- Independent human release approval or blind-review adjudication.
+- Production telemetry for trigger precision, feedback usefulness, or false-positive privacy rejection.
+- Longitudinal retention and multi-session contention measurements.
+- Provider-specific native permission enforcement across OpenAI, Claude, generic Agent Skills, and VS Code.