w-dispatch-ai 1.0.38 → 1.0.40

package/docs/wkf_runRolePipeline.mjs.html

@@ -183,7 +183,7 @@ export default runRolePipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Sep 24 2026 15:32:02 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 Wed Sep 30 2026 11:57:15 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_salvageTruncatedArray.mjs.html

@@ -165,7 +165,7 @@ export default salvageTruncatedArray
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Sep 24 2026 15:32:02 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 Wed Sep 30 2026 11:57:15 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.38",
+  "version": "1.0.40",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.9.3"

package/src/dispatchAiFallback.mjs

@@ -54,6 +54,14 @@ import { BODY_NOT_JSON } from './describeNonJsonBody.mjs'
 //   中止後每個後續呼叫進門即回ABORTED, 整條工作流自然快速收束, 不需逐層實作。
 //   不中止進行中之嘗試(不殺子進程/不斷開請求), 此為已知設計取捨(避免侵入execCli層)。
 //
+// 【組盡事件(group-exhausted)】逐次事件(try/next-key/skip-group等)不帶呼叫識別, 而同一onEvent常被並行呼叫共用
+//   (如runFanout之各席位)。呼叫端要判斷「某條目在這次呼叫裡整組試完仍無成交」(如健康層據以降序)時,
+//   若以金鑰數與逐把失敗次數重建, 並行呼叫跨越一次成交就會多計或少計——游標只在成交時推進,
+//   在途呼叫與新呼叫的起點不同(2026-09-24下游w-knowledge-extract實測重現), 且重建本身依賴本層之
+//   游標推進時機、每把至多一次、金鑰濾法三項內部性質。故由本層於本組未成交而試完時直接發出,
+//   每次呼叫每組恰一次; 成交、預算用盡、中止(本組未試完)皆不發——後兩者屬呼叫端的時間或意願, 非該組故障。
+//   組邊界只發事件, 不寫入tried(tried為逐次嘗試歷程, 其長度即嘗試次數)。
+//
 // 【meta保留鍵】「剔除自用鍵後原樣轉傳」令條目即調校點, 但呼叫端放進條目/opt的任何
 //   自有欄位都會被靜默轉傳——保留meta一鍵保證永不轉傳, 呼叫端要掛分類/標籤/註記
 //   一律放meta, 與轉傳機制永久絕緣(工作流各層之規格物件同此約定)。
