w-dispatch-ai 1.0.5 → 1.0.7

package/docs/dispatchApiOpenaiCompat.mjs.html

@@ -504,7 +504,7 @@ export default dispatchApiOpenaiCompat
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchClaude.mjs.html

@@ -190,7 +190,7 @@ export default dispatchClaude
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchCodex.mjs.html

@@ -191,7 +191,7 @@ export default dispatchCodex
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchOpencode.mjs.html

@@ -260,7 +260,7 @@ export default dispatchOpencode
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getCliArgs.mjs.html

@@ -113,7 +113,7 @@ export default getCliArgs
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getErrorResult.mjs.html

@@ -102,7 +102,7 @@ export default getErrorResult
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/global.html

@@ -376,7 +376,7 @@ console.log(dfTimeoutMs)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line62">line 62</a>
+        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line70">line 70</a>
     </li></ul></dd>
     
 
@@ -736,7 +736,7 @@ parse＋check接進遞補層之validate——非法回覆視為該家失敗而
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line135">line 135</a>
+        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line144">line 144</a>
     </li></ul></dd>
     
 
@@ -1250,6 +1250,46 @@ await test()
 
     
 
+        <tr>
+            
+                <td class="name"><code>minAttemptMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>20000</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入搭配budgetMs之開工門檻毫秒正整數，剩餘預算低於此值即不再開工，預設20000</p></td>
+        </tr>
+
+    
+
         <tr>
             
                 <td class="name"><code>maxRetries</code></td>
@@ -1405,7 +1445,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入遞補層事件回調函數，預設null</p></td>
+            <td class="description last"><p>輸入遞補層事件回調函數，預設null。除上列外之其餘鍵(retryDelayMs、maxBuffer、onStdout等)亦一律原樣轉傳dispatchAiFallback</p></td>
         </tr>
 
     
@@ -2238,7 +2278,7 @@ providers陣列順序即優先序，排前面的先用；
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line189">line 189</a>
+        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line199">line 199</a>
     </li></ul></dd>
     
 
@@ -2714,7 +2754,47 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入狀態持久化物件{get:()=&gt;state,set:(state)=&gt;{}}，state內含cursors(逐群組游標)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖</p></td>
+            <td class="description last"><p>輸入狀態持久化物件{get:()=&gt;state,set:(state)=&gt;{}}，state內含cursors(逐群組游標)與cooling(供應商冷卻時間戳，僅cooldownMs&gt;0時使用)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>cooldownMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>0</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入供應商冷卻視窗毫秒非負整數，&gt;0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用</p></td>
         </tr>
 
     
@@ -7190,7 +7270,7 @@ console.log(getErrorResult(null).error)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line85">line 85</a>
+        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line94">line 94</a>
     </li></ul></dd>
     
 
@@ -7978,7 +8058,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入前段名額規格陣列，各元素{ use, fallback, maxRetries?, timeoutMs? }等(除use/fallback外之鍵覆寫該名額呼叫設定)</p></td>
+            <td class="description last"><p>輸入前段名額規格陣列，各元素{ use, fallback, check?, maxRetries?, timeoutMs? }等(check可覆寫頂層檢核；除use/fallback/check外之鍵覆寫該名額呼叫設定)</p></td>
         </tr>
 
     
@@ -8014,7 +8094,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入整合名額規格物件{ use, fallback, prompt?, ... }，prompt可為(candidates)=&gt;String自訂整合提示詞，省略用預設模板</p></td>
+            <td class="description last"><p>輸入整合名額規格物件{ use, fallback, prompt?, check?, ... }，prompt可為(candidates)=&gt;String自訂整合提示詞(省略用預設模板)；check為終稿專屬檢核(終稿判準常與候選不同，如須含固定段落)，未給則沿用頂層check</p></td>
         </tr>
 
     
@@ -8054,7 +8134,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入候選與終稿共用之檢核函數(json)=&gt;Boolean，預設null</p></td>
+            <td class="description last"><p>輸入檢核函數(json)=&gt;Boolean，作為候選與終稿之共用預設，名額規格與integrate可各自帶check覆寫，預設null</p></td>
         </tr>
 
     
@@ -8639,7 +8719,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入前段共用檢核函數，後段各階段自帶check，預設null</p></td>
+            <td class="description last"><p>輸入前段共用檢核函數(前段名額規格與integrate可各自帶check覆寫，同runFanout)，後段各階段自帶check，預設null</p></td>
         </tr>
 
     
@@ -9230,7 +9310,7 @@ await test()
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/resolveProviders.mjs.html

