Unity Qframework

Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Generating QFramework architecture-layer code — Architecture/System/Model/Command/Utility/Query classes
• Generating bound view code for a QFramework ViewController component, or UIKit panel code for a UI prefab
• Checking QFramework installation status, scanning IArchitecture/ISystem/IModel/ICommand/IQuery/IController implementations, or searching QFramework's built-in API documentation attributes
• Marking, building or clearing QFramework ResKit AssetBundles, or reading/writing ResKit build options (SimulationMode, append-hash, auto-generate-class)
• Reading/writing UIKit project settings (namespace, script/prefab dirs) or LocaleKit editor locale / language defines
• 生成 QFramework 架构层代码、绑定 ViewController/UIKit 面板代码生成、检查安装状态与架构扫描、ResKit AssetBundle 标记与构建、UIKit/LocaleKit 设置读写

Unity QFramework Skills

Editor-side automation for QFramework — architecture codegen, UIKit/ResKit tooling, LocaleKit configuration, and read-only architecture/API-doc scanning.

QFramework has no UPM package. It installs one of two ways: the Toolkits unitypackage (asmdef-based: QFramework / QFramework.CoreKit / UIKit / UIKit.Editor / ResKit / ResKit.Editor / AudioKit), or a single-file QFramework.cs dropped straight into Assets/ (no asmdef, core architecture interfaces only, no Toolkits). This module holds zero direct references to either form — every call resolves through reflection against a fully-qualified type name, so the UnitySkills Editor assembly compiles identically regardless of what (if anything) is installed. qframework_get_status works in every state; every other skill returns MISSING_PACKAGE when its anchor type cannot be resolved.

Requires: QFramework (no package id — install via the official unitypackage or QFramework.cs, API anchored to v1.0.257). Companion module: qframework-design for architecture design rules (four-layer responsibilities, Command/Query/Event/BindableProperty usage, IOCContainer vs. Toolkits IOCKit) — advisory only, no REST skills, load it before writing or reviewing QFramework architecture code.

Guardrails

Operating Mode (three-tier):

• SemiAuto — the 8 ReadOnly skills run directly in all three modes without a grant: qframework_get_status, qframework_list_architecture_code_types, qframework_preview_architecture_code, qframework_get_uikit_settings, qframework_list_asset_bundle_marks, qframework_get_reskit_build_options, qframework_scan_architecture, qframework_query_api_docs.

• FullAuto (needs a user grant under Approval; runs directly under Auto/Bypass with audit) — the 6 write skills that are not NeverInSemi: qframework_mark_asset_bundle, qframework_mark_asset_bundle_batch, qframework_set_uikit_settings, qframework_set_reskit_build_options, qframework_set_editor_locale, qframework_set_language_defines.

• Auto-forbidden (NeverInSemi — returns MODE_FORBIDDEN under both Approval and Auto; only Bypass or a user-managed Allowlist entry can run these; never attempt a grant) — 6 skills, triggered by two different metadata flags:

  • MayTriggerReload=true on all four codegen-to-disk skills: qframework_generate_architecture_code, qframework_generate_architecture_code_batch, qframework_generate_view_controller_code, qframework_generate_ui_panel_code.
  • RiskLevel="high" on qframework_build_asset_bundles (also LongRunning=true, SupportsDryRun=false — blocks the Editor main thread for the build duration) and qframework_clear_asset_bundles (also Operation=Delete — deletes AssetBundles/ and StreamingAssets/AssetBundles/ outright).

  This is stricter than a plain "write skill needs a grant" reading: the four codegen skills are not just gated behind a grant, they are unreachable under Approval and Auto — Bypass or Allowlist only.

Two-phase code generation protocol. qframework_generate_view_controller_code and qframework_generate_ui_panel_code write .cs/.Designer.cs files synchronously and return pendingCompile: true before compilation happens. The generated component is attached to the GameObject (view controller case) only later, by a [DidReloadScripts] callback that fires after the next domain reload. After calling either skill, poll compile status (script_get_compile_feedback / debug_get_errors) before re-inspecting the GameObject or prefab — a 503/busy response from the service during that window is expected, not a failure. The two skills name their Designer-file output field differently — expectedDesignerScriptPath on the view-controller skill, expectedDesignerPath on the UI-panel skill — this is deliberate, not a typo; don't assume the same key works for both.

This module declares no RequiresPackages. QFramework has no real UPM package id, so tagging skills with RequiresPackages=["QFramework"] would only make PackageManagerHelper.IsPackageInstalled("QFramework") permanently return false and demote every QFramework skill -5 in /skills/recommend scoring regardless of actual install state — dotween sets the same precedent for non-UPM distributions. The MISSING_PACKAGE gate is entirely reflection-driven: every skill (except qframework_get_status) probes its own anchor API (QType(...)) at call time and returns a structured MISSING_PACKAGE error naming the exact missing type/member when it can't resolve.

