w-dispatch-ai 1.0.36 → 1.0.38

package/src/dispatchApiTypesafeSystemone.mjs

@@ -11,6 +11,8 @@ import castPintOr from './castPintOr.mjs'
 import buildValidator from './buildValidator.mjs'
 import getErrorResult from './getErrorResult.mjs'
 import dfTimeoutMs from './dfTimeoutMs.mjs'
+import { safeValidate } from './checkTruncation.mjs'
+import describeNonJsonBody from './describeNonJsonBody.mjs'
 
 
 // dispatchApiTypesafeSystemone.mjs — 以fetch直呼TypeSafe AI之System One API(POST /v1/systemone)
@@ -41,6 +43,11 @@ import dfTimeoutMs from './dfTimeoutMs.mjs'
 //   {detail:{error_type:'api_usage_error', message:'Unknown model: X'}}; 題型不合規或questions為空422
 //   {detail:[{type,loc,msg,...}]}。皆以HTTP <code>回報、原始本體置stderr; 4xx(429除外)不重試。
 //
+// 【預設帶Accept-Encoding: identity(2026-09-24起)】防伺服器壓縮卻漏標Content-Encoding而令fetch不解壓、
+//   JSON.parse失敗; 與dispatchApiOpenaiCompat同一決策與依據(見該檔檔頭; 本kind亦經Zen之/systemone), opt.headers可覆寫。
+//   HTTP 200但本體非JSON時另報INVALID_RESPONSE: body is not JSON(附原始位元組資訊), 與「缺answers」分開
+//   (同dispatchApiOpenaiCompat, 見describeNonJsonBody.mjs)。
+//
 // 【混用注意】
 //   1. 答案形狀與文字模型完全不同, 不可與文字生成條目混在同一條dispatchAiFallback鏈中遞補;
 //      同一鏈只放本kind之條目(可多把金鑰輪替)。預設providers.mjs收有typesafe:jev-latest,
@@ -99,7 +106,9 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
         controller.abort()
     }, timeoutMs)
 
+    //本體先取原始位元組再以UTF-8解碼(等同res.text()), 本體非JSON時才有原始位元組可供診斷(見describeNonJsonBody.mjs)
     let res = null
