w-dispatch-ai 1.0.16 → 1.0.18

package/docs/dispatchApiOpenaiCompat.mjs.html

@@ -490,7 +490,7 @@ export default dispatchApiOpenaiCompat
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchClaude.mjs.html

@@ -185,7 +185,7 @@ export default dispatchClaude
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchCodex.mjs.html

@@ -186,7 +186,7 @@ export default dispatchCodex
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/dispatchOpencode.mjs.html

@@ -255,7 +255,7 @@ export default dispatchOpencode
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getCliArgs.mjs.html

@@ -113,7 +113,7 @@ export default getCliArgs
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getErrorResult.mjs.html

@@ -109,7 +109,7 @@ export default getErrorResult
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/getErrorType.mjs.html

@@ -158,7 +158,7 @@ export { attachErrorType }
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/global.html

@@ -9935,7 +9935,7 @@ providers與table同源產出故必然一致；
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="resolveProviders.mjs.html">resolveProviders.mjs</a>, <a href="resolveProviders.mjs.html#line80">line 80</a>
+        <a href="resolveProviders.mjs.html">resolveProviders.mjs</a>, <a href="resolveProviders.mjs.html#line86">line 86</a>
     </li></ul></dd>
     
 
@@ -9992,7 +9992,12 @@ let env = readEnvFile('./.env')
 //全取: envVar展開為keys, 缺環境變數者列入skipped
 let { providers, table, skipped } = resolveProviders(providersAll, { env })
 console.log(providers.length, skipped)
-// => 10 []
+// => 16 []
+
+//pick打錯字時, missing附拼寫提示hints(最接近之可用id)
+let rm = resolveProviders(providersAll, { env, pick: ['poolside/laguna-s-2.1'] })
+console.log(rm.missing, rm.hints)
+// => [ 'poolside/laguna-s-2.1' ] { 'poolside/laguna-s-2.1': 'poolside:laguna-s-2.1' }
 
 //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
 let r2 = resolveProviders(providersAll, { env, pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
@@ -10329,7 +10334,7 @@ console.log(r3.table['claude:sonnet'].exe, r3.table['claude:sonnet'].timeoutMs)
 
         
 <div class="param-desc">
-    <p>回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)</p>
+    <p>回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)、hints(missing id對最接近可用id之拼寫提示物件，pick查無多半是打錯字，附最接近id供直接定位；僅為相似度最高者非保證正解，無missing時為空物件)</p>
 </div>
 
 
@@ -12080,7 +12085,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 Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/readEnvFile.mjs.html

@@ -119,7 +119,7 @@ export default readEnvFile
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/resolveProviders.mjs.html

@@ -51,6 +51,7 @@ import isarr from 'wsemi/src/isarr.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
+import strFindSimilar from 'wsemi/src/strFindSimilar.mjs'
 
 
 // resolveProviders.mjs — 把providers定義檔展開為可直接使用的條目
@@ -90,7 +91,7 @@ import isearr from 'wsemi/src/isearr.mjs'
  * @param {Array} [opt.pick=null] 輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)
  * @param {Object} [opt.exes=null] 輸入kind對執行檔絕對路徑之物件(如{claude:'C:/.../claude.exe'})，命中kind之條目補上exe欄位(條目已自帶exe者不覆寫——條目層設定優先)，預設null代表不注入
  * @param {Object} [opt.patch=null] 輸入id對部分欄位之物件(如{'claude:sonnet':{timeoutMs:360000}})，命中id之條目淺合併覆寫，於exes之後施作故可覆寫exe，預設null代表不覆寫
- * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)
+ * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)、hints(missing id對最接近可用id之拼寫提示物件，pick查無多半是打錯字，附最接近id供直接定位；僅為相似度最高者非保證正解，無missing時為空物件)
  * @example
  *
  * import resolveProviders from './src/resolveProviders.mjs'
@@ -103,7 +104,12 @@ import isearr from 'wsemi/src/isearr.mjs'
  * //全取: envVar展開為keys, 缺環境變數者列入skipped
  * let { providers, table, skipped } = resolveProviders(providersAll, { env })
  * console.log(providers.length, skipped)
