w-dispatch-ai 1.0.2 → 1.0.3

package/src/wkf/callAiWithFallback.mjs

@@ -0,0 +1,209 @@
+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'
+ *
+ * let providers = {
+ *     'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
+ *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await callAiWithFallback('只回覆JSON: {"a":1}', {
+ *         providers,
+ *         spec: { use: 'deepseek', fallback: ['sonnet'] },
+ *         check: (j) => j.a === 1,
+ *     })
+ *     console.log(r.ok, r.json, r.providerId)
+ *     // => true { a: 1 } 'deepseek'
+ *
+ * }
+ * 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 }

package/src/wkf/extractJsonLoose.mjs

@@ -0,0 +1,108 @@
+// extractJsonLoose.mjs — 從AI回覆文字中寬鬆抽取JSON(工作流層預設解析器, 可被注入覆寫)
+//
+// 【為何需要】各家CLI的回覆常帶code fence、前後說明文字、ANSI色碼;
+//   直接JSON.parse必炸。本函數做清理後以「括號配對」找出第一個完整
+//   物件或陣列再解析。呼叫端若有更強的解析器(如含截斷搶救), 以opt.parse注入即可。
+
+
+/**
+ * 從文字中抽取第一個完整的JSON物件或陣列
+ *
+ * 特點：
+ * 先去除ANSI色碼與code fence標記後嘗試整段解析(最常見情境之最快路徑)；
+ * 整段非法時自第一個`{`或`[`起以括號配對(跳過字串與跳脫)取得第一個完整片段再解析；
+ * 僅接受物件與陣列，純量(字串/數字/布林)回傳null；
+ * 括號未閉合(輸出被截斷)或片段非法一律回傳null，不throw
+ *
+ * @param {String} text 輸入AI回覆文字字串
+ * @returns {Object|Array|null} 回傳解析成功之物件或陣列，失敗回傳null
+ * @example
+ *
+ * import extractJsonLoose from './src/wkf/extractJsonLoose.mjs'
+ *
+ * console.log(extractJsonLoose('{"a":1}'))
+ * // => { a: 1 }
+ *
+ * console.log(extractJsonLoose('說明文字\n```json\n{"a":1}\n```\n後記'))
+ * // => { a: 1 }
+ *
+ * console.log(extractJsonLoose('{"a":1')) //截斷
+ * // => null
+ *
+ * console.log(extractJsonLoose('純文字回覆'))
+ * // => null
+ *
+ */
+function extractJsonLoose(text) {
+    let s = String(text || '')
+
+    //去ANSI色碼與code fence標記
+    s = s.replace(new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g'), '')
+    s = s.replace(/```(?:json)?/g, '')
+    s = s.trim()
+    if (s === '') {
+        return null
+    }
+
+    //整段直接解析(最常見情境, 最快路徑)
+    try {
+        let j = JSON.parse(s)
+        if (j !== null && typeof j === 'object') {
+            return j
+        }
+    }
+    catch (e) { /* 進入括號配對路徑 */ }
+
+    //括號配對: 自第一個{或[起, 逐字元追蹤深度(跳過字串與跳脫), 取得第一個完整片段
+    let start = -1
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '{' || s[i] === '[') {
+            start = i
+            break
+        }
+    }
+    if (start < 0) {
+        return null
+    }
+    let depth = 0
+    let inStr = false
+    let esc = false
+    for (let i = start; i < s.length; i++) {
+        let c = s[i]
+        if (inStr) {
+            if (esc) {
+                esc = false
+            }
+            else if (c === '\\') {
+                esc = true
+            }
+            else if (c === '"') {
+                inStr = false
+            }
+            continue
+        }
+        if (c === '"') {
+            inStr = true
+        }
+        else if (c === '{' || c === '[') {
+            depth++
+        }
+        else if (c === '}' || c === ']') {
+            depth--
+            if (depth === 0) {
+                try {
+                    let j = JSON.parse(s.slice(start, i + 1))
+                    if (j !== null && typeof j === 'object') {
+                        return j
+                    }
+                }
+                catch (e) { /* 片段仍非法, 視為失敗 */ }
+                return null
+            }
+        }
+    }
+    return null //括號未閉合(輸出被截斷)
+}
+
+
+export default extractJsonLoose

package/src/wkf/runFanout.mjs

@@ -0,0 +1,155 @@
+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 ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import callAiWithFallback from './callAiWithFallback.mjs'
+
+
+// runFanout.mjs — Fanout工作流: 多開執行＋單點整合收斂
+//
+// 【結構】前段(fanout)並行開N個AI名額執行同一任務, 各名額可指定主模型與自帶fallback;
+//   後段開單一AI名額把成功候選整合成最終版; 整合成果即工作流成果。
+//
+// 【部分接受】個別名額失敗不炸整輪: 成功候選達minCandidates才進整合;
+//   未達門檻(含恰為1份)時不硬整合, 直接以首位成功候選為成果(integrated:false)——
+//   單稿無從「整合」, 硬呼叫整合者只是空耗一次額度。
+//   全部失敗才回ok:false, 且已成功候選仍完整回傳(便於接續重試)。
+//
+// 【實測依據(2026-08-10評比)】整合者是本流程的單點故障——端點不穩的模型
+//   (如偶發靜默空回者)當整合者時, 靠spec.fallback遞補或maxRetries調高才能保住整條鏈。
+
+
+/**
+ * 預設整合提示詞模板：把成功候選JSON併入整合任務
+ *
+ * @param {Array} candidates 輸入成功候選物件陣列
+ * @param {Object} [opt={}] 輸入設定物件(取schema作為輸出格式示意)，預設{}
+ * @returns {String} 回傳整合提示詞字串
+ */
+function defaultIntegratePrompt(candidates, opt = {}) {
+    let schema = get(opt, 'schema', '')
+    let schemaLine = isestr(schema) ? `\n只回覆 JSON 物件，不要任何其他說明文字，格式與候選相同：\n${schema}\n` : '\n只回覆 JSON 物件，不要任何其他說明文字，格式與候選相同。\n'
+    return `你是整合者。以下是同一任務由 ${candidates.length} 個獨立執行產生的候選結果（JSON），請整合成單一最佳版本：擇優合併、去重、保留最完整的證據標注與爭議呈現，不可加入候選中沒有的數字或結論。
+${schemaLine}
+${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('\n\n')}`
+}
+
+
+/**
+ * 執行Fanout工作流：多開執行與單點整合
+ *
+ * 特點：
+ * 前段各名額並行執行同一任務，各名額可指定主模型(use)與自帶遞補鏈(fallback)；
+ * 後段為單一整合名額，同樣可帶遞補鏈；
+ * 個別名額失敗不中斷整輪，成功候選未達minCandidates時以首位候選為成果(integrated:false)不硬整合；
+ * 成功候選完整保留於回傳(部分接受、便於接續重試整合)；
+ * 本函數不會reject
+ *
+ * @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 {String} [opt.schema=''] 輸入輸出格式示意字串，供預設整合模板嵌入，預設''
+ * @param {Number} [opt.minCandidates=2] 輸入進入整合所需之最少成功候選數正整數，未達門檻以首位候選為成果，預設2
+ * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定(cwd、store、onEvent、timeoutMs、promptPrefix等)，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(工作流成果)、integrated(是否經過整合布林值)、agents(各名額完整結果陣列)、candidates(成功候選陣列)、integrateDetail(整合呼叫完整結果)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runFanout from './src/wkf/runFanout.mjs'
+ *
+ * let providers = {
+ *     'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
+ *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await runFanout({
+ *         providers,
+ *         task: '分析並只回覆JSON: {"essence":"..."}',
+ *         agents: [
+ *             { use: 'deepseek', fallback: ['sonnet'] },
+ *             { use: 'sonnet' },
+ *         ],
+ *         integrate: { use: 'sonnet' },
+ *         check: (j) => !!j.essence,
+ *     })
+ *     console.log(r.ok, r.integrated, r.candidates.length)
+ *     // => true true 2
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runFanout(opt = {}) {
+    let t0 = Date.now()
+    let providers = get(opt, 'providers', null)
+    let task = get(opt, 'task', '')
+    let agents = get(opt, 'agents', null)
+    let integrate = get(opt, 'integrate', null)
+    let check = get(opt, 'check', null)
+    let callOpt = get(opt, 'callOpt', {})
+
+    if (!isestr(task)) {
+        return { ok: false, result: null, integrated: false, agents: [], candidates: [], totalMs: 0, error: 'task must be a non-empty string' }
+    }
+    if (!isearr(agents)) {
+        return { ok: false, result: null, integrated: false, agents: [], candidates: [], totalMs: 0, error: 'agents must be a non-empty array' }
+    }
+
+    let minCandidates = get(opt, 'minCandidates', null)
+    if (!ispint(minCandidates)) {
+        minCandidates = 2
+    }
+    else {
+        minCandidates = cint(minCandidates)
+    }
+
+    //前段: 並行多開, 個別失敗不炸整輪
+    let rsAgents = await Promise.all(agents.map((spec) => {
+        let { use, fallback, ...overrides } = spec
+        return callAiWithFallback(task, { ...callOpt, ...overrides, providers, spec: { use, fallback }, check })
+    }))
+    let candidates = rsAgents.filter((r) => r.ok).map((r) => r.json)
+
+    //全部失敗
+    if (candidates.length === 0) {
+        return { ok: false, result: null, integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: 'all agents failed' }
+    }
+
+    //未達整合門檻(含恰為1份): 不硬整合, 以首位成功候選為成果
+    if (candidates.length === 1 || candidates.length < minCandidates) {
+        return { ok: true, result: candidates[0], integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: '' }
+    }
+
+    //後段: 整合
+    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
+    let intPrompt = isfun(intPromptFn) ? intPromptFn(candidates) : defaultIntegratePrompt(candidates, opt)
+    let rInt = await callAiWithFallback(intPrompt, { ...callOpt, ...intOverrides, providers, spec: { use, fallback }, check })
+
+    return {
+        ok: rInt.ok,
+        result: rInt.ok ? rInt.json : null,
+        integrated: rInt.ok,
+        agents: rsAgents,
+        candidates, //即使整合失敗, 成功候選仍完整回傳, 供接續重試整合(只重跑整合段)
+        integrateDetail: rInt,
+        totalMs: Date.now() - t0,
+        error: rInt.ok ? '' : `integrate failed: ${rInt.error}`,
+    }
+}
+
+
+export default runFanout
+export { defaultIntegratePrompt }

package/src/wkf/runFanoutPipeline.mjs

@@ -0,0 +1,106 @@
+import get from 'lodash-es/get.js'
+import runFanout from './runFanout.mjs'
+import runRolePipeline from './runRolePipeline.mjs'
+
+
+// runFanoutPipeline.mjs — FanoutPipeline工作流(Fanout+RolePipeline): 多開收斂成果接串行角色鏈
+//
+// 【結構】先跑runFanout(多開 → 整合), 其成果作為runRolePipeline的input
+//   (各階段以ctx.input取用), 最末階段回傳即工作流成果。
+//
+// 【實測依據(2026-08-10評比)】Fanout+RolePipeline是品質天花板: 前段的多樣性擇優給出最豐底稿、
+//   審計鏈再修幻覺與證據標注; 六模型的歷史最高品質全部出現在此組合(或與純RolePipeline並列)。
+//
+// 【部分接受】前段失敗即回(附前段完整明細, 含已成功候選);
+//   後段失敗回傳前段成果與後段已完成階段——呼叫端可只重跑失敗段。
+
+
+/**
+ * 執行FanoutPipeline工作流(Fanout+RolePipeline)：多開＋整合＋串行角色鏈
+ *
+ * 特點：
+ * 前段同runFanout(agents各名額可自帶fallback、integrate單點整合)；
+ * 後段同runRolePipeline(stages各階段可自帶AI／fallback／提示詞)，其input即前段成果；
+ * 本函數不會reject
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)
+ * @param {String} opt.task 輸入前段各名額共用之任務提示詞字串
+ * @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 {String} [opt.schema=''] 輸入輸出格式示意字串(供前段預設整合模板)，預設''
+ * @param {Number} [opt.minCandidates=2] 輸入前段整合門檻正整數，預設2
+ * @param {Object} [opt.callOpt={}] 輸入透傳兩段之共用呼叫設定，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(工作流成果)、A(前段runFanout完整結果)、B(後段runRolePipeline完整結果)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runFanoutPipeline from './src/wkf/runFanoutPipeline.mjs'
+ *
+ * let providers = {
+ *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await runFanoutPipeline({
+ *         providers,
+ *         task: '分析並只回覆JSON: {"essence":"..."}',
+ *         agents: [{ use: 'sonnet' }, { use: 'luna' }],
+ *         integrate: { use: 'sonnet' },
+ *         stages: [
+ *             { id: 'audit', use: 'luna', prompt: (ctx) => `審計此稿並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.input)}` },
+ *         ],
+ *         check: (j) => !!j.essence,
+ *     })
+ *     console.log(r.ok, r.A.integrated, r.B.order)
+ *     // => true true [ 'audit' ]
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runFanoutPipeline(opt = {}) {
+    let t0 = Date.now()
+
+    //前段: Fanout(多開 → 整合)
+    let rA = await runFanout({
+        providers: get(opt, 'providers', null),
+        task: get(opt, 'task', ''),
+        agents: get(opt, 'agents', null),
+        integrate: get(opt, 'integrate', null),
+        check: get(opt, 'check', null),
+        schema: get(opt, 'schema', ''),
+        minCandidates: get(opt, 'minCandidates', null),
+        callOpt: get(opt, 'callOpt', {}),
+    })
+    if (!rA.ok) {
+        return { ok: false, result: null, A: rA, B: null, totalMs: Date.now() - t0, error: `A failed: ${rA.error}` }
+    }
+
+    //後段: RolePipeline, input即前段成果
+    let rB = await runRolePipeline({
+        providers: get(opt, 'providers', null),
+        input: rA.result,
+        stages: get(opt, 'stages', null),
+        callOpt: get(opt, 'callOpt', {}),
+    })
+
+    return {
+        ok: rB.ok,
+        result: rB.ok ? rB.result : null,
+        A: rA, //前段成果與明細一律回傳——後段失敗時可據此只重跑後段
+        B: rB,
+        totalMs: Date.now() - t0,
+        error: rB.ok ? '' : `B failed: ${rB.error}`,
+    }
+}
+
+
+export default runFanoutPipeline