image-vision-mcp 1.0.0 → 1.0.2

package/dist/proxy/imageProxy.js

@@ -1,17 +1,29 @@
 import http from "http";
 import https from "https";
-import { URL } from "url";
+import { URL, fileURLToPath } from "url";
 import zlib from "zlib";
 import fs from "fs";
 import path from "path";
 import os from "os";
-import { execSync } from "child_process";
+import { spawn } from "child_process";
+import crypto from "crypto";
 import { callMoonshot } from "../services/moonshot.js";
 // ────────────────────── 日志 ──────────────────────
-// 日志文件路径：优先用环境变量，否则放系统临时目录（跨平台、无需权限处理）
+// 日志文件路径：优先用环境变量，否则放项目内 logs/ 目录。
+// 用 import.meta.url 定位 dist/proxy/ → 反推项目根：独立代理进程是 detached
+// spawn 的，cwd 不可靠（可能继承自任意 Claude Code 会话），只能用脚本自身位置定位。
+const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 const LOG_FILE = process.env.VISION_MCP_LOG_FILE ||
-    path.join(os.tmpdir(), "vision-mcp-proxy.log");
+    path.join(PROJECT_ROOT, "logs", "vision-mcp-proxy.log");
 const LOG_MAX_SIZE = 10 * 1024 * 1024; // 10MB，超过后清空旧日志