+    let raw = new Uint8Array(0)
     let txt = ''
     try {
         res = await fetch(url, {
@@ -108,7 +117,8 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
             body: JSON.stringify(body),
             signal: controller.signal,
         })
-        txt = await res.text()
+        raw = new Uint8Array(await res.arrayBuffer())
+        txt = new TextDecoder('utf-8').decode(raw)
     }
     catch (err) {
         clearTimeout(timer)
@@ -138,6 +148,7 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
     let answers = null
     let modelResolved = ''
     let usage = null
+    let parsed = true
     try {
         let j = JSON.parse(txt)
         answers = get(j, 'answers', null)
@@ -151,7 +162,17 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
         }
     }
     catch {
-        answers = null
+        parsed = false
+    }
+
+    //本體非JSON, 與「JSON缺answers」分開回報並附原始位元組資訊; 遞補層據前綴整組跳過(見describeNonJsonBody.mjs)
+    if (!parsed) {
+        return mkResult({
+            stderr: strTruncate(txt, 500, optTruncate),
+            code: res.status,
+            error: describeNonJsonBody(raw, res.headers),
+            errorType: 'invalid-response',
+        })
     }
     if (!isobj(answers)) {
         return mkResult({
@@ -180,16 +201,20 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
     //content, answers序列化為stdout(令遞補層與工作流層之parse/check通用)
     let content = JSON.stringify(answers)
 
-    //validator, error與execCli一致令dispatchAiFallback可統一分流
-    if (validator && !validator(content)) {
-        return mkResult({
-            stdout: strTruncate(content, 500, optTruncate),
-            code: res.status,
-            error: 'OUTPUT_VALIDATION_FAILED',
-            errorType: 'validation',
-            usage,
-            modelResolved,
-        })
+    //validator, error與execCli一致令dispatchAiFallback可統一分流; 拋錯視同拒絕(不reject), 訊息置stderr
+    if (validator) {
+        let v = safeValidate(validator, content)
+        if (!v.pass) {
+            return mkResult({
+                stdout: strTruncate(content, 500, optTruncate),
+                stderr: v.threw ? `validate threw: ${v.threw}` : '',
+                code: res.status,
+                error: 'OUTPUT_VALIDATION_FAILED',
+                errorType: 'validation',
+                usage,
+                modelResolved,
+            })
+        }
     }
 
     return mkResult({
@@ -225,9 +250,9 @@ async function callOnce(url, headers, body, ids, timeoutMs, validator) {
  * @param {String} [opt.model='jev-latest'] 輸入模型名稱字串，預設'jev-latest'(另有'jev-preview')
  * @param {String} [opt.key=''] 輸入API key字串，以Bearer置於Authorization標頭，預設''代表不帶認證標頭
  * @param {Object} [opt.body={}] 輸入額外請求本體物件，將併入預設body(同名鍵以此為準)，預設{}
- * @param {Object} [opt.headers={}] 輸入額外請求標頭物件，預設{}
+ * @param {Object} [opt.headers={}] 輸入額外請求標頭物件，同名鍵覆寫預設標頭；預設標頭含'Accept-Encoding: identity'(防伺服器壓縮卻漏標Content-Encoding，見檔頭)，預設{}
  * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將中止請求，全套件統一預設300000
- * @param {String|Function} [opt.validate=undefined] 輸入stdout(answers之JSON字串)驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
+ * @param {String|Function} [opt.validate=undefined] 輸入stdout(answers之JSON字串)驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，自訂函數拋錯視同驗證失敗，預設undefined代表不驗證
  * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，4xx(429除外)不重試，預設0
  * @param {Number} [opt.retryDelayMs=5000] 輸入重試間隔毫秒正整數，實際間隔為retryDelayMs乘以重試次數且上限15000ms，預設5000
  * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(answers之JSON字串)、stderr(失敗時之原始回應本體)、code(HTTP狀態碼，網路錯誤與逾時為null)、error(錯誤訊息字串，成功時為空字串)、errorType(僅失敗時，機器可讀錯誤類別字串，一覽見getErrorType.mjs檔頭)、durationMs(耗時毫秒)、attempts(實際嘗試次數)、usage(原始回應之token用量物件原樣透傳，欄位名為input_tokens/output_tokens，無則null)、answers(成功時為已解析之答案物件，否則null)、modelResolved(回應所載之實際模型版本字串，如'jev-1.13.0'，無則'')，本函數不會reject
@@ -335,7 +360,7 @@ async function dispatchApiTypesafeSystemone(prompt, opt = {}) {
     let ids = Object.keys(isobj(body.questions) ? body.questions : questions)
 
     //headers
-    let headers = { 'Content-Type': 'application/json', ...headersExtra }
+    let headers = { 'Content-Type': 'application/json', 'Accept-Encoding': 'identity', ...headersExtra } //Accept-Encoding預設identity, 見檔頭
     if (isestr(key)) {
         headers['Authorization'] = `Bearer ${key}`
     }

package/src/getErrorType.mjs

@@ -23,9 +23,13 @@ import isestr from 'wsemi/src/isestr.mjs'
 //   'fetch'            網路層錯誤(DNS/連線拒絕, 僅api類)
 //   'tool-unsupported' 模型回tool_calls而本轉接器不支援工具(僅api類)
 //   'invalid-response' 回應結構不合規(缺choices[0].message.content、缺output陣列,
-//                      或api-typesafe-systemone缺answers物件/缺所請求題目之答案, 僅api類)
-//   'incomplete'       Responses API之status非completed(如max_output_tokens耗盡而截斷,
-//                      僅api-openai-responses; 半截內容不當成功回傳, 見該轉接器檔頭)
+//                      或api-typesafe-systemone缺answers物件/缺所請求題目之答案, 僅api類);
+//                      HTTP 200但本體非JSON時error另為'INVALID_RESPONSE: body is not JSON (...)'(附位元組資訊,
+//                      遞補層整組跳過; 見describeNonJsonBody.mjs), 「JSON缺欄位」則仍換金鑰
+//   'incomplete'       回應未完整: 截斷(chat/completions之finish_reason為length/content_filter、
+//                      Responses API之status為incomplete; 結果另帶truncated:true, 規則見checkTruncation.mjs)
+//                      與Responses API之其餘非completed狀態(如failed; truncated:false)。僅api類;
+//                      半截內容預設不當成功回傳, 呼叫端明示acceptTruncated才可放行(2026-09-24起兩轉接器同規則)
 //   'aborted'          shouldStop中止(僅dispatchAiFallback)
 //   'budget'           時間預算用盡(僅dispatchAiFallback)
 

package/src/providers.mjs

@@ -398,7 +398,7 @@ let providers = [
         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易截斷, 而本轉接器遇截斷仍回ok(內容殘缺或為空);
+        //同日實測列10縣市一題即用5222(推理4849+正文373), 8192易截斷(轉接器遇截斷預設判失敗換家, 見checkTruncation.mjs);
         //長文(README前8000字)摘要成JSON一題用3385(推理3045), 三題finish_reason皆stop, 故取32768留約6倍餘裕。
     },
 

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,19 @@ 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遇截斷一律判失敗換家。可顯式覆寫。
+//   注意此自動同意只在本層: 直接呼叫dispatchAiFallback或轉接器、把搶救寫在validate裡者須自給acceptTruncated:true。
+//   CLI類轉接器拿不到終止訊號, 截斷不可判(已知限制)。
 //
 // 【防寫檔前綴】agentic CLI之cwd不是隔離邊界(可用絕對路徑寫到cwd外),
 //   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
@@ -90,16 +103,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 +166,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 +175,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 +247,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,17 @@
 //
 // 【只搶救「掃到結尾仍未閉合」的截斷】陣列有正常閉合但parse失敗屬別種毛病
 //   (非法字元/壞跳脫), 補`]`救不了反而可能拼出語意錯誤的結果, 一律不碰回null。
+//
+// 【與REST截斷判定之銜接(2026-09-24起)】REST文字類轉接器於validate之前判定截斷且預設失敗;
+//   工作流callAi之acceptTruncated預設為「有自訂parse且非rawText」, 故以本工具組成自訂parse注入即同意
+//   接受截斷內容(既有用法不必改), 結果之truncated:true可辨識救回者為半批; 直接呼叫dispatchAiFallback或轉接器、
+//   且把本工具寫在validate裡者須自給acceptTruncated:true(1.0.37起, 否則截斷在validate之前即判失敗;
+//   安裝方實例: w-knowledge-extract 1.0.1之callJson因此失去搶救, 2026-09-24回報)。
+//   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,10 @@ 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(截斷處理之規格測試用, 見下方常數)
+//   garbage-200    — 200, Content-Type為application/json但本體為8個非JSON位元組(模擬壓縮或損壞本體)
 //   其他           — 404
 // 【responses之行為路由(依body.model)】
 //   echo           — 200, message之output_text為JSON字串{ auth, body }
@@ -30,19 +35,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/garbage-200 — 同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/garbage-200 — 同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 +99,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 {
@@ -84,6 +118,13 @@ async function fakeServerForApiTest() {
                 return
             }
 
+            //garbage-200, 三種端點共用: 200且宣稱JSON, 本體卻是8個非JSON位元組(不論Accept-Encoding)
+            if (body.model === 'garbage-200') {
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(Buffer.from([0x8b, 0xef, 0x02, 0x00, 0xe4, 0xff, 0x11, 0x22]))
+                return
+            }
+
             //無效金鑰, 模擬Zen之401形態(systemone則模擬TypeSafe之形態)
             if (auth.includes('sk-bad')) {
                 res.writeHead(401, { 'Content-Type': 'application/json' })
@@ -129,6 +170,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 +265,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 +364,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')