/**
 * Vision Router — 把图片路由到视觉模型(groq),翻译成文字描述(Phase 2)。
 *
 * 对标 godot-ai/plugin/addons/godot_ai/vision_routing.gd(2026-08-10 深挖报告),
 * 但因 godot-mcp-enhanced 截图架构不同(TS 侧读文件,非 GD addon 实时截图),
 * 本模块是纯 TS 实现,不需要 worker 线程 / deferred 机制 / 加密存储。
 *
 * 核心流程:
 *   图片 base64 + prompt → groq API(OpenAI dialect)→ 文字描述
 *
 * 错误处理(对标 godot-ai fallback 设计):
 *   任何失败都返回 {success: false, error},调用方(screenshot.ts)负责
 *   fallback 到现有 detail 分层 + 追加 note,工具链不破。
 *
 * @module vision-router
 */
/**
 * Vision Routing 请求选项。
 *
 * API key 通过环境变量 GODOT_MCP_VISION_KEY 传入(对标 unity-mcp-server 的
 * UNITY_MCP_* 环境变量模式;godot-ai 用加密存储是因为它在 Godot editor 进程内,
 * TS server 用环境变量更自然,且 CI/容器场景友好)。
 */
export interface VisionRouteOptions {
    /** groq API key(必填)。 */
    apiKey: string;
    /** 模型 id。默认 `meta-llama/llama-4-scout-17b-16e-instruct`(groq 视觉模型,有免费档)。 */
    model?: string;
    /** 可选上下文(追加到 prompt,让视觉模型知道 agent 在做什么)。 */
    question?: string;
    /** 超时毫秒。默认 30000(groq 视觉模型首 token 约 2-5s + 描述生成 5-10s,30s 余量充足)。 */
    timeoutMs?: number;
    /** 可选:覆盖 API endpoint(用于兼容 OpenAI dialect 的国内中转/本地 ollama)。 */
    baseUrl?: string;
}
/** Vision Routing 返回结果。 */
export interface VisionRouteResult {
    /** 成功=true(有 description);失败=false(有 error,调用方 fallback)。 */
    success: boolean;
    /** 视觉模型返回的文字描述(success=true 时)。 */
    description?: string;
    /** 路由标识,如 "groq:meta-llama/llama-4-scout-17b-16e-instruct"(success=true 时)。 */
    routedVia?: string;
    /** 失败原因(success=false 时,用于 fallback note)。 */
    error?: string;
}
/**
 * 构建 prompt(对标 godot-ai vision_routing.gd:313-327,通用化处理)。
 *
 * godot-ai 的 prompt 偏 "Godot editor viewport",godot-mcp-enhanced 的截图
 * 可能是任意场景(游戏运行时/editor/headless),改为通用描述。
 *
 * @param question 可选上下文(agent 传入,如"我在调试 Player 走路动画")
 */
export declare function buildPrompt(question?: string): string;
/**
 * 从视觉模型响应解析描述(对标 godot-ai _parse_openai + _strip_think)。
 *
 * groq(OpenAI dialect)响应格式:
 *   { choices: [{ message: { content: "..." } }] }
 *
 * 推理模型可能把输出包在 `<think>...</think>` 块里,需 strip。
 */
export declare function parseDescription(responseJson: unknown): string | null;
/**
 * 剥离 `<think>...</think>` 块(对标 godot-ai _strip_think)。
 * 推理模型(如 llama-4-scout)有时把 Chain-of-Thought 包在此块里。
 */
export declare function stripThinkBlocks(text: string): string;
/**
 * 把图片路由到视觉模型,返回文字描述。
 *
 * 调用方(screenshot.ts analyze action)负责:
 *   1. 检测 vision_route=true
 *   2. 提供 apiKey(从 GODOT_MCP_VISION_KEY)
 *   3. 失败时 fallback 到现有 detail 分层 + 追加 note
 *
 * @param imageBase64 图片 base64(不含 data: 前缀)
 * @param mimeType 图片 MIME 类型('image/png' 或 'image/jpeg')
 * @param options 路由选项
 * @returns VisionRouteResult(success 时有 description + routedVia;失败时有 error)
 */
export declare function routeImage(imageBase64: string, mimeType: 'image/png' | 'image/jpeg', options: VisionRouteOptions): Promise<VisionRouteResult>;