w-dispatch-ai 1.0.35 → 1.0.37

package/src/providers.mjs

@@ -24,14 +24,16 @@
 //     v2頁列為Free但實測全不可用(CLI回UnknownError、REST回400 Upstream request failed: Model is unavailable):
 //       deepseek-v4-flash-free / laguna-s-2.1-free / ling-3.0-tiny-free / longcat-2.0-free / north-mini-code-free
 //     v1頁有而v2頁未列, 但實測可用: mimo-v2.6-flash-free / jev-1.13-free / muse-spark-1.2與1.3 / nemotron-3.5-lightning-free
-//     兩頁皆列且實測可用: big-pickle(CLI 7.1s) / mimo-v2.5-free / nemotron-3-ultra-free
+//     兩頁皆列且實測可用: big-pickle(CLI 7.1s) / mimo-v2.5-free / nemotron-3-ultra-free /
+//       space-bunny-free(2026-09-24新上線: CLI 8.1s、REST 1.9s)
 //     故判準固定為: 文件只用於「端點種類與計價」, 「能不能用」一律以/zen/v1/models或`opencode models`加實測為準。
 //
 //   ★ 核心事實: zen「不是」單一OpenAI相容端點, 端點依模型家族而異 ★
 //     依官方文件之端點欄(2026-09-22以v2 Console/Models頁複查, 分佈與v1一致):
 //       /zen/v1/chat/completions   @ai-sdk/openai-compatible  ← 本套件api-openai-compat僅支援此種
 //         mimo-v2.5-free / ling-3.0-flash-fin-free / nemotron-3-ultra-free /
-//         nemotron-3.5-lightning-free / big-pickle / glm-* / kimi-* / minimax-* / deepseek-v4-*
+//         nemotron-3.5-lightning-free / big-pickle / space-bunny-free(2026-09-24查證) /
+//         glm-* / kimi-* / minimax-* / deepseek-v4-*
 //       /zen/v1/responses          @ai-sdk/openai        (OpenAI Responses API, 非chat/completions)
 //         muse-spark-1.2-contributor-free / muse-spark-1.3-contributor-free / GPT系 / Grok系
 //       /zen/v1/messages           @ai-sdk/anthropic     Claude系 / Qwen系(qwen3.5~3.7-plus/max)
@@ -77,9 +79,11 @@
 //     屬刻意之反濫用政策; 付費模型不受限) ★
 //     症狀: 403 FreeTierError「OpenCode's free tier can only be used from within OpenCode」。
 //     判定依據(2026-09-18本機矩陣實測, opencode 1.18.31):
-//       - REST直呼(任何金鑰): /chat/completions與/responses之免費模型一律403 → 該類zen:條目自此為政策性失效。
-//         例外(2026-09-22實測): /systemone之jev-1.13-free不受此閘門, 帶金鑰或匿名皆200(0.6~1.2s)——
-//         閘門只套在對話型免費模型, 故zen:jev-1.13-free之REST條目可用(見該條)。
+//       - REST直呼(任何金鑰): /chat/completions與/responses之免費模型(當日逐一實測者)一律403 → 該類zen:條目自此為政策性失效。
+//         例外(2026-09-22實測): /systemone之jev-1.13-free不受此閘門, 帶金鑰或匿名皆200(0.6~1.2s),
+//         故zen:jev-1.13-free之REST條目可用(見該條)。
+//         例外(2026-09-24實測): /chat/completions之space-bunny-free亦不受此閘門, 匿名與帶金鑰皆200(1.9~2.0s)——
+//         即閘門係逐模型套用, 並非「對話型免費模型一律擋」; 例外可能隨時收回, 新模型能否走REST一律以實測為準。
 //       - opencode CLI匿名或帶金鑰: 通過; 但注入的設定若把bash工具deny掉(permission.bash:'deny'、
 //         舊式tools.bash:false、agent覆寫deny)即被判非opencode而403; 只deny edit、或改為ask則通過。
 //         即閘門以「請求之工具清單是否含bash」為指紋之一(另一指紋為User-Agent之版本字串, 非正式版build被拒)。
@@ -92,8 +96,8 @@
 //     (實測: muse-spark 1.2/1.3之REST 500而CLI皆秒級成功)。CLI版模型id為
 //     `opencode/<model-id>`, 可用 `opencode models` 列出; 兩者屬不同供應商條目(見id命名)。
 //
-// 【zen免費模型清單為「更新日快照」, 不保證即為當前狀態】zen:系收錄截至2026-08-21
-//   經GET https://opencode.ai/zen/v1/models 查得之免費模型(*-free), 不做好用篩選——
+// 【zen免費模型清單為「更新日快照」, 不保證即為當前狀態】zen:系收錄起於2026-08-21
+//   經GET https://opencode.ai/zen/v1/models 查得之免費模型(*-free), 其後之增刪見本段漂移紀錄(最近一次2026-09-24), 不做好用篩選——
 //   新模型會上線、舊模型可能下架或限流, 且各模型能力/速度/輸出習慣差異極大
 //   (各條目註解記錄已測特性), 由呼叫端自行評估選用; 要查當前清單, 以OPENCODE_KEYS
 //   打上述/models端點即可。暫時打不通的條目(限流/額度/上游中斷)依本套件哲學保留不移除:
