企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

导读

本文面向使用 gsd-2 项目中code-optimizer技能（SKILL.md）的开发者与 AI Agent，深度拆解其第五号专项 Agent 所依据的检测清单——bundle-dependencies.md。这份参考文件定义了"包体积与依赖"领域的全部可机器化扫描模式：从lodash全量导入、moment.js残留，到重复功能库并存、devDependencies 混入生产代码、大型组件缺失懒加载，以及未优化图片资源。读完本文，你将掌握一套可直接复制到 Grep/Glob 工具的检测正则，理解每类反模式的性能成因，并获得从"扫描命中"到"修复落地"的完整策略，包括与仓库内react-best-practices相关规则的配套用法。

一、这份参考文件在技能体系中的位置

gsd-2 的code-optimizer技能采用"并行多 Agent 审计"架构：检测到技术栈后一次性并行派发 13 个专项 Agent，每个 Agent 只负责一个性能问题域，且严禁在搜索反模式之前阅读源码——先读代码会产生"锚定偏差"（anchoring bias），让 Agent 把现有实现默认为合理而错过更优方案。正确的执行顺序是：先读references/下的参考文件装载检测模式，再用 Grep/Glob 全库扫描，命中后仅读取 5–10 行上下文确认问题，最后基于最佳实践（而非现有代码）给出修复方案。

"Bundle & Dependencies"（包体积与依赖）是其中的第五个 Agent（表格第 5 行），其职责定义原文为：

Heavy imports, unused deps, duplicate libs, missing lazy loading

它所依据的检测模式清单正是 bundle-dependencies.md。所有模式均为语言与生态无关的通用正则，可在 JavaScript/TypeScript、Python、Go 等任何项目的源码目录中直接执行。

二、先扫技术栈：让模式匹配到正确的生态

在投入扫描之前，技能要求先用 Glob 识别项目技术栈（SKILL.md 的 Step 1），使依赖审计聚焦到实际存在的生态，例如：

技术栈结果随后注入各 Agent 的提示词（{DETECTED_STACK}），用于过滤与本项目无关的检测模式——例如纯 Python 项目就不必关心lodash。

三、六大检测模式详解

bundle-dependencies.md将包体积反模式划分为六类，每类都给出了可直接执行的 Grep/Glob 正则。下面逐类说明模式的语义、正则写法与性能成因。

3.1 Heavy Imports：重量级库被全量导入

第一类检测"重导入"，核心是把本可按需引入的大库整体拉进 bundle：

