archive-behance

name	archive-behance
description	Archive Behance projects to Eagle DAM (Digital Asset Management) library. Use when user wants to archive or save a Behance project URL to their Eagle collection with proper metadata. Triggers include requests like '归档 https://www.behance.net/gallery/...', '保存 Behance 项目', 'archive behance project', or any request to download or save Behance gallery content to local Eagle library.
argument-hint	<Behance project URL>
disable-model-invocation	true

Archive Behance

Archive Behance projects to Eagle DAM library with proper folder structure and metadata.

Workflow

When user requests to archive a Behance URL:

1. Extract project info from the Behance page:

   • Project title
   • Creative field/category (e.g., "Illustration", "Graphic Design")
   • All project images (from mir-s3-cdn domain)
   • Tags

2. Determine target folder in Eagle library:

   • Base path: Collections > Behance
   • Subfolder based on creative field:
     • "Illustration" → 插画
     • "Graphic Design" → 平面设计
     • "Photography" → 摄影
     • "UI/UX" → UI/UX
     • "Motion Graphics" → 动效
     • "Typography" → 字体设计
     • Others → ask user or use 未分类

3. Create project folder with sanitized name (slug from URL or project title)

4. Download images and create Eagle metadata:

   • Use original image URL from mir-s3-cdn-cf.behance.net
   • Name: use image alt text or generate sequential name
   • URL: image source URL (permanent link)
   • Tags: optional, can be empty

5. Provide summary to user with download statistics

Browser Access

Use Playwright MCP (mcp__plugin_playwright_playwright__browser_navigate) to access Behance pages.

Never write Python/shell scripts that call Playwright directly.

Extracting Project Data

Use JavaScript evaluation to extract:

// Get project info and images
() => {
  const images = [];
  document.querySelectorAll('img').forEach((img, i) => {
    if (img.src && img.src.includes('mir-s3-cdn')) {
      images.push({
        src: img.src,
        alt: img.alt || '',
        width: img.width,
        height: img.height
      });
    }
  });

  // Filter to main project images only (exclude thumbnails and avatars)
  const mainImages = images.filter(img =>
    img.src.includes('project_modules') &&
    !img.src.includes('/projects/404/')
  );

  return {
    title: document.querySelector('h1')?.textContent?.trim() || '',
    creativeField: document.querySelector('a[href*="field="]')?.textContent?.trim() || '',
    : .(.())
      .( t..()),
    : mainImages
  };
}

Finding Target Folder in metadata.json

Important: metadata.json can be very large (100k+ tokens). Never read the entire file into memory.

Method 1: Using grep (Recommended)

Use grep to extract just the folder ID without loading the entire file:

import subprocess
import json
from pathlib import Path

def find_folder_id_by_name(library_root: Path, folder_name: str) -> str:
    """
    Find folder ID by name using grep (memory efficient).
    Returns folder ID or None if not found.
    """
    metadata_path = library_root / "metadata.json"

    # Use grep to find the line with the folder name
    result = subprocess.run(
        ['grep', '-B', '5', f'"name": "{folder_name}"', str(metadata_path)],
        capture_output=True, text=True
    )

    if result.returncode != 0:
        return None

    # Parse the output to find ID
    for line in result.stdout.split('\n'):
        if '"id":' in line:
            # Extract ID from "id": "ABC123"
            import re
            match = re.search(r'"id":\s*"([^"]+)"', line)
            if match:
                return match.group(1)

    return None

# Usage: Find "图形设计" folder ID
folder_id = find_folder_id_by_name(Path("."), "图形设计")

Method 2: Using ijson (Streaming Parser)

For complex searches through nested structures, use ijson to stream-parse:

import ijson
from pathlib import Path

def find_behance_folder(library_root: Path, creative_field: str) -> str:
    """
    Find Behance subfolder ID using streaming JSON parser.
    Memory efficient for large metadata files.
    """
    metadata_path = library_root / "metadata.json"

    field_map = {
        "Illustration": "插图",
        "Graphic Design": "图形设计",
        "Photography": "摄影",
        "UI/UX": "UI/UX",
        "Motion Graphics": "动画",
        "Typography": "字体设计",
        "Branding": "图形设计",
        "3D Art": "3D Art",
        "Architecture": "建筑",
        "Fashion": "时尚",
        "Advertising": "广告",
        "Fine Arts": "美术",
        "Crafts": "手工艺",
        "Game Design": "游戏设计",
    }

    target_name = field_map.get(creative_field, "未分类")

    with open(metadata_path, 'rb') as f:
        # Stream through folders
        for folder in ijson.items(f, 'folders.item'):
            if folder.get() == :
                 child  folder.get(, []):
                     child.get() == :
                         subfolder  child.get(, []):
                             subfolder.get() == target_name:
                                 subfolder[]

     

