lofter-lottie-opt 1.0.1 → 1.0.2

package/README.md

@@ -1,371 +1,148 @@
 # Lottie Optimizer
 
-A plugin-based Lottie JSON optimizer with flexible plugin system for customizable optimization.
-
-## Features
-
-✅ **插件化架构**: 每个优化效果作为独立插件  
-✅ **灵活组合**: 用户可自由选择和组合插件  
-✅ **CLI 工具**: 命令行工具支持批量处理  
-✅ **编程接口**: 可在代码中直接使用的 API  
-✅ **质量控制**: 内置优化统计和警告系统  
-✅ **质量验证**: 完整的压缩前后对比和验证系统  
-✅ **视觉验证**: 播放能力测试和渲染验证  
-✅ **详细报告**: HTML 格式的综合分析报告  
+插件化 Lottie JSON 优化器，灵活组合优化策略，大幅减小动画文件体积。
 
 ## 安装
 
 ```bash
-pnpm install
-pnpm build
+npm install lofter-lottie-opt -g
+# 或
+pnpm add lofter-lottie-opt -g
 ```
 
-## 使用方式
-
-### CLI 使用
+## CLI 使用
 
 ```bash
-# 构建项目
-pnpm build
+# 基础用法：优化 Lottie 文件（使用所有默认插件）
+lottie-opt input.json output.json
 
-# 使用所有默认插件优化
-node dist/cli/index.js input.json output.json
+# 指定使用特定插件
+lottie-opt input.json -o output.json --plugins remove-unused-assets,simplify-paths
 
-# 指定特定插件
-node dist/cli/index.js input.json --plugins remove-unused-assets,simplify-paths
+# 禁用某些插件
+lottie-opt input.json --disable compress-images
 
-# 排除某些插件
-node dist/cli/index.js input.json --disable compress-images
-
-# 插件配置
-node dist/cli/index.js input.json --plugin-config simplify-paths.tolerance=0.5,compress-images.quality=balanced
+# 自定义插件配置
+lottie-opt input.json --plugin-config simplify-paths.tolerance=0.5,compress-images.quality=balanced
 
 # 查看可用插件
-node dist/cli/index.js --list-plugins
-
-# 配置调试工具
-node dist/cli/index.js input.json --show-config
-node dist/cli/index.js input.json --show-config-sources
+lottie-opt --list-plugins
 
-# 详细报告和调试
-node dist/cli/index.js input.json --verbose --report
+# 详细输出 + 生成报告
+lottie-opt input.json --verbose --report
 
-# 质量验证和对比
-node dist/cli/index.js validate input.json --report --visual --playback
+# 预览模式（不保存）
+lottie-opt input.json --dry-run
 ```
 
-### 质量验证命令
-
-新增的 `validate` 命令提供完整的质量验证和压缩对比功能：
+### 质量验证
 
 ```bash
-# 基础验证
-node dist/cli/index.js validate input.json
-
-# 包含视觉验证的完整验证
-node dist/cli/index.js validate input.json --visual --playback
-
-# 生成详细 HTML 报告
-node dist/cli/index.js validate input.json --report
-
-# 自定义测试配置
-node dist/cli/index.js validate input.json --plugins remove-unused-assets,simplify-paths --report
+# 验证 Lottie 文件质量
+lottie-opt validate input.json
 
-# 完整验证（推荐）
-node dist/cli/index.js validate input.json --report --visual --playback
+# 完整验证 + HTML 报告
+lottie-opt validate input.json --report --visual --playback
 ```
 
-**验证功能说明：**
-- **结构验证**: 检查 Lottie JSON 格式完整性和规范性
-- **质量指标**: 计算结构完整性、动画连续性、数据一致性、性能评分
-- **视觉验证**: 模拟播放测试，检查渲染能力和性能指标  
-- **压缩对比**: 多个预设同时测试，生成对比表格和推荐
-- **HTML 报告**: 生成美观的网页报告，包含所有验证结果
-```
-
-### 编程接口
+## 编程接口
 
 ```typescript
-import { optimize } from 'lottie-opt';
+import { optimize } from 'lofter-lottie-opt';
 
 const result = await optimize(lottieData, {
   plugins: ['remove-unused-assets', 'minify-json', 'simplify-paths'],
   pluginOptions: {
-    'simplify-paths': { tolerance: 0.3, algorithm: 'rdp' },
-    'minify-json': { compressNames: false, keepMatchName: true }
+    'simplify-paths': { tolerance: 0.3 },
+    'minify-json': { compressNames: false }
   }
 });
 
