dsh-qqchat 0.2.0

package/lib/gateway/normalize.js

@@ -0,0 +1,248 @@
+function authorId(author = {}) {
+    return String(author.user_openid || author.member_openid || author.id || '');
+}
+function authorName(author = {}) {
+    return String(author.username || author.nickname || '').trim();
+}
+/** Replace QQ's stable mention tokens with the best known display name. */
+export function renderQQMentionNames(text, data, lookup = () => undefined) {
+    const mentions = Array.isArray(data.mentions) ? data.mentions : [];
+    let rendered = String(text || '');
+    for (const item of mentions) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const id = String(item.user_openid || item.member_openid || item.openid || item.id || '').trim();
+        if (!id)
+            continue;
+        const name = String(item.username || item.nickname || item.display_name || item.name || lookup(id) || '').trim();
+        if (!name)
+            continue;
+        const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        rendered = rendered
+            .replace(new RegExp(`<@!?${escaped}>`, 'g'), `@${name}`)
+            .replace(new RegExp(`@${escaped}(?![A-Za-z0-9_-])`, 'g'), `@${name}`);
+    }
+    return rendered;
+}
+export function messageMentionsBot(data, eventType) {
+    if (!Object.prototype.hasOwnProperty.call(data, 'mentions')) {
+        return eventType === 'GROUP_AT_MESSAGE_CREATE';
+    }
+    const mentions = data.mentions;
+    if (!Array.isArray(mentions))
+        return false;
+    if (mentions.length === 0)
+        return eventType === 'GROUP_AT_MESSAGE_CREATE';
+    for (const item of mentions) {
+        if (!item || typeof item !== 'object' || item.bot !== true)
+            continue;
+        if (Object.prototype.hasOwnProperty.call(item, 'is_you'))
+            return item.is_you === true;
+        return true;
+    }
+    return false;
+}
+export function botMentionId(data, eventType) {
+    const mentions = data.mentions;
+    if (Array.isArray(mentions)) {
+        for (const item of mentions) {
+            if (!item || typeof item !== 'object' || item.bot !== true)
+                continue;
+            for (const key of ['id', 'user_openid', 'member_openid', 'openid']) {
+                if (item[key])
+                    return String(item[key]);
+            }
+        }
+    }
+    if (eventType === 'GROUP_AT_MESSAGE_CREATE') {
+        const match = String(data.content || '').match(/<@!?([^>]+)>/);
+        if (match?.[1])
+            return match[1];
+    }
+    return '';
+}
+export function normalizeQQDispatch(eventType, data, accountId) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    if (eventType === 'C2C_MESSAGE_CREATE') {
+        const senderId = authorId(data.author);
+        if (!senderId)
+            return undefined;
+        return {
+            platform: 'qq', accountId, chatType: 'c2c', chatId: senderId,
+            senderId, senderName: authorName(data.author), groupOpenid: undefined,
+            messageId: String(data.id || ''), msgIdx: messageSceneIndex(data), refMsgIdx: messageReferenceIndex(data), text: String(data.content || '').trim(),
+            quotedText: extractQuotedText(data), quote: extractQuote(data), attachments: extractAttachments(data), mentioned: true,
+            botMentionId: '', raw: data,
+        };
+    }
+    if (eventType === 'GROUP_AT_MESSAGE_CREATE' || eventType === 'GROUP_MESSAGE_CREATE') {
+        const senderId = authorId(data.author);
+        const groupOpenid = String(data.group_openid || '');
+        if (!senderId || !groupOpenid)
+            return undefined;
+        return {
+            platform: 'qq', accountId, chatType: 'group', chatId: groupOpenid,
+            senderId, senderName: authorName(data.author), groupOpenid,
+            messageId: String(data.id || ''), msgIdx: messageSceneIndex(data), refMsgIdx: messageReferenceIndex(data), text: String(data.content || '').trim(),
+            quotedText: extractQuotedText(data), quote: extractQuote(data), attachments: extractAttachments(data), mentioned: messageMentionsBot(data, eventType),
+            botMentionId: botMentionId(data, eventType), raw: data,
+        };
+    }
+    return undefined;
+}
+function extractQuotedText(data) {
+    const reference = data.message_reference || data.reference || data.quote;
+    if (reference && typeof reference === 'object') {
+        const text = String(reference.content || reference.text || '').trim();
+        if (text)
+            return decodeQQText(text);
+    }
+    // QQ's native reply payload uses message_scene.ext/ref_msg_idx and keeps the
+    // referenced message in msg_elements instead of message_reference.
+    const elements = data.msg_elements || [];
+    if (elements.length === 0)
+        return '';
+    const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : [];
+    const referenceIndex = messageReferenceIndex(data);
+    const ownIndex = sceneValue(ext, 'msg_idx');
+    const element = referenceIndex
+        ? elements.find(item => String(item.msg_idx || '') === referenceIndex)
+        : elements.find(item => String(item.msg_idx || '') !== ownIndex);
+    if (!element)
+        return '';
+    return decodeQQText(String(element.content || element.text || '').trim());
+}
+function extractQuote(data) {
+    const text = extractQuotedText(data);
+    const reference = data.message_reference || data.reference || data.quote;
+    let record = reference && typeof reference === 'object' ? reference : undefined;
+    if (!record && Array.isArray(data.msg_elements)) {
+        const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : [];
+        const referenceIndex = messageReferenceIndex(data);
+        const element = referenceIndex ? data.msg_elements.find(item => String(item.msg_idx || '') === referenceIndex) : undefined;
+        if (element)
+            record = element;
+    }
+    const messageId = String(record?.id || record?.message_id || record?.messageId || '').trim() || undefined;
+    const sender = record?.author && typeof record.author === 'object' ? record.author : undefined;
+    const senderId = String(sender?.user_openid || sender?.member_openid || sender?.id || record?.sender_id || '').trim() || undefined;
+    const senderName = String(sender?.username || sender?.nickname || record?.sender_name || '').trim() || undefined;
+    const attachments = extractAttachments(record, true);
+    if (!text && !messageId && !senderId && attachments.length === 0)
+        return undefined;
+    return { messageId, senderId, senderName, text, attachments };
+}
+function messageSceneIndex(data) {
+    const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : [];
+    return sceneValue(ext, 'msg_idx') || String(data.id || '').trim() || undefined;
+}
+function messageReferenceIndex(data) {
+    const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : [];
+    return sceneValue(ext, 'ref_msg_idx') || sceneValue(ext, 'msg_ref_idx') || undefined;
+}
+function extractAttachments(data, quoted = false) {
+    if (!data)
+        return [];
+    const values = [];
+    if (Array.isArray(data.attachments))
+        values.push(...data.attachments.filter(isRecord));
+    if (Array.isArray(data.msg_elements)) {
+        const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : [];
+        const referenceIndex = sceneValue(ext, 'ref_msg_idx') || sceneValue(ext, 'msg_ref_idx');
+        for (const element of data.msg_elements) {
+            if (!quoted && referenceIndex && String(element.msg_idx || '') === referenceIndex)
+                continue;
+            const type = String(element.type || element.element_type || element.kind || '').toLowerCase();
+            if (type && !/(image|photo|picture|file|video|audio|voice|record|media|attachment)/u.test(type))
+                continue;
+            if (isRecord(element.attachment))
+                values.push(element.attachment);
+            else
+                values.push(element);
+        }
+    }
+    const output = [];
+    const seen = new Set();
+    for (const value of values) {
+        const sourceUrl = firstString(value, ['url', 'file_url', 'download_url', 'downloadUrl', 'href', 'file']);
+        const platformFileId = firstString(value, ['file_id', 'fileid', 'fileId', 'id']);
+        if (!sourceUrl && !platformFileId && !isRecord(value.attachment))
+            continue;
+        const filename = firstString(value, ['filename', 'file_name', 'name']) || inferFilename(sourceUrl) || 'QQ附件';
+        const contentType = firstString(value, ['content_type', 'contentType', 'mime', 'mime_type', 'type']);
+        const kind = mediaKind(contentType, filename, String(value.type || value.element_type || value.kind || ''));
+        const key = `${platformFileId || ''}|${sourceUrl || ''}|${filename}|${kind}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        output.push({
+            sourceUrl, filename, contentType, platformFileId,
+            size: numberValue(value, ['size', 'file_size', 'bytes']),
+            width: numberValue(value, ['width', 'img_width']),
+            height: numberValue(value, ['height', 'img_height']),
+            durationMs: numberValue(value, ['duration_ms', 'duration']), quoted, kind,
+        });
+    }
+    return output;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function firstString(value, keys) {
+    for (const key of keys) {
+        const item = value[key];
+        if (typeof item === 'string' && item.trim())
+            return item.trim();
+    }
+    return undefined;
+}
+function numberValue(value, keys) {
+    for (const key of keys) {
+        const item = Number(value[key]);
+        if (Number.isFinite(item) && item >= 0)
+            return item;
+    }
+    return undefined;
+}
+function inferFilename(url) {
+    if (!url)
+        return undefined;
+    try {
+        const name = decodeURIComponent(new URL(url).pathname.split('/').pop() || '');
+        return name && name !== '/' ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function mediaKind(contentType, filename, rawType) {
+    const value = `${contentType || ''} ${filename} ${rawType}`.toLowerCase();
+    if (/voice|record|audio|\.(amr|silk|mp3|wav|ogg|m4a)(?:$|\?)/u.test(value))
+        return 'voice';
+    if (/video|\.(mp4|mov|avi|mkv|webm)(?:$|\?)/u.test(value))
+        return 'video';
+    if (/image|photo|picture|\.(png|jpe?g|gif|webp|bmp|heic)(?:$|\?)/u.test(value))
+        return 'image';
+    if (/audio/u.test(value))
+        return 'audio';
+    return 'file';
+}
+function sceneValue(ext, key) {
+    const prefix = `${key}=`;
+    for (const item of ext) {
+        if (typeof item === 'string' && item.startsWith(prefix))
+            return item.slice(prefix.length).trim();
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        if (record.key === key)
+            return String(record.value || '').trim();
+        if (key in record)
+            return String(record[key] || '').trim();
+    }
+    return '';
+}
+function decodeQQText(value) {
+    return value.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&');
+}

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { QQChatConfigInput } from './types.js';
+export declare const name = "dsh-qqchat";
+export declare const inject: readonly ["connection", "agents", "agentDefaultModel", "commands", "llm", "tools", "workspaceRegistry"];
+export declare function apply(ctx: Context, inputConfig?: QQChatConfigInput): void;
+export type { QQChatConfig, QQChatConfigInput } from './types.js';
+export { QQChatDatabase } from './storage/db.js';
+export { normalizeQQDispatch } from './gateway/normalize.js';
+declare const _default: {
+    name: string;
+    inject: readonly ["connection", "agents", "agentDefaultModel", "commands", "llm", "tools", "workspaceRegistry"];
+    apply: typeof apply;
+};
+export default _default;

package/lib/index.js

@@ -0,0 +1,35 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DshQQBridge } from './session/agent-bridge.js';
+import { resolveConfig } from './config.js';
+import { QQChatDatabase } from './storage/db.js';
+import { QQChatLogger } from './shared/logging.js';
+import { MemoryEngine } from './storage/memory.js';
+import { QQMediaStore } from './media/store.js';
+import { QQApiClient } from './gateway/api.js';
+import { QQBindService } from './gateway/auth.js';
+import { createQQChatRpc } from './transport/rpc.js';
+import { QQChatRuntime } from './session/runtime.js';
+export const name = 'dsh-qqchat';
+export const inject = ['connection', 'agents', 'agentDefaultModel', 'commands', 'llm', 'tools', 'workspaceRegistry'];
+export function apply(ctx, inputConfig = {}) {
+    const config = resolveConfig(inputConfig);
+    mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
+    const db = new QQChatDatabase(join(config.dataDir, 'qqchat.sqlite'));
+    const baseLogger = ctx.logger || console;
+    const logger = new QQChatLogger(baseLogger);
+    const api = new QQApiClient(db, config);
+    const auth = new QQBindService(db, config);
+    const memory = new MemoryEngine(ctx, db, config, logger);
+    const media = new QQMediaStore(db, ctx, logger);
+    const bridge = new DshQQBridge(ctx, db, memory, config, logger);
+    const runtime = new QQChatRuntime(ctx, db, api, auth, memory, bridge, config, logger, media);
+    ctx.connection.rpc.handle('/qqchat', createQQChatRpc(runtime), { authority: 'loopback' });
+    ctx.effect(() => {
+        void runtime.start().catch(error => logger.error?.(error));
+        return () => runtime.stop();
+    }, 'dsh-qqchat runtime');
+}
+export { QQChatDatabase } from './storage/db.js';
+export { normalizeQQDispatch } from './gateway/normalize.js';
+export default { name, inject, apply };

package/lib/media/image-tool.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { QQChatDatabase } from '../storage/db.js';
+/** Exposes stored QQ images through DSH's durable image-block seam. */
+export declare function registerQQImageTool(ctx: Context, db: QQChatDatabase, isAllowed?: (agentId: string, attachmentId: string) => boolean): () => void;

package/lib/media/image-tool.js

@@ -0,0 +1,62 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+/** Exposes stored QQ images through DSH's durable image-block seam. */
+export function registerQQImageTool(ctx, db, isAllowed = () => true) {
+    const definition = defineTool({
+        name: 'qqchat_describe_image',
+        description: '查看 QQ 消息中的图片。传入 QQChat 提供的 attachment_id，可用于 OCR、截图、界面和照片分析。',
+        parameters: {
+            attachment_id: { type: 'string', required: true, description: 'QQChat 图片附件 ID' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    ok: { type: 'boolean' },
+                    attachment_id: { type: 'string' },
+                    filename: { type: 'string' },
+                    media_type: { type: 'string' },
+                    bytes: { type: 'number' },
+                    image_ref: { type: 'json' },
+                    error: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: value.error || '图片不可用。' }];
+                if (!value.image_ref || typeof value.image_ref !== 'object')
+                    return [{ type: 'text', text: '图片已找到，但当前 DSH 没有可用的图片附件服务。' }];
+                return [
+                    { type: 'text', text: `已加载图片：${value.filename || value.attachment_id}` },
+                    { type: 'image', attachment: value.image_ref },
+                ];
+            },
+        },
+        async execute(args, exec) {
+            const attachment = db.attachmentById(args.attachment_id);
+            if (!attachment || attachment.kind !== 'image' || !attachment.imageRef) {
+                return { ok: false, attachment_id: args.attachment_id, error: '找不到可查看的 QQ 图片附件。' };
+            }
+            const agent = exec.agent;
+            if (!isAllowed(String(agent?.id || ''), args.attachment_id)) {
+                return { ok: false, attachment_id: args.attachment_id, error: '当前 QQ 消息没有权限访问这张图片。' };
+            }
+            if (agent?.options?.provider && agent.options.model) {
+                try {
+                    const info = await ctx.llm.resolveModelInfo(agent.options.provider, agent.options.model, exec.signal);
+                    if (!info.inputModalities?.includes('image')) {
+                        return { ok: false, attachment_id: args.attachment_id, error: '当前模型不支持图片输入。' };
+                    }
+                }
+                catch {
+                    return { ok: false, attachment_id: args.attachment_id, error: '无法确认当前模型是否支持图片输入。' };
+                }
+            }
+            return {
+                ok: true, attachment_id: attachment.id, filename: attachment.filename,
+                media_type: attachment.imageRef.mediaType, bytes: attachment.sizeBytes, image_ref: { ...attachment.imageRef },
+            };
+        },
+    });
+    return ctx.tools.register(definition);
+}

package/lib/media/media-tools.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { QQChatDatabase } from '../storage/db.js';
+export declare function registerQQMediaTools(ctx: Context, db: QQChatDatabase, isAllowed?: (agentId: string, attachmentId: string) => boolean): () => void;

package/lib/media/media-tools.js

@@ -0,0 +1,68 @@
+import { readFile, stat } from 'node:fs/promises';
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+const execFile = promisify(execFileCallback);
+const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+export function registerQQMediaTools(ctx, db, isAllowed = () => true) {
+    const readFileTool = defineTool({
+        name: 'qqchat_read_file',
+        description: '读取 QQ 消息中的文本文件。传入 QQChat 提供的 attachment_id；二进制文件不会被当作文本读取。',
+        parameters: { attachment_id: { type: 'string', required: true, description: 'QQChat 文件附件 ID' } },
+        output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+        async execute(args, exec) {
+            const attachment = db.attachmentById(args.attachment_id);
+            const agentId = String(exec.agent?.id || '');
+            if (!attachment || !attachment.localPath || !isAllowed(agentId, args.attachment_id))
+                return '当前 QQ 消息没有可读取的文件附件。';
+            if (attachment.kind !== 'file')
+                return '这个附件不是普通文本文件。';
+            if (attachment.sizeBytes > MAX_TEXT_BYTES)
+                return `文件过大，超过 ${MAX_TEXT_BYTES} 字节读取上限。`;
+            try {
+                return await readFile(attachment.localPath, { encoding: 'utf8', signal: exec.signal });
+            }
+            catch {
+                return '文件读取失败或文件已过期。';
+            }
+        },
+    });
+    const mediaInfoTool = defineTool({
+        name: 'qqchat_media_info',
+        description: '查看 QQ 图片、语音、视频或文件附件的元数据；视频可在服务器安装 ffprobe 时补充流信息。',
+        parameters: { attachment_id: { type: 'string', required: true, description: 'QQChat 媒体附件 ID' } },
+        output: {
+            schema: { type: 'object', properties: { ok: { type: 'boolean' }, info: { type: 'string' }, error: { type: 'string' } }, additionalProperties: false },
+            render: (_args, value) => [{ type: 'text', text: value.ok ? (value.info || '{}') : (value.error || '媒体信息不可用。') }],
+        },
+        async execute(args, exec) {
+            const attachment = db.attachmentById(args.attachment_id);
+            const agentId = String(exec.agent?.id || '');
+            if (!attachment || !isAllowed(agentId, args.attachment_id))
+                return { ok: false, error: '当前 QQ 消息没有权限访问这个附件。' };
+            const info = {
+                attachmentId: attachment.id, kind: attachment.kind, filename: attachment.filename,
+                contentType: attachment.contentType || null, sizeBytes: attachment.sizeBytes,
+            };
+            if (attachment.localPath) {
+                try {
+                    info.fileSize = Number((await stat(attachment.localPath)).size);
+                }
+                catch { }
+                if (attachment.kind === 'video' || attachment.kind === 'voice' || attachment.kind === 'audio') {
+                    try {
+                        const result = await execFile('ffprobe', ['-v', 'quiet', '-print_format', 'json', '-show_format', '-show_streams', attachment.localPath], { timeout: 10_000, signal: exec.signal });
+                        info.ffprobe = JSON.parse(result.stdout);
+                    }
+                    catch {
+                        info.ffprobe = 'ffprobe 不可用或媒体格式无法探测。';
+                    }
+                }
+            }
+            return { ok: true, info: JSON.stringify(info, null, 2) };
+        },
+    });
+    const disposeRead = ctx.tools.register(readFileTool);
+    const disposeInfo = ctx.tools.register(mediaInfoTool);
+    return () => { disposeInfo(); disposeRead(); };
+}

package/lib/media/store.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { LoggerLike, QQAttachmentInput, StoredAttachmentSummary } from '../types.js';
+import type { QQChatDatabase } from '../storage/db.js';
+export declare class QQMediaStore {
+    private readonly db;
+    private readonly ctx?;
+    private readonly logger;
+    readonly root: string;
+    constructor(db: QQChatDatabase, ctx?: Context | undefined, logger?: LoggerLike);
+    ingest(accountId: number, messageId: string, attachments: QQAttachmentInput[]): Promise<StoredAttachmentSummary[]>;
+    cleanup(): Promise<void>;
+    private download;
+    private saveImageRef;
+}

package/lib/media/store.js

@@ -0,0 +1,176 @@
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const MAX_FILE_BYTES = 50 * 1024 * 1024;
+const MAX_MESSAGE_BYTES = 100 * 1024 * 1024;
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export class QQMediaStore {
+    db;
+    ctx;
+    logger;
+    root;
+    constructor(db, ctx, logger = console) {
+        this.db = db;
+        this.ctx = ctx;
+        this.logger = logger;
+        this.root = join(dirname(db.path), 'media');
+    }
+    async ingest(accountId, messageId, attachments) {
+        const result = [];
+        let messageBytes = 0;
+        for (const [sourceIndex, input] of attachments.slice(0, 12).entries()) {
+            try {
+                if (input.attachmentId) {
+                    const existingById = this.db.attachmentById(input.attachmentId);
+                    if (existingById?.localPath) {
+                        try {
+                            await access(existingById.localPath);
+                            this.db.extendAttachment(existingById.id, Date.now() + RETENTION_MS);
+                            result.push({ ...existingById, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId || existingById.sourceFileId, sourceIndex });
+                            continue;
+                        }
+                        catch { }
+                    }
+                }
+                const reusable = this.db.findReusableAttachment(accountId, messageId, input.platformFileId, input.kind);
+                if (reusable?.localPath) {
+                    try {
+                        await access(reusable.localPath);
+                        this.db.extendAttachment(reusable.id, Date.now() + RETENTION_MS);
+                        result.push({ ...reusable, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId || reusable.sourceFileId, sourceIndex });
+                        continue;
+                    }
+                    catch { }
+                }
+                const downloaded = await this.download(input, messageBytes);
+                if (!downloaded)
+                    continue;
+                messageBytes += downloaded.data.byteLength;
+                const id = `qqatt-${randomUUID()}`;
+                const extension = safeExtension(input.filename, input.contentType);
+                await mkdir(this.root, { recursive: true, mode: 0o700 });
+                const path = join(this.root, `${id}${extension}`);
+                await writeFile(path, downloaded.data, { mode: 0o600 });
+                const imageRef = await this.saveImageRef(input, downloaded.data);
+                const kind = input.kind || inferKind(input.contentType, input.filename);
+                const summary = {
+                    id, kind, filename: safeFilename(input.filename), contentType: input.contentType,
+                    sizeBytes: downloaded.data.byteLength, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId, sourceIndex, localPath: path, imageRef,
+                };
+                this.db.saveAttachment({ id, accountId, sourceMessageId: messageId, sourceFileId: input.platformFileId,
+                    kind, filename: summary.filename, contentType: input.contentType, sizeBytes: summary.sizeBytes,
+                    localPath: path, imageRef, expiresAt: Date.now() + RETENTION_MS });
+                result.push(summary);
+            }
+            catch (error) {
+                this.logger.warn?.(`[dsh-qqchat] QQ media ingest failed for ${safeFilename(input.filename)}: ${error instanceof Error ? error.message : String(error)}`);
+                // Media is optional input. The text turn must remain usable when a download fails.
+            }
+        }
+        return result;
+    }
+    async cleanup() {
+        const cutoff = Date.now();
+        this.db.expireQuoteIndex(cutoff);
+        this.db.expireAttachments(cutoff);
+        for (const path of this.db.expiredAttachmentPaths(cutoff)) {
+            try {
+                await rm(path, { force: true });
+                this.db.markAttachmentDeleted(path);
+            }
+            catch {
+                // Keep the expired row for the next sweep if the physical object is busy.
+            }
+        }
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+    }
+    async download(input, currentBytes) {
+        const source = input.sourceUrl;
+        if (!source)
+            return undefined;
+        let url = source;
+        for (let redirect = 0; redirect <= 3; redirect++) {
+            const parsed = new URL(url);
+            if (parsed.protocol !== 'https:')
+                throw new Error('QQ media URL must use HTTPS');
+            await assertPublicHost(parsed.hostname);
+            const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(20_000) });
+            if ([301, 302, 303, 307, 308].includes(response.status)) {
+                const location = response.headers.get('location');
+                if (!location)
+                    return undefined;
+                url = new URL(location, url).toString();
+                continue;
+            }
+            if (!response.ok)
+                return undefined;
+            const length = Number(response.headers.get('content-length') || 0);
+            if (length > MAX_FILE_BYTES || currentBytes + length > MAX_MESSAGE_BYTES)
+                throw new Error('QQ media size limit exceeded');
+            const data = new Uint8Array(await response.arrayBuffer());
+            if (data.byteLength > MAX_FILE_BYTES || currentBytes + data.byteLength > MAX_MESSAGE_BYTES)
+                throw new Error('QQ media size limit exceeded');
+            return { data };
+        }
+        return undefined;
+    }
+    async saveImageRef(input, data) {
+        const service = this.ctx?.get('attachments');
+        const mediaType = sniffImageType(data);
+        if (!service || !mediaType)
+            return undefined;
+        try {
+            return await service.saveImage({ data, mediaType, name: safeFilename(input.filename) });
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+async function assertPublicHost(hostname) {
+    const addresses = isIP(hostname) ? [hostname] : (await lookup(hostname, { all: true })).map(item => item.address);
+    for (const address of addresses) {
+        if (isPrivateAddress(address))
+            throw new Error('QQ media URL resolves to a private address');
+    }
+}
+function isPrivateAddress(address) {
+    if (address === '::1' || address === '0.0.0.0' || address === '::')
+        return true;
+    if (address.includes(':'))
+        return address === '::1' || address.toLowerCase().startsWith('fc') || address.toLowerCase().startsWith('fd') || address.toLowerCase().startsWith('fe8') || address.toLowerCase().startsWith('fe9') || address.toLowerCase().startsWith('fea') || address.toLowerCase().startsWith('feb');
+    const parts = address.split('.').map(Number);
+    const [a, b] = parts;
+    return parts.length === 4 && (a === 10 || a === 127 || (a === 172 && b !== undefined && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254));
+}
+function sniffImageType(data) {
+    if (data.length >= 8 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47)
+        return 'image/png';
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff)
+        return 'image/jpeg';
+    if (data.length >= 6 && new TextDecoder().decode(data.slice(0, 6)) === 'GIF89a')
+        return 'image/gif';
+    if (data.length >= 12 && new TextDecoder().decode(data.slice(0, 4)) === 'RIFF' && new TextDecoder().decode(data.slice(8, 12)) === 'WEBP')
+        return 'image/webp';
+    return undefined;
+}
+function safeFilename(value) { return basename(value || 'QQ附件').replace(/[^\p{L}\p{N}._-]+/gu, '_').slice(0, 160) || 'QQ附件'; }
+function safeExtension(filename, contentType) {
+    const ext = extname(filename).replace(/[^a-zA-Z0-9.]/g, '').slice(0, 12);
+    if (ext)
+        return ext.toLowerCase();
+    const typeExtension = contentType?.split('/')[1];
+    return typeExtension ? `.${typeExtension.replace(/[^a-zA-Z0-9]/g, '')}` : '.bin';
+}
+function inferKind(contentType, filename = '') {
+    const value = `${contentType || ''} ${filename}`.toLowerCase();
+    if (value.includes('video') || /\.(mp4|mov|avi|mkv|webm)$/u.test(value))
+        return 'video';
+    if (value.includes('audio') || /\.(mp3|wav|ogg|m4a|amr|silk)$/u.test(value))
+        return 'voice';
+    if (value.includes('image') || /\.(png|jpe?g|gif|webp|bmp|heic)$/u.test(value))
+        return 'image';
+    return 'file';
+}