w-dispatch-ai 1.0.4 → 1.0.6

package/src/dispatchAiWkf.mjs

@@ -24,6 +24,15 @@ import runFanoutPipeline from './wkf/runFanoutPipeline.mjs'
 //   額度池與故障域各自獨立而屬不同供應商, 鍵名須帶上路徑加以區分。
 //   命名規則與取捨詳見dispatchAiFallback.mjs檔頭之「條目id之設計規則」。
 //
+// 【timeout速覽】(完整說明見README之「Timeout 總覽」)
+//   單次AI嘗試: timeoutMs, 全套件統一預設300000(5分鐘, 單一來源dfTimeoutMs.mjs),
+//     直接呼叫轉接器與工作流內皆同一數字;
+//   單一名額(遞補鏈): budgetMs, 預設null不限; minAttemptMs開工門檻預設20000(無budget時不作用);
+//   工作流總時長: 無獨立參數(刻意)——由結構推導: Fanout≈最慢名額+整合(並行),
+//     RolePipeline≈Σ各階段(序列); 要上限就對每名額設budgetMs。
+//   最壞情況公式: 名額≤K×timeoutMs(K=鏈組數, 逾時每組只燒一次即跳組)。
+//   調整四層(細者覆蓋粗者): defaults(此處) → 各工作流callOpt → 階段/名額規格 → provider條目。
+//
 // 【定義providers時如何選kind: CLI或API】判準是「該階段需不需要工具」:
 //   需要讀本機檔案、grep、執行指令、抓網頁 → CLI類kind(opencode/claude/codex/antigravity);
 //   純文字生成(素材皆已在prompt內) → API類kind(api-openai-compat), 免安裝免登入且較快。

package/src/dispatchAntigravity.mjs

@@ -8,6 +8,7 @@ import cint from 'wsemi/src/cint.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 // dispatchAntigravity.mjs — 以Google Antigravity CLI(agy)呼叫AI模型
@@ -37,7 +38,7 @@ import getErrorResult from './getErrorResult.mjs'
 
 //預設值
 let DEFAULT_EXE = 'agy'
-let DEFAULT_TIMEOUT_MS = 300000 //agent型CLI, 對齊agy自身print-timeout預設5m0s, 不沿用套件通用120000
+let DEFAULT_TIMEOUT_MS = dfTimeoutMs //全套件統一預設300000(恰對齊agy自身print-timeout預設5m0s)
 let MAX_PROMPT_LENGTH = 30000 //命令列上限32767扣除exe路徑與旗標後之保守值
 let PRINT_TIMEOUT_BUFFER_S = 30
 let MIN_PRINT_TIMEOUT_S = 30