@@ -176,7 +176,7 @@ export default resolveProviders
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_callAiWithFallback.mjs.html

@@ -46,6 +46,7 @@
     <section>
         <article>
             <pre class="prettyprint source linenums"><code>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'
@@ -81,6 +82,13 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 //   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
 
 
+//本層自用之設定鍵, 其餘鍵(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 = [
     '【執行約束】你只需把結果輸出在回覆內容中。',
@@ -146,10 +154,11 @@ function buildChain(providers, spec) {
  * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
  * @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
@@ -232,15 +241,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) || dfTimeoutMs, //全套件統一預設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,
     })
 
     //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件
@@ -279,7 +285,7 @@ export { buildChain, NO_SIDE_EFFECT }
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_extractJsonLoose.mjs.html

@@ -167,7 +167,7 @@ export default extractJsonLoose
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runFanout.mjs.html

@@ -97,9 +97,9 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)，透傳callAiWithFallback
  * @param {String} opt.task 輸入前段各名額共用之任務提示詞字串
- * @param {Array} opt.agents 輸入前段名額規格陣列，各元素{ use, fallback, maxRetries?, timeoutMs? }等(除use/fallback外之鍵覆寫該名額呼叫設定)
- * @param {Object} opt.integrate 輸入整合名額規格物件{ use, fallback, prompt?, ... }，prompt可為(candidates)=>String自訂整合提示詞，省略用預設模板
- * @param {Function} [opt.check=null] 輸入候選與終稿共用之檢核函數(json)=>Boolean，預設null
+ * @param {Array} opt.agents 輸入前段名額規格陣列，各元素{ use, fallback, check?, maxRetries?, timeoutMs? }等(check可覆寫頂層檢核；除use/fallback/check外之鍵覆寫該名額呼叫設定)
+ * @param {Object} opt.integrate 輸入整合名額規格物件{ use, fallback, prompt?, check?, ... }，prompt可為(candidates)=>String自訂整合提示詞(省略用預設模板)；check為終稿專屬檢核(終稿判準常與候選不同，如須含固定段落)，未給則沿用頂層check
+ * @param {Function} [opt.check=null] 輸入檢核函數(json)=>Boolean，作為候選與終稿之共用預設，名額規格與integrate可各自帶check覆寫，預設null
  * @param {String} [opt.schema=''] 輸入輸出格式示意字串，供預設整合模板嵌入，預設''
  * @param {Number} [opt.minCandidates=2] 輸入進入整合所需之最少成功候選數正整數，未達門檻以首位候選為成果，預設2
  * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定(cwd、store、onEvent、timeoutMs、promptPrefix等)，預設{}
@@ -161,9 +161,11 @@ async function runFanout(opt = {}) {
     }
 
     //前段: 並行多開, 個別失敗不炸整輪
+    //各名額可自帶check覆寫頂層(候選與終稿判準本可不同); 自spec抽出而非留在overrides,
+    //否則會被後方明給之check靜默覆蓋(曾為死鍵)
     let rsAgents = await Promise.all(agents.map((spec) => {
-        let { use, fallback, ...overrides } = spec
-        return callAiWithFallback(task, { ...callOpt, ...overrides, providers, spec: { use, fallback }, check })
+        let { use, fallback, check: checkAgent, ...overrides } = spec
+        return callAiWithFallback(task, { ...callOpt, ...overrides, providers, spec: { use, fallback }, check: isfun(checkAgent) ? checkAgent : check })
     }))
     let candidates = rsAgents.filter((r) => r.ok).map((r) => r.json)
 
