w-dispatch-ai 1.0.21 → 1.0.22

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#NO_SIDE_EFFECT">NO_SIDE_EFFECT</a></li><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#attachErrorType">attachErrorType</a></li><li><a href="global.html#budgetFor">budgetFor</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#castPintOr">castPintOr</a></li><li><a href="global.html#createFileStore">createFileStore</a></li><li><a href="global.html#createUsageCounter">createUsageCounter</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#getErrorType">getErrorType</a></li><li><a href="global.html#initState">initState</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#readEnvFile">readEnvFile</a></li><li><a href="global.html#reorderByCooling">reorderByCooling</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><li><a href="global.html#salvageTruncatedArray">salvageTruncatedArray</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#NO_SIDE_EFFECT">NO_SIDE_EFFECT</a></li><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#attachErrorType">attachErrorType</a></li><li><a href="global.html#budgetFor">budgetFor</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#castPintOr">castPintOr</a></li><li><a href="global.html#createFileStore">createFileStore</a></li><li><a href="global.html#createUsageCounter">createUsageCounter</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#dispatchApiOpenaiResponses">dispatchApiOpenaiResponses</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#extractOutputText">extractOutputText</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#getErrorType">getErrorType</a></li><li><a href="global.html#initState">initState</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li><li><a href="global.html#readEnvFile">readEnvFile</a></li><li><a href="global.html#reorderByCooling">reorderByCooling</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><li><a href="global.html#salvageTruncatedArray">salvageTruncatedArray</a></li></ul>
     
 </nav>
 
@@ -220,7 +220,7 @@ callAiWithFallback預設自動掛上(傳promptPrefix:''關閉)，
     
     <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#line42">line 42</a>
+        <a href="WDispatchAi.mjs.html">WDispatchAi.mjs</a>, <a href="WDispatchAi.mjs.html#line43">line 43</a>
     </li></ul></dd>
     
 
@@ -294,7 +294,7 @@ callAiWithFallback預設自動掛上(傳promptPrefix:''關閉)，
     
     <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#line57">line 57</a>
+        <a href="adapters.mjs.html">adapters.mjs</a>, <a href="adapters.mjs.html#line58">line 58</a>
     </li></ul></dd>
     
 
@@ -350,7 +350,7 @@ callAiWithFallback預設自動掛上(傳promptPrefix:''關閉)，
     <pre class="prettyprint"><code>import adapters from './src/adapters.mjs'
 
 console.log(Object.keys(adapters))
-// => ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat']</code></pre>
+// => ['opencode', 'claude', 'codex', 'antigravity', 'api-openai-compat', 'api-openai-responses']</code></pre>
 
 
 
@@ -456,7 +456,7 @@ console.log(dfTimeoutMs)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="getErrorType.mjs.html">getErrorType.mjs</a>, <a href="getErrorType.mjs.html#line87">line 87</a>
+        <a href="getErrorType.mjs.html">getErrorType.mjs</a>, <a href="getErrorType.mjs.html#line89">line 89</a>
     </li></ul></dd>
     
 
@@ -983,13 +983,17 @@ console.log(buildChain(providers, { use: 'a', fallback: ['b', 'c'] }))
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>建立驗證函式(規則語法同execCli之validate)</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>建立驗證函式(規則語法同execCli之validate)</p>
+<p>特點：
+傳入自訂函式時直接使用；
+規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接(須全部通過)；
+規則本身無效(如'min:abc')視為驗證失敗而非靜默跳過——避免打錯規則卻以為有在驗</p></li></ul></dd>
     
 
     
     <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#line75">line 75</a>
+        <a href="buildValidator.mjs.html">buildValidator.mjs</a>, <a href="buildValidator.mjs.html#line38">line 38</a>
     </li></ul></dd>
     
 
@@ -1034,6 +1038,18 @@ console.log(buildChain(providers, { use: 'a', fallback: ['b', 'c'] }))
 
 
 
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>import buildValidator from './src/buildValidator.mjs'
+
+let v = buildValidator('nonempty,min:3')
+console.log(v('abcd'), v('ab'), v(''))
+// => true false false
+
+console.log(buildValidator(null))
+// => null</code></pre>
+
+
 
 
     <h5 class="h5-parameters">Parameters:</h5>
@@ -1981,7 +1997,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#line141">line 141</a>
+        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line77">line 77</a>
     </li></ul></dd>
     
 
@@ -2222,7 +2238,7 @@ await test()
 
     
 
-    <h4 class="name" id="castPintOr"><span class="type-signature"></span>castPintOr<span class="signature">(v, df)</span><span class="type-signature"> &rarr; {Number|*}</span></h4>
+    <h4 class="name" id="callOnce"><span class="type-signature type-signature-async">(async) </span>callOnce<span class="signature">(url, headers, body, timeoutMs, validator)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -2232,16 +2248,13 @@ await test()
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>正整數正規化：有效正整數即轉整數回傳，否則回傳預設值</p>
-<p>本套件各層之數值設定(timeoutMs、budgetMs、minAttemptMs、cooldownMs、retryDelayMs等)
-皆採同一寬容策略「無效即靜默回退預設」，統一收斂於此，
-避免同一7行判斷區塊散落各轉接器(曾重複6處)</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>單次HTTP呼叫(內部使用, 不含重試邏輯)</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="castPintOr.mjs.html">castPintOr.mjs</a>, <a href="castPintOr.mjs.html#line29">line 29</a>
+        <a href="dispatchApiOpenaiResponses.mjs.html">dispatchApiOpenaiResponses.mjs</a>, <a href="dispatchApiOpenaiResponses.mjs.html#line120">line 120</a>
     </li></ul></dd>
     
 
@@ -2286,20 +2299,6 @@ await test()
 
 
 
-    <h5 class="h5-examples">Example</h5>
-    
-    <pre class="prettyprint"><code>import castPintOr from './src/castPintOr.mjs'
-
-console.log(castPintOr(5000, 300000))
-// => 5000
-
-console.log(castPintOr('abc', 300000))
-// => 300000
-
-console.log(castPintOr(undefined, null))
-// => null</code></pre>
-
-
 
 
     <h5 class="h5-parameters">Parameters:</h5>
@@ -2327,13 +2326,13 @@ console.log(castPintOr(undefined, null))
 
         <tr>
             
-                <td class="name"><code>v</code></td>
+                <td class="name"><code>url</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">*</span>
+<span class="param-type">String</span>
 
 
 
@@ -2344,20 +2343,20 @@ console.log(castPintOr(undefined, null))
 
             
 
-            <td class="description last"><p>輸入待正規化之值</p></td>
+            <td class="description last"><p>輸入完整端點網址字串</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>df</code></td>
+                <td class="name"><code>headers</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">*</span>
+<span class="param-type">Object</span>
 
 
 
@@ -2368,7 +2367,82 @@ console.log(castPintOr(undefined, null))
 
             
 
-            <td class="description last"><p>輸入無效時之預設值(可為null代表不限)</p></td>
+            <td class="description last"><p>輸入請求標頭物件</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>body</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入請求本體物件</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>timeoutMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入逾時毫秒</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>validator</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">function</span>
+|
+
+<span class="param-type">null</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入驗證函式</p></td>
         </tr>
 
     
@@ -2394,7 +2468,7 @@ console.log(castPintOr(undefined, null))
 
         
 <div class="param-desc">
-    <p>回傳正規化後之正整數，v非有效正整數時回傳df</p>
+    <p>回傳Promise，resolve回傳結果物件</p>
 </div>
 
 
@@ -2405,10 +2479,7 @@ console.log(castPintOr(undefined, null))
     </dt>
     <dd>
         
-<span class="param-type">Number</span>
-|
-
-<span class="param-type">*</span>
+<span class="param-type">Promise</span>
 
 
 
@@ -2424,7 +2495,7 @@ console.log(castPintOr(undefined, null))
 
     
 
-    <h4 class="name" id="createFileStore"><span class="type-signature"></span>createFileStore<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
+    <h4 class="name" id="castPintOr"><span class="type-signature"></span>castPintOr<span class="signature">(v, df)</span><span class="type-signature"> &rarr; {Number|*}</span></h4>
 
     
 
@@ -2434,18 +2505,16 @@ console.log(castPintOr(undefined, null))
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>建立dispatchAiFallback之store的檔案持久化(游標與冷卻跨行程有效)</p>
-<p>特點：
-採排除式passthrough——state原封存還，僅剔除本層自用欄位(預設只有at：人讀的最後更新時間戳)，
-日後套件擴充state欄位(如cooling)即自動相容，不需改本函數；
-檔案不存在或非法JSON時get回空物件(套件視為全新狀態)；
-stamp可注入時間戳函數(排程環境建議注入時區錨定者)，寫入時補進at欄位供人工debug</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>正整數正規化：有效正整數即轉整數回傳，否則回傳預設值</p>
+<p>本套件各層之數值設定(timeoutMs、budgetMs、minAttemptMs、cooldownMs、retryDelayMs等)
+皆採同一寬容策略「無效即靜默回退預設」，統一收斂於此，
+避免同一7行判斷區塊散落各轉接器(曾重複6處)</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_createFileStore.mjs.html">wkf/createFileStore.mjs</a>, <a href="wkf_createFileStore.mjs.html#line56">line 56</a>
+        <a href="castPintOr.mjs.html">castPintOr.mjs</a>, <a href="castPintOr.mjs.html#line29">line 29</a>
     </li></ul></dd>
     
 