Method 3: Cached Folder IDs

For repeated operations, cache the folder IDs:

# Cache of known Behance folder IDs (update as needed)
BEHANCE_FOLDER_IDS = {
    "插图": "7UAPMLRGTWT",
    "图形设计": "UWFE6X4QRC4",
    "摄影": "36QLX1XSJCC",
    "UI/UX": "LKC0V82UMSW",
    "动画": "25BUAQGOJFH",
    "3D Art": "6GIONKGOYTW",
    "建筑": "CQPDELSDAAY",
    "产品设计": "6FODRRZQTFO",
    "时尚": "SWHR57VFNM0",
    "广告": "JC3ZLIHEUSG",
    "美术": "KP2UWOJ4WDN",
    "手工艺": "PMQ8B3ODHKY",
    "游戏设计": "0JAUXK03C29",
    "声音": "ZS4GICO0BY8",
}

def get_behance_folder_id(creative_field: str) -> str:
    """Get folder ID from cache or use fallback."""
    field_map = {
        "Illustration": "插图",
        "Graphic Design": "图形设计",
        "Photography": "摄影",
        "UI/UX": "UI/UX",
        "Motion Graphics": "动画",
        "Typography": "字体设计",
        "Branding": "图形设计",
        "3D Art": ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
        : ,
    }

    target_name = field_map.get(creative_field)
     target_name:
         BEHANCE_FOLDER_IDS.get(target_name)

     

Field to Folder Mapping

Behance Creative Field	Eagle Folder Name	Cached ID
Illustration	插图	7UAPMLRGTWT
Graphic Design	图形设计	UWFE6X4QRC4
Branding	图形设计	UWFE6X4QRC4
Label Design	图形设计	UWFE6X4QRC4
Photography	摄影	36QLX1XSJCC
UI/UX	UI/UX	LKC0V82UMSW
Motion Graphics	动画	25BUAQGOJFH
Typography	字体设计	(varies)
3D Art	3D Art	6GIONKGOYTW
Architecture	建筑	CQPDELSDAAY
Fashion	时尚	SWHR57VFNM0
Advertising	广告	JC3ZLIHEUSG
Fine Arts	美术	KP2UWOJ4WDN
Crafts	手工艺	PMQ8B3ODHKY
Game Design	游戏设计	0JAUXK03C29

Downloading Images

Use Python requests to download images with proper headers:

import requests
from pathlib import Path
import time

def download_image(url: str, dest_path: Path, max_retries: int = 3) -> int:
    """
    Download image from Behance CDN.
    Returns file size in bytes.
    """
    headers = {
        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        "Referer": "https://www.behance.net/"
    }

    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, timeout=60)
            response.raise_for_status()
            dest_path.write_bytes(response.content)
            return len(response.content)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)  # Wait before retry

Handling SSL Errors

If you encounter SSLEOFError during batch downloads:

• Implement retry logic with exponential backoff
• Reduce concurrent connections
• Use smaller batch sizes

Image URL Patterns

Behance images follow these patterns:

• Source: https://mir-s3-cdn-cf.behance.net/project_modules/{size}/{hash}.{ext}
• Size variants: max_632, 1400, 1400_webp, original
• For archiving: use the largest available (1400 or original)

To get original size, replace size in URL:

/max_632_webp/ → /original/
/1400_webp/ → /original/

Folder Mapping

Behance Creative Field	Eagle Folder Name	Folder ID Example
Illustration	插图	7UAPMLRGTWT
Graphic Design	图形设计	UWFE6X4QRC4
Photography	摄影	36QLX1XSJCC
UI/UX	UI/UX	LKC0V82UMSW
Motion Graphics	动画	25BUAQGOJFH
Typography	字体设计	(varies)
3D Art	3D Art	6GIONKGOYTW
Architecture	建筑	CQPDELSDAAY
Fashion	时尚	SWHR57VFNM0
Advertising	广告	JC3ZLIHEUSG
Fine Arts	美术	KP2UWOJ4WDN
Crafts	手工艺	PMQ8B3ODHKY
Game Design	游戏设计	0JAUXK03C29
(unknown)	未分类	ask user

Creating Eagle Metadata

Eagle stores metadata in images/{ID}.info/metadata.json:

import json
import random
import string
from pathlib import Path
from datetime import datetime
from PIL import Image

