qq-codex-bridge 0.1.0

package/dist/packages/adapters/qq/src/qq-sender.js

@@ -0,0 +1,241 @@
+import { buildMediaArtifactFromReference, parseQqMediaSegments } from "./qq-media-parser.js";
+const QQ_MARKDOWN_DEFAULT_IMAGE_SIZE = { width: 512, height: 512 };
+export function chunkTextForQq(text, limit = 5000, mode = "plain") {
+    if (mode === "markdown") {
+        return chunkMarkdownTextForQq(text, limit);
+    }
+    const chunks = [];
+    for (let index = 0; index < text.length; index += limit) {
+        chunks.push(text.slice(index, index + limit));
+    }
+    return chunks.length > 0 ? chunks : [""];
+}
+export class QqSender {
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    async deliver(draft) {
+        const providerMessageId = await this.deliverThroughApiClient(draft);
+        return {
+            jobId: draft.draftId,
+            sessionKey: draft.sessionKey,
+            providerMessageId,
+            deliveredAt: draft.createdAt
+        };
+    }
+    async sendTextSegment(target, text, replyToMessageId) {
+        if (!text) {
+            return null;
+        }
+        let lastProviderMessageId = null;
+        const preferMarkdown = shouldUseMarkdownForQq(text);
+        const chunkMode = preferMarkdown ? "markdown" : "plain";
+        for (const chunk of chunkTextForQq(text, 5000, chunkMode)) {
+            if (!chunk) {
+                continue;
+            }
+            if (target.chatType === "c2c") {
+                lastProviderMessageId = await this.apiClient.sendC2CMessage(target.peerId, chunk, replyToMessageId, {
+                    preferMarkdown
+                });
+                continue;
+            }
+            if (target.chatType === "group") {
+                lastProviderMessageId = await this.apiClient.sendGroupMessage(target.peerId, chunk, replyToMessageId, {
+                    preferMarkdown
+                });
+                continue;
+            }
+        }
+        return lastProviderMessageId;
+    }
+    async sendMediaArtifact(target, artifact, replyToMessageId) {
+        if (target.chatType === "c2c" && this.apiClient?.sendC2CMediaArtifact) {
+            return this.apiClient.sendC2CMediaArtifact(target.peerId, artifact, replyToMessageId);
+        }
+        if (target.chatType === "group" && this.apiClient?.sendGroupMediaArtifact) {
+            return this.apiClient.sendGroupMediaArtifact(target.peerId, artifact, replyToMessageId);
+        }
+        return null;
+    }
+    buildMediaFailureText(artifact, error) {
+        const filename = artifact.originalName || artifact.localPath || artifact.sourceUrl || "未知附件";
+        const reason = error instanceof Error ? error.message : String(error);
+        return `媒体发送失败：${filename}\n${reason}`;
+    }
+    async deliverThroughApiClient(draft) {
+        if (!this.apiClient) {
+            return null;
+        }
+        const replyToMessageId = draft.replyToMessageId ?? draft.draftId;
+        const target = parseSessionTarget(draft.sessionKey);
+        let lastProviderMessageId = null;
+        const deliveredArtifactKeys = new Set();
+        for (const segment of parseQqMediaSegments(draft.text)) {
+            if (segment.type === "text") {
+                lastProviderMessageId = await this.sendTextSegment(target, normalizeTextSegmentForQq(segment.text), replyToMessageId);
+                continue;
+            }
+            const artifact = buildMediaArtifactFromReference(segment.reference);
+            deliveredArtifactKeys.add(buildArtifactKey(artifact));
+            try {
+                lastProviderMessageId = await this.sendMediaArtifact(target, artifact, replyToMessageId);
+            }
+            catch (error) {
+                lastProviderMessageId = await this.sendTextSegment(target, this.buildMediaFailureText(artifact, error), replyToMessageId);
+            }
+        }
+        if (draft.mediaArtifacts?.length) {
+            for (const artifact of draft.mediaArtifacts) {
+                const artifactKey = buildArtifactKey(artifact);
+                if (deliveredArtifactKeys.has(artifactKey)) {
+                    continue;
+                }
+                deliveredArtifactKeys.add(artifactKey);
+                try {
+                    lastProviderMessageId = await this.sendMediaArtifact(target, artifact, replyToMessageId);
+                }
+                catch (error) {
+                    lastProviderMessageId = await this.sendTextSegment(target, this.buildMediaFailureText(artifact, error), replyToMessageId);
+                }
+            }
+        }
+        if (lastProviderMessageId !== null) {
+            return lastProviderMessageId;
+        }
+        return this.sendTextSegment(target, normalizeTextSegmentForQq(draft.text), replyToMessageId);
+    }
+}
+function normalizeTextSegmentForQq(text) {
+    if (!text) {
+        return text;
+    }
+    return text.replace(/!\[(.*?)\]\((https?:\/\/[^)]+)\)/g, (_match, altText, url) => {
+        if (/^#\d+px\s+#\d+px$/i.test(altText.trim())) {
+            return `![${altText}](${url})`;
+        }
+        return `![#${QQ_MARKDOWN_DEFAULT_IMAGE_SIZE.width}px #${QQ_MARKDOWN_DEFAULT_IMAGE_SIZE.height}px](${url})`;
+    });
+}
+function shouldUseMarkdownForQq(text) {
+    if (!text.trim()) {
+        return false;
+    }
+    return (/```[\s\S]*```/.test(text) ||
+        /^\|.+\|\s*$/m.test(text) ||
+        /^\s*#{1,6}\s/m.test(text) ||
+        /^\s*>\s/m.test(text) ||
+        /^\s*[-*+]\s/m.test(text) ||
+        /^\s*\d+\.\s/m.test(text) ||
+        /!\[[^\]]*\]\([^)]+\)/.test(text) ||
+        /`[^`\n]+`/.test(text));
+}
+function chunkMarkdownTextForQq(text, limit) {
+    if (!text) {
+        return [""];
+    }
+    const lines = text.replace(/\r\n/g, "\n").split("\n");
+    const chunks = [];
+    let current = "";
+    let inFence = false;
+    let fenceHeader = "";
+    const pushCurrent = (reopenFence) => {
+        if (!current.trim()) {
+            current = reopenFence && fenceHeader ? `${fenceHeader}\n` : "";
+            return;
+        }
+        let chunk = current;
+        if (inFence && fenceHeader) {
+            if (!chunk.endsWith("\n")) {
+                chunk += "\n";
+            }
+            chunk += "```";
+        }
+        chunks.push(chunk);
+        current = reopenFence && inFence && fenceHeader ? `${fenceHeader}\n` : "";
+    };
+    const appendLine = (line) => {
+        current = current ? `${current}\n${line}` : line;
+    };
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+        const isFenceLine = /^```/.test(trimmedLine);
+        if (!current) {
+            appendLine(line);
+        }
+        else if (`${current}\n${line}`.length > limit) {
+            pushCurrent(true);
+            if (line.length > limit) {
+                const oversizedParts = splitOversizedMarkdownLine(line, limit, inFence, fenceHeader);
+                if (oversizedParts.length > 1) {
+                    chunks.push(...oversizedParts.slice(0, -1));
+                    current = oversizedParts.at(-1) ?? "";
+                }
+                else {
+                    current = oversizedParts[0] ?? "";
+                }
+            }
+            else {
+                appendLine(line);
+            }
+        }
+        else {
+            appendLine(line);
+        }
+        if (isFenceLine) {
+            if (!inFence) {
+                fenceHeader = trimmedLine;
+                inFence = true;
+            }
+            else {
+                inFence = false;
+                fenceHeader = "";
+            }
+        }
+    }
+    if (current.trim()) {
+        if (inFence && fenceHeader) {
+            if (!current.endsWith("\n")) {
+                current += "\n";
+            }
+            current += "```";
+        }
+        chunks.push(current);
+    }
+    return chunks.length > 0 ? chunks : [""];
+}
+function splitOversizedMarkdownLine(line, limit, inFence, fenceHeader) {
+    const parts = [];
+    let rest = line;
+    while (rest.length > limit) {
+        const chunkBody = rest.slice(0, limit);
+        if (inFence && fenceHeader) {
+            parts.push(`${fenceHeader}\n${chunkBody}\n\`\`\``);
+            rest = `${fenceHeader}\n${rest.slice(limit)}`;
+            break;
+        }
+        parts.push(chunkBody);
+        rest = rest.slice(limit);
+    }
+    if (rest) {
+        parts.push(rest);
+    }
+    return parts;
+}
+function parseSessionTarget(sessionKey) {
+    const [, peerKey = ""] = sessionKey.split("::");
+    const segments = peerKey.split(":");
+    return {
+        chatType: segments[1] ?? "",
+        peerId: segments.slice(2).join(":")
+    };
+}
+function buildArtifactKey(artifact) {
+    return [
+        artifact.kind,
+        artifact.localPath || "",
+        artifact.sourceUrl || "",
+        artifact.originalName || ""
+    ].join("::");
+}

