FallbackRemoteImageProvider.cs

using MediaBrowser.Common.Net;
using MediaBrowser.Controller.Entities;
using MediaBrowser.Controller.Entities.Movies;
using MediaBrowser.Controller.Entities.TV;
using MediaBrowser.Controller.Library;
using MediaBrowser.Controller.Providers;
using MediaBrowser.Model.Configuration;
using MediaBrowser.Model.Entities;
using MediaBrowser.Model.Globalization;
using MediaBrowser.Model.IO;
using MediaBrowser.Model.Logging;
using MediaBrowser.Model.Providers;
using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

namespace EmbyImageLanguageFallback
{
    public class FallbackRemoteImageProvider : IRemoteImageProvider, IHasOrder
    {
        private const string ConstructorLogPrefix = "Fallback provider constructed";
        // 通过浅拷贝复制 LibraryOptions，仅覆盖语言字段，避免污染调用方传入的实例。
        private static readonly MethodInfo MemberwiseCloneMethod = typeof(object).GetMethod("MemberwiseClone", BindingFlags.Instance | BindingFlags.NonPublic);
        private static readonly string[] DefaultProviderNames = { "TheMovieDb", "FanArt", "TheTVDB" };
        // Emby 内部 provider 命名并不总是统一，这里维护别名到规范名的映射。
        private static readonly Dictionary<string, string[]> ProviderNameAliases = new Dictionary<string, string[]>(StringComparer.OrdinalIgnoreCase)
        {
            { "TheMovieDb", new[] { "TheMovieDb", "Tmdb", "TMDB" } },
            { "FanArt", new[] { "FanArt", "Fanart" } },
            { "TheTVDB", new[] { "TheTVDB", "Tvdb", "TVDB" } }
        };

        private readonly IHttpClient _httpClient;
        private readonly IProviderManager _providerManager;
        private readonly ILibraryManager _libraryManager;
        private readonly IDirectoryService _directoryService;
        private readonly ILogger _logger;

        public FallbackRemoteImageProvider(
            IHttpClient httpClient,
            IProviderManager providerManager,
            ILibraryManager libraryManager,
            IFileSystem fileSystem,
            ILogManager logManager)
        {
            _httpClient = httpClient;
            _providerManager = providerManager;
            _libraryManager = libraryManager;
            _directoryService = new DirectoryService(fileSystem);
            _logger = logManager.GetLogger(Plugin.Instance.Name);

            WriteInfoLog("{0}. Name={1}, Order={2}", ConstructorLogPrefix, Name, Order);
        }

        public string Name => Plugin.Instance.Name;

        public int Order => -100;

        public bool Supports(BaseItem item)
        {
            var supported = item is Movie
                || item is Series
                || item is Season
                || item is BoxSet;

            WriteInfoLog("Fallback provider Supports called. ItemName={0}, ItemType={1}, Supported={2}",
            item == null ? "<null>" : item.Name,
            item == null ? "<null>" : item.GetType().Name,
            supported);

            return supported;
        }

        public IEnumerable<ImageType> GetSupportedImages(BaseItem item)
        {
            var types = new[]
            {
                ImageType.Primary,
                ImageType.Logo,
                ImageType.Thumb,
                ImageType.Banner,
                ImageType.Art,
                ImageType.Disc,
                ImageType.Backdrop
            };

            WriteInfoLog("Fallback provider GetSupportedImages called. ItemName={0}, ItemType={1}, Types={2}",
            item == null ? "<null>" : item.Name,
            item == null ? "<null>" : item.GetType().Name,
            string.Join(",", types.Select(i => i.ToString())));

            return types;
        }

        public async Task<IEnumerable<RemoteImageInfo>> GetImages(BaseItem item, LibraryOptions libraryOptions, CancellationToken cancellationToken)
        {
            var options = Plugin.Instance.CurrentOptions;

            if (options == null || !options.Enabled)
            {
                return Array.Empty<RemoteImageInfo>();
            }

            var primaryLanguages = options.GetPrimaryLanguages().Select(NormalizeLanguage).Where(i => !string.IsNullOrWhiteSpace(i)).Distinct(StringComparer.OrdinalIgnoreCase).ToList();
            var fallbackLanguages = options.GetFallbackLanguages().Select(NormalizeLanguage).Where(i => !string.IsNullOrWhiteSpace(i)).Distinct(StringComparer.OrdinalIgnoreCase).ToList();
            var primaryLanguage = primaryLanguages.FirstOrDefault();
            var fallbackLanguage = fallbackLanguages.FirstOrDefault();
            var enabledProviders = GetEnabledProviders(options);
            var providerPlans = GetProviderPlans(enabledProviders).ToList();

            WriteInfoLog("Fallback provider querying item '{0}'. Primary={1}, Fallback={2}, IncludeNeutral={3}, Providers={4}",
            item.Name,
            primaryLanguages.Count == 0 ? "<none>" : string.Join(",", primaryLanguages),
            fallbackLanguages.Count == 0 ? "<none>" : string.Join(",", fallbackLanguages),
            options.IncludeLanguageNeutralImages,
            providerPlans.Count == 0 ? "<none>" : string.Join(" | ", providerPlans.Select(FormatProviderPlan)));

            var allImages = new List<RemoteImageInfo>();
            var effectiveLibraryOptions = libraryOptions ?? _libraryManager.GetLibraryOptions(item);

            LogItemDiagnostics(item, effectiveLibraryOptions);

            foreach (var providerPlan in providerPlans)
            {
                cancellationToken.ThrowIfCancellationRequested();

                var providerImages = await QueryUpstreamProviderAsync(
                    item,
                    effectiveLibraryOptions,
                    providerPlan,
                    primaryLanguages,
                    fallbackLanguages,
                    cancellationToken).ConfigureAwait(false);

                allImages.AddRange(providerImages);
            }

            if (allImages.Count == 0)
            {
                WriteInfoLog("Fallback provider found no remote images for '{0}'.", item.Name);
                return Array.Empty<RemoteImageInfo>();
            }

            var result = new List<RemoteImageInfo>();

            foreach (var imageType in allImages.Select(i => i.Type).Distinct())
            {
                var typeImages = allImages.Where(i => i.Type == imageType).ToList();

                WriteInfoLog("Fallback provider image-type summary. Item='{0}', Type={1}, Summary={2}",
                item.Name,
                imageType,
                    BuildLanguageSummary(typeImages, primaryLanguages, fallbackLanguages));

                var typeSelection = BuildFallbackSelection(typeImages, primaryLanguages, fallbackLanguages, options.IncludeLanguageNeutralImages);

                WriteInfoLog("Fallback provider selected {0} images for item '{1}' type {2}. SelectionSummary={3}",
                typeSelection.Count,
                item.Name,
                imageType,
                    BuildLanguageSummary(typeSelection, primaryLanguages, fallbackLanguages));

                var rewrittenSelection = options.RewriteSelectedFallbackImagesAsEnglish
                    ? RewriteSelectedFallbackImages(typeSelection, fallbackLanguages)
                    : typeSelection;

                WriteInfoLog("Fallback provider rewritten {0} images for item '{1}' type {2}. ReturnSummary={3}",
                rewrittenSelection.Count,
                item.Name,
                imageType,
                    BuildLanguageSummary(rewrittenSelection, primaryLanguages, fallbackLanguages));

                result.AddRange(rewrittenSelection);
            }

            WriteInfoLog("Fallback provider returning {0} images for '{1}'.", result.Count, item.Name);
            return result;
        }

