w-dispatch-ai 1.0.3 → 1.0.5

package/docs/global.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#buildChain">buildChain</a></li><li><a href="global.html#buildValidator">buildValidator</a></li><li><a href="global.html#callAiWithFallback">callAiWithFallback</a></li><li><a href="global.html#callOnce">callOnce</a></li><li><a href="global.html#defaultIntegratePrompt">defaultIntegratePrompt</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAiWkf">dispatchAiWkf</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchApiOpenaiCompat">dispatchApiOpenaiCompat</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#extractJsonLoose">extractJsonLoose</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#runFanout">runFanout</a></li><li><a href="global.html#runFanoutPipeline">runFanoutPipeline</a></li><li><a href="global.html#runRolePipeline">runRolePipeline</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#buildChain">buildChain</a></li><li><a href="global.html#buildValidator">buildValidator</a></li><li><a href="global.html#callAiWithFallback">callAiWithFallback</a></li><li><a href="global.html#callOnce">callOnce</a></li><li><a href="global.html#defaultIntegratePrompt">defaultIntegratePrompt</a></li><li><a href="global.html#dfTimeoutMs">dfTimeoutMs</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAiWkf">dispatchAiWkf</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchApiOpenaiCompat">dispatchApiOpenaiCompat</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#extractJsonLoose">extractJsonLoose</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#resolveProviders">resolveProviders</a></li><li><a href="global.html#runFanout">runFanout</a></li><li><a href="global.html#runFanoutPipeline">runFanoutPipeline</a></li><li><a href="global.html#runRolePipeline">runRolePipeline</a></li></ul>
     
 </nav>
 
@@ -140,7 +140,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WDispatchAi.mjs.html">WDispatchAi.mjs</a>, <a href="WDispatchAi.mjs.html#line33">line 33</a>
+        <a href="WDispatchAi.mjs.html">WDispatchAi.mjs</a>, <a href="WDispatchAi.mjs.html#line35">line 35</a>
     </li></ul></dd>
     
 
@@ -191,7 +191,7 @@
 
     <h5 class="h5-examples">Example</h5>
     
-    <pre class="prettyprint"><code>詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat範例</code></pre>
+    <pre class="prettyprint"><code>詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、resolveProviders範例</code></pre>
 
 
 
@@ -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>
     
 
@@ -275,6 +275,81 @@ console.log(Object.keys(adapters))
 
 
         
+            
+<h4 class="name" id="dfTimeoutMs"><span class="type-signature"></span>dfTimeoutMs<span class="type-signature"></span></h4>
+
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>全套件統一之預設逾時毫秒</p></li></ul></dd>
+    
+
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="dfTimeoutMs.mjs.html">dfTimeoutMs.mjs</a>, <a href="dfTimeoutMs.mjs.html#line23">line 23</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+<div class="description usertext">
+    <p>全套件統一之預設逾時毫秒</p>
+</div>
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>import dfTimeoutMs from './src/dfTimeoutMs.mjs'
+
+console.log(dfTimeoutMs)
+// => 300000</code></pre>
+
+
+
+        
     
 
     
@@ -301,7 +376,7 @@ console.log(Object.keys(adapters))
     
     <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#line52">line 52</a>
+        <a href="wkf_callAiWithFallback.mjs.html">wkf/callAiWithFallback.mjs</a>, <a href="wkf_callAiWithFallback.mjs.html#line62">line 62</a>
     </li></ul></dd>
     
 
@@ -492,7 +567,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#line71">line 71</a>
     </li></ul></dd>
     
 
@@ -661,7 +736,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#line135">line 135</a>
     </li></ul></dd>
     
 
@@ -712,20 +787,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()
@@ -1129,7 +1205,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入單次嘗試逾時毫秒正整數，預設300000</p></td>
+            <td class="description last"><p>輸入單次嘗試逾時毫秒正整數，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -1405,7 +1481,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#line137">line 137</a>
     </li></ul></dd>
     
 