import\s+\w+\s+from\s+['"]lodash['"] (full lodash import vs lodash/specific) import\s+\w+\s+from\s+['"]moment['"] (moment.js - use date-fns/dayjs) import\s+\w+\s+from\s+['"]underscore['"] (underscore - mostly native now) import\s+\*\s+as (wildcard imports prevent tree-shaking) require\(['"]lodash['"]\) (CJS lodash import) from\s+pandas\s+import\s+\* (full pandas import) import\s+tensorflow (full TF import) import\s+boto3 (full AWS SDK)

逐条解读其性能影响：

• lodash全量导入：import _ from 'lodash'会把整个库打包进主 chunk。正确姿势是lodash-es/specific按需导入，或直接使用原生等价物（Array.find、Object.entries等）。仓库内的 bundle-barrel-imports.md 同样把lodash列入"应避免从入口桶文件导入"的高风险库名单。
• moment.js：体积约为替代品的 10 倍，应替换为date-fns或dayjs。
• underscore：其绝大多数工具函数已被原生 JavaScript 覆盖（Array.prototype.find、Object.entries、Array.from等），属于"基本无需再引入"的库。
• 通配符导入import * as：会阻止 tree-shaking（摇树优化）发挥作用，因为打包器无法静态判定哪些具名导出未被使用。
• Python 侧全量导入：from pandas import *、import tensorflow、import boto3都会在启动时加载整个重型模块；Boto3（AWS SDK）尤其如此，应当按服务子模块或使用延迟导入。

3.2 Unused Dependencies：声明了却从未使用的依赖

# Check package.json dependencies vs actual imports # Check requirements.txt vs actual imports # Check go.mod vs actual imports import.*from.*'"['"] (cross-reference with package.json)

这是交叉引用式检测：用正则import.*from.*'"['"]抓取源码中所有实际导入的包名，再与package.json/requirements.txt/go.mod中声明的依赖做差集。命中的"声明但未导入"依赖应当从清单中删除——它们白白占用安装时间、锁文件体积，还可能引入供应链漏洞暴露面。技能 SKILL.md 建议对每个发现项读取 5–10 行上下文确认"确实是死依赖"后再报告。

3.3 Duplicate Functionality：同一职责多个库并存

# Multiple date libraries moment.*\n.*date-fns (both moment and date-fns) moment.*\n.*dayjs (both moment and dayjs) # Multiple HTTP clients axios.*\n.*node-fetch (both axios and fetch) axios.*\n.*got (both axios and got) # Multiple utility libraries lodash.*\n.*underscore (both lodash and underscore) # Multiple state managers redux.*\n.*mobx (both redux and mobx) zustand.*\n.*jotai (multiple state libs)

这里运用了跨行正则（\n连接两个模式），检测"同一关注点被多个库同时覆盖"的冗余。每类场景的处理原则相同：每个关注点只保留一个库——保留体积更小、生态更活跃、与项目架构更契合的那一个，删除其余。日期库保留date-fns/dayjs之一；HTTP 客户端保留axios/fetch/got之一（现代 Node 与浏览器原生fetch常已足够）；工具库在lodash与underscore中二选一；状态管理在redux/mobx/zustand/jotai中收敛为一个。

3.4 Dev Dependencies in Production：开发依赖与调试代码混入生产

# devDependencies imported in src/ import.*from.*'" # Debug/test code in production console\.log\( console\.debug\( debugger; \.only\( (test.only left in)

两个子类：

1. 生产源码导入 devDependencies：正则匹配@testing、jest、mocha、chai、sinon、cypress、storybook等测试/故事书包在生产路径src/下出现。这会把这些依赖连同其传递依赖一起打进生产 bundle，显著膨胀体积。
2. 调试残留：console.log/console.debug、debugger;、.only(（如it.only、test.only遗留）。这与 build-compilation.md 中"Development-Only Code in Production"一节的模式完全一致，后者还补充了console.trace、.skip(、__DEV__等模式，并建议用构建插件（如babel-plugin-transform-remove-console）在构建期统一剥离。

3.5 Dynamic Imports Missing：本应懒加载却被静态引入

# Large components imported statically that could be lazy import.*Modal (modals are great candidates for lazy loading) import.*Chart (charts are heavy) import.*Editor (rich editors are heavy) import.*PDF (PDF libs are heavy) import.*Map (map components are heavy) # Route-level components not lazy loaded import.*Page.*from (page components should often be lazy)

此类命中"体积大、首屏不需要"的组件被静态导入：Modal（弹窗）、Chart（图表库）、Editor（富文本/代码编辑器）、PDF（渲染库）、Map（地图组件）是典型的懒加载候选；路由级页面组件（import.*Page.*from）也应按路由拆分。

仓库内的 bundle-dynamic-imports.md 给出了这个主题的实战样板——以 Monaco 编辑器为例：

// 错误：Monaco 被打进主 chunk，约增加 300KB import { MonacoEditor } from './monaco-editor' function CodePanel({ code }: { code: string }) { return <MonacoEditor value={code} /> }

// 正确：Monaco 按需加载 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} /> }

该规则被标记为 CRITICAL 级，因为其直接影响 TTI（交互时间）与 LCP（最大内容绘制）。

3.6 Large Assets：未优化的静态资源

# Check for unoptimized assets \.png['"] (check if could be webp/avif) \.jpg['"] (check if could be webp/avif) \.gif['"] (check if could be video/webp) \.svg['"].*import (SVGs imported as modules - check size) base64 (inline base64 assets) data:image (inline images)

针对资源体积：.png/.jpg检查能否转为 WebP/AVIF（通常可节省 30%–80% 体积）；.gif考虑转为视频或 WebP；被当作模块导入的.svg需要核查尺寸；base64与data:image标记的是内联图片——内联在 JS bundle 中会放大主包体积并阻碍缓存复用。

四、七大改进策略：从命中到落地

bundle-dependencies.md在检测清单之外给出了 7 条策略，对应上面的各类命中：

1. Lodash：改用lodash-es/specific按需导入，或直接用原生等价物（Array.find、Object.entries等）。
2. Moment.js：替换为date-fns或dayjs（体积小约 10 倍）。
3. 通配符导入：改用具名导入以启用 tree-shaking。
4. 未使用依赖：从package.json/requirements.txt/go.mod中删除。
5. 动态导入：对重型、首屏以下的组件使用React.lazy/import()。
6. 图片：转换为 WebP/AVIF，使用响应式srcset，对首屏以下图片懒加载。
7. 重复库：每个关注点只保留一个库。

当这些策略在审计报告中被汇总时，技能要求按严重级别（CRITICAL > HIGH > MEDIUM > LOW）排序，再按文件分组，输出"当前代码—为什么慢—最优修复—预期影响"四元组（SKILL.md 的 Agent Prompt Template 与 Report Format），使包体积修复能直接进入按文件逐条执行的改进计划。

五、与仓库内其他规则的配套使用

包体积治理在 gsd-2 的规则体系中并非孤立存在，与本参考文件强相关的配套规则包括：

• bundle-barrel-imports.md：禁止桶文件（barrel file）导入。像lucide-react、@mui/material这类库的入口可能包含上万个再导出，仅导入行为就可能耗时 200–800ms。推荐的修复是直接导入深层路径（lucide-react/dist/esm/icons/check）或使用 Next.js 的optimizePackageImports在构建期自动转换；受影响的常见库名单与bundle-dependencies.md高度重合（lodash、date-fns、react-icons等）。
• bundle-dynamic-imports.md：提供next/dynamic/React.lazy的完整代码样板。
• build-compilation.md：覆盖构建期维度的同主题——生产模式缺失、devtool: source-map泄漏、splitChunks关闭、sideEffects: true阻断 tree-shaking、CI 无缓存等，并补充了"大型/慢速启动导入"（import tensorflow、import pandas等）与"慢测试套件"（--runInBand、-p no:xdist）模式。

六、实际使用流程小结

要在实际项目上运行这套"包体积与依赖"审计，完整流程可归纳为：

1. 用 Glob 确认技术栈（package.json/requirements.txt/go.mod等）；
2. 把 bundle-dependencies.md 中的正则分批执行于源码目录：先扫六类反模式（重导入、未用依赖、重复库、生产中的开发依赖、缺失懒加载、大资源）；
3. 对每个命中项读取 5–10 行上下文，排除误报；
4. 按 3.4/五节中的配套规则决定修复手段，命中项标注文件:行号、严重级别、当前代码、性能成因、最优修复与预期影响；
5. 汇总报告时按严重级别排序、按文件分组，形成从高到低影响的改进计划。

需要说明的是：这份参考文件是code-optimizer技能内部供并行 Agent 装载的检测模式清单，文中涉及的具体性能数字（如"moment 小 10 倍""Monaco 约 300KB""导入耗时 200–800ms"）均出自 bundle-dependencies.md 及其配套规则文件的原始表述，属于该技能文档给出的参考估值，具体收益会随项目与版本不同而波动，落地时建议以本项目的实际测量为准。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用