scheme = "littletree_wallpaper_source_v3"
identifier = "com.example.wallpaper_source"
name = "壁纸源名称"
version = "1.0.0"
categories = "categories.toml"
apis = ["apis/*.toml"]

# source.toml
scheme = "littletree_wallpaper_source_v3"
identifier = "com.nature.wallpapers"
name = "自然壁纸源"
version = "1.0.0"

# 必需的文件引用
categories = "categories.toml"
apis = ["apis/*.toml"]

# 可选配置
config = "config.toml"
description = "提供高质量自然风景壁纸，每日更新"

# Base64 编码的图标（SVG格式）
logo = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAwIiBoZWlnaHQ9IjEwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI0MCIgc3R5bGU9ImZpbGw6IzQyYjdkZSIvPjwvc3ZnPgo="

# 详细说明（Markdown格式）
details = """
# 自然壁纸源

## 功能特性
- **每日更新**：每天提供新的自然风景壁纸
- **多分辨率**：支持 1080p、2K、4K 等分辨率
- **高质量**：所有图片均经过精选，确保画质
- **无广告**：纯净的壁纸体验

## 使用说明
1. 在客户端中启用本壁纸源
2. 进入「自然」分类查看壁纸
3. 点击喜欢的壁纸设置为桌面

## 更新日志
### v1.0.0 (2025-01-15)
- 初始版本发布
- 支持自然风景壁纸
- 添加每日更新功能
"""

footer_text = "© 2025 自然壁纸源 | 发现世界之美"

# 验证示例
☑ scheme 必须是 "littletree_wallpaper_source_v3"
☑ identifier 格式正确（com.xxx.xxx）
☑ name 长度在 2-32 字符之间
☑ version 符合语义化版本格式
☑ categories 文件存在
☑ apis 数组非空且匹配到至少一个文件

# 验证示例（如果存在）
☑ config 文件存在（如果指定）
☑ description 长度 ≤ 100 字符
☑ logo 是有效的 Base64 或 URL
☑ details 是有效的字符串
☑ footer_text 长度 ≤ 200 字符

# ❌ 错误：缺少 identifier
scheme = "littletree_wallpaper_source_v3"
name = "壁纸源"
# 缺少 identifier 字段

# ✅ 正确：包含所有必需字段
scheme = "littletree_wallpaper_source_v3"
identifier = "com.example.source"
name = "壁纸源"
version = "1.0.0"
categories = "categories.toml"
apis = ["apis/*.toml"]

# ❌ 错误：使用本地文件路径
logo = "icon.png"  # 不允许

# ✅ 正确：使用 Base64 编码
logo = "data:image/svg+xml;base64,..."

# ✅ 正确：使用外部 URL
logo = "https://example.com/icon.svg"

# ❌ 错误：版本格式不正确
version = "1.0"      # 缺少修订号
version = "v1.0.0"   # 包含前缀v
version = "1.0.0.1"  # 过多部分

# ✅ 正确：语义化版本
version = "1.0.0"
version = "2.1.3"

# ❌ 错误：标识符格式不正确
identifier = "my_source"          # 缺少域名部分
identifier = "com.my source"      # 包含空格
identifier = "COM.EXAMPLE.SOURCE" # 大写字母

# ✅ 正确：反向域名格式
identifier = "com.example.source"
identifier = "com.littletree.bing"

[request]
global_interval_seconds = 3600  # 全局请求间隔（秒），0=不限制
timeout_seconds = 30           # 请求超时时间（秒）
max_concurrent = 3             # 最大并发请求数
skip_ssl_verify = false        # 是否跳过 SSL 验证
user_agent = "LittleTreeWallpaper/3.0"  # 自定义 User-Agent

[request.headers]
Accept = "application/json"
Accept-Language = "zh-CN,zh;q=0.9"
Accept-Encoding = "gzip, deflate"

[request.retry]
max_attempts = 3        # 最大重试次数
backoff_base = 2.0      # 退避基数（指数退避）
initial_delay_ms = 1000  # 初始延迟（毫秒）

[request.cache]
enabled = true          # 是否启用缓存
default_ttl_seconds = 300  # 默认缓存时间（秒）
max_memory_mb = 100     # 最大内存缓存大小（MB）

[request.variables]
timestamp = "{{timestamp_ms}}"      # 当前时间戳（毫秒）
date = "{{date_iso}}"              # 当前日期（ISO格式）
date_cn = "{{date_cn}}"            # 中文日期
random = "{{random_string:8}}"     # 8位随机字符串
random_int = "{{random_int:1:100}}" # 1-100随机整数

# config.toml
[request]
global_interval_seconds = 1800
timeout_seconds = 20
max_concurrent = 2
skip_ssl_verify = false
user_agent = "MyWallpaperClient/3.0"

[request.headers]
Accept = "application/json"
Accept-Language = "zh-CN"

[request.retry]
max_attempts = 2
backoff_base = 1.5
initial_delay_ms = 500

[request.cache]
enabled = true
default_ttl_seconds = 600

[request.variables]
timestamp = "{{timestamp_ms}}"
date = "{{date_iso}}"
random = "{{random_string:6}}"

# 分类模板（可选）
[template]
icon = "data:image/svg+xml;base64,..."  # Base64 图标
category = "默认分类"

# 分类列表
[[categories]]
id = "nature"           # 必填：分类唯一标识符
name = "自然风光"        # 必填：分类显示名称
category = "风景"        # 必填：一级分类
subcategory = "自然"     # 可选：二级分类
icon = "data:image/svg+xml;base64,..."  # 可选：Base64 图标
description = "自然风景壁纸"  # 可选：分类描述

# 层级图标定义（可选）
[level_icons]
# 一级分类图标（按category值匹配）
[level_icons.category]
风景 = "data:image/svg+xml;base64,..."
自然 = "data:image/svg+xml;base64,..."
二次元 = "data:image/svg+xml;base64,..."

# 二级分类图标（按subcategory值匹配）  
[level_icons.subcategory]
山脉 = "data:image/svg+xml;base64,..."
湖泊 = "data:image/svg+xml;base64,..."
动漫 = "data:image/svg+xml;base64,..."

# 三级分类图标（按subsubcategory值匹配）
[level_icons.subsubcategory]
精选 = "data:image/svg+xml;base64,..."
热门 = "data:image/svg+xml;base64,..."
最新 = "data:image/svg+xml;base64,..."

[[category_groups]]
name = "热门分类"
category_ids = ["nature", "anime", "abstract"]

[[category_groups]]
name = "每日更新"
category_ids = ["daily", "trending"]

# categories.toml
[template]
icon = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkM2LjQ4IDIgMiA2LjQ4IDIgMTJzNC40OCAxMCAxMCAxMCAxMC00LjQ4IDEwLTEwUzE3LjUyIDIgMTIgMlptMCAxOGMtNC40MSAwLTgtMy41OS04LThzMy41OS04IDgtOCA4IDMuNTkgOCA4LTMuNTkgOC04IDhaIiBmaWxsPSIjNjY2Ii8+PC9zdmc+Cg=="
category = "其他"

[[categories]]
id = "mountain"
name = "山脉"
category = "自然"
subcategory = "风景"
icon = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgM0w0IDIxaDE2TDEyIDNaTTEyIDcuNDQyTDkuMTAyIDE2LjVIMTQuODk2TDEyIDcuNDQyWiIgZmlsbD0iIzQyYjdkZSIvPjwvc3ZnPgo="

[[categories]]
id = "anime"
name = "动漫"
category = "二次元"
icon = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkM2LjQ4IDIgMiA2LjQ4IDIgMTJzNC40OCAxMCAxMCAxMCAxMC00LjQ4IDEwLTEwUzE3LjUyIDIgMTIgMlptMCAxOGMtNC40MSAwLTgtMy41OS04LThzMy41OS04IDgtOCA4IDMuNTkgOCA4LTMuNTkgOC04IDhaIiBmaWxsPSIjRkY2Njk5Ii8+PHBhdGggZD0iTTEyIDE3QzE0Ljc2MTQgMTcgMTcgMTQuNzYxNCAxNyAxMkMxNyA5LjIzODYgMTQuNzYxNCA3IDEyIDdDOS4yMzg2IDcgNyA5LjIzODYgNyAxMkM3IDE0Ljc2MTQgOS4yMzg2IDE3IDEyIDE3WiIgZmlsbD0iI0ZGNjY5OSIvPjwvc3ZnPgo="

# 分类分组
[[category_groups]]
name = "自然分类"
category_ids = ["mountain"]

[[category_groups]]
name = "动漫分类"
category_ids = ["anime"]

# 基本信息
name = "API 名称"
description = "API 功能描述"
logo = "data:image/svg+xml;base64,..."  # Base64 图标

# 分类绑定（必填）
categories = ["category_id1", "category_id2"]

# 参数定义
[[parameters]]
key = "param_name"
type = "choice"  # choice, text, boolean
label = "参数标签"
default = "默认值"
choices = ["选项1", "选项2"]  # choice 类型必需
hidden = false  # 是否在 UI 中隐藏

# 请求配置
[request]
url = "https://api.example.com/data?param={{param_name}}"
method = "GET"  # GET 或 POST
timeout_seconds = 10  # 覆盖全局配置
interval_seconds = 3600  # 0=使用全局，-1=不限制