@@ -2162,7 +2238,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#line189">line 189</a>
     </li></ul></dd>
     
 
@@ -2218,21 +2294,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 +2547,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>
 
     
@@ -2670,7 +2754,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入事件回調函數(ev)=&gt;{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'，回調拋出例外不影響主流程，預設null</p></td>
+            <td class="description last"><p>輸入事件回調函數(ev)=&gt;{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'；失敗事件(next-key/skip-group)另帶stdout(被拒回覆)與stderr(錯誤輸出)供診斷，兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null</p></td>
         </tr>
 
     
@@ -2705,12 +2789,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>120000</code>
+                    <code>300000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入各attempt共用之逾時毫秒正整數，條目可覆寫，預設120000</p></td>
+            <td class="description last"><p>輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -2824,7 +2908,7 @@ await test()
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳)，本函數不會reject</p>
+    <p>回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳；失敗項含stdout與stderr供診斷被拒原因)，本函數不會reject</p>
 </div>
 
 
@@ -2871,7 +2955,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#line106">line 106</a>
     </li></ul></dd>
     
 
@@ -2922,11 +3006,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 +3022,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)
@@ -3184,7 +3276,7 @@ agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAntigravity.mjs.html">dispatchAntigravity.mjs</a>, <a href="dispatchAntigravity.mjs.html#line105">line 105</a>
+        <a href="dispatchAntigravity.mjs.html">dispatchAntigravity.mjs</a>, <a href="dispatchAntigravity.mjs.html#line106">line 106</a>
     </li></ul></dd>
     
 
@@ -3615,12 +3707,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>[]</code>
+                    <code>自動納入cwd</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入加入workspace之目錄字串陣列，逐項展開為<code>--add-dir</code>，預設[]</p></td>
+            <td class="description last"><p>輸入加入workspace之目錄字串陣列，逐項展開為<code>--add-dir</code>。agy以自身scratch目錄為工作區而不採子進程cwd，故未給本參數時自動納入有效cwd令檔案可視範圍與其他CLI轉接器一致；明示給陣列(含空陣列[]代表不揭露任何目錄)則完全尊重呼叫端</p></td>
         </tr>
 
     
@@ -3700,7 +3792,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，agy為agent型CLI故預設較長之300000，預設300000</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000(恰對齊agy自身print-timeout預設5m0s)</p></td>
         </tr>
 
     
@@ -3740,7 +3832,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入子進程工作目錄字串，預設process.cwd()</p></td>
+            <td class="description last"><p>輸入子進程工作目錄字串，預設process.cwd()。注意本參數不影響agy之檔案可視範圍(agy以自身scratch目錄為工作區)，可視範圍由addDirs決定(未給addDirs時自動納入本目錄)</p></td>
         </tr>
 
     
@@ -3894,6 +3986,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 +3997,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#line327">line 327</a>
     </li></ul></dd>
     
 
@@ -4300,7 +4394,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>
 
     
@@ -4375,12 +4469,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>120000</code>
+                    <code>300000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，預設120000</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -4585,7 +4679,7 @@ prompt一律走stdin而非位置參數，因摘要內文可達數萬字，當命
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchClaude.mjs.html">dispatchClaude.mjs</a>, <a href="dispatchClaude.mjs.html#line74">line 74</a>
+        <a href="dispatchClaude.mjs.html">dispatchClaude.mjs</a>, <a href="dispatchClaude.mjs.html#line77">line 77</a>
     </li></ul></dd>
     
 
