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/batch_processor.py
View on GitHub#!/usr/bin/env python3
"""
batch_processor.py — 批量处理引擎
==================================
批量处理多个产品的素材生成,支持进度追踪、断点续传和失败重试。
核心职责:
1. 解析产品列表
2. 为每个产品调用 category_detector + style_matcher 生成配置
3. 输出标准化的任务队列
4. 追踪完成状态(实时更新状态文件)
5. 支持断点续传和失败重试
注意: 本脚本负责流程编排和输入准备,实际的生图和文字渲染
由主流程的 AI agent 执行。
Usage:
# 生成任务队列(预处理阶段)
python scripts/batch_processor.py \\
--input products.json \\
--output-dir ./batch_output \\
--status-file status.json \\
--prepare
# 查看当前状态
python scripts/batch_processor.py \\
--status-file status.json \\
--status
# 标记产品完成
python scripts/batch_processor.py \\
--status-file status.json \\
--mark-complete product_001 \\
--output-subdir ./batch_output/product_001 \\
--images-count 11
# 标记产品失败
python scripts/batch_processor.py \\
--status-file status.json \\
--mark-failed product_002 \\
--error "AI融合生图超时"
# 获取下一个待处理产品
python scripts/batch_processor.py \\
--status-file status.json \\
--next
# 重试失败的产品
python scripts/batch_processor.py \\
--status-file status.json \\
--retry-failed
# 生成汇总报告
python scripts/batch_processor.py \\
--status-file status.json \\
--report
依赖: 无外部依赖(纯Python + json)
"""
import argparse
import json
import os
import sys
import subprocess
from pathlib import Path
from datetime import datetime
from typing import Dict, List, Optional, Any
# ============================================================================
# 路径常量
# ============================================================================
SKILL_DIR = Path(__file__).parent.parent
SCRIPTS_DIR = SKILL_DIR / "scripts"
# ============================================================================
# 状态管理
# ============================================================================
def create_status_file(batch_id: str, products: List[dict],
status_file: str) -> dict:
"""
创建初始状态文件。
Args:
batch_id: 批次ID
products: 产品列表
status_file: 状态文件路径
Returns:
状态数据字典
"""
status = {
"batch_id": batch_id,
"created_at": datetime.now().isoformat(),
"last_updated": datetime.now().isoformat(),
"total": len(products),
"completed": 0,
"failed": 0,
"in_progress": 0,
"pending": len(products),
"products": []
}
for product in products:
pid = product.get("id", f"product_{products.index(product)}")
status["products"].append({
"id": pid,
"product_image": product.get("product_image", ""),
"brand": product.get("brand", ""),
"model": product.get("model", ""),
"category": product.get("category", ""),
"price": product.get("price", 0),
"platform": product.get("platform", "general"),
"style": product.get("style", ""),
"selling_points": product.get("selling_points", []),
"status": "pending",
"output_dir": None,
"images_count": 0,
"error": None,
"current_step": None,
"config_file": None,
"started_at": None,
"completed_at": None,
})
_save_status(status, status_file)
return status
def load_status(status_file: str) -> dict:
"""加载状态文件"""
if not os.path.isfile(status_file):
print(f"Error: 状态文件不存在: {status_file}", file=sys.stderr)
sys.exit(1)
with open(status_file, "r", encoding="utf-8") as f:
return json.load(f)
def _save_status(status: dict, status_file: str):
"""保存状态文件"""
status["last_updated"] = datetime.now().isoformat()
# 重新计算统计
statuses = [p["status"] for p in status["products"]]
status["completed"] = statuses.count("completed")
status["failed"] = statuses.count("failed")
status["in_progress"] = statuses.count("in_progress")
status["pending"] = statuses.count("pending")
output_path = Path(status_file)
output_path.parent.mkdir(parents=True, exist_ok=True)
with open(output_path, "w", encoding="utf-8") as f:
json.dump(status, f, ensure_ascii=False, indent=2)
def load_product_list(input_file: str) -> List[dict]:
"""
加载产品列表JSON。
Args:
input_file: 产品列表JSON路径
Returns:
产品列表
"""
if not os.path.isfile(input_file):
print(f"Error: 产品列表文件不存在: {input_file}", file=sys.stderr)
sys.exit(1)
with open(input_file, "r", encoding="utf-8") as f:
products = json.load(f)
if not isinstance(products, list):
print("Error: 产品列表必须是JSON数组", file=sys.stderr)
sys.exit(1)
# 验证必填字段
for i, product in enumerate(products):
if "product_image" not in product:
print(f"Error: 产品[{i}]缺少必填字段 product_image", file=sys.stderr)
sys.exit(1)
if "id" not in product:
product["id"] = f"product_{i+1:03d}"
return products
# ============================================================================
# 预处理:为每个产品生成配置
# ============================================================================
def prepare_product_config(product: dict, output_dir: str) -> dict:
"""
为单个产品生成配置文件(调用category_detector + style_matcher)。
Args:
product: 产品配置字典
output_dir: 输出目录
Returns:
配置结果字典
"""
pid = product["id"]
product_dir = Path(output_dir) / pid
product_dir.mkdir(parents=True, exist_ok=True)
config = {
"product_id": pid,
"product_image": product.get("product_image", ""),
"brand": product.get("brand", ""),
"model": product.get("model", ""),
"price": product.get("price", 0),
"platform": product.get("platform", "general"),
"selling_points": product.get("selling_points", []),
}
# Step 1: 品类识别(如果用户未指定品类)
category_result = None
if not product.get("category"):
category_file = product_dir / "category.json"
cmd = [
sys.executable, str(SCRIPTS_DIR / "category_detector.py"),
"--image", product["product_image"],
"--output", str(category_file)
]
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
if result.returncode == 0 and category_file.exists():
with open(category_file, "r", encoding="utf-8") as f:
category_result = json.load(f)
config["category"] = category_result.get("category", "家居日用")
config["sub_category"] = category_result.get("sub_category", "")
config["category_attributes"] = category_result.get("attributes", {})
else:
config["category"] = "家居日用"
config["sub_category"] = ""
config["category_note"] = "品类识别失败,使用默认品类"
except Exception as e:
config["category"] = "家居日用"
config["sub_category"] = ""
config["category_note"] = f"品类识别异常: {e}"
else:
config["category"] = product["category"]
config["sub_category"] = product.get("sub_category", product["category"])
# Step 2: 风格匹配
style_result = None
if config.get("category"):
style_file = product_dir / "style_recommendation.json"
cmd = [
sys.executable, str(SCRIPTS_DIR / "style_matcher.py"),
"--category", config["category"],
"--sub-category", config.get("sub_category", config["category"]),
"--price", str(config.get("price", 100)),
"--platform", config.get("platform", "general"),
"--output", str(style_file)
]
if product.get("brand"):
cmd.extend(["--brand", product["brand"]])
try:
result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
if result.returncode == 0 and style_file.exists():
with open(style_file, "r", encoding="utf-8") as f:
style_result = json.load(f)
config["style_recommendation"] = style_result
# 如果用户未指定风格,使用推荐的第一模板
if not product.get("style"):
templates = style_result.get("recommended_templates", [])
if templates:
config["style"] = templates[0].get("template_id", "minimalist")
except Exception as e:
config["style_note"] = f"风格匹配异常: {e}"
if not config.get("style"):
config["style"] = product.get("style", "minimalist")
# 保存配置
config_file = product_dir / "product_config.json"
with open(config_file, "w", encoding="utf-8") as f:
json.dump(config, f, ensure_ascii=False, indent=2)
config["config_file"] = str(config_file)
config["output_dir"] = str(product_dir)
return config
def prepare_batch(product_list: List[dict], output_dir: str,
status_file: str) -> dict:
"""
批量预处理:为所有产品生成配置并创建状态文件。
Args:
product_list: 产品列表
output_dir: 输出根目录
status_file: 状态文件路径
Returns:
状态数据字典
"""
batch_id = f"batch_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
# 创建状态文件
status = create_status_file(batch_id, product_list, status_file)
print(f"批次ID: {batch_id}")
print(f"产品总数: {len(product_list)}")
print(f"输出目录: {output_dir}")
print(f"状态文件: {status_file}")
print()
# 为每个产品生成配置
for i, product in enumerate(product_list):
pid = product["id"]
print(f"[{i+1}/{len(product_list)}] 预处理: {pid} ...", end=" ")
try:
config = prepare_product_config(product, output_dir)
# 更新状态文件
for p in status["products"]:
if p["id"] == pid:
p["config_file"] = config.get("config_file")
p["output_dir"] = config.get("output_dir")
p["category"] = config.get("category", "")
p["style"] = config.get("style", "")
break
print(f"✓ (品类: {config.get('category', '?')}, 风格: {config.get('style', '?')})")
except Exception as e:
print(f"✗ ({e})")
for p in status["products"]:
if p["id"] == pid:
p["status"] = "failed"
p["error"] = f"预处理失败: {e}"
break
_save_status(status, status_file)
# 打印汇总
print(f"\n预处理完成:")
print(f" 成功: {sum(1 for p in status['products'] if p['status'] == 'pending')}")
print(f" 失败: {sum(1 for p in status['products'] if p['status'] == 'failed')}")
return status
# ============================================================================
# 状态操作
# ============================================================================
def show_status(status_file: str):
"""显示当前状态"""
status = load_status(status_file)
print(f"=== 批次 {status['batch_id']} ===")
print(f"总计: {status['total']} | 完成: {status['completed']} | "
f"进行中: {status['in_progress']} | 失败: {status['failed']} | "
f"待处理: {status['pending']}")
print()
for p in status["products"]:
status_icon = {
"completed": "✅", "in_progress": "🔄",
"failed": "❌", "pending": "⏳"
}.get(p["status"], "?")
line = f" {status_icon} {p['id']}"
if p.get("category"):
line += f" ({p['category']})"
if p.get("current_step"):
line += f" [步骤: {p['current_step']}]"
if p["status"] == "completed":
line += f" → {p.get('images_count', 0)}张图"
elif p["status"] == "failed" and p.get("error"):
line += f" — {p['error'][:50]}"
print(line)
def get_next_product(status_file: str) -> Optional[dict]:
"""
获取下一个待处理的产品。
Returns:
下一个产品的配置信息,或None
"""
status = load_status(status_file)
for p in status["products"]:
if p["status"] == "pending":
# 标记为进行中
p["status"] = "in_progress"
p["current_step"] = "category_detect"
p["started_at"] = datetime.now().isoformat()
_save_status(status, status_file)
# 输出产品配置(供AI agent读取)
if p.get("config_file") and os.path.isfile(p["config_file"]):
with open(p["config_file"], "r", encoding="utf-8") as f:
config = json.load(f)
print(json.dumps(config, ensure_ascii=False, indent=2))
else:
print(json.dumps(p, ensure_ascii=False, indent=2))
return p
print("所有产品已处理完毕!")
return None
def mark_complete(status_file: str, product_id: str,
output_subdir: str = None, images_count: int = 0):
"""标记产品处理完成"""
status = load_status(status_file)
found = False
for p in status["products"]:
if p["id"] == product_id:
p["status"] = "completed"
p["completed_at"] = datetime.now().isoformat()
p["current_step"] = None
if output_subdir:
p["output_dir"] = output_subdir
p["images_count"] = images_count
found = True
break
if not found:
print(f"Error: 未找到产品 {product_id}", file=sys.stderr)
sys.exit(1)
_save_status(status, status_file)
print(f"✅ {product_id} 已标记完成 ({images_count}张图)")
def mark_failed(status_file: str, product_id: str, error: str = ""):
"""标记产品处理失败"""
status = load_status(status_file)
found = False
for p in status["products"]:
if p["id"] == product_id:
p["status"] = "failed"
p["error"] = error
p["current_step"] = None
found = True
break
if not found:
print(f"Error: 未找到产品 {product_id}", file=sys.stderr)
sys.exit(1)
_save_status(status, status_file)
print(f"❌ {product_id} 已标记失败: {error}")
def update_step(status_file: str, product_id: str, step: str):
"""更新产品当前处理步骤"""
status = load_status(status_file)
for p in status["products"]:
if p["id"] == product_id:
p["current_step"] = step
break
_save_status(status, status_file)
print(f"🔄 {product_id} 当前步骤: {step}")
def retry_failed(status_file: str) -> List[str]:
"""
重置失败的产品为待处理状态。
Returns:
被重置的产品ID列表
"""
status = load_status(status_file)
retried = []
for p in status["products"]:
if p["status"] == "failed":
p["status"] = "pending"
p["error"] = None
p["current_step"] = None
p["started_at"] = None
p["completed_at"] = None
retried.append(p["id"])
_save_status(status, status_file)
if retried:
print(f"已重置 {len(retried)} 个失败产品为待处理:")
for pid in retried:
print(f" ⏳ {pid}")
else:
print("没有失败的产品需要重试")
return retried
def generate_report(status_file: str) -> dict:
"""
生成批次处理汇总报告。
Returns:
报告字典
"""
status = load_status(status_file)
completed = [p for p in status["products"] if p["status"] == "completed"]
failed = [p for p in status["products"] if p["status"] == "failed"]
pending = [p for p in status["products"] if p["status"] == "pending"]
total_images = sum(p.get("images_count", 0) for p in completed)
report = {
"batch_id": status["batch_id"],
"created_at": status.get("created_at", ""),
"last_updated": status.get("last_updated", ""),
"summary": {
"total": status["total"],
"completed": len(completed),
"failed": len(failed),
"pending": len(pending),
"success_rate": f"{len(completed)/max(status['total'],1)*100:.1f}%",
"total_images": total_images,
},
"completed_products": [
{
"id": p["id"],
"category": p.get("category", ""),
"style": p.get("style", ""),
"images_count": p.get("images_count", 0),
"output_dir": p.get("output_dir", ""),
}
for p in completed
],
"failed_products": [
{
"id": p["id"],
"error": p.get("error", "未知错误"),
}
for p in failed
],
"pending_products": [
{"id": p["id"]}
for p in pending
]
}
# 打印可读报告
print("=" * 60)
print(f" 批次处理报告 — {status['batch_id']}")
print("=" * 60)
print(f" 总产品数: {status['total']}")
print(f" 完成: {len(completed)} | 失败: {len(failed)} | 待处理: {len(pending)}")
print(f" 成功率: {report['summary']['success_rate']}")
print(f" 总产出图数: {total_images}")
print()
if completed:
print("✅ 已完成:")
for p in completed:
print(f" {p['id']} — {p.get('images_count', 0)}张图 → {p.get('output_dir', '?')}")
if failed:
print("\n❌ 失败:")
for p in failed:
print(f" {p['id']} — {p.get('error', '?')}")
if pending:
print(f"\n⏳ 待处理: {', '.join(p['id'] for p in pending)}")
print("=" * 60)
return report
# ============================================================================
# CLI 入口
# ============================================================================
def main():
parser = argparse.ArgumentParser(
description="批量处理引擎 — 多产品素材生成流程编排",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
示例:
# 预处理:生成任务队列
python scripts/batch_processor.py \\
--input products.json --output-dir ./batch_output \\
--status-file status.json --prepare
# 查看状态
python scripts/batch_processor.py --status-file status.json --status
# 获取下一个待处理
python scripts/batch_processor.py --status-file status.json --next
# 标记完成
python scripts/batch_processor.py --status-file status.json \\
--mark-complete product_001 --output-subdir ./batch_output/product_001 \\
--images-count 11
# 标记失败
python scripts/batch_processor.py --status-file status.json \\
--mark-failed product_002 --error "生图超时"
# 重试失败
python scripts/batch_processor.py --status-file status.json --retry-failed
# 生成报告
python scripts/batch_processor.py --status-file status.json --report
"""
)
# 输入参数
parser.add_argument(
"--input", default=None,
help="产品列表JSON路径"
)
parser.add_argument(
"--output-dir", default=None,
help="输出根目录"
)
parser.add_argument(
"--status-file", default=None,
help="状态文件路径"
)
# 操作模式(互斥)
group = parser.add_mutually_exclusive_group(required=True)
group.add_argument("--prepare", action="store_true",
help="预处理模式:生成任务队列")
group.add_argument("--status", action="store_true",
help="查看当前状态")
group.add_argument("--next", action="store_true",
help="获取下一个待处理产品")
group.add_argument("--mark-complete", metavar="PRODUCT_ID",
help="标记产品处理完成")
group.add_argument("--mark-failed", metavar="PRODUCT_ID",
help="标记产品处理失败")
group.add_argument("--update-step", metavar="STEP",
help="更新当前处理步骤(需配合 --product-id)")
group.add_argument("--retry-failed", action="store_true",
help="重试所有失败产品")
group.add_argument("--report", action="store_true",
help="生成汇总报告")
# 辅助参数
parser.add_argument("--product-id", default=None,
help="产品ID(配合 --update-step 使用)")
parser.add_argument("--output-subdir", default=None,
help="产品输出子目录(配合 --mark-complete 使用)")
parser.add_argument("--images-count", type=int, default=0,
help="产出图片数(配合 --mark-complete 使用)")
parser.add_argument("--error", default=None,
help="错误信息(配合 --mark-failed 使用)")
args = parser.parse_args()
# 验证必要参数
if args.prepare:
if not args.input or not args.output_dir or not args.status_file:
parser.error("--prepare 模式需要 --input, --output-dir, --status-file")
product_list = load_product_list(args.input)
prepare_batch(product_list, args.output_dir, args.status_file)
elif args.status:
if not args.status_file:
parser.error("--status 需要 --status-file")
show_status(args.status_file)
elif args.next:
if not args.status_file:
parser.error("--next 需要 --status-file")
get_next_product(args.status_file)
elif args.mark_complete:
if not args.status_file:
parser.error("--mark-complete 需要 --status-file")
mark_complete(args.status_file, args.mark_complete,
args.output_subdir, args.images_count)
elif args.mark_failed:
if not args.status_file:
parser.error("--mark-failed 需要 --status-file")
mark_failed(args.status_file, args.mark_failed, args.error or "未知错误")
elif args.update_step:
if not args.status_file or not args.product_id:
parser.error("--update-step 需要 --status-file 和 --product-id")
update_step(args.status_file, args.product_id, args.update_step)
elif args.retry_failed:
if not args.status_file:
parser.error("--retry-failed 需要 --status-file")
retry_failed(args.status_file)
elif args.report:
if not args.status_file:
parser.error("--report 需要 --status-file")
generate_report(args.status_file)
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 |