koishi-plugin-chatluna-image-resolver 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Copyright (c) 2026 yabo083
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License version 3
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+Full license text:
+https://www.gnu.org/licenses/agpl-3.0.txt

package/README.md

@@ -0,0 +1,52 @@
+# koishi-plugin-chatluna-image-resolver
+
+ChatLuna 图片解析工具插件。
+
+当前主路径使用 SerpApi Google Images：把“关键词搜图、获取原图候选、下载外链、转存为 Koishi 可访问 URL”封装成一个工具，减少模型直接处理防盗链、超时外链和大 HTML 的机会。
+
+## ChatLuna 工具
+
+默认注册工具：`image_search_resolve`
+
+输入：
+
+- `query`: 图片搜索词。
+- `count`: 返回图片数量，默认 1。
+- `safeMode`: 是否启用保守过滤，默认 true。
+
+输出：
+
+- `ok`: 是否找到并转存图片。
+- `images`: 已转存图片列表，包含 `url`、`sourcePage`、`originalUrl`、`width`、`height`、`bytes`。
+- `failures`: 被跳过或失败的来源摘要。
+
+## 搜索来源
+
+默认搜索提供方：`serpapi`
+
+SerpApi 会调用 Google Images Search API（`engine=google_images`），优先读取 `images_results[].original` 作为待下载原图，并把 `images_results[].link` 作为下载 Referer。插件下载成功后仍会转存到 ChatLuna Storage 或本地 HTTP 路由，避免直接把第三方图片热链交给聊天平台。
+
+推荐配置：
+
+```yaml
+chatluna-image-resolver:
+  search:
+    provider: serpapi
+    serpApiKey: <your-serpapi-api-key>
+    serpApiGoogleDomain: google.com
+    serpApiGl: cn
+    serpApiHl: zh-cn
+    serpApiSafe: active
+  delivery:
+    publicBaseUrl: http://172.26.0.1:5140
+```
+
+如果希望 SerpApi 不足时继续尝试 Tavily/DuckDuckGo 页面解析，可将 `provider` 改为 `serpapi-fallback`。
+
+`delivery.publicBaseUrl` 用于控制最终返回给聊天平台的图片 URL 根地址。NapCat/OneBot 在 Docker 中运行时，容器内的 `127.0.0.1` 不是宿主 Koishi；此时应填写容器可访问宿主的地址，例如 Docker 网桥网关 `http://172.26.0.1:5140` 或局域网地址 `http://192.168.0.107:5140`。
+
+## 存储
+
+优先使用 `chatluna-storage-service` 的 `createTempFile()` 生成本地可访问链接。
+
+可选 WebDAV 同步会在本地转存成功后，把同一份图片用 HTTP `PUT` 上传到 WebDAV 目录，并在结果里返回 `webdavUrl`。

package/lib/index.d.ts

@@ -0,0 +1,92 @@
+import { Context, Schema } from 'koishi';
+export declare const name = "chatluna-image-resolver";
+export declare const inject: {
+    optional: readonly ["chatluna", "chatluna_storage", "puppeteer", "server"];
+};
+export interface WebDavConfig {
+    enabled: boolean;
+    endpoint: string;
+    username: string;
+    password: string;
+    basePath: string;
+    publicBaseUrl: string;
+}
+export interface Config {
+    tool: {
+        enabled: boolean;
+        name: string;
+        description: string;
+    };
+    search: {
+        provider: 'serpapi' | 'serpapi-fallback' | 'duckduckgo' | 'tavily' | 'both';
+        serpApiKey: string;
+        serpApiGoogleDomain: string;
+        serpApiGl: string;
+        serpApiHl: string;
+        serpApiSafe: 'active' | 'off';
+        tavilyApiKey: string;
+        maxSearchResults: number;
+        maxPages: number;
+        pageTimeoutMs: number;
+        usePuppeteerFallback: boolean;
+    };
+    image: {
+        maxCount: number;
+        maxDownloadBytes: number;
+        minWidth: number;
+        minHeight: number;
+        tempExpireHours: number;
+        userAgent: string;
+    };
+    storage: {
+        localFallback: boolean;
+        localDirectory: string;
+        localPublicPath: string;
+    };
+    delivery: {
+        publicBaseUrl: string;
+    };
+    webdav: WebDavConfig;
+    debug: boolean;
+}
+interface ImageCandidate {
+    url: string;
+    sourcePage: string;
+    score: number;
+    width?: number;
+    height?: number;
+    reason: string;
+}
+export declare const Config: Schema<Config>;
+export declare const usage = "\n<p><strong>ChatLuna \u56FE\u7247\u89E3\u6790\u5668</strong></p>\n<p>\u6CE8\u518C <code>image_search_resolve</code> \u5DE5\u5177\uFF0C\u7528\u4E8E\u641C\u7D22\u56FE\u7247\u3001\u63D0\u53D6\u5019\u9009\u56FE\u7247\u3001\u4E0B\u8F7D\u5916\u94FE\u3001\u8F6C\u5B58\u4E3A Koishi \u53EF\u8BBF\u95EE\u94FE\u63A5\uFF0C\u5E76\u53EF\u9009\u540C\u6B65\u5230 WebDAV\u3002</p>\n<p>\u5EFA\u8BAE\u8BA9\u89D2\u8272\u9884\u8BBE\u5728\u56FE\u7247\u8BF7\u6C42\u4E2D\u4F18\u5148\u8C03\u7528\u8BE5\u5DE5\u5177\uFF0C\u518D\u628A\u8FD4\u56DE\u7684 <code>images[].url</code> \u653E\u8FDB <code>character_reply.image</code>\u3002</p>\n";
+declare module 'koishi' {
+    interface Context {
+        chatluna?: any;
+        chatluna_storage?: {
+            createTempFile: (buffer: Buffer, filename: string, expireHours?: number, mimeType?: string) => Promise<{
+                url: string;
+            }>;
+        };
+        puppeteer?: {
+            page: () => Promise<any>;
+        };
+        server?: {
+            selfUrl?: string;
+            get: (path: string, handler: (koa: any) => Promise<void> | void) => void;
+        };
+    }
+}
+export declare function apply(ctx: Context, config: Config): void;
+export interface SerpApiImagesUrlOptions {
+    apiKey: string;
+    query: string;
+    count: number;
+    googleDomain?: string;
+    gl?: string;
+    hl?: string;
+    safe?: 'active' | 'off';
+}
+export declare function buildSerpApiImagesUrl(options: SerpApiImagesUrlOptions): string;
+export declare function serpApiImagesToCandidates(payload: any): ImageCandidate[];
+export declare function rewriteUrlBase(url: string, publicBaseUrl: string): string;
+export {};

