@tencent-connect/dsh-qqbot 0.4.0 → 0.5.1

package/dist/media/send-file-tool.js

@@ -0,0 +1,150 @@
+/**
+ * 内置 qqbot_send_file 工具 — 将本地文件发送给 QQ 用户或群。
+ *
+ *   - 发送目标默认自动定位（exec.agent → SessionManager.findByAgent → replyTarget），
+ *     无需模型手动传 openid；显式 target 参数作为覆盖。
+ *   - 按扩展名分发到 SDK 的 sendImage / sendVideo / sendVoice / sendFile。
+ *   - 路径白名单：默认只允许访问 media 目录 + agent cwd，可开关 + 扩展白名单。
+ */
+import { existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { MEDIA_ROOT } from "./media-cleaner.js";
+/** 工具名（qqbot 前缀避免与其他通道的同名工具冲突） */
+export const SEND_FILE_TOOL_NAME = 'qqbot_send_file';
+const DESCRIPTION = 'Send a local file (image, video, voice, or generic file) to the QQ user or group '
+    + 'of the current conversation. Pass the absolute path of a file that already exists on disk. '
+    + 'Use this when the user asks you to deliver a generated file (chart, report, exported data, '
+    + 'screenshot, etc.) or to send an existing media/file back to them.';
+const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp']);
+const VIDEO_EXTS = new Set(['.mp4', '.mov', '.avi', '.mkv', '.webm']);
+const VOICE_EXTS = new Set(['.mp3', '.wav', '.ogg', '.aac', '.silk', '.amr']);
+/** 解析显式 target（"c2c:openid" / "group:openid"），非法返回 undefined */
+function parseTarget(input) {
+    const idx = input.indexOf(':');
+    if (idx <= 0)
+        return undefined;
+    const scope = input.slice(0, idx);
+    const targetId = input.slice(idx + 1);
+    if (!targetId || (scope !== 'c2c' && scope !== 'group'))
+        return undefined;
+    return { scope, targetId };
+}
+/** 判断 filePath 是否位于 root 目录内（含 root 本身） */
+function isWithinRoot(filePath, root) {
+    const rel = relative(resolve(root), filePath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/** 路径白名单校验：restrictPaths 关闭时放行任意路径，否则限定 media + cwd + extraRoots */
+function isPathAllowed(filePath, config, cwd) {
+    if (!config.restrictPaths)
+        return true;
+    const roots = [MEDIA_ROOT, cwd, ...config.extraRoots];
+    return roots.some((root) => isWithinRoot(filePath, root));
+}
+/** 注册 qqbot_send_file 工具（tools 服务缺失时优雅降级，不阻断插件启动） */
+export function registerSendFileTool(ctx, bot, manager, config, logger) {
+    const tools = ctx.get('tools');
+    if (!tools?.register) {
+        logger.warn('im-qqbot: tools 服务不可用，qqbot_send_file 工具未注册');
+        return;
+    }
+    const cwd = config.cwd || process.cwd();
+    const definition = {
+        name: SEND_FILE_TOOL_NAME,
+        description: DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                file_path: {
+                    type: 'string',
+                    description: 'Absolute path to the local file to send (image/video/voice/generic file).',
+                },
+                target: {
+                    type: 'string',
+                    description: 'Optional send target as "c2c:openid" or "group:openid". Omit to send to the current conversation.',
+                },
+            },
+            required: ['file_path'],
+            additionalProperties: false,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    fileName: { type: 'string' },
+                    fileSize: { type: 'integer' },
+                    target: { type: 'string' },
+                    fileUuid: { type: 'string' },
+                    messageId: { type: 'string' },
+                },
+                required: ['fileName', 'fileSize', 'target', 'fileUuid'],
+                additionalProperties: false,
+            },
+            render: (_args, value) => {
+                const v = value;
+                return [{ type: 'text', text: `已发送 ${v.fileName} → ${v.target}` }];
+            },
+        },
+        async execute(args, exec) {
+            const { file_path, target } = args;
+            if (typeof file_path !== 'string' || file_path.length === 0) {
+                throw new Error('qqbot_send_file: `file_path` must be a non-empty string');
+            }
+            // 1. 解析发送目标：显式 target > 当前会话（exec.agent → SessionRecord）
+            let replyTarget;
+            if (target !== undefined && target !== '') {
+                replyTarget = parseTarget(target);
+                if (replyTarget === undefined) {
+                    throw new Error(`qqbot_send_file: target 格式错误，需要 c2c:openid 或 group:openid，收到: ${target}`);
+                }
+            }
+            else if (exec.agent !== undefined) {
+                replyTarget = manager.findByAgent(exec.agent)?.replyTarget;
+            }
+            if (replyTarget === undefined) {
+                throw new Error('qqbot_send_file: 无法确定发送目标，请显式传 target 参数');
+            }
+            // 2. 校验文件 + 路径白名单
+            const absPath = resolve(file_path);
+            if (!isPathAllowed(absPath, config.sendFile, cwd)) {
+                throw new Error(`qqbot_send_file: file_path 不在允许的目录内: ${absPath}`);
+            }
+            if (!existsSync(absPath)) {
+                throw new Error(`qqbot_send_file: 文件不存在: ${absPath}`);
+            }
+            const info = await stat(absPath);
+            if (!info.isFile()) {
+                throw new Error(`qqbot_send_file: 路径不是普通文件: ${absPath}`);
+            }
+            // 3. 按扩展名分类发送
+            const fileName = basename(absPath);
+            const ext = absPath.slice(absPath.lastIndexOf('.')).toLowerCase();
+            const source = { localPath: absPath };
+            let result;
+            if (IMAGE_EXTS.has(ext)) {
+                result = await bot.sendImage(replyTarget, source);
+            }
+            else if (VIDEO_EXTS.has(ext)) {
+                result = await bot.sendVideo(replyTarget, source);
+            }
+            else if (VOICE_EXTS.has(ext)) {
+                result = await bot.sendVoice(replyTarget, source);
+            }
+            else {
+                result = await bot.sendFile(replyTarget, source, { fileName });
+            }
+            logger.info(`im-qqbot: qqbot_send_file 发送 ${fileName} (${info.size} bytes) → ${replyTarget.scope}:${replyTarget.targetId}`);
+            return {
+                fileName,
+                fileSize: info.size,
+                target: `${replyTarget.scope}:${replyTarget.targetId}`,
+                fileUuid: result.upload.file_uuid,
+                ...(result.message?.id !== undefined ? { messageId: result.message.id } : {}),
+            };
+        },
+    };
+    tools.register(definition);
+    logger.info('im-qqbot: qqbot_send_file 工具已注册');
+}
+//# sourceMappingURL=send-file-tool.js.map

package/dist/media/send-file-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-file-tool.js","sourceRoot":"","sources":["../../src/media/send-file-tool.ts"],"names":[],"mappings":"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"}

package/dist/media/vision-tool.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { VisionConfig } from '../config.ts';
+import type { Logger } from '../types.ts';
+/** 工具名（qqbot 前缀避免与外部 describe-image 包的同名工具冲突） */
+export declare const DESCRIBE_IMAGE_TOOL_NAME = "qqbot_describe_image";
+/**
+ * 启动时检查 settings.yaml 里 vision 模型的 input 模态是否声明了 image。
+ *
+ * 模型配置界面不暴露 `input` 字段，用户通过界面配置的视觉模型默认是纯文本，
+ * 会导致 pi-ai adapter 拒绝图片输入。这里在启动时兜底：未声明 image 时自动补 `[text, image]`。
+ * 幂等（已声明则跳过），解析/写入失败仅 warn 不阻断启动。
+ */
+export declare function ensureVisionInputModal(vision: VisionConfig, logger: Logger): void;
+/** 注册 qqbot_describe_image 工具（服务缺失时优雅降级，不阻断插件启动） */
+export declare function registerDescribeImageTool(ctx: Context, vision: VisionConfig, logger: Logger): void;
+//# sourceMappingURL=vision-tool.d.ts.map