        public Task<HttpResponseInfo> GetImageResponse(string url, CancellationToken cancellationToken)
        {
            WriteInfoLog("Fallback provider GetImageResponse called. Url={0}", url ?? "<null>");

            if (string.IsNullOrWhiteSpace(url))
            {
                throw new ArgumentNullException(nameof(url));
            }

            return _httpClient.GetResponse(new HttpRequestOptions
            {
                Url = url,
                CancellationToken = cancellationToken,
                BufferContent = false
            });
        }

        private List<RemoteImageInfo> BuildFallbackSelection(
            List<RemoteImageInfo> images,
            IReadOnlyCollection<string> primaryLanguages,
            IReadOnlyCollection<string> fallbackLanguages,
            bool includeNeutral)
        {
            // 最终只保留：主语言 -> 备选语言 -> 可选无语言，不再把其它语言兜底返回。
            var selected = new List<RemoteImageInfo>();
            var seenUrls = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

            AddMatches(selected, seenUrls, images, primaryLanguages);

            var effectiveFallbackLanguages = fallbackLanguages
                ?.Where(i => primaryLanguages == null || !primaryLanguages.Contains(i, StringComparer.OrdinalIgnoreCase))
                .ToList()
                ?? new List<string>();

            if (effectiveFallbackLanguages.Count > 0)
            {
                AddMatches(selected, seenUrls, images, effectiveFallbackLanguages);
            }

            if (includeNeutral)
            {
                foreach (var image in images.Where(IsLanguageNeutral))
                {
                    if (seenUrls.Add(image.Url ?? string.Empty))
                    {
                        selected.Add(image);
                    }
                }
            }

            return selected;
        }

        private void AddMatches(List<RemoteImageInfo> selected, HashSet<string> seenUrls, IEnumerable<RemoteImageInfo> images, IEnumerable<string> languages)
        {
            var materializedLanguages = languages
                ?.Select(NormalizeLanguage)
                .Where(i => !string.IsNullOrWhiteSpace(i))
                .Distinct(StringComparer.OrdinalIgnoreCase)
                .ToList();

            if (materializedLanguages == null || materializedLanguages.Count == 0)
            {
                return;
            }

            foreach (var image in images.Where(i => LanguageMatchesAny(i, materializedLanguages)))
            {
                if (seenUrls.Add(image.Url ?? string.Empty))
                {
                    selected.Add(image);
                }
            }
        }

        private bool LanguageMatches(RemoteImageInfo image, string language)
        {
            var normalizedLanguage = NormalizeLanguage(language);
            var imageLanguage = NormalizeLanguage(image.Language);
            var displayLanguage = NormalizeLanguage(image.DisplayLanguage);

            if (string.IsNullOrWhiteSpace(normalizedLanguage))
            {
                return false;
            }

            foreach (var candidate in ExpandLanguageCandidates(normalizedLanguage))
            {
                if (LanguageValueMatches(imageLanguage, candidate) || DisplayLanguageMatches(displayLanguage, candidate))
                {
                    return true;
                }
            }

            return false;
        }

        private bool LanguageMatchesAny(RemoteImageInfo image, IEnumerable<string> languages)
        {
            return languages != null && languages.Any(language => LanguageMatches(image, language));
        }

        private bool IsLanguageNeutral(RemoteImageInfo image)
        {
            return string.IsNullOrWhiteSpace(image.Language)
                || string.Equals(image.Language, "null", StringComparison.OrdinalIgnoreCase)
                || string.Equals(image.Language, "00", StringComparison.OrdinalIgnoreCase);
        }

        private string NormalizeLanguage(string language)
        {
            if (string.IsNullOrWhiteSpace(language))
            {
                return null;
            }

            return PluginOptions.GetCanonicalLanguageValue(language.Trim()) ?? language.Trim();
        }

        private IEnumerable<string> ExpandLanguageCandidates(string language)
        {
            var normalizedLanguage = NormalizeLanguage(language);

            if (string.IsNullOrWhiteSpace(normalizedLanguage))
            {
                return Array.Empty<string>();
            }

            var candidates = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
            {
                normalizedLanguage
            };

            foreach (var alias in PluginOptions.GetLanguageAliases(normalizedLanguage))
            {
                AddLanguageCandidateVariants(candidates, alias);
            }

            return candidates;
        }

        private void AddLanguageCandidateVariants(HashSet<string> candidates, string value)
        {
            if (candidates == null || string.IsNullOrWhiteSpace(value))
            {
                return;
            }

            var trimmed = value.Trim();
            if (trimmed.Length == 0)
            {
                return;
            }

            candidates.Add(trimmed);

            var hyphenated = trimmed.Replace('_', '-');
            var underscored = trimmed.Replace('-', '_');
            candidates.Add(hyphenated);
            candidates.Add(underscored);

            var parts = hyphenated.Split(new[] { '-' }, StringSplitOptions.RemoveEmptyEntries);
            if (parts.Length > 0)
            {
                candidates.Add(parts[0]);
            }
        }

        private bool LanguageValueMatches(string actualLanguage, string expectedLanguage)
        {
            if (string.IsNullOrWhiteSpace(actualLanguage) || string.IsNullOrWhiteSpace(expectedLanguage))
            {
                return false;
            }

            return string.Equals(actualLanguage, expectedLanguage, StringComparison.OrdinalIgnoreCase)
                || actualLanguage.StartsWith(expectedLanguage + "-", StringComparison.OrdinalIgnoreCase)
                || actualLanguage.StartsWith(expectedLanguage + "_", StringComparison.OrdinalIgnoreCase);
        }