@@ -276,7 +284,7 @@ function isKeyIndependentFail(r) {
  * @param {Function} [opt.coolDetect=null] 輸入冷卻觸發判定函數(r)=>Boolean，收完整失敗結果物件(含stdout、stderr、code、error)，回傳true即視同冷卻觸發(內建429/TIMEOUT觸發不受影響)——CLI類限流埋在stderr且各家字樣不同，簽章表由觀察到字樣的呼叫端維護，如(r)=>/FreeUsageLimitError/i.test(r.stderr||'')；僅cooldownMs>0時有效，回調拋出例外視同false，預設null
  * @param {Function} [opt.shouldStop=null] 輸入中止判定函數()=>Boolean，於每次嘗試之間檢查，回傳true即停止遞補回報ABORTED(不中止進行中之嘗試)——供呼叫端於成果已無人接收時(如客戶端斷線)止損；經工作流層原樣轉傳，中止後各後續呼叫進門即回ABORTED令整條工作流快速收束；回調拋出例外視同false，預設null
  * @param {*} [opt.meta=undefined] 輸入呼叫端自有資訊，保留鍵保證永不轉傳各轉接器，預設undefined
- * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs>0時出現)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
+ * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs>0時出現)、'group-exhausted'(本組未成交而試完，每次呼叫每組恰一次，位於本組最後一個next-key或skip-group之後、下一組首個try之前；帶keys(有效金鑰數，0代表登入態之單一虛擬金鑰)、attempted(本組實際嘗試數)、by('all-keys'每把皆換鑰失敗，或'skip-group'以與金鑰無關之失敗收尾)、errorTypes(本組各次嘗試之errorType依序)與error(本組最後一次錯誤)；成交、預算用盡、中止之組不發，亦不寫入tried)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null
  * @param {Number} [opt.timeoutMs=300000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000
  * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
  * @param {Boolean} [opt.acceptTruncated=false] 輸入是否接受REST文字類轉接器回報之截斷內容布林值(原樣轉傳轉接器)，1.0.37起截斷於validate之前判失敗，validate內含搶救策略者須給true，預設false
@@ -428,6 +436,7 @@ async function dispatchAiFallback(prompt, opt = {}) {
         //組內逐把嘗試, 每把至多一次, 全敗即組盡遞補下一組
         let nAttempts = (nk > 0) ? nk : 1
         let skipGroup = false
+        let groupStart = tried.length //本組於tried之起點, 供組盡事件取本組各次嘗試
         for (let a = 0; a < nAttempts && !skipGroup; a++) {
 
             //中止檢查(嘗試邊界): 成果已無人接收時止損, 不中止進行中之嘗試(見檔頭【中止】)
@@ -519,6 +528,20 @@ async function dispatchAiFallback(prompt, opt = {}) {
             }
 
         }
+
+        //組盡: 走到這裡即本組未成交且已試完(成交、預算用盡、中止皆於迴圈內回傳), 每次呼叫每組恰發一次(見檔頭【組盡事件】)
+        let tg = tried.slice(groupStart)
+        emit({
+            type: 'group-exhausted',
+            providerId: id,
+            keyIndex: null,
+            keyId: id,
+            keys: nk, //有效金鑰數(同上方濾法), 0代表登入態之單一虛擬金鑰
+            attempted: tg.length, //本組實際送出之嘗試數
+            by: skipGroup ? 'skip-group' : 'all-keys', //以與金鑰無關之失敗收尾, 或每把皆換鑰失敗
+            errorTypes: tg.map((t) => t.errorType), //本組各次嘗試之errorType, 依嘗試順序
+            error: get(lastResult, 'error', ''), //本組最後一次嘗試之錯誤
+        })
     }
 
     //全數失敗, 回傳最後一筆失敗結果(含其errorType)與完整歷程

package/src/dispatchCodex.mjs

@@ -54,7 +54,7 @@ let OWN_KEYS = ['exe', 'model', 'sandbox', 'extraArgs', 'input']
  * @param {String} prompt 輸入提示詞字串，一律以stdin傳入子進程
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.exe='codex'] 輸入codex執行檔名稱或絕對路徑字串，給予名稱時由execCli自系統PATH解析，預設'codex'
- * @param {String} [opt.model=''] 輸入模型ID字串，例如'gpt-5.6-luna'、'gpt-6-sol'，預設''代表不帶`-m`旗標
+ * @param {String} [opt.model=''] 輸入模型ID字串，例如'gpt-5.6-luna'、'gpt-6.1-sol'，預設''代表不帶`-m`旗標(此時由CLI依config.toml之model或官方推薦預設決定)
  * @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=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000

package/src/providers.mjs

@@ -194,6 +194,26 @@ let OC_READONLY = { edit: 'deny', bash: 'ask' }
 let CLAUDE_READONLY = ['--tools', 'Read,Glob,Grep', '--strict-mcp-config']
 
 
+//各條目之思考強度(單一來源, 2026-09-30使用者指示一律high): 各家參數不同, 條目引用下列常數而不手寫。
+//  claude   --effort(low/medium/high/xhigh/max): 未給時-p實測為medium(Claude Code 2.1.285, session紀錄之effort欄)。
+//  codex    --config model_reasoning_effort: 未給時沿用執行機之~/.codex/config.toml(本機為high), 再無則為模型預設
+//           (app-server model/list之defaultReasoningEffort, gpt-6.1-sol為low)——明給令條目不隨安裝機之設定而變;
+//           同日實測--config覆寫優先於config.toml(給low時session記為low)。
+//  opencode --variant: 僅部分模型有檔位, 以`opencode models <provider> --verbose`之variants查(同日opencode 1.18.33:
+//           muse-spark-1.2/1.3與space-bunny有high; big-pickle、mimo無檔位; agnes-ai、poolside為自訂provider亦無),
+//           無檔位之條目不帶。同日實測space-bunny之variant low/high推理token為18/71, opencode.db之訊息記錄variant。
+//  REST     body.reasoning_effort: 僅zen:space-bunny-free帶——opencode模型目錄宣告其high檔即{reasoningEffort:'high'}
+//           (@ai-sdk/openai-compatible轉為此欄), 與oc:版同參數。agnes接受此欄但同日兩題各兩輪推理token無一致差異,
+//           視為未生效故不帶(其預設即會思考, usage可見推理token)。poolside之思考為開關(chat_template_kwargs.enable_thinking)
+//           而非檔位, 同日由關改開(見該條); jev(systemone)為決策模型無此概念。
+//  agy      以模型slug之檔位表示(gemini-3.8-flash-high), 不另帶--effort(與slug檔位不一致時agy報conflicts)。
+//  注意: 條目覆寫extraArgs時須一併帶上本常數(與防寫常數), 否則回退各CLI之預設強度。
+let EFFORT = 'high'
+let CLAUDE_EFFORT = ['--effort', EFFORT]
+let CODEX_EFFORT = ['--config', `model_reasoning_effort="${EFFORT}"`]
+let OC_EFFORT = ['--variant', EFFORT]
+
+
 let providers = [
 
     //cli版
@@ -246,7 +266,10 @@ let providers = [
         config: {
             permission: OC_READONLY,
         },
-        //2026-09-03實測8.1s(opencode CLI 1.18.27); 同模型另有zen:REST版, 額度池與故障域各自獨立
+        extraArgs: OC_EFFORT,
+        //2026-09-03實測8.1s(opencode CLI 1.18.27); 同模型另有zen:REST版, 額度池與故障域各自獨立。
+        //2026-09-30(opencode 1.18.33)連3次2.0s即失敗: 伺服器回UnknownError「Unexpected server error」, 帶不帶--variant皆同,
+        //同時1.3正常——屬上游暫時故障, 依套件哲學保留不移除(恢復之偵測即下次再打)
     },
     {
         id: 'oc:opencode/muse-spark-1.3-contributor-free',
@@ -257,6 +280,7 @@ let providers = [
         config: {
             permission: OC_READONLY,
         },
+        extraArgs: OC_EFFORT,
         //2026-09-03實測6.1s(opencode CLI 1.18.27)。註: 同日同模型走zen REST回HTTP 500,
         //僅CLI路徑可用——同模型不同路徑屬不同供應商之實例(故未增zen:對應條目)
     },
@@ -294,6 +318,7 @@ let providers = [
         config: {
             permission: OC_READONLY,
         },
+        extraArgs: OC_EFFORT,
         //2026-09-24新增(官方v1/v2文件、CLI清單與/zen/v1/models皆有; 〈Pricing〉全Free, 限時免費之stealth推理模型,
         //context 1M、可輸入圖片與影片)。匿名CLI實測(opencode 1.18.32): 簡答8.1s、推理題34.9s答對、
         //read工具讀相對路徑13.2s正確、要求寫檔被OC_READONLY擋下未落地。官方〈Privacy〉載明其供應商零保留
@@ -312,16 +337,18 @@ let providers = [
     },
     //claude/codex各兩條: 在前者為預設(全取遞補時先試), 在後者為較強之新模型(2026-09-23使用者指示)
     {
-        id: 'claude:sonnet',
+        id: 'claude:sonnet', //當前為5.5
         model: 'sonnet',
         kind: 'claude',
-        extraArgs: CLAUDE_READONLY,
+        extraArgs: [...CLAUDE_READONLY, ...CLAUDE_EFFORT],
+        //官方2026-09-28發布Sonnet 5.5; 2026-09-30於Claude Code 2.1.285以modelUsage實測別名已指向claude-sonnet-5-5。
+        //用別名則新版Sonnet發布即自動切換(與opus-5.5寫全名之取捨見該條)
     },
     {
         id: 'claude:opus-5.5',
         model: 'claude-opus-5-5',
         kind: 'claude',
-        extraArgs: CLAUDE_READONLY,
+        extraArgs: [...CLAUDE_READONLY, ...CLAUDE_EFFORT],
         //2026-09-23新增Opus 5.5(官方2026-09-22發布, API id claude-opus-5-5): Claude Code 2.1.280實測4.9~5.1s,
         //以--output-format json之modelUsage確認實際服務模型為claude-opus-5-5。
         //刻意寫全名而非別名'opus': 別名當下雖同樣指向5.5(同日實測), 但日後新版Opus發布時會無聲切換,
@@ -332,16 +359,20 @@ let providers = [
         model: 'gpt-5.6-luna',
         kind: 'codex',
         sandbox: 'read-only',
+        extraArgs: CODEX_EFFORT,
     },
     {
-        id: 'codex:gpt-6-sol',
-        model: 'gpt-6-sol',
+        id: 'codex:gpt-6.1-sol',
+        model: 'gpt-6.1-sol',
         kind: 'codex',
         sandbox: 'read-only',
-        //2026-09-23新增GPT-6 Sol(官方定位複雜程式與agentic工作): Codex CLI 0.156.1(穩定版)實測6.3~6.9s,
-        //該帳號之app-server model/list已列gpt-6-sol/gpt-6-luna/gpt-6-astra; 金絲雀實測唯讀沙箱擋下寫檔。
-        //openai/codex issue #47420稱「僅alpha版可用」係0.154.0使用者之回報, 0.156.1已不成立;
-        //若本機為較舊之codex而清單無此模型, 先執行`codex update`。推理強度沿用使用者config(實測為high)
+        extraArgs: CODEX_EFFORT,
+        //2026-09-30以GPT-6.1 Sol取代GPT-6 Sol(使用者指示; 前者2026-09-23收錄): 官方2026-09-29發布, Codex對Plus/Pro等開放;
+        //Codex CLI 0.159.2之app-server model/list已列且為該帳號預設模型(isDefault), 實測8.6s, session紀錄確認服務模型為gpt-6.1-sol;
+        //金絲雀實測唯讀沙箱擋下寫檔(回報沙箱唯讀、檔案未落地)。
+        //寫全名而非別名: Codex無「最新版sol」之別名——官方Models文件未載別名, model/list各筆亦無別名欄位且upgrade為null;
+        //不給model則改用執行機config.toml之model(本機實測不帶-m時跑gpt-5.6-sol)或官方推薦預設(不限sol系), 故新版發布時手動換。
+        //若本機為較舊之codex而清單無此模型, 先執行`codex update`
     },
 
     //api版
@@ -385,9 +416,13 @@ let providers = [
         envVar: 'POOLSIDE_KEYS',
         baseURL: 'https://inference.poolside.ai/v1',
         body: {
-            max_tokens: 8192,
-            chat_template_kwargs: { enable_thinking: false },
+            max_tokens: 32768,
+            chat_template_kwargs: { enable_thinking: true },
         },
+        //思考為開關而非檔位: 2026-09-30依「思考強度一律high」由false改true(原false無紀錄說明)。同日實測(第1把金鑰):
+        //不帶此欄即為開啟(推理829、27.6s); false時推理0、3.8s但一題正整數邊長矩形題答錯(12,3,6), true時答對(3,3,3、20.7s)。
+        //reasoning_effort於false時HTTP 400、true時接受但推理token無一致差異, 故不帶。開思考後推理token計入max_tokens,
+        //依README「推理模型請放寬body.max_tokens」由8192改32768(同日實測接受, 列10縣市題用538)
     },
     {
         id: 'zen:space-bunny-free',
@@ -395,11 +430,12 @@ let providers = [
         kind: 'api-openai-compat',
         envVar: 'OPENCODE_KEYS',
         baseURL: 'https://opencode.ai/zen/v1',
-        body: { max_tokens: 32768 },
+        body: { max_tokens: 32768, reasoning_effort: EFFORT },
         //2026-09-24新增: 對話型免費模型中少數REST可通者(免費層閘門未套用, 見檔頭; 例外可能隨時收回)——
         //匿名1.9s、第1把金鑰2.0s皆200。max_tokens刻意不用zen條目慣例之8192: 此為推理模型, 推理token計入max_tokens,
         //同日實測列10縣市一題即用5222(推理4849+正文373), 8192易截斷(轉接器遇截斷預設判失敗換家, 見checkTruncation.mjs);
         //長文(README前8000字)摘要成JSON一題用3385(推理3045), 三題finish_reason皆stop, 故取32768留約6倍餘裕。
+        //2026-09-30加reasoning_effort(思考強度見EFFORT常數): 同日帶high列10縣市題用277(推理89)、6.6s、finish_reason為stop
     },
 
 ]

package/test/tools/fakeServerForApiTest.mjs

@@ -25,6 +25,7 @@ import zlib from 'zlib'
 //                    Content-Encoding(模擬2026-09-24使用端回報之伺服器: 壓縮卻漏標, Node fetch因而不解壓)
 //   TRUNC_ROUTES   — 200, 依表回指定之finish_reason與content(截斷處理之規格測試用, 見下方常數)
 //   garbage-200    — 200, Content-Type為application/json但本體為8個非JSON位元組(模擬壓縮或損壞本體)
+//   slow-401       — 延遲300ms後回401(與金鑰有關之失敗但耗時, 供組內預算用盡之情境)
 //   其他           — 404
 // 【responses之行為路由(依body.model)】
 //   echo           — 200, message之output_text為JSON字串{ auth, body }
@@ -367,6 +368,12 @@ async function fakeServerForApiTest() {
             else if (model === 'br-noheader') {
                 sendUndeclaredBr({ choices: [{ finish_reason: 'stop', message: { role: 'assistant', content: '完成' } }] })
             }
+            else if (model === 'slow-401') {
+                setTimeout(() => {
+                    res.writeHead(401, { 'Content-Type': 'application/json' })
+                    res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                }, 300)
+            }
             else if (TRUNC_ROUTES[model] !== undefined) {
                 let t = TRUNC_ROUTES[model]
                 res.writeHead(200, { 'Content-Type': 'application/json' })

package/test/unit-dispatchAiFallback.test.mjs

@@ -1,6 +1,7 @@
 import assert from 'assert'
 import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
 import createFakeCli from './tools/fakeCliForTest.mjs'
+import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
 
 
 //assertKey, 由假CLI回聲之OPENCODE_AUTH_CONTENT解出本次注入之金鑰
@@ -18,15 +19,20 @@ let getInjectedKey = (stdout) => {
 describe('dispatchAiFallback', function() {
 
     let fake = null
+    let svr = null
 
-    before(function() {
+    before(async function() {
         fake = createFakeCli('fake-fallback')
+        svr = await fakeServerForApiTest() //組邊界事件之情境需REST假伺服器(401/截斷/延遲401)
     })
 
-    after(function() {
+    after(async function() {
         if (fake) {
             fake.clean()
         }
+        if (svr) {
+            await svr.close()
+        }
     })
 
     it('prompt非有效字串時回傳錯誤結果物件且tried為空', async function() {
@@ -676,4 +682,241 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('group-exhausted: 組內每把皆換鑰失敗, 於最後一個next-key之後恰發一次(by為all-keys), tried不增項', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-all', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-a', 'sk-bad-b'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.providerId, x.keyIndex, x.keyId, x.keys, x.attempted, x.by, x.errorTypes]),
+            ge[0].error !== '' && ge[0].error === t.tried[1].error, //本組最後一次嘗試之錯誤
+            t.tried.map((x) => x.outcome), //組邊界只發事件, 不寫入逐次嘗試歷程
+        ]
+        let rr = [
+            false,
+            [['try', 'ge-all#0'], ['next-key', 'ge-all#0'], ['try', 'ge-all#1'], ['next-key', 'ge-all#1'], ['group-exhausted', 'ge-all']],
+            [['ge-all', null, 'ge-all', 2, 2, 'all-keys', ['http', 'http']]],
+            true,
+            ['next-key', 'next-key'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 換鑰後遇與金鑰無關之失敗(截斷)整組跳過, by為skip-group', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-skip2', kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-bad-1', 'sk-good-2'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            false,
+            [['try', 'ge-skip2#0'], ['next-key', 'ge-skip2#0'], ['try', 'ge-skip2#1'], ['skip-group', 'ge-skip2#1'], ['group-exhausted', 'ge-skip2']],
+            [[2, 2, 'skip-group', ['http', 'incomplete']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 首把即整組跳過時attempted為1, keys為濾除無效值後之有效金鑰數', async function() {
+        let evs = []
+        await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-skip1', kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-good-1', '', null, 'sk-good-2'] }],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            evs.map((x) => [x.type, x.keyId]),
+            ge.map((x) => [x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            [['try', 'ge-skip1#0'], ['skip-group', 'ge-skip1#0'], ['group-exhausted', 'ge-skip1']],
+            [[2, 1, 'skip-group', ['incomplete']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 組內有任一把成交則不發(含換鑰後成交)', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-ok', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-good-2'] }],
+            onEvent: (ev) => evs.push([ev.type, ev.keyId]),
+        })
+        let r = [t.ok, evs]
+        let rr = [true, [['try', 'ge-ok#0'], ['next-key', 'ge-ok#0'], ['try', 'ge-ok#1'], ['ok', 'ge-ok#1']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 組內預算用盡或中止(未試完)者不發, 之前已試完之組照發', async function() {
+        //預算用盡: 第1把延遲300ms後401, 輪到第2把時剩餘預算不足minAttemptMs → budget-out, 本組未試完
+        let evs1 = []
+        let t1 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-bud', kind: 'api-openai-compat', baseURL: svr.url, model: 'slow-401', keys: ['sk-x-1', 'sk-x-2'] }],
+            budgetMs: 1000,
+            minAttemptMs: 800,
+            onEvent: (ev) => evs1.push([ev.type, ev.keyId]),
+        })
+        //中止: 輪到第2把時shouldStop轉true → aborted, 本組未試完
+        let n2 = 0
+        let evs2 = []
+        let t2 = await dispatchAiFallback('abc', {
+            providers: [{ id: 'ge-abt', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-bad-2'] }],
+            shouldStop: () => n2++ >= 1,
+            onEvent: (ev) => evs2.push([ev.type, ev.keyId]),
+        })
+        //跨組: 第1組已試完(照發), 第2組首把之前中止(不發)
+        let n3 = 0
+        let evs3 = []
+        let t3 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-abt-a', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1'] },
+                { id: 'ge-abt-b', kind: 'claude', exe: fake.exe },
+            ],
+            shouldStop: () => n3++ >= 1,
+            onEvent: (ev) => evs3.push([ev.type, ev.keyId]),
+        })
+        //跨組(預算): 第1組已試完(照發), 第2組首把之前剩餘預算不足 → budget-out(不發)
+        let evs4 = []
+        let t4 = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-bud-a', kind: 'api-openai-compat', baseURL: svr.url, model: 'slow-401', keys: ['sk-q-1'] },
+                { id: 'ge-bud-b', kind: 'claude', exe: fake.exe },
+            ],
+            budgetMs: 1000,
+            minAttemptMs: 800,
+            onEvent: (ev) => evs4.push([ev.type, ev.keyId]),
+        })
+        let r = [[t1.errorType, evs1], [t2.errorType, evs2], [t3.errorType, evs3], [t4.errorType, evs4]]
+        let rr = [
+            ['budget', [['try', 'ge-bud#0'], ['next-key', 'ge-bud#0'], ['budget-out', 'ge-bud#1']]],
+            ['aborted', [['try', 'ge-abt#0'], ['next-key', 'ge-abt#0'], ['aborted', 'ge-abt']]],
+            ['aborted', [['try', 'ge-abt-a#0'], ['next-key', 'ge-abt-a#0'], ['group-exhausted', 'ge-abt-a'], ['aborted', 'ge-abt-b']]],
+            ['budget', [['try', 'ge-bud-a#0'], ['next-key', 'ge-bud-a#0'], ['group-exhausted', 'ge-bud-a'], ['budget-out', 'ge-bud-b']]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 無keys或單把金鑰之條目失敗亦恰發一次(keys為0或1, attempted為1), 回調拋出例外不影響遞補', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-nokey-a', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1'] }, //換鑰型失敗(exec)
+                { id: 'ge-nokey-b', kind: 'claude', exe: fake.exe, validate: 'min:100000' }, //與金鑰無關之失敗(validation)
+                { id: 'ge-onekey', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1'] }, //單把金鑰換鑰型失敗(http)
+                { id: 'ge-badkind', kind: 'no-such-kind', keys: ['k-1', 'k-2'] }, //kind無效, 首把即整組跳過(params)
+                { id: 'ge-nokey-ok', kind: 'claude', exe: fake.exe },
+            ],
+            onEvent: (ev) => {
+                evs.push(ev)
+                throw new Error('callback error should not break the loop')
+            },
+        })
+        let ge = evs.filter((x) => x.type === 'group-exhausted')
+        let r = [
+            t.ok,
+            t.providerId,
+            ge.map((x) => [x.providerId, x.keyIndex, x.keyId, x.keys, x.attempted, x.by, x.errorTypes]),
+        ]
+        let rr = [
+            true,
+            'ge-nokey-ok',
+            [
+                ['ge-nokey-a', null, 'ge-nokey-a', 0, 1, 'all-keys', ['exec']],
+                ['ge-nokey-b', null, 'ge-nokey-b', 0, 1, 'skip-group', ['validation']],
+                ['ge-onekey', null, 'ge-onekey', 1, 1, 'all-keys', ['http']],
+                ['ge-badkind', null, 'ge-badkind', 2, 1, 'skip-group', ['params']],
+            ],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 多組鏈中每個試完之組各發一次, 皆位於下一組首個try之前(與cooled並存時殿後)', async function() {
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'ge-m1', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-bad-1', 'sk-bad-2'] },
+                { id: 'ge-m2', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-sleep=9000'], timeoutMs: 500 }, //逾時 → cooled與skip-group
+                { id: 'ge-m3', kind: 'claude', exe: fake.exe },
+            ],
+            store,
+            cooldownMs: 300000,
+            onEvent: (ev) => evs.push([ev.type, ev.keyId]),
+        })
+        let r = [t.ok, t.providerId, evs]
+        let rr = [
+            true,
+            'ge-m3',
+            [
+                ['try', 'ge-m1#0'], ['next-key', 'ge-m1#0'], ['try', 'ge-m1#1'], ['next-key', 'ge-m1#1'], ['group-exhausted', 'ge-m1'],
+                ['try', 'ge-m2'], ['cooled', 'ge-m2'], ['skip-group', 'ge-m2'], ['group-exhausted', 'ge-m2'],
+                ['try', 'ge-m3'], ['ok', 'ge-m3'],
+            ],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('group-exhausted: 並行呼叫共用onEvent與store且跨越一次成交時, 事件數恰等於試完之呼叫數', async function() {
+        //以金鑰數與逐把失敗次數重建「整組全敗」時, 並行跨越成交會多計或少計(游標只在成交時推進, 各呼叫起點不同);
+        //本事件由各呼叫自身之組迴圈發出, 不受並行交錯影響(對應安裝方報告之多計/少計情境)
+        let stored = { cursors: {}, cooling: {} }
+        let store = {
+            get: () => stored,
+            set: (s) => {
+                stored = s
+            }
+        }
+        let count = (evs) => evs.filter((x) => x === 'group-exhausted').length
+        //情境一(多計): X與Y同時自游標0起跑, X首把立即成交(游標推進至1), Y兩把皆於成交之後401; 其後Z自新游標1起跑兩把皆敗
+        let base1 = { id: 'ge-par1', kind: 'api-openai-compat', baseURL: svr.url }
+        let evs1 = []
+        let on1 = (ev) => evs1.push(ev.type)
+        let [tx, ty] = await Promise.all([
+            dispatchAiFallback('abc', { providers: [{ ...base1, model: 'echo', keys: ['sk-x-0', 'sk-x-1'] }], store, onEvent: on1 }),
+            dispatchAiFallback('abc', { providers: [{ ...base1, model: 'slow-401', keys: ['sk-y-0', 'sk-y-1'] }], store, onEvent: on1 }),
+        ])
+        let tz = await dispatchAiFallback('abc', { providers: [{ ...base1, model: 'slow-401', keys: ['sk-z-0', 'sk-z-1'] }], store, onEvent: on1 })
+        //情境二(少計): W首把立即401(成交之前), V首把成交, W次把延遲300ms後401(成交之後)
+        let base2 = { id: 'ge-par2', kind: 'api-openai-compat', baseURL: svr.url }
+        let evs2 = []
+        let on2 = (ev) => evs2.push(ev.type)
+        let [tw, tv] = await Promise.all([
+            dispatchAiFallback('abc', { providers: [{ ...base2, model: 'slow-401', keys: ['sk-bad-w-0', 'sk-w-1'] }], store, onEvent: on2 }),
+            dispatchAiFallback('abc', { providers: [{ ...base2, model: 'echo', keys: ['sk-v-0', 'sk-v-1'] }], store, onEvent: on2 }),
+        ])
+        let r = [
+            [tx.ok, ty.ok, tz.ok],
+            ty.tried.map((x) => x.keyId),
+            tz.tried.map((x) => x.keyId),
+            count(evs1),
+            [tw.ok, tv.ok],
+            tw.tried.map((x) => x.keyId),
+            count(evs2),
+        ]
+        let rr = [
+            [true, false, false],
+            ['ge-par1#0', 'ge-par1#1'],
+            ['ge-par1#1', 'ge-par1#0'],
+            2, //Y與Z各一
+            [false, true],
+            ['ge-par2#0', 'ge-par2#1'],
+            1, //W一
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
 })

package/test/unit-providers.test.mjs

@@ -109,4 +109,41 @@ describe('providers', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('思考強度一律high: claude、codex、antigravity條目必明給; opencode之--variant與REST之reasoning_effort帶則須為high, REST不得關閉思考', function() {
+        //未明給時claude回退-p預設(2026-09-30實測medium)、codex回退執行機之config.toml, 結果隨安裝機而異;
+        //opencode之variant與REST之reasoning_effort僅部分模型有(見providers.mjs之EFFORT常數), 故只檢「帶則為high」
+        let flagValues = (a, flag) => {
+            let arr = Array.isArray(a) ? a : []
+            let vs = []
+            for (let i = 0; i < arr.length - 1; i++) {
+                if (arr[i] === flag) {
+                    vs.push(arr[i + 1])
+                }
+            }
+            return vs
+        }
+        let isHigh = (p) => {
+            if (p.kind === 'claude') {
+                let vs = flagValues(p.extraArgs, '--effort')
+                return vs.length === 1 && vs[0] === 'high'
+            }
+            if (p.kind === 'codex') {
+                let vs = flagValues(p.extraArgs, '--config').filter((s) => /^model_reasoning_effort\s*=/.test(s))
+                return vs.length === 1 && vs[0] === 'model_reasoning_effort="high"'
+            }
+            if (p.kind === 'antigravity') {
+                return /-high$/.test(p.model) || p.effort === 'high' //檔位以slug或effort表示
+            }
+            if (p.kind === 'opencode') {
+                return flagValues(p.extraArgs, '--variant').every((v) => v === 'high')
+            }
+            let body = p.body || {}
+            let thinkingOff = !!body.chat_template_kwargs && body.chat_template_kwargs.enable_thinking === false
+            return (body.reasoning_effort === undefined || body.reasoning_effort === 'high') && !thinkingOff
+        }
+        let r = providers.map((p) => [p.id, isHigh(p)])
+        let rr = providers.map((p) => [p.id, true])
+        assert.strict.deepEqual(r, rr)
+    })
+
 })