w-dispatch-ai 1.0.0

package/src/dispatchOpencode.mjs

@@ -0,0 +1,188 @@
+import get from 'lodash-es/get.js'
+import omit from 'lodash-es/omit.js'
+import isobj from 'wsemi/src/isobj.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import execCli from 'wsemi/src/execCli.mjs'
+import getCliArgs from './getCliArgs.mjs'
+import getErrorResult from './getErrorResult.mjs'
+
+
+// dispatchOpencode.mjs — 以opencode CLI呼叫AI模型
+//
+// 【金鑰注入(2026-08-08於本機實測確認，非讀碼推論)】
+//   OPENCODE_AUTH_CONTENT環境變數會「完全覆蓋」opencode的auth.json：
+//   實測帶入無效key → `Error: Invalid API key.`(code=1、訊息在stderr、stdout空)；
+//   帶入真實key → 正常回應。以env傳入「不會改寫」auth.json(實測md5前後一致)，
+//   屬process層級，可與同時執行的其他專案並行而互不干擾。
+//   註：OPENCODE_API_KEY在auth.json已有憑證時不生效，故一律走OPENCODE_AUTH_CONTENT。
+//
+// 【provider與model必須配對】不同provider的金鑰不可互換：
+//   實測把agnes-ai的金鑰用於opencode/...模型 → `Invalid API key`。
+//   故呼叫端傳入的key／provider／model須為同一組。
+//
+// 【第三方provider須另給config(2026-08-09於本機實測確認)】
+//   opencode僅內建自家provider，第三方(例如agnes-ai)未定義於設定檔時，
+//   只注入金鑰仍無法使用：實測`opencode models`不列出該provider之模型，
+//   直接指定模型則回`UnknownError／Unexpected server error`。
+//   OPENCODE_CONFIG_CONTENT環境變數可逐次注入設定內容，補上provider定義後
+//   `opencode models`即列出agnes-ai/agnes-2.0-flash且可正常對話，
+//   與OPENCODE_AUTH_CONTENT同為process層級，不改寫使用者設定檔。
+
+
+//預設值
+let DEFAULT_EXE = 'opencode'
+let DEFAULT_AGENT = 'build'
+
+
+//本轉接器自用之設定鍵, 其餘鍵一律原樣轉傳execCli
+let OWN_KEYS = ['exe', 'model', 'key', 'provider', 'agent', 'config', 'extraArgs', 'input', 'env']
+
+
+/**
+ * 以opencode CLI呼叫AI模型
+ *
+ * 特點：
+ * prompt一律走stdin而非位置參數，因摘要內文可達數萬字，當命令列參數會spawn ENAMETOOLONG，
+ * 而opencode run未帶位置message時即從stdin讀取；
+ * 同時給予key與provider時，以OPENCODE_AUTH_CONTENT環境變數逐次注入金鑰，
+ * 該注入僅作用於當次子進程且不改寫auth.json，故可多把金鑰輪替並與其他程序並行；
+ * 未給key或provider時沿用CLI既有登入狀態；
+ * 使用opencode未內建之第三方provider時，須另以config給予其provider定義；
+ * 本函數不會reject，一律以結果物件之ok與error欄位回報成敗
+ *
+ * @param {String} prompt 輸入提示詞字串，一律以stdin傳入子進程
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.exe='opencode'] 輸入opencode執行檔名稱或絕對路徑字串，給予名稱時由execCli自系統PATH解析，預設'opencode'
+ * @param {String} [opt.model=''] 輸入模型ID字串，例如'opencode/deepseek-v4-flash-free'，預設''代表不帶`-m`旗標
+ * @param {String} [opt.key=''] 輸入該provider之API key字串，須與provider同時給予才會注入，預設''代表沿用CLI既有登入狀態
+ * @param {String} [opt.provider=''] 輸入key所屬provider名稱字串，須與key同時給予才會注入，且須與model為同一組，預設''
+ * @param {Object|String} [opt.config=null] 輸入opencode設定內容物件或其JSON字串，將以OPENCODE_CONFIG_CONTENT逐次注入，供補上第三方provider之定義，預設null代表沿用使用者既有設定檔
+ * @param {String} [opt.agent='build'] 輸入opencode代理名稱字串，預設'build'
+ * @param {Array} [opt.extraArgs=[]] 輸入額外命令列旗標字串陣列，將接於固定旗標之後，預設[]
+ * @param {Object} [opt.env=undefined] 輸入本次調用額外注入之環境變數物件，同時給予key與provider時會再併入OPENCODE_AUTH_CONTENT，預設undefined
+ * @param {Number} [opt.timeoutMs=120000] 輸入逾時毫秒正整數，逾時將強制關閉子進程及其子孫程序，預設120000
+ * @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 opencode cli in system PATH
+ *
+ * import dispatchOpencode from './src/dispatchOpencode.mjs'
+ *
+ * let test = async () => {
+ *
+ *     //沿用CLI既有登入狀態
+ *     let r1 = await dispatchOpencode('請只回覆兩個字：完成', { model: 'opencode/deepseek-v4-flash-free' })
+ *     console.log(r1.ok, r1.stdout.includes('完成'))
+ *     // => true true
+ *
+ *     //逐次注入金鑰, key與provider與model須為同一組
+ *     let r2 = await dispatchOpencode('請只回覆兩個字：完成', {
+ *         model: 'opencode/deepseek-v4-flash-free',
+ *         provider: 'opencode',
+ *         key: 'sk-xxxxxx',
+ *     })
+ *     console.log(r2.ok)
+ *     // => true
+ *
+ *     //opencode未內建之第三方provider, 須另以config給予其定義
+ *     let r3 = await dispatchOpencode('請只回覆兩個字：完成', {
+ *         model: 'agnes-ai/agnes-2.0-flash',
+ *         provider: 'agnes-ai',
+ *         key: 'sk-xxxxxx',
+ *         config: {
+ *             provider: {
+ *                 'agnes-ai': {
+ *                     npm: '@ai-sdk/openai-compatible',
+ *                     name: 'Agnes',
+ *                     options: { baseURL: 'https://apihub.agnes-ai.com/v1' },
+ *                     models: { 'agnes-2.0-flash': { name: 'Agnes 2.0 Flash' } },
+ *                 },
+ *             },
+ *         },
+ *     })
+ *     console.log(r3.ok)
+ *     // => true
+ *
+ * }
+ * await test()
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
+ */
+async function dispatchOpencode(prompt, opt = {}) {
+
+    //check prompt, 不reject故以錯誤結果物件回報
+    if (!isestr(prompt)) {
+        return getErrorResult('prompt must be a non-empty string')
+    }
+
+    //exe, 無效回退預設'opencode', 由execCli自系統PATH解析實體路徑
+    let exe = get(opt, 'exe', null)
+    if (!isestr(exe)) {
+        exe = DEFAULT_EXE
+    }
+
+    //model, 無效時整段`-m`旗標不出現, 由CLI自行決定使用模型
+    let model = get(opt, 'model', null)
+
+    //agent, 無效回退預設'build'
+    let agent = get(opt, 'agent', null)
+    if (!isestr(agent)) {
+        agent = DEFAULT_AGENT
+    }
+
+    //extraArgs
+    let extraArgs = get(opt, 'extraArgs', null)
+
+    //args
+    let args = getCliArgs(
+        'run',
+        ['--agent', agent],
+        isestr(model) ? ['-m', model] : [],
+        extraArgs,
+    )
+
+    //env, 無效回退undefined代表不覆寫任何變數
+    let env = get(opt, 'env', null)
+    if (!isobj(env)) {
+        env = undefined
+    }
+
+    //config有效才注入, 否則沿用使用者既有設定檔, 物件則序列化為JSON字串
+    let config = get(opt, 'config', null)
+    if (isobj(config)) {
+        config = JSON.stringify(config)
+    }
+    if (isestr(config)) {
+        env = {
+            ...env,
+            OPENCODE_CONFIG_CONTENT: config,
+        }
+    }
+
+    //key與provider皆有效才注入, 否則沿用auth.json既有登入狀態(單金鑰時即為原有行為)
+    let key = get(opt, 'key', null)
+    let provider = get(opt, 'provider', null)
+    if (isestr(key) && isestr(provider)) {
+        env = {
+            ...env,
+            OPENCODE_AUTH_CONTENT: JSON.stringify({ [provider]: { type: 'api', key } }),
+        }
+    }
+
+    //optCli, 剔除本轉接器自用鍵後原樣轉傳, 令呼叫端可用execCli全部設定(例如onStdout、maxBuffer)
+    let optCli = omit(opt, OWN_KEYS)
+
+    //execCli, prompt一律走stdin
+    return execCli(exe, args, {
+        ...optCli,
+        input: prompt,
+        env,
+    })
+}
+
+
+export default dispatchOpencode

