w-dispatch-ai 1.0.5 → 1.0.7

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-callAiWithFallback.test.mjs

@@ -135,6 +135,21 @@ describe('callAiWithFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('minAttemptMs等fallback層設定可經工作流層原樣轉傳(曾因白名單漏鍵而失效)', async function() {
+        //budgetMs=60000(高於預設門檻20000)+minAttemptMs=600000(遠大於budget):
+        //minAttemptMs有被轉送才會立即budget exhausted; 漏鍵時會照樣執行並成功
+        let t = await callAiWithFallback('abc', {
+            providers,
+            spec: { use: 'p-claude' },
+            promptPrefix: '',
+            budgetMs: 60000,
+            minAttemptMs: 600000,
+        })
+        let r = [t.ok, t.error, t.tried.map((x) => x.outcome)]
+        let rr = [false, 'budget exhausted', ['budget-out']]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('多金鑰條目經由keys輪替且keyId帶索引', async function() {
         let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-oc' }, promptPrefix: '' })
         let auth = JSON.parse(t.json.env.OPENCODE_AUTH_CONTENT)

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-dispatchAiWkf.test.mjs

@@ -86,6 +86,14 @@ describe('dispatchAiWkf', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('defaults之minAttemptMs經callAi生效(README第一層教學之回歸測試)', async function() {
+        let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: '', budgetMs: 60000, minAttemptMs: 600000 } })
+        let t = await wkf.callAi('abc', { spec: { use: 'p-a' } })
+        let r = [t.ok, t.error]
+        let rr = [false, 'budget exhausted']
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('runFanout綁定providers與defaults(defaults併入callOpt)', async function() {
         let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: '' } })
         let t = await wkf.runFanout({

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: {

package/test/unit-runFanout.test.mjs

@@ -156,6 +156,52 @@ describe('runFanout', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('integrate可帶獨立check(終稿判準), 未給則沿用頂層check', async function() {
+        //頂層check放行所有echo物件; integrate.check要求stdin含候選標記(僅整合者符合)
+        let t1 = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int', check: (j) => j.stdin.includes('【候選 1】') },
+            check: (j) => Array.isArray(j.args),
+            callOpt,
+        })
+        //integrate.check不通過時整合失敗, 但候選不受影響(判準不再互相牽制)
+        let t2 = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int', check: () => false },
+            check: (j) => Array.isArray(j.args),
+            callOpt,
+        })
+        let r = [
+            [t1.ok, t1.integrated],
+            [t2.ok, t2.integrated, t2.candidates.length, t2.error.indexOf('integrate failed:') === 0],
+        ]
+        let rr = [
+            [true, true],
+            [false, false, 2, true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('名額規格可帶獨立check覆寫頂層(曾為被靜默覆蓋之死鍵)', async function() {
+        let t = await runFanout({
+            providers,
+            task: 'abc',
+            agents: [
+                { use: 'p-a', check: () => false }, //此名額專屬判準: 必不過
+                { use: 'p-b' }, //沿用頂層(未給即預設放行)
+            ],
+            integrate: { use: 'p-int' },
+            callOpt,
+        })
+        let r = [t.ok, t.integrated, t.agents[0].ok, t.agents[1].ok, t.candidates.length]
+        let rr = [true, false, false, true, 1] //單稿放行(integrated:false)
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('defaultIntegratePrompt嵌入候選數與schema', function() {
         let s = defaultIntegratePrompt([{ a: 1 }, { b: 2 }], { schema: '{"x":"..."}' })
         let r = [s.includes('2 個獨立執行'), s.includes('{"x":"..."}'), s.includes('【候選 2】')]