# 响应配置
[response]
format = "json"  # json, toml, image_url, image_raw, static_list, static_dict
type = "multi"  # single, multi

# 字段映射
[mapping]
# 单图模式
image = "/data/url"
title = "/data/title"

# 多图模式
items = "/data/list"
item_mapping = { image = "/url", title = "/name" }

[[parameters]]
key = "resolution"
type = "choice"
label = "分辨率"
default = "1920x1080"
choices = ["1920x1080", "2560x1440", "3840x2160"]
description = "选择壁纸分辨率"

[[parameters]]
key = "keyword"
type = "text"
label = "搜索关键词"
default = ""
placeholder = "输入关键词"
min_length = 1
max_length = 100

[[parameters]]
key = "safe_mode"
type = "boolean"
label = "安全模式"
default = true

[[parameters]]
key = "api_key"
type = "text"
default = "ABC123"
hidden = true  # 不在UI显示，但参与请求

[response]
format = "json"
type = "multi"

[mapping]
items = "/data/wallpapers"
item_mapping = { 
    image = "/image_url", 
    title = "/title",
    width = "/width",
    height = "/height"
}

[response]
format = "static_dict"

[static_dict]
[[items]]
image = "https://example.com/wallpaper1.jpg"
title = "壁纸标题"
description = "壁纸描述"
width = 1920
height = 1080

[[items]]
image = "https://example.com/wallpaper2.jpg"
title = "另一个壁纸"

[response]
format = "static_list"

[static_list]
urls = [
    "https://example.com/w1.jpg",
    "https://example.com/w2.jpg",
    "https://example.com/w3.jpg"
]

[response]
format = "image_url"
# 响应体应为单行图片URL

[response]
format = "image_raw"
# 响应体应为原始图片二进制数据

# 绝对路径
image = "/data/url"

# 数组索引
image = "/data/images/0/url"

# 通配符（匹配第一个）
image = "/data/images/*/url"

# 递归通配符
image = "/**/image_url"

# 多重路径（按顺序尝试）
image = ["/images/hd_url", "/images/url", "/url"]

image = "data.url"
title = "data.wallpaper.title"

[validation]
# 必需字段
required_fields = ["image", "title"]

# 字段格式验证
field_patterns = [
    { path = "image", regex = "^https?://.+\\.(jpg|png|webp)$" },
    { path = "title", max_length = 100 }
]

# 数据质量验证
quality_rules = [
    { path = "width", min = 1920 },
    { path = "height", min = 1080 }
]

[validation]
required_fields = ["image"]

field_patterns = [
  { path = "image", regex = "^https://.+\\.(jpg|jpeg|png|webp)$" }
]

[validation]
required_fields = ["image", "width", "height"]

quality_rules = [
  { path = "width", min = 1920 },
  { path = "height", min = 1080 }
]

[error_handling]
# HTTP状态码处理
http_codes = [
    { code = 429, message = "请求过于频繁", retry_after = 60 },
    { code = 404, message = "内容不存在", fallback = true }
]

# 响应处理错误
on_empty_response = "skip"
on_mapping_failed = "skip_item"

[error_handling]
fallback_to = "backup_api"  # 指向 apis/backup_api.toml（按文件名基名匹配）

[cache]
enabled = true
ttl_seconds = 86400
key_template = "api_{{param1}}_{{date}}"

# apis/bing_daily.toml
name = "Bing 每日壁纸"
description = "微软Bing每日更新的壁纸"
logo = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTkgMTJIMTFWN0gxOUMyMC4xMDUgNyAyMSA3Ljg5NSA3IDlWMTlDNyAxOC4xMDUgNy44OTUgMTcgOSAxN0gxN1YxMkgyMFYxOEMyMCAyMC4yMDkgMTguMjA5IDIyIDE2IDIySDhDNS43OTEgMjIgNCAyMC4yMDkgNCAxOFY2QzQgMy43OTEgNS43OTEgMiA4IDJIMTZDMTguMjA5IDIgMjAgMy43OTEgMjAgNlYxMkgxOVoiIGZpbGw9IiM0MmI3ZGUiLz48L3N2Zz4K"

categories = ["daily"]

[[parameters]]
key = "mkt"
type = "choice"
label = "地区"
default = "zh-CN"
choices = ["zh-CN", "en-US", "ja-JP"]

[[parameters]]
key = "n"
type = "choice"
label = "数量"
default = "8"
choices = ["1", "5", "8", "15"]

[request]
url = "https://www.bing.com/HPImageArchive.aspx?format=js&n={{n}}&mkt={{mkt}}&ts={{timestamp_ms}}"
method = "GET"
timeout_seconds = 15
interval_seconds = 3600

[request.headers]
Referer = "https://www.bing.com"

[response]
format = "json"
type = "multi"

