w-dispatch-ai 1.0.36 → 1.0.37

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)
     })
 

package/test/unit-dispatchApiOpenaiResponses.test.mjs

@@ -3,6 +3,7 @@ import dispatchApiOpenaiResponses, { extractOutputText } from '../src/dispatchAp
 import dispatchAi from '../src/dispatchAi.mjs'
 import dispatchAiFallback from '../src/dispatchAiFallback.mjs'
 import dispatchAiWkf from '../src/dispatchAiWkf.mjs'
+import salvageTruncatedArray from '../src/wkf/salvageTruncatedArray.mjs'
 import fakeServerForApiTest from './tools/fakeServerForApiTest.mjs'
 
 
@@ -77,20 +78,77 @@ describe('dispatchApiOpenaiResponses', function() {
         assert.strict.deepEqual(r, rr)
     })
 
-    it('status非completed一律失敗不回半截內容: incomplete與failed', async function() {
+    it('預設帶Accept-Encoding: identity——伺服器壓縮卻漏標Content-Encoding時仍可正確解析(同dispatchApiOpenaiCompat)', async function() {
+        let t = await dispatchApiOpenaiResponses('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('status非completed預設失敗不回半截內容: incomplete(截斷, 無可見輸出另附說明)與failed(非截斷)', async function() {
         let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete' })
         let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'failed' })
         let r = [
-            [t1.ok, t1.errorType, t1.error],
-            [t2.ok, t2.errorType, t2.error],
+            [t1.ok, t1.errorType, t1.error, t1.truncated, t1.finishReason],
+            [t2.ok, t2.errorType, t2.error, t2.truncated],
+        ]
+        let rr = [
+            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=incomplete (max_output_tokens); no visible output (reasoning may have used up the output token limit)', true, 'length'],
+            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=failed (upstream blew up)', false],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('截斷(incomplete)帶部分文字預設失敗; acceptTruncated:true且validate通過則ok帶truncated; content_filter一律失敗; 重試遇截斷不重打', async function() {
+        let salvage = (s) => salvageTruncatedArray(s) !== null
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete-partial' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete-partial', acceptTruncated: true, validate: salvage })
+        let t3 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete-filter', acceptTruncated: true })
+        let t4 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'incomplete-partial', maxRetries: 2, retryDelayMs: 10 })
+        let r = [
+            [t1.ok, t1.errorType, t1.truncated, t1.finishReason, t1.error],
+            [t2.ok, t2.stdout, t2.truncated, t2.finishReason],
+            [t3.ok, t3.errorType, t3.truncated, t3.finishReason],
+            t4.attempts,
         ]
         let rr = [
-            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=incomplete (max_output_tokens)'],
-            [false, 'incomplete', 'INCOMPLETE_RESPONSE: status=failed (upstream blew up)'],
+            [false, 'incomplete', true, 'length', 'INCOMPLETE_RESPONSE: status=incomplete (max_output_tokens)'],
+            [true, '[{"a":1},{"b":2},{"c":', true, 'length'],
+            [false, 'incomplete', true, 'content_filter'],
+            1,
         ]
         assert.strict.deepEqual(r, rr)
     })
 
+    it('failed與缺status非截斷(truncated為false), 遞補鏈照舊逐把換金鑰; 完成時finishReason為stop', async function() {
+        let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'no-status' })
+        let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo' })
+        let tf = await dispatchAiFallback('abc', {
+            providers: [{ id: 'g-failed', kind: 'api-openai-responses', baseURL: svr.url, model: 'failed', keys: ['sk-f0', 'sk-f1'] }],
+        })
+        let r = [
+            [t1.ok, t1.errorType, t1.truncated, t1.error],
+            [t2.ok, t2.truncated, t2.finishReason],
+            tf.tried.map((x) => [x.keyId, x.outcome]),
+        ]
+        let rr = [
+            [false, 'incomplete', false, 'INCOMPLETE_RESPONSE: status=missing (unknown)'],
+            [true, false, 'stop'],
+            [['g-failed#0', 'next-key'], ['g-failed#1', 'next-key']],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate拋錯視同驗證失敗, Promise照常resolve不reject', async function() {
+        let boom = () => {
+            throw new Error('boom-validate')
+        }
+        let t = await dispatchApiOpenaiResponses('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('結構不合規之回應: 缺output陣列、非JSON、僅reasoning無message', async function() {
         let t1 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'no-output' })
         let t2 = await dispatchApiOpenaiResponses('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'not-json' })

package/test/unit-dispatchApiTypesafeSystemone.test.mjs

@@ -58,6 +58,23 @@ describe('dispatchApiTypesafeSystemone', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('預設帶Accept-Encoding: identity——伺服器壓縮卻漏標Content-Encoding時仍可正確解析(同dispatchApiOpenaiCompat)', async function() {
+        let t = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'br-noheader', questions: Q })
+        let r = [t.ok, t.code, Object.keys(t.answers || {}), t.error]
+        let rr = [true, 200, ['category', 'urgent'], '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('validate拋錯視同驗證失敗, Promise照常resolve不reject(同dispatchApiOpenaiCompat)', async function() {
+        let boom = () => {
+            throw new Error('boom-validate')
+        }
+        let t = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', questions: Q, 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('成功: stdout為answers之JSON字串且與answers一致, 追加modelResolved, usage原樣透傳', async function() {
         let t = await dispatchApiTypesafeSystemone('abc', { baseURL: svr.url, key: 'sk-good-1', model: 'echo', questions: Q })
         let r = [t.ok, t.error, JSON.parse(t.stdout), Object.keys(t.answers), t.modelResolved, t.usage]