ln-832-bundle-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

路径说明： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，再向上一级即为仓库根目录。

ln-832-bundle-optimizer

ln-832-包体积优化工具

Type: L3 Worker Category: 8XX Optimization Parent: ln-830-code-modernization-coordinator

Reduces JavaScript/TypeScript bundle size. Metric: bundle size in bytes. Each optimization verified via build with keep/discard pattern. JS/TS projects only.

类型： L3 Worker 分类： 8XX 优化类 父级： ln-830-代码现代化协调器

用于减小JavaScript/TypeScript项目的包体积。衡量指标：包体积（字节）。每一项优化都会通过保留/丢弃模式的构建流程进行验证。仅支持JS/TS项目。

Overview

概述

Aspect	Details
Input	JS/TS project (auto-detect from package.json)
Output	Smaller bundle, optimization report
Scope	JS/TS only (skip for other stacks)

维度	详情
输入	JS/TS项目（通过package.json自动检测）
输出	体积更小的包、优化报告
适用范围	仅JS/TS项目（其他技术栈将被跳过）

Workflow

工作流程

Phases: Pre-flight → Baseline → Analyze → Optimize Loop → Report

阶段： 预检 → 基准线建立 → 分析 → 优化循环 → 报告

Phase 0: Pre-flight Checks

阶段0：预检检查

Check	Required	Action if Missing
package.json exists	Yes	Block (not a JS/TS project)
Build command available	Yes	Block (need build for size measurement)
dist/ or build/ output	Yes	Run build first to establish baseline
Git clean state	Yes	Block (need clean baseline for revert)

MANDATORY READ: Load

shared/references/ci_tool_detection.md

— use Build section for build command detection.

检查项	是否必填	缺失时的操作
package.json存在	是	阻止执行（非JS/TS项目）
构建命令可用	是	阻止执行（需要构建来测量体积）
dist/或build/输出目录存在	是	先执行构建以建立基准线
Git工作区处于干净状态	是	阻止执行（需要干净的基准线以便回滚）

必读： 加载

shared/references/ci_tool_detection.md

—— 使用其中的构建部分来检测构建命令。

Worktree & Branch Isolation

工作区与分支隔离

MANDATORY READ: Load

shared/references/git_worktree_fallback.md

— use ln-832 row.

必读： 加载

shared/references/git_worktree_fallback.md

—— 使用其中ln-832对应的内容。

Phase 1: Establish Baseline

阶段1：建立基准线

Measure Current Bundle Size

测量当前包体积

1. Run build: npm run build (or detected build command)
2. Measure: total size of dist/ or build/ directory
3. Record: baseline_bytes, baseline_files

Metric	How
Total size	Sum of all files in output directory
Per-chunk sizes	Individual JS/CSS file sizes
Source map excluded	Do not count .map files

1. 执行构建：npm run build（或检测到的构建命令）
2. 测量：dist/或build/目录的总大小
3. 记录：baseline_bytes（基准体积）、baseline_files（基准文件数）

指标	测量方式
总大小	输出目录下所有文件的大小之和
分块大小	单个JS/CSS文件的大小
排除源映射	不计算.map文件

Phase 2: Analyze Opportunities

阶段2：分析优化机会

Analysis Tools

分析工具

Check	Tool	What It Finds
Unused dependencies	`npx depcheck`	Packages in package.json not imported anywhere
Bundle composition	`npx vite-bundle-visualizer` or `webpack-bundle-analyzer`	Large dependencies, duplicates
Tree-shaking gaps	Manual scan	`import * as` instead of named imports
Code splitting	Route analysis	Large initial bundle, lazy-loadable routes

检查项	工具	检测内容
未使用依赖	`npx depcheck`	package.json中声明但未被任何地方导入的包
包组成分析	`npx vite-bundle-visualizer` 或 `webpack-bundle-analyzer`	体积较大的依赖、重复依赖
摇树优化缺口	手动扫描	使用 `import * as` 而非具名导入的情况
代码拆分	路由分析	初始包体积过大、可懒加载的路由

Optimization Categories

优化类别

Category	Example	Typical Savings
Remove unused deps	`lodash` installed but not imported	10-50KB per dep
Named imports	`import { debounce } from 'lodash-es'` vs `import _ from 'lodash'`	50-200KB
Lighter alternatives	`date-fns` instead of `moment`	50-300KB
Dynamic imports	`React.lazy(() => import('./HeavyComponent'))`	Reduce initial load
CSS optimization	Purge unused CSS, minify	10-100KB

类别	示例	典型优化效果
移除未使用依赖	安装了 `lodash` 但未导入	每个依赖可节省10-50KB
具名导入	使用 `import { debounce } from 'lodash-es'` 替代 `import _ from 'lodash'`	节省50-200KB
轻量替代方案	使用 `date-fns` 替代 `moment`	节省50-300KB
动态导入	`React.lazy(() => import('./HeavyComponent'))`	减小初始加载体积
CSS优化	清除未使用CSS、压缩	节省10-100KB

Phase 3: Optimize Loop (Keep/Discard)

阶段3：优化循环（保留/丢弃机制）

