@kkarum/framework 2.3.17 → 2.3.19

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": {}
+}

package/docs/UI_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,260 @@
+# UI Development Guide
+
+本文档定义基于本框架开发 UI 的标准做法。
+
+## UI 类型
+
+### 常驻层
+
+适合主界面、HUD、底部导航。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.PERMANENT;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.PERMANENT;
+```
+
+可使用：
+
+```ts
+this.hide();
+this.display();
+```
+
+框架会暂停/恢复节点系统事件、框架事件和定时器。
+
+### 普通 UI
+
+适合可重复打开的页面。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.REPEAT;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+```
+
+### 队列弹窗
+
+适合奖励弹窗、确认弹窗。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.POPUP_QUEUE;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.POPUP;
+```
+
+已有队列弹窗时，新弹窗会入队，当前弹窗关闭后再打开下一个。
+
+### 一次性弹窗
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.POPUP_DISPOSABLE;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.POPUP;
+```
+
+## LayerController 标准结构
+
+```ts
+export class InventoryLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+  layerType = FW.SystemDefine.FWLayerType.REPEAT;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  private closeButton: cc.Node;
+  private titleLabel: cc.Label;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<InventoryAssetConfig>().preLoad.prefab["InventoryLayer"] as FW.AssetProperty;
+  }
+
+  onInit(args?: any) {
+    this.cacheNodes();
+    this.bindEvents();
+    this.render();
+  }
+
+  private cacheNodes() {
+    this.closeButton = this.find("CloseButton", this.layer.node);
+    this.titleLabel = this.findComponent("TitleLabel", this.layer.node, cc.Label);
+  }
+
+  private bindEvents() {
+    this.cc(this.closeButton, this.onCloseClick);
+  }
+
+  private render() {
+    this.titleLabel.string = "Inventory";
+  }
+
+  private onCloseClick = () => {
+    this.close();
+  };
+}
+```
+
+## 节点查找
+
+推荐：
+
+```ts
+const node = this.find("CloseButton", this.layer.node);
+const label = this.findComponent("TitleLabel", this.layer.node, cc.Label);
+```
+
+可使用装饰器：
+
+```ts
+@FWPropertyNode({ path: "CloseButton" })
+private closeButton: cc.Node;
+
+@FWPropertyComponent(cc.Label, "TitleLabel")
+private titleLabel: cc.Label;
+```
+
+注意：
+
+- 装饰器改写 `onLoad`，更适合 Cocos Component。
+- LayerController 不是挂在节点上的 Cocos Component，优先使用 `find()`。
+
+## 事件绑定
+
+按钮：
+
+```ts
+this.cc(buttonNode, this.onButtonClick);
+```
+
+自定义事件：
+
+```ts
+this.fw("INVENTORY_CHANGED", this.render);
+```
+
+复杂：
+
+```ts
+this.registerEvent({
+  CCEvent: [{
+    target: buttonNode,
+    eventName: cc.Node.EventType.TOUCH_END,
+    responseInterval: 500,
+    cb: this.onButtonClick,
+  }],
+});
+```
+
+不要在 LayerController 中散落裸 `node.on()`。如必须使用，必须在关闭时手动 `off`。
+
+## 列表开发
+
+### 小列表
+
+可以直接实例化 item prefab，但仍应使用 `FW.Entry.resMgr` 加载资源。
+
+### 大列表
+
+优先使用：
+
+- `FWVirtualViewComponent`
+- `FWVirtuaScrollViewComponent`
+- `FW.Entry.objectMgr.createObjectPool()`
+
+`FWVirtualViewComponent` 常用字段：
+
+```ts
+list.onRender = (item, index) => {};
+list.onSelected = (item, index, lastIndex, selected?) => {};
+list.onPageChange = (item, page) => {};
+list.count = data.length;
+list.updateItem(index);
+list.updateAll();
+list.scrollTo(index, 0.3);
+list.prePage();
+list.nextPage();
+list.skipPage(page, 0.3);
+```
+
+## UI 与 Data 同步
+
+推荐方向：
+
+```text
+Logic -> Data -> evtMgr.dispatch -> LayerController.render
+```
+
+示例：
+
+```ts
+// Data
+setItems(items: Item[]) {
+  this.items = items;
+  FW.Entry.evtMgr.dispatch("INVENTORY_ITEMS_CHANGED", items);
+}
+
+// LayerController
+this.fw("INVENTORY_ITEMS_CHANGED", this.renderItems);
+```
+
+## 打开和关闭
+
+打开：
+
+```ts
+await FW.Entry.layerMgr.openAsync<InventoryLayerController>({
+  type: InventoryLayerController,
+  args: { selectedTab: 1 },
+});
+```
+
+关闭：
+
+```ts
+this.close();
+```
+
+关闭前异步处理：
+
+```ts
+async onClose() {
+  await this.playCloseAnimation();
+}
+```
+
+`FWLayerManager.close()` 会等待 `onClose()`，再销毁节点、释放资源、清理状态。
+
+## 资源释放
+
+LayerController 属性：
+
+```ts
+autoRelease = true;
+```
+
+关闭时，如果 `autoRelease` 为 true，框架会调用：
+
+```ts
+FW.Entry.resMgr.releaseAsset(ctr.layerData.layerAssetProperty);
+```
+
+注意：资源释放依赖 `AssetProperty.autoRelease` 和引用计数。不要手动释放还在使用的公共资源。
+
+## UI 自动化约定
+
+使用 cocos-mcp 创建 UI 时：
+
+- 根节点名与 prefab 名一致。
+- 交互节点名与代码一致。
+- 按钮节点含 `cc.Button` 和可视组件。
+- 文本节点含 `cc.Label`。
+- 滚动区域含 `cc.ScrollView`、`content`、`cc.Layout`。
+- 全屏根节点使用 `cc.Widget` stretch/full。
+
+## UI 质量检查
+
+完成 UI 功能前检查：
+
+- `layerAssetProperty` 能解析到有效 prefab。
+- `onInit()` 中所有 `find()` 节点存在。
+- 按钮不会重复注册。
+- 列表刷新不会无限实例化节点。
+- 关闭时没有未清理定时器。
+- 弹窗类型和渲染顺序符合用途。
+- `autoRelease` 与资源复用场景一致。

