@mison/ag-kit-cn 2.0.1

package/.agent/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md

@@ -0,0 +1,311 @@
+# 1. 消除瀑布流
+
+> **影响：** 严重（CRITICAL）
+> **重点：** 瀑布流是头号性能杀手。每一次串行 await 都会增加完整网络延迟。消除它们收益最大。
+
+---
+
+## 概览
+
+本节包含 **5 条规则**，专注于消除瀑布流。
+
+---
+
+## 规则 1.1：延迟 await 到需要时
+
+**影响：** 高（HIGH）  
+**标签：** async（异步）, await, conditional（条件）, optimization（优化）  
+
+## 延迟 await 到需要时
+
+将 `await` 操作移动到实际使用它们的分支，避免阻塞不需要它们的路径。
+
+**错误示例（阻塞两个分支）：**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**正确示例（仅在需要时阻塞）：**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**另一个例子（提前返回优化）：**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+当跳过的分支经常发生，或被延后的操作很昂贵时，这种优化价值很大。
+
+---
+
+## 规则 1.2：基于依赖的并行化
+
+**影响：** 严重（CRITICAL）  
+**标签：** async（异步）, parallelization（并行化）, dependencies（依赖）, better-all  
+
+## 基于依赖的并行化
+
+对于存在部分依赖的操作，使用 `better-all` 最大化并行度。它会在最早时刻启动每个任务。
+
+**错误示例（profile 不必要地等待 config）：**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**正确示例（config 与 profile 并行）：**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**不引入额外依赖的替代方案：**
+
+也可以先创建全部 Promise，最后再 `Promise.all()`。
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+参考：<https://github.com/shuding/better-all>
+
+---
+
+## 规则 1.3：防止 API 路由中的瀑布链
+
+**影响：** 严重（CRITICAL）  
+**标签：** api-routes, server-actions, waterfalls, parallelization  
+
+## 防止 API 路由中的瀑布链
+
+在 API 路由与 Server Actions 中，立即启动独立操作，即使暂时不 await。
+
+**错误示例（config 等待 auth，data 等待两者）：**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**正确示例（auth 与 config 立即开始）：**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+对更复杂依赖链，使用 `better-all` 自动最大化并行度（见“基于依赖的并行化”）。
+
+---
+
+## 规则 1.4：独立操作使用 Promise.all()
+
+**影响：** 严重（CRITICAL）  
+**标签：** async（异步）, parallelization（并行化）, promises, waterfalls  
+
+## 独立操作使用 Promise.all()
+
+当异步操作之间无依赖时，用 `Promise.all()` 并发执行。
+
+**错误示例（串行执行，3 次往返）：**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**正确示例（并行执行，1 次往返）：**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+---
+
+## 规则 1.5：策略性 Suspense 边界
+
+**影响：** 高（HIGH）  
+**标签：** async（异步）, suspense, streaming（流式）, layout-shift（布局偏移）  
+
+## 策略性 Suspense 边界
+
+不要在 async 组件中先 await 数据再返回 JSX。用 Suspense 边界让外层 UI 先显示、数据后流入。
+
+**错误示例（外层被数据阻塞）：**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+整个布局会等待数据，即便只有中间区域需要它。
+
+**正确示例（外层立即渲染，数据流式进入）：**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar、Header、Footer 立即渲染，只有 DataDisplay 等待数据。
+
+**替代方案（跨组件共享 Promise）：**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+两个组件共享同一个 promise，因此只发生一次请求。布局立即渲染，两个组件一起等待。
+
+**何时不使用该模式：**
+
+- 布局决策所需的关键数据（影响定位）
+- 首屏（Above the fold）对 SEO 至关重要的内容
+- 极小且很快的查询（Suspense 开销不值得）
+- 当你想避免布局偏移（加载 → 内容跳动）
+
+**权衡：** 更快的首屏绘制 vs 潜在的布局偏移。根据你的 UX 优先级选择。

package/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md