package/dist/packages/adapters/qq/src/qq-stt.js

@@ -0,0 +1,189 @@
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import os from "node:os";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function resolveQqSttConfigFromEnv(env) {
+    if (env.QQBOT_STT_ENABLED === "false") {
+        return null;
+    }
+    if (env.QQBOT_STT_PROVIDER === "local-whisper-cpp") {
+        const binaryPath = env.QQBOT_STT_BINARY_PATH;
+        const modelPath = env.QQBOT_STT_MODEL_PATH;
+        if (!binaryPath || !modelPath) {
+            return null;
+        }
+        return {
+            provider: "local-whisper-cpp",
+            binaryPath,
+            modelPath,
+            language: env.QQBOT_STT_LANGUAGE ?? "zh"
+        };
+    }
+    if (env.QQBOT_STT_PROVIDER === "volcengine-flash") {
+        const appId = env.QQBOT_STT_APP_ID;
+        const accessKey = env.QQBOT_STT_ACCESS_KEY;
+        const resourceId = env.QQBOT_STT_RESOURCE_ID;
+        const endpoint = env.QQBOT_STT_ENDPOINT ??
+            "https://openspeech.bytedance.com/api/v3/auc/bigmodel/recognize/flash";
+        if (!appId || !accessKey || !resourceId) {
+            return null;
+        }
+        return {
+            provider: "volcengine-flash",
+            endpoint: endpoint.replace(/\/+$/, ""),
+            appId,
+            accessKey,
+            resourceId,
+            model: env.QQBOT_STT_MODEL ?? "bigmodel"
+        };
+    }
+    const apiKey = env.QQBOT_STT_API_KEY ?? env.OPENAI_API_KEY;
+    if (!apiKey) {
+        return null;
+    }
+    const baseUrl = env.QQBOT_STT_BASE_URL ?? env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+    const model = env.QQBOT_STT_MODEL ?? "whisper-1";
+    return {
+        provider: "openai-compatible",
+        baseUrl: baseUrl.replace(/\/+$/, ""),
+        apiKey,
+        model
+    };
+}
+export async function transcribeAudioFile(audioPath, config, fetchFn = fetch, commandRunner = execFile) {
+    if (config.provider === "local-whisper-cpp") {
+        return transcribeWithLocalWhisperCpp(audioPath, config, commandRunner);
+    }
+    if (config.provider === "volcengine-flash") {
+        return transcribeWithVolcengineFlash(audioPath, config, fetchFn);
+    }
+    const fileBuffer = readFileSync(audioPath);
+    const fileName = path.basename(audioPath);
+    const mimeType = inferAudioMimeType(fileName);
+    const form = new FormData();
+    form.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
+    form.append("model", config.model);
+    const response = await fetchFn(`${config.baseUrl}/audio/transcriptions`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`
+        },
+        body: form
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`QQ STT failed (HTTP ${response.status}): ${detail.slice(0, 300)}`);
+    }
+    const payload = (await response.json());
+    const text = payload.text?.trim();
+    return text || null;
+}
+async function transcribeWithLocalWhisperCpp(audioPath, config, commandRunner) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "qqbot-whisper-"));
+    const outputPrefix = path.join(tempDir, "transcript");
+    const args = [
+        "-m",
+        config.modelPath,
+        "-f",
+        audioPath,
+        "-otxt",
+        "-of",
+        outputPrefix,
+        "-np"
+    ];
+    if (config.language?.trim()) {
+        args.push("-l", config.language.trim());
+    }
+    try {
+        await promisifyCommandRunner(commandRunner)(config.binaryPath, args);
+        const transcriptPath = `${outputPrefix}.txt`;
+        const transcript = (await readFile(transcriptPath, "utf8")).trim();
+        return transcript || null;
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function transcribeWithVolcengineFlash(audioPath, config, fetchFn) {
+    const audioBuffer = readFileSync(audioPath);
+    const requestId = randomUUID();
+    const base64Audio = audioBuffer.toString("base64");
+    const response = await fetchFn(config.endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Api-App-Key": config.appId,
+            "X-Api-Access-Key": config.accessKey,
+            "X-Api-Resource-Id": config.resourceId,
+            "X-Api-Request-Id": requestId,
+            "X-Api-Sequence": "-1"
+        },
+        body: JSON.stringify({
+            user: {
+                uid: config.appId
+            },
+            audio: {
+                data: base64Audio
+            },
+            request: {
+                model_name: config.model
+            }
+        })
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`QQ STT failed (HTTP ${response.status}): ${detail.slice(0, 300)}`);
+    }
+    const payload = (await response.json());
+    const text = extractVolcengineTranscript(payload)?.trim();
+    return text || null;
+}
+function extractVolcengineTranscript(payload) {
+    if ("text" in payload) {
+        return payload.text;
+    }
+    if ("result" in payload) {
+        return payload.result?.text;
+    }
+    return null;
+}
+function promisifyCommandRunner(commandRunner) {
+    if (commandRunner === execFile) {
+        return execFileAsync;
+    }
+    return (file, args) => new Promise((resolve, reject) => {
+        commandRunner(file, args, (error, stdout, stderr) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve({
+                stdout: typeof stdout === "string" ? stdout : String(stdout ?? ""),
+                stderr: typeof stderr === "string" ? stderr : String(stderr ?? "")
+            });
+        });
+    });
+}
+function inferAudioMimeType(fileName) {
+    const extension = path.extname(fileName).toLowerCase();
+    switch (extension) {
+        case ".wav":
+            return "audio/wav";
+        case ".mp3":
+            return "audio/mpeg";
+        case ".ogg":
+            return "audio/ogg";
+        case ".m4a":
+            return "audio/mp4";
+        case ".aac":
+            return "audio/aac";
+        case ".amr":
+            return "audio/amr";
+        default:
+            return "application/octet-stream";
+    }
+}

package/dist/packages/domain/src/driver.js

@@ -0,0 +1,7 @@
+export class DesktopDriverError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}

package/dist/packages/domain/src/message.js

@@ -0,0 +1,7 @@
+export var MediaArtifactKind;
+(function (MediaArtifactKind) {
+    MediaArtifactKind["Image"] = "image";
+    MediaArtifactKind["Audio"] = "audio";
+    MediaArtifactKind["Video"] = "video";
+    MediaArtifactKind["File"] = "file";
+})(MediaArtifactKind || (MediaArtifactKind = {}));

package/dist/packages/domain/src/session.js

@@ -0,0 +1,7 @@
+export var BridgeSessionStatus;
+(function (BridgeSessionStatus) {
+    BridgeSessionStatus["Active"] = "active";
+    BridgeSessionStatus["NeedsRebind"] = "needs_rebind";
+    BridgeSessionStatus["DriverUnhealthy"] = "driver_unhealthy";
+    BridgeSessionStatus["Paused"] = "paused";
+})(BridgeSessionStatus || (BridgeSessionStatus = {}));

package/dist/packages/orchestrator/src/bridge-orchestrator.js

@@ -0,0 +1,143 @@
+import { BridgeSessionStatus } from "../../domain/src/session.js";
+import { DesktopDriverError } from "../../domain/src/driver.js";
+export class BridgeOrchestrator {
+    deps;
+    recentInboundFingerprints = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async handleInbound(message) {
+        const alreadySeen = await this.deps.transcriptStore.hasInbound(message.messageId);
+        if (alreadySeen) {
+            return;
+        }
+        await this.deps.sessionStore.withSessionLock(message.sessionKey, async () => {
+            const seenInsideLock = await this.deps.transcriptStore.hasInbound(message.messageId);
+            if (seenInsideLock) {
+                return;
+            }
+            if (this.isLikelyDuplicateInbound(message)) {
+                console.warn("[qq-codex-bridge] duplicate inbound suppressed", {
+                    messageId: message.messageId,
+                    sessionKey: message.sessionKey
+                });
+                return;
+            }
+            const existing = await this.deps.sessionStore.getSession(message.sessionKey);
+            if (!existing) {
+                const created = {
+                    sessionKey: message.sessionKey,
+                    accountKey: message.accountKey,
+                    peerKey: message.peerKey,
+                    chatType: message.chatType,
+                    peerId: message.senderId,
+                    codexThreadRef: null,
+                    skillContextKey: null,
+                    status: BridgeSessionStatus.Active,
+                    lastInboundAt: message.receivedAt,
+                    lastOutboundAt: null,
+                    lastError: null
+                };
+                await this.deps.sessionStore.createSession(created);
+            }
+            await this.deps.transcriptStore.recordInbound(message);
+            this.rememberInbound(message);
+            try {
+                const deliveredDraftIds = new Set();
+                const deliveryErrors = [];
+                const handleDraft = async (draft) => {
+                    if (deliveredDraftIds.has(draft.draftId)) {
+                        return;
+                    }
+                    deliveredDraftIds.add(draft.draftId);
+                    await this.deps.transcriptStore.recordOutbound(draft);
+                    try {
+                        await this.deps.qqEgress.deliver(draft);
+                    }
+                    catch (error) {
+                        const reason = error instanceof Error ? error.message : String(error);
+                        deliveryErrors.push(`${draft.draftId}: ${reason}`);
+                        console.warn("[qq-codex-bridge] draft delivery failed", {
+                            sessionKey: message.sessionKey,
+                            messageId: message.messageId,
+                            draftId: draft.draftId,
+                            error: reason
+                        });
+                    }
+                };
+                const drafts = await this.deps.conversationProvider.runTurn(message, {
+                    onDraft: handleDraft
+                });
+                for (const draft of drafts) {
+                    await handleDraft(draft);
+                }
+                await this.deps.sessionStore.updateSessionStatus(message.sessionKey, BridgeSessionStatus.Active, deliveryErrors.length > 0 ? deliveryErrors.at(-1) ?? null : null);
+            }
+            catch (error) {
+                const lastError = error instanceof Error ? error.message : String(error);
+                if (isRecoverableTurnError(error)) {
+                    await this.deps.sessionStore.updateSessionStatus(message.sessionKey, BridgeSessionStatus.Active, lastError);
+                    console.warn("[qq-codex-bridge] recoverable turn error", {
+                        messageId: message.messageId,
+                        sessionKey: message.sessionKey,
+                        error: lastError
+                    });
+                    return;
+                }
+                await this.deps.sessionStore.updateSessionStatus(message.sessionKey, BridgeSessionStatus.NeedsRebind, lastError);
+                throw error;
+            }
+        });
+    }
+    isLikelyDuplicateInbound(message) {
+        const record = this.recentInboundFingerprints.get(message.sessionKey);
+        if (!record) {
+            return false;
+        }
+        const receivedAtMs = Date.parse(message.receivedAt);
+        if (!Number.isFinite(receivedAtMs)) {
+            return false;
+        }
+        return (record.fingerprint === buildInboundFingerprint(message) &&
+            receivedAtMs - record.receivedAtMs >= 0 &&
+            receivedAtMs - record.receivedAtMs <= 90_000);
+    }
+    rememberInbound(message) {
+        const receivedAtMs = Date.parse(message.receivedAt);
+        if (!Number.isFinite(receivedAtMs)) {
+            return;
+        }
+        const now = receivedAtMs;
+        for (const [sessionKey, record] of this.recentInboundFingerprints.entries()) {
+            if (now - record.receivedAtMs > 120_000) {
+                this.recentInboundFingerprints.delete(sessionKey);
+            }
+        }
+        this.recentInboundFingerprints.set(message.sessionKey, {
+            fingerprint: buildInboundFingerprint(message),
+            receivedAtMs,
+            messageId: message.messageId
+        });
+    }
+}
+function isRecoverableTurnError(error) {
+    return error instanceof DesktopDriverError && error.reason === "reply_timeout";
+}
+function buildInboundFingerprint(message) {
+    const mediaFingerprint = (message.mediaArtifacts ?? [])
+        .map((artifact) => [
+        artifact.kind,
+        artifact.localPath || "",
+        artifact.sourceUrl || "",
+        artifact.originalName || ""
+    ].join("::"))
+        .join("|");
+    return [
+        message.accountKey,
+        message.sessionKey,
+        message.senderId,
+        message.chatType,
+        message.text.trim(),
+        mediaFingerprint
+    ].join("||");
+}

package/dist/packages/orchestrator/src/job-runner.js

@@ -0,0 +1,5 @@
+export async function deliverDrafts(egress, drafts) {
+    for (const draft of drafts) {
+        await egress.deliver(draft);
+    }
+}

package/dist/packages/orchestrator/src/media-context.js

@@ -0,0 +1,90 @@
+import { buildQqbotSkillContext, shouldInjectQqbotSkillContext } from "./qqbot-skill-context.js";
+export function buildCodexInboundText(message, options = {}) {
+    const baseText = message.text.trim();
+    const mediaArtifacts = message.mediaArtifacts ?? [];
+    const voiceTranscriptSection = buildVoiceTranscriptSection(mediaArtifacts);
+    const visibleSections = [baseText, voiceTranscriptSection].filter(Boolean);
+    const sections = [
+        visibleSections.length > 0 ? visibleSections.join("\n\n") : inferAttachmentOnlyPlaceholder(message)
+    ];
+    const hiddenContexts = [];
+    const attachmentContextArtifacts = mediaArtifacts.filter(shouldKeepAttachmentContext);
+    if (attachmentContextArtifacts.length > 0) {
+        hiddenContexts.push(buildHiddenAttachmentContext(attachmentContextArtifacts));
+    }
+    if ((options.includeSkillContext ?? true) && shouldInjectQqbotSkillContext(message)) {
+        hiddenContexts.push(wrapHiddenContext("QQBOT_RUNTIME_CONTEXT", buildQqbotSkillContext(message)));
+    }
+    if (hiddenContexts.length > 0) {
+        sections.push("", ...hiddenContexts);
+    }
+    return sections.join("\n");
+}
+function buildHiddenAttachmentContext(artifacts) {
+    const lines = ["QQBOT_ATTACHMENTS"];
+    for (const [index, artifact] of artifacts.entries()) {
+        lines.push(`${index + 1}. ${renderArtifactLabel(artifact)}：${artifact.originalName}`);
+        lines.push(`path=${artifact.localPath}`);
+        lines.push(`mime=${artifact.mimeType}`);
+        lines.push(`size=${artifact.fileSize}`);
+        const extractedText = artifact.extractedText?.trim();
+        if (extractedText && !isGenericAttachmentText(extractedText, artifact)) {
+            lines.push(`extracted=${extractedText}`);
+        }
+        const transcript = artifact.transcript?.trim();
+        if (transcript) {
+            lines.push(`transcript=${transcript}`);
+        }
+        const transcriptSource = artifact.transcriptSource?.trim();
+        if (transcriptSource) {
+            lines.push(`transcriptSource=${transcriptSource}`);
+        }
+    }
+    return wrapHiddenContext("QQBOT_ATTACHMENTS", lines.join("\n"));
+}
+function wrapHiddenContext(label, content) {
+    return [`<!-- ${label}`, content, "-->"].join("\n");
+}
+function inferAttachmentOnlyPlaceholder(message) {
+    if (message.mediaArtifacts?.length) {
+        const count = message.mediaArtifacts.length;
+        return `（用户发送了 ${count} 个 QQ 附件）`;
+    }
+    return "(用户消息未包含文本)";
+}
+function buildVoiceTranscriptSection(artifacts) {
+    const voiceArtifacts = artifacts.filter((artifact) => artifact.kind === "audio" && artifact.transcript?.trim());
+    if (voiceArtifacts.length === 0) {
+        return "";
+    }
+    if (voiceArtifacts.length === 1) {
+        return `[语音消息] ${voiceArtifacts[0].transcript.trim()}`;
+    }
+    return voiceArtifacts
+        .map((artifact, index) => `[语音${index + 1}] ${artifact.transcript.trim()}`)
+        .join("\n");
+}
+function renderArtifactLabel(artifact) {
+    switch (artifact.kind) {
+        case "image":
+            return "图片";
+        case "audio":
+            return "音频";
+        case "video":
+            return "视频";
+        case "file":
+            return "文件";
+        default:
+            return "附件";
+    }
+}
+function isGenericAttachmentText(text, artifact) {
+    const genericPrefixes = ["图片附件：", "语音附件：", "视频附件：", "文件附件："];
+    return genericPrefixes.some((prefix) => text === `${prefix}${artifact.originalName}`);
+}
+function shouldKeepAttachmentContext(artifact) {
+    if (artifact.kind === "audio" && artifact.transcript?.trim()) {
+        return false;
+    }
+    return true;
+}