@mison/ag-kit-cn 2.0.1

package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md

@@ -0,0 +1,149 @@
+# 8. 高级模式
+
+> **影响:** 可变（VARIABLE）
+> **重点:** 针对需要仔细实现的特定情况的高级模式。
+
+---
+
+## 概览
+
+本节包含 **3 条规则**，专注于高级模式。
+
+---
+
+## 规则 8.1: 初始化应用一次，而不是每次挂载
+
+**影响:** 中低（LOW-MEDIUM）
+**标签:** initialization, useEffect, app-startup, side-effects
+
+## 初始化应用一次，而不是每次挂载
+
+不要将必须在每个应用加载时运行一次的应用级初始化放在组件的 `useEffect([])` 内部。组件可以重新挂载，effect 会重新运行。请改用模块级守卫或入口模块中的顶层初始化。
+
+**错误（在开发环境中运行两次，在重新挂载时重新运行）：**
+
+```tsx
+function Comp() {
+    useEffect(() => {
+        loadFromStorage();
+        checkAuthToken();
+    }, []);
+
+    // ...
+}
+```
+
+**正确（每个应用加载一次）：**
+
+```tsx
+let didInit = false;
+
+function Comp() {
+    useEffect(() => {
+        if (didInit) return;
+        didInit = true;
+        loadFromStorage();
+        checkAuthToken();
+    }, []);
+
+    // ...
+}
+```
+
+参考: [初始化应用](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+## 规则 8.2: 将事件处理程序存储在 Ref 中
+
+**影响:** 低（LOW）
+**标签:** advanced, hooks, refs, event-handlers, optimization
+
+## 将事件处理程序存储在 Ref 中
+
+当在不应能在回调更改时重新订阅的 effect 中使用回调时，将回调存储在 ref 中。
+
+**错误（每次渲染都重新订阅）：**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+    useEffect(() => {
+        window.addEventListener(event, handler);
+        return () => window.removeEventListener(event, handler);
+    }, [event, handler]);
+}
+```
+
+**正确（稳定订阅）：**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+    const handlerRef = useRef(handler);
+    useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+
+    useEffect(() => {
+        const listener = (e) => handlerRef.current(e);
+        window.addEventListener(event, listener);
+        return () => window.removeEventListener(event, listener);
+    }, [event]);
+}
+```
+
+**替代方案: 如果你使用的是最新 React，请使用 `useEffectEvent`:**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function useWindowEvent(event: string, handler: (e) => void) {
+    const onEvent = useEffectEvent(handler);
+
+    useEffect(() => {
+        window.addEventListener(event, onEvent);
+        return () => window.removeEventListener(event, onEvent);
+    }, [event]);
+}
+```
+
+`useEffectEvent` 为相同的模式提供了更清晰的 API：它创建一个稳定的函数引用，始终调用处理程序的最新版本。
+
+---
+
+## 规则 8.3: 用于稳定回调 Ref 的 useEffectEvent
+
+**影响:** 低（LOW）
+**标签:** advanced, hooks, useEffectEvent, refs, optimization
+
+## 用于稳定回调 Ref 的 useEffectEvent
+
+在回调中访问最新值，而无需将其添加到依赖数组中。防止 Effect 重新运行，同时避免过时的闭包。
+
+**错误（Effect 在每次回调更改时重新运行）：**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+    const [query, setQuery] = useState("");
+
+    useEffect(() => {
+        const timeout = setTimeout(() => onSearch(query), 300);
+        return () => clearTimeout(timeout);
+    }, [query, onSearch]);
+}
+```
+
+**正确（使用 React 的 useEffectEvent）：**
+
+```tsx
+import { useEffectEvent } from "react";
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+    const [query, setQuery] = useState("");
+    const onSearchEvent = useEffectEvent(onSearch);
+
+    useEffect(() => {
+        const timeout = setTimeout(() => onSearchEvent(query), 300);
+        return () => clearTimeout(timeout);
+    }, [query]);
+}
+```

