@kkarum/framework 2.3.17 → 2.3.19

package/README.md

@@ -1,93 +1,167 @@
-# 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
+
+`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,151 @@
+# Codex Guide
+
+本文档是 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": {}
+}

package/docs/ERROR_HANDLING.md

@@ -0,0 +1,233 @@
+# Error Handling
+
+本文档定义框架内业务错误处理、异步失败、资源失败和生命周期清理规范。
+
+## 日志
+
+统一使用 `FW.Log`：
+
+```ts
+FW.Log.debug("message");
+FW.Log.warn("warning", data);
+FW.Log.error("error", error);
+FW.Log.request("request", msg);
+FW.Log.response("response", msg);
+FW.Log.send("socket send", msg);
+FW.Log.receive("socket receive", msg);
+FW.Log.system("system", msg);
+```
+
+发布构建中框架会关闭 console 输出。业务代码不要自行覆盖 console。
+
+## FrameworkBase.invoke
+
+异步业务方法优先用 `invoke()`：
+
+```ts
+const result = await this.invoke(
+  FW.Entry.resMgr.loadAssetData(asset),
+  "loadAssetData",
+);
+
+if (!result) {
+  return;
+}
+```
+
+`invoke()` 会：
+
+- 记录开始和结束时间。
+- 上报到 `performanceMgr`。
+- 慢操作输出 warn。
+- 捕获异常并输出结构化错误。
+- 返回 `undefined`。
+
+调用方必须处理 `undefined`。
+
+## Promise 错误
+
+使用 `FW.Entry.promiseMgr.execute()` 时设置合理超时：
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute(resolveWork, {
+  timeout: 10000,
+  retryCount: 3,
+  retryInterval: 2,
+  retryCondition: (error, count) => true,
+});
+```
+
+取消：
+
+```ts
+proxy.abort("layer closed");
+```
+
+批量结果不会直接抛出所有错误，而是返回：
+
+```ts
+{
+  success: [{ id, value }],
+  failed: [{ id, reason }],
+  cancelled: [id]
+}
+```
+
+## 资源加载失败
+
+资源加载统一走 `FW.Entry.resMgr`。可注册拒绝处理器：
+
+```ts
+FW.Entry.resMgr.registerRejectHandler({
+  loadBundleHandler(error, bundleName) {
+    FW.Log.error("load bundle failed", bundleName, error);
+  },
+  loadResHandler(error, path) {
+    FW.Log.error("load resource failed", path, error);
+  },
+});
+```
+
+加载失败时：
+
+- 不继续操作节点。
+- 不调用 `getAsset()` 兜底。
+- UI 应显示空态、重试按钮或关闭弹窗。
+- Codex 不应通过修改框架资源管理器绕过错误。
+
+## Layer 错误
+
+`FWLayerManager.openAsync()` 失败时会：
+
+- 设置状态为 loading/opening。
+- 失败后移除状态。
+- 清理失败的 Layer 注册。
+- 抛出错误。
+
+业务调用：
+
+```ts
+try {
+  await FW.Entry.layerMgr.openAsync({ type: RewardLayerController });
+} catch (error) {
+  FW.Log.error("open reward layer failed", error);
+}
+```
+
+`openSync()` 失败通常返回 `undefined`，调用方必须判断。
+
+## Socket 错误
+
+Socket 错误处理在 `Handle` 中实现：
+
+```ts
+onError(msg: any) {
+  FW.Log.error("socket error", msg);
+}
+
+onTimeout() {
+  FW.Entry.evtMgr.dispatch("SOCKET_TIMEOUT");
+}
+
+onWeakNetWork() {
+  FW.Entry.evtMgr.dispatch("SOCKET_WEAK_NETWORK");
+}
+
+onClose() {
+  FW.Entry.evtMgr.dispatch("SOCKET_CLOSED");
+}
+```
+
+框架会处理：
+
+- 心跳发送。
+- 弱网检测。
+- 心跳超时重连。
+- 最大重连次数。
+- 协议轮询清理。
+
+业务不要重复实现底层重连循环。
+
+## 事件清理
+
+LayerController 销毁时，框架会调用：
+
+```ts
+FW.Entry.timeMgr.unSchedule(this);
+FW.Entry.evtMgr.targetOff(this);
+this.layer?.unscheduleAllCallbacks();
+this.layer?.node?.stopAllActions();
+this.layer?.node?.destroy();
+```
+
+普通对象或非 Layer 组件必须自行清理：
+
+```ts
+onDestroy() {
+  FW.Entry.evtMgr.targetOff(this);
+  FW.Entry.timeMgr.unSchedule(this);
+}
+```
+
+UI 事件使用 `uiMgr.register()` 后，可用：
+
+```ts
+FW.Entry.uiMgr.unRegisterTarget(target);
+```
+
+## 定时器清理
+
+创建定时器时传 target：
+
+```ts
+FW.Entry.timeMgr.schedule(this.tick, 1, cc.macro.REPEAT_FOREVER, this);
+```
+
+销毁时：
+
+```ts
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+禁止使用无 target 的长期定时器，除非它属于全局系统并有明确 tag。
+
+## 空值和节点有效性
+
+操作 Cocos 节点前检查：
+
+```ts
+if (!cc.isValid(node)) {
+  FW.Log.warn("node invalid");
+  return;
+}
+```
+
+`FW.Entry.uiMgr.find()` 找不到节点会返回 `null` 并打印 warn。业务代码要处理：
+
+```ts
+const button = this.find("ConfirmButton", this.layer.node);
+if (!button) return;
+```
+
+## 错误边界
+
+推荐分层处理：
+
+- 网络层：解析、连接、超时错误。
+- Logic：业务失败和重试。
+- Data：不抛 UI 错误。
+- LayerController：展示失败状态、关闭或重试。
+
+不要让底层错误直接导致 UI 生命周期中断且没有日志。
+
+## Codex 错误处理清单
+
+生成代码时必须检查：
+
+- 每个 `await` 的失败路径是否可接受。
+- `invoke()` 返回 `undefined` 时是否处理。
+- `openSync()` 返回空是否处理。
+- 节点查找失败是否处理。
+- 事件和定时器是否随 target 清理。
+- 资源路径是否来自 `AssetConfig`。
+- Socket 错误是否在 `Handle` 中有入口。

package/docs/ERROR_HANDLING.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "a955657c-a1bb-4b4a-b218-f17ff5649eb3",
+  "importer": "markdown",
+  "subMetas": {}
+}