@kkarum/framework 2.3.18 → 2.3.20

package/README.md

@@ -1,93 +1,191 @@
-# framework
-
-
-
-## Getting started
-
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
-
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
-
-## Add your files
-
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
-
-```
-cd existing_repo
-git remote add origin http://47.243.247.195:8099/crazy_client/framework.git
-git branch -M main
-git push -uf origin main
-```
-
-## Integrate with your tools
-
-- [ ] [Set up project integrations](http://47.243.247.195:8099/crazy_client/framework/-/settings/integrations)
-
-## Collaborate with your team
-
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
-
-## Test and Deploy
-
-Use the built-in continuous integration in GitLab.
-
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
-
-***
-
-# Editing this README
-
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
-
-## Suggestions for a good README
-
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
-
-## Name
-Choose a self-explaining name for your project.
-
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
-
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
-
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
-
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
-
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
-
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
-
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
-
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
-
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
-
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
-
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
-
-## License
-For open source projects, say how it is licensed.
-
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+# Framework
+
+## AI 工具使用约定
+
+Codex / AI 工具生成本项目业务代码时必须遵守：
+
+- 获取 `AssetProperty` 使用点访问：`FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer`，不要使用 `["ShopLayer"]`。
+- `LayerController` 不查找节点或组件；节点/组件引用定义在对应 `FW.Layer` 中，节点用 `FWPropertyNode`，组件用 `FWPropertyComponent`，变量名与节点名一致。
+- 默认不要在业务层调用 `invoke()`，除非用户明确要求。
+- 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`；`bundleName` 和 `addRegistry()` 的 key 必须一致，统一使用小写 bundle 名。
+
+Registry 示例：
+
+```ts
+import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
+import { RegisterLogic } from "../logic/RegisterLogic";
+
+export class RegisterRegistry extends FW.Registry {
+  bundleName = "register";
+  logic: FW.Newable<FW.Logic> = RegisterLogic;
+  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
+}
+
+FW.Framework.addRegistry("register", RegisterRegistry);
+```
+
+`assets/framework` 是面向 Cocos Creator 2.x 的自写业务框架，核心目标是把业务模块、UI Layer、资源、事件、网络、定时器、对象池和异步流程统一到 `FW` 全局命名空间下管理。
+
+本 README 只做快速总览。详细开发规范请阅读 `assets/framework/docs/` 下的文档。
+
+## 核心入口
+
+框架初始化后会创建全局 `FW`：
+
+- `FW.Framework`：依赖注入容器，负责注册和获取业务组件。
+- `FW.Entry`：业务统一入口，聚合所有管理器。
+- `FW.Log`：统一日志输出。
+- `FW.SystemDefine`：框架枚举。
+- `FW.EventDefine`：系统事件枚举。
+
+业务代码应优先通过 `FW.Entry` 使用框架能力，不要直接 new 框架管理器。
+
+## 主要模块
+
+| 模块 | 说明 |
+| --- | --- |
+| `FW.Registry` | bundle 注册表，声明 Logic/Data/Config/Sender/Handle |
+| `FW.FrameworkBase` | 业务基类，提供依赖获取、性能记录和错误包装 |
+| `FW.Logic` | 业务流程 |
+| `FW.Data` | 业务数据 |
+| `FW.AssetConfig` | 资源配置 |
+| `FW.LayerController` | UI Layer 控制器 |
+| `FW.Entry.resMgr` | bundle 和资源加载/释放 |
+| `FW.Entry.layerMgr` | UI Layer 打开、关闭、队列和栈 |
+| `FW.Entry.uiMgr` | UI 事件注册、节点查找、按钮状态 |
+| `FW.Entry.evtMgr` | 框架事件总线 |
+| `FW.Entry.timeMgr` | 游戏生命周期定时器 |
+| `FW.Entry.promiseMgr` | 可取消、超时、重试的 Promise |
+| `FW.Entry.socketMgr` | Socket 连接管理 |
+| `FW.Entry.objectMgr` | 对象池 |
+| `FW.Entry.taskMgr` | 分帧任务 |
+
+## 推荐业务结构
+
+新增业务功能时，推荐按 bundle 拆分：
+
+```text
+assets/<bundle>/
+  registry/<Bundle>Registry.ts
+  logic/<Bundle>Logic.ts
+  data/<Bundle>Data.ts
+  config/<Bundle>AssetConfig.ts
+  socket/<Bundle>Sender.ts
+  socket/<Bundle>Handle.ts
+  ui/<Feature>/<Feature>LayerController.ts
+  prefab/<Feature>Layer.prefab
+```
+
+命名必须保留框架后缀，例如 `ShopLogic`、`ShopData`、`ShopAssetConfig`、`ShopSender`、`ShopHandle`。框架会根据类名和 bundle 名自动推断依赖。
+
+## UI 开发约定
+
+UI 页面、弹窗、常驻面板应使用 `FW.LayerController`：
+
+```ts
+await FW.Entry.layerMgr.openAsync({
+  type: ShopLayerController,
+  args: { tab: "hot" },
+});
+```
+
+LayerController 中：
+
+- 使用 `this.find()` 查找节点。
+- 使用 `this.cc()` 绑定按钮事件。
+- 使用 `this.fw()` 监听框架事件。
+- 使用 `this.close()` 关闭 Layer。
+- 通过 `layerAssetProperty` 指向 `AssetConfig` 中的 prefab。
+
+不要在业务代码中绕过 `layerMgr` 直接 `cc.instantiate` 业务弹窗。
+
+## 资源开发约定
+
+资源统一写入 `FW.AssetConfig`：
+
+```ts
+preLoad = {
+  prefab: {
+    ShopLayer: {
+      bundle: "shop",
+      path: "prefab/ShopLayer",
+      type: cc.Prefab,
+      priorityLoaded: true,
+      autoRelease: true,
+    },
+  },
+};
+```
+
+加载资源时使用：
+
+```ts
+const prefab = await FW.Entry.resMgr.loadAsset<cc.Prefab>(assetProperty);
+```
+
+不要在业务代码中散落硬编码资源路径，也不要在资源未加载时调用 `getAsset()`。
+
+## 事件和异步
+
+框架事件：
+
+```ts
+FW.Entry.evtMgr.dispatch("SHOP_GOODS_CHANGED", goods);
+FW.Entry.evtMgr.register("SHOP_GOODS_CHANGED", this.renderGoods, this);
+```
+
+定时器：
+
+```ts
+FW.Entry.timeMgr.schedule(this.tick, 1, cc.macro.REPEAT_FOREVER, this);
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+异步流程：
+
+```ts
+const result = await this.invoke(
+  FW.Entry.resMgr.loadAssetData(assetProperty),
+  "loadAsset",
+);
+```
+
+`invoke()` 会记录性能并统一输出错误。调用方必须处理返回 `undefined` 的情况。
+
+## cocos-mcp 协作
+
+使用 cocos-mcp 做 UI 自动化时：
+
+1. 先用 `cocos_mcp_diagnose` 检查连接。
+2. 用 `scene_get_tree` 获取真实节点路径。
+3. 用 `asset_query` 或 `asset_resolve` 确认资源。
+4. 用 `ui_create_tree` 或 `ui_create_node` 创建 UI。
+5. 用 `ui_set_sprite_frame` 绑定图片。
+6. 需要复用时用 `prefab_create_from_node` 生成 prefab。
+7. 运行时事件优先写在 `LayerController` 中，不强行用编辑器 clickEvents。
+
+MCP 节点路径必须使用绝对路径，例如 `/Canvas/ShopLayer/CloseButton`。
+
+## Codex 使用原则
+
+Codex 在本项目中新增功能时必须遵守：
+
+- 不修改框架内部源码，除非用户明确要求维护框架。
+- 优先复用 `FW.Entry`、`FW.FrameworkBase`、`FW.LayerController`。
+- UI 功能走 LayerController + prefab + AssetConfig。
+- 业务流程放 Logic，业务状态放 Data。
+- 网络协议放 Sender/Handle。
+- 资源路径集中在 AssetConfig。
+- 事件、定时器、Promise、对象池全部使用框架 API。
+
+## 详细文档
+
+- [FRAMEWORK_OVERVIEW.md](docs/FRAMEWORK_OVERVIEW.md)：框架整体架构。
+- [FRAMEWORK_USAGE.md](docs/FRAMEWORK_USAGE.md)：业务使用方式。
+- [FRAMEWORK_API.md](docs/FRAMEWORK_API.md)：常用 API 速查。
+- [FRAMEWORK_PATTERNS.md](docs/FRAMEWORK_PATTERNS.md)：新增功能模式和禁止事项。
+- [FRAMEWORK_EXAMPLES.md](docs/FRAMEWORK_EXAMPLES.md)：可复制代码示例。
+- [CODEX_GUIDE.md](docs/CODEX_GUIDE.md)：Codex 长期开发规范。
+- [MCP_INTEGRATION.md](docs/MCP_INTEGRATION.md)：cocos-mcp 自动化流程。
+- [UI_DEVELOPMENT_GUIDE.md](docs/UI_DEVELOPMENT_GUIDE.md)：UI 开发规范。
+- [ERROR_HANDLING.md](docs/ERROR_HANDLING.md)：错误处理和生命周期清理。

package/docs/CODEX_GUIDE.md

@@ -0,0 +1,219 @@
+# Codex Guide
+
+## AI 生成代码强制规则
+
+以下规则优先级高于本文档中的旧示例。Codex 或其他 AI 工具为本项目生成业务代码时必须遵守：
+
+1. 获取 `AssetProperty` 必须使用点访问，不要使用字符串下标访问。
+
+```ts
+// 推荐
+return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+
+// 禁止
+return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab["ShopLayer"];
+```
+
+2. `LayerController` 不要查找节点或组件，不要调用 `find()` / `findComponent()` 做 UI 引用缓存。
+   UI 节点和组件引用必须定义在对应 `FW.Layer` 组件中，并使用 `FWPropertyNode` / `FWPropertyComponent` 装饰器。变量名默认必须与节点名一致。
+
+```ts
+@ccclass
+export class ShopLayer extends FW.Layer {
+  @FWPropertyNode()
+  BtnClose: cc.Node = null;
+
+  @FWPropertyComponent(cc.Label)
+  TitleLabel: cc.Label = null;
+}
+
+export class ShopLayerController extends FW.LayerController {
+  private bindEvents() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+  }
+}
+```
+
+3. 业务层默认不要调用 `invoke()`。除非用户明确要求统一性能记录、错误包装或可恢复异步流程，否则直接 `await` 业务方法、网络方法或资源方法。
+
+```ts
+// 推荐
+await FW.Entry.getComponent(ShopLogic).buyGoods(goodsId);
+
+// 仅在用户明确要求时使用
+await this.invoke(FW.Entry.getComponent(ShopLogic).buyGoods(goodsId), "buyGoods");
+```
+
+4. 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`。`bundleName` 与 `addRegistry()` 的 bundle key 必须完全一致，统一使用小写 bundle 名。
+
+```ts
+import { RegisterAssetConfig } from "../config/RegisterAssetConfig";
+import { RegisterLogic } from "../logic/RegisterLogic";
+
+export class RegisterRegistry extends FW.Registry {
+  bundleName = "register";
+  logic: FW.Newable<FW.Logic> = RegisterLogic;
+  config: FW.Newable<FW.AssetConfig> = RegisterAssetConfig;
+}
+
+FW.Framework.addRegistry("register", RegisterRegistry);
+```
+
+规则：
+
+- `Registry` 类名使用业务名 + `Registry`，例如 `RegisterRegistry`。
+- `bundleName` 使用小写业务 bundle 名，例如 `"register"`。
+- `logic/data/config/sender/handle` 字段必须显式声明为对应 `FW.Newable<...>` 类型。
+- `FW.Framework.addRegistry("register", RegisterRegistry)` 必须与 `bundleName` 完全一致。
+- 只声明实际存在的业务组件，不要为了占位声明空的 Data/Sender/Handle。
+
+本文档是 Codex 在本项目中新增、修改业务功能时必须优先参考的工作规范。
+
+## 首要约束
+
+- 不修改 `assets/framework` 内部源码。
+- 不把框架 README 当作唯一依据；以源码和 `docs/FRAMEWORK_*.md` 为准。
+- 新业务功能优先扩展业务 bundle。
+- 所有框架能力优先复用 `FW.Entry`、`FW.FrameworkBase`、`FW.LayerController`。
+- UI 自动化优先配合 cocos-mcp 创建节点、绑定资源、保存 prefab 或场景。
+
+## 开工前检查
+
+Codex 在写代码前应先做：
+
+1. 搜索目标 bundle 是否已存在。
+2. 查找已有 `Registry`、`Logic`、`Data`、`AssetConfig`、`LayerController`。
+3. 查找同类 UI 控制器的命名、目录、事件风格。
+4. 查找资源路径和 prefab 命名。
+5. 如果涉及 Cocos 场景/UI，先通过 cocos-mcp `scene_get_tree` 获取真实节点路径。
+
+## 新增业务功能决策
+
+### 用户要新增页面、弹窗、面板
+
+执行：
+
+1. 新增或复用 prefab。
+2. 新增 `XxxLayerController extends FW.LayerController`。
+3. 在 `AssetConfig` 中声明 prefab。
+4. `layerAssetProperty` 返回该资源。
+5. 使用 `FW.Entry.layerMgr.openAsync({ type: XxxLayerController, args })` 打开。
+6. 事件用 `this.cc()`、`this.fw()`。
+
+不要：
+
+- 直接 `cc.instantiate(prefab)` 打开业务 UI。
+- 直接在组件里 `node.on` 后不清理。
+- 在构造函数里查节点。
+
+### 用户要新增业务流程
+
+执行：
+
+1. 放入 `XxxLogic`。
+2. 状态读写放入 `XxxData`。
+3. 网络请求通过 `XxxSender`。
+4. 网络返回通过 `XxxHandle` 写入 Data 或派发事件。
+5. UI 监听事件刷新。
+
+不要：
+
+- 把网络请求写在 LayerController。
+- 把 UI 节点保存到 Data。
+
+### 用户要新增资源
+
+执行：
+
+1. 在 `XxxAssetConfig` 增加 `preLoad` 或 `demandLoad`。
+2. 使用 `FW.Entry.resMgr.loadAsset()` 或 `loadAssetData()`。
+3. 如果用于 Layer prefab，优先 `preLoad.prefab`。
+
+不要：
+
+- 在多个文件硬编码相同资源路径。
+- 资源未加载就调用 `getAsset()`。
+
+### 用户要新增 Socket 协议
+
+执行：
+
+1. 在 `Sender` 写发送方法。
+2. 在 `Handle.onMessage()` 做协议分发。
+3. 用 `FW.Entry.evtMgr.dispatch()` 通知业务。
+4. 心跳识别实现 `onHeart()`。
+5. 协议轮询实现 `getProtocolKey()`。
+
+不要：
+
+- 直接 new `WebSocket`。
+- 在 UI 中解析所有网络消息。
+
+## 必须复用的 API
+
+| 场景 | 必须优先使用 |
+| --- | --- |
+| 打开 UI | `FW.Entry.layerMgr.openAsync/openSync` |
+| 关闭 UI | `ctr.close()` 或 `FW.Entry.layerMgr.close(ctr)` |
+| 查节点 | `ctr.find()` 或 `FW.Entry.uiMgr.find()` |
+| 按钮事件 | `ctr.cc()` 或 `ctr.registerEvent()` |
+| 全局事件 | `FW.Entry.evtMgr.register/dispatch` |
+| 资源加载 | `FW.Entry.resMgr` |
+| 定时器 | `FW.Entry.timeMgr` |
+| 异步重试/取消 | `FW.Entry.promiseMgr` 或 `FrameworkBase.invoke()` |
+| 对象复用 | `FW.Entry.objectMgr.createObjectPool()` |
+| 日志 | `FW.Log.debug/warn/error/...` |
+| 业务依赖 | `this.getLogic/getData/getConfig/getSender/getHandle` |
+
+## 代码风格
+
+必须：
+
+- 类名使用业务名前缀和框架后缀。
+- 继承对应框架基类。
+- 控制器使用 `private` 方法拆分 `cacheNodes()`、`bindEvents()`、`render()`。
+- 异步方法处理 `undefined` 返回。
+- 用 `FW.Log` 记录业务错误。
+- UI 事件设置合理 `responseInterval`，默认 500ms 已由 `LayerController` 提供。
+
+避免：
+
+- 在一个方法里混合资源加载、网络请求、UI 渲染、数据变更。
+- 使用魔法字符串事件名散落各处；大型功能应集中定义事件常量。
+- 同一资源路径在多个文件重复。
+- 在 `onDestroy` 外留下未清理定时器和事件。
+
+## cocos-mcp 工作流
+
+当任务涉及 UI 自动化：
+
+1. 调用 `cocos_mcp_diagnose` 检查连接和当前场景。
+2. 调用 `scene_get_tree({ includeDiagnostics: true })` 获取节点路径。
+3. 如果要绑定真实资源，先用 `asset_query` 或 `asset_resolve` 获取准确资源。
+4. 创建大结构用 `ui_create_tree`，小改动用 `ui_create_node`、`ui_set_node_props`、`ui_add_component`。
+5. 设置 SpriteFrame 用 `ui_set_sprite_frame`，不要猜 uuid。
+6. 创建 prefab 用 `prefab_create_from_tree` 或 `prefab_create_from_node`。
+7. 绑定按钮只在脚本组件和 handler 已存在时使用 `ui_bind_button_event`；否则让 `LayerController.cc()` 在代码中绑定。
+8. 完成后用 `scene_get_tree` 验证节点。
+9. 用户确认需要保存时调用 `scene_save`。
+
+## UI 自动化注意事项
+
+- MCP 节点路径必须是绝对路径，如 `/Canvas/ShopLayer/CloseButton`。
+- 不要随机选择同名资源；如果 `asset_resolve` 返回 ambiguous，必须让用户或上下文消歧。
+- 创建 UI 前确认 Canvas 和目标父节点存在。
+- 如果生成框架 Layer prefab，根节点应挂 `FW.Layer` 对应组件名，且 prefab 名应与 `layerAssetProperty.path` 对齐。
+- UI 代码中的节点名必须和 MCP 创建的节点名一致。
+
+## 完成前验证
+
+Codex 完成改动后应检查：
+
+- 没有修改 `assets/framework`。
+- 新业务类名满足注入约定。
+- `AssetConfig` 资源路径和 prefab 实际路径一致。
+- LayerController 的 `layerAssetProperty` 不为空。
+- 事件和定时器有生命周期清理。
+- TypeScript 没有明显类型错误。
+- 如果用 MCP 创建 UI，真实场景树里节点存在。

package/docs/CODEX_GUIDE.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "f0b82119-ca20-436b-b62c-502d61a98227",
+  "importer": "markdown",
+  "subMetas": {}
+}