@jack200714/mafw 4.5.1

package/gateway/dist/media/media-plugin-loader.js

@@ -0,0 +1,254 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaPluginLoader = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+const pi_adapter_1 = require("./pi-adapter");
+const plugin_context_1 = require("./plugin-context");
+const VALID_MODALITIES = new Set(['image', 'video', 'audio']);
+class MediaPluginLoader {
+    pluginsDir;
+    state = new Map();
+    engines = new Map();
+    watcher;
+    debounceTimer;
+    getCredentials;
+    constructor(pluginsDir, opts) {
+        this.pluginsDir = pluginsDir;
+        this.getCredentials = opts?.getCredentials;
+    }
+    async init() {
+        this.ensureDir();
+        await this.scan();
+        this.startWatch();
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.pluginsDir)) {
+            fs.mkdirSync(this.pluginsDir, { recursive: true });
+            fs.writeFileSync(path.join(this.pluginsDir, 'README.md'), README_CONTENT);
+            fs.writeFileSync(path.join(this.pluginsDir, 'example.js.disabled'), EXAMPLE_CONTENT);
+            logger_1.log.info(`[MediaPluginLoader] Created ${this.pluginsDir}`);
+        }
+    }
+    async scan() {
+        if (!fs.existsSync(this.pluginsDir))
+            return;
+        const files = fs.readdirSync(this.pluginsDir).filter(f => f.endsWith('.js'));
+        const seen = new Set();
+        const loadedNames = new Set();
+        for (const file of files.sort()) {
+            await this.loadFile(file, loadedNames);
+            seen.add(file);
+        }
+        for (const [file] of this.state) {
+            if (!seen.has(file)) {
+                const prev = this.state.get(file);
+                if (prev?.name)
+                    this.engines.delete(prev.name);
+                this.state.delete(file);
+            }
+        }
+    }
+    async loadFile(file, loadedNames) {
+        const fullPath = path.join(this.pluginsDir, file);
+        try {
+            const cacheKey = require.resolve(fullPath);
+            delete require.cache[cacheKey];
+        }
+        catch { /* first load */ }
+        try {
+            const mod = require(fullPath);
+            const name = mod?.name;
+            if (!name || typeof name !== 'string') {
+                this.state.set(file, { file, status: 'error', error: 'missing name' });
+                return;
+            }
+            const modalities = mod?.modalities;
+            if (!Array.isArray(modalities) || modalities.length === 0 || !modalities.every((m) => VALID_MODALITIES.has(m))) {
+                this.state.set(file, { file, name, status: 'error', error: 'invalid modalities' });
+                return;
+            }
+            const hasCreatePrompt = typeof mod.createPrompt === 'function';
+            const hasPiEngine = mod.engine === 'pi';
+            if (!hasCreatePrompt && !hasPiEngine) {
+                this.state.set(file, { file, name, status: 'error', error: 'missing createPrompt() or engine:"pi"' });
+                return;
+            }
+            if (hasCreatePrompt && hasPiEngine) {
+                this.state.set(file, { file, name, status: 'error', error: 'createPrompt and engine:"pi" are mutually exclusive' });
+                return;
+            }
+            if (loadedNames.has(name)) {
+                this.state.set(file, { file, name, status: 'error', error: 'duplicate name' });
+                logger_1.log.warn(`[MediaPluginLoader] ${file}: duplicate name '${name}', skipping`);
+                return;
+            }
+            let prompt;
+            const creds = this.getCredentials?.();
+            if (hasCreatePrompt) {
+                const ctx = (0, plugin_context_1.createMediaPluginContext)(name, creds);
+                prompt = await mod.createPrompt(ctx);
+                if (typeof prompt !== 'function') {
+                    this.state.set(file, { file, name, status: 'error', error: 'createPrompt did not return a function' });
+                    return;
+                }
+            }
+            else {
+                const fixPayload = typeof mod.fixPayload === 'function' ? mod.fixPayload : undefined;
+                prompt = (0, pi_adapter_1.createPiPromptAdapter)({ fixPayload, credentials: creds });
+            }
+            loadedNames.add(name);
+            this.engines.set(name, { prompt, modalities });
+            this.state.set(file, { file, name, status: 'ok', modalities });
+            logger_1.log.info(`[MediaPluginLoader] Loaded ${file} (${name}, modalities: ${modalities.join(',')})`);
+        }
+        catch (err) {
+            const prev = this.state.get(file);
+            this.state.set(file, {
+                file,
+                name: prev?.name,
+                status: 'error',
+                error: err.message,
+            });
+            logger_1.log.warn(`[MediaPluginLoader] ${file} load error: ${err.message}`);
+        }
+    }
+    getEngines() {
+        return this.engines;
+    }
+    getState() {
+        return [...this.state.values()];
+    }
+    async reload() {
+        await this.scan();
+    }
+    startWatch() {
+        if (!fs.existsSync(this.pluginsDir))
+            return;
+        try {
+            this.watcher = fs.watch(this.pluginsDir, () => {
+                if (this.debounceTimer)
+                    clearTimeout(this.debounceTimer);
+                this.debounceTimer = setTimeout(async () => {
+                    if (!fs.existsSync(this.pluginsDir)) {
+                        logger_1.log.warn(`[MediaPluginLoader] plugins dir deleted, stopping watch`);
+                        this.watcher?.close();
+                        this.watcher = undefined;
+                        return;
+                    }
+                    await this.scan();
+                }, 300);
+            });
+        }
+        catch (err) {
+            logger_1.log.warn(`[MediaPluginLoader] watch failed: ${err.message}`);
+        }
+    }
+    stop() {
+        this.watcher?.close();
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+    }
+}
+exports.MediaPluginLoader = MediaPluginLoader;
+const README_CONTENT = `# Media Engine Plugins
+
+Place \`.js\` files here to add custom media analysis engines. Two forms:
+
+## Form A: Custom Engine (full control)
+
+\`\`\`js
+module.exports = {
+  name: "gemini-vision",
+  modalities: ["image", "video"],
+  async createPrompt(ctx) {
+    const key = ctx.apiKey("google");
+    return async (parts, opts) => {
+      // parts: [{type:'file', mime, url: 'data:...'}, {type:'text', text}]
+      // opts: { providerID, modelID }
+      // Return analysis text.
+      const res = await ctx.fetch("https://api.example.com/analyze", {
+        method: "POST",
+        headers: { Authorization: \`Bearer \${key}\` },
+        body: JSON.stringify({ parts }),
+      });
+      const data = await res.json();
+      return data.result;
+    };
+  },
+};
+\`\`\`
+
+## Form B: Pi Engine with Custom Wire Fixer
+
+\`\`\`js
+module.exports = {
+  name: "qwen-vl",
+  modalities: ["image", "video"],
+  engine: "pi",
+  fixPayload(payload) {
+    // Rewrite wire format for your provider. Return undefined for no change.
+    return payload;
+  },
+};
+\`\`\`
+
+**ctx methods:**
+- \`ctx.apiKey(name)\` — read provider key from opencode auth.json
+- \`ctx.fetch(url, opts)\` — fetch with 60s timeout
+- \`ctx.pluginConfig(name)\` — read media.pluginConfig[name] from config
+- \`ctx.log\` — gateway logger
+
+Select engine per modality in config:
+\`\`\`yaml
+media:
+  engine: pi              # default
+  video:
+    engine: qwen-vl       # override for video
+\`\`\`
+`;
+const EXAMPLE_CONTENT = `// Rename to example.js to activate
+module.exports = {
+  name: "example",
+  modalities: ["image"],
+  async createPrompt(ctx) {
+    return async (parts, opts) => {
+      return "Example analysis result";
+    };
+  },
+};
+`;

