@kkarum/framework 2.3.18 → 2.3.20

package/docs/FRAMEWORK_USAGE.md

@@ -0,0 +1,344 @@
+# Framework Usage
+
+## AI 工具使用约定
+
+Codex / AI 工具生成业务代码时必须遵守：
+
+- `AssetConfig` 资源读取使用点访问，例如 `preLoad.prefab.ShopLayer`；不要使用 `preLoad.prefab["ShopLayer"]`。
+- `LayerController` 不负责查找节点和组件。节点使用 `FWPropertyNode`、组件使用 `FWPropertyComponent`，统一定义在对应 `FW.Layer` 组件中，变量名与节点名一致。
+- `invoke()` 默认不在业务层使用。只有用户明确要求性能记录、错误包装或特殊异步治理时才调用。
+- 新增业务 bundle 必须提供 `FW.Registry` 注册表，并在文件末尾调用 `FW.Framework.addRegistry()`。`bundleName` 与 `addRegistry()` 的 bundle key 必须完全一致，统一使用小写 bundle 名。
+
+示例：
+
+```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 {
+  get layerAssetProperty(): FW.AssetProperty {
+    return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+  }
+
+  onInit() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+  }
+}
+```
+
+本文档给出业务开发时的实际用法和推荐流程。
+
+## 基本规则
+
+- 所有框架能力从 `FW.Entry` 进入。
+- 业务组件继承框架基类：`FW.Logic`、`FW.Data`、`FW.AssetConfig`、`FW.Sender`、`FW.Handle`、`FW.LayerController`。
+- 每个 bundle 使用 `FW.Registry` 注册自身组件。
+- 异步资源走 `FW.Entry.resMgr`。
+- UI 打开关闭走 `FW.Entry.layerMgr`。
+- 事件绑定走 `LayerController.registerEvent()`、`cc()`、`fw()` 或 `FW.Entry.evtMgr`。
+- 定时器走 `FW.Entry.timeMgr`。
+- 可取消/带重试异步流程走 `FW.Entry.promiseMgr`。
+
+## 新增业务 Bundle
+
+推荐目录结构：
+
+```text
+assets/<bundle>/
+  config/<Bundle>AssetConfig.ts
+  data/<Bundle>Data.ts
+  logic/<Bundle>Logic.ts
+  registry/<Bundle>Registry.ts
+  ui/<Feature>/<Feature>LayerController.ts
+  prefab/<Feature>Layer.prefab
+```
+
+注册类示例：
+
+```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"`。
+- `FW.Framework.addRegistry("register", RegisterRegistry)` 必须与 `bundleName` 完全一致。
+- `logic/data/config/sender/handle` 字段必须显式声明为对应 `FW.Newable<...>` 类型。
+- 只声明实际存在的业务组件，不要为了占位声明空的 Data/Sender/Handle。
+
+业务组件命名必须包含 bundle 名，并以 `Logic/Data/Config/Sender/Handle` 结尾。`FrameworkBase.initializeDependencies()` 会按类名推断 bundle 和组件类型。
+
+## Logic
+
+`Logic` 放业务流程，不持有复杂 UI 节点引用。
+
+```ts
+export class ShopLogic extends FW.Logic {
+  initialize() {
+    // 初始化轻量状态，避免在构造阶段访问尚未加载的资源节点。
+  }
+
+  async refreshGoods() {
+    return this.getSender<ShopSender>().sendGetGoods();
+  }
+}
+```
+
+规范：
+
+- 默认直接 `await` 或 `return` 异步业务方法，不使用 `this.invoke()`。
+- 只有用户明确要求性能记录、错误包装或特殊异步治理时才使用 `this.invoke()`。
+- 业务数据写入 `this.getData<ShopData>()`。
+- UI 通知用 `FW.Entry.evtMgr.dispatch()`。
+- 不直接加载 prefab 打开 UI，应调用 `FW.Entry.layerMgr`。
+
+## Data
+
+`Data` 保存业务状态，避免混入 UI 节点。
+
+```ts
+export class ShopData extends FW.Data {
+  goods: GoodsItem[] = [];
+
+  setGoods(list: GoodsItem[]) {
+    this.goods = list || [];
+    FW.Entry.evtMgr.dispatch("SHOP_GOODS_CHANGED", this.goods);
+  }
+}
+```
+
+规范：
+
+- `Data` 不发起网络请求。
+- `Data` 不操作 Cocos 节点。
+- 对外提供明确方法，不鼓励外部到处直接改字段。
+
+## AssetConfig
+
+资源地址统一放在 Config。
+
+```ts
+export class ShopAssetConfig extends FW.AssetConfig {
+  preLoad: FW.LoadConfig = {
+    prefab: {
+      ShopLayer: {
+        bundle: "shop",
+        path: "prefab/ShopLayer",
+        type: cc.Prefab,
+        priorityLoaded: true,
+        autoRelease: true,
+      },
+    },
+  };
+
+  demandLoad: FW.LoadConfig = {
+    texture: {
+      IconCoin: {
+        bundle: "shop",
+        path: "texture/icon_coin",
+        type: cc.Texture2D,
+      },
+    },
+  };
+}
+```
+
+使用：
+
+```ts
+const cfg = FW.Entry.getComponent<ShopAssetConfig>(ShopAssetConfig);
+const prefab = await FW.Entry.resMgr.loadAsset<cc.Prefab>(
+  cfg.preLoad.prefab["ShopLayer"] as FW.AssetProperty,
+);
+```
+
+## LayerController
+
+UI 控制器示例：
+
+```ts
+export class ShopLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+  layerType = FW.SystemDefine.FWLayerType.REPEAT;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<ShopAssetConfig>().preLoad.prefab["ShopLayer"] as FW.AssetProperty;
+  }
+
+  onInit(args?: { tab?: string }) {
+    const closeBtn = this.find("CloseButton", this.layer.node);
+    this.cc(closeBtn, this.onCloseClick);
+    this.fw("SHOP_GOODS_CHANGED", this.renderGoods);
+  }
+
+  private onCloseClick = () => {
+    this.close();
+  };
+
+  private renderGoods = (goods: GoodsItem[]) => {
+    // 更新 UI
+  };
+}
+```
+
+打开：
+
+```ts
+await FW.Entry.layerMgr.openAsync<ShopLayerController>({
+  type: ShopLayerController,
+  args: { tab: "hot" },
+});
+```
+
+## 资源加载
+
+```ts
+const sf = await FW.Entry.resMgr.loadAsset<cc.SpriteFrame>({
+  bundle: "shop",
+  path: "texture/icon_coin",
+  type: cc.Texture2D,
+});
+```
+
+注意：
+
+- 传入 `cc.Texture2D` 时，`FWResManager` 默认会包装成 `cc.SpriteFrame`。
+- 如果只要原始 Texture，使用 `loadAsset(assetProperty, true)`。
+- 同步 `getAsset()` 只能用于已加载资源，否则会报错。
+
+## 事件注册
+
+优先使用控制器便捷方法：
+
+```ts
+this.cc(this.find("BuyButton", this.layer.node), this.onBuyClick);
+this.fw("SHOP_GOODS_CHANGED", this.renderGoods);
+```
+
+复杂事件：
+
+```ts
+this.registerEvent({
+  CCEvent: [{
+    target: buyButton,
+    eventName: cc.Node.EventType.TOUCH_END,
+    responseInterval: 500,
+    cb: this.onBuyClick,
+  }],
+  FWEvent: [{
+    eventName: "SHOP_REFRESH",
+    responseInterval: 200,
+    cb: this.onRefresh,
+  }],
+});
+```
+
+销毁时 LayerController 会清理自身事件，普通对象必须调用 `FW.Entry.evtMgr.targetOff(target)` 或通过框架管理生命周期。
+
+## 定时器
+
+```ts
+const schedule = FW.Entry.timeMgr.scheduleOnce(() => {
+  this.refreshGoods();
+}, 1, this);
+
+FW.Entry.timeMgr.schedule(
+  () => this.tick(),
+  0.5,
+  cc.macro.REPEAT_FOREVER,
+  this,
+  "shop_tick",
+);
+
+FW.Entry.timeMgr.unSchedule(this);
+```
+
+不要直接使用 `setTimeout`、`setInterval` 管理业务定时器。
+
+## Promise
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute<string>((resolve, reject, signal) => {
+  // 异步操作
+  signal.addEventListener("abort", () => {
+    // 清理
+  });
+}, {
+  timeout: 10000,
+  retryCount: 3,
+  retryInterval: 2,
+});
+
+const result = await proxy.promise;
+```
+
+需要取消时：
+
+```ts
+proxy.abort("layer closed");
+```
+
+## Socket
+
+业务 bundle 可注册 `Sender` 和 `Handle`：
+
+```ts
+export class GameSender extends FW.Sender {
+  sendHeart() {
+    this.send(JSON.stringify({ cmd: "heart" }));
+  }
+
+  async onHeart(msg: any) {
+    return JSON.parse(msg).cmd === "heart";
+  }
+
+  async onBeforeSendingMessage(msg: any) {
+    return typeof msg === "string" ? msg : JSON.stringify(msg);
+  }
+
+  getProtocolKey(msg: any) {
+    return JSON.parse(msg).seq;
+  }
+}
+```
+
+```ts
+export class GameHandle extends FW.Handle {
+  async onBeforeReceivingMessage(event: MessageEvent) {
+    return JSON.parse(event.data);
+  }
+
+  onMessage(msg: any) {
+    FW.Entry.evtMgr.dispatch(`SOCKET_${msg.cmd}`, msg);
+  }
+
+  async onHeart(msg: any) {
+    return msg.cmd === "heart";
+  }
+
+  getProtocolKey(msg: any) {
+    return msg.seq;
+  }
+}
+```
+
+创建连接走 `FW.Entry.socketMgr.createSocket()`，不要直接 new `WebSocket`。

package/docs/FRAMEWORK_USAGE.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "6a4c7da4-306c-4eea-9d3b-aa499018e592",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs/MCP_INTEGRATION.md

@@ -0,0 +1,241 @@
+# MCP Integration
+
+本文档说明如何配合 cocos-mcp 进行 UI 自动化开发，并让生成的 UI 与本框架协作。
+
+## 适用范围
+
+cocos-mcp 用于：
+
+- 读取当前 Cocos 场景树。
+- 创建 UI 节点树。
+- 添加 Cocos 白名单组件。
+- 绑定 SpriteFrame。
+- 实例化 prefab。
+- 创建 prefab 资源。
+- 保存场景。
+
+框架代码用于：
+
+- 定义业务 LayerController。
+- 管理 Layer 打开/关闭。
+- 绑定运行时事件。
+- 管理资源生命周期。
+
+二者分工：MCP 负责编辑器里的节点和资源，框架负责运行时行为。
+
+## 推荐流程
+
+### 1. 诊断连接
+
+```text
+cocos_mcp_diagnose
+```
+
+确认：
+
+- WebSocket bridge reachable。
+- 当前场景已打开。
+- Canvas 存在。
+- Cocos Creator 版本兼容。
+
+### 2. 获取真实场景树
+
+```text
+scene_get_tree({
+  includeDiagnostics: true,
+  maxDepth: 6
+})
+```
+
+禁止猜测节点路径。后续 MCP 操作必须使用绝对路径，例如 `/Canvas/MainLayer/CloseButton`。
+
+### 3. 查询或解析资源
+
+```text
+asset_query({
+  pattern: "db://assets/**/*.png",
+  type: "sprite-frame"
+})
+```
+
+或：
+
+```text
+asset_resolve({
+  path: "assets/shop/texture/icon_coin.png",
+  type: "sprite-frame"
+})
+```
+
+规则：
+
+- 资源缺失时不要继续绑定。
+- 多个候选时不要随机选择。
+- 使用 Sprite 时绑定 `sprite-frame`，不是 texture 原图。
+
+### 4. 创建 UI 树
+
+大结构使用 `ui_create_tree`：
+
+```json
+{
+  "root": "/Canvas",
+  "tree": {
+    "name": "ShopLayer",
+    "props": { "width": 720, "height": 1280, "x": 0, "y": 0 },
+    "components": [
+      { "type": "cc.Widget", "props": { "isAlignTop": true, "isAlignBottom": true, "isAlignLeft": true, "isAlignRight": true } }
+    ],
+    "children": [
+      {
+        "name": "CloseButton",
+        "props": { "width": 96, "height": 96, "x": 300, "y": 560 },
+        "components": [
+          { "type": "cc.Button" },
+          { "type": "cc.Sprite" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+小改动使用：
+
+- `ui_create_node`
+- `ui_set_node_props`
+- `ui_add_component`
+- `ui_set_component_props`
+- `ui_apply_widget`
+- `ui_apply_layout`
+
+### 5. 绑定图片
+
+```text
+ui_set_sprite_frame({
+  nodePath: "/Canvas/ShopLayer/CloseButton",
+  asset: {
+    url: "db://assets/shop/texture/close.png",
+    type: "sprite-frame"
+  },
+  addComponentIfMissing: true
+})
+```
+
+### 6. 生成 prefab
+
+如果 UI 是运行时 Layer，推荐保存为 prefab：
+
+```text
+prefab_create_from_node({
+  nodePath: "/Canvas/ShopLayer",
+  url: "db://assets/shop/prefab/ShopLayer.prefab",
+  overwrite: true
+})
+```
+
+然后在 `ShopAssetConfig` 中声明：
+
+```ts
+ShopLayer: {
+  bundle: "shop",
+  path: "prefab/ShopLayer",
+  type: cc.Prefab,
+  priorityLoaded: true,
+  autoRelease: true,
+}
+```
+
+### 7. 运行时代码绑定事件
+
+优先在 `LayerController` 中绑定：
+
+```ts
+onInit() {
+  this.cc(this.find("CloseButton", this.layer.node), this.onCloseClick);
+}
+```
+
+只有当目标节点上已经有脚本组件和 handler 时，才使用 MCP 的 `ui_bind_button_event`。
+
+## Layer prefab 约定
+
+用于 `FW.Entry.layerMgr` 的 prefab 应满足：
+
+- 根节点名和资源名清晰对应，例如 `ShopLayer`。
+- 根节点挂载 `FW.Layer` 或业务继承的 Layer 组件。
+- 控制器类不挂在节点上，由 `FWLayerManager` 创建并绑定到 `layer.ctr`。
+- prefab 资源路径与 `AssetConfig` 一致。
+- 需要全屏适配时根节点使用 `cc.Widget` full/stretch。
+
+## UI 节点命名约定
+
+推荐：
+
+- `CloseButton`
+- `ConfirmButton`
+- `CancelButton`
+- `TitleLabel`
+- `GoodsScrollView`
+- `Content`
+- `ItemTemplate`
+- `IconSprite`
+
+避免：
+
+- `node1`
+- `btn`
+- 中文节点名
+- 与多个兄弟节点重复的名字
+
+原因：`LayerController.find()` 和装饰器依赖节点名查找。重复或含义不明的节点会降低自动化可靠性。
+
+## Codex + MCP 协作模板
+
+当用户要求“创建一个商店弹窗”：
+
+1. 用 MCP 读取场景树，确认 `/Canvas`。
+2. 用 MCP 创建 `ShopLayer` 节点树。
+3. 查询资源并绑定 SpriteFrame。
+4. 保存为 `assets/shop/prefab/ShopLayer.prefab`。
+5. 在业务代码新增 `ShopLayerController`。
+6. 在 `ShopAssetConfig` 声明 prefab。
+7. 用 `this.cc()` 绑定 `CloseButton`、`BuyButton`。
+8. 用 `FW.Entry.layerMgr.openAsync({ type: ShopLayerController })` 打开。
+
+## 干运行和验证
+
+优先使用 `dryRun: true` 验证高风险操作：
+
+- 删除节点。
+- 覆盖 prefab。
+- 批量创建大树。
+- 绑定不确定资源。
+
+完成后验证：
+
+```text
+scene_get_tree({ includeDiagnostics: true, maxDepth: 8 })
+```
+
+检查：
+
+- 节点路径存在。
+- 组件存在。
+- SpriteFrame 已绑定。
+- prefab 已生成。
+- 没有多余测试节点遗留。
+
+## 保存策略
+
+不要在用户未确认时随意保存场景。以下情况可保存：
+
+- 用户明确要求保存。
+- 当前任务目标就是生成 prefab 或落地 UI。
+- 已完成验证且保存是任务必要结果。
+
+保存使用：
+
+```text
+scene_save()
+```

package/docs/MCP_INTEGRATION.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "3ef5e4b7-ab3c-4792-b365-533e6193a30c",
+  "importer": "markdown",
+  "subMetas": {}
+}