package/src/getCliArgs.mjs

@@ -0,0 +1,54 @@
+import isarr from 'wsemi/src/isarr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+
+
+/**
+ * 將各段命令列參數展平為字串陣列，並濾除非有效字串
+ *
+ * 各轉接器之參數為「固定旗標」加「可選旗標」加「額外旗標」之組合，
+ * 其中可選旗標於未給值時須整段消失(例如未給model就不可出現懸空的`--model`)，
+ * 故呼叫端須以「整段陣列給或不給」表達，本函數僅負責展平與濾除非有效字串，不判斷旗標配對；
+ * 過濾之必要在於Nodejs之spawn要求各參數必為字串，混入undefined或數字會直接拋出TypeError，
+ * 破壞本套件「不reject、僅以結果物件回報」之約定
+ *
+ * @param {...(String|Array)} args 輸入參數字串或參數字串陣列，可給多個
+ * @returns {Array} 回傳展平且濾除非有效字串後之參數字串陣列
+ * @example
+ *
+ * import getCliArgs from './src/getCliArgs.mjs'
+ *
+ * console.log(getCliArgs('-p', ['--model', 'sonnet']))
+ * // => ['-p', '--model', 'sonnet']
+ *
+ * console.log(getCliArgs('-p', null, 123, ['', '--verbose']))
+ * // => ['-p', '--verbose']
+ *
+ */
+function getCliArgs(...args) {
+
+    let r = []
+
+    for (let arg of args) {
+
+        //陣列則逐項展開, 僅展一層
+        if (isarr(arg)) {
+            for (let v of arg) {
+                if (isestr(v)) {
+                    r.push(v)
+                }
+            }
+            continue
+        }
+
+        //非陣列即視為單一參數
+        if (isestr(arg)) {
+            r.push(arg)
+        }
+
+    }
+
+    return r
+}
+
+
+export default getCliArgs