@@ -0,0 +1,241 @@
+# 2. 包体积优化
+
+> **影响:** 严重（CRITICAL）
+> **重点:** 减小初始包体积可缩短可交互时间（Time to Interactive，TTI）和最大内容绘制（LCP）。
+
+---
+
+## 概览
+
+本节包含 **5 条规则**，专注于包体积优化。
+
+---
+
+## 规则 2.1: 避免桶文件导入
+
+**影响:** 严重（CRITICAL）
+**标签:** bundle, imports, tree-shaking, barrel-files, performance
+
+## 避免桶文件导入
+
+直接从源文件导入，而不是从桶文件导入，以避免加载数千个未使用的模块。**桶文件（Barrel File）**是重新导出多个模块的入口点（例如，`index.js` 执行 `export * from './module'`）。
+
+流行的图标和组件库在入口文件中可能有 **多达 10,000 个重新导出**。对于许多 React 包，**仅导入它们就需要 200-800ms**，影响开发速度和生产环境的冷启动。
+
+**为什么 Tree-shaking（摇树优化）没用：** 当库被标记为外部（不捆绑）时，捆绑器无法优化它。如果你捆绑它以启用 Tree-shaking，分析整个模块图会使构建变得大大减慢。
+
+**错误示范（导入整个库）：**
+
+```tsx
+import { Check, X, Menu } from "lucide-react";
+// 加载 1,583 个模块，开发环境额外耗时 ~2.8s
+// 运行时成本: 每次冷启动 200-800ms
+
+import { Button, TextField } from "@mui/material";
+// 加载 2,225 个模块，开发环境额外耗时 ~4.2s
+```
+
+**正确示范（仅导入你需要的）：**
+
+```tsx
+import Check from "lucide-react/dist/esm/icons/check";
+import X from "lucide-react/dist/esm/icons/x";
+import Menu from "lucide-react/dist/esm/icons/menu";
+// 仅加载 3 个模块 (~2KB vs ~1MB)
+
+import Button from "@mui/material/Button";
+import TextField from "@mui/material/TextField";
+// 仅加载你使用的
+```
+
+**替代方案（Next.js 13.5+）：**
+
+```js
+// next.config.js - 使用 optimizePackageImports
+module.exports = {
+    experimental: {
+        optimizePackageImports: ["lucide-react", "@mui/material"],
+    },
+};
+
+// 此时你可以保持便捷的桶文件导入：
+import { Check, X, Menu } from "lucide-react";
+// 构建时自动转换为直接导入
+```
+
+直接导入可提供 15-70% 更快的开发启动速度，28% 更快的构建速度，40% 更快的冷启动速度，以及显著更快的 HMR（热更新）。
+
+常见受影响的库: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`。
+
+参考: [Next.js 如何优化包导入](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+---
+
+## 规则 2.2: 条件模块加载
+
+**影响:** 高（HIGH）
+**标签:** bundle, conditional-loading, lazy-loading
+
+## 条件模块加载
+
+仅当功能激活时才加载大数据或模块。
+
+**示例（懒加载动画帧）：**
+
+```tsx
+function AnimationPlayer({
+    enabled,
+    setEnabled,
+}: {
+    enabled: boolean;
+    setEnabled: React.Dispatch<React.SetStateAction<boolean>>;
+}) {
+    const [frames, setFrames] = useState<Frame[] | null>(null);
+
+    useEffect(() => {
+        if (enabled && !frames && typeof window !== "undefined") {
+            import("./animation-frames.js")
+                .then((mod) => setFrames(mod.frames))
+                .catch(() => setEnabled(false));
+        }
+    }, [enabled, frames, setEnabled]);
+
+    if (!frames) return <Skeleton />;
+    return <Canvas frames={frames} />;
+}
+```
+
+`typeof window !== 'undefined'` 检查防止了此模块被捆绑到 SSR（服务端渲染）中，优化了服务器包体积和构建速度。
+
+---
+
+## 规则 2.3: 推迟非关键的第三方库
+
+**影响:** 中（MEDIUM）
+**标签:** bundle, third-party, analytics, defer
+
+## 推迟非关键的第三方库
+
+分析、日志和错误追踪不会阻塞用户交互。在水合（Hydration）之后加载它们。
+
+**错误示范（阻塞初始包）：**
+
+```tsx
+import { Analytics } from "@vercel/analytics/react";
+
+export default function RootLayout({ children }) {
+    return (
+        <html>
+            <body>
+                {children}
+                <Analytics />
+            </body>
+        </html>
+    );
+}
+```
+
+**正确示范（水合后加载）：**
+
+```tsx
+import dynamic from "next/dynamic";
+
+const Analytics = dynamic(
+    () => import("@vercel/analytics/react").then((m) => m.Analytics),
+    { ssr: false },
+);
+
+export default function RootLayout({ children }) {
+    return (
+        <html>
+            <body>
+                {children}
+                <Analytics />
+            </body>
+        </html>
+    );
+}
+```
+
+---
+
+## 规则 2.4: 对重型组件使用动态导入
+
+**影响:** 严重（CRITICAL）
+**标签:** bundle, dynamic-import, code-splitting, next-dynamic
+
+## 对重型组件使用动态导入
+
+使用 `next/dynamic` 懒加载初始渲染不需要的大型组件。
+
+**错误示范（Monaco 与主 chunk 捆绑在一起 ~300KB）：**
+
+```tsx
+import { MonacoEditor } from "./monaco-editor";
+
+function CodePanel({ code }: { code: string }) {
+    return <MonacoEditor value={code} />;
+}
+```
+
+**正确示范（Monaco 按需加载）：**
+
+```tsx
+import dynamic from "next/dynamic";
+
+const MonacoEditor = dynamic(
+    () => import("./monaco-editor").then((m) => m.MonacoEditor),
+    { ssr: false },
+);
+
+function CodePanel({ code }: { code: string }) {
+    return <MonacoEditor value={code} />;
+}
+```
+
+---
+
+## 规则 2.5: 基于用户意图预加载
+
+**影响:** 中（MEDIUM）
+**标签:** bundle, preload, user-intent, hover
+
+## 基于用户意图预加载
+
+在需要之前预加载繁重的包，以减少感知延迟。
+
+**示例（悬停/聚焦时预加载）：**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+    const preload = () => {
+        if (typeof window !== "undefined") {
+            void import("./monaco-editor");
+        }
+    };
+
+    return (
+        <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+            打开编辑器
+        </button>
+    );
+}
+```
+
+**示例（当功能标志启用时预加载）：**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+    useEffect(() => {
+        if (flags.editorEnabled && typeof window !== "undefined") {
+            void import("./monaco-editor").then((mod) => mod.init());
+        }
+    }, [flags.editorEnabled]);
+
+    return (
+        <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>
+    );
+}
+```
+
+`typeof window !== 'undefined'` 检查防止了预加载模块被捆绑到 SSR（服务端渲染）中。