@mison/ag-kit-cn 2.0.1

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

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+React Performance Checker
+Automated performance audit for React/Next.js projects
+Based on Vercel Engineering best practices
+"""
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+class PerformanceChecker:
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path)
+        self.issues = []
+        self.warnings = []
+        self.passed = []
+
+    def check_waterfalls(self):
+        """Check for sequential await patterns (Section 1)"""
+        print("\n[*] Checking for waterfalls (sequential awaits)...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: multiple awaits in sequence without Promise.all
+                sequential_awaits = re.findall(r'await\s+\w+.*?\n\s*await\s+\w+', content)
+
+                if sequential_awaits:
+                    self.issues.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Sequential awaits detected (waterfall)',
+                        'fix': 'Use Promise.all() for parallel fetching',
+                        'section': '1-async-eliminating-waterfalls.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_barrel_imports(self):
+        """Check for barrel imports (Section 2)"""
+        print("[*] Checking for barrel imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: import from index files or barrel exports
+                barrel_imports = re.findall(r"import.*from\s+['\"](@/.*?)/index['\"]", content)
+                barrel_imports += re.findall(r"import.*from\s+['\"]\.\.?/.*?['\"](?!.*?\.tsx?)", content)
+
+                if barrel_imports:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Potential barrel imports detected',
+                        'fix': 'Import directly from specific files',
+                        'section': '2-bundle-bundle-size-optimization.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_dynamic_imports(self):
+        """Check if large components use dynamic imports (Section 2)"""
+        print("[*] Checking for missing dynamic imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check file size - if > 10KB, should probably use dynamic import
+                if len(content) > 10000:
+                    # Check if it's imported statically somewhere
+                    filename = filepath.stem
+
+                    # Search for static imports of this component
+                    for check_file in self.project_path.rglob('*.{ts,tsx}'):
+                        if check_file == filepath or 'node_modules' in str(check_file):
+                            continue
+
+                        check_content = check_file.read_text(encoding='utf-8')
+                        if f"import {filename}" in check_content or f"import {{ {filename}" in check_content:
+                            if 'dynamic(' not in check_content:
+                                self.warnings.append({
+                                    'file': str(check_file.relative_to(self.project_path)),
+                                    'type': 'CRITICAL',
+                                    'issue': f'Large component {filename} imported statically',
+                                    'fix': 'Use dynamic() for code splitting',
+                                    'section': '2-bundle-bundle-size-optimization.md'
+                                })
+                                break
+            except Exception as e:
+                continue
+
+    def check_useEffect_fetching(self):
+        """Check for data fetching in useEffect (Section 4)"""
+        print("[*] Checking for useEffect data fetching...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: fetch or axios in useEffect
+                if 'useEffect' in content:
+                    if re.search(r'useEffect.*?fetch\(', content, re.DOTALL):
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM-HIGH',
+                            'issue': 'Data fetching in useEffect',
+                            'fix': 'Consider using SWR or React Query for deduplication',
+                            'section': '4-client-client-side-data-fetching.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_missing_memoization(self):
+        """Check for missing React.memo, useMemo, useCallback (Section 5)"""
+        print("[*] Checking for missing memoization...")
+
+        for filepath in self.project_path.rglob('*.{tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for component definitions without memo
+                components = re.findall(r'(?:export\s+)?(?:const|function)\s+([A-Z]\w+)', content)
+
+                if components and 'React.memo' not in content and 'memo(' not in content:
+                    # Check if component receives props
+                    if 'props:' in content or 'Props>' in content:
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM',
+                            'issue': 'Component with props not memoized',
+                            'fix': 'Consider using React.memo if props are stable',
+                            'section': '5-rerender-re-render-optimization.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_image_optimization(self):
+        """Check for unoptimized images (Section 6)"""
+        print("[*] Checking for image optimization...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for <img> tags instead of next/image
+                if '<img' in content and 'next/image' not in content:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'MEDIUM',
+                        'issue': 'Using <img> instead of next/image',
+                        'fix': 'Use next/image for automatic optimization',
+                        'section': '6-rendering-rendering-performance.md'
+                    })
+            except Exception as e:
+                continue
+
+    def generate_report(self):
+        """Generate final report"""
+        print("\n" + "="*60)
+        print("REACT PERFORMANCE AUDIT REPORT")
+        print("="*60)
+
+        print(f"\n[CRITICAL ISSUES] ({len([i for i in self.issues if i['type'] == 'CRITICAL'])})")
+        for issue in self.issues:
+            if issue['type'] == 'CRITICAL':
+                print(f"  - {issue['file']}")
+                print(f"    Issue: {issue['issue']}")
+                print(f"    Fix: {issue['fix']}")
+                print(f"    Reference: {issue['section']}\n")
+
+        print(f"\n[WARNINGS] ({len(self.warnings)})")
+        for warning in self.warnings[:10]:  # Show first 10
+            print(f"  - {warning['file']}")
+            print(f"    Issue: {warning['issue']}")
+            print(f"    Fix: {warning['fix']}")
+            print(f"    Reference: {warning['section']}\n")
+
+        if len(self.warnings) > 10:
+            print(f"  ... and {len(self.warnings) - 10} more warnings")
+
+        print("\n" + "="*60)
+        print(f"SUMMARY:")
+        print(f"  Critical Issues: {len([i for i in self.issues if i['type'] == 'CRITICAL'])}")
+        print(f"  Warnings: {len(self.warnings)}")
+        print("="*60)
+
+        if len(self.issues) == 0 and len(self.warnings) == 0:
+            print("\n[SUCCESS] No major performance issues detected!")
+        else:
+            print("\n[ACTION REQUIRED] Review and fix issues above")
+            print("Priority: CRITICAL > HIGH > MEDIUM > LOW")
+
+    def run(self):
+        """Run all checks"""
+        print("="*60)
+        print("React Performance Checker (Vercel Engineering)")
+        print("="*60)
+        print(f"Scanning: {self.project_path}")
+
+        self.check_waterfalls()
+        self.check_barrel_imports()
+        self.check_dynamic_imports()
+        self.check_useEffect_fetching()
+        self.check_missing_memoization()
+        self.check_image_optimization()
+
+        self.generate_report()
+
+
+def main():
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python react_performance_checker.py <project_path>")
+        sys.exit(1)
+
+    project_path = sys.argv[1]
+
+    if not os.path.exists(project_path):
+        print(f"[ERROR] Path not found: {project_path}")
+        sys.exit(1)
+
+    checker = PerformanceChecker(project_path)
+    checker.run()
+
+
+if __name__ == '__main__':
+    main()

package/.agent/skills/nodejs-best-practices/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: nodejs-best-practices
+description: Node.js 开发原则与决策方法。覆盖框架选型、异步模式、安全与架构设计。强调思考，而非照抄。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Node.js 最佳实践
+
+> 面向 2025 的 Node.js 开发原则与决策方法。  
+> **学习如何思考，不要只记代码套路。**
+
+---
+
+## ⚠️ 本技能使用方式
+
+本技能教授的是**决策原则**，不是固定代码模板。
+
+- 需求不明确时，先向用户确认偏好
+- 根据上下文（Context）选择框架与模式
+- 不要每次都默认同一套方案
+
+---
+
+## 1. 框架选型（2025）
+
+### 决策树
+
+```
+你要构建什么？
+│
+├── Edge/Serverless（边缘/无服务器，Cloudflare、Vercel）
+│   └── Hono（零依赖、冷启动极快）
+│
+├── 高性能 API
+│   └── Fastify（通常比 Express 快 2-3 倍）
+│
+├── 企业协作/团队熟悉度优先
+│   └── NestJS（结构化、DI、装饰器）
+│
+├── 传统/稳定/生态最大化
+│   └── Express（成熟、middleware 最多）
+│
+└── 前后端一体
+    └── Next.js API Routes 或 tRPC
+```
+
+### 对比原则
+
+| 维度 | Hono | Fastify | Express |
+|------|------|---------|---------|
+| **适用场景** | Edge、serverless | 性能优先 | 传统、学习 |
+| **冷启动** | 最快 | 快 | 中等 |
+| **生态** | 成长中 | 较好 | 最大 |
+| **TypeScript** | 原生支持 | 优秀 | 良好 |
+| **学习曲线** | 低 | 中 | 低 |
+
+### 选型前必须询问：
+1. 部署目标是什么？
+2. 冷启动时间是否关键？
+3. 团队是否有既有经验？
+4. 是否存在需要维护的遗留代码？
+
+---
+
+## 2. 运行时考量（2025）
+
+### 原生 TypeScript
+
+```
+Node.js 22+: --experimental-strip-types
+├── 可直接运行 .ts 文件
+├── 简单项目可免构建步骤
+└── 适用：脚本、简单 API
+```
+
+### 模块系统决策
+
+```
+ESM（import/export）
+├── 现代标准
+├── 更好的 tree-shaking
+├── 异步模块加载
+└── 适用：新项目
+
+CommonJS（require）
+├── 遗留兼容性更好
+├── 对部分 npm 包支持更成熟
+└── 适用：既有代码库、特定边界场景
+```
+
+### Runtime 选择
+
+| Runtime | 适用场景 |
+|---------|----------|
+| **Node.js** | 通用场景、生态最大 |
+| **Bun** | 性能优先、内置 bundler |
+| **Deno** | 安全优先、内置 TypeScript |
+
+---
+
+## 3. 架构原则
+
+### 分层结构概念
+
+```
+请求流（Request Flow）:
+│
+├── Controller/Route 层
+│   ├── 处理 HTTP 细节
+│   ├── 在边界做输入校验
+│   └── 调用 service 层
+│
+├── Service 层
+│   ├── 承载业务逻辑
+│   ├── 与框架解耦
+│   └── 调用 repository 层
+│
+└── Repository 层
+    ├── 仅处理数据访问
+    ├── 数据库查询
+    └── ORM 交互
+```
+
+### 为什么重要
+- **可测性（Testability）：** 可独立 mock 每一层
+- **灵活性（Flexibility）：** 更换数据库不影响业务层
+- **清晰性（Clarity）：** 每层职责单一
+
+### 何时简化
+- 小型脚本 → 单文件可接受
+- 原型验证 → 可降低结构复杂度
+- 始终追问：“这个项目会继续增长吗？”
+
+---
+
+## 4. 错误处理原则
+
+### 集中式错误处理
+
+```
+Pattern:
+├── 定义自定义错误类
+├── 各层都可 throw
+├── 在顶层统一 catch（middleware）
+└── 输出一致的响应格式
+```
+
+### 错误响应哲学
+
+```
+Client gets:
+├── 合理的 HTTP 状态码
+├── 可程序化处理的错误码
+├── 对用户友好的提示
+└── 不暴露内部细节（安全要求）
+
+Logs get:
+├── 完整堆栈信息
+├── 请求上下文
+├── 用户 ID（如适用）
+└── 时间戳
+```
+
+### 状态码选择
+
+| 场景 | 状态码 | 说明 |
+|------|--------|------|
+| Bad input | 400 | 客户端输入无效 |
+| No auth | 401 | 缺少或无效凭据 |
+| No permission | 403 | 已认证但无权限 |
+| Not found | 404 | 资源不存在 |
+| Conflict | 409 | 重复或状态冲突 |
+| Validation | 422 | schema 合法但业务规则失败 |
+| Server error | 500 | 服务端责任，完整记录日志 |
+
+---
+
+## 5. 异步模式原则
+
+### 各模式使用时机
+
+| 模式 | 适用场景 |
+|------|----------|
+| `async/await` | 串行异步操作 |
+| `Promise.all` | 可并行且互不依赖 |
+| `Promise.allSettled` | 并行且允许部分失败 |
+| `Promise.race` | 超时控制或“先返回者胜出” |
+
+### Event Loop 认知
+
+```
+I/O-bound（异步有帮助）:
+├── 数据库查询
+├── HTTP 请求
+├── 文件系统
+└── 网络操作
+
+CPU-bound（异步无帮助）:
+├── 加密计算
+├── 图像处理
+├── 复杂计算
+└── → 使用 worker threads 或外部任务卸载
+```
+
+### 避免阻塞 Event Loop
+
+- 生产环境避免使用同步方法（如 `fs.readFileSync`）
+- CPU 密集任务必须卸载
+- 大数据处理优先使用 streaming
+
+---
+
+## 6. 校验原则
+
+### 在边界做校验
+
+```
+校验位置：
+├── API 入口（request body/params）
+├── 数据库操作之前
+├── 外部数据（API 响应、文件上传）
+└── 环境变量（启动时）
+```
+
+### 校验库选型
+
+| 库 | 适用场景 |
+|----|----------|
+| **Zod** | TypeScript 优先、类型推断友好 |
+| **Valibot** | 包体积更小（tree-shakeable） |
+| **ArkType** | 性能敏感场景 |
+| **Yup** | 既有 React Form 生态 |
+
+### 校验哲学
+
+- Fail fast：尽早校验、尽早失败
+- Be specific：错误信息必须明确
+- Don't trust：即使“内部数据”也不能默认可信
+
+---
+
+## 7. 安全原则
+
+### 安全检查清单（不是代码模板）
+
+- [ ] **Input validation（输入校验）**：所有输入已校验
+- [ ] **Parameterized queries（参数化查询）**：SQL 禁止字符串拼接
+- [ ] **Password hashing（密码哈希）**：使用 bcrypt 或 argon2
+- [ ] **JWT verification（JWT 校验）**：必须校验签名与过期时间
+- [ ] **Rate limiting（限流）**：具备防滥用机制
+- [ ] **Security headers（安全响应头）**：使用 Helmet.js 或同等方案
+- [ ] **HTTPS**：生产环境全链路启用
+- [ ] **CORS**：配置正确
+- [ ] **Secrets（密钥）**：仅使用环境变量管理
+- [ ] **Dependencies（依赖）**：定期审计
+
+### 安全思维
+
+```
+Trust nothing（默认不信任）:
+├── Query params（查询参数）→ 校验
+├── Request body（请求体）→ 校验
+├── Headers（请求头）→ 校验
+├── Cookies → 校验
+├── File uploads（文件上传）→ 扫描
+└── External APIs（外部 API）→ 校验响应
+```
+
+---
+
+## 8. 测试原则
+
+### 测试策略选择
+
+| 类型 | 目的 | 工具 |
+|------|------|------|
+| **Unit（单元测试）** | 业务逻辑 | node:test, Vitest |
+| **Integration（集成测试）** | API 端点 | Supertest |
+| **E2E（端到端）** | 完整流程 | Playwright |
+
+### 测试优先级
+
+1. **关键路径**：鉴权、支付、核心业务
+2. **边界场景**：空输入、边界值
+3. **错误处理**：失败时系统如何表现
+4. **不值得测**：框架内部代码、过于简单的 getter
+
+### 内置测试运行器（Node.js 22+）
+
+```
+node --test src/**/*.test.ts
+├── 无需额外依赖
+├── 覆盖率报告可用
+└── 支持 watch mode（监听模式）
+```
+
+---
+
+## 10. 需要避免的反模式
+
+### ❌ 不要这样做：
+- 新 Edge 项目默认用 Express（优先考虑 Hono）
+- 在生产代码中使用同步方法
+- 在 controller 中堆业务逻辑
+- 跳过输入校验
+- 硬编码 secrets
+- 不校验就信任外部数据
+- 用 CPU 重任务阻塞 event loop（事件循环）
+
+### ✅ 推荐做法：
+- 基于上下文选择框架
+- 需求不清晰先询问用户偏好
+- 可增长项目采用分层架构
+- 对所有输入做校验
+- secrets 使用环境变量管理
+- 优化前先做 profile（性能分析）
+
+---
+
+## 11. 决策检查清单
+
+开始实现前：
+
+- [ ] **是否询问了用户的技术栈偏好？**
+- [ ] **是否为当前上下文选了合适框架？**（而非默认）
+- [ ] **是否考虑了部署目标？**
+- [ ] **是否规划了错误处理策略？**
+- [ ] **是否识别了校验边界点？**
+- [ ] **是否评估了安全要求？**
+
+---
+
+> **牢记：** Node.js 最佳实践的核心是“决策能力”，不是“背模板”。每个项目都应基于其真实需求重新判断。