npm - w-dispatch-ai - Versions diffs - 1.0.0 → 1.0.2 - Mend

w-dispatch-ai 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +108 -6
package/dist/w-dispatch-ai.umd.js +2 -2
package/dist/w-dispatch-ai.umd.js.map +1 -1
package/docs/WDispatchAi.mjs.html +8 -4
package/docs/adapters.mjs.html +5 -3
package/docs/dispatchAi.mjs.html +2 -2
package/docs/dispatchAiFallback.mjs.html +406 -0
package/docs/dispatchAntigravity.mjs.html +264 -0
package/docs/dispatchClaude.mjs.html +2 -2
package/docs/dispatchCodex.mjs.html +2 -2
package/docs/dispatchOpencode.mjs.html +2 -2
package/docs/getCliArgs.mjs.html +2 -2
package/docs/getErrorResult.mjs.html +2 -2
package/docs/global.html +1600 -6
package/docs/index.html +2 -2
package/g.mjs +46 -2
package/package.json +1 -1
package/src/WDispatchAi.mjs +6 -2
package/src/adapters.mjs +3 -1
package/src/dispatchAiFallback.mjs +334 -0
package/src/dispatchAntigravity.mjs +192 -0
package/test/tools/fakeCliForTest.mjs +8 -0
package/test/unit-WDispatchAi.test.mjs +13 -6
package/test/unit-adapters.test.mjs +5 -3
package/test/unit-dispatchAi.test.mjs +7 -3
package/test/unit-dispatchAiFallback.test.mjs +422 -0
package/test/unit-dispatchAntigravity.test.mjs +173 -0

package/docs/dispatchAiFallback.mjs.html ADDED Viewed

@@ -0,0 +1,406 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>dispatchAiFallback.mjs - Documentation</title>
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+<label for="nav-trigger" class="overlay"></label>
+<nav >
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
+</nav>
+<div id="main">
+    <h1 class="page-title">dispatchAiFallback.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import isobj from 'wsemi/src/isobj.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import dispatchAi from './dispatchAi.mjs'
+import getErrorResult from './getErrorResult.mjs'
+// dispatchAiFallback.mjs — 多供應商自動遞補層
+//
+// 【兩層策略】群組之間依providers宣告順序(優先序), 群組之內(keys多把)以游標輪替(額度均攤)。
+//
+// 【失敗分流】只分兩路:
+//   與金鑰無關之失敗(TIMEOUT/ENOENT/參數錯誤/驗證失敗/未知kind) → 整組跳過——
+//   同組各金鑰共用同一exe與model, 換金鑰必然再敗一次, 純屬空耗;
+//   其餘失敗(含額度上限/金鑰無效/服務回錯等一切未分類者) → 換組內下一把, 不記憶、不停用。
+//   不可把正確性建立在「錯誤分類器必須窮盡」之上——實測各家額度/金鑰錯誤訊息
+//   含中文(无效的令牌)與無特徵字串(UnknownError), 正則涵蓋不了; 而額度視窗有5小時滾動、
+//   逐小時、逐日等多種形態, 「命中即停用到當日結束」會把已復活的金鑰冰到隔天。
+//   故跨次執行不設停用清單: 額度恢復的偵測就是「下次再打一次」, 代價僅一次快速失敗。
+//
+// 【跨次記憶只有游標】成功後游標推進至下一把, 令額度在同組多把金鑰間自動均攤;
+//   死金鑰的代價也被游標攤平——這輪從key1敗轉key2成功後游標停在key3, 下輪不會先碰key1。
+//
+// 【時間預算】budgetMs限制整輪遞補的總時長, 剩餘預算會壓進每次呼叫的timeoutMs,
+//   防止多家連續卡逾時而撞破外部排程的執行上限。
+//fallback層自用之設定鍵, 其餘鍵作為各attempt之共用預設原樣轉傳
+let FALLBACK_KEYS = ['providers', 'budgetMs', 'minAttemptMs', 'store', 'onEvent']
+//providers條目自用之設定鍵, 其餘鍵(含kind)即該條目之opt原樣轉傳對應轉接器
+let ENTRY_KEYS = ['id', 'keys']
+//預設值
+let DEFAULT_MIN_ATTEMPT_MS = 20000
+let DEFAULT_TIMEOUT_MS = 120000
+//memoryState, 未注入store時之行程內預設狀態(跨呼叫有效, 重啟歸零)
+let memoryState = { cursors: {} }
+/**
+ * 判斷失敗結果是否與「哪一把金鑰」無關(換組內金鑰必然再敗, 應整組跳過)
+ *
+ * @param {Object} r 輸入dispatchAi失敗結果物件
+ * @returns {Boolean} 回傳是否應整組跳過之布林值
+ */
+function isKeyIndependentFail(r) {
+    let error = get(r, 'error', '')
+    if (!isestr(error)) {
+        error = ''
+    }
+    let code = get(r, 'code', null)
+    //逾時, 該服務卡住, 同服務其他金鑰只會再空耗一次完整timeout
+    if (error.indexOf('TIMEOUT') === 0) {
+        return true
+    }
+    //執行檔不存在, 同組共用同一exe
+    if (error.includes('ENOENT')) {
+        return true
+    }
+    //參數錯誤, 同組共用同一組旗標
+    if (code === 2) {
+        return true
+    }
+    //輸出未過驗證, CLI正常結束(code=0)且模型有回應, 換金鑰仍是同一模型之產出習慣
+    //注意判定依據是error字串而非code===0(code===0且ok===true是成功)
+    if (error === 'OUTPUT_VALIDATION_FAILED') {
+        return true
+    }
+    //kind無效, 屬條目設定錯誤
+    if (error.indexOf('unknown ai kind') === 0) {
+        return true
+    }
+    return false
+}
+/**
+ * 依供應商清單順序自動遞補調用AI，組內多金鑰以游標輪替
+ *
+ * 特點：
+ * providers陣列順序即優先序，排前面的先用；
+ * 條目本身即該次調用之opt(除id與keys外原樣透傳對應轉接器)，與dispatchAi「條目直接當opt」同一約定；
+ * 條目給予keys(多把金鑰)時以游標輪替，某把失敗自動換下一把，全數失敗才遞補下一組；
+ * 與金鑰無關之失敗(逾時/執行檔不存在/參數錯誤/輸出未過驗證/未知kind)直接整組跳過，不逐把空耗；
+ * 跨次執行僅記憶游標(經store注入持久化)，不設金鑰停用清單——額度視窗形態多樣(5小時滾動/逐時/逐日)，
+ * 停用會把已恢復的金鑰閒置，而重探的代價僅一次快速失敗；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，一律以stdin傳入子進程
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {Array} opt.providers 輸入供應商條目物件陣列，順序即優先序。各條目除下列鍵外，其餘鍵(kind、model、exe、provider、config、sandbox、timeoutMs等)即該條目之opt原樣透傳對應轉接器
+ * @param {String} [opt.providers[].id=條目索引字串] 輸入群組識別字串，游標以此為鍵，多金鑰條目應給予穩定id，預設為條目索引字串
+ * @param {Array} [opt.providers[].keys=[]] 輸入同一服務之多把API key字串陣列，逐次注入輪替(kind為opencode時須同時於條目給予provider)，省略代表沿用CLI既有登入狀態之單一虛擬金鑰
+ * @param {Number} [opt.budgetMs=null] 輸入整輪遞補之時間上限毫秒正整數，剩餘預算會壓進每次呼叫之timeoutMs，預設null代表不限
+ * @param {Number} [opt.minAttemptMs=20000] 輸入單次嘗試之最低剩餘預算毫秒正整數，剩餘低於此值即停止嘗試回報budget exhausted，預設20000
+ * @param {Object} [opt.store=null] 輸入狀態持久化物件{get:()=>state,set:(state)=>{}}，state內含cursors(逐群組游標)，省略代表用行程內記憶體(跨呼叫有效，重啟歸零)。假定單行程序列調用，並行請自行加鎖
+ * @param {Function} [opt.onEvent=null] 輸入事件回調函數(ev)=>{}，ev.type可為'try'、'ok'、'next-key'、'skip-group'、'budget-out'，回調拋出例外不影響主流程，預設null
+ * @param {Number} [opt.timeoutMs=120000] 輸入各attempt共用之逾時毫秒正整數，條目可覆寫，預設120000
+ * @param {String|Function} [opt.validate=undefined] 輸入各attempt共用之stdout驗證規則，條目可覆寫，預設undefined
+ * @param {Number} [opt.maxRetries=0] 輸入各attempt共用之同家重試次數非負整數，韌性建議交給換家而非重試同一家，預設0
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，除execCli既有欄位(ok、stdout、stderr、code、error、durationMs、attempts、pid)外，追加providerId(實際使用之群組)、keyIndex(實際使用之金鑰索引，無keys時為null)、kind、model、tried(全部嘗試歷程陣列，成功時亦回傳)，本函數不會reject
+ * @example
+ * //need opencode, claude, codex cli in system PATH
+ *
+ * import dispatchAiFallback from './src/dispatchAiFallback.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await dispatchAiFallback('請只回覆兩個字：完成', {
+ *         providers: [
+ *             {
+ *                 id: 'deepseek',
+ *                 kind: 'opencode',
+ *                 model: 'opencode/deepseek-v4-flash-free',
+ *                 provider: 'opencode',
+ *                 keys: ['sk-aaa', 'sk-bbb'], //多把金鑰, 某把失敗自動換下一把
+ *                 timeoutMs: 180000,
+ *             },
+ *             { id: 'claude', kind: 'claude', model: 'sonnet' }, //deepseek全敗時遞補
+ *             { id: 'codex', kind: 'codex', model: 'gpt-5.6-luna', sandbox: 'read-only' },
+ *         ],
+ *         budgetMs: 600000,
+ *         onEvent: (ev) => console.log(ev.type, ev.providerId, ev.keyIndex),
+ *     })
+ *     console.log(r.ok, r.providerId, r.keyIndex, r.tried.length)
+ *     // => true 'deepseek' 0 1
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchAiFallback(prompt, opt = {}) {
+    //check prompt, 於頂層先擋, 否則會逐組空跑同一錯誤
+    if (!isestr(prompt)) {
+        return { ...getErrorResult('prompt must be a non-empty string'), tried: [] }
+    }
+    //providers, 濾除非物件條目
+    let providersRaw = get(opt, 'providers', null)
+    let providers = isarr(providersRaw) ? providersRaw.filter(isobj) : []
+    if (providers.length === 0) {
+        return { ...getErrorResult('providers must be a non-empty array'), tried: [] }
+    }
+    //budgetMs, 無效視為不限
+    let budgetMs = get(opt, 'budgetMs', null)
+    if (!ispint(budgetMs)) {
+        budgetMs = null
+    }
+    else {
+        budgetMs = cint(budgetMs)
+    }
+    let deadline = (budgetMs === null) ? null : Date.now() + budgetMs
+    //minAttemptMs, 無效回退預設20000
+    let minAttemptMs = get(opt, 'minAttemptMs', null)
+    if (!ispint(minAttemptMs)) {
+        minAttemptMs = DEFAULT_MIN_ATTEMPT_MS
+    }
+    else {
+        minAttemptMs = cint(minAttemptMs)
+    }
+    //store, 須同時具get與set函數才視為有效, 否則用行程內記憶體
+    let store = get(opt, 'store', null)
+    let useStore = isobj(store) &amp;&amp; isfun(store.get) &amp;&amp; isfun(store.set)
+    let state = null
+    if (useStore) {
+        try {
+            state = store.get()
+        }
+        catch {}
+    }
+    if (!isobj(state)) {
+        state = useStore ? { cursors: {} } : memoryState
+    }
+    if (!isobj(state.cursors)) {
+        state.cursors = {}
+    }
+    let saveState = () => {
+        if (useStore) {
+            try {
+                store.set(state)
+            }
+            catch {}
+        }
+    }
+    //onEvent, 回調拋出例外不得中斷主流程
+    let onEvent = get(opt, 'onEvent', null)
+    let emit = (ev) => {
+        if (isfun(onEvent)) {
+            try {
+                onEvent(ev)
+            }
+            catch {}
+        }
+    }
+    //sharedOpt, 剔除fallback層自用鍵後作為各attempt共用預設, 條目覆寫之
+    let sharedOpt = omit(opt, FALLBACK_KEYS)
+    let tried = []
+    let lastResult = null
+    let lastMeta = null
+    //逐群組(宣告順序即優先序), 單向單輪不回頭
+    for (let ig = 0; ig &lt; providers.length; ig++) {
+        let entry = providers[ig]
+        //id, 無效回退條目索引字串
+        let id = get(entry, 'id', null)
+        if (!isestr(id)) {
+            id = String(ig)
+        }
+        //kind與model僅供事件與回傳meta, kind有效性由dispatchAi判定
+        let kind = get(entry, 'kind', null)
+        let model = get(entry, 'model', null)
+        //keys, 濾除非有效字串, 空陣列視同未給(登入態單一虛擬金鑰)
+        let keysRaw = get(entry, 'keys', null)
+        let keys = isarr(keysRaw) ? keysRaw.filter(isestr) : []
+        let nk = keys.length
+        //entryOpt, 剔除條目自用鍵後即該條目之opt
+        let entryOpt = omit(entry, ENTRY_KEYS)
+        //游標, 逐群組記錄, 以現行keys長度取模自癒(金鑰陣列改動時不出界)
+        let cursor = 0
+        if (nk > 0) {
+            let c = get(state.cursors, id, 0)
+            cursor = ispint(c) ? cint(c) % nk : 0
+        }
+        //組內逐把嘗試, 每把至多一次, 全敗即組盡遞補下一組
+        let nAttempts = (nk > 0) ? nk : 1
+        let skipGroup = false
+        for (let a = 0; a &lt; nAttempts &amp;&amp; !skipGroup; a++) {
+            //keyIndex, 無keys時為null
+            let keyIndex = (nk > 0) ? (cursor + a) % nk : null
+            let keyId = (keyIndex === null) ? id : `${id}#${keyIndex}`
+            //attemptOpt, 共用預設 &lt;- 條目覆寫 &lt;- 本把金鑰
+            let attemptOpt = { ...sharedOpt, ...entryOpt }
+            if (nk > 0) {
+                attemptOpt.key = keys[keyIndex]
+            }
+            //有效timeout, 有預算時以剩餘預算封頂
+            let effTimeout = get(attemptOpt, 'timeoutMs', null)
+            if (!ispint(effTimeout)) {
+                effTimeout = DEFAULT_TIMEOUT_MS
+            }
+            else {
+                effTimeout = cint(effTimeout)
+            }
+            if (deadline !== null) {
+                let remaining = deadline - Date.now()
+                //剩餘不足一次最低嘗試, 停止遞補回報預算用盡
+                if (remaining &lt; minAttemptMs) {
+                    emit({ type: 'budget-out', providerId: id, keyIndex, keyId, remainingMs: remaining })
+                    tried.push({ providerId: id, keyIndex, keyId, outcome: 'budget-out' })
+                    return { ...getErrorResult('budget exhausted'), tried }
+                }
+                effTimeout = Math.min(effTimeout, remaining)
+            }
+            attemptOpt.timeoutMs = effTimeout
+            //dispatch
+            emit({ type: 'try', providerId: id, keyIndex, keyId, kind, model })
+            let r = await dispatchAi(kind, prompt, attemptOpt)
+            //成功, 推進游標(額度均攤)並回傳
+            if (r.ok) {
+                if (nk > 0) {
+                    state.cursors[id] = (keyIndex + 1) % nk
+                    saveState()
+                }
+                emit({ type: 'ok', providerId: id, keyIndex, keyId, durationMs: r.durationMs })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'ok', durationMs: r.durationMs })
+                return { ...r, providerId: id, keyIndex, kind, model, tried }
+            }
+            //失敗分流
+            lastResult = r
+            lastMeta = { providerId: id, keyIndex, kind, model }
+            if (isKeyIndependentFail(r)) {
+                //與金鑰無關, 整組跳過
+                emit({ type: 'skip-group', providerId: id, keyIndex, keyId, error: r.error })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'skip-group', error: r.error, durationMs: r.durationMs })
+                skipGroup = true
+            }
+            else {
+                //其餘(含額度上限/金鑰無效/未分類), 換組內下一把, 不記憶不停用
+                emit({ type: 'next-key', providerId: id, keyIndex, keyId, error: r.error })
+                tried.push({ providerId: id, keyIndex, keyId, outcome: 'next-key', error: r.error, durationMs: r.durationMs })
+            }
+        }
+    }
+    //全數失敗, 回傳最後一筆失敗結果與完整歷程
+    let r = lastResult || getErrorResult('all providers failed')
+    return { ...r, ...(lastMeta || {}), tried }
+}
+export default dispatchAiFallback
+</code></pre>
+        </article>
+    </section>
+</div>
+<br class="clear">
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 10 2026 09:36:49 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+</body>
+</html>

package/docs/dispatchAntigravity.mjs.html ADDED Viewed

@@ -0,0 +1,264 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>dispatchAntigravity.mjs - Documentation</title>
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+<label for="nav-trigger" class="overlay"></label>
+<nav >
+    <h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#WDispatchAi">WDispatchAi</a></li><li><a href="global.html#adapters">adapters</a></li><li><a href="global.html#dispatchAi">dispatchAi</a></li><li><a href="global.html#dispatchAiFallback">dispatchAiFallback</a></li><li><a href="global.html#dispatchAntigravity">dispatchAntigravity</a></li><li><a href="global.html#dispatchClaude">dispatchClaude</a></li><li><a href="global.html#dispatchCodex">dispatchCodex</a></li><li><a href="global.html#dispatchOpencode">dispatchOpencode</a></li><li><a href="global.html#getCliArgs">getCliArgs</a></li><li><a href="global.html#getErrorResult">getErrorResult</a></li><li><a href="global.html#isKeyIndependentFail">isKeyIndependentFail</a></li></ul>
+</nav>
+<div id="main">
+    <h1 class="page-title">dispatchAntigravity.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isarr from 'wsemi/src/isarr.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import execCli from 'wsemi/src/execCli.mjs'
+import getCliArgs from './getCliArgs.mjs'
+import getErrorResult from './getErrorResult.mjs'
+// dispatchAntigravity.mjs — 以Google Antigravity CLI(agy)呼叫AI模型
+//
+// agy為Google官方之Gemini CLI後繼者(Gemini CLI已於2026-06-18停服), 命令名為agy非antigravity。
+// 實測其models清單除Gemini系外亦含claude與gpt-oss等模型, 屬多模型閘道。
+//
+// 【prompt走--print旗標, 不走stdin(2026-08-10於本機agy 1.1.11實測確認)】
+//   --print為帶值旗標(無值即回`flag needs an argument: -print`), 不可能由stdin取prompt;
+//   把prompt塞stdin而args無--print會進互動模式卡住。此為與另三家轉接器最大差異。
+//
+// 【命令列長度上限(實測)】prompt作為命令列參數受Windows CreateProcess之32767字元上限:
+//   純文字32600可spawn、32700即spawn ENAMETOOLONG(同步拋出, 會穿透execCli成rejection)。
+//   且含引號之prompt經spawn轉義後長度會膨脹(實測2萬個引號轉義後仍炸), 故防護須兩層:
+//   前置長度檢查(常見情境給清楚錯誤訊息) + try/catch兜底(轉義膨脹等漏網情境),
+//   兩層皆回錯誤結果物件, 維持本套件「不reject」之契約。
+//
+// 【model與effort之衝突規則(實測)】帶檔位之slug(如gemini-3.1-pro-high)與--effort同時給定時,
+//   檔位「不一致」才拒絕(`--model gemini-3.1-pro-high conflicts with --effort=low`, exit 1),
+//   一致(gemini-3.1-pro-high + --effort high)則放行; 基礎slug(如gemini-3.1-pro)搭配effort亦放行。
+//   本轉接器不預判slug格式(模型清單會演進), 衝突時由agy回報conflicts錯誤。
+//
+// 【雙逾時對齊】agy自身有--print-timeout(預設5m0s), 與execCli之timeoutMs為兩層獨立逾時。
+//   printTimeout未給時由timeoutMs推導並預留30秒緩衝, 令CLI先於外層逾時,
+//   使錯誤訊息來自agy自身而非被外層強殺。
+//預設值
+let DEFAULT_EXE = 'agy'
+let DEFAULT_TIMEOUT_MS = 300000 //agent型CLI, 對齊agy自身print-timeout預設5m0s, 不沿用套件通用120000
+let MAX_PROMPT_LENGTH = 30000 //命令列上限32767扣除exe路徑與旗標後之保守值
+let PRINT_TIMEOUT_BUFFER_S = 30
+let MIN_PRINT_TIMEOUT_S = 30
+//本轉接器自用之設定鍵, 其餘鍵一律原樣轉傳execCli
+let OWN_KEYS = ['exe', 'model', 'effort', 'skipPermissions', 'printTimeout', 'addDirs', 'extraArgs', 'input']
+/**
+ * 以Google Antigravity CLI(agy)呼叫AI模型
+ *
+ * 特點：
+ * prompt作為`--print`旗標之值傳遞而非stdin(agy介面如此，塞stdin會進互動模式卡住)，
+ * 故prompt受命令列長度上限約束，超過30000字元回傳錯誤結果物件；
+ * model須為`agy models`第一欄之slug(如gemini-3.6-flash-low)，注意agy錯誤訊息列出的是顯示名稱而非slug；
+ * 帶檔位之slug(-high/-medium/-low結尾)與effort同時給定且檔位不一致時agy回conflicts錯誤(一致則放行)，
+ * effort需agy>=1.1.11，建議搭配不帶檔位之基礎slug(如gemini-3.1-pro)使用；
+ * 預設帶`--dangerously-skip-permissions`令非互動print模式不卡權限確認，可給予skipPermissions為false保留權限閘門；
+ * agy自身之--print-timeout未給時由timeoutMs推導並預留30秒緩衝，令CLI先於外層逾時；
+ * 沿用agy既有OAuth登入狀態(首次須於桌面互動模式完成登入)；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，作為`--print`旗標之值傳遞，長度上限30000字元
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.exe='agy'] 輸入agy執行檔名稱或絕對路徑字串，命令名為agy非antigravity，給予名稱時由execCli自系統PATH解析，預設'agy'
+ * @param {String} [opt.model=''] 輸入模型slug字串，須為`agy models`第一欄之slug，例如'gemini-3.6-flash-low'、'gemini-3.1-pro-high'，預設''代表不帶`--model`旗標由agy自行決定
+ * @param {String} [opt.effort=''] 輸入推理深度字串，可選'low'、'medium'、'high'，需agy>=1.1.11，建議搭配不帶檔位之基礎slug；與帶檔位slug併用且檔位不一致時agy回conflicts錯誤，預設''代表不帶
+ * @param {Boolean} [opt.skipPermissions=true] 輸入是否帶`--dangerously-skip-permissions`旗標布林值，false代表保留CLI權限閘門，預設true
+ * @param {String} [opt.printTimeout=''] 輸入agy自身等待上限字串(如'10m'、'570s')，預設''代表由timeoutMs推導(扣30秒緩衝，下限30秒)
+ * @param {Array} [opt.addDirs=[]] 輸入加入workspace之目錄字串陣列，逐項展開為`--add-dir`，預設[]
+ * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列(如--output-format、--json-schema、--mode)，將接於固定旗標之後、`--print`之前，預設[]
+ * @param {Number} [opt.timeoutMs=300000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，agy為agent型CLI故預設較長之300000，預設300000
+ * @param {String} [opt.cwd=process.cwd()] 輸入子進程工作目錄字串，預設process.cwd()
+ * @param {String|Function} [opt.validate=undefined] 輸入stdout驗證規則字串或自訂驗證函數，規則字串支援'nonempty'、'json'、'min:100'，多規則可用逗號串接，預設undefined代表不驗證
+ * @param {Number} [opt.maxRetries=0] 輸入失敗後最大重試次數非負整數，預設0
+ * @returns {Promise} 回傳Promise，resolve回傳結果物件，內含ok(是否成功布林值)、stdout(標準輸出字串)、stderr(標準錯誤字串)、code(離開碼)、error(錯誤訊息字串，成功時為空字串)、durationMs(耗時毫秒)、attempts(實際嘗試次數)，本函數不會reject
+ * @example
+ * //need agy cli in system PATH, and OAuth login completed
+ *
+ * import dispatchAntigravity from './src/dispatchAntigravity.mjs'
+ *
+ * let test = async () => {
+ *
+ *     let r = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.6-flash-low' })
+ *     console.log(r.ok, r.stdout.trim())
+ *     // => true 完成
+ *
+ *     //基礎slug搭配effort(不可用帶檔位之slug併用effort)
+ *     let r2 = await dispatchAntigravity('請只回覆兩個字：完成', { model: 'gemini-3.1-pro', effort: 'low' })
+ *     console.log(r2.ok)
+ *     // => true
+ *
+ *     let re = await dispatchAntigravity('')
+ *     console.log(re.ok, re.error)
+ *     // => false 'prompt must be a non-empty string'
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchAntigravity(prompt, opt = {}) {
+    //check prompt, 不reject故以錯誤結果物件回報
+    if (!isestr(prompt)) {
+        return getErrorResult('prompt must be a non-empty string')
+    }
+    //check prompt length, agy之prompt走命令列旗標而非stdin, 受CreateProcess 32767字元上限約束
+    if (prompt.length > MAX_PROMPT_LENGTH) {
+        return getErrorResult(`prompt too long (${prompt.length} chars > ${MAX_PROMPT_LENGTH}), agy passes prompt via --print flag and Windows command line is capped at 32767 chars`)
+    }
+    //exe, 無效回退預設'agy', 由execCli自系統PATH解析實體路徑
+    let exe = get(opt, 'exe', null)
+    if (!isestr(exe)) {
+        exe = DEFAULT_EXE
+    }
+    //model, 無效時整段`--model`旗標不出現, 由agy自行決定使用模型
+    let model = get(opt, 'model', null)
+    //effort, 無效時整段`--effort`旗標不出現; 與帶檔位slug之衝突由agy判定(檔位不一致時conflicts錯誤, exit 1)
+    let effort = get(opt, 'effort', null)
+    //skipPermissions, 非布林值回退預設true(非互動print模式不卡權限確認)
+    let skipPermissions = get(opt, 'skipPermissions', null)
+    if (!isbol(skipPermissions)) {
+        skipPermissions = true
+    }
+    //timeoutMs, 先行取值以供printTimeout推導, agy專屬預設300000
+    let timeoutMs = get(opt, 'timeoutMs', null)
+    if (!ispint(timeoutMs)) {
+        timeoutMs = DEFAULT_TIMEOUT_MS
+    }
+    else {
+        timeoutMs = cint(timeoutMs)
+    }
+    //printTimeout, 未給時由timeoutMs推導並預留緩衝, 令agy先於外層逾時而回報自身錯誤訊息
+    let printTimeout = get(opt, 'printTimeout', null)
+    if (!isestr(printTimeout)) {
+        printTimeout = `${Math.max(MIN_PRINT_TIMEOUT_S, Math.floor(timeoutMs / 1000) - PRINT_TIMEOUT_BUFFER_S)}s`
+    }
+    //addDirs, 逐項展開為--add-dir(agy該旗標可重複)
+    let addDirs = get(opt, 'addDirs', null)
+    let addDirArgs = []
+    if (isarr(addDirs)) {
+        for (let d of addDirs) {
+            if (isestr(d)) {
+                addDirArgs.push('--add-dir', d)
+            }
+        }
+    }
+    //extraArgs
+    let extraArgs = get(opt, 'extraArgs', null)
+    //args, prompt作為--print之值放最後
+    let args = getCliArgs(
+        skipPermissions ? '--dangerously-skip-permissions' : [],
+        ['--print-timeout', printTimeout],
+        isestr(model) ? ['--model', model] : [],
+        isestr(effort) ? ['--effort', effort] : [],
+        addDirArgs,
+        extraArgs,
+        ['--print', prompt],
+    )
+    //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
+    let optCli = omit(opt, OWN_KEYS)
+    //execCli, 不帶input(agy由--print取得prompt); try/catch兜底轉義膨脹等
+    //前置檢查漏網之spawn同步拋出(如ENAMETOOLONG), 維持不reject契約
+    try {
+        return await execCli(exe, args, {
+            ...optCli,
+            timeoutMs,
+        })
+    }
+    catch (err) {
+        return getErrorResult(`${err.code || 'UNKNOWN'}: ${err.message}`)
+    }
+}
+export default dispatchAntigravity
+</code></pre>
+        </article>
+    </section>
+</div>
+<br class="clear">
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Aug 10 2026 09:36:49 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+</body>
+</html>