w-dispatch-ai 1.0.3 → 1.0.5

package/src/providers.mjs

@@ -0,0 +1,133 @@
+// providers.mjs — 預設providers定義檔(實測可用之供應商條目, 開發端可直接全用或自選)
+//
+// 【性質】純資料檔, 不讀環境變數。金鑰以envVar間接引用(機密不落設定檔),
+//   使用前須經resolveProviders展開(envVar → keys, 缺變數者自動停用並回報);
+//   展開後之陣列可直接餵dispatchAiFallback, table可直接餵dispatchAiWkf。
+//
+// 【id命名】依「路徑:模型」規則(詳dispatchAiFallback.mjs檔頭之id設計規則):
+//   oc:＝經opencode CLI(有工具、較慢) / agy:＝antigravity CLI / claude:/codex:＝訂閱登入態CLI
+//   zen:/agnes:/poolside:＝REST直呼(免CLI免登入、快, 純文字生成)
+//   同一模型之CLI版與REST版屬不同供應商(能力與額度池皆不同), 故各為一條。
+//
+// 【使用方式】
+//   import providers from 'w-dispatch-ai/src/providers.mjs'
+//   import resolveProviders from 'w-dispatch-ai/src/resolveProviders.mjs'
+//   process.loadEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS, 逗號分隔多把
+//   let { providers: ps, table, skipped } = resolveProviders(providers) //全取
+//   let r2 = resolveProviders(providers, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] }) //自選, pick順序即遞補優先序
+//
+// 【timeout規劃】各條目刻意不帶timeoutMs, 由上層依任務型態統一給定、條目僅於特例覆寫:
+//   簡單任務(秒級~分鐘級): 沿用套件統一預設即可(全轉接器一律300000＝5分鐘, 見dfTimeoutMs.mjs)。
+//   複雜任務(單一AI工作約15分鐘、fallback須能走到最末):
+//     timeoutMs:    1200000 (20min＝15min工作＋33%餘裕, 單次嘗試上限)
+//     minAttemptMs: 1200000 (剩餘預算不足完整視窗即不開工——開了也不可能完成, 純浪費)
+//     budgetMs:     鏈長K×timeoutMs (逾時型失敗每組只燒一次timeout即跳組, 故K×20min
+//                   保證能走到最末; 例K=4 → 4800000＝80min。無外部排程時限則可null＝不限)
+//     agy之printTimeout由timeoutMs自動推導(−30s), 無須另設。
+//   工作流層總時長: RolePipeline為各階段序列相加(M階段≈M×名額預算);
+//   Fanout各名額並行(≈單一名額預算＋整合名額預算), 外部排程上限須據此預留。
+//   外部調整四層(細者覆蓋粗者): dispatchAiWkf之defaults(全域) → 各工作流callOpt
+//   → 各階段/名額規格 → 各provider條目。
+
+
+let providers = [
+
+    //cli版
+    {
+        id: 'oc:opencode/deepseek-v4-flash-free',
+        model: 'opencode/deepseek-v4-flash-free',
+        kind: 'opencode',
+        envVar: 'OPENCODE_KEYS',
+        provider: 'opencode',
+        config: {
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'oc:agnes-ai/agnes-2.5-flash',
+        model: 'agnes-ai/agnes-2.5-flash',
+        kind: 'opencode',
+        envVar: 'AGNES_KEYS',
+        provider: 'agnes-ai',
+        config: {
+            provider: {
+                'agnes-ai': {
+                    npm: '@ai-sdk/openai-compatible',
+                    name: 'Agnes',
+                    options: { baseURL: 'https://apihub.agnes-ai.com/v1' },
+                    models: { 'agnes-2.5-flash': { name: 'Agnes 2.5 Flash' } },
+                },
+            },
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'oc:poolside/poolside/laguna-s-2.1',
+        model: 'poolside/poolside/laguna-s-2.1',
+        kind: 'opencode',
+        envVar: 'POOLSIDE_KEYS',
+        provider: 'poolside',
+        config: {
+            provider: {
+                'poolside': {
+                    npm: '@ai-sdk/openai-compatible',
+                    name: 'Poolside',
+                    options: { baseURL: 'https://inference.poolside.ai/v1' },
+                    models: { 'poolside/laguna-s-2.1': { name: 'Laguna S 2.1' } },
+                },
+            },
+            permission: { edit: 'deny', write: 'deny', bash: 'deny' },
+        },
+    },
+    {
+        id: 'agy:gemini-3.7-flash-high',
+        model: 'gemini-3.7-flash-high',
+        kind: 'antigravity',
+        addDirs: ['.'],
+    },
+    {
+        id: 'claude:sonnet',
+        model: 'sonnet',
+        kind: 'claude',
+        extraArgs: ['--disallowedTools', 'Write,Edit,NotebookEdit,Bash'],
+    },
+    {
+        id: 'codex:gpt-5.6-luna',
+        model: 'gpt-5.6-luna',
+        kind: 'codex',
+        sandbox: 'read-only',
+    },
+
+    //api版
+    {
+        id: 'zen:deepseek-v4-flash-free',
+        model: 'deepseek-v4-flash-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 8192 },
+    },
+    {
+        id: 'agnes:agnes-2.5-flash',
+        model: 'agnes-2.5-flash',
+        kind: 'api-openai-compat',
+        envVar: 'AGNES_KEYS',
+        baseURL: 'https://apihub.agnes-ai.com/v1',
+        body: { max_tokens: 8192 },
+    },
+    {
+        id: 'poolside:laguna-s-2.1',
+        model: 'poolside/laguna-s-2.1',
+        kind: 'api-openai-compat',
+        envVar: 'POOLSIDE_KEYS',
+        baseURL: 'https://inference.poolside.ai/v1',
+        body: {
+            max_tokens: 8192,
+            chat_template_kwargs: { enable_thinking: false },
+        },
+    },
+
+]
+
+
+export default providers

package/src/resolveProviders.mjs

@@ -0,0 +1,117 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+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'
+
+
+// resolveProviders.mjs — 把providers定義檔展開為可直接使用的條目
+//
+// 【為何需要】providers.mjs之條目以envVar間接引用金鑰(機密不落設定檔, 只寫變數名),
+//   而dispatchAiFallback只認keys陣列——本函數負責envVar → keys之展開,
+//   缺對應環境變數者停用該條目並列入skipped回報(不中斷、不throw),
+//   訂閱登入態條目(claude/codex等無envVar)原樣通過。
+//
+// 【自選】opt.pick給id陣列即可只取用部分條目, 且依pick之順序回傳
+//   (順序即dispatchAiFallback之優先序); 查無之id列入missing回報。
+
+
+/**
+ * 展開providers定義條目：envVar → keys，並可依id自選子集
+ *
+ * 特點：
+ * 條目之envVar依env來源(預設process.env)展開為keys陣列(變數值以逗號分隔多把)，envVar欄位自輸出移除；
+ * 缺對應環境變數(或值為空)之條目停用並列入skipped，不中斷不throw；
+ * 無envVar之條目(訂閱登入態CLI)原樣通過；條目已自帶有效keys者以keys為準；
+ * opt.pick可依id自選子集並以pick順序回傳(順序即遞補優先序)；
+ * 輸入陣列與條目皆不被改動(輸出為淺拷貝)
+ *
+ * @param {Array} providers 輸入providers條目物件陣列(如providers.mjs之預設匯出)
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} [opt.env=process.env] 輸入金鑰來源物件(變數名 → 逗號分隔之金鑰字串)，預設process.env
+ * @param {Array} [opt.pick=null] 輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)
+ * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)
+ * @example
+ *
+ * import resolveProviders from './src/resolveProviders.mjs'
+ * import providersAll from './src/providers.mjs'
+ *
+ * process.loadEnvFile('./.env') //金鑰放.env, 變數值以逗號分隔多把
+ *
+ * //全取: envVar展開為keys, 缺環境變數者列入skipped
+ * let { providers, table, skipped } = resolveProviders(providersAll)
+ * console.log(providers.length, skipped)
+ * // => 10 []
+ *
+ * //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
+ * let r2 = resolveProviders(providersAll, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
+ * console.log(r2.providers.map((p) => p.id))
+ * // => [ 'agnes:agnes-2.5-flash', 'claude:sonnet' ]
+ *
+ * //table可直接餵dispatchAiWkf之providers定義表
+ * //let wkf = dispatchAiWkf({ providers: r2.table, defaults: { timeoutMs: 1200000 } })
+ *
+ */
+function resolveProviders(providers, opt = {}) {
+
+    //env, 無效回退process.env(瀏覽器環境無process則空物件)
+    let env = get(opt, 'env', null)
+    if (!isobj(env)) {
+        env = (typeof process !== 'undefined' && process && isobj(process.env)) ? process.env : {}
+    }
+
+    //providersRaw
+    let providersRaw = isarr(providers) ? providers.filter(isobj) : []
+
+    //pick, 依id自選並依pick順序回傳
+    let pick = get(opt, 'pick', null)
+    let missing = []
+    let selected = providersRaw
+    if (isearr(pick)) {
+        selected = []
+        for (let id of pick) {
+            let entry = providersRaw.find((p) => get(p, 'id', null) === id)
+            if (entry) {
+                selected.push(entry)
+            }
+            else {
+                missing.push(String(id))
+            }
+        }
+    }
+
+    //展開envVar → keys
+    let out = []
+    let skipped = []
+    for (let entry of selected) {
+        let envVar = get(entry, 'envVar', null)
+
+        //無envVar(訂閱登入態CLI)或已自帶有效keys, 原樣通過(僅移除envVar欄位)
+        if (!isestr(envVar) || isearr(get(entry, 'keys', null))) {
+            out.push(omit(entry, ['envVar']))
+            continue
+        }
+
+        //envVar → keys, 變數值以逗號分隔多把
+        let keys = String(get(env, envVar, '') || '').split(',').map((k) => k.trim()).filter(Boolean)
+        if (keys.length === 0) {
+
+            //缺環境變數: 停用該條目並回報, 不中斷(設計providers原則§四.4)
+            skipped.push({ id: get(entry, 'id', ''), envVar })
+            continue
+        }
+        out.push({ ...omit(entry, ['envVar']), keys })
+    }
+
+    //table, id → 條目, 可直接作dispatchAiWkf之providers定義表
+    let table = {}
+    for (let entry of out) {
+        table[entry.id] = entry
+    }
+
+    return { providers: out, table, skipped, missing }
+}
+
+
+export default resolveProviders

package/src/wkf/callAiWithFallback.mjs

@@ -4,6 +4,7 @@ import isestr from 'wsemi/src/isestr.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
 import dispatchAiFallback from '../dispatchAiFallback.mjs'
+import dfTimeoutMs from '../dfTimeoutMs.mjs'
 import extractJsonLoose from './extractJsonLoose.mjs'
 
 
@@ -23,13 +24,22 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 // 【防寫檔前綴】agentic CLI對cwd隔離免疫(會自行解析專案根目錄寫檔),
 //   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
 //   殷鑑: 2026-08-10執行任務歷史.md遭AI覆寫、評比腳本繞過前綴又產生根目錄孤兒檔。
+//
+//   措辭須豁免「唯讀查閱」(2026-08-13 A/B實測): 各CLI取得檔案內容的途徑不同——
+//   opencode與claude有獨立的read/grep工具, 不受「禁止執行指令」約束;
+//   但codex讀檔即是執行shell指令, 舊措辭「禁止執行任何指令」對它等同「禁止讀檔」,
+//   凡需讀專案的任務會得到一句「請貼上檔案內容」而非成果, 且該拒答是合法字串,
+//   會通過驗證被遞補層當成「成功」, 整條fallback鏈就此停住——兜底地位被靜默廢掉。
+//   實測: 舊措辭下codex回「無法讀取該檔案」, 改為下列措辭後正常讀檔作答(11.1s),
+//   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
 
 
-//預設防寫檔前綴
+//預設防寫檔前綴(禁副作用, 但豁免唯讀查閱——codex以shell讀檔, 一律禁指令等同禁讀檔)
 let NO_SIDE_EFFECT = [
     '【執行約束】你只需把結果輸出在回覆內容中。',
-    '禁止建立、修改或刪除任何檔案，禁止執行任何指令——呼叫端只讀取你的回覆文字，',
-    '任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '禁止建立、修改或刪除任何檔案，也不要執行任何會改動磁碟或系統狀態的指令——',
+    '呼叫端只讀取你的回覆文字，任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '唯讀查閱（讀取檔案、搜尋內容、列出目錄）不在此限，需要時請照常使用。',
     '', '',
 ].join('\n')
 
@@ -87,7 +97,7 @@ function buildChain(providers, spec) {
  * @param {Function} [opt.parse=extractJsonLoose] 輸入回覆解析函數(stdout)=>Object|null，預設寬鬆JSON抽取
  * @param {Boolean} [opt.rawText=false] 輸入是否以純文字模式運作布林值，true代表不解析JSON(json欄位為修剪後文字、check收文字)，預設false
  * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
- * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，預設300000
+ * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，全套件統一預設300000
  * @param {Number} [opt.budgetMs=null] 輸入整條遞補鏈之時間預算毫秒正整數，預設null代表不限
  * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試)
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
@@ -99,20 +109,21 @@ function buildChain(providers, spec) {
  *
  * import callAiWithFallback from './src/wkf/callAiWithFallback.mjs'
  *
+ * //鍵名須區分到模型並帶上路徑, 詳見dispatchAiFallback.mjs檔頭之id設計規則
  * let providers = {
- *     'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'zen:deepseek-v4-flash-free': { kind: 'api-openai-compat', baseURL: 'https://opencode.ai/zen/v1', model: 'deepseek-v4-flash-free', keys: ['sk-xxx'] },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
  * }
  *
  * let test = async () => {
  *
  *     let r = await callAiWithFallback('只回覆JSON: {"a":1}', {
  *         providers,
- *         spec: { use: 'deepseek', fallback: ['sonnet'] },
+ *         spec: { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
  *         check: (j) => j.a === 1,
  *     })
  *     console.log(r.ok, r.json, r.providerId)
- *     // => true { a: 1 } 'deepseek'
+ *     // => true { a: 1 } 'zen:deepseek-v4-flash-free'
  *
  * }
  * await test()
@@ -177,7 +188,7 @@ async function callAiWithFallback(prompt, opt = {}) {
     let r = await dispatchAiFallback(promptPrefix + prompt, {
         providers: chain,
         validate,
-        timeoutMs: get(opt, 'timeoutMs', null) || 300000,
+        timeoutMs: get(opt, 'timeoutMs', null) || dfTimeoutMs, //全套件統一預設300000
         budgetMs: get(opt, 'budgetMs', null) || undefined,
         maxRetries: get(opt, 'maxRetries', null) || 0,
         cwd: get(opt, 'cwd', null) || process.cwd(),

package/src/wkf/runFanout.mjs

@@ -63,8 +63,8 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  * import runFanout from './src/wkf/runFanout.mjs'
  *
  * let providers = {
- *     'deepseek': { kind: 'opencode', model: 'opencode/deepseek-v4-flash-free', provider: 'opencode', keys: ['sk-xxx'] },
- *     'sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'zen:deepseek-v4-flash-free': { kind: 'api-openai-compat', baseURL: 'https://opencode.ai/zen/v1', model: 'deepseek-v4-flash-free', keys: ['sk-xxx'] },
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
  * }
  *
  * let test = async () => {
@@ -73,10 +73,10 @@ ${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('
  *         providers,
  *         task: '分析並只回覆JSON: {"essence":"..."}',
  *         agents: [
- *             { use: 'deepseek', fallback: ['sonnet'] },
- *             { use: 'sonnet' },
+ *             { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
+ *             { use: 'claude:sonnet' },
  *         ],
- *         integrate: { use: 'sonnet' },
+ *         integrate: { use: 'claude:sonnet' },
  *         check: (j) => !!j.essence,
  *     })
  *     console.log(r.ok, r.integrated, r.candidates.length)

package/src/wkf/runFanoutPipeline.mjs

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

package/src/wkf/runRolePipeline.mjs

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

package/test/tools/fakeServerForApiTest.mjs

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

package/test/unit-WDispatchAi.test.mjs

@@ -10,6 +10,8 @@ import dispatchClaude from '../src/dispatchClaude.mjs'
 import dispatchCodex from '../src/dispatchCodex.mjs'
 import dispatchAntigravity from '../src/dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
+import providers from '../src/providers.mjs'
+import resolveProviders from '../src/resolveProviders.mjs'
 
 
 describe('WDispatchAi', function() {
@@ -26,6 +28,8 @@ describe('WDispatchAi', function() {
             'dispatchCodex',
             'dispatchAntigravity',
             'dispatchApiOpenaiCompat',
+            'providers',
+            'resolveProviders',
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -36,9 +40,9 @@ describe('WDispatchAi', function() {
         assert.strict.deepEqual(r, rr)
     })
 
-    it('除KINDS外各鍵值皆為函數', function() {
+    it('各鍵值型別正確(KINDS與providers為物件, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function']
+        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -52,8 +56,10 @@ describe('WDispatchAi', function() {
             wi.dispatchCodex === dispatchCodex,
             wi.dispatchAntigravity === dispatchAntigravity,
             wi.dispatchApiOpenaiCompat === dispatchApiOpenaiCompat,
+            wi.providers === providers,
+            wi.resolveProviders === resolveProviders,
         ]
-        let rr = [true, true, true, true, true, true, true, true]
+        let rr = [true, true, true, true, true, true, true, true, true, true]
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchAi.test.mjs

@@ -70,7 +70,7 @@ describe('dispatchAi', function() {
             [true, ['run', '--agent', 'build', '-m', 'mdl']],
             [true, ['-p', '--dangerously-skip-permissions', '--model', 'mdl']],
             [true, ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-m', 'mdl']],
-            [true, ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'mdl', '--print', 'abc']],
+            [true, ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'mdl', '--add-dir', process.cwd(), '--print', 'abc']],
         ]
         assert.strict.deepEqual(r, rr)
     })

package/test/unit-dispatchAiFallback.test.mjs

@@ -316,6 +316,31 @@ describe('dispatchAiFallback', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('失敗事件與tried帶被拒回覆(stdout)與錯誤輸出(stderr)供診斷', async function() {
+        let evs = []
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                //驗證失敗(skip-group): 被拒的回覆內容應可於事件與tried取得
+                { id: 'g-diag-v', kind: 'claude', exe: fake.exe, validate: 'min:100000' },
+                //exit 1(next-key): stderr之錯誤訊息應可於事件與tried取得
+                { id: 'g-diag-e', kind: 'claude', exe: fake.exe, extraArgs: ['--fake-exit=1', '--fake-stderr=Invalid API key.'] },
+                { id: 'g-diag-ok', kind: 'claude', exe: fake.exe },
+            ],
+            onEvent: (ev) => evs.push(ev),
+        })
+        let evV = evs.find((x) => x.type === 'skip-group')
+        let evE = evs.find((x) => x.type === 'next-key')
+        let r = [
+            t.ok,
+            evV.stdout.includes('"stdin"'), //被拒回覆即假CLI之echo JSON
+            t.tried[0].stdout.includes('"stdin"'),
+            evE.stderr,
+            t.tried[1].stderr,
+        ]
+        let rr = [true, true, true, 'Invalid API key.', 'Invalid API key.']
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('onEvent依序回報事件, 回調拋出例外不影響主流程', async function() {
         let evs = []
         let t = await dispatchAiFallback('abc', {

package/test/unit-dispatchAntigravity.test.mjs

@@ -62,7 +62,7 @@ describe('dispatchAntigravity', function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe })
         let o = JSON.parse(t.stdout)
         let r = [t.ok, o.args]
-        let rr = [true, ['--dangerously-skip-permissions', '--print-timeout', '270s', '--print', 'abc']]
+        let rr = [true, ['--dangerously-skip-permissions', '--print-timeout', '270s', '--add-dir', process.cwd(), '--print', 'abc']]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -78,7 +78,7 @@ describe('dispatchAntigravity', function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe, model: 'gemini-3.6-flash-low' })
         let o = JSON.parse(t.stdout)
         let r = o.args
-        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'gemini-3.6-flash-low', '--print', 'abc']
+        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'gemini-3.6-flash-low', '--add-dir', process.cwd(), '--print', 'abc']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -86,7 +86,7 @@ describe('dispatchAntigravity', function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe, model: 'gemini-3.1-pro', effort: 'low' })
         let o = JSON.parse(t.stdout)
         let r = o.args
-        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'gemini-3.1-pro', '--effort', 'low', '--print', 'abc']
+        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--model', 'gemini-3.1-pro', '--effort', 'low', '--add-dir', process.cwd(), '--print', 'abc']
         assert.strict.deepEqual(r, rr)
     })
 
@@ -94,7 +94,7 @@ describe('dispatchAntigravity', function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe, skipPermissions: false })
         let o = JSON.parse(t.stdout)
         let r = [t.ok, o.args]
-        let rr = [true, ['--print-timeout', '270s', '--print', 'abc']]
+        let rr = [true, ['--print-timeout', '270s', '--add-dir', process.cwd(), '--print', 'abc']]
         assert.strict.deepEqual(r, rr)
     })
 
@@ -123,6 +123,26 @@ describe('dispatchAntigravity', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('未給addDirs時自動納入有效cwd(明給的cwd優先)', async function() {
+        let t1 = await dispatchAntigravity('abc', { exe: fake.exe }) //cwd未給 → process.cwd()
+        let t2 = await dispatchAntigravity('abc', { exe: fake.exe, cwd: fake.fd }) //cwd明給
+        let o1 = JSON.parse(t1.stdout)
+        let o2 = JSON.parse(t2.stdout)
+        let i1 = o1.args.indexOf('--add-dir')
+        let i2 = o2.args.indexOf('--add-dir')
+        let r = [o1.args[i1 + 1], o2.args[i2 + 1]]
+        let rr = [process.cwd(), fake.fd]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('明示addDirs為空陣列時不自動加入(代表不揭露任何目錄)', async function() {
+        let t = await dispatchAntigravity('abc', { exe: fake.exe, addDirs: [] })
+        let o = JSON.parse(t.stdout)
+        let r = [t.ok, o.args.includes('--add-dir')]
+        let rr = [true, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('addDirs逐項展開為--add-dir並濾除非有效字串', async function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe, addDirs: ['c:/a', null, 'c:/b', 123] })
         let o = JSON.parse(t.stdout)
@@ -135,7 +155,7 @@ describe('dispatchAntigravity', function() {
         let t = await dispatchAntigravity('abc', { exe: fake.exe, extraArgs: ['--output-format', 'json'] })
         let o = JSON.parse(t.stdout)
         let r = o.args
-        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--output-format', 'json', '--print', 'abc']
+        let rr = ['--dangerously-skip-permissions', '--print-timeout', '270s', '--add-dir', process.cwd(), '--output-format', 'json', '--print', 'abc']
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -178,6 +178,37 @@ describe('dispatchApiOpenaiCompat', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('模型回tool_calls時明確回報不支援而非靜默成功', async function() {
+        let t = await dispatchApiOpenaiCompat('台北天氣如何', {
+            baseURL: svr.url,
+            key: 'sk-good-1',
+            model: 'tool-calls',
+            body: { tools: [{ type: 'function', function: { name: 'get_weather', parameters: {} } }] },
+        })
+        let r = [
+            t.ok,
+            t.code,
+            t.stdout,
+            t.error.indexOf('TOOL_CALLS_UNSUPPORTED') === 0,
+            t.error.includes('cli kind'),
+            t.stderr.includes('get_weather'), //原始回應保留供除錯
+        ]
+        let rr = [false, 200, '', true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('tool_calls為與金鑰無關之失敗, 於fallback鏈中不逐把空耗而遞補下一組', async function() {
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'g-tool', kind: 'api-openai-compat', baseURL: svr.url, model: 'tool-calls', keys: ['sk-t0', 'sk-t1'] },
+                { id: 'g-text', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-x0'] },
+            ],
+        })
+        let r = [t.ok, t.providerId, t.tried.map((x) => [x.keyId, x.outcome])]
+        let rr = [true, 'g-text', [['g-tool#0', 'next-key'], ['g-tool#1', 'next-key'], ['g-text#0', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('可經dispatchAi以kind api-openai-compat分派', async function() {
         let t = await dispatchAi('api-openai-compat', 'abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
         let o = JSON.parse(t.stdout)