@agent-proxy/zcode 0.20.3 → 0.21.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { bindHostMethods, withHostServices } from "@agent-proxy/plugin-api";
+import { bindHostMethods, getHostServices, withHostServices } from "@agent-proxy/plugin-api";
 import path from "node:path";
 import { isIP } from "node:net";
 import { resolvePaths } from "@agent-proxy/plugin-api";
@@ -306,6 +306,11 @@ function buildZcodeAdapter(config, dependencies = {}) {
             const incoming = new URL(request.url);
             const group = logGroupFromPath(incoming.pathname);
             const zcode = isZcodeModel(input.model);
+            // 响应体由 HTTP 层在本插件的 withHostServices 之外泵送，流中段（onComplete、
+            // 视觉续跑腿）再调 getHostServices 会抛「插件主机上下文未初始化」——这也是
+            // 插件交换日志长期缺失的根因。捕获本次请求的主机上下文供流内回调显式重入。
+            const host = getHostServices();
+            const inHostContext = (action) => withHostServices(host, action);
             // 渠道（zai/bigmodel）只在转发时按当前套餐快照判定，用于鉴权与日志分流；模型 ID 不携带渠道。
             let family;
             let key = "";
@@ -349,24 +354,27 @@ function buildZcodeAdapter(config, dependencies = {}) {
                 logged = true;
                 const durationMs = Date.now() - start;
                 const at = incoming.pathname + incoming.search;
-                logExchange(sink, group, {
-                    requestTime, method: request.method, url: at,
-                    reqHeaders: request.headers, reqBody: redactValue(input),
-                    status, resHeaders: headers, resBody: redact(body), upstreamUrl, upstreamRequestHeaders, upstreamRequestBody, durationMs,
-                }, "zcode");
-                // 与网关主链一样，进程日志里每条请求恰好一行：逻辑错误也算错误，走错误摘要。
-                if (status >= 400 || logicalError) {
-                    logGatewayError(sink?.processLog, {
+                // onComplete 等流内调用点已在主机上下文之外，落盘前显式重入。
+                inHostContext(() => {
+                    logExchange(sink, group, {
                         requestTime, method: request.method, url: at,
-                        status: logicalError && status < 400 ? 502 : status,
-                        message: redact(logicalError ?? body), upstreamUrl, durationMs,
-                    });
-                }
-                else {
-                    logRequestSummary(sink?.processLog, {
-                        requestTime, method: request.method, url: at, status, upstreamUrl, durationMs,
-                    });
-                }
+                        reqHeaders: request.headers, reqBody: redactValue(input),
+                        status, resHeaders: headers, resBody: redact(body), upstreamUrl, upstreamRequestHeaders, upstreamRequestBody, durationMs,
+                    }, "zcode");
+                    // 与网关主链一样，进程日志里每条请求恰好一行：逻辑错误也算错误，走错误摘要。
+                    if (status >= 400 || logicalError) {
+                        logGatewayError(sink?.processLog, {
+                            requestTime, method: request.method, url: at,
+                            status: logicalError && status < 400 ? 502 : status,
+                            message: redact(logicalError ?? body), upstreamUrl, durationMs,
+                        });
+                    }
+                    else {
+                        logRequestSummary(sink?.processLog, {
+                            requestTime, method: request.method, url: at, status, upstreamUrl, durationMs,
+                        });
+                    }
+                });
             };
             const fail = (status, message, type) => {
                 const response = zcodeError(status, redact(message), type);
@@ -468,6 +476,7 @@ function buildZcodeAdapter(config, dependencies = {}) {
                 // 图片识别适配：请求含图片时把被吸收的 analyze_image 调用落到网关执行并续跑上游。
                 let gatewayTools;
                 let continuationLegs = 0;
+                const visionAttemptNotes = [];
                 if (translated.vision) {
                     gatewayTools = {
                         maxContinuations: 3,
@@ -495,6 +504,24 @@ function buildZcodeAdapter(config, dependencies = {}) {
                                     signal: abort.signal,
                                     // 错误正文脱敏必须在截断之前发生（见 ZcodeExecutorOptions.redact）。
                                     redact,
+                                    // 执行腿不经过网关交换日志：每次尝试的结局写进程日志，并在收尾时
+                                    // 汇入交换日志尾部，服务端瞬时故障（如 MCP 1210）才能事后取证。
+                                    onAttempt: (summary) => {
+                                        visionAttemptNotes.push(`attempt ${summary.attempt}/${summary.maxAttempts} ${summary.ok ? "ok" : "failed"}: ${summary.detail}`);
+                                        const entry = {
+                                            requestTime, method: "POST",
+                                            url: `${incoming.pathname}${incoming.search} [analyze_image ${summary.attempt}/${summary.maxAttempts}]`,
+                                            durationMs: summary.durationMs, upstreamUrl: routedUrl,
+                                        };
+                                        inHostContext(() => {
+                                            if (summary.ok) {
+                                                logRequestSummary(sink?.processLog, { ...entry, status: 200 });
+                                            }
+                                            else {
+                                                logGatewayError(sink?.processLog, { ...entry, status: 502, message: `[analyze_image] ${summary.detail}` });
+                                            }
+                                        });
+                                    },
                                 });
                             }
                             catch (error) {
@@ -596,8 +623,9 @@ function buildZcodeAdapter(config, dependencies = {}) {
                         // 剥离的内置工具与图片识别续跑腿数写进交换日志，避免“静默降级”无从排查。
                         const stripped = translated.dropped.length ? `\n--- stripped built-in tools: ${translated.dropped.join(", ")} ---` : "";
                         const visionLegs = continuationLegs > 0 ? `\n--- analyze_image continuation legs: ${continuationLegs} ---` : "";
+                        const visionAttempts = visionAttemptNotes.length ? `\n--- analyze_image attempts ---\n${visionAttemptNotes.join("\n")}` : "";
                         if (!mapResult)
-                            log(stream ? 200 : payload.status === "failed" ? 502 : 200, stream ? `${chunks}${stripped}${visionLegs}\n--- response.${payload.status} ---\n${JSON.stringify(redactValue(payload))}` : `${JSON.stringify(redactValue(payload))}${stripped}${visionLegs}`, new Headers({ "content-type": stream ? "text/event-stream" : "application/json" }), payload.status === "failed" ? JSON.stringify(payload.error ?? "响应失败") : undefined);
+                            log(stream ? 200 : payload.status === "failed" ? 502 : 200, stream ? `${chunks}${stripped}${visionLegs}${visionAttempts}\n--- response.${payload.status} ---\n${JSON.stringify(redactValue(payload))}` : `${JSON.stringify(redactValue(payload))}${stripped}${visionLegs}${visionAttempts}`, new Headers({ "content-type": stream ? "text/event-stream" : "application/json" }), payload.status === "failed" ? JSON.stringify(payload.error ?? "响应失败") : undefined);
                     },
                 });
                 if (!mapResult)

package/dist/response.js

@@ -1,4 +1,4 @@
-import { createClientResponse } from "@agent-proxy/llm-bridge";
+import { createClientResponse, remapUndeclaredToolName } from "@agent-proxy/llm-bridge";
 import { encodeZcodeThinking, isZcodeRecord } from "./wire.js";
 import { gatewayToolCallNarration, gatewayToolResultNarration } from "./vision.js";
 /** z.ai 的服务端搜索按 web_search_prime/search_query 形状返回 query；兼容 Anthropic 标准的 query。 */
@@ -483,9 +483,18 @@ export async function createZcodeResponse(upstream, options) {
                 const tool = normalized.find((value) => value.type === "tool_call_start");
                 const call = record(tool?.tool_call, "tool call");
                 const name = requiredString(call.name, "tool name");
-                const mapped = options.tools.get(name);
-                if (!mapped)
-                    throw new Error(`ZCode 返回了未声明的工具：${name}`);
+                let mapped = options.tools.get(name);
+                if (!mapped) {
+                    // 上游可能回吐与折叠声明名仅分隔符/哈希不同的调用名：骨架唯一匹配时
+                    // 对回声明名；完全无法对应的调用按未知块忽略，不再整条断流。
+                    const remapped = remapUndeclaredToolName(name, options.tools);
+                    if (remapped !== undefined)
+                        mapped = options.tools.get(remapped);
+                }
+                if (!mapped) {
+                    ignoredBlocks.add(index);
+                    return result;
+                }
                 if (mapped.gateway) {
                     if (!options.gatewayTools)
                         throw new Error(`ZCode 网关工具 ${name} 缺少执行钩子`);

package/dist/vision.d.ts

@@ -40,6 +40,12 @@ export declare function collectZcodeImages(messages: unknown): ZcodeRequestImage
 export declare function matchZcodeAnalyzeImage(source: unknown, images: ZcodeRequestImage[]): ZcodeRequestImage | undefined;
 /** 执行器 SSE 把公告与结果拼接成文本；结果通常跟在最后一个 result_summary 标记后。 */
 export declare function analysisFromExecutorText(text: string): string;
+/**
+ * 服务端 analyze_image 执行失败的识别：失败时 result_summary 的首个文本条目以
+ * `MCP error <code>` 开头（实测瞬时故障返回 `MCP error 400: … "图片输入格式/解析错误"`）。
+ * 只检查摘要片段开头的一小段，避免把「内容恰好描述 MCP 报错的截图」的识别成功误判为失败。
+ */
+export declare function serverToolResultFailed(text: string): boolean;
 export interface ZcodeExecutorOptions {
     url: string;
     model: string;
@@ -57,6 +63,17 @@ export interface ZcodeExecutorOptions {
      * 边界时，先截断再脱敏会留下可还原的前缀片段。由调用方（zcode.ts）注入。
      */
     redact?: (text: string) => string;
+    /** 每次尝试结束（成功、服务端失败或异常）后的观测回调；用于进程日志留痕。 */
+    onAttempt?: (summary: ZcodeExecutorAttempt) => void;
+}
+/** 一次 analyze_image 执行尝试的结果摘要；detail 已由调用方脱敏。 */
+export interface ZcodeExecutorAttempt {
+    attempt: number;
+    maxAttempts: number;
+    /** false 表示服务端执行失败（MCP 错误结果）或本次尝试抛错。 */
+    ok: boolean;
+    durationMs: number;
+    detail: string;
 }
 /** 网关侧执行 analyze_image：以 Claude Code 指纹信封侧请求，服务端在同一条 SSE 内完成识别。 */
 export declare function executeZcodeAnalyzeImage(options: ZcodeExecutorOptions): Promise<string>;

package/dist/vision.js

@@ -117,6 +117,26 @@ export function analysisFromExecutorText(text) {
     const unwrapped = tail.replace(/^[::*`\s"']+/, "").replace(/[`"']+$/, "").trim();
     return unwrapped || text.trim();
 }
+/**
+ * 服务端 analyze_image 执行失败的识别：失败时 result_summary 的首个文本条目以
+ * `MCP error <code>` 开头（实测瞬时故障返回 `MCP error 400: … "图片输入格式/解析错误"`）。
+ * 只检查摘要片段开头的一小段，避免把「内容恰好描述 MCP 报错的截图」的识别成功误判为失败。
+ */
+export function serverToolResultFailed(text) {
+    const marker = "analyze_image_result_summary";
+    const index = text.lastIndexOf(marker);
+    const segment = (index >= 0 ? text.slice(index + marker.length) : text).slice(0, 200).replace(/\\/g, "");
+    return /mcp error \d+/i.test(segment);
+}
+/** 观测回调必须不致命：落日志失败不得影响识别执行本身。 */
+function reportAttempt(options, summary) {
+    try {
+        options.onAttempt?.(summary);
+    }
+    catch {
+        // 依赖插件主机上下文的日志实现可能在流中段抛错；观察钩子静默降级。
+    }
+}
 async function attemptOnce(options) {
     const headers = await options.headers();
     const timeout = AbortSignal.timeout(options.attemptTimeoutMs ?? 120_000);
@@ -191,11 +211,31 @@ export async function executeZcodeAnalyzeImage(options) {
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         if (options.signal?.aborted)
             throw new ZcodeVisionError("analyze_image 执行已取消");
+        const startedAt = Date.now();
         try {
-            return await attemptOnce(options);
+            const result = await attemptOnce(options);
+            // 服务端把 MCP 错误当正常结果流回（信封本身 HTTP 200）：识别为失败并重试，
+            // 实测该类失败为上游瞬时故障，同图同链路稍后即可成功。
+            if (serverToolResultFailed(result)) {
+                const detail = options.redact ? options.redact(result.slice(0, 200)) : result.slice(0, 200);
+                reportAttempt(options, { attempt, maxAttempts, ok: false, durationMs: Date.now() - startedAt, detail });
+                lastError = new ZcodeVisionError(detail);
+                if (options.signal?.aborted)
+                    throw lastError;
+                continue;
+            }
+            reportAttempt(options, {
+                attempt, maxAttempts, ok: true, durationMs: Date.now() - startedAt,
+                detail: `识别成功（图片 ${options.image.identifier}，${Math.trunc(options.image.data.length * 3 / 4 / 1024)}KB）`,
+            });
+            return result;
         }
         catch (error) {
             lastError = error;
+            reportAttempt(options, {
+                attempt, maxAttempts, ok: false, durationMs: Date.now() - startedAt,
+                detail: options.redact ? options.redact(error instanceof Error ? error.message : String(error)).slice(0, 200) : String(error).slice(0, 200),
+            });
             if (options.signal?.aborted)
                 throw error;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-proxy/zcode",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Agent Proxy zcode 插件；保留基线转换行为。",
   "type": "module",
   "exports": {
@@ -35,11 +35,11 @@
     "url": "git+https://github.com/aceHubert/codex-cliproxy-gateway.git"
   },
   "devDependencies": {
-    "@agent-proxy/models": "0.20.2"
+    "@agent-proxy/models": "0.21.0"
   },
   "dependencies": {
-    "@agent-proxy/llm-bridge": "0.20.3",
-    "@agent-proxy/plugin-api": "0.20.2"
+    "@agent-proxy/llm-bridge": "0.21.0",
+    "@agent-proxy/plugin-api": "0.21.0"
   },
-  "gitHead": "b5922449d4fc9c2952b324031aee4f254e1b4d14"
+  "gitHead": "59b68f3e371fec94cfc4854303e34fc5d8427e3b"
 }