@@ -2492,11 +2561,16 @@ stamp可注入時間戳函數(排程環境建議注入時區錨定者)，寫入
 
     <h5 class="h5-examples">Example</h5>
     
-    <pre class="prettyprint"><code>import createFileStore from './src/wkf/createFileStore.mjs'
-import dispatchAiFallback from './src/dispatchAiFallback.mjs'
+    <pre class="prettyprint"><code>import castPintOr from './src/castPintOr.mjs'
 
-let store = createFileStore({ dir: './state' })
-//let r = await dispatchAiFallback(prompt, { providers, store, cooldownMs: 3600000 })</code></pre>
+console.log(castPintOr(5000, 300000))
+// => 5000
+
+console.log(castPintOr('abc', 300000))
+// => 300000
+
+console.log(castPintOr(undefined, null))
+// => null</code></pre>
 
 
 
@@ -2514,12 +2588,8 @@ let store = createFileStore({ dir: './state' })
         <th>Type</th>
 
         
-        <th>Attributes</th>
-        
 
         
-        <th>Default</th>
-        
 
         <th class="last">Description</th>
     </tr>
@@ -2530,13 +2600,13 @@ let store = createFileStore({ dir: './state' })
 
         <tr>
             
-                <td class="name"><code>opt</code></td>
+                <td class="name"><code>v</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">*</span>
 
 
 
@@ -2544,62 +2614,23 @@ let store = createFileStore({ dir: './state' })
             </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>
+            <td class="description last"><p>輸入待正規化之值</p></td>
+        </tr>
 
-    <tbody>
     
 
         <tr>
             
-                <td class="name"><code>file</code></td>
+                <td class="name"><code>df</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">String</span>
+<span class="param-type">*</span>
 
 
 
@@ -2607,198 +2638,15 @@ let store = createFileStore({ dir: './state' })
             </td>
 
             
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
 
             
-                <td class="default">
-                
-                    <code>null</code>
-                
-                </td>
-            
 
-            <td class="description last"><p>輸入狀態檔完整路徑字串，與dir/name二擇一</p></td>
+            <td class="description last"><p>輸入無效時之預設值(可為null代表不限)</p></td>
         </tr>
 
     
-
-        <tr>
-            
-                <td class="name"><code>dir</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">String</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>null</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入狀態目錄字串，與name組成檔案路徑</p></td>
-        </tr>
-
-    
-
-        <tr>
-            
-                <td class="name"><code>name</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">String</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>'ai-cursor.json'</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入狀態檔名字串，預設'ai-cursor.json'</p></td>
-        </tr>
-
-    
-
-        <tr>
-            
-                <td class="name"><code>ownKeys</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">Array</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>['at']</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入本層自用、不屬於套件狀態之欄位名字串陣列，get時剔除set時補回，預設['at']</p></td>
-        </tr>
-
-    
-
-        <tr>
-            
-                <td class="name"><code>stamp</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">function</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>ISO時間戳</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入時間戳函數()=&gt;String，寫入at欄位用，預設回傳new Date().toISOString()</p></td>
-        </tr>
-
-    
-    </tbody>
-</table>
-
-            </td>
-        </tr>
-
-    
-    </tbody>
-</table>
+    </tbody>
+</table>
 
 
 
@@ -2819,7 +2667,7 @@ let store = createFileStore({ dir: './state' })
 
         
 <div class="param-desc">
-    <p>回傳store物件，內含get、set(可直接餵dispatchAiFallback之store)與file(狀態檔路徑)</p>
+    <p>回傳正規化後之正整數，v非有效正整數時回傳df</p>
 </div>
 
 
@@ -2830,7 +2678,10 @@ let store = createFileStore({ dir: './state' })
     </dt>
     <dd>
         
-<span class="param-type">Object</span>
+<span class="param-type">Number</span>
+|
+
+<span class="param-type">*</span>
 
 
 
@@ -2846,7 +2697,7 @@ let store = createFileStore({ dir: './state' })
 
     
 
-    <h4 class="name" id="createUsageCounter"><span class="type-signature"></span>createUsageCounter<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
+    <h4 class="name" id="createFileStore"><span class="type-signature"></span>createFileStore<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
 
     
 
@@ -2856,19 +2707,18 @@ let store = createFileStore({ dir: './state' })
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>建立逐日、逐鍵之用量計數器(純觀測, 不參與任何判斷)</p>
+    <dd class="tag-description"><ul class="dummy"><li><p>建立dispatchAiFallback之store的檔案持久化(游標與冷卻跨行程有效)</p>
 <p>特點：
-onEvent可直接掛進dispatchAiFallback/dispatchAiWkf，於type為'try'時依keyOf取鍵累加——
-嘗試時即記帳，行程被外部時限中途砍掉已發出的請求仍有紀錄；
-逐日分桶並僅保留最近keepDays天，避免檔案無限成長；
-getDate可注入時區錨定之日期函數——預設隨系統時區，排程session之系統時區可能為UTC+0
-而使日界錯8小時，排程環境務必注入</p></li></ul></dd>
+採排除式passthrough——state原封存還，僅剔除本層自用欄位(預設只有at：人讀的最後更新時間戳)，
+日後套件擴充state欄位(如cooling)即自動相容，不需改本函數；
+檔案不存在或非法JSON時get回空物件(套件視為全新狀態)；
+stamp可注入時間戳函數(排程環境建議注入時區錨定者)，寫入時補進at欄位供人工debug</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_createUsageCounter.mjs.html">wkf/createUsageCounter.mjs</a>, <a href="wkf_createUsageCounter.mjs.html#line59">line 59</a>
+        <a href="wkf_createFileStore.mjs.html">wkf/createFileStore.mjs</a>, <a href="wkf_createFileStore.mjs.html#line56">line 56</a>
     </li></ul></dd>
     
 
@@ -2915,12 +2765,11 @@ getDate可注入時區錨定之日期函數——預設隨系統時區，排程s
 
     <h5 class="h5-examples">Example</h5>
     
-    <pre class="prettyprint"><code>import createUsageCounter from './src/wkf/createUsageCounter.mjs'
+    <pre class="prettyprint"><code>import createFileStore from './src/wkf/createFileStore.mjs'
+import dispatchAiFallback from './src/dispatchAiFallback.mjs'
 
-let usage = createUsageCounter({ dir: './state' })
-//let r = await dispatchAiFallback(prompt, { providers, onEvent: usage.onEvent })
-//console.log(usage.today())
-// => { today: '2026-08-18', byKey: { 'agnes:agnes-2.5-flash#0': 3 }, total: 3 }</code></pre>
+let store = createFileStore({ dir: './state' })
+//let r = await dispatchAiFallback(prompt, { providers, store, cooldownMs: 3600000 })</code></pre>
 
 
 
@@ -3050,7 +2899,7 @@ let usage = createUsageCounter({ dir: './state' })
                 </td>
             
 
-            <td class="description last"><p>輸入用量檔完整路徑字串，與dir/name二擇一</p></td>
+            <td class="description last"><p>輸入狀態檔完整路徑字串，與dir/name二擇一</p></td>
         </tr>
 
     
@@ -3090,7 +2939,7 @@ let usage = createUsageCounter({ dir: './state' })
                 </td>
             
 
-            <td class="description last"><p>輸入狀態目錄字串</p></td>
+            <td class="description last"><p>輸入狀態目錄字串，與name組成檔案路徑</p></td>
         </tr>
 
     
@@ -3125,65 +2974,25 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="default">
                 
-                    <code>'ai-usage.json'</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入用量檔名字串，預設'ai-usage.json'</p></td>
-        </tr>
-
-    
-
-        <tr>
-            
-                <td class="name"><code>getDate</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">function</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>系統日期</code>
+                    <code>'ai-cursor.json'</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入日期函數()=&gt;'YYYY-MM-DD'，預設隨系統時區(排程環境建議注入時區錨定者)</p></td>
+            <td class="description last"><p>輸入狀態檔名字串，預設'ai-cursor.json'</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>keepDays</code></td>
+                <td class="name"><code>ownKeys</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Number</span>
+<span class="param-type">Array</span>
 
 
 
@@ -3205,19 +3014,19 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="default">
                 
-                    <code>14</code>
+                    <code>['at']</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入保留天數正整數，預設14</p></td>
+            <td class="description last"><p>輸入本層自用、不屬於套件狀態之欄位名字串陣列，get時剔除set時補回，預設['at']</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>keyOf</code></td>
+                <td class="name"><code>stamp</code></td>
             
 
             <td class="type">
@@ -3245,12 +3054,12 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="default">
                 
-                    <code>(ev)=>ev.keyId||ev.providerId</code>
+                    <code>ISO時間戳</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入計帳鍵函數(ev)=&gt;String，決定粒度(金鑰或條目)，預設優先keyId</p></td>
+            <td class="description last"><p>輸入時間戳函數()=&gt;String，寫入at欄位用，預設回傳new Date().toISOString()</p></td>
         </tr>
 
     
@@ -3283,7 +3092,7 @@ let usage = createUsageCounter({ dir: './state' })
 
         
 <div class="param-desc">
-    <p>回傳計數器物件，內含onEvent(可直接餵dispatch之onEvent)、bump(手動累加)、today(今日統計)與file(用量檔路徑)</p>
+    <p>回傳store物件，內含get、set(可直接餵dispatchAiFallback之store)與file(狀態檔路徑)</p>
 </div>
 
 
@@ -3310,7 +3119,7 @@ let usage = createUsageCounter({ dir: './state' })
 
     
 
