asset-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Asset Manager

资产管理器

Manages design assets across projects: directory organization, naming conventions, image/font optimization, brand libraries, and version control. Use when assets need to be organized, compressed, converted to modern formats, or tracked across releases. Not for runtime image transformations or CDN configuration beyond path prefixing.

跨项目管理设计资产：目录整理、命名规范、图片/字体优化、品牌库及版本控制。适用于需要整理、压缩、转换为现代格式或跨版本跟踪资产的场景。不适用于运行时图片转换或路径前缀之外的CDN配置。

Quick Reference

快速参考

Task	Tool / Approach	Key Points
Image optimization	Sharp	Resize, compress, convert to WebP/AVIF/JPEG/PNG
SVG optimization	SVGO (v4+)	`removeViewBox` and `removeTitle` off by default in v4
Font conversion	`woff2_compress` , `sfnt2woff`	TTF/OTF to WOFF2 (primary) + WOFF (fallback)
Font subsetting	Glyphhanger	Remove unused glyphs, auto-detect from crawled pages
Responsive images	Sharp breakpoints	Generate mobile (640), tablet (768), desktop (1920) variants
Asset versioning	SHA-256 hash tracking	`asset-versions.json` manifest with change detection
Large files in git	Git LFS	Track PSD, AI, Sketch, Figma, MP4, MOV files
Brand assets	Typed manifest	`BrandAssets` interface with logos, colors, typography

任务	工具/方法	关键点
图片优化	Sharp	调整尺寸、压缩、转换为WebP/AVIF/JPEG/PNG格式
SVG优化	SVGO (v4+)	v4版本中默认关闭 `removeViewBox` 和 `removeTitle` 功能
字体转换	`woff2_compress` , `sfnt2woff`	将TTF/OTF格式转换为WOFF2（主格式）+ WOFF（兼容 fallback）
字体子集化	Glyphhanger	移除未使用字形，自动从爬取页面中检测需保留的字形
响应式图片生成	Sharp断点配置	生成移动端（640）、平板端（768）、桌面端（1920）变体图片
资产版本控制	SHA-256哈希跟踪	通过 `asset-versions.json` 清单文件实现变更检测
Git中的大文件处理	Git LFS	跟踪PSD、AI、Sketch、Figma、MP4、MOV等文件
品牌资产管理	类型化清单	包含Logo、颜色、排版规范的 `BrandAssets` 接口

Directory Structure

目录结构

Directory	Contents
`assets/images/{category}/`	Products, team, marketing, UI images
`assets/icons/svg/`	SVG icon files
`assets/fonts/{family}/`	WOFF2 + WOFF font files
`assets/videos/`	Video assets
`assets/logos/svg/` , `png/` , `variants/`	Logo formats and color variants
`brand/`	Colors JSON, typography JSON, guidelines

目录路径	内容
`assets/images/{category}/`	产品、团队、营销、UI类图片
`assets/icons/svg/`	SVG图标文件
`assets/fonts/{family}/`	WOFF2 + WOFF格式字体文件
`assets/videos/`	视频资产
`assets/logos/svg/` , `png/` , `variants/`	Logo的不同格式及颜色变体
`brand/`	颜色JSON、排版JSON、品牌规范文档

Naming Conventions

命名规范

Asset Type	Pattern	Example
Images	`{category}-{description}-{size}.{format}`	`product-hero-1920x1080.jpg`
Icons	`{icon-name}-{variant}.svg`	`home-outline.svg`
Fonts	`{font-family}-{weight}.{format}`	`Inter-Regular.woff2`
Logos	`logo-{variant}.{format}`	`logo-full.svg` , `logo-white.svg`

资产类型	命名模式	示例
图片	`{category}-{description}-{size}.{format}`	`product-hero-1920x1080.jpg`
图标	`{icon-name}-{variant}.svg`	`home-outline.svg`
字体	`{font-family}-{weight}.{format}`	`Inter-Regular.woff2`
Logo	`logo-{variant}.{format}`	`logo-full.svg` , `logo-white.svg`

Optimization Targets

优化目标

Format	Tool	Use Case
WebP	Sharp	Primary web images
AVIF	Sharp	Modern browsers, best compression
JPEG	Sharp (mozjpeg)	Fallback photos
PNG	Sharp	UI elements with transparency
SVG	SVGO	Icons and logos
WOFF2	`woff2_compress`	Primary web fonts
WOFF	`sfnt2woff`	Font fallback

格式	工具	使用场景
WebP	Sharp	网页主图格式
AVIF	Sharp	现代浏览器，压缩效果最优
JPEG	Sharp (mozjpeg)	图片兼容 fallback
PNG	Sharp	带透明效果的UI元素
SVG	SVGO	图标和Logo
WOFF2	`woff2_compress`	网页主字体格式
WOFF	`sfnt2woff`	字体兼容 fallback

Pipeline Steps

流水线步骤

Step	Action
Organize	Sort unsorted assets by naming rules into directories
Optimize images	Resize, compress, generate WebP/AVIF variants
Responsive images	Generate mobile/tablet/desktop breakpoint sizes
Optimize fonts	Convert TTF/OTF to WOFF2 + WOFF
Version	Hash-based tracking with `asset-versions.json`

步骤	操作内容
整理资产	按照命名规则将未分类资产归类到对应目录
图片优化	调整尺寸、压缩、生成WebP/AVIF格式变体
响应式图片生成	生成移动端/平板端/桌面端断点尺寸的图片变体
字体优化	将TTF/OTF格式转换为WOFF2 + WOFF格式
版本控制	通过 `asset-versions.json` 实现基于哈希的资产跟踪

Common Mistakes

常见错误

Mistake	Fix
Committing raw design files to git	Use Git LFS for PSD, AI, Sketch, Figma, video files
Serving original-size images	Generate responsive variants at breakpoints
Using only JPEG/PNG	Generate WebP + AVIF with fallbacks
No font subsetting	Use Glyphhanger to subset unused glyphs
Missing `font-display: swap`	Always set on `@font-face` to avoid FOIT
No CDN for assets	Prefix asset paths with `CDN_URL` env variable
Using imagemin for new projects	Use Sharp directly; imagemin is unmaintained
Using SVGO v3 plugin config with v4	`removeViewBox` and `removeTitle` are off by default in v4

错误内容	修复方案
将原始设计文件提交到Git	使用Git LFS管理PSD、AI、Sketch、Figma、视频文件
直接提供原始尺寸图片	生成对应断点尺寸的响应式图片变体
仅使用JPEG/PNG格式	生成WebP + AVIF格式图片并保留兼容 fallback
未进行字体子集化	使用Glyphhanger移除未使用字形
未设置 `font-display: swap`	在 `@font-face` 中始终设置该属性以避免FOIT（字体加载时文本不可见）
未使用CDN托管资产	使用 `CDN_URL` 环境变量为资产路径添加前缀
新项目中使用imagemin	直接使用Sharp；imagemin已停止维护
在SVGO v4中使用v3版本的插件配置	SVGO v4版本默认关闭 `removeViewBox` 和 `removeTitle` 功能

Delegation

任务委派

Discover asset organization patterns in a codebase: Use
```
Explore
```
agent to find existing asset directories, naming conventions, and optimization scripts
Optimize a batch of images or fonts: Use
```
Task
```
agent to run Sharp pipelines, font conversions, and responsive image generation
Plan a complete asset pipeline: Use
```
Plan
```
agent to design directory structure, naming conventions, optimization steps, and CI integration

探索代码库中的资产组织模式：使用
```
Explore
```
agent查找现有资产目录、命名规范及优化脚本
批量优化图片或字体：使用
```
Task
```
agent运行Sharp流水线、字体转换及响应式图片生成任务
规划完整资产流水线：使用
```
Plan
```
agent设计目录结构、命名规范、优化步骤及CI集成方案

References

参考文档

Organization
Image Optimization
Font Management
Version Control
Brand Library
Best Practices

资产组织
图片优化
字体管理
版本控制
品牌库
最佳实践