@@ -181,9 +183,10 @@ async function runFanout(opt = {}) {
     if (!integrate || !isestr(get(integrate, 'use', ''))) {
         return { ok: false, result: null, integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: 'integrate spec (with use) is required' }
     }
-    let { use, fallback, prompt: intPromptFn, ...intOverrides } = integrate
+    //整合可帶獨立check(終稿判準常較候選嚴, 如須含固定小標題), 未給則沿用頂層check
+    let { use, fallback, prompt: intPromptFn, check: checkInt, ...intOverrides } = integrate
     let intPrompt = isfun(intPromptFn) ? intPromptFn(candidates) : defaultIntegratePrompt(candidates, opt)
-    let rInt = await callAiWithFallback(intPrompt, { ...callOpt, ...intOverrides, providers, spec: { use, fallback }, check })
+    let rInt = await callAiWithFallback(intPrompt, { ...callOpt, ...intOverrides, providers, spec: { use, fallback }, check: isfun(checkInt) ? checkInt : check })
 
     return {
         ok: rInt.ok,
@@ -214,7 +217,7 @@ export { defaultIntegratePrompt }
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runFanoutPipeline.mjs.html

@@ -76,7 +76,7 @@ import runRolePipeline from './runRolePipeline.mjs'
  * @param {Array} opt.agents 輸入前段名額規格陣列(同runFanout)
  * @param {Object} opt.integrate 輸入前段整合名額規格物件(同runFanout)
  * @param {Array} opt.stages 輸入後段階段規格陣列(同runRolePipeline)，各階段以ctx.input取得前段成果
- * @param {Function} [opt.check=null] 輸入前段共用檢核函數，後段各階段自帶check，預設null
+ * @param {Function} [opt.check=null] 輸入前段共用檢核函數(前段名額規格與integrate可各自帶check覆寫，同runFanout)，後段各階段自帶check，預設null
  * @param {String} [opt.schema=''] 輸入輸出格式示意字串(供前段預設整合模板)，預設''
  * @param {Number} [opt.minCandidates=2] 輸入前段整合門檻正整數，預設2
  * @param {Object} [opt.callOpt={}] 輸入透傳兩段之共用呼叫設定，預設{}
@@ -165,7 +165,7 @@ export default runFanoutPipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runRolePipeline.mjs.html

@@ -182,7 +182,7 @@ export default runRolePipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 14 2026 15:11:06 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.8.70"

package/src/dispatchAiFallback.mjs

@@ -27,6 +27,15 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 // 【跨次記憶只有游標】成功後游標推進至下一把, 令額度在同組多把金鑰間自動均攤;
 //   死金鑰的代價也被游標攤平——這輪從key1敗轉key2成功後游標停在key3, 下輪不會先碰key1。
 //
+// 【供應商冷卻(選用, cooldownMs>0啟用, 預設關閉)】多階段工作流的每一階段都會從鏈首
+//   重新探測同一家已失效的供應商——限流時每階段各踩一輪429、卡死時各燒一次完整逾時
+//   (使用端實測: 一次107秒的多階段請求中72秒耗在重複踩同一組429, 啟用冷卻後降至15秒)。
+//   設計與「金鑰停用清單」(已否決)的關鍵差異: 以「條目」為單位、短視窗、且「只降序不移除」
+//   ——冷卻中的條目移到鏈尾而非移除, 前面全敗時照樣會被嘗試, 故不存在把已恢復服務冰住的問題;
+//   任一次成功立即解除。觸發限於限流(HTTP 429, 僅api-openai-compat可靠偵測; CLI類之限流
+//   埋在stderr文字中不納入)與逾時(TIMEOUT開頭, 各kind皆可)兩類——其餘失敗已有換金鑰換家
+//   機制處理, 納入反而誤傷。狀態存於state.cooling, 與cursors同走store持久化。
+//
 // 【時間預算】budgetMs限制整輪遞補的總時長, 剩餘預算會壓進每次呼叫的timeoutMs,
 //   防止多家連續卡逾時而撞破外部排程的執行上限。
 //
@@ -60,7 +69,7 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 
 
 //fallback層自用之設定鍵, 其餘鍵作為各attempt之共用預設原樣轉傳
-let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'store', 'onEvent']
+let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'cooldownMs', 'store', 'onEvent']
 
 
 //providers條目自用之設定鍵, 其餘鍵(含kind)即該條目之opt原樣轉傳對應轉接器