@@ -134,6 +138,9 @@
 //     且維護者已明示為刻意政策而非故障, 故不適用「暫時失敗保留」之哲學。同模型之CLI版(oc:opencode/*)
 //     不受影響且已收錄, 能力覆蓋相同。日後政策放寬時, 依檔頭收錄檢核重新收錄即可(端點種類見端點表)。
 //     副作用: 移除後預設清單已無api-openai-responses之條目(該kind仍受支援, 僅無預設條目)。
+//   2026-09-24之漂移: 新增space-bunny-free之兩條目(oc:與zen:, 使用者指示)。官方v1/v2文件〈Pricing〉全Free,
+//     說明為限時免費之stealth推理模型(供應商零保留、不以資料訓練), 端點/chat/completions; CLI清單與/zen/v1/models皆有。
+//     與其他對話型免費模型不同, 其REST未被免費層閘門擋下(匿名與帶金鑰皆200), 故兩路皆收; 實測數據見兩條目註解。
 //
 // 【使用方式】
 //   import providers from 'w-dispatch-ai/src/providers.mjs'
@@ -278,6 +285,20 @@ let providers = [
         //2026-09-22新增(官方文件與CLI清單皆有, 端點/chat/completions): 匿名CLI實測7.0s成功;
         //REST不收zen:版——同日實測403 FreeTierError(對話型免費模型之閘門, 見檔頭)
     },
+    {
+        id: 'oc:opencode/space-bunny-free',
+        model: 'opencode/space-bunny-free',
+        kind: 'opencode',
+        provider: 'opencode',
+        useStoredAuth: false,
+        config: {
+            permission: OC_READONLY,
+        },
+        //2026-09-24新增(官方v1/v2文件、CLI清單與/zen/v1/models皆有; 〈Pricing〉全Free, 限時免費之stealth推理模型,
+        //context 1M、可輸入圖片與影片)。匿名CLI實測(opencode 1.18.32): 簡答8.1s、推理題34.9s答對、
+        //read工具讀相對路徑13.2s正確、要求寫檔被OC_READONLY擋下未落地。官方〈Privacy〉載明其供應商零保留
+        //且不以資料訓練(與big-pickle及各*-free模型之「可能用於改進模型」不同)。同模型另有zen:REST版(見該條)
+    },
     {
         id: 'agy:gemini-3.8-flash-high',
         model: 'gemini-3.8-flash-high', //2026-09-03自3.7升版(agy 1.1.25): 實測12.5s vs 3.7之62.2s, 讀檔14.6s vs 57.6s
@@ -348,7 +369,7 @@ let providers = [
         //付費版jev-1.13未收: 同日以第1把金鑰實測403(Upstream request failed: Model access is disabled),
         //屬該金鑰工作區未開此模型; 要收須先於Zen後台開啟並確認計費($0.042/1M輸入)。
     },
-    //zen:系為2026-08-21快照(檔頭聲明), 各條註記當日以「請只回覆兩個字：完成」實測之結果
+    //REST文字生成條目(api-openai-compat): agnes:/poolside:走各家官方端點; zen:走OpenCode Zen轉售(端點表與免費層閘門見檔頭)
     {
         id: 'agnes:agnes-3.0-flash',
         model: 'agnes-3.0-flash',
@@ -368,6 +389,18 @@ let providers = [
             chat_template_kwargs: { enable_thinking: false },
         },
     },
+    {
+        id: 'zen:space-bunny-free',
+        model: 'space-bunny-free',
+        kind: 'api-openai-compat',
+        envVar: 'OPENCODE_KEYS',
+        baseURL: 'https://opencode.ai/zen/v1',
+        body: { max_tokens: 32768 },
+        //2026-09-24新增: 對話型免費模型中少數REST可通者(免費層閘門未套用, 見檔頭; 例外可能隨時收回)——
+        //匿名1.9s、第1把金鑰2.0s皆200。max_tokens刻意不用zen條目慣例之8192: 此為推理模型, 推理token計入max_tokens,
+        //同日實測列10縣市一題即用5222(推理4849+正文373), 8192易截斷(轉接器遇截斷預設判失敗換家, 見checkTruncation.mjs);
+        //長文(README前8000字)摘要成JSON一題用3385(推理3045), 三題finish_reason皆stop, 故取32768留約6倍餘裕。
+    },
 
 ]
 

package/src/resolveProviders.mjs

@@ -57,7 +57,7 @@ import strFindSimilar from 'wsemi/src/strFindSimilar.mjs'
  * //全取: envVar展開為keys, 缺環境變數者列入skipped
  * let { providers, table, skipped } = resolveProviders(providersAll, { env })
  * console.log(providers.length, skipped)
