w-dispatch-ai 1.0.2 → 1.0.4

package/g.mjs

@@ -27,7 +27,7 @@ let test = async () => {
 
     //可用之AI供應商種類
     console.log('KINDS:', wdi.KINDS)
-    // => KINDS: [ 'opencode', 'claude', 'codex', 'antigravity' ]
+    // => KINDS: [ 'opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat' ]
 
     let prompt = '請只回覆兩個字：完成，不要有任何其他文字'
 
@@ -51,6 +51,15 @@ let test = async () => {
     console.log('antigravity:', r3b.ok, r3b.stdout.trim())
     // => antigravity: true 完成
 
+    //以OpenAI相容API直呼(免CLI免登入), 給baseURL+key+model即可; Zen端點即opencode CLI之自家閘道
+    let r3c = await wdi.dispatchApiOpenaiCompat(prompt, {
+        baseURL: 'https://apihub.agnes-ai.com/v1',
+        key: agnesKeys[0],
+        model: 'agnes-2.0-flash',
+    })
+    console.log('api-openai-compat:', r3c.ok, r3c.code, r3c.stdout.trim())
+    // => api-openai-compat: true 200 完成
+
     //以供應商條目輪替, 一個條目即一組(kind, model, 可選的key與provider與config), 輪到誰就用誰的CLI與模型
     //opencode支援逐次注入金鑰, 故同一provider之多把金鑰可各成一個條目
     let items = [
@@ -75,36 +84,43 @@ let test = async () => {
     //未知供應商回傳error結果物件, 不會reject
     let r4 = await wdi.dispatchAi('gemini', prompt)
     console.log('invalid kind:', r4.ok, r4.error)
-    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity)
+    // => invalid kind: false unknown ai kind: "gemini" (available: opencode, claude, codex, antigravity, api-openai-compat)
 
     //prompt非有效字串亦回傳error結果物件
     let r5 = await wdi.dispatchClaude('')
     console.log('invalid prompt:', r5.ok, r5.error)
     // => invalid prompt: false prompt must be a non-empty string
 
-    //CLI執行失敗時, 由ok、code、error與stderr判斷原因
-    let r6 = await wdi.dispatchOpencode(prompt, {
-        model: 'opencode/deepseek-v4-flash-free',
-        provider: 'opencode',
+    //執行失敗時, 由ok、code、error與stderr判斷原因
+    //REST路徑之錯誤依HTTP狀態碼分流(401金鑰無效、429限流、5xx服務端), 判別比CLI之stderr字串可靠
+    let r6 = await wdi.dispatchApiOpenaiCompat(prompt, {
+        baseURL: 'https://apihub.agnes-ai.com/v1',
+        model: 'agnes-2.0-flash',
         key: 'sk-invalid-key',
     })
-    console.log('invalid key:', r6.ok, r6.code, r6.error, r6.stderr.includes('Invalid API key'))
-    // => invalid key: false 1 Exit code 1 true
+    console.log('invalid key:', r6.ok, r6.code, r6.error, r6.stderr.includes('无效的令牌'))
+    // => invalid key: false 401 HTTP 401 true
 
     //多供應商自動遞補: providers順序即優先序, 組內keys以游標輪替
-    //此例第1把金鑰無效 → 自動換組內下一把成功; 若整組用盡會遞補下一組(claude), 再失敗遞補codex
+    //此例第1把金鑰無效 → 自動換組內下一把成功; 若整組用盡會遞補下一組, 依序往下
+    //
+    //【id命名】id為游標鍵與日誌標籤, 須區分到「模型」而非只到「廠商」——
+    //  取'claude'則日後無法同時掛sonnet與opus, 且日誌看不出實際用了哪個模型;
+    //  同一模型經不同路徑(REST／CLI／不同閘道)取得時額度池與故障域各自獨立,
+    //  屬不同供應商, 故id須帶上路徑前綴加以區分
     let r7 = await wdi.dispatchAiFallback(prompt, {
         providers: [
+            //REST版排前面: 免CLI、快3~5倍, 純文字任務優先走此路
             {
-                id: 'deepseek',
-                kind: 'opencode',
-                model: 'opencode/deepseek-v4-flash-free',
-                provider: 'opencode',
-                keys: ['sk-invalid-key-demo', opencodeKeys[0]], //第1把無效, 示範組內輪替
-                timeoutMs: 180000,
+                id: 'api:agnes-2.0-flash',
+                kind: 'api-openai-compat',
+                baseURL: 'https://apihub.agnes-ai.com/v1',
+                model: 'agnes-2.0-flash',
+                keys: ['sk-invalid-key-demo', agnesKeys[0]], //第1把無效, 示範組內輪替
             },
+            //同一個agnes模型之CLI版: 有工具能力但較慢, 額度池亦不同, 屬另一個供應商
             {
-                id: 'agnes',
+                id: 'oc:agnes-ai/agnes-2.0-flash',
                 kind: 'opencode',
                 model: 'agnes-ai/agnes-2.0-flash',
                 provider: 'agnes-ai',
@@ -112,21 +128,21 @@ let test = async () => {
                 config: configAgnes, //第三方provider須另給定義
                 timeoutMs: 180000,
             },
-            { id: 'claude', kind: 'claude', model: 'sonnet' },
-            { id: 'codex', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
-            { id: 'antigravity', kind: 'antigravity', model: 'gemini-3.6-flash-low' },
+            { id: 'claude:sonnet', kind: 'claude', model: 'sonnet' },
+            { id: 'codex:gpt-5.6-luna', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
+            { id: 'agy:gemini-3.6-flash-low', kind: 'antigravity', model: 'gemini-3.6-flash-low' },
         ],
         budgetMs: 600000,
         onEvent: (ev) => console.log('  event:', ev.type, ev.keyId, ev.error || ''),
     })
     console.log('fallback:', r7.ok, r7.providerId, r7.keyIndex, r7.stdout.trim())
     console.log('tried:', r7.tried.map((x) => `${x.keyId}:${x.outcome}`).join(', '))
-    // =>   event: try deepseek#0
-    // =>   event: next-key deepseek#0 Exit code 1
-    // =>   event: try deepseek#1
-    // =>   event: ok deepseek#1
-    // => fallback: true deepseek 1 完成
-    // => tried: deepseek#0:next-key, deepseek#1:ok
+    // =>   event: try api:agnes-2.0-flash#0
+    // =>   event: next-key api:agnes-2.0-flash#0 HTTP 401
+    // =>   event: try api:agnes-2.0-flash#1
+    // =>   event: ok api:agnes-2.0-flash#1
+    // => fallback: true api:agnes-2.0-flash 1 完成
+    // => tried: api:agnes-2.0-flash#0:next-key, api:agnes-2.0-flash#1:ok
 
 }
 await test()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.8.70"

package/src/WDispatchAi.mjs

@@ -2,10 +2,12 @@ import keys from 'lodash-es/keys.js'
 import adapters from './adapters.mjs'
 import dispatchAi from './dispatchAi.mjs'
 import dispatchAiFallback from './dispatchAiFallback.mjs'
+import dispatchAiWkf from './dispatchAiWkf.mjs'
 import dispatchOpencode from './dispatchOpencode.mjs'
 import dispatchClaude from './dispatchClaude.mjs'
 import dispatchCodex from './dispatchCodex.mjs'
 import dispatchAntigravity from './dispatchAntigravity.mjs'
+import dispatchApiOpenaiCompat from './dispatchApiOpenaiCompat.mjs'
 
 
 // WDispatchAi.mjs — AI供應商分派層
@@ -22,20 +24,22 @@ let KINDS = keys(adapters)
 /**
  * AI供應商分派
  *
- * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，以及dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity之async函數
+ * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，dispatchAiWkf之工作流工廠函數，以及dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat之async函數
  * @example
  *
- * 詳見dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity範例
+ * 詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat範例
  *
  */
 let WDispatchAi = {
     KINDS,
     dispatchAi,
     dispatchAiFallback,
+    dispatchAiWkf,
     dispatchOpencode,
     dispatchClaude,
     dispatchCodex,
     dispatchAntigravity,
+    dispatchApiOpenaiCompat,
 }
 
 

package/src/adapters.mjs

@@ -2,6 +2,41 @@ import dispatchOpencode from './dispatchOpencode.mjs'
 import dispatchClaude from './dispatchClaude.mjs'
 import dispatchCodex from './dispatchCodex.mjs'
 import dispatchAntigravity from './dispatchAntigravity.mjs'
+import dispatchApiOpenaiCompat from './dispatchApiOpenaiCompat.mjs'
+
+
+// adapters.mjs — kind對照表, 亦為「CLI或API」之選型判準所在
+//
+// ══ 選 kind 的唯一判準: 這次呼叫需不需要「工具」? ══
+//
+//   需要工具 → 用CLI類kind(opencode/claude/codex/antigravity)
+//     所謂工具即: 讀取本機檔案、grep搜尋、執行shell指令、抓取網頁、寫檔。
+//     CLI本身是agentic harness, 自帶完整工具迴圈, 呼叫端什麼都不必做。
+//
+//   純文字生成 → 用API類kind(api-openai-compat)
+//     所謂純文字即: 摘要、分析、改寫、翻譯、產出JSON——所有素材都已在prompt內,
+//     模型只需讀prompt再輸出文字, 全程不需要碰外部世界。
+//     免安裝CLI、免預先登入, 且實測比CLI快(agnes: API 1~2.5s vs CLI 4~6s)。
+//
+// ══ 為何API類不自建工具迴圈(2026-08-11實測後之決策, 勿再自行推翻) ══
+//
+//   1. 閘道端零內建工具: 實測Zen與Agnes皆然, 連web_search都沒有——
+//      對`tools:[{type:'web_search'}]`回400並要求function.parameters,
+//      即端點只接受「呼叫端自行定義且自行執行」的function工具。
+//   2. 協定雖支援function calling(Zen之nemotron與Agnes皆實測回tool_calls),
+//      但工具的定義、執行、錯誤處理、安全邊界全部得由本套件實作與維護,
+//      等同重造CLI已經提供的harness; 工作流日後仍會持續擴充,
+//      自建工具集之維護成本只會擴大, 故一律不走此路。
+//   3. tool_calls有會話束縛(tool_call_id須於同一條messages串回填),
+//      無法跨行程外傳給上層agent(如hermes)代為執行——
+//      工作流是被上層阻塞呼叫的函式, 沒有反向請求工具的通道。
+//      詳見dispatchApiOpenaiCompat.mjs檔頭。
+//
+// ══ 混用才是常態 ══
+//
+//   同一條dispatchAiFallback鏈可逐條目混搭kind, 工作流各階段亦然:
+//   產生候選、整合收斂等純文字階段用API(快且省), 需要讀專案檔案或grep的
+//   階段換CLI。判準永遠是「這一步需不需要碰外部世界」, 而非整條鏈二選一。
 
 
 /**
@@ -16,14 +51,15 @@ import dispatchAntigravity from './dispatchAntigravity.mjs'
  * import adapters from './src/adapters.mjs'
  *
  * console.log(Object.keys(adapters))
- * // => ['opencode', 'claude', 'codex', 'antigravity']
+ * // => ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']
  *
  */
 let adapters = {
-    opencode: dispatchOpencode,
-    claude: dispatchClaude,
-    codex: dispatchCodex,
-    antigravity: dispatchAntigravity,
+    'opencode': dispatchOpencode,
+    'claude': dispatchClaude,
+    'codex': dispatchCodex,
+    'antigravity': dispatchAntigravity,
+    'api-openai-compat': dispatchApiOpenaiCompat,
 }
 
 

package/src/dispatchAiFallback.mjs

@@ -28,6 +28,32 @@ import getErrorResult from './getErrorResult.mjs'
 //
 // 【時間預算】budgetMs限制整輪遞補的總時長, 剩餘預算會壓進每次呼叫的timeoutMs,
 //   防止多家連續卡逾時而撞破外部排程的執行上限。
+//
+// ══ 條目id之設計規則(呼叫端負責, 本套件不解讀其內容) ══
+//
+//   id於本套件內只有兩個用途: 游標的物件鍵(state.cursors[id])與日誌標籤
+//   (providerId、keyId=`${id}#${keyIndex}`)。不查表、不比對、無格式要求,
+//   純粹是呼叫端的命名空間——故「什麼算同一個供應商」由呼叫端定義, 本套件不猜。
+//
+//   ① id須能區分到「模型」而非只到「廠商」
+//      ✗ id:'claude' —— 日後要同時掛sonnet與opus就無法並存, 且日誌看不出用了哪個模型
+//      ✓ id:'claude:sonnet' / id:'claude:opus'
+//
+//   ② 同一模型經不同路徑取得時, id須帶上路徑
+//      同一個laguna可經Poolside官方REST、OpenRouter、opencode CLI三條路,
+//      三者額度池與故障域各自獨立, 屬三個供應商:
+//      ✓ 'poolside:laguna-s-2.1' / 'or:poolside/laguna-s-2.1:free' / 'oc:poolside/poolside/laguna-s-2.1'
+//
+//   ③ id務必給且務必唯一
+//      未給時本套件回退為「陣列索引字串」——索引是位置不是身分, 日後於鏈中插入條目
+//      會讓後續條目繼承他人的游標進度(輪替張冠李戴), 故正式設定一律明給。
+//      兩個條目同id則共用同一游標且日誌無法區分, 屬設定錯誤。
+//
+//   ④ 同一組金鑰用於多個條目時, 各條目游標獨立
+//      例如agnes的CLI版與REST版共用同一批金鑰時, 兩者各自從游標起點輪替,
+//      同一把金鑰可能被連續使用而另一把閒置(帳號額度未均攤)。
+//      要讓它們共享輪替進度就給相同id(代價: 日誌無法區分兩者);
+//      要能區分就分開命名(代價: 額度不均攤)。此取捨由呼叫端依實際需求決定。
 
 
 //fallback層自用之設定鍵, 其餘鍵作為各attempt之共用預設原樣轉傳
@@ -106,7 +132,7 @@ function isKeyIndependentFail(r) {
  * @param {String} prompt 輸入提示詞字串，一律以stdin傳入子進程
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Array} opt.providers 輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器
- * @param {String} [opt.providers[].id=條目索引字串] 輸入群組識別字串，游標以此為鍵，多金鑰條目應給予穩定id，預設為條目索引字串
+ * @param {String} [opt.providers[].id=條目索引字串] 輸入群組識別字串，游標以此為鍵、亦為日誌標籤，本套件不解讀其內容。須區分到「模型」而非只到「廠商」(如'claude:sonnet'而非'claude')，同一模型經不同路徑取得時須帶上路徑(如'poolside:laguna-s-2.1'與'or:poolside/laguna-s-2.1:free')，且務必唯一。省略時回退為陣列索引字串——索引是位置不是身分，日後插入條目會令後續條目繼承他人游標進度，故正式設定一律明給。詳見本檔檔頭之id設計規則
  * @param {Array} [opt.providers[].keys=[]] 輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰
  * @param {Number} [opt.budgetMs=null] 輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限
  * @param {Number} [opt.minAttemptMs=20000] 輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000
@@ -126,21 +152,29 @@ function isKeyIndependentFail(r) {
  *     let r = await dispatchAiFallback('請只回覆兩個字：完成', {
  *         providers: [
  *             {
- *                 id: 'deepseek',
+ *                 //id區分到模型且帶路徑: 同一模型經REST與CLI取得屬兩個供應商
+ *                 id: 'zen:deepseek-v4-flash-free',
+ *                 kind: 'api-openai-compat',
+ *                 baseURL: 'https://opencode.ai/zen/v1',
+ *                 model: 'deepseek-v4-flash-free',
+ *                 keys: ['sk-aaa', 'sk-bbb'], //多把金鑰, 某把失敗自動換下一把
+ *             },
+ *             {
+ *                 id: 'oc:opencode/deepseek-v4-flash-free', //同一模型之CLI版(有工具, 較慢)
  *                 kind: 'opencode',
  *                 model: 'opencode/deepseek-v4-flash-free',
  *                 provider: 'opencode',
- *                 keys: ['sk-aaa', 'sk-bbb'], //多把金鑰, 某把失敗自動換下一把
+ *                 keys: ['sk-aaa', 'sk-bbb'],
  *                 timeoutMs: 180000,
  *             },
- *             { id: 'claude', kind: 'claude', model: 'sonnet' }, //deepseek全敗時遞補
- *             { id: 'codex', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
+ *             { id: 'claude:sonnet', kind: 'claude', model: 'sonnet' }, //以上全敗時遞補
+ *             { id: 'codex:gpt-5.6-luna', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
  *         ],
  *         budgetMs: 600000,
  *         onEvent: (ev) => console.log(ev.type, ev.providerId, ev.keyIndex),
  *     })
  *     console.log(r.ok, r.providerId, r.keyIndex, r.tried.length)
- *     // => true 'deepseek' 0 1
+ *     // => true 'zen:deepseek-v4-flash-free' 0 1
  *
  * }
  * await test()

package/src/dispatchAiWkf.mjs

@@ -0,0 +1,125 @@
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import callAiWithFallback from './wkf/callAiWithFallback.mjs'
+import runFanout from './wkf/runFanout.mjs'
+import runRolePipeline from './wkf/runRolePipeline.mjs'
+import runFanoutPipeline from './wkf/runFanoutPipeline.mjs'
+
+
+// dispatchAiWkf.mjs — 工作流工廠: 注入provider定義表與共用預設, 回傳綁定版API
+//
+// 【用途】專案端只需注入一次providers(名稱 → dispatchAiFallback條目)與共用設定
+//   (cwd、store、onEvent、timeoutMs…), 之後以名稱宣告工作流即可, 不必每次傳定義表。
+//
+// 【並行與游標之說明】多名額並行且共用同一store時, 游標read-modify-write
+//   可能交錯, 造成金鑰輪替不完全均攤——只影響公平性、不影響正確性(每把金鑰仍有效),
+//   故不加鎖; 要求嚴格均攤者可注入自帶佇列的store。
+//
+// 【本函數為同步工廠會throw】providers無效屬設定錯誤, 應於啟動期即失敗(fail fast),
+//   與各dispatch函數「不reject」之約定不衝突——後者是執行期呼叫, 前者是組裝期設定。
+//
+// 【定義表之鍵名即條目id】該鍵名會成為dispatchAiFallback之條目id(游標鍵與日誌標籤),
+//   須區分到「模型」而非只到「廠商」——鍵名取'claude'則日後無法同時掛sonnet與opus,
+//   且日誌看不出實際用了哪個模型; 同一模型經不同路徑(REST／CLI／不同閘道)取得時,
+//   額度池與故障域各自獨立而屬不同供應商, 鍵名須帶上路徑加以區分。
+//   命名規則與取捨詳見dispatchAiFallback.mjs檔頭之「條目id之設計規則」。
+//
+// 【定義providers時如何選kind: CLI或API】判準是「該階段需不需要工具」:
+//   需要讀本機檔案、grep、執行指令、抓網頁 → CLI類kind(opencode/claude/codex/antigravity);
+//   純文字生成(素材皆已在prompt內) → API類kind(api-openai-compat), 免安裝免登入且較快。
+//   工作流常態是混用: runFanout之候選生成與整合、runRolePipeline之審計修訂等
+//   多屬純文字階段可走API; 唯獨需要實際翻閱專案檔案的階段必須走CLI。
+//   API類不支援工具且不會自建工具迴圈, 理由詳見adapters.mjs檔頭之選型判準區塊。
+//
+// 【工具無法向上層轉送】工作流各名額(如runFanout之agents)只是同行程之async函數呼叫,
+//   非獨立agent; 模型回傳之tool_calls受會話束縛而無法外傳給上層agent(如hermes)代跑,
+//   故「讓外殼提供工具給工作流內的模型使用」在本架構下不成立——需要工具就選CLI類kind。
+
+
+/**
+ * 建立AI工作流執行環境(工廠)，注入provider定義表與共用預設後回傳綁定版API
+ *
+ * 特點：
+ * providers為名稱對dispatchAiFallback條目之定義表，之後各工作流以名稱宣告主模型與遞補鏈；
+ * defaults為共用呼叫設定，各工作流之callOpt與名額規格可逐項覆寫；
+ * 回傳之各函數皆不reject；本工廠為同步函數，providers無效時throw(設定錯誤應於啟動期即失敗)
+ *
+ * @param {Object} opt 輸入設定物件
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → dispatchAiFallback條目：{ kind, model, keys, exe, provider, config, sandbox, extraArgs... })
+ * @param {Object} [opt.defaults={}] 輸入共用呼叫設定物件(cwd、store、onEvent、timeoutMs、budgetMs、maxRetries、promptPrefix、parse等)，預設{}
+ * @returns {Object} 回傳綁定版API物件，內含callAi(單一名額呼叫)、runFanout(多開＋整合)、runRolePipeline(串行角色鏈)、runFanoutPipeline(多開＋整合＋角色鏈)、providers(定義表原樣)
+ * @example
+ * //need cli in system PATH
+ *
+ * import dispatchAiWkf from './src/dispatchAiWkf.mjs'
+ *
+ * //定義表之鍵名即dispatchAiFallback之條目id, 須區分到模型而非只到廠商,
+ * //同一模型經不同路徑取得時須帶上路徑(REST與CLI屬兩個供應商, 能力與速度皆不同)
+ * let wkf = dispatchAiWkf({
+ *     providers: {
+ *         'zen:deepseek-v4-flash-free': { kind: 'api-openai-compat', baseURL: 'https://opencode.ai/zen/v1', model: 'deepseek-v4-flash-free', keys: ['sk-xxx'] },
+ *         'oc:opencode/deepseek-v4-flash-free': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
+ *         'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *         'claude:opus': { kind: 'claude', model: 'opus' },
+ *         'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ *     },
+ *     defaults: { timeoutMs: 300000 },
+ * })
+ *
+ * let test = async () => {
+ *
+ *     //單一名額: 主模型＋遞補鏈
+ *     let r1 = await wkf.callAi('只回覆JSON: {"a":1}', { spec: { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] }, check: (j) => j.a === 1 })
+ *     console.log(r1.ok, r1.json)
+ *     // => true { a: 1 }
+ *
+ *     //Fanout工作流: 多開執行＋單點整合
+ *     //純文字階段用REST(快), 需要讀專案檔案之階段才用CLI(有工具)
+ *     let r2 = await wkf.runFanout({
+ *         task: '分析並只回覆JSON: {"essence":"..."}',
+ *         agents: [
+ *             { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
+ *             { use: 'claude:sonnet' },
+ *         ],
+ *         integrate: { use: 'codex:gpt-5.6-luna' },
+ *         check: (j) => !!j.essence,
+ *     })
+ *     console.log(r2.ok, r2.integrated)
+ *     // => true true
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+function dispatchAiWkf(opt = {}) {
+    let providers = get(opt, 'providers', null)
+    if (!isobj(providers)) {
+        throw new Error('dispatchAiWkf: opt.providers must be an object (name → provider entry)')
+    }
+    let defaults = get(opt, 'defaults', null)
+    if (!isobj(defaults)) {
+        defaults = {}
+    }
+
+    return {
+        providers,
+
+        //單一名額呼叫: callAi(prompt, { spec:{use,fallback}, check, ... })
+        callAi: (prompt, o = {}) => callAiWithFallback(prompt, { ...defaults, ...o, providers }),
+
+        //Fanout工作流: runFanout({ task, agents, integrate, check, schema, minCandidates, callOpt? })
+        runFanout: (o = {}) => runFanout({ ...o, providers, callOpt: { ...defaults, ...get(o, 'callOpt', {}) } }),
+
+        //RolePipeline工作流: runRolePipeline({ input, stages, callOpt? })
+        runRolePipeline: (o = {}) => runRolePipeline({ ...o, providers, callOpt: { ...defaults, ...get(o, 'callOpt', {}) } }),
+
+        //FanoutPipeline工作流: runFanoutPipeline({ task, agents, integrate, stages, check, schema, callOpt? })
+        runFanoutPipeline: (o = {}) => runFanoutPipeline({ ...o, providers, callOpt: { ...defaults, ...get(o, 'callOpt', {}) } }),
+    }
+}
+
+
+export default dispatchAiWkf