package/.agent/skills/nextjs-react-expert/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: react-best-practices
+description: 来自 Vercel Engineering 的 React 与 Next.js 性能优化规则。适用于构建组件、优化性能、消除瀑布式请求（waterfalls）、缩减 bundle、性能代码审查与服务端/客户端优化实现。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Next.js 与 React 性能专家
+
+> **来自 Vercel Engineering** - 按影响优先级整理的 57 条优化规则  
+> **哲学：** 先消除 waterfall，再优化 bundle，最后再做微优化。
+
+---
+
+## 🎯 选择性阅读规则（强制）
+
+**只阅读与当前任务相关的章节！** 先看下面内容地图，再按需加载。
+
+> 🔴 **进行性能评审时：先看 CRITICAL（1-2），再看 HIGH/MEDIUM。**
+
+---
+
+## 📑 内容地图
+
+| 文件                                    | 影响等级            | 规则数 | 阅读时机                                                       |
+| --------------------------------------- | ------------------- | ------ | -------------------------------------------------------------- |
+| `1-async-eliminating-waterfalls.md`     | 🔴 **CRITICAL**     | 5 条   | 页面加载慢、串行 API 调用、数据获取 waterfall（瀑布式请求）    |
+| `2-bundle-bundle-size-optimization.md`  | 🔴 **CRITICAL**     | 5 条   | bundle 体积过大、TTI 慢、首屏加载问题                          |
+| `3-server-server-side-performance.md`   | 🟠 **HIGH**         | 7 条   | SSR 缓慢、API Route 优化、服务端 waterfall（瀑布式请求）       |
+| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH**  | 4 条   | 客户端数据管理、SWR 模式、请求去重                             |
+| `5-rerender-re-render-optimization.md`  | 🟡 **MEDIUM**       | 12 条  | 过度重渲染、React 性能、memoization                            |
+| `6-rendering-rendering-performance.md`  | 🟡 **MEDIUM**       | 9 条   | 渲染瓶颈、虚拟列表、图像优化                                   |
+| `7-js-javascript-performance.md`        | ⚪ **LOW-MEDIUM**   | 12 条  | 微优化、缓存、循环性能                                         |
+| `8-advanced-advanced-patterns.md`       | 🔵 **VARIABLE**     | 3 条   | 高级 React 模式、useLatest、init-once                          |
+
+**总计：8 大类，共 57 条规则**
+
+---
+
+## 🚀 快速决策树
+
+**你的性能问题属于哪一类？**
+
+```
+🐌 页面加载慢 / 可交互时间（Time to Interactive，TTI）长
+  → 阅读第 1 节：消除瀑布式请求（Eliminating Waterfalls）
+  → 阅读第 2 节：包体积优化（Bundle Size Optimization）
+
+📦 bundle 体积过大（> 200KB）
+  → 阅读第 2 节：包体积优化（Bundle Size Optimization）
+  → 检查：动态导入（dynamic imports）、桶文件导入（barrel imports）、tree-shaking
+
+🖥️ 服务端渲染慢（SSR）
+  → 阅读第 3 节：服务端性能（Server-Side Performance）
+  → 检查：并行数据获取、streaming
+
+🔄 重渲染过多 / UI 卡顿
+  → 阅读第 5 节：重渲染优化（Re-render Optimization）
+  → 检查：React.memo、useMemo、useCallback
+
+🎨 渲染性能问题
+  → 阅读第 6 节：渲染性能（Rendering Performance）
+  → 检查：虚拟化、layout thrashing
+
+🌐 客户端数据获取问题
+  → 阅读第 4 节：客户端数据获取（Client-Side Data Fetching）
+  → 检查：SWR 去重（deduplication）、localStorage
+
+✨ 需要高级模式
+  → 阅读第 8 节：高级模式（Advanced Patterns）
+```
+
+---
+
+## 📊 影响优先级指南
+
+**进行全量优化时，按以下顺序：**
+
+```
+1️⃣ CRITICAL（收益最大，先做）：
+   ├─ 第 1 节：消除瀑布式请求（Eliminating Waterfalls）
+   │  └─ 每个 waterfall 都会引入完整网络延迟（100-500ms+）
+   └─ 第 2 节：包体积优化（Bundle Size Optimization）
+      └─ 直接影响可交互时间（Time to Interactive）与最大内容绘制（LCP）
+
+2️⃣ HIGH（显著收益，第二步）：
+   └─ 第 3 节：服务端性能（Server-Side Performance）
+      └─ 消除服务端 waterfall，提升响应速度
+
+3️⃣ MEDIUM（中等收益，第三步）：
+   ├─ 第 4 节：客户端数据获取（Client-Side Data Fetching）
+   ├─ 第 5 节：重渲染优化（Re-render Optimization）
+   └─ 第 6 节：渲染性能（Rendering Performance）
+
+4️⃣ LOW（打磨项，最后做）：
+   ├─ 第 7 节：JavaScript 性能（JavaScript Performance）
+   └─ 第 8 节：高级模式（Advanced Patterns）
+```
+
+---
+
+## 🔗 相关技能
+
+| 需求                    | 技能                              |
+| ----------------------- | --------------------------------- |
+| API 设计模式            | `@[skills/api-patterns]`          |
+| 数据库优化              | `@[skills/database-design]`       |
+| 测试策略                | `@[skills/testing-patterns]`      |
+| UI/UX 设计原则          | `@[skills/frontend-design]`       |
+| TypeScript 模式         | `@[skills/typescript-expert]`     |
+| 部署与 DevOps           | `@[skills/deployment-procedures]` |
+
+---
+
+## ✅ 性能评审清单
+
+上线前检查：
+
+**Critical（必须修复）：**
+
+- [ ] 无串行数据获取（waterfall 瀑布式请求已消除）
+- [ ] 主 bundle（包）< 200KB
+- [ ] 应用代码中无 barrel imports（桶文件导入）
+- [ ] 大组件已使用动态导入（dynamic imports）
+- [ ] 可并行的数据获取已并行化
+
+**High Priority（高优先级）：**
+
+- [ ] 合适场景使用 Server Components（服务端组件）
+- [ ] API Routes（接口路由）已优化（无 N+1 查询）
+- [ ] 数据获取路径配置了 Suspense（挂起）边界
+- [ ] 可静态生成内容已采用 SSG（静态生成）
+
+**Medium Priority（中优先级）：**
+
+- [ ] 高开销计算已 memoize（记忆化）
+- [ ] 大列表（>100 项）已虚拟化
+- [ ] 图片通过 `next/image` 优化
+- [ ] 无不必要重渲染
+
+**Low Priority（打磨）：**
+
+- [ ] 热路径循环已优化
+- [ ] RegExp 已提升至循环外
+- [ ] 循环内属性访问已缓存
+
+---
+
+## ❌ 反模式
+
+**不要这样做（DON'T）：**
+
+- ❌ 对互不依赖任务使用串行 `await`
+- ❌ 只用一个函数却导入整个库
+- ❌ 在应用代码中使用 barrel exports（`index.ts` 重导出）
+- ❌ 大组件/大库不做动态导入（dynamic imports）
+- ❌ `useEffect` 拉数据却不做去重
+- ❌ 高开销计算不做 memoization（记忆化）
+- ❌ 本可用 server component 却硬用 client component
+
+**推荐做法（DO）：**
+
+- ✅ 使用 `Promise.all()` 并行获取数据
+- ✅ 使用动态导入：`const Comp = dynamic(() => import('./Heavy'))`
+- ✅ 精确导入：`import { specific } from 'library/specific'`
+- ✅ 用 Suspense（挂起）边界提升体验
+- ✅ 利用 React Server Components（服务端组件）
+- ✅ 优化前先测量
+- ✅ 使用 Next.js 内建优化（`next/image`、`next/font`）
+
+---
+
+## 🎯 如何使用本技能
+
+### 新功能开发场景：
+
+1. 开发阶段优先检查 **Section 1 & 2**（预防 waterfall 瀑布式请求，控制 bundle 包体积）
+2. 默认优先考虑 server components（服务端组件，Section 3）
+3. 对高开销操作应用 memoization（记忆化，Section 5）
+
+### 性能评审场景：
+
+1. 从 **Section 1** 开始（waterfall 影响最大）
+2. 再看 **Section 2**（bundle 体积）
+3. 再看 **Section 3**（服务端性能）
+4. 最后按需补充其他章节
+
+### 慢性能排障场景：
+
+1. 先识别症状（慢加载、卡顿等）
+2. 使用上方快速决策树
+3. 阅读对应章节
+4. 按优先级顺序落地修复
+
+---
+
+## 📚 学习路径
+
+**初级（先抓关键）：**  
+→ 第 1 节：消除瀑布式请求（Eliminating Waterfalls）  
+→ 第 2 节：包体积优化（Bundle Size Optimization）
+
+**中级（补齐高优先级）：**  
+→ 第 3 节：服务端性能（Server-Side Performance）  
+→ 第 5 节：重渲染优化（Re-render Optimization）
+
+**高级（全量优化）：**  
+→ 全章节 + 第 8 节：高级模式（Advanced Patterns）
+
+---
+
+## 🔍 验证脚本
+
+| 脚本                                   | 用途                        | 执行命令                                                     |
+| -------------------------------------- | --------------------------- | ------------------------------------------------------------ |
+| `scripts/react_performance_checker.py` | 自动化性能审计              | `python scripts/react_performance_checker.py <project_path>` |
+
+---
+
+## 📖 章节说明
+
+### 第 1 节：消除瀑布式请求（CRITICAL）
+
+**影响：** 每个 waterfall（瀑布式请求）会增加 100-500ms+ 延迟  
+**关键概念：** 并行获取、`Promise.all()`、Suspense 边界、预加载
+
+### 第 2 节：包体积优化（CRITICAL）
+
+**影响：** 直接影响 TTI（可交互时间）、LCP（最大内容绘制）  
+**关键概念：** 动态导入、tree-shaking（摇树优化）、避免 barrel imports（桶文件导入）
+
+### 第 3 节：服务端性能（HIGH）
+
+**影响：** 更快服务端响应、更好 SEO  
+**关键概念：** 服务端并行获取、streaming、API Route（接口路由）优化
+
+### 第 4 节：客户端数据获取（MEDIUM-HIGH）
+
+**影响：** 减少冗余请求、提升 UX（用户体验）  
+**关键概念：** SWR 去重、localStorage 缓存、事件监听
+
+### 第 5 节：重渲染优化（MEDIUM）
+
+**影响：** UI 更流畅、减少无效计算  
+**关键概念：** `React.memo`、`useMemo`、`useCallback`、组件结构
+
+### 第 6 节：渲染性能（MEDIUM）
+
+**影响：** 提升渲染效率  
+**关键概念：** 虚拟化、图像优化、layout thrashing（布局抖动）
+
+### 第 7 节：JavaScript 性能（LOW-MEDIUM）
+
+**影响：** 热路径增量优化  
+**关键概念：** 循环优化、缓存、RegExp 提升
+
+### 第 8 节：高级模式（VARIABLE）
+
+**影响：** 特定场景收益明显  
+**关键概念：** `useLatest` hook（钩子）、init-once 模式、event handler refs（事件处理引用）
+
+---
+
+## 🎓 最佳实践总结
+
+**黄金法则：**
+
+1. **先测量再优化** - 使用 React DevTools Profiler、Chrome DevTools
+2. **先做高收益项** - Waterfalls（瀑布式请求）→ Bundle（包体积）→ Server（服务端）→ Micro（微优化）
+3. **避免过度优化** - 聚焦真实瓶颈
+4. **善用平台能力** - Next.js 内建大量优化
+5. **关注真实用户环境** - 不是只看本机结果
+
+**性能思维：**
+
+- 串行 `await` 可能就是 waterfall（瀑布式请求）
+- 每个 `import` 都可能引入 bundle（包体积）膨胀
+- 每次无意义重渲染都是浪费
+- server components（服务端组件）能减少下发 JS
+- 用数据说话，不靠猜测
+
+---
+
+**来源：** Vercel Engineering  
+**日期：** 2026 年 1 月  
+**版本：** 1.0.0  
+**规则总数：** 57 条，分 8 大类