-console.log(`优化: ${result.stats.originalSize} → ${result.stats.optimizedSize} bytes`);
+console.log(`${result.stats.originalSize} → ${result.stats.optimizedSize} bytes`);
 console.log(`压缩率: ${result.stats.compressionRatio.toFixed(1)}%`);
 ```
 
-## 配置系统
-
-### 配置调试
-
-lottie-opt 提供强大的配置调试工具，帮助您理解参数如何生效：
+## CLI 参数
 
-```bash
-# 查看每个插件的最终配置
-node dist/cli/index.js input.json --plugins compress-images --show-config
-
-# 查看配置来源（默认值 vs 用户值）
-node dist/cli/index.js input.json --plugins compress-images --show-config-sources
-```
+| 参数 | 说明 |
+|------|------|
+| `--plugins <list>` | 逗号分隔的插件列表 |
+| `--disable <list>` | 禁用的插件列表 |
+| `--plugin-config <config>` | 插件配置，格式 `plugin.option=value` |
+| `-c, --config <path>` | 配置文件路径 |
+| `-v, --verbose` | 详细日志 |
+| `-r, --report` | 生成优化报告 |
+| `--dry-run` | 仅分析不保存 |
+| `--show-config` | 显示生效的配置 |
+| `--list-plugins` | 列出可用插件 |
 
-输出示例：
-```
-[INFO] [compress-images] Configuration sources:
-  Default options: {
-    "quality": "balanced",     ← 插件默认值
-    "enableWebp": true,
-    "enableAvif": false
-  }
-  User options: {
-    "quality": "lossless",     ← 用户配置覆盖了默认值
-    "enableWebp": true,
-    "enableAvif": false
-  }
-```
+## 可用插件
 
-### 配置验证与建议
+### remove-unused-assets
 
-系统会自动验证配置并提供优化建议：
+**清理未使用的资源**，安全无损。BFS 算法扫描，支持预合成嵌套检测。
 
 ```bash
-# 使用可能有冲突的配置
-node -e "
-const opt = new (require('./dist/core/optimizer').LottieOptimizer)();
-opt.optimize({layers:[]}, {
-  plugins: ['compress-images', 'simplify-paths'],
-  pluginOptions: {
-    'compress-images': { quality: 'lossless', enableAvif: true, longEdge: 0 },
-    'simplify-paths': { tolerance: 2.0 }
-  },
-  debug: { showConfigSources: true }
-});
-"
-```
-
-输出：
-```
-[INFO] [compress-images] Suggestions: 使用无损质量时，现代格式的优势较小，考虑使用 balanced 质量
-[WARN] Configuration conflicts detected:
-  - 配置冲突：compress-images 使用无损质量，但 simplify-paths 的容差较大
-  - 性能警告：启用了 AVIF 且未限制图像尺寸，可能导致处理时间过长
+lottie-opt input.json --plugins remove-unused-assets
 ```
 
-### 配置优先级
+### simplify-paths
 
-配置按以下优先级合并（从高到低）：
-1. **用户直接传入的配置**
-2. **插件默认配置**
+**路径简化**，使用 RDP 算法减少贝塞尔曲线控制点。
 
-详细配置指南请参考 [配置系统文档](docs/configuration-guide.md)。
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `tolerance` | `1.0` | 误差容忍度（像素） |
+| `mode` | `static-only` | 模式：`static-only` / `animated-consistent` / `all` |
+| `minPoints` | `6` | 每条路径最少保留点数 |
+| `preserveCorners` | `true` | 保留尖角 |
 
-### compress-images 插件配置
-
-`compress-images` 插件使用简化的压缩策略，专注于文件大小优化：
-
-```typescript
-import { optimize } from 'lottie-opt';
-
-const result = await optimize(lottieData, {
-  plugins: ['compress-images'],  // 启用图像压缩插件
-  pluginOptions: {
-    'compress-images': {
-      enableWebp: true,     // 启用 WebP 格式（推荐）
-      enableAvif: false,    // 启用 AVIF 格式（更小但处理较慢）
-      quality: 'balanced',  // 质量档位：smallest/balanced/lossless
-      longEdge: 1920,       // 限制最长边像素
-      embed: true,          // 内嵌为 Data URL
-      onLog: console.log,   // 启用日志
-    }
-  }
-});
-```
-
-**简化的压缩策略**：
-- **质量档位**: 为每个档位预设多个质量级别进行测试
-  - `smallest`: [75, 60, 45] - 最小文件大小
-  - `balanced`: [85, 75, 60] - 质量与大小平衡
-  - `lossless`: [95, 85, 75] - 高质量压缩
-- **格式优先级**: 按用户偏好测试 WebP → AVIF → 传统格式
-- **自动选择**: 直接选择文件大小最小的结果
-- **透明度处理**: 自动选择 PNG（透明）或 JPEG（不透明）作为保底
-
-### minify-json 插件配置
-
-`minify-json` 插件专注于 JSON 结构层面的精简优化：
-
-```typescript
-import { optimize } from 'lottie-opt';
-
-const result = await optimize(lottieData, {
-  plugins: ['minify-json'],
-  pluginOptions: {
-    'minify-json': {
-      removeMetadataKeys: true,    // 删除 ix、mn、bm、ddd、np、cix 等元数据键
-      enableGlobalPrecision: true, // 全局数值精度控制，统一截取到3位小数
-      removeDefaultValues: true,   // 删除 bm:0、ddd:0、hd:false 等默认值
-      keepMatchName: true,         // 保留 matchName（mn）以确保工具兼容性
-      compressNames: true,         // 压缩名称字段为单字符（影响调试）
-      keepIds: false,              // ID 短名化，长ID转36进制短码
-      mergeNearbyNumbers: false,   // 合并相邻数值（激进优化）
-    }
-  }
-});
-```
-
-**JSON 精简策略**：
-- **元数据清理**: 删除渲染无关的索引、混合模式、3D标记等元数据键
-- **精度控制**: 全局统一数值精度，从平均2.97位小数降到3位小数上限
-- **默认值删除**: 系统性删除 bm:0、ddd:0、ao:0、sr:1、hd:false 等默认值
-- **名称压缩**: 可选将 nm 字段压缩为单字符（修/描/填/变等）
-- **ID优化**: 长ID转换为36进制短码，大幅减少字符数
+```bash
+lottie-opt input.json --plugin-config simplify-paths.tolerance=0.5,simplify-paths.preserveCorners=true
 ```
 
-## 可用插件
-
-### 核心优化插件
-- `remove-unused-assets`: 清理未引用资源（安全无损）
-- `simplify-paths`: 路径简化（RDP算法，可控有损）
-- `compress-images`: 图像压缩和优化（高级优化）
-- `minify-json`: JSON结构精简（删除元数据、降低精度、压缩体积）
-
-### 使用建议
-- **保守优化**: 使用 `remove-unused-assets`
-- **平衡优化**: 使用 `remove-unused-assets` + `minify-json` + `simplify-paths`
-- **激进优化**: 使用所有插件（默认行为）
+### compress-images
 
-## 优化效果
+**图像压缩**，支持 WebP/AVIF/JPEG/PNG，自动选择最小体积格式。
 
-**实际测试效果：**
-
-| 文件类型 | 基础优化 | 平衡优化 | 完整优化 | 质量保持 |
-|---------|----------|----------|----------|----------|
-| 简单动画 (2KB) | 10.9% | 10.9% | 10.9% | 100% |
-| 复杂动画 (156KB) | 0.1% | 0.1% | 67.3% | 100% |
-
-**插件特殊效果：**
-- **compress-images**: Sharp 图像压缩（简化版），支持 WebP/AVIF/JPEG/PNG，自动选择最小文件大小
-- **remove-unused-assets**: BFS 算法安全清理未引用资源，支持预合成嵌套
-- **simplify-paths**: RDP 算法路径简化，误差受控的贝塞尔曲线优化
-- **minify-json**: JSON精简优化，删除元数据键、降低数值精度、压缩名称字段
-
-## 项目架构
-
-```
-src/
-├── core/           # 核心优化引擎
-├── plugins/        # 插件实现（平铺结构，无分类文件夹）
-│   ├── remove-unused-assets/    # BFS 算法清理未引用资源
-│   ├── simplify-paths/          # RDP 算法路径简化
-│   ├── compress-images/         # Sharp 图像压缩（简化版）
-│   ├── minify-json/             # JSON结构精简优化
-│   └── index.ts                 # 插件注册
-├── plugins/        # 插件实现（平铺结构）
-├── cli/           # 命令行工具
-├── validation/    # 质量验证系统
-├── testing/       # 对比测试工具
-├── utils/         # 工具函数
-└── types/         # 类型定义
-```
-
-**插件系统特点：**
-- **平铺架构**: 所有插件文件位于 `plugins/` 根目录，便于管理和扩展
-- **自由组合**: 用户可以自由选择任意插件组合
-- **无预设依赖**: 移除了预设系统，简化了架构
-- **灵活配置**: 每个插件都可独立配置参数
-- **简化维护**: 新增插件只需添加到 `plugins/` 目录
-
-## 开发状态
-
-✅ **已完成**:
-- **核心架构**: 插件化架构系统
-- **CLI 工具**: 完整的命令行接口和编程 API  
-- **核心插件**: 4个实际可用插件
-  - `remove-unused-assets`: BFS 算法安全清理未引用资源
-  - `simplify-paths`: RDP 算法路径简化  
-  - `compress-images`: Sharp 图像压缩（简化版，文件大小优先策略）
-  - `minify-json`: JSON结构精简（删除元数据、降低精度、压缩体积）
-- **算法实现**: RDP 路径简化算法，BFS 资源清理算法
-- **图像处理**: Sharp 真实图像压缩，支持 WebP/AVIF/JPEG/PNG
-- **质量系统**: 完整的质量验证和对比测试框架
-- **可视化报告**: HTML 格式的详细分析报告
-- **视觉验证**: 播放能力测试和渲染验证
-
-✅ **质量验证系统功能**:
-- 结构完整性验证
-- 动画连续性检查  
-- 数据一致性分析
-- 性能指标计算
-- 多预设压缩对比
-- 视觉播放验证
-- HTML 详细报告生成
-
-🚧 **待完成**:
-- 像素级回归测试 (SSIM/RMSE)
-- ZIP 格式的完整 .lottie 包结构
-- 更多图像格式支持和优化算法
-
-## 使用示例
-
-### 完整的质量验证工作流
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enableWebp` | `true` | 启用 WebP |
+| `enableAvif` | `false` | 启用 AVIF（更小但处理慢） |
+| `quality` | `balanced` | 质量档位：`smallest` / `balanced` / `lossless` |
+| `longEdge` | `0` | 限制最长边像素，0=不限制 |
+| `embed` | `true` | 内嵌为 Data URL |
+| `useTinyPNG` | `false` | 使用 TinyPNG 压缩 |
 
 ```bash
-# 1. 先验证原始文件质量
-node dist/cli/index.js validate input.json --visual --playback
-
-# 2. 生成完整的对比报告
-node dist/cli/index.js validate input.json --report --visual --playback
-
-# 3. 根据推荐选择最佳预设进行优化
-node dist/cli/index.js input.json output.json --preset aggressive --report
-
-# 4. 验证优化后的文件
-node dist/cli/index.js validate output.json --visual --playback
+lottie-opt input.json --plugin-config compress-images.enableWebp=true,compress-images.quality=smallest
 ```
 
