@agent-proxy/zcode 0.0.0-stage → 0.11.1

package/dist/vision.js

@@ -0,0 +1,204 @@
+/** zcode 链路图片识别适配：analyze_image 声明、图片清单、标识反查与网关侧执行器。 */
+import { createHash } from "node:crypto";
+import executorTemplateJson from "./vision-template.json";
+import { isZcodeRecord } from "./wire.js";
+export const ANALYZE_IMAGE_TOOL_NAME = "analyze_image";
+export class ZcodeVisionError extends Error {
+    constructor(message) { super(message); this.name = "ZcodeVisionError"; }
+}
+/**
+ * z.ai 内置工具的调用与结果是以普通助手 Markdown 流式输出的（实测 web_search_prime：
+ * `**🌐 Z.ai Built-in Tool: …**` + Input 代码块 + `*Executing on server...*`，随后另起一条
+ * `**Output:**\n**…_result_summary:** [...]`）。网关代执行 analyze_image 时复刻同一形状，
+ * Codex 才会把它渲染成与 web_search_prime 相同的 "Z.ai Built-in Tool" 卡片。
+ */
+export function gatewayToolCallNarration(call) {
+    return [
+        `**🌐 Z.ai Built-in Tool: ${call.name}**`,
+        "",
+        "**Input:**",
+        "```json",
+        JSON.stringify(call.input),
+        "```",
+        "*Executing on server...*",
+        "",
+    ].join("\n");
+}
+/** 与 z.ai 的 result_summary 旁白同形：结果作为 JSON 文本块出现在 Output 卡片里。 */
+export function gatewayToolResultNarration(name, result) {
+    return `**Output:**\n**${name}_result_summary:** [{"text": ${JSON.stringify(result)}, "type": "text"}]`;
+}
+/**
+ * 与 z.ai MCP 形状对齐（imageSource + prompt）；显式声明后模型会确定性地调用图片识别，
+ * 并在 imageSource 里携带服务端改写给它的图片 URL。
+ */
+export const ANALYZE_IMAGE_TOOL_DECLARATION = {
+    name: ANALYZE_IMAGE_TOOL_NAME,
+    description: "Analyze an image using advanced AI vision models with comprehensive understanding capabilities. Only supports remote URL.",
+    input_schema: {
+        type: "object",
+        properties: {
+            imageSource: { type: "string", description: "Remote URL to the image (supports PNG, JPG, JPEG)" },
+            prompt: { type: "string", description: "Detailed text prompt describing what to analyze, extract, or understand from the image." },
+        },
+        required: ["imageSource", "prompt"],
+        additionalProperties: false,
+    },
+};
+export const ANALYZE_IMAGE_SYSTEM_NOTE = [
+    "## 图片识别适配",
+    "当前模型无法直接查看图片像素；请求中的图片已由服务端上传并替换为 CDN URL（图片附近会给出以 maas-log-prod 开头的 URL，URL 文件名即图片标识）。",
+    `请使用 ${ANALYZE_IMAGE_TOOL_NAME} 工具识别图片：imageSource 传图片 URL，prompt 传具体识别要求。`,
+    "不要假装能看到图片内容，也不要用本地 OCR 命令替代；识别结果返回后再整理作答。",
+].join("\n");
+/**
+ * 图片字节的内容标识。非安全用途：z.ai CDN 以图片字节摘要的 32 位十六进制作为 URL
+ * 文件名（实测确认），网关用同一约定把模型回传的 URL 反查回本地 base64，不做完整性校验。
+ */
+export function imageIdentifier(data) {
+    return createHash("md5").update(Buffer.from(data, "base64")).digest("hex");
+}
+/** 遍历翻译后的 Anthropic messages，收集全部 base64 图片（按标识去重）。 */
+export function collectZcodeImages(messages) {
+    const images = new Map();
+    const visitBlock = (block) => {
+        if (!isZcodeRecord(block))
+            return;
+        if (block.type === "image" && isZcodeRecord(block.source)) {
+            const source = block.source;
+            if (source.type === "base64" && typeof source.data === "string" && source.data) {
+                const mediaType = typeof source.media_type === "string" && source.media_type ? source.media_type : "image/png";
+                const identifier = imageIdentifier(source.data);
+                if (!images.has(identifier))
+                    images.set(identifier, { identifier, media_type: mediaType, data: source.data });
+            }
+            return;
+        }
+        // tool_result 的图片在 content 数组内（view_image 等工具的返回形态）。
+        if (block.type === "tool_result" && Array.isArray(block.content))
+            block.content.forEach(visitBlock);
+    };
+    const visitContent = (content) => {
+        if (Array.isArray(content))
+            content.forEach(visitBlock);
+        else if (isZcodeRecord(content))
+            visitContent(content.content);
+    };
+    if (Array.isArray(messages)) {
+        for (const message of messages) {
+            if (isZcodeRecord(message))
+                visitContent(message.content);
+        }
+    }
+    return [...images.values()];
+}
+/** 模型回传的 imageSource（CDN URL 或其他引用）反查请求图片；单图时无条件兜底。 */
+export function matchZcodeAnalyzeImage(source, images) {
+    if (images.length === 0)
+        return undefined;
+    if (images.length === 1)
+        return images[0];
+    if (typeof source !== "string" || !source)
+        return undefined;
+    const match = source.match(/([0-9a-f]{32})\.(?:png|jpe?g|webp|gif|bmp)/i);
+    if (!match)
+        return undefined;
+    const identifier = match[1].toLowerCase();
+    return images.find((image) => image.identifier === identifier);
+}
+const executorTemplate = executorTemplateJson;
+/** 执行器 SSE 把公告与结果拼接成文本；结果通常跟在最后一个 result_summary 标记后。 */
+export function analysisFromExecutorText(text) {
+    const marker = "analyze_image_result_summary";
+    const index = text.lastIndexOf(marker);
+    if (index < 0)
+        return text.trim();
+    const tail = text.slice(index + marker.length).trim();
+    const unwrapped = tail.replace(/^[::*`\s"']+/, "").replace(/[`"']+$/, "").trim();
+    return unwrapped || text.trim();
+}
+async function attemptOnce(options) {
+    const headers = await options.headers();
+    const timeout = AbortSignal.timeout(options.attemptTimeoutMs ?? 120_000);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    const instruction = `使用 analyze_image 工具识别这张图片，按以下要求输出：${options.prompt}`;
+    const body = {
+        model: options.model,
+        max_tokens: 4096,
+        stream: true,
+        // 完整 Claude Code 指纹（system+tools）是服务端代执行的触发条件，模板逐字来自实测请求。
+        system: executorTemplate.system,
+        tools: executorTemplate.tools,
+        messages: [{
+                role: "user",
+                content: [
+                    { type: "image", source: { type: "base64", media_type: options.image.media_type, data: options.image.data } },
+                    { type: "text", text: instruction },
+                ],
+            }],
+    };
+    const response = await options.fetchImpl(options.url, {
+        method: "POST", headers, body: JSON.stringify(body), redirect: "manual", signal,
+    });
+    if (!response.ok || !response.body) {
+        const text = await response.text().catch(() => "");
+        // 先对完整正文脱敏、后截断：截断会把跨边界的 key 切成脱敏匹配不到的前缀片段。
+        const sanitized = options.redact ? options.redact(text) : text;
+        throw new ZcodeVisionError(`执行信封上游返回 HTTP ${response.status}${sanitized ? `：${sanitized.slice(0, 200)}` : ""}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let text = "";
+    let executed = false;
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let index;
+        while ((index = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, index).trim();
+            buffer = buffer.slice(index + 1);
+            if (!line.startsWith("data:"))
+                continue;
+            const payload = line.slice(5).trim();
+            if (!payload || payload === "[DONE]")
+                continue;
+            let frame;
+            try {
+                frame = JSON.parse(payload);
+            }
+            catch {
+                continue;
+            }
+            const block = isZcodeRecord(frame.content_block) ? frame.content_block : undefined;
+            if (frame.type === "content_block_start" && block?.type === "server_tool_use" && block.name === ANALYZE_IMAGE_TOOL_NAME)
+                executed = true;
+            const delta = isZcodeRecord(frame.delta) ? frame.delta : undefined;
+            if (frame.type === "content_block_delta" && delta?.type === "text_delta" && typeof delta.text === "string")
+                text += delta.text;
+        }
+    }
+    if (!executed)
+        throw new ZcodeVisionError("执行信封未触发服务端 analyze_image");
+    return analysisFromExecutorText(text);
+}
+/** 网关侧执行 analyze_image：以 Claude Code 指纹信封侧请求，服务端在同一条 SSE 内完成识别。 */
+export async function executeZcodeAnalyzeImage(options) {
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (options.signal?.aborted)
+            throw new ZcodeVisionError("analyze_image 执行已取消");
+        try {
+            return await attemptOnce(options);
+        }
+        catch (error) {
+            lastError = error;
+            if (options.signal?.aborted)
+                throw error;
+        }
+    }
+    throw new ZcodeVisionError(`analyze_image 执行失败（${maxAttempts} 次尝试）：${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}

package/dist/wire.d.ts

@@ -0,0 +1,23 @@
+/** ZCode 协议共享类型；元数据不包含授权凭据。 */
+export interface ZcodeToolDefinition {
+    name: string;
+    custom: boolean;
+    namespace?: string;
+    /** 网关代执行标记：该工具由网关在上游续跑中执行并吸收，不回传客户端。 */
+    gateway?: "analyze_image";
+}
+export type ZcodeToolMap = Map<string, ZcodeToolDefinition>;
+export interface ZcodeTranslatedRequest {
+    body: Record<string, unknown>;
+    tools: ZcodeToolMap;
+    /** 被剥离的服务器内置工具类型名，供日志与降级说明使用。 */
+    dropped: string[];
+    /** 请求含图片且已声明网关代执行的 analyze_image 工具。 */
+    vision: boolean;
+    /** 请求内收集到的 base64 图片清单（按内容标识去重），供代执行反查。 */
+    images: import("./vision.ts").ZcodeRequestImage[];
+}
+export declare function isZcodeRecord(value: unknown): value is Record<string, unknown>;
+/** 本地不透明回传载荷，不代表 OpenAI 的加密思考格式。 */
+export declare function encodeZcodeThinking(model: string, blocks: Record<string, unknown>[]): string;
+export declare function decodeZcodeThinking(value: unknown, model: string): Record<string, unknown>[] | undefined;

package/dist/wire.js

@@ -0,0 +1,25 @@
+export function isZcodeRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const THINKING_PREFIX = "zcode-thinking-v1:";
+/** 本地不透明回传载荷，不代表 OpenAI 的加密思考格式。 */
+export function encodeZcodeThinking(model, blocks) {
+    return THINKING_PREFIX + Buffer.from(JSON.stringify({ model, blocks }), "utf8").toString("base64");
+}
+export function decodeZcodeThinking(value, model) {
+    if (typeof value !== "string" || !value.startsWith(THINKING_PREFIX))
+        return undefined;
+    try {
+        const data = JSON.parse(Buffer.from(value.slice(THINKING_PREFIX.length), "base64").toString("utf8"));
+        if (!isZcodeRecord(data) || data.model !== model || !Array.isArray(data.blocks))
+            return undefined;
+        if (!data.blocks.every((block) => isZcodeRecord(block)
+            && ((block.type === "thinking" && typeof block.thinking === "string" && typeof block.signature === "string")
+                || (block.type === "redacted_thinking" && typeof block.data === "string"))))
+            return undefined;
+        return data.blocks;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@agent-proxy/zcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.11.1",
+  "description": "Agent Proxy zcode 插件；保留基线转换行为。",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./dist/*.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-library.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "bun ../../scripts/verify-package.ts ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aceHubert/codex-cliproxy-gateway.git"
+  },
+  "devDependencies": {
+    "@agent-proxy/models": "0.11.1"
+  },
+  "dependencies": {
+    "@agent-proxy/llm-bridge": "0.11.1",
+    "@agent-proxy/plugin-api": "0.11.1"
+  },
+  "gitHead": "affd71836c6cb82ec474edc5efa46146eb92398f"
+}