w-dispatch-ai 1.0.2 → 1.0.4

package/src/wkf/extractJsonLoose.mjs

@@ -0,0 +1,108 @@
+// extractJsonLoose.mjs — 從AI回覆文字中寬鬆抽取JSON(工作流層預設解析器, 可被注入覆寫)
+//
+// 【為何需要】各家CLI的回覆常帶code fence、前後說明文字、ANSI色碼;
+//   直接JSON.parse必炸。本函數做清理後以「括號配對」找出第一個完整
+//   物件或陣列再解析。呼叫端若有更強的解析器(如含截斷搶救), 以opt.parse注入即可。
+
+
+/**
+ * 從文字中抽取第一個完整的JSON物件或陣列
+ *
+ * 特點：
+ * 先去除ANSI色碼與code fence標記後嘗試整段解析(最常見情境之最快路徑)；
+ * 整段非法時自第一個`{`或`[`起以括號配對(跳過字串與跳脫)取得第一個完整片段再解析；
+ * 僅接受物件與陣列，純量(字串/數字/布林)回傳null；
+ * 括號未閉合(輸出被截斷)或片段非法一律回傳null，不throw
+ *
+ * @param {String} text 輸入AI回覆文字字串
+ * @returns {Object|Array|null} 回傳解析成功之物件或陣列，失敗回傳null
+ * @example
+ *
+ * import extractJsonLoose from './src/wkf/extractJsonLoose.mjs'
+ *
+ * console.log(extractJsonLoose('{"a":1}'))
+ * // => { a: 1 }
+ *
+ * console.log(extractJsonLoose('說明文字\n```json\n{"a":1}\n```\n後記'))
+ * // => { a: 1 }
+ *
+ * console.log(extractJsonLoose('{"a":1')) //截斷
+ * // => null
+ *
+ * console.log(extractJsonLoose('純文字回覆'))
+ * // => null
+ *
+ */
+function extractJsonLoose(text) {
+    let s = String(text || '')
+
+    //去ANSI色碼與code fence標記
+    s = s.replace(new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g'), '')
+    s = s.replace(/```(?:json)?/g, '')
+    s = s.trim()
+    if (s === '') {
+        return null
+    }
+
+    //整段直接解析(最常見情境, 最快路徑)
+    try {
+        let j = JSON.parse(s)
+        if (j !== null && typeof j === 'object') {
+            return j
+        }
+    }
+    catch (e) { /* 進入括號配對路徑 */ }
+
+    //括號配對: 自第一個{或[起, 逐字元追蹤深度(跳過字串與跳脫), 取得第一個完整片段
+    let start = -1
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '{' || s[i] === '[') {
+            start = i
+            break
+        }
+    }
+    if (start < 0) {
+        return null
+    }
+    let depth = 0
+    let inStr = false
+    let esc = false
+    for (let i = start; i < s.length; i++) {
+        let c = s[i]
+        if (inStr) {
+            if (esc) {
+                esc = false
+            }
+            else if (c === '\\') {
+                esc = true
+            }
+            else if (c === '"') {
+                inStr = false
+            }
+            continue
+        }
+        if (c === '"') {
+            inStr = true
+        }
+        else if (c === '{' || c === '[') {
+            depth++
+        }
+        else if (c === '}' || c === ']') {
+            depth--
+            if (depth === 0) {
+                try {
+                    let j = JSON.parse(s.slice(start, i + 1))
+                    if (j !== null && typeof j === 'object') {
+                        return j
+                    }
+                }
+                catch (e) { /* 片段仍非法, 視為失敗 */ }
+                return null
+            }
+        }
+    }
+    return null //括號未閉合(輸出被截斷)
+}
+
+
+export default extractJsonLoose

package/src/wkf/runFanout.mjs

@@ -0,0 +1,155 @@
+import get from 'lodash-es/get.js'
+import isearr from 'wsemi/src/isearr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import callAiWithFallback from './callAiWithFallback.mjs'
+
+
+// runFanout.mjs — Fanout工作流: 多開執行＋單點整合收斂
+//
+// 【結構】前段(fanout)並行開N個AI名額執行同一任務, 各名額可指定主模型與自帶fallback;
+//   後段開單一AI名額把成功候選整合成最終版; 整合成果即工作流成果。
+//
+// 【部分接受】個別名額失敗不炸整輪: 成功候選達minCandidates才進整合;
+//   未達門檻(含恰為1份)時不硬整合, 直接以首位成功候選為成果(integrated:false)——
+//   單稿無從「整合」, 硬呼叫整合者只是空耗一次額度。
+//   全部失敗才回ok:false, 且已成功候選仍完整回傳(便於接續重試)。
+//
+// 【實測依據(2026-08-10評比)】整合者是本流程的單點故障——端點不穩的模型
+//   (如偶發靜默空回者)當整合者時, 靠spec.fallback遞補或maxRetries調高才能保住整條鏈。
+
+
+/**
+ * 預設整合提示詞模板：把成功候選JSON併入整合任務
+ *
+ * @param {Array} candidates 輸入成功候選物件陣列
+ * @param {Object} [opt={}] 輸入設定物件(取schema作為輸出格式示意)，預設{}
+ * @returns {String} 回傳整合提示詞字串
+ */
+function defaultIntegratePrompt(candidates, opt = {}) {
+    let schema = get(opt, 'schema', '')
+    let schemaLine = isestr(schema) ? `\n只回覆 JSON 物件，不要任何其他說明文字，格式與候選相同：\n${schema}\n` : '\n只回覆 JSON 物件，不要任何其他說明文字，格式與候選相同。\n'
+    return `你是整合者。以下是同一任務由 ${candidates.length} 個獨立執行產生的候選結果（JSON），請整合成單一最佳版本：擇優合併、去重、保留最完整的證據標注與爭議呈現，不可加入候選中沒有的數字或結論。
+${schemaLine}
+${candidates.map((c, i) => `【候選 ${i + 1}】\n${JSON.stringify(c)}`).join('\n\n')}`
+}
+
+
+/**
+ * 執行Fanout工作流：多開執行與單點整合
+ *
+ * 特點：
+ * 前段各名額並行執行同一任務，各名額可指定主模型(use)與自帶遞補鏈(fallback)；
+ * 後段為單一整合名額，同樣可帶遞補鏈；
+ * 個別名額失敗不中斷整輪，成功候選未達minCandidates時以首位候選為成果(integrated:false)不硬整合；
+ * 成功候選完整保留於回傳(部分接受、便於接續重試整合)；
+ * 本函數不會reject
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)，透傳callAiWithFallback
+ * @param {String} opt.task 輸入前段各名額共用之任務提示詞字串
+ * @param {Array} opt.agents 輸入前段名額規格陣列，各元素{ use, fallback, maxRetries?, timeoutMs? }等(除use/fallback外之鍵覆寫該名額呼叫設定)
+ * @param {Object} opt.integrate 輸入整合名額規格物件{ use, fallback, prompt?, ... }，prompt可為(candidates)=>String自訂整合提示詞，省略用預設模板
+ * @param {Function} [opt.check=null] 輸入候選與終稿共用之檢核函數(json)=>Boolean，預設null
+ * @param {String} [opt.schema=''] 輸入輸出格式示意字串，供預設整合模板嵌入，預設''
+ * @param {Number} [opt.minCandidates=2] 輸入進入整合所需之最少成功候選數正整數，未達門檻以首位候選為成果，預設2
+ * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定(cwd、store、onEvent、timeoutMs、promptPrefix等)，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(工作流成果)、integrated(是否經過整合布林值)、agents(各名額完整結果陣列)、candidates(成功候選陣列)、integrateDetail(整合呼叫完整結果)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runFanout from './src/wkf/runFanout.mjs'
+ *
+ * let providers = {
+ *     '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 runFanout({
+ *         providers,
+ *         task: '分析並只回覆JSON: {"essence":"..."}',
+ *         agents: [
+ *             { use: 'zen:deepseek-v4-flash-free', fallback: ['claude:sonnet'] },
+ *             { use: 'claude:sonnet' },
+ *         ],
+ *         integrate: { use: 'claude:sonnet' },
+ *         check: (j) => !!j.essence,
+ *     })
+ *     console.log(r.ok, r.integrated, r.candidates.length)
+ *     // => true true 2
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runFanout(opt = {}) {
+    let t0 = Date.now()
+    let providers = get(opt, 'providers', null)
+    let task = get(opt, 'task', '')
+    let agents = get(opt, 'agents', null)
+    let integrate = get(opt, 'integrate', null)
+    let check = get(opt, 'check', null)
+    let callOpt = get(opt, 'callOpt', {})
+
+    if (!isestr(task)) {
+        return { ok: false, result: null, integrated: false, agents: [], candidates: [], totalMs: 0, error: 'task must be a non-empty string' }
+    }
+    if (!isearr(agents)) {
+        return { ok: false, result: null, integrated: false, agents: [], candidates: [], totalMs: 0, error: 'agents must be a non-empty array' }
+    }
+
+    let minCandidates = get(opt, 'minCandidates', null)
+    if (!ispint(minCandidates)) {
+        minCandidates = 2
+    }
+    else {
+        minCandidates = cint(minCandidates)
+    }
+
+    //前段: 並行多開, 個別失敗不炸整輪
+    let rsAgents = await Promise.all(agents.map((spec) => {
+        let { use, fallback, ...overrides } = spec
+        return callAiWithFallback(task, { ...callOpt, ...overrides, providers, spec: { use, fallback }, check })
+    }))
+    let candidates = rsAgents.filter((r) => r.ok).map((r) => r.json)
+
+    //全部失敗
+    if (candidates.length === 0) {
+        return { ok: false, result: null, integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: 'all agents failed' }
+    }
+
+    //未達整合門檻(含恰為1份): 不硬整合, 以首位成功候選為成果
+    if (candidates.length === 1 || candidates.length < minCandidates) {
+        return { ok: true, result: candidates[0], integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: '' }
+    }
+
+    //後段: 整合
+    if (!integrate || !isestr(get(integrate, 'use', ''))) {
+        return { ok: false, result: null, integrated: false, agents: rsAgents, candidates, totalMs: Date.now() - t0, error: 'integrate spec (with use) is required' }
+    }
+    let { use, fallback, prompt: intPromptFn, ...intOverrides } = integrate
+    let intPrompt = isfun(intPromptFn) ? intPromptFn(candidates) : defaultIntegratePrompt(candidates, opt)
+    let rInt = await callAiWithFallback(intPrompt, { ...callOpt, ...intOverrides, providers, spec: { use, fallback }, check })
+
+    return {
+        ok: rInt.ok,
+        result: rInt.ok ? rInt.json : null,
+        integrated: rInt.ok,
+        agents: rsAgents,
+        candidates, //即使整合失敗, 成功候選仍完整回傳, 供接續重試整合(只重跑整合段)
+        integrateDetail: rInt,
+        totalMs: Date.now() - t0,
+        error: rInt.ok ? '' : `integrate failed: ${rInt.error}`,
+    }
+}
+
+
+export default runFanout
+export { defaultIntegratePrompt }

package/src/wkf/runFanoutPipeline.mjs

@@ -0,0 +1,106 @@
+import get from 'lodash-es/get.js'
+import runFanout from './runFanout.mjs'
+import runRolePipeline from './runRolePipeline.mjs'
+
+
+// runFanoutPipeline.mjs — FanoutPipeline工作流(Fanout+RolePipeline): 多開收斂成果接串行角色鏈
+//
+// 【結構】先跑runFanout(多開 → 整合), 其成果作為runRolePipeline的input
+//   (各階段以ctx.input取用), 最末階段回傳即工作流成果。
+//
+// 【實測依據(2026-08-10評比)】Fanout+RolePipeline是品質天花板: 前段的多樣性擇優給出最豐底稿、
+//   審計鏈再修幻覺與證據標注; 六模型的歷史最高品質全部出現在此組合(或與純RolePipeline並列)。
+//
+// 【部分接受】前段失敗即回(附前段完整明細, 含已成功候選);
+//   後段失敗回傳前段成果與後段已完成階段——呼叫端可只重跑失敗段。
+
+
+/**
+ * 執行FanoutPipeline工作流(Fanout+RolePipeline)：多開＋整合＋串行角色鏈
+ *
+ * 特點：
+ * 前段同runFanout(agents各名額可自帶fallback、integrate單點整合)；
+ * 後段同runRolePipeline(stages各階段可自帶AI／fallback／提示詞)，其input即前段成果；
+ * 本函數不會reject
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)
+ * @param {String} opt.task 輸入前段各名額共用之任務提示詞字串
+ * @param {Array} opt.agents 輸入前段名額規格陣列(同runFanout)
+ * @param {Object} opt.integrate 輸入前段整合名額規格物件(同runFanout)
+ * @param {Array} opt.stages 輸入後段階段規格陣列(同runRolePipeline)，各階段以ctx.input取得前段成果
+ * @param {Function} [opt.check=null] 輸入前段共用檢核函數，後段各階段自帶check，預設null
+ * @param {String} [opt.schema=''] 輸入輸出格式示意字串(供前段預設整合模板)，預設''
+ * @param {Number} [opt.minCandidates=2] 輸入前段整合門檻正整數，預設2
+ * @param {Object} [opt.callOpt={}] 輸入透傳兩段之共用呼叫設定，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(工作流成果)、A(前段runFanout完整結果)、B(後段runRolePipeline完整結果)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runFanoutPipeline from './src/wkf/runFanoutPipeline.mjs'
+ *
+ * let providers = {
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await runFanoutPipeline({
+ *         providers,
+ *         task: '分析並只回覆JSON: {"essence":"..."}',
+ *         agents: [{ use: 'claude:sonnet' }, { use: 'codex:gpt-5.6-luna' }],
+ *         integrate: { use: 'claude:sonnet' },
+ *         stages: [
+ *             { id: 'audit', use: 'codex:gpt-5.6-luna', prompt: (ctx) => `審計此稿並修訂, 只回覆同格式JSON: ${JSON.stringify(ctx.input)}` },
+ *         ],
+ *         check: (j) => !!j.essence,
+ *     })
+ *     console.log(r.ok, r.A.integrated, r.B.order)
+ *     // => true true [ 'audit' ]
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runFanoutPipeline(opt = {}) {
+    let t0 = Date.now()
+
+    //前段: Fanout(多開 → 整合)
+    let rA = await runFanout({
+        providers: get(opt, 'providers', null),
+        task: get(opt, 'task', ''),
+        agents: get(opt, 'agents', null),
+        integrate: get(opt, 'integrate', null),
+        check: get(opt, 'check', null),
+        schema: get(opt, 'schema', ''),
+        minCandidates: get(opt, 'minCandidates', null),
+        callOpt: get(opt, 'callOpt', {}),
+    })
+    if (!rA.ok) {
+        return { ok: false, result: null, A: rA, B: null, totalMs: Date.now() - t0, error: `A failed: ${rA.error}` }
+    }
+
+    //後段: RolePipeline, input即前段成果
+    let rB = await runRolePipeline({
+        providers: get(opt, 'providers', null),
+        input: rA.result,
+        stages: get(opt, 'stages', null),
+        callOpt: get(opt, 'callOpt', {}),
+    })
+
+    return {
+        ok: rB.ok,
+        result: rB.ok ? rB.result : null,
+        A: rA, //前段成果與明細一律回傳——後段失敗時可據此只重跑後段
+        B: rB,
+        totalMs: Date.now() - t0,
+        error: rB.ok ? '' : `B failed: ${rB.error}`,
+    }
+}
+
+
+export default runFanoutPipeline

package/src/wkf/runRolePipeline.mjs

@@ -0,0 +1,123 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isearr from 'wsemi/src/isearr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import callAiWithFallback from './callAiWithFallback.mjs'
+
+
+// runRolePipeline.mjs — RolePipeline工作流: 多角色串行鏈(stage1 → … → stageN)
+//
+// 【結構】各階段可各自指定AI(use)、遞補鏈(fallback)、提示詞(角色與任務)與檢核;
+//   前一階段的成果傳給下一階段、一路傳到最末階段, 其成果即工作流成果。
+//
+// 【提示詞為函數】stage.prompt收ctx = { input, prev, results, index }:
+//   input＝工作流輸入(如原始任務或Fanout的整合稿)、prev＝上一階段成果、
+//   results＝已完成各階段成果(依id查詢, 例如修訂階段要同時引用初稿與審計意見)。
+//
+// 【部分接受】某階段(含遞補全敗)失敗即中止後續, 但已完成階段之成果完整回傳
+//   (failedStage標明斷點), 呼叫端可據此只重跑失敗段而非整條鏈。
+//
+// 【實測依據(2026-08-10評比)】審計類角色鏈曾出現「審計刪過頭」——
+//   修訂／終審提示詞應包含護欄「意見未涉及的內容不可刪除」; 此屬提示詞設計,
+//   本函數不代寫角色提示詞, 由呼叫端(或上層預設模板)自理。
+
+
+//各階段規格自用之鍵, 其餘鍵覆寫該階段之呼叫設定
+let STAGE_KEYS = ['id', 'use', 'fallback', 'prompt', 'check']
+
+
+/**
+ * 執行RolePipeline工作流：多角色串行鏈
+ *
+ * 特點：
+ * 各階段可各自指定use／fallback／prompt／check(含rawText純文字階段)；
+ * 階段成果依序傳遞，最末階段成果即工作流成果；
+ * 失敗即止但已完成成果完整回傳(部分接受、便於接續重跑失敗段)；
+ * 本函數不會reject
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Object} opt.providers 輸入provider定義表物件(名稱 → 條目)
+ * @param {*} [opt.input=null] 輸入工作流輸入(原始任務字串或前一工作流之成果物件)，提供給各階段ctx.input，預設null
+ * @param {Array} opt.stages 輸入階段規格陣列，各元素{ id, use, fallback, prompt:(ctx)=>String, check?, rawText?, maxRetries?, timeoutMs? }等
+ * @param {Object} [opt.callOpt={}] 輸入透傳callAiWithFallback之共用設定，預設{}
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(布林值)、result(最末階段成果)、stages(id對階段完整呼叫結果之物件)、results(id對階段成果之物件)、order(階段id順序陣列)、failedStage(失敗階段id，無失敗為null)、totalMs(總耗時毫秒)、error(錯誤訊息字串)，本函數不會reject
+ * @example
+ * //need cli in system PATH
+ *
+ * import runRolePipeline from './src/wkf/runRolePipeline.mjs'
+ *
+ * let providers = {
+ *     'claude:sonnet': { kind: 'claude', model: 'sonnet' },
+ *     'codex:gpt-5.6-luna': { kind: 'codex', model: 'gpt-5.6-luna' },
+ * }
+ *
+ * let test = async () => {
+ *
+ *     let r = await runRolePipeline({
+ *         providers,
+ *         input: '原始任務',
+ *         stages: [
+ *             { 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)
+ *     // => true [ 'draft', 'review' ] null
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function runRolePipeline(opt = {}) {
+    let t0 = Date.now()
+    let providers = get(opt, 'providers', null)
+    let input = get(opt, 'input', null)
+    let stages = get(opt, 'stages', null)
+    let callOpt = get(opt, 'callOpt', {})
+
+    if (!isearr(stages)) {
+        return { ok: false, result: null, stages: {}, results: {}, order: [], failedStage: null, totalMs: 0, error: 'stages must be a non-empty array' }
+    }
+
+    let results = {} //id → 成果(json或文字)
+    let details = {} //id → 完整呼叫結果
+    let order = []
+    let prev = null
+
+    for (let i = 0; i < stages.length; i++) {
+        let stage = stages[i]
+        let id = isestr(get(stage, 'id', '')) ? stage.id : `stage${i + 1}`
+        order.push(id)
+
+        let promptFn = get(stage, 'prompt', null)
+        if (!isfun(promptFn)) {
+            details[id] = { ok: false, error: `stage[${id}].prompt must be a function` }
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: details[id].error }
+        }
+        let prompt = promptFn({ input, prev, results, index: i })
+        if (!isestr(prompt)) {
+            details[id] = { ok: false, error: `stage[${id}].prompt returned empty` }
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: details[id].error }
+        }
+
+        //overrides, 剔除階段自用鍵後其餘鍵覆寫該階段呼叫設定(rawText、maxRetries、timeoutMs等)
+        let overrides = omit(stage, STAGE_KEYS)
+        let r = await callAiWithFallback(prompt, { ...callOpt, ...overrides, providers, spec: { use: get(stage, 'use', ''), fallback: get(stage, 'fallback', null) }, check: get(stage, 'check', null) })
+        details[id] = r
+        if (!r.ok) {
+            //失敗即止: 已完成階段成果保留於results, 供呼叫端接續重跑
+            return { ok: false, result: null, stages: details, results, order, failedStage: id, totalMs: Date.now() - t0, error: `stage[${id}] failed: ${r.error}` }
+        }
+        results[id] = r.json
+        prev = r.json
+    }
+
+    return { ok: true, result: prev, stages: details, results, order, failedStage: null, totalMs: Date.now() - t0, error: '' }
+}
+
+
+export default runRolePipeline

package/test/tools/fakeServerForApiTest.mjs

@@ -0,0 +1,151 @@
+import http from 'http'
+
+
+// fakeServerForApiTest.mjs — 測試用的OpenAI相容假伺服器
+//
+// dispatchApiOpenaiCompat之可觀察行為為「送出什麼HTTP請求、如何處理各種回應」,
+// 故起一個本機http伺服器, 依請求之model與Authorization決定回應行為,
+// 即可對成功/401/429/500/逾時/畸形回應逐條斷言, 而無須真的呼叫外部API。
+//
+// 【行為路由(依body.model)】
+//   echo           — 200, content為JSON字串{ auth, body }, 供斷言請求組成
+//   empty-content  — 200, content為空字串(驗證路徑用)
+//   slow           — 延遲10秒才回應(逾時路徑用)
+//   err-500        — 500
+//   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路由), 模擬無效金鑰。
+
+
+/**
+ * 啟動測試用OpenAI相容假伺服器
+ *
+ * @returns {Promise} 回傳Promise，resolve回傳物件，內含port(埠號)、url(基底網址字串，等同baseURL)、close(關閉伺服器之async函數)
+ */
+async function fakeServerForApiTest() {
+
+    //flakyCount, 記錄flaky-429各金鑰之呼叫次數
+    let flakyCount = {}
+
+    //sockets, 追蹤連線供close時強制斷開(避免keep-alive令close懸置)
+    let sockets = new Set()
+
+    let server = http.createServer((req, res) => {
+
+        //僅受理POST /v1/chat/completions
+        if (req.method !== 'POST' || !req.url.endsWith('/chat/completions')) {
+            res.writeHead(404, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify({ error: { message: 'not found' } }))
+            return
+        }
+
+        let chunks = []
+        req.on('data', (c) => chunks.push(c))
+        req.on('end', () => {
+
+            let auth = req.headers['authorization'] || ''
+
+            //body非JSON → 400
+            let body = null
+            try {
+                body = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+            }
+            catch {
+                res.writeHead(400, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: 'invalid json body' } }))
+                return
+            }
+
+            //無效金鑰, 模擬Zen之401形態
+            if (auth.includes('sk-bad')) {
+                res.writeHead(401, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ type: 'error', error: { type: 'AuthError', message: 'Invalid API key.' } }))
+                return
+            }
+
+            let model = body.model || ''
+            let ok = (content) => {
+                res.writeHead(200, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ choices: [{ message: { role: 'assistant', content } }] }))
+            }
+
+            if (model === 'echo') {
+                ok(JSON.stringify({ auth, body }))
+            }
+            else if (model === 'empty-content') {
+                ok('')
+            }
+            else if (model === 'slow') {
+                setTimeout(() => ok('too late'), 10000)
+            }
+            else if (model === 'err-500') {
+                res.writeHead(500, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: 'internal error' } }))
+            }
+            else if (model === 'flaky-429') {
+                flakyCount[auth] = (flakyCount[auth] || 0) + 1
+                if (flakyCount[auth] === 1) {
+                    res.writeHead(429, { 'Content-Type': 'application/json' })
+                    res.end(JSON.stringify({ error: { message: 'rate limited' } }))
+                }
+                else {
+                    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' }))
+            }
+            else if (model === 'not-json') {
+                res.writeHead(200, { 'Content-Type': 'text/plain' })
+                res.end('plain text body')
+            }
+            else {
+                res.writeHead(404, { 'Content-Type': 'application/json' })
+                res.end(JSON.stringify({ error: { message: `model ${model} not found` } }))
+            }
+
+        })
+    })
+
+    server.on('connection', (s) => {
+        sockets.add(s)
+        s.on('close', () => sockets.delete(s))
+    })
+
+    //listen於127.0.0.1動態埠
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve)
+    })
+    let port = server.address().port
+
+    let close = async () => {
+        for (let s of sockets) {
+            s.destroy()
+        }
+        await new Promise((resolve) => {
+            server.close(resolve)
+        })
+    }
+
+    return { port, url: `http://127.0.0.1:${port}/v1`, close }
+}
+
+
+export default fakeServerForApiTest