koishi-plugin-share-links-analysis 0.14.0 → 0.15.0

package/lib/index.js

@@ -90,7 +90,8 @@ exports.Config = koishi_1.Schema.intersect([
 ----------
 {mainbody}
 ----------
-{sourceUrl}`).description('图文/视频输出格式。<br/>可用占位符: `{title}`, `{cover}`, `{authorName}`, `{mainbody}`, `{stats}`, `{sourceUrl}`'),
+{cache}
+{sourceUrl}`).description('图文/视频输出格式。<br/>可用占位符: `{title}`, `{cover}`, `{authorName}`, `{mainbody}`, `{stats}`, `{cache}`, `{sourceUrl}`'),
     }).description("格式化模板"),
     koishi_1.Schema.object({
         parseLimit: koishi_1.Schema.number().default(3).description("单对话多链接解析上限"),
@@ -151,6 +152,258 @@ async function reportMetric(ctx, config, payload) {
         }
     });
 }
+function getCombinedRetentionHours(config) {
+    const expirations = [config.cacheExpiration, config.optimisticExpiration];
+    if (expirations.some(value => value === 0))
+        return 0;
+    return Math.max(...expirations);
+}
+function getRetentionThreshold(hours) {
+    if (hours === 0)
+        return null;
+    return Date.now() - hours * 60 * 60 * 1000;
+}
+function normalizeForCompare(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeForCompare);
+    if (value && typeof value === 'object') {
+        const output = {};
+        for (const key of Object.keys(value).sort()) {
+            if (key.startsWith('_'))
+                continue;
+            output[key] = normalizeForCompare(value[key]);
+        }
+        return output;
+    }
+    return value;
+}
+function stableStringify(value) {
+    return JSON.stringify(normalizeForCompare(value));
+}
+function isSameParsedInfo(a, b) {
+    return stableStringify(a) === stableStringify(b);
+}
+function formatDiffValue(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return value.length > 160 ? `${value.slice(0, 157)}...` : value;
+    const text = JSON.stringify(value);
+    return text.length > 160 ? `${text.slice(0, 157)}...` : text;
+}
+function collectDiffLines(before, after, path = '') {
+    if (stableStringify(before) === stableStringify(after))
+        return [];
+    if (Array.isArray(before) || Array.isArray(after)) {
+        return [
+            `- ${path || 'root'}: ${formatDiffValue(before)}`,
+            `+ ${path || 'root'}: ${formatDiffValue(after)}`
+        ];
+    }
+    if (before && after &&
+        typeof before === 'object' &&
+        typeof after === 'object') {
+        const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+        const lines = [];
+        for (const key of [...keys].sort()) {
+            if (key.startsWith('_'))
+                continue;
+            const nextPath = path ? `${path}.${key}` : key;
+            lines.push(...collectDiffLines(before[key], after[key], nextPath));
+        }
+        return lines;
+    }
+    return [
+        `- ${path || 'root'}: ${formatDiffValue(before)}`,
+        `+ ${path || 'root'}: ${formatDiffValue(after)}`
+    ];
+}
+function buildParsedInfoDelta(previous, current) {
+    if (!previous)
+        return 'base';
+    const lines = collectDiffLines(normalizeForCompare(previous), normalizeForCompare(current));
+    return lines.length > 0 ? lines.join('\n') : 'no changes';
+}
+function summarizeParsedInfo(data) {
+    const parts = [
+        `标题: ${data.title || '无标题'}`,
+        `作者: ${data.authorName || '未知'}`,
+        `文件: ${Array.isArray(data.files) ? data.files.length : 0}`,
+    ];
+    if (data.stats)
+        parts.push(`统计: ${data.stats}`);
+    return parts.join('\n');
+}
+function summarizeDelta(delta) {
+    const lines = delta.split('\n');
+    const text = lines.length > 8
+        ? `${lines.slice(0, 8).join('\n')}\n...`
+        : delta;
+    return text.length > 800 ? `${text.slice(0, 797)}...` : text;
+}
+function formatTime(timestamp) {
+    return new Date(timestamp).toLocaleString('zh-CN', { hour12: false });
+}
+function createTimelineNodeId(cacheKey, createdAt = Date.now()) {
+    const safeKey = cacheKey.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return `${safeKey}:${createdAt}:${Math.random().toString(36).slice(2, 8)}`;
+}
+async function getTimelineNodes(ctx, cacheKey) {
+    const nodes = await ctx.database.get('sla_parse_timeline', { cache_key: cacheKey });
+    return nodes.sort((a, b) => a.created_at - b.created_at);
+}
+function isTimelineNodeActive(config, node) {
+    const threshold = getRetentionThreshold(getCombinedRetentionHours(config));
+    if (threshold === null)
+        return true;
+    return (node.last_checked_at || node.created_at) >= threshold;
+}
+async function getActiveTimelineNodes(ctx, config, cacheKey) {
+    const nodes = await getTimelineNodes(ctx, cacheKey);
+    return nodes.filter(node => isTimelineNodeActive(config, node));
+}
+async function touchTimelineNode(ctx, node, checkedAt = Date.now()) {
+    const touched = { ...node, last_checked_at: checkedAt };
+    await ctx.database.upsert('sla_parse_timeline', [touched]);
+    return touched;
+}
+async function createTimelineNodeFromCache(ctx, cacheKey, result, createdAt, delta = 'base') {
+    const node = {
+        node_id: createTimelineNodeId(cacheKey, createdAt),
+        cache_key: cacheKey,
+        data: result,
+        delta,
+        created_at: createdAt,
+        last_checked_at: createdAt,
+    };
+    await ctx.database.upsert('sla_parse_timeline', [node]);
+    return node;
+}
+async function upsertTimelineIfChanged(ctx, config, cacheKey, result) {
+    const nodes = await getActiveTimelineNodes(ctx, config, cacheKey);
+    const latest = nodes[nodes.length - 1];
+    if (latest && isSameParsedInfo(latest.data, result)) {
+        return touchTimelineNode(ctx, latest);
+    }
+    const now = Date.now();
+    const node = {
+        node_id: createTimelineNodeId(cacheKey, now),
+        cache_key: cacheKey,
+        data: result,
+        delta: buildParsedInfoDelta(latest?.data ?? null, result),
+        created_at: now,
+        last_checked_at: now,
+    };
+    await ctx.database.upsert('sla_parse_timeline', [node]);
+    return node;
+}
+async function removeExpiredTimelineNodes(ctx, threshold) {
+    if (threshold === null)
+        return;
+    await ctx.database.remove('sla_parse_timeline', {
+        last_checked_at: { $lt: threshold }
+    });
+}
+async function pruneExpiredTimelineNodes(ctx, config) {
+    await removeExpiredTimelineNodes(ctx, getRetentionThreshold(getCombinedRetentionHours(config)));
+}
+async function getLatestTimelineNode(ctx, config, cacheKey) {
+    const nodes = await getActiveTimelineNodes(ctx, config, cacheKey);
+    return nodes[nodes.length - 1] || null;
+}
+function registerLegacyParseCacheModel(ctx) {
+    ctx.model.extend('sla_parse_cache', {
+        key: 'string',
+        data: 'json',
+        created_at: 'double',
+    }, { primary: 'key' });
+}
+async function getLegacyParseCacheEntries(ctx) {
+    try {
+        registerLegacyParseCacheModel(ctx);
+        return await ctx.database.get('sla_parse_cache', {});
+    }
+    catch {
+        return [];
+    }
+}
+async function migrateLegacyParseCache(ctx) {
+    const legacyEntries = await getLegacyParseCacheEntries(ctx);
+    let migrated = 0;
+    let skipped = 0;
+    let invalid = 0;
+    for (const entry of legacyEntries) {
+        if (!entry?.key || !entry.data || !entry.created_at) {
+            invalid++;
+            continue;
+        }
+        const nodes = await getTimelineNodes(ctx, entry.key);
+        const sameNode = nodes.find(node => isSameParsedInfo(node.data, entry.data));
+        if (sameNode) {
+            await touchTimelineNode(ctx, sameNode, Math.max(sameNode.last_checked_at || 0, entry.created_at));
+            skipped++;
+            continue;
+        }
+        const latest = nodes[nodes.length - 1];
+        const delta = latest ? buildParsedInfoDelta(latest.data, entry.data) : 'base';
+        await createTimelineNodeFromCache(ctx, entry.key, entry.data, entry.created_at, delta);
+        migrated++;
+    }
+    let mismatched = 0;
+    for (const entry of legacyEntries) {
+        if (!entry?.key || !entry.data)
+            continue;
+        const nodes = await getTimelineNodes(ctx, entry.key);
+        if (!nodes.some(node => isSameParsedInfo(node.data, entry.data))) {
+            mismatched++;
+        }
+    }
+    return {
+        legacyParse: legacyEntries.length,
+        migrated,
+        skipped,
+        invalid,
+        mismatched,
+    };
+}
+async function dropLegacyParseCache(ctx) {
+    const messages = [];
+    try {
+        registerLegacyParseCacheModel(ctx);
+        await ctx.database.remove('sla_parse_cache', {});
+        messages.push('旧 sla_parse_cache 数据已清空。');
+    }
+    catch (e) {
+        messages.push(`清空旧 sla_parse_cache 失败: ${e.message || String(e)}`);
+    }
+    const database = ctx.database;
+    const candidates = [
+        { fn: database.drop, args: ['sla_parse_cache'] },
+        { fn: database.dropTable, args: ['sla_parse_cache'] },
+        { fn: database.dropTables, args: [['sla_parse_cache']] },
+    ];
+    let dropped = false;
+    for (const candidate of candidates) {
+        if (typeof candidate.fn !== 'function')
+            continue;
+        try {
+            const result = candidate.fn.apply(database, candidate.args);
+            if (result && typeof result.then === 'function')
+                await result;
+            messages.push('旧表 sla_parse_cache 已尝试删除。');
+            dropped = true;
+            break;
+        }
+        catch {
+        }
+    }
+    if (!dropped) {
+        messages.push('当前数据库适配器未暴露删除 sla_parse_cache 的表 API，请按需手动 drop。');
+    }
+    return messages.join('\n');
+}
 function apply(ctx, config) {
     // 数据库模型定义
     ctx.model.extend('sla_cookie_cache', {
@@ -166,12 +419,6 @@ function apply(ctx, config) {
     }, {
         primary: 'guildId',
     });
-    // 解析结果缓存
-    ctx.model.extend('sla_parse_cache', {
-        key: 'string', // platform + ':' + id
-        data: 'json',
-        created_at: 'double',
-    }, { primary: 'key' });
     // 资源文件缓存 (hash)
     ctx.model.extend('sla_file_cache', {
         hash: 'string', // URL MD5
@@ -179,6 +426,15 @@ function apply(ctx, config) {
         url: 'string',
         created_at: 'double',
     }, { primary: 'hash' });
+    // 解析结果时间线
+    ctx.model.extend('sla_parse_timeline', {
+        node_id: 'string',
+        cache_key: 'string',
+        data: 'json',
+        delta: 'text',
+        created_at: 'double',
+        last_checked_at: 'double',
+    }, { primary: 'node_id' });
     const logger = ctx.logger('share-links-analysis');
     // 根据配置设置日志等级
     if (config.debug) {
@@ -189,32 +445,13 @@ function apply(ctx, config) {
     const cleanExpiredCache = async () => {
         if (!config.enableCache)
             return;
-        const now = Date.now();
-        let maxExpiration = 0;
-        if (config.optimisticCache) {
-            // 如果开启了乐观缓存，且 L1 或 L2 中有任何一个设为 0（永不过期），则直接跳过定时清理
-            if (config.cacheExpiration === 0 || config.optimisticExpiration === 0) {
-                return;
-            }
-            // 只有两者都不为 0 时，才取它们的最大值作为物理清理时间
-            maxExpiration = Math.max(config.cacheExpiration, config.optimisticExpiration);
-        }
-        else {
-            // 如果没开启乐观缓存，且 L1 设为 0（永不过期），直接跳过
-            if (config.cacheExpiration === 0) {
-                return;
-            }
-            maxExpiration = config.cacheExpiration;
-        }
-        const threshold = now - maxExpiration * 60 * 60 * 1000;
-        // 清理解析缓存
-        await ctx.database.remove('sla_parse_cache', {
-            created_at: { $lt: threshold }
-        });
+        const fileAndTimelineThreshold = getRetentionThreshold(getCombinedRetentionHours(config));
         // 清理文件缓存
-        const expiredFiles = await ctx.database.get('sla_file_cache', {
-            created_at: { $lt: threshold }
-        });
+        const expiredFiles = fileAndTimelineThreshold === null
+            ? []
+            : await ctx.database.get('sla_file_cache', {
+                created_at: { $lt: fileAndTimelineThreshold }
+            });
         for (const file of expiredFiles) {
             try {
                 if (fs.existsSync(file.path)) {
@@ -225,9 +462,12 @@ function apply(ctx, config) {
                 logger.warn(`删除过期文件失败 ${file.path}: ${e}`);
             }
         }
-        await ctx.database.remove('sla_file_cache', {
-            created_at: { $lt: threshold }
-        });
+        if (fileAndTimelineThreshold !== null) {
+            await ctx.database.remove('sla_file_cache', {
+                created_at: { $lt: fileAndTimelineThreshold }
+            });
+            await pruneExpiredTimelineNodes(ctx, config);
+        }
         if (expiredFiles.length > 0) {
             logger.info(`已自动清理 ${expiredFiles.length} 个过期文件。`);
         }
@@ -284,10 +524,27 @@ function apply(ctx, config) {
         await ctx.database.remove('sla_group_settings', { guildId: session.guildId });
         return '已重置为全局默认设置。';
     });
+    cmd.subcommand('.migratecache', '迁移旧解析缓存到新时间线并校验', { authority: 4 })
+        .action(async () => {
+        const result = await migrateLegacyParseCache(ctx);
+        const status = result.mismatched === 0 ? '校验通过' : `校验失败 ${result.mismatched} 条`;
+        return [
+            '旧解析缓存迁移完成。',
+            `旧解析缓存记录: ${result.legacyParse}`,
+            `新增节点: ${result.migrated}`,
+            `已存在/续期: ${result.skipped}`,
+            `无效记录: ${result.invalid}`,
+            status,
+        ].join('\n');
+    });
+    cmd.subcommand('.dropoldcache', '删除旧 sla_parse_cache 数据/表', { authority: 4 })
+        .action(async () => {
+        return await dropLegacyParseCache(ctx);
+    });
     // 清除缓存指令
     cmd.subcommand('.clean', '清除所有缓存和文件', { authority: 3 })
         .action(async () => {
-        await ctx.database.remove('sla_parse_cache', {});
+        await ctx.database.remove('sla_parse_timeline', {});
         const allFiles = await ctx.database.get('sla_file_cache', {});
         for (const file of allFiles) {
             try {
@@ -301,8 +558,8 @@ function apply(ctx, config) {
         await ctx.database.remove('sla_file_cache', {});
         return '缓存及对应文件已清理。';
     });
-    cmd.subcommand('.checkcache <url:string>', '查看缓存数据状态', { authority: 2 })
-        .action(async ({ session }, url) => {
+    cmd.subcommand('.checkcache <url:string> [index:string]', '查看缓存时间线/读取指定节点', { authority: 1 })
+        .action(async ({ session }, url, index) => {
         if (!session)
             return '会话不可用。';
         if (!config.enableCache)
@@ -312,23 +569,43 @@ function apply(ctx, config) {
             return '未在该链接中识别到支持的内容。';
         const link = links[0];
         const cacheKey = `${link.platform}:${link.id}`;
-        const cached = await ctx.database.get('sla_parse_cache', cacheKey);
-        if (cached.length === 0)
-            return `未找到缓存数据: ${cacheKey}`;
-        const entry = cached[0];
-        const ageMs = Date.now() - entry.created_at;
-        const isExpiredL1 = config.cacheExpiration > 0 && (ageMs > config.cacheExpiration * 60 * 60 * 1000);
-        const isExpiredL2 = config.optimisticExpiration > 0 && (ageMs > config.optimisticExpiration * 60 * 60 * 1000);
-        if (isExpiredL2)
-            return `缓存数据已完全过期: ${cacheKey}`;
-        const cacheTimeStr = new Date(entry.created_at).toLocaleString('zh-CN', { hour12: false });
-        const result = { ...entry.data };
-        if (isExpiredL1 && config.optimisticCache) {
-            result.mainbody = (result.mainbody || '') + `\n\n[📦 L2 缓存 | 缓存时间: ${cacheTimeStr}]`;
+        const nodes = await getTimelineNodes(ctx, cacheKey);
+        if (!index) {
+            if (nodes.length === 0)
+                return `未找到历史节点: ${cacheKey}`;
+            const latest = nodes[nodes.length - 1];
+            const lines = [
+                `历史节点: ${cacheKey}`,
+                summarizeParsedInfo(latest.data),
+                ''
+            ];
+            nodes.forEach((node, nodeIndex) => {
+                lines.push(`#${nodeIndex + 1} | ${formatTime(node.created_at)}`);
+                lines.push(summarizeDelta(node.delta));
+            });
+            return lines.join('\n');
+        }
+        let selectedIndex;
+        const normalizedIndex = index.trim().toLowerCase();
+        if (normalizedIndex === 'l' || normalizedIndex === 'latest') {
+            if (nodes.length === 0)
+                return `未找到历史节点: ${cacheKey}`;
+            selectedIndex = nodes.length;
         }
         else {
-            result.mainbody = (result.mainbody || '') + `\n\n[📦 L1 缓存 | 缓存时间: ${cacheTimeStr}]`;
+            selectedIndex = Number.parseInt(normalizedIndex, 10);
+            if (!Number.isInteger(selectedIndex) || `${selectedIndex}` !== normalizedIndex || selectedIndex < 1) {
+                return '节点编号必须是从 1 开始的整数，或 l/latest。';
+            }
         }
+        const node = nodes[selectedIndex - 1];
+        if (!node)
+            return `节点不存在: #${selectedIndex}`;
+        const result = { ...node.data };
+        result._cache = {
+            ...result._cache,
+            parse: `Timeline #${selectedIndex} | 节点时间: ${formatTime(node.created_at)}`
+        };
         const sendStats = { downloadTime: 0, sendTime: 0, errors: [] };
         await (0, utils_1.sendResult)(ctx, session, config, result, logger, sendStats);
         return;
@@ -348,11 +625,8 @@ function apply(ctx, config) {
             return `解析失败: ${link.platform}/${link.type}:${link.id}`;
         const cacheKey = `${link.platform}:${link.id}`;
         if (config.enableCache) {
-            await ctx.database.upsert('sla_parse_cache', [{
-                    key: cacheKey,
-                    data: result,
-                    created_at: Date.now()
-                }]);
+            await upsertTimelineIfChanged(ctx, config, cacheKey, result);
+            result._cache = { ...result._cache, parse: `强制刷新 | 缓存时间: ${formatTime(Date.now())}` };
         }
         const sendStats = { downloadTime: 0, sendTime: 0, errors: [] };
         await (0, utils_1.sendResult)(ctx, session, config, result, logger, sendStats);
@@ -568,9 +842,12 @@ function apply(ctx, config) {
             }
             // === 性能统计变量 ===
             const startTotal = Date.now();
-            const sendStats = { downloadTime: 0, sendTime: 0, errors: [] };
+            const sendStats = {
+                downloadTime: 0,
+                sendTime: 0,
+                errors: []
+            };
             let parseTime = 0;
-            let isCache = false;
             let status = "success";
             let errorMsg = "";
             let errorStack = "";
@@ -580,31 +857,25 @@ function apply(ctx, config) {
             let optimisticData = null; // 用于暂存乐观缓存数据
             let optimisticTime = 0; // 记录乐观缓存的生成时间
             try {
-                // 1. 查持久化缓存 (DB)
+                // 1. 查解析时间线的最新节点
                 if (config.enableCache) {
-                    const cached = await ctx.database.get('sla_parse_cache', cacheKey);
-                    // 检查是否存在
-                    if (cached.length > 0) {
-                        const entry = cached[0];
-                        const ageMs = Date.now() - entry.created_at;
+                    const latestNode = await getLatestTimelineNode(ctx, config, cacheKey);
+                    if (latestNode) {
+                        const checkedAt = latestNode.last_checked_at || latestNode.created_at;
+                        const ageMs = Date.now() - checkedAt;
                         // 分别判断是否超过 L1 和 乐观缓存 时效
                         const isExpiredL1 = config.cacheExpiration > 0 && (ageMs > config.cacheExpiration * 60 * 60 * 1000);
                         const isExpiredL2 = config.optimisticExpiration > 0 && (ageMs > config.optimisticExpiration * 60 * 60 * 1000);
                         if (!isExpiredL1) {
                             logger.debug(`使用 L1 缓存解析结果: ${cacheKey}`);
-                            result = { ...entry.data }; // 浅拷贝，避免修改污染原缓存对象
-                            const cacheTimeStr = new Date(entry.created_at).toLocaleString('zh-CN', { hour12: false });
-                            result.mainbody = (result.mainbody || '') + `\n\n[📦 正在使用 L1 缓存 | 缓存时间: ${cacheTimeStr}]`;
-                            isCache = true;
+                            result = { ...latestNode.data }; // 浅拷贝，避免修改污染原缓存对象
+                            const cacheTimeStr = formatTime(checkedAt);
+                            result._cache = { ...result._cache, parse: `L1 命中 | 缓存时间: ${cacheTimeStr}` };
                         }
                         else if (config.optimisticCache && !isExpiredL2) {
                             logger.debug(`L1 缓存已过期，暂存乐观缓存备用: ${cacheKey}`);
-                            optimisticData = { ...entry.data }; // 浅拷贝备用
-                            optimisticTime = entry.created_at;
-                        }
-                        else {
-                            // 彻底过期，删除
-                            await ctx.database.remove('sla_parse_cache', { key: cacheKey });
+                            optimisticData = { ...latestNode.data }; // 浅拷贝备用
+                            optimisticTime = checkedAt;
                         }
                     }
                 }
@@ -617,7 +888,6 @@ function apply(ctx, config) {
                             result = await pendingChecks.get(cacheKey) || null;
                             // 若合并任务返回的结果带有乐观缓存标记
                             if (result && result._isOptimisticFallback) {
-                                isCache = true;
                                 status = "optimistic_fallback";
                             }
                         }
@@ -632,10 +902,12 @@ function apply(ctx, config) {
                             if (optimisticData) {
                                 logger.warn(`合并任务失败，触发乐观缓存回退: ${cacheKey} | Error: ${mergeErrDetail}`);
                                 result = optimisticData;
-                                const cacheTimeStr = new Date(optimisticTime).toLocaleString('zh-CN', { hour12: false });
-                                result.mainbody = (result.mainbody || '') + `\n\n[⚠️ 并发请求异常，回退 L2 乐观缓存 | 缓存时间: ${cacheTimeStr}]`;
+                                const cacheTimeStr = formatTime(optimisticTime);
+                                result._cache = {
+                                    ...result._cache,
+                                    parse: `L2 回退: 并发请求异常 | 缓存时间: ${cacheTimeStr}`
+                                };
                                 result._isOptimisticFallback = true;
-                                isCache = true;
                                 status = "optimistic_fallback";
                             }
                             else {
@@ -653,8 +925,11 @@ function apply(ctx, config) {
                                 if (!res) {
                                     if (optimisticData) {
                                         logger.warn(`API 返回 null，触发乐观缓存回退: ${cacheKey}`);
-                                        const cacheTimeStr = new Date(optimisticTime).toLocaleString('zh-CN', { hour12: false });
-                                        optimisticData.mainbody = (optimisticData.mainbody || '') + `\n\n[⚠️ 解析数据为空，回退 L2 乐观缓存 | 缓存时间: ${cacheTimeStr}]`;
+                                        const cacheTimeStr = formatTime(optimisticTime);
+                                        optimisticData._cache = {
+                                            ...optimisticData._cache,
+                                            parse: `L2 回退: 解析数据为空 | 缓存时间: ${cacheTimeStr}`
+                                        };
                                         optimisticData._isOptimisticFallback = true;
                                         return optimisticData;
                                     }
@@ -662,11 +937,12 @@ function apply(ctx, config) {
                                 }
                                 // 解析成功且开启缓存，则写入 DB，刷新缓存时间戳
                                 if (config.enableCache) {
-                                    await ctx.database.upsert('sla_parse_cache', [{
-                                            key: cacheKey,
-                                            data: res,
-                                            created_at: Date.now()
-                                        }]);
+                                    const cacheTime = Date.now();
+                                    await upsertTimelineIfChanged(ctx, config, cacheKey, res);
+                                    res._cache = {
+                                        ...res._cache,
+                                        parse: `未命中，已刷新 | 缓存时间: ${formatTime(cacheTime)}`
+                                    };
                                 }
                                 return res;
                             }
@@ -681,8 +957,11 @@ function apply(ctx, config) {
                                 // 抛出异常（网络错误/封禁）时触发乐观回退
                                 if (optimisticData) {
                                     logger.warn(`解析抛出异常，触发乐观缓存回退: ${cacheKey} | Error: ${errDetail}`);
-                                    const cacheTimeStr = new Date(optimisticTime).toLocaleString('zh-CN', { hour12: false });
-                                    optimisticData.mainbody = (optimisticData.mainbody || '') + `\n\n[⚠️ 接口触发异常，回退 L2 乐观缓存 | 缓存时间: ${cacheTimeStr}]`;
+                                    const cacheTimeStr = formatTime(optimisticTime);
+                                    optimisticData._cache = {
+                                        ...optimisticData._cache,
+                                        parse: `L2 回退: 接口异常 | 缓存时间: ${cacheTimeStr}`
+                                    };
                                     optimisticData._isOptimisticFallback = true;
                                     return optimisticData;
                                 }
@@ -701,7 +980,6 @@ function apply(ctx, config) {
                             result = await task;
                             // 识别最终是否使用了乐观缓存回退
                             if (result && result._isOptimisticFallback) {
-                                isCache = true;
                                 status = "optimistic_fallback";
                             }
                         }
@@ -770,7 +1048,7 @@ function apply(ctx, config) {
                     raw_content_len: session.content ? session.content.length : 0, // 查明是否因长文本混排导致误触
                     // === 3. 执行状态与缓存命中 ===
                     status: status, // success, failed, error, optimistic_fallback
-                    is_cache: isCache,
+                    is_cache: (sendStats.fileCacheHits || 0) > 0,
                     // === 4. 关键排障配置状态 ===
                     // 记录当时的运行配置，排查是否是特定模式下才报错（如本地下载+混合发送）
                     cfg_using_local: config.usingLocal,

package/lib/types.d.ts

@@ -13,11 +13,16 @@ export interface ParsedInfo {
     files: FileInfo[];
     sourceUrl: string;
     stats: string;
+    _cache?: ParsedInfoCacheStatus;
 }
 export interface FileInfo {
     type: 'video' | 'audio' | 'generic';
     url: string;
 }
+export interface ParsedInfoCacheStatus {
+    parse?: string;
+    file?: string;
+}
 export interface PluginConfig {
     Video_ClarityPriority: '1' | '2';
     Max_size: number;
@@ -100,6 +105,7 @@ declare module 'koishi' {
         sla_parse_cache: SlaParseCache;
         sla_file_cache: SlaFileCache;
         sla_cookie_cache: SlaCookieCache;
+        sla_parse_timeline: SlaParseTimelineNode;
         sla_group_settings: SlaGroupSettings;
     }
 }
@@ -119,6 +125,14 @@ export interface SlaCookieCache {
     cookie: string;
     updated_at: number;
 }
+export interface SlaParseTimelineNode {
+    node_id: string;
+    cache_key: string;
+    data: ParsedInfo;
+    delta: string;
+    created_at: number;
+    last_checked_at: number;
+}
 export interface SlaGroupSettings {
     guildId: string;
     custom_parsers: Record<string, boolean>;

package/lib/utils.d.ts

@@ -44,14 +44,20 @@ export declare function sendResult(ctx: Context, session: Session, config: Plugi
     downloadTime: number;
     sendTime: number;
     errors: string[];
+    fileCacheHits?: number;
+    fileCacheMisses?: number;
 }): Promise<void>;
 export declare function sendResult_plain(ctx: Context, session: Session, config: PluginConfig, result: ParsedInfo, logger: Logger, statsRef: {
     downloadTime: number;
     sendTime: number;
     errors: string[];
+    fileCacheHits?: number;
+    fileCacheMisses?: number;
 }): Promise<void>;
 export declare function sendResult_forward(ctx: Context, session: Session, config: PluginConfig, result: ParsedInfo, logger: Logger, mixed_sending: boolean | undefined, statsRef: {
     downloadTime: number;
     sendTime: number;
     errors: string[];
+    fileCacheHits?: number;
+    fileCacheMisses?: number;
 }): Promise<void>;

package/lib/utils.js

@@ -385,7 +385,7 @@ function parseHtmlToSegments(html) {
     }
     return segments;
 }
-async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, onebotReadDir, logger, enableCache) {
+async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, onebotReadDir, logger, enableCache, statsRef) {
     await fs.promises.mkdir(localDownloadDir, { recursive: true });
     // 1. 计算 Hash
     const hash = (0, crypto_1.createHash)('md5').update(url).digest('hex');
@@ -400,6 +400,14 @@ async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, o
                 if (fs.existsSync(cachedPath)) {
                     const filename = path_1.default.basename(cachedPath);
                     const onebotPath = path_1.default.posix.join(onebotReadDir, filename);
+                    await ctx.database.upsert('sla_file_cache', [{
+                            hash,
+                            path: cachedPath,
+                            url,
+                            created_at: Date.now()
+                        }]);
+                    if (statsRef)
+                        statsRef.fileCacheHits = (statsRef.fileCacheHits || 0) + 1;
                     logger.debug(`缓存命中: ${url} -> ${cachedPath}`);
                     return `file://${onebotPath}`;
                 }
@@ -427,6 +435,8 @@ async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, o
                 url,
                 created_at: Date.now()
             }]);
+        if (statsRef)
+            statsRef.fileCacheHits = (statsRef.fileCacheHits || 0) + 1;
         return fileUrl;
     }
     const attemptDownload = () => new Promise((resolve, reject) => {
@@ -443,7 +453,7 @@ async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, o
             if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
                 req.destroy();
                 logger.debug(`重定向: ${url} -> ${res.headers.location}`);
-                resolve(downloadAndMapUrl(ctx, res.headers.location, proxy, userAgent, localDownloadDir, onebotReadDir, logger, enableCache));
+                resolve(downloadAndMapUrl(ctx, res.headers.location, proxy, userAgent, localDownloadDir, onebotReadDir, logger, enableCache, statsRef));
                 return;
             }
             if (res.statusCode !== 200) {
@@ -479,6 +489,8 @@ async function downloadAndMapUrl(ctx, url, proxy, userAgent, localDownloadDir, o
                         logger.warn(`写入文件缓存数据库失败: ${dbErr}`);
                     }
                 }
+                if (statsRef)
+                    statsRef.fileCacheMisses = (statsRef.fileCacheMisses || 0) + 1;
                 resolve(fileUrl);
             })
                 .catch((err) => {
@@ -653,6 +665,15 @@ async function isUserAdmin(session, userId) {
     }
 }
 async function sendResult(ctx, session, config, result, logger, statsRef) {
+    if (config.enableCache && config.usingLocal) {
+        const availability = await getLocalCacheAvailability(ctx, result);
+        if (availability.total > 0) {
+            result._cache = {
+                ...result._cache,
+                file: `命中 ${availability.hits}/${availability.total}`
+            };
+        }
+    }
     if (!session.channel) {
         await sendResult_plain(ctx, session, config, result, logger, statsRef);
         return;
@@ -669,6 +690,47 @@ async function sendResult(ctx, session, config, result, logger, statsRef) {
             break;
     }
 }
+function collectResultRemoteUrls(result) {
+    const urls = new Set();
+    if (result.coverUrl)
+        urls.add(result.coverUrl);
+    if (result.mainbody) {
+        for (const match of result.mainbody.matchAll(/<img\s[^>]*src\s*=\s*["']?([^"'>\s]+)["']?/gi)) {
+            urls.add(match[1]);
+        }
+    }
+    if (Array.isArray(result.files)) {
+        for (const file of result.files) {
+            if (file?.url)
+                urls.add(file.url);
+        }
+    }
+    return [...urls].filter(url => /^https?:\/\//i.test(url));
+}
+async function getLocalCacheAvailability(ctx, result) {
+    const urls = collectResultRemoteUrls(result);
+    let hits = 0;
+    for (const url of urls) {
+        const hash = (0, crypto_1.createHash)('md5').update(url).digest('hex');
+        const cached = await ctx.database.get('sla_file_cache', hash);
+        if (cached.length > 0 && cached[0].path && fs.existsSync(cached[0].path)) {
+            hits++;
+        }
+    }
+    return { total: urls.length, hits };
+}
+function buildCachePlaceholder(result, statsRef) {
+    const lines = [];
+    if (result._cache?.parse)
+        lines.push(`解析缓存: ${result._cache.parse}`);
+    if (result._cache?.file) {
+        lines.push(`文件缓存: ${result._cache.file}`);
+    }
+    else if ((statsRef.fileCacheHits || 0) > 0 || (statsRef.fileCacheMisses || 0) > 0) {
+        lines.push(`文件缓存: 命中 ${statsRef.fileCacheHits || 0} / 新下载 ${statsRef.fileCacheMisses || 0}`);
+    }
+    return lines.join('\n');
+}
 async function sendResult_plain(ctx, session, config, result, logger, statsRef) {
     logger.debug('进入普通发送');
     const localDownloadDir = config.localDownloadDir;
@@ -685,7 +747,7 @@ async function sendResult_plain(ctx, session, config, result, logger, statsRef)
         if (config.usingLocal) {
             const t = Date.now(); // 计时开始
             try {
-                mediaCoverUrl = await downloadAndMapUrl(ctx, result.coverUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                mediaCoverUrl = await downloadAndMapUrl(ctx, result.coverUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
                 logger.debug(`封面已下载: ${mediaCoverUrl}`);
             }
             catch (e) {
@@ -708,7 +770,7 @@ async function sendResult_plain(ctx, session, config, result, logger, statsRef)
             const remoteUrl = match[1];
             if (config.usingLocal) {
                 try {
-                    const localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                    const localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
                     urlMap[remoteUrl] = localUrl;
                     logger.debug(`正文图片已下载: ${localUrl}`);
                 }
@@ -736,6 +798,7 @@ async function sendResult_plain(ctx, session, config, result, logger, statsRef)
     message = message.replace(/{sourceUrl}/g, escapeHtml(result.sourceUrl || ''));
     message = message.replace(/{cover}/g, mediaCoverUrl ? koishi_1.h.image(mediaCoverUrl).toString() : '');
     message = message.replace(/{stats}/g, escapeHtml(result.stats || ''));
+    message = message.replace(/{cache}/g, escapeHtml(buildCachePlaceholder(result, statsRef)));
     // 清理空行
     const cleanMessage = message.split('\n').filter(line => line.trim() !== '' || line.includes('<')).join('\n');
     logger.debug(`解析结果: \n ${JSON.stringify(result, null, 2)}`);
@@ -783,7 +846,7 @@ async function sendResult_plain(ctx, session, config, result, logger, statsRef)
                     let localUrl = remoteUrl;
                     if (config.usingLocal) {
                         const t = Date.now();
-                        localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                        localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
                         statsRef.downloadTime += Date.now() - t;
                     }
                     if (!localUrl)
@@ -841,7 +904,7 @@ async function sendResult_forward(ctx, session, config, result, logger, mixed_se
         if (config.usingLocal) {
             const t = Date.now();
             try {
-                mediaCoverUrl = await downloadAndMapUrl(ctx, result.coverUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                mediaCoverUrl = await downloadAndMapUrl(ctx, result.coverUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
             }
             catch (e) {
                 logger.warn('封面下载失败', e);
@@ -864,7 +927,7 @@ async function sendResult_forward(ctx, session, config, result, logger, mixed_se
                 try {
                     // 去重下载
                     if (!urlMap[url]) {
-                        urlMap[url] = await downloadAndMapUrl(ctx, url, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                        urlMap[url] = await downloadAndMapUrl(ctx, url, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
                     }
                 }
                 catch (e) {
@@ -888,6 +951,7 @@ async function sendResult_forward(ctx, session, config, result, logger, mixed_se
     message = message.replace(/{authorName}/g, result.authorName || '');
     message = message.replace(/{sourceUrl}/g, result.sourceUrl || '');
     message = message.replace(/{stats}/g, result.stats || '');
+    message = message.replace(/{cache}/g, buildCachePlaceholder(result, statsRef));
     const lines = message.split('\n').filter(line => line.trim() !== '');
     const mainSegments = [];
     for (let i = 0; i < lines.length; i++) {
@@ -983,7 +1047,7 @@ async function sendResult_forward(ctx, session, config, result, logger, mixed_se
                     let localUrl = remoteUrl;
                     if (config.usingLocal) {
                         const t = Date.now();
-                        localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache);
+                        localUrl = await downloadAndMapUrl(ctx, remoteUrl, proxy, config.userAgent, localDownloadDir, onebotReadDir, logger, config.enableCache, statsRef);
                         statsRef.downloadTime += Date.now() - t;
                     }
                     if (!localUrl)

package/package.json

@@ -2,7 +2,7 @@
   "name": "koishi-plugin-share-links-analysis",
   "description": "自用插件",
   "license": "MIT",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [