@mclawnet/agent 0.6.20 → 0.6.22

package/skills/cocos-creator-3x-cn/references/review/architecture-review.md

@@ -0,0 +1,183 @@
+# 架构审查清单 — Cocos Creator 3.8
+
+> 📖 本文件为 `cocos-creator-3x-cn` 技能参考文件，提供代码架构审查的标准清单。
+
+---
+
+## 审查优先级
+
+| 级别 | 说明 | 要求 |
+|------|------|------|
+| 🔴 P0 - 阻断 | 必须修复才能合并 | 运行时崩溃、资源泄漏、事件泄漏 |
+| 🟡 P1 - 重要 | 建议当前迭代修复 | 架构违规、性能隐患 |
+| 🟢 P2 - 建议 | 下次迭代修复 | 代码风格、可读性 |
+
+---
+
+## 1. 模块导入审查
+
+### 检查项
+
+- [ ] 🔴 所有引擎 API 通过 `import { ... } from 'cc'` 导入，不使用 `cc.` 前缀
+- [ ] 🔴 环境宏通过 `import { DEBUG } from 'cc/env'` 导入，不使用 `CC_DEBUG`
+- [ ] 🟡 导入按规范顺序排列（引擎核心 → UI 组件 → 项目公共 → 当前模块）
+- [ ] 🟡 没有未使用的导入
+- [ ] 🟢 没有 `import * as` 风格的全量导入
+
+### 示例
+
+```typescript
+// ✅ 正确
+import { _decorator, Component, Node, Vec3, Sprite } from 'cc';
+import { DEBUG } from 'cc/env';
+import { GameManager } from '../manager/GameManager';
+
+// ❌ 错误
+const { ccclass } = cc._decorator; // 2.x 风格
+if (CC_DEBUG) { }                  // 2.x 宏
+```
+
+---
+
+## 2. 组件声明审查
+
+### 检查项
+
+- [ ] 🔴 `@ccclass('Name')` 参数与类名一致且全局唯一
+- [ ] 🔴 属性 `@property` 正确声明类型
+- [ ] 🟡 引用类型属性使用 `Type | null = null` 或 `Type = null!`（非空断言仅限确定编辑器赋值的场景）
+- [ ] 🟡 不在构造函数中初始化逻辑（使用 `onLoad`/`start`）
+- [ ] 🟢 组件遵循单一职责原则
+- [ ] 🟢 使用 `@requireComponent` 声明依赖
+
+### 示例
+
+```typescript
+// ✅
+@ccclass('PlayerController')
+export class PlayerController extends Component {
+    @property(Node)
+    private readonly target: Node | null = null;
+    
+    @property
+    private readonly speed = 10;
+}
+
+// ❌ cc 类名与类名不一致
+@ccclass('Player')
+export class PlayerController extends Component { }
+
+// ❌ 未声明类型的引用属性
+@property
+target = null; // 编辑器无法识别类型
+```
+
+---
+
+## 3. 生命周期审查
+
+### 检查项
+
+- [ ] 🔴 `onEnable` 中注册的事件在 `onDisable` 中全部注销
+- [ ] 🔴 `onDestroy` 中释放了所有动态加载的资源（`decRef` / `releaseAsset`）
+- [ ] 🔴 `onDestroy` 中停止了所有缓动和定时器
+- [ ] 🟡 `onLoad` 不依赖其他组件的 `start` 初始化结果
+- [ ] 🟡 不在 `update` 中每帧调用 `find`/`getComponent`
+- [ ] 🟢 `update` 中不创建临时对象（`new Vec3()` 等）
+
+### 事件配对检查器
+
+```
+onEnable 调用的 on()   →   onDisable 必须有对应 off()
+onLoad 调用的 on()     →   onDestroy 必须有对应 off()
+```
+
+---
+
+## 4. 事件系统审查
+
+### 检查项
+
+- [ ] 🔴 使用枚举常量注册事件（`Node.EventType.TOUCH_START`），不使用字符串
+- [ ] 🔴 事件回调使用named function/方法引用，不使用匿名函数（否则无法 off）
+- [ ] 🔴 自定义事件类继承自 `Event`，不直接 `new Event()`（Event 是抽象类）
+- [ ] 🟡 `EventTarget` 用于自定义事件，不通过 `Node` 做自定义事件
+- [ ] 🟡 `emit` 参数不超过 5 个
+- [ ] 🟢 触摸事件穿透使用 `event.preventSwallow`
+
+---
+
+## 5. 资源管理审查
+
+### 检查项
+
+- [ ] 🔴 动态加载的资源有明确的释放策略（`addRef`/`decRef` 或手动 `releaseAsset`）
+- [ ] 🔴 `resources` 目录仅包含需要动态加载的资源
+- [ ] 🔴 加载回调处理了 `err` 参数
+- [ ] 🟡 使用预加载（`preload`）优化体验
+- [ ] 🟡 大量资源使用 Asset Bundle 分模块
+- [ ] 🟡 场景勾选自动释放（高频主场景除外）
+- [ ] 🟢 加载路径使用常量/配置，不硬编码
+
+---
+
+## 6. 性能架构审查
+
+### 检查项
+
+- [ ] 🔴 频繁创建销毁的节点使用对象池
+- [ ] 🟡 Draw Call 在合理范围（2D < 50）
+- [ ] 🟡 使用图集合并碎图
+- [ ] 🟡 低频逻辑使用 `schedule` 而非 `update`
+- [ ] 🟢 使用 `Vec3.set/copy` 复用对象，避免 `new Vec3()`
+- [ ] 🟢 使用距离平方比较替代距离比较
+
+---
+
+## 7. TypeScript 质量审查
+
+### 检查项
+
+- [ ] 🔴 没有 `any` 类型（必要时使用 `unknown` + 类型守卫）
+- [ ] 🔴 没有未捕获的异步错误
+- [ ] 🟡 使用可选链 `?.` 和空值合并 `??`
+- [ ] 🟡 枚举在编辑器使用时调用了 `Enum()`
+- [ ] 🟡 `const enum` 用于纯代码常量（编译内联）
+- [ ] 🟢 调试代码用 `DEBUG` 宏包裹
+- [ ] 🟢 没有 `console.log` 残留（或有 `DEBUG` 保护）
+
+---
+
+## 8. 项目结构审查
+
+### 检查项
+
+- [ ] 🟡 文件命名 PascalCase 与类名一致
+- [ ] 🟡 目录结构清晰（common/manager/ui/game/config/data）
+- [ ] 🟡 没有循环依赖
+- [ ] 🟡 公共工具类提取到 common 目录
+- [ ] 🟢 README 文档更新
+
+---
+
+## 审查报告模板
+
+```markdown
+## 架构审查报告
+
+**文件**: `PlayerController.ts`
+**审查日期**: YYYY-MM-DD
+**审查人**: XXX
+
+### P0 - 阻断
+- [ ] `onEnable` 注册了 TOUCH_START 但 `onDisable` 未注销 (L42)
+- [ ] 动态加载的 Prefab 未调用 `addRef`，可能被意外释放 (L78)
+
+### P1 - 重要
+- [ ] `update` 中每帧调用 `find('Canvas/Enemy')` (L55)
+- [ ] 缺少加载错误处理 (L78)
+
+### P2 - 建议
+- [ ] 使用魔法数字 `0.5` 作为移动倍率 (L60)，建议提取常量
+- [ ] 残留 `console.log` (L90)
+```

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