package/dist/media/vision-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-tool.d.ts","sourceRoot":"","sources":["../../src/media/vision-tool.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AASnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA2B1C,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAwH/D;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAwCjF;AAED,oDAAoD;AACpD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAqElG"}

package/dist/media/vision-tool.js

@@ -0,0 +1,241 @@
+/**
+ * 内置 qqbot_describe_image 视觉工具。
+ *
+ * 复用 dsh 生态的 llm + attachments 服务：
+ *   1. 加载图片（本地绝对路径 / http URL）→ magic bytes 嗅探 mediaType
+ *   2. attachments.saveImage → ImageAttachmentRef（字节不进 session log）
+ *   3. createUserMessage(ImageBlock + text) → llm.stream → BlockAssembler 收集文本
+ *
+ * 手写 ToolDefinition（标准 JSON Schema），避免引入 dsh-tools 的 8 个 peer 依赖。
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
+/** 工具名（qqbot 前缀避免与外部 describe-image 包的同名工具冲突） */
+export const DESCRIBE_IMAGE_TOOL_NAME = 'qqbot_describe_image';
+const DESCRIPTION = 'Inspect one image and return the text the user needs. The image is a local absolute path '
+    + '(downloaded by the QQ bot) or an http(s) URL. Use this when the user references an image, '
+    + 'or when a task needs OCR, chart/diagram reading, screenshot or UI analysis, translation of '
+    + 'image text, or photo understanding. Always pass an explicit `prompt` with a precise '
+    + 'instruction (e.g. "transcribe all text", "extract the table as CSV", "translate the text '
+    + 'into Chinese") instead of relying on the generic default.';
+/** 图片 magic bytes 嗅探 → 标准 MIME（不信声明，安全底线） */
+function sniffImageMediaType(bytes) {
+    if (bytes.length < 12)
+        return null;
+    // PNG: 89 50 4E 47
+    if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47)
+        return 'image/png';
+    // JPEG: FF D8 FF
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    // GIF: 47 49 46 38
+    if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38)
+        return 'image/gif';
+    // WEBP: 52 49 46 46 .. 57 45 42 50
+    if (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46
+        && bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50)
+        return 'image/webp';
+    return null;
+}
+/** 加载图片字节（本地路径 / http URL），校验大小 + 嗅探 MIME */
+async function loadImageBytes(image, maxBytes, signal) {
+    let data;
+    if (/^https?:\/\//i.test(image)) {
+        const resp = await fetch(image, { signal, redirect: 'error' });
+        if (!resp.ok)
+            throw new Error(`qqbot_describe_image: download failed (HTTP ${resp.status})`);
+        const buf = Buffer.from(await resp.arrayBuffer());
+        if (buf.length > maxBytes)
+            throw new Error(`qqbot_describe_image: image too large (${buf.length} bytes)`);
+        data = new Uint8Array(buf);
+    }
+    else {
+        const info = await stat(image).catch(() => null);
+        if (!info?.isFile())
+            throw new Error(`qqbot_describe_image: image file not found: ${image}`);
+        if (info.size > maxBytes)
+            throw new Error(`qqbot_describe_image: image too large (${info.size} bytes)`);
+        data = new Uint8Array(await readFile(image));
+    }
+    const mediaType = sniffImageMediaType(data);
+    if (mediaType === null)
+        throw new Error('qqbot_describe_image: unrecognized image format (png/jpeg/gif/webp only)');
+    return { data, mediaType };
+}
+/** 将终端 finish reason 转成辅助调用失败 */
+function finishError(finish) {
+    switch (finish.kind) {
+        case 'error':
+        case 'aborted':
+            return new Error(finish.failure.message);
+        default:
+            return undefined;
+    }
+}
+/** 调视觉模型描述图片，返回纯文本 */
+async function callVision(llm, vision, prompt, imageRef, signal) {
+    const message = createUserMessage({
+        content: [
+            { type: 'image', attachment: imageRef },
+            { type: 'text', text: prompt },
+        ],
+        source: { kind: 'plugin', plugin: 'dsh-im-qqbot' },
+    });
+    const options = {
+        provider: vision.provider,
+        model: vision.model,
+        messages: [message],
+        maxTokens: vision.maxTokens,
+        signal,
+    };
+    const assembler = new BlockAssembler();
+    for await (const chunk of llm.stream(options)) {
+        assembler.push(chunk);
+    }
+    const terminalError = finishError(assembler.finish);
+    if (terminalError !== undefined)
+        throw terminalError;
+    const text = assembler.blocks()
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join(' ')
+        .trim();
+    if (text.length === 0)
+        throw new Error('qqbot_describe_image: vision model returned no text');
+    return text;
+}
+/** 展开 `~`/`~/`/`~\` 前缀 */
+function expandHomePath(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+/**
+ * 解析 DSH_HOME 的优先级与跨平台处理：
+ * 显式配置 > `$DSH_HOME`（空/空白视为未设置）> `~/.dsh`，展开 `~` 后 resolve 为绝对路径。
+ */
+function resolveDshHome() {
+    const fromEnv = process.env.DSH_HOME;
+    const selected = fromEnv !== undefined && fromEnv.trim().length > 0
+        ? fromEnv
+        : join(homedir(), '.dsh');
+    return resolve(expandHomePath(selected));
+}
+/**
+ * 启动时检查 settings.yaml 里 vision 模型的 input 模态是否声明了 image。
+ *
+ * 模型配置界面不暴露 `input` 字段，用户通过界面配置的视觉模型默认是纯文本，
+ * 会导致 pi-ai adapter 拒绝图片输入。这里在启动时兜底：未声明 image 时自动补 `[text, image]`。
+ * 幂等（已声明则跳过），解析/写入失败仅 warn 不阻断启动。
+ */
+export function ensureVisionInputModal(vision, logger) {
+    if (!vision.enabled || !vision.provider || !vision.model)
+        return;
+    const settingsPath = resolve(resolveDshHome(), 'settings.yaml');
+    try {
+        if (!existsSync(settingsPath))
+            return;
+        // YAML 禁止 tab 缩进（配置界面/编辑器可能写入），读入时把行首 tab 规范化为空格
+        const raw = readFileSync(settingsPath, 'utf8');
+        const normalized = raw.replace(/^\t+/gm, (tabs) => '  '.repeat(tabs.length));
+        const doc = yaml.load(normalized);
+        if (doc === null || typeof doc !== 'object')
+            return;
+        const piAi = doc['llm-pi-ai'];
+        const provider = piAi?.providers?.[vision.provider];
+        const models = provider?.models;
+        if (!Array.isArray(models)) {
+            logger.warn(`im-qqbot: settings.yaml 未找到 llm-pi-ai.providers.${vision.provider}.models，请手动确认 vision 模型已声明 image 输入`);
+            return;
+        }
+        const model = models.find((m) => typeof m === 'object' && m !== null && m.id === vision.model);
+        if (model === undefined) {
+            logger.warn(`im-qqbot: settings.yaml 未找到 vision 模型 ${vision.model}，请手动确认已声明 image 输入`);
+            return;
+        }
+        const input = model.input;
+        if (Array.isArray(input) && input.includes('image'))
+            return; // 已声明，幂等跳过
+        model.input = ['text', 'image'];
+        writeFileSync(settingsPath, yaml.dump(doc), 'utf8');
+        logger.info(`im-qqbot: 已为 vision 模型补充 input: [text, image] (${vision.provider}/${vision.model})`);
+    }
+    catch (err) {
+        logger.warn(`im-qqbot: 检查 settings.yaml vision input 失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** 注册 qqbot_describe_image 工具（服务缺失时优雅降级，不阻断插件启动） */
+export function registerDescribeImageTool(ctx, vision, logger) {
+    if (!vision.enabled)
+        return;
+    if (!vision.provider || !vision.model) {
+        logger.warn('im-qqbot: vision.provider/model 未配置，qqbot_describe_image 工具未注册');
+        return;
+    }
+    const tools = ctx.get('tools');
+    const llm = ctx.get('llm');
+    const attachments = ctx.get('attachments');
+    if (!tools?.register || !llm?.stream || !attachments?.saveImage) {
+        logger.warn('im-qqbot: tools/llm/attachments 服务不可用，qqbot_describe_image 工具未注册');
+        return;
+    }
+    const definition = {
+        name: DESCRIBE_IMAGE_TOOL_NAME,
+        description: DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                image: {
+                    type: 'string',
+                    description: 'Absolute path to a local image file, or an http(s) URL of the image.',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Your precise instruction for the vision model about this image.',
+                },
+            },
+            required: ['image'],
+            additionalProperties: false,
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    text: { type: 'string' },
+                    model: { type: 'string' },
+                    image: { type: 'string' },
+                    mimeType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/gif', 'image/webp'] },
+                    bytes: { type: 'integer' },
+                },
+                required: ['text', 'model', 'image', 'mimeType', 'bytes'],
+                additionalProperties: false,
+            },
+            render: (_args, value) => [
+                { type: 'text', text: value.text },
+            ],
+        },
+        async execute(args, exec) {
+            const { image, prompt } = args;
+            if (typeof image !== 'string' || image.length === 0) {
+                throw new Error('qqbot_describe_image: `image` must be a non-empty string');
+            }
+            const loaded = await loadImageBytes(image, vision.maxBytes, exec.signal);
+            const ref = await attachments.saveImage({
+                data: loaded.data,
+                mediaType: loaded.mediaType,
+                name: /^https?:\/\//i.test(image) ? undefined : basename(image),
+            });
+            const text = await callVision(llm, vision, prompt ?? vision.defaultPrompt, ref, exec.signal);
+            return { text, model: vision.model, image, mimeType: loaded.mediaType, bytes: loaded.data.length };
+        },
+    };
+    tools.register(definition);
+    logger.info(`im-qqbot: qqbot_describe_image 工具已注册 (provider=${vision.provider} model=${vision.model})`);
+}
+//# sourceMappingURL=vision-tool.js.map

package/dist/media/vision-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-tool.js","sourceRoot":"","sources":["../../src/media/vision-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,IAAI,MAAM,SAAS,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoCzE,iDAAiD;AACjD,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D,MAAM,WAAW,GACf,2FAA2F;MACzF,4FAA4F;MAC5F,6FAA6F;MAC7F,sFAAsF;MACtF,2FAA2F;MAC3F,2DAA2D,CAAC;AAEhE,6CAA6C;AAC7C,SAAS,mBAAmB,CAAC,KAAiB;IAC5C,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IACnC,mBAAmB;IACnB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACzG,iBAAiB;IACjB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IACrF,mBAAmB;IACnB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACzG,mCAAmC;IACnC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;WAC/E,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAC7G,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6CAA6C;AAC7C,KAAK,UAAU,cAAc,CAC3B,KAAa,EACb,QAAgB,EAChB,MAAmB;IAEnB,IAAI,IAAgB,CAAC;IACrB,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAC7F,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QAClD,IAAI,GAAG,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,CAAC,MAAM,SAAS,CAAC,CAAC;QAC1G,IAAI,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,KAAK,EAAE,CAAC,CAAC;QAC7F,IAAI,IAAI,CAAC,IAAI,GAAG,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC;QACxG,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,SAAS,KAAK,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IACpH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,iCAAiC;AACjC,SAAS,WAAW,CAAC,MAAoB;IACvC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,OAAO,CAAC;QACb,KAAK,SAAS;YACZ,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,sBAAsB;AACtB,KAAK,UAAU,UAAU,CACvB,GAAmB,EACnB,MAAoB,EACpB,MAAc,EACd,QAA4B,EAC5B,MAAmB;IAEnB,MAAM,OAAO,GAAG,iBAAiB,CAAC;QAChC,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE;YACvC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;SAC/B;QACD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE;KACnD,CAAC,CAAC;IAEH,MAAM,OAAO,GAAoB;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,MAAM;KACP,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,cAAc,EAAE,CAAC;IACvC,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IACD,MAAM,aAAa,GAAG,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,aAAa,KAAK,SAAS;QAAE,MAAM,aAAa,CAAC;IAErD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAoD,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;SAC1F,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,CAAC;IACV,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC9F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0BAA0B;AAC1B,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,cAAc;IACrB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;IACrC,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACjE,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAoB,EAAE,MAAc;IACzE,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO;IAEjE,MAAM,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,EAAE,eAAe,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAAE,OAAO;QAEtC,iDAAiD;QACjD,MAAM,GAAG,GAAG,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAmC,CAAC;QACpE,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO;QAEpD,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAwD,CAAC;QACrF,MAAM,QAAQ,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAqC,CAAC;QACxF,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,mDAAmD,MAAM,CAAC,QAAQ,qCAAqC,CAAC,CAAC;YACrH,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CACvB,CAAC,CAAC,EAAgC,EAAE,CAClC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAA6B,CAAC,EAAE,KAAK,MAAM,CAAC,KAAK,CAC5F,CAAC;QACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,yCAAyC,MAAM,CAAC,KAAK,oBAAoB,CAAC,CAAC;YACvF,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,CAAC,WAAW;QAExE,KAAK,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,kDAAkD,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IACpG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,+CAA+C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjH,CAAC;AACH,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,yBAAyB,CAAC,GAAY,EAAE,MAAoB,EAAE,MAAc;IAC1F,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO;IAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;QAC9E,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAkC,CAAC;IAChE,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAA+B,CAAC;IACzD,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,aAAa,CAAoC,CAAC;IAC9E,IAAI,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;QAChF,OAAO;IACT,CAAC;IAED,MAAM,UAAU,GAAG;QACjB,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EAAE,WAAW;QACxB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sEAAsE;iBACpF;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iEAAiE;iBAC/E;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;YACnB,oBAAoB,EAAE,KAAK;SAC5B;QACD,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE;oBAC1F,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;iBAC3B;gBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC;gBACzD,oBAAoB,EAAE,KAAK;aAC5B;YACD,MAAM,EAAE,CAAC,KAAc,EAAE,KAAc,EAAkB,EAAE,CAAC;gBAC1D,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAG,KAA0B,CAAC,IAAI,EAAE;aACzD;SACF;QACD,KAAK,CAAC,OAAO,CAAC,IAAa,EAAE,IAA6B;YACxD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAyB,CAAC;YACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;YAC9E,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACzE,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC;gBACtC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;aAChE,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,IAAI,MAAM,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7F,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACrG,CAAC;KACF,CAAC;IAEF,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC3B,MAAM,CAAC,IAAI,CAAC,kDAAkD,MAAM,CAAC,QAAQ,UAAU,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;AAC1G,CAAC"}

package/dist/middleware/attachment.d.ts

@@ -1,11 +1,11 @@
 /**
- * 附件下载中间件 — 在中间件链中下载 file 附件
+ * 富媒体下载中间件 — 在中间件链中下载 image/video/file 附件
  *
  * 结果写入 ctx.state.downloadedFiles，供 handleInbound 读取。
  * 下载失败不阻断消息（记录告警后放行），确保附件异常不影响正常文本处理。
  */
 import type { MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
-import type { ImQQBotConfig } from '../config.js';
-import type { Logger } from '../types.js';
+import type { ImQQBotConfig } from '../config.ts';
+import type { Logger } from '../types.ts';
 export declare function attachmentProcessor(config: ImQQBotConfig, logger: Logger): (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
 //# sourceMappingURL=attachment.d.ts.map

package/dist/middleware/attachment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../../src/middleware/attachment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AAEzD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,IACzD,KAAK,iBAAiB,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAchF"}
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../../src/middleware/attachment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAmC,MAAM,aAAa,CAAC;AAE3E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,IACzD,KAAK,iBAAiB,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CA4BhF"}

package/dist/middleware/attachment.js

@@ -1,12 +1,25 @@
-import { downloadFileAttachments } from '../transport/attachment.js';
+import { downloadMediaAttachments } from "../transport/attachment.js";
 export function attachmentProcessor(config, logger) {
     return async (ctx, next) => {
         const msg = ctx.message;
-        const cwd = config.cwd || process.cwd();
-        const messageId = msg.messageId ?? 'unknown';
         try {
-            const downloaded = await downloadFileAttachments(msg.attachments, cwd, messageId, logger);
+            // 当前消息附件
+            const downloaded = await downloadMediaAttachments(msg.attachments, config.media, logger);
             ctx.state.downloadedFiles = downloaded;
+            // 引用消息附件：转成 RawAttachment 结构复用下载（voice 由 downloadMediaAttachments 自动跳过）
+            const quoteAttachments = ctx.state.quote?.attachments;
+            if (quoteAttachments && quoteAttachments.length > 0) {
+                const rawQuote = quoteAttachments
+                    .filter(a => a.url)
+                    .map((a) => ({
+                    content_type: a.contentType ?? '',
+                    filename: a.filename ?? '',
+                    size: 0,
+                    url: a.url,
+                }));
+                const downloadedQuote = await downloadMediaAttachments(rawQuote, config.media, logger);
+                ctx.state.downloadedQuoteFiles = downloadedQuote;
+            }
         }
         catch (err) {
             logger.warn(`im-qqbot: attachment download failed: ${err instanceof Error ? err.message : String(err)}`);

package/dist/middleware/attachment.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachment.js","sourceRoot":"","sources":["../../src/middleware/attachment.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAIrE,MAAM,UAAU,mBAAmB,CAAC,MAAqB,EAAE,MAAc;IACvE,OAAO,KAAK,EAAE,GAAsB,EAAE,IAAyB,EAAiB,EAAE;QAChF,MAAM,GAAG,GAAG,GAAG,CAAC,OAAgE,CAAC;QACjF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QACxC,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,SAAS,CAAC;QAE7C,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,uBAAuB,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YAC1F,GAAG,CAAC,KAAK,CAAC,eAAe,GAAG,UAAU,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3G,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"attachment.js","sourceRoot":"","sources":["../../src/middleware/attachment.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAItE,MAAM,UAAU,mBAAmB,CAAC,MAAqB,EAAE,MAAc;IACvE,OAAO,KAAK,EAAE,GAAsB,EAAE,IAAyB,EAAiB,EAAE;QAChF,MAAM,GAAG,GAAG,GAAG,CAAC,OAA4C,CAAC;QAE7D,IAAI,CAAC;YACH,SAAS;YACT,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACzF,GAAG,CAAC,KAAK,CAAC,eAAe,GAAG,UAAU,CAAC;YAEvC,wEAAwE;YACxE,MAAM,gBAAgB,GAAI,GAAG,CAAC,KAA0D,CAAC,KAAK,EAAE,WAAW,CAAC;YAC5G,IAAI,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpD,MAAM,QAAQ,GAAG,gBAAgB;qBAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;qBAClB,GAAG,CAAC,CAAC,CAAC,EAAiB,EAAE,CAAC,CAAC;oBAC1B,YAAY,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;oBACjC,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;oBAC1B,IAAI,EAAE,CAAC;oBACP,GAAG,EAAE,CAAC,CAAC,GAAa;iBACrB,CAAC,CAAC,CAAC;gBACN,MAAM,eAAe,GAAG,MAAM,wBAAwB,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBACvF,GAAG,CAAC,KAAK,CAAC,oBAAoB,GAAG,eAAe,CAAC;YACnD,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,yCAAyC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3G,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/question-answer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 待答问题截获中间件 — 在中间件链中截获 ask_user_question 的答案
+ *
+ * 必须放在 concurrencyGuard 之前：答案消息需绕过并发守卫的 merge 缓冲，
+ * 否则会被排队而无法到达 tryAnswer，导致「turn 等答案 ↔ 答案被缓冲」死锁。
+ */
+import type { MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import type { SessionManager } from '../session/index.ts';
+export declare function questionAnswer(manager: SessionManager): (ctx: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+//# sourceMappingURL=question-answer.d.ts.map

package/dist/middleware/question-answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-answer.d.ts","sourceRoot":"","sources":["../../src/middleware/question-answer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,IACtC,KAAK,iBAAiB,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAehF"}

package/dist/middleware/question-answer.js

@@ -0,0 +1,19 @@
+import { cacheMsgId } from "../transport/msgid-cache.js";
+export function questionAnswer(manager) {
+    return async (ctx, next) => {
+        const questionChannel = manager.questionChannel;
+        if (!questionChannel) {
+            await next();
+            return;
+        }
+        if (questionChannel.tryAnswer(ctx.replyTarget.scope, ctx.replyTarget.targetId, ctx.message.content.trim())) {
+            // 答案消息被截获（不再走到 bot.on('message')），在此补录其 msgId，
+            // 供被动回复超限时切换到缓存的最近 msgId。
+            cacheMsgId(ctx.replyTarget.scope, ctx.replyTarget.targetId, ctx.replyTarget.msgId);
+            ctx.stop('question-answer');
+            return;
+        }
+        await next();
+    };
+}
+//# sourceMappingURL=question-answer.js.map

package/dist/middleware/question-answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-answer.js","sourceRoot":"","sources":["../../src/middleware/question-answer.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,UAAU,cAAc,CAAC,OAAuB;IACpD,OAAO,KAAK,EAAE,GAAsB,EAAE,IAAyB,EAAiB,EAAE;QAChF,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAChD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,MAAM,IAAI,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,eAAe,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3G,+CAA+C;YAC/C,0BAA0B;YAC1B,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YACnF,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/dist/model/index.d.ts

@@ -3,8 +3,8 @@
  *
  * 统一的模型发现、路由解析、per-peer 偏好管理。
  */
-export { ModelResolver } from './model-resolver.js';
-export { PrefsStore } from './prefs-store.js';
-export { SettingsReader } from './settings-reader.js';
-export type { ModelRoute, ModelEntry } from './types.js';
+export { ModelResolver } from './model-resolver.ts';
+export { PrefsStore } from './prefs-store.ts';
+export { SettingsReader } from './settings-reader.ts';
+export type { ModelRoute, ModelEntry } from './types.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/model/index.js

@@ -3,7 +3,7 @@
  *
  * 统一的模型发现、路由解析、per-peer 偏好管理。
  */
-export { ModelResolver } from './model-resolver.js';
-export { PrefsStore } from './prefs-store.js';
-export { SettingsReader } from './settings-reader.js';
+export { ModelResolver } from "./model-resolver.js";
+export { PrefsStore } from "./prefs-store.js";
+export { SettingsReader } from "./settings-reader.js";
 //# sourceMappingURL=index.js.map