@@ -139,7 +148,8 @@ function isKeyIndependentFail(r) {
  * @param {Array} [opt.providers[].keys=[]] 輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰
  * @param {Number} [opt.budgetMs=null] 輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限
  * @param {Number} [opt.minAttemptMs=20000] 輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000
- * @param {Object} [opt.store=null] 輸入狀態持久化物件{get:()=>state,set:(state)=>{}}，state內含cursors(逐群組游標)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖
+ * @param {Object} [opt.store=null] 輸入狀態持久化物件{get:()=>state,set:(state)=>{}}，state內含cursors(逐群組游標)與cooling(供應商冷卻時間戳，僅cooldownMs>0時使用)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖
+ * @param {Number} [opt.cooldownMs=0] 輸入供應商冷卻視窗毫秒非負整數，>0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用
  * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'；失敗事件(next-key/skip-group)另帶stdout(被拒回覆)與stderr(錯誤輸出)供診斷，兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
  * @param {Number} [opt.timeoutMs=300000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000
  * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
@@ -235,6 +245,9 @@ async function dispatchAiFallback(prompt, opt = {}) {
     if (!isobj(state.cursors)) {
         state.cursors = {}
     }
+    if (!isobj(state.cooling)) {
+        state.cooling = {}
+    }
     let saveState = () => {
         if (useStore) {
             try {
@@ -244,6 +257,43 @@ async function dispatchAiFallback(prompt, opt = {}) {
         }
     }
 
+    //cooldownMs, 無效視為0＝不啟用(現行行為零改變)
+    let cooldownMs = get(opt, 'cooldownMs', null)
+    if (!ispint(cooldownMs)) {
+        cooldownMs = 0
+    }
+    else {
+        cooldownMs = cint(cooldownMs)
+    }
+
+    //供應商冷卻: 冷卻中的條目「只降序不移除」——移到鏈尾, 前面全敗時仍會被嘗試,
+    //故不存在把已恢復服務冰住的問題(此為與「金鑰停用清單」的關鍵差異, 後者已被否決)。
+    //僅追蹤有明給id之條目(索引式id會因重排而錯位); 過期項順手清除
+    if (cooldownMs > 0) {
+        let now = Date.now()
+        let act = []
+        let cool = []
+        let dirty = false
+        for (let p of providers) {
+            let pid = get(p, 'id', null)
+            let ts = isestr(pid) ? get(state.cooling, pid, null) : null
+            if (ispint(ts) && (now - ts) < cooldownMs) {
+                cool.push(p)
+            }
+            else {
+                if (isestr(pid) && state.cooling[pid] !== undefined) {
+                    delete state.cooling[pid] //冷卻已過期, 清除
+                    dirty = true
+                }
+                act.push(p)
+            }
+        }
+        providers = [...act, ...cool]
+        if (dirty) {
+            saveState()
+        }
+    }
+
     //onEvent, 回調拋出例外不得中斷主流程
     let onEvent = get(opt, 'onEvent', null)
     let emit = (ev) => {
@@ -266,9 +316,10 @@ async function dispatchAiFallback(prompt, opt = {}) {
     for (let ig = 0; ig < providers.length; ig++) {
         let entry = providers[ig]
 
-        //id, 無效回退條目索引字串
+        //id, 無效回退條目索引字串; idExplicit供冷卻機制判別(索引式id不參與冷卻)
         let id = get(entry, 'id', null)
-        if (!isestr(id)) {
+        let idExplicit = isestr(id)
+        if (!idExplicit) {
             id = String(ig)
         }
 
@@ -331,8 +382,12 @@ async function dispatchAiFallback(prompt, opt = {}) {
             emit({ type: 'try', providerId: id, keyIndex, keyId, kind, model })
             let r = await dispatchAi(kind, prompt, attemptOpt)
 
-            //成功, 推進游標(額度均攤)並回傳
+            //成功, 推進游標(額度均攤)並回傳; 任一次成功立即解除該家冷卻
             if (r.ok) {
+                if (cooldownMs > 0 && idExplicit && state.cooling[id] !== undefined) {
+                    delete state.cooling[id]
+                    saveState()
+                }
                 if (nk > 0) {
                     state.cursors[id] = (keyIndex + 1) % nk
                     saveState()
@@ -345,6 +400,16 @@ async function dispatchAiFallback(prompt, opt = {}) {
             //失敗分流
             lastResult = r
             lastMeta = { providerId: id, keyIndex, kind, model }
+            //冷卻觸發: 限流(HTTP 429, 僅api類可偵測)與逾時(TIMEOUT開頭, CLI與api皆可)兩類——
+            //其餘失敗(金鑰無效/服務端錯誤)已有換金鑰換家機制處理, 納入冷卻反而誤傷
+            if (cooldownMs > 0 && idExplicit) {
+                let isCoolTrigger = (r.code === 429) || (isestr(r.error) && r.error.indexOf('TIMEOUT') === 0)
+                if (isCoolTrigger) {
+                    state.cooling[id] = Date.now()
+                    saveState()
+                }
+            }
+
             //失敗事件與tried一併帶被拒回覆(stdout)與錯誤輸出(stderr), 供呼叫端診斷失敗原因
             //(如驗證失敗時模型究竟回了什麼); 兩者於失敗路徑已由轉接器截斷(≤500/1000字元), 不會過大
             if (isKeyIndependentFail(r)) {

package/src/wkf/callAiWithFallback.mjs

@@ -1,4 +1,5 @@
 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'
@@ -34,6 +35,13 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 //   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
 
 
+//本層自用之設定鍵, 其餘鍵(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 = [
     '【執行約束】你只需把結果輸出在回覆內容中。',
@@ -99,10 +107,11 @@ function buildChain(providers, spec) {
  * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
  * @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
@@ -185,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) || dfTimeoutMs, //全套件統一預設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,
     })
 
     //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件