@zqagent/core 0.3.11 → 0.3.13

package/dist/{TurnEngine-DtGEuVLT.d.ts → TurnEngine-BZjUGic_.d.ts}

@@ -1,5 +1,6 @@
 import { T as TokenUsage, M as Message, a as ToolSchema, R as ReasoningEffort, S as StreamChunk, b as MessageAttachment, c as StoredAttachment } from './types-BYyXWWPW.js';
 import { a as ToolMetadata, T as ToolRegistry } from './ToolRegistry-Cy0fQxrb.js';
+import { ApiMode } from './internal/providers/diagnostics.js';
 import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
 import { ModelCapability } from '@zqagent/shared/model-capabilities';
@@ -344,22 +345,51 @@ declare class OpenAIProvider implements ProviderClient {
     private _logDir?;
     /** 服务端点 baseURL（用于识别 DeepSeek 等特定供应商） */
     private _baseURL;
-    /** 模型 → API 模式缓存：某模型不支持 Responses 后，后续直走 Chat */
-    private _modeByModel;
+    /**
+     * 本实例的 API 模式。
+     *
+     * 显式配置 > 全局 `OPENAI_FORCE_API_MODE` > auto（先 Responses 再降级）。
+     * 早先只有全局环境变量一种表达方式，一个节点挂两家供应商时无法各自指定。
+     */
+    private _apiMode;
     constructor(opts: {
+        /**
+         * API Key。
+         *
+         * - 显式 `""`（含纯空白）：**明确表示该端点不需要鉴权**（本地 Ollama /
+         *   llama.cpp、内网网关），不会回落到环境变量，SDK 收到占位 Key。
+         * - `undefined`：回落到 `OPENAI_API_KEY`；两者都没有时抛错（多数情况是
+         *   真的没配，早点给出可读提示好过让用户对着 401 猜）。
+         *
+         * 调用方不要用「配置里 Key 为空」来推断无需鉴权：那也可能只是还没填，
+         * 见 `LlmProviderEntry.noApiKey`。
+         */
         apiKey?: string;
         baseURL?: string;
         /** LLM 请求日志根目录，按日期分目录，不传则不记录 */
         logDir?: string;
+        /**
+         * 单次请求超时（毫秒）。缺省/非法时回落到 `OPENAI_TIMEOUT_MS`，再回落 10 分钟。
+         *
+         * 必须能按供应商设置：推理模型的合理预算与普通模型差一个数量级，共用一个全局值
+         * 只能二选一（慢模型被掐断，或快模型失败时干等十分钟）。
+         */
+        timeoutMs?: number | null;
+        /**
+         * API 模式（auto / responses / chat）。缺省时读 `OPENAI_FORCE_API_MODE`，再缺省 auto。
+         */
+        apiMode?: ApiMode | null;
     });
     /**
      * 解析指定模型的 API 模式。
      *
-     * 优先级：环境变量 OPENAI_FORCE_API_MODE（responses|chat）强制指定
-     * > 运行时降级缓存（该模型曾因"不支持"失败而缓存为 chat）
+     * 优先级：本实例的显式配置（responses|chat）
+     * > 运行时降级缓存（该端点+模型曾因"不支持"失败而缓存为 chat）
      * > 默认 responses（Responses 优先）。
      */
     private _resolveMode;
+    /** 记录「该端点+模型不支持 Responses」，后续同进程内的请求直走 Chat */
+    private _markChatMode;
     /**
      * Responses 失败的分类（决定「能不能改走 Chat Completions」以及要不要缓存降级）。
      *

package/dist/{TurnEngine-BPKhWuSI.d.cts → TurnEngine-CMGdcSdp.d.cts}

@@ -1,5 +1,6 @@
 import { T as TokenUsage, M as Message, a as ToolSchema, R as ReasoningEffort, S as StreamChunk, b as MessageAttachment, c as StoredAttachment } from './types-BYyXWWPW.cjs';
 import { a as ToolMetadata, T as ToolRegistry } from './ToolRegistry-DouDvn9E.cjs';
+import { ApiMode } from './internal/providers/diagnostics.cjs';
 import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
 import { ModelCapability } from '@zqagent/shared/model-capabilities';
@@ -344,22 +345,51 @@ declare class OpenAIProvider implements ProviderClient {
     private _logDir?;
     /** 服务端点 baseURL（用于识别 DeepSeek 等特定供应商） */
     private _baseURL;
-    /** 模型 → API 模式缓存：某模型不支持 Responses 后，后续直走 Chat */
-    private _modeByModel;
+    /**
+     * 本实例的 API 模式。
+     *
+     * 显式配置 > 全局 `OPENAI_FORCE_API_MODE` > auto（先 Responses 再降级）。
+     * 早先只有全局环境变量一种表达方式，一个节点挂两家供应商时无法各自指定。
+     */
+    private _apiMode;
     constructor(opts: {
+        /**
+         * API Key。
+         *
+         * - 显式 `""`（含纯空白）：**明确表示该端点不需要鉴权**（本地 Ollama /
+         *   llama.cpp、内网网关），不会回落到环境变量，SDK 收到占位 Key。
+         * - `undefined`：回落到 `OPENAI_API_KEY`；两者都没有时抛错（多数情况是
+         *   真的没配，早点给出可读提示好过让用户对着 401 猜）。
+         *
+         * 调用方不要用「配置里 Key 为空」来推断无需鉴权：那也可能只是还没填，
+         * 见 `LlmProviderEntry.noApiKey`。
+         */
         apiKey?: string;
         baseURL?: string;
         /** LLM 请求日志根目录，按日期分目录，不传则不记录 */
         logDir?: string;
+        /**
+         * 单次请求超时（毫秒）。缺省/非法时回落到 `OPENAI_TIMEOUT_MS`，再回落 10 分钟。
+         *
+         * 必须能按供应商设置：推理模型的合理预算与普通模型差一个数量级，共用一个全局值
+         * 只能二选一（慢模型被掐断，或快模型失败时干等十分钟）。
+         */
+        timeoutMs?: number | null;
+        /**
+         * API 模式（auto / responses / chat）。缺省时读 `OPENAI_FORCE_API_MODE`，再缺省 auto。
+         */
+        apiMode?: ApiMode | null;
     });
     /**
      * 解析指定模型的 API 模式。
      *
-     * 优先级：环境变量 OPENAI_FORCE_API_MODE（responses|chat）强制指定
-     * > 运行时降级缓存（该模型曾因"不支持"失败而缓存为 chat）
+     * 优先级：本实例的显式配置（responses|chat）
+     * > 运行时降级缓存（该端点+模型曾因"不支持"失败而缓存为 chat）
      * > 默认 responses（Responses 优先）。
      */
     private _resolveMode;
+    /** 记录「该端点+模型不支持 Responses」，后续同进程内的请求直走 Chat */
+    private _markChatMode;
     /**
      * Responses 失败的分类（决定「能不能改走 Chat Completions」以及要不要缓存降级）。
      *

package/dist/index.cjs

@@ -386,9 +386,23 @@ function paramErrorHints(message, code = "") {
   }
   return hints;
 }
-function llmTimeoutMs() {
+var DEFAULT_LLM_TIMEOUT_MS = 6e5;
+function normLlmTimeoutMs(v) {
+  if (v === null || v === void 0 || v === "") return null;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return Math.min(Math.round(n), 30 * 6e4);
+}
+function llmTimeoutMs(explicit) {
+  const fromArg = normLlmTimeoutMs(explicit);
+  if (fromArg) return fromArg;
   const n = Number(process.env.OPENAI_TIMEOUT_MS);
-  return Number.isFinite(n) && n > 0 ? n : 6e5;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_LLM_TIMEOUT_MS;
+}
+function normApiMode(v) {
+  const s = typeof v === "string" ? v.trim().toLowerCase() : "";
+  if (s === "auto" || s === "responses" || s === "chat") return s;
+  return null;
 }
 function llmStreamIdleMs() {
   const n = Number(process.env.OPENAI_STREAM_IDLE_MS);
@@ -4615,6 +4629,32 @@ var ResponsesApiError = class extends Error {
   type;
   requestId;
 };
+var NO_AUTH_KEY = "not-needed";
+var degradedModes = /* @__PURE__ */ new Map();
+var DEGRADED_TTL_MS = 30 * 6e4;
+var DEGRADED_MAX = 500;
+function modeKey(baseURL, model) {
+  return `${baseURL}::${model}`;
+}
+function isDegraded(baseURL, model) {
+  const k = modeKey(baseURL, model);
+  const hit = degradedModes.get(k);
+  if (!hit) return false;
+  if (Date.now() - hit.at > DEGRADED_TTL_MS) {
+    degradedModes.delete(k);
+    return false;
+  }
+  return true;
+}
+function markDegraded(baseURL, model) {
+  degradedModes.delete(modeKey(baseURL, model));
+  degradedModes.set(modeKey(baseURL, model), { at: Date.now() });
+  while (degradedModes.size > DEGRADED_MAX) {
+    const oldest = degradedModes.keys().next();
+    if (oldest.done) break;
+    degradedModes.delete(oldest.value);
+  }
+}
 var OpenAIProvider = class {
   /** OpenAI SDK 客户端 */
   client;
@@ -4622,23 +4662,31 @@ var OpenAIProvider = class {
   _logDir;
   /** 服务端点 baseURL（用于识别 DeepSeek 等特定供应商） */
   _baseURL;
-  /** 模型 → API 模式缓存：某模型不支持 Responses 后，后续直走 Chat */
-  _modeByModel = /* @__PURE__ */ new Map();
+  /**
+   * 本实例的 API 模式。
+   *
+   * 显式配置 > 全局 `OPENAI_FORCE_API_MODE` > auto（先 Responses 再降级）。
+   * 早先只有全局环境变量一种表达方式，一个节点挂两家供应商时无法各自指定。
+   */
+  _apiMode;
   constructor(opts) {
+    const explicitKey = opts.apiKey !== void 0;
     const apiKey = cleanLlmValue(opts.apiKey ?? process.env.OPENAI_API_KEY);
     const baseURL = normalizeBaseURL(opts.baseURL ?? process.env.OPENAI_BASE_URL);
-    if (!apiKey) {
+    if (!apiKey && !explicitKey) {
       throw new Error(sanitizeEmoji("\u274C \u672A\u8BBE\u7F6E OPENAI_API_KEY \u73AF\u5883\u53D8\u91CF"));
     }
+    const effectiveKey = apiKey ?? NO_AUTH_KEY;
     this._baseURL = baseURL ?? "";
+    this._apiMode = normApiMode(opts.apiMode) ?? normApiMode(process.env.OPENAI_FORCE_API_MODE) ?? "auto";
     const agent = socksAgent();
     const proxyHint = unsupportedProxyHint();
     if (proxyHint) console.warn(`[llm] ${proxyHint}`);
     const baseFetch = agent ? makeSocksFetch(agent) : ((input, init) => globalThis.fetch(input, init));
     this.client = new import_openai.default({
-      apiKey,
+      apiKey: effectiveKey,
       ...baseURL ? { baseURL } : {},
-      timeout: llmTimeoutMs(),
+      timeout: llmTimeoutMs(opts.timeoutMs),
       maxRetries: llmMaxRetries(),
       // 类型：SDK 期望 (RequestInfo, RequestInit) => Promise<Response>，
       // node-fetch 的 Response 与 DOM Response 结构不同，此处显式放宽
@@ -4655,14 +4703,17 @@ var OpenAIProvider = class {
   /**
    * 解析指定模型的 API 模式。
    *
-   * 优先级：环境变量 OPENAI_FORCE_API_MODE（responses|chat）强制指定
-   * > 运行时降级缓存（该模型曾因"不支持"失败而缓存为 chat）
+   * 优先级：本实例的显式配置（responses|chat）
+   * > 运行时降级缓存（该端点+模型曾因"不支持"失败而缓存为 chat）
    * > 默认 responses（Responses 优先）。
    */
   _resolveMode(model) {
-    const forced = process.env.OPENAI_FORCE_API_MODE?.toLowerCase();
-    if (forced === "responses" || forced === "chat") return forced;
-    return this._modeByModel.get(model) ?? "responses";
+    if (this._apiMode !== "auto") return this._apiMode;
+    return isDegraded(this._baseURL, model) ? "chat" : "responses";
+  }
+  /** 记录「该端点+模型不支持 Responses」，后续同进程内的请求直走 Chat */
+  _markChatMode(model) {
+    markDegraded(this._baseURL, model);
   }
   /**
    * Responses 失败的分类（决定「能不能改走 Chat Completions」以及要不要缓存降级）。
@@ -4738,7 +4789,7 @@ var OpenAIProvider = class {
         } catch (err) {
           const kind = this._responsesFailureKind(err, true);
           if (kind) {
-            if (kind === "endpoint") this._modeByModel.set(model, "chat");
+            if (kind === "endpoint") this._markChatMode(model);
             console.warn(
               `[llm] ${model} Responses API \u4E0D\u53EF\u7528(${kind})\uFF0C\u6539\u7528 Chat Completions (${String(
                 err?.message ?? err
@@ -4812,7 +4863,7 @@ var OpenAIProvider = class {
       } catch (err) {
         const kind = this._responsesFailureKind(err, true);
         if (kind) {
-          if (kind === "endpoint") this._modeByModel.set(model, "chat");
+          if (kind === "endpoint") this._markChatMode(model);
           console.warn(
             `[llm] ${model} Responses API \u4E0D\u53EF\u7528(${kind})\uFF0C\u6539\u7528 Chat Completions (${String(
               err?.message ?? err
@@ -4858,7 +4909,7 @@ var OpenAIProvider = class {
     } catch (err) {
       const kind = emitted ? null : this._responsesFailureKind(err, false);
       if (!kind) throw enrichLlmError(err, this._baseURL);
-      if (kind === "endpoint") this._modeByModel.set(ctx.model, "chat");
+      if (kind === "endpoint") this._markChatMode(ctx.model);
       console.warn(
         `[llm] ${ctx.model} Responses \u6D41\u5185\u5931\u8D25(${kind})\uFF0C\u6539\u7528 Chat Completions (${String(
           err?.message ?? err
@@ -13387,6 +13438,8 @@ function createDefaultEngine(opts) {
     mode = "interactive" /* INTERACTIVE */,
     maxIterations = DEFAULT_MAX_ITERATIONS,
     reasoningEffort,
+    timeoutMs,
+    apiMode,
     allowedCommands = [],
     shellPolicy = "approve",
     sandbox,
@@ -13407,7 +13460,7 @@ function createDefaultEngine(opts) {
   } = opts;
   const envEffort = process.env.OPENAI_REASONING_EFFORT?.toLowerCase();
   const effectiveEffort = reasoningEffort ?? (envEffort === "low" || envEffort === "medium" || envEffort === "high" ? envEffort : void 0);
-  const effectiveProvider = provider ?? new OpenAIProvider({ logDir });
+  const effectiveProvider = provider ?? new OpenAIProvider({ logDir, timeoutMs, apiMode });
   const sandboxPlan = resolveSandbox({ ...sandbox, workspace });
   const registry = new ToolRegistry();
   const conflictGuard = new ConflictGuard();