w-dispatch-ai 1.0.3 → 1.0.4

package/docs/wkf_runRolePipeline.mjs.html

@@ -95,8 +95,8 @@ let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
  * import runRolePipeline from './src/wkf/runRolePipeline.mjs'
  *
  * let providers = {
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
- *     'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
  * }
  *
  * let test = async () => {
@@ -105,8 +105,8 @@ let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
  *         providers,
  *         input: '原始任務',
  *         stages: [
- *             { id: 'draft', use: 'sonnet', prompt: (ctx) => `就「${ctx.input}」寫初稿, 只回覆JSON: {"text":"..."}` },
- *             { id: 'review', use: 'luna', prompt: (ctx) => `審閱並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.prev)}` },
+ *             { id: 'draft', use: 'claude:sonnet', prompt: (ctx) => `就「${ctx.input}」寫初稿, 只回覆JSON: {"text":"..."}` },
+ *             { id: 'review', use: 'codex:gpt-5.6-luna', prompt: (ctx) => `審閱並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.prev)}` },
  *         ],
  *     })
  *     console.log(r.ok, r.order, r.failedStage)
@@ -182,7 +182,7 @@ export default runRolePipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Tue Aug 11 2026 13:18:34 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Thu Aug 13 2026 21:57:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g.mjs