        private bool DisplayLanguageMatches(string displayLanguage, string expectedLanguage)
        {
            if (string.IsNullOrWhiteSpace(displayLanguage) || string.IsNullOrWhiteSpace(expectedLanguage))
            {
                return false;
            }

            switch (expectedLanguage.ToLowerInvariant())
            {
                case "ja":
                case "ja-jp":
                case "ja_jp":
                case "jpn":
                case "japanese":
                    return displayLanguage.IndexOf("japanese", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("日本", StringComparison.OrdinalIgnoreCase) >= 0;
                case "zh-hans":
                case "zh":
                case "zh-cn":
                case "zh_cn":
                case "zh-sg":
                case "zh_sg":
                case "zho":
                case "chi":
                case "chinese":
                    return displayLanguage.IndexOf("chinese", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("中文", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("汉语", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("简体", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("簡體", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("新加坡", StringComparison.OrdinalIgnoreCase) >= 0;
                case "zh-hant-tw":
                case "zh-tw":
                case "zh_tw":
                case "zhtw":
                case "traditional chinese":
                    return displayLanguage.IndexOf("traditional chinese", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("繁体", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("繁體", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("台灣", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("台湾", StringComparison.OrdinalIgnoreCase) >= 0;
                case "zh-hant-hk":
                case "zh-hk":
                case "zh_hk":
                    return displayLanguage.IndexOf("traditional chinese", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("繁体", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("繁體", StringComparison.OrdinalIgnoreCase) >= 0
                        || displayLanguage.IndexOf("香港", StringComparison.OrdinalIgnoreCase) >= 0;
                case "en":
                case "en-us":
                case "en_us":
                case "eng":
                case "english":
                    return displayLanguage.IndexOf("english", StringComparison.OrdinalIgnoreCase) >= 0;
                default:
                    return false;
            }
        }

        private List<RemoteImageInfo> RewriteSelectedFallbackImages(IEnumerable<RemoteImageInfo> images, IEnumerable<string> fallbackLanguages)
        {
            var materializedFallbackLanguages = fallbackLanguages
                ?.Select(NormalizeLanguage)
                .Where(i => !string.IsNullOrWhiteSpace(i))
                .Distinct(StringComparer.OrdinalIgnoreCase)
                .ToList()
                ?? new List<string>();

            return images.Select(image => RewriteSelectedFallbackImage(image, materializedFallbackLanguages)).ToList();
        }

        private RemoteImageInfo RewriteSelectedFallbackImage(RemoteImageInfo image, IReadOnlyCollection<string> fallbackLanguages)
        {
            if (image == null || fallbackLanguages == null || fallbackLanguages.Count == 0 || !LanguageMatchesAny(image, fallbackLanguages))
            {
                return image;
            }

            var rewrittenImage = CloneRemoteImageInfo(image);
            rewrittenImage.Language = "en";
            rewrittenImage.DisplayLanguage = "English";
            return rewrittenImage;
        }

        private RemoteImageInfo CloneRemoteImageInfo(RemoteImageInfo source)
        {
            if (source == null)
            {
                return null;
            }

            return new RemoteImageInfo
            {
                ProviderName = source.ProviderName,
                Url = source.Url,
                ThumbnailUrl = source.ThumbnailUrl,
                CommunityRating = source.CommunityRating,
                Height = source.Height,
                Width = source.Width,
                VoteCount = source.VoteCount,
                Language = source.Language,
                Type = source.Type,
                RatingType = source.RatingType,
                DisplayLanguage = source.DisplayLanguage
            };
        }

        private HashSet<string> GetEnabledProviders(PluginOptions options)
        {
            return new HashSet<string>(
                options?.GetEnabledProviders() ?? Array.Empty<string>(),
                StringComparer.OrdinalIgnoreCase);
        }

        private HashSet<string> ParseEnabledProviders(string providers)
        {
            return new HashSet<string>(
                (providers ?? string.Empty)
                    .Split(new[] { ',' }, StringSplitOptions.RemoveEmptyEntries)
                    .Select(i => i.Trim())
                    .Where(i => !string.IsNullOrWhiteSpace(i)),
                StringComparer.OrdinalIgnoreCase);
        }

        private IEnumerable<ProviderQueryPlan> GetProviderPlans(HashSet<string> enabledProviders)
        {
            var requestedProviders = enabledProviders.Count > 0 ? enabledProviders : new HashSet<string>(DefaultProviderNames, StringComparer.OrdinalIgnoreCase);
            var seenCanonicalNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

            foreach (var requestedProvider in requestedProviders)
            {
                var canonicalName = CanonicalizeProviderName(requestedProvider);

                if (string.IsNullOrWhiteSpace(canonicalName)
                    || string.Equals(canonicalName, Name, StringComparison.OrdinalIgnoreCase)
                    || !seenCanonicalNames.Add(canonicalName))
                {
                    continue;
                }

                yield return new ProviderQueryPlan
                {
                    RequestedName = requestedProvider,
                    CanonicalName = canonicalName,
                    QueryNames = GetQueryNamesForProvider(canonicalName, requestedProvider)
                };
            }
        }

        private async Task<List<RemoteImageInfo>> QueryUpstreamProviderAsync(
            BaseItem item,
            LibraryOptions libraryOptions,
            ProviderQueryPlan providerPlan,
            IReadOnlyCollection<string> primaryLanguages,
            IReadOnlyCollection<string> fallbackLanguages,
            CancellationToken cancellationToken)
        {
            // 优先直接调用已注册的上游 IRemoteImageProvider，避免 provider 内部再次重入 ProviderManager。
            var directProviders = ResolveDirectUpstreamProviders(providerPlan);

            WriteInfoLog("Fallback provider resolved direct upstream providers. Item='{0}', Requested={1}, Canonical={2}, Providers={3}",
            item.Name,
            providerPlan.RequestedName,
            providerPlan.CanonicalName,
            FormatDirectProviders(directProviders));

            if (directProviders.Count == 0)
            {
                WriteWarningLog("Fallback provider could not resolve any direct upstream providers for item '{0}'. Requested={1}, Canonical={2}, Aliases=[{3}]. Falling back to ProviderManager query.",
                item.Name,
                providerPlan.RequestedName,
                providerPlan.CanonicalName,
                string.Join(",", providerPlan.QueryNames));

                // 某些运行时如果无法直接发现上游 provider，则退回旧的 ProviderManager 查询路径。
                if (!(Plugin.Instance.CurrentOptions?.EnableProviderManagerFallback ?? true))
                {
                    return new List<RemoteImageInfo>();
                }

                return await QueryUpstreamProviderViaManagerAsync(
                    item,
                    libraryOptions,
                    providerPlan,
                    primaryLanguages,
                    fallbackLanguages,
                    cancellationToken).ConfigureAwait(false);
            }

            foreach (var upstreamProvider in directProviders)
            {
                try
                {
                    var providerDisplayName = DescribeRemoteImageProvider(upstreamProvider);
                    var supports = upstreamProvider.Supports(item);
                    var supportedTypes = supports
                        ? SafeGetSupportedImages(upstreamProvider, item)
                        : new List<ImageType>();
                    // 直接调用上游 provider 时没有 IncludeAllLanguages 开关，因此按多种语言上下文轮询并合并结果。
                    var languageFetchPlans = BuildLanguageFetchPlans(item, libraryOptions, primaryLanguages, fallbackLanguages);

                    WriteInfoLog("Fallback provider invoking direct upstream provider {0} for item '{1}'. Supports={2}, SupportedTypes={3}, Requested={4}, Canonical={5}, LanguagePlans={6}",
                    providerDisplayName,
                    item.Name,
                    supports,
                    supportedTypes.Count == 0 ? "<none>" : string.Join(",", supportedTypes),
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName,
                    string.Join(" | ", languageFetchPlans.Select(FormatLanguageFetchPlan)));

                    if (!supports)
                    {
                        continue;
                    }

                    var mergedImages = new List<RemoteImageInfo>();
                    var seenImageKeys = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

                    foreach (var languageFetchPlan in languageFetchPlans)
                    {
                        var fetchLibraryOptions = CreateLibraryOptionsForLanguage(libraryOptions, languageFetchPlan.Language, languageFetchPlan.CountryCode);
                        var effectivePreferredLanguage = GetPreferredMetadataLanguage(item, fetchLibraryOptions);
                        var effectivePreferredCountry = GetPreferredMetadataCountryCode(item, fetchLibraryOptions);

                        WriteInfoLog("Fallback provider invoking direct upstream provider {0} language pass {1} for item '{2}'. RequestedLanguage={3}, RequestedCountry={4}, EffectivePreferredLanguage={5}, EffectivePreferredCountry={6}",
                        providerDisplayName,
                        languageFetchPlan.Label,
                        item.Name,
                        languageFetchPlan.Language ?? "<null>",
                        languageFetchPlan.CountryCode ?? "<null>",
                        effectivePreferredLanguage ?? "<null>",
                        effectivePreferredCountry ?? "<null>");

                        var providerImages = await InvokeUpstreamGetImagesAsync(
                                upstreamProvider,
                                item,
                                fetchLibraryOptions,
                                languageFetchPlan,
                                cancellationToken)
                            .ConfigureAwait(false)
                            ?? Enumerable.Empty<RemoteImageInfo>();

                        var materializedImages = providerImages
                            .Where(i => !string.Equals(i.ProviderName, Name, StringComparison.OrdinalIgnoreCase))
                            .ToList();

                        WriteInfoLog("Fallback provider received {0} images from direct upstream provider {1} language pass {2} for item '{3}'. Requested={4}, Canonical={5}",
                        materializedImages.Count,
                        providerDisplayName,
                        languageFetchPlan.Label,
                        item.Name,
                        providerPlan.RequestedName,
                        providerPlan.CanonicalName);

                        WriteInfoLog("Fallback provider upstream language summary. Item='{0}', ProviderAlias={1}, Requested={2}, Canonical={3}, Pass={4}, Summary={5}",
                        item.Name,
                        providerDisplayName,
                        providerPlan.RequestedName,
                        providerPlan.CanonicalName,
                        languageFetchPlan.Label,
                            BuildLanguageSummary(materializedImages, primaryLanguages, fallbackLanguages));

                        AddUniqueImages(mergedImages, seenImageKeys, materializedImages);
                    }

                    WriteInfoLog("Fallback provider merged direct upstream results. Item='{0}', Provider={1}, Requested={2}, Canonical={3}, Summary={4}",
                    item.Name,
                    providerDisplayName,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName,
                        BuildLanguageSummary(mergedImages, primaryLanguages, fallbackLanguages));

                    if (mergedImages.Count > 0)
                    {
                        return mergedImages;
                    }
                }
                catch (Exception ex)
                {
                    WriteErrorLog("Fallback provider failed invoking direct upstream provider {0} for item '{1}'. Requested={2}, Canonical={3}", ex, DescribeRemoteImageProvider(upstreamProvider),
                    item.Name,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName);
                }
            }

            WriteWarningLog("Fallback provider received zero images from all aliases for item '{0}'. Requested={1}, Canonical={2}, Tried=[{3}]",
            item.Name,
            providerPlan.RequestedName,
            providerPlan.CanonicalName,
            string.Join(",", providerPlan.QueryNames));

            return new List<RemoteImageInfo>();
        }

        private List<LanguageFetchPlan> BuildLanguageFetchPlans(BaseItem item, LibraryOptions libraryOptions, IEnumerable<string> primaryLanguages, IEnumerable<string> fallbackLanguages)
        {
            // 先尝试原始库上下文，再尝试主/备语言，最后尝试无语言上下文。
            var plans = new List<LanguageFetchPlan>();
            var seenKeys = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

            AddLanguageFetchPlan(plans, seenKeys, "original", GetPreferredMetadataLanguage(item, libraryOptions), GetPreferredMetadataCountryCode(item, libraryOptions));

            foreach (var primaryLanguage in primaryLanguages ?? Enumerable.Empty<string>())
            {
                AddLanguageFetchPlan(plans, seenKeys, "primary:" + primaryLanguage, primaryLanguage, DeriveCountryCode(primaryLanguage));
            }

            foreach (var fallbackLanguage in fallbackLanguages ?? Enumerable.Empty<string>())
            {
                AddLanguageFetchPlan(plans, seenKeys, "fallback:" + fallbackLanguage, fallbackLanguage, DeriveCountryCode(fallbackLanguage));
            }

            AddLanguageFetchPlan(plans, seenKeys, "neutral", null, null);

            return plans;
        }

        private void AddLanguageFetchPlan(List<LanguageFetchPlan> plans, HashSet<string> seenKeys, string label, string language, string countryCode)
        {
            var normalizedLanguage = NormalizeLanguage(language);
            var normalizedCountryCode = NormalizeCountryCode(countryCode);
            var planKey = string.Format("{0}|{1}", normalizedLanguage ?? "<null>", normalizedCountryCode ?? "<null>");

            if (!seenKeys.Add(planKey))
            {
                return;
            }

            plans.Add(new LanguageFetchPlan
            {
                Label = label,
                Language = normalizedLanguage,
                CountryCode = normalizedCountryCode
            });
        }

        private LibraryOptions CreateLibraryOptionsForLanguage(LibraryOptions libraryOptions, string language, string countryCode)
        {
            if (libraryOptions == null)
            {
                return null;
            }

            var normalizedLanguage = NormalizeLanguage(language);
            var normalizedCountryCode = NormalizeCountryCode(countryCode);

            var clone = ShallowClone(libraryOptions) ?? libraryOptions;

            // 每个语言轮次都使用克隆后的 LibraryOptions，仅改图片/元数据语言与国家码。
            clone.PreferredImageLanguage = normalizedLanguage;
            clone.PreferredMetadataLanguage = normalizedLanguage;
            clone.MetadataCountryCode = normalizedCountryCode;

            return clone;
        }

        private LibraryOptions ShallowClone(LibraryOptions libraryOptions)
        {
            if (libraryOptions == null || MemberwiseCloneMethod == null)
            {
                return libraryOptions;
            }

            try
            {
                return MemberwiseCloneMethod.Invoke(libraryOptions, null) as LibraryOptions ?? libraryOptions;
            }
            catch
            {
                return libraryOptions;
            }
        }

        private async Task<IEnumerable<RemoteImageInfo>> InvokeUpstreamGetImagesAsync(
            IRemoteImageProvider upstreamProvider,
            BaseItem item,
            LibraryOptions libraryOptions,
            LanguageFetchPlan languageFetchPlan,
            CancellationToken cancellationToken)
        {
            if (upstreamProvider is IRemoteImageProviderWithOptions providerWithOptions)
            {
                var fetchOptions = BuildRemoteImageFetchOptions(item, libraryOptions, languageFetchPlan);

                try
                {
                    WriteInfoLog("Fallback provider using provider-with-options path for {0}. Pass={1}, MetadataLanguages={2}, MetadataCountryCode={3}",
                    DescribeRemoteImageProvider(upstreamProvider),
                    languageFetchPlan.Label,
                    fetchOptions.MetadataLanguages == null || fetchOptions.MetadataLanguages.Length == 0
                        ? "<none>"
                        : string.Join(",", fetchOptions.MetadataLanguages.Select(i => i?.ThreeLetterISOLanguageName ?? i?.TwoLetterISOLanguageName ?? i?.Name ?? "<null>")),
                    fetchOptions.MetadataCountryCode ?? "<null>");

                    return await providerWithOptions.GetImages(fetchOptions, cancellationToken).ConfigureAwait(false);
                }
                catch (NotImplementedException ex)
                {
                    WriteWarningLog("Fallback provider provider-with-options path threw NotImplementedException for {0}. Pass={1}. Falling back to base GetImages. Error={2}",
                    DescribeRemoteImageProvider(upstreamProvider),
                    languageFetchPlan.Label,
                    ex.Message);
                }
            }

            return await upstreamProvider.GetImages(item, libraryOptions, cancellationToken).ConfigureAwait(false);
        }

        private RemoteImageFetchOptions BuildRemoteImageFetchOptions(BaseItem item, LibraryOptions libraryOptions, LanguageFetchPlan languageFetchPlan)
        {
            return new RemoteImageFetchOptions
            {
                Item = item,
                LibraryOptions = libraryOptions,
                DirectoryService = _directoryService,
                MetadataCountryCode = languageFetchPlan.CountryCode,
                MetadataLanguages = BuildCultureDtos(languageFetchPlan.Language)
            };
        }

        private CultureDto[] BuildCultureDtos(string language)
        {
            var normalizedLanguage = NormalizeLanguage(language);

            if (string.IsNullOrWhiteSpace(normalizedLanguage))
            {
                return Array.Empty<CultureDto>();
            }

            var dto = new CultureDto();
            SetCultureDtoString(dto, normalizedLanguage, "Name", "DisplayName", "TwoLetterISOLanguageName");

            var separators = new[] { '-', '_' };
            var parts = normalizedLanguage.Split(separators, StringSplitOptions.RemoveEmptyEntries);
            if (parts.Length > 0)
            {
                SetCultureDtoString(dto, parts[0], "TwoLetterISOLanguageName");
            }

            if (string.Equals(normalizedLanguage, "zh-CN", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zh-SG", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zho", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zh-Hans", StringComparison.OrdinalIgnoreCase))
            {
                SetCultureDtoString(dto, "zho", "ThreeLetterISOLanguageName");
            }
            else if (string.Equals(normalizedLanguage, "zh-TW", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zh-HK", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zhtw", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zh-Hant-TW", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "zh-Hant-HK", StringComparison.OrdinalIgnoreCase))
            {
                SetCultureDtoString(dto, "zht", "ThreeLetterISOLanguageName");
            }
            else if (string.Equals(normalizedLanguage, "ja", StringComparison.OrdinalIgnoreCase)
                || string.Equals(normalizedLanguage, "ja-JP", StringComparison.OrdinalIgnoreCase))
            {
                SetCultureDtoString(dto, "jpn", "ThreeLetterISOLanguageName");
            }

            return new[] { dto };
        }

        private void SetCultureDtoString(CultureDto dto, string value, params string[] propertyNames)
        {
            if (dto == null || string.IsNullOrWhiteSpace(value))
            {
                return;
            }

            var dtoType = dto.GetType();

            foreach (var propertyName in propertyNames)
            {
                var property = dtoType.GetProperty(propertyName, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
                if (property != null && property.CanWrite && property.PropertyType == typeof(string))
                {
                    try
                    {
                        property.SetValue(dto, value);
                    }
                    catch
                    {
                    }
                }
            }
        }

        private void AddUniqueImages(List<RemoteImageInfo> destination, HashSet<string> seenImageKeys, IEnumerable<RemoteImageInfo> images)
        {
            foreach (var image in images)
            {
                var imageKey = BuildImageKey(image);

                if (seenImageKeys.Add(imageKey))
                {
                    destination.Add(image);
                }
            }
        }

        private string BuildImageKey(RemoteImageInfo image)
        {
            // URL 优先作为去重键；没有 URL 时退回到复合键，避免多语言轮询产生重复候选。
            if (!string.IsNullOrWhiteSpace(image?.Url))
            {
                return image.Url.Trim();
            }

            return string.Format(
                "{0}|{1}|{2}|{3}|{4}",
                image?.ProviderName ?? "<null>",
                image?.Type.ToString() ?? "<null>",
                NormalizeLanguage(image?.Language) ?? "<null>",
                image?.DisplayLanguage ?? "<null>",
                image?.ThumbnailUrl ?? "<null>");
        }

        private string DeriveCountryCode(string language)
        {
            var normalizedLanguage = NormalizeLanguage(language);

            if (string.IsNullOrWhiteSpace(normalizedLanguage))
            {
                return null;
            }

            var separators = new[] { '-', '_' };
            var parts = normalizedLanguage.Split(separators, StringSplitOptions.RemoveEmptyEntries);

            if (parts.Length > 1 && parts[parts.Length - 1].Length == 2)
            {
                return NormalizeCountryCode(parts[parts.Length - 1]);
            }

            switch (normalizedLanguage.ToLowerInvariant())
            {
                case "ja":
                case "jpn":
                    return "JP";
                case "zh-hans":
                case "zh":
                case "zh-cn":
                case "zh-sg":
                case "zho":
                    return "CN";
                case "zh-hant-tw":
                case "zh-tw":
                case "zhtw":
                    return "TW";
                case "zh-hant-hk":
                case "zh-hk":
                    return "HK";
                case "en":
                    return "US";
                case "ko":
                    return "KR";
                case "de":
                    return "DE";
                default:
                    return null;
            }
        }

        private string NormalizeCountryCode(string countryCode)
        {
            return string.IsNullOrWhiteSpace(countryCode) ? null : countryCode.Trim().ToUpperInvariant();
        }

        private void WriteInfoLog(string format, params object[] args)
        {
            if (GetConfiguredLogLevel() >= PluginLogLevel.Info)
            {
                _logger.Info(format, args);
            }
        }

        private void WriteWarningLog(string format, params object[] args)
        {
            if (GetConfiguredLogLevel() >= PluginLogLevel.Warning)
            {
                _logger.Warn(format, args);
            }
        }

        private void WriteErrorLog(string format, Exception exception, params object[] args)
        {
            _logger.ErrorException(format, exception, args);
        }

        private PluginLogLevel GetConfiguredLogLevel()
        {
            return Plugin.Instance?.CurrentOptions?.LogLevel ?? PluginLogLevel.Info;
        }

        private string FormatLanguageFetchPlan(LanguageFetchPlan plan)
        {
            return string.Format(
                "label={0},language={1},country={2}",
                plan.Label,
                plan.Language ?? "<null>",
                plan.CountryCode ?? "<null>");
        }

        private async Task<List<RemoteImageInfo>> QueryUpstreamProviderViaManagerAsync(
            BaseItem item,
            LibraryOptions libraryOptions,
            ProviderQueryPlan providerPlan,
            IReadOnlyCollection<string> primaryLanguages,
            IReadOnlyCollection<string> fallbackLanguages,
            CancellationToken cancellationToken)
        {
            // 兼容性兜底路径：仅在无法直接调用上游 provider 时使用。
            foreach (var providerName in providerPlan.QueryNames)
            {
                try
                {
                    WriteInfoLog("Fallback provider querying upstream provider alias {0} for item '{1}'. Requested={2}, Canonical={3}",
                    providerName,
                    item.Name,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName);

                    var providerImages = await _providerManager.GetAvailableRemoteImages(
                        item,
                        libraryOptions,
                        new RemoteImageQuery
                        {
                            IncludeAllLanguages = true,
                            IncludeDisabledProviders = true,
                            ProviderName = providerName
                        },
                        cancellationToken).ConfigureAwait(false);

                    var materializedImages = providerImages
                        .Where(i => !string.Equals(i.ProviderName, Name, StringComparison.OrdinalIgnoreCase))
                        .ToList();

                    WriteInfoLog("Fallback provider received {0} images from upstream provider alias {1} for item '{2}'. Requested={3}, Canonical={4}",
                    materializedImages.Count,
                    providerName,
                    item.Name,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName);

                    WriteInfoLog("Fallback provider upstream language summary. Item='{0}', ProviderAlias={1}, Requested={2}, Canonical={3}, Summary={4}",
                    item.Name,
                    providerName,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName,
                        BuildLanguageSummary(materializedImages, primaryLanguages, fallbackLanguages));

                    if (materializedImages.Count > 0)
                    {
                        return materializedImages;
                    }
                }
                catch (Exception ex)
                {
                    WriteErrorLog("Fallback provider failed querying upstream provider alias {0} for item '{1}'. Requested={2}, Canonical={3}", ex, providerName,
                    item.Name,
                    providerPlan.RequestedName,
                    providerPlan.CanonicalName);
                }
            }

            WriteWarningLog("Fallback provider received zero images from all aliases for item '{0}'. Requested={1}, Canonical={2}, Tried=[{3}]",
            item.Name,
            providerPlan.RequestedName,
            providerPlan.CanonicalName,
            string.Join(",", providerPlan.QueryNames));

            return new List<RemoteImageInfo>();
        }

        private void LogItemDiagnostics(BaseItem item, LibraryOptions libraryOptions)
        {
            WriteInfoLog("Fallback provider item diagnostics. Item='{0}', ItemType={1}, ProviderIds=[{2}], PreferredMetadataLanguage={3}, PreferredCountryCode={4}",
            item?.Name ?? "<null>",
            item?.GetType().Name ?? "<null>",
            BuildProviderIdsSummary(item),
            GetPreferredMetadataLanguage(item, libraryOptions) ?? "<null>",
            GetPreferredMetadataCountryCode(item, libraryOptions) ?? "<null>");

            WriteInfoLog("Fallback provider manager diagnostics. ManagerType={0}, DirectRemoteProviders={1}, RegisteredProviderHints={2}",
            _providerManager?.GetType().FullName ?? "<null>",
            FormatDirectProviders(DiscoverRemoteImageProviders()),
            DiscoverRegisteredProviderHints());
        }

        private List<IRemoteImageProvider> ResolveDirectUpstreamProviders(ProviderQueryPlan providerPlan)
        {
            var queryNames = new HashSet<string>(providerPlan.QueryNames, StringComparer.OrdinalIgnoreCase);

            return DiscoverRemoteImageProviders()
                .Where(i => !IsSelfProvider(i) && ProviderMatchesQuery(i, queryNames))
                .ToList();
        }

        private List<IRemoteImageProvider> DiscoverRemoteImageProviders()
        {
            // Emby 不同构建里 provider 的暴露位置可能不同，因此同时扫描属性和字段。
            var discoveredProviders = new List<IRemoteImageProvider>();
            var seenProviders = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
            var managerType = _providerManager?.GetType();

            if (managerType == null)
            {
                return discoveredProviders;
            }

            foreach (var property in managerType.GetProperties(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic))
            {
                if (property.GetIndexParameters().Length > 0)
                {
                    continue;
                }

                object value;

                try
                {
                    value = property.GetValue(_providerManager);
                }
                catch
                {
                    continue;
                }

                CollectRemoteImageProviders(value, discoveredProviders, seenProviders);
            }

            foreach (var field in managerType.GetFields(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic))
            {
                object value;

                try
                {
                    value = field.GetValue(_providerManager);
                }
                catch
                {
                    continue;
                }

                CollectRemoteImageProviders(value, discoveredProviders, seenProviders);
            }

            return discoveredProviders;
        }

        private void CollectRemoteImageProviders(object value, List<IRemoteImageProvider> discoveredProviders, HashSet<string> seenProviders)
        {
            var directProvider = UnwrapRemoteImageProvider(value);

            if (directProvider != null)
            {
                AddRemoteImageProvider(discoveredProviders, seenProviders, directProvider);
                return;
            }

            if (value is string || !(value is IEnumerable enumerable))
            {
                return;
            }

            foreach (var entry in enumerable)
            {
                var entryProvider = UnwrapRemoteImageProvider(entry);

                if (entryProvider != null)
                {
                    AddRemoteImageProvider(discoveredProviders, seenProviders, entryProvider);
                }
            }
        }

        private IRemoteImageProvider UnwrapRemoteImageProvider(object value)
        {
            // 某些集合元素是包装对象而不是 provider 本体，需要继续向内拆。
            if (value is IRemoteImageProvider provider)
            {
                return provider;
            }

            if (value == null)
            {
                return null;
            }

            var valueType = value.GetType();

            foreach (var property in valueType.GetProperties(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic))
            {
                if (property.GetIndexParameters().Length > 0 || !typeof(IRemoteImageProvider).IsAssignableFrom(property.PropertyType))
                {
                    continue;
                }

                try
                {
                    return property.GetValue(value) as IRemoteImageProvider;
                }
                catch
                {
                }
            }

            foreach (var field in valueType.GetFields(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic))
            {
                if (!typeof(IRemoteImageProvider).IsAssignableFrom(field.FieldType))
                {
                    continue;
                }

                try
                {
                    return field.GetValue(value) as IRemoteImageProvider;
                }
                catch
                {
                }
            }

            return null;
        }

        private void AddRemoteImageProvider(List<IRemoteImageProvider> discoveredProviders, HashSet<string> seenProviders, IRemoteImageProvider provider)
        {
            if (provider == null)
            {
                return;
            }

            var providerKey = string.Format(
                "{0}|{1}",
                provider.GetType().FullName ?? provider.GetType().Name,
                SafeGetProviderName(provider) ?? "<null>");

            if (seenProviders.Add(providerKey))
            {
                discoveredProviders.Add(provider);
            }
        }

        private bool ProviderMatchesQuery(IRemoteImageProvider provider, HashSet<string> queryNames)
        {
            // 同时按 provider.Name 和实现类型名匹配，兼容命名不一致的情况。
            var providerName = NormalizeLanguage(SafeGetProviderName(provider));
            var providerTypeName = provider?.GetType().Name;
            var providerTypeFullName = provider?.GetType().FullName;

            foreach (var queryName in queryNames)
            {
                if (string.IsNullOrWhiteSpace(queryName))
                {
                    continue;
                }

                if (string.Equals(providerName, queryName, StringComparison.OrdinalIgnoreCase)
                    || (!string.IsNullOrWhiteSpace(providerName) && providerName.IndexOf(queryName, StringComparison.OrdinalIgnoreCase) >= 0)
                    || (!string.IsNullOrWhiteSpace(providerTypeName) && providerTypeName.IndexOf(queryName, StringComparison.OrdinalIgnoreCase) >= 0)
                    || (!string.IsNullOrWhiteSpace(providerTypeFullName) && providerTypeFullName.IndexOf(queryName, StringComparison.OrdinalIgnoreCase) >= 0))
                {
                    return true;
                }
            }

            return false;
        }

        private bool IsSelfProvider(IRemoteImageProvider provider)
        {
            return provider == null
                || ReferenceEquals(provider, this)
                || string.Equals(SafeGetProviderName(provider), Name, StringComparison.OrdinalIgnoreCase);
        }

        private List<ImageType> SafeGetSupportedImages(IRemoteImageProvider provider, BaseItem item)
        {
            try
            {
                return (provider.GetSupportedImages(item) ?? Enumerable.Empty<ImageType>())
                    .Distinct()
                    .ToList();
            }
            catch (Exception ex)
            {
                WriteWarningLog("Fallback provider failed reading supported image types from direct provider {0}. Error={1}",
                DescribeRemoteImageProvider(provider),
                ex.GetType().Name);

                return new List<ImageType>();
            }
        }

        private string SafeGetProviderName(IRemoteImageProvider provider)
        {
            if (provider == null)
            {
                return null;
            }

            try
            {
                return provider.Name;
            }
            catch (Exception ex)
            {
                return "<error:" + ex.GetType().Name + ">";
            }
        }

        private string DescribeRemoteImageProvider(IRemoteImageProvider provider)
        {
            if (provider == null)
            {
                return "<null>";
            }

            return string.Format(
                "{0}({1})",
                SafeGetProviderName(provider) ?? "<null>",
                provider.GetType().FullName ?? provider.GetType().Name);
        }

        private string FormatDirectProviders(IEnumerable<IRemoteImageProvider> providers)
        {
            var materializedProviders = providers
                ?.Where(i => i != null)
                .Select(DescribeRemoteImageProvider)
                .Distinct(StringComparer.OrdinalIgnoreCase)
                .OrderBy(i => i, StringComparer.OrdinalIgnoreCase)
                .ToList()
                ?? new List<string>();

            return materializedProviders.Count == 0 ? "<none>" : string.Join(" | ", materializedProviders);
        }

        private string BuildProviderIdsSummary(BaseItem item)
        {
            if (item?.ProviderIds == null)
            {
                return "<null>";
            }

            var pairs = item.ProviderIds
                .OrderBy(i => i.Key, StringComparer.OrdinalIgnoreCase)
                .Select(i => string.Format("{0}={1}", i.Key, i.Value ?? "<null>"))
                .ToList();

            return pairs.Count == 0 ? "<empty>" : string.Join(" | ", pairs);
        }

        private string GetPreferredMetadataLanguage(BaseItem item, LibraryOptions libraryOptions)
        {
            if (item == null || libraryOptions == null)
            {
                return null;
            }

            try
            {
                return item.GetPreferredMetadataLanguage(libraryOptions);
            }
            catch (Exception ex)
            {
                return "<error:" + ex.GetType().Name + ">";
            }
        }

        private string GetPreferredMetadataCountryCode(BaseItem item, LibraryOptions libraryOptions)
        {
            if (item == null || libraryOptions == null)
            {
                return null;
            }

            try
            {
                return item.GetPreferredMetadataCountryCode(libraryOptions);
            }
            catch (Exception ex)
            {
                return "<error:" + ex.GetType().Name + ">";
            }
        }

        private string DiscoverRegisteredProviderHints()
        {
            try
            {
                var managerType = _providerManager?.GetType();

                if (managerType == null)
                {
                    return "<null>";
                }

                var candidateProperties = new[] { "RemoteImageProviders", "ImageProviders", "Providers", "MetadataProviders" };
                var discovered = new List<string>();

                foreach (var propertyName in candidateProperties)
                {
                    var property = managerType.GetProperty(propertyName, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);

                    if (property == null)
                    {
                        continue;
                    }

                    string summary;

                    try
                    {
                        summary = BuildProviderHintSummary(property.GetValue(_providerManager));
                    }
                    catch (Exception ex)
                    {
                        summary = "<error:" + ex.GetType().Name + ">";
                    }

                    discovered.Add(propertyName + "=" + summary);
                }

                return discovered.Count == 0 ? "<unavailable>" : string.Join("; ", discovered);
            }
            catch (Exception ex)
            {
                return "<error:" + ex.GetType().Name + ">";
            }
        }

        private string BuildProviderHintSummary(object value)
        {
            if (value == null)
            {
                return "<null>";
            }

            if (!(value is IEnumerable enumerable))
            {
                return "<not-enumerable:" + value.GetType().Name + ">";
            }

            var names = new List<string>();

            foreach (var entry in enumerable)
            {
                if (entry == null)
                {
                    names.Add("<null>");
                    continue;
                }

                if (entry is string stringEntry)
                {
                    names.Add(stringEntry);
                    continue;
                }

                var entryType = entry.GetType();
                var nameProperty = entryType.GetProperty("Name", BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
                var nameValue = nameProperty?.GetValue(entry) as string;
                names.Add(string.IsNullOrWhiteSpace(nameValue) ? entryType.Name : string.Format("{0}({1})", nameValue, entryType.Name));
            }

            return names.Count == 0
                ? "<empty>"
                : string.Join(",", names.Distinct(StringComparer.OrdinalIgnoreCase).OrderBy(i => i, StringComparer.OrdinalIgnoreCase));
        }

        private string CanonicalizeProviderName(string providerName)
        {
            var normalizedProviderName = NormalizeLanguage(providerName);

            if (string.IsNullOrWhiteSpace(normalizedProviderName))
            {
                return null;
            }

            foreach (var entry in ProviderNameAliases)
            {
                if (entry.Value.Any(i => string.Equals(i, normalizedProviderName, StringComparison.OrdinalIgnoreCase)))
                {
                    return entry.Key;
                }
            }

            return normalizedProviderName;
        }

        private List<string> GetQueryNamesForProvider(string canonicalName, string requestedName)
        {
            var names = new List<string>();

            if (!string.IsNullOrWhiteSpace(requestedName))
            {
                names.Add(requestedName.Trim());
            }

            if (!string.IsNullOrWhiteSpace(canonicalName))
            {
                names.Add(canonicalName);
            }

            if (!string.IsNullOrWhiteSpace(canonicalName) && ProviderNameAliases.TryGetValue(canonicalName, out var aliases))
            {
                names.AddRange(aliases);
            }

            return names
                .Where(i => !string.IsNullOrWhiteSpace(i) && !string.Equals(i, Name, StringComparison.OrdinalIgnoreCase))
                .Distinct(StringComparer.OrdinalIgnoreCase)
                .ToList();
        }

        private string FormatProviderPlan(ProviderQueryPlan providerPlan)
        {
            return string.Format(
                "requested={0},canonical={1},aliases=[{2}]",
                providerPlan.RequestedName,
                providerPlan.CanonicalName,
                string.Join(",", providerPlan.QueryNames));
        }

        private string BuildLanguageSummary(IEnumerable<RemoteImageInfo> images, IEnumerable<string> primaryLanguages, IEnumerable<string> fallbackLanguages)
        {
            var materialized = images.ToList();
            var materializedPrimaryLanguages = primaryLanguages?.Where(i => !string.IsNullOrWhiteSpace(i)).Distinct(StringComparer.OrdinalIgnoreCase).ToList() ?? new List<string>();
            var materializedFallbackLanguages = fallbackLanguages?.Where(i => !string.IsNullOrWhiteSpace(i)).Distinct(StringComparer.OrdinalIgnoreCase).ToList() ?? new List<string>();
            var primaryCount = materialized.Count(i => LanguageMatchesAny(i, materializedPrimaryLanguages));
            var fallbackCount = materialized.Count(i => LanguageMatchesAny(i, materializedFallbackLanguages));
            var neutralCount = materialized.Count(IsLanguageNeutral);

            var providerGroups = materialized
                .GroupBy(i => string.Format(
                    "provider={0},lang={1},display={2}",
                    i.ProviderName ?? "<null>",
                    NormalizeLanguage(i.Language) ?? "<neutral>",
                    i.DisplayLanguage ?? "<null>"))
                .OrderByDescending(g => g.Count())
                .Select(g => string.Format("{0},count={1}", g.Key, g.Count()));

            return string.Format(
                "total={0}; primary({1})={2}; fallback({3})={4}; neutral={5}; groups=[{6}]",
                materialized.Count,
                materializedPrimaryLanguages.Count == 0 ? "<null>" : string.Join(",", materializedPrimaryLanguages),
                primaryCount,
                materializedFallbackLanguages.Count == 0 ? "<null>" : string.Join(",", materializedFallbackLanguages),
                fallbackCount,
                neutralCount,
                string.Join(" | ", providerGroups));
        }

        private sealed class ProviderQueryPlan
        {
            public string RequestedName { get; set; }
            public string CanonicalName { get; set; }
            public List<string> QueryNames { get; set; } = new List<string>();
        }

        private sealed class LanguageFetchPlan
        {
            public string Label { get; set; }
            public string Language { get; set; }
            public string CountryCode { get; set; }
        }
    }
}