package/src/getErrorResult.mjs

@@ -0,0 +1,43 @@
+import isestr from 'wsemi/src/isestr.mjs'
+
+
+/**
+ * 產生與execCli同結構之錯誤結果物件
+ *
+ * 本套件各dispatch函數一律不reject，參數檢核失敗時即以本函數回傳錯誤結果物件，
+ * 其欄位與wsemi之execCli回傳結構一致，故呼叫端可用同一套欄位判斷成敗，
+ * 無須區分「參數錯誤」與「CLI執行失敗」兩種來源
+ *
+ * @param {String} error 輸入錯誤訊息字串
+ * @returns {Object} 回傳結果物件，內含ok(布林值，恆為false)、stdout(空字串)、stderr(空字串)、code(null)、error(錯誤訊息字串)、durationMs(0)、attempts(0)
+ * @example
+ *
+ * import getErrorResult from './src/getErrorResult.mjs'
+ *
+ * console.log(getErrorResult('prompt must be a non-empty string'))
+ * // => { ok: false, stdout: '', stderr: '', code: null, error: 'prompt must be a non-empty string', durationMs: 0, attempts: 0 }
+ *
+ * console.log(getErrorResult(null).error)
+ * // => 'unknown error'
+ *
+ */
+function getErrorResult(error) {
+
+    //check, 非有效字串時給予預設訊息, 確保error欄位恆為非空字串
+    if (!isestr(error)) {
+        error = 'unknown error'
+    }
+
+    return {
+        ok: false,
+        stdout: '',
+        stderr: '',
+        code: null,
+        error,
+        durationMs: 0,
+        attempts: 0,
+    }
+}
+
+
+export default getErrorResult

package/test/tools/fakeCliForTest.mjs

@@ -0,0 +1,139 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+
+// fakeCliForTest.mjs — 測試用的假CLI
+//
+// 各dispatch函數之可觀察行為為「以什麼參數、什麼stdin、什麼環境變數啟動子進程」，
+// 故產生一支會把args／stdin／env原樣印回stdout(JSON)的假CLI，即可對規格逐條斷言，
+// 而無須真的呼叫claude／codex／opencode(耗時、需登入、輸出不決定性)。
+//
+// 【為何要做成npm shim形狀】Windows下wsemi之execCli遇.cmd會先解析出JS入口再直接以node執行，
+//   解析不到才退回cmd.exe。做成npm全域安裝之shim形狀(入口置於node_modules下)即走前者，
+//   可完全避開cmd.exe之編碼與跳脫問題，令中文與多行參數皆可正確傳遞。
+//
+// 【產物落點】產物落在本檔所在之test資料夾下(test/tmp/)，不落主cwd根目錄，
+//   避免與專案根之./tmp/混用而難以清理；測試結束由clean()逐一清除。
+//   路徑由本檔位置衍生而非cwd-relative，故不論由何處啟動mocha皆落在同一處。
+
+
+//fdBase, 由本檔位置衍生(test/tools/ → test/tmp/), 屬「產物落在腳本所在資料夾」之情境
+//URL轉實體路徑只可用fileURLToPath, 不可用new URL(...).pathname(會回URL-encoded字串)
+let FD_BASE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'tmp')
+
+
+//假CLI本體, 由node執行
+let CODE_ENTRY = `
+let args = process.argv.slice(2)
+
+//--fake-exit=N, 令假CLI以指定離開碼結束, 供測試失敗與重試路徑
+let mExit = args.map((a) => /^--fake-exit=(\\d+)$/.exec(a)).find((m) => !!m)
+let exitCode = mExit ? Number(mExit[1]) : 0
+
+//--fake-stderr=XXX, 令假CLI輸出指定文字至stderr
+let mErr = args.map((a) => /^--fake-stderr=(.*)$/.exec(a)).find((m) => !!m)
+if (mErr) {
+    process.stderr.write(mErr[1])
+}
+
+//--fake-sleep=N, 令假CLI延遲N毫秒才結束, 供測試逾時路徑
+let mSleep = args.map((a) => /^--fake-sleep=(\\d+)$/.exec(a)).find((m) => !!m)
+
+let chunks = []
+process.stdin.on('data', (c) => {
+    chunks.push(c)
+})
+process.stdin.on('end', () => {
+    let r = {
+        args,
+        stdin: Buffer.concat(chunks).toString('utf8'),
+        cwd: process.cwd(),
+        env: {
+            OPENCODE_AUTH_CONTENT: process.env.OPENCODE_AUTH_CONTENT || '',
+            OPENCODE_CONFIG_CONTENT: process.env.OPENCODE_CONFIG_CONTENT || '',
+            FAKE_ENV: process.env.FAKE_ENV || '',
+        },
+    }
+    let end = () => {
+        process.stdout.write(JSON.stringify(r))
+        process.exit(exitCode)
+    }
+    if (mSleep) {
+        setTimeout(end, Number(mSleep[1]))
+    }
+    else {
+        end()
+    }
+})
+`
+
+
+/**
+ * 產生一支測試用的假CLI，回傳其執行檔路徑與清除函數
+ *
+ * @param {String} name 輸入假CLI名稱字串，各測試檔須給予不同名稱，避免mocha並行執行時互相干擾
+ * @returns {Object} 回傳物件，內含exe(假CLI執行檔絕對路徑字串)、fd(產物資料夾絕對路徑字串)、clean(清除產物之函數)
+ */
+function createFakeCli(name) {
+
+    //fd, 印出absolute路徑供除錯驗收
+    let fd = path.resolve(FD_BASE, name)
+
+    //fdEntry, 做成npm shim形狀, 入口須置於node_modules下才會被execCli解析出來
+    let fdEntry = path.join(fd, 'node_modules', name)
+    fs.mkdirSync(fdEntry, { recursive: true })
+
+    //entry
+    let fpEntry = path.join(fdEntry, 'entry.mjs')
+    fs.writeFileSync(fpEntry, CODE_ENTRY, 'utf8')
+
+    //exe
+    let exe = ''
+    if (process.platform === 'win32') {
+
+        //Windows, npm全域安裝之.cmd shim形狀
+        exe = path.join(fd, `${name}.cmd`)
+        let code = [
+            '@ECHO off',
+            'SETLOCAL',
+            'CALL :find_dp0',
+            'SET "_prog=node"',
+            `"%_prog%"  "%dp0%\\node_modules\\${name}\\entry.mjs" %*`,
+            'ENDLOCAL',
+            'EXIT /b %errorlevel%',
+            ':find_dp0',
+            'SET dp0=%~dp0',
+            'EXIT /b',
+            '',
+        ].join('\r\n')
+        fs.writeFileSync(exe, code, 'utf8')
+    }
+    else {
+
+        //POSIX, sh啟動器, node以絕對路徑給予避免PATH差異
+        exe = path.join(fd, name)
+        let code = [
+            '#!/bin/sh',
+            `exec "${process.execPath}" "$(dirname "$0")/node_modules/${name}/entry.mjs" "$@"`,
+            '',
+        ].join('\n')
+        fs.writeFileSync(exe, code, 'utf8')
+        fs.chmodSync(exe, 0o755)
+    }
+
+    //clean, 一併嘗試移除已空之上層資料夾, 令測試結束後test/tmp/不留殘跡
+    //上層可能仍有其他測試檔並行中之產物, 故rmdir失敗即忽略
+    let clean = () => {
+        fs.rmSync(fd, { recursive: true, force: true })
+        try {
+            fs.rmdirSync(FD_BASE)
+        }
+        catch {}
+    }
+
+    return { exe, fd, clean }
+}
+
+
+export default createFakeCli

