w-dispatch-ai 1.0.2 → 1.0.3

package/src/wkf/runRolePipeline.mjs

@@ -0,0 +1,123 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isearr from 'wsemi/src/isearr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import callAiWithFallback from './callAiWithFallback.mjs'
+
+
+// runRolePipeline.mjs — RolePipeline工作流: 多角色串行鏈(stage1 → … → stageN)
+//
+// 【結構】各階段可各自指定AI(use)、遞補鏈(fallback)、提示詞(角色與任務)與檢核;
+//   前一階段的成果傳給下一階段、一路傳到最末階段, 其成果即工作流成果。
+//
+// 【提示詞為函數】stage.prompt收ctx = { input, prev, results, index }:
+//   input＝工作流輸入(如原始任務或Fanout的整合稿)、prev＝上一階段成果、
+//   results＝已完成各階段成果(依id查詢, 例如修訂階段要同時引用初稿與審計意見)。
+//
+// 【部分接受】某階段(含遞補全敗)失敗即中止後續, 但已完成階段之成果完整回傳
+//   (failedStage標明斷點), 呼叫端可據此只重跑失敗段而非整條鏈。
+//
+// 【實測依據(2026-08-10評比)】審計類角色鏈曾出現「審計刪過頭」——
+//   修訂／終審提示詞應包含護欄「意見未涉及的內容不可刪除」; 此屬提示詞設計,
+//   本函數不代寫角色提示詞, 由呼叫端(或上層預設模板)自理。
+
+
+//各階段規格自用之鍵, 其餘鍵覆寫該階段之呼叫設定
+let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
+
+
+/**
+ * 執行RolePipeline工作流：多角色串行鏈
+ *
+ * 特點：
+ * 各階段可各自指定use／fallback／prompt／check(含rawText純文字階段)；
+ * 階段成果依序傳遞，最末階段成果即工作流成果；
+ * 失敗即止但已完成成果完整回傳(部分接受、便於接續重跑失敗段)；
+ * 本函數不會reject
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)
+ * @param {*} [opt.input=null] 輸入工作流輸入(原始任務字串或前一工作流之成果物件)，提供給各階段ctx.input，預設null
+ * @param {Array} opt.stages 輸入階段規格陣列，各元素{ id, use, fallback, prompt:(ctx)=>String, check?, rawText?, maxRetries?, timeoutMs? }等
+ * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(最末階段成果)、stages(id對階段完整呼叫結果之物件)、results(id對階段成果之物件)、order(階段id順序陣列)、failedStage(失敗階段id，無失敗為null)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runRolePipeline from './src/wkf/runRolePipeline.mjs'
+ *
+ * let providers = {
+ *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await runRolePipeline({
+ *         providers,
+ *         input: '原始任務',
+ *         stages: [
+ *             { id: 'draft', use: 'sonnet', prompt: (ctx) => `就「${ctx.input}」寫初稿, 只回覆JSON: {"text":"..."}` },
+ *             { id: 'review', use: 'luna', prompt: (ctx) => `審閱並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.prev)}` },
+ *         ],
+ *     })
+ *     console.log(r.ok, r.order, r.failedStage)
+ *     // => true [ 'draft', 'review' ] null
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runRolePipeline(opt = {}) {
+    let t0 = Date.now()
+    let providers = get(opt, 'providers', null)
+    let input = get(opt, 'input', null)
+    let stages = get(opt, 'stages', null)
+    let callOpt = get(opt, 'callOpt', {})
+
+    if (!isearr(stages)) {
+        return { ok: false, result: null, stages: {}, results: {}, order: [], failedStage: null, totalMs: 0, error: 'stages must be a non-empty array' }
+    }
+
+    let results = {} //id → 成果(json或文字)
+    let details = {} //id → 完整呼叫結果
+    let order = []
+    let prev = null
+
+    for (let i = 0; i < stages.length; i++) {
+        let stage = stages[i]
+        let id = isestr(get(stage, 'id', '')) ? stage.id : `stage${i + 1}`
+        order.push(id)
+
+        let promptFn = get(stage, 'prompt', null)
+        if (!isfun(promptFn)) {
+            details[id] = { ok: false, error: `stage[${id}].prompt must be a function` }
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: details[id].error }
+        }
+        let prompt = promptFn({ input, prev, results, index: i })
+        if (!isestr(prompt)) {
+            details[id] = { ok: false, error: `stage[${id}].prompt returned empty` }
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: details[id].error }
+        }
+
+        //overrides, 剔除階段自用鍵後其餘鍵覆寫該階段呼叫設定(rawText、maxRetries、timeoutMs等)
+        let overrides = omit(stage, STAGE_KEYS)
+        let r = await callAiWithFallback(prompt, { ...callOpt, ...overrides, providers, spec: { use: get(stage, 'use', ''), fallback: get(stage, 'fallback', null) }, check: get(stage, 'check', null) })
+        details[id] = r
+        if (!r.ok) {
+            //失敗即止: 已完成階段成果保留於results, 供呼叫端接續重跑
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: `stage[${id}] failed: ${r.error}` }
+        }
+        results[id] = r.json
+        prev = r.json
+    }
+
+    return { ok: true, result: prev, stages: details, results, order, failedStage: null, totalMs: Date.now() - t0, error: '' }
+}
+
+
+export default runRolePipeline

package/test/tools/fakeServerForApiTest.mjs

@@ -0,0 +1,137 @@
+import http from 'http'
+
+
+// fakeServerForApiTest.mjs — 測試用的OpenAI相容假伺服器
+//
+// dispatchApiOpenaiCompat之可觀察行為為「送出什麼HTTP請求、如何處理各種回應」,
+// 故起一個本機http伺服器, 依請求之model與Authorization決定回應行為,
+// 即可對成功/401/429/500/逾時/畸形回應逐條斷言, 而無須真的呼叫外部API。
+//
+// 【行為路由(依body.model)】
+//   echo           — 200, content為JSON字串{ auth, body }, 供斷言請求組成
+//   empty-content  — 200, content為空字串(驗證路徑用)
+//   slow           — 延遲10秒才回應(逾時路徑用)
+//   err-500        — 500
+//   flaky-429      — 同一Authorization首次429, 之後200(重試路徑用)
+//   no-choices     — 200但無choices(畸形回應路徑用)
+//   not-json       — 200但本體非JSON(畸形回應路徑用)
+//   其他           — 404
+// 【金鑰規則】Authorization含'sk-bad'一律401(優先於model路由), 模擬無效金鑰。
+
+
+/**
+ * 啟動測試用OpenAI相容假伺服器
+ *
+ * @returns {Promise} 回傳Promise，resolve回傳物件，內含port(埠號)、url(基底網址字串，等同baseURL)、close(關閉伺服器之async函數)
+ */
+async function fakeServerForApiTest() {
+
+    //flakyCount, 記錄flaky-429各金鑰之呼叫次數
+    let flakyCount = {}
+
+    //sockets, 追蹤連線供close時強制斷開(避免keep-alive令close懸置)
+    let sockets = new Set()
+
+    let server = http.createServer((req, res) => {
+
+        //僅受理POST /v1/chat/completions
+        if (req.method !== 'POST' || !req.url.endsWith('/chat/completions')) {
+            res.writeHead(404, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify({ error: { message: 'not found' } }))
+            return
+        }
+
+        let chunks = []
+        req.on('data', (c) => chunks.push(c))
+        req.on('end', () => {
+
+            let auth = req.headers['authorization'] || ''
+
+            //body非JSON → 400
+            let body = null
+            try {
+                body = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+            }
+            catch {
+                res.writeHead(400, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: 'invalid json body' } }))
+                return
+            }
+
+            //無效金鑰, 模擬Zen之401形態
+            if (auth.includes('sk-bad')) {
+                res.writeHead(401, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                return
+            }
+
+            let model = body.model || ''
+            let ok = (content) => {
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ choices: [{ message: { role: 'assistant', content } }] }))
+            }
+
+            if (model === 'echo') {
+                ok(JSON.stringify({ auth, body }))
+            }
+            else if (model === 'empty-content') {
+                ok('')
+            }
+            else if (model === 'slow') {
+                setTimeout(() => ok('too late'), 10000)
+            }
+            else if (model === 'err-500') {
+                res.writeHead(500, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: 'internal error' } }))
+            }
+            else if (model === 'flaky-429') {
+                flakyCount[auth] = (flakyCount[auth] || 0) + 1
+                if (flakyCount[auth] === 1) {
+                    res.writeHead(429, { 'Content-Type': 'application/json' })
+                    res.end(JSON.stringify({ error: { message: 'rate limited' } }))
+                }
+                else {
+                    ok(JSON.stringify({ attempt: flakyCount[auth] }))
+                }
+            }
+            else if (model === 'no-choices') {
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ id: 'x', object: 'chat.completion' }))
+            }
+            else if (model === 'not-json') {
+                res.writeHead(200, { 'Content-Type': 'text/plain' })
+                res.end('plain text body')
+            }
+            else {
+                res.writeHead(404, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: `model ${model} not found` } }))
+            }
+
+        })
+    })
+
+    server.on('connection', (s) => {
+        sockets.add(s)
+        s.on('close', () => sockets.delete(s))
+    })
+
+    //listen於127.0.0.1動態埠
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve)
+    })
+    let port = server.address().port
+
+    let close = async () => {
+        for (let s of sockets) {
+            s.destroy()
+        }
+        await new Promise((resolve) => {
+            server.close(resolve)
+        })
+    }
+
+    return { port, url: `http://127.0.0.1:${port}/v1`, close }
+}
+
+
+export default fakeServerForApiTest

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)
+    })
+
+})