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

Sub-doc Routing

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# 基础类型的大量链式扩展，数量过大未在本模块展开；用到时按目标类型去对应源文件查。