package/test/unit-WDispatchAi.test.mjs

@@ -0,0 +1,79 @@
+import assert from 'assert'
+import keys from 'lodash-es/keys.js'
+import map from 'lodash-es/map.js'
+import wi from '../src/WDispatchAi.mjs'
+import dispatchAi from '../src/dispatchAi.mjs'
+import dispatchOpencode from '../src/dispatchOpencode.mjs'
+import dispatchClaude from '../src/dispatchClaude.mjs'
+import dispatchCodex from '../src/dispatchCodex.mjs'
+
+
+describe('WDispatchAi', function() {
+
+    it('對外提供KINDS與各dispatch函數', function() {
+        let r = keys(wi)
+        let rr = [
+            'KINDS',
+            'dispatchAi',
+            'dispatchOpencode',
+            'dispatchClaude',
+            'dispatchCodex',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('KINDS為可用之供應商種類字串陣列', function() {
+        let r = wi.KINDS
+        let rr = ['opencode', 'claude', 'codex']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('除KINDS外各鍵值皆為函數', function() {
+        let r = map(keys(wi), (k) => typeof wi[k])
+        let rr = ['object', 'function', 'function', 'function', 'function']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('各鍵值即為對應模組之預設匯出', function() {
+        let r = [
+            wi.dispatchAi === dispatchAi,
+            wi.dispatchOpencode === dispatchOpencode,
+            wi.dispatchClaude === dispatchClaude,
+            wi.dispatchCodex === dispatchCodex,
+        ]
+        let rr = [true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('KINDS各項皆可由dispatchAi分派', async function() {
+        let r = []
+        for (let kind of wi.KINDS) {
+            let t = await wi.dispatchAi(kind, '')
+            r.push(t.error)
+        }
+        let rr = ['prompt must be a non-empty string', 'prompt must be a non-empty string', 'prompt must be a non-empty string']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可由WDispatchAi呼叫dispatchAi', async function() {
+        let t = await wi.dispatchAi('gemini', 'abc')
+        let r = [t.ok, t.error]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex)']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('可由WDispatchAi呼叫各轉接器', async function() {
+        let r = []
+        for (let fn of [wi.dispatchOpencode, wi.dispatchClaude, wi.dispatchCodex]) {
+            let t = await fn('')
+            r.push([t.ok, t.error])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-adapters.test.mjs

@@ -0,0 +1,34 @@
+import assert from 'assert'
+import keys from 'lodash-es/keys.js'
+import map from 'lodash-es/map.js'
+import adapters from '../src/adapters.mjs'
+import dispatchOpencode from '../src/dispatchOpencode.mjs'
+import dispatchClaude from '../src/dispatchClaude.mjs'
+import dispatchCodex from '../src/dispatchCodex.mjs'
+
+
+describe('adapters', function() {
+
+    it('對照表鍵名即為可用之供應商種類', function() {
+        let r = keys(adapters)
+        let rr = ['opencode', 'claude', 'codex']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('各鍵值皆為函數', function() {
+        let r = map(keys(adapters), (k) => typeof adapters[k])
+        let rr = ['function', 'function', 'function']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('各鍵值即為對應模組之預設匯出', function() {
+        let r = [
+            adapters.opencode === dispatchOpencode,
+            adapters.claude === dispatchClaude,
+            adapters.codex === dispatchCodex,
+        ]
+        let rr = [true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/unit-dispatchAi.test.mjs

@@ -0,0 +1,104 @@
+import assert from 'assert'
+import dispatchAi from '../src/dispatchAi.mjs'
+import createFakeCli from './tools/fakeCliForTest.mjs'
+
+
+describe('dispatchAi', function() {
+
+    let fake = null
+
+    before(function() {
+        fake = createFakeCli('fake-dispatchai')
+    })
+
+    after(function() {
+        if (fake) {
+            fake.clean()
+        }
+    })
+
+    it('未知kind時回傳錯誤結果物件且不reject', async function() {
+        let t = await dispatchAi('gemini', 'abc')
+        let r = [t.ok, t.error, t.attempts]
+        let rr = [false, 'unknown ai kind: "gemini" (available: opencode, claude, codex)', 0]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('kind非有效字串時回傳錯誤結果物件', async function() {
+        let r = []
+        for (let kind of [null, undefined, '', 123, {}]) {
+            let t = await dispatchAi(kind, 'abc')
+            r.push([t.ok, t.error.indexOf('unknown ai kind') === 0])
+        }
+        let rr = [[false, true], [false, true], [false, true], [false, true], [false, true]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('kind為原型鍵名時不可誤判為有效供應商', async function() {
+        let r = []
+        for (let kind of ['constructor', 'toString', 'hasOwnProperty', '__proto__']) {
+            let t = await dispatchAi(kind, 'abc')
+            r.push([t.ok, t.error.indexOf('unknown ai kind') === 0])
+        }
+        let rr = [[false, true], [false, true], [false, true], [false, true]]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('prompt之檢核由各轉接器負責, 錯誤結果物件一致', async function() {
+        let r = []
+        for (let kind of ['opencode', 'claude', 'codex']) {
+            let t = await dispatchAi(kind, '')
+            r.push([t.ok, t.error])
+        }
+        let rr = [
+            [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
+            [false, 'prompt must be a non-empty string'],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('各kind分派至對應轉接器, 由其固定旗標可辨識', async function() {
+        let r = []
+        for (let kind of ['opencode', 'claude', 'codex']) {
+            let t = await dispatchAi(kind, 'abc', { exe: fake.exe, model: 'mdl' })
+            let o = JSON.parse(t.stdout)
+            r.push([t.ok, o.args])
+        }
+        let rr = [
+            [true, ['run', '--agent', 'build', '-m', 'mdl']],
+            [true, ['-p', '--dangerously-skip-permissions', '--model', 'mdl']],
+            [true, ['exec', '--sandbox', 'workspace-write', '--skip-git-repo-check', '-m', 'mdl']],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('opt原樣轉傳至對應轉接器', async function() {
+        let t = await dispatchAi('opencode', 'abc', { exe: fake.exe, provider: 'opencode', key: 'sk-abc', extraArgs: ['--fake-stderr=warn'] })
+        let o = JSON.parse(t.stdout)
+        let r = [t.stderr, JSON.parse(o.env.OPENCODE_AUTH_CONTENT).opencode.key]
+        let rr = ['warn', 'sk-abc']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('供應商條目可逐一輪替, 各條目自帶kind與model', async function() {
+        let items = [
+            { kind: 'opencode', model: 'opencode/free', provider: 'opencode', key: 'sk-1' },
+            { kind: 'claude', model: 'sonnet' },
+            { kind: 'codex', model: 'gpt-5.6-luna' },
+        ]
+        let r = []
+        for (let item of items) {
+            let t = await dispatchAi(item.kind, 'abc', { ...item, exe: fake.exe })
+            let o = JSON.parse(t.stdout)
+            r.push([item.kind, o.args[0], o.args.includes(item.model)])
+        }
+        let rr = [
+            ['opencode', 'run', true],
+            ['claude', '-p', true],
+            ['codex', 'exec', true],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})