@@ -68,10 +69,10 @@ let OWN_KEYS = ['exe', 'model', 'effort', 'skipPermissions', 'printTimeout', 'ad
  * @param {String} [opt.effort=''] 輸入推理深度字串，可選'low'、'medium'、'high'，需agy>=1.1.11，建議搭配不帶檔位之基礎slug；與帶檔位slug併用且檔位不一致時agy回conflicts錯誤，預設''代表不帶
  * @param {Boolean} [opt.skipPermissions=true] 輸入是否帶`--dangerously-skip-permissions`旗標布林值，false代表保留CLI權限閘門，預設true
  * @param {String} [opt.printTimeout=''] 輸入agy自身等待上限字串(如'10m'、'570s')，預設''代表由timeoutMs推導(扣30秒緩衝，下限30秒)
- * @param {Array} [opt.addDirs=[]] 輸入加入workspace之目錄字串陣列，逐項展開為`--add-dir`，預設[]
+ * @param {Array} [opt.addDirs=自動納入cwd] 輸入加入workspace之目錄字串陣列，逐項展開為`--add-dir`。agy以自身scratch目錄為工作區而不採子進程cwd，故未給本參數時自動納入有效cwd令檔案可視範圍與其他CLI轉接器一致；明示給陣列(含空陣列[]代表不揭露任何目錄)則完全尊重呼叫端
  * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列(如--output-format、--json-schema、--mode)，將接於固定旗標之後、`--print`之前，預設[]
- * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，agy為agent型CLI故預設較長之300000，預設300000
- * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000(恰對齊agy自身print-timeout預設5m0s)
+ * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()。注意本參數不影響agy之檔案可視範圍(agy以自身scratch目錄為工作區)，可視範圍由addDirs決定(未給addDirs時自動納入本目錄)
  * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject
@@ -132,7 +133,7 @@ async function dispatchAntigravity(prompt, opt = {}) {
         skipPermissions = true
     }
 
-    //timeoutMs, 先行取值以供printTimeout推導, agy專屬預設300000
+    //timeoutMs, 先行取值以供printTimeout推導, 無效回退全套件統一預設300000
     let timeoutMs = get(opt, 'timeoutMs', null)
     if (!ispint(timeoutMs)) {
         timeoutMs = DEFAULT_TIMEOUT_MS
@@ -148,13 +149,23 @@ async function dispatchAntigravity(prompt, opt = {}) {
     }
 
     //addDirs, 逐項展開為--add-dir(agy該旗標可重複)
+    //未給時自動納入有效cwd(明給的或預設process.cwd()): agy以自身scratch目錄為工作區,
+    //不採子進程之cwd, 僅--add-dir能擴其檔案可視範圍——僅給cwd時弱模型直接回「找不到檔案」、
+    //強模型得自行摸索(實測116s vs 帶--add-dir僅6s), 且兩者皆ok:true屬靜默失敗,
+    //極易被誤判為模型能力不足(2026-08-13以隨機token實測確認)。
+    //明示addDirs(含空陣列[]代表不揭露任何目錄)則完全尊重呼叫端, 不自動加入
     let addDirs = get(opt, 'addDirs', null)
+    if (!isarr(addDirs)) {
+        let cwdEff = get(opt, 'cwd', null)
+        if (!isestr(cwdEff)) {
+            cwdEff = process.cwd()
+        }
+        addDirs = [cwdEff]
+    }
     let addDirArgs = []
-    if (isarr(addDirs)) {
-        for (let d of addDirs) {
-            if (isestr(d)) {
-                addDirArgs.push('--add-dir', d)
-            }
+    for (let d of addDirs) {
+        if (isestr(d)) {
+            addDirArgs.push('--add-dir', d)
         }
     }
 

package/src/dispatchApiOpenaiCompat.mjs

@@ -11,6 +11,7 @@ import strleft from 'wsemi/src/strleft.mjs'
 import strdelleft from 'wsemi/src/strdelleft.mjs'
 import strTruncate from 'wsemi/src/strTruncate.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 // dispatchApiOpenaiCompat.mjs — 以fetch直呼OpenAI相容API(chat/completions)
@@ -50,7 +51,7 @@ import getErrorResult from './getErrorResult.mjs'
 
 
 //預設值
-let DEFAULT_TIMEOUT_MS = 120000
+let DEFAULT_TIMEOUT_MS = dfTimeoutMs //全套件統一預設300000
 let DEFAULT_RETRY_DELAY_MS = 5000
 let MAX_RETRY_DELAY_MS = 15000
 
@@ -282,7 +283,7 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
  * @param {String} [opt.system=''] 輸入system提示詞字串，將以system角色置於messages首位，預設''代表不帶
  * @param {Object} [opt.body={}] 輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}。注意本轉接器不支援工具，帶入tools而模型回tool_calls時一律以TOOL_CALLS_UNSUPPORTED回報失敗，需要工具請改用CLI類kind
  * @param {Object} [opt.headers={}] 輸入額外請求標頭物件，預設{}
- * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，預設120000
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，全套件統一預設300000
  * @param {String|Function} [opt.validate=undefined] 輸入回覆內容驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0
  * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000

package/src/dispatchClaude.mjs

@@ -1,10 +1,13 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 // dispatchClaude.mjs — 以Claude Code CLI呼叫Claude模型
@@ -44,7 +47,7 @@ let OWN_KEYS = ['exe', 'model', 'skipPermissions', 'extraArgs', 'input']
  * @param {String} [opt.model=''] 輸入模型別名或模型ID字串，例如'sonnet'、'opus'，預設''代表不帶`--model`旗標
  * @param {Boolean} [opt.skipPermissions=true] 輸入是否帶`--dangerously-skip-permissions`旗標布林值，false代表保留CLI權限閘門，預設true
  * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列，將接於固定旗標之後，預設[]
- * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
@@ -56,7 +59,7 @@ let OWN_KEYS = ['exe', 'model', 'skipPermissions', 'extraArgs', 'input']
  *
  * let test = async () => {
  *
- *     let r = await dispatchClaude('請只回覆兩個字：完成', { model: 'sonnet', timeoutMs: 120000 })
+ *     let r = await dispatchClaude('請只回覆兩個字：完成', { model: 'sonnet' })
  *     console.log(r.ok, r.stdout.trim())
  *     // => true '完成'
  *
@@ -104,6 +107,15 @@ async function dispatchClaude(prompt, opt = {}) {
         extraArgs,
     )
 
+    //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = dfTimeoutMs
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
@@ -111,6 +123,7 @@ async function dispatchClaude(prompt, opt = {}) {
     return execCli(exe, args, {
         ...optCli,
         input: prompt,
+        timeoutMs,
     })
 }
 

package/src/dispatchCodex.mjs

@@ -1,9 +1,12 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 // dispatchCodex.mjs — 以OpenAI Codex CLI呼叫GPT模型
@@ -44,7 +47,7 @@ let OWN_KEYS = ['exe', 'model', 'sandbox', 'extraArgs', 'input']
  * @param {String} [opt.model=''] 輸入模型ID字串，例如'gpt-5.6-luna'，預設''代表不帶`-m`旗標
  * @param {String} [opt.sandbox='workspace-write'] 輸入沙箱模式字串，例如'read-only'、'workspace-write'、'danger-full-access'，預設'workspace-write'
  * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列，例如['--config', 'model_reasoning_effort="max"']，將接於固定旗標之後，預設[]
- * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
@@ -105,6 +108,15 @@ async function dispatchCodex(prompt, opt = {}) {
         extraArgs,
     )
 
+    //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = dfTimeoutMs
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
@@ -112,6 +124,7 @@ async function dispatchCodex(prompt, opt = {}) {
     return execCli(exe, args, {
         ...optCli,
         input: prompt,
+        timeoutMs,
     })
 }
 

package/src/dispatchOpencode.mjs

@@ -1,10 +1,13 @@
 import get from 'lodash-es/get.js'
 import omit from 'lodash-es/omit.js'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import execCli from 'wsemi/src/execCli.mjs'
 import getCliArgs from './getCliArgs.mjs'
 import getErrorResult from './getErrorResult.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 // dispatchOpencode.mjs — 以opencode CLI呼叫AI模型
@@ -60,7 +63,7 @@ let OWN_KEYS = ['exe', 'model', 'key', 'provider', 'agent', 'config', 'extraArgs
  * @param {String} [opt.agent='build'] 輸入opencode代理名稱字串，預設'build'
  * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列，將接於固定旗標之後，預設[]
  * @param {Object} [opt.env=undefined] 輸入本次調用額外注入之環境變數物件，同時給予key與provider時會再併入OPENCODE_AUTH_CONTENT，預設undefined
- * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
@@ -173,6 +176,15 @@ async function dispatchOpencode(prompt, opt = {}) {
         }
     }
 
+    //timeoutMs, 無效回退全套件統一預設(dfTimeoutMs=300000), 各轉接器一致令呼叫方無須記多套數字
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = dfTimeoutMs
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+
     //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
     let optCli = omit(opt, OWN_KEYS)
 
@@ -181,6 +193,7 @@ async function dispatchOpencode(prompt, opt = {}) {
         ...optCli,
         input: prompt,
         env,
+        timeoutMs,
     })
 }
 

package/src/providers.mjs

@@ -0,0 +1,133 @@
+// providers.mjs — 預設providers定義檔(實測可用之供應商條目, 開發端可直接全用或自選)
+//
+// 【性質】純資料檔, 不讀環境變數。金鑰以envVar間接引用(機密不落設定檔),
+//   使用前須經resolveProviders展開(envVar → keys, 缺變數者自動停用並回報);
+//   展開後之陣列可直接餵dispatchAiFallback, table可直接餵dispatchAiWkf。
+//
+// 【id命名】依「路徑:模型」規則(詳dispatchAiFallback.mjs檔頭之id設計規則):
+//   oc:＝經opencode CLI(有工具、較慢) / agy:＝antigravity CLI / claude:/codex:＝訂閱登入態CLI
+//   zen:/agnes:/poolside:＝REST直呼(免CLI免登入、快, 純文字生成)
+//   同一模型之CLI版與REST版屬不同供應商(能力與額度池皆不同), 故各為一條。
+//
+// 【使用方式】
+//   import providers from 'w-dispatch-ai/src/providers.mjs'
+//   import resolveProviders from 'w-dispatch-ai/src/resolveProviders.mjs'
+//   process.loadEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS, 逗號分隔多把
+//   let { providers: ps, table, skipped } = resolveProviders(providers) //全取
+//   let r2 = resolveProviders(providers, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] }) //自選, pick順序即遞補優先序
+//
+// 【timeout規劃】各條目刻意不帶timeoutMs, 由上層依任務型態統一給定、條目僅於特例覆寫:
+//   簡單任務(秒級~分鐘級): 沿用套件統一預設即可(全轉接器一律300000＝5分鐘, 見dfTimeoutMs.mjs)。
+//   複雜任務(單一AI工作約15分鐘、fallback須能走到最末):
+//     timeoutMs:    1200000 (20min＝15min工作＋33%餘裕, 單次嘗試上限)
+//     minAttemptMs: 1200000 (剩餘預算不足完整視窗即不開工——開了也不可能完成, 純浪費)
+//     budgetMs:     鏈長K×timeoutMs (逾時型失敗每組只燒一次timeout即跳組, 故K×20min
+//                   保證能走到最末; 例K=4 → 4800000＝80min。無外部排程時限則可null＝不限)
+//     agy之printTimeout由timeoutMs自動推導(−30s), 無須另設。
+//   工作流層總時長: RolePipeline為各階段序列相加(M階段≈M×名額預算);
+//   Fanout各名額並行(≈單一名額預算＋整合名額預算), 外部排程上限須據此預留。
+//   外部調整四層(細者覆蓋粗者): dispatchAiWkf之defaults(全域) → 各工作流callOpt
+//   → 各階段/名額規格 → 各provider條目。
+
+
+let providers = [
+
+    //cli版
+    {
+        id: 'oc:opencode/deepseek-v4-flash-free',
+        model: 'opencode/deepseek-v4-flash-free',
+        kind: 'opencode',
+        envVar: 'OPENCODE_KEYS',
+        provider: 'opencode',
+        config: {
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'oc:agnes-ai/agnes-2.5-flash',
+        model: 'agnes-ai/agnes-2.5-flash',
+        kind: 'opencode',
+        envVar: 'AGNES_KEYS',
+        provider: 'agnes-ai',
+        config: {
+            provider: {
+                'agnes-ai': {
+                    npm: '@ai-sdk/openai-compatible',
+                    name: 'Agnes',
+                    options: { baseURL: 'https://apihub.agnes-ai.com/v1' },
+                    models: { 'agnes-2.5-flash': { name: 'Agnes 2.5 Flash' } },
+                },
+            },
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'oc:poolside/poolside/laguna-s-2.1',
+        model: 'poolside/poolside/laguna-s-2.1',
+        kind: 'opencode',
+        envVar: 'POOLSIDE_KEYS',
+        provider: 'poolside',
+        config: {
+            provider: {
+                'poolside': {
+                    npm: '@ai-sdk/openai-compatible',
+                    name: 'Poolside',
+                    options: { baseURL: 'https://inference.poolside.ai/v1' },
+                    models: { 'poolside/laguna-s-2.1': { name: 'Laguna S 2.1' } },
+                },
+            },
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'agy:gemini-3.7-flash-high',
+        model: 'gemini-3.7-flash-high',
+        kind: 'antigravity',
+        addDirs: ['.'],
+    },
+    {
+        id: 'claude:sonnet',
+        model: 'sonnet',
+        kind: 'claude',
+        extraArgs: ['--disallowedTools', 'Write,Edit,NotebookEdit,Bash'],
+    },
+    {
+        id: 'codex:gpt-5.6-luna',
+        model: 'gpt-5.6-luna',
+        kind: 'codex',
+        sandbox: 'read-only',
+    },
+
+    //api版
+    {
+        id: 'zen:deepseek-v4-flash-free',
+        model: 'deepseek-v4-flash-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+    },
+    {
+        id: 'agnes:agnes-2.5-flash',
+        model: 'agnes-2.5-flash',
+        kind: 'api-openai-compat',
+        envVar: 'AGNES_KEYS',
+        baseURL: 'https://apihub.agnes-ai.com/v1',
+        body: { max_tokens: 8192 },
+    },
+    {
+        id: 'poolside:laguna-s-2.1',
+        model: 'poolside/laguna-s-2.1',
+        kind: 'api-openai-compat',
+        envVar: 'POOLSIDE_KEYS',
+        baseURL: 'https://inference.poolside.ai/v1',
+        body: {
+            max_tokens: 8192,
+            chat_template_kwargs: { enable_thinking: false },
+        },
+    },
+
+]
+
+
+export default providers

package/src/resolveProviders.mjs

@@ -0,0 +1,117 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import isobj from 'wsemi/src/isobj.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+
+
+// resolveProviders.mjs — 把providers定義檔展開為可直接使用的條目
+//
+// 【為何需要】providers.mjs之條目以envVar間接引用金鑰(機密不落設定檔, 只寫變數名),
+//   而dispatchAiFallback只認keys陣列——本函數負責envVar → keys之展開,
+//   缺對應環境變數者停用該條目並列入skipped回報(不中斷、不throw),
+//   訂閱登入態條目(claude/codex等無envVar)原樣通過。
+//
+// 【自選】opt.pick給id陣列即可只取用部分條目, 且依pick之順序回傳
+//   (順序即dispatchAiFallback之優先序); 查無之id列入missing回報。
+
+
+/**
+ * 展開providers定義條目：envVar → keys，並可依id自選子集
+ *
+ * 特點：
+ * 條目之envVar依env來源(預設process.env)展開為keys陣列(變數值以逗號分隔多把)，envVar欄位自輸出移除；
+ * 缺對應環境變數(或值為空)之條目停用並列入skipped，不中斷不throw；
+ * 無envVar之條目(訂閱登入態CLI)原樣通過；條目已自帶有效keys者以keys為準；
+ * opt.pick可依id自選子集並以pick順序回傳(順序即遞補優先序)；
+ * 輸入陣列與條目皆不被改動(輸出為淺拷貝)
+ *
+ * @param {Array} providers 輸入providers條目物件陣列(如providers.mjs之預設匯出)
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} [opt.env=process.env] 輸入金鑰來源物件(變數名 → 逗號分隔之金鑰字串)，預設process.env
+ * @param {Array} [opt.pick=null] 輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)
+ * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)
+ * @example
+ *
+ * import resolveProviders from './src/resolveProviders.mjs'
+ * import providersAll from './src/providers.mjs'
+ *
+ * process.loadEnvFile('./.env') //金鑰放.env, 變數值以逗號分隔多把
+ *
+ * //全取: envVar展開為keys, 缺環境變數者列入skipped
+ * let { providers, table, skipped } = resolveProviders(providersAll)
+ * console.log(providers.length, skipped)
+ * // => 10 []
+ *
+ * //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
+ * let r2 = resolveProviders(providersAll, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
+ * console.log(r2.providers.map((p) => p.id))
+ * // => [ 'agnes:agnes-2.5-flash', 'claude:sonnet' ]
+ *
+ * //table可直接餵dispatchAiWkf之providers定義表
+ * //let wkf = dispatchAiWkf({ providers: r2.table, defaults: { timeoutMs: 1200000 } })
+ *
+ */
+function resolveProviders(providers, opt = {}) {
+
+    //env, 無效回退process.env(瀏覽器環境無process則空物件)
+    let env = get(opt, 'env', null)
+    if (!isobj(env)) {
+        env = (typeof process !== 'undefined' && process && isobj(process.env)) ? process.env : {}
+    }
+
+    //providersRaw
+    let providersRaw = isarr(providers) ? providers.filter(isobj) : []
+
+    //pick, 依id自選並依pick順序回傳
+    let pick = get(opt, 'pick', null)
+    let missing = []
+    let selected = providersRaw
+    if (isearr(pick)) {
+        selected = []
+        for (let id of pick) {
+            let entry = providersRaw.find((p) => get(p, 'id', null) === id)
+            if (entry) {
+                selected.push(entry)
+            }
+            else {
+                missing.push(String(id))
+            }
+        }
+    }
+
+    //展開envVar → keys
+    let out = []
+    let skipped = []
+    for (let entry of selected) {
+        let envVar = get(entry, 'envVar', null)
+
+        //無envVar(訂閱登入態CLI)或已自帶有效keys, 原樣通過(僅移除envVar欄位)
+        if (!isestr(envVar) || isearr(get(entry, 'keys', null))) {
+            out.push(omit(entry, ['envVar']))
+            continue
+        }
+
+        //envVar → keys, 變數值以逗號分隔多把
+        let keys = String(get(env, envVar, '') || '').split(',').map((k) => k.trim()).filter(Boolean)
+        if (keys.length === 0) {
+
+            //缺環境變數: 停用該條目並回報, 不中斷(設計providers原則§四.4)
+            skipped.push({ id: get(entry, 'id', ''), envVar })
+            continue
+        }
+        out.push({ ...omit(entry, ['envVar']), keys })
+    }
+
+    //table, id → 條目, 可直接作dispatchAiWkf之providers定義表
+    let table = {}
+    for (let entry of out) {
+        table[entry.id] = entry
+    }
+
+    return { providers: out, table, skipped, missing }
+}
+
+
+export default resolveProviders

package/src/wkf/callAiWithFallback.mjs

@@ -1,9 +1,11 @@
 import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
 import isearr from 'wsemi/src/isearr.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import dispatchAiFallback from '../dispatchAiFallback.mjs'
+import dfTimeoutMs from '../dfTimeoutMs.mjs'
 import extractJsonLoose from './extractJsonLoose.mjs'
 
 
@@ -23,13 +25,29 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 // 【防寫檔前綴】agentic CLI對cwd隔離免疫(會自行解析專案根目錄寫檔),
 //   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
 //   殷鑑: 2026-08-10執行任務歷史.md遭AI覆寫、評比腳本繞過前綴又產生根目錄孤兒檔。
+//
+//   措辭須豁免「唯讀查閱」(2026-08-13 A/B實測): 各CLI取得檔案內容的途徑不同——
+//   opencode與claude有獨立的read/grep工具, 不受「禁止執行指令」約束;
+//   但codex讀檔即是執行shell指令, 舊措辭「禁止執行任何指令」對它等同「禁止讀檔」,
+//   凡需讀專案的任務會得到一句「請貼上檔案內容」而非成果, 且該拒答是合法字串,
+//   會通過驗證被遞補層當成「成功」, 整條fallback鏈就此停住——兜底地位被靜默廢掉。
+//   實測: 舊措辭下codex回「無法讀取該檔案」, 改為下列措辭後正常讀檔作答(11.1s),
+//   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
+
+
+//本層自用之設定鍵, 其餘鍵(timeoutMs/budgetMs/minAttemptMs/maxRetries/cwd/store/onEvent/
+//retryDelayMs/maxBuffer等)一律原樣轉傳dispatchAiFallback——與各轉接器「剔除自用鍵後
+//原樣轉傳」同一約定; 曾因白名單式轉送漏掉minAttemptMs, 令README教學之工作流層
+//budget保護靜默失效(2026-08-14使用端實測回報), 故改採omit式轉傳杜絕同類漏鍵
+let OWN_KEYS = ['providers', 'spec', 'check', 'parse', 'rawText', 'promptPrefix']
 
 
-//預設防寫檔前綴
+//預設防寫檔前綴(禁副作用, 但豁免唯讀查閱——codex以shell讀檔, 一律禁指令等同禁讀檔)
 let NO_SIDE_EFFECT = [
     '【執行約束】你只需把結果輸出在回覆內容中。',
-    '禁止建立、修改或刪除任何檔案，禁止執行任何指令——呼叫端只讀取你的回覆文字，',
-    '任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '禁止建立、修改或刪除任何檔案，也不要執行任何會改動磁碟或系統狀態的指令——',
+    '呼叫端只讀取你的回覆文字，任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '唯讀查閱（讀取檔案、搜尋內容、列出目錄）不在此限，需要時請照常使用。',
     '', '',
 ].join('\n')
 
@@ -87,12 +105,13 @@ function buildChain(providers, spec) {
  * @param {Function} [opt.parse=extractJsonLoose] 輸入回覆解析函數(stdout)=>Object|null，預設寬鬆JSON抽取
  * @param {Boolean} [opt.rawText=false] 輸入是否以純文字模式運作布林值，true代表不解析JSON(json欄位為修剪後文字、check收文字)，預設false
  * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
- * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，預設300000
+ * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，全套件統一預設300000
  * @param {Number} [opt.budgetMs=null] 輸入整條遞補鏈之時間預算毫秒正整數，預設null代表不限
+ * @param {Number} [opt.minAttemptMs=20000] 輸入搭配budgetMs之開工門檻毫秒正整數，剩餘預算低於此值即不再開工，預設20000
  * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試)
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {Object} [opt.store=null] 輸入游標持久化物件{get,set}，預設null代表用行程內記憶體
- * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null
+ * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null。除上列外之其餘鍵(retryDelayMs、maxBuffer、onStdout等)亦一律原樣轉傳dispatchAiFallback
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、error(錯誤訊息字串)，本函數不會reject
  * @example
  * //need cli in system PATH
@@ -175,15 +194,12 @@ async function callAiWithFallback(prompt, opt = {}) {
         return check ? check(j) === true : true
     }
 
+    //剔除本層自用鍵後原樣轉傳(含minAttemptMs/retryDelayMs/maxBuffer等), providers與validate由本層給定
     let r = await dispatchAiFallback(promptPrefix + prompt, {
+        ...omit(opt, OWN_KEYS),
         providers: chain,
         validate,
-        timeoutMs: get(opt, 'timeoutMs', null) || 300000,
-        budgetMs: get(opt, 'budgetMs', null) || undefined,
-        maxRetries: get(opt, 'maxRetries', null) || 0,
-        cwd: get(opt, 'cwd', null) || process.cwd(),
-        store: get(opt, 'store', null) || undefined,
-        onEvent: get(opt, 'onEvent', null) || undefined,
+        timeoutMs: get(opt, 'timeoutMs', null) || dfTimeoutMs, //全套件統一預設300000
     })
 
     //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件

package/test/unit-WDispatchAi.test.mjs

@@ -10,6 +10,8 @@ import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
+import providers from '../src/providers.mjs'
+import resolveProviders from '../src/resolveProviders.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -26,6 +28,8 @@ describe('WDispatchAi', function() {
             'dispatchCodex',
             'dispatchAntigravity',
             'dispatchApiOpenaiCompat',
+            'providers',
+            'resolveProviders',
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -36,9 +40,9 @@ describe('WDispatchAi', function() {
         assert.strict.deepEqual(r, rr)
     })
 
-    it('除KINDS外各鍵值皆為函數', function() {
+    it('各鍵值型別正確(KINDS與providers為物件, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -52,8 +56,10 @@ describe('WDispatchAi', function() {
             wi.dispatchCodex === dispatchCodex,
             wi.dispatchAntigravity === dispatchAntigravity,
             wi.dispatchApiOpenaiCompat === dispatchApiOpenaiCompat,
+            wi.providers === providers,
+            wi.resolveProviders === resolveProviders,
         ]
-        let rr = [true, true, true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })