w-dispatch-ai 1.0.2 → 1.0.4

package/src/dispatchApiOpenaiCompat.mjs

@@ -0,0 +1,444 @@
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import isnum from 'wsemi/src/isnum.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import isp0int from 'wsemi/src/isp0int.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import delay from 'wsemi/src/delay.mjs'
+import strleft from 'wsemi/src/strleft.mjs'
+import strdelleft from 'wsemi/src/strdelleft.mjs'
+import strTruncate from 'wsemi/src/strTruncate.mjs'
+import getErrorResult from './getErrorResult.mjs'
+
+
+// dispatchApiOpenaiCompat.mjs — 以fetch直呼OpenAI相容API(chat/completions)
+//
+// 【為何需要】opencode CLI調用的deepseek(OpenCode Zen閘道)與agnes-ai本體都是
+//   OpenAI相容REST API, 直呼即可免安裝CLI、免預先登入(2026-08-11於本機實測):
+//     OpenCode Zen — https://opencode.ai/zen/v1 (金鑰同auth.json之sk-..., 模型名去掉opencode/前綴)
+//     Agnes — https://apihub.agnes-ai.com/v1
+//   實測四把金鑰直呼皆200; 壞金鑰回401(Zen: `{"type":"AuthError","message":"Invalid API key."}`,
+//   Agnes: `{"message":"无效的令牌...","type":"AgnesAI_error"}`)。
+//
+// 【與CLI轉接器之差異】prompt走HTTP body無命令列長度限制; 錯誤依HTTP狀態碼精確分流
+//   (401/403金鑰、429限流、5xx服務端), 不再依賴stderr字串猜測; 純completion無agentic
+//   能力(不讀檔不跑指令), 天然無寫檔風險。
+//   注意: claude與codex走訂閱帳號登入態而非API金鑰, 無法比照, 仍須CLI轉接器。
+//
+// 【本轉接器不支援工具, 需要工具請改用CLI類kind(2026-08-11實測後之決策)】
+//   閘道端零內建工具: 實測Zen與Agnes皆對`tools:[{type:'web_search'}]`回400並要求
+//   function.parameters, 即只接受「呼叫端自行定義且自行執行」之function工具;
+//   協定層雖支援function calling(Zen之nemotron-3-ultra-free與Agnes皆實測回
+//   finish_reason:'tool_calls'且tool_calls格式標準), 但工具之定義、執行、錯誤處理與
+//   安全邊界全須本套件自行實作與維護, 等同重造CLI已提供之harness, 故不做。
+//   又tool_calls有會話束縛(tool_call_id須於同一條messages串內回填, 且須保留前文),
+//   該messages串活在本函數單次呼叫之生命週期內, 無法暫停後跨行程外傳給上層agent代跑
+//   ——工作流是被上層阻塞呼叫的函式, 沒有反向請求工具的通道; 同理工作流(如runFanout)
+//   之各名額亦只是同行程之async函數呼叫, 無法把tool_calls往上層轉送。
+//   故呼叫端若於body帶入tools, 本函數一律以TOOL_CALLS_UNSUPPORTED回報失敗而不假裝成功
+//   (實測Agnes於tool_calls時content為"\n\n"而非null, 不特別處理會靜默回傳空白內容)。
+//
+// 【重試語意對齊execCli】4xx(429除外)為客戶端錯誤不可重試而立即中止;
+//   429/5xx/網路錯誤/逾時依maxRetries線性退避重試(間隔retryDelayMs*次數, 上限15000ms)。
+//
+// 【結果結構對齊execCli】{ ok, stdout, stderr, code, error, durationMs, attempts },
+//   stdout為回覆內容、code為HTTP狀態碼(網路錯誤與逾時為null)、逾時error以TIMEOUT開頭、
+//   驗證失敗error為OUTPUT_VALIDATION_FAILED——故dispatchAiFallback之失敗分流
+//   (TIMEOUT/驗證失敗跳組, 其餘換金鑰)對本轉接器同樣成立, 無須任何修改。
+
+
+//預設值
+let DEFAULT_TIMEOUT_MS = 120000
+let DEFAULT_RETRY_DELAY_MS = 5000
+let MAX_RETRY_DELAY_MS = 15000
+
+
+//optTruncate, 裁切失敗結果之內容時於刪節號後標註原始總長度(同execCli)
+let optTruncate = {
+    funWithMsg: (str) => `(truncated, total ${str.length} chars)`,
+}
+
+
+/**
+ * 建立驗證函式(規則語法同execCli之validate)
+ *
+ * @param {String|Function} rule 輸入驗證規則字串('nonempty'、'json'、'min:100', 逗號可串接)或自訂函式
+ * @returns {Function|null} 回傳驗證函式，無有效規則回傳null
+ */
+function buildValidator(rule) {
+
+    //自訂函式直接使用
+    if (isfun(rule)) {
+        return rule
+    }
+
+    //check
+    if (!isestr(rule)) {
+        return null
+    }
+
+    //checks
+    let checks = rule.split(',').map((r) => r.trim()).filter(Boolean)
+    if (checks.length === 0) {
+        return null
+    }
+
+    return (stdout) => {
+        for (let check of checks) {
+
+            if (check === 'nonempty') {
+                if (!isestr(stdout) || stdout.trim() === '') {
+                    return false
+                }
+            }
+
+            else if (check === 'json') {
+                try {
+                    JSON.parse(stdout)
+                }
+                catch {
+                    return false
+                }
+            }
+
+            else if (strleft(check, 4) === 'min:') {
+
+                //規則本身無效(如min:abc) → 視為驗證失敗, 不靜默跳過
+                let smin = strdelleft(check, 4)
+                if (!isnum(smin)) {
+                    return false
+                }
+
+                let min = cint(smin)
+                if (!isestr(stdout) || stdout.length < min) {
+                    return false
+                }
+            }
+
+        }
+        return true
+    }
+}
+
+
+/**
+ * 單次HTTP呼叫(內部使用, 不含重試邏輯)
+ *
+ * @param {String} url 輸入完整端點網址字串
+ * @param {Object} headers 輸入請求標頭物件
+ * @param {Object} body 輸入請求本體物件
+ * @param {Number} timeoutMs 輸入逾時毫秒
+ * @param {Function|null} validator 輸入驗證函式
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件
+ */
+async function callOnce(url, headers, body, timeoutMs, validator) {
+
+    let t0 = Date.now()
+
+    //AbortController, 逾時中止(含回應本體之串流讀取)
+    let controller = new AbortController()
+    let timer = setTimeout(() => {
+        controller.abort()
+    }, timeoutMs)
+
+    let res = null
+    let txt = ''
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        })
+        txt = await res.text()
+    }
+    catch (err) {
+        clearTimeout(timer)
+        let durationMs = Date.now() - t0
+
+        //逾時, error以TIMEOUT開頭令dispatchAiFallback視為與金鑰無關而跳組
+        if (err.name === 'AbortError') {
+            return {
+                ok: false,
+                stdout: '',
+                stderr: '',
+                code: null,
+                error: `TIMEOUT after ${timeoutMs / 1000}s`,
+                durationMs,
+            }
+        }
+
+        //網路層錯誤(DNS/連線拒絕等)
+        let cause = get(err, 'cause.code', '') || err.message
+        return {
+            ok: false,
+            stdout: '',
+            stderr: '',
+            code: null,
+            error: `FETCH_ERROR: ${cause}`,
+            durationMs,
+        }
+    }
+    clearTimeout(timer)
+
+    let durationMs = Date.now() - t0
+
+    //HTTP非2xx, 原始回應本體放stderr供除錯與分類
+    if (!res.ok) {
+        return {
+            ok: false,
+            stdout: '',
+            stderr: strTruncate(txt, 1000, optTruncate),
+            code: res.status,
+            error: `HTTP ${res.status}`,
+            durationMs,
+        }
+    }
+
+    //取出choices[0]
+    let content = null
+    let finishReason = ''
+    let toolCalls = null
+    try {
+        let j = JSON.parse(txt)
+        content = get(j, 'choices.0.message.content', null)
+        finishReason = get(j, 'choices.0.finish_reason', '')
+        toolCalls = get(j, 'choices.0.message.tool_calls', null)
+    }
+    catch {}
+
+    //tool_calls, 本轉接器不支援工具迴圈(見檔頭), 明確回報而不假裝成功
+    //(Agnes於tool_calls時content為"\n\n"非null, 不攔截會靜默回傳空白內容)
+    if (finishReason === 'tool_calls' || (toolCalls !== null && toolCalls !== undefined)) {
+        return {
+            ok: false,
+            stdout: '',
+            stderr: strTruncate(txt, 1000, optTruncate),
+            code: res.status,
+            error: 'TOOL_CALLS_UNSUPPORTED: use a cli kind (opencode/claude/codex/antigravity) when tools are needed',
+            durationMs,
+        }
+    }
+
+    if (content === null || content === undefined) {
+        return {
+            ok: false,
+            stdout: '',
+            stderr: strTruncate(txt, 500, optTruncate),
+            code: res.status,
+            error: 'INVALID_RESPONSE: missing choices[0].message.content',
+            durationMs,
+        }
+    }
+    if (typeof content !== 'string') {
+        content = JSON.stringify(content) //少數閘道回array形態
+    }
+
+    //validator, error與execCli一致令dispatchAiFallback可統一分流
+    if (validator && !validator(content)) {
+        return {
+            ok: false,
+            stdout: strTruncate(content, 500, optTruncate),
+            stderr: '',
+            code: res.status,
+            error: 'OUTPUT_VALIDATION_FAILED',
+            durationMs,
+        }
+    }
+
+    return {
+        ok: true,
+        stdout: content,
+        stderr: '',
+        code: res.status,
+        error: '',
+        durationMs,
+    }
+}
+
+
+//本轉接器不使用execCli, 全部設定鍵自理, 未知鍵一律忽略
+
+
+/**
+ * 以fetch直呼OpenAI相容API(chat/completions)呼叫AI模型
+ *
+ * 特點：
+ * 免安裝CLI、免預先登入，給baseURL＋key＋model即可呼叫(如OpenCode Zen、Agnes等OpenAI相容閘道)；
+ * 僅供純文字生成(摘要、分析、改寫、產出JSON等素材已在prompt內之任務)——
+ * 需要讀本機檔案、grep、執行指令、抓網頁等工具能力時，請改用CLI類kind(opencode/claude/codex/antigravity)；
+ * prompt走HTTP body，無命令列長度限制；
+ * 錯誤依HTTP狀態碼分流：4xx(429除外)為客戶端錯誤不重試，429/5xx/網路錯誤/逾時依maxRetries線性退避重試；
+ * 結果結構與逾時/驗證失敗之error字樣對齊execCli，可直接作為dispatchAi與dispatchAiFallback之kind('api-openai-compat')使用；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，作為user訊息置於HTTP body
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} opt.baseURL 輸入API基底網址字串，例如'https://opencode.ai/zen/v1'、'https://apihub.agnes-ai.com/v1'，將於尾端接上/chat/completions
+ * @param {String} opt.model 輸入模型ID字串，例如'deepseek-v4-flash-free'(Zen之模型名不帶opencode/前綴)、'agnes-2.0-flash'
+ * @param {String} [opt.key=''] 輸入API key字串，以Bearer置於Authorization標頭，預設''代表不帶認證標頭
+ * @param {String} [opt.system=''] 輸入system提示詞字串，將以system角色置於messages首位，預設''代表不帶
+ * @param {Object} [opt.body={}] 輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}。注意本轉接器不支援工具，帶入tools而模型回tool_calls時一律以TOOL_CALLS_UNSUPPORTED回報失敗，需要工具請改用CLI類kind
+ * @param {Object} [opt.headers={}] 輸入額外請求標頭物件，預設{}
+ * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，預設120000
+ * @param {String|Function} [opt.validate=undefined] 輸入回覆內容驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
+ * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0
+ * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject
+ * @example
+ * //need network, no cli required
+ *
+ * import dispatchApiOpenaiCompat from './src/dispatchApiOpenaiCompat.mjs'
+ *
+ * let test = async () => {
+ *
+ *     //OpenCode Zen(即opencode CLI之自家閘道), 模型名不帶opencode/前綴
+ *     let r1 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
+ *         baseURL: 'https://opencode.ai/zen/v1',
+ *         key: 'sk-xxxxxx',
+ *         model: 'deepseek-v4-flash-free',
+ *     })
+ *     console.log(r1.ok, r1.stdout.trim())
+ *     // => true 完成
+ *
+ *     //Agnes
+ *     let r2 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
+ *         baseURL: 'https://apihub.agnes-ai.com/v1',
+ *         key: 'sk-xxxxxx',
+ *         model: 'agnes-2.0-flash',
+ *     })
+ *     console.log(r2.ok, r2.stdout.trim())
+ *     // => true 完成
+ *
+ *     let re = await dispatchApiOpenaiCompat('abc', { baseURL: 'https://opencode.ai/zen/v1', key: 'sk-bad', model: 'deepseek-v4-flash-free' })
+ *     console.log(re.ok, re.code, re.error)
+ *     // => false 401 HTTP 401
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchApiOpenaiCompat(prompt, opt = {}) {
+
+    //check prompt, 不reject故以錯誤結果物件回報
+    if (!isestr(prompt)) {
+        return getErrorResult('prompt must be a non-empty string')
+    }
+
+    //baseURL必填, API無CLI可回退
+    let baseURL = get(opt, 'baseURL', null)
+    if (!isestr(baseURL)) {
+        return getErrorResult('baseURL must be a non-empty string')
+    }
+
+    //model必填, chat/completions無預設模型
+    let model = get(opt, 'model', null)
+    if (!isestr(model)) {
+        return getErrorResult('model must be a non-empty string')
+    }
+
+    //key, 無效代表不帶認證標頭(部分閘道免認證)
+    let key = get(opt, 'key', null)
+
+    //system
+    let system = get(opt, 'system', null)
+
+    //bodyExtra
+    let bodyExtra = get(opt, 'body', null)
+    if (!isobj(bodyExtra)) {
+        bodyExtra = {}
+    }
+
+    //headersExtra
+    let headersExtra = get(opt, 'headers', null)
+    if (!isobj(headersExtra)) {
+        headersExtra = {}
+    }
+
+    //timeoutMs
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = DEFAULT_TIMEOUT_MS
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+
+    //maxRetries
+    let maxRetries = get(opt, 'maxRetries', null)
+    if (!isp0int(maxRetries)) {
+        maxRetries = 0
+    }
+    else {
+        maxRetries = cint(maxRetries)
+    }
+
+    //retryDelayMs
+    let retryDelayMs = get(opt, 'retryDelayMs', null)
+    if (!ispint(retryDelayMs)) {
+        retryDelayMs = DEFAULT_RETRY_DELAY_MS
+    }
+    else {
+        retryDelayMs = cint(retryDelayMs)
+    }
+
+    //validator
+    let validator = buildValidator(get(opt, 'validate', null))
+
+    //url, baseURL尾端斜線正規化後接上端點
+    let url = baseURL.replace(/\/+$/, '') + '/chat/completions'
+
+    //messages
+    let messages = []
+    if (isestr(system)) {
+        messages.push({ role: 'system', content: system })
+    }
+    messages.push({ role: 'user', content: prompt })
+
+    //body, 額外鍵以bodyExtra為準(可覆寫temperature等, 覆寫messages屬進階用法)
+    let body = { model, messages, ...bodyExtra }
+
+    //headers
+    let headers = { 'Content-Type': 'application/json', ...headersExtra }
+    if (isestr(key)) {
+        headers['Authorization'] = `Bearer ${key}`
+    }
+
+    let lastResult = null
+    let totalAttempts = 0
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+
+        //delay, 重試間隔隨次數遞增, 上限15000ms(同execCli)
+        if (attempt > 0) {
+            await delay(Math.min(retryDelayMs * attempt, MAX_RETRY_DELAY_MS))
+        }
+
+        lastResult = await callOnce(url, headers, body, timeoutMs, validator)
+        totalAttempts = attempt + 1
+
+        if (lastResult.ok) {
+            lastResult.attempts = totalAttempts
+            return lastResult
+        }
+
+        //不可重試: 4xx(429除外)為客戶端錯誤, 重試無意義
+        let c = lastResult.code
+        if (isnum(c) && c >= 400 && c < 500 && c !== 429) {
+            break
+        }
+
+    }
+
+    lastResult.attempts = totalAttempts
+
+    return lastResult
+}
+
+
+export default dispatchApiOpenaiCompat

package/src/wkf/callAiWithFallback.mjs

@@ -0,0 +1,210 @@
+import get from 'lodash-es/get.js'
+import isearr from 'wsemi/src/isearr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import isobj from 'wsemi/src/isobj.mjs'
+import dispatchAiFallback from '../dispatchAiFallback.mjs'
+import extractJsonLoose from './extractJsonLoose.mjs'
+
+
+// callAiWithFallback.mjs — 工作流的最小呼叫單元: 一個「AI名額」＝主模型＋自帶遞補鏈
+//
+// 【設計】呼叫端以名稱宣告主模型與遞補(use:'deepseek', fallback:['agnes-ai','sonnet']),
+//   本函數依providers定義表把名稱展開成dispatchAiFallback的providers陣列
+//   (順序即優先序), 故「各AI名額可各自指定fallback」天然成立。
+//   名稱查無定義時視為設定錯誤直接回報(fail fast), 不靜默略過——
+//   否則fallback名稱打錯字只會讓遞補鏈無感知地短一截, 事後無從察覺。
+//
+// 【JSON驗證接進遞補層】parse＋check包成dispatchAiFallback的validate:
+//   回覆非法(空回、截斷、缺欄位)時為OUTPUT_VALIDATION_FAILED, 遞補層視為
+//   與金鑰無關之失敗而「整組跳過換下一家」(不換組內金鑰——同模型換金鑰仍是
+//   同樣的產出習慣); 端點不穩而偶發空回的模型, 以maxRetries調高令同鍵重試。
+//
+// 【防寫檔前綴】agentic CLI對cwd隔離免疫(會自行解析專案根目錄寫檔),
+//   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
+//   殷鑑: 2026-08-10執行任務歷史.md遭AI覆寫、評比腳本繞過前綴又產生根目錄孤兒檔。
+
+
+//預設防寫檔前綴
+let NO_SIDE_EFFECT = [
+    '【執行約束】你只需把結果輸出在回覆內容中。',
+    '禁止建立、修改或刪除任何檔案，禁止執行任何指令——呼叫端只讀取你的回覆文字，',
+    '任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '', '',
+].join('\n')
+
+
+/**
+ * 依providers定義表把「名稱規格」展開成dispatchAiFallback的providers陣列
+ *
+ * @param {Object} providers 輸入定義表物件(名稱 → 條目)
+ * @param {Object} spec 輸入名額規格物件{ use, fallback }
+ * @returns {Object} 回傳物件，內含chain(條目物件陣列，id一律用名稱)與missing(查無定義之名稱字串陣列)
+ * @example
+ *
+ * import { buildChain } from './src/wkf/callAiWithFallback.mjs'
+ *
+ * let providers = { a: { kind: 'claude' }, b: { kind: 'codex' } }
+ * console.log(buildChain(providers, { use: 'a', fallback: ['b', 'c'] }))
+ * // => { chain: [ { id: 'a', kind: 'claude' }, { id: 'b', kind: 'codex' } ], missing: [ 'c' ] }
+ *
+ */
+function buildChain(providers, spec) {
+    let names = [get(spec, 'use', '')]
+    let fallback = get(spec, 'fallback', null)
+    if (isearr(fallback)) {
+        names = [...names, ...fallback]
+    }
+    let chain = []
+    let missing = []
+    for (let name of names) {
+        let entry = get(providers, name, null)
+        if (isobj(entry)) {
+            chain.push({ id: name, ...entry }) //id一律用名稱, 令游標與事件可讀
+        }
+        else {
+            missing.push(String(name))
+        }
+    }
+    return { chain, missing }
+}
+
+
+/**
+ * 呼叫一個AI名額(主模型＋自帶遞補鏈)，回覆經parse＋check驗證後回傳結構化結果
+ *
+ * 特點：
+ * spec.use為主模型名稱、spec.fallback為遞補名稱陣列，依序展開為遞補鏈，名稱查無定義即回報錯誤(fail fast)；
+ * parse＋check接進遞補層之validate——非法回覆視為該家失敗而自動換下一家，不把壞結果帶回來；
+ * 預設掛防寫檔前綴(promptPrefix傳空字串可關閉)；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → dispatchAiFallback條目，條目內含kind、model、keys、exe、provider、config等)
+ * @param {Object} opt.spec 輸入名額規格物件{ use:'主模型名稱', fallback:['遞補名稱', ...] }
+ * @param {Function} [opt.check=null] 輸入結果檢核函數(json)=>Boolean，預設null代表只要能解析出JSON即通過
+ * @param {Function} [opt.parse=extractJsonLoose] 輸入回覆解析函數(stdout)=>Object|null，預設寬鬆JSON抽取
+ * @param {Boolean} [opt.rawText=false] 輸入是否以純文字模式運作布林值，true代表不解析JSON(json欄位為修剪後文字、check收文字)，預設false
+ * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
+ * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，預設300000
+ * @param {Number} [opt.budgetMs=null] 輸入整條遞補鏈之時間預算毫秒正整數，預設null代表不限
+ * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試)
+ * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
+ * @param {Object} [opt.store=null] 輸入游標持久化物件{get,set}，預設null代表用行程內記憶體
+ * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import callAiWithFallback from './src/wkf/callAiWithFallback.mjs'
+ *
+ * //鍵名須區分到模型並帶上路徑, 詳見dispatchAiFallback.mjs檔頭之id設計規則
+ * let providers = {
+ *     'zen:deepseek-v4-flash-free': { kind: 'api-openai-compat', baseURL: 'https://opencode.ai/zen/v1', model: 'deepseek-v4-flash-free', keys: ['sk-xxx'] },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await callAiWithFallback('只回覆JSON: {"a":1}', {
+ *         providers,
+ *         spec: { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
+ *         check: (j) => j.a === 1,
+ *     })
+ *     console.log(r.ok, r.json, r.providerId)
+ *     // => true { a: 1 } 'zen:deepseek-v4-flash-free'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function callAiWithFallback(prompt, opt = {}) {
+    let t0 = Date.now()
+
+    if (!isestr(prompt)) {
+        return { ok: false, json: null, error: 'prompt must be a non-empty string', ms: 0, tried: [] }
+    }
+
+    let providers = get(opt, 'providers', null)
+    let spec = get(opt, 'spec', null)
+    if (!isobj(providers) || !isobj(spec)) {
+        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, ms: 0, tried: [] }
+    }
+
+    //buildChain, 名稱查無定義即回報(fail fast), 不讓打錯字的fallback靜默消失
+    let { chain, missing } = buildChain(providers, spec)
+    if (missing.length > 0) {
+        return { ok: false, json: null, error: `unknown provider name(s): ${missing.join(', ')}`, ms: 0, tried: [] }
+    }
+    if (chain.length === 0) {
+        return { ok: false, json: null, error: `no valid provider for spec: ${JSON.stringify(spec)}`, ms: 0, tried: [] }
+    }
+
+    let rawText = get(opt, 'rawText', false) === true
+    let parse = get(opt, 'parse', null)
+    if (!isfun(parse)) {
+        parse = extractJsonLoose
+    }
+    let check = get(opt, 'check', null)
+    if (!isfun(check)) {
+        check = null
+    }
+
+    let promptPrefix = get(opt, 'promptPrefix', null)
+    if (!isestr(promptPrefix)) {
+        promptPrefix = (promptPrefix === '') ? '' : NO_SIDE_EFFECT
+    }
+
+    //validate接進遞補層: 非法回覆＝這一家失敗, 遞補層換下一家
+    let validate = (stdout) => {
+        if (rawText) {
+            let s = String(stdout || '').trim()
+            if (s === '') {
+                return false
+            }
+            return check ? check(s) === true : true
+        }
+        let j = parse(stdout)
+        if (j === null) {
+            return false
+        }
+        return check ? check(j) === true : true
+    }
+
+    let r = await dispatchAiFallback(promptPrefix + prompt, {
+        providers: chain,
+        validate,
+        timeoutMs: get(opt, 'timeoutMs', null) || 300000,
+        budgetMs: get(opt, 'budgetMs', null) || undefined,
+        maxRetries: get(opt, 'maxRetries', null) || 0,
+        cwd: get(opt, 'cwd', null) || process.cwd(),
+        store: get(opt, 'store', null) || undefined,
+        onEvent: get(opt, 'onEvent', null) || undefined,
+    })
+
+    //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件
+    let result = null
+    if (r.ok) {
+        result = rawText ? String(r.stdout || '').trim() : parse(r.stdout)
+    }
+    let providerId = get(r, 'providerId', null)
+    let keyIndex = get(r, 'keyIndex', null)
+    return {
+        ok: r.ok && result !== null,
+        json: result, //rawText模式下此欄為文字
+        providerId,
+        keyIndex,
+        keyId: (keyIndex === null) ? providerId : `${providerId}#${keyIndex}`,
+        ms: Date.now() - t0,
+        tried: get(r, 'tried', []),
+        error: r.ok ? '' : get(r, 'error', 'unknown error'),
+    }
+}
+
+
+export default callAiWithFallback
+export { buildChain, NO_SIDE_EFFECT }