Toolkits vs. core-only install. qframework_get_status.installKind is "toolkits", "coreOnly", or "none". On "coreOnly" (single-file QFramework.cs), architecture codegen, UIKit, ResKit and LocaleKit skills still report MISSING_PACKAGE — those anchor types only ship with the Toolkits.

Skills

Status & Discovery (3)

qframework_get_status

Report install kind (Toolkits vs. core-only vs. none), detected assemblies, package version, editor locale, and ResKit SimulationMode. Works with or without QFramework installed — call this first. Parameters: None Returns: installed, installKind, assemblies, version, editorLocaleIsCN, simulationMode

qframework_scan_architecture

Scan loaded assemblies (excluding QFramework's own assemblies and system assemblies) for non-abstract types implementing IArchitecture / ISystem / IModel / ICommand(<T>) / IQuery<T> / IController. Read-only type metadata inspection; does not enter Play Mode. Parameters: None Returns: architectures, systems, models, commands, queries, controllers, totalCount

qframework_query_api_docs

Search QFramework's built-in API documentation attributes (ClassAPIAttribute/MethodAPIAttribute/PropertyAPIAttribute + APIDescriptionCN/EN + APIExampleCode) across loaded assemblies.

Returns: count, truncated, classes

Architecture CodeGen (4)

qframework_list_architecture_code_types

List ArchitectureCodeType values (Architecture/System/Model/Command/Utility/Query) with whether each supports interface generation and its Architecture registration method name. Parameters: None Returns: count, types

qframework_preview_architecture_code

Preview the architecture-layer code ArchitectureCodeGenerator.CreatePreview would generate for a name, without writing any file.

Returns: isValid, error, codeType, className, namespaceName, assetPath, code. On isValid: false, the response also carries a hint field — ArchitectureCodeGenerator's own validation message (error) is QFramework's hardcoded upstream text and may be in Chinese (e.g. "请输入名字"); hint is a fixed English annotation pointing at which of codeType/inputName/namespaceName/outputRoot to check.

qframework_generate_architecture_code

Generate architecture-layer code to disk via CreatePreview + Generate. Refuses to overwrite an existing file at the target path. NeverInSemi (MayTriggerReload=true) — Bypass or Allowlist only.

Same parameters as qframework_preview_architecture_code (codeType, inputName, namespaceName, outputRoot required; generateInterface optional, default false). Returns: success, error, assetPath, codeType, className. Failure responses also add hint: the same upstream-validation annotation as qframework_preview_architecture_code when CreatePreview itself rejects the input, or a fixed note that QFramework's file-exists error means it refused to overwrite existing code when Generate fails after a valid preview.

qframework_generate_architecture_code_batch

Generate multiple architecture-layer code files in one request. NeverInSemi (MayTriggerReload=true).

Returns: totalItems, successCount, failCount, results

UIKit CodeGen & Settings (4)

qframework_generate_view_controller_code

Generate the bound-view code for a GameObject's ViewController component via CodeGenKit.Generate(IBindGroup). Writes .cs/.Designer.cs immediately and returns before compilation — see the two-phase protocol in Guardrails. NeverInSemi (MayTriggerReload=true). Target GameObject must already carry a ViewController component (or subclass) with ScriptsFolder and ScriptName set.

*At least one of the six is required. Lookup priority: entityId > instanceId > path > name (exact, then substring) > tag > componentType, per GameObjectFinder.Find. Returns: pendingCompile, error, expectedScriptPath, expectedDesignerScriptPath, className, namespaceName, scriptsFolder

qframework_generate_ui_panel_code

Generate UIKit panel + Designer code for a UI prefab via UICodeGenerator.DoCreateCode. The target must already be a regular (or variant) Prefab asset — QFramework silently no-ops for anything else, so this skill pre-validates and reports a real error instead. UICodeGenerator writes <Panel>.cs only if it doesn't already exist but always rewrites <Panel>.Designer.cs; this skill snapshots the Designer file either way (modified-before snapshot if it already existed, created-asset snapshot if it's new), so workflow_* undo covers both files. NeverInSemi (MayTriggerReload=true).

Returns: pendingCompile, error, expectedScriptPath, expectedDesignerPath, prefabPath, uiScriptDir, uiPrefabDir, namespaceName

qframework_get_uikit_settings

Read UIKit project settings (Assets/QFrameworkData/ProjectConfig/ProjectConfig.json) — default namespace, UI script/prefab output directories, and the assembly names UICodeGenerator searches for bind types. Parameters: None Returns: namespaceName, uiScriptDir, uiPrefabDir, assemblyNamesToSearch, isDefaultNamespace

qframework_set_uikit_settings

Write UIKit project settings and persist to ProjectConfig.json. Only the parameters you pass are changed.

Returns: changed, namespaceName, uiScriptDir, uiPrefabDir, assemblyNamesToSearch, isDefaultNamespace

ResKit AssetBundle (7)