- * // => 10 []
+ * // => 16 []
+ *
+ * //pick打錯字時, missing附拼寫提示hints(最接近之可用id)
+ * let rm = resolveProviders(providersAll, { env, pick: ['poolside/laguna-s-2.1'] })
+ * console.log(rm.missing, rm.hints)
+ * // => [ 'poolside/laguna-s-2.1' ] { 'poolside/laguna-s-2.1': 'poolside:laguna-s-2.1' }
  *
  * //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
  * let r2 = resolveProviders(providersAll, { env, pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
@@ -152,6 +158,16 @@ function resolveProviders(providers, opt = {}) {
         }
     }
 
+    //hints, missing之拼寫提示: 自全部條目id中找最接近者——實務上pick查無多半是打錯字
+    //(如'poolside/laguna'誤作分隔符), 附上最接近id可直接定位; 僅為相似度最高者, 非保證正解
+    let hints = {}
+    if (missing.length > 0) {
+        let ids = providersRaw.map((p) => get(p, 'id', null)).filter(isestr)
+        for (let mid of missing) {
+            hints[mid] = (ids.length > 0) ? get(strFindSimilar(mid, ids), 'bestMatch.target', null) : null
+        }
+    }
+
     //展開envVar → keys
     let out = []
     let skipped = []
@@ -205,7 +221,7 @@ function resolveProviders(providers, opt = {}) {
         table[entry.id] = entry
     }
 
-    return { providers: out, table, skipped, missing }
+    return { providers: out, table, skipped, missing, hints }
 }
 
 
@@ -224,7 +240,7 @@ export default resolveProviders
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_callAiWithFallback.mjs.html

@@ -274,7 +274,7 @@ export { buildChain, NO_SIDE_EFFECT }
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_createFileStore.mjs.html

@@ -162,7 +162,7 @@ export default createFileStore
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_createUsageCounter.mjs.html

@@ -200,7 +200,7 @@ export default createUsageCounter
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_extractJsonLoose.mjs.html

@@ -167,7 +167,7 @@ export default extractJsonLoose
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_noSideEffectPrefix.mjs.html

@@ -108,7 +108,7 @@ export default NO_SIDE_EFFECT
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runFanout.mjs.html

@@ -217,7 +217,7 @@ export { defaultIntegratePrompt }
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runFanoutPipeline.mjs.html

@@ -161,7 +161,7 @@ export default runFanoutPipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_runRolePipeline.mjs.html

@@ -183,7 +183,7 @@ export default runRolePipeline
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/wkf_salvageTruncatedArray.mjs.html

@@ -154,7 +154,7 @@ export default salvageTruncatedArray
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Aug 21 2026 10:53:56 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 Wed Aug 26 2026 16:22:12 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
-    "wsemi": "^1.8.79"
+    "wsemi": "^1.8.80"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.15"

package/src/providers.mjs

@@ -9,6 +9,13 @@
 //   zen:/agnes:/poolside:＝REST直呼(免CLI免登入、快, 純文字生成)
 //   同一模型之CLI版與REST版屬不同供應商(能力與額度池皆不同), 故各為一條。
 //
+// 【zen免費模型清單為「更新日快照」, 不保證即為當前狀態】zen:系收錄截至2026-08-21
+//   經GET https://opencode.ai/zen/v1/models 查得之「全部」免費模型(*-free), 不做好用篩選——
+//   新模型會上線、舊模型可能下架或限流, 且各模型能力/速度/輸出習慣差異極大
+//   (各條目註解記錄已測特性), 由呼叫端自行評估選用; 要查當前清單, 以OPENCODE_KEYS
+//   打上述/models端點即可。暫時打不通的條目(限流/額度)依本套件哲學保留不移除:
+//   恢復的偵測就是下次再打一次, 代價僅一次快速失敗(fallback/cooldownMs即為此而生)。
+//
 // 【使用方式】
 //   import providers from 'w-dispatch-ai/src/providers.mjs'
 //   import resolveProviders from 'w-dispatch-ai/src/resolveProviders.mjs'
