@nestim/koishi-plugin-qq-group-manager 0.1.5 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miseat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.js

@@ -23,7 +23,8 @@ exports.Config = koishi_1.Schema.intersect([
         dryRun: koishi_1.Schema.boolean().default(false).description('演练模式：仅输出计划动作，不执行群管理操作。'),
     }).description('基础设置'),
     koishi_1.Schema.object({
-        bannedWords: koishi_1.Schema.array(String).role('table').default([]).description('违禁词列表（命中任意词即视为违规）。'),
+        bannedWords: koishi_1.Schema.array(String).role('table').default([]).description('违禁词列表。支持顺序模糊匹配（如“领红包”可命中“领xxx元红包”）。可用“关键词|分值”自定义权重，分值越高越容易单独触发。'),
+        bannedWordScoreThreshold: koishi_1.Schema.natural().min(1).max(100).default(70).description('违禁词评分触发阈值：整条消息累计得分达到该值才触发管控（默认 70）。'),
         blockCardMessage: koishi_1.Schema.boolean().default(true).description('是否禁止卡片消息（json/xml）。'),
         blockForwardMessage: koishi_1.Schema.boolean().default(true).description('是否禁止合并转发消息（forward）。'),
         autoDeleteViolation: koishi_1.Schema.boolean().default(true).description('违规消息是否自动撤回。'),
@@ -31,7 +32,7 @@ exports.Config = koishi_1.Schema.intersect([
         groupRules: koishi_1.Schema.array(koishi_1.Schema.object({
             guildId: koishi_1.Schema.string().required().description('群号。'),
             enableAiReply: koishi_1.Schema.boolean().description('该群是否启用 AI 回复（留空则跟随全局设置）。'),
-            bannedWords: koishi_1.Schema.array(String).role('table').default([]).description('该群专属违禁词列表。'),
+            bannedWords: koishi_1.Schema.array(String).role('table').default([]).description('该群专属违禁词列表（同样支持“关键词|分值”与顺序模糊匹配）。'),
             blockCardMessage: koishi_1.Schema.boolean().default(true).description('该群是否禁止卡片消息（json/xml）。'),
             blockForwardMessage: koishi_1.Schema.boolean().default(true).description('该群是否禁止合并转发消息（forward）。'),
             autoDeleteViolation: koishi_1.Schema.boolean().default(true).description('该群违规消息是否自动撤回。'),

package/lib/service.js

@@ -29,6 +29,7 @@ class QQGroupManagerService extends koishi_1.Service {
     pendingJoinRequests = new Map();
     pendingJoinRequestFlags = new Map();
     violationRecords = new Map();
+    _imageDataUrlCache = new Map();
     constructor(ctx, config) {
         super(ctx, 'nestimQqGroupManager', true);
         this.ctx = ctx;
@@ -181,7 +182,11 @@ class QQGroupManagerService extends koishi_1.Service {
     }
     getMessageText(session) {
         const raw = session?.content ?? '';
-        return raw.replace(/\[CQ:[^\]]+\]/g, ' ').trim();
+        return raw
+            .replace(/\[CQ:[^\]]+\]/g, ' ')
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
     }
     aiGroupKey(session) {
         if (!session?.guildId)
@@ -582,20 +587,28 @@ class QQGroupManagerService extends koishi_1.Service {
             return { reply, score, reason: 'parse-fallback' };
         }
     }
-    buildInterestContextPrompt(groupKey, currentText, window = 8) {
+    buildInterestContextPrompt(groupKey, currentText, window = 8, extras = {}) {
         const size = Math.max(4, Math.min(16, window));
         const records = (this.aiBuffers.get(groupKey) ?? []).slice(-size);
         const lines = records.map((item, idx) => {
-            const imageHint = item.imageUrls.length ? ` [图片:${item.imageUrls.length}张]` : '';
+            const imageHint = item.imageUrls?.length ? ` [图片:${item.imageUrls.length}张]` : '';
             const content = item.text?.trim() || '[图片消息]';
             return `${idx + 1}. ${item.name}(${item.userId}): ${content}${imageHint}`;
         });
         const topicHint = (this.aiTopicMemory.get(groupKey)?.text || '').replace(/\s+/g, ' ').trim().slice(0, 120);
+        const currentHint = extras.hasSticker
+            ? '（当前消息是表情包/贴纸，没有文字。表情包是常见的互动方式，可以顺势接梗或回应其情绪，不要因为"没有文字"就直接判定为无价值。）'
+            : (extras.hasImage
+                ? '（当前消息含图片，没有文字。图片内容是重要的可回应素材，可以描述或调侃画面内容。）'
+                : '');
         const prompt = [
             `当前消息：${currentText || '[空文本]'}`,
+            currentHint,
             topicHint ? `当前群话题参考：${topicHint}` : '',
             `最近上下文（最多${size}条）：`,
             ...(lines.length ? lines : ['(无历史上下文)']),
+            '判定要点：表情包/图片本身就是群聊中正常的互动内容，尤其是当对方在回应你刚才的发言时，应当积极接话。',
+            '只有在明显与你无关、且属于无意义刷屏时才选择不回复。不要仅因为「没有文字」就压低评分。',
         ].filter(Boolean).join('\n');
         return { prompt, ctxSize: lines.length, topicHint };
     }
@@ -619,7 +632,9 @@ class QQGroupManagerService extends koishi_1.Service {
                 body: JSON.stringify({
                     model,
                     temperature: 0.15,
-                    max_tokens: 48,
+                    // deepseek-flash 等带思考的模型会先消耗 reasoning tokens，
+                    // 额度太小会导致 content 为空（finish_reason=length），判定直接失效
+                    max_tokens: 512,
                     messages: [
                         {
                             role: 'system',
@@ -627,21 +642,33 @@ class QQGroupManagerService extends koishi_1.Service {
                         },
                         {
                             role: 'user',
-                            content: `请判断是否值得回复这条消息（从严，降低热度）。以下是消息与上下文：\n${contextPrompt}`,
+                            content: `请判断是否值得回复这条消息。表情包/图片是群聊中正常的互动内容，不要因为「没有文字」就判定为无价值；仅在与本群无关且明显无意义刷屏时才不回复。以下是消息与上下文：\n${contextPrompt}`,
                         },
                     ],
                 }),
                 signal: controller.signal,
             });
             const payload = await response.json().catch(() => ({}));
-            const content = payload?.choices?.[0]?.message?.content;
+            const choice = payload?.choices?.[0];
+            const content = choice?.message?.content;
             if (!response.ok)
                 return { reply: false, score: 0, reason: `http-${response.status}` };
-            const plain = typeof content === 'string'
+            let plain = typeof content === 'string'
                 ? content
                 : Array.isArray(content)
                     ? content.map((item) => item?.text || '').join('')
                     : '';
+            // 兜底：若仍为空（思考模型额度被截断），从 reasoning_content 里捞 JSON
+            if (!plain.trim()) {
+                const reasoning = String(choice?.message?.reasoning_content || '');
+                const jsonLike = reasoning.match(/\{[\s\S]*\}/);
+                if (jsonLike)
+                    plain = jsonLike[0];
+                if (!plain.trim()) {
+                    this._logger.warn(`[ai-interest] 判定返回空内容 finish=${choice?.finish_reason} reasoningTokens=${payload?.usage?.completion_tokens_details?.reasoning_tokens} | ${this.sessionTag?.('') ?? ''}`);
+                    return { reply: false, score: 0, reason: `empty(finish=${choice?.finish_reason || 'unknown'})` };
+                }
+            }
             return this.parseInterestDecision(plain);
         }
         catch {
@@ -671,10 +698,11 @@ class QQGroupManagerService extends koishi_1.Service {
                     systemInstruction: {
                         parts: [{ text: '你是群聊回复开关决策器。只输出 JSON: {"reply":boolean,"score":0-100,"reason":"..."}。除 JSON 外不输出任何文字。' }],
                     },
-                    contents: [{ role: 'user', parts: [{ text: `请判断是否值得回复这条消息（从严，降低热度）。以下是消息与上下文：\n${contextPrompt}` }] }],
+                    contents: [{ role: 'user', parts: [{ text: `请判断是否值得回复这条消息。表情包/图片是群聊中正常的互动内容，不要因为「没有文字」就判定为无价值；仅在与本群无关且明显无意义刷屏时才不回复。以下是消息与上下文：\n${contextPrompt}` }] }],
                     generationConfig: {
                         temperature: 0.15,
-                        maxOutputTokens: 64,
+                        // 带思考的模型会先消耗思考 token，额度太小会导致正文为空
+                        maxOutputTokens: 512,
                     },
                 }),
                 signal: controller.signal,
@@ -695,7 +723,10 @@ class QQGroupManagerService extends koishi_1.Service {
         }
     }
     async shouldReplyByInterest(params) {
-        const context = this.buildInterestContextPrompt(params.groupKey, params.text, this.config.aiInterestContextWindow || 8);
+        const context = this.buildInterestContextPrompt(params.groupKey, params.text, this.config.aiInterestContextWindow || 8, {
+            hasSticker: !!params.hasSticker,
+            hasImage: !!params.hasImage,
+        });
         const decision = this.config.aiProvider === 'gemini'
             ? await this.decideInterestByGemini(context.prompt)
             : await this.decideInterestByOpenAI(context.prompt);
@@ -995,82 +1026,396 @@ class QQGroupManagerService extends koishi_1.Service {
             return [];
         return this.extractMessageImageUrls(session, maxCount);
     }
-    isImageSendableUrl(value) {
+    isImageReference(value) {
         if (!value || typeof value !== 'string')
             return false;
         const v = value.trim();
+        if (!v)
+            return false;
         if (/^https?:\/\//i.test(v))
             return true;
         if (/^data:image\//i.test(v))
             return true;
+        if (/^base64:\/\//i.test(v))
+            return true;
+        if (/^file:\/\//i.test(v))
+            return true;
+        if (/^[A-Za-z]:[\\/]/.test(v) || v.startsWith('/'))
+            return true;
+        // NapCat 常见：纯文件名 / hash.jpg
+        if (/^[0-9A-Fa-f]{16,}\.[A-Za-z0-9]{2,5}$/.test(v))
+            return true;
         return false;
     }
-    extractMessageImageUrls(session, maxCount = 4) {
-        const urls = [];
-        const content = session.content ?? '';
-        const cqPattern = /\[CQ:image,[^\]]*\]/gi;
-        const cqList = content.match(cqPattern) ?? [];
-        for (const chunk of cqList) {
-            const match = chunk.match(/(?:url|src)=([^,\]]+)/i);
-            let value = match ? decodeURIComponent(match[1].trim()) : '';
-            if (!this.isImageSendableUrl(value)) {
-                // 部分适配器把 url 放在 file 字段
-                const fm = chunk.match(/file=([^,\]]+)/i);
-                if (fm) {
-                    const f = decodeURIComponent(fm[1].trim());
-                    if (this.isImageSendableUrl(f))
-                        value = f;
+    extractImageCandidates(session, maxCount = 6) {
+        const out = [];
+        for (const item of this.extractImageElements(session)) {
+            for (const candidate of [item.url, item.ref]) {
+                if (!this.isImageReference(candidate))
+                    continue;
+                if (!out.includes(candidate))
+                    out.push(candidate);
+            }
+        }
+        return out.slice(0, Math.max(1, maxCount));
+    }
+    collectReplyAwareImageCandidates(session, maxCount = 2) {
+        const own = this.extractImageCandidates(session, maxCount);
+        const quotedSession = session?.quote;
+        const quoted = quotedSession ? this.extractImageCandidates(quotedSession, maxCount) : [];
+        const merged = [];
+        for (const item of [...own, ...quoted]) {
+            if (!merged.includes(item))
+                merged.push(item);
+        }
+        return { own, quoted, merged: merged.slice(0, Math.max(1, maxCount)) };
+    }
+    detectImageMime(buffer, fallback = 'image/jpeg') {
+        if (!buffer || buffer.length < 12)
+            return fallback;
+        const b = buffer;
+        if (b[0] === 0xFF && b[1] === 0xD8 && b[2] === 0xFF)
+            return 'image/jpeg';
+        if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4E && b[3] === 0x47)
+            return 'image/png';
+        if (b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46)
+            return 'image/gif';
+        if (b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46
+            && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50)
+            return 'image/webp';
+        if (b[0] === 0x42 && b[1] === 0x4D)
+            return 'image/bmp';
+        return fallback;
+    }
+    async resolveImageReferenceToDataUrl(ref, session) {
+        const value = String(ref ?? '').trim();
+        if (!value)
+            return '';
+        // 已经是 data URL，直接沿用
+        if (/^data:image\//i.test(value)) {
+            return value.length > 64 * 1024 * 1024 ? '' : value;
+        }
+        try {
+            let finalUrl = value;
+            let headers = {};
+            if (/^base64:\/\//i.test(value)) {
+                // Koishi/OneBot 常见形态：base64://<裸base64>
+                const raw = value.replace(/^base64:\/\//i, '');
+                const buffer = Buffer.from(raw, 'base64');
+                if (!buffer.length)
+                    return '';
+                return `data:${this.detectImageMime(buffer)};base64,${buffer.toString('base64')}`;
+            }
+            if (/^https?:\/\//i.test(value)) {
+                // OneBot 的 get_image 能把 file_id 换成可访问链接
+                const direct = await this.fetchImageAsDataUrl(value, headers);
+                if (direct)
+                    return direct;
+                return '';
+            }
+            // 其余形态（file_id / 文件名 / 本地路径）交给 get_image 解析
+            const onebot = this.getOneBotApi(session);
+            if (onebot?.getImage) {
+                const resolved = await onebot.getImage(value).catch(() => null);
+                const url = resolved?.url || resolved?.file || resolved?.filename || '';
+                const isLocal = url && !/^https?:\/\//i.test(url) && !/^data:/i.test(url);
+                if (isLocal) {
+                    try {
+                        finalUrl = String(url).replace(/^file:\/\//i, '');
+                    }
+                    catch {
+                        finalUrl = '';
+                    }
+                }
+                else if (url) {
+                    const dataUrl = await this.fetchImageAsDataUrl(url, headers);
+                    if (dataUrl)
+                        return dataUrl;
+                }
+                if (finalUrl && finalUrl !== value && !/^https?:\/\//i.test(finalUrl)) {
+                    try {
+                        const buffer = await node_fs_1.default.promises.readFile(finalUrl);
+                        if (buffer.length)
+                            return `data:${this.detectImageMime(buffer)};base64,${buffer.toString('base64')}`;
+                    }
+                    catch {
+                        return '';
+                    }
                 }
             }
-            if (!this.isImageSendableUrl(value))
-                continue;
-            urls.push(value);
-            if (urls.length >= maxCount)
-                return urls;
+            if (/^file:\/\//i.test(value) || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('/')) {
+                const localPath = value.replace(/^file:\/\//i, '');
+                const buffer = await node_fs_1.default.promises.readFile(localPath).catch(() => null);
+                if (buffer?.length)
+                    return `data:${this.detectImageMime(buffer)};base64,${buffer.toString('base64')}`;
+            }
+            return '';
         }
-        const elements = session.elements ?? [];
-        for (const element of elements) {
-            if (element.type !== 'image')
-                continue;
-            const maybeUrl = (typeof element.url === 'string' && element.url)
-                || (typeof element.src === 'string' && element.src)
-                || (typeof element.attrs?.url === 'string' && element.attrs.url)
-                || (typeof element.attrs?.src === 'string' && element.attrs.src);
-            if (!this.isImageSendableUrl(maybeUrl))
-                continue;
-            urls.push(maybeUrl);
-            if (urls.length >= maxCount)
+        catch (error) {
+            this._logger.warn(`[img-fetch] resolve failed: ${String(error)} ref=${value.slice(0, 120)} | ${this.sessionTag(session)}`);
+            return '';
+        }
+    }
+    async fetchImageAsDataUrl(url, extraHeaders = {}) {
+        const MAX_BYTES = 8 * 1024 * 1024;
+        const cached = this._imageDataUrlCache?.get(url);
+        if (cached !== undefined)
+            return cached;
+        if (!this._imageDataUrlCache)
+            this._imageDataUrlCache = new Map();
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 12_000);
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) NapCat/QQ',
+                    Accept: 'image/avif,image/webp,image/apng,image/*,*/*;q=0.8',
+                    ...extraHeaders,
+                },
+                redirect: 'follow',
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                this._logger.warn(`[img-fetch] http ${response.status} url=${url.slice(0, 140)}`);
+                this.rememberImageDataUrl(url, '');
+                return '';
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const buffer = Buffer.from(arrayBuffer);
+            if (!buffer.length) {
+                this.rememberImageDataUrl(url, '');
+                return '';
+            }
+            if (buffer.length > MAX_BYTES) {
+                this._logger.warn(`[img-fetch] image too large (${buffer.length} bytes) url=${url.slice(0, 140)}`);
+                this.rememberImageDataUrl(url, '');
+                return '';
+            }
+            const mime = this.detectImageMime(buffer, response.headers.get('content-type')?.split(';')[0] || 'image/jpeg');
+            const dataUrl = `data:${mime};base64,${buffer.toString('base64')}`;
+            this.rememberImageDataUrl(url, dataUrl);
+            return dataUrl;
+        }
+        catch (error) {
+            this._logger.warn(`[img-fetch] download failed: ${String(error)} url=${url.slice(0, 140)}`);
+            this.rememberImageDataUrl(url, '');
+            return '';
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    rememberImageDataUrl(url, dataUrl) {
+        if (!this._imageDataUrlCache)
+            this._imageDataUrlCache = new Map();
+        if (this._imageDataUrlCache.size > 64)
+            this._imageDataUrlCache.clear();
+        this._imageDataUrlCache.set(url, dataUrl);
+    }
+    async resolveImagesForModel(refs, session, maxCount) {
+        const limit = Math.max(1, maxCount || 1);
+        const out = [];
+        for (const ref of refs) {
+            if (out.length >= limit)
                 break;
+            const candidates = Array.isArray(ref) ? ref : [ref];
+            for (const candidate of candidates) {
+                const dataUrl = await this.resolveImageReferenceToDataUrl(candidate, session);
+                if (dataUrl) {
+                    out.push(dataUrl);
+                    break;
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * 把 extractImageElements 的结构化条目解析为可直接喂给模型的 data URL。
+     * 每个条目会依次尝试：原始 URL -> 本地文件名（走 OneBot get_image）。
+     */
+    async resolveVisualItemsForModel(items, session, maxCount) {
+        const limit = Math.max(1, maxCount || 1);
+        const out = [];
+        for (const item of items) {
+            if (out.length >= limit)
+                break;
+            const attempts = [];
+            if (item.url)
+                attempts.push(item.url);
+            if (item.ref && item.ref !== item.url)
+                attempts.push(item.ref);
+            for (const candidate of attempts) {
+                const dataUrl = await this.resolveImageReferenceToDataUrl(candidate, session);
+                if (dataUrl) {
+                    out.push(dataUrl);
+                    break;
+                }
+            }
+        }
+        return out;
+    }
+    isImageSendableUrl(value) {
+        if (!value || typeof value !== 'string')
+            return false;
+        const v = value.trim();
+        if (/^https?:\/\//i.test(v))
+            return true;
+        if (/^data:image\//i.test(v))
+            return true;
+        return false;
+    }
+    decodeHtmlEntities(value) {
+        if (typeof value !== 'string' || !value)
+            return '';
+        return value
+            .replace(/&amp;/gi, '&')
+            .replace(/&lt;/gi, '<')
+            .replace(/&gt;/gi, '>')
+            .replace(/&quot;/gi, '"')
+            .replace(/&#0?39;/g, "'")
+            .replace(/&apos;/gi, "'")
+            .replace(/&#x2f;/gi, '/')
+            .replace(/&#0?38;/g, '&');
+    }
+    parseHtmlTagParams(tag) {
+        const params = {};
+        const re = /([a-zA-Z][\w-]*)\s*=\s*"([^"]*)"|([a-zA-Z][\w-]*)\s*=\s*'([^']*)'/g;
+        let m;
+        while ((m = re.exec(tag))) {
+            const key = (m[1] || m[3] || '').toLowerCase();
+            const raw = m[2] !== undefined ? m[2] : m[4];
+            if (!key)
+                continue;
+            params[key.replace(/-/g, '')] = this.decodeHtmlEntities(raw);
         }
-        return [...new Set(urls)].slice(0, maxCount);
+        return params;
+    }
+    extractImageElements(session) {
+        const items = [];
+        const seen = new Set();
+        const push = (url, ref, sticker) => {
+            const u = this.decodeHtmlEntities(url || '').trim();
+            const r = (ref || '').trim();
+            const key = u || r;
+            if (!key || seen.has(key))
+                return;
+            seen.add(key);
+            items.push({
+                url: u,
+                ref: r,
+                sticker: !!sticker,
+                sendable: this.isImageSendableUrl(u),
+            });
+        };
+        const isStickerParams = (params) => {
+            const sub = String(params.subtype ?? params.subType ?? params['sub-type'] ?? '');
+            const summary = String(params.summary ?? '');
+            return sub === '1' || /动画表情|表情|贴纸|sticker|mface/i.test(summary);
+        };
+        // 1) CQ 码形态
+        const content = session?.content ?? '';
+        for (const chunk of content.match(/\[CQ:image,[^\]]*\]/gi) ?? []) {
+            const params = this.parseCqImageParams(chunk);
+            push(params.url || params.src || params.file, params.file_id || params.file || params.id, isStickerParams(params));
+        }
+        // 2) koishi onebot 适配器的 HTML 形态：<img src="..." summary="[动画表情]" .../>
+        for (const tag of content.match(/<img\b[^>]*\/?>/gi) ?? []) {
+            const attrs = this.parseHtmlTagParams(tag);
+            push(attrs.src || attrs.url || attrs.file, attrs.file || attrs.fileid, isStickerParams(attrs));
+        }
+        // 3) 元素形态：type 可能是 image / img / face / sticker / mface
+        for (const element of session?.elements ?? []) {
+            const type = String(element?.type ?? '').toLowerCase();
+            const attrs = element?.attrs ?? {};
+            const rawAttrs = {};
+            for (const k of Object.keys(attrs)) rawAttrs[String(k).toLowerCase().replace(/-/g, '')] = attrs[k];
+            const isImgLike = type === 'img' || type === 'image';
+            const isStickerLike = type === 'face' || type === 'sticker' || type === 'mface';
+            if (!isImgLike && !isStickerLike)
+                continue;
+            const url = element?.url || element?.src
+                || attrs.url || attrs.src
+                || attrs.image || attrs.href || '';
+            const ref = element?.file || element?.fileId || element?.file_id || element?.id
+                || attrs.file || attrs.fileid || attrs.file_id || attrs.id || '';
+            const sticker = isStickerLike || isStickerParams(rawAttrs) || isStickerParams(attrs);
+            push(url, ref, sticker);
+        }
+        return items;
+    }
+    extractImageUrlsFromSession(session, maxCount = 4) {
+        return this.extractImageElements(session)
+            .filter((item) => item.sendable)
+            .map((item) => item.url)
+            .slice(0, Math.max(1, maxCount));
+    }
+    hasAnyImageElement(session) {
+        if (!session)
+            return false;
+        if (this.extractImageElements(session).length)
+            return true;
+        const content = session.content ?? '';
+        return /\[CQ:image,/i.test(content)
+            || /<img\b/i.test(content)
+            || (session.elements ?? []).some((el) => {
+                const t = String(el?.type ?? '').toLowerCase();
+                return t === 'img' || t === 'image' || t === 'face' || t === 'sticker' || t === 'mface';
+            });
+    }
+    isStickerElement(element) {
+        if (!element || typeof element !== 'object')
+            return false;
+        const type = String(element.type ?? '').toLowerCase();
+        if (type === 'face' || type === 'sticker' || type === 'mface' || type === 'img' || type === 'image')
+            return true;
+        const attrs = element.attrs ?? {};
+        const sub = String(attrs.subType ?? attrs.subtype ?? attrs['sub-type'] ?? '');
+        return type === 'image' && sub === '1';
+    }
+    hasStickerContent(session) {
+        if (!session)
+            return false;
+        if (/\[CQ:(face|mface|sticker),/i.test(session.content ?? ''))
+            return true;
+        return this.extractImageElements(session).some((item) => item.sticker);
+    }
+    extractMessageImageUrls(session, maxCount = 4) {
+        return this.extractImageUrlsFromSession(session, maxCount);
     }
     describeImageMessage(session) {
         const content = session.content ?? '';
-        const rawCq = (content.match(/\[CQ:image,[^\]]+\]/gi) ?? []);
+        const rawCq = (content.match(/\[CQ:image,[^\]]*\]/gi) ?? []);
+        const rawHtml = (content.match(/<img\b[^>]*\/?>/gi) ?? []);
+        const items = this.extractImageElements(session);
         const elems = [];
         for (const el of session.elements ?? []) {
-            if (el?.type !== 'image')
+            const t = String(el?.type ?? '').toLowerCase();
+            if (t !== 'image' && t !== 'img' && t !== 'face' && t !== 'sticker' && t !== 'mface')
                 continue;
-            const fields = {
+            const attrs = el.attrs ?? {};
+            elems.push({
                 type: el.type,
-                url: el.url || el.attrs?.url || '',
-                src: el.src || el.attrs?.src || '',
-                file: el.file || el.attrs?.file || '',
-                fileId: el.fileId || el.file_id || el.attrs?.file_id || '',
-                data: el.data ? String(el.data).slice(0, 40) : (el.attrs?.data ? String(el.attrs.data).slice(0, 40) : ''),
-            };
-            elems.push(fields);
+                url: el.url || attrs.url || '',
+                src: el.src || attrs.src || '',
+                file: el.file || attrs.file || '',
+                fileId: el.fileId || el.file_id || attrs.fileId || attrs.fileid || attrs.file_id || '',
+                subType: attrs.subType ?? attrs.subtype ?? attrs['sub-type'] ?? '',
+                summary: attrs.summary || '',
+            });
         }
         return {
             hasCqImage: rawCq.length > 0,
             rawCq,
+            rawHtml,
+            items,
             elementImages: elems,
-            extractableUrls: this.extractMessageImageUrls(session, 10),
+            extractableUrls: this.extractImageUrlsFromSession(session, 10),
+            candidates: this.extractImageCandidates(session, 10),
         };
     }
     logImageDebug(session) {
         const info = this.describeImageMessage(session);
-        this._logger.info(`[img-debug] cq=${info.rawCq.length} elements=${info.elementImages.length} urls=${JSON.stringify(info.extractableUrls)} cqRaw=${JSON.stringify(info.rawCq.slice(0, 2))} elems=${JSON.stringify(info.elementImages).slice(0, 300)} | ${this.sessionTag(session)}`);
+        this._logger.info(`[img-debug] cq=${info.rawCq.length} html=${info.rawHtml.length} elements=${info.elementImages.length} sendable=${JSON.stringify(info.extractableUrls)} candidates=${JSON.stringify(info.candidates)} items=${JSON.stringify(info.items).slice(0, 400)} | ${this.sessionTag(session)}`);
     }
     extractImageFingerprintKeys(session, maxCount = 6) {
         const keys = [];
@@ -1362,11 +1707,18 @@ class QQGroupManagerService extends koishi_1.Service {
     extractImageSendRefs(session, maxCount = 6) {
         const refs = [];
         const pushRef = (value) => {
-            const v = value.trim();
+            const v = String(value ?? '').trim();
             if (!v)
                 return;
             refs.push(v);
         };
+        // 统一走 extractImageElements：同时覆盖 CQ 与 koishi HTML(<img>) 两种形态
+        for (const item of this.extractImageElements(session)) {
+            pushRef(item.ref);
+            pushRef(item.url);
+            if (refs.length >= maxCount)
+                return [...new Set(refs)].slice(0, maxCount);
+        }
         const content = session.content ?? '';
         const cqPattern = /\[CQ:image,[^\]]*\]/gi;
         for (const chunk of content.match(cqPattern) ?? []) {
@@ -1384,27 +1736,6 @@ class QQGroupManagerService extends koishi_1.Service {
             if (refs.length >= maxCount)
                 return [...new Set(refs)].slice(0, maxCount);
         }
-        const elements = session.elements ?? [];
-        for (const element of elements) {
-            if (element.type !== 'image')
-                continue;
-            const candidates = [
-                typeof element.id === 'string' ? element.id : '',
-                typeof element.file === 'string' ? element.file : '',
-                typeof element.url === 'string' ? element.url : '',
-                typeof element.src === 'string' ? element.src : '',
-                typeof element.attrs?.file_id === 'string' ? element.attrs.file_id : '',
-                typeof element.attrs?.id === 'string' ? element.attrs.id : '',
-                typeof element.attrs?.file === 'string' ? element.attrs.file : '',
-                typeof element.attrs?.url === 'string' ? element.attrs.url : '',
-                typeof element.attrs?.src === 'string' ? element.attrs.src : '',
-            ].filter(Boolean);
-            for (const item of candidates) {
-                pushRef(item);
-                if (refs.length >= maxCount)
-                    return [...new Set(refs)].slice(0, maxCount);
-            }
-        }
         return [...new Set(refs)].slice(0, maxCount);
     }
     async fetchMessageImagePayload(session, maxCount = 6) {
@@ -1626,7 +1957,9 @@ class QQGroupManagerService extends koishi_1.Service {
             return { ok: false, message: '无可用聊天上下文。' };
         let prompt = this.buildAiUserPrompt(records, options);
         prompt = await this.decoratePromptWithMemory(prompt, options);
-        const focusImages = (options?.focusImages ?? []).filter((url) => /^https?:\/\//i.test(url));
+        const focusImages = (options?.focusImages ?? [])
+            .filter((url) => typeof url === 'string' && (/^https?:\/\//i.test(url) || /^data:image\//i.test(url)))
+            .slice(0, Math.max(1, this.config.aiImageMaxCount || 2));
         const result = this.config.aiProvider === 'gemini'
             ? await this.callGemini(focusImages.length
                 ? `${prompt}\n\n点名消息图片链接（如可访问请一并识别）：\n${focusImages.map((item, i) => `${i + 1}. ${item}`).join('\n')}`
@@ -1656,16 +1989,40 @@ class QQGroupManagerService extends koishi_1.Service {
         if (!groupKey)
             return;
         const text = this.extractAiMessageText(session);
-        // Always record context first, including other users during follow-up windows.
-        this.pushAiRecord(session, text || '@bot');
         const atBot = this.isMentionBot(session);
         const messageImages = this.extractImageUrls(session);
-        // 识图调试：消息里带图但提取不到可发送链接时，记录原始图片字段，便于排查
+        // 识图：当前消息没有图时，回退到「被回复的那条消息」里的图（适配器已把原消息放在 session.quote）
+        const ownItems = this.extractImageElements(session);
+        const quoteItems = session.quote ? this.extractImageElements(session.quote) : [];
+        const itemsForModel = ownItems.length ? ownItems : quoteItems;
+        const imageCandidates = this.collectReplyAwareImageCandidates(session, Math.max(1, this.config.aiImageMaxCount || 2));
+        const replyImageRefs = messageImages.length ? [] : imageCandidates.quoted;
+        const rawImageRefs = messageImages.length ? [] : imageCandidates.merged;
+        // 注意：图片下载（http -> data URL）延迟到"确认要回复"之后，避免每条含图消息都产生网络开销
+        let focusImages = messageImages;
+        const hasSticker = this.hasStickerContent(session)
+            || !!(session.quote && this.hasStickerContent(session.quote));
+        // 识图调试：消息里带图/表情但提取不到可发送图片时，记录原始字段，便于排查
         if (this.config.aiEnableImageRecognition) {
-            const hasImage = /\[CQ:image,/i.test(session.content ?? '')
-                || (session.elements ?? []).some((el) => el?.type === 'image');
-            if (hasImage && !messageImages.length) {
+            const quotedHasImage = this.hasAnyImageElement(session.quote);
+            if ((this.hasAnyImageElement(session) || quotedHasImage) && !messageImages.length) {
                 this.logImageDebug(session);
+                this._logger.info(`[img-debug] reply-aware ownItems=${ownItems.length} quoteItems=${quoteItems.length} own=${JSON.stringify(imageCandidates.own)} quoted=${JSON.stringify(replyImageRefs)} hasQuote=${!!session.quote} | ${this.sessionTag(session)}`);
+            }
+        }
+        // 纯图片/表情包消息也参与 AI 判定（此前会被下面的空文本早退直接丢弃）
+        const hasVisualContent = hasSticker || !!rawImageRefs.length || focusImages.length > 0;
+        const visualText = hasVisualContent ? '[图片/表情]' : '';
+        const effectiveText = text || visualText;
+        // 记录上下文（放在视觉变量计算之后，避免 const 暂时性死区）
+        this.pushAiRecord(session, text || visualText || '@bot');
+        if (hasVisualContent) {
+            // 用视觉占位文本刷新上下文，避免 buffer 里该条为空文本
+            const buffered = this.aiBuffers.get(groupKey) ?? [];
+            const last = buffered[buffered.length - 1];
+            if (last && !String(last.text ?? '').trim()) {
+                last.text = visualText;
+                last.imageUrls = last.imageUrls?.length ? last.imageUrls : (hasSticker ? ['sticker'] : ['image']);
             }
         }
         const directMention = this.config.aiEnableDirectMentionTrigger && (this.containsAgentName(text) || atBot);
@@ -1689,7 +2046,8 @@ class QQGroupManagerService extends koishi_1.Service {
         }
         if (followup && !isFollowupUser && !directMention && !relatedContextFollowup)
             return;
-        if (!text && !directMention && !followupForce && !relatedContextFollowup)
+        // 纯图片/表情消息也允许进入随机/阈值/兴趣判定（visualText 已给出占位文本）
+        if (!effectiveText && !hasVisualContent && !directMention && !followupForce && !relatedContextFollowup)
             return;
         if (this.config.aiIgnoreCommandMessage && !directMention && !followupForce && !relatedContextFollowup && this.isCommandLikeMessage(text))
             return;
@@ -1702,7 +2060,7 @@ class QQGroupManagerService extends koishi_1.Service {
             return;
         const topicHint = (this.aiTopicMemory.get(groupKey)?.text || '').replace(/\s+/g, ' ').trim().slice(0, 120);
         if (trigger.reason === 'interest-check') {
-            const interest = await this.shouldReplyByInterest({ groupKey, text });
+            const interest = await this.shouldReplyByInterest({ groupKey, text: effectiveText, hasSticker, hasImage: focusImages.length > 0 });
             this.logCommandResult('ai-interest', { ok: interest.ok, message: `score=${interest.score} threshold=${interest.threshold} reason=${interest.reason}` }, session, { ctxSize: interest.ctxSize, topicHint: interest.topicHint || topicHint || undefined });
             if (!interest.ok)
                 return;
@@ -1725,7 +2083,7 @@ class QQGroupManagerService extends koishi_1.Service {
             }
         }
         if (thresholdMode) {
-            const interest = await this.shouldReplyByInterest({ groupKey, text });
+            const interest = await this.shouldReplyByInterest({ groupKey, text: effectiveText, hasSticker, hasImage: focusImages.length > 0 });
             this.logCommandResult('ai-threshold-interest', { ok: interest.ok, message: `score=${interest.score} threshold=${interest.threshold} reason=${interest.reason}` }, session, { ctxSize: interest.ctxSize, topicHint: interest.topicHint || topicHint || undefined });
             if (!interest.ok) {
                 this.logCommandResult('ai-threshold-skip-by-interest', { ok: true, message: 'threshold hit but skipped by low interest' }, session, {
@@ -1738,14 +2096,29 @@ class QQGroupManagerService extends koishi_1.Service {
         }
         this.aiInFlight.add(groupKey);
         const startedAt = Date.now();
+        // 已确认要回复，此时才把图片下载/转换为 base64（模型需要可直接读取的图片数据）
+        const maxImg = Math.max(1, this.config.aiImageMaxCount || 2);
+        let modelImages = focusImages.filter((u) => /^data:image\//i.test(u)).slice(0, maxImg);
+        if (this.config.aiEnableImageRecognition && modelImages.length < maxImg) {
+            const pendingItems = itemsForModel.slice();
+            if (pendingItems.length) {
+                const resolved = await this.resolveVisualItemsForModel(pendingItems, session, maxImg - modelImages.length);
+                modelImages = [...modelImages, ...resolved].slice(0, maxImg);
+            }
+            else if (rawImageRefs.length) {
+                const resolved = await this.resolveImagesForModel(rawImageRefs, session, maxImg - modelImages.length);
+                modelImages = [...modelImages, ...resolved].slice(0, maxImg);
+            }
+        }
+        this._logger.info(`[img-probe] trigger=${trigger.reason} ownItems=${ownItems.length} quoteItems=${quoteItems.length} candidates=${rawImageRefs.length} modelImages=${modelImages.length} sticker=${hasSticker} | ${this.sessionTag(session)}`);
         try {
             const result = await this.generateAiReply(session, {
                 directMention,
                 followup: (followupForce || relatedContextFollowup),
                 thresholdMode,
-                focusText: (directMention || followupForce || relatedContextFollowup) ? (text || '@bot') : undefined,
+                focusText: (directMention || followupForce || relatedContextFollowup) ? (effectiveText || '@bot') : undefined,
                 focusUserId: (directMention || followupForce || relatedContextFollowup) ? session.userId : undefined,
-                focusImages: messageImages,
+                focusImages: modelImages,
                 focusUserName: (directMention || followupForce || relatedContextFollowup) ? this.getDisplayName(session) : undefined,
                 topicTokens: thresholdMode ? topicTokens : undefined,
                 selectedRecord,
@@ -2602,7 +2975,9 @@ class QQGroupManagerService extends koishi_1.Service {
         return onebot ?? null;
     }
     extractTextForFilter(session) {
-        const raw = (session.content ?? '').replace(/\[CQ:[^\]]+\]/g, ' ');
+        const raw = (session.content ?? '')
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/\[CQ:[^\]]+\]/g, ' ');
         return raw.trim();
     }
     hasTextContent(session) {
@@ -2620,7 +2995,12 @@ class QQGroupManagerService extends koishi_1.Service {
         const content = session.content ?? '';
         if (/\[CQ:(image|face|record|video|flash),/i.test(content))
             return true;
-        return (session.elements ?? []).some((el) => el.type === 'image' || el.type === 'face' || el.type === 'record' || el.type === 'video' || el.type === 'flash');
+        if (/<img\b/i.test(content))
+            return true;
+        return (session.elements ?? []).some((el) => {
+            const t = String(el?.type ?? '').toLowerCase();
+            return t === 'img' || t === 'image' || t === 'face' || t === 'record' || t === 'video' || t === 'flash';
+        });
     }
     hasCardMessage(session) {
         const content = session.content ?? '';
@@ -2674,9 +3054,168 @@ class QQGroupManagerService extends koishi_1.Service {
             violationWindowMinutes: rule.autoViolationWindowMinutes ?? this.config.autoViolationWindowMinutes,
         };
     }
-    detectViolation(session, policy) {
-        // 防误判：纯图片/表情/贴纸（无实际文字内容）的消息不作为违规处理，避免表情包被当成违禁词
-        if (this.hasImageOrFace(session) && !this.hasTextContent(session)) {
+    /**
+     * 违禁词分档默认分值（可通过配置用 "关键词|分值" 或 {keyword,score} 覆盖）
+     * 设计原则：单独出现时属于强广告特征的词给高分（可独立触发），
+     * 需要组合才能确认的弱特征词给低分（需多条累计）。
+     */
+    static DEFAULT_BANNED_WORD_SCORES = {
+        // 显式广告行为（单条精确命中即可接近/达到阈值）
+        '加群': 50, '拉人': 50, '拉群': 50, '互推': 50, '引流': 55,
+        '加微信': 55, '加v': 50, '加V': 50, '加qq': 50, '加QQ': 50,
+        '扫码进群': 80, '进群领': 60, '加我好友': 50, '私信我': 50,
+        '点击链接': 50, '刷单': 60, '躺赚': 60, '日结': 50,
+        // 需要组合确认的运营/营销词
+        '邀请你': 35, '问卷': 30, '兼职': 40, '赚钱': 35, '赚米': 35,
+        '返利': 45, '代理': 30, '招人': 35, '零成本': 40, '速来': 30,
+        '福利群': 45, '红包群': 45, '活动群': 40, '转发群': 40,
+        '免费领': 50, '免费送': 45, '领红包': 40, '抢红包': 35, '领福利': 40,
+        '点击查看': 35, '名额有限': 35,
+    };
+    static DEFAULT_BANNED_WORD_SCORE = 40;
+    normalizeBannedWordEntry(entry) {
+        const raw = String(entry ?? '').trim();
+        if (!raw)
+            return null;
+        let keyword = raw;
+        let score = null;
+        // 支持 "关键词|分值"、全角竖线、逗号分隔
+        const m = raw.match(/^(.+?)\s*[|｜,，:：]\s*(\d{1,3})$/);
+        if (m) {
+            keyword = m[1].trim();
+            const parsed = parseInt(m[2], 10);
+            if (Number.isFinite(parsed))
+                score = Math.max(0, Math.min(100, parsed));
+        }
+        if (!keyword)
+            return null;
+        if (score === null) {
+            const table = this.constructor.DEFAULT_BANNED_WORD_SCORES || {};
+            const hit = Object.keys(table).find((k) => k.toLowerCase() === keyword.toLowerCase());
+            score = hit ? table[hit] : this.constructor.DEFAULT_BANNED_WORD_SCORE;
+        }
+        return { keyword, score };
+    }
+    normalizeBannedWordList(list) {
+        const out = [];
+        const seen = new Set();
+        for (const entry of list ?? []) {
+            let keyword;
+            let score;
+            if (entry && typeof entry === 'object') {
+                keyword = String(entry.keyword ?? entry.word ?? entry.text ?? '').trim();
+                const parsed = Number(entry.score ?? entry.weight ?? NaN);
+                score = Number.isFinite(parsed) ? Math.max(0, Math.min(100, parsed)) : null;
+                if (keyword && score === null) {
+                    const table = this.constructor.DEFAULT_BANNED_WORD_SCORES || {};
+                    const hit = Object.keys(table).find((k) => k.toLowerCase() === keyword.toLowerCase());
+                    score = hit ? table[hit] : this.constructor.DEFAULT_BANNED_WORD_SCORE;
+                }
+            }
+            else {
+                const norm = this.normalizeBannedWordEntry(entry);
+                if (!norm)
+                    continue;
+                keyword = norm.keyword;
+                score = norm.score;
+            }
+            if (!keyword)
+                continue;
+            const key = keyword.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ keyword, score });
+        }
+        return out;
+    }
+    /**
+     * 顺序子序列匹配：关键词的字符按顺序出现在文本中即命中，允许中间隔词。
+     * 返回匹配跨度与紧凑度（跨度越接近词长，置信度越高）。
+     */
+    /**
+     * 模糊命中的最低置信度门槛。
+     * 短关键词（2~4 字）极易被无关文本凑齐（如「领导说…红色包装袋」凑出「领红包」），
+     * 因此对短词要求更高的置信度；长词本身信息量足，门槛可放宽。
+     */
+    minBannedWordConfidence(keywordLength) {
+        if (keywordLength <= 1)
+            return 1;
+        if (keywordLength <= 2)
+            return 0.6;
+        if (keywordLength <= 4)
+            return 0.65;
+        if (keywordLength <= 6)
+            return 0.55;
+        return 0.45;
+    }
+    subsequenceMatch(text, keyword) {
+        if (!text || !keyword)
+            return null;
+        const first = text.indexOf(keyword);
+        if (first >= 0) {
+            return { start: first, end: first + keyword.length, span: keyword.length, ratio: 1, exact: true };
+        }
+        const chars = Array.from(keyword);
+        let pos = 0;
+        let start = -1;
+        let end = -1;
+        for (let i = 0; i < chars.length; i++) {
+            const idx = text.indexOf(chars[i], pos);
+            if (idx < 0) {
+                // 单个字符找不到即判定不命中
+                return null;
+            }
+            if (i === 0)
+                start = idx;
+            end = idx;
+            pos = idx + 1;
+        }
+        const span = end - start + 1;
+        const overflow = span - chars.length;
+        // 分散过滤：隔得太开（跨度超过词长 + 8 或 3 倍词长）视为偶然凑齐
+        if (span > chars.length * 3 || overflow > 8) {
+            return null;
+        }
+        // 置信度按「词长归一化的溢出」衰减：短词对间隔更敏感
+        // 例：领红包(len3) 在「领xxx元红包」(span6,overflow3) → 1-0.25*1 = 0.75
+        const confidence = Math.max(0.25, 1 - 0.25 * (overflow / chars.length));
+        // 短词需要更高置信度才算命中，避免无关文本偶然凑齐字符
+        if (confidence < this.minBannedWordConfidence(chars.length)) {
+            return null;
+        }
+        return { start, end: end + 1, span, overflow, ratio: chars.length / span, confidence, exact: false };
+    }
+    evaluateBannedWords(text, policy) {
+        const words = this.normalizeBannedWordList(policy?.bannedWords ?? []);
+        const evaluations = [];
+        let total = 0;
+        for (const { keyword, score } of words) {
+            if (!keyword || keyword.length < 1)
+                continue;
+            const match = this.subsequenceMatch(text, keyword);
+            if (!match)
+                continue;
+            const confidence = match.exact ? 1 : (match.confidence ?? 0.3);
+            const gained = Math.round(score * Math.min(1, confidence) * 100) / 100;
+            if (gained <= 0)
+                continue;
+            total += gained;
+            evaluations.push({
+                keyword,
+                score,
+                confidence: Math.round(Math.min(1, confidence) * 100) / 100,
+                gained,
+                span: match.span,
+                exact: !!match.exact,
+            });
+        }
+        evaluations.sort((a, b) => b.gained - a.gained);
+        return { total: Math.round(total * 100) / 100, evaluations };
+    }
+    detectViolation(session, policy, type = 'message') {
+        // 纯图片/表情/贴纸（无实际文字内容）的消息不作为违规处理，避免表情包被当成违禁词
+        if (type === 'message' && this.hasImageOrFace(session) && !this.hasTextContent(session)) {
             return null;
         }
         if (policy.blockCardMessage && this.hasCardMessage(session)) {
@@ -2688,13 +3227,17 @@ class QQGroupManagerService extends koishi_1.Service {
         const text = this.extractTextForFilter(session);
         if (!text)
             return null;
-        for (const word of policy.bannedWords) {
-            const keyword = word?.trim();
-            if (!keyword)
-                continue;
-            if (text.includes(keyword)) {
-                return { type: 'banned-word', detail: `命中违禁词: ${keyword}` };
-            }
+        const assessment = this.evaluateBannedWords(text, policy);
+        const threshold = Math.max(1, Math.min(100, Number(this.config.bannedWordScoreThreshold ?? 70)));
+        if (assessment.total >= threshold) {
+            const top = assessment.evaluations.slice(0, 4)
+                .map((item) => `${item.keyword}(+${item.gained}${item.exact ? '' : `/${item.confidence}`})`)
+                .join(' ');
+            return {
+                type: 'banned-word',
+                detail: `违禁词评分 ${assessment.total}/${threshold}：${top}`,
+                assessment,
+            };
         }
         return null;
     }
@@ -2796,10 +3339,13 @@ class QQGroupManagerService extends koishi_1.Service {
                 if (policy.autoDeleteViolation) {
                     deleted = await this.deleteMessage(session);
                 }
-                this._logger.warn(`[moderation] type=${violation.type} detail="${violation.detail}" deleted=${deleted} | ${this.sessionTag(session)}`);
+                const scoreInfo = violation.assessment
+                    ? ` score=${violation.assessment.total} hits=${violation.assessment.evaluations.map((item) => `${item.keyword}:${item.gained}${item.exact ? '' : '/fuzzy'}`).join(',')}`
+                    : '';
+                this._logger.warn(`[moderation] type=${violation.type} detail="${violation.detail}"${scoreInfo} deleted=${deleted} | ${this.sessionTag(session)}`);
                 if (policy.sendViolationNotice) {
                     const notice = violation.type === 'banned-word'
-                        ? '检测到违禁词，消息已处理。'
+                        ? `检测到违禁内容（评分 ${violation.assessment?.total ?? '-'}），消息已处理。`
                         : violation.type === 'card'
                             ? '卡片消息不被允许，消息已处理。'
                             : '合并转发消息不被允许，消息已处理。';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nestim/koishi-plugin-qq-group-manager",
   "description": "Koishi QQ群管理插件（OneBot/LLOneBot）：群管命令、权限校验、图片菜单、状态卡片、复读、AI群聊回复、记忆库、识图与自动管控（禁言/踢人）。",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -1,9 +1,56 @@
-# koishi-qq-group-manager
+# koishi-qq-group-manager
 
-[![npm](https://img.shields.io/npm/v/%40meownestim%2Fkoishi-qq-group-manager?style=flat-square)](https://www.npmjs.com/package/@nestim/koishi-qq-group-manager)
+[![npm](https://img.shields.io/npm/v/%40nestim%2Fkoishi-qq-group-manager?style=flat-square)](https://www.npmjs.com/package/@nestim/koishi-plugin-qq-group-manager)
 
 QQ群管理插件（OneBot/LLOneBot）：群管命令、权限校验、图片菜单、状态卡片、复读、AI群聊回复、记忆库、识图与自动管控（禁言/踢人）。
 
+## v0.1.6 重点更新
+
+### 1. 识图彻底修复（此前完全不可用）
+
+早前版本的图片检测对 NapCat/Koishi 实际下发的消息结构**完全不匹配**，导致 AI 永远「看不到图」：
+
+| 旧实现假设 | 实际情况 |
+| --- | --- |
+| `session.content` 含 `[CQ:image,...]` | 实际是 HTML 形态 `<img src="..." summary="[动画表情]" sub-type="1"/>` |
+| 元素 `type === 'image'` | 实际是 `type === 'img'` |
+| 图片地址在 `url` / `src` | 实际在 `attrs.src` |
+| 表情包靠 `[CQ:face]` | 实际靠 `attrs.subType === 1` / `summary="[动画表情]"` |
+
+此外 `<img src>` 中的 `&amp;` 是 HTML 实体，**未解码直接请求必然 404**。
+
+修复后：
+- 新增统一视觉解析器，同时兼容 CQ 码、HTML `<img>`、element 三种形态，并自动解码 HTML 实体；
+- 图片会**下载并转为 base64 data URL** 再交给模型，不再依赖模型侧能否访问 QQ 图链（QQ 图链需 `rkey` 鉴权且有时效）；
+- 支持**「回复某张图片再 @bot」**：适配器已把被回复消息放在 `session.quote`，现在会从中取图；
+- 表情包（`subType=1`）同样会被识别与理解。
+
+### 2. 修复随机/阈值触发对纯图片、表情包无效
+
+- 纯图片/表情消息此前会被「无文本」守卫直接丢弃，现改为参与兴趣/阈值判定；
+- 兴趣判定提示词不再把「没有文字」等同于「无价值」，表情包/图片可作为正常互动被接话。
+
+### 3. 修复兴趣判定长期失效（`reason=empty`）
+
+`deepseek-flash` 等**带思考的模型**会先消耗 reasoning tokens。原兴趣判定只给 `max_tokens: 48`，额度被思考过程耗尽后正文为空，导致判定恒为 `score=0 reason=empty`、随机回复形同虚设。
+
+- 额度提升至 512（OpenAI 兼容与 Gemini 两条路径同步修复）；
+- 正文仍为空时，回退从 `reasoning_content` 中提取 JSON。
+
+### 4. 违禁词改为「整条消息评分」制
+
+原实现是逐词 `includes` 精确包含，广告把词隔开即可绕过（如 `领红包` 无法命中 `领xxx元红包`）。
+
+新机制：
+- **顺序子序列匹配**：关键词字符按序出现即命中，允许中间隔词；
+- **置信度**：按「词长归一化的间隔溢出」衰减，跨度超过词长 3 倍或溢出超过 8 字则判定为偶然凑齐、直接拒绝（可拦住 `领 导 强 调 红 色 包 装` 这类）；
+- **词长自适应门槛**：短词（2~4 字）需要更高置信度，降低无关文本误伤；
+- **可配置权重**：`"关键词|分值"` 形式，未指定时按内置分档表取值（显式广告词如 `扫码进群` 80 分，营销组合词如 `赚钱` 35 分）；
+- **整条消息累计得分 ≥ `bannedWordScoreThreshold`（默认 70）** 才触发管控（撤回/禁言/踢人），日志会输出命中明细与得分。
+
+> 局限说明：字符级匹配无法区分「字符顺序与间隔完全一致」的两个串。
+> 例如 `领xxx元红包`（广告）与 `领导说把红色包装袋收好`（正常）跨度均为 7、置信度均为 0.667，属于原理性边界，可通过调整阈值与权重缓解。
+
 ## 禁言指令优化（v0.0.4）
 
 `群管 mute` 不再依赖固定顺序解析参数，改为智能解析，避免「禁言时长被识别成 QQ 号」：