---

name: unity-qframework-design description: Source-anchored design rules for QFramework v1.0.257 covering the four-layer architecture (Controller/System/Model/Utility), Command/Query/Event/BindableProperty core tools, and the CoreKit-family toolkits (UIKit/ResKit/ActionKit/PackageKit), distilled from QFramework.cs source and the official Doc.md tutorial with every rule citing a file/line anchor to guard against stale-memory hallucination.

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

• Writing or reviewing QFramework architecture code (Controller/System/Model/Utility)
• Registering Systems/Models/Utilities, sending Commands/Queries/Events
• Binding BindableProperty / BindableList / BindableDictionary in views
• Choosing between the core IOCContainer and the Toolkits IOCKit, or between architecture events and EasyEvent
• 编写或审查 QFramework 架构代码、四层职责划分、Command/Query/Event/BindableProperty 使用、核心容器与 Toolkits 容器选型

QFramework - Design Rules（v1.0.257）

Advisory 模块。全部规则提炼自 QFramework 官方源码与教程：

• QFramework.cs（核心架构单文件源码，仓库根目录 QFramework.cs，内部注释标注 Latest Update: 2026.8.12 return module instance after register）
• Doc.md（官方教程全文，8820 行，仓库根目录 Doc.md）
• QFramework API.md（核心层签名索引；Toolkits 无覆盖，且截至本次抓取仍未同步 2026-08-12 的返回值变更）

每条规则都标注具体文件/行号（行号对应上游 liangxiegame/QFramework 主仓库 v1.0.257 快照；Toolkits 源码位于 QFramework.Unity2018+/Assets/QFramework/），遇到分歧以 QFramework.cs 源码为准，Doc.md/API.md 仅供交叉印证——教程本身可能滞后于源码。正文中文，API 名/代码保持英文。

Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

When to Load This Module

生成或审查以下任意一项之前先加载：

• Architecture<T> 子类的 Init() 启动逻辑、RegisterSystem/RegisterModel/RegisterUtility 调用
• IController / ISystem / IModel / IUtility 接口实现，或给这些接口增删 ICan* 能力接口
• SendCommand / SendQuery / SendEvent / RegisterEvent 调用，ICommand / ICommand<TResult> / IQuery<TResult> 实现
• BindableProperty<T> / BindableList<T> / BindableDictionary<TKey,TValue> 的声明、Register/RegisterWithInitValue/Comparer 使用
• TypeEventSystem / EasyEvent 系列的注册与手动注销
• 覆写 Architecture<T>.ExecuteCommand 做 Command 拦截（日志/中间件/撤销/自动化测试）
• 判断某个数据该放 Model 还是留在 MonoBehaviour 局部
• 在 QFramework.cs 自带的 IOCContainer 与 Toolkits CoreKit.IOCKit（IQFrameworkContainer + [Inject]）之间选型
• Toolkits 安装形态确认（unitypackage 导入 Assets/，无 UPM）、版本号核对

Critical Rule Summary

#	Rule	Source anchor
1	RegisterSystem<T>/RegisterModel<T>/RegisterUtility<T> 返回注册的实例本身（不再是 void），自 2026-08-12 起生效；IArchitecture 接口已声明 TSystem/TModel/TUtility 返回类型。官方 Doc.md 全部教程示例（含"用接口设计模块"一节 2408-2422 行）仍是丢弃返回值的旧写法，是过时示例，不代表当前推荐用法	QFramework.cs:43,45,47,132-163
2	四层接口：IController(226) ISystem(235) IModel(264) IUtility(291)；ICommand(299) / ICommand<TResult>(305)；IQuery<TResult> 只有泛型形式，没有非泛型 IQuery(342)	QFramework.cs:226,235,264,291,299,305,342
3	分层通用规则：IController 改 System/Model 状态必须走 Command；System/Model 通知上层必须用 Event 或 BindableProperty；上层可直接获取下层，下层不能获取上层；Command/Query 不能有状态。规则是"理想状态"，作者原话允许按需放宽（如给 IController 追加 ICanSendEvent）	Doc.md:2682-2820（放宽原话 2791，改接口示例 2793-2805）
4	判断数据是否该放 Model：时间上共享（跨启动持久化）、物理上共享（跨界面/跨场景常驻内存）、配置表三类才放 Model；反例——敌人生命不放 Model，交给敌人脚本自己管理	Doc.md:4051-4077（反例 4064-4066）
5	BindableProperty<T>.Value setter 靠 Comparer 判等后再触发事件；ComparerAutoRegister（[RuntimeInitializeOnLoadMethod]）已为 int/float/string/Vector2-4/Color/Quaternion 等类型把默认 Equals 换成 ==。Register 只订阅后续变化，RegisterWithInitValue 会先用当前值回调一次	QFramework.cs:711,762-789,740-749
6	BindableList<T> / BindableDictionary<TKey,TValue> 是 2024-09-18/19 才加的 Toolkits 附加工具（_CoreKit/BindableKit/，不在 QFramework.cs 单文件里），边缘工具而非核心概念；作者原话承认不知道 BindableDictionary 能用在什么场景——按需评估，不要当成默认选型。BindableList 索引器赋值只触发 OnReplace，Move 只触发 OnMove（都不会连带 OnAdd/OnRemove）	Doc.md:8438-8592,8593-8712（原话 8595）；BindableList.cs:38-115,BindableDictionary.cs:17-44
7	事件工具三选一：TypeEventSystem（跨对象、支持接口继承事件、适合通用系统）／EasyEvent（脱离架构、更轻量、无字段名）／架构内建 SendEvent（基于 TypeEventSystem 实例）。手动注销必须用具名方法（匿名委托无法 -=）；UnRegisterWhenCurrentSceneUnloaded() 无需传 GameObject，换场景即自动清空；事件类型建议用 struct 减少 GC	Doc.md:3305-3461（小结 3440-3461），QFramework.cs:610-611,624-641
8	Command 拦截：覆写 Architecture<T>.ExecuteCommand(ICommand)（前后各插一段逻辑）可做日志/中间件/撤销/自动化测试，官方源码默认实现只是直接 command.Execute()	Doc.md:3137-3186，QFramework.cs:183-187
9	两套容器不要混淆：核心 IOCContainer（Dictionary<Type,object>，仅单例注册/获取，Architecture<T> 内部私有持有一份，无反射）；Toolkits CoreKit.IOCKit（IQFrameworkContainer/QFrameworkContainer）是完全独立的反射式依赖注入实现——支持类型映射、命名注册、关系映射、按 [Inject] 特性做字段/属性注入、按参数最多的公开构造函数自动解析依赖——不在 QFramework.cs 源文件里	核心：QFramework.cs:130,647-684；Toolkits：IOCKit.cs:19-31,33-136,141,239-263,315-358（_CoreKit/IOCKit/IOCKit.cs）
10	Toolkits 安装形态：.unitypackage 导入 Assets/，没有 UPM 包；已装版本看 PackageKit 编辑器面板或安装目录下的 PackageVersion.json，GitHub/Gitee Release tag 会滞后于 PackageKit 实时源	Doc.md:4178-4182；PackageData.cs:286（PackageVersion.json 写入路径，Toolkits 源码）

Sub-doc Routing

Sub-doc	When to read
LAYERS.md	四层接口与职责、通用规则与放宽方式、共享数据判据、Command 拦截、Architecture<T> 生命周期（InitArchitecture/Deinit）
BINDABLE_QUERY.md	BindableProperty（含 Comparer/RegisterWithInitValue）、BindableList/BindableDictionary、Command vs Query 的 CQRS 分工
EVENT_TOOLS.md	TypeEventSystem、EasyEvent 家族、IOCContainer（核心）vs IOCKit（Toolkits）、注销模式（UnRegisterWhenGameObjectDestroyed/UnRegisterWhenCurrentSceneUnloaded/IUnRegisterList）
CODEGEN_UIKIT.md	CodeGenKit 两阶段代码生成（Designer 覆盖规则、命名空间迁移、ScriptsFolder 不 fallback、ViewController 嵌套、OtherBinds）与 UIKit 界面工作流（面板开关/生命周期/Apply 选错 UIRoot 的硬坑/UIKitSettingData 配置）
RESKIT.md	ResKit 资源方案：AssetBundle 标记粒度、场景独占 AB、模拟/非模拟模式、ResLoader 引用计数语义、构建输出目录、AB 跨包 Prefab 依赖的 Unity 官方 bug
ACTIONKIT.md	ActionKit 链式动作序列（Delay/Sequence/Parallel/Repeat/Condition、全局生命周期、TimeScale 与场景切换）、SingletonKit 六种单例选型、AudioKit 三通道与纯编辑态访问 Settings 会 NPE 的陷阱、ScreenTransition
DATA_KITS.md	FSMKit（链式 vs 类模式）、TableKit（联合查询与内部基础设施定位）、PoolKit（两种池语义差异）、GridKit/DynaGrid

Routing to Other Modules

• REST 端点/操作层面的 QFramework 技能调用 → 加载并行编写的 qframework REST 模块（本模块只覆盖设计规则，不覆盖 REST 参数）
• 与 UniTask/协程的桥接（ActionKit 序列 vs async）→ unitask-design / async
• 整体架构分层评审、状态管理选型 → architecture / patterns
• 事件/BindableProperty 高频触发场景的性能评审 → performance
• ResKit 底层如走 Addressables 的资源生命周期 → addressables-design
• Asmdef 布局（QFramework.cs 与 Toolkits 分别装配）→ asmdef

Version Scope

锚定 v1.0.257（QFramework.cs 内部注释最后更新 2026-08-12，本模块 2026-08 抓取）。

• QFramework.cs 是单文件核心架构，版本号不随 Toolkits 独立发布，跟随 GitHub/Gitee 主仓库 tag。
• Toolkits（CoreKit/UIKit/ResKit/ActionKit/AudioKit/PackageKit…）版本以 PackageKit 面板/PackageVersion.json 为准，可能领先于本模块引用的 unitypackage 快照。
• 关键分水岭：RegisterSystem/RegisterModel/RegisterUtility 返回值语义在 2026-08-12 从 void 改为返回实例——凡是引用早于此版本的第三方教程或历史代码，示例可能与当前源码签名不符，以 QFramework.cs 为准。

当有疑问时，去读源码引用的行号，而不是凭记忆或凭教程旧例。

Known Gaps

• LocaleKit 官方教程零覆盖：Doc.md 全篇只在工具清单里一句话提到 LocaleKit（"本地化&多语言工具集"），没有任何用法示例或 API 说明。从源码看它当前主要是编辑器内 CN/EN 显示开关（LocaleKitEditor.IsCN，EditorPrefs 键 EDITOR_CN）加一份语言定义 ScriptableObject（LanguageDefineConfig），并不是面向游戏运行时文本的完整多语言方案，与其自我描述有落差。需要运行时本地化时不要假设 LocaleKit 能直接胜任，先读源码确认。
• FluentAPI 方法清单未逐条收录：_CoreKit/FluentAPI/ 覆盖 GameObject/Transform/Camera/Color/Graphic/Vector/RectTransform 及 C# 基础类型的大量链式扩展，数量过大未在本模块展开；用到时按目标类型去对应源文件查。