w-dispatch-ai 1.0.11 → 1.0.13

package/src/wkf/salvageTruncatedArray.mjs

@@ -0,0 +1,95 @@
+// salvageTruncatedArray.mjs — 截斷JSON陣列之前段搶救
+//
+// 【為何需要】免費模型常在長陣列輸出中途被截斷(無閉合括號), 整包JSON.parse必失敗,
+//   但前面k個元素是完整的。使用端殷鑑(2026-08-07~08): 兩日22次OUTPUT_VALIDATION_FAILED,
+//   preview首元素皆完整合法——整批成果被截斷尾巴拖垮, 其中一輪3/3批全滅、整輪0產出。
+//   字元掃描(含字串與跳脫感知)找出「最後一個完整的頂層元素」, 補上`]`後重新解析——
+//   搶救回來的是**完整合法**的前段元素, 不是半成品。
+//
+// 【定位: 獨立工具, 不併入extractJsonLoose預設行為】「截斷」有兩種同樣合法的策略:
+//   ①判失敗換家重產(全涵蓋驗證, 如逐篇摘要——缺篇的輸出本身即不完整);
+//   ②搶救前段部分接受(批次萃取——避免全有全無, 一批30項救回25項遠勝重跑)。
+//   套件提供工具, 策略由呼叫端選: extractJsonLoose檔頭明示之opt.parse擴充點即為此而留。
+//
+// 【只搶救「掃到結尾仍未閉合」的截斷】陣列有正常閉合但parse失敗屬別種毛病
+//   (非法字元/壞跳脫), 補`]`救不了反而可能拼出語意錯誤的結果, 一律不碰回null。
+
+
+/**
+ * 自截斷的JSON陣列文字搶救出前段完整元素(頂層元素須為物件)
+ *
+ * 特點：
+ * 自第一個`[`起逐字元掃描(字串與跳脫感知)，追蹤「最後一個完整結束的頂層物件元素」，
+ * 補上`]`重新解析——回傳的每個元素皆完整合法，不是半成品；
+ * 陣列有正常閉合(＝非截斷)、無`[`、或救回後為空陣列，一律回null不硬救；
+ * 典型用法：extractJsonLoose回null時之後備，或組成自訂parse注入callAiWithFallback
+ *
+ * @param {String} text 輸入模型輸出文字字串
+ * @returns {Array|null} 回傳搶救出之非空陣列，無法搶救回null
+ * @example
+ *
+ * import salvageTruncatedArray from './src/wkf/salvageTruncatedArray.mjs'
+ *
+ * console.log(salvageTruncatedArray('[{"a":1},{"b":2},{"c":'))
+ * // => [ { a: 1 }, { b: 2 } ]
+ *
+ * console.log(salvageTruncatedArray('[{"a":1}]')) //有閉合＝非截斷, 不在搶救範圍
+ * // => null
+ *
+ */
+function salvageTruncatedArray(text) {
+    let s = String(text || '')
+    let start = s.indexOf('[')
+    if (start < 0) {
+        return null
+    }
+    let depth = 0
+    let inStr = false
+    let esc = false
+    let lastComplete = -1
+    for (let i = start; i < s.length; i++) {
+        let ch = s[i]
+        if (esc) {
+            esc = false
+            continue
+        }
+        if (inStr) {
+            if (ch === '\\') {
+                esc = true
+            }
+            else if (ch === '"') {
+                inStr = false
+            }
+            continue
+        }
+        if (ch === '"') {
+            inStr = true
+            continue
+        }
+        if (ch === '[' || ch === '{') {
+            depth++
+        }
+        else if (ch === ']' || ch === '}') {
+            depth--
+            if (depth === 1 && ch === '}') {
+                lastComplete = i //頂層元素(物件)完整結束
+            }
+            if (depth === 0) {
+                return null //陣列有閉合＝非截斷, 不在搶救範圍
+            }
+        }
+    }
+    if (lastComplete < 0) {
+        return null
+    }
+    try {
+        let r = JSON.parse(s.slice(start, lastComplete + 1) + ']')
+        return (Array.isArray(r) && r.length > 0) ? r : null
+    }
+    catch (e) {
+        return null
+    }
+}
+
+
+export default salvageTruncatedArray