Per-Optimization Cycle

单轮优化流程

FOR each optimization (O1..ON):
  1. APPLY: Make change (remove dep, rewrite import, add lazy load)
  2. BUILD: Run build command
     IF build FAILS → DISCARD (revert) → next optimization
  3. MEASURE: New bundle size
  4. COMPARE:
     IF new_bytes < baseline_bytes → KEEP (new baseline = new_bytes)
     IF new_bytes >= baseline_bytes → DISCARD (revert, no improvement)
  5. LOG: Record result

FOR 每个优化项（O1..ON）：
  1. 应用：执行修改（移除依赖、重写导入、添加懒加载）
  2. 构建：执行构建命令
     如果构建失败 → 丢弃（回滚）→ 处理下一个优化项
  3. 测量：新的包体积
  4. 对比：
     如果new_bytes < baseline_bytes → 保留（更新基准线为new_bytes）
     如果new_bytes >= baseline_bytes → 丢弃（回滚，无优化效果）
  5. 记录：记录优化结果

Keep/Discard Decision

保留/丢弃决策

Condition	Decision
Build fails	DISCARD
Bundle smaller	KEEP (update baseline)
Bundle same or larger	DISCARD

条件	决策
构建失败	丢弃
包体积减小	保留（更新基准线）
包体积不变或增大	丢弃

Optimization Order

优化顺序

Order	Category	Reason
1	Remove unused deps	Safest, immediate savings
2	Named imports / tree-shaking	Medium risk, good savings
3	Lighter alternatives	Higher risk (API changes)
4	Dynamic imports / code splitting	Structural change, test carefully
5	CSS optimization	Lowest priority

顺序	类别	原因
1	移除未使用依赖	最安全，可立即获得优化效果
2	具名导入 / 摇树优化	中等风险，优化效果好
3	轻量替代方案	风险较高（涉及API变更）
4	动态导入 / 代码拆分	结构性变更，需仔细测试
5	CSS优化	优先级最低

Phase 4: Report Results

阶段4：生成报告

Report Schema

报告结构

Field	Description
project	Project path
baseline_bytes	Original bundle size
final_bytes	Final bundle size
reduction_bytes	Bytes saved
reduction_percent	Percentage reduction
optimizations_applied	Count of kept optimizations
optimizations_discarded	Count + reasons
details[]	Per-optimization: category, description, bytes saved
deps_removed[]	Unused dependencies removed

字段	描述
project	项目路径
baseline_bytes	原始包体积
final_bytes	最终包体积
reduction_bytes	节省的字节数
reduction_percent	体积减小百分比
optimizations_applied	已保留的优化项数量
optimizations_discarded	已丢弃的优化项数量及原因
details[]	每个优化项的详情：类别、描述、节省的字节数
deps_removed[]	已移除的未使用依赖列表

Configuration

配置

yaml

Options:
  # Build
  build_command: ""             # Auto-detect from ci_tool_detection.md
  output_dir: ""                # Auto-detect: dist/ or build/

  # Analysis
  run_depcheck: true
  run_bundle_analyzer: false    # Opens browser, skip in CI

  # Optimization scope
  remove_unused_deps: true
  fix_tree_shaking: true
  suggest_alternatives: true
  add_code_splitting: false     # Structural change, opt-in

  # Verification
  run_build: true

yaml

Options:
  # 构建相关
  build_command: ""             # 从ci_tool_detection.md自动检测
  output_dir: ""                # 自动检测：dist/ 或 build/

  # 分析相关
  run_depcheck: true
  run_bundle_analyzer: false    # 会打开浏览器，CI环境下请跳过

  # 优化范围
  remove_unused_deps: true
  fix_tree_shaking: true
  suggest_alternatives: true
  add_code_splitting: false     # 结构性变更，需手动开启

  # 验证相关
  run_build: true

Error Handling

错误处理

Error	Cause	Solution
depcheck not available	Not installed	`npx depcheck` (runs without install)
Build fails after removal	Dep used in dynamic import / config	Revert, mark as false positive
No output directory	Non-standard build setup	Check package.json for output config
Not a JS/TS project	No package.json	Skip entirely with info message

错误	原因	解决方案
depcheck不可用	未安装	使用 `npx depcheck` （无需安装即可运行）
移除依赖后构建失败	依赖被用于动态导入/配置文件中	回滚变更，标记为误报
无输出目录	非标准构建配置	检查package.json中的输出配置
非JS/TS项目	无package.json	直接跳过并输出提示信息

References

参考资料

```
shared/references/ci_tool_detection.md
```
(build detection)

```
shared/references/ci_tool_detection.md
```
（构建命令检测）

版本： 1.0.0 最后更新： 2026-03-08

Definition of Done

—

JS/TS project confirmed (package.json present)
Baseline bundle size measured (build + measure dist/)
Unused deps identified via depcheck
Each optimization applied with keep/discard: build passes + smaller → keep
Compound: each kept optimization updates baseline for next
Report returned with baseline, final, reduction%, per-optimization details

Version: 1.0.0 Last Updated: 2026-03-08

—