@mclawnet/agent 0.6.20 → 0.6.22

package/skills/cocos-creator-3x-cn/references/language/performance.md

@@ -0,0 +1,363 @@
+# 性能优化指南 — Cocos Creator 3.8
+
+> 📖 本文件为 `cocos-creator-3x-cn` 技能参考文件，提供性能优化的全面指导。
+
+---
+
+## 1. 性能优化层次
+
+```
+┌─────────────────────────────────────┐
+│         架构层优化 (影响最大)         │
+│  对象池、资源管理、加载策略           │
+├─────────────────────────────────────┤
+│         渲染层优化                   │
+│  Draw Call、合批、纹理压缩           │
+├─────────────────────────────────────┤
+│         逻辑层优化                   │
+│  算法、缓存、调度频率               │
+├─────────────────────────────────────┤
+│         内存层优化 (基础保障)         │
+│  GC 减压、引用管理、泄漏预防        │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 2. 渲染性能
+
+### 2.1 Draw Call 优化
+
+```typescript
+// 1. 使用图集（SpriteAtlas）合并碎图
+// 同一图集 + 同一材质 + 相邻渲染顺序 = 自动合批
+
+// 2. 合理规划渲染层级，避免合批打断
+// ❌ 打断合批的排列：
+// Sprite(Atlas_A) → Sprite(Atlas_B) → Sprite(Atlas_A)
+// ✅ 友好排列：
+// Sprite(Atlas_A) → Sprite(Atlas_A) → Sprite(Atlas_B)
+
+// 3. 减少 Mask 使用（每个 Mask 增加 2 个 draw call）
+
+// 4. Label 优化
+// - 使用 BMFont 替代系统字体
+// - 静态文本使用 BITMAP 缓存模式
+// - 频繁更新的文本使用 CHAR 缓存模式
+```
+
+### 2.2 纹理优化
+
+```
+纹理规范:
+- 使用 2 的幂次方尺寸（256/512/1024/2048）
+- 尽量使用图集而非散图
+- 大面积背景考虑使用 JPEG + 单独 Alpha 通道
+- 移动端使用压缩纹理格式（ASTC/ETC2/PVRTC）
+- UI 图集建议不超过 2048x2048
+```
+
+### 2.3 节点树优化
+
+```typescript
+// 1. 不可见节点设为 inactive（跳过整棵子树）
+node.active = false; // ✅ 比 opacity = 0 更高效
+
+// 2. 减少节点树深度
+// 扁平化结构比深层嵌套更高效
+
+// 3. 避免频繁增删节点
+// 使用对象池 + active 控制显隐
+```
+
+---
+
+## 3. 内存优化
+
+### 3.1 对象池模式
+
+```typescript
+import { NodePool, instantiate, Prefab, Node } from 'cc';
+
+class ObjectPool {
+    private _pool: NodePool;
+    private _prefab: Prefab;
+
+    constructor(prefab: Prefab, name: string, initCount = 10) {
+        this._prefab = prefab;
+        this._pool = new NodePool(name);
+        // 预热
+        for (let i = 0; i < initCount; i++) {
+            this._pool.put(instantiate(prefab));
+        }
+    }
+
+    public get(): Node {
+        return this._pool.size() > 0
+            ? this._pool.get()!
+            : instantiate(this._prefab);
+    }
+
+    public put(node: Node): void {
+        this._pool.put(node);
+    }
+
+    public clear(): void {
+        this._pool.clear();
+    }
+
+    public get size(): number {
+        return this._pool.size();
+    }
+}
+```
+
+### 3.2 避免 GC 抖动
+
+```typescript
+// ❌ 每帧创建临时对象
+protected update(dt: number): void {
+    const dir = new Vec3(1, 0, 0);
+    Vec3.multiplyScalar(dir, dir, this.speed * dt);
+    this.node.position = this.node.position.add(dir);
+}
+
+// ✅ 复用预分配对象
+private _tempDir = new Vec3();
+private _tempPos = new Vec3();
+
+protected update(dt: number): void {
+    Vec3.set(this._tempDir, 1, 0, 0);
+    Vec3.multiplyScalar(this._tempDir, this._tempDir, this.speed * dt);
+    Vec3.add(this._tempPos, this.node.position, this._tempDir);
+    this.node.setPosition(this._tempPos);
+}
+```
+
+### 3.3 数组操作优化
+
+```typescript
+// ❌ 频繁 splice 删除（触发数组重排）
+for (let i = arr.length - 1; i >= 0; i--) {
+    if (arr[i].dead) arr.splice(i, 1);
+}
+
+// ✅ 交换删除法（无需重排）
+function swapRemove<T>(arr: T[], index: number): void {
+    arr[index] = arr[arr.length - 1];
+    arr.pop();
+}
+
+// ✅ 标记-清除（批量处理）
+const alive: Enemy[] = [];
+for (const e of enemies) {
+    if (!e.dead) alive.push(e);
+}
+enemies.length = 0;
+enemies.push(...alive);
+```
+
+### 3.4 字符串优化
+
+```typescript
+// ❌ 频繁字符串拼接
+let result = '';
+for (const item of items) {
+    result += item.name + ',';
+}
+
+// ✅ 使用数组 join
+const parts: string[] = [];
+for (const item of items) {
+    parts.push(item.name);
+}
+const result = parts.join(',');
+```
+
+---
+
+## 4. 逻辑优化
+
+### 4.1 更新频率控制
+
+```typescript
+// ❌ 所有逻辑都放 update（每帧执行）
+protected update(dt: number): void {
+    this.checkEnemies();    // 不需要每帧
+    this.updateUI();        // 不需要每帧
+    this.movePlayer(dt);    // 需要每帧
+}
+
+// ✅ 低频逻辑使用 schedule
+protected start(): void {
+    this.schedule(this.checkEnemies, 0.5);  // 每 0.5 秒
+    this.schedule(this.updateUI, 0.1);      // 每 0.1 秒
+}
+
+protected update(dt: number): void {
+    this.movePlayer(dt);  // 仅高频逻辑
+}
+```
+
+### 4.2 计算缓存
+
+```typescript
+// ❌ 重复计算
+update() {
+    const dist = Vec3.distance(this.node.position, this.target.position);
+    if (dist < 100) { /* ... */ }
+}
+
+// ✅ 使用距离平方比较（避免 sqrt）
+private readonly RANGE_SQ = 100 * 100;
+update() {
+    const distSq = Vec3.squaredDistance(this.node.position, this.target.position);
+    if (distSq < this.RANGE_SQ) { /* ... */ }
+}
+```
+
+### 4.3 查找优化
+
+```typescript
+// ❌ 每帧 find/getComponent
+protected update(): void {
+    const player = find('Canvas/Player');
+    const hp = player?.getComponent(HealthBar);
+}
+
+// ✅ onLoad/start 中缓存
+private _player: Node | null = null;
+private _hp: HealthBar | null = null;
+
+protected start(): void {
+    this._player = find('Canvas/Player');
+    this._hp = this._player?.getComponent(HealthBar) ?? null;
+}
+```
+
+### 4.4 条件判断优化
+
+```typescript
+// ✅ 提前返回减少嵌套
+protected update(dt: number): void {
+    if (!this._isPlaying) return;
+    if (!this._target?.isValid) return;
+    
+    // 核心逻辑
+}
+
+// ✅ 高概率条件前置
+if (commonCase) {
+    // 最可能的分支
+} else if (lessCommon) {
+    // ...
+} else {
+    // 极少情况
+}
+```
+
+---
+
+## 5. 加载性能
+
+### 5.1 资源预加载
+
+```typescript
+// 场景预加载
+director.preloadScene('GameScene', (err) => {
+    // 预加载完成，切换更快
+    director.loadScene('GameScene');
+});
+
+// 资源预加载
+resources.preload('prefabs/boss', Prefab);
+resources.preload('audio/battle', AudioClip);
+```
+
+### 5.2 分帧加载
+
+```typescript
+// 大量节点分帧创建，避免单帧卡顿
+private async createItems(count: number, prefab: Prefab, parent: Node): Promise<void> {
+    const BATCH = 5; // 每帧创建 5 个
+    for (let i = 0; i < count; i++) {
+        const node = instantiate(prefab);
+        parent.addChild(node);
+        if ((i + 1) % BATCH === 0) {
+            await this.nextFrame(); // 等待下一帧
+        }
+    }
+}
+
+private nextFrame(): Promise<void> {
+    return new Promise(resolve => {
+        this.scheduleOnce(resolve, 0);
+    });
+}
+```
+
+### 5.3 Bundle 按需加载
+
+```typescript
+// 根据游戏进度加载资源
+private async loadLevel(level: number): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        assetManager.loadBundle(`level_${level}`, (err, bundle) => {
+            if (err) { reject(err); return; }
+            bundle.loadScene('main', (err, scene) => {
+                if (err) { reject(err); return; }
+                director.runScene(scene);
+                resolve();
+            });
+        });
+    });
+}
+```
+
+---
+
+## 6. 性能监测
+
+### 6.1 帧率监控
+
+```typescript
+import { director, game } from 'cc';
+
+// 设置目标帧率
+game.frameRate = 60;
+
+// 获取当前帧间隔
+const dt = director.getDeltaTime();
+const currentFPS = 1 / dt;
+```
+
+### 6.2 调试工具
+
+```
+Chrome DevTools 性能分析:
+1. Performance 面板 → 录制游戏片段
+2. 查看 Scripting/Rendering/GC 时间占比
+3. 关注长任务（>16ms）
+
+Cocos Creator 调试面板:
+- 菜单栏 → 开发者 → 调试面板
+- 查看 Draw Call、Node Count、Triangles 等指标
+```
+
+---
+
+## 7. 性能优化清单
+
+| 优先级 | 检查项 | 目标 |
+|--------|--------|------|
+| P0 | Draw Call 数量 | 2D 游戏 < 50, 可试玩广告 < 30 |
+| P0 | 帧率稳定性 | ≥ 30fps, 目标 60fps |
+| P0 | 内存占用 | 移动端 < 150MB |
+| P1 | 图集使用率 | > 70% 使用率 |
+| P1 | 对象池覆盖 | 频繁创建/销毁的节点使用池 |
+| P1 | 事件泄漏 | on/off 严格配对 |
+| P2 | 临时对象分配 | update 中零分配 |
+| P2 | 查找调用缓存 | find/getComponent 缓存结果 |
+| P2 | 低频逻辑分离 | 从 update 移到 schedule |
+| P3 | 资源按需加载 | 使用 Bundle 分模块 |
+| P3 | 压缩纹理 | 启用平台对应格式 |

package/skills/cocos-creator-3x-cn/references/language/quality-hygiene.md

@@ -0,0 +1,307 @@
+# TypeScript 代码质量与卫生规范 — Cocos Creator 3.8
+
+> 📖 本文件为 `cocos-creator-3x-cn` 技能参考文件，提供 TypeScript 代码质量规范。
+
+---
+
+## 1. 导入规范
+
+### 1.1 模块导入
+
+```typescript
+// ✅ 正确：从 'cc' 统一导入
+import { _decorator, Component, Node, Vec3, Sprite, SpriteFrame, resources } from 'cc';
+const { ccclass, property } = _decorator;
+
+// ✅ 正确：环境宏从 'cc/env' 导入
+import { DEBUG, EDITOR, PREVIEW, BUILD } from 'cc/env';
+
+// ❌ 错误：不使用 cc. 全局前缀（3.x 中不存在）
+// const node = new cc.Node();
+
+// ✅ 按需导入第三方库
+import { someUtil } from '../utils/SomeUtil';
+```
+
+### 1.2 导入顺序
+
+```typescript
+// 1. 引擎核心模块
+import { _decorator, Component, Node, Vec3 } from 'cc';
+import { DEBUG } from 'cc/env';
+
+// 2. 引擎 UI/渲染组件
+import { Sprite, Label, Button } from 'cc';
+
+// 3. 项目公共模块
+import { EventDispatcher } from '../common/EventDispatcher';
+import { GameConfig } from '../config/GameConfig';
+
+// 4. 当前模块相关
+import { PlayerData } from './PlayerData';
+```
+
+---
+
+## 2. 命名规范
+
+| 类别 | 规范 | 示例 |
+|------|------|------|
+| 类名 | PascalCase | `PlayerController`, `GameManager` |
+| cc 类名 | 与类名一致 | `@ccclass('PlayerController')` |
+| 方法名 | camelCase | `moveForward()`, `onTouchStart()` |
+| 属性名 | camelCase | `moveSpeed`, `targetNode` |
+| 私有成员 | _camelCase | `_isMoving`, `_cachedPos` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_HEALTH`, `MOVE_SPEED` |
+| 枚举名 | PascalCase | `GameState`, `Direction` |
+| 枚举值 | PascalCase | `GameState.Playing` |
+| 事件名 | kebab-case | `'game-over'`, `'level-up'` |
+| 文件名 | PascalCase (与类名一致) | `PlayerController.ts` |
+
+---
+
+## 3. 类型安全
+
+### 3.1 属性声明
+
+```typescript
+// ✅ 使用联合类型 + null 初始值
+@property(Node)
+targetNode: Node | null = null;
+
+// ✅ 使用非空断言（确保在编辑器中赋值）
+@property(Sprite)
+readonly sprite!: Sprite;
+
+// ✅ 数组初始化
+@property({ type: [Node] })
+waypoints: Node[] = [];
+
+// ❌ 避免 any
+// @property
+// data: any = null;
+```
+
+### 3.2 Null 安全
+
+```typescript
+// ✅ 使用可选链
+const pos = this.targetNode?.position;
+const sprite = this.node.getComponent(Sprite)?.spriteFrame;
+
+// ✅ 空值合并
+const speed = this.config?.speed ?? 10;
+
+// ✅ 提前返回
+private onTouchStart(event: EventTouch): void {
+    if (!this.targetNode) return;
+    // 安全使用 this.targetNode
+}
+
+// ✅ 非空断言（仅在确信不为空时）
+const label = this.getComponent(Label)!;
+```
+
+### 3.3 枚举使用
+
+```typescript
+import { Enum } from 'cc';
+
+// 需要在编辑器面板显示的枚举
+enum GameState {
+    Idle = 0,
+    Playing = 1,
+    Paused = 2,
+    GameOver = 3,
+}
+Enum(GameState); // 注册到 cc 枚举系统
+
+@ccclass('GameManager')
+export class GameManager extends Component {
+    @property({ type: GameState })
+    state: GameState = GameState.Idle;
+}
+
+// 仅代码使用的枚举，可用 const enum（编译后内联为数值）
+const enum Direction {
+    Up = 0,
+    Down = 1,
+    Left = 2,
+    Right = 3,
+}
+```
+
+---
+
+## 4. 生命周期卫生
+
+### 4.1 事件监听配对
+
+```typescript
+// ✅ 正确：onEnable / onDisable 严格配对
+protected onEnable(): void {
+    input.on(Input.EventType.TOUCH_START, this.onTouchStart, this);
+    input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
+    this.node.on(Node.EventType.TOUCH_START, this.onNodeTouch, this);
+}
+
+protected onDisable(): void {
+    input.off(Input.EventType.TOUCH_START, this.onTouchStart, this);
+    input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
+    this.node.off(Node.EventType.TOUCH_START, this.onNodeTouch, this);
+}
+```
+
+### 4.2 资源引用管理
+
+```typescript
+@ccclass('ResourceHolder')
+export class ResourceHolder extends Component {
+    private _loadedAssets: Asset[] = [];
+
+    public loadAsset(path: string, type: typeof Asset): void {
+        resources.load(path, type, (err, asset) => {
+            if (err) return;
+            asset.addRef();
+            this._loadedAssets.push(asset);
+        });
+    }
+
+    protected onDestroy(): void {
+        // 释放所有持有的资源
+        for (const asset of this._loadedAssets) {
+            asset.decRef();
+        }
+        this._loadedAssets.length = 0;
+    }
+}
+```
+
+### 4.3 定时器清理
+
+```typescript
+protected onDestroy(): void {
+    this.unscheduleAllCallbacks();
+    Tween.stopAllByTarget(this.node);
+}
+```
+
+---
+
+## 5. 代码组织
+
+### 5.1 文件结构
+
+```
+assets/scripts/
+├── common/              # 公共工具
+│   ├── EventDispatcher.ts
+│   ├── ObjectPool.ts
+│   └── Utils.ts
+├── config/              # 配置
+│   ├── GameConfig.ts
+│   └── AudioConfig.ts
+├── manager/             # 管理器（单例）
+│   ├── GameManager.ts
+│   ├── AudioManager.ts
+│   └── UIManager.ts
+├── ui/                  # UI 组件
+│   ├── HUD.ts
+│   ├── ResultPanel.ts
+│   └── LoadingScreen.ts
+├── game/                # 游戏逻辑
+│   ├── Player.ts
+│   ├── Enemy.ts
+│   └── Bullet.ts
+└── data/                # 数据模型
+    ├── PlayerData.ts
+    └── LevelData.ts
+```
+
+### 5.2 单一职责
+
+```typescript
+// ✅ 每个组件职责单一
+@ccclass('PlayerMovement')
+export class PlayerMovement extends Component {
+    // 只负责移动逻辑
+}
+
+@ccclass('PlayerAnimation')
+export class PlayerAnimation extends Component {
+    // 只负责动画控制
+}
+
+@ccclass('PlayerHealth')  
+export class PlayerHealth extends Component {
+    // 只负责血量管理
+}
+
+// ❌ 避免上帝组件
+// class PlayerController { /* 包含移动+动画+血量+UI+音效 */ }
+```
+
+### 5.3 访问修饰符
+
+```typescript
+@ccclass('Example')
+export class Example extends Component {
+    // public: 编辑器属性 + 外部 API
+    @property
+    public readonly speed: number = 10;
+    
+    // protected: 子类可访问
+    protected _state: GameState = GameState.Idle;
+    
+    // private: 仅内部使用
+    private _timer: number = 0;
+    private _cache: Map<string, any> = new Map();
+
+    // public 方法：对外接口
+    public startGame(): void { /* ... */ }
+    
+    // private 方法：内部实现
+    private calculateScore(): number { /* ... */ return 0; }
+}
+```
+
+---
+
+## 6. 常见代码异味
+
+| 异味 | 问题 | 修正 |
+|------|------|------|
+| `as any` 类型断言 | 绕过类型检查 | 使用正确类型或类型守卫 |
+| 魔法数字 | 可读性差 | 提取为命名常量 |
+| 深层嵌套回调 | 可读性差 | 使用 Promise 或 async/await |
+| 超长函数 (>50行) | 难以维护 | 拆分为小函数 |
+| 重复代码 | 维护成本高 | 提取公共方法/基类 |
+| `console.log` 残留 | 影响性能和包体 | 使用 `DEBUG` 宏包裹 |
+| 未处理 `err` 参数 | 静默失败 | 添加错误处理 |
+| 硬编码路径字符串 | 易出错 | 提取为常量/配置 |
+
+---
+
+## 7. 调试规范
+
+```typescript
+import { DEBUG } from 'cc/env';
+
+// ✅ 使用 DEBUG 宏包裹调试代码
+if (DEBUG) {
+    console.log('Player position:', this.node.position);
+}
+
+// ✅ 封装日志工具
+class Logger {
+    public static log(msg: string, ...args: any[]): void {
+        if (DEBUG) console.log(`[Game] ${msg}`, ...args);
+    }
+    public static warn(msg: string, ...args: any[]): void {
+        if (DEBUG) console.warn(`[Game] ${msg}`, ...args);
+    }
+    public static error(msg: string, ...args: any[]): void {
+        console.error(`[Game] ${msg}`, ...args); // 错误始终输出
+    }
+}
+```