@@ -4638,7 +4732,7 @@ import dispatchClaude from './src/dispatchClaude.mjs'
 
 let test = async () => {
 
-    let r = await dispatchClaude('請只回覆兩個字：完成', { model: 'sonnet', timeoutMs: 120000 })
+    let r = await dispatchClaude('請只回覆兩個字：完成', { model: 'sonnet' })
     console.log(r.ok, r.stdout.trim())
     // => true '完成'
 
@@ -4971,12 +5065,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>120000</code>
+                    <code>300000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -5179,7 +5273,7 @@ prompt一律走stdin而非位置參數，因摘要內文可達數萬字，當命
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchCodex.mjs.html">dispatchCodex.mjs</a>, <a href="dispatchCodex.mjs.html#line74">line 74</a>
+        <a href="dispatchCodex.mjs.html">dispatchCodex.mjs</a>, <a href="dispatchCodex.mjs.html#line77">line 77</a>
     </li></ul></dd>
     
 
@@ -5565,12 +5659,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>120000</code>
+                    <code>300000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -5775,7 +5869,7 @@ prompt一律走stdin而非位置參數，因摘要內文可達數萬字，當命
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchOpencode.mjs.html">dispatchOpencode.mjs</a>, <a href="dispatchOpencode.mjs.html#line115">line 115</a>
+        <a href="dispatchOpencode.mjs.html">dispatchOpencode.mjs</a>, <a href="dispatchOpencode.mjs.html#line118">line 118</a>
     </li></ul></dd>
     
 
@@ -6347,12 +6441,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>120000</code>
+                    <code>300000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000</p></td>
         </tr>
 
     
@@ -7096,7 +7190,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#line85">line 85</a>
     </li></ul></dd>
     
 
@@ -7238,6 +7332,357 @@ console.log(getErrorResult(null).error)
 
     
 
+    <h4 class="name" id="resolveProviders"><span class="type-signature"></span>resolveProviders<span class="signature">(providers, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>展開providers定義條目：envVar → keys，並可依id自選子集</p>
+<p>特點：
+條目之envVar依env來源(預設process.env)展開為keys陣列(變數值以逗號分隔多把)，envVar欄位自輸出移除；
+缺對應環境變數(或值為空)之條目停用並列入skipped，不中斷不throw；
+無envVar之條目(訂閱登入態CLI)原樣通過；條目已自帶有效keys者以keys為準；
+opt.pick可依id自選子集並以pick順序回傳(順序即遞補優先序)；
+輸入陣列與條目皆不被改動(輸出為淺拷貝)</p></li></ul></dd>
+    
+
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="resolveProviders.mjs.html">resolveProviders.mjs</a>, <a href="resolveProviders.mjs.html#line56">line 56</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>import resolveProviders from './src/resolveProviders.mjs'
+import providersAll from './src/providers.mjs'
+
+process.loadEnvFile('./.env') //金鑰放.env, 變數值以逗號分隔多把
+
+//全取: envVar展開為keys, 缺環境變數者列入skipped
+let { providers, table, skipped } = resolveProviders(providersAll)
+console.log(providers.length, skipped)
+// => 10 []
+
+//自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
+let r2 = resolveProviders(providersAll, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
+console.log(r2.providers.map((p) => p.id))
+// => [ 'agnes:agnes-2.5-flash', 'claude:sonnet' ]
+
+//table可直接餵dispatchAiWkf之providers定義表
+//let wkf = dispatchAiWkf({ providers: r2.table, defaults: { timeoutMs: 1200000 } })</code></pre>
+
+
+
+
+    <h5 class="h5-parameters">Parameters:</h5>
+    
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+        <th>Attributes</th>
+        
+
+        
+        <th>Default</th>
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>providers</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入providers條目物件陣列(如providers.mjs之預設匯出)</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>opt</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>{}</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入設定物件，預設{}</p>
+                <h6>Properties</h6>
+                
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+        <th>Attributes</th>
+        
+
+        
+        <th>Default</th>
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>env</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>process.env</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入金鑰來源物件(變數名 → 逗號分隔之金鑰字串)，預設process.env</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>pick</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Object</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
     <h4 class="name" id="runFanout"><span class="type-signature type-signature-async">(async) </span>runFanout<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
@@ -7312,8 +7757,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 +7767,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 +8306,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 +8315,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 +8892,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 +8902,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 +9230,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 Fri Aug 14 2026 12:01:07 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>