- * // => 15 []
+ * // => 17 []
  *
  * //pick打錯字時, missing附拼寫提示hints(最接近之可用id)
  * let rm = resolveProviders(providersAll, { env, pick: ['poolside/laguna-s-2.1'] })

package/src/wkf/callAiWithFallback.mjs

@@ -4,8 +4,11 @@ import isearr from 'wsemi/src/isearr.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isobj from 'wsemi/src/isobj.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
 import dispatchAiFallback from '../dispatchAiFallback.mjs'
 import dfTimeoutMs from '../dfTimeoutMs.mjs'
+import buildValidator from '../buildValidator.mjs'
+import { safeValidate } from '../checkTruncation.mjs'
 import extractJsonLoose from './extractJsonLoose.mjs'
 import NO_SIDE_EFFECT from './noSideEffectPrefix.mjs'
 
@@ -19,9 +22,18 @@ import NO_SIDE_EFFECT from './noSideEffectPrefix.mjs'
 //   否則fallback名稱打錯字只會讓遞補鏈無感知地短一截, 事後無從察覺。
 //
 // 【JSON驗證接進遞補層】parse＋check包成dispatchAiFallback的validate:
-//   回覆非法(空回、截斷、缺欄位)時為OUTPUT_VALIDATION_FAILED, 遞補層視為
+//   回覆非法(空回、缺欄位)時為OUTPUT_VALIDATION_FAILED, 遞補層視為
 //   與金鑰無關之失敗而「整組跳過換下一家」(不換組內金鑰——同模型換金鑰仍是
 //   同樣的產出習慣); 端點不穩而偶發空回的模型, 以maxRetries調高令同鍵重試。
+//   parse或check拋錯視同非法(不reject); 條目自帶validate時與本層validate取交集(兩者皆過才算過)——
+//   遞補層之「條目覆寫共用預設」會讓條目validate取代本層validate, 曾致非法回覆通過轉接器、
+//   本層重解析失敗而回ok:false且error為空(不再遞補), 2026-09-24由複審指出後修正。
+//
+// 【截斷(2026-09-24起)】REST文字類轉接器於validate之前判定截斷, 預設回INCOMPLETE_RESPONSE(errorType
+//   incomplete, 遞補層整組跳過且不重試), 不再經驗證失敗路徑。本層之acceptTruncated預設為「有自訂parse且非
+//   rawText」: README明文之策略②(組成自訂parse注入搶救截斷前段, 見salvageTruncatedArray.mjs)本身即同意訊號,
+//   既有使用者不必改任何東西; 預設parse(extractJsonLoose)與rawText遇截斷一律判失敗換家。可顯式覆寫。
+//   CLI類轉接器拿不到終止訊號, 截斷不可判(已知限制)。
 //
 // 【防寫檔前綴】agentic CLI之cwd不是隔離邊界(可用絕對路徑寫到cwd外),
 //   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
@@ -90,16 +102,17 @@ function buildChain(providers, spec) {
  * @param {Function} [opt.check=null] 輸入結果檢核函數(json)=>Boolean，預設null代表只要能解析出JSON即通過
  * @param {Function} [opt.parse=extractJsonLoose] 輸入回覆解析函數(stdout)=>Object|null，預設寬鬆JSON抽取
  * @param {Boolean} [opt.rawText=false] 輸入是否以純文字模式運作布林值，true代表不解析JSON(json欄位為修剪後文字、check收文字)，預設false
+ * @param {Boolean} [opt.acceptTruncated] 輸入是否接受REST文字類轉接器回報之截斷內容(交parse＋check裁決)布林值，預設為「有給自訂parse且非rawText」(自訂parse即搶救策略之同意訊號，見salvageTruncatedArray.mjs)，其餘情況截斷一律判失敗換家
  * @param {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束(見wkf/noSideEffectPrefix.mjs)，傳''關閉
  * @param {Number} [opt.timeoutMs=300000] 輸入單次嘗試逾時毫秒正整數，全套件統一預設300000
  * @param {Number} [opt.budgetMs=null] 輸入整條遞補鏈之時間預算毫秒正整數，預設null代表不限
  * @param {Number} [opt.minAttemptMs=20000] 輸入搭配budgetMs之開工門檻毫秒正整數，剩餘預算低於此值即不再開工，預設20000
- * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試)
+ * @param {Number} [opt.maxRetries=0] 輸入同家重試次數非負整數，預設0(韌性交給遞補；端點不穩偶發空回之模型可調高令同鍵重試；截斷不重試)
  * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
  * @param {Object} [opt.store=null] 輸入游標持久化物件{get,set}，預設null代表用行程內記憶體
  * @param {*} [opt.meta=undefined] 輸入呼叫端自有資訊(分類、標籤、註記)，保留鍵保證永不轉傳下層，預設undefined
  * @param {Function} [opt.onEvent=null] 輸入遞補層事件回調函數，預設null。除上列外之其餘鍵(retryDelayMs、maxBuffer、shouldStop、coolDetect、cooldownMs等)亦一律原樣轉傳dispatchAiFallback
- * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、usage(api類之token用量原樣透傳，CLI類為null)、error(錯誤訊息字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)，本函數不會reject
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否取得可用結果布林值)、json(解析後物件，rawText模式下為文字)、providerId(實際使用之名稱)、keyIndex、keyId、ms(總耗時毫秒)、tried(遞補嘗試歷程陣列)、usage(api類之token用量原樣透傳，CLI類為null)、finishReason(REST文字類之正規化終止原因字串，CLI類為'')、truncated(是否為截斷內容布林值，接受搶救時ok亦可能為true)、error(錯誤訊息字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)，本函數不會reject
  * @example
  * //need cli in system PATH
  *