package/docs/UI_DEVELOPMENT_GUIDE.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "a1d8b0f1-89cd-4fad-be1a-84e8df02cb56",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs.meta

@@ -0,0 +1,13 @@
+{
+  "ver": "1.1.3",
+  "uuid": "1e0c55a2-93ba-4368-9b54-26c8d470d0ed",
+  "importer": "folder",
+  "isBundle": false,
+  "bundleName": "",
+  "priority": 1,
+  "compressionType": {},
+  "optimizeHotUpdate": {},
+  "inlineSpriteFrames": {},
+  "isRemoteBundle": {},
+  "subMetas": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkarum/framework",
-  "version": "2.3.17",
+  "version": "2.3.19",
   "description": "cocoscreator 2.x mvc framework",
   "main": "index.js",
   "keywords": [

package/service/http/FWHttp.ts

@@ -34,7 +34,22 @@ export class FWHttp extends FW.Service {
       FW.SystemDefine.FWHttpRequestType.POST,
     );
   }
-
+  protected async postApiMessage(
+    url: string,
+    params?: string,
+    headers?: string,
+    cb?: (response: string) => void,
+    tag?: string,
+  ): Promise<string> {
+    return this.processApi(
+      url,
+      params,
+      headers,
+      cb,
+      tag,
+      FW.SystemDefine.FWHttpRequestType.POST,
+    );
+  }
   private async process(
     url: string,
     params: string,
@@ -97,7 +112,71 @@ export class FWHttp extends FW.Service {
       tag ? `http request ->${tag}` : "",
     );
   }
+  private async processApi(
+    url: string,
+    params: string,
+    headers: string,
+    cb: (response: any) => void,
+    tag: string,
+    type: FW.SystemDefine.FWHttpRequestType,
+  ): Promise<string> {
+    let xhr: XMLHttpRequest;
+
+    const promiseProxy: FW.PromiseProxy<string> =
+      FW.Entry.promiseMgr.execute<string>(
+        (resolve, reject, signal, reason) => {
+          xhr = new XMLHttpRequest();
+
+          xhr.onreadystatechange = () => {
+            if (xhr.readyState !== 4) return;
 
+            if (xhr.status >= 200 && xhr.status < 300) {
+              cb?.(xhr.response);
+              resolve(xhr.response);
+              return;
+            }
+
+            const errMsg = `http request failed, status: ${xhr.status}, url: ${url}`;
+            FW.Log.warn(errMsg);
+            reject(errMsg);
+          };
+
+          xhr.onerror = (err: any) => {
+            FW.Log.error("http request error:", err);
+            this.onError?.(err);
+            reject(`http request error:${err}`);
+          };
+
+          xhr.ontimeout = () => {
+            this.onTimeout?.();
+            reject(`http request timeout!`);
+          };
+
+          xhr.open(type as string, url, true);
+          xhr.setRequestHeader("Content-Type", "application/json");
+          xhr.setRequestHeader("sign", headers);
+          xhr.send(params);
+        },
+        {
+          ...FWSystemConfig.PromiseConfig.http,
+          retryCondition(error, retryCount) {
+            return (
+              !!error &&
+              retryCount < (FWSystemConfig.PromiseConfig.http.retryCount || 0)
+            );
+          },
+        },
+      );
+
+    promiseProxy.addAbortEventListener(() => {
+      xhr.abort();
+    });
+
+    return await this.invoke(
+      promiseProxy.promise,
+      tag ? `http request ->${tag}` : "",
+    );
+  }
   onError?(err: any);
   onTimeout?();
 }