@@ -43,6 +50,7 @@ let providers = [
         config: {
             permission: { edit: 'deny', write: 'deny', bash: 'deny' },
         },
+        //2026-08-21實測失敗(UnknownError, 與zen:deepseek同日之401同源); 保留理由見該條註記
     },
     {
         id: 'oc:agnes-ai/agnes-2.5-flash',
@@ -105,6 +113,7 @@ let providers = [
     },
 
     //api版
+    //zen:系為2026-08-21快照(檔頭聲明), 各條註記當日以「請只回覆兩個字：完成」實測之結果
     {
         id: 'zen:deepseek-v4-flash-free',
         model: 'deepseek-v4-flash-free',
@@ -112,6 +121,71 @@ let providers = [
         envVar: 'OPENCODE_KEYS',
         baseURL: 'https://opencode.ai/zen/v1',
         body: { max_tokens: 8192 },
+        //2026-08-21實測回401(官方訊息: Free promotion has ended); opencode方案端仍列此模型,
+        //判讀為用量壓力下之暫時狀態而保留, 恢復之偵測即下次再打
+    },
+    {
+        id: 'zen:laguna-s-2.1-free',
+        model: 'laguna-s-2.1-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測4.0s; 同一laguna之第三條路(Poolside官方REST/oc CLI/zen), 三者故障域獨立
+    },
+    {
+        id: 'zen:x-preview-f-free',
+        model: 'x-preview-f-free', //官方顯示名Ox Alpha Free
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測2.4s; 使用端回報批次涵蓋率偏低(3篇輸入常只回1~2篇), 批次任務慎用
+    },
+    {
+        id: 'zen:muse-spark-1.2-contributor-free',
+        model: 'muse-spark-1.2-contributor-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測3.9s; 使用端回報批次涵蓋率100%、術語標準、內容密度高
+    },
+    {
+        id: 'zen:mimo-v2.5-free',
+        model: 'mimo-v2.5-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測連續429(FreeUsageLimitError, 容量型)——429證明閘道認得此id(寫錯會回其他4xx)
+    },
+    {
+        id: 'zen:hy3-free',
+        model: 'hy3-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測3.2s
+    },
+    {
+        id: 'zen:nemotron-3-ultra-free',
+        model: 'nemotron-3-ultra-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測2.2s; function calling協定實測可用(tool_calls格式標準, 但本套件api類不支援工具)
+    },
+    {
+        id: 'zen:nemotron-3.5-lightning-free',
+        model: 'nemotron-3.5-lightning-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+        //2026-08-21實測27.4s——名為lightning實測卻最慢, timeout與批量規劃須留意
     },
     {
         id: 'agnes:agnes-2.5-flash',

package/src/resolveProviders.mjs

@@ -4,6 +4,7 @@ import isarr from 'wsemi/src/isarr.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
+import strFindSimilar from 'wsemi/src/strFindSimilar.mjs'
 
 
 // resolveProviders.mjs — 把providers定義檔展開為可直接使用的條目
@@ -43,7 +44,7 @@ import isearr from 'wsemi/src/isearr.mjs'
  * @param {Array} [opt.pick=null] 輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)
  * @param {Object} [opt.exes=null] 輸入kind對執行檔絕對路徑之物件(如{claude:'C:/.../claude.exe'})，命中kind之條目補上exe欄位(條目已自帶exe者不覆寫——條目層設定優先)，預設null代表不注入
  * @param {Object} [opt.patch=null] 輸入id對部分欄位之物件(如{'claude:sonnet':{timeoutMs:360000}})，命中id之條目淺合併覆寫，於exes之後施作故可覆寫exe，預設null代表不覆寫
- * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)
+ * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)、hints(missing id對最接近可用id之拼寫提示物件，pick查無多半是打錯字，附最接近id供直接定位；僅為相似度最高者非保證正解，無missing時為空物件)
  * @example
  *
  * import resolveProviders from './src/resolveProviders.mjs'
