w-dispatch-ai 1.0.3 → 1.0.4

package/docs/dispatchAiWkf.mjs.html

@@ -64,6 +64,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。
 
 
 /**
@@ -83,11 +100,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 },
  * })
@@ -95,15 +116,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)
@@ -159,7 +184,7 @@ export default dispatchAiWkf
 <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/docs/dispatchAntigravity.mjs.html

@@ -251,7 +251,7 @@ export default dispatchAntigravity
 <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/docs/dispatchApiOpenaiCompat.mjs.html

@@ -74,6 +74,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)。
 //
@@ -231,13 +244,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,
@@ -283,6 +314,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')使用；
@@ -294,7 +327,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代表不驗證
@@ -470,7 +503,7 @@ export default dispatchApiOpenaiCompat
 <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/docs/dispatchClaude.mjs.html

@@ -177,7 +177,7 @@ export default dispatchClaude
 <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/docs/dispatchCodex.mjs.html

@@ -178,7 +178,7 @@ export default dispatchCodex
 <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/docs/dispatchOpencode.mjs.html

@@ -247,7 +247,7 @@ export default dispatchOpencode
 <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/docs/getCliArgs.mjs.html

@@ -113,7 +113,7 @@ export default getCliArgs
 <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/docs/getErrorResult.mjs.html

@@ -102,7 +102,7 @@ export default getErrorResult
 <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/docs/global.html

@@ -214,7 +214,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="adapters.mjs.html">adapters.mjs</a>, <a href="adapters.mjs.html#line23">line 23</a>
+        <a href="adapters.mjs.html">adapters.mjs</a>, <a href="adapters.mjs.html#line57">line 57</a>
     </li></ul></dd>
     
 
@@ -492,7 +492,7 @@ console.log(buildChain(providers, { use: 'a', fallback: ['b', 'c'] }))
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line57">line 57</a>
+        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line70">line 70</a>
     </li></ul></dd>
     
 
@@ -661,7 +661,7 @@ parse＋check接進遞補層之validate——非法回覆視為該家失敗而
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line124">line 124</a>
+        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line125">line 125</a>
     </li></ul></dd>
     
 
@@ -712,20 +712,21 @@ parse＋check接進遞補層之validate——非法回覆視為該家失敗而
 
 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()
@@ -1405,7 +1406,7 @@ await test()
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line123">line 123</a>
+        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line136">line 136</a>
     </li></ul></dd>
     
 
@@ -2162,7 +2163,7 @@ providers陣列順序即優先序，排前面的先用；
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line152">line 152</a>
+        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line186">line 186</a>
     </li></ul></dd>
     
 
@@ -2218,21 +2219,29 @@ let test = async () => {
     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()
@@ -2463,7 +2472,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入群組識別字串，游標以此為鍵，多金鑰條目應給予穩定id，預設為條目索引字串</p></td>
+            <td class="description last"><p>輸入群組識別字串，游標以此為鍵、亦為日誌標籤，本套件不解讀其內容。須區分到「模型」而非只到「廠商」(如'claude:sonnet'而非'claude')，同一模型經不同路徑取得時須帶上路徑(如'poolside:laguna-s-2.1'與'or:poolside/laguna-s-2.1:free')，且務必唯一。省略時回退為陣列索引字串——索引是位置不是身分，日後插入條目會令後續條目繼承他人游標進度，故正式設定一律明給。詳見本檔檔頭之id設計規則</p></td>
         </tr>
 
     
@@ -2871,7 +2880,7 @@ defaults為共用呼叫設定，各工作流之callOpt與名額規格可逐項
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAiWkf.mjs.html">dispatchAiWkf.mjs</a>, <a href="dispatchAiWkf.mjs.html#line72">line 72</a>
+        <a href="dispatchAiWkf.mjs.html">dispatchAiWkf.mjs</a>, <a href="dispatchAiWkf.mjs.html#line97">line 97</a>
     </li></ul></dd>
     
 
@@ -2922,11 +2931,15 @@ defaults為共用呼叫設定，各工作流之callOpt與名額規格可逐項
 
 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 },
 })
@@ -2934,15 +2947,19 @@ let wkf = dispatchAiWkf({
 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)
@@ -3894,6 +3911,8 @@ await test()
     <dd class="tag-description"><ul class="dummy"><li><p>以fetch直呼OpenAI相容API(chat/completions)呼叫AI模型</p>
 <p>特點：
 免安裝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')使用；
@@ -3903,7 +3922,7 @@ prompt走HTTP body，無命令列長度限制；
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line293">line 293</a>
+        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line326">line 326</a>
     </li></ul></dd>
     
 
@@ -4300,7 +4319,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}</p></td>
+            <td class="description last"><p>輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}。注意本轉接器不支援工具，帶入tools而模型回tool_calls時一律以TOOL_CALLS_UNSUPPORTED回報失敗，需要工具請改用CLI類kind</p></td>
         </tr>
 
     
@@ -7096,7 +7115,7 @@ console.log(getErrorResult(null).error)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line56">line 56</a>
+        <a href="dispatchAiFallback.mjs.html">dispatchAiFallback.mjs</a>, <a href="dispatchAiFallback.mjs.html#line82">line 82</a>
     </li></ul></dd>
     
 
@@ -7312,8 +7331,8 @@ console.log(getErrorResult(null).error)
 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 () => {
@@ -7322,10 +7341,10 @@ let test = async () => {
         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)
@@ -7861,8 +7880,8 @@ await test()
 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 () => {
@@ -7870,10 +7889,10 @@ let test = async () => {
     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,
     })
@@ -8447,8 +8466,8 @@ await test()
 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 () => {
@@ -8457,8 +8476,8 @@ let test = async () => {
         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)
@@ -8785,7 +8804,7 @@ await test()
 <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/docs/index.html

@@ -71,7 +71,7 @@
 <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/docs/wkf_callAiWithFallback.mjs.html

@@ -146,20 +146,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()
@@ -268,7 +269,7 @@ export { buildChain, NO_SIDE_EFFECT }
 <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/docs/wkf_extractJsonLoose.mjs.html

@@ -167,7 +167,7 @@ export default extractJsonLoose
 <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/docs/wkf_runFanout.mjs.html

@@ -110,8 +110,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 () => {
@@ -120,10 +120,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)
@@ -214,7 +214,7 @@ export { defaultIntegratePrompt }
 <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/docs/wkf_runFanoutPipeline.mjs.html

@@ -87,8 +87,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 () => {
@@ -96,10 +96,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,
  *     })
@@ -165,7 +165,7 @@ export default runFanoutPipeline
 <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>