+// 确保日志目录存在（环境变量覆盖到自定义路径时同样需要）。同步创建一次即可，
+// 失败也不影响代理功能——后续 appendFile 会静默失败，请求转发不受影响。
+try {
+    fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+}
+catch {
+    // 目录已存在或无权限，忽略
+}
 function log(msg) {
     const line = `[${new Date().toISOString()}] ${msg}\n`;
     console.error(line.trim());
@@ -50,133 +62,320 @@ const UPSTREAM_AUTH_TOKEN = process.env.UPSTREAM_AUTH_TOKEN ||
     "";
 const IMAGE_DESC_PROMPT = process.env.IMAGE_DESC_PROMPT ||
     "请详细描述这张图片的内容。如果是图表/截图，请提取关键信息；如果包含文字，请提取文字内容；如果是 UI 界面，请描述界面元素和布局。描述要简洁准确。";
+// 复用到上游模型的连接，减少慢流式响应场景下频繁建连的额外开销。
+const upstreamHttpAgent = new http.Agent({ keepAlive: true, maxSockets: 50 });
+const upstreamHttpsAgent = new https.Agent({ keepAlive: true, maxSockets: 50 });
 // ────────────────────── 图片识别 ──────────────────────
-async function describeImage(base64Data, mimeType) {
+// ────────────────────── 图片识别缓存 ──────────────────────
+// Claude Code 每次请求都带完整对话历史，历史里的图片会被反复识别（每张 30-60s）。
+// 用 base64 的 sha256 做 key 缓存识别结果，同一张图只识别一次。
+// LRU 淘汰：Map 按插入顺序，命中时删除重插移到末尾，超限时删最早的。
+const IMAGE_CACHE_MAX = 100;
+const imageCache = new Map();
+// 同一张图片可能同时出现在多个并发请求或历史消息里。复用进行中的识别，
+// 只有所有等待者都取消时才中止底层 Moonshot 请求，避免误伤其他请求。
+const pendingImageDescriptions = new Map();
+function hashImage(base64Data) {
+    return crypto.createHash("sha256").update(base64Data).digest("hex").slice(0, 32);
+}
+function getCachedDescription(base64Data) {
+    const key = hashImage(base64Data);
+    const desc = imageCache.get(key);
+    if (desc) {
+        imageCache.delete(key);
+        imageCache.set(key, desc); // 移到末尾，标记为最近使用
+        return desc;
+    }
+    return null;
+}
+function setCachedDescription(base64Data, description) {
+    const key = hashImage(base64Data);
+    imageCache.set(key, description);
+    if (imageCache.size > IMAGE_CACHE_MAX) {
+        const oldestKey = imageCache.keys().next().value;
+        if (oldestKey)
+            imageCache.delete(oldestKey);
+    }
+}
+// 失败短期缓存：识别失败（超时/空响应）的图 5 分钟内不重试，
+// 避免对话历史里某张图每次请求都卡 60s 超时。过期后允许重试（Moonshot 恢复后能成功）。
+const FAILURE_CACHE_TTL_MS = 5 * 60 * 1000;
+const failureCache = new Map(); // hash -> 失败时间戳
+function getFailureTimestamp(base64Data) {
+    const key = hashImage(base64Data);
+    const ts = failureCache.get(key);
+    if (ts === undefined)
+        return null;
+    failureCache.delete(key); // LRU 移到末尾
+    if (Date.now() - ts > FAILURE_CACHE_TTL_MS) {
+        return null; // 过期，不再缓存
+    }
+    failureCache.set(key, ts);
+    return ts;
+}
+function setFailureTimestamp(base64Data) {
+    const key = hashImage(base64Data);
+    failureCache.set(key, Date.now());
+    if (failureCache.size > IMAGE_CACHE_MAX) {
+        const oldestKey = failureCache.keys().next().value;
+        if (oldestKey)
+            failureCache.delete(oldestKey);
+    }
+}
+function isCanceledError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.name === "CanceledError" ||
+        err.message === "canceled" ||
+        err.message.includes("请求已取消"));
+}
+async function waitForPendingImage(task, signal) {
+    task.waiters++;
+    let removeAbortListener = () => { };
+    try {
+        if (!signal) {
+            return await task.promise;
+        }
+        if (signal.aborted) {
+            throw new Error("请求已取消");
+        }
+        return await new Promise((resolve, reject) => {
+            const onAbort = () => reject(new Error("请求已取消"));
+            removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+            signal.addEventListener("abort", onAbort, { once: true });
+            task.promise.then(resolve, reject);
+        });
+    }
+    finally {
+        removeAbortListener();
+        task.waiters--;
+        if (task.waiters === 0 && !task.settled) {
+            task.controller.abort();
+        }
+    }
+}
+async function describeImage(base64Data, mimeType, signal) {
+    if (signal?.aborted) {
+        throw new Error("请求已取消");
+    }
+    // 成功缓存命中：历史消息里反复出现的同一张图不重复调 Moonshot
+    const cached = getCachedDescription(base64Data);
+    if (cached) {
+        log(`[image-proxy] 图片命中缓存，跳过识别`);
+        return cached;
+    }
+    // 失败缓存命中：近期识别失败过的图短期不重试，避免每次请求都卡超时
+    if (getFailureTimestamp(base64Data) !== null) {
+        log(`[image-proxy] 图片命中失败缓存，跳过重试`);
+        throw new Error("图片近期识别失败，跳过重试");
+    }
     const dataUrl = `data:${mimeType};base64,${base64Data}`;
     const apiKey = process.env.MOONSHOT_API_KEY || "";
     if (!apiKey) {
         throw new Error("MOONSHOT_API_KEY 未设置");
     }
-    const response = await callMoonshot({
-        apiKey,
-        messages: [
-            {
-                role: "user",
-                content: [
-                    { type: "image_url", image_url: { url: dataUrl } },
-                    { type: "text", text: IMAGE_DESC_PROMPT },
+    const key = hashImage(base64Data);
+    const pending = pendingImageDescriptions.get(key);
+    if (pending) {
+        log(`[image-proxy] 图片识别进行中，复用同一个请求`);
+        return waitForPendingImage(pending, signal);
+    }
+    const task = {
+        controller: new AbortController(),
+        waiters: 0,
+        settled: false,
+    };
+    task.promise = (async () => {
+        try {
+            const response = await callMoonshot({
+                apiKey,
+                messages: [
+                    {
+                        role: "user",
+                        content: [
+                            { type: "image_url", image_url: { url: dataUrl } },
+                            { type: "text", text: IMAGE_DESC_PROMPT },
+                        ],
+                    },
                 ],
-            },
-        ],
-        maxTokens: 2048,
-    });
-    const description = response.choices?.[0]?.message?.content || "";
-    if (!description) {
-        throw new Error("Moonshot API 返回空内容");
+                maxTokens: 2048,
+                signal: task.controller.signal,
+            });
+            const description = response.choices?.[0]?.message?.content || "";
+            if (!description) {
+                throw new Error("Moonshot API 返回空内容");
+            }
+            setCachedDescription(base64Data, description);
+            return description;
+        }
+        catch (err) {
+            // 失败：记入失败缓存，短期不再重试（让对话继续，不阻塞 60s）
+            if (!isCanceledError(err)) {
+                setFailureTimestamp(base64Data);
+            }
+            throw err;
+        }
+        finally {
+            task.settled = true;
+            pendingImageDescriptions.delete(key);
+        }
+    })();
+    pendingImageDescriptions.set(key, task);
+    return waitForPendingImage(task, signal);
+}
+const IMAGE_MARKER_RE = /"type"\s*:\s*"(image|image_url|tool_result)"|"source"\s*:\s*\{\s*"type"\s*:\s*"base64"|data:image\/[a-z+.-]+;base64,/i;
+function mayContainImagePayload(rawBody) {
+    // 大多数消息无图，先用轻量文本探测跳过 JSON.parse 和深度扫描。
+    return IMAGE_MARKER_RE.test(rawBody);
+}
+function contentHasImage(content) {
+    if (!Array.isArray(content))
+        return false;
+    for (const block of content) {
+        if (block?.type === "image" || block?.type === "image_url") {
+            return true;
+        }
+        if (block?.type === "tool_result" && contentHasImage(block.content)) {
+            return true;
+        }
     }
-    return description;
+    return false;
 }
-async function processContent(content) {
-    if (typeof content === "string")
-        return content;
+function collectForwardedImageTexts(content, result) {
     if (!Array.isArray(content))
-        return content;
-    // 日志：记录所有 block 类型，方便排查
-    const blockTypes = content.map((b) => b?.type || "unknown");
-    log(`[image-proxy] content blocks: ${JSON.stringify(blockTypes)}`);
-    const newContent = [];
+        return;
     for (const block of content) {
-        // 格式1: Anthropic 标准 {"type":"image","source":{"type":"base64",...}}
-        if (block?.type === "image" && block.source?.type === "base64") {
-            const { media_type, data } = block.source;
+        if (block?.type === "text" &&
+            typeof block.text === "string" &&
+            (block.text.includes("[以下是用户粘贴的图片内容描述]") ||
+                block.text.includes("[以下是截图内容描述]") ||
+                block.text.includes("[图片识别失败:"))) {
+            result.push(block.text);
+        }
+        if (block?.type === "tool_result") {
+            collectForwardedImageTexts(block.content, result);
+        }
+    }
+}
+function logForwardedImageTexts(messages) {
+    if (!Array.isArray(messages))
+        return;
+    const forwardedTexts = [];
+    for (const message of messages) {
+        if (message && typeof message === "object" && "content" in message) {
+            collectForwardedImageTexts(message.content, forwardedTexts);
+        }
+    }
+    forwardedTexts.forEach((text, index) => {
+        log(`[image-proxy] 转发到上游 /v1/messages 的图片内容 #${index + 1} (${text.length} chars):\n${text}`);
+    });
+}
+// 处理单个 content block：图片类型识别后替换为文字，其余原样返回。
+// 同层数组的多个图片块由调用方 Promise.all 并行触发，这里只负责单块转换。
+async function describeBlock(block, signal) {
+    // 格式1: Anthropic 标准 {"type":"image","source":{"type":"base64",...}}
+    if (block?.type === "image" && block.source?.type === "base64") {
+        const { media_type, data } = block.source;
+        try {
+            const description = await describeImage(data, media_type, signal);
+            log(`[image-proxy] 图片已识别 (${media_type}, ${Math.round((data.length * 0.75) / 1024)} KB)`);
+            return {
+                type: "text",
+                text: `[以下是用户粘贴的图片内容描述]\n${description}\n[图片描述结束]`,
+            };
+        }
+        catch (err) {
+            log(`[image-proxy] 图片识别失败: ${err.message}`);
+            return {
+                type: "text",
+                text: `[图片识别失败: ${err.message}]`,
+            };
+        }
+    }
+    // 格式2: OpenAI 风格 {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
+    if (block?.type === "image_url" &&
+        block.image_url?.url?.startsWith("data:image")) {
+        const url = block.image_url.url;
+        const match = url.match(/^data:(image\/[a-z+]+);base64,(.+)$/i);
+        if (match) {
+            const [, media_type, data] = match;
             try {
-                const description = await describeImage(data, media_type);
-                newContent.push({
+                const description = await describeImage(data, media_type, signal);
+                log(`[image-proxy] image_url 图片已识别 (${media_type})`);
+                return {
                     type: "text",
-                    text: `[以下是用户粘贴的图片内容描述]\n${description}\n[图片描述结束]`,
-                });
-                log(`[image-proxy] 图片已识别 (${media_type}, ${Math.round((data.length * 0.75) / 1024)} KB)`);
+                    text: `[以下是截图内容描述]\n${description}\n[图片描述结束]`,
+                };
             }
             catch (err) {
-                log(`[image-proxy] 图片识别失败: ${err.message}`);
-                newContent.push({
+                log(`[image-proxy] image_url 图片识别失败: ${err.message}`);
+                return {
                     type: "text",
                     text: `[图片识别失败: ${err.message}]`,
-                });
+                };
             }
         }
-        // 格式2: OpenAI 风格 {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}
-        else if (block?.type === "image_url" &&
-            block.image_url?.url?.startsWith("data:image")) {
-            const url = block.image_url.url;
-            const match = url.match(/^data:(image\/[a-z+]+);base64,(.+)$/i);
-            if (match) {
-                const [, media_type, data] = match;
-                try {
-                    const description = await describeImage(data, media_type);
-                    newContent.push({
-                        type: "text",
-                        text: `[以下是截图内容描述]\n${description}\n[图片描述结束]`,
-                    });
-                    log(`[image-proxy] image_url 图片已识别 (${media_type})`);
-                }
-                catch (err) {
-                    log(`[image-proxy] image_url 图片识别失败: ${err.message}`);
-                    newContent.push({
-                        type: "text",
-                        text: `[图片识别失败: ${err.message}]`,
-                    });
-                }
-            }
-            else {
-                newContent.push(block);
-            }
-        }
-        // 格式3: tool_result 里嵌套图片（MCP 工具返回的截图）
-        else if (block?.type === "tool_result" && Array.isArray(block.content)) {
-            const toolContent = block.content;
-            const processed = await processContent(toolContent);
-            newContent.push({ ...block, content: processed });
-        }
-        else if (block?.type === "image" && block.source && !block.source.type?.startsWith("base64")) {
-            log(`[image-proxy] 未识别的 image source type: ${block.source.type}`);
-            newContent.push(block);
-        }
-        else {
-            newContent.push(block);
-        }
+        return block;
+    }
+    // 格式3: tool_result 里嵌套图片（MCP 工具返回的截图）
+    if (block?.type === "tool_result" && Array.isArray(block.content)) {
+        const toolContent = block.content;
+        const processed = await processContent(toolContent, signal);
+        return { ...block, content: processed };
     }
-    return newContent;
+    // 其他未识别的 image source type
+    if (block?.type === "image" && block.source && !block.source.type?.startsWith("base64")) {
+        log(`[image-proxy] 未识别的 image source type: ${block.source.type}`);
+    }
+    return block;
+}
+async function processContent(content, signal) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return content;
+    // 日志：记录所有 block 类型，方便排查
+    const blockTypes = content.map((b) => b?.type || "unknown");
+    log(`[image-proxy] content blocks: ${JSON.stringify(blockTypes)}`);
+    // 并行识别同一层级的所有图片块，map 保持原顺序
+    return Promise.all(content.map((block) => describeBlock(block, signal)));
 }
-async function processMessages(messages) {
+async function processMessages(messages, signal) {
     if (!Array.isArray(messages))
         return messages;
     for (const message of messages) {
+        if (signal?.aborted)
+            throw new Error("请求已取消");
         if (message && typeof message === "object" && message.content !== undefined) {
-            message.content = await processContent(message.content);
+            message.content = await processContent(message.content, signal);
         }
     }
     return messages;
 }
-// ────────────────────── 转发请求 ──────────────────────
-function forwardRequest(req, res, body) {
+function forwardRequest(req, res, body, meta, signal) {
     const baseUrl = new URL(UPSTREAM_BASE_URL);
     const basePath = baseUrl.pathname.replace(/\/+$/, "");
     const fullPath = basePath + (req.url || "");
     const isHttps = baseUrl.protocol === "https:";
     const lib = isHttps ? https : http;
+    const upstreamUrl = new URL(fullPath, baseUrl.origin).toString();
+    const pathOnly = (req.url || "").split("?")[0];
+    if (meta) {
+        const elapsed = Date.now() - meta.reqStart;
+        log(`[阶段] 转发开始 ${req.method} ${pathOnly} -> ${upstreamUrl} body=${meta.origSizeKB}KB ${meta.hasImage ? "有图" : "无图"} elapsed=${elapsed}ms`);
+    }
     const headers = { ...req.headers };
     delete headers["host"];
-    delete headers["content-length"];
-    // body 已被解压/修改，必须删除原压缩标记和逐跳头，否则上游会尝试解压明文导致失败
-    delete headers["content-encoding"];
-    delete headers["transfer-encoding"];
     headers["host"] = baseUrl.host;
     if (UPSTREAM_AUTH_TOKEN) {
         headers["authorization"] = `Bearer ${UPSTREAM_AUTH_TOKEN}`;
         headers["x-api-key"] = UPSTREAM_AUTH_TOKEN;
     }
-    if (body) {
+    if (body !== null) {
+        delete headers["content-length"];
+        // body 已被解压/修改，必须删除原压缩标记和逐跳头，否则上游会尝试解压明文导致失败
+        delete headers["content-encoding"];
+        delete headers["transfer-encoding"];
         headers["content-length"] = String(Buffer.byteLength(body));
     }
     const options = {
@@ -185,50 +384,103 @@ function forwardRequest(req, res, body) {
         port: baseUrl.port || (isHttps ? 443 : 80),
         path: fullPath,
         headers,
+        agent: isHttps ? upstreamHttpsAgent : upstreamHttpAgent,
+        signal,
     };
     const proxyReq = lib.request(options, (proxyRes) => {
-        res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
+        const status = proxyRes.statusCode || 502;
+        if (meta) {
+            const elapsed = Date.now() - meta.reqStart;
+            log(`[阶段] 上游响应 ${req.method} ${pathOnly} -> ${upstreamUrl} status=${status} body=${meta.origSizeKB}KB ${meta.hasImage ? "有图" : "无图"} 首包耗时=${elapsed}ms`);
+        }
+        if (res.destroyed) {
+            proxyRes.destroy();
+            return;
+        }
+        res.writeHead(status, proxyRes.headers);
         proxyRes.pipe(res);
     });
     proxyReq.on("error", (err) => {
-        log(`[image-proxy] 转发失败: ${err.message}`);
+        if (signal?.aborted || isCanceledError(err) || err.name === "AbortError") {
+            return;
+        }
+        if (meta) {
+            const elapsed = Date.now() - meta.reqStart;
+            log(`[image-proxy] 转发失败 ${req.method} ${pathOnly} -> ${upstreamUrl} (耗时=${elapsed}ms): ${err.message}`);
+        }
+        else {
+            log(`[image-proxy] 转发失败 ${req.method} ${pathOnly} -> ${upstreamUrl}: ${err.message}`);
+        }
         if (!res.headersSent) {
             res.writeHead(502, { "Content-Type": "application/json" });
             res.end(JSON.stringify({ error: { type: "proxy_error", message: err.message } }));
         }
     });
-    if (body) {
-        proxyReq.write(body);
+    if (body !== null) {
+        proxyReq.end(body);
     }
     else {
         req.pipe(proxyReq);
+        req.on("aborted", () => proxyReq.destroy(new Error("客户端请求已取消")));
+        req.on("error", (err) => proxyReq.destroy(err));
+    }
+}
+// ────────────────────── 单例锁 ──────────────────────
+// 锁文件路径：系统临时目录，跨平台无需权限处理
+const LOCK_FILE = path.join(os.tmpdir(), "vision-mcp-proxy.lock");
+// 检测 PID 对应的进程是否仍在运行（信号 0 不实际发信号，仅探测存活）
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        // ESRCH: 进程不存在；EPERM: 存在但无权限。两者都视为"不可达"，允许接管
+        return false;
     }
-    proxyReq.end();
 }
-// ────────────────────── 端口清理 ──────────────────────
-function killProcessOnPort(port) {
+// 尝试获取单例锁：保证全局只有一个 vision-mcp 进程启动图片代理，
+// 避免多个 MCP 进程互相 kill 对方占用的 8787 端口（会把正在处理请求的代理杀掉）。
+// 返回 true 表示拿到锁、应由本进程启动代理；false 表示已有代理在运行，跳过。
+function tryAcquireLock() {
     try {
-        if (process.platform === "win32") {
-            execSync(`powershell -NoProfile -Command "Get-NetTCPConnection -LocalPort ${port} -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue }"`, { stdio: "ignore", timeout: 5000 });
+        // O_EXCL (wx) 原子创建：文件已存在则抛 EEXIST
+        const fd = fs.openSync(LOCK_FILE, "wx");
+        fs.writeFileSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST") {
+            // 其他 IO 错误，保守起见不获取锁
+            return false;
         }
-        else if (process.platform === "darwin" || process.platform === "linux") {
-            // macOS/Linux: lsof 找到占用端口的 PID 并 kill -9
-            // lsof 不存在时静默失败，|| true 保证命令返回 0
-            execSync(`lsof -ti :${port} 2>/dev/null | xargs kill -9 2>/dev/null || true`, {
-                stdio: "ignore",
-                timeout: 5000,
-            });
+        // 锁文件已存在：检查持有者是否还活着
+        try {
+            const holderPid = parseInt(fs.readFileSync(LOCK_FILE, "utf8").trim(), 10);
+            if (holderPid && isProcessAlive(holderPid)) {
+                return false; // 持有者仍存活，复用已有代理
+            }
+            // 持有者已退出（崩溃未释放锁）：清理僵尸锁后递归重试
+            fs.unlinkSync(LOCK_FILE);
+            return tryAcquireLock();
         }
-        else {
+        catch {
             return false;
         }
-        log(`[image-proxy] 已清理占用端口 ${port} 的旧进程`);
-        return true;
+    }
+}
+// 释放锁：仅当锁文件登记的 PID 是本进程时才删除，避免误删他人的锁
+function releaseLock() {
+    try {
+        const holderPid = parseInt(fs.readFileSync(LOCK_FILE, "utf8").trim(), 10);
+        if (holderPid === process.pid) {
+            fs.unlinkSync(LOCK_FILE);
+        }
     }
     catch {
-        // 忽略错误
+        // 忽略：文件可能已被删除
     }
-    return false;
 }
 // ────────────────────── 启动代理 ──────────────────────
 export function startImageProxy() {
@@ -238,10 +490,44 @@ export function startImageProxy() {
             resolve();
             return;
         }
+        // 单例锁：保证全局只有一个代理进程。拿不到锁说明已有代理在运行，
+        // 直接复用，避免多 MCP 进程互相 kill 8787 端口导致正在处理的请求中断。
+        if (!tryAcquireLock()) {
+            log("[image-proxy] 已有代理进程在运行，跳过启动（复用已有代理，MCP 工具仍可用）");
+            resolve();
+            return;
+        }
+        // 进程退出时释放锁，让其他 MCP 进程下次启动时能接管
+        const releaseOnExit = () => releaseLock();
+        process.on("SIGINT", releaseOnExit);
+        process.on("SIGTERM", releaseOnExit);
+        process.on("beforeExit", releaseOnExit);
+        process.on("exit", releaseOnExit);
         const server = http.createServer(async (req, res) => {
+            const reqStart = Date.now();
+            // Claude Code 中断/重试时立即取消本轮代理工作，避免旧请求继续占用
+            // Moonshot 调用或上游流式连接。
+            const requestController = new AbortController();
+            const abortRequest = () => {
+                if (!res.writableEnded) {
+                    requestController.abort();
+                }
+            };
+            req.on("aborted", abortRequest);
+            res.on("close", abortRequest);
+            // /v1/messages 是 Anthropic Claude Messages API 端点，只有这类请求的 body
+            // 里才可能带图片，需要读全 body 拦截处理；其它请求（/v1/models、健康检查等）
+            // 直接透传，不解析 body 以省开销。用 includes 而非 === 是因为 url 可能带
+            // query string 或 UPSTREAM_BASE_URL 的 basePath 前缀。
             const isMessagesEndpoint = req.method === "POST" && (req.url || "").includes("/v1/messages");
+            const pathOnly = (req.url || "").split("?")[0];
+            log(`[阶段] 接收 ${req.method} ${pathOnly}`);
             if (!isMessagesEndpoint) {
-                forwardRequest(req, res, null);
+                forwardRequest(req, res, null, {
+                    reqStart,
+                    hasImage: false,
+                    origSizeKB: "?",
+                }, requestController.signal);
                 return;
             }
             const chunks = [];
@@ -249,6 +535,7 @@ export function startImageProxy() {
             req.on("end", async () => {
                 const buffer = Buffer.concat(chunks);
                 const contentEncoding = (req.headers["content-encoding"] || "").toLowerCase();
+                log(`[阶段] body读取完成 ${req.method} ${pathOnly} size=${(buffer.length / 1024).toFixed(1)}KB encoding=${contentEncoding || "none"} elapsed=${Date.now() - reqStart}ms`);
                 // 解压请求体（支持 gzip / deflate / br），否则 JSON.parse 会失败
                 let rawBody;
                 try {
@@ -264,6 +551,7 @@ export function startImageProxy() {
                     else {
                         rawBody = buffer.toString("utf8");
                     }
+                    log(`[阶段] body解码完成 ${req.method} ${pathOnly} rawSize=${(Buffer.byteLength(rawBody) / 1024).toFixed(1)}KB elapsed=${Date.now() - reqStart}ms`);
                 }
                 catch (err) {
                     log(`[image-proxy] 请求体解压失败: ${err.message}`);
@@ -276,36 +564,50 @@ export function startImageProxy() {
                     return;
                 }
                 try {
+                    const origSizeKB = (Buffer.byteLength(rawBody) / 1024).toFixed(1);
+                    if (!mayContainImagePayload(rawBody)) {
+                        log(`[阶段] 无图快速转发 ${req.method} ${pathOnly} elapsed=${Date.now() - reqStart}ms`);
+                        forwardRequest(req, res, rawBody, {
+                            reqStart,
+                            hasImage: false,
+                            origSizeKB,
+                        }, requestController.signal);
+                        return;
+                    }
                     const requestData = JSON.parse(rawBody);
+                    log(`[阶段] JSON解析完成 ${req.method} ${pathOnly} elapsed=${Date.now() - reqStart}ms`);
                     let hasImage = false;
                     if (Array.isArray(requestData.messages)) {
                         for (const msg of requestData.messages) {
-                            if (Array.isArray(msg.content)) {
-                                for (const block of msg.content) {
-                                    // 检测所有可能的图片格式
-                                    if (block?.type === "image" ||
-                                        block?.type === "image_url" ||
-                                        (block?.type === "tool_result" && Array.isArray(block.content))) {
-                                        hasImage = true;
-                                        break;
-                                    }
-                                }
-                            }
+                            hasImage = contentHasImage(msg.content);
                             if (hasImage)
                                 break;
                         }
                     }
                     if (hasImage) {
                         log(`[image-proxy] 检测到图片，开始识别...`);
-                        requestData.messages = await processMessages(requestData.messages);
+                        requestData.messages = await processMessages(requestData.messages, requestController.signal);
+                        log(`[阶段] 图片处理完成 ${req.method} ${pathOnly} elapsed=${Date.now() - reqStart}ms`);
+                        logForwardedImageTexts(requestData.messages);
                         const newBody = JSON.stringify(requestData);
-                        forwardRequest(req, res, newBody);
+                        forwardRequest(req, res, newBody, {
+                            reqStart,
+                            hasImage: true,
+                            origSizeKB,
+                        }, requestController.signal);
                     }
                     else {
-                        forwardRequest(req, res, rawBody);
+                        forwardRequest(req, res, rawBody, {
+                            reqStart,
+                            hasImage: false,
+                            origSizeKB,
+                        }, requestController.signal);
                     }
                 }
                 catch (err) {
+                    if (requestController.signal.aborted || isCanceledError(err)) {
+                        return;
+                    }
                     log(`[image-proxy] 处理失败: ${err.message}`);
                     if (!res.headersSent) {
                         res.writeHead(500, { "Content-Type": "application/json" });
@@ -319,28 +621,73 @@ export function startImageProxy() {
                 log(`[image-proxy] 请求错误: ${err.message}`);
             });
         });
-        let retried = false;
         server.on("error", (err) => {
             const msg = err.message;
-            if (msg.includes("EADDRINUSE") && !retried) {
-                retried = true;
-                log(`[image-proxy] 端口 ${PROXY_PORT} 被占用，清理旧进程后重试...`);
-                killProcessOnPort(PROXY_PORT);
-                setTimeout(() => {
-                    server.listen(PROXY_PORT, "127.0.0.1");
-                }, 1000);
+            if (msg.includes("EADDRINUSE")) {
+                // 端口已被占用。锁机制保证正常情况下只有一个本 MCP 代理在跑，
+                // 这里被占用说明是其他程序，或锁在极端情况下漏网。
+                // 不再 kill（避免杀掉正在处理请求的代理），直接放弃启动。
+                log(`[image-proxy] 端口 ${PROXY_PORT} 已被占用，放弃启动代理（MCP 工具仍可用）`);
             }
             else {
-                // 其他错误或重试仍失败，不阻塞 MCP 启动
                 log(`[image-proxy] 代理启动失败（MCP 工具仍可用）: ${msg}`);
-                resolve();
             }
+            releaseLock();
+            resolve();
         });
         server.listen(PROXY_PORT, "127.0.0.1", () => {
-            log(`[image-proxy] 代理已启动: http://127.0.0.1:${PROXY_PORT}`);
+            log(`[image-proxy] 代理已启动: http://127.0.0.1:${PROXY_PORT} (pid ${process.pid})`);
             log(`[image-proxy] 上游 API: ${UPSTREAM_BASE_URL}`);
             resolve();
         });
     });
 }
+// ────────────────────── MCP 端：按需拉起独立代理 ──────────────────────
+// 独立代理入口脚本（与本文件同目录，编译后为 dist/proxy/standaloneProxy.js）
+const STANDALONE_SCRIPT = fileURLToPath(new URL("standaloneProxy.js", import.meta.url));
+// 读取锁文件里登记的代理 PID；不存在/无效返回 null
+function readLockHolderPid() {
+    try {
+        const pid = parseInt(fs.readFileSync(LOCK_FILE, "utf8").trim(), 10);
+        return Number.isFinite(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+// MCP 进程调用：确保有一个独立常驻的图片代理在运行。
+// - 锁持有者进程存活 → 复用已有代理
+// - 否则 detached spawn 一个独立代理进程，与本 MCP 进程生命周期解耦
+// 任何一个 Claude Code 会话退出都不影响代理，代理常驻至自身崩溃或被主动 kill。
+export function ensureImageProxyRunning() {
+    return new Promise((resolve) => {
+        if (!UPSTREAM_BASE_URL) {
+            log("[image-proxy] 未设置 UPSTREAM_BASE_URL，代理功能不可用（MCP 工具仍可用）");
+            resolve();
+            return;
+        }
+        // 1. 已有独立代理在运行则直接复用
+        const holderPid = readLockHolderPid();
+        if (holderPid !== null && isProcessAlive(holderPid)) {
+            log(`[image-proxy] 独立代理已在运行 (pid ${holderPid})，复用`);
+            resolve();
+            return;
+        }
+        // 2. detached spawn 独立代理进程：stdio ignore + unref，独立于父进程生命周期
+        try {
+            const child = spawn(process.execPath, [STANDALONE_SCRIPT], {
+                detached: true,
+                stdio: "ignore",
+                env: { ...process.env },
+            });
+            child.unref();
+            log(`[image-proxy] 已拉起独立代理进程 (pid ${child.pid})`);
+        }
+        catch (err) {
+            log(`[image-proxy] 拉起独立代理进程失败: ${err.message}（MCP 工具仍可用）`);
+        }
+        // 不等待子进程 listen 完成即返回：MCP 工具不依赖代理，代理会在后台就绪
+        resolve();
+    });
+}
 //# sourceMappingURL=imageProxy.js.map