@@ -56,7 +57,12 @@ import isearr from 'wsemi/src/isearr.mjs'
  * //全取: envVar展開為keys, 缺環境變數者列入skipped
  * let { providers, table, skipped } = resolveProviders(providersAll, { env })
  * console.log(providers.length, skipped)
- * // => 10 []
+ * // => 16 []
+ *
+ * //pick打錯字時, missing附拼寫提示hints(最接近之可用id)
+ * let rm = resolveProviders(providersAll, { env, pick: ['poolside/laguna-s-2.1'] })
+ * console.log(rm.missing, rm.hints)
+ * // => [ 'poolside/laguna-s-2.1' ] { 'poolside/laguna-s-2.1': 'poolside:laguna-s-2.1' }
  *
  * //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
  * let r2 = resolveProviders(providersAll, { env, pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
@@ -105,6 +111,16 @@ function resolveProviders(providers, opt = {}) {
         }
     }
 
+    //hints, missing之拼寫提示: 自全部條目id中找最接近者——實務上pick查無多半是打錯字
+    //(如'poolside/laguna'誤作分隔符), 附上最接近id可直接定位; 僅為相似度最高者, 非保證正解
+    let hints = {}
+    if (missing.length > 0) {
+        let ids = providersRaw.map((p) => get(p, 'id', null)).filter(isestr)
+        for (let mid of missing) {
+            hints[mid] = (ids.length > 0) ? get(strFindSimilar(mid, ids), 'bestMatch.target', null) : null
+        }
+    }
+
     //展開envVar → keys
     let out = []
     let skipped = []
@@ -158,7 +174,7 @@ function resolveProviders(providers, opt = {}) {
         table[entry.id] = entry
     }
 
-    return { providers: out, table, skipped, missing }
+    return { providers: out, table, skipped, missing, hints }
 }
 
 

package/test/unit-WDispatchAi.test.mjs

@@ -20,6 +20,7 @@ describe('WDispatchAi', function() {
         let r = keys(wi)
         let rr = [
             'KINDS',
+            'NO_SIDE_EFFECT',
             'dispatchAi',
             'dispatchAiFallback',
             'dispatchAiWkf',
@@ -35,7 +36,6 @@ describe('WDispatchAi', function() {
             'createFileStore',
             'createUsageCounter',
             'salvageTruncatedArray',
-            'NO_SIDE_EFFECT',
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -48,7 +48,7 @@ describe('WDispatchAi', function() {
 
     it('各鍵值型別正確(KINDS與providers為物件, NO_SIDE_EFFECT為字串, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'string']
+        let rr = ['object', 'string', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function']
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-resolveProviders.test.mjs

@@ -120,6 +120,32 @@ describe('resolveProviders', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('pick查無時missing附拼寫提示hints(最接近之可用id), 無missing時hints為空物件', function() {
+        let defs = [
+            { id: 'poolside:laguna-s-2.1', kind: 'api-openai-compat', model: 'm' },
+            { id: 'claude:sonnet', kind: 'claude', model: 'sonnet' },
+        ]
+        //實務上pick查無多半是打錯字(如分隔符「/」誤替「:」), hints直接定位
+        let t1 = resolveProviders(defs, { env: {}, pick: ['poolside/laguna-s-2.1', 'claude:sonnet'] })
+        let t2 = resolveProviders(defs, { env: {} })
+        let r = [t1.missing, t1.hints, t1.providers.map((p) => p.id), t2.missing, t2.hints]
+        let rr = [
+            ['poolside/laguna-s-2.1'],
+            { 'poolside/laguna-s-2.1': 'poolside:laguna-s-2.1' },
+            ['claude:sonnet'], //查無者不影響其餘pick
+            [],
+            {},
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('providers為空而pick有值時hints值為null(無可比對之id), 不throw', function() {
+        let t = resolveProviders([], { env: {}, pick: ['x'] })
+        let r = [t.missing, t.hints]
+        let rr = [['x'], { x: null }]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('exes與patch皆省略時行為與原版完全相同(向後相容), 且不改動輸入條目', function() {
         let defs = [{ id: 'a:m', kind: 'claude', model: 'm' }]
         let before = JSON.stringify(defs)