package/gateway/dist/media/media-runtime-executor.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaRuntimeExecutor = void 0;
+exports.mediaSessionKey = mediaSessionKey;
+exports.createMediaRuntimeExecutor = createMediaRuntimeExecutor;
+const crypto_1 = require("crypto");
+const pi_adapter_1 = require("./pi-adapter");
+const auth_1 = require("../runtime/auth");
+const logger_1 = require("../core/utils/logger");
+function mediaSessionKey(dataUrl, providerID, modelID) {
+    return (0, crypto_1.createHash)('sha256').update(dataUrl).update('\x00').update(providerID).update('\x00').update(modelID).digest('hex').slice(0, 16);
+}
+class MediaRuntimeExecutor {
+    rt;
+    opts;
+    completeFn;
+    sessions = new Map();
+    inflight = new Set();
+    ttlMs;
+    timeoutMs;
+    constructor(rt, opts = {}, completeFn) {
+        this.rt = rt;
+        this.opts = opts;
+        this.completeFn = completeFn;
+        this.ttlMs = opts.sessionTtlMs ?? 24 * 60 * 60 * 1000;
+        this.timeoutMs = opts.timeoutMs ?? 180_000;
+    }
+    /** PromptFn 实现——MediaService 注入点。 */
+    prompt = async (parts, opts) => {
+        const filePart = parts.find((p) => p.type === 'file');
+        const textPart = parts.find((p) => p.type === 'text');
+        const kind = this.kindOf(filePart);
+        // 无媒体 part（追问轮）：复用最近使用的 image 会话（同 provider/model）
+        if (!filePart) {
+            const entry = this.latestFor(opts.providerID, opts.modelID);
+            if (entry) {
+                return this.analyzeInSession(entry, textPart ? String(textPart.text ?? '') : '请描述这个媒体内容。');
+            }
+            return this.withTimeout('media analysis', () => this.completeFn(parts, opts));
+        }
+        // video/audio：单次 complete 路径（fixMediaPayload wire 重写，已验证）
+        if (kind !== 'image') {
+            return this.withTimeout('media analysis', () => this.completeFn(parts, opts));
+        }
+        const dataUrl = String(filePart.url ?? '');
+        const key = mediaSessionKey(dataUrl, opts.providerID, opts.modelID);
+        this.gc();
+        let entry = this.sessions.get(key);
+        this.inflight.add(key);
+        try {
+            if (!entry) {
+                const { id } = await this.rt.session.create({ directory: undefined });
+                entry = { sessionID: id, kind, dataUrl, providerID: opts.providerID, modelID: opts.modelID, createdAt: Date.now() };
+                this.sessions.set(key, entry);
+                await this.rt.session.promptAsync({
+                    sessionID: id,
+                    parts: [
+                        { type: 'file', url: dataUrl, mime: filePart.mime, text: '' },
+                        ...(textPart ? [{ type: 'text', text: String(textPart.text ?? '') }] : []),
+                    ],
+                });
+            }
+            else {
+                const text = textPart ? String(textPart.text ?? '') : '请描述这个媒体内容。';
+                await this.rt.session.promptAsync({ sessionID: entry.sessionID, message: text });
+            }
+            const result = await this.fetchLatestAssistant(entry.sessionID);
+            return result;
+        }
+        catch (err) {
+            if (entry)
+                await this.cancel(key);
+            logger_1.log.error(`[MediaRuntimeExecutor] analysis failed: ${err?.message ?? String(err)}`);
+            throw err;
+        }
+        finally {
+            this.inflight.delete(key);
+        }
+    };
+    /** 在同一会话内发消息并取最新 assistant 输出。 */
+    async analyzeInSession(entry, text) {
+        const key = `inflight:${entry.sessionID}`;
+        this.inflight.add(key);
+        try {
+            await this.rt.session.promptAsync({ sessionID: entry.sessionID, message: text });
+            return await this.fetchLatestAssistant(entry.sessionID);
+        }
+        catch (err) {
+            await this.cancelBySession(entry.sessionID);
+            throw err;
+        }
+        finally {
+            this.inflight.delete(key);
+        }
+    }
+    async fetchLatestAssistant(sessionID) {
+        return this.withTimeout('fetch latest assistant message', async () => {
+            const { data } = await this.rt.session.messages({ sessionID });
+            const latest = [...data].reverse().find((m) => m?.role === 'assistant');
+            const text = (latest?.content || []).map((c) => c?.text ?? '').join('\n').trim();
+            return text || '（无文本输出）';
+        });
+    }
+    /** 同 provider/model 下最近使用的会话（追问轮复用）。 */
+    latestFor(providerID, modelID) {
+        let latest;
+        for (const entry of this.sessions.values()) {
+            if (entry.providerID !== providerID || entry.modelID !== modelID)
+                continue;
+            if (!latest || entry.createdAt > latest.createdAt)
+                latest = entry;
+        }
+        return latest;
+    }
+    /** 中止指定媒体会话。 */
+    async cancel(key) {
+        const entry = this.sessions.get(key);
+        if (entry)
+            await this.cancelBySession(entry.sessionID);
+    }
+    async cancelBySession(sessionID) {
+        try {
+            await this.rt.session.abort({ sessionID });
+        }
+        catch { /* ignore */ }
+    }
+    /** A2A cancelTask 调用：中止所有进行中会话。 */
+    async cancelInflight() {
+        for (const key of this.inflight)
+            await this.cancel(key);
+        this.inflight.clear();
+    }
+    async dispose() {
+        for (const entry of this.sessions.values()) {
+            try {
+                await this.rt.session.delete({ sessionID: entry.sessionID });
+            }
+            catch { /* ignore */ }
+        }
+        this.sessions.clear();
+        this.inflight.clear();
+    }
+    kindOf(filePart) {
+        if (!filePart)
+            return 'text';
+        const mime = String(filePart.mime ?? filePart.url ?? '');
+        if (mime.startsWith('video/'))
+            return 'video';
+        if (mime.startsWith('audio/'))
+            return 'audio';
+        return 'image';
+    }
+    gc() {
+        const now = Date.now();
+        for (const [key, entry] of this.sessions) {
+            if (now - entry.createdAt > this.ttlMs) {
+                this.sessions.delete(key);
+                try {
+                    void this.rt.session.delete({ sessionID: entry.sessionID });
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    async withTimeout(label, fn) {
+        let timer;
+        try {
+            return await Promise.race([
+                fn(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`${label} timed out after ${this.timeoutMs}ms`)), this.timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+exports.MediaRuntimeExecutor = MediaRuntimeExecutor;
+function createMediaRuntimeExecutor(rt, opts = {}) {
+    const authPath = opts.authPath ?? (0, auth_1.DEFAULT_AUTH_PATH)();
+    // Contract path: stateless single-shot completion over rt.completion
+    // (completionApi capability). Media parts ride the contract's image carrier;
+    // wire-format rewriting (video_url/input_audio) is the implementing
+    // runtime's internal concern (pi: fixMediaPayload via onPayload).
+    const contractComplete = async (parts, po) => {
+        const channel = rt.capabilities?.completionApi ? rt.completion : undefined;
+        if (!channel)
+            throw new Error('no completion channel');
+        const filePart = parts.find((p) => p.type === 'file');
+        const textPart = parts.find((p) => p.type === 'text');
+        const dataUrl = String(filePart?.url ?? '');
+        const mime = filePart?.mime || dataUrl.match(/^data:([^;]+);/)?.[1] || 'image/png';
+        const data = dataUrl.includes(',') ? dataUrl.split(',')[1] || '' : '';
+        const user = [];
+        if (textPart && String(textPart.text ?? '').trim())
+            user.push({ type: 'text', text: String(textPart.text) });
+        if (filePart && data)
+            user.push({ type: 'image', data, mimeType: mime });
+        const res = await channel.complete({
+            model: { providerID: po.providerID, modelID: po.modelID },
+            system: [{ text: 'You are a precise media analysis assistant. Answer the user\'s question about the attached media concisely and factually.' }],
+            user,
+            timeoutMs: 180_000,
+        });
+        return res.text;
+    };
+    const legacyComplete = opts.completeFn ?? (async (parts, po) => {
+        const { createPiPromptAdapter } = await import('./pi-adapter.js');
+        const adapter = createPiPromptAdapter({ fixPayload: pi_adapter_1.fixMediaPayload, authPath });
+        return adapter(parts, po);
+    });
+    // Explicit opts.completeFn wins outright (tests / custom engines); the
+    // default path prefers the runtime contract and falls back to the pi
+    // adapter on absence or failure.
+    const completeFn = opts.completeFn ?? (async (parts, po) => {
+        try {
+            return await contractComplete(parts, po);
+        }
+        catch {
+            return legacyComplete(parts, po);
+        }
+    });
+    return new MediaRuntimeExecutor(rt, opts, completeFn);
+}

package/gateway/dist/media/media-service.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaService = exports.AUDIO_NARRATIVE_PROMPT = exports.AUDIO_STRUCTURED_PROMPT = exports.LANG_INSTRUCTIONS = exports.DESCRIBE_PROMPT = exports.MediaError = void 0;
+exports.kindFromMediaType = kindFromMediaType;
+const crypto_1 = require("crypto");
+/**
+ * MediaService — multimodal (image / video / audio) analysis client that
+ * routes every request through the opencode server SDK (`session.prompt`).
+ *
+ * Credentials and endpoints are owned by opencode: the caller (gateway) only
+ * picks the model per modality (`{ providerID, modelID }`) and opencode
+ * resolves the provider's API key from its own auth store. No MAFW-side API
+ * key or base URL is required.
+ *
+ * Configuration comes from the gateway config `media:` section:
+ *   provider: 'xiaomi'              — opencode provider that owns the key
+ *   model:    'mimo-v2.5'           — default model for every modality
+ *   image/video/audio: { provider?, model } — per-modality overrides
+ *   lang: 'zh'                      — optional answer-language instruction
+ *
+ * The gateway owns cache, retries and logging; the plugin only does hook
+ * shape work (job collection, focus hints, channel note, failure note).
+ */
+class MediaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MediaError';
+    }
+}
+exports.MediaError = MediaError;
+exports.DESCRIBE_PROMPT = 'Please describe the contents of this media in detail.';
+exports.LANG_INSTRUCTIONS = {
+    zh: '请使用简体中文回答。',
+    en: 'Please respond in English.',
+};
+/**
+ * 音频理解结构化 prompt（opt-in）——要求模型返回 JSON：
+ *   { "transcript": "转写文本", "emotion": "情绪", "tone": "语调/语气", "confidence": 0-1 }
+ * 仅供实时语音对话等需要情绪/语调的场景使用；FLEURS 评测走默认 analyze()，不受影响。
+ */
+exports.AUDIO_STRUCTURED_PROMPT = '请分析这段音频内容本身（不要转写本指令），返回 JSON（不要其他内容）：\n' +
+    '{"transcript": "语音转写文本；若音频无语音则为声音描述", ' +
+    '"emotion": "说话者情绪（如 高兴/沮丧/愤怒/中性/惊讶；无语音则 null）", ' +
+    '"tone": "语调起伏/语气（如 平稳/激动/低沉/上扬；无语音则 null）", "confidence": 0.0-1.0}';
+/**
+ * 音频首轮叙述式分析 prompt（主 Agent 场景）：自然语言描述内容 + 情绪/语调轨迹 + 意图，
+ * 不强制 JSON——主 Agent（文本模型）直接理解，无需解析层。
+ */
+exports.AUDIO_NARRATIVE_PROMPT = '请分析这段音频，用自然语言按顺序描述：\n' +
+    '1. 内容：说话者说了什么（完整转写；若音频无语音，则描述声音本身，如环境音/音乐/效果声）\n' +
+    '2. 情绪与语调变化：语气起伏、语速、停顿等细节（如"开头平静，说到\'…\'时语速加快、语调上扬，' +
+    '明显不满；最后\'…\'时语气放缓，带妥协与无奈"）\n' +
+    '3. 意图：说话者的目的与态度\n' +
+    '可用"开头 / 说到这句时 / 最后"等相对位置描述，不要求精确时间戳。\n' +
+    '不要输出 JSON，用流畅的中文。';
+const CACHE_MAX = 128;
+function kindFromMediaType(mediaType) {
+    if (mediaType.startsWith('video/'))
+        return 'video';
+    if (mediaType.startsWith('audio/'))
+        return 'audio';
+    return 'image';
+}
+class MediaService {
+    deps;
+    cache = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Effective media config (gateway config merged over defaults). */
+    loadConfig() {
+        const base = { provider: 'xiaomi', model: 'mimo-v2.5' };
+        const fromCfg = this.deps.config ? (this.deps.config() ?? {}) : {};
+        const merged = { ...base, ...fromCfg };
+        return merged;
+    }
+    /** Media routing is ready whenever a prompt channel was injected. */
+    get isConfigured() {
+        return !!this.deps?.prompt;
+    }
+    /** Resolve the provider/model pair for a modality (per-modality, else default). */
+    modelFor(cfg, kind) {
+        const ref = cfg[kind] ?? { model: '' };
+        return {
+            providerID: ref.provider || cfg.provider,
+            modelID: ref.model || cfg.model,
+        };
+    }
+    cacheKey(kind, engine, providerID, modelID, mediaUrl, prompt) {
+        return (0, crypto_1.createHash)('sha256')
+            .update(kind)
+            .update('\x00')
+            .update(engine)
+            .update('\x00')
+            .update(providerID)
+            .update('\x00')
+            .update(modelID)
+            .update('\x00')
+            .update(mediaUrl)
+            .update('\x00')
+            .update(prompt)
+            .digest('hex');
+    }
+    /**
+     * Analyze media (image / video / audio) with the model configured for that
+     * modality. Routes through the opencode server via the injected PromptFn —
+     * opencode performs the provider auth and the multimodal part conversion.
+     */
+    async analyze(input, promptText) {
+        const kind = input.kind || kindFromMediaType(input.mediaType);
+        const cfg = this.loadConfig();
+        const { providerID, modelID } = this.modelFor(cfg, kind);
+        const engineName = cfg[kind]?.engine ?? cfg.engine ?? 'pi';
+        const promptFn = this.deps.resolvePrompt?.(kind, cfg) ?? this.deps.prompt;
+        const cacheKey = this.cacheKey(kind, engineName, providerID, modelID, input.dataUrl, promptText);
+        const cached = this.cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        let text = promptText || exports.DESCRIBE_PROMPT;
+        if (cfg.lang)
+            text = exports.LANG_INSTRUCTIONS[cfg.lang] + '\n\n' + text;
+        const ext = (input.mediaType.split('/')[1] || 'bin').split(';')[0].split('+')[0];
+        const parts = [
+            {
+                type: 'file',
+                mime: input.mediaType,
+                filename: `media.${ext}`,
+                url: input.dataUrl,
+            },
+            { type: 'text', text },
+        ];
+        let result;
+        try {
+            result = await promptFn(parts, { providerID, modelID });
+        }
+        catch (err) {
+            throw new MediaError(`Media API request failed: ${err.message}`);
+        }
+        if (!result || !result.trim()) {
+            throw new MediaError('Media API returned an empty description');
+        }
+        if (this.cache.size >= CACHE_MAX) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+    /** Describe an image — image-only convenience entry. */
+    async describe(imageUrl, prompt) {
+        return this.analyze({ kind: 'image', dataUrl: imageUrl, mediaType: 'image/png' }, prompt);
+    }
+    /**
+     * 音频理解（结构化）：返回 JSON { transcript, emotion, tone, confidence }。
+     * 独立于默认 analyze()——默认路径与 FLEURS 评测兼容，此方法仅供需要情绪/语调的场景。
+     */
+    async analyzeAudioStructured(input, promptText) {
+        const cfg = this.loadConfig();
+        const { providerID, modelID } = this.modelFor(cfg, 'audio');
+        const engineName = cfg.audio?.engine ?? cfg.engine ?? 'pi';
+        const promptFn = this.deps.resolvePrompt?.('audio', cfg) ?? this.deps.prompt;
+        const prompt = `${exports.AUDIO_STRUCTURED_PROMPT}\n\n${promptText || ''}`.trim();
+        const cacheKey = this.cacheKey('audio', engineName, providerID, modelID, input.dataUrl, prompt);
+        const cached = this.cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const ext = (input.mediaType.split('/')[1] || 'bin').split(';')[0].split('+')[0];
+        const parts = [
+            { type: 'file', mime: input.mediaType, filename: `media.${ext}`, url: input.dataUrl },
+            { type: 'text', text: prompt },
+        ];
+        let result;
+        try {
+            result = await promptFn(parts, { providerID, modelID });
+        }
+        catch (err) {
+            throw new MediaError(`Media API request failed: ${err.message}`);
+        }
+        if (!result || !result.trim()) {
+            throw new MediaError('Media API returned an empty structured analysis');
+        }
+        if (this.cache.size >= CACHE_MAX) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+    /**
+     * 音频首轮叙述式分析（主 Agent 场景）：自然语言输出内容转写 + 情绪/语调轨迹 + 意图。
+     * 与 analyzeAudioStructured 独立——不强制 JSON，无解析层。
+     */
+    async analyzeAudioNarrative(input) {
+        return this.analyze({ kind: 'audio', dataUrl: input.dataUrl, mediaType: input.mediaType }, exports.AUDIO_NARRATIVE_PROMPT);
+    }
+}
+exports.MediaService = MediaService;