@@ -152,7 +165,8 @@ async function callAiWithFallback(prompt, opt = {}) {
 
     let rawText = get(opt, 'rawText', false) === true
     let parse = get(opt, 'parse', null)
-    if (!isfun(parse)) {
+    let parseGiven = isfun(parse)
+    if (!parseGiven) {
         parse = extractJsonLoose
     }
     let check = get(opt, 'check', null)
@@ -160,44 +174,71 @@ async function callAiWithFallback(prompt, opt = {}) {
         check = null
     }
 
+    //acceptTruncated, 顯式布林值優先; 預設「有自訂parse且非rawText」——自訂parse即搶救策略之同意訊號(見檔頭【截斷】)
+    let acceptTruncated = get(opt, 'acceptTruncated', null)
+    if (!isbol(acceptTruncated)) {
+        acceptTruncated = parseGiven && !rawText
+    }
+
     let promptPrefix = get(opt, 'promptPrefix', null)
     if (!isestr(promptPrefix)) {
         promptPrefix = (promptPrefix === '') ? '' : NO_SIDE_EFFECT
     }
 
-    //validate接進遞補層: 非法回覆＝這一家失敗, 遞補層換下一家
+    //validate接進遞補層: 非法回覆＝這一家失敗, 遞補層換下一家; parse/check拋錯視同非法(不reject)
     let validate = (stdout) => {
-        if (rawText) {
-            let s = String(stdout || '').trim()
-            if (s === '') {
+        try {
+            if (rawText) {
+                let s = String(stdout || '').trim()
+                if (s === '') {
+                    return false
+                }
+                return check ? check(s) === true : true
+            }
+            let j = parse(stdout)
+            if (j === null) {
                 return false
             }
-            return check ? check(s) === true : true
+            return check ? check(j) === true : true
         }
-        let j = parse(stdout)
-        if (j === null) {
+        catch {
             return false
         }
-        return check ? check(j) === true : true
     }
 
-    //剔除本層自用鍵後原樣轉傳(含minAttemptMs/retryDelayMs/maxBuffer等), providers與validate由本層給定
+    //條目自帶validate時與本層validate取交集(兩者皆過才算過), 免遞補層之條目覆寫令本層驗證被繞過(見檔頭)
+    chain = chain.map((e) => {
+        let ev = buildValidator(get(e, 'validate', null))
+        if (ev === null) {
+            return e
+        }
+        return { ...e, validate: (s) => safeValidate(ev, s).pass && validate(s) }
+    })
+
+    //剔除本層自用鍵後原樣轉傳(含minAttemptMs/retryDelayMs/maxBuffer等), providers、validate與acceptTruncated由本層給定
     let r = await dispatchAiFallback(promptPrefix + prompt, {
         ...omit(opt, OWN_KEYS),
         providers: chain,
         validate,
+        acceptTruncated,
         timeoutMs: get(opt, 'timeoutMs', null) || dfTimeoutMs, //全套件統一預設300000
     })
 
-    //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件
+    //result, 已過validate故此處parse必然成功(同一解析器), 重解析僅為取出物件; 防禦性接住拋錯
     let result = null
     if (r.ok) {
-        result = rawText ? String(r.stdout || '').trim() : parse(r.stdout)
+        try {
+            result = rawText ? String(r.stdout || '').trim() : parse(r.stdout)
+        }
+        catch {
+            result = null
+        }
     }
+    let ok = r.ok && result !== null
     let providerId = get(r, 'providerId', null)
     let keyIndex = get(r, 'keyIndex', null)
     return {
-        ok: r.ok && result !== null,
+        ok,
         json: result, //rawText模式下此欄為文字
         providerId,
         keyIndex,
@@ -205,8 +246,10 @@ async function callAiWithFallback(prompt, opt = {}) {
         ms: Date.now() - t0,
         tried: get(r, 'tried', []),
         usage: get(r, 'usage', null), //api類轉接器之token用量原樣透傳, CLI類為null(無可靠來源)
-        error: r.ok ? '' : get(r, 'error', 'unknown error'),
-        ...(r.ok ? {} : { errorType: get(r, 'errorType', 'exec') }), //機器可讀錯誤類別, 僅失敗時
+        finishReason: get(r, 'finishReason', ''), //REST文字類之正規化終止原因, CLI類為''
+        truncated: get(r, 'truncated', false) === true, //接受搶救之截斷內容時ok亦可能為true
+        error: ok ? '' : (r.ok ? 'OUTPUT_VALIDATION_FAILED' : get(r, 'error', 'unknown error')),
+        ...(ok ? {} : { errorType: r.ok ? 'validation' : get(r, 'errorType', 'exec') }), //機器可讀錯誤類別, 僅失敗時
     }
 }
 

package/src/wkf/runFanout.mjs

@@ -19,6 +19,8 @@ import callAiWithFallback from './callAiWithFallback.mjs'
 //
 // 【實測依據(2026-08-10評比)】整合者是本流程的單點故障——端點不穩的模型
 //   (如偶發靜默空回者)當整合者時, 靠spec.fallback遞補或maxRetries調高才能保住整條鏈。
+//   注意推理模型之空回常是推理耗盡輸出上限(REST類以截斷回報且不重試, 見checkTruncation.mjs),
+//   該調的是max_tokens而非maxRetries。
 
 
 /**

package/src/wkf/salvageTruncatedArray.mjs

@@ -13,6 +13,15 @@
 //
 // 【只搶救「掃到結尾仍未閉合」的截斷】陣列有正常閉合但parse失敗屬別種毛病
 //   (非法字元/壞跳脫), 補`]`救不了反而可能拼出語意錯誤的結果, 一律不碰回null。
+//
+// 【與REST截斷判定之銜接(2026-09-24起)】REST文字類轉接器於validate之前判定截斷且預設失敗;
+//   工作流callAi之acceptTruncated預設為「有自訂parse且非rawText」, 故以本工具組成自訂parse注入即同意
+//   接受截斷內容(既有用法不必改), 結果之truncated:true可辨識救回者為半批; 直接呼叫轉接器須自給acceptTruncated:true。
+//   CLI類拿不到終止訊號, 其截斷只能靠本工具於解析時發現。
+//
+// 【已知限制(2026-09-24複審指出, 讀碼確認)】只記錄頂層「物件」元素之結束(`}`), 故元素非物件之陣列
+//   (如["a","b",…)救不回; 自第一個`[`起算, 故外包物件(如{"items":[…)會救回內層陣列(形狀改變,
+//   呼叫端check須能接受), 前言含`[`(如「[注意]」)則誤判為已閉合而回null。
 
 
 /**

package/test/tools/fakeServerForApiTest.mjs

@@ -1,4 +1,5 @@
 import http from 'http'
+import zlib from 'zlib'
 
 
 // fakeServerForApiTest.mjs — 測試用的OpenAI相容假伺服器
@@ -20,6 +21,9 @@ import http from 'http'
 //   no-choices     — 200但無choices(畸形回應路徑用)
 //   not-json       — 200但本體非JSON(畸形回應路徑用)
 //   tool-calls     — 200但finish_reason為tool_calls(工具不支援路徑用)
+//   br-noheader    — 200, 請求之Accept-Encoding恰為identity才回原文; 否則回brotli壓縮本體且刻意不帶
+//                    Content-Encoding(模擬2026-09-24使用端回報之伺服器: 壓縮卻漏標, Node fetch因而不解壓)
+//   TRUNC_ROUTES   — 200, 依表回指定之finish_reason與content(截斷處理之規格測試用, 見下方常數)
 //   其他           — 404
 // 【responses之行為路由(依body.model)】
 //   echo           — 200, message之output_text為JSON字串{ auth, body }
@@ -30,19 +34,40 @@ import http from 'http'
 //   reasoning-only — 200且completed但output僅reasoning無message(結構不合規)
 //   tool-calls     — 200但output含function_call元素
 //   no-output      — 200但缺output陣列
-//   not-json/slow/err-500/flaky-429 — 同chat/completions之對應行為
+//   incomplete-partial — 200, status為incomplete(max_output_tokens)但已有部分文字(可搶救之截斷陣列)
+//   incomplete-filter  — 200, status為incomplete(content_filter)且有部分文字
+//   no-status      — 200, 缺status欄但有文字(非截斷之不合規狀態)
+//   not-json/slow/err-500/flaky-429/br-noheader — 同chat/completions之對應行為
 //   其他           — 401(同Zen實測: 未知model回401非404)
 // 【systemone之行為路由(POST /v1/systemone, 依body.model; 形狀取自2026-09-17 TypeSafe實測)】
 //   echo / jev-latest — 200, 每題回{type:'noul', noul:0.5, echoAuth, echoBody}, 供斷言請求組成
 //   missing-answer    — 200但answers缺最後一題
 //   no-answers        — 200但無answers
 //   bad-question      — 422 {detail:[{type:'union_tag_invalid',...}]}
-//   not-json/slow/err-500/flaky-429 — 同chat/completions之對應行為
+//   not-json/slow/err-500/flaky-429/br-noheader — 同chat/completions之對應行為
 //   其他              — 400 {detail:{error_type:'api_usage_error', message:'Unknown model: X'}}
 // 【金鑰規則】Authorization含'sk-bad'一律401(優先於model路由), 模擬無效金鑰;
 //   systemone路由之401本體採TypeSafe形狀{detail:{error_type:'authentication_error'}}。
 
 
+//TRUNC_ROUTES, chat/completions之截斷與終止原因情境(2026-09-24截斷處理之規格測試):
+//fr為finish_reason原值(含大小寫與null), content為message.content原值(含null與純空白)
+let TRUNC_ROUTES = {
+    'trunc-empty': { fr: 'length', content: '', usage: { prompt_tokens: 181, completion_tokens: 600, total_tokens: 781, completion_tokens_details: { reasoning_tokens: 600 } } }, //推理耗盡(Zen實測形態)
+    'trunc-null': { fr: 'length', content: null },
+    'trunc-space': { fr: 'length', content: '\n\n' },
+    'trunc-array': { fr: 'length', content: '[{"a":1},{"b":2},{"c":' }, //可搶救前段
+    'trunc-text': { fr: 'length', content: '第一段說明，第二' },
+    'trunc-tail': { fr: 'length', content: '{"a":1}\n\n說明：因為' }, //完整載荷+截尾(寬鬆解析可過)
+    'trunc-upper': { fr: 'LENGTH', content: '[{"a":1},{"b":' }, //大小寫不同
+    'filtered': { fr: 'content_filter', content: '部分內容' },
+    'finish-stop': { fr: 'stop', content: '完成' },
+    'finish-null': { fr: null, content: '完成' },
+    'finish-other': { fr: 'eos', content: '完成' }, //未知值, 不可誤殺
+    'plain-content': { fr: 'stop', content: 'hello world' }, //非JSON純文字
+}
+
+
 /**
  * 啟動測試用OpenAI相容假伺服器
  *
@@ -73,6 +98,14 @@ async function fakeServerForApiTest() {
 
             let auth = req.headers['authorization'] || ''
 
+            //sendUndeclaredBr, br-noheader路由用: 客戶端明示identity才回原文, 否則回brotli本體且刻意不帶Content-Encoding
+            let ae = String(req.headers['accept-encoding'] || '').trim().toLowerCase()
+            let sendUndeclaredBr = (obj) => {
+                let buf = Buffer.from(JSON.stringify(obj))
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(ae === 'identity' ? buf : zlib.brotliCompressSync(buf))
+            }
+
             //body非JSON → 400
             let body = null
             try {
@@ -129,6 +162,13 @@ async function fakeServerForApiTest() {
                 else if (model === 'bad-question') {
                     send(422, { detail: [{ type: 'union_tag_invalid', loc: ['body', 'questions', ids[0]], msg: 'Input tag does not match any of the expected tags' }] })
                 }
+                else if (model === 'br-noheader') {
+                    let answers = {}
+                    for (let id of ids) {
+                        answers[id] = { type: 'noul', noul: 0.5 }
+                    }
+                    sendUndeclaredBr({ model: 'jev-1.13.0', answers, usage })
+                }
                 else if (model === 'not-json') {
                     res.writeHead(200, { 'Content-Type': 'text/plain' })
                     res.end('plain text body')
@@ -217,6 +257,32 @@ async function fakeServerForApiTest() {
                 else if (model === 'no-output') { //缺output陣列
                     send(200, { status: 'completed', model, id: 'resp_y' })
                 }
+                else if (model === 'incomplete-partial') { //max_output_tokens耗盡但已有部分文字
+                    send(200, {
+                        status: 'incomplete',
+                        model,
+                        error: null,
+                        incomplete_details: { reason: 'max_output_tokens' },
+                        output: [{ type: 'message', content: [{ type: 'output_text', text: '[{"a":1},{"b":2},{"c":' }] }],
+                        usage: { ...usage, output_tokens_details: { reasoning_tokens: 9 } },
+                    })
+                }
+                else if (model === 'incomplete-filter') {
+                    send(200, { status: 'incomplete', model, error: null, incomplete_details: { reason: 'content_filter' }, output: [{ type: 'message', content: [{ type: 'output_text', text: '部分' }] }], usage })
+                }
+                else if (model === 'no-status') {
+                    send(200, { model, error: null, incomplete_details: null, output: [{ type: 'message', content: [{ type: 'output_text', text: 'x' }] }], usage })
+                }
+                else if (model === 'br-noheader') {
+                    sendUndeclaredBr({
+                        status: 'completed',
+                        model,
+                        error: null,
+                        incomplete_details: null,
+                        output: [{ type: 'message', content: [{ type: 'output_text', text: '完成' }] }],
+                        usage,
+                    })
+                }
                 else if (model === 'not-json') {
                     res.writeHead(200, { 'Content-Type': 'text/plain' })
                     res.end('plain text body')
@@ -290,6 +356,17 @@ async function fakeServerForApiTest() {
                 res.writeHead(200, { 'Content-Type': 'application/json' })
                 res.end(JSON.stringify({ id: 'x', object: 'chat.completion' }))
             }
+            else if (model === 'br-noheader') {
+                sendUndeclaredBr({ choices: [{ finish_reason: 'stop', message: { role: 'assistant', content: '完成' } }] })
+            }
+            else if (TRUNC_ROUTES[model] !== undefined) {
+                let t = TRUNC_ROUTES[model]
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({
+                    choices: [{ finish_reason: t.fr, message: { role: 'assistant', content: t.content } }],
+                    usage: t.usage || { prompt_tokens: 3, completion_tokens: 7, total_tokens: 10 },
+                }))
+            }
             else if (model === 'not-json') {
                 res.writeHead(200, { 'Content-Type': 'text/plain' })
                 res.end('plain text body')

package/test/unit-dispatchApiOpenaiCompat.test.mjs

@@ -3,6 +3,8 @@ import dispatchApiOpenaiCompat from '../src/dispatchApiOpenaiCompat.mjs'
 import dispatchAi from '../src/dispatchAi.mjs'
 import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
 import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import extractJsonLoose from '../src/wkf/extractJsonLoose.mjs'
+import salvageTruncatedArray from '../src/wkf/salvageTruncatedArray.mjs'
 import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
 
 
@@ -161,6 +163,20 @@ describe('dispatchApiOpenaiCompat', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('預設帶Accept-Encoding: identity——伺服器壓縮卻漏標Content-Encoding時仍可正確解析(2026-09-24使用端回報)', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'br-noheader' })
+        let r = [t.ok, t.code, t.stdout, t.error]
+        let rr = [true, 200, '完成', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('呼叫端headers可覆寫Accept-Encoding: 改回允許壓縮時, 遇漏標之壓縮本體即解析失敗(invalid-response)', async function() {
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'br-noheader', headers: { 'Accept-Encoding': 'gzip, deflate' } })
+        let r = [t.ok, t.code, t.errorType, t.error]
+        let rr = [false, 200, 'invalid-response', 'INVALID_RESPONSE: missing choices[0].message.content']
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('validate字串規則與自訂函數皆可用, 失敗回傳OUTPUT_VALIDATION_FAILED', async function() {
         let t1 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'empty-content', validate: 'nonempty' })
         let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: 'nonempty,json' })
@@ -205,7 +221,159 @@ describe('dispatchApiOpenaiCompat', function() {
             ],
         })
         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']]]
+        let rr = [true, 'g-text', [['g-tool#0', 'skip-group'], ['g-text#0', 'ok']]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('截斷預設失敗: finish_reason為length且可見輸出為空(空字串/null/純空白)一律incomplete, 訊息標明無可見輸出並附reasoning_tokens', async function() {
+        let r = []
+        for (let model of ['trunc-empty', 'trunc-null', 'trunc-space']) {
+            let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model })
+            r.push([t.ok, t.errorType, t.truncated, t.finishReason, t.error.indexOf('INCOMPLETE_RESPONSE: finish_reason=length') === 0, t.error.includes('no visible output')])
+        }
+        let t0 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-empty' })
+        r.push(t0.error.includes('reasoning_tokens=600'))
+        let rr = [
+            [false, 'incomplete', true, 'length', true, true],
+            [false, 'incomplete', true, 'length', true, true],
+            [false, 'incomplete', true, 'length', true, true],
+            true,
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('截斷預設失敗且與validate無關: 截斷陣列/截斷文字/完整載荷加截尾 × {無, nonempty, json, 搶救函數}皆incomplete', async function() {
+        let salvage = (s) => salvageTruncatedArray(s) !== null
+        let r = []
+        for (let model of ['trunc-array', 'trunc-text', 'trunc-tail']) {
+            for (let validate of [undefined, 'nonempty', 'json', salvage]) {
+                let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model, validate })
+                r.push([model, t.ok, t.errorType, t.truncated])
+            }
+        }
+        let rr = []
+        for (let model of ['trunc-array', 'trunc-text', 'trunc-tail']) {
+            for (let i = 0; i < 4; i++) {
+                rr.push([model, false, 'incomplete', true])
+            }
+        }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('acceptTruncated:true才放行: length且內容非空交validate(通過ok帶truncated、不過incomplete、無validate亦ok); 空內容與content_filter仍失敗', async function() {
+        let salvage = (s) => salvageTruncatedArray(s) !== null
+        let a1 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-array', acceptTruncated: true, validate: salvage })
+        let a2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-text', acceptTruncated: true, validate: 'json' })
+        let a3 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-text', acceptTruncated: true })
+        let a4 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-empty', acceptTruncated: true })
+        let a5 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'filtered', acceptTruncated: true })
+        let r = [
+            [a1.ok, a1.stdout, a1.truncated, a1.finishReason],
+            [a2.ok, a2.errorType, a2.truncated, a2.error.includes('rejected by validate')],
+            [a3.ok, a3.stdout, a3.truncated],
+            [a4.ok, a4.errorType],
+            [a5.ok, a5.errorType, a5.truncated, a5.finishReason],
+        ]
+        let rr = [
+            [true, '[{"a":1},{"b":2},{"c":', true, 'length'],
+            [false, 'incomplete', true, true],
+            [true, '第一段說明，第二', true],
+            [false, 'incomplete'],
+            [false, 'incomplete', true, 'content_filter'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('防誤殺: finish_reason為stop、null、未知值時照常成功且truncated為false; 截斷判定不分大小寫', async function() {
+        let r = []
+        for (let model of ['finish-stop', 'finish-null', 'finish-other']) {
+            let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model })
+            r.push([model, t.ok, t.stdout, t.truncated, t.finishReason])
+        }
+        let tu = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-upper' })
+        r.push(['trunc-upper', tu.ok, tu.errorType, tu.finishReason])
+        let rr = [
+            ['finish-stop', true, '完成', false, 'stop'],
+            ['finish-null', true, '完成', false, ''],
+            ['finish-other', true, '完成', false, 'eos'],
+            ['trunc-upper', false, 'incomplete', 'length'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('截斷與金鑰無關: 遞補鏈只試一把即整組跳過且tried帶truncated; 轉接器重試遇截斷不重打', async function() {
+        let t = await dispatchAiFallback('abc', {
+            providers: [
+                { id: 'g-trunc', kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-a0', 'sk-a1'] },
+                { id: 'g-ok', kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-b0'] },
+            ],
+        })
+        let t2 = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'trunc-text', maxRetries: 2, retryDelayMs: 10 })
+        let r = [t.ok, t.providerId, t.tried.map((x) => [x.keyId, x.outcome, x.truncated === true]), t2.attempts]
+        let rr = [true, 'g-ok', [['g-trunc#0', 'skip-group', true], ['g-ok#0', 'ok', false]], 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate拋錯視同驗證失敗, Promise照常resolve不reject', async function() {
+        let boom = () => {
+            throw new Error('boom-validate')
+        }
+        let t = await dispatchApiOpenaiCompat('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', validate: boom })
+        let r = [t.ok, t.errorType, t.error, t.stderr.includes('boom-validate')]
+        let rr = [false, 'validation', 'OUTPUT_VALIDATION_FAILED', true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('工作流: 自訂搶救parse遇截斷即視為同意→ok且json為前段、truncated可見; 預設parse、rawText、明示acceptTruncated:false遇截斷→失敗', async function() {
+        let wkf = dispatchAiWkf({
+            providers: {
+                'p-trunc': { kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-array', keys: ['sk-w1'] },
+                'p-trunc-text': { kind: 'api-openai-compat', baseURL: svr.url, model: 'trunc-text', keys: ['sk-w2'] },
+            },
+            defaults: { promptPrefix: '' },
+        })
+        let parseSalvage = (s) => extractJsonLoose(s) || salvageTruncatedArray(s)
+        let t1 = await wkf.callAi('abc', { spec: { use: 'p-trunc' }, parse: parseSalvage })
+        let t2 = await wkf.callAi('abc', { spec: { use: 'p-trunc' } })
+        let t3 = await wkf.callAi('abc', { spec: { use: 'p-trunc-text' }, rawText: true })
+        let t4 = await wkf.callAi('abc', { spec: { use: 'p-trunc' }, parse: parseSalvage, acceptTruncated: false })
+        let r = [
+            [t1.ok, t1.json, t1.truncated, t1.finishReason],
+            [t2.ok, t2.errorType, t2.truncated, t2.tried.map((x) => x.outcome)],
+            [t3.ok, t3.errorType],
+            [t4.ok, t4.errorType],
+        ]
+        let rr = [
+            [true, [{ a: 1 }, { b: 2 }], true, 'length'],
+            [false, 'incomplete', true, ['skip-group']],
+            [false, 'incomplete'],
+            [false, 'incomplete'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('工作流: 條目自帶validate不再繞過工作流驗證(兩者取交集), 不過即遞補下一家', async function() {
+        let wkf = dispatchAiWkf({
+            providers: {
+                'p-plain': { kind: 'api-openai-compat', baseURL: svr.url, model: 'plain-content', keys: ['sk-v1'], validate: 'nonempty' },
+                'p-echo': { kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-v2'] },
+            },
+            defaults: { promptPrefix: '' },
+        })
+        let t = await wkf.callAi('abc', { spec: { use: 'p-plain', fallback: ['p-echo'] } })
+        let r = [t.ok, t.providerId, t.tried.map((x) => [x.providerId, x.outcome, x.error || null])]
+        let rr = [true, 'p-echo', [['p-plain', 'skip-group', 'OUTPUT_VALIDATION_FAILED'], ['p-echo', 'ok', null]]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('工作流: check拋錯視同驗證失敗, callAi照常resolve不reject', async function() {
+        let wkf = dispatchAiWkf({
+            providers: { 'p-e1': { kind: 'api-openai-compat', baseURL: svr.url, model: 'echo', keys: ['sk-c1'] } },
+            defaults: { promptPrefix: '' },
+        })
+        let t = await wkf.callAi('abc', { spec: { use: 'p-e1' }, check: (j) => j.nope.deep === 1 })
+        let r = [t.ok, t.errorType, t.error]
+        let rr = [false, 'validation', 'OUTPUT_VALIDATION_FAILED']
         assert.strict.deepEqual(r, rr)
     })