-    <h4 class="name" id="defaultIntegratePrompt"><span class="type-signature"></span>defaultIntegratePrompt<span class="signature">(candidates, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {String}</span></h4>
+    <h4 class="name" id="createUsageCounter"><span class="type-signature"></span>createUsageCounter<span class="signature">(opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Object}</span></h4>
 
     
 
@@ -3320,13 +3129,19 @@ let usage = createUsageCounter({ dir: './state' })
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>預設整合提示詞模板：把成功候選JSON併入整合任務</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>建立逐日、逐鍵之用量計數器(純觀測, 不參與任何判斷)</p>
+<p>特點：
+onEvent可直接掛進dispatchAiFallback/dispatchAiWkf，於type為'try'時依keyOf取鍵累加——
+嘗試時即記帳，行程被外部時限中途砍掉已發出的請求仍有紀錄；
+逐日分桶並僅保留最近keepDays天，避免檔案無限成長；
+getDate可注入時區錨定之日期函數——預設隨系統時區，排程session之系統時區可能為UTC+0
+而使日界錯8小時，排程環境務必注入</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="wkf_runFanout.mjs.html">wkf/runFanout.mjs</a>, <a href="wkf_runFanout.mjs.html#line31">line 31</a>
+        <a href="wkf_createUsageCounter.mjs.html">wkf/createUsageCounter.mjs</a>, <a href="wkf_createUsageCounter.mjs.html#line59">line 59</a>
     </li></ul></dd>
     
 
@@ -3371,6 +3186,16 @@ let usage = createUsageCounter({ dir: './state' })
 
 
 
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>import createUsageCounter from './src/wkf/createUsageCounter.mjs'
+
+let usage = createUsageCounter({ dir: './state' })
+//let r = await dispatchAiFallback(prompt, { providers, onEvent: usage.onEvent })
+//console.log(usage.today())
+// => { today: '2026-08-18', byKey: { 'agnes:agnes-2.5-flash#0': 3 }, total: 3 }</code></pre>
+
+
 
 
     <h5 class="h5-parameters">Parameters:</h5>
@@ -3402,13 +3227,13 @@ let usage = createUsageCounter({ dir: './state' })
 
         <tr>
             
-                <td class="name"><code>candidates</code></td>
+                <td class="name"><code>opt</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Array</span>
+<span class="param-type">Object</span>
 
 
 
@@ -3418,6 +3243,8 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="attributes">
                 
+                    &lt;optional><br>
+                
 
                 
 
@@ -3428,23 +3255,48 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="default">
                 
+                    <code>{}</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入成功候選物件陣列</p></td>
-        </tr>
+            <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>opt</code></td>
+                <td class="name"><code>file</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">String</span>
 
 
 
@@ -3466,186 +3318,59 @@ let usage = createUsageCounter({ dir: './state' })
             
                 <td class="default">
                 
-                    <code>{}</code>
+                    <code>null</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入設定物件(取schema作為輸出格式示意)，預設{}</p></td>
+            <td class="description last"><p>輸入用量檔完整路徑字串，與dir/name二擇一</p></td>
         </tr>
 
     
-    </tbody>
-</table>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-<h5 class="h5-returns">Returns:</h5>
-
-        
-<div class="param-desc">
-    <p>回傳整合提示詞字串</p>
-</div>
-
 
+        <tr>
+            
+                <td class="name"><code>dir</code></td>
+            
 
-<dl class="param-type">
-    <dt>
-        Type
-    </dt>
-    <dd>
-        
+            <td class="type">
+            
+                
 <span class="param-type">String</span>
 
 
 
-    </dd>
-</dl>
-
-    
-
-
-
-        
             
+            </td>
 
-    
-
-    <h4 class="name" id="dispatchAi"><span class="type-signature type-signature-async">(async) </span>dispatchAi<span class="signature">(kind, prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
-
-    
-
-
-
-
-<dl class="details">
-    
-    <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>依供應商種類(kind)分派至對應之轉接器</p>
-<p>kind清單以adapters.mjs對照表為唯一來源(目前為'opencode'、'claude'、'codex'、'antigravity'、
-'api-openai-compat'，CLI或API之選型判準見adapters.mjs檔頭)。
-各家金鑰模式不同(2026-08-08起於本機實測確認)：opencode與api-openai-compat支援逐次注入金鑰，
-故可多把金鑰輪替；claude/codex/antigravity沿用CLI既有登入狀態，無逐次金鑰概念。
-故「輪替」的單位是「供應商條目」而非單純的金鑰：一個條目即一組(kind, model, 可選的key／provider)，
-輪到誰就用誰的轉接器與模型</p></li></ul></dd>
-    
-
-    
-    <dt class="tag-source">Source:</dt>
-    <dd class="tag-source"><ul class="dummy"><li>
-        <a href="dispatchAi.mjs.html">dispatchAi.mjs</a>, <a href="dispatchAi.mjs.html#line44">line 44</a>
-    </li></ul></dd>
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-</dl>
-
-
-
-
-
-
-
-
-
-
-
-    <h5 class="h5-examples">Example</h5>
-    
-    <pre class="prettyprint"><code>//need claude, codex or opencode cli in system PATH
-
-import dispatchAi from './src/dispatchAi.mjs'
-
-let test = async () => {
-
-    let r = await dispatchAi('claude', '請只回覆兩個字：完成', { model: 'sonnet' })
-    console.log(r.ok, r.stdout.trim())
-    // => true '完成'
-
-    let re = await dispatchAi('gemini', 'abc')
-    console.log(re.ok, re.error.indexOf('unknown ai kind: "gemini"') === 0)
-    // => false true
-
-}
-await test()
-    .catch((err) => {
-        console.log(err)
-    })</code></pre>
-
-
-
-
-    <h5 class="h5-parameters">Parameters:</h5>
-    
-
-<table class="params">
-    <thead>
-    <tr>
-        
-        <th>Name</th>
-        
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
 
-        <th>Type</th>
+                
 
-        
-        <th>Attributes</th>
-        
+                
+                </td>
+            
 
-        
-        <th>Default</th>
-        
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
 
-        <th class="last">Description</th>
-    </tr>
-    </thead>
+            <td class="description last"><p>輸入狀態目錄字串</p></td>
+        </tr>
 
-    <tbody>
     
 
         <tr>
             
-                <td class="name"><code>kind</code></td>
+                <td class="name"><code>name</code></td>
             
 
             <td class="type">
@@ -3661,6 +3386,8 @@ await test()
             
                 <td class="attributes">
                 
+                    &lt;optional><br>
+                
 
                 
 
@@ -3671,23 +3398,25 @@ await test()
             
                 <td class="default">
                 
+                    <code>'ai-usage.json'</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入供應商種類字串，須為adapters.mjs對照表之鍵名，目前可選'opencode'、'claude'、'codex'、'antigravity'、'api-openai-compat'</p></td>
+            <td class="description last"><p>輸入用量檔名字串，預設'ai-usage.json'</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>prompt</code></td>
+                <td class="name"><code>getDate</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">String</span>
+<span class="param-type">function</span>
 
 
 
@@ -3697,6 +3426,8 @@ await test()
             
                 <td class="attributes">
                 
+                    &lt;optional><br>
+                
 
                 
 
@@ -3707,23 +3438,25 @@ await test()
             
                 <td class="default">
                 
+                    <code>系統日期</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入提示詞字串</p></td>
+            <td class="description last"><p>輸入日期函數()=&gt;'YYYY-MM-DD'，預設隨系統時區(排程環境建議注入時區錨定者)</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>opt</code></td>
+                <td class="name"><code>keepDays</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">Number</span>
 
 
 
@@ -3745,19 +3478,66 @@ await test()
             
                 <td class="default">
                 
-                    <code>{}</code>
+                    <code>14</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入設定物件，原樣轉傳對應轉接器，各轉接器可用設定詳見dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat，預設{}</p></td>
+            <td class="description last"><p>輸入保留天數正整數，預設14</p></td>
         </tr>
 
     
-    </tbody>
-</table>
-
-
+
+        <tr>
+            
+                <td class="name"><code>keyOf</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">function</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>(ev)=>ev.keyId||ev.providerId</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入計帳鍵函數(ev)=&gt;String，決定粒度(金鑰或條目)，預設優先keyId</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
 
 
 
@@ -3776,7 +3556,7 @@ await test()
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject</p>
+    <p>回傳計數器物件，內含onEvent(可直接餵dispatch之onEvent)、bump(手動累加)、today(今日統計)與file(用量檔路徑)</p>
 </div>
 
 
@@ -3787,7 +3567,7 @@ await test()
     </dt>
     <dd>
         
-<span class="param-type">Promise</span>
+<span class="param-type">Object</span>
 
 
 
@@ -3803,7 +3583,7 @@ await test()
 
     
 
-    <h4 class="name" id="dispatchAiFallback"><span class="type-signature type-signature-async">(async) </span>dispatchAiFallback<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id="defaultIntegratePrompt"><span class="type-signature"></span>defaultIntegratePrompt<span class="signature">(candidates, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {String}</span></h4>
 
     
 
@@ -3813,21 +3593,13 @@ await test()
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>依供應商清單順序自動遞補調用AI，組內多金鑰以游標輪替</p>
-<p>特點：
-providers陣列順序即優先序，排前面的先用；
-條目本身即該次調用之opt(除id與keys外原樣透傳對應轉接器)，與dispatchAi「條目直接當opt」同一約定；
-條目給予keys(多把金鑰)時以游標輪替，某把失敗自動換下一把，全數失敗才遞補下一組；
-與金鑰無關之失敗(逾時/執行檔不存在/參數錯誤/輸出未過驗證/未知kind)直接整組跳過，不逐把空耗；
-跨次執行僅記憶游標(經store注入持久化)，不設金鑰停用清單——額度視窗形態多樣(5小時滾動/逐時/逐日)，
-停用會把已恢復的金鑰閒置，而重探的代價僅一次快速失敗；
-本函數不會reject，一律以結果物件之ok與error欄位回報成敗</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>預設整合提示詞模板：把成功候選JSON併入整合任務</p></li></ul></dd>
     
 
     
     <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#line292">line 292</a>
+        <a href="wkf_runFanout.mjs.html">wkf/runFanout.mjs</a>, <a href="wkf_runFanout.mjs.html#line31">line 31</a>
     </li></ul></dd>
     
 
@@ -3872,48 +3644,6 @@ providers陣列順序即優先序，排前面的先用；
 
 
 
-    <h5 class="h5-examples">Example</h5>
-    
-    <pre class="prettyprint"><code>//need opencode, claude, codex cli in system PATH
-
-import dispatchAiFallback from './src/dispatchAiFallback.mjs'
-
-let test = async () => {
-
-    let r = await dispatchAiFallback('請只回覆兩個字：完成', {
-        providers: [
-            {
-                //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'],
-                timeoutMs: 180000,
-            },
-            { 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 'zen:deepseek-v4-flash-free' 0 1
-
-}
-await test()
-    .catch((err) => {
-        console.log(err)
-    })</code></pre>
-
-
 
 
     <h5 class="h5-parameters">Parameters:</h5>
@@ -3945,13 +3675,13 @@ await test()
 
         <tr>
             
-                <td class="name"><code>prompt</code></td>
+                <td class="name"><code>candidates</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">String</span>
+<span class="param-type">Array</span>
 
 
 
@@ -3974,7 +3704,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入提示詞字串，一律以stdin傳入子進程</p></td>
+            <td class="description last"><p>輸入成功候選物件陣列</p></td>
         </tr>
 
     
@@ -4014,227 +3744,187 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入設定物件，預設{}</p>
-                <h6>Properties</h6>
-                
+            <td class="description last"><p>輸入設定物件(取schema作為輸出格式示意)，預設{}</p></td>
+        </tr>
 
-<table class="params">
-    <thead>
-    <tr>
-        
-        <th>Name</th>
-        
+    
+    </tbody>
+</table>
 
-        <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>輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器</p>
-                <h6>Properties</h6>
-                
 
-<table class="params">
-    <thead>
-    <tr>
-        
-        <th>Name</th>
+<h5 class="h5-returns">Returns:</h5>
+
         
+<div class="param-desc">
+    <p>回傳整合提示詞字串</p>
+</div>
 
-        <th>Type</th>
 
-        
-        <th>Attributes</th>
-        
 
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
         
-        <th>Default</th>
-        
+<span class="param-type">String</span>
 
-        <th class="last">Description</th>
-    </tr>
-    </thead>
 
-    <tbody>
-    
 
-        <tr>
-            
-                <td class="name"><code>id</code></td>
-            
+    </dd>
+</dl>
 
-            <td class="type">
-            
-                
-<span class="param-type">String</span>
+    
 
 
 
+        
             
-            </td>
 
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
+    
 
-                
+    <h4 class="name" id="dispatchAi"><span class="type-signature type-signature-async">(async) </span>dispatchAi<span class="signature">(kind, prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+
+    
 
-                
-                </td>
-            
 
-            
-                <td class="default">
-                
-                    <code>條目索引字串</code>
-                
-                </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>
 
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>依供應商種類(kind)分派至對應之轉接器</p>
+<p>kind清單以adapters.mjs對照表為唯一來源(目前為'opencode'、'claude'、'codex'、'antigravity'、
+'api-openai-compat'，CLI或API之選型判準見adapters.mjs檔頭)。
+各家金鑰模式不同(2026-08-08起於本機實測確認)：opencode與api-openai-compat支援逐次注入金鑰，
+故可多把金鑰輪替；claude/codex/antigravity沿用CLI既有登入狀態，無逐次金鑰概念。
+故「輪替」的單位是「供應商條目」而非單純的金鑰：一個條目即一組(kind, model, 可選的key／provider)，
+輪到誰就用誰的轉接器與模型</p></li></ul></dd>
     
 
-        <tr>
-            
-                <td class="name"><code>keys</code></td>
-            
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="dispatchAi.mjs.html">dispatchAi.mjs</a>, <a href="dispatchAi.mjs.html#line44">line 44</a>
+    </li></ul></dd>
+    
 
-            <td class="type">
-            
-                
-<span class="param-type">Array</span>
+    
 
+    
 
+    
 
-            
-            </td>
+    
 
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
+    
 
-                
+    
 
-                
-                </td>
-            
+    
 
-            
-                <td class="default">
-                
-                    <code>[]</code>
-                
-                </td>
-            
+    
 
-            <td class="description last"><p>輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰</p></td>
-        </tr>
+    
 
     
 
-        <tr>
-            
-                <td class="name"><code>meta</code></td>
-            
+    
 
-            <td class="type">
-            
-                
-<span class="param-type">*</span>
+    
 
+    
 
+    
+
+    
+</dl>
 
-            
-            </td>
 
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
 
-                
 
-                
-                </td>
-            
 
-            
-                <td class="default">
-                
-                </td>
-            
 
-            <td class="description last"><p>輸入呼叫端自有資訊(分類、標籤、註記)，保留鍵保證永不轉傳對應轉接器——條目其餘鍵一律原樣轉傳，自有欄位放此鍵可與轉傳機制永久絕緣，預設undefined</p></td>
-        </tr>
 
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
     
-    </tbody>
-</table>
+    <pre class="prettyprint"><code>//need claude, codex or opencode cli in system PATH
 
-            </td>
-        </tr>
+import dispatchAi from './src/dispatchAi.mjs'
+
+let test = async () => {
+
+    let r = await dispatchAi('claude', '請只回覆兩個字：完成', { model: 'sonnet' })
+    console.log(r.ok, r.stdout.trim())
+    // => true '完成'
+
+    let re = await dispatchAi('gemini', 'abc')
+    console.log(re.ok, re.error.indexOf('unknown ai kind: "gemini"') === 0)
+    // => false true
+
+}
+await test()
+    .catch((err) => {
+        console.log(err)
+    })</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>budgetMs</code></td>
+                <td class="name"><code>kind</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Number</span>
+<span class="param-type">String</span>
 
 
 
@@ -4244,8 +3934,6 @@ await test()
             
                 <td class="attributes">
                 
-                    &lt;optional><br>
-                
 
                 
 
@@ -4256,25 +3944,23 @@ await test()
             
                 <td class="default">
                 
-                    <code>null</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限</p></td>
+            <td class="description last"><p>輸入供應商種類字串，須為adapters.mjs對照表之鍵名，目前可選'opencode'、'claude'、'codex'、'antigravity'、'api-openai-compat'</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>minAttemptMs</code></td>
+                <td class="name"><code>prompt</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Number</span>
+<span class="param-type">String</span>
 
 
 
@@ -4284,8 +3970,6 @@ await test()
             
                 <td class="attributes">
                 
-                    &lt;optional><br>
-                
 
                 
 
@@ -4296,19 +3980,17 @@ await test()
             
                 <td class="default">
                 
-                    <code>20000</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000</p></td>
+            <td class="description last"><p>輸入提示詞字串</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>store</code></td>
+                <td class="name"><code>opt</code></td>
             
 
             <td class="type">
@@ -4336,65 +4018,1433 @@ await test()
             
                 <td class="default">
                 
-                    <code>null</code>
+                    <code>{}</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入狀態持久化物件{get:()=&gt;state,set:(state)=&gt;{}}，state內含cursors(逐群組游標)與cooling(供應商冷卻時間戳，僅cooldownMs&gt;0時使用)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖</p></td>
+            <td class="description last"><p>輸入設定物件，原樣轉傳對應轉接器，各轉接器可用設定詳見dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat，預設{}</p></td>
         </tr>
 
     
+    </tbody>
+</table>
 
-        <tr>
-            
-                <td class="name"><code>cooldownMs</code></td>
-            
 
-            <td class="type">
-            
-                
-<span class="param-type">Number</span>
 
 
 
-            
-            </td>
 
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
 
-                
 
-                
-                </td>
-            
 
-            
-                <td class="default">
-                
-                    <code>0</code>
-                
-                </td>
-            
 
-            <td class="description last"><p>輸入供應商冷卻視窗毫秒非負整數，&gt;0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測；CLI類可經coolDetect注入判定)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用</p></td>
-        </tr>
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Promise</span>
+
+
+
+    </dd>
+</dl>
 
     
 
-        <tr>
-            
-                <td class="name"><code>coolDetect</code></td>
-            
 
-            <td class="type">
+
+        
             
-                
-<span class="param-type">function</span>
+
+    
+
+    <h4 class="name" id="dispatchAiFallback"><span class="type-signature type-signature-async">(async) </span>dispatchAiFallback<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>依供應商清單順序自動遞補調用AI，組內多金鑰以游標輪替</p>
+<p>特點：
+providers陣列順序即優先序，排前面的先用；
+條目本身即該次調用之opt(除id與keys外原樣透傳對應轉接器)，與dispatchAi「條目直接當opt」同一約定；
+條目給予keys(多把金鑰)時以游標輪替，某把失敗自動換下一把，全數失敗才遞補下一組；
+與金鑰無關之失敗(逾時/執行檔不存在/參數錯誤/輸出未過驗證/未知kind)直接整組跳過，不逐把空耗；
+跨次執行僅記憶游標(經store注入持久化)，不設金鑰停用清單——額度視窗形態多樣(5小時滾動/逐時/逐日)，
+停用會把已恢復的金鑰閒置，而重探的代價僅一次快速失敗；
+本函數不會reject，一律以結果物件之ok與error欄位回報成敗</p></li></ul></dd>
+    
+
+    
+    <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#line292">line 292</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>//need opencode, claude, codex cli in system PATH
+
+import dispatchAiFallback from './src/dispatchAiFallback.mjs'
+
+let test = async () => {
+
+    let r = await dispatchAiFallback('請只回覆兩個字：完成', {
+        providers: [
+            {
+                //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'],
+                timeoutMs: 180000,
+            },
+            { 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 'zen:deepseek-v4-flash-free' 0 1
+
+}
+await test()
+    .catch((err) => {
+        console.log(err)
+    })</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>prompt</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">String</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入提示詞字串，一律以stdin傳入子進程</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>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>輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器</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>id</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">String</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>條目索引字串</code>
+                
+                </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>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>keys</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>[]</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>meta</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">*</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入呼叫端自有資訊(分類、標籤、註記)，保留鍵保證永不轉傳對應轉接器——條目其餘鍵一律原樣轉傳，自有欄位放此鍵可與轉傳機制永久絕緣，預設undefined</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>budgetMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>minAttemptMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>20000</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>store</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入狀態持久化物件{get:()=&gt;state,set:(state)=&gt;{}}，state內含cursors(逐群組游標)與cooling(供應商冷卻時間戳，僅cooldownMs&gt;0時使用)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>cooldownMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>0</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入供應商冷卻視窗毫秒非負整數，&gt;0啟用：條目(限有明給id者)遭遇限流(HTTP 429，僅api類可偵測；CLI類可經coolDetect注入判定)或逾時(TIMEOUT開頭)後，於冷卻視窗內之後續呼叫中被移至鏈尾——只降序不移除，前面全敗時仍會被嘗試，任一次成功立即解除；注意啟用時「providers順序即優先序」會被暫時重排，此即本機制之目的；預設0代表不啟用</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>coolDetect</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">function</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入冷卻觸發判定函數(r)=&gt;Boolean，收完整失敗結果物件(含stdout、stderr、code、error)，回傳true即視同冷卻觸發(內建429/TIMEOUT觸發不受影響)——CLI類限流埋在stderr且各家字樣不同，簽章表由觀察到字樣的呼叫端維護，如(r)=&gt;/FreeUsageLimitError/i.test(r.stderr||'')；僅cooldownMs&gt;0時有效，回調拋出例外視同false，預設null</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>shouldStop</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">function</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入中止判定函數()=&gt;Boolean，於每次嘗試之間檢查，回傳true即停止遞補回報ABORTED(不中止進行中之嘗試)——供呼叫端於成果已無人接收時(如客戶端斷線)止損；經工作流層原樣轉傳，中止後各後續呼叫進門即回ABORTED令整條工作流快速收束；回調拋出例外視同false，預設null</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>meta</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">*</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入呼叫端自有資訊，保留鍵保證永不轉傳各轉接器，預設undefined</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>onEvent</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">function</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入事件回調函數(ev)=&gt;{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs&gt;0時出現)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>timeoutMs</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>300000</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>validate</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">String</span>
+|
+
+<span class="param-type">function</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>maxRetries</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>0</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入各attempt共用之同家重試次數非負整數，韌性建議交給換家而非重試同一家，預設0</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳；失敗項含errorType、stdout與stderr供診斷被拒原因)；失敗結果帶機器可讀之errorType(一覽見getErrorType.mjs檔頭)；api類轉接器提供usage(token用量)時原樣流出於結果與tried各項，CLI類無此欄；本函數不會reject</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Promise</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
+    <h4 class="name" id="dispatchAiWkf"><span class="type-signature"></span>dispatchAiWkf<span class="signature">(opt)</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>建立AI工作流執行環境(工廠)，注入provider定義表與共用預設後回傳綁定版API</p>
+<p>特點：
+providers為名稱對dispatchAiFallback條目之定義表，之後各工作流以名稱宣告主模型與遞補鏈；
+defaults為共用呼叫設定，各工作流之callOpt與名額規格可逐項覆寫；
+回傳之各函數皆不reject；本工廠為同步函數，providers無效時throw(設定錯誤應於啟動期即失敗)</p></li></ul></dd>
+    
+
+    
+    <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#line106">line 106</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>//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)
+    })</code></pre>
+
+
+
+
+    <h5 class="h5-parameters">Parameters:</h5>
+    
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>opt</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </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>providers</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Object</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入provider定義表物件(名稱 → dispatchAiFallback條目：{ kind, model, keys, exe, provider, config, sandbox, extraArgs... })</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>defaults</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>輸入共用呼叫設定物件(cwd、store、onEvent、timeoutMs、budgetMs、maxRetries、promptPrefix、parse等)，預設{}</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+            </td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳綁定版API物件，內含callAi(單一名額呼叫)、runFanout(多開＋整合)、runRolePipeline(串行角色鏈)、runFanoutPipeline(多開＋整合＋角色鏈)、providers(定義表原樣)</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Object</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
+    <h4 class="name" id="dispatchAntigravity"><span class="type-signature type-signature-async">(async) </span>dispatchAntigravity<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>以Google Antigravity CLI(agy)呼叫AI模型</p>
+<p>特點：
+prompt作為<code>--print</code>旗標之值傳遞而非stdin(agy介面如此，塞stdin會進互動模式卡住)，
+故prompt受命令列長度上限約束，超過30000字元回傳錯誤結果物件；
+model須為<code>agy models</code>第一欄之slug(如gemini-3.6-flash-low)，注意agy錯誤訊息列出的是顯示名稱而非slug；
+帶檔位之slug(-high/-medium/-low結尾)與effort同時給定且檔位不一致時agy回conflicts錯誤(一致則放行)，
+effort需agy&gt;=1.1.11，建議搭配不帶檔位之基礎slug(如gemini-3.1-pro)使用；
+預設帶<code>--dangerously-skip-permissions</code>令非互動print模式不卡權限確認，可給予skipPermissions為false保留權限閘門；
+agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令CLI先於外層逾時；
+沿用agy既有OAuth登入狀態(首次須於桌面互動模式完成登入)；
+本函數不會reject，一律以結果物件之ok與error欄位回報成敗</p></li></ul></dd>
+    
+
+    
+    <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#line106">line 106</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>//need agy cli in system PATH, and OAuth login completed
+
+import dispatchAntigravity from './src/dispatchAntigravity.mjs'
+
+let test = async () => {
+
+    let r = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.6-flash-low' })
+    console.log(r.ok, r.stdout.trim())
+    // => true 完成
+
+    //基礎slug搭配effort(不可用帶檔位之slug併用effort)
+    let r2 = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.1-pro', effort: 'low' })
+    console.log(r2.ok)
+    // => true
+
+    let re = await dispatchAntigravity('')
+    console.log(re.ok, re.error)
+    // => false 'prompt must be a non-empty string'
+
+}
+await test()
+    .catch((err) => {
+        console.log(err)
+    })</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>prompt</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">String</span>
 
 
 
@@ -4404,8 +5454,6 @@ await test()
             
                 <td class="attributes">
                 
-                    &lt;optional><br>
-                
 
                 
 
@@ -4416,25 +5464,23 @@ await test()
             
                 <td class="default">
                 
-                    <code>null</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入冷卻觸發判定函數(r)=&gt;Boolean，收完整失敗結果物件(含stdout、stderr、code、error)，回傳true即視同冷卻觸發(內建429/TIMEOUT觸發不受影響)——CLI類限流埋在stderr且各家字樣不同，簽章表由觀察到字樣的呼叫端維護，如(r)=&gt;/FreeUsageLimitError/i.test(r.stderr||'')；僅cooldownMs&gt;0時有效，回調拋出例外視同false，預設null</p></td>
+            <td class="description last"><p>輸入提示詞字串，作為<code>--print</code>旗標之值傳遞，長度上限30000字元</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>shouldStop</code></td>
+                <td class="name"><code>opt</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">function</span>
+<span class="param-type">Object</span>
 
 
 
@@ -4456,25 +5502,48 @@ await test()
             
                 <td class="default">
                 
-                    <code>null</code>
+                    <code>{}</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入中止判定函數()=&gt;Boolean，於每次嘗試之間檢查，回傳true即停止遞補回報ABORTED(不中止進行中之嘗試)——供呼叫端於成果已無人接收時(如客戶端斷線)止損；經工作流層原樣轉傳，中止後各後續呼叫進門即回ABORTED令整條工作流快速收束；回調拋出例外視同false，預設null</p></td>
-        </tr>
+            <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>meta</code></td>
+                <td class="name"><code>exe</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">*</span>
+<span class="param-type">String</span>
 
 
 
@@ -4496,23 +5565,25 @@ await test()
             
                 <td class="default">
                 
+                    <code>'agy'</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入呼叫端自有資訊，保留鍵保證永不轉傳各轉接器，預設undefined</p></td>
+            <td class="description last"><p>輸入agy執行檔名稱或絕對路徑字串，命令名為agy非antigravity，給予名稱時由execCli自系統PATH解析，預設'agy'</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>onEvent</code></td>
+                <td class="name"><code>model</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">function</span>
+<span class="param-type">String</span>
 
 
 
@@ -4534,25 +5605,25 @@ await test()
             
                 <td class="default">
                 
-                    <code>null</code>
+                    <code>''</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入事件回調函數(ev)=&gt;{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'、'aborted'、'cooled'(冷卻觸發，帶error與cooldownMs，僅cooldownMs&gt;0時出現)；失敗事件(next-key/skip-group)另帶errorType、stdout(被拒回覆)與stderr(錯誤輸出)供診斷，後兩者於失敗路徑已由轉接器截斷；回調拋出例外不影響主流程，預設null</p></td>
+            <td class="description last"><p>輸入模型slug字串，須為<code>agy models</code>第一欄之slug，例如'gemini-3.6-flash-low'、'gemini-3.1-pro-high'，預設''代表不帶<code>--model</code>旗標由agy自行決定</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>timeoutMs</code></td>
+                <td class="name"><code>effort</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Number</span>
+<span class="param-type">String</span>
 
 
 
@@ -4574,28 +5645,25 @@ await test()
             
                 <td class="default">
                 
-                    <code>300000</code>
+                    <code>''</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入各attempt共用之逾時毫秒正整數，條目可覆寫，全套件統一預設300000</p></td>
+            <td class="description last"><p>輸入推理深度字串，可選'low'、'medium'、'high'，需agy&gt;=1.1.11，建議搭配不帶檔位之基礎slug；與帶檔位slug併用且檔位不一致時agy回conflicts錯誤，預設''代表不帶</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>validate</code></td>
+                <td class="name"><code>skipPermissions</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">String</span>
-|
-
-<span class="param-type">function</span>
+<span class="param-type">Boolean</span>
 
 
 
@@ -4617,23 +5685,25 @@ await test()
             
                 <td class="default">
                 
+                    <code>true</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined</p></td>
+            <td class="description last"><p>輸入是否帶<code>--dangerously-skip-permissions</code>旗標布林值，false代表保留CLI權限閘門，預設true</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>maxRetries</code></td>
+                <td class="name"><code>printTimeout</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Number</span>
+<span class="param-type">String</span>
 
 
 
@@ -4655,217 +5725,105 @@ await test()
             
                 <td class="default">
                 
-                    <code>0</code>
+                    <code>''</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入各attempt共用之同家重試次數非負整數，韌性建議交給換家而非重試同一家，預設0</p></td>
-        </tr>
-
-    
-    </tbody>
-</table>
-
-            </td>
+            <td class="description last"><p>輸入agy自身等待上限字串(如'10m'、'570s')，預設''代表由timeoutMs推導(扣30秒緩衝，下限30秒)</p></td>
         </tr>
 
     
-    </tbody>
-</table>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-<h5 class="h5-returns">Returns:</h5>
-
-        
-<div class="param-desc">
-    <p>回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳；失敗項含errorType、stdout與stderr供診斷被拒原因)；失敗結果帶機器可讀之errorType(一覽見getErrorType.mjs檔頭)；api類轉接器提供usage(token用量)時原樣流出於結果與tried各項，CLI類無此欄；本函數不會reject</p>
-</div>
-
-
-
-<dl class="param-type">
-    <dt>
-        Type
-    </dt>
-    <dd>
-        
-<span class="param-type">Promise</span>
-
-
-
-    </dd>
-</dl>
-
-    
-
 
-
-        
+        <tr>
+            
+                <td class="name"><code>addDirs</code></td>
             
 
-    
-
-    <h4 class="name" id="dispatchAiWkf"><span class="type-signature"></span>dispatchAiWkf<span class="signature">(opt)</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>建立AI工作流執行環境(工廠)，注入provider定義表與共用預設後回傳綁定版API</p>
-<p>特點：
-providers為名稱對dispatchAiFallback條目之定義表，之後各工作流以名稱宣告主模型與遞補鏈；
-defaults為共用呼叫設定，各工作流之callOpt與名額規格可逐項覆寫；
-回傳之各函數皆不reject；本工廠為同步函數，providers無效時throw(設定錯誤應於啟動期即失敗)</p></li></ul></dd>
-    
-
-    
-    <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#line106">line 106</a>
-    </li></ul></dd>
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-</dl>
-
-
-
-
-
-
-
-
-
-
-
-    <h5 class="h5-examples">Example</h5>
-    
-    <pre class="prettyprint"><code>//need cli in system PATH
-
-import dispatchAiWkf from './src/dispatchAiWkf.mjs'
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
 
-//定義表之鍵名即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 }
+            
+            </td>
 
-    //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
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
 
-}
-await test()
-    .catch((err) => {
-        console.log(err)
-    })</code></pre>
+                
 
+                
+                </td>
+            
 
+            
+                <td class="default">
+                
+                    <code>自動納入cwd</code>
+                
+                </td>
+            
 
+            <td class="description last"><p>輸入加入workspace之目錄字串陣列，逐項展開為<code>--add-dir</code>。agy以自身scratch目錄為工作區而不採子進程cwd，故未給本參數時自動納入有效cwd令檔案可視範圍與其他CLI轉接器一致；明示給陣列(含空陣列[]代表不揭露任何目錄)則完全尊重呼叫端</p></td>
+        </tr>
 
-    <h5 class="h5-parameters">Parameters:</h5>
     
 
-<table class="params">
-    <thead>
-    <tr>
-        
-        <th>Name</th>
-        
+        <tr>
+            
+                <td class="name"><code>extraArgs</code></td>
+            
 
-        <th>Type</th>
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
 
-        
 
-        
 
-        <th class="last">Description</th>
-    </tr>
-    </thead>
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>[]</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入額外命令列旗標字串陣列(如--output-format、--json-schema、--mode)，將接於固定旗標之後、<code>--print</code>之前，預設[]</p></td>
+        </tr>
 
-    <tbody>
     
 
         <tr>
             
-                <td class="name"><code>opt</code></td>
+                <td class="name"><code>timeoutMs</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">Number</span>
 
 
 
@@ -4873,46 +5831,82 @@ await test()
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
+                <td class="default">
+                
+                    <code>300000</code>
+                
+                </td>
+            
 
-            <td class="description last"><p>輸入設定物件</p>
-                <h6>Properties</h6>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000(恰對齊agy自身print-timeout預設5m0s)</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>cwd</code></td>
+            
+
+            <td class="type">
+            
                 
+<span class="param-type">String</span>
 
-<table class="params">
-    <thead>
-    <tr>
-        
-        <th>Name</th>
-        
 
-        <th>Type</th>
 
-        
-        <th>Attributes</th>
-        
+            
+            </td>
 
-        
-        <th>Default</th>
-        
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
 
-        <th class="last">Description</th>
-    </tr>
-    </thead>
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>process.cwd()</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入子進程工作目錄字串，預設process.cwd()。注意本參數不影響agy之檔案可視範圍(agy以自身scratch目錄為工作區)，可視範圍由addDirs決定(未給addDirs時自動納入本目錄)</p></td>
+        </tr>
 
-    <tbody>
     
 
         <tr>
             
-                <td class="name"><code>providers</code></td>
+                <td class="name"><code>validate</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">String</span>
+|
+
+<span class="param-type">function</span>
 
 
 
@@ -4922,6 +5916,8 @@ await test()
             
                 <td class="attributes">
                 
+                    &lt;optional><br>
+                
 
                 
 
@@ -4935,20 +5931,20 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入provider定義表物件(名稱 → dispatchAiFallback條目：{ kind, model, keys, exe, provider, config, sandbox, extraArgs... })</p></td>
+            <td class="description last"><p>輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>defaults</code></td>
+                <td class="name"><code>maxRetries</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Object</span>
+<span class="param-type">Number</span>
 
 
 
@@ -4970,12 +5966,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>{}</code>
+                    <code>0</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入共用呼叫設定物件(cwd、store、onEvent、timeoutMs、budgetMs、maxRetries、promptPrefix、parse等)，預設{}</p></td>
+            <td class="description last"><p>輸入失敗後最大重試次數非負整數，預設0</p></td>
         </tr>
 
     
@@ -5008,7 +6004,7 @@ await test()
 
         
 <div class="param-desc">
-    <p>回傳綁定版API物件，內含callAi(單一名額呼叫)、runFanout(多開＋整合)、runRolePipeline(串行角色鏈)、runFanoutPipeline(多開＋整合＋角色鏈)、providers(定義表原樣)</p>
+    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject</p>
 </div>
 
 
@@ -5019,7 +6015,7 @@ await test()
     </dt>
     <dd>
         
-<span class="param-type">Object</span>
+<span class="param-type">Promise</span>
 
 
 
@@ -5035,7 +6031,7 @@ await test()
 
     
 
-    <h4 class="name" id="dispatchAntigravity"><span class="type-signature type-signature-async">(async) </span>dispatchAntigravity<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id="dispatchApiOpenaiCompat"><span class="type-signature type-signature-async">(async) </span>dispatchApiOpenaiCompat<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -5045,23 +6041,21 @@ await test()
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>以Google Antigravity CLI(agy)呼叫AI模型</p>
+    <dd class="tag-description"><ul class="dummy"><li><p>以fetch直呼OpenAI相容API(chat/completions)呼叫AI模型</p>
 <p>特點：
-prompt作為<code>--print</code>旗標之值傳遞而非stdin(agy介面如此，塞stdin會進互動模式卡住)，
-故prompt受命令列長度上限約束，超過30000字元回傳錯誤結果物件；
-model須為<code>agy models</code>第一欄之slug(如gemini-3.6-flash-low)，注意agy錯誤訊息列出的是顯示名稱而非slug；
-帶檔位之slug(-high/-medium/-low結尾)與effort同時給定且檔位不一致時agy回conflicts錯誤(一致則放行)，
-effort需agy&gt;=1.1.11，建議搭配不帶檔位之基礎slug(如gemini-3.1-pro)使用；
-預設帶<code>--dangerously-skip-permissions</code>令非互動print模式不卡權限確認，可給予skipPermissions為false保留權限閘門；
-agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令CLI先於外層逾時；
-沿用agy既有OAuth登入狀態(首次須於桌面互動模式完成登入)；
+免安裝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')使用；
 本函數不會reject，一律以結果物件之ok與error欄位回報成敗</p></li></ul></dd>
     
 
     
     <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#line106">line 106</a>
+        <a href="dispatchApiOpenaiCompat.mjs.html">dispatchApiOpenaiCompat.mjs</a>, <a href="dispatchApiOpenaiCompat.mjs.html#line261">line 261</a>
     </li></ul></dd>
     
 
@@ -5108,24 +6102,33 @@ agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令
 
     <h5 class="h5-examples">Example</h5>
     
-    <pre class="prettyprint"><code>//need agy cli in system PATH, and OAuth login completed
+    <pre class="prettyprint"><code>//need network, no cli required
 
-import dispatchAntigravity from './src/dispatchAntigravity.mjs'
+import dispatchApiOpenaiCompat from './src/dispatchApiOpenaiCompat.mjs'
 
 let test = async () => {
 
-    let r = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.6-flash-low' })
-    console.log(r.ok, r.stdout.trim())
+    //OpenCode Zen(即opencode CLI之自家閘道), 模型名不帶opencode/前綴
+    let r1 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
+        baseURL: 'https://opencode.ai/zen/v1',
+        key: 'sk-xxxxxx',
+        model: 'deepseek-v4-flash-free',
+    })
+    console.log(r1.ok, r1.stdout.trim())
     // => true 完成
 
-    //基礎slug搭配effort(不可用帶檔位之slug併用effort)
-    let r2 = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.1-pro', effort: 'low' })
-    console.log(r2.ok)
-    // => true
+    //Agnes
+    let r2 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
+        baseURL: 'https://apihub.agnes-ai.com/v1',
+        key: 'sk-xxxxxx',
+        model: 'agnes-2.0-flash',
+    })
+    console.log(r2.ok, r2.stdout.trim())
+    // => true 完成
 
-    let re = await dispatchAntigravity('')
-    console.log(re.ok, re.error)
-    // => false 'prompt must be a non-empty string'
+    let re = await dispatchApiOpenaiCompat('abc', { baseURL: 'https://opencode.ai/zen/v1', key: 'sk-bad', model: 'deepseek-v4-flash-free' })
+    console.log(re.ok, re.code, re.error)
+    // => false 401 HTTP 401
 
 }
 await test()
@@ -5194,7 +6197,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入提示詞字串，作為<code>--print</code>旗標之值傳遞，長度上限30000字元</p></td>
+            <td class="description last"><p>輸入提示詞字串，作為user訊息置於HTTP body</p></td>
         </tr>
 
     
@@ -5264,47 +6267,7 @@ await test()
 
         <tr>
             
-                <td class="name"><code>exe</code></td>
-            
-
-            <td class="type">
-            
-                
-<span class="param-type">String</span>
-
-
-
-            
-            </td>
-
-            
-                <td class="attributes">
-                
-                    &lt;optional><br>
-                
-
-                
-
-                
-                </td>
-            
-
-            
-                <td class="default">
-                
-                    <code>'agy'</code>
-                
-                </td>
-            
-
-            <td class="description last"><p>輸入agy執行檔名稱或絕對路徑字串，命令名為agy非antigravity，給予名稱時由execCli自系統PATH解析，預設'agy'</p></td>
-        </tr>
-
-    
-
-        <tr>
-            
-                <td class="name"><code>model</code></td>
+                <td class="name"><code>baseURL</code></td>
             
 
             <td class="type">
@@ -5320,8 +6283,6 @@ await test()
             
                 <td class="attributes">
                 
-                    &lt;optional><br>
-                
 
                 
 
@@ -5332,19 +6293,17 @@ await test()
             
                 <td class="default">
                 
-                    <code>''</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入模型slug字串，須為<code>agy models</code>第一欄之slug，例如'gemini-3.6-flash-low'、'gemini-3.1-pro-high'，預設''代表不帶<code>--model</code>旗標由agy自行決定</p></td>
+            <td class="description last"><p>輸入API基底網址字串，例如'https://opencode.ai/zen/v1'、'https://apihub.agnes-ai.com/v1'，將於尾端接上/chat/completions</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>effort</code></td>
+                <td class="name"><code>model</code></td>
             
 
             <td class="type">
@@ -5360,8 +6319,6 @@ await test()
             
                 <td class="attributes">
                 
-                    &lt;optional><br>
-                
 
                 
 
@@ -5372,25 +6329,23 @@ await test()
             
                 <td class="default">
                 
-                    <code>''</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入推理深度字串，可選'low'、'medium'、'high'，需agy&gt;=1.1.11，建議搭配不帶檔位之基礎slug；與帶檔位slug併用且檔位不一致時agy回conflicts錯誤，預設''代表不帶</p></td>
+            <td class="description last"><p>輸入模型ID字串，例如'deepseek-v4-flash-free'(Zen之模型名不帶opencode/前綴)、'agnes-2.0-flash'</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>skipPermissions</code></td>
+                <td class="name"><code>key</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Boolean</span>
+<span class="param-type">String</span>
 
 
 
@@ -5412,19 +6367,19 @@ await test()
             
                 <td class="default">
                 
-                    <code>true</code>
+                    <code>''</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入是否帶<code>--dangerously-skip-permissions</code>旗標布林值，false代表保留CLI權限閘門，預設true</p></td>
+            <td class="description last"><p>輸入API key字串，以Bearer置於Authorization標頭，預設''代表不帶認證標頭</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>printTimeout</code></td>
+                <td class="name"><code>system</code></td>
             
 
             <td class="type">
@@ -5457,20 +6412,20 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入agy自身等待上限字串(如'10m'、'570s')，預設''代表由timeoutMs推導(扣30秒緩衝，下限30秒)</p></td>
+            <td class="description last"><p>輸入system提示詞字串，將以system角色置於messages首位，預設''代表不帶</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>addDirs</code></td>
+                <td class="name"><code>body</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Array</span>
+<span class="param-type">Object</span>
 
 
 
@@ -5492,25 +6447,25 @@ await test()
             
                 <td class="default">
                 
-                    <code>自動納入cwd</code>
+                    <code>{}</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入加入workspace之目錄字串陣列，逐項展開為<code>--add-dir</code>。agy以自身scratch目錄為工作區而不採子進程cwd，故未給本參數時自動納入有效cwd令檔案可視範圍與其他CLI轉接器一致；明示給陣列(含空陣列[]代表不揭露任何目錄)則完全尊重呼叫端</p></td>
+            <td class="description last"><p>輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}。注意本轉接器不支援工具，帶入tools而模型回tool_calls時一律以TOOL_CALLS_UNSUPPORTED回報失敗，需要工具請改用CLI類kind</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>extraArgs</code></td>
+                <td class="name"><code>headers</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">Array</span>
+<span class="param-type">Object</span>
 
 
 
@@ -5532,12 +6487,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>[]</code>
+                    <code>{}</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入額外命令列旗標字串陣列(如--output-format、--json-schema、--mode)，將接於固定旗標之後、<code>--print</code>之前，預設[]</p></td>
+            <td class="description last"><p>輸入額外請求標頭物件，預設{}</p></td>
         </tr>
 
     
@@ -5577,20 +6532,23 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，全套件統一預設300000(恰對齊agy自身print-timeout預設5m0s)</p></td>
+            <td class="description last"><p>輸入逾時毫秒正整數，逾時將中止請求(含回應串流讀取)，全套件統一預設300000</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>cwd</code></td>
+                <td class="name"><code>validate</code></td>
             
 
             <td class="type">
             
                 
 <span class="param-type">String</span>
+|
+
+<span class="param-type">function</span>
 
 
 
@@ -5612,28 +6570,23 @@ await test()
             
                 <td class="default">
                 
-                    <code>process.cwd()</code>
-                
                 </td>
             
 
-            <td class="description last"><p>輸入子進程工作目錄字串，預設process.cwd()。注意本參數不影響agy之檔案可視範圍(agy以自身scratch目錄為工作區)，可視範圍由addDirs決定(未給addDirs時自動納入本目錄)</p></td>
+            <td class="description last"><p>輸入回覆內容驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>validate</code></td>
+                <td class="name"><code>maxRetries</code></td>
             
 
             <td class="type">
             
                 
-<span class="param-type">String</span>
-|
-
-<span class="param-type">function</span>
+<span class="param-type">Number</span>
 
 
 
@@ -5655,17 +6608,19 @@ await test()
             
                 <td class="default">
                 
+                    <code>0</code>
+                
                 </td>
             
 
-            <td class="description last"><p>輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證</p></td>
+            <td class="description last"><p>輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0</p></td>
         </tr>
 
     
 
         <tr>
             
-                <td class="name"><code>maxRetries</code></td>
+                <td class="name"><code>retryDelayMs</code></td>
             
 
             <td class="type">
@@ -5693,12 +6648,12 @@ await test()
             
                 <td class="default">
                 
-                    <code>0</code>
+                    <code>5000</code>
                 
                 </td>
             
 
-            <td class="description last"><p>輸入失敗後最大重試次數非負整數，預設0</p></td>
+            <td class="description last"><p>輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000</p></td>
         </tr>
 
     
@@ -5731,7 +6686,7 @@ await test()
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject</p>
+    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，無則null)，本函數不會reject</p>
 </div>
 
 
@@ -5758,7 +6713,7 @@ await test()
 
     
 
-    <h4 class="name" id="dispatchApiOpenaiCompat"><span class="type-signature type-signature-async">(async) </span>dispatchApiOpenaiCompat<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
+    <h4 class="name" id="dispatchApiOpenaiResponses"><span class="type-signature type-signature-async">(async) </span>dispatchApiOpenaiResponses<span class="signature">(prompt, opt<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
 
     
 
@@ -5768,21 +6723,21 @@ await test()
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>以fetch直呼OpenAI相容API(chat/completions)呼叫AI模型</p>
+    <dd class="tag-description"><ul class="dummy"><li><p>以fetch直呼OpenAI Responses API(/responses)呼叫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')使用；
+免安裝CLI、免預先登入，給baseURL＋key＋model即可呼叫(如OpenCode Zen之muse-spark系與GPT系)；
+端點型別與dispatchApiOpenaiCompat不同——Zen之端點依模型家族而異，收錄前須查官方文件端點欄
+(https://opencode.ai/docs/zh-tw/zen/)，打錯端點會得到HTTP 500而非404，詳見providers.mjs檔頭；
+僅供純文字生成，需要工具能力請改用CLI類kind(opencode/claude/codex/antigravity)；
+status非completed(如max_output_tokens耗盡)一律以INCOMPLETE_RESPONSE回報，不回半截內容；
+結果結構與dispatchApiOpenaiCompat完全一致，可直接作為dispatchAi與dispatchAiFallback之kind('api-openai-responses')使用；
 本函數不會reject，一律以結果物件之ok與error欄位回報成敗</p></li></ul></dd>
     
 
     
     <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#line325">line 325</a>
+        <a href="dispatchApiOpenaiResponses.mjs.html">dispatchApiOpenaiResponses.mjs</a>, <a href="dispatchApiOpenaiResponses.mjs.html#line322">line 322</a>
     </li></ul></dd>
     
 
@@ -5831,31 +6786,22 @@ prompt走HTTP body，無命令列長度限制；
     
     <pre class="prettyprint"><code>//need network, no cli required
 
-import dispatchApiOpenaiCompat from './src/dispatchApiOpenaiCompat.mjs'
+import dispatchApiOpenaiResponses from './src/dispatchApiOpenaiResponses.mjs'
 
 let test = async () => {
 
-    //OpenCode Zen(即opencode CLI之自家閘道), 模型名不帶opencode/前綴
-    let r1 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
+    //OpenCode Zen之muse-spark系走/responses(非chat/completions), 詳見providers.mjs檔頭
+    let r = await dispatchApiOpenaiResponses('請只回覆兩個字：完成', {
         baseURL: 'https://opencode.ai/zen/v1',
         key: 'sk-xxxxxx',
-        model: 'deepseek-v4-flash-free',
-    })
-    console.log(r1.ok, r1.stdout.trim())
-    // => true 完成
-
-    //Agnes
-    let r2 = await dispatchApiOpenaiCompat('請只回覆兩個字：完成', {
-        baseURL: 'https://apihub.agnes-ai.com/v1',
-        key: 'sk-xxxxxx',
-        model: 'agnes-2.0-flash',
+        model: 'muse-spark-1.3-contributor-free',
     })
-    console.log(r2.ok, r2.stdout.trim())
+    console.log(r.ok, r.stdout.trim())
     // => true 完成
 
-    let re = await dispatchApiOpenaiCompat('abc', { baseURL: 'https://opencode.ai/zen/v1', key: 'sk-bad', model: 'deepseek-v4-flash-free' })
-    console.log(re.ok, re.code, re.error)
-    // => false 401 HTTP 401
+    let re = await dispatchApiOpenaiResponses('abc', { baseURL: 'https://opencode.ai/zen/v1', key: 'sk-bad', model: 'muse-spark-1.3-contributor-free' })
+    console.log(re.ok, re.code, re.errorType)
+    // => false 401 http
 
 }
 await test()
@@ -5924,7 +6870,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入提示詞字串，作為user訊息置於HTTP body</p></td>
+            <td class="description last"><p>輸入提示詞字串，作為input置於HTTP body</p></td>
         </tr>
 
     
@@ -6023,7 +6969,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入API基底網址字串，例如'https://opencode.ai/zen/v1'、'https://apihub.agnes-ai.com/v1'，將於尾端接上/chat/completions</p></td>
+            <td class="description last"><p>輸入API基底網址字串，例如'https://opencode.ai/zen/v1'，將於尾端接上/responses</p></td>
         </tr>
 
     
@@ -6059,7 +7005,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入模型ID字串，例如'deepseek-v4-flash-free'(Zen之模型名不帶opencode/前綴)、'agnes-2.0-flash'</p></td>
+            <td class="description last"><p>輸入模型ID字串，例如'muse-spark-1.3-contributor-free'</p></td>
         </tr>
 
     
@@ -6139,7 +7085,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入system提示詞字串，將以system角色置於messages首位，預設''代表不帶</p></td>
+            <td class="description last"><p>輸入system提示詞字串，將置於instructions欄位(Responses API之system管道)，預設''代表不帶</p></td>
         </tr>
 
     
@@ -6179,7 +7125,7 @@ await test()
                 </td>
             
 
-            <td class="description last"><p>輸入額外請求本體物件(如temperature、max_tokens、response_format)，將併入預設body(同名鍵以此為準)，預設{}。注意本轉接器不支援工具，帶入tools而模型回tool_calls時一律以TOOL_CALLS_UNSUPPORTED回報失敗，需要工具請改用CLI類kind</p></td>
+            <td class="description last"><p>輸入額外請求本體物件(如temperature、max_output_tokens、reasoning)，將併入預設body(同名鍵以此為準)，預設{}。注意輸出上限欄位名為max_output_tokens而非max_tokens；本轉接器不支援工具，帶入tools而模型回function_call時一律以TOOL_CALLS_UNSUPPORTED回報失敗</p></td>
         </tr>
 
     
@@ -6413,7 +7359,7 @@ await test()
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，無則null)，本函數不會reject</p>
+    <p>回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(回覆內容字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，欄位名為input_tokens/output_tokens/total_tokens，無則null)，本函數不會reject</p>
 </div>
 
 
@@ -8598,6 +9544,178 @@ console.log(extractJsonLoose('純文字回覆'))
 
     
 
+    <h4 class="name" id="extractOutputText"><span class="type-signature"></span>extractOutputText<span class="signature">(output)</span><span class="type-signature"> &rarr; {String}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>自Responses API之output陣列取出文字內容(僅取message型元素之output_text)</p>
+<p>reasoning型元素為模型思考過程(Zen實測其content為空陣列)，不屬回覆內容故略過；
+多個message元素依序串接</p></li></ul></dd>
+    
+
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="dispatchApiOpenaiResponses.mjs.html">dispatchApiOpenaiResponses.mjs</a>, <a href="dispatchApiOpenaiResponses.mjs.html#line86">line 86</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-examples">Example</h5>
+    
+    <pre class="prettyprint"><code>import { extractOutputText } from './src/dispatchApiOpenaiResponses.mjs'
+
+let output = [
+    { type: 'reasoning', content: [] },
+    { type: 'message', content: [{ type: 'output_text', text: '完成' }] },
+]
+console.log(extractOutputText(output))
+// => '完成'</code></pre>
+
+
+
+
+    <h5 class="h5-parameters">Parameters:</h5>
+    
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>output</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Array</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入回應之output陣列</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳串接後之文字內容，無有效內容回傳空字串</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">String</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
     <h4 class="name" id="getCliArgs"><span class="type-signature"></span>getCliArgs<span class="signature">(&hellip;args)</span><span class="type-signature"> &rarr; {Array}</span></h4>
 
     
@@ -9034,7 +10152,7 @@ console.log(getErrorResult(null).error)
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="getErrorType.mjs.html">getErrorType.mjs</a>, <a href="getErrorType.mjs.html#line53">line 53</a>
+        <a href="getErrorType.mjs.html">getErrorType.mjs</a>, <a href="getErrorType.mjs.html#line55">line 55</a>
     </li></ul></dd>
     
 
@@ -9992,7 +11110,7 @@ let env = readEnvFile('./.env')
 //全取: envVar展開為keys, 缺環境變數者列入skipped
 let { providers, table, skipped } = resolveProviders(providersAll, { env })
 console.log(providers.length, skipped)
-// => 16 []
+// => 17 []
 
 //pick打錯字時, missing附拼寫提示hints(最接近之可用id)
 let rm = resolveProviders(providersAll, { env, pick: ['poolside/laguna-s-2.1'] })
@@ -12085,7 +13203,7 @@ console.log(salvageTruncatedArray('[{"a":1}]')) //有閉合＝非截斷, 不在
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Sep 02 2026 18:01:49 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 Sep 03 2026 11:40:21 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>