package/lib/index.js

@@ -0,0 +1,753 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usage = exports.Config = exports.inject = exports.name = void 0;
+exports.apply = apply;
+exports.buildSerpApiImagesUrl = buildSerpApiImagesUrl;
+exports.serpApiImagesToCandidates = serpApiImagesToCandidates;
+exports.rewriteUrlBase = rewriteUrlBase;
+const koishi_1 = require("koishi");
+const tools_1 = require("@langchain/core/tools");
+const zod_1 = require("zod");
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+exports.name = 'chatluna-image-resolver';
+exports.inject = { optional: ['chatluna', 'chatluna_storage', 'puppeteer', 'server'] };
+const TOOL_SCHEMA = zod_1.z.object({
+    query: zod_1.z.string().min(1).describe('Image search query, for example "天童爱丽丝 普通图片" or "Tendou Aris fanart".'),
+    count: zod_1.z.number().int().min(1).max(8).optional().describe('Number of images to resolve. Defaults to 1.'),
+    safeMode: zod_1.z.boolean().optional().describe('Use conservative filtering for icons, logos, tiny images, and risky pages. Defaults to true.')
+});
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        tool: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().default(true).description('是否注册 ChatLuna 工具。'),
+            name: koishi_1.Schema.string().default('image_search_resolve').description('ChatLuna 工具名称。'),
+            description: koishi_1.Schema.string().role('textarea').default('Searches for images, extracts real image candidates, downloads them with browser-like headers, stores them as Koishi-accessible URLs, and returns ready-to-send image links. Use this instead of sending remote hotlink URLs directly.').description('工具描述。')
+        }).description('工具')
+    }),
+    koishi_1.Schema.object({
+        search: koishi_1.Schema.object({
+            provider: koishi_1.Schema.union([
+                koishi_1.Schema.const('serpapi').description('SerpApi Google Images，直接返回原图候选。'),
+                koishi_1.Schema.const('serpapi-fallback').description('优先 SerpApi Google Images，不足时回退到 Tavily/DuckDuckGo 网页解析。'),
+                koishi_1.Schema.const('duckduckgo').description('DuckDuckGo HTML/Lite 搜索。'),
+                koishi_1.Schema.const('tavily').description('Tavily 搜索。'),
+                koishi_1.Schema.const('both').description('先 Tavily 后 DuckDuckGo。')
+            ]).default('serpapi').description('搜索提供方。'),
+            serpApiKey: koishi_1.Schema.string().role('secret').default('').description('SerpApi API Key。provider 为 SerpApi 时必填。'),
+            serpApiGoogleDomain: koishi_1.Schema.string().default('google.com').description('SerpApi google_domain；留空则使用默认。'),
+            serpApiGl: koishi_1.Schema.string().default('cn').description('SerpApi gl 地区参数。'),
+            serpApiHl: koishi_1.Schema.string().default('zh-cn').description('SerpApi hl 语言参数。'),
+            serpApiSafe: koishi_1.Schema.union([
+                koishi_1.Schema.const('active').description('开启 Google SafeSearch。'),
+                koishi_1.Schema.const('off').description('关闭 Google SafeSearch。')
+            ]).default('active').description('SerpApi safe 参数。'),
+            tavilyApiKey: koishi_1.Schema.string().role('secret').default('').description('Tavily API Key，留空则跳过 Tavily。'),
+            maxSearchResults: koishi_1.Schema.number().min(1).max(100).default(12).description('最多读取多少条搜索结果。'),
+            maxPages: koishi_1.Schema.number().min(1).max(8).default(4).description('最多打开多少个候选页面。'),
+            pageTimeoutMs: koishi_1.Schema.number().min(3000).max(60000).default(12000).description('页面抓取/下载超时。'),
+            usePuppeteerFallback: koishi_1.Schema.boolean().default(true).description('普通 HTML 抓不到图片时，是否用 Puppeteer 读取 DOM 图片。')
+        }).description('搜索')
+    }),
+    koishi_1.Schema.object({
+        image: koishi_1.Schema.object({
+            maxCount: koishi_1.Schema.number().min(1).max(8).default(4).description('单次最多返回图片数。'),
+            maxDownloadBytes: koishi_1.Schema.number().min(100000).max(20000000).default(8000000).description('单张图片最大下载字节数。'),
+            minWidth: koishi_1.Schema.number().min(1).max(4000).default(220).description('候选图片最小宽度。'),
+            minHeight: koishi_1.Schema.number().min(1).max(4000).default(220).description('候选图片最小高度。'),
+            tempExpireHours: koishi_1.Schema.number().min(1).max(24 * 365).default(24 * 30).description('转存到 ChatLuna Storage 的过期小时数。'),
+            userAgent: koishi_1.Schema.string().default('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36').description('下载图片时使用的 User-Agent。')
+        }).description('图片')
+    }),
+    koishi_1.Schema.object({
+        storage: koishi_1.Schema.object({
+            localFallback: koishi_1.Schema.boolean().default(true).description('没有 chatluna-storage-service 时，是否使用插件本地目录和 HTTP 路由兜底。'),
+            localDirectory: koishi_1.Schema.string().default('data/chatluna-image-resolver').description('本地兜底目录，相对 Koishi baseDir。'),
+            localPublicPath: koishi_1.Schema.string().default('/chatluna-image-resolver').description('本地兜底 HTTP 路径。')
+        }).description('本地转存')
+    }),
+    koishi_1.Schema.object({
+        delivery: koishi_1.Schema.object({
+            publicBaseUrl: koishi_1.Schema.string().default('').description('返回给聊天平台拉取图片的公开根地址；用于 NapCat/OneBot Docker 等无法访问 127.0.0.1 的场景，例如 http://172.26.0.1:5140。留空则保留存储服务原 URL。')
+        }).description('发送链接')
+    }),
+    koishi_1.Schema.object({
+        webdav: koishi_1.Schema.object({
+            enabled: koishi_1.Schema.boolean().default(false).description('是否同步到 WebDAV。'),
+            endpoint: koishi_1.Schema.string().default('').description('WebDAV 根地址，例如 https://example.com/dav。'),
+            username: koishi_1.Schema.string().default('').description('WebDAV 用户名。'),
+            password: koishi_1.Schema.string().role('secret').default('').description('WebDAV 密码。'),
+            basePath: koishi_1.Schema.string().default('chatluna-images').description('WebDAV 目录。'),
+            publicBaseUrl: koishi_1.Schema.string().default('').description('公开访问根地址；留空则只同步，不返回公开 URL。')
+        }).description('WebDAV 同步'),
+        debug: koishi_1.Schema.boolean().default(false).description('输出调试日志。')
+    })
+]);
+exports.usage = `
+<p><strong>ChatLuna 图片解析器</strong></p>
+<p>注册 <code>image_search_resolve</code> 工具，用于搜索图片、提取候选图片、下载外链、转存为 Koishi 可访问链接，并可选同步到 WebDAV。</p>
+<p>建议让角色预设在图片请求中优先调用该工具，再把返回的 <code>images[].url</code> 放进 <code>character_reply.image</code>。</p>
+`;
+class ImageResolverTool extends tools_1.StructuredTool {
+    ctx;
+    config;
+    name;
+    description;
+    schema = TOOL_SCHEMA;
+    constructor(ctx, config) {
+        super({});
+        this.ctx = ctx;
+        this.config = config;
+        this.name = config.tool.name.trim() || 'image_search_resolve';
+        this.description = config.tool.description.trim();
+    }
+    async _call(input) {
+        const count = clamp(input.count ?? 1, 1, this.config.image.maxCount);
+        const safeMode = input.safeMode ?? true;
+        const resolver = new ImageResolver(this.ctx, this.config);
+        const result = await resolver.resolve(input.query, count, safeMode);
+        return JSON.stringify(result, null, 2);
+    }
+}
+class ImageResolver {
+    ctx;
+    config;
+    constructor(ctx, config) {
+        this.ctx = ctx;
+        this.config = config;
+    }
+    async resolve(query, count, safeMode) {
+        const failures = [];
+        const candidates = [];
+        const seenPages = new Set();
+        const directCandidates = await this.searchDirectImages(query, count, failures);
+        candidates.push(...directCandidates.map((candidate) => scoreCandidate(candidate, this.config, safeMode)));
+        if (this.config.search.provider !== 'serpapi' && candidates.length < count * 2) {
+            const searchResults = await this.search(query, failures);
+            for (const result of searchResults.slice(0, this.config.search.maxPages)) {
+                if (seenPages.has(result.url))
+                    continue;
+                seenPages.add(result.url);
+                if (looksLikeImageUrl(result.url)) {
+                    candidates.push(scoreCandidate({ url: result.url, sourcePage: result.url, score: 0, reason: 'search-result-url' }, this.config, safeMode));
+                    continue;
+                }
+                const pageCandidates = await this.extractFromPage(result.url, failures);
+                candidates.push(...pageCandidates.map((candidate) => scoreCandidate(candidate, this.config, safeMode)));
+                if (candidates.length >= count * 4)
+                    break;
+            }
+        }
+        const ranked = uniqueBy(candidates, (item) => normalizeImageUrl(item.url))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score);
+        const images = [];
+        for (const candidate of ranked) {
+            if (images.length >= count)
+                break;
+            try {
+                const downloaded = await this.download(candidate);
+                if (!downloaded)
+                    continue;
+                const stored = await this.store(downloaded.buffer, downloaded.filename, downloaded.mime);
+                const webdavUrl = await this.syncWebDav(downloaded.buffer, downloaded.filename, downloaded.mime, failures);
+                images.push({
+                    url: stored,
+                    webdavUrl,
+                    originalUrl: candidate.url,
+                    sourcePage: candidate.sourcePage,
+                    width: candidate.width,
+                    height: candidate.height,
+                    bytes: downloaded.buffer.length,
+                    mime: downloaded.mime
+                });
+            }
+            catch (error) {
+                failures.push(`download/store failed: ${candidate.url} (${formatError(error)})`);
+            }
+        }
+        return {
+            ok: images.length > 0,
+            query,
+            images,
+            searchedPages: uniqueBy([
+                ...directCandidates.map((candidate) => candidate.sourcePage),
+                ...Array.from(seenPages)
+            ], (item) => item),
+            candidateCount: ranked.length,
+            failures: failures.slice(-12),
+            hint: images.length > 0
+                ? 'Use images[].url in character_reply.image. These URLs are already re-hosted by Koishi storage/local fallback.'
+                : 'No sendable image was resolved. Reply with the failure summary instead of inventing an image.'
+        };
+    }
+    async search(query, failures) {
+        const results = [];
+        const provider = this.config.search.provider;
+        if ((provider === 'tavily' || provider === 'both' || provider === 'serpapi-fallback') && this.config.search.tavilyApiKey.trim()) {
+            results.push(...await this.searchTavily(query, failures));
+        }
+        if (provider === 'duckduckgo' || provider === 'both' || provider === 'serpapi-fallback' || results.length === 0) {
+            results.push(...await this.searchDuckDuckGo(query, failures));
+        }
+        return uniqueBy(results, (item) => item.url).slice(0, this.config.search.maxSearchResults);
+    }
+    async searchDirectImages(query, count, failures) {
+        const provider = this.config.search.provider;
+        if (provider !== 'serpapi' && provider !== 'serpapi-fallback')
+            return [];
+        if (!this.config.search.serpApiKey.trim()) {
+            failures.push('serpapi failed: missing API key');
+            return [];
+        }
+        return this.searchSerpApiImages(query, Math.max(count * 4, this.config.search.maxSearchResults), failures);
+    }
+    async searchSerpApiImages(query, count, failures) {
+        try {
+            const url = buildSerpApiImagesUrl({
+                apiKey: this.config.search.serpApiKey,
+                query,
+                count: clamp(count, 1, this.config.search.maxSearchResults),
+                googleDomain: this.config.search.serpApiGoogleDomain,
+                gl: this.config.search.serpApiGl,
+                hl: this.config.search.serpApiHl,
+                safe: this.config.search.serpApiSafe
+            });
+            const response = await fetchWithTimeout(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'User-Agent': this.config.image.userAgent
+                }
+            }, this.config.search.pageTimeoutMs);
+            const payload = await response.json();
+            if (!response.ok)
+                throw new Error(payload?.error || `HTTP ${response.status}`);
+            if (payload?.error)
+                throw new Error(String(payload.error));
+            return serpApiImagesToCandidates(payload).slice(0, count);
+        }
+        catch (error) {
+            failures.push(`serpapi failed: ${formatError(error)}`);
+            return [];
+        }
+    }
+    async searchTavily(query, failures) {
+        try {
+            const response = await fetchWithTimeout('https://api.tavily.com/search', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    api_key: this.config.search.tavilyApiKey,
+                    query: `${query} image wallpaper fanart`,
+                    search_depth: 'basic',
+                    max_results: this.config.search.maxSearchResults
+                })
+            }, this.config.search.pageTimeoutMs);
+            const payload = await response.json();
+            return (payload.results ?? []).map((item) => ({
+                title: String(item.title ?? ''),
+                url: String(item.url ?? ''),
+                snippet: String(item.content ?? '')
+            })).filter((item) => item.url.startsWith('http'));
+        }
+        catch (error) {
+            failures.push(`tavily failed: ${formatError(error)}`);
+            return [];
+        }
+    }
+    async searchDuckDuckGo(query, failures) {
+        const url = `https://duckduckgo.com/html/?q=${encodeURIComponent(`${query} 图片 壁纸 fanart`)}`;
+        try {
+            const response = await fetchWithTimeout(url, {
+                headers: {
+                    'User-Agent': this.config.image.userAgent,
+                    'Accept': 'text/html,application/xhtml+xml'
+                }
+            }, this.config.search.pageTimeoutMs);
+            const html = await response.text();
+            const results = [];
+            const linkPattern = /<a[^>]+class="[^"]*result__a[^"]*"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+            let match;
+            while ((match = linkPattern.exec(html)) && results.length < this.config.search.maxSearchResults) {
+                const decoded = decodeHtml(match[1]);
+                const resultUrl = decodeDuckUrl(decoded);
+                if (!resultUrl?.startsWith('http'))
+                    continue;
+                results.push({ title: stripTags(match[2]), url: resultUrl });
+            }
+            return results;
+        }
+        catch (error) {
+            failures.push(`duckduckgo failed: ${formatError(error)}`);
+            return [];
+        }
+    }
+    async extractFromPage(url, failures) {
+        try {
+            const response = await fetchWithTimeout(url, {
+                headers: {
+                    'User-Agent': this.config.image.userAgent,
+                    'Accept': 'text/html,application/xhtml+xml',
+                    'Referer': new URL(url).origin
+                }
+            }, this.config.search.pageTimeoutMs);
+            const contentType = response.headers.get('content-type') ?? '';
+            if (contentType.startsWith('image/')) {
+                return [{ url, sourcePage: url, score: 0, reason: 'page-is-image' }];
+            }
+            const html = await response.text();
+            const candidates = extractImageCandidates(html, url);
+            if (candidates.length || !this.config.search.usePuppeteerFallback || !this.ctx.puppeteer) {
+                return candidates;
+            }
+        }
+        catch (error) {
+            failures.push(`html extract failed: ${url} (${formatError(error)})`);
+        }
+        if (!this.config.search.usePuppeteerFallback || !this.ctx.puppeteer)
+            return [];
+        return this.extractWithPuppeteer(url, failures);
+    }
+    async extractWithPuppeteer(url, failures) {
+        let page;
+        try {
+            page = await this.ctx.puppeteer.page();
+            await page.setUserAgent?.(this.config.image.userAgent);
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: this.config.search.pageTimeoutMs });
+            await page.evaluate(() => window.scrollTo(0, Math.min(document.body.scrollHeight, 2400)));
+            await page.waitForTimeout?.(800);
+            const raw = await page.evaluate(() => {
+                const out = [];
+                document.querySelectorAll('img, source').forEach((node) => {
+                    out.push({
+                        src: node.currentSrc || node.src || node.getAttribute('src') || node.getAttribute('data-src') || node.getAttribute('data-original'),
+                        srcset: node.getAttribute('srcset'),
+                        width: node.naturalWidth || node.width,
+                        height: node.naturalHeight || node.height
+                    });
+                });
+                return out;
+            });
+            return raw.flatMap((item) => candidatesFromRawImage(item, url));
+        }
+        catch (error) {
+            failures.push(`puppeteer extract failed: ${url} (${formatError(error)})`);
+            return [];
+        }
+        finally {
+            await page?.close?.().catch(() => undefined);
+        }
+    }
+    async download(candidate) {
+        const headers = {
+            'User-Agent': this.config.image.userAgent,
+            'Accept': 'image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8',
+            'Referer': candidate.sourcePage
+        };
+        const response = await fetchWithTimeout(candidate.url, { headers }, this.config.search.pageTimeoutMs);
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const mime = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (!mime.startsWith('image/'))
+            throw new Error(`not image: ${mime || 'unknown content-type'}`);
+        const length = Number(response.headers.get('content-length') ?? '0');
+        if (length > this.config.image.maxDownloadBytes)
+            throw new Error(`image too large: ${length}`);
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        if (buffer.length > this.config.image.maxDownloadBytes)
+            throw new Error(`image too large: ${buffer.length}`);
+        const ext = mimeToExt(mime) || extFromUrl(candidate.url) || '.jpg';
+        const hash = (0, node_crypto_1.createHash)('sha1').update(buffer).digest('hex').slice(0, 12);
+        return { buffer, mime, filename: `resolved-${hash}${ext}` };
+    }
+    async store(buffer, filename, mime) {
+        if (this.ctx.chatluna_storage?.createTempFile) {
+            const stored = await this.ctx.chatluna_storage.createTempFile(buffer, filename, this.config.image.tempExpireHours, mime);
+            return rewriteUrlBase(stored.url, this.config.delivery.publicBaseUrl);
+        }
+        if (!this.config.storage.localFallback) {
+            throw new Error('chatluna-storage-service is not available and local fallback is disabled');
+        }
+        const dir = (0, node_path_1.join)(this.ctx.baseDir, this.config.storage.localDirectory);
+        await (0, promises_1.mkdir)(dir, { recursive: true });
+        await (0, promises_1.writeFile)((0, node_path_1.join)(dir, filename), buffer);
+        const base = trimTrailingSlash(this.ctx.server?.selfUrl ?? '');
+        return rewriteUrlBase(`${base}${this.config.storage.localPublicPath}/${filename}`, this.config.delivery.publicBaseUrl);
+    }
+    async syncWebDav(buffer, filename, mime, failures) {
+        const cfg = this.config.webdav;
+        if (!cfg.enabled || !cfg.endpoint.trim())
+            return undefined;
+        try {
+            const basePath = trimSlashes(cfg.basePath);
+            const uploadUrl = `${trimTrailingSlash(cfg.endpoint)}/${basePath ? `${basePath}/` : ''}${encodeURIComponent(filename)}`;
+            await ensureWebDavCollections(cfg, basePath, this.config.search.pageTimeoutMs);
+            const response = await fetchWithTimeout(uploadUrl, {
+                method: 'PUT',
+                headers: {
+                    'Authorization': basicAuth(cfg.username, cfg.password),
+                    'Content-Type': mime,
+                    'Content-Length': String(buffer.length)
+                },
+                body: buffer
+            }, this.config.search.pageTimeoutMs);
+            if (!response.ok && response.status !== 201 && response.status !== 204) {
+                throw new Error(`WebDAV PUT HTTP ${response.status}`);
+            }
+            if (!cfg.publicBaseUrl.trim())
+                return undefined;
+            return `${trimTrailingSlash(cfg.publicBaseUrl)}/${basePath ? `${basePath}/` : ''}${encodeURIComponent(filename)}`;
+        }
+        catch (error) {
+            failures.push(`webdav sync failed: ${formatError(error)}`);
+            return undefined;
+        }
+    }
+}
+function apply(ctx, config) {
+    if (config.storage.localFallback) {
+        ctx.inject(['server'], (ctx2) => {
+            if (!ctx2.server)
+                return;
+            ctx2.server.get(`${config.storage.localPublicPath}/:name`, async (koa) => {
+                const filename = String(koa.params.name ?? '');
+                if (!/^[a-zA-Z0-9._-]+$/.test(filename)) {
+                    koa.status = 400;
+                    return;
+                }
+                try {
+                    const file = await (0, promises_1.readFile)((0, node_path_1.join)(ctx.baseDir, config.storage.localDirectory, filename));
+                    koa.set('Content-Type', mimeFromFilename(filename));
+                    koa.body = file;
+                }
+                catch {
+                    koa.status = 404;
+                }
+            });
+        });
+    }
+    const registerTool = (ctx2) => {
+        if (!config.tool.enabled)
+            return;
+        if (!ctx2.chatluna?.platform?.registerTool) {
+            ctx2.logger(exports.name).warn('ChatLuna platform is unavailable; skip registering image resolver tool.');
+            return;
+        }
+        const toolName = config.tool.name.trim() || 'image_search_resolve';
+        ctx2.effect(() => ctx2.chatluna.platform.registerTool(toolName, {
+            description: config.tool.description,
+            selector() {
+                return true;
+            },
+            createTool() {
+                return new ImageResolverTool(ctx2, config);
+            },
+            meta: {
+                source: 'extension',
+                group: 'image-resolver',
+                tags: ['image-resolver', 'image-search', 'webdav'],
+                defaultAvailability: {
+                    enabled: true,
+                    main: true,
+                    chatluna: true,
+                    characterScope: 'all'
+                }
+            }
+        }));
+        ctx2.logger(exports.name).info('registered ChatLuna tool: %s', toolName);
+    };
+    ctx.inject(['chatluna'], registerTool);
+    ctx.command('image-resolver <query:text>', '搜索并转存图片为 Koishi 可访问链接')
+        .option('count', '-c <count:number> 返回图片数量')
+        .action(async ({ session, options }, query) => {
+        if (!query?.trim())
+            return '请输入搜索词。';
+        const count = clamp(Number(options?.count ?? 1) || 1, 1, config.image.maxCount);
+        const resolver = new ImageResolver(ctx, config);
+        const result = await resolver.resolve(query, count, true);
+        if (!result.ok) {
+            return `没有解析到可发送图片：${result.failures.slice(-3).join('；') || '无可用候选'}`;
+        }
+        if (!session) {
+            return result.images.map((image) => image.url).join('\n');
+        }
+        for (const image of result.images) {
+            await session.send(koishi_1.h.image(image.url));
+        }
+        return `已转存 ${result.images.length} 张图片。`;
+    });
+}
+function extractImageCandidates(html, pageUrl) {
+    const candidates = [];
+    const metaPattern = /<meta[^>]+(?:property|name)=["'](?:og:image|twitter:image|og:image:secure_url)["'][^>]+content=["']([^"']+)["'][^>]*>/gi;
+    let match;
+    while ((match = metaPattern.exec(html))) {
+        pushCandidate(candidates, match[1], pageUrl, 'meta-image');
+    }
+    const imgPattern = /<(?:img|source)\b([^>]+)>/gi;
+    while ((match = imgPattern.exec(html))) {
+        const attrs = parseAttributes(match[1]);
+        candidates.push(...candidatesFromRawImage({
+            src: attrs.currentSrc || attrs.src || attrs['data-src'] || attrs['data-original'] || attrs['data-lazy-src'],
+            srcset: attrs.srcset || attrs['data-srcset'],
+            width: Number(attrs.width || 0),
+            height: Number(attrs.height || 0)
+        }, pageUrl));
+    }
+    const bgPattern = /url\((["']?)([^"')]+)\1\)/gi;
+    while ((match = bgPattern.exec(html))) {
+        pushCandidate(candidates, match[2], pageUrl, 'css-url');
+    }
+    return uniqueBy(candidates, (item) => normalizeImageUrl(item.url));
+}
+function candidatesFromRawImage(raw, pageUrl) {
+    const out = [];
+    if (raw?.src)
+        pushCandidate(out, raw.src, pageUrl, 'img-src', raw.width, raw.height);
+    if (raw?.srcset) {
+        for (const item of parseSrcset(String(raw.srcset))) {
+            pushCandidate(out, item.url, pageUrl, `srcset-${item.descriptor}`, raw.width, raw.height);
+        }
+    }
+    return out;
+}
+function pushCandidate(out, value, pageUrl, reason, width, height) {
+    const url = absolutizeUrl(decodeHtml(value.trim()), pageUrl);
+    if (!url || !url.startsWith('http'))
+        return;
+    out.push({ url, sourcePage: pageUrl, score: 0, width, height, reason });
+}
+function buildSerpApiImagesUrl(options) {
+    const url = new URL('https://serpapi.com/search.json');
+    url.searchParams.set('engine', 'google_images');
+    url.searchParams.set('api_key', options.apiKey);
+    url.searchParams.set('q', options.query);
+    url.searchParams.set('num', String(clamp(Math.floor(options.count), 1, 100)));
+    if (options.googleDomain?.trim())
+        url.searchParams.set('google_domain', options.googleDomain.trim());
+    if (options.gl?.trim())
+        url.searchParams.set('gl', options.gl.trim());
+    if (options.hl?.trim())
+        url.searchParams.set('hl', options.hl.trim());
+    if (options.safe)
+        url.searchParams.set('safe', options.safe);
+    return url.href;
+}
+function serpApiImagesToCandidates(payload) {
+    const results = Array.isArray(payload?.images_results) ? payload.images_results : [];
+    const candidates = [];
+    for (const item of results) {
+        const sourcePage = bestSourcePage(item);
+        const width = numberOrUndefined(item?.original_width ?? item?.width);
+        const height = numberOrUndefined(item?.original_height ?? item?.height);
+        if (typeof item?.original === 'string') {
+            pushCandidate(candidates, item.original, sourcePage, 'serpapi-original', width, height);
+            continue;
+        }
+        if (typeof item?.thumbnail === 'string') {
+            pushCandidate(candidates, item.thumbnail, sourcePage, 'serpapi-thumbnail', width, height);
+        }
+    }
+    return uniqueBy(candidates, (item) => normalizeImageUrl(item.url));
+}
+function bestSourcePage(item) {
+    for (const value of [item?.link, item?.source, item?.original]) {
+        if (typeof value === 'string' && /^https?:\/\//i.test(value))
+            return value;
+    }
+    return 'https://serpapi.com/';
+}
+function numberOrUndefined(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? number : undefined;
+}
+function scoreCandidate(candidate, config, safeMode) {
+    const url = normalizeImageUrl(candidate.url);
+    let score = 20;
+    if (/^https:/.test(url))
+        score += 5;
+    if (looksLikeImageUrl(url))
+        score += 20;
+    if (candidate.reason === 'serpapi-original')
+        score += 35;
+    if (candidate.reason === 'serpapi-thumbnail')
+        score -= 18;
+    if (candidate.reason.startsWith('meta'))
+        score += 10;
+    if (candidate.reason.startsWith('srcset'))
+        score += 8;
+    if (candidate.width && candidate.width >= config.image.minWidth)
+        score += 8;
+    if (candidate.height && candidate.height >= config.image.minHeight)
+        score += 8;
+    if (candidate.width && candidate.height) {
+        const pixels = candidate.width * candidate.height;
+        if (pixels > 1_000_000)
+            score += 14;
+        else if (pixels > 300_000)
+            score += 8;
+    }
+    if (/\b(logo|icon|avatar|face|emoji|sprite|placeholder|blank|loading)\b/i.test(url))
+        score -= 35;
+    if (/\.(svg)(?:[?#].*)?$/i.test(url))
+        score -= safeMode ? 40 : 12;
+    if (/\bthumb|thumbnail|small|_s\b/i.test(url))
+        score -= 8;
+    if (candidate.width && candidate.width < config.image.minWidth)
+        score -= 20;
+    if (candidate.height && candidate.height < config.image.minHeight)
+        score -= 20;
+    return { ...candidate, url, score };
+}
+function parseSrcset(srcset) {
+    return srcset.split(',').map((part) => {
+        const [url, descriptor = ''] = part.trim().split(/\s+/, 2);
+        return { url, descriptor };
+    }).filter((item) => item.url);
+}
+function parseAttributes(raw) {
+    const attrs = {};
+    const pattern = /([:\w-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+    let match;
+    while ((match = pattern.exec(raw))) {
+        attrs[match[1]] = decodeHtml(match[2] ?? match[3] ?? match[4] ?? '');
+    }
+    return attrs;
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function ensureWebDavCollections(cfg, basePath, timeoutMs) {
+    if (!basePath)
+        return;
+    let current = trimTrailingSlash(cfg.endpoint);
+    for (const segment of basePath.split('/').filter(Boolean)) {
+        current = `${current}/${encodeURIComponent(segment)}`;
+        await fetchWithTimeout(current, {
+            method: 'MKCOL',
+            headers: { 'Authorization': basicAuth(cfg.username, cfg.password) }
+        }, timeoutMs).catch(() => undefined);
+    }
+}
+function decodeDuckUrl(url) {
+    try {
+        const parsed = new URL(url, 'https://duckduckgo.com');
+        const uddg = parsed.searchParams.get('uddg');
+        return uddg ? decodeURIComponent(uddg) : parsed.href;
+    }
+    catch {
+        return url;
+    }
+}
+function absolutizeUrl(raw, base) {
+    if (!raw || raw.startsWith('data:') || raw.startsWith('blob:'))
+        return '';
+    if (raw.startsWith('//'))
+        return `https:${raw}`;
+    try {
+        return new URL(raw, base).href;
+    }
+    catch {
+        return '';
+    }
+}
+function normalizeImageUrl(url) {
+    return url.replace(/&amp;/g, '&');
+}
+function rewriteUrlBase(url, publicBaseUrl) {
+    const base = trimTrailingSlash(publicBaseUrl.trim());
+    if (!base)
+        return url;
+    try {
+        const parsed = new URL(url);
+        return `${base}${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+    catch {
+        const path = url.startsWith('/') ? url : `/${url}`;
+        return `${base}${path}`;
+    }
+}
+function looksLikeImageUrl(url) {
+    return /\.(?:jpe?g|png|webp|gif|avif)(?:[?#].*)?$/i.test(url);
+}
+function extFromUrl(url) {
+    try {
+        const ext = (0, node_path_1.extname)(new URL(url).pathname).toLowerCase();
+        return ['.jpg', '.jpeg', '.png', '.webp', '.gif', '.avif'].includes(ext) ? ext : '';
+    }
+    catch {
+        return '';
+    }
+}
+function mimeToExt(mime) {
+    if (mime.includes('jpeg'))
+        return '.jpg';
+    if (mime.includes('png'))
+        return '.png';
+    if (mime.includes('webp'))
+        return '.webp';
+    if (mime.includes('gif'))
+        return '.gif';
+    if (mime.includes('avif'))
+        return '.avif';
+    return '';
+}
+function mimeFromFilename(filename) {
+    const ext = (0, node_path_1.extname)(filename).toLowerCase();
+    if (ext === '.png')
+        return 'image/png';
+    if (ext === '.webp')
+        return 'image/webp';
+    if (ext === '.gif')
+        return 'image/gif';
+    if (ext === '.avif')
+        return 'image/avif';
+    return 'image/jpeg';
+}
+function stripTags(value) {
+    return decodeHtml(value.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim());
+}
+function decodeHtml(value) {
+    return value
+        .replace(/&amp;/g, '&')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>');
+}
+function basicAuth(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, '');
+}
+function uniqueBy(items, getKey) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const key = getKey(item);
+        if (!key || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(item);
+    }
+    return out;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "koishi-plugin-chatluna-image-resolver",
+  "version": "0.1.0",
+  "description": "ChatLuna image search resolver that extracts, downloads, stores, and optionally syncs images to WebDAV.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yabo083/koishi-plugin-chatluna-image-resolver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yabo083/koishi-plugin-chatluna-image-resolver/issues"
+  },
+  "homepage": "https://github.com/yabo083/koishi-plugin-chatluna-image-resolver#readme",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "koishi",
+    "koishi-plugin",
+    "chatluna",
+    "image",
+    "resolver",
+    "webdav"
+  ],
+  "author": "yabo",
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/*.test.cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "koishi": "^4.18.0",
+    "koishi-plugin-chatluna-character": "*"
+  },
+  "peerDependenciesMeta": {
+    "koishi-plugin-chatluna-character": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "typescript": "^5.6.2"
+  },
+  "koishi": {
+    "description": {
+      "zh": "ChatLuna 图片解析器：搜索图片、提取候选、下载转存为 Koishi 本地链接，并可同步到 WebDAV。"
+    },
+    "service": {
+      "optional": [
+        "chatluna",
+        "chatluna_storage",
+        "puppeteer"
+      ]
+    }
+  }
+}