davepoon/buildwithclaude / plugins/all-skills/skills/ecommerce-material-studio
ecommerce-material-studio
Verified电商素材工坊(中英双语)。用户需要生成电商主图、详情图、场景图、产品图合成、品牌叠加时使用。自动识别品类→匹配风格→场景感知合成→统一文字→自动质检→多平台适配→标准化交付。E-commerce product image studio: category detection, style matching, scene-aware compositing, text overlay, quality check, multi-platform adaptation, batch delivery.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
| references/brand_config_template.jsonexecutable | script | 798 B |
| references/brand_profiles/langke.json | config | 923 B |
| references/category_templates.json | config | 14.7 KB |
| references/product_profiles.json | config | 991 B |
| references/user_preferences.json | config | 231 B |
| scripts/batch_processor.pyexecutable | script | 23.7 KB |
| scripts/brand_loader.py | script | 12.9 KB |
| scripts/category_detector.pyexecutable | script | 27.2 KB |
| scripts/delivery_packager.py | script | 26.7 KB |
| scripts/layout_engine.pyexecutable | script | 38.7 KB |
| scripts/platform_adapter.pyexecutable | script | 22.8 KB |
| scripts/preference_memory.py | script | 14.8 KB |
| scripts/quality_check.pyexecutable | script | 20.4 KB |
| scripts/scene_aware_compositor.py | script | 49.1 KB |
| scripts/style_matcher.py | script | 19.8 KB |
| scripts/text_engine.py | script | 46.5 KB |
scripts/quality_check.py
View on GitHub#!/usr/bin/env python3
"""
quality_check.py — 自动质检清单
================================
出图前自动检查常见问题,输出JSON质检报告 + 人类可读checklist。
检查项:
1. 分辨率检查:主图≥1000×1000,详情图≥1200×1600
2. 文字可读性:采样文字区域背景色和文字色,计算对比度
3. 品牌Logo检查:检测logo区域是否有非透明像素
4. 文件完整性:检查output_dir中是否有完整的11张图
5. 文字重叠检测:检查text_zones和product_bbox是否有重叠
用法:
# 完整质检(读取plan.json + 检查成品图)
python quality_check.py --plan /path/to/plan.json
# 只检查文件完整性
python quality_check.py --plan /path/to/plan.json --check-only files
# 检查单张图片
python quality_check.py --image /path/to/image.png --type main
# 输出详细JSON报告
python quality_check.py --plan /path/to/plan.json --format json --output report.json
依赖: Pillow (可选: numpy用于更精确的对比度检测)
"""
import argparse
import json
import os
import sys
from pathlib import Path
from typing import Optional, List, Dict, Any, Tuple
from datetime import datetime
from PIL import Image
# ============================================================================
# 常量
# ============================================================================
# 标准尺寸
MAIN_IMAGE_SIZE = (1000, 1000)
DETAIL_IMAGE_SIZE = (1200, 1600)
EXPECTED_MAIN_COUNT = 5
EXPECTED_DETAIL_COUNT = 6
EXPECTED_TOTAL = EXPECTED_MAIN_COUNT + EXPECTED_DETAIL_COUNT
# 对比度阈值(WCAG AA)
MIN_CONTRAST_RATIO = 4.5
# 允许的分辨率误差(像素)
RESOLUTION_TOLERANCE = 50
# ============================================================================
# 颜色工具
# ============================================================================
def relative_luminance(r: int, g: int, b: int) -> float:
"""计算RGB的相对亮度"""
def linearize(c: int) -> float:
s = c / 255.0
return s / 12.92 if s <= 0.03928 else ((s + 0.055) / 1.055) ** 2.4
return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b)
def contrast_ratio(c1: Tuple[int, int, int], c2: Tuple[int, int, int]) -> float:
"""计算两个RGB颜色的对比度"""
l1 = relative_luminance(*c1)
l2 = relative_luminance(*c2)
lighter = max(l1, l2)
darker = min(l1, l2)
return (lighter + 0.05) / (darker + 0.05)
def sample_region_avg(img: Image.Image, bbox: Tuple[int, int, int, int]) -> Tuple[int, int, int]:
"""采样区域平均颜色"""
x1, y1, x2, y2 = bbox
x1, y1 = max(0, x1), max(0, y1)
x2, y2 = min(img.width, x2), min(img.height, y2)
if x2 <= x1 or y2 <= y1:
return (128, 128, 128)
region = img.crop((x1, y1, x2, y2)).convert("RGB")
pixels = list(region.getdata())
if not pixels:
return (128, 128, 128)
return (
sum(p[0] for p in pixels) // len(pixels),
sum(p[1] for p in pixels) // len(pixels),
sum(p[2] for p in pixels) // len(pixels),
)
# ============================================================================
# 检查器
# ============================================================================
class CheckResult:
"""单项检查结果"""
def __init__(self, name: str, passed: bool, message: str,
severity: str = "info", details: Optional[Dict] = None):
self.name = name
self.passed = passed
self.message = message
self.severity = severity # "error", "warning", "info"
self.details = details or {}
def to_dict(self) -> Dict:
return {
"name": self.name,
"passed": self.passed,
"message": self.message,
"severity": self.severity,
"details": self.details,
}
def check_resolution(image_path: str, image_type: str) -> CheckResult:
"""
检查图片分辨率
Args:
image_path: 图片路径
image_type: "main" 或 "detail"
"""
try:
img = Image.open(image_path)
w, h = img.size
except Exception as e:
return CheckResult("分辨率检查", False, f"无法打开图片: {e}", "error")
if image_type == "main":
expected_w, expected_h = MAIN_IMAGE_SIZE
name = "主图"
else:
expected_w, expected_h = DETAIL_IMAGE_SIZE
name = "详情图"
w_ok = w >= expected_w - RESOLUTION_TOLERANCE
h_ok = h >= expected_h - RESOLUTION_TOLERANCE
if w_ok and h_ok:
return CheckResult(
f"{name}分辨率检查", True,
f"{w}×{h} ✅ (要求≥{expected_w}×{expected_h})"
)
else:
return CheckResult(
f"{name}分辨率检查", False,
f"{w}×{h} ❌ (要求≥{expected_w}×{expected_h})",
"error",
{"actual": [w, h], "expected": [expected_w, expected_h]}
)
def check_text_readability(image_path: str, text_zones: List[Dict],
text_colors: List[Tuple[int, int, int]]) -> CheckResult:
"""
检查文字可读性(对比度)
Args:
image_path: 成品图路径
text_zones: 文字区域列表 [{x1, y1, x2, y2}, ...]
text_colors: 对应的文字颜色列表
"""
if not text_zones:
return CheckResult("文字可读性", True, "无文字区域,跳过检查")
try:
img = Image.open(image_path).convert("RGB")
except Exception as e:
return CheckResult("文字可读性", False, f"无法打开图片: {e}", "error")
issues = []
min_ratio = float('inf')
for i, zone in enumerate(text_zones):
if isinstance(zone, dict) and "bbox" in zone:
bbox = zone["bbox"]
else:
bbox = zone
x1, y1 = bbox.get("x1", 0), bbox.get("y1", 0)
x2, y2 = bbox.get("x2", img.width), bbox.get("y2", img.height)
# 采样文字区域周围的背景色
# 取文字区域上方和左方的背景
sample_bboxes = [
(max(0, x1 - 20), max(0, y1 - 20), x1, y1), # 左上角外侧
(x2, max(0, y1 - 20), min(img.width, x2 + 20), y1), # 右上角外侧
]
bg_colors = [sample_region_avg(img, sb) for sb in sample_bboxes]
if not bg_colors:
continue
avg_bg = (
sum(c[0] for c in bg_colors) // len(bg_colors),
sum(c[1] for c in bg_colors) // len(bg_colors),
sum(c[2] for c in bg_colors) // len(bg_colors),
)
text_color = text_colors[i] if i < len(text_colors) else (255, 255, 255)
ratio = contrast_ratio(avg_bg, text_color)
min_ratio = min(min_ratio, ratio)
if ratio < MIN_CONTRAST_RATIO:
issues.append({
"zone_id": zone.get("id", f"zone_{i}"),
"contrast_ratio": round(ratio, 2),
"bg_color": avg_bg,
"text_color": text_color,
"minimum_required": MIN_CONTRAST_RATIO,
})
if issues:
return CheckResult(
"文字可读性", False,
f"{len(issues)}个文字区域对比度不足 (最低: {min_ratio:.1f}:1, 要求≥{MIN_CONTRAST_RATIO}:1)",
"warning",
{"issues": issues}
)
return CheckResult(
"文字可读性", True,
f"所有文字区域对比度合格 (最低: {min_ratio:.1f}:1)"
)
def check_logo_presence(image_path: str, logo_zone: Optional[Dict]) -> CheckResult:
"""
检查Logo是否正确叠加
Args:
image_path: 成品图路径
logo_zone: Logo区域 {x1, y1, x2, y2}
"""
if not logo_zone:
return CheckResult("Logo检查", True, "无Logo区域配置,跳过检查")
try:
img = Image.open(image_path).convert("RGBA")
except Exception as e:
return CheckResult("Logo检查", False, f"无法打开图片: {e}", "error")
x1 = logo_zone.get("x1", 0)
y1 = logo_zone.get("y1", 0)
x2 = logo_zone.get("x2", img.width)
y2 = logo_zone.get("y2", img.height)
# 检查Logo区域是否有非白色/非透明像素
region = img.crop((x1, y1, x2, y2))
pixels = list(region.getdata())
non_white_count = 0
for p in pixels:
if len(p) >= 4 and p[3] > 50: # 有alpha
if p[0] < 240 or p[1] < 240 or p[2] < 240: # 非纯白
non_white_count += 1
elif len(p) < 4:
if p[0] < 240 or p[1] < 240 or p[2] < 240:
non_white_count += 1
total_pixels = len(pixels)
ratio = non_white_count / total_pixels if total_pixels > 0 else 0
if ratio > 0.05: # 至少5%的像素是Logo内容
return CheckResult(
"Logo检查", True,
f"Logo区域检测到内容 ({ratio*100:.1f}%非背景像素)"
)
else:
return CheckResult(
"Logo检查", False,
f"Logo区域几乎无内容 ({ratio*100:.1f}%非背景像素),可能未叠加",
"warning",
{"zone": logo_zone, "non_bg_ratio": round(ratio, 4)}
)
def check_file_completeness(output_dir: str, plan: Dict) -> CheckResult:
"""
检查输出文件完整性
Args:
output_dir: 输出目录
plan: plan.json数据
"""
if not output_dir or not Path(output_dir).exists():
return CheckResult("文件完整性", False, f"输出目录不存在: {output_dir}", "error")
expected_files = []
for img_cfg in plan.get("main_images", []):
expected_files.append(f"{img_cfg['id']}.png")
for img_cfg in plan.get("detail_images", []):
expected_files.append(f"{img_cfg['id']}.png")
missing = []
present = []
for f in expected_files:
if Path(output_dir, f).exists():
present.append(f)
else:
missing.append(f)
if missing:
return CheckResult(
"文件完整性", False,
f"缺少 {len(missing)}/{len(expected_files)} 张图",
"error",
{"missing": missing, "present": present}
)
return CheckResult(
"文件完整性", True,
f"全部 {len(expected_files)} 张图已生成"
)
def check_text_product_overlap(plan_image: Dict) -> CheckResult:
"""
检查文字区域与产品bbox是否重叠
Args:
plan_image: 单张图的plan配置
"""
product_bbox = plan_image.get("product_bbox")
text_zones = plan_image.get("text_zones", [])
if not product_bbox:
return CheckResult("文字避让", True, "无产品bbox,跳过检查")
if not text_zones:
return CheckResult("文字避让", True, "无text_zones配置,跳过检查")
overlaps = []
for zone in text_zones:
zone_bbox = zone.get("bbox", {})
if not zone_bbox:
continue
# 检查重叠
x1 = max(product_bbox.get("x1", 0), zone_bbox.get("x1", 0))
y1 = max(product_bbox.get("y1", 0), zone_bbox.get("y1", 0))
x2 = min(product_bbox.get("x2", 0), zone_bbox.get("x2", 0))
y2 = min(product_bbox.get("y2", 0), zone_bbox.get("y2", 0))
if x2 > x1 and y2 > y1:
overlap_area = (x2 - x1) * (y2 - y1)
zone_area = (zone_bbox.get("x2", 0) - zone_bbox.get("x1", 0)) * \
(zone_bbox.get("y2", 0) - zone_bbox.get("y1", 0))
if zone_area > 0:
overlap_ratio = overlap_area / zone_area
if overlap_ratio > 0.2: # 超过20%面积重叠
overlaps.append({
"zone_id": zone.get("id", "unknown"),
"overlap_ratio": round(overlap_ratio, 3),
"overlap_area": overlap_area,
})
if overlaps:
return CheckResult(
"文字避让", False,
f"{len(overlaps)}个文字区域与产品区域重叠",
"warning",
{"overlaps": overlaps}
)
return CheckResult("文字避让", True, "文字区域与产品无重叠")
# ============================================================================
# 质检报告生成
# ============================================================================
def run_full_check(plan_path: str, check_type: Optional[str] = None) -> Dict:
"""
运行完整质检
Args:
plan_path: plan.json路径
check_type: 限定检查类型 ("files", "resolution", "readability", "logo", "overlap")
Returns:
质检报告dict
"""
with open(plan_path, "r", encoding="utf-8") as f:
plan = json.load(f)
output_dir = plan.get("output_dir", "")
results: List[CheckResult] = []
all_images = []
for kind, items in [("main", plan.get("main_images", [])),
("detail", plan.get("detail_images", []))]:
for img_cfg in items:
all_images.append((kind, img_cfg))
# 1. 文件完整性
if not check_type or check_type == "files":
results.append(check_file_completeness(output_dir, plan))
# 逐图检查
for kind, img_cfg in all_images:
img_id = img_cfg.get("id", "unknown")
img_path = str(Path(output_dir) / f"{img_id}.png")
if not Path(img_path).exists():
if not check_type or check_type == "resolution":
results.append(CheckResult(
f"{img_id}分辨率", False,
"文件不存在,跳过检查", "error"
))
continue
# 2. 分辨率检查
if not check_type or check_type == "resolution":
results.append(check_resolution(img_path, kind))
# 3. 文字可读性
if not check_type or check_type == "readability":
text_zones = img_cfg.get("text_zones", [])
# 提取文字颜色
text_colors = []
for text_cfg in img_cfg.get("texts", []):
color_str = text_cfg.get("color", "#FFFFFF")
if isinstance(color_str, str):
c = color_str.lstrip("#")
if len(c) == 6:
text_colors.append((int(c[0:2], 16), int(c[2:4], 16), int(c[4:6], 16)))
else:
text_colors.append((255, 255, 255))
else:
text_colors.append(tuple(color_str[:3]))
results.append(check_text_readability(img_path, text_zones, text_colors))
# 4. Logo检查
if not check_type or check_type == "logo":
brand_zones = img_cfg.get("brand_zones", {})
logo_zone = brand_zones.get("logo")
results.append(check_logo_presence(img_path, logo_zone))
# 5. 文字重叠检测
if not check_type or check_type == "overlap":
results.append(check_text_product_overlap(img_cfg))
# 生成报告
report = {
"timestamp": datetime.now().isoformat(),
"plan_path": plan_path,
"product": plan.get("product", {}).get("name", "unknown"),
"total_checks": len(results),
"passed": sum(1 for r in results if r.passed),
"failed": sum(1 for r in results if not r.passed),
"errors": sum(1 for r in results if not r.passed and r.severity == "error"),
"warnings": sum(1 for r in results if not r.passed and r.severity == "warning"),
"results": [r.to_dict() for r in results],
}
report["overall_pass"] = all(
r.passed or r.severity != "error" for r in results
)
return report
def format_human_readable(report: Dict) -> str:
"""生成人类可读的质检清单"""
lines = []
lines.append("=" * 60)
lines.append(f"📋 质检报告 — {report.get('product', 'unknown')}")
lines.append(f"📅 {report.get('timestamp', '')}")
lines.append("=" * 60)
lines.append("")
total = report.get("total_checks", 0)
passed = report.get("passed", 0)
failed = report.get("failed", 0)
errors = report.get("errors", 0)
warnings = report.get("warnings", 0)
status_emoji = "✅" if report.get("overall_pass") else "⚠️"
lines.append(f"总评: {status_emoji} {'通过' if report.get('overall_pass') else '有问题需关注'}")
lines.append(f"检查项: {total} | 通过: {passed} | 失败: {failed} (错误: {errors}, 警告: {warnings})")
lines.append("")
lines.append("-" * 40)
for r in report.get("results", []):
icon = "✅" if r["passed"] else ("❌" if r["severity"] == "error" else "⚠️")
lines.append(f" {icon} {r['name']}: {r['message']}")
lines.append("")
lines.append("=" * 60)
if not report.get("overall_pass"):
lines.append("")
lines.append("⚠️ 需要处理的问题:")
for r in report.get("results", []):
if not r["passed"] and r["severity"] == "error":
lines.append(f" ❌ {r['name']}: {r['message']}")
lines.append("")
lines.append("💡 建议:")
if any("分辨率" in r["name"] for r in report["results"] if not r["passed"]):
lines.append(" - 重新生成低分辨率的图片,确保主图≥1000×1000,详情图≥1200×1600")
if any("文件完整性" in r["name"] for r in report["results"] if not r["passed"]):
lines.append(" - 检查缺失的文件并重新渲染")
if any("可读性" in r["name"] for r in report["results"] if not r["passed"]):
lines.append(" - 为对比度不足的文字添加背景块或描边,或使用text_engine.py的自动可读性增强")
if any("Logo" in r["name"] for r in report["results"] if not r["passed"]):
lines.append(" - 检查Logo文件路径是否正确,或重新运行品牌叠加")
return "\n".join(lines)
# ============================================================================
# CLI
# ============================================================================
def main():
parser = argparse.ArgumentParser(
description="自动质检清单 — 电商素材一站式工坊",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
示例:
# 完整质检
python quality_check.py --plan /path/to/plan.json
# 只检查文件完整性
python quality_check.py --plan /path/to/plan.json --check-only files
# 检查单张图片
python quality_check.py --image /path/to/image.png --type main
# 输出JSON报告
python quality_check.py --plan /path/to/plan.json --format json --output report.json
检查项:
1. 分辨率检查:主图≥1000×1000,详情图≥1200×1600
2. 文字可读性:对比度≥4.5:1 (WCAG AA)
3. Logo检查:Logo区域是否有内容
4. 文件完整性:11张图是否齐全
5. 文字重叠:text_zones与product_bbox无重叠
"""
)
parser.add_argument("--plan", help="plan.json 路径")
parser.add_argument("--image", help="检查单张图片")
parser.add_argument("--type", choices=["main", "detail"], help="图片类型(配合--image使用)")
parser.add_argument("--check-only", choices=["files", "resolution", "readability", "logo", "overlap"],
help="只运行特定检查")
parser.add_argument("--format", default="text", choices=["text", "json"],
help="输出格式 (default: text)")
parser.add_argument("--output", help="输出文件路径")
args = parser.parse_args()
if args.image:
# 单图模式
if not args.type:
print("❌ 请指定 --type main 或 --type detail", file=sys.stderr)
sys.exit(1)
results = [check_resolution(args.image, args.type)]
report = {
"timestamp": datetime.now().isoformat(),
"image": args.image,
"total_checks": len(results),
"passed": sum(1 for r in results if r.passed),
"failed": sum(1 for r in results if not r.passed),
"results": [r.to_dict() for r in results],
"overall_pass": all(r.passed for r in results),
}
elif args.plan:
report = run_full_check(args.plan, args.check_only)
else:
parser.print_help()
sys.exit(0)
# 输出
if args.format == "json":
output_str = json.dumps(report, ensure_ascii=False, indent=2)
else:
output_str = format_human_readable(report)
if args.output:
Path(args.output).parent.mkdir(parents=True, exist_ok=True)
with open(args.output, "w", encoding="utf-8") as f:
f.write(output_str)
print(f"📄 报告已保存到: {args.output}")
else:
print(output_str)
# 退出码
sys.exit(0 if report.get("overall_pass", True) else 1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |