w-dispatch-ai 1.0.2 → 1.0.4

package/test/unit-WDispatchAi.test.mjs

@@ -4,10 +4,12 @@ import map from 'lodash-es/map.js'
 import wi from '../src/WDispatchAi.mjs'
 import dispatchAi from '../src/dispatchAi.mjs'
 import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
+import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
 import dispatchOpencode from '../src/dispatchOpencode.mjs'
 import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
+import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -18,23 +20,25 @@ describe('WDispatchAi', function() {
             'KINDS',
             'dispatchAi',
             'dispatchAiFallback',
+            'dispatchAiWkf',
             'dispatchOpencode',
             'dispatchClaude',
             'dispatchCodex',
             'dispatchAntigravity',
+            'dispatchApiOpenaiCompat',
         ]
         assert.strict.deepEqual(r, rr)
     })
 
     it('KINDS為可用之供應商種類字串陣列', function() {
         let r = wi.KINDS
-        let rr = ['opencode', 'claude', 'codex', 'antigravity']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']
         assert.strict.deepEqual(r, rr)
     })
 
     it('除KINDS外各鍵值皆為函數', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -42,12 +46,14 @@ describe('WDispatchAi', function() {
         let r = [
             wi.dispatchAi === dispatchAi,
             wi.dispatchAiFallback === dispatchAiFallback,
+            wi.dispatchAiWkf === dispatchAiWkf,
             wi.dispatchOpencode === dispatchOpencode,
             wi.dispatchClaude === dispatchClaude,
             wi.dispatchCodex === dispatchCodex,
             wi.dispatchAntigravity === dispatchAntigravity,
+            wi.dispatchApiOpenaiCompat === dispatchApiOpenaiCompat,
         ]
-        let rr = [true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -57,20 +63,20 @@ describe('WDispatchAi', function() {
             let t = await wi.dispatchAi(kind, '')
             r.push(t.error)
         }
-        let rr = ['prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string']
+        let rr = ['prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string']
         assert.strict.deepEqual(r, rr)
     })
 
     it('可由WDispatchAi呼叫dispatchAi', async function() {
         let t = await wi.dispatchAi('gemini', 'abc')
         let r = [t.ok, t.error]
-        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)']
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat)']
         assert.strict.deepEqual(r, rr)
     })
 
     it('可由WDispatchAi呼叫各轉接器', async function() {
         let r = []
-        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity]) {
+        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex, wi.dispatchAntigravity, wi.dispatchApiOpenaiCompat]) {
             let t = await fn('')
             r.push([t.ok, t.error])
         }
@@ -79,6 +85,7 @@ describe('WDispatchAi', function() {
             [false, 'prompt must be a non-empty string'],
             [false, 'prompt must be a non-empty string'],
             [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
         ]
         assert.strict.deepEqual(r, rr)
     })

package/test/unit-adapters.test.mjs

@@ -6,19 +6,20 @@ import dispatchOpencode from '../src/dispatchOpencode.mjs'
 import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
+import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 
 
 describe('adapters', function() {
 
     it('對照表鍵名即為可用之供應商種類', function() {
         let r = keys(adapters)
-        let rr = ['opencode', 'claude', 'codex', 'antigravity']
+        let rr = ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']
         assert.strict.deepEqual(r, rr)
     })
 
     it('各鍵值皆為函數', function() {
         let r = map(keys(adapters), (k) => typeof adapters[k])
-        let rr = ['function', 'function', 'function', 'function']
+        let rr = ['function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -28,8 +29,9 @@ describe('adapters', function() {
             adapters.claude === dispatchClaude,
             adapters.codex === dispatchCodex,
             adapters.antigravity === dispatchAntigravity,
+            adapters['api-openai-compat'] === dispatchApiOpenaiCompat,
         ]
-        let rr = [true, true, true, true]
+        let rr = [true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-callAiWithFallback.test.mjs

@@ -0,0 +1,146 @@
+import assert from 'assert'
+import callAiWithFallback, { buildChain, NO_SIDE_EFFECT } from '../src/wkf/callAiWithFallback.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('callAiWithFallback', function() {
+
+    let fake = null
+    let providers = null
+
+    before(function() {
+        fake = createFakeCli('fake-wkf-call')
+        providers = {
+            'p-claude': { kind: 'claude', exe: fake.exe, model: 'sonnet' },
+            'p-codex': { kind: 'codex', exe: fake.exe, model: 'gpt-5.6-luna' },
+            'p-oc': { kind: 'opencode', exe: fake.exe, model: 'opencode/free', provider: 'opencode', keys: ['sk-c0', 'sk-c1'] },
+            'p-dead': { kind: 'claude', exe: fake.exe, model: 'sonnet', extraArgs: ['--fake-exit=1'] },
+            'p-noexe': { kind: 'claude', exe: 'wkf-no-such-cli' },
+        }
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('buildChain以名稱展開條目並回報查無定義之名稱', function() {
+        let { chain, missing } = buildChain(providers, { use: 'p-claude', fallback: ['p-codex', 'p-typo'] })
+        let r = [chain.map((x) => x.id), missing]
+        let rr = [['p-claude', 'p-codex'], ['p-typo']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt非有效字串時回傳錯誤結果物件', async function() {
+        let t = await callAiWithFallback('', { providers, spec: { use: 'p-claude' } })
+        let r = [t.ok, t.json, t.error, t.tried]
+        let rr = [false, null, 'prompt must be a non-empty string', []]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('providers或spec無效時回傳錯誤結果物件', async function() {
+        let r = []
+        for (let [p, s] of [[null, { use: 'x' }], [providers, null], [providers, 'abc']]) {
+            let t = await callAiWithFallback('abc', { providers: p, spec: s })
+            r.push([t.ok, t.error.indexOf('no valid provider') === 0])
+        }
+        let rr = [[false, true], [false, true], [false, true]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('名稱查無定義時fail fast回報, 不靜默略過', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude', fallback: ['p-typo1', 'p-codex', 'p-typo2'] } })
+        let r = [t.ok, t.error]
+        let rr = [false, 'unknown provider name(s): p-typo1, p-typo2']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('成功時回傳解析後json與名稱式providerId', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: '' })
+        let r = [t.ok, t.providerId, t.keyIndex, t.keyId, t.json.args, t.json.stdin]
+        let rr = [true, 'p-claude', null, 'p-claude', ['-p', '--dangerously-skip-permissions', '--model', 'sonnet'], 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('預設掛防寫檔前綴, promptPrefix傳空字串可關閉, 自訂前綴可覆寫', async function() {
+        let t1 = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' } })
+        let t2 = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: '' })
+        let t3 = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, promptPrefix: 'PREFIX:' })
+        let r = [t1.json.stdin, t2.json.stdin, t3.json.stdin]
+        let rr = [NO_SIDE_EFFECT + 'abc', 'abc', 'PREFIX:abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('check未過視為該家失敗, 遞補層自動換下一家', async function() {
+        //check要求args含opencode之run旗標 → p-claude不合(換家) → p-oc合
+        let t = await callAiWithFallback('abc', {
+            providers,
+            spec: { use: 'p-claude', fallback: ['p-oc'] },
+            check: (j) => j.args[0] === 'run',
+            promptPrefix: '',
+        })
+        let r = [t.ok, t.providerId, t.keyIndex, t.keyId, t.tried.map((x) => [x.providerId, x.outcome])]
+        let rr = [true, 'p-oc', 0, 'p-oc#0', [['p-claude', 'skip-group'], ['p-oc', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('CLI失敗(exit 1)時遞補至下一家', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-dead', fallback: ['p-codex'] }, promptPrefix: '' })
+        let r = [t.ok, t.providerId, t.tried.map((x) => [x.providerId, x.outcome])]
+        let rr = [true, 'p-codex', [['p-dead', 'next-key'], ['p-codex', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('全數失敗時回傳error與完整tried', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-dead', fallback: ['p-noexe'] }, promptPrefix: '' })
+        let r = [t.ok, t.json, t.error !== '', t.tried.length]
+        let rr = [false, null, true, 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('rawText模式不解析JSON, json欄為修剪後文字', async function() {
+        let t = await callAiWithFallback('abc', { providers, spec: { use: 'p-claude' }, rawText: true, promptPrefix: '' })
+        let r = [t.ok, typeof t.json, JSON.parse(t.json).stdin]
+        let rr = [true, 'string', 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('rawText模式check收文字', async function() {
+        let seen = []
+        let t = await callAiWithFallback('abc', {
+            providers,
+            spec: { use: 'p-claude' },
+            rawText: true,
+            check: (s) => {
+                seen.push(typeof s)
+                return s.includes('"stdin"')
+            },
+            promptPrefix: '',
+        })
+        let r = [t.ok, seen.includes('string')]
+        let rr = [true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('自訂parse可覆寫預設解析器', async function() {
+        let t = await callAiWithFallback('abc', {
+            providers,
+            spec: { use: 'p-claude' },
+            parse: (stdout) => ({ wrapped: JSON.parse(stdout).stdin }),
+            promptPrefix: '',
+        })
+        let r = t.json
+        let rr = { wrapped: 'abc' }
+        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)
+        let r = [t.ok, t.providerId, typeof t.keyIndex, t.keyId.indexOf('p-oc#') === 0, ['sk-c0', 'sk-c1'].includes(auth.opencode.key)]
+        let rr = [true, 'p-oc', 'number', true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchAi.test.mjs

@@ -20,7 +20,7 @@ describe('dispatchAi', function() {
     it('未知kind時回傳錯誤結果物件且不reject', async function() {
         let t = await dispatchAi('gemini', 'abc')
         let r = [t.ok, t.error, t.attempts]
-        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)', 0]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat)', 0]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchAiWkf.test.mjs

@@ -0,0 +1,118 @@
+import assert from 'assert'
+import keys from 'lodash-es/keys.js'
+import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import { NO_SIDE_EFFECT } from '../src/wkf/callAiWithFallback.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('dispatchAiWkf', function() {
+
+    let fake = null
+    let providers = null
+
+    before(function() {
+        fake = createFakeCli('fake-wkf-factory')
+        providers = {
+            'p-a': { kind: 'claude', exe: fake.exe, model: 'sonnet' },
+            'p-b': { kind: 'codex', exe: fake.exe, model: 'gpt-5.6-luna' },
+            'p-int': { kind: 'opencode', exe: fake.exe, model: 'opencode/free' },
+        }
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('providers無效時throw(設定錯誤於啟動期即失敗)', function() {
+        let r = []
+        for (let providers of [undefined, null, 'abc', 123, []]) {
+            try {
+                dispatchAiWkf({ providers })
+                r.push('no-throw')
+            }
+            catch (err) {
+                r.push(err.message.indexOf('dispatchAiWkf:') === 0)
+            }
+        }
+        let rr = [true, true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('回傳綁定版API物件', function() {
+        let wkf = dispatchAiWkf({ providers })
+        let r = [
+            keys(wkf),
+            wkf.providers === providers,
+            typeof wkf.callAi,
+            typeof wkf.runFanout,
+            typeof wkf.runRolePipeline,
+            typeof wkf.runFanoutPipeline,
+        ]
+        let rr = [
+            ['providers', 'callAi', 'runFanout', 'runRolePipeline', 'runFanoutPipeline'],
+            true,
+            'function',
+            'function',
+            'function',
+            'function',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('callAi綁定providers, 以名稱宣告即可呼叫', async function() {
+        let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: '' } })
+        let t = await wkf.callAi('abc', { spec: { use: 'p-a' } })
+        let r = [t.ok, t.providerId, t.json.stdin]
+        let rr = [true, 'p-a', 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('defaults為共用預設且呼叫時可逐項覆寫', async function() {
+        let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: 'DEF:' } })
+        let t1 = await wkf.callAi('abc', { spec: { use: 'p-a' } })
+        let t2 = await wkf.callAi('abc', { spec: { use: 'p-a' }, promptPrefix: 'OVR:' })
+        let r = [t1.json.stdin, t2.json.stdin]
+        let rr = ['DEF:abc', 'OVR:abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未給defaults時預設掛防寫檔前綴', async function() {
+        let wkf = dispatchAiWkf({ providers })
+        let t = await wkf.callAi('abc', { spec: { use: 'p-a' } })
+        let r = t.json.stdin
+        let rr = NO_SIDE_EFFECT + 'abc'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('runFanout綁定providers與defaults(defaults併入callOpt)', async function() {
+        let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: '' } })
+        let t = await wkf.runFanout({
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int' },
+        })
+        let r = [t.ok, t.integrated, t.result.stdin.includes('【候選 1】')]
+        let rr = [true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('runRolePipeline與runFanoutPipeline皆已綁定可用', async function() {
+        let wkf = dispatchAiWkf({ providers, defaults: { promptPrefix: '' } })
+        let t1 = await wkf.runRolePipeline({
+            input: 'x',
+            stages: [{ id: 's1', use: 'p-a', prompt: (ctx) => `on ${ctx.input}` }],
+        })
+        let t2 = await wkf.runFanoutPipeline({
+            task: 'abc',
+            agents: [{ use: 'p-a' }, { use: 'p-b' }],
+            integrate: { use: 'p-int' },
+            stages: [{ id: 's1', use: 'p-a', prompt: () => 'y' }],
+        })
+        let r = [t1.ok, t1.results.s1.stdin, t2.ok, t2.B.order]
+        let rr = [true, 'on x', true, ['s1']]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -0,0 +1,264 @@
+import assert from 'assert'
+import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
+import dispatchAi from '../src/dispatchAi.mjs'
+import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
+import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
+
+
+describe('dispatchApiOpenaiCompat', function() {
+
+    let svr = null
+
+    before(async function() {
+        svr = await fakeServerForApiTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('prompt非有效字串時回傳錯誤結果物件且不reject', async function() {
+        let r = []
+        for (let prompt of [null, undefined, '', 123, {}, []]) {
+            let t = await dispatchApiOpenaiCompat(prompt)
+            r.push([t.ok, t.error, t.attempts])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+            [false, 'prompt must be a non-empty string', 0],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('baseURL與model必填, 缺一即回傳錯誤結果物件', async function() {
+        let t1 = await dispatchApiOpenaiCompat('abc', { model: 'echo' })
+        let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url })
+        let r = [[t1.ok, t1.error], [t2.ok, t2.error]]
+        let rr = [
+            [false, 'baseURL must be a non-empty string'],
+            [false, 'model must be a non-empty string'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('成功時stdout為回覆內容, 請求含Bearer金鑰與model與user訊息', async function() {
+        let t = await dispatchApiOpenaiCompat('中文prompt\n第二行', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let o = JSON.parse(t.stdout)
+        let r = [
+            t.ok,
+            t.code,
+            t.error,
+            t.attempts,
+            o.auth,
+            o.body.model,
+            o.body.messages,
+        ]
+        let rr = [
+            true,
+            200,
+            '',
+            1,
+            'Bearer sk-good-1',
+            'echo',
+            [{ role: 'user', content: '中文prompt\n第二行' }],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未給key時不帶Authorization標頭', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, model: 'echo' })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.auth]
+        let rr = [true, '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('baseURL尾端斜線自動正規化', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url + '///', key: 'sk-good-1', model: 'echo' })
+        let r = [t.ok, t.code]
+        let rr = [true, 200]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('system置於messages首位, body額外鍵可併入', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', {
+            baseURL: svr.url,
+            key: 'sk-good-1',
+            model: 'echo',
+            system: '你是審計者',
+            body: { temperature: 0.2, max_tokens: 100 },
+        })
+        let o = JSON.parse(t.stdout)
+        let r = [
+            o.body.messages,
+            o.body.temperature,
+            o.body.max_tokens,
+        ]
+        let rr = [
+            [{ role: 'system', content: '你是審計者' }, { role: 'user', content: 'abc' }],
+            0.2,
+            100,
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('無效金鑰回401且不重試(4xx為客戶端錯誤)', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-bad-x', model: 'echo', maxRetries: 3, retryDelayMs: 100 })
+        let r = [t.ok, t.code, t.error, t.attempts, t.stderr.includes('Invalid API key')]
+        let rr = [false, 401, 'HTTP 401', 1, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('429依maxRetries重試後成功', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-flaky1', model: 'flaky-429', maxRetries: 1, retryDelayMs: 100 })
+        let r = [t.ok, t.code, t.attempts, JSON.parse(t.stdout).attempt]
+        let rr = [true, 200, 2, 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('429且maxRetries為0時直接失敗', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-flaky2', model: 'flaky-429' })
+        let r = [t.ok, t.code, t.error, t.attempts]
+        let rr = [false, 429, 'HTTP 429', 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 500回傳失敗且stderr含回應本體', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'err-500' })
+        let r = [t.ok, t.code, t.error, t.stderr.includes('internal error')]
+        let rr = [false, 500, 'HTTP 500', true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('逾時時中止請求且error以TIMEOUT開頭', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'slow', timeoutMs: 1000 })
+        let r = [t.ok, t.code, t.error, t.durationMs < 9000]
+        let rr = [false, null, 'TIMEOUT after 1s', true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('網路層錯誤回傳FETCH_ERROR', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: 'http://127.0.0.1:1/v1', key: 'sk-good-1', model: 'echo', timeoutMs: 3000 })
+        let r = [t.ok, t.code, t.error.indexOf('FETCH_ERROR') === 0]
+        let rr = [false, null, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('回應缺choices時回傳INVALID_RESPONSE', async function() {
+        let r = []
+        for (let model of ['no-choices', 'not-json']) {
+            let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model })
+            r.push([t.ok, t.code, t.error.indexOf('INVALID_RESPONSE') === 0])
+        }
+        let rr = [[false, 200, true], [false, 200, true]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate字串規則與自訂函數皆可用, 失敗回傳OUTPUT_VALIDATION_FAILED', async function() {
+        let t1 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'empty-content', validate: 'nonempty' })
+        let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: 'nonempty,json' })
+        let t3 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: (s) => s.includes('絕不存在的字串') })
+        let r = [
+            [t1.ok, t1.code, t1.error],
+            [t2.ok, t2.error],
+            [t3.ok, t3.error],
+        ]
+        let rr = [
+            [false, 200, 'OUTPUT_VALIDATION_FAILED'],
+            [true, ''],
+            [false, 'OUTPUT_VALIDATION_FAILED'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('模型回tool_calls時明確回報不支援而非靜默成功', async function() {
+        let t = await dispatchApiOpenaiCompat('台北天氣如何', {
+            baseURL: svr.url,
+            key: 'sk-good-1',
+            model: 'tool-calls',
+            body: { tools: [{ type: 'function', function: { name: 'get_weather', parameters: {} } }] },
+        })
+        let r = [
+            t.ok,
+            t.code,
+            t.stdout,
+            t.error.indexOf('TOOL_CALLS_UNSUPPORTED') === 0,
+            t.error.includes('cli kind'),
+            t.stderr.includes('get_weather'), //原始回應保留供除錯
+        ]
+        let rr = [false, 200, '', true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('tool_calls為與金鑰無關之失敗, 於fallback鏈中不逐把空耗而遞補下一組', async function() {
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'g-tool', kind: 'api-openai-compat', baseURL: svr.url, model: 'tool-calls', keys: ['sk-t0', 'sk-t1'] },
+                { id: 'g-text', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-x0'] },
+            ],
+        })
+        let r = [t.ok, t.providerId, t.tried.map((x) => [x.keyId, x.outcome])]
+        let rr = [true, 'g-text', [['g-tool#0', 'next-key'], ['g-tool#1', 'next-key'], ['g-text#0', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可經dispatchAi以kind api-openai-compat分派', async function() {
+        let t = await dispatchAi('api-openai-compat', 'abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.body.model]
+        let rr = [true, 'echo']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可作為dispatchAiFallback條目, 多金鑰輪替(401換下一把)', async function() {
+        let t = await dispatchAiFallback('abc', {
+            providers: [{
+                id: 'g-api',
+                kind: 'api-openai-compat',
+                baseURL: svr.url,
+                model: 'echo',
+                keys: ['sk-bad-r0', 'sk-good-r1'],
+            }],
+        })
+        let o = JSON.parse(t.stdout)
+        let r = [
+            t.ok,
+            t.providerId,
+            t.keyIndex,
+            o.auth,
+            t.tried.map((x) => [x.keyId, x.outcome, x.error || null]),
+        ]
+        let rr = [
+            true,
+            'g-api',
+            1,
+            'Bearer sk-good-r1',
+            [['g-api#0', 'next-key', 'HTTP 401'], ['g-api#1', 'ok', null]],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可作為工作流provider, 回覆JSON經解析與檢核', async function() {
+        let wkf = dispatchAiWkf({
+            providers: {
+                'api-echo': { kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-good-w0'] },
+            },
+            defaults: { promptPrefix: '' },
+        })
+        let t = await wkf.callAi('abc', {
+            spec: { use: 'api-echo' },
+            check: (j) => j.body.model === 'echo',
+        })
+        let r = [t.ok, t.providerId, t.keyId, t.json.auth, t.json.body.messages[0].content]
+        let rr = [true, 'api-echo', 'api-echo#0', 'Bearer sk-good-w0', 'abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})