koishi-plugin-emojiluna-plus 0.0.1

package/lib/collectors/autoCollector.js

@@ -0,0 +1,728 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoCollector = void 0;
+const koishi_1 = require("koishi");
+const image_1 = require("../image");
+const utils_1 = require("../utils");
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+const PENDING_REF_TTL_MS = 60_000;
+const REJECTED_HASH_TTL_MS = 6 * HOUR_MS;
+const AI_VERDICT_TTL_MS = 24 * HOUR_MS;
+const SIGNATURE_SAMPLE_FRAMES = 3;
+const AVERAGE_HASH_GRID = { width: 8, height: 8 };
+const DIFFERENCE_HASH_GRID = { width: 9, height: 8 };
+const MAX_SIGNATURE_CACHE = 2000;
+const FRAME_WEIGHT = 0.7;
+const ASPECT_WEIGHT = 0.2;
+const SIZE_WEIGHT = 0.1;
+const TONE_PENALTY_SCALE = 0.6;
+const CONTRAST_PENALTY_SCALE = 0.2;
+const APPEARANCE_PENALTY_CAP = 0.15;
+const RECENT_LOG_SIZE = 8;
+const PROBE_IMAGE_LIMIT = 3;
+const MAX_NAME_LENGTH = 48;
+const SIGNATURE_READY_BUDGET_MS = 15_000;
+const PRELOAD_PAGE_SIZE = 200;
+const POPCOUNT = [0, 1, 1, 2, 1, 2, 2, 3, 1, 2, 2, 3, 2, 3, 3, 4];
+class AutoCollector {
+    ctx;
+    config;
+    debug;
+    signatures = new Map();
+    frequency = new Map();
+    counters = new Map();
+    globalDay = createCounter();
+    pendingRefs = new Map();
+    inFlight = new Set();
+    rejectedHashes = new Map();
+    aiVerdicts = new Map();
+    queue = [];
+    active = 0;
+    nameSeq = 0;
+    manualEnabled = null;
+    signaturesReady = false;
+    stopped = false;
+    metrics = {
+        seen: 0,
+        collected: 0,
+        rejected: {},
+    };
+    recent = [];
+    constructor(ctx, config, debug) {
+        this.ctx = ctx;
+        this.config = config;
+        this.debug = debug;
+        ctx.setInterval(() => this.pruneCaches(), 5 * 60_000);
+        void this.preloadSignatures();
+    }
+    get luna() {
+        return this.ctx.emojiluna;
+    }
+    get isEnabled() {
+        return !this.stopped && (this.manualEnabled ?? this.config.autoCollect);
+    }
+    start() {
+        if (!this.config.autoCollect) {
+            this.debug.log('collect', '自动获取未启用，跳过监听注册');
+            return;
+        }
+        this.ctx.on('message', (session) => this.observe(session));
+        this.ctx.logger.info('Auto collector started');
+    }
+    observe(session) {
+        if (!this.isEnabled)
+            return 0;
+        const images = koishi_1.h.select(session.elements ?? [], 'img');
+        if (images.length === 0)
+            return 0;
+        const isDirect = Boolean(session.isDirect);
+        const chatKey = this.chatKey(session, isDirect);
+        this.metrics.seen += images.length;
+        const scope = this.evaluateScope(isDirect, session);
+        if (!scope.ok) {
+            this.reject('生效范围', scope.detail, chatKey);
+            return 0;
+        }
+        let queued = 0;
+        for (const element of images) {
+            if (this.queue.length >= this.config.autoCollectQueueSize) {
+                this.reject('队列', `队列已满 ${this.config.autoCollectQueueSize}`, chatKey);
+                break;
+            }
+            const limit = this.evaluateLimit(chatKey);
+            if (!limit.ok) {
+                this.reject('限流', limit.detail, chatKey);
+                break;
+            }
+            this.queue.push({ session, element, chatKey, isDirect });
+            queued += 1;
+        }
+        if (queued)
+            this.pump();
+        return queued;
+    }
+    async probe(session, dryRun = true, elements) {
+        const isDirect = Boolean(session.isDirect);
+        const chatKey = this.chatKey(session, isDirect);
+        const images = koishi_1.h.select(elements ?? session.elements ?? [], 'img');
+        if (images.length === 0) {
+            return [{ gate: '取图', ok: false, detail: '消息中没有图片元素' }];
+        }
+        const trace = [
+            this.evaluateScope(isDirect, session),
+            this.evaluateLimit(chatKey),
+            {
+                gate: '服务',
+                ok: this.luna.isInitialized,
+                detail: this.luna.isInitialized
+                    ? 'emojiluna 已就绪'
+                    : 'emojiluna 尚未完成初始化，仍将尝试入库',
+            },
+        ];
+        for (const element of images.slice(0, PROBE_IMAGE_LIMIT)) {
+            await this.processJob({ session, element, chatKey, isDirect, trace, dryRun }, true);
+        }
+        return trace;
+    }
+    stats() {
+        return {
+            enabled: this.isEnabled,
+            configured: this.config.autoCollect,
+            mode: this.config.autoCollectMode,
+            seen: this.metrics.seen,
+            collected: this.metrics.collected,
+            rejected: { ...this.metrics.rejected },
+            queue: this.queue.length,
+            active: this.active,
+            signatures: this.signatures.size,
+            preloaded: this.signaturesReady,
+            recent: [...this.recent],
+        };
+    }
+    setEnabled(enabled) {
+        this.manualEnabled = enabled;
+    }
+    resetCounters() {
+        this.counters.clear();
+        this.globalDay = createCounter();
+        this.metrics = { seen: 0, collected: 0, rejected: {} };
+        this.recent = [];
+        this.debug.clear();
+    }
+    dispose() {
+        this.stopped = true;
+        this.queue = [];
+    }
+    pump() {
+        while (!this.stopped &&
+            this.active < this.config.autoCollectQueue &&
+            this.queue.length > 0) {
+            const job = this.queue.shift();
+            this.active += 1;
+            this.processJob(job, false)
+                .catch((error) => this.ctx.logger.error(`Auto collect job failed: ${error.message}`))
+                .finally(() => {
+                this.active -= 1;
+                this.pump();
+            });
+        }
+    }
+    async processJob(job, probe) {
+        const { session, element, chatKey, isDirect, dryRun } = job;
+        const pass = (result) => {
+            job.trace?.push(result);
+            this.debug.log('collect', `${result.gate}: ${result.detail}`);
+            if (result.ok)
+                return true;
+            if (!probe)
+                this.reject(result.gate, result.detail, chatKey);
+            return probe;
+        };
+        const ref = (0, utils_1.getImageRefs)(element)[0];
+        if (!ref) {
+            return void pass({
+                gate: '取图',
+                ok: false,
+                detail: '图片元素没有 url / src / file / path 属性',
+            });
+        }
+        if (this.pendingRefs.has(ref)) {
+            return void pass({
+                gate: '取图',
+                ok: false,
+                detail: `同一来源正在处理: ${ref}`,
+            });
+        }
+        this.pendingRefs.set(ref, Date.now());
+        try {
+            const image = await (0, utils_1.readImageBuffer)(this.ctx, element, {
+                timeout: this.config.fetchTimeout,
+                allowLocalPaths: this.config.allowLocalPaths,
+                localPathRoots: this.config.localPathRoots,
+            });
+            if (image.kind !== 'ok') {
+                return void pass({
+                    gate: image.failure === 'unsupported-format' ? '格式' : '取图',
+                    ok: false,
+                    detail: image.detail,
+                });
+            }
+            const size = this.evaluateSize(image.buffer.length);
+            if (!pass(size))
+                return;
+            const hash = (0, utils_1.hashBuffer)(image.buffer);
+            if (!pass(this.evaluateKnownHash(hash)))
+                return;
+            this.inFlight.add(hash);
+            try {
+                if (!pass(this.evaluateFrequency(hash, chatKey)))
+                    return;
+                const signature = await this.buildSignature(image.buffer);
+                if (signature) {
+                    if (!pass(this.evaluateResolution(signature)))
+                        return;
+                    if (!pass(this.evaluateSimilarity(signature)))
+                        return;
+                }
+                if (!pass(await this.evaluateAiFilter(hash, image.buffer)))
+                    return;
+                if (!pass(this.evaluateLibrary()))
+                    return;
+                if (dryRun) {
+                    return void pass({
+                        gate: '入库',
+                        ok: true,
+                        detail: `试运行：将保存为 "${this.buildName(session, isDirect)}"，未实际写入`,
+                    });
+                }
+                const saved = await this.save(image.buffer, signature, hash, session, isDirect);
+                if (!pass(saved))
+                    return;
+                this.consumeQuota(chatKey);
+                this.metrics.collected += 1;
+                this.record(`${saved.detail} @ ${chatKey}`);
+            }
+            finally {
+                this.inFlight.delete(hash);
+            }
+        }
+        finally {
+            this.pendingRefs.delete(ref);
+        }
+    }
+    async save(buffer, signature, hash, session, isDirect) {
+        const name = this.buildName(session, isDirect);
+        const tags = this.buildTags(session, isDirect);
+        try {
+            const emoji = await this.luna.addEmoji({ name, category: this.config.autoCollectCategory, tags }, buffer);
+            if (signature)
+                this.rememberSignature(hash, signature);
+            return {
+                gate: '入库',
+                ok: true,
+                detail: `已收集 "${emoji.name}" (${emoji.id})，${this.config.autoAnalyze ? '已排入 AI 分析队列' : '未启用 AI 分析'}`,
+            };
+        }
+        catch (error) {
+            const message = error.message ?? String(error);
+            if (/already exists|已存在/i.test(message)) {
+                this.rejectedHashes.set(hash, Date.now());
+            }
+            return { gate: '入库', ok: false, detail: message };
+        }
+    }
+    evaluateScope(isDirect, session) {
+        if (isDirect) {
+            return {
+                gate: '生效范围',
+                ok: this.config.collectDirect,
+                detail: this.config.collectDirect
+                    ? '私聊已启用'
+                    : '私聊自动获取未启用',
+            };
+        }
+        if (!this.config.collectGroup) {
+            return {
+                gate: '生效范围',
+                ok: false,
+                detail: '群聊自动获取未启用',
+            };
+        }
+        const guildId = String(session.guildId ?? session.channelId ?? '');
+        const whitelist = this.config.whitelistGroups.map(String);
+        const blacklist = this.config.blacklistGroups.map(String);
+        const listed = (list) => list.includes(guildId) || list.includes(String(session.channelId));
+        if (this.config.groupScope === 'whitelist') {
+            return {
+                gate: '生效范围',
+                ok: listed(whitelist),
+                detail: listed(whitelist)
+                    ? `白名单群 ${guildId}`
+                    : `群 ${guildId} 不在白名单内`,
+            };
+        }
+        if (this.config.groupScope === 'blacklist') {
+            return {
+                gate: '生效范围',
+                ok: !listed(blacklist),
+                detail: listed(blacklist)
+                    ? `群 ${guildId} 在黑名单内`
+                    : `群 ${guildId} 未被排除`,
+            };
+        }
+        return { gate: '生效范围', ok: true, detail: `所有群（含 ${guildId}）` };
+    }
+    evaluateSize(bytes) {
+        const sizeKB = bytes / 1024;
+        const sizeMB = sizeKB / 1024;
+        if (sizeKB < this.config.minEmojiSize) {
+            return {
+                gate: '大小',
+                ok: false,
+                detail: `过小 ${sizeKB.toFixed(1)}KB < ${this.config.minEmojiSize}KB`,
+            };
+        }
+        if (sizeMB > this.config.maxEmojiSize) {
+            return {
+                gate: '大小',
+                ok: false,
+                detail: `过大 ${sizeMB.toFixed(2)}MB > ${this.config.maxEmojiSize}MB`,
+            };
+        }
+        return {
+            gate: '大小',
+            ok: true,
+            detail: sizeKB > 1024 ? `${sizeMB.toFixed(2)}MB` : `${sizeKB.toFixed(1)}KB`,
+        };
+    }
+    evaluateResolution(signature) {
+        const min = this.config.minEdgePixels;
+        const edge = Math.min(signature.width, signature.height);
+        if (min > 0 && edge < min) {
+            return {
+                gate: '分辨率',
+                ok: false,
+                detail: `${signature.width}x${signature.height} 短边 ${edge} < ${min}`,
+            };
+        }
+        return {
+            gate: '分辨率',
+            ok: true,
+            detail: `${signature.width}x${signature.height}`,
+        };
+    }
+    evaluateKnownHash(hash) {
+        if (this.inFlight.has(hash)) {
+            return { gate: '去重', ok: false, detail: '同一张图片正在处理中' };
+        }
+        if (this.luna.uploadManager.hasHash(hash)) {
+            return { gate: '去重', ok: false, detail: '库中已存在相同内容的表情' };
+        }
+        const rejectedAt = this.rejectedHashes.get(hash);
+        if (rejectedAt && Date.now() - rejectedAt < REJECTED_HASH_TTL_MS) {
+            return { gate: '去重', ok: false, detail: '此前已判定为重复，暂不再试' };
+        }
+        return { gate: '去重', ok: true, detail: `内容哈希 ${hash.slice(0, 8)}` };
+    }
+    evaluateSimilarity(signature) {
+        let best = null;
+        for (const [hash, cached] of this.signatures) {
+            const score = similarityScore(signature, cached);
+            if (score >= this.config.similarityThreshold && (!best || score > best.score)) {
+                best = { hash, score };
+            }
+        }
+        if (!best) {
+            return {
+                gate: '相似',
+                ok: true,
+                detail: `与近 ${this.signatures.size} 张特征均不相似`,
+            };
+        }
+        return {
+            gate: '相似',
+            ok: false,
+            detail: `与表情 ${best.hash.slice(0, 8)} 相似度 ${best.score.toFixed(3)}，阈值 ${this.config.similarityThreshold}`,
+        };
+    }
+    evaluateFrequency(hash, chatKey) {
+        const windowMs = this.config.frequencyWindow * 60_000;
+        const key = `${hash}|${chatKey}`;
+        const now = Date.now();
+        const stamps = (this.frequency.get(key) ?? []).filter((stamp) => now - stamp <= windowMs);
+        stamps.push(now);
+        this.frequency.set(key, stamps);
+        const reached = stamps.length >= this.config.emojiFrequencyThreshold;
+        if (this.config.autoCollectMode !== 'frequency') {
+            return {
+                gate: '频次',
+                ok: true,
+                detail: `窗口内第 ${stamps.length} 次（即时模式不要求频次）`,
+            };
+        }
+        return {
+            gate: '频次',
+            ok: reached,
+            detail: `窗口内第 ${stamps.length}/${this.config.emojiFrequencyThreshold} 次`,
+        };
+    }
+    evaluateLimit(chatKey) {
+        const counter = this.windowCounter(chatKey);
+        const quota = this.config.groupAutoCollectLimit?.[chatKey.split(':')[1]];
+        const hourLimit = quota?.hourLimit ?? 20;
+        const dayLimit = quota?.dayLimit ?? 100;
+        if (hourLimit > 0 && counter.hourCount >= hourLimit) {
+            return {
+                gate: '限流',
+                ok: false,
+                detail: `本会话本小时已收集 ${counter.hourCount}/${hourLimit}`,
+            };
+        }
+        if (dayLimit > 0 && counter.dayCount >= dayLimit) {
+            return {
+                gate: '限流',
+                ok: false,
+                detail: `本会话今日已收集 ${counter.dayCount}/${dayLimit}`,
+            };
+        }
+        if (this.config.globalDayLimit > 0 &&
+            this.globalDay.dayCount >= this.config.globalDayLimit) {
+            return {
+                gate: '限流',
+                ok: false,
+                detail: `全局今日已收集 ${this.globalDay.dayCount}/${this.config.globalDayLimit}`,
+            };
+        }
+        return {
+            gate: '限流',
+            ok: true,
+            detail: `本会话 ${counter.hourCount}/${hourLimit} 每小时、${counter.dayCount}/${dayLimit} 每日`,
+        };
+    }
+    evaluateLibrary() {
+        const limit = this.config.maxEmojiCount;
+        const count = this.luna.getEmojiCount();
+        if (limit > 0 && count >= limit) {
+            return { gate: '库存', ok: false, detail: `库内 ${count}/${limit} 已达上限` };
+        }
+        return { gate: '库存', ok: true, detail: `库内 ${count} 张` };
+    }
+    async evaluateAiFilter(hash, buffer) {
+        if (!this.config.enableImageTypeFilter) {
+            return { gate: 'AI过滤', ok: true, detail: '未启用图片类型过滤' };
+        }
+        const cached = this.aiVerdicts.get(hash);
+        if (cached && Date.now() - cached.at < AI_VERDICT_TTL_MS) {
+            const { gate, ok, detail } = cached;
+            return { gate, ok, detail: `复用上次判定：${detail}` };
+        }
+        const fallbackOk = this.config.aiFilterFallback === 'accept';
+        let verdict = {
+            gate: 'AI过滤',
+            ok: fallbackOk,
+            detail: fallbackOk
+                ? 'AI 未返回判定，按兜底策略接受'
+                : 'AI 未返回判定，按兜底策略拒绝',
+        };
+        try {
+            const result = await (0, utils_1.withTimeout)(this.luna.filterImageByType(buffer.toString('base64')), this.config.aiFilterTimeout, 'AI 图片类型过滤');
+            if (result) {
+                verdict = {
+                    gate: 'AI过滤',
+                    ok: result.isAcceptable,
+                    detail: `类型 ${result.imageType}，置信度 ${result.confidence ?? 0}，${result.reason ?? ''}`.trim(),
+                };
+            }
+        }
+        catch (error) {
+            verdict = {
+                gate: 'AI过滤',
+                ok: fallbackOk,
+                detail: `AI 过滤失败（${error.message}），按兜底策略${fallbackOk ? '接受' : '拒绝'}`,
+            };
+        }
+        this.aiVerdicts.set(hash, { ...verdict, at: Date.now() });
+        return verdict;
+    }
+    async buildSignature(buffer) {
+        try {
+            const metadata = await (0, image_1.getImageMetadata)(buffer);
+            const indices = (0, image_1.sampleFrameIndices)(metadata.frameCount, SIGNATURE_SAMPLE_FRAMES);
+            const frames = [];
+            for (const index of indices) {
+                const frame = await (0, image_1.extractFrameRgba)(buffer, metadata, index);
+                const averagePixels = await (0, image_1.resizeFrameToGrayscale)(frame, AVERAGE_HASH_GRID.width, AVERAGE_HASH_GRID.height);
+                const differencePixels = await (0, image_1.resizeFrameToGrayscale)(frame, DIFFERENCE_HASH_GRID.width, DIFFERENCE_HASH_GRID.height);
+                frames.push({
+                    averageHash: averageHash(averagePixels),
+                    differenceHash: differenceHash(differencePixels),
+                    ...describeTone(averagePixels),
+                });
+            }
+            if (!frames.length || !metadata.width || !metadata.height)
+                return null;
+            return { frames, width: metadata.width, height: metadata.height };
+        }
+        catch (error) {
+            this.debug.log('collect', `感知特征提取失败，跳过相似判定: ${error.message}`);
+            return null;
+        }
+    }
+    async preloadSignatures() {
+        const startedAt = Date.now();
+        try {
+            await (0, utils_1.withTimeout)(this.luna.ready, SIGNATURE_READY_BUDGET_MS, 'emojiluna 初始化');
+        }
+        catch (error) {
+            this.ctx.logger.warn(`EmojiLuna is not ready for auto collect preload: ${error.message}`);
+        }
+        try {
+            let offset = 0;
+            while (!this.stopped) {
+                const page = await this.luna.getEmojiPage({
+                    limit: PRELOAD_PAGE_SIZE,
+                    offset,
+                });
+                const items = page?.items ?? [];
+                if (!items.length)
+                    break;
+                for (const emoji of items) {
+                    const buffer = await this.luna.readEmojiBuffer(emoji);
+                    if (!buffer)
+                        continue;
+                    const signature = await this.buildSignature(buffer);
+                    if (signature)
+                        this.rememberSignature((0, utils_1.hashBuffer)(buffer), signature);
+                }
+                offset += items.length;
+                if (items.length < PRELOAD_PAGE_SIZE)
+                    break;
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        catch (error) {
+            this.ctx.logger.warn(`Failed to preload emoji signatures: ${error.message}`);
+        }
+        this.signaturesReady = true;
+        this.debug.log('collect', `预热感知特征完成：${this.signatures.size} 条，用时 ${Date.now() - startedAt}ms`);
+    }
+    rememberSignature(hash, signature) {
+        if (this.signatures.has(hash))
+            this.signatures.delete(hash);
+        this.signatures.set(hash, signature);
+        while (this.signatures.size > MAX_SIGNATURE_CACHE) {
+            const oldest = this.signatures.keys().next().value;
+            this.signatures.delete(oldest);
+        }
+    }
+    windowCounter(chatKey) {
+        const now = Date.now();
+        const counter = this.counters.get(chatKey) ?? createCounter(now);
+        this.counters.set(chatKey, counter);
+        if (now - counter.hourStart >= HOUR_MS) {
+            counter.hourStart = now;
+            counter.hourCount = 0;
+        }
+        if (now - counter.dayStart >= DAY_MS) {
+            counter.dayStart = now;
+            counter.dayCount = 0;
+        }
+        return counter;
+    }
+    consumeQuota(chatKey) {
+        const counter = this.windowCounter(chatKey);
+        counter.hourCount += 1;
+        counter.dayCount += 1;
+        const now = Date.now();
+        if (now - this.globalDay.dayStart >= DAY_MS) {
+            this.globalDay = createCounter(now);
+        }
+        this.globalDay.dayCount += 1;
+    }
+    pruneCaches() {
+        const now = Date.now();
+        const windowMs = this.config.frequencyWindow * 60_000;
+        pruneExpired(this.pendingRefs, now, PENDING_REF_TTL_MS);
+        pruneExpired(this.rejectedHashes, now, REJECTED_HASH_TTL_MS);
+        pruneByTimestamp(this.aiVerdicts, now, AI_VERDICT_TTL_MS);
+        for (const [key, stamps] of this.frequency) {
+            const kept = stamps.filter((stamp) => now - stamp <= windowMs);
+            if (kept.length)
+                this.frequency.set(key, kept);
+            else
+                this.frequency.delete(key);
+        }
+    }
+    chatKey(session, isDirect) {
+        return isDirect
+            ? `direct:${session.userId ?? session.channelId}`
+            : `group:${session.guildId ?? session.channelId}`;
+    }
+    buildName(session, isDirect) {
+        const now = new Date();
+        const pad = (value) => String(value).padStart(2, '0');
+        const tokens = {
+            date: `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`,
+            time: `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`,
+            sender: String(session.username || session.userId || 'unknown'),
+            chat: isDirect
+                ? 'direct'
+                : String(session.guildId ?? session.channelId ?? ''),
+            index: String(++this.nameSeq % 100_000),
+        };
+        return this.config.autoCollectNameTemplate
+            .replace(/\{(\w+)\}/g, (_, key) => tokens[key] ?? `{${key}}`)
+            .slice(0, MAX_NAME_LENGTH);
+    }
+    buildTags(session, isDirect) {
+        const scope = isDirect
+            ? '私聊'
+            : `群:${session.guildId ?? session.channelId ?? 'unknown'}`;
+        return [...new Set(['自动获取', scope])]
+            .map((tag) => tag.trim())
+            .filter(Boolean);
+    }
+    reject(gate, detail, chatKey) {
+        this.metrics.rejected[gate] = (this.metrics.rejected[gate] ?? 0) + 1;
+        this.record(`拦截 ${gate} @ ${chatKey}: ${detail}`);
+    }
+    record(text) {
+        this.recent.push(text);
+        while (this.recent.length > RECENT_LOG_SIZE)
+            this.recent.shift();
+    }
+}
+exports.AutoCollector = AutoCollector;
+function createCounter(now = Date.now()) {
+    return { hourStart: now, hourCount: 0, dayStart: now, dayCount: 0 };
+}
+function pruneExpired(map, now, ttl) {
+    for (const [key, at] of map) {
+        if (now - at > ttl)
+            map.delete(key);
+    }
+}
+function pruneByTimestamp(map, now, ttl) {
+    for (const [key, value] of map) {
+        if (now - value.at > ttl)
+            map.delete(key);
+    }
+}
+function toHex(bits) {
+    let hex = '';
+    for (let i = 0; i < bits.length; i += 4) {
+        hex += parseInt(bits.slice(i, i + 4), 2).toString(16);
+    }
+    return hex;
+}
+function averageHash(pixels) {
+    const total = pixels.reduce((sum, value) => sum + value, 0);
+    const mean = total / (pixels.length || 1);
+    let bits = '';
+    for (const value of pixels)
+        bits += value > mean ? '1' : '0';
+    return toHex(bits);
+}
+function differenceHash(pixels) {
+    const { width, height } = DIFFERENCE_HASH_GRID;
+    let bits = '';
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width - 1; x++) {
+            bits += pixels[row + x] > pixels[row + x + 1] ? '1' : '0';
+        }
+    }
+    return toHex(bits);
+}
+function describeTone(pixels) {
+    const total = pixels.length || 1;
+    const mean = pixels.reduce((sum, value) => sum + value, 0) / total;
+    const variance = pixels.reduce((sum, value) => sum + (value - mean) ** 2, 0) / total;
+    return { mean, stdev: Math.sqrt(variance) };
+}
+function hexHamming(left, right) {
+    const length = Math.min(left.length, right.length);
+    let distance = 0;
+    for (let i = 0; i < length; i++) {
+        const a = parseInt(left[i], 16);
+        const b = parseInt(right[i], 16);
+        if (Number.isNaN(a) || Number.isNaN(b)) {
+            distance += 4;
+            continue;
+        }
+        distance += POPCOUNT[(a ^ b) & 0xf];
+    }
+    return distance + Math.abs(left.length - right.length) * 4;
+}
+function hashSimilarity(left, right) {
+    const bits = Math.max(left.length, right.length) * 4;
+    if (!bits)
+        return 0;
+    return 1 - hexHamming(left, right) / bits;
+}
+function frameSimilarity(left, right) {
+    const structure = 0.5 * hashSimilarity(left.averageHash, right.averageHash) +
+        0.5 * hashSimilarity(left.differenceHash, right.differenceHash);
+    const penalty = Math.min(APPEARANCE_PENALTY_CAP, (Math.abs(left.mean - right.mean) / 255) * TONE_PENALTY_SCALE +
+        (Math.abs(left.stdev - right.stdev) / 128) * CONTRAST_PENALTY_SCALE);
+    return Math.max(0, structure - penalty);
+}
+function framesSimilarity(frames, others) {
+    if (!frames.length || !others.length)
+        return 0;
+    const best = frames.map((frame) => Math.max(...others.map((other) => frameSimilarity(frame, other))));
+    return best.reduce((sum, score) => sum + score, 0) / best.length;
+}
+function similarityScore(left, right) {
+    const aspectOf = (item) => item.height === 0 ? 0 : item.width / item.height;
+    const aspect = Math.max(0, 1 - Math.abs(aspectOf(left) - aspectOf(right)));
+    const areaLeft = left.width * left.height;
+    const areaRight = right.width * right.height;
+    const size = areaLeft > 0 && areaRight > 0
+        ? Math.min(areaLeft, areaRight) / Math.max(areaLeft, areaRight)
+        : 0;
+    return (framesSimilarity(left.frames, right.frames) * FRAME_WEIGHT +
+        aspect * ASPECT_WEIGHT +
+        size * SIZE_WEIGHT);
+}