@@ -0,0 +1,251 @@
+# 代码质量审查清单 — Cocos Creator 3.8
+
+> 📖 本文件为 `cocos-creator-3x-cn` 技能参考文件，提供代码质量审查的详细清单。
+
+---
+
+## 1. 代码正确性
+
+### 1.1 类型安全
+
+| 检查项 | 严重级 | 说明 |
+|--------|--------|------|
+| 无 `as any` 类型断言 | 🔴 | 使用正确类型或 `unknown` + 类型守卫 |
+| 属性正确声明可空性 | 🔴 | `Node \| null = null` 或 `Node = null!` |
+| 无隐式 `any` | 🟡 | tsconfig 开启 `strict` / `noImplicitAny` |
+| 回调参数类型正确 | 🟡 | `(event: EventTouch)` 而非 `(event: any)` |
+| 泛型类型明确 | 🟢 | `assetManager.loadRemote<ImageAsset>(...)` |
+
+### 1.2 空值安全
+
+```typescript
+// ✅ 审查通过模式
+const sprite = this.node.getComponent(Sprite);
+if (!sprite) {
+    console.error('Sprite component not found');
+    return;
+}
+sprite.spriteFrame = newFrame;
+
+// ✅ 可选链 + 提前返回
+private onTouchStart(event: EventTouch): void {
+    const target = this.targetNode;
+    if (!target) return;
+    // 安全使用 target
+}
+
+// ❌ 审查不通过
+const sprite = this.node.getComponent(Sprite)!; // 危险的非空断言（除非确定一定存在）
+sprite.spriteFrame = newFrame;
+```
+
+---
+
+## 2. 资源生命周期
+
+### 2.1 加载-释放配对
+
+```
+每个 resources.load / bundle.load → 必须有对应的释放策略
+每个 addRef()                     → 必须有对应的 decRef()
+每个 instantiate()                → 必须有对应的 destroy()
+```
+
+### 2.2 审查清单
+
+| 检查项 | 严重级 |
+|--------|--------|
+| load 回调处理了 err 参数 | 🔴 |
+| 动态加载并长期持有的资源调用了 addRef | 🔴 |
+| onDestroy 中为持有资源调用了 decRef | 🔴 |
+| 对象池 clear 时释放资源引用 | 🔴 |
+| instantiate 的节点在不需要时 destroy | 🟡 |
+| 场景勾选自动释放（除主场景外） | 🟡 |
+| 不在 resources 目录放不需要动态加载的资源 | 🟡 |
+
+---
+
+## 3. 事件生命周期
+
+### 3.1 事件配对表
+
+审查时构建以下配对表，确认每个 `on` 都有对应的 `off`：
+
+```
+┌─────────────┬──────────────────────┬───────────────────────┐
+│ 注册位置     │ on() 调用            │ off() 对应位置         │
+├─────────────┼──────────────────────┼───────────────────────┤
+│ onEnable    │ input.on(TOUCH,...)  │ onDisable: input.off  │
+│ onEnable    │ node.on(TOUCH,...)   │ onDisable: node.off   │
+│ onLoad      │ eventBus.on(...)     │ onDestroy: eventBus.off│
+└─────────────┴──────────────────────┴───────────────────────┘
+```
+
+### 3.2 常见问题
+
+```typescript
+// ❌ 匿名函数无法取消监听
+onEnable() {
+    input.on(Input.EventType.TOUCH_START, (e) => this.handleTouch(e), this);
+    // onDisable 中无法 off 这个匿名函数！
+}
+
+// ✅ 使用方法引用
+protected onEnable(): void {
+    input.on(Input.EventType.TOUCH_START, this.handleTouch, this);
+}
+protected onDisable(): void {
+    input.off(Input.EventType.TOUCH_START, this.handleTouch, this);
+}
+private handleTouch(event: EventTouch): void: void { /* ... */ }
+```
+
+---
+
+## 4. 缓动与定时器
+
+### 审查清单
+
+| 检查项 | 严重级 |
+|--------|--------|
+| onDestroy 中调用了 `Tween.stopAllByTarget(this.node)` | 🔴 |
+| onDestroy 中调用了 `this.unscheduleAllCallbacks()` | 🔴 |
+| 缓动目标节点仍然有效（未被销毁） | 🟡 |
+| 长时间运行的缓动有停止条件 | 🟡 |
+
+```typescript
+// ✅ 标准清理模式
+protected onDestroy(): void {
+    Tween.stopAllByTarget(this.node);
+    this.unscheduleAllCallbacks();
+}
+```
+
+---
+
+## 5. update 循环质量
+
+### 审查清单
+
+| 检查项 | 严重级 | 说明 |
+|--------|--------|------|
+| 无 `new Vec3/Vec2/Color` 等对象创建 | 🟡 | 使用类成员缓存 |
+| 无 `find()` / `getComponent()` 调用 | 🟡 | 提前缓存引用 |
+| 无字符串拼接 | 🟢 | 缓存或使用模板 |
+| 有提前返回跳过不必要逻辑 | 🟢 | `if (!this._active) return;` |
+| 低频逻辑移到 schedule | 🟢 | AI/碰撞检测等 |
+
+```typescript
+// ✅ 审查通过的 update
+private _tempVec = new Vec3();
+private _isPlaying = false;
+
+protected update(dt: number): void {
+    if (!this._isPlaying) return;
+    
+    Vec3.set(this._tempVec, this.speed * dt, 0, 0);
+    const pos = this.node.position;
+    this.node.setPosition(pos.x + this._tempVec.x, pos.y, pos.z);
+}
+```
+
+---
+
+## 6. 编码风格
+
+### 6.1 命名审查
+
+| 检查项 | 严重级 |
+|--------|--------|
+| 类名 PascalCase | 🟡 |
+| @ccclass 参数与类名一致 | 🟡 |
+| 方法/属性 camelCase | 🟢 |
+| 私有成员 `_` 前缀 | 🟢 |
+| 常量 UPPER_SNAKE_CASE | 🟢 |
+| 事件名 kebab-case | 🟢 |
+
+### 6.2 代码组织
+
+| 检查项 | 严重级 |
+|--------|--------|
+| 文件不超过 300 行 | 🟢 |
+| 函数不超过 50 行 | 🟢 |
+| 嵌套不超过 3 层 | 🟢 |
+| Import 排列有序 | 🟢 |
+| 无重复代码块 (>10行) | 🟡 |
+
+---
+
+## 7. 调试与日志
+
+| 检查项 | 严重级 |
+|--------|--------|
+| 无裸露的 `console.log`（需 `DEBUG` 保护） | 🟡 |
+| 错误日志使用 `console.error` | 🟢 |
+| 无 `debugger` 语句 | 🔴 |
+| 调试工具代码在 BUILD 模式下排除 | 🟡 |
+
+```typescript
+// ✅ 正确的日志模式
+import { DEBUG } from 'cc/env';
+
+if (DEBUG) {
+    console.log('Debug info:', data);
+}
+
+// 错误始终记录
+console.error('Critical error:', err);
+```
+
+---
+
+## 8. 3.8 特定检查
+
+### 从 2.x 升级相关
+
+| 检查项 | 严重级 | 说明 |
+|--------|--------|------|
+| 不使用 `cc.` 前缀 | 🔴 | 3.x 使用 ES Module 导入 |
+| 不使用 `CC_DEBUG` / `CC_EDITOR` | 🔴 | 使用 `import { DEBUG, EDITOR } from 'cc/env'` |
+| 不使用 `cc.systemEvent` | 🟡 | 使用 `input` 对象 |
+| 不使用 `Event.EventCustom` | 🟡 | 自定义类继承 `Event` |
+| 不使用 `cc.Class({})` 声明 | 🔴 | 使用 `@ccclass` 装饰器 |
+| 不使用 `cc.tween()` | 🟡 | 使用 `import { tween } from 'cc'` |
+
+### 3.8 新特性检查
+
+| 检查项 | 严重级 | 说明 |
+|--------|--------|------|
+| 正确使用 `@property` 声明类型 | 🟡 | 引用类型必须显式声明 |
+| 使用 `input` 替代废弃的 `systemEvent` | 🟡 | v3.4+ 推荐 |
+| Bundle 配置在项目设置中正确配置 | 🟡 | v3.8 移到项目设置 |
+
+---
+
+## 审查流程
+
+```
+1. 打开变更文件列表
+2. 按优先级顺序检查：
+   a. P0 阻断项 → 必须全部通过
+   b. P1 重要项 → 确认修复计划
+   c. P2 建议项 → 记录到改进清单
+3. 输出审查报告
+4. 跟踪修复状态
+```
+
+### 快速审查命令
+
+```bash
+# 搜索 2.x 风格代码
+grep -rn "cc\.\|CC_DEBUG\|CC_EDITOR\|systemEvent" --include="*.ts" assets/scripts/
+
+# 搜索裸露的 console.log
+grep -rn "console\.log" --include="*.ts" assets/scripts/ | grep -v "DEBUG"
+
+# 搜索 any 类型
+grep -rn ": any\|as any" --include="*.ts" assets/scripts/
+
+# 搜索未处理的 err
+grep -rn "err," --include="*.ts" assets/scripts/ | grep -v "if.*err"
+```

package/skills/cocos-performance-optimizer/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: cocos-performance-optimizer
+description: 对 Cocos Creator 3.x（TypeScript）项目进行运行时性能优化，重点在减少函数调用开销、降低运算复杂度、复用对象与排查内存问题。当用户报告 Cocos 项目卡顿/掉帧/CPU 高/GC 抖动/包体或内存问题，要求优化 update/lateUpdate/tick、对象池、Vec2/Vec3 复用，或贴出 DevTools / Cocos Profiler / Performance Call Tree 截图与日志时触发。也适用于审查热点脚本、可试玩广告 60fps 调优、Profiler 分析指导。
+version: 1.0.0
+---
+
+# Cocos Creator 性能优化专家
+
+帮助 Cocos Creator 3.x（TypeScript）项目把 CPU 帧时间和内存抖动压下去。聚焦三件事：**少调用、少计算、多复用**，并提供一套从 Profiler 读数据 → 定位热点 → 给出可落地代码改动的工作流。
+
+## When to Use
+
+- 用户说 Cocos 项目卡顿、掉帧、`update`/`lateUpdate`/`tick` 占用高
+- 用户贴出 Chrome DevTools Performance、Cocos Profiler、Frame 分析截图或火焰图
+- 需要审查/重构高频调用的脚本（粒子、子弹、敌人 AI、UI 频繁刷新等）
+- 需要引入或复审对象池（NodePool、自定义池）、Vec2/Vec3 复用、`out` 参数模式
+- 可试玩广告（playable ads）需要稳定 60fps、低端机适配
+- 出现 GC 抖动、内存增长、监听器 / 计时器泄漏
+
+## When NOT to Use
+
+- **包体瘦身 / 资源压缩**：用 `cocos-playable-optimizer` 或 `theone-cocos-standards` 里的资源章节
+- **架构、模块拆分、依赖治理**：用 `architecture` 或 `cocos-creator-3x-cn`
+- **3.x API 用法本身的问题**（不是性能）：用 `cocos-creator-3x-cn`
+- **渲染管线、Shader 级别 GPU 优化**：超出本 skill 范围，提示用户走专门通道
+- **没有数据的"感觉慢"**：先让用户跑 Profiler 拿到数据再回来
+
+## 核心优化目标
+
+1. **减少函数调用开销** — 合并高频小函数、降低调用层级、缓存函数引用
+2. **降低运算复杂度** — 缓存结果、循环外提、避免在 tick 里重算不变量
+3. **最大化对象复用** — 对象池 + 临时数学对象复用，杜绝热路径 `new`
+
+## 工作流（按顺序执行）
+
+### Step 1：先要数据，不猜
+
+在改任何代码前，要求或确认以下至少一项：
+
+- Chrome DevTools → Performance 面板的录制（含 Main thread 火焰图、Bottom-Up）
+- Cocos Creator 编辑器 / 真机 Profiler 截图（FPS、Draw Call、Logic、Render 时间）
+- 帧时间日志：`game.frameTime`、`director.getDeltaTime()` 趋势
+- 复现场景描述：低端机型号、复现步骤、现象（卡帧/掉帧/启动慢/操作后卡）
+
+如果用户只说"慢"，不要凭空改代码。**先指导他们怎么采集数据**（见 §Profiler 分析指南）。
+
+### Step 2：定位热点
+
+按以下优先级查瓶颈：
+
+1. **Main Thread Long Tasks > 50ms** — 单帧爆点
+2. **Self Time Top 10 函数** — 自身耗时大户，多半是热路径主体
+3. **Total Time Top 10 函数** — 调用链顶部的协调者，删一处省一片
+4. **Bottom-Up 高频叶子函数** — 被疯狂调用的小函数，最适合内联/缓存
+5. **GC / Minor GC 抖动** — 锯齿状帧时间通常是临时对象太多
+
+记录定位结果（哪个文件 / 哪个函数 / 调用次数 / 单次耗时 / 帧占比），再进入 Step 3。
+
+### Step 3：按类别套优化清单
+
+#### 3.1 函数调用优化
+
+- [ ] `update / lateUpdate / tick` 里被调用的所有函数过一遍：能内联的内联
+- [ ] 把"每帧不变的查询"挪到 `onLoad / onEnable / start`：`getComponent`、`find`、`getChildByName`
+- [ ] 缓存方法引用：`const setPos = this.node.setPosition.bind(this.node)`，避免 `.` 链式查找
+- [ ] 合并相似职责的小函数（`updatePosX` + `updatePosY` → `updatePos`）
+- [ ] 减少深层嵌套调用链：3 层以上的同模块调用通常可拍平
+- [ ] `EventTarget.emit` 在热路径慎用，改直接函数调用或回调引用
+
+#### 3.2 运算优化
+
+- [ ] **循环外提**：所有循环不变量提到 `for` 之外（包括 `arr.length`）
+- [ ] **缓存结果**：本帧多处用到的值算一次存到局部变量
+- [ ] **减少高开销函数**：`Math.sqrt` 用平方距离替代、`Math.sin/cos` 用查表
+- [ ] **位运算替代**：整数乘除 2 的幂用 `<<` `>>`；`Math.floor(x)` 用 `x | 0`（仅当 x ∈ int32）
+- [ ] **避免热路径 `new`**：`new Vec3()`、`new Color()`、字面量数组 / 对象都算
+- [ ] **字符串拼接热点**：用模板字符串或预生成；不要在 update 里拼 path
+
+#### 3.3 对象复用
+
+- [ ] 频繁创建/销毁的节点 → `NodePool`（先 `put` 再 `get`）
+- [ ] 频繁 new 的数据对象 → 自定义对象池（数组栈，`acquire/release`）
+- [ ] 数学对象用 **静态临时变量** 复用：
+
+  ```ts
+  private static readonly _tmpV3 = new Vec3();
+  // 热路径里
+  Vec3.subtract(MyClass._tmpV3, a, b);
+  ```
+
+- [ ] 优先使用带 `out` 参数的 API：`Vec3.add(out, a, b)` 而不是 `a.clone().add(b)`
+- [ ] 数组预分配：`const arr = new Array(n)`，避免 `push` 触发扩容
+- [ ] 事件对象复用：自定义事件 payload 用同一个对象重置字段
+
+#### 3.4 内存与生命周期
+
+- [ ] `onDestroy` 里：`node.off(...)` / `EventTarget.off`、清 `setTimeout/Interval`、`unschedule`
+- [ ] 资源释放：`assetManager.releaseAsset` / `bundle.release` 的时机正确
+- [ ] 循环引用：父子节点互相持有时考虑弱引用或显式解开
+- [ ] 监听器去重：注册前判断或先 `off` 再 `on`
+
+### Step 4：给出可落地的代码改动
+
+每条建议**必须**包含：
+
+1. **位置**：文件:行号（或"在 XxxComponent.update 中"）
+2. **优化前 / 优化后** 代码对比
+3. **优化原因**：哪条清单 + 为什么省
+4. **预估收益**：定性（"减少每帧 N 次 GC 分配"）或定量（"调用次数 60→1，自身耗时 -85%"）
+5. **风险点**：是否影响行为、是否需要重测某个场景
+
+### Step 5：复测
+
+要求用户用相同场景再跑一次 Profiler 比对：
+
+- FPS / 帧时间均值 + 99 分位
+- 目标函数的 Self Time / Total Time
+- GC 次数与停顿时长
+
+如果改完没变好，回 Step 2 重新定位（说明你打错靶子了）。
+
+## Profiler 分析指南
+
+### A. Chrome DevTools Performance（H5 / 预览模式）
+
+**采集**：F12 → Performance → 录制 5–10 秒 → Stop。
+
+**关键面板**：
+
+1. **Main 轨道（火焰图）**
+   - 找黄色 Scripting 块里的"长条"——长 = 单次耗时高
+   - 找密集的窄条——窄 + 多 = 高频调用
+   - 红色三角 = Long Task（>50ms），优先处理
+
+2. **Bottom-Up（自下而上）**
+   - 按 **Self Time** 倒序：自身耗时榜，热点函数本体
+   - 按 **Total Time** 倒序：含子调用的总耗时，找上游入口
+   - 展开 → 查看调用来源，定位到具体业务代码
+
+3. **Call Tree（自上而下）**
+   - 看 `requestAnimationFrame → director._tick → ...` 这条主链
+   - 找 `Component.update` 类别下的大头
+
+4. **Memory + Performance 联看**
+   - 锯齿状内存曲线 = GC 频繁 → 找热路径的对象分配
+   - 持续上涨不回落 = 泄漏 → Heap Snapshot 对比
+
+### B. Cocos Creator Profiler（编辑器 / 真机）
+
+- **FPS**：稳定值 vs 抖动 → 抖动通常是 GC 或偶发长任务
+- **Logic（逻辑） vs Render（渲染）** 时间占比：
+  - Logic 高 → 脚本优化（本 skill 主战场）
+  - Render 高 → Draw Call、合批、Shader（不在本 skill）
+- **Draw Call**：>100 在低端机就要警惕；本 skill 不深入，但要识别
+- **Triangles / Vertices**：突变说明有大模型/特效进出
+
+### C. 真机数据采集（Android）
+
+- USB 连接 → Chrome `chrome://inspect` 调试 WebView
+- 或 Cocos `--debug` 包配合 `cc.profiler.showStats()`
+- 关注**低端机**而不是开发机；iPhone Pro 上看不到的问题，红米上一抓一大把
+
+## 输出格式
+
+回复用户时按以下结构组织：
+
+```
+## 性能瓶颈定位
+- 热点 1：<文件:行> | Self Time XX ms | 调用次数 N
+- 热点 2：...
+
+## 优化方案
+
+### 优化点 A：<标题>
+**位置**：path/to/file.ts:123
+**类别**：函数调用优化 / 运算优化 / 对象复用 / 内存
+
+**优化前：**
+```ts
+// ...原代码...
+```
+
+**优化后：**
+```ts
+// ...新代码...
+```
+
+**原因**：<对应清单条目 + 解释>
+**预估收益**：<定量或定性>
+**风险**：<行为差异 / 需要回归的场景，或"无">
+
+### 优化点 B：...
+
+## 复测建议
+- 跑一次 <场景>，对比 <指标>
+- 重点验证 <可能受影响的功能>
+```
+
+## Anti-Patterns（不要这么做）
+
+- **没数据先改代码** — 90% 的"优化"会打错靶子，可能反而变慢
+- **过度对象池化** — 一次性、低频对象别建池，池本身有维护成本
+- **过早微优化** — 还没找到瓶颈就到处 `x | 0`，可读性崩了收益为零
+- **改完不复测** — 你以为快了，可能只是浏览器缓存热了
+- **盲目用 `requestAnimationFrame` 替代 `update`** — Cocos 的调度链你绕不开
+- **把 `update` 改成 `schedule(fn, 0)`** — 调度开销可能更高
+- **对临时变量用 `static` 但忘了线程安全** — 单线程 JS 没事，但被嵌套调用时会互相覆盖
+
+## Related Skills
+
+- `cocos-creator-3x-cn` — 3.x API 正确用法（先把 API 用对，再谈优化）
+- `theone-cocos-standards` — TheOne Studio 的代码规范与 playable 约束
+- `cocos-playable-optimizer` — 包体大小 / 资源压缩（互补维度）
+- `code-review` — 优化改动较大时配合做一轮系统化 review