@@ -91,29 +91,36 @@ let test = async () => {
     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',
@@ -121,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.3",
+  "version": "1.0.4",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
     "wsemi": "^1.8.70"

package/src/adapters.mjs

@@ -5,6 +5,40 @@ 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。判準永遠是「這一步需不需要碰外部世界」, 而非整條鏈二選一。
+
+
 /**
  * 各AI供應商種類(kind)對CLI轉接器函數之對照表
  *

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

@@ -17,6 +17,23 @@ import runFanoutPipeline from './wkf/runFanoutPipeline.mjs'
 //
 // 【本函數為同步工廠會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。
 
 
 /**
@@ -36,11 +53,15 @@ import runFanoutPipeline from './wkf/runFanoutPipeline.mjs'
  *
  * import dispatchAiWkf from './src/dispatchAiWkf.mjs'
  *
+ * //定義表之鍵名即dispatchAiFallback之條目id, 須區分到模型而非只到廠商,
+ * //同一模型經不同路徑取得時須帶上路徑(REST與CLI屬兩個供應商, 能力與速度皆不同)
  * let wkf = dispatchAiWkf({
  *     providers: {
- *         'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
- *         'sonnet': { kind: 'claude', model: 'sonnet' },
- *         'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ *         '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 },
  * })
@@ -48,15 +69,19 @@ import runFanoutPipeline from './wkf/runFanoutPipeline.mjs'
  * let test = async () => {
  *
  *     //單一名額: 主模型＋遞補鏈
- *     let r1 = await wkf.callAi('只回覆JSON: {"a":1}', { spec: { use: 'deepseek', fallback: ['sonnet'] }, check: (j) => j.a === 1 })
+ *     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: 'deepseek', fallback: ['sonnet'] }, { use: 'sonnet' }],
- *         integrate: { use: 'luna' },
+ *         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)

package/src/dispatchApiOpenaiCompat.mjs

@@ -27,6 +27,19 @@ import getErrorResult from './getErrorResult.mjs'
 //   能力(不讀檔不跑指令), 天然無寫檔風險。
 //   注意: 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)。
 //
@@ -184,13 +197,31 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
         }
     }
 
-    //取出choices[0].message.content
+    //取出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,
@@ -236,6 +267,8 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
  *
  * 特點：
  * 免安裝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')使用；
@@ -247,7 +280,7 @@ async function callOnce(url, headers, body, timeoutMs, validator) {
  * @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(同名鍵以此為準)，預設{}
+ * @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代表不驗證

package/src/wkf/callAiWithFallback.mjs

@@ -99,20 +99,21 @@ function buildChain(providers, spec) {
  *
  * import callAiWithFallback from './src/wkf/callAiWithFallback.mjs'
  *
+ * //鍵名須區分到模型並帶上路徑, 詳見dispatchAiFallback.mjs檔頭之id設計規則
  * let providers = {
- *     'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ *     '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: 'deepseek', fallback: ['sonnet'] },
+ *         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 } 'deepseek'
+ *     // => true { a: 1 } 'zen:deepseek-v4-flash-free'
  *
  * }
  * await test()

package/src/wkf/runFanout.mjs

@@ -63,8 +63,8 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  * 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' },
+ *     '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 () => {
@@ -73,10 +73,10 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  *         providers,
  *         task: '分析並只回覆JSON: {"essence":"..."}',
  *         agents: [
- *             { use: 'deepseek', fallback: ['sonnet'] },
- *             { use: 'sonnet' },
+ *             { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
+ *             { use: 'claude:sonnet' },
  *         ],
- *         integrate: { use: 'sonnet' },
+ *         integrate: { use: 'claude:sonnet' },
  *         check: (j) => !!j.essence,
  *     })
  *     console.log(r.ok, r.integrated, r.candidates.length)

package/src/wkf/runFanoutPipeline.mjs

@@ -40,8 +40,8 @@ import runRolePipeline from './runRolePipeline.mjs'
  * import runFanoutPipeline from './src/wkf/runFanoutPipeline.mjs'
  *
  * let providers = {
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
- *     'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
  * }
  *
  * let test = async () => {
@@ -49,10 +49,10 @@ import runRolePipeline from './runRolePipeline.mjs'
  *     let r = await runFanoutPipeline({
  *         providers,
  *         task: '分析並只回覆JSON: {"essence":"..."}',
- *         agents: [{ use: 'sonnet' }, { use: 'luna' }],
- *         integrate: { use: 'sonnet' },
+ *         agents: [{ use: 'claude:sonnet' }, { use: 'codex:gpt-5.6-luna' }],
+ *         integrate: { use: 'claude:sonnet' },
  *         stages: [
- *             { id: 'audit', use: 'luna', prompt: (ctx) => `審計此稿並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.input)}` },
+ *             { id: 'audit', use: 'codex:gpt-5.6-luna', prompt: (ctx) => `審計此稿並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.input)}` },
  *         ],
  *         check: (j) => !!j.essence,
  *     })

package/src/wkf/runRolePipeline.mjs

@@ -48,8 +48,8 @@ let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
  * import runRolePipeline from './src/wkf/runRolePipeline.mjs'
  *
  * let providers = {
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
- *     'luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
  * }
  *
  * let test = async () => {
@@ -58,8 +58,8 @@ let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
  *         providers,
  *         input: '原始任務',
  *         stages: [
- *             { id: 'draft', use: 'sonnet', prompt: (ctx) => `就「${ctx.input}」寫初稿, 只回覆JSON: {"text":"..."}` },
- *             { id: 'review', use: 'luna', prompt: (ctx) => `審閱並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.prev)}` },
+ *             { id: 'draft', use: 'claude:sonnet', prompt: (ctx) => `就「${ctx.input}」寫初稿, 只回覆JSON: {"text":"..."}` },
+ *             { id: 'review', use: 'codex:gpt-5.6-luna', prompt: (ctx) => `審閱並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.prev)}` },
  *         ],
  *     })
  *     console.log(r.ok, r.order, r.failedStage)

package/test/tools/fakeServerForApiTest.mjs

@@ -15,6 +15,7 @@ import http from 'http'
 //   flaky-429      — 同一Authorization首次429, 之後200(重試路徑用)
 //   no-choices     — 200但無choices(畸形回應路徑用)
 //   not-json       — 200但本體非JSON(畸形回應路徑用)
+//   tool-calls     — 200但finish_reason為tool_calls(工具不支援路徑用)
 //   其他           — 404
 // 【金鑰規則】Authorization含'sk-bad'一律401(優先於model路由), 模擬無效金鑰。
 
@@ -94,6 +95,19 @@ async function fakeServerForApiTest() {
                     ok(JSON.stringify({ attempt: flakyCount[auth] }))
                 }
             }
+            else if (model === 'tool-calls') {
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({
+                    choices: [{
+                        finish_reason: 'tool_calls',
+                        message: {
+                            role: 'assistant',
+                            content: '\n\n', //Agnes實測形態: 非null而是空白, 不攔截會靜默成功
+                            tool_calls: [{ id: 'call-1', type: 'function', function: { name: 'get_weather', arguments: '{"city":"台北"}' } }],
+                        },
+                    }],
+                }))
+            }
             else if (model === 'no-choices') {
                 res.writeHead(200, { 'Content-Type': 'application/json' })
                 res.end(JSON.stringify({ id: 'x', object: 'chat.completion' }))

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -178,6 +178,37 @@ describe('dispatchApiOpenaiCompat', function() {
         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)