[mapping]
items = "/images"
item_mapping = { 
    image = "/url", 
    title = "/copyright",
    startdate = "/startdate"
}

[post_process]
image = "https://www.bing.com{{image}}"

[validation]
required_fields = ["image"]

[error_handling]
http_codes = [
    { code = 429, message = "请求过于频繁", retry_after = 300 }
]

[cache]
enabled = true
ttl_seconds = 43200
key_template = "bing_{{mkt}}_{{date}}"

# 基本用法
wallpaper-source-pack source_directory output_file.ltws

# 示例
wallpaper-source-pack ./my_source ./my_source.ltws

{
  "format_version": "1.0",
  "source_schema": "littletree_wallpaper_source_v3",
  "generated_at": "2024-01-15T12:00:00Z",
  "tool_version": "wallpaper-source-pack/1.0.0",
  "files": [
    {
      "path": "source.toml",
      "sha256": "abc123...",
      "size": 1024
    }
  ],
  "metadata": {
    "name": "自然壁纸源",
    "identifier": "com.nature.wallpapers",
    "version": "1.0.0"
  }
}

mkdir my_wallpaper_source
cd my_wallpaper_source
mkdir apis

scheme = "littletree_wallpaper_source_v3"
identifier = "com.my.first_source"
name = "我的第一个壁纸源"
version = "1.0.0"
categories = "categories.toml"
apis = ["apis/*.toml"]

[[categories]]
id = "simple"
name = "简单壁纸"
category = "示例"

name = "简单壁纸"
categories = ["simple"]

[request]
url = "https://picsum.photos/1920/1080"

[response]
format = "image_raw"
type = "single"

wallpaper-source-pack ./my_wallpaper_source ./my_wallpaper_source.ltws

wallpaper-source-validate ./my_wallpaper_source.ltws

# 安装
pip install wallpaper-source-tools

# 使用
wallpaper-source-pack ./source ./output.ltws
wallpaper-source-validate ./source.ltws
wallpaper-source-ls ./source.ltws

# 将图片转换为 Base64
convert-to-base64 icon.png
# 输出: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

# 验证目录结构
wallpaper-source-check ./my_source

# 输出:
# ✅ source.toml: 有效
# ✅ categories.toml: 包含 3 个分类
# ✅ apis/: 包含 5 个 API 文件
# ⚠️  发现本地图标引用，建议转换为 Base64

# source.toml 中的合并配置
[merge]
enabled = true                      # 参与合并的建议开关（默认：false；客户端可忽略/覆盖）
strategy = "same_id"                # 合并策略：same_id（相同ID）、same_name（相同名称）
priority = 100                      # 合并优先级（0-1000，默认：100）
metadata_source = "high_priority"   # 元数据来源：high_priority（高优先级源）、first_loaded（最先加载）、last_updated（最后更新）
allow_metadata_override = true      # 是否允许其他源覆盖本源的分类元数据

# categories.toml
[[categories]]
id = "nature"
name = "自然风光"
category = "风景"
icon = "data:image/svg+xml;base64,A"
description = "源A的自然壁纸"

# categories.toml  
[[categories]]
id = "nature"
name = "自然风景"
category = "自然"
icon = "data:image/svg+xml;base64,B"
description = "源B的自然壁纸"

# 推荐配置
[merge]
enabled = true
strategy = "same_id"                # 更精确的合并
priority = 100                      # 中等优先级，允许其他源覆盖
metadata_source = "high_priority"   # 公平的元数据选择
allow_metadata_override = true      # 允许更好的源提供更优元数据

# 特殊场景：作为基础源（不希望被覆盖）
[merge]
enabled = true
strategy = "same_id"
priority = 1000                     # 最高优先级，确保元数据不被覆盖
metadata_source = "high_priority"
allow_metadata_override = false     # 禁止其他源覆盖

# 推荐：使用 Base64 编码的小图标
logo = "data:image/svg+xml;base64,..."  # SVG 格式最佳

# 可选：使用外部 CDN
logo = "https://cdn.example.com/icon.svg"

# 不推荐：大尺寸图片或本地文件
# logo = "icon.png"  # ❌ 不允许

# 设置合理的缓存时间
[cache]
ttl_seconds = 3600  # 根据更新频率设置

# 使用多图 API 减少请求次数
[response]
type = "multi"  # 而不是多次调用单图 API

# 配置降级策略
[error_handling]
fallback_to = "backup_api"  # 引用备用 API

# 设置合理的重试策略
[request.retry]
max_attempts = 2  # 避免无限重试

# 使用 HTTPS
url = "https://api.example.com/data"  # ✅ 推荐

# 隐藏敏感参数
[[parameters]]
key = "api_key"
hidden = true  # 不在 UI 显示