def generate_eagle_id() -> str:
    """
    Generate correct Eagle ID format.
    - Asset ID: K + 12 chars = 13 chars total
    - Folder ID: 11-13 chars, can start with any character
    """
    chars = string.ascii_uppercase + string.ascii_lowercase + string.digits
    return 'K' + ''.join(random.choices(chars, k=12))

def create_thumbnail(img_path: Path, thumb_path: Path, size=(240, 240)):
    """Create thumbnail for Eagle display."""
    with Image.open(img_path) as img:
        if img.mode in ('RGBA', 'P'):
            img = img.convert('RGB')
        img.thumbnail(size, Image.Resampling.LANCZOS)
        background = Image.new('RGB', size, (255, 255, 255))
        offset = ((size[0] - img.width) // 2, (size[1] - img.height) // 2)
        background.paste(img, offset)
        background.save(thumb_path, 'PNG')

def get_exif_orientation(img) -> int:
    """Get EXIF orientation, default to 1 (normal)."""
    :
        exif = img._getexif()
         exif    exif:
             exif[]
    :
        
     

 () -> :
    
    
    asset_id = generate_eagle_id()
    asset_dir = library_root /  / 
    asset_dir.mkdir(parents=, exist_ok=)

    
    ext = image_url.split()[-].split()[]
     ext   [, , , , ]:
        ext = 

    
    img_path = asset_dir / 
    download_image(image_url, img_path)

    
    
    thumb_path = asset_dir / 
    create_thumbnail(img_path, thumb_path)

    
     Image.(img_path)  img:
        width, height = img.size
        orientation = get_exif_orientation(img)

    stat = img_path.stat()
    now_ms = (datetime.now().timestamp() * )

    
    metadata = {
        : asset_id,                           
        : name,
        : stat.st_size,
        : (stat.st_birthtime * ),   
        : (stat.st_mtime * ),       
        : ext,
        : width,
        : height,
        : orientation,               
        : now_ms,               
        : now_ms,                   
        : [folder_id],
        : tags  [],
        : ,
        : image_url,
        : ,
        : []
    }

    
    meta_path = asset_dir / 
    meta_path.write_text(json.dumps(metadata, ensure_ascii=, indent=))

     metadata

Rebuilding mtime.json Index

Eagle relies on mtime.json for fast resource loading. After adding resources, rebuild it:

def rebuild_mtime_index(library_root: Path):
    """Rebuild mtime.json index after adding new resources."""
    mtime_data = {}

    for asset_dir in library_root.glob('images/K*.info'):
        meta_path = asset_dir / 'metadata.json'
        if meta_path.exists():
            asset_id = asset_dir.name.replace('.info', '')
            stat = meta_path.stat()
            mtime_data[asset_id] = int(stat.st_mtime * 1000)

    # Atomic write
    mtime_path = library_root / 'mtime.json'
    temp = mtime_path.with_suffix('.tmp')
    temp.write_text(json.dumps(mtime_data, ensure_ascii=False))
    temp.replace(mtime_path)

    print(f"Rebuilt index: {len(mtime_data)} assets")

Verifying Asset Integrity

After creating resources, verify they are complete:

def verify_asset_integrity(asset_dir: Path) -> dict:
    """
    Verify a single Eagle asset is complete and valid.
    Returns validation result with errors and warnings.
    """
    result = {'valid': True, 'errors': [], 'warnings': []}

    # Check metadata exists
    meta_path = asset_dir / 'metadata.json'
    if not meta_path.exists():
        result['valid'] = False
        result['errors'].append('Missing metadata.json')
        return result

    # Parse metadata
    try:
        meta = json.loads(meta_path.read_text())
    except json.JSONDecodeError:
        result['valid'] = False
        result['errors'].append('Invalid metadata.json format')
        return result

    # Validate required fields
    required = ['id', 'name', 'size', 'btime', 'mtime', 'ext',
                'width', 'height', 'orientation', 'modificationTime',
                'lastModified', 'folders', 'isDeleted']

    for field in required:
        if field not in meta:
            result['errors'].append()

    
    asset_id = meta.get(, )
     (asset_id) != :
        result[].append()
      asset_id.startswith():
        result[].append()

    
    ext = meta.get(, )
    img_path = asset_dir / 
      img_path.exists():
        result[].append()

    
    thumbs = (asset_dir.glob())
      thumbs:
        result[].append()

    result[] = (result[]) == 
     result

 () -> :
    
    results = {: , : , : []}

     asset_dir  library_root.glob():
        meta_path = asset_dir / 
          meta_path.exists():
            

        meta = json.loads(meta_path.read_text())
         folder_id   meta.get(, []):
            

        result = verify_asset_integrity(asset_dir)
         result[]:
            results[] += 
        :
            results[] += 
            results[].append({
                : meta.get(, ),
                : result[]
            })

     results

Complete Workflow Example

def archive_behance_project(
    library_root: Path,
    project_url: str,
    project_title: str,
    creative_field: str,
    images: list
):
    """Complete workflow to archive a Behance project."""

    # 1. Find target folder
    folder_id = find_behance_folder(library_root, creative_field)
    if not folder_id:
        raise ValueError(f"Folder not found for: {creative_field}")

    # 2. Create project folder in metadata.json
    # CRITICAL: Must verify folder is actually saved before downloading!
    project_folder_id = create_project_folder(
        library_root, folder_id, project_title
    )

    # 3. Verify folder exists before downloading (DEFENSIVE!)
    # This catches cases where metadata.json wasn't properly saved
    verify_metadata = json.loads((library_root / "metadata.json").read_text())
    folder_exists = False
    for folder in verify_metadata.get("folders", []):
        if folder["name"] == "Collections":
            for child in folder.get("children", []):
                if child["name"] == "Behance":
                    for sub in child.get("children", []):
                        for proj in sub.get("children", []):
                            if proj["id"] == project_folder_id:
                                folder_exists = 
                                

      folder_exists:
         RuntimeError(
            
            
        )

    
    downloaded = []
    failed = []

     i, img_info  (images, ):
        :
            name = img_info.get()  
            create_eagle_asset(
                library_root=library_root,
                image_url=img_info[],
                name=name,
                folder_id=project_folder_id,
                tags=[]
            )
            downloaded.append(img_info)
         Exception  e:
            failed.append({: img_info[], : (e)})

    
    rebuild_mtime_index(library_root)

    
    verification = verify_folder_assets(library_root, project_folder_id)
     verification[] > :
        ()
         detail  verification[]:
            ()

    
     {
        : project_title,
        : project_folder_id,
        : (downloaded),
        : (failed),
        : verification[]
    }

Project Folder Naming

Use the URL slug or sanitized project title:

• URL: https://www.behance.net/gallery/244361827/New-raft-new-river
• Folder: New-raft-new-river (use slug from URL)

Sanitize rules:

• Remove leading/trailing whitespace
• Replace multiple spaces with single space
• Keep alphanumeric, hyphens, underscores
• Max length: 100 characters

Common Mistakes and Fixes

ID Length Error

Problem: Eagle doesn't recognize resources with 24-char IDs.

Wrong:

# ❌ Generates 24-char ID
def generate_id_wrong():
    timestamp = int(time.time() * 1000)  # 13 chars
    random = ''.join(choices(chars, k=10))  # 10 chars
    return f"K{timestamp}{random}"  # 1+13+10 = 24 chars ❌
# Result: K1771836829121PXBP4Wt1hE (24 chars)

Correct:

# ✅ Generates 13-char ID
def generate_eagle_id():
    chars = ascii_uppercase + ascii_lowercase + digits
    return 'K' + ''.join(choices(chars, k=12))  # 1+12 = 13 chars ✅
# Result: KldZIybF9RPGJ (13 chars)

Missing Required Fields

Problem: Eagle shows folder but not resources.

Missing fields that cause issues:

• orientation - Required for image display
• modificationTime - Required for sorting
• lastModified - Required for sync

Filename Mismatch

Problem: Thumbnail visible but original file won't open.

Cause: Filename doesn't match metadata name field.

Wrong:

# metadata.json: "name": "New raft new river - 26"
# Actual file:   KldZIybF9RPGJ.jpg    ❌ Eagle can't find it

Correct:

# metadata.json: "name": "New raft new river - 26"
# Actual file:   New raft new river - 26.jpg    ✅ Matches name field

Missing Thumbnail

Problem: Resources invisible in grid view.

Required file structure:

KldZIybF9RPGJ.info/
├── New raft new river - 26.jpg    # Original image (matches "name" field)
├── metadata.json                  # Metadata
└── New raft new river - 26_thumbnail.png  # Thumbnail (matches filename)

Outdated mtime.json

Problem: Eagle can't find new resources.

Fix: Always rebuild index after adding resources.

Project Folder Not Saved

Problem: Resources downloaded but not visible in Eagle. Folder appears to be created but doesn't exist in metadata.json.

Cause: Folder created in memory but not properly persisted to metadata.json, or saved to wrong location in the JSON tree.

Correct Implementation:

def create_project_folder(library_root: Path, parent_folder_id: str,
                          project_name: str) -> str:
    """
    Create project folder in metadata.json with verification.
    Returns the new folder ID.
    """
    import json
    import random
    import string
    from datetime import datetime
    from pathlib import Path

    def generate_folder_id():
        chars = string.ascii_uppercase + string.ascii_lowercase + string.digits
        return ''.join(random.choices(chars, k=13))

    metadata_path = library_root / "metadata.json"

    # Read current metadata
    with open(metadata_path, 'r', encoding='utf-8') as f:
        metadata = json.load(f)

    # Generate folder
    folder_id = generate_folder_id()
    now_ms = int(datetime.now().timestamp() * 1000)

    new_folder = {
        "id": folder_id,
        "name": project_name,
        "description": "",
        "children": [],
        "modificationTime": now_ms,
        "tags": [],
        "password": "",
        "passwordTips": ""
    }

    # Find and update parent folder
    folder_added = False
    for folder  metadata.get(, []):
         folder[] == :
             child  folder.get(, []):
                 child[] == :
                     sub  child.get(, []):
                         sub[] == parent_folder_id:
                            sub.setdefault(, []).append(new_folder)
                            folder_added = 
                            ()
                            
                     folder_added:
                        
             folder_added:
                

      folder_added:
         ValueError()

    
    
    temp_path = metadata_path.with_suffix()
     (temp_path, , encoding=)  f:
        json.dump(metadata, f, ensure_ascii=, indent=)

    
    temp_path.replace(metadata_path)

    
     (metadata_path, , encoding=)  f:
        verify = json.load(f)

    folder_found = 
     folder  verify.get(, []):
         folder[] == :
             child  folder.get(, []):
                 child[] == :
                     sub  child.get(, []):
                         proj  sub.get(, []):
                             proj[] == folder_id:
                                folder_found = 
                                

      folder_found:
         RuntimeError()

    ()
     folder_id

Verification Checklist:

1. ✅ Parent folder ID exists in metadata.json
2. ✅ New folder added to correct parent's children array
3. ✅ File saved atomically (temp file → rename)
4. ✅ Re-read and verify folder exists after save
5. ✅ Only proceed with downloads after folder verification

Providing User Summary

After archiving, provide a comprehensive summary:

def generate_summary(
    project_title: str,
    project_url: str,
    author: str,
    creative_field: str,
    folder_path: str,
    downloaded: list,
    failed: list
) -> str:
    """Generate a formatted summary for the user."""

    lines = [
        "## 归档完成 ✅",
        "",
        f"**项目**: [{project_title}]({project_url})",
        f"**作者**: {author}",
        f"**分类**: {creative_field} → **{folder_path}**",
        f"**图片数量**: {len(downloaded)} 张",
    ]

    if failed:
        lines.append(f"**失败**: {len(failed)} 张")

    lines.extend([
        "",
        "### 已下载图片",
        "",
        "| 序号 | 分辨率 | 大小 |",
        "|------|--------|------|",
    ])

    for i, img in enumerate(downloaded[:10], 1):
        lines.append(
            f"| {i} | {img['width']}×{img['height']} | {img['size']/1024:.1f} KB |"
        )

    if (downloaded) > :
        lines.append()

    lines.extend([
        ,
        ,
        ,
        ,
        ,
        ,
        ,
        ,
        ,
        
    ])

     .join(lines)

Complete Example

User request: "归档 https://www.behance.net/gallery/244361827/New-raft-new-river"

Implementation steps:

1. Navigate to the URL using Playwright MCP
2. Extract project info: title, creative field, images
3. Parse metadata.json to find target folder ID for "Illustration" → "插图"
4. Download each image using requests with retry logic
5. Create metadata.json for each asset with proper folder reference
6. Generate summary showing download statistics

Expected output:

## 归档完成 ✅

**项目**: [New raft, new river.](https://www.behance.net/gallery/244361827/New-raft-new-river)
**作者**: Jesús Sotés
**分类**: Illustration → **Collections > Behance > 插图**
**图片数量**: 26 张

### 已下载图片

| 序号 | 分辨率 | 大小 |
|------|--------|------|
| 1 | 1400×840 | 57.7 KB |
| 2 | 1400×2149 | 413.8 KB |
| ... | ... | ... |

现在打开 Eagle 应用，在 **Collections > Behance > 插图** 中即可查看这些图片。

References

• Eagle Metadata Format - Complete specification for Eagle's JSON metadata structure