package/.agent/skills/nextjs-react-expert/scripts/convert_rules.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Conversion Script: React Best Practices → .agent Format
+Merges 59 individual rules into 8 grouped section files
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Section metadata from _sections.md
+SECTIONS = {
+    'async': {
+        'number': 1,
+        'title': 'Eliminating Waterfalls',
+        'impact': 'CRITICAL',
+        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+    },
+    'bundle': {
+        'number': 2,
+        'title': 'Bundle Size Optimization',
+        'impact': 'CRITICAL',
+        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+    },
+    'server': {
+        'number': 3,
+        'title': 'Server-Side Performance',
+        'impact': 'HIGH',
+        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+    },
+    'client': {
+        'number': 4,
+        'title': 'Client-Side Data Fetching',
+        'impact': 'MEDIUM-HIGH',
+        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+    },
+    'rerender': {
+        'number': 5,
+        'title': 'Re-render Optimization',
+        'impact': 'MEDIUM',
+        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+    },
+    'rendering': {
+        'number': 6,
+        'title': 'Rendering Performance',
+        'impact': 'MEDIUM',
+        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+    },
+    'js': {
+        'number': 7,
+        'title': 'JavaScript Performance',
+        'impact': 'LOW-MEDIUM',
+        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+    },
+    'advanced': {
+        'number': 8,
+        'title': 'Advanced Patterns',
+        'impact': 'VARIABLE',
+        'description': 'Advanced patterns for specific cases that require careful implementation.'
+    }
+}
+
+
+def parse_frontmatter(content: str) -> Tuple[Dict, str]:
+    """Parse markdown frontmatter and body"""
+    if not content.startswith('---'):
+        return {}, content
+
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}, content
+
+    # Parse YAML frontmatter manually (simple key: value)
+    frontmatter = {}
+    for line in parts[1].strip().split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+
+    body = parts[2].strip()
+    return frontmatter, body
+
+
+def parse_rule_file(filepath: Path) -> Dict:
+    """Parse a single rule file"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    frontmatter, body = parse_frontmatter(content)
+
+    # Extract prefix from filename
+    filename = filepath.stem
+    prefix = filename.split('-')[0]
+
+    return {
+        'filename': filepath.name,
+        'prefix': prefix,
+        'title': frontmatter.get('title', filename),
+        'impact': frontmatter.get('impact', ''),
+        'impactDescription': frontmatter.get('impactDescription', ''),
+        'tags': frontmatter.get('tags', ''),
+        'body': body,
+        'frontmatter': frontmatter
+    }
+
+
+def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
+    """Group all rules by their section prefix"""
+    grouped = {prefix: [] for prefix in SECTIONS.keys()}
+
+    for rule_file in sorted(rules_dir.glob('*.md')):
+        # Skip special files
+        if rule_file.name.startswith('_'):
+            continue
+
+        rule = parse_rule_file(rule_file)
+        prefix = rule['prefix']
+
+        if prefix in grouped:
+            grouped[prefix].append(rule)
+        else:
+            print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
+
+    return grouped
+
+
+def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
+    """Generate a merged section file"""
+    if not rules:
+        print(f"[WARNING] No rules found for section: {section_prefix}")
+        return
+
+    section_meta = SECTIONS[section_prefix]
+    section_num = section_meta['number']
+    section_title = section_meta['title']
+    impact = section_meta['impact']
+    description = section_meta['description']
+
+    # Sort rules by title
+    rules.sort(key=lambda r: r['title'])
+
+    # Build content
+    content = f"""# {section_num}. {section_title}
+
+> **Impact:** {impact}
+> **Focus:** {description}
+
+---
+
+## Overview
+
+This section contains **{len(rules)} rules** focused on {section_title.lower()}.
+
+"""
+
+    # Add each rule
+    for i, rule in enumerate(rules, 1):
+        rule_id = f"{section_num}.{i}"
+        title = rule['title']
+        rule_impact = rule['impact']
+        tags = rule['tags']
+        body = rule['body']
+
+        content += f"""---
+
+## Rule {rule_id}: {title}
+
+"""
+
+        if rule_impact:
+            content += f"**Impact:** {rule_impact}  \n"
+
+        if tags:
+            content += f"**Tags:** {tags}  \n"
+
+        content += f"\n{body}\n\n"
+
+    # Write file
+    output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
+    output_file.write_text(content, encoding='utf-8')
+    print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
+
+
+def main():
+    """Main conversion function"""
+    # Paths
+    base_dir = Path(__file__).parent.parent.parent.parent.parent
+    rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
+    output_dir = base_dir / ".agent/skills/react-best-practices"
+
+    print(f"[*] Reading rules from: {rules_dir}")
+    print(f"[*] Output to: {output_dir}")
+    print()
+
+    # Check if rules directory exists
+    if not rules_dir.exists():
+        print(f"[ERROR] Rules directory not found: {rules_dir}")
+        return
+
+    # Group rules
+    print("[*] Grouping rules by section...")
+    grouped_rules = group_rules_by_section(rules_dir)
+
+    # Stats
+    total_rules = sum(len(rules) for rules in grouped_rules.values())
+    print(f"[*] Found {total_rules} total rules")
+    print()
+
+    # Generate section files
+    print("[*] Generating section files...")
+    for section_prefix in SECTIONS.keys():
+        rules = grouped_rules[section_prefix]
+        generate_section_file(section_prefix, rules, output_dir)
+
+    print()
+    print("[SUCCESS] Conversion complete!")
+    print(f"[*] Generated 8 section files from {total_rules} rules")
+
+
+if __name__ == '__main__':
+    main()