package/test/unit-WDispatchAi.test.mjs

@@ -16,7 +16,7 @@ import resolveProviders from '../src/resolveProviders.mjs'
 
 describe('WDispatchAi', function() {
 
-    it('對外提供KINDS與各dispatch函數', function() {
+    it('對外提供KINDS與各dispatch函數與工具', function() {
         let r = keys(wi)
         let rr = [
             'KINDS',
@@ -30,6 +30,12 @@ describe('WDispatchAi', function() {
             'dispatchApiOpenaiCompat',
             'providers',
             'resolveProviders',
+            'readEnvFile',
+            'budgetFor',
+            'createFileStore',
+            'createUsageCounter',
+            'salvageTruncatedArray',
+            'NO_SIDE_EFFECT',
         ]
         assert.strict.deepEqual(r, rr)
     })
@@ -40,9 +46,9 @@ describe('WDispatchAi', function() {
         assert.strict.deepEqual(r, rr)
     })
 
-    it('各鍵值型別正確(KINDS與providers為物件, 其餘為函數)', function() {
+    it('各鍵值型別正確(KINDS與providers為物件, NO_SIDE_EFFECT為字串, 其餘為函數)', function() {
         let r = map(keys(wi), (k) => typeof wi[k])
-        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function']
+        let rr = ['object', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'function', 'object', 'function', 'function', 'function', 'function', 'function', 'function', 'string']
         assert.strict.deepEqual(r, rr)
     })
 

package/test/unit-budgetFor.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'assert'
+import budgetFor from '../src/budgetFor.mjs'
+import dfTimeoutMs from '../src/dfTimeoutMs.mjs'
+
+
+describe('budgetFor', function() {
+
+    it('遞補鏈時間預算為各條目timeoutMs之總和', function() {
+        let r = budgetFor([{ timeoutMs: 180000 }, { timeoutMs: 240000 }])
+        let rr = 420000
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未帶或無效timeoutMs之條目以套件統一預設計(與執行時實際取值一致)', function() {
+        let r = budgetFor([{ timeoutMs: 180000 }, {}, { timeoutMs: 'abc' }, { timeoutMs: -1 }])
+        let rr = 180000 + dfTimeoutMs * 3
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('輸入非陣列回傳0', function() {
+        let r = [budgetFor(null), budgetFor(undefined), budgetFor('abc'), budgetFor({})]
+        let rr = [0, 0, 0, 0]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-callAiWithFallback.test.mjs

@@ -1,5 +1,6 @@
 import assert from 'assert'
 import callAiWithFallback, { buildChain, NO_SIDE_EFFECT } from '../src/wkf/callAiWithFallback.mjs'
+import noSideEffectPrefix from '../src/wkf/noSideEffectPrefix.mjs'
 import createFakeCli from './tools/fakeCliForTest.mjs'
 
 
@@ -25,6 +26,13 @@ describe('callAiWithFallback', function() {
         }
     })
 
+    it('NO_SIDE_EFFECT為單一來源: 本層再匯出與noSideEffectPrefix模組為同一份', function() {
+        //措辭曾分岔於消費端(套件修了codex唯讀豁免、消費端還帶舊措辭), 抽檔後鎖定同源
+        let r = [NO_SIDE_EFFECT === noSideEffectPrefix, NO_SIDE_EFFECT.includes('唯讀查閱')]
+        let rr = [true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
     it('buildChain以名稱展開條目並回報查無定義之名稱', function() {
         let { chain, missing } = buildChain(providers, { use: 'p-claude', fallback: ['p-codex', 'p-typo'] })
         let r = [chain.map((x) => x.id), missing]

package/test/unit-createFileStore.test.mjs

@@ -0,0 +1,66 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import assert from 'assert'
+import createFileStore from '../src/wkf/createFileStore.mjs'
+
+
+//產物落test/tmp/(同fakeCliForTest慣例), 測試結束清除
+let FD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'tmp', 'file-store')
+
+
+describe('createFileStore', function() {
+
+    before(function() {
+        fs.mkdirSync(FD, { recursive: true })
+    })
+
+    after(function() {
+        fs.rmSync(FD, { recursive: true, force: true })
+        try {
+            fs.rmdirSync(path.dirname(FD))
+        }
+        catch (e) {}
+    })
+
+    it('file與dir皆缺時throw(組裝期設定錯誤fail fast)', function() {
+        assert.throws(() => createFileStore(), { message: 'createFileStore: file or dir is required' })
+    })
+
+    it('dir+name組路徑, 檔案不存在時get回空物件(套件視為全新狀態)', function() {
+        let store = createFileStore({ dir: FD, name: 'fresh.json' })
+        let r = [store.file, store.get()]
+        let rr = [path.join(FD, 'fresh.json'), {}]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('排除式passthrough: 未知欄位原封存還, 僅剔除自用欄位at(白名單丟棄cooling殷鑑)', function() {
+        let store = createFileStore({ dir: FD, name: 'rt.json', stamp: () => 'T0' })
+        //state含cursors/cooling與「套件未來新增的未知欄位」zz, 全數應原封回來
+        store.set({ cursors: { a: 1 }, cooling: { b: 1234 }, zz: { future: true } })
+        let onDisk = JSON.parse(fs.readFileSync(store.file, 'utf8'))
+        let r = [store.get(), onDisk.at]
+        let rr = [{ cursors: { a: 1 }, cooling: { b: 1234 }, zz: { future: true } }, 'T0']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可直接作dispatchAiFallback之store(get/set契約), 跨store實例讀同一檔', function() {
+        let fp = path.join(FD, 'shared.json')
+        let s1 = createFileStore({ file: fp })
+        s1.set({ cursors: { 'g-a': 2 } })
+        let s2 = createFileStore({ file: fp }) //新實例(模擬下一次行程)
+        let r = s2.get()
+        let rr = { cursors: { 'g-a': 2 } }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('檔案內容非法JSON時get回空物件不throw', function() {
+        let fp = path.join(FD, 'broken.json')
+        fs.writeFileSync(fp, '{ not valid json', 'utf8')
+        let store = createFileStore({ file: fp })
+        let r = store.get()
+        let rr = {}
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-createUsageCounter.test.mjs

@@ -0,0 +1,76 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import assert from 'assert'
+import createUsageCounter from '../src/wkf/createUsageCounter.mjs'
+
+
+//產物落test/tmp/(同fakeCliForTest慣例), 測試結束清除
+let FD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'tmp', 'usage-counter')
+
+
+describe('createUsageCounter', function() {
+
+    before(function() {
+        fs.mkdirSync(FD, { recursive: true })
+    })
+
+    after(function() {
+        fs.rmSync(FD, { recursive: true, force: true })
+        try {
+            fs.rmdirSync(path.dirname(FD))
+        }
+        catch (e) {}
+    })
+
+    it('file與dir皆缺時throw(組裝期設定錯誤fail fast)', function() {
+        assert.throws(() => createUsageCounter(), { message: 'createUsageCounter: file or dir is required' })
+    })
+
+    it('onEvent只於try事件記帳, 依keyOf(預設keyId)分鍵累加', function() {
+        let usage = createUsageCounter({ dir: FD, name: 'u1.json', getDate: () => '2026-08-18' })
+        usage.onEvent({ type: 'try', providerId: 'agnes:agnes-2.5-flash', keyIndex: 0, keyId: 'agnes:agnes-2.5-flash#0' })
+        usage.onEvent({ type: 'try', providerId: 'agnes:agnes-2.5-flash', keyIndex: 0, keyId: 'agnes:agnes-2.5-flash#0' })
+        usage.onEvent({ type: 'try', providerId: 'claude:sonnet', keyIndex: null, keyId: 'claude:sonnet' })
+        usage.onEvent({ type: 'ok', providerId: 'claude:sonnet', keyIndex: null, keyId: 'claude:sonnet' }) //非try不記
+        usage.onEvent({ type: 'next-key', providerId: 'x', keyId: 'x#0' }) //非try不記
+        let r = usage.today()
+        let rr = { today: '2026-08-18', byKey: { 'agnes:agnes-2.5-flash#0': 2, 'claude:sonnet': 1 }, total: 3 }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('keyOf可改計帳粒度(記到條目), bump可手動累加', function() {
+        let usage = createUsageCounter({ dir: FD, name: 'u2.json', getDate: () => '2026-08-18', keyOf: (ev) => ev.providerId })
+        usage.onEvent({ type: 'try', providerId: 'agnes:agnes-2.5-flash', keyId: 'agnes:agnes-2.5-flash#0' })
+        usage.onEvent({ type: 'try', providerId: 'agnes:agnes-2.5-flash', keyId: 'agnes:agnes-2.5-flash#1' }) //不同金鑰同條目
+        usage.bump('manual-key', 5)
+        let r = usage.today()
+        let rr = { today: '2026-08-18', byKey: { 'agnes:agnes-2.5-flash': 2, 'manual-key': 5 }, total: 7 }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('逐日分桶且只保留最近keepDays天', function() {
+        let day = '2026-08-01'
+        let usage = createUsageCounter({ dir: FD, name: 'u3.json', getDate: () => day, keepDays: 2 })
+        usage.bump('k')
+        day = '2026-08-02'
+        usage.bump('k')
+        day = '2026-08-03'
+        usage.bump('k')
+        let onDisk = JSON.parse(fs.readFileSync(usage.file, 'utf8'))
+        let r = [Object.keys(onDisk).sort(), usage.today()]
+        let rr = [['2026-08-02', '2026-08-03'], { today: '2026-08-03', byKey: { k: 1 }, total: 1 }] //08-01已被修剪
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('跨計數器實例讀同一檔(模擬下一次行程)', function() {
+        let usage1 = createUsageCounter({ dir: FD, name: 'u4.json', getDate: () => '2026-08-18' })
+        usage1.bump('k1')
+        let usage2 = createUsageCounter({ dir: FD, name: 'u4.json', getDate: () => '2026-08-18' })
+        usage2.bump('k1')
+        let r = usage2.today()
+        let rr = { today: '2026-08-18', byKey: { k1: 2 }, total: 2 }
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-readEnvFile.test.mjs

@@ -0,0 +1,52 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import assert from 'assert'
+import readEnvFile from '../src/readEnvFile.mjs'
+
+
+//產物落test/tmp/(同fakeCliForTest慣例), 測試結束清除
+let FD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'tmp', 'read-env-file')
+
+
+describe('readEnvFile', function() {
+
+    before(function() {
+        fs.mkdirSync(FD, { recursive: true })
+    })
+
+    after(function() {
+        fs.rmSync(FD, { recursive: true, force: true })
+        try {
+            fs.rmdirSync(path.dirname(FD))
+        }
+        catch (e) {}
+    })
+
+    it('解析KEY=value, 剝除成對引號, 忽略空行註解與無效行, 且不寫入process.env', function() {
+        let fp = path.join(FD, 'a.env')
+        fs.writeFileSync(fp, [
+            '# comment',
+            'AGNES_KEYS=sk-a,sk-b',
+            'QUOTED_D="sk-dq"',
+            'QUOTED_S=\'sk-sq\'',
+            'SPACED =  sk-sp  ',
+            'not a valid line',
+            '',
+            'EMPTY_VAL=',
+        ].join('\n'), 'utf8')
+        let r = [readEnvFile(fp), process.env.AGNES_KEYS === undefined || process.env.AGNES_KEYS !== 'sk-a,sk-b']
+        let rr = [
+            { AGNES_KEYS: 'sk-a,sk-b', QUOTED_D: 'sk-dq', QUOTED_S: 'sk-sq', SPACED: 'sk-sp', EMPTY_VAL: '' },
+            true,
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('檔案不存在回空物件不throw(金鑰缺失交由skipped機制回報)', function() {
+        let r = readEnvFile(path.join(FD, 'no-such.env'))
+        let rr = {}
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-resolveProviders.test.mjs

@@ -82,4 +82,53 @@ describe('resolveProviders', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    it('exes逐kind注入exe, 條目已自帶exe者不覆寫(條目層優先)', function() {
+        let defs = [
+            { id: 'claude:sonnet', kind: 'claude', model: 'sonnet' },
+            { id: 'claude:opus', kind: 'claude', model: 'opus', exe: 'D:/own/claude.exe' }, //自帶exe
+            { id: 'codex:g', kind: 'codex', model: 'g' }, //exes未含codex → 不動
+        ]
+        let t = resolveProviders(defs, { env: {}, exes: { claude: 'C:/bin/claude.exe' } })
+        let r = [
+            t.table['claude:sonnet'].exe,
+            t.table['claude:opus'].exe,
+            t.table['codex:g'].exe,
+            t.providers[0].exe, //陣列版與table版同源, 必然一致
+        ]
+        let rr = ['C:/bin/claude.exe', 'D:/own/claude.exe', undefined, 'C:/bin/claude.exe']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('patch逐id淺合併覆寫, 於exes之後施作故可覆寫exe, 陣列與table同步生效', function() {
+        let defs = [
+            { id: 'claude:sonnet', kind: 'claude', model: 'sonnet' },
+            { id: 'codex:g', kind: 'codex', model: 'g' },
+        ]
+        let t = resolveProviders(defs, {
+            env: {},
+            exes: { claude: 'C:/bin/claude.exe' },
+            patch: { 'claude:sonnet': { timeoutMs: 360000, exe: 'C:/patched/claude.exe' } },
+        })
+        let r = [
+            t.table['claude:sonnet'].timeoutMs,
+            t.table['claude:sonnet'].exe, //patch後於exes施作, 覆寫成功
+            t.providers[0].timeoutMs, //陣列版同步
+            t.table['codex:g'].timeoutMs, //未命中id者不動
+            t.providers[0] === t.table['claude:sonnet'], //同源同一物件
+        ]
+        let rr = [360000, 'C:/patched/claude.exe', 360000, undefined, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('exes與patch皆省略時行為與原版完全相同(向後相容), 且不改動輸入條目', function() {
+        let defs = [{ id: 'a:m', kind: 'claude', model: 'm' }]
+        let before = JSON.stringify(defs)
+        let t1 = resolveProviders(defs, { env: {} })
+        let t2 = resolveProviders(defs, { env: {}, exes: { claude: 'C:/bin/claude.exe' }, patch: { 'a:m': { timeoutMs: 1 } } })
+        let r = [JSON.stringify(t1.table['a:m']), JSON.stringify(defs) === before, defs[0].exe, defs[0].timeoutMs]
+        let rr = ['{"id":"a:m","kind":"claude","model":"m"}', true, undefined, undefined]
+        assert.strict.deepEqual(r, rr)
+        assert.strict.deepEqual(t2.table['a:m'].timeoutMs, 1)
+    })
+
 })

package/test/unit-salvageTruncatedArray.test.mjs

@@ -0,0 +1,39 @@
+import assert from 'assert'
+import salvageTruncatedArray from '../src/wkf/salvageTruncatedArray.mjs'
+
+
+describe('salvageTruncatedArray', function() {
+
+    it('截斷陣列搶救出前段完整元素(每個元素皆完整合法)', function() {
+        let r = [
+            salvageTruncatedArray('[{"a":1},{"b":2},{"c":'), //尾元素半途截斷
+            salvageTruncatedArray('[{"a":1},{"b":2}'), //恰於元素邊界截斷
+            salvageTruncatedArray('前導說明```json\n[{"a":1},{"b":{"c":2}},{"d"'), //含前導文字與巢狀物件
+        ]
+        let rr = [
+            [{ a: 1 }, { b: 2 }],
+            [{ a: 1 }, { b: 2 }],
+            [{ a: 1 }, { b: { c: 2 } }],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('字串與跳脫感知: 元素內含括號與跳脫引號不干擾配對', function() {
+        let r = salvageTruncatedArray('[{"a":"x]}","b":"y\\"z"},{"c":')
+        let rr = [{ a: 'x]}', b: 'y"z' }]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('有正常閉合(非截斷)、無陣列、或救不回任何完整元素, 一律回null不硬救', function() {
+        let r = [
+            salvageTruncatedArray('[{"a":1}]'), //有閉合＝非截斷
+            salvageTruncatedArray('純文字回覆'), //無[
+            salvageTruncatedArray('[{"a":'), //首元素即截斷, 無完整元素
+            salvageTruncatedArray(''),
+            salvageTruncatedArray(null),
+        ]
+        let rr = [null, null, null, null, null]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})