@world-engines/project-host 0.1.0-alpha.0

package/dist/authoring-model-connection.js

@@ -0,0 +1,757 @@
+/**
+ * 作者侧真实模型连接。认证材料仅存在于 host process 内存和请求 header 中，
+ * 错误对象、usage 与返回值都不会携带 token、底层响应正文或请求 URL。
+ */
+export const AUTHORING_EMBEDDING_MODEL_ALLOWLIST = Object.freeze([
+    "qwen/qwen3-embedding-8b",
+    "qwen/qwen3-embedding-4b",
+    "openai/text-embedding-3-small",
+]);
+const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+const DEFAULT_BASE_URL_ALLOWLIST = Object.freeze([
+    DEFAULT_BASE_URL,
+]);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 900_000;
+export const EMBEDDING_BATCH_SIZE = 128;
+const DEFAULT_MAX_OUTPUT_TOKENS = 4_096;
+const DEFAULT_STRUCTURED_TEMPERATURE = 0;
+const MAX_DEEPSEEK_OUTPUT_TOKENS = 384_000;
+const OPENROUTER_PRODUCTION_BASE_URL = "https://openrouter.ai/api/v1";
+const DEEPSEEK_PRODUCTION_BASE_URL = "https://api.deepseek.com";
+const DEEPSEEK_V4_FLASH_MODEL = "deepseek-v4-flash";
+// 仅已实际遇到且审核过的有限字段名可进入错误路径；不回显任意 provider key。
+const SAFE_ADDITIONAL_PROPERTY_DIAGNOSTIC_KEYS = new Set(["labels"]);
+/** 所有失败都是可穷举、已脱敏的 terminal result；本模块绝不静默降级。 */
+export class AuthoringModelConnectionError extends Error {
+    code;
+    retryable;
+    status;
+    responseMetadata;
+    schemaIssue;
+    validationStage;
+    parseIssue;
+    name = "AuthoringModelConnectionError";
+    terminal = true;
+    validationIssues;
+    constructor(code, retryable, status, responseMetadata, schemaIssue, validationStage, parseIssue) {
+        super(`authoring_model_connection:${code}`);
+        this.code = code;
+        this.retryable = retryable;
+        this.status = status;
+        this.responseMetadata = responseMetadata;
+        this.schemaIssue = schemaIssue;
+        this.validationStage = validationStage;
+        this.parseIssue = parseIssue;
+        this.validationIssues = Object.freeze(schemaIssue === undefined ? [] : [schemaIssue]);
+    }
+}
+function fail(code, stage) {
+    throw new AuthoringModelConnectionError(code, false, undefined, undefined, undefined, stage);
+}
+function plainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null ? value : undefined;
+}
+function finishReason(value) {
+    switch (value) {
+        case "stop":
+        case "length":
+        case "tool_calls":
+        case "content_filter":
+        case "error":
+            return value;
+        case undefined:
+        case null:
+            return "missing";
+        default:
+            return "other";
+    }
+}
+function responseMetadata(finishReasonValue, content) {
+    let contentType;
+    if (content === null)
+        contentType = "null";
+    else if (Array.isArray(content))
+        contentType = "array";
+    else if (typeof content === "string")
+        contentType = "string";
+    else if (typeof content === "number")
+        contentType = "number";
+    else if (typeof content === "boolean")
+        contentType = "boolean";
+    else if (typeof content === "undefined")
+        contentType = "undefined";
+    else
+        contentType = "object";
+    const contentLength = typeof content === "string" || Array.isArray(content) ? content.length : null;
+    return Object.freeze({ finishReason: finishReason(finishReasonValue), contentType, contentLength });
+}
+function parseProviderJson(text, layer, metadata) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        // 不暴露 SyntaxError.message（V8 会在其中回显 provider 正文）。
+        const positionText = error instanceof Error ? /position (\d+)/u.exec(error.message)?.[1] : undefined;
+        const position = positionText === undefined ? null : Number(positionText);
+        throw new AuthoringModelConnectionError("provider_response_invalid", false, undefined, metadata, undefined, "response_parse", Object.freeze({ layer, position }));
+    }
+}
+function structuredJsonFrame(text) {
+    // 仅解包完整单围栏，不抽取子串、不修 JSON，也不容忍围栏外说明或多个文档。
+    const match = /^[\t\r\n ]*```json\r?\n([\s\S]*?)\r?\n```[\t\r\n ]*$/u.exec(text);
+    return Object.freeze(match === null ? { text, framing: "bare_json" } : { text: match[1], framing: "single_json_fence" });
+}
+function requireSafeText(value, maximum) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum || value.trim() !== value
+        || value.normalize("NFC") !== value || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value)) {
+        fail("invalid_request");
+    }
+    return value;
+}
+function canonicalBaseUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "") {
+            throw new Error("unsafe URL");
+        }
+        return url.toString().replace(/\/$/u, "");
+    }
+    catch {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+}
+function requireUsage(value, outputRequired) {
+    const usage = plainRecord(value);
+    const inputTokens = usage?.prompt_tokens;
+    const outputTokens = usage?.completion_tokens ?? (outputRequired ? undefined : 0);
+    const totalTokens = usage?.total_tokens;
+    if (!Number.isSafeInteger(inputTokens) || inputTokens < 0
+        || !Number.isSafeInteger(outputTokens) || outputTokens < 0
+        || !Number.isSafeInteger(totalTokens) || totalTokens < 0
+        || totalTokens < inputTokens + outputTokens) {
+        fail("provider_response_invalid", "usage");
+    }
+    return Object.freeze({
+        inputTokens: inputTokens,
+        outputTokens: outputTokens,
+        totalTokens: totalTokens,
+        requests: 1,
+    });
+}
+function addUsage(left, right) {
+    const inputTokens = left.inputTokens + right.inputTokens;
+    const outputTokens = left.outputTokens + right.outputTokens;
+    const totalTokens = left.totalTokens + right.totalTokens;
+    const requests = left.requests + right.requests;
+    if (![inputTokens, outputTokens, totalTokens, requests].every(Number.isSafeInteger)) {
+        fail("provider_response_invalid");
+    }
+    return Object.freeze({ inputTokens, outputTokens, totalTokens, requests });
+}
+function combineAbort(signal, timeoutMs) {
+    const controller = new AbortController();
+    let timeout = false;
+    const abort = () => controller.abort();
+    if (signal?.aborted)
+        controller.abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+        timeout = true;
+        controller.abort();
+    }, timeoutMs);
+    return Object.freeze({
+        signal: controller.signal,
+        timedOut: () => timeout,
+        dispose: () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+        },
+    });
+}
+function requireApiKey(apiKey) {
+    if (typeof apiKey !== "string" || apiKey.length === 0 || apiKey.trim() !== apiKey || /[\r\n]/u.test(apiKey)) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+}
+function optionalApiKey(apiKey) {
+    if (apiKey === "")
+        return false;
+    requireApiKey(apiKey);
+    return true;
+}
+function retryPolicy(input) {
+    const policy = Object.freeze({
+        maxAttempts: input?.maxAttempts ?? 3,
+        baseDelayMs: input?.baseDelayMs ?? 250,
+        maxDelayMs: input?.maxDelayMs ?? 10_000,
+    });
+    if (!Number.isSafeInteger(policy.maxAttempts) || policy.maxAttempts < 1 || policy.maxAttempts > 5
+        || !Number.isSafeInteger(policy.baseDelayMs) || policy.baseDelayMs < 0 || policy.baseDelayMs > 60_000
+        || !Number.isSafeInteger(policy.maxDelayMs) || policy.maxDelayMs < policy.baseDelayMs || policy.maxDelayMs > 120_000) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    return policy;
+}
+function retryDelay(response, attempt, policy) {
+    const header = response?.headers.get("retry-after") ?? null;
+    let requested;
+    if (header !== null && /^\d+(?:\.\d+)?$/u.test(header.trim()))
+        requested = Math.ceil(Number(header) * 1_000);
+    else if (header !== null) {
+        const date = Date.parse(header);
+        if (Number.isFinite(date))
+            requested = Math.max(0, date - Date.now());
+    }
+    const base = Math.min(policy.maxDelayMs, requested ?? policy.baseDelayMs * (2 ** Math.max(0, attempt - 1)));
+    const jitterCeiling = Math.min(250, Math.floor(base * 0.2));
+    const jitter = jitterCeiling === 0 ? 0 : Math.floor(Math.random() * (jitterCeiling + 1));
+    return Math.min(policy.maxDelayMs, base + jitter);
+}
+async function waitForRetry(delayMs, signal) {
+    if (signal?.aborted)
+        throw new AuthoringModelConnectionError("aborted", false);
+    if (delayMs === 0)
+        return;
+    await new Promise((resolve, reject) => {
+        const done = () => {
+            signal?.removeEventListener("abort", aborted);
+            resolve();
+        };
+        const aborted = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", aborted);
+            reject(new AuthoringModelConnectionError("aborted", false));
+        };
+        const timer = setTimeout(done, delayMs);
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+}
+function createJsonPoster(options) {
+    return async (path, body, signal, timeoutOverrideMs) => {
+        let serialized;
+        try {
+            serialized = JSON.stringify(body);
+        }
+        catch {
+            fail("invalid_request");
+        }
+        const timeoutMs = timeoutOverrideMs ?? options.timeoutMs;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS)
+            fail("invalid_request");
+        for (let attempt = 1; attempt <= options.retry.maxAttempts; attempt += 1) {
+            if (signal?.aborted)
+                throw new AuthoringModelConnectionError("aborted", false);
+            const abort = combineAbort(signal, timeoutMs);
+            try {
+                options.onAttempt?.();
+                const response = await fetch(`${options.baseUrl}${path}`, {
+                    method: "POST",
+                    headers: Object.freeze({ authorization: `Bearer ${options.apiKey}`, "content-type": "application/json" }),
+                    body: serialized,
+                    signal: abort.signal,
+                });
+                if (!response.ok) {
+                    const retryable = response.status === 429 || response.status >= 500;
+                    if (retryable && attempt < options.retry.maxAttempts) {
+                        const delayMs = retryDelay(response, attempt, options.retry);
+                        await response.body?.cancel();
+                        abort.dispose();
+                        await waitForRetry(delayMs, signal);
+                        continue;
+                    }
+                    throw new AuthoringModelConnectionError("provider_rejected", retryable, response.status);
+                }
+                // 读流错误交给 transport retry；完整但非法的 HTTP JSON 保留独立 parse layer。
+                const decoded = parseProviderJson(await response.text(), "http_envelope");
+                const record = plainRecord(decoded);
+                if (record === undefined)
+                    fail("provider_response_invalid", "response_shape");
+                return record;
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw new AuthoringModelConnectionError("aborted", false);
+                if (error instanceof AuthoringModelConnectionError)
+                    throw error;
+                const code = abort.timedOut() ? "timeout" : "transport_failed";
+                if (attempt < options.retry.maxAttempts) {
+                    // 响应丢失时远端可能已处理；只有限重发原 serialized body，不推测其 token 消耗。
+                    abort.dispose();
+                    await waitForRetry(retryDelay(undefined, attempt, options.retry), signal);
+                    continue;
+                }
+                throw new AuthoringModelConnectionError(code, true);
+            }
+            finally {
+                abort.dispose();
+            }
+        }
+        throw new AuthoringModelConnectionError("provider_rejected", true);
+    };
+}
+function assertClosedJsonSchema(value, depth = 0) {
+    const schema = plainRecord(value);
+    if (schema === undefined || depth > 32)
+        fail("invalid_request");
+    const type = schema.type;
+    if (type !== "object" && type !== "array" && type !== "string" && type !== "number"
+        && type !== "integer" && type !== "boolean" && type !== "null")
+        fail("invalid_request");
+    if (schema.enum !== undefined && !Array.isArray(schema.enum))
+        fail("invalid_request");
+    if (type === "object") {
+        const properties = plainRecord(schema.properties);
+        if (properties === undefined || schema.additionalProperties !== false || !Array.isArray(schema.required)
+            || !schema.required.every((key) => typeof key === "string" && Object.hasOwn(properties, key)))
+            fail("invalid_request");
+        Object.values(properties).forEach((property) => assertClosedJsonSchema(property, depth + 1));
+    }
+    else if (type === "array") {
+        assertClosedJsonSchema(schema.items, depth + 1);
+    }
+    else if (type === "string" && schema.pattern !== undefined) {
+        if (typeof schema.pattern !== "string")
+            fail("invalid_request");
+        try {
+            new RegExp(schema.pattern, "u");
+        }
+        catch {
+            fail("invalid_request");
+        }
+    }
+}
+function schemaPath(path, key) {
+    return `${path}/${String(key).replace(/~/gu, "~0").replace(/\//gu, "~1")}`;
+}
+function closedJsonSchemaIssue(value, schema, path = "$", depth = 0) {
+    const issue = (keyword, issuePath = path) => Object.freeze({ path: issuePath, keyword });
+    if (depth > 32)
+        return issue("type");
+    if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => Object.is(candidate, value)))
+        return issue("enum");
+    switch (schema.type) {
+        case "null": return value === null ? undefined : issue("type");
+        case "boolean": return typeof value === "boolean" ? undefined : issue("type");
+        case "number":
+        case "integer": {
+            if (typeof value !== "number" || !Number.isFinite(value) || (schema.type === "integer" && !Number.isSafeInteger(value)))
+                return issue("type");
+            if (typeof schema.minimum === "number" && value < schema.minimum)
+                return issue("minimum");
+            return typeof schema.maximum === "number" && value > schema.maximum ? issue("maximum") : undefined;
+        }
+        case "string": {
+            if (typeof value !== "string")
+                return issue("type");
+            if (typeof schema.minLength === "number" && value.length < schema.minLength)
+                return issue("minLength");
+            if (typeof schema.maxLength === "number" && value.length > schema.maxLength)
+                return issue("maxLength");
+            return typeof schema.pattern === "string" && !new RegExp(schema.pattern, "u").test(value) ? issue("pattern") : undefined;
+        }
+        case "array": {
+            if (!Array.isArray(value))
+                return issue("type");
+            if (typeof schema.minItems === "number" && value.length < schema.minItems)
+                return issue("minItems");
+            if (typeof schema.maxItems === "number" && value.length > schema.maxItems)
+                return issue("maxItems");
+            const items = plainRecord(schema.items);
+            if (items === undefined)
+                return issue("type");
+            for (let index = 0; index < value.length; index += 1) {
+                const nested = closedJsonSchemaIssue(value[index], items, schemaPath(path, index), depth + 1);
+                if (nested !== undefined)
+                    return nested;
+            }
+            return undefined;
+        }
+        case "object": {
+            const object = plainRecord(value);
+            const properties = plainRecord(schema.properties);
+            if (object === undefined || properties === undefined)
+                return issue("type");
+            const required = schema.required;
+            const missing = required.find((key) => !Object.hasOwn(object, key));
+            if (missing !== undefined)
+                return issue("required", schemaPath(path, missing));
+            const extraKey = Object.keys(object).find((key) => !Object.hasOwn(properties, key));
+            if (schema.additionalProperties === false && extraKey !== undefined) {
+                return issue("additionalProperties", SAFE_ADDITIONAL_PROPERTY_DIAGNOSTIC_KEYS.has(extraKey) ? schemaPath(path, extraKey) : path);
+            }
+            for (const [key, item] of Object.entries(object)) {
+                const property = plainRecord(properties[key]);
+                if (property === undefined)
+                    return issue("additionalProperties");
+                const nested = closedJsonSchemaIssue(item, property, schemaPath(path, key), depth + 1);
+                if (nested !== undefined)
+                    return nested;
+            }
+            return undefined;
+        }
+        default: return issue("type");
+    }
+}
+function createEmbeddingPort(options) {
+    return Object.freeze({
+        providerId: options.providerId,
+        modelId: options.modelId,
+        dimensions: options.dimensions,
+        origin: options.origin,
+        async embed(texts, requestOptions) {
+            if (options.available === false) {
+                throw new AuthoringModelConnectionError("embedding_credentials_missing", false);
+            }
+            if (!Array.isArray(texts) || texts.length === 0)
+                fail("invalid_request");
+            const inputKind = requestOptions?.inputKind ?? "document";
+            const input = texts.map((text) => requireSafeText(inputKind === "query"
+                ? `Instruct: 检索虚构世界中能够回答问题的事实。\nQuery: ${text}` : text, 1_000_000));
+            const complete = [];
+            for (let offset = 0; offset < input.length; offset += EMBEDDING_BATCH_SIZE) {
+                const batch = input.slice(offset, offset + EMBEDDING_BATCH_SIZE);
+                const response = await options.post("/embeddings", {
+                    model: options.modelId,
+                    input: batch,
+                    dimensions: options.dimensions,
+                    encoding_format: "float",
+                }, requestOptions?.signal);
+                if (!Array.isArray(response.data) || response.data.length !== batch.length)
+                    fail("provider_response_invalid");
+                const ordered = new Array(batch.length);
+                for (const itemValue of response.data) {
+                    const item = plainRecord(itemValue);
+                    if (item === undefined || !Number.isSafeInteger(item.index) || item.index < 0
+                        || item.index >= batch.length || ordered[item.index] !== undefined
+                        || !Array.isArray(item.embedding) || item.embedding.length !== options.dimensions
+                        || !item.embedding.every((value) => typeof value === "number" && Number.isFinite(value))) {
+                        fail("provider_response_invalid");
+                    }
+                    ordered[item.index] = Object.freeze([...item.embedding]);
+                }
+                if (ordered.some((vector) => vector === undefined))
+                    fail("provider_response_invalid");
+                const usage = requireUsage(response.usage, false);
+                options.recordUsage(usage);
+                complete.push(...ordered);
+            }
+            return Object.freeze(complete);
+        },
+    });
+}
+export function createOpenAiCompatibleAuthoringModelConnection(config) {
+    requireApiKey(config.apiKey);
+    if (!AUTHORING_EMBEDDING_MODEL_ALLOWLIST.includes(config.embeddingModel)) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    if (!Number.isSafeInteger(config.embeddingDimensions) || config.embeddingDimensions <= 0) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    if (typeof config.structuredChatModel !== "string" || config.structuredChatModel.length === 0
+        || !config.structuredChatModelAllowlist.includes(config.structuredChatModel)) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    const baseUrl = canonicalBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL);
+    const baseUrlAllowlist = (config.baseUrlAllowlist ?? DEFAULT_BASE_URL_ALLOWLIST).map(canonicalBaseUrl);
+    if (!baseUrlAllowlist.includes(baseUrl)) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    let aggregate = Object.freeze({ inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0 });
+    const post = createJsonPoster({ apiKey: config.apiKey, baseUrl, timeoutMs, retry: retryPolicy(config.retry) });
+    const embedding = createEmbeddingPort({
+        providerId: "openai-compatible",
+        modelId: config.embeddingModel,
+        dimensions: config.embeddingDimensions,
+        origin: new URL(baseUrl).origin,
+        post,
+        recordUsage: (usage) => { aggregate = addUsage(aggregate, usage); },
+    });
+    const structuredJson = Object.freeze({
+        providerId: "openai-compatible",
+        modelId: config.structuredChatModel,
+        async generate(request) {
+            if (request.reasoningEffort !== undefined)
+                fail("invalid_request");
+            const schemaName = requireSafeText(request.schemaName, 64);
+            if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(schemaName) || plainRecord(request.jsonSchema) === undefined
+                || !Array.isArray(request.messages) || request.messages.length === 0 || request.messages.length > 128) {
+                fail("invalid_request");
+            }
+            const messages = request.messages.map((message) => {
+                if (message.role !== "system" && message.role !== "user" && message.role !== "assistant")
+                    fail("invalid_request");
+                return Object.freeze({ role: message.role, content: requireSafeText(message.content, 1_000_000) });
+            });
+            const response = await post("/chat/completions", {
+                model: config.structuredChatModel,
+                messages,
+                response_format: {
+                    type: "json_schema",
+                    json_schema: { name: schemaName, strict: true, schema: request.jsonSchema },
+                },
+            }, request.signal);
+            if (!Array.isArray(response.choices) || response.choices.length !== 1)
+                fail("provider_response_invalid");
+            const choice = plainRecord(response.choices[0]);
+            const message = plainRecord(choice?.message);
+            const metadata = responseMetadata(choice?.finish_reason, message?.content);
+            const usage = requireUsage(response.usage, true);
+            aggregate = addUsage(aggregate, usage);
+            if (metadata.finishReason === "length") {
+                throw new AuthoringModelConnectionError("provider_output_truncated", false, undefined, metadata);
+            }
+            if (typeof message?.content !== "string") {
+                throw new AuthoringModelConnectionError("provider_response_invalid", false, undefined, metadata);
+            }
+            let value;
+            try {
+                value = JSON.parse(message.content);
+            }
+            catch {
+                throw new AuthoringModelConnectionError("provider_response_invalid", false, undefined, metadata);
+            }
+            return Object.freeze({ value: value, usage });
+        },
+    });
+    return Object.freeze({ embedding, structuredJson, usage: () => aggregate });
+}
+function requireDeepSeekUsage(value) {
+    const usage = plainRecord(value);
+    const details = plainRecord(usage?.input_tokens_details);
+    const inputTokens = usage?.input_tokens;
+    const outputTokens = usage?.output_tokens;
+    const totalTokens = usage?.total_tokens;
+    const cachedInputTokens = details?.cached_tokens;
+    if (!Number.isSafeInteger(inputTokens) || inputTokens < 0
+        || !Number.isSafeInteger(outputTokens) || outputTokens < 0
+        || !Number.isSafeInteger(totalTokens) || totalTokens < 0
+        || totalTokens < inputTokens + outputTokens
+        || (cachedInputTokens !== undefined && (!Number.isSafeInteger(cachedInputTokens)
+            || cachedInputTokens < 0 || cachedInputTokens > inputTokens))) {
+        fail("provider_response_invalid", "usage");
+    }
+    return Object.freeze({
+        inputTokens: inputTokens,
+        outputTokens: outputTokens,
+        totalTokens: totalTokens,
+        requests: 1,
+        providerId: "deepseek",
+        modelId: DEEPSEEK_V4_FLASH_MODEL,
+        ...(cachedInputTokens === undefined ? {} : { cachedInputTokens: cachedInputTokens }),
+    });
+}
+function addProviderUsage(left, right) {
+    const totals = addUsage(left, right);
+    const cachedInputTokens = (left.cachedInputTokens ?? 0) + (right.cachedInputTokens ?? 0);
+    if (!Number.isSafeInteger(cachedInputTokens))
+        fail("provider_response_invalid");
+    return Object.freeze({
+        ...totals,
+        ...(right.providerId === undefined ? {} : { providerId: right.providerId }),
+        ...(right.modelId === undefined ? {} : { modelId: right.modelId }),
+        cachedInputTokens,
+    });
+}
+function taskInstruction(mode) {
+    switch (mode) {
+        case "extraction": return "执行结构化事实抽取；不得省略、猜测或添加 schema 外字段。";
+        case "simulation_retrieval": return "执行模拟检索与结构化排序；只依据输入候选，不得虚构候选。";
+        case "full_book_planning": return "对完整长文执行结构化规划；覆盖全局结构并保持可追溯，不得输出 schema 外字段。";
+    }
+}
+function isTaskMode(value) {
+    return value === "extraction" || value === "simulation_retrieval" || value === "full_book_planning";
+}
+/**
+ * 生产作者模型连接：embedding 固定走 OpenRouter/Qwen3，structured JSON 固定走
+ * DeepSeek 官方 Responses API/V4 Flash；两个 credential 永远位于不同 poster closure。
+ */
+export function createProductionAuthoringModelConnection(config) {
+    // deferred ingestion 只消费 structured port；另一份凭据在真正被消费前验证。
+    const embeddingAvailable = optionalApiKey(config.embedding.apiKey);
+    const structuredAvailable = optionalApiKey(config.structured.apiKey);
+    if ((config.embedding.baseUrl !== undefined && config.embedding.baseUrl !== OPENROUTER_PRODUCTION_BASE_URL)
+        || (config.embedding.model !== undefined && config.embedding.model !== "qwen/qwen3-embedding-8b")
+        || (config.embedding.dimensions !== undefined && config.embedding.dimensions !== 1024)
+        || (config.structured.baseUrl !== undefined && config.structured.baseUrl !== DEEPSEEK_PRODUCTION_BASE_URL)
+        || (config.structured.model !== undefined && config.structured.model !== DEEPSEEK_V4_FLASH_MODEL)
+        || (config.structured.thinking !== undefined && config.structured.thinking !== "disabled")
+        || (config.structured.responseFormat !== undefined && config.structured.responseFormat !== "json_schema")
+        || (config.structured.defaultTaskMode !== undefined && !isTaskMode(config.structured.defaultTaskMode))) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    const embeddingTimeoutMs = config.embedding.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const structuredTimeoutMs = config.structured.timeoutMs ?? 120_000;
+    const defaultMaxOutputTokens = config.structured.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    const temperature = config.structured.temperature === undefined ? DEFAULT_STRUCTURED_TEMPERATURE : config.structured.temperature;
+    if (!Number.isSafeInteger(embeddingTimeoutMs) || embeddingTimeoutMs < 1 || embeddingTimeoutMs > MAX_TIMEOUT_MS
+        || !Number.isSafeInteger(structuredTimeoutMs) || structuredTimeoutMs < 1 || structuredTimeoutMs > MAX_TIMEOUT_MS
+        || !Number.isSafeInteger(defaultMaxOutputTokens) || defaultMaxOutputTokens < 1
+        || defaultMaxOutputTokens > MAX_DEEPSEEK_OUTPUT_TOKENS
+        || !Number.isFinite(temperature) || temperature < 0 || temperature > 2) {
+        throw new AuthoringModelConnectionError("invalid_configuration", false);
+    }
+    const policy = retryPolicy(config.retry);
+    let embeddingAggregate = Object.freeze({ inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0 });
+    let embeddingRequestAttempts = 0;
+    let structuredRequestAttempts = 0;
+    const embeddingPost = createJsonPoster({
+        apiKey: config.embedding.apiKey,
+        baseUrl: OPENROUTER_PRODUCTION_BASE_URL,
+        timeoutMs: embeddingTimeoutMs,
+        retry: policy,
+        onAttempt: () => { embeddingRequestAttempts += 1; },
+    });
+    const embedding = createEmbeddingPort({
+        providerId: "openrouter",
+        modelId: "qwen/qwen3-embedding-8b",
+        dimensions: 1024,
+        origin: new URL(OPENROUTER_PRODUCTION_BASE_URL).origin,
+        post: embeddingPost,
+        available: embeddingAvailable,
+        recordUsage: (usage) => { embeddingAggregate = addUsage(embeddingAggregate, usage); },
+    });
+    const deepSeekPost = createJsonPoster({
+        apiKey: config.structured.apiKey,
+        baseUrl: DEEPSEEK_PRODUCTION_BASE_URL,
+        timeoutMs: structuredTimeoutMs,
+        retry: policy,
+        onAttempt: () => { structuredRequestAttempts += 1; },
+    });
+    let structuredAggregate = Object.freeze({
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        requests: 0,
+        providerId: "deepseek",
+        modelId: DEEPSEEK_V4_FLASH_MODEL,
+        cachedInputTokens: 0,
+    });
+    const structuredJson = Object.freeze({
+        providerId: "deepseek",
+        modelId: DEEPSEEK_V4_FLASH_MODEL,
+        async generate(request) {
+            if (!structuredAvailable) {
+                throw new AuthoringModelConnectionError("structured_credentials_missing", false);
+            }
+            const schemaName = requireSafeText(request.schemaName, 64);
+            if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(schemaName)
+                || !Array.isArray(request.messages) || request.messages.length === 0 || request.messages.length > 128) {
+                fail("invalid_request");
+            }
+            assertClosedJsonSchema(request.jsonSchema);
+            const reasoningEffort = request.reasoningEffort ?? "none";
+            if ((request.reasoningEffort !== undefined && request.reasoningEffort !== "none" && request.reasoningEffort !== "low")
+                || (config.structured.thinking === "disabled" && reasoningEffort !== "none"))
+                fail("invalid_request");
+            const messages = request.messages.map((message) => {
+                if (message.role !== "system" && message.role !== "user" && message.role !== "assistant")
+                    fail("invalid_request");
+                return Object.freeze({ role: message.role, content: requireSafeText(message.content, 1_000_000) });
+            });
+            const mode = request.taskMode ?? config.structured.defaultTaskMode ?? "extraction";
+            if (!isTaskMode(mode))
+                fail("invalid_request");
+            const maxOutputTokens = request.maxOutputTokens ?? defaultMaxOutputTokens;
+            if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens < 1 || maxOutputTokens > MAX_DEEPSEEK_OUTPUT_TOKENS) {
+                fail("invalid_request");
+            }
+            // 只派生根字段的类型提示；完整规则仍仅由同一 text.format.schema 提供。
+            const properties = plainRecord(request.jsonSchema.properties);
+            const requiredFieldTypes = request.jsonSchema.type === "object"
+                ? Object.fromEntries(request.jsonSchema.required.map((key) => [key, plainRecord(properties?.[key])?.type]))
+                : undefined;
+            const response = await deepSeekPost("/responses", {
+                model: DEEPSEEK_V4_FLASH_MODEL,
+                reasoning: { effort: reasoningEffort },
+                temperature,
+                max_output_tokens: maxOutputTokens,
+                instructions: `${taskInstruction(mode)}\n直接输出单个裸 JSON 文本，禁止 Markdown 代码围栏、前言、解释和后记。输出数据实例，不是 Schema；响应格式中的 JSON Schema 是验证规则，不是待输出内容，不得复述其定义。根值类型为 ${String(request.jsonSchema.type)}。${requiredFieldTypes === undefined ? "" : `根对象必需字段及各自值类型为 ${JSON.stringify(requiredFieldTypes)}；这些字段必须填写根据任务得出的实际值，而不是类型描述对象或类型名称。`}所有字段和嵌套值仍须符合响应格式中的同一 Schema；不要输出示例、占位值或 Schema 本身。`,
+                input: messages,
+                text: { format: { type: "json_schema", name: schemaName, schema: request.jsonSchema } },
+            }, request.signal, request.timeoutMs);
+            const usage = requireDeepSeekUsage(response.usage);
+            structuredAggregate = addProviderUsage(structuredAggregate, usage);
+            if (response.model !== DEEPSEEK_V4_FLASH_MODEL) {
+                throw new AuthoringModelConnectionError("provider_model_mismatch", false);
+            }
+            const output = Array.isArray(response.output) ? response.output : [];
+            const messagesOutput = output.map(plainRecord).filter((item) => item?.type === "message");
+            const content = messagesOutput.length === 1 && Array.isArray(messagesOutput[0]?.content)
+                ? messagesOutput[0].content
+                : [];
+            const textParts = content.map(plainRecord).filter((item) => item?.type === "output_text");
+            const text = textParts.length === 1 ? textParts[0]?.text : undefined;
+            const incompleteDetails = plainRecord(response.incomplete_details);
+            const metadata = responseMetadata(response.status === "incomplete" && incompleteDetails?.reason === "max_output_tokens" ? "length" : response.status, text);
+            if (response.status === "incomplete" && incompleteDetails?.reason === "max_output_tokens") {
+                throw new AuthoringModelConnectionError("provider_output_truncated", false, undefined, metadata);
+            }
+            if (response.status !== "completed" || typeof text !== "string") {
+                throw new AuthoringModelConnectionError("provider_response_invalid", false, undefined, metadata, undefined, "response_shape");
+            }
+            const framed = structuredJsonFrame(text);
+            const framedMetadata = Object.freeze({ ...metadata, framing: framed.framing });
+            const value = parseProviderJson(framed.text, "model_output", framedMetadata);
+            const schemaIssue = closedJsonSchemaIssue(value, request.jsonSchema);
+            if (schemaIssue !== undefined) {
+                throw new AuthoringModelConnectionError("provider_response_invalid", false, undefined, framedMetadata, schemaIssue, "closed_schema");
+            }
+            return Object.freeze({ value: value, usage, framing: framed.framing });
+        },
+    });
+    return Object.freeze({
+        embedding,
+        structuredJson,
+        assertAvailable(ports) {
+            for (const port of ports) {
+                if (port === "embedding") {
+                    if (!embeddingAvailable)
+                        throw new AuthoringModelConnectionError("embedding_credentials_missing", false);
+                }
+                else if (port === "structured") {
+                    if (!structuredAvailable)
+                        throw new AuthoringModelConnectionError("structured_credentials_missing", false);
+                }
+                else {
+                    throw new AuthoringModelConnectionError("invalid_configuration", false);
+                }
+            }
+        },
+        usage: () => {
+            const total = addUsage(embeddingAggregate, structuredAggregate);
+            const byProviderModel = Object.freeze([
+                Object.freeze({
+                    providerId: "openrouter",
+                    modelId: "qwen/qwen3-embedding-8b",
+                    inputTokens: embeddingAggregate.inputTokens,
+                    outputTokens: embeddingAggregate.outputTokens,
+                    totalTokens: embeddingAggregate.totalTokens,
+                    requests: embeddingAggregate.requests,
+                    requestAttempts: embeddingRequestAttempts,
+                }),
+                Object.freeze({
+                    providerId: "deepseek",
+                    modelId: DEEPSEEK_V4_FLASH_MODEL,
+                    inputTokens: structuredAggregate.inputTokens,
+                    outputTokens: structuredAggregate.outputTokens,
+                    totalTokens: structuredAggregate.totalTokens,
+                    cachedInputTokens: structuredAggregate.cachedInputTokens ?? 0,
+                    requests: structuredAggregate.requests,
+                    requestAttempts: structuredRequestAttempts,
+                }),
+            ]);
+            return Object.freeze({ ...total, requestAttempts: embeddingRequestAttempts + structuredRequestAttempts,
+                cachedInputTokens: structuredAggregate.cachedInputTokens ?? 0, byProviderModel });
+        },
+    });
+}