w-dispatch-ai 1.0.6 → 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:30: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:30: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:30: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:30: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:30: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:30: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

@@ -2278,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>
     
 
@@ -2754,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>
 
     
@@ -7230,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>
     
 
@@ -8018,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>
 
     
@@ -8054,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>
 
     
@@ -8094,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>
 
     
@@ -8679,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>
 
     
@@ -9270,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:30: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:30: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:30: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

@@ -285,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:30: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:30: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:30: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:30: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:30: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.6",
+  "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/runFanout.mjs

@@ -50,9 +50,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等)，預設{}
@@ -114,9 +114,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)
 
@@ -134,9 +136,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,

package/src/wkf/runFanoutPipeline.mjs

@@ -29,7 +29,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={}] 輸入透傳兩段之共用呼叫設定，預設{}

package/test/unit-dispatchAiFallback.test.mjs

@@ -316,6 +316,101 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('cooldownMs啟用時, 逾時觸發冷卻且次輪該條目降至鏈尾(只降序不移除)', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let pHang = { id: 'cd-hang', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 }
+        let pOk = { id: 'cd-ok', kind: 'claude', exe: fake.exe }
+        //第1輪: hang在鏈首 → 逾時跳組並觸發冷卻 → ok遞補
+        let r1 = await dispatchAiFallback('abc', { providers: [pHang, pOk], store, cooldownMs: 300000 })
+        //第2輪: hang冷卻中 → 降至鏈尾, ok先上且成功, hang完全未被嘗試
+        let r2 = await dispatchAiFallback('abc', { providers: [pHang, pOk], store, cooldownMs: 300000 })
+        let r = [
+            r1.providerId,
+            r1.tried.map((x) => x.providerId),
+            typeof stored.cooling['cd-hang'],
+            r2.providerId,
+            r2.tried.map((x) => x.providerId), //只有cd-ok, 未浪費一次逾時
+        ]
+        let rr = ['cd-ok', ['cd-hang', 'cd-ok'], 'number', 'cd-ok', ['cd-ok']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('冷卻中的條目於前面全敗時仍會被嘗試, 且成功即解除冷卻', async function() {
+        let stored = { cursors: {}, cooling: { 'cd2-a': Date.now() } } //預置: a冷卻中
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd2-a', kind: 'claude', exe: fake.exe }, //冷卻中 → 降至鏈尾
+                { id: 'cd2-b', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] }, //鏈首但必敗
+            ],
+            store,
+            cooldownMs: 300000,
+        })
+        let r = [
+            r1.ok,
+            r1.providerId, //b先上失敗 → 降序後的a仍被嘗試且成功
+            r1.tried.map((x) => x.providerId),
+            stored.cooling['cd2-a'], //成功即解除
+        ]
+        let rr = [true, 'cd2-a', ['cd2-b', 'cd2-a'], undefined]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('冷卻過期後恢復原順序並清除過期紀錄', async function() {
+        let stored = { cursors: {}, cooling: { 'cd3-a': Date.now() - 1000 } } //1秒前觸發
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd3-a', kind: 'claude', exe: fake.exe },
+                { id: 'cd3-b', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 500, //視窗0.5秒, 已過期
+        })
+        let r = [r1.providerId, stored.cooling['cd3-a']]
+        let rr = ['cd3-a', undefined] //恢復鏈首, 過期紀錄被清除
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('cooldownMs未啟用(預設)時不重排也不寫入cooling', async function() {
+        let stored = { cursors: {}, cooling: { 'cd4-a': Date.now() } }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let r1 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'cd4-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 },
+                { id: 'cd4-b', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+        })
+        let r = [
+            r1.tried.map((x) => x.providerId), //cooling有預置紀錄仍不重排(未啟用)
+            typeof stored.cooling['cd4-a'] === 'number' && stored.cooling['cd4-b'] === undefined, //逾時亦不新增紀錄
+        ]
+        let rr = [['cd4-a', 'cd4-b'], true]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('失敗事件與tried帶被拒回覆(stdout)與錯誤輸出(stderr)供診斷', async function() {
         let evs = []
         let t = await dispatchAiFallback('abc', {

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -245,6 +245,34 @@ describe('dispatchApiOpenaiCompat', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('HTTP 429觸發冷卻: 次輪該條目降至鏈尾', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        //flaky-429對同一金鑰首次回429; maxRetries預設0故第1輪即失敗並觸發冷卻
+        let p429 = { id: 'cd-api-429', kind: 'api-openai-compat', baseURL: svr.url, model: 'flaky-429', keys: ['sk-good-cd429'] }
+        let pEcho = { id: 'cd-api-echo', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-cd-e'] }
+        let r1 = await dispatchAiFallback('abc', { providers: [p429, pEcho], store, cooldownMs: 300000 })
+        let r2 = await dispatchAiFallback('abc', { providers: [p429, pEcho], store, cooldownMs: 300000 })
+        let r = [
+            r1.providerId,
+            r1.tried.map((x) => [x.providerId, x.error || null]),
+            typeof stored.cooling['cd-api-429'],
+            r2.tried.map((x) => x.providerId), //429者已降尾, echo先上即成功
+        ]
+        let rr = [
+            'cd-api-echo',
+            [['cd-api-429', 'HTTP 429'], ['cd-api-echo', null]],
+            'number',
+            ['cd-api-echo'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('可作為工作流provider, 回覆JSON經解析與檢核', async function() {
         let wkf = dispatchAiWkf({
             providers: {