@agent-proxy/zcode 0.0.0-stage → 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-cliproxy-gateway contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @agent-proxy/zcode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Deploy](https://github.com/aceHubert/codex-cliproxy-gateway/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/aceHubert/codex-cliproxy-gateway/actions/workflows/deploy.yml)
+[![npm 版本](https://img.shields.io/npm/v/@agent-proxy/zcode)](https://www.npmjs.com/package/@agent-proxy/zcode)
+
+Agent Proxy 的 ZCode 插件，组合本地配置、套餐与 API Key 模型目录，
+处理 ZCode 模型路由和请求、响应转换。
+通过 `createZcodePlugin` 接入宿主服务。
+
+## 安装
+
+```sh
+bun add @agent-proxy/zcode
+```
+
+插件由 [@agent-proxy/gateway](https://www.npmjs.com/package/@agent-proxy/gateway)
+显式装配，并依赖宿主注入 `HostServices`；使用前需准备可用的 ZCode 配置。
+模型预设已内联到发布产物，无需安装私有 `@agent-proxy/models` 包。
+
+[项目源码与文档](https://github.com/aceHubert/codex-cliproxy-gateway)

package/dist/catalog.d.ts

@@ -0,0 +1,30 @@
+import type { ModelCatalog } from "@agent-proxy/plugin-api";
+import type { ZcodeProviderSnapshot, ZcodeSelection } from "./config.ts";
+export declare function isZcodeModel(model: unknown): boolean;
+/** ZCode 对外模型 ID 的固定前缀族：旧 API Key 命名空间与各套餐作用域前缀。
+ * API Key 多 provider 的前缀（zcode-<providerId>/）由 provider ID 动态生成，不在此列。 */
+export declare function zcodeStaticModelPrefixes(): string[];
+/** 从对外模型 ID 解析套餐连接形态；未声明的 zcode- 段不属于任何套餐。 */
+export declare function zcodeModelPlan(model: string): ZcodeSelection["kind"] | undefined;
+export declare function zcodeAPIProviderPrefix(providerID: string): string;
+/** 从 `zcode-<providerId>/model` 提取 provider ID；URL 编码用于容忍特殊 ID。 */
+export declare function zcodeAPIProviderIDFromModel(model: string): string | undefined;
+/** 目录使用厂商规范名称，上游使用当前套餐配置中的原始模型拼写。 */
+export declare function zcodeUpstreamModel(model: string, snapshot: ZcodeProviderSnapshot): string | undefined;
+/**
+ * 仅由模型包的厂商预设合成全量裸 ID 目录。纯内存计算，
+ * 重建成本与模型条数同级，不需要磁盘缓存，也不携带任何套餐或授权信息。
+ */
+export declare function buildZcodeVendorCatalog(): ModelCatalog;
+/** /models 只按快照套餐的支持集合筛选并加套餐作用域前缀，不重新合成厂商元数据。 */
+export declare function createZcodeCatalog(snapshot: ZcodeProviderSnapshot, cached: ModelCatalog): ModelCatalog;
+/** 按套餐支持集合（或多个套餐/entitlement 的能力并集）合成带套餐作用域前缀的目录。 */
+export declare function createZcodeCatalogForModels(modelIds: readonly string[], cached: ModelCatalog, plan?: ZcodeSelection["kind"], apiProviderID?: string, apiProviderName?: string): ModelCatalog;
+/** 启用 ZCode 时保留 zcode/ 顶层命名空间，防止上游同名条目与 ZCode 目录冲突。 */
+export declare function mergeZcodeCatalog(base: ModelCatalog, zcode: ModelCatalog): ModelCatalog;
+/**
+ * 把当前套餐的对外目录落盘。watch 驱动的账号/套餐切换与启动首读都会经过这里，
+ * `/v1/models` 只消费内存中的同一份结果；配置失效时写入空 models，不留旧套餐模型。
+ * 内容未变化时不写盘，返回是否发生了实际变更。
+ */
+export declare function writeZcodeServedCatalog(file: string, catalog: ModelCatalog): boolean;

package/dist/catalog.js

@@ -0,0 +1,150 @@
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { getVendorModelPresets } from "./resources/models.js";
+import { compileModelOverrides, synthesizeModelEntry } from "@agent-proxy/plugin-api";
+import { atomicWrite } from "@agent-proxy/plugin-api";
+const vendorModelIds = () => (getVendorModelPresets()["z.ai"] ?? []).map((model) => model.name);
+/** 旧版单 API Key 命名空间；新版多 Key 目录不再生成该前缀。 */
+const ZCODE_PREFIX = "zcode/";
+/** 套餐作用域前缀；API Key 因可有多个 provider，前缀由 provider ID 动态生成。 */
+const PLAN_PREFIXES = {
+    "individual-coding-plan": "zcode-individual-coding-plan/",
+    "team-coding-plan": "zcode-team-coding-plan/",
+    "start-plan": "zcode-start-plan/",
+};
+/** 显示名括号内与 ZCode 客户端模型选择器的套餐分组（个人/团队/免费）一致。 */
+const PLAN_DISPLAY_LABELS = {
+    "individual-coding-plan": "个人",
+    "team-coding-plan": "团队",
+    "start-plan": "免费",
+};
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export function isZcodeModel(model) {
+    return typeof model === "string" && /^zcode(?:\/|-)/i.test(model);
+}
+/** ZCode 对外模型 ID 的固定前缀族：旧 API Key 命名空间与各套餐作用域前缀。
+ * API Key 多 provider 的前缀（zcode-<providerId>/）由 provider ID 动态生成，不在此列。 */
+export function zcodeStaticModelPrefixes() {
+    return [ZCODE_PREFIX, ...Object.values(PLAN_PREFIXES)].filter((prefix) => typeof prefix === "string");
+}
+/** 从对外模型 ID 解析套餐连接形态；未声明的 zcode- 段不属于任何套餐。 */
+export function zcodeModelPlan(model) {
+    if (!isZcodeModel(model))
+        return undefined;
+    const id = model.toLowerCase();
+    for (const [kind, prefix] of Object.entries(PLAN_PREFIXES)) {
+        if (id.startsWith(prefix))
+            return kind;
+    }
+    return id.startsWith(ZCODE_PREFIX) || /^zcode-[^/]+\//.test(id) ? "api-key" : undefined;
+}
+export function zcodeAPIProviderPrefix(providerID) {
+    return `zcode-${encodeURIComponent(providerID)}/`;
+}
+/** 从 `zcode-<providerId>/model` 提取 provider ID；URL 编码用于容忍特殊 ID。 */
+export function zcodeAPIProviderIDFromModel(model) {
+    if (zcodeModelPlan(model) !== "api-key")
+        return undefined;
+    const match = /^zcode-([^/]+)\//i.exec(model);
+    if (!match)
+        return undefined;
+    try {
+        return decodeURIComponent(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 目录使用厂商规范名称，上游使用当前套餐配置中的原始模型拼写。 */
+export function zcodeUpstreamModel(model, snapshot) {
+    const plan = zcodeModelPlan(model);
+    // 套餐段必须与快照的连接形态一致：会话选了哪个套餐，就只能用该套餐的模型拼写。
+    if (!plan || plan !== snapshot.plan)
+        return;
+    const prefix = plan === "api-key"
+        ? model.toLowerCase().startsWith(zcodeAPIProviderPrefix(snapshot.providerID))
+            ? zcodeAPIProviderPrefix(snapshot.providerID)
+            : ZCODE_PREFIX
+        : PLAN_PREFIXES[plan];
+    if (!model.toLowerCase().startsWith(prefix.toLowerCase()))
+        return;
+    const id = model.slice(prefix.length).toLowerCase();
+    if (!id)
+        return;
+    if (!vendorModelIds().some((candidate) => candidate.toLowerCase() === id))
+        return;
+    return snapshot.modelIds.find((candidate) => candidate.toLowerCase() === id);
+}
+/** 归一化显示名：剥掉历史 ZCode 前缀/后缀，确保渠道标识只由投影层统一添加。 */
+function stripZcodeChannelLabel(name) {
+    return name
+        .replace(/^ZCode\//, "")
+        .replace(/ \(ZCode[^)]*\)$/, "")
+        .replace(/（ZCode[^）]*）$/, "");
+}
+/**
+ * 仅由模型包的厂商预设合成全量裸 ID 目录。纯内存计算，
+ * 重建成本与模型条数同级，不需要磁盘缓存，也不携带任何套餐或授权信息。
+ */
+export function buildZcodeVendorCatalog() {
+    const vendorModels = getVendorModelPresets();
+    const modelIds = (vendorModels["z.ai"] ?? []).map((model) => model.name);
+    const vendors = compileModelOverrides(vendorModels, "vendor_models.json");
+    const preset = { models: modelIds.map((id, index) => synthesizeModelEntry(`z.ai/${id}`, index, { models: [] }, vendors)) };
+    return { models: preset.models.map((entry) => {
+            const slug = entry.slug.slice("z.ai/".length);
+            return {
+                ...entry,
+                slug,
+                display_name: entry.display_name ?? slug,
+                prefer_websockets: false,
+                // zcode 链路已把 Responses web_search 原生映射为 web_search_20250305（实测 z.ai 支持）。
+                supports_search_tool: true,
+            };
+        }) };
+}
+/** /models 只按快照套餐的支持集合筛选并加套餐作用域前缀，不重新合成厂商元数据。 */
+export function createZcodeCatalog(snapshot, cached) {
+    return createZcodeCatalogForModels(snapshot.modelIds, cached, snapshot.plan, snapshot.plan === "api-key" ? snapshot.providerID : undefined, snapshot.providerName);
+}
+/** 按套餐支持集合（或多个套餐/entitlement 的能力并集）合成带套餐作用域前缀的目录。 */
+export function createZcodeCatalogForModels(modelIds, cached, plan = "api-key", apiProviderID, apiProviderName) {
+    const supported = new Set(modelIds.map((model) => model.toLowerCase()));
+    const prefix = plan === "api-key" && apiProviderID
+        ? zcodeAPIProviderPrefix(apiProviderID)
+        : PLAN_PREFIXES[plan] ?? ZCODE_PREFIX;
+    // 渠道统一用 ZCode/ 前缀标注（与 cliproxy/new-api 的同名条目区分），括号内只保留
+    // 套餐分组或多 Key 的 provider 名，不再重复 ZCode 字样。
+    const qualifier = plan === "api-key"
+        ? apiProviderID ? `（${apiProviderName ?? apiProviderID}）` : ""
+        : PLAN_DISPLAY_LABELS[plan] ? ` (${PLAN_DISPLAY_LABELS[plan]})` : "";
+    return { models: cached.models.filter((entry) => supported.has(entry.slug.toLowerCase())).map((entry) => ({
+            ...entry,
+            slug: `${prefix}${entry.slug}`,
+            display_name: `ZCode/${stripZcodeChannelLabel(entry.display_name ?? entry.slug)}${qualifier}`,
+        })) };
+}
+/** 启用 ZCode 时保留 zcode/ 顶层命名空间，防止上游同名条目与 ZCode 目录冲突。 */
+export function mergeZcodeCatalog(base, zcode) {
+    const models = base.models.filter((model) => !isZcodeModel(model.slug));
+    const priority = Math.max(0, ...models.map((model) => Number(model.priority) || 0)) + 100;
+    return { models: [...models, ...zcode.models.map((model, index) => ({ ...model, priority: priority + index }))] };
+}
+/**
+ * 把当前套餐的对外目录落盘。watch 驱动的账号/套餐切换与启动首读都会经过这里，
+ * `/v1/models` 只消费内存中的同一份结果；配置失效时写入空 models，不留旧套餐模型。
+ * 内容未变化时不写盘，返回是否发生了实际变更。
+ */
+export function writeZcodeServedCatalog(file, catalog) {
+    const contents = `${JSON.stringify({
+        content_hash: digest(catalog.models),
+        models: catalog.models,
+    }, null, 2)}\n`;
+    try {
+        if (fs.readFileSync(file, "utf8") === contents)
+            return false;
+    }
+    catch { /* 缺失或不可读时直接写入。 */ }
+    atomicWrite(file, contents);
+    return true;
+}

package/dist/client-signing.d.ts

@@ -0,0 +1,46 @@
+/** 业务 key 必须是恰好一个点分隔的 `{id}.{secret}`；账号 JWT（两个点）不适用。 */
+export declare function parseClientSigningCredential(apiKey: string): {
+    apiKeyId: string;
+    apiKeySecret: string;
+} | undefined;
+/** PoW：对 `id\nappId\nsessionId\nts` 的 SHA-256 hex 前缀找 8 个前导零比特。 */
+export declare function solveClientRequestPow(input: {
+    apiKeyId: string;
+    sessionId: string;
+    ts: string;
+}, bits?: number): string;
+/** 401 响应正文中的可刷新签名拒绝原因；与官方客户端同序检查 msg/data.reason/error.*。 */
+export declare function clientSigningVerifyRejection(body: string): string | undefined;
+export interface ZcodeClientSigningOptions {
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    now?: () => number;
+    randomHex?: (bytes: number) => string;
+    handshakeTimeoutMs?: number;
+    failureCooldownMs?: number;
+}
+export interface ZcodeClientSigningScope {
+    apiKey: string;
+    /** provider baseURL；握手 origin 与缓存键取自它（签名发生在端点重映射之前）。 */
+    baseUrl: string;
+    clientVersion: string;
+    sessionId: string;
+}
+export declare class ZcodeClientSigning {
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly randomHexImpl;
+    private readonly handshakeTimeoutMs;
+    private readonly failureCooldownMs;
+    private readonly keys;
+    private readonly retryAfter;
+    constructor(options?: ZcodeClientSigningOptions);
+    /**
+     * 就地补齐一个请求的签名头；返回是否签名成功。除缺少必要输入外，任何失败
+     * （网络、协议、密码学）都返回 false 并保持原头不动，由调用方按未签名继续。
+     */
+    decorate(headers: Headers, scope: ZcodeClientSigningScope): Promise<boolean>;
+    /** 服务端拒绝（VERIFY_*）或密钥疑似轮换后作废缓存；下一次 decorate 重新握手。 */
+    invalidate(apiKey: string, baseUrl: string): void;
+    private beginHandshake;
+    private handshake;
+}

package/dist/client-signing.js

@@ -0,0 +1,225 @@
+/**
+ * ZCode Client Request Signing（coding plan 官方客户端签名）。
+ *
+ * 官方客户端对 coding plan 且官方域名的模型请求会附加一组逐请求签名头
+ * （X-App-Id/X-Client-Ts/X-Client-Version/X-Client-Sig/X-Client-Nonce/X-Client-Pow），
+ * 服务端据此把流量归因为官方 ZCode 客户端。签名身份通过握手建立：客户端用
+ * `{id}.{secret}` 形态的业务 key 派生 HKDF 密钥，向上游换取一份用该密钥加密的
+ * Ed25519 私钥，再对每个请求的时间戳/随机数做 Ed25519 签名与轻量 PoW。
+ *
+ * 本模块逐字节复刻该协议，全部输入来自网关已持有的业务 key；任何一步失败都
+ * fail-open：不加签名头，请求按未签名继续发送（与官方客户端 VERIFY_* 重试耗尽
+ * 后的 bypass 行为一致），绝不阻塞或断流。
+ */
+import { createHash } from "node:crypto";
+const HANDSHAKE_PATH = "/api/paas/c1f3a7e2/v2/client";
+const HANDSHAKE_ACTION = "get_sign_key";
+const KDF_SALT = "WD_CLIENT_SIGN_KDF_SALT";
+const HMAC_INFO = "getSignKey_hmac";
+const PRIVATE_KEY_INFO = "ed25519_priv";
+const APP_ID = "zcode";
+const POW_BITS = 8;
+const NONCE_BYTES = 16;
+const POW_SALT_BYTES = 12;
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+const FAILURE_COOLDOWN_MS = 30_000;
+const MAX_KEY_ENTRIES = 32;
+const VERIFY_SIGNATURE_INVALID = "VERIFY_SIGNATURE_INVALID";
+const VERIFY_APIKEY_EXPIRED = "VERIFY_APIKEY_EXPIRED";
+/** 业务 key 必须是恰好一个点分隔的 `{id}.{secret}`；账号 JWT（两个点）不适用。 */
+export function parseClientSigningCredential(apiKey) {
+    const separator = apiKey.indexOf(".");
+    if (separator <= 0 || separator !== apiKey.lastIndexOf("."))
+        return undefined;
+    if (!apiKey.slice(0, separator).trim() || !apiKey.slice(separator + 1).trim())
+        return undefined;
+    return { apiKeyId: apiKey.slice(0, separator), apiKeySecret: apiKey.slice(separator + 1) };
+}
+/** 本地 TS 库把 TextEncoder 结果声明为 ArrayBufferLike；WebCrypto 形参需要 ArrayBuffer。 */
+function encodeUtf8(value) {
+    const encoded = new TextEncoder().encode(value);
+    const bytes = new Uint8Array(encoded.byteLength);
+    bytes.set(encoded);
+    return bytes;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(value) {
+    if (!value || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value))
+        throw new Error("invalid base64");
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function randomHex(bytes) {
+    return bytesToHex(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+/** HKDF-SHA-256(ikm=secret, salt=固定盐, info, 32 字节)；与官方客户端的派生参数一致。 */
+async function deriveBytes(secret, info) {
+    const key = await crypto.subtle.importKey("raw", encodeUtf8(secret), "HKDF", false, ["deriveBits"]);
+    return new Uint8Array(await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt: encodeUtf8(KDF_SALT), info: encodeUtf8(info) }, key, 256));
+}
+function leadingZeroBits(hash) {
+    let total = 0;
+    for (const byte of hash) {
+        if (byte === 0) {
+            total += 8;
+            continue;
+        }
+        let prefix = 0;
+        for (let mask = 0x80; mask > 0 && !(byte & mask); mask >>= 1)
+            prefix += 1;
+        return total + prefix;
+    }
+    return total;
+}
+/** PoW：对 `id\nappId\nsessionId\nts` 的 SHA-256 hex 前缀找 8 个前导零比特。 */
+export function solveClientRequestPow(input, bits = POW_BITS) {
+    const prefix = createHash("sha256")
+        .update(`${input.apiKeyId}\n${APP_ID}\n${input.sessionId}\n${input.ts}`)
+        .digest("hex")
+        .slice(0, 32);
+    const salt = randomHex(POW_SALT_BYTES);
+    for (let counter = 0; counter <= 0xffffffff; counter += 1) {
+        const candidate = `${salt}${counter.toString(16).padStart(8, "0")}`;
+        const digest = createHash("sha256").update(`${prefix}\n${candidate}`).digest();
+        if (leadingZeroBits(digest) >= bits)
+            return candidate;
+    }
+    throw new Error("Unable to solve client request proof of work");
+}
+/** 401 响应正文中的可刷新签名拒绝原因；与官方客户端同序检查 msg/data.reason/error.*。 */
+export function clientSigningVerifyRejection(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return undefined;
+    const envelope = parsed;
+    const reasonOf = (value) => (value !== null && typeof value === "object" && !Array.isArray(value) ? value : {});
+    const data = reasonOf(envelope.data);
+    const error = reasonOf(envelope.error);
+    for (const candidate of [envelope.msg, data.reason, error.reason, error.message]) {
+        if (candidate === VERIFY_SIGNATURE_INVALID || candidate === VERIFY_APIKEY_EXPIRED)
+            return candidate;
+    }
+    return undefined;
+}
+export class ZcodeClientSigning {
+    fetchImpl;
+    now;
+    randomHexImpl;
+    handshakeTimeoutMs;
+    failureCooldownMs;
+    keys = new Map();
+    retryAfter = new Map();
+    constructor(options = {}) {
+        this.fetchImpl = options.fetch ?? ((url, init) => fetch(url, init));
+        this.now = options.now ?? Date.now;
+        this.randomHexImpl = options.randomHex ?? randomHex;
+        this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
+        this.failureCooldownMs = options.failureCooldownMs ?? FAILURE_COOLDOWN_MS;
+    }
+    /**
+     * 就地补齐一个请求的签名头；返回是否签名成功。除缺少必要输入外，任何失败
+     * （网络、协议、密码学）都返回 false 并保持原头不动，由调用方按未签名继续。
+     */
+    async decorate(headers, scope) {
+        try {
+            const credential = parseClientSigningCredential(scope.apiKey);
+            if (!credential || !scope.clientVersion || !scope.sessionId)
+                return false;
+            const origin = new URL(scope.baseUrl).origin;
+            const cacheKey = `${scope.apiKey}\n${origin}`;
+            if ((this.retryAfter.get(cacheKey) ?? 0) > this.now())
+                return false;
+            const privateKey = await (this.keys.get(cacheKey)
+                ?? this.beginHandshake(cacheKey, { ...credential, apiKey: scope.apiKey }, origin));
+            const ts = String(this.now());
+            const nonce = this.randomHexImpl(NONCE_BYTES);
+            const pow = solveClientRequestPow({ apiKeyId: credential.apiKeyId, sessionId: scope.sessionId, ts });
+            const message = `${credential.apiKeyId}\n${ts}\n${scope.clientVersion}\n${scope.sessionId}\n${nonce}`;
+            const signature = bytesToBase64(new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, encodeUtf8(message))));
+            headers.set("X-Client-Ts", ts);
+            headers.set("X-Client-Version", scope.clientVersion);
+            headers.set("X-Client-Sig", signature);
+            headers.set("X-Session-Id", scope.sessionId);
+            headers.set("X-Client-Nonce", nonce);
+            headers.set("X-App-Id", APP_ID);
+            headers.set("X-Client-Pow", pow);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 服务端拒绝（VERIFY_*）或密钥疑似轮换后作废缓存；下一次 decorate 重新握手。 */
+    invalidate(apiKey, baseUrl) {
+        try {
+            const cacheKey = `${apiKey}\n${new URL(baseUrl).origin}`;
+            this.keys.delete(cacheKey);
+            this.retryAfter.delete(cacheKey);
+        }
+        catch { /* 无效 baseUrl 视为无可作废的缓存。 */ }
+    }
+    beginHandshake(cacheKey, credential, origin) {
+        const promise = this.handshake(credential, origin).catch((error) => {
+            this.keys.delete(cacheKey);
+            // 失败不缓存结果，但短冷却避免上游故障时每个模型请求都打一次握手。
+            this.retryAfter.set(cacheKey, this.now() + this.failureCooldownMs);
+            throw error;
+        });
+        this.keys.set(cacheKey, promise);
+        while (this.keys.size > MAX_KEY_ENTRIES)
+            this.keys.delete(this.keys.keys().next().value);
+        return promise;
+    }
+    async handshake(credential, origin) {
+        const ts = String(this.now());
+        const nonce = this.randomHexImpl(NONCE_BYTES);
+        const hmacKey = await crypto.subtle.importKey("raw", await deriveBytes(credential.apiKeySecret, HMAC_INFO), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+        const sig = bytesToBase64(new Uint8Array(await crypto.subtle.sign("HMAC", hmacKey, encodeUtf8(`${HANDSHAKE_ACTION}\n${credential.apiKeyId}\n${ts}\n${nonce}`))));
+        const response = await this.fetchImpl(`${origin}${HANDSHAKE_PATH}`, {
+            method: "POST",
+            headers: { Authorization: credential.apiKey, "Content-Type": "application/json" },
+            body: JSON.stringify({ apiKey: credential.apiKey, nonce, sig, ts }),
+            redirect: "manual",
+            signal: AbortSignal.timeout(this.handshakeTimeoutMs),
+        });
+        const envelope = await response.json();
+        if (!response.ok || !envelope || typeof envelope !== "object")
+            throw new Error("client signing handshake protocol error");
+        if (envelope.code === 500)
+            throw new Error("client signing handshake server error");
+        if (envelope.code !== 200)
+            throw new Error(`client signing handshake rejected: ${String(envelope.msg ?? "")}`);
+        const cipher = typeof envelope.data?.privateCipher === "string" ? envelope.data.privateCipher : "";
+        if (!cipher)
+            throw new Error("client signing handshake omitted privateCipher");
+        return decryptSigningPrivateKey(credential, cipher);
+    }
+}
+/** privateCipher = base64([12 字节 IV | AES-GCM(密文+tag)])；明文是 pkcs8 的 base64 字符串。 */
+async function decryptSigningPrivateKey(credential, privateCipher) {
+    const cipher = base64ToBytes(privateCipher);
+    if (cipher.byteLength <= 12 + 16)
+        throw new Error("privateCipher is too short");
+    const aesKey = await crypto.subtle.importKey("raw", await deriveBytes(credential.apiKeySecret, PRIVATE_KEY_INFO), "AES-GCM", false, ["decrypt"]);
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: cipher.slice(0, 12), additionalData: encodeUtf8(credential.apiKeyId), tagLength: 128 }, aesKey, cipher.slice(12)));
+    const pkcs8 = base64ToBytes(new TextDecoder().decode(plaintext));
+    return crypto.subtle.importKey("pkcs8", pkcs8, "Ed25519", false, ["sign"]);
+}

package/dist/config.d.ts

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+export type ZcodeFamily = "zai" | "bigmodel";
+export interface ZcodeSelection {
+    family: ZcodeFamily;
+    providerID: string;
+    kind: "individual-coding-plan" | "team-coding-plan" | "start-plan" | "api-key";
+    team?: {
+        productId: string;
+        organizationId: string;
+        projectId: string;
+    };
+}
+export interface ZcodeProviderSnapshot {
+    family: ZcodeFamily;
+    providerID: string;
+    /** provider_config 的显示名；仅用于目录展示，不参与鉴权。 */
+    providerName?: string;
+    /** 该快照所属的套餐连接形态；决定对外 slug 作用域、显示名与鉴权头差异。 */
+    plan: ZcodeSelection["kind"];
+    apiKey: string;
+    baseURL: string;
+    modelIds: readonly string[];
+    expiresAt?: number;
+}
+export interface ZcodeConfigCache {
+    get(): Promise<ZcodeProviderSnapshot>;
+    /** 显式刷新本地配置与所需凭据；注入缓存可省略。 */
+    refresh?(): Promise<ZcodeProviderSnapshot>;
+    /** 仅重读本地目录元数据，不发起凭据网络；apiKey 可能为空，不用于请求认证。 */
+    reload?(): Promise<ZcodeProviderSnapshot>;
+    close(): void;
+}
+export declare class ZcodeConfigError extends Error {
+}
+export interface ZcodeCacheDependencies {
+    /** 共享目录采集器可禁止启动首读，随后显式 refresh。 */
+    refreshOnStart?: boolean;
+    watch?: typeof fs.watch;
+    stat?: typeof fs.statSync;
+    now?: () => number;
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** 固定解析某个套餐槽位（个人/团队/Start Plan/api-key），缺省跟随当前选择。 */
+    plan?: ZcodeSelection["kind"];
+    /** 固定 API Key provider；plan 为 api-key 时用于区分多个官方 Key。 */
+    apiProviderID?: string;
+    /** 只统计实际业务 Key 的构建，不接收或暴露密钥。 */
+    onCredentialBuild?: () => void;
+    /** 用于验证差分检查只在需要时读取 provider 配置。 */
+    onConfigRead?: () => void;
+    /** 套餐选择变化或当前选择不可解析时通知调用方，用于立即撤下已失效的下游目录条目。 */
+    onSelectionChange?: () => void;
+    /** 内存快照（渠道/套餐/模型集合/凭据）变化后触发，用于重建对外目录。 */
+    onSnapshotChange?: (snapshot: ZcodeProviderSnapshot) => void;
+}
+export interface ZcodePlanSelections {
+    /** 当前渠道（providerFamilyDomain）；失败根因优先取它的解析错误。 */
+    domain: ZcodeFamily;
+    /** 各套餐槽位当前可解析的选择；同一槽位两个渠道都有时取当前渠道。 */
+    plans: Partial<Record<ZcodeSelection["kind"], ZcodeSelection>>;
+    /** 渠道级解析失败（未知 kind、缺 provider 选择等）；该渠道的所有槽位都不可用。 */
+    failures: Partial<Record<ZcodeFamily, ZcodeConfigError>>;
+}
+export interface ZcodeAPIKeyProvider {
+    family: ZcodeFamily;
+    providerID: string;
+    providerName?: string;
+}
+/** 列出 provider_config 中全部可用官方 API Key，供目录为每个 Key 建独立路由。 */
+export declare function readZcodeAPIKeyProviders(homeDirectory: string): ZcodeAPIKeyProvider[];
+/**
+ * 本机 ZCode 配置是否就绪：setting.json 与 config.json/provider_config.json 至少
+ * 一组可用路由都存在才算可用。只做存在性探测，不读文件内容；home 与 v2 两种布局
+ * 各自按 readPreferred 的回退顺序判定。
+ */
+export declare function zcodeConfigPresent(homeDirectory: string): boolean;
+/** 文件检查同步完成，凭证仅按 Key 的实际变化构建；事件不废弃有效快照。 */
+export declare function createZcodeConfigCache(homeDirectory: string, dependencies?: ZcodeCacheDependencies): ZcodeConfigCache;