w-dispatch-ai 1.0.11 → 1.0.13

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "w-dispatch-ai",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "main": "dist/w-dispatch-ai.umd.js",
   "dependencies": {
-    "wsemi": "^1.8.75"
+    "wsemi": "^1.8.76"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.12"

package/src/WDispatchAi.mjs

@@ -10,6 +10,12 @@ import dispatchAntigravity from './dispatchAntigravity.mjs'
 import dispatchApiOpenaiCompat from './dispatchApiOpenaiCompat.mjs'
 import providers from './providers.mjs'
 import resolveProviders from './resolveProviders.mjs'
+import readEnvFile from './readEnvFile.mjs'
+import budgetFor from './budgetFor.mjs'
+import createFileStore from './wkf/createFileStore.mjs'
+import createUsageCounter from './wkf/createUsageCounter.mjs'
+import salvageTruncatedArray from './wkf/salvageTruncatedArray.mjs'
+import NO_SIDE_EFFECT from './wkf/noSideEffectPrefix.mjs'
 
 
 // WDispatchAi.mjs — AI供應商分派層
@@ -27,7 +33,7 @@ let KINDS = keys(adapters)
 /**
  * AI供應商分派
  *
- * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，dispatchAiWkf之工作流工廠函數，dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat之async函數，以及providers(預設providers定義檔)與resolveProviders(envVar展開器)
+ * @returns {Object} 回傳物件，其內含KINDS(可用供應商種類字串陣列)，dispatchAiWkf之工作流工廠函數，dispatchAi、dispatchAiFallback、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat之async函數，providers(預設providers定義檔)與resolveProviders(envVar展開器)，以及readEnvFile(讀.env不污染process.env)、budgetFor(遞補鏈時間預算推導)、createFileStore(store檔案持久化)、createUsageCounter(逐日用量計帳)、salvageTruncatedArray(截斷陣列搶救)、NO_SIDE_EFFECT(防副作用prompt前綴)等工具
  * @example
  *
  * 詳見dispatchAi、dispatchAiFallback、dispatchAiWkf、dispatchOpencode、dispatchClaude、dispatchCodex、dispatchAntigravity、dispatchApiOpenaiCompat、resolveProviders範例
@@ -35,6 +41,7 @@ let KINDS = keys(adapters)
  */
 let WDispatchAi = {
     KINDS,
+    NO_SIDE_EFFECT,
     dispatchAi,
     dispatchAiFallback,
     dispatchAiWkf,
@@ -45,6 +52,11 @@ let WDispatchAi = {
     dispatchApiOpenaiCompat,
     providers,
     resolveProviders,
+    readEnvFile,
+    budgetFor,
+    createFileStore,
+    createUsageCounter,
+    salvageTruncatedArray,
 }
 
 

package/src/budgetFor.mjs

@@ -0,0 +1,52 @@
+import get from 'lodash-es/get.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import castPintOr from './castPintOr.mjs'
+import dfTimeoutMs from './dfTimeoutMs.mjs'
+
+
+// budgetFor.mjs — 由供應商鏈推導走滿全鏈之時間預算
+//
+// 【為何屬本套件】「逾時型失敗每組只燒一次timeout即跳組, 故走滿全鏈的上限＝各組
+//   timeout相加」是dispatchAiFallback失敗分流模型的直接推論。消費端手算此值,
+//   會在改動fallback鏈時忘記同步而再度budget exhausted(使用端殷鑑: 2026-08-14
+//   revise名額之預算未跟上鏈變動而失敗); 或於設定檔維護一大段人工反推註解。
+//
+// 【與外部排程上限的關係】本函數給的是「保證能遞補到鏈尾」的值; 呼叫端之外層
+//   常另有硬上限(如Windows排程ExecutionTimeLimit), 兩者取小者交budgetMs即可——
+//   截短的取捨(可能走不完全鏈)由呼叫端自行決定。
+
+
+/**
+ * 計算遞補鏈走滿所需之時間預算(＝各條目timeoutMs之總和, 未帶者以套件統一預設計)
+ *
+ * 特點：
+ * 條目timeoutMs取正整數者計入，未帶或無效者以dfTimeoutMs(全套件統一預設300000)計——
+ * 與dispatchAiFallback執行時之實際取值一致，故總和即為走滿全鏈之上限；
+ * 輸入非陣列回傳0
+ *
+ * @param {Array} providers 輸入供應商條目物件陣列(dispatchAiFallback之providers)
+ * @returns {Number} 回傳時間預算毫秒整數
+ * @example
+ *
+ * import budgetFor from './src/budgetFor.mjs'
+ *
+ * console.log(budgetFor([{ timeoutMs: 180000 }, { timeoutMs: 240000 }]))
+ * // => 420000
+ *
+ * console.log(budgetFor([{ timeoutMs: 180000 }, {}])) //未帶者以套件統一預設300000計
+ * // => 480000
+ *
+ */
+function budgetFor(providers) {
+    if (!isarr(providers)) {
+        return 0
+    }
+    let n = 0
+    for (let p of providers) {
+        n += castPintOr(get(p, 'timeoutMs', null), dfTimeoutMs)
+    }
+    return n
+}
+
+
+export default budgetFor

package/src/providers.mjs

@@ -12,9 +12,10 @@
 // 【使用方式】
 //   import providers from 'w-dispatch-ai/src/providers.mjs'
 //   import resolveProviders from 'w-dispatch-ai/src/resolveProviders.mjs'
-//   process.loadEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS, 逗號分隔多把
-//   let { providers: ps, table, skipped } = resolveProviders(providers) //全取
-//   let r2 = resolveProviders(providers, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] }) //自選, pick順序即遞補優先序
+//   import readEnvFile from 'w-dispatch-ai/src/readEnvFile.mjs'
+//   let env = readEnvFile('./.env') //OPENCODE_KEYS/AGNES_KEYS/POOLSIDE_KEYS, 逗號分隔多把; 不污染process.env
+//   let { providers: ps, table, skipped } = resolveProviders(providers, { env }) //全取
+//   let r2 = resolveProviders(providers, { env, pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] }) //自選, pick順序即遞補優先序
 //
 // 【timeout規劃】各條目刻意不帶timeoutMs, 由上層依任務型態統一給定、條目僅於特例覆寫:
 //   簡單任務(秒級~分鐘級): 沿用套件統一預設即可(全轉接器一律300000＝5分鐘, 見dfTimeoutMs.mjs)。

package/src/readEnvFile.mjs

@@ -0,0 +1,60 @@
+import fs from 'fs'
+
+
+// readEnvFile.mjs — 讀.env為金鑰來源物件(不污染process.env)
+//
+// 【為何需要】resolveProviders之opt.env本為「不用process.env」而設計——多專案並行時
+//   污染全域環境變數會互相覆蓋金鑰——但「env物件從哪來」套件原無答案, README舊教法
+//   process.loadEnvFile('./.env')反而把金鑰塞進process.env, 與該設計目的自相矛盾。
+//   兩個消費端專案已各寫一份解析器且行為不一致(2026-08-18使用端調研), 收斂於此。
+//
+// 【為何讀不到回空物件而非拋錯】金鑰缺失由resolveProviders之skipped機制回報
+//   (缺金鑰停用該條目、不中斷), 此處拋錯反而讓「部分供應商無金鑰」升級成整體啟動失敗;
+//   要fail-loud的呼叫端自行檢查回傳(如Object.keys(env).length)。
+//
+// 【只解析KEY=value最簡格式】不引入dotenv: 金鑰為單行純文字, 僅剝除成對之首尾引號,
+//   不做跳脫與多行處理——加解析規則只會製造與其他.env工具的行為差異。
+
+
+/**
+ * 讀取.env檔為鍵值物件(金鑰來源, 不寫入process.env)
+ *
+ * 特點：
+ * 只解析`KEY=value`形式(KEY限英數底線)，忽略空行、註解與無效行；
+ * value修剪空白並剝除成對之首尾引號(單雙引號皆可)；
+ * 檔案不存在或不可讀一律回空物件不throw(金鑰缺失交由resolveProviders之skipped回報)
+ *
+ * @param {String} file 輸入.env檔案路徑字串
+ * @returns {Object} 回傳鍵值物件(變數名 → 字串值)，讀取失敗回空物件
+ * @example
+ *
+ * import readEnvFile from './src/readEnvFile.mjs'
+ * import resolveProviders from './src/resolveProviders.mjs'
+ * import providersAll from './src/providers.mjs'
+ *
+ * //金鑰放.env(變數值以逗號分隔多把), 讀成物件交resolveProviders, 不污染process.env
+ * let env = readEnvFile('./.env')
+ * let { providers, skipped } = resolveProviders(providersAll, { env, pick: ['agnes:agnes-2.5-flash'] })
+ *
+ */
+function readEnvFile(file) {
+    let out = {}
+    let text = ''
+    try {
+        text = fs.readFileSync(file, 'utf8')
+    }
+    catch (e) {
+        return out //檔案不存在或不可讀, 回空由skipped機制回報
+    }
+    for (let line of text.split(/\r?\n/)) {
+        let m = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*(.*)$/)
+        if (!m) {
+            continue
+        }
+        out[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, '$2')
+    }
+    return out
+}
+
+
+export default readEnvFile

package/src/resolveProviders.mjs

@@ -15,6 +15,14 @@ import isearr from 'wsemi/src/isearr.mjs'
 //
 // 【自選】opt.pick給id陣列即可只取用部分條目, 且依pick之順序回傳
 //   (順序即dispatchAiFallback之優先序); 查無之id列入missing回報。
+//
+// 【後處理單一入口: opt.exes與opt.patch】消費端常需於展開後對條目做兩類覆寫:
+//   ①逐kind注入CLI執行檔絕對路徑(Windows排程於session 0執行時PATH可能不含npm
+//     全域目錄, 靠指令名會ENOENT); ②逐id覆寫任意欄位(如各家實測耗時相差近10倍,
+//     timeoutMs須逐條指定)。此前只能於呼叫端自行map, 而陣列版(providers)與表格版
+//     (table)若各自後處理, 極易只套用其一——使用端殷鑑(2026-08-14): 逐條timeout
+//     只加在陣列版, 工作流走表格版全部落回全域預設而不自知。後處理收進本函數,
+//     兩種輸出同源產出, 結構性杜絕單邊套用。
 
 
 /**
@@ -25,30 +33,46 @@ import isearr from 'wsemi/src/isearr.mjs'
  * 缺對應環境變數(或值為空)之條目停用並列入skipped，不中斷不throw；
  * 無envVar之條目(訂閱登入態CLI)原樣通過；條目已自帶有效keys者以keys為準；
  * opt.pick可依id自選子集並以pick順序回傳(順序即遞補優先序)；
+ * opt.exes依kind注入CLI執行檔路徑、opt.patch依id淺合併覆寫欄位——皆於展開後施作，
+ * providers與table同源產出故必然一致；
  * 輸入陣列與條目皆不被改動(輸出為淺拷貝)
  *
  * @param {Array} providers 輸入providers條目物件陣列(如providers.mjs之預設匯出)
  * @param {Object} [opt={}] 輸入設定物件，預設{}
- * @param {Object} [opt.env=process.env] 輸入金鑰來源物件(變數名 → 逗號分隔之金鑰字串)，預設process.env
+ * @param {Object} [opt.env=process.env] 輸入金鑰來源物件(變數名 → 逗號分隔之金鑰字串)，預設process.env。建議以readEnvFile('./.env')讀成物件傳入，不污染process.env
  * @param {Array} [opt.pick=null] 輸入自選id字串陣列，依此順序回傳對應條目，查無之id列入missing，預設null代表全取(依原順序)
+ * @param {Object} [opt.exes=null] 輸入kind對執行檔絕對路徑之物件(如{claude:'C:/.../claude.exe'})，命中kind之條目補上exe欄位(條目已自帶exe者不覆寫——條目層設定優先)，預設null代表不注入
+ * @param {Object} [opt.patch=null] 輸入id對部分欄位之物件(如{'claude:sonnet':{timeoutMs:360000}})，命中id之條目淺合併覆寫，於exes之後施作故可覆寫exe，預設null代表不覆寫
  * @returns {Object} 回傳物件，內含providers(可直接餵dispatchAiFallback之條目陣列)、table(id對條目之物件，可直接餵dispatchAiWkf)、skipped(缺環境變數而停用之{id,envVar}陣列)、missing(pick查無之id字串陣列)
  * @example
  *
  * import resolveProviders from './src/resolveProviders.mjs'
+ * import readEnvFile from './src/readEnvFile.mjs'
  * import providersAll from './src/providers.mjs'
  *
- * process.loadEnvFile('./.env') //金鑰放.env, 變數值以逗號分隔多把
+ * //金鑰放.env(變數值以逗號分隔多把), 以readEnvFile讀成物件, 不污染process.env
+ * let env = readEnvFile('./.env')
  *
  * //全取: envVar展開為keys, 缺環境變數者列入skipped
- * let { providers, table, skipped } = resolveProviders(providersAll)
+ * let { providers, table, skipped } = resolveProviders(providersAll, { env })
  * console.log(providers.length, skipped)
  * // => 10 []
  *
  * //自選: 依pick順序回傳(順序即遞補優先序), 可直接餵dispatchAiFallback
- * let r2 = resolveProviders(providersAll, { pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
+ * let r2 = resolveProviders(providersAll, { env, pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'] })
  * console.log(r2.providers.map((p) => p.id))
  * // => [ 'agnes:agnes-2.5-flash', 'claude:sonnet' ]
  *
+ * //後處理: exes逐kind注入執行檔、patch逐id覆寫欄位, 陣列與table同步生效
+ * let r3 = resolveProviders(providersAll, {
+ *     env,
+ *     pick: ['agnes:agnes-2.5-flash', 'claude:sonnet'],
+ *     exes: { claude: 'C:/Users/x/.local/bin/claude.exe' },
+ *     patch: { 'claude:sonnet': { timeoutMs: 360000 } },
+ * })
+ * console.log(r3.table['claude:sonnet'].exe, r3.table['claude:sonnet'].timeoutMs)
+ * // => 'C:/Users/x/.local/bin/claude.exe' 360000
+ *
  * //table可直接餵dispatchAiWkf之providers定義表
  * //let wkf = dispatchAiWkf({ providers: r2.table, defaults: { timeoutMs: 1200000 } })
  *
@@ -104,6 +128,30 @@ function resolveProviders(providers, opt = {}) {
         out.push({ ...omit(entry, ['envVar']), keys })
     }
 
+    //後處理: exes(逐kind)與patch(逐id), 於table組建「之前」施作——
+    //providers與table由同一份out產出, 兩種輸出必然一致(檔頭之單邊套用殷鑑)
+    let exes = get(opt, 'exes', null)
+    let patch = get(opt, 'patch', null)
+    if (isobj(exes) || isobj(patch)) {
+        out = out.map((entry) => {
+            let e = entry
+
+            //exes: 條目已自帶exe者不覆寫(條目層設定優先於全域注入)
+            let exe = isobj(exes) ? get(exes, get(e, 'kind', ''), null) : null
+            if (isestr(exe) && !isestr(get(e, 'exe', null))) {
+                e = { ...e, exe }
+            }
+
+            //patch: 依id淺合併, 於exes之後施作故可覆寫exe
+            let pt = isobj(patch) ? get(patch, get(e, 'id', ''), null) : null
+            if (isobj(pt)) {
+                e = { ...e, ...pt }
+            }
+
+            return e
+        })
+    }
+
     //table, id → 條目, 可直接作dispatchAiWkf之providers定義表
     let table = {}
     for (let entry of out) {

package/src/wkf/callAiWithFallback.mjs

@@ -7,6 +7,7 @@ import isobj from 'wsemi/src/isobj.mjs'
 import dispatchAiFallback from '../dispatchAiFallback.mjs'
 import dfTimeoutMs from '../dfTimeoutMs.mjs'
 import extractJsonLoose from './extractJsonLoose.mjs'
+import NO_SIDE_EFFECT from './noSideEffectPrefix.mjs'
 
 
 // callAiWithFallback.mjs — 工作流的最小呼叫單元: 一個「AI名額」＝主模型＋自帶遞補鏈
@@ -24,15 +25,9 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 //
 // 【防寫檔前綴】agentic CLI對cwd隔離免疫(會自行解析專案根目錄寫檔),
 //   故預設在prompt前掛「禁止建檔」約束(實測有效); 不需要時傳promptPrefix:''關閉。
-//   殷鑑: 2026-08-10執行任務歷史.md遭AI覆寫、評比腳本繞過前綴又產生根目錄孤兒檔。
-//
-//   措辭須豁免「唯讀查閱」(2026-08-13 A/B實測): 各CLI取得檔案內容的途徑不同——
-//   opencode與claude有獨立的read/grep工具, 不受「禁止執行指令」約束;
-//   但codex讀檔即是執行shell指令, 舊措辭「禁止執行任何指令」對它等同「禁止讀檔」,
-//   凡需讀專案的任務會得到一句「請貼上檔案內容」而非成果, 且該拒答是合法字串,
-//   會通過驗證被遞補層當成「成功」, 整條fallback鏈就此停住——兜底地位被靜默廢掉。
-//   實測: 舊措辭下codex回「無法讀取該檔案」, 改為下列措辭後正常讀檔作答(11.1s),
-//   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
+//   措辭已移至獨立模組wkf/noSideEffectPrefix.mjs(單一來源)——不經本層、
+//   直接呼叫dispatchAiFallback的呼叫端亦應引用同一份, 措辭修正時全體同步;
+//   措辭本身的殷鑑(孤兒檔、codex唯讀豁免之A/B實測)詳見該檔檔頭。
 
 
 //本層自用之設定鍵, 其餘鍵(timeoutMs/budgetMs/minAttemptMs/maxRetries/cwd/store/onEvent/
@@ -43,16 +38,6 @@ import extractJsonLoose from './extractJsonLoose.mjs'
 let OWN_KEYS = ['providers', 'spec', 'check', 'parse', 'rawText', 'promptPrefix', 'meta']
 
 
-//預設防寫檔前綴(禁副作用, 但豁免唯讀查閱——codex以shell讀檔, 一律禁指令等同禁讀檔)
-let NO_SIDE_EFFECT = [
-    '【執行約束】你只需把結果輸出在回覆內容中。',
-    '禁止建立、修改或刪除任何檔案，也不要執行任何會改動磁碟或系統狀態的指令——',
-    '呼叫端只讀取你的回覆文字，任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
-    '唯讀查閱（讀取檔案、搜尋內容、列出目錄）不在此限，需要時請照常使用。',
-    '', '',
-].join('\n')
-
-
 /**
  * 依providers定義表把「名稱規格」展開成dispatchAiFallback的providers陣列
  *
@@ -105,7 +90,7 @@ 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 {String} [opt.promptPrefix=防寫檔約束] 輸入prompt前綴字串，預設為防寫檔約束，傳''關閉
+ * @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

package/src/wkf/createFileStore.mjs

@@ -0,0 +1,103 @@
+import path from 'path'
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import fsReadJson from 'wsemi/src/fsReadJson.mjs'
+import fsWriteJson from 'wsemi/src/fsWriteJson.mjs'
+
+
+// createFileStore.mjs — dispatchAiFallback之store的檔案持久化實作
+//
+// 【為何需要】dispatchAiFallback只定義store契約{get,set}, 預設用行程內記憶體——
+//   排程任務每次執行都是獨立行程, 記憶體狀態每次歸零: 金鑰輪替游標永遠從第一把開始,
+//   跨次輪替形同失效、額度無法均攤; 供應商冷卻亦然(上一輪已測得失效者, 本輪照樣先踩)。
+//   每個跨行程消費端都得重寫這份檔案實作, 收斂於此。
+//
+// 【採排除式而非白名單式——本設計最重要的一條】本函數只負責「把套件給的state
+//   原封不動存下、再原封不動拿回來」, 不理解state內有哪些欄位。使用端殷鑑:
+//   曾以白名單只取cursors, 於套件1.0.7新增cooling(供應商冷卻)時被靜默丟棄,
+//   cooldownMs形同未啟用——且不會有任何錯誤訊息, 只會「功能沒作用」。
+//   排除式(僅剔除本層自用欄位)使日後state再擴充欄位即自動相容。
+//
+// 【併發假定】與dispatchAiFallback之store文件一致: 假定單行程序列調用,
+//   並行執行同一任務請自行加鎖, 否則兩行程互相覆蓋游標。
+//
+// 【本工廠為同步函數會throw】file與dir皆缺屬設定錯誤, 應於組裝期即失敗(fail fast),
+//   與dispatchAiWkf工廠同一約定; 執行期之get/set則不throw(讀壞回空、寫失敗靜默)。
+
+
+/**
+ * 建立dispatchAiFallback之store的檔案持久化(游標與冷卻跨行程有效)
+ *
+ * 特點：
+ * 採排除式passthrough——state原封存還，僅剔除本層自用欄位(預設只有at：人讀的最後更新時間戳)，
+ * 日後套件擴充state欄位(如cooling)即自動相容，不需改本函數；
+ * 檔案不存在或非法JSON時get回空物件(套件視為全新狀態)；
+ * stamp可注入時間戳函數(排程環境建議注入時區錨定者)，寫入時補進at欄位供人工debug
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.file=null] 輸入狀態檔完整路徑字串，與dir/name二擇一
+ * @param {String} [opt.dir=null] 輸入狀態目錄字串，與name組成檔案路徑
+ * @param {String} [opt.name='ai-cursor.json'] 輸入狀態檔名字串，預設'ai-cursor.json'
+ * @param {Array} [opt.ownKeys=['at']] 輸入本層自用、不屬於套件狀態之欄位名字串陣列，get時剔除set時補回，預設['at']
+ * @param {Function} [opt.stamp=ISO時間戳] 輸入時間戳函數()=>String，寫入at欄位用，預設回傳new Date().toISOString()
+ * @returns {Object} 回傳store物件，內含get、set(可直接餵dispatchAiFallback之store)與file(狀態檔路徑)
+ * @example
+ *
+ * import createFileStore from './src/wkf/createFileStore.mjs'
+ * import dispatchAiFallback from './src/dispatchAiFallback.mjs'
+ *
+ * let store = createFileStore({ dir: './state' })
+ * //let r = await dispatchAiFallback(prompt, { providers, store, cooldownMs: 3600000 })
+ *
+ */
+function createFileStore(opt = {}) {
+    let file = get(opt, 'file', null)
+    if (!isestr(file)) {
+        let dir = get(opt, 'dir', null)
+        if (!isestr(dir)) {
+            throw new Error('createFileStore: file or dir is required')
+        }
+        let name = get(opt, 'name', null)
+        file = path.join(dir, isestr(name) ? name : 'ai-cursor.json')
+    }
+
+    let ownKeys = get(opt, 'ownKeys', null)
+    if (!isearr(ownKeys)) {
+        ownKeys = ['at']
+    }
+
+    let stamp = get(opt, 'stamp', null)
+    if (!isfun(stamp)) {
+        stamp = () => new Date().toISOString()
+    }
+
+    return {
+
+        file,
+
+        get: () => {
+            let r = fsReadJson(file)
+            let j = (get(r, 'error', undefined) !== undefined) ? null : get(r, 'success', null)
+            if (!isobj(j)) {
+                return {}
+            }
+            let state = { ...j }
+            for (let k of ownKeys) {
+                delete state[k]
+            }
+            return state
+        },
+
+        set: (state) => {
+            let out = { ...(isobj(state) ? state : {}), at: stamp() }
+            fsWriteJson(file, out, { useFormat: true })
+        },
+
+    }
+}
+
+
+export default createFileStore

package/src/wkf/createUsageCounter.mjs

@@ -0,0 +1,141 @@
+import path from 'path'
+import get from 'lodash-es/get.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import fsReadJson from 'wsemi/src/fsReadJson.mjs'
+import fsWriteJson from 'wsemi/src/fsWriteJson.mjs'
+
+
+// createUsageCounter.mjs — 逐日、逐鍵之AI用量計帳(純觀測)
+//
+// 【純觀測, 絕不據以節流或阻擋——本檔最重要的警語】用量門檻是臆測值: 服務端額度視窗
+//   形態多樣(逐日/逐時/5小時滾動/以token計而非以次數計), 呼叫端量得到的只有次數。
+//   以臆測門檻擋自己的呼叫等同拿猜測當事實: 太保守則白白不用已有額度, 太寬鬆則毫無作用。
+//   正確作法是「打下去、失敗了換下一家」(dispatchAiFallback之職責), 本計數器只提供
+//   事後回答「那天各鍵各打了幾次」的本機證據——真要查「某家是不是被打爆了」時,
+//   這是唯一的本機依據。
+//
+// 【於try事件記帳而非事後統計tried】即使行程被外部排程之時限中途砍掉,
+//   已發出的請求仍會留下紀錄; 事後統計則會漏掉被砍那一輪的全部嘗試。
+//   兩個消費端專案已各自寫過此接線(且各寫兩處), 故本函數直接提供onEvent。
+//
+// 【keyOf決定計帳粒度】預設記到金鑰(keyId如'agnes:agnes-2.5-flash#0'),
+//   要記到條目改傳(ev)=>ev.providerId即可。
+//
+// 【本工廠為同步函數會throw】file與dir皆缺屬設定錯誤, 應於組裝期即失敗(fail fast),
+//   與dispatchAiWkf工廠同一約定; 執行期之記帳與查詢則不throw。
+
+
+/**
+ * 建立逐日、逐鍵之用量計數器(純觀測, 不參與任何判斷)
+ *
+ * 特點：
+ * onEvent可直接掛進dispatchAiFallback/dispatchAiWkf，於type為'try'時依keyOf取鍵累加——
+ * 嘗試時即記帳，行程被外部時限中途砍掉已發出的請求仍有紀錄；
+ * 逐日分桶並僅保留最近keepDays天，避免檔案無限成長；
+ * getDate可注入時區錨定之日期函數——預設隨系統時區，排程session之系統時區可能為UTC+0
+ * 而使日界錯8小時，排程環境務必注入
+ *
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.file=null] 輸入用量檔完整路徑字串，與dir/name二擇一
+ * @param {String} [opt.dir=null] 輸入狀態目錄字串
+ * @param {String} [opt.name='ai-usage.json'] 輸入用量檔名字串，預設'ai-usage.json'
+ * @param {Function} [opt.getDate=系統日期] 輸入日期函數()=>'YYYY-MM-DD'，預設隨系統時區(排程環境建議注入時區錨定者)
+ * @param {Number} [opt.keepDays=14] 輸入保留天數正整數，預設14
+ * @param {Function} [opt.keyOf=(ev)=>ev.keyId||ev.providerId] 輸入計帳鍵函數(ev)=>String，決定粒度(金鑰或條目)，預設優先keyId
+ * @returns {Object} 回傳計數器物件，內含onEvent(可直接餵dispatch之onEvent)、bump(手動累加)、today(今日統計)與file(用量檔路徑)
+ * @example
+ *
+ * import createUsageCounter from './src/wkf/createUsageCounter.mjs'
+ *
+ * let usage = createUsageCounter({ dir: './state' })
+ * //let r = await dispatchAiFallback(prompt, { providers, onEvent: usage.onEvent })
+ * //console.log(usage.today())
+ * // => { today: '2026-08-18', byKey: { 'agnes:agnes-2.5-flash#0': 3 }, total: 3 }
+ *
+ */
+function createUsageCounter(opt = {}) {
+    let file = get(opt, 'file', null)
+    if (!isestr(file)) {
+        let dir = get(opt, 'dir', null)
+        if (!isestr(dir)) {
+            throw new Error('createUsageCounter: file or dir is required')
+        }
+        let name = get(opt, 'name', null)
+        file = path.join(dir, isestr(name) ? name : 'ai-usage.json')
+    }
+
+    let getDate = get(opt, 'getDate', null)
+    if (!isfun(getDate)) {
+        getDate = () => {
+            let d = new Date()
+            let p2 = (n) => String(n).padStart(2, '0')
+            return `${d.getFullYear()}-${p2(d.getMonth() + 1)}-${p2(d.getDate())}`
+        }
+    }
+
+    let keepDays = get(opt, 'keepDays', null)
+    if (!ispint(keepDays)) {
+        keepDays = 14
+    }
+
+    let keyOf = get(opt, 'keyOf', null)
+    if (!isfun(keyOf)) {
+        keyOf = (ev) => get(ev, 'keyId', null) || get(ev, 'providerId', '')
+    }
+
+    let readAll = () => {
+        let r = fsReadJson(file)
+        let j = (get(r, 'error', undefined) !== undefined) ? null : get(r, 'success', null)
+        return isobj(j) ? j : {}
+    }
+
+    let bump = (key, n = 1) => {
+        if (!isestr(key)) {
+            return
+        }
+        let raw = readAll()
+        let today = getDate()
+        let cur = isobj(raw[today]) ? raw[today] : {}
+        cur[key] = (Number(cur[key]) || 0) + n
+        raw[today] = cur
+
+        //只留最近keepDays天
+        let days = Object.keys(raw).sort().slice(-keepDays)
+        let trimmed = {}
+        for (let d of days) {
+            trimmed[d] = raw[d]
+        }
+        fsWriteJson(file, trimmed, { useFormat: true })
+    }
+
+    return {
+
+        file,
+
+        //可直接餵dispatch之onEvent: 於type為'try'時依keyOf記帳。要同時掛自有回調, 於自有onEvent內轉呼叫本函數即可
+        onEvent: (ev) => {
+            if (get(ev, 'type', null) === 'try') {
+                bump(keyOf(ev))
+            }
+        },
+
+        //手動累加(不經事件之呼叫路徑用)
+        bump,
+
+        //今日各鍵用量統計
+        today: () => {
+            let raw = readAll()
+            let today = getDate()
+            let byKey = isobj(raw[today]) ? raw[today] : {}
+            let total = Object.values(byKey).reduce((a, b) => a + (Number(b) || 0), 0)
+            return { today, byKey, total }
+        },
+
+    }
+}
+
+
+export default createUsageCounter

package/src/wkf/noSideEffectPrefix.mjs

@@ -0,0 +1,49 @@
+// noSideEffectPrefix.mjs — 防副作用prompt前綴(單一來源)
+//
+// 【為何獨立成檔】此措辭原內嵌於callAiWithFallback, 但不經該層、直接呼叫
+//   dispatchAiFallback的呼叫端也需要同一約束——實例(2026-08-18使用端調研):
+//   某使用端自帶一份「舊措辭」(一律禁止執行任何指令), 而該措辭的codex禁讀bug
+//   本套件早已修正, 形成「套件修了、消費端沒跟上」的分岔。抽成獨立模組後
+//   所有路徑引用同一來源, 措辭再修正時全體同步。
+//
+// 【為何需要此前綴】agentic CLI自帶檔案讀寫工具且對cwd隔離免疫(會自行解析
+//   專案根目錄以絕對路徑寫檔), 實測會「順手」把結果另存孤兒檔,
+//   甚至可能覆蓋呼叫端資料本體(殷鑑: 2026-08-10執行任務歷史.md遭AI覆寫、
+//   評比腳本繞過前綴又產生根目錄孤兒檔); 各家CLI的權限機制彼此不同(codex有sandbox、
+//   claude有--disallowedTools、opencode有config.permission),
+//   唯有prompt指示跨provider一致生效。CLI層限制可作第二道防線並存
+//   (內建providers.mjs各CLI條目即自帶機械防寫, 對照表見README)。
+//
+// 【措辭須豁免「唯讀查閱」(2026-08-13 A/B實測)】各CLI取得檔案內容的途徑不同——
+//   opencode與claude有獨立的read/grep工具, 不受「禁止執行指令」約束;
+//   但codex讀檔即是執行shell指令, 舊措辭「禁止執行任何指令」對它等同「禁止讀檔」,
+//   凡需讀專案的任務會得到一句「請貼上檔案內容」而非成果, 且該拒答是合法字串,
+//   會通過驗證被遞補層當成「成功」, 整條fallback鏈就此停住——兜底地位被靜默廢掉。
+//   實測: 舊措辭下codex回「無法讀取該檔案」, 現行措辭正常讀檔作答(11.1s),
+//   防副作用(建檔/改檔/刪檔/改動系統狀態)之本旨不變。
+
+
+/**
+ * 防副作用prompt前綴：禁止寫入類副作用、豁免唯讀查閱
+ *
+ * 用法：`NO_SIDE_EFFECT + prompt`後交dispatchAiFallback；
+ * callAiWithFallback預設自動掛上(傳promptPrefix:''關閉)，
+ * 直接呼叫dispatchAiFallback的呼叫端自行前綴
+ *
+ * @example
+ *
+ * import NO_SIDE_EFFECT from './src/wkf/noSideEffectPrefix.mjs'
+ *
+ * //let r = await dispatchAiFallback(NO_SIDE_EFFECT + prompt, { providers })
+ *
+ */
+let NO_SIDE_EFFECT = [
+    '【執行約束】你只需把結果輸出在回覆內容中。',
+    '禁止建立、修改或刪除任何檔案，也不要執行任何會改動磁碟或系統狀態的指令——',
+    '呼叫端只讀取你的回覆文字，任何寫入磁碟的動作都不會被採用，只會製造無人讀取的垃圾檔。',
+    '唯讀查閱（讀取檔案、搜尋內容、列出目錄）不在此限，需要時請照常使用。',
+    '', '',
+].join('\n')
+
+
+export default NO_SIDE_EFFECT