-### 实际测试示例
-
-基于真实项目测试：
-
-```bash
-# 简单动画文件（主要优化未使用资源）
-$ node dist/cli/index.js simple.json --plugins remove-unused-assets --verbose
-✓ Optimization Results: 424 B → 356 B (16.0% reduction)
-
-# 包含图片的复杂动画（所有插件优化）
-$ node dist/cli/index.js complex_with_images.json --report
-✓ Optimization Results: 156KB → 51KB (67.3% reduction)
-  Plugin Details:
-  - remove-unused-assets: 156KB → 156KB (0.0%)
-  - simplify-paths: 156KB → 155KB (0.6%) 
-  - compress-images: 155KB → 51KB (67.1%) ⚡ 主要优化
-```
+### minify-json
 
-### 验证报告示例
+**JSON 结构精简**，删除元数据、降低精度、压缩名称。
 
-质量验证会生成类似以下的对比表格：
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `removeMetadataKeys` | `true` | 删除 ix/mn/bm/ddd 等元数据 |
+| `enableGlobalPrecision` | `true` | 全局数值精度控制 |
+| `removeDefaultValues` | `true` | 删除默认值（bm:0, hd:false 等） |
+| `keepMatchName` | `true` | 保留 matchName 兼容性 |
+| `compressNames` | `true` | 压缩名称为单字符 |
+| `keepIds` | `false` | 保留原始 ID（否则转短码） |
 
-```
-┌─────────────┬─────────────┬─────────────┬──────────────┬────────────┐
-│ Config      │ Compression │ Quality     │ Playback     │ Rating     │
-├─────────────┼─────────────┼─────────────┼──────────────┼────────────┤
-│ basic       │       10.9% │      100.0% │          Yes │ Good       │
-│ balanced    │       10.9% │      100.0% │          Yes │ Good       │
-│ complete    │       67.3% │      100.0% │          Yes │ Excellent  │
-└─────────────┴─────────────┴─────────────┴──────────────┴────────────┘
-
-🏆 Recommended: Complete optimization
+```bash
+lottie-opt input.json --plugin-config minify-json.compressNames=false,minify-json.keepIds=true
 ```
 
-## 贡献
+## 推荐配置
 
-这是一个基于研究的 Lottie 优化器实现，遵循 LottieFiles 的优化原理并使用成熟的算法进行路径简化和质量验证。
+| 场景 | 命令 |
+|------|------|
+| 保守优化 | `--plugins remove-unused-assets` |
+| 平衡优化 | `--plugins remove-unused-assets,minify-json,simplify-paths` |
+| 激进优化 | 默认（全部插件） |
 
 ## 许可证
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lofter-lottie-opt",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A plugin-based Lottie JSON optimizer with configurable presets",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,7 +51,7 @@
     "lint": "eslint src --ext .ts",
     "clean": "rimraf dist",
     "changeset": "changeset",
-    "version": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "version": "changeset version && git add -A && git commit -m \"chore: version packages\"",
+    "release": "pnpm run build && changeset publish && git push && git push --tags"
   }
 }