agentflowctl 0.13.0 → 0.13.1

package/README.md

@@ -2,6 +2,8 @@
 
 讓 Claude Code、Codex、Gemini CLI 等 agent 在同一個專案裡分工：整理需求、規劃、寫測試與程式、交叉審查，最後建立 PR。agentflowctl 負責推進流程，並用檔案、測試和檢查結果決定能否進到下一步。
 
+目前內建支援三種 LLM CLI：**Claude Code、Codex、Gemini CLI**。未來可擴充自定義 LLM adapter，讓其他模型供應商加入流程。目前若要串接其他 CLI，可使用 `command` adapter，自行提供執行命令；需要模型驗證時，也須提供探測命令。
+
 每次執行都會建立獨立的 git worktree 與 `flow/<id>` 分支，不會直接修改你目前的工作目錄。兩個 agent 就能運作；若只有一個，也能執行，但無法做到跨 agent 審查。
 
 ## 開始使用
@@ -130,13 +132,33 @@ agentflowctl model mode adaptive
 agentflowctl run --req-file ./requirement.md
 ```
 
-把 `MODEL_NAME` 換成該 CLI 目前可呼叫的別名或完整 ID。`model add` 會用目前登入的帳號送出短請求，可能耗用少量 token；成功才寫入設定。需要重驗時執行 `model check`。用 `model set claude MODEL_NAME --strength medium` 改強度、`model remove claude MODEL_NAME` 移除模型，或用 `model stage taskReview high` 調整階段最低強度；`model stage` 不帶強度時列出各階段實際生效的強度。終端機每次呼叫會顯示送給 CLI 的模型名稱，Claude Code 與 Gemini CLI 回報的實際模型不同時也會顯示；`status <id>` 會按階段、任務、模型與步驟顯示用量。`run --model-mode balanced` 可暫時回到原設定。
+把 `MODEL_NAME` 換成該 CLI 目前可呼叫的別名或完整 ID。`model add` 會用目前登入的帳號送出短請求，可能耗用少量 token；成功才寫入設定。需要重驗時執行 `model check`。用 `model set claude MODEL_NAME --strength medium` 改強度、`model remove claude MODEL_NAME` 移除模型，或用 `model stage taskReview high` 調整階段最低強度；`model stage` 不帶強度時列出各階段實際生效的強度。終端機每次呼叫會顯示送給 CLI 的模型名稱；CLI 回報的實際模型不同時也會顯示（Claude Code 與 Gemini CLI 每次回報，Codex 只在模型被改派時回報）；`status <id>` 會按階段、任務、模型與步驟顯示用量。`run --model-mode balanced` 可暫時回到原設定。
 
 `status <id>` 的用量以每次 LLM 呼叫為一筆，失敗、額度用完及代打也會計入呼叫次數。只有 CLI 同時回報輸入與輸出 token，才把兩者納入合計與模型強度占比；明確回報的 0 仍算已回報。缺少任一數字列為「未回報」；舊紀錄無法分辨真實 0 與預設補值，列為「舊紀錄不明」，原始數字只供查閱。各 agent、階段、任務、模型與步驟、模型強度是同一批呼叫的不同分組，不應跨組相加。輸入 token 一律包含 cache 讀取與寫入：Claude Code 回報的 `input_tokens` 不含 cache，agentflowctl 會把 cache 讀寫加回去；Codex 的 `input_tokens` 本來就包含 cache。有回報 cache 時，`status` 與 `logs` 會另外標出其中讀取與寫入 cache 各多少。`model add/check` 的探測請求可能耗用 token，但不屬於 run，因此不在 `status` 內。
 
 計畫 agent 會查閱相關程式碼，依影響範圍、技術不確定性與失敗後果為每個任務標註 `low`／`medium`／`high` 難度，取三者中最高等級，並在計畫中寫出依據；計畫審查會逐項核對。自動選模先遵守角色分配，再取階段強度與任務難度中較高者；失敗重試會提高強度。若分配到的 agent 沒有足夠強度的模型，會選它最強的模型並提示。這些強度是你對模型能力的設定，不由 CLI 自動評分。
 
-模型探測必須能禁止工具。這版 Codex CLI 沒有可確認的無工具探測參數，因此 `model add` 無法驗證並登記 Codex 模型；手動寫入 `models` 仍可執行，但不代表已驗證可用。`balanced` 仍可照原方式使用。自訂 `command` adapter 另需提供會實際呼叫模型的探測命令；設定方式與限制見[詳細參考](docs/reference.md#模型設定與自動選模)。
+#### 模型驗證
+
+Claude Code、Codex 與 Gemini CLI 都使用專用探測流程：以 `--model` 指定模型，在獨立暫存目錄要求「只回答 OK」，不沿用正常工作時的 `extraArgs`。
+
+| CLI | 探測時的工具限制 |
+|---|---|
+| Claude Code | `--tools ""` 停用內建工具，`--strict-mcp-config` 不載入外部 MCP，`--disable-slash-commands` 停用 slash commands |
+| Codex | 唯讀沙箱與 `approval_policy="never"` 禁止寫入及權限升級；停用 shell、外部工具與 hooks，忽略使用者設定及 rules。仍可能有模型內建檔案工具，由唯讀沙箱限制 |
+| Gemini CLI | admin/user policy 禁止所有工具（合法優先級 `999`），停用 extensions、MCP 與 hooks；政策載入問題使驗證失敗 |
+
+三家共用相同的通過條件：CLI 結束碼為 0、有非空文字與成功完成事件，且沒有工具嘗試或失敗事件。即使後來回覆成功，先前的失敗也不會被忽略。
+
+探測上限為 30 秒，結束後清除暫存目錄；macOS／Linux 逾時或按 Ctrl-C 中斷時會停止整個程序群組，包含 CLI 啟動的子程序。`model add` 成功才新增模型，失敗保持設定原狀；`model check` 只重驗、不修改設定。CLI 不支援探測參數（版本過舊或參數已改名）時直接失敗並提示更新 CLI，不會改用更寬鬆的權限重試。
+
+Codex 另有幾點差異：
+- 只寫在 stderr 的工具拒絕（例如唯讀沙箱擋下 patch）同樣算失敗。
+- Codex 的 `error` item 是非致命通知，例如找不到模型 metadata 改用預設值、設定警告、棄用提示，不影響探測與 run 結果；`logs` 以 ⚠️ 顯示，不列入錯誤段落。真正的失敗是 `turn.failed` 與頂層 `error` 事件。
+- Codex 只在模型被改派時回報實際模型，其餘情況只確認指定名稱可呼叫，不推測別名對應。
+- `logs` 會顯示 Codex 每回合的完成事件，跨回合的 shell 指令分開整理。
+
+自訂 `command` adapter 另需提供會實際呼叫模型的探測命令；設定方式與各 CLI 已查核版本見[詳細參考](docs/reference.md#模型設定與自動選模)。
 
 ### 專案設定
 

package/dist/agents/codex.js

@@ -1,4 +1,49 @@
 import { num, str, tryJson } from "./types.js";
+/** 不是工具呼叫的 item；其餘 item（shell、MCP、搜尋、todo……）都當成工具 */
+const NON_TOOL_ITEMS = new Set(["agent_message", "reasoning", "error"]);
+function parse(line) {
+    const ev = tryJson(line);
+    if (!ev)
+        return [];
+    const out = [];
+    if (ev.type === "item.completed") {
+        const item = (ev.item ?? {});
+        if (item.type === "agent_message" && str(item.text)?.trim())
+            out.push({ kind: "text", text: str(item.text) });
+        else if (item.type === "command_execution")
+            out.push({ kind: "tool", name: "shell", detail: str(item.command) });
+        else if (item.type === "file_change") {
+            const changes = Array.isArray(item.changes) ? item.changes : [];
+            const paths = changes.map((c) => str(c.path)).filter(Boolean);
+            out.push({ kind: "tool", name: "edit", detail: paths.length ? paths.join(", ") : undefined });
+        }
+        else if (item.type === "error") {
+            // error item 是非致命通知（設定警告、棄用提示、模型改派）；真正的失敗走 turn.failed 或頂層 error
+            const message = str(item.message) ?? "Codex 回報錯誤";
+            const rerouted = /^model rerouted: \S+ -> (\S+)/.exec(message)?.[1];
+            if (rerouted)
+                out.push({ kind: "model", id: rerouted });
+            out.push({ kind: "warning", message });
+        }
+        else if (typeof item.type === "string" && !NON_TOOL_ITEMS.has(item.type)) {
+            out.push({ kind: "tool", name: item.type, detail: str(item.tool) ?? str(item.query) });
+        }
+    }
+    else if (ev.type === "turn.completed") {
+        const usage = (ev.usage ?? {});
+        if (num(usage.input_tokens) !== undefined || num(usage.output_tokens) !== undefined) {
+            const cacheRead = num(usage.cached_input_tokens);
+            out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens),
+                ...(cacheRead !== undefined && { cacheReadTokens: cacheRead }) });
+        }
+        out.push({ kind: "done", ok: true });
+    }
+    else if (ev.type === "turn.failed" || ev.type === "error") {
+        const err = (ev.error ?? {});
+        out.push({ kind: "done", ok: false, summary: str(err.message) ?? str(ev.message) ?? "Codex 執行失敗" });
+    }
+    return out;
+}
 /**
  * OpenAI Codex CLI：`codex exec --json`，prompt 由 stdin 傳入（`-`）。
  * workspace-write 沙箱只允許修改工作目錄，且預設不能連網，
@@ -6,41 +51,36 @@ import { num, str, tryJson } from "./types.js";
  */
 export const codex = {
     probe: () => ({ cmd: "codex", args: ["--version"] }),
-    invoke: (o) => ({
+    // Codex 沒有 --tools 空清單；停用可執行工具，剩餘檔案工具由唯讀沙箱限制。
+    invokeModelProbe: (model, cwd) => ({
         cmd: "codex",
-        args: ["exec", "--json", "--sandbox", "workspace-write", "-C", o.cwd, ...(o.model ? ["-m", o.model] : []), ...o.extraArgs, "-"],
-        input: o.prompt,
+        args: ["exec", "--json", "--sandbox", "read-only", "--skip-git-repo-check", "--ephemeral",
+            "--ignore-user-config", "--ignore-rules", "--strict-config", "-C", cwd, "-m", model,
+            "-c", 'approval_policy="never"', "-c", 'web_search="disabled"', "-c", "mcp_servers={}",
+            "-c", "project_doc_max_bytes=0",
+            "-c", "tools.experimental_request_user_input.enabled=false", "-c", "tools.update_plan.enabled=false",
+            ...["shell_tool", "hooks", "apps", "plugins", "tool_suggest", "multi_agent", "multi_agent_v2",
+                "browser_use", "computer_use", "image_generation", "view_image", "code_mode", "code_mode_host",
+                "goals", "memories", "sleep_tool", "unbounded_connection_retries"].flatMap((feature) => ["--disable", feature]), "-"],
+        input: "只回答 OK，不要呼叫任何工具。",
     }),
-    parse(line) {
+    // 探測也拒絕尚未完成的工具；一般 log 仍在 item.completed 時顯示結果。
+    parseModelProbe(line) {
+        const out = parse(line);
         const ev = tryJson(line);
-        if (!ev)
-            return [];
-        const out = [];
-        if (ev.type === "item.completed") {
-            const item = (ev.item ?? {});
-            if (item.type === "agent_message" && str(item.text)?.trim())
-                out.push({ kind: "text", text: str(item.text) });
-            else if (item.type === "command_execution")
-                out.push({ kind: "tool", name: "shell", detail: str(item.command) });
-            else if (item.type === "file_change") {
-                const changes = Array.isArray(item.changes) ? item.changes : [];
-                const paths = changes.map((c) => str(c.path)).filter(Boolean);
-                out.push({ kind: "tool", name: "edit", detail: paths.length ? paths.join(", ") : undefined });
-            }
-        }
-        else if (ev.type === "turn.completed") {
-            const usage = (ev.usage ?? {});
-            if (num(usage.input_tokens) !== undefined || num(usage.output_tokens) !== undefined) {
-                const cacheRead = num(usage.cached_input_tokens);
-                out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens),
-                    ...(cacheRead !== undefined && { cacheReadTokens: cacheRead }) });
-            }
-        }
-        else if (ev.type === "turn.failed" || ev.type === "error") {
-            const err = (ev.error ?? {});
-            out.push({ kind: "done", ok: false, summary: str(err.message) ?? str(ev.message) ?? "Codex 執行失敗" });
+        const item = ev?.item;
+        if (ev?.type === "item.started" && typeof item?.type === "string" && !NON_TOOL_ITEMS.has(item.type)) {
+            out.push({ kind: "tool", name: item.type });
         }
         return out;
     },
+    // 拒絕 apply_patch 時可能只寫 stderr，沒有 file_change 事件。
+    modelProbeFailure: (stderr) => /patch rejected|tools::router.*error=/i.test(stderr) ? `模型檢查期間嘗試呼叫工具：${stderr.trim()}` : undefined,
+    invoke: (o) => ({
+        cmd: "codex",
+        args: ["exec", "--json", "--sandbox", "workspace-write", "-C", o.cwd, ...(o.model ? ["-m", o.model] : []), ...o.extraArgs, "-"],
+        input: o.prompt,
+    }),
+    parse,
 };
 //# sourceMappingURL=codex.js.map

package/dist/agents/gemini.js

@@ -1,4 +1,4 @@
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { num, str, toolDetail, tryJson } from "./types.js";
 /**
@@ -11,11 +11,17 @@ export const gemini = {
     probe: () => ({ cmd: "gemini", args: ["--version"] }),
     invokeModelProbe: (model, cwd) => {
         const policy = join(cwd, "deny-tools.toml");
-        writeFileSync(policy, '[[rule]]\ntoolName = "*"\ndecision = "deny"\npriority = 10000\n');
+        mkdirSync(join(cwd, ".gemini"), { recursive: true });
+        writeFileSync(join(cwd, ".gemini", "settings.json"), JSON.stringify({ hooksConfig: { enabled: false } }));
+        // priority 是 tier 內的 0–999；不能用 10000 嘗試跨 tier。
+        writeFileSync(policy, '[[rule]]\ntoolName = "*"\ndecision = "deny"\npriority = 999\n');
         return { cmd: "gemini", args: ["-p", "只回答 OK", "--model", model, "--output-format", "stream-json",
-                "--approval-mode", "default", "--extensions", "none", "--policy", policy],
+                "--approval-mode", "default", "--extensions", "none", "--allowed-mcp-server-names", "",
+                "--admin-policy", policy, "--policy", policy],
             env: { GEMINI_CLI_TRUST_WORKSPACE: "true" } };
     },
+    modelProbeFailure: (stderr) => /ignoring --admin-policy|policy file (error|warning)|error loading policy|invalid policy|failed to load.*polic/i.test(stderr)
+        ? `CLI 未完整載入模型探測的工具限制：${stderr.trim()}` : undefined,
     invoke: (o) => ({
         cmd: "gemini",
         args: ["-p", o.prompt, "--output-format", "stream-json", "--approval-mode", "yolo", ...(o.model ? ["-m", o.model] : []), ...o.extraArgs],
@@ -41,7 +47,8 @@ export const gemini = {
             const outputTokens = num(stats.output_tokens) ?? num(stats.outputTokens);
             if (inputTokens !== undefined || outputTokens !== undefined)
                 out.push({ kind: "usage", inputTokens, outputTokens });
-            out.push({ kind: "done", ok: ev.status !== "error", summary: str(ev.response) });
+            const error = (ev.error ?? {});
+            out.push({ kind: "done", ok: ev.status !== "error", summary: str(error.message) ?? str(ev.response) });
         }
         else if (ev.type === "error") {
             out.push({ kind: "done", ok: false, summary: str(ev.message) ?? "Gemini 執行失敗" });

package/dist/logs.js

@@ -120,6 +120,8 @@ function renderEvent(ev, full, lastText) {
         }
         case "usage":
             return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens${ev.cacheReadTokens !== undefined || ev.cacheWriteTokens !== undefined ? `（input 含 cache 讀 ${ev.cacheReadTokens ?? 0}、寫 ${ev.cacheWriteTokens ?? 0}）` : ""}`;
+        case "warning":
+            return `⚠️  ${indent(ev.message.trim())}`;
         case "done": {
             const summary = ev.summary?.trim();
             // 最後一則回覆通常就是 summary，精簡模式不再重印一次

package/dist/modelProbe.js

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { ADAPTERS } from "./agents/index.js";
 import { exec } from "./proc.js";
 export function probeFailureReason(message) {
+    if (/unknown (option|argument|feature)|unexpected argument|unrecognized (option|argument)/i.test(message))
+        return `CLI 不支援模型探測參數（版本過舊或參數已改名），請更新 CLI 或回報：${message}`;
     if (/\b429\b|quota|rate.?limit|usage limit/i.test(message))
         return `額度或速率限制：${message}`;
     if (/invalid model|model.*(not found|unknown|unavailable)|unknown model/i.test(message))
@@ -14,7 +16,7 @@ export function probeFailureReason(message) {
         return `網路連線失敗：${message}`;
     return message;
 }
-/** 在獨立暫存目錄對指定模型送出最短請求；安全能力不足時直接拒絕。 */
+/** 在獨立暫存目錄對指定模型送出最短請求；停用工具或限制成唯讀，工具事件一律不通過。 */
 export async function probeModel(def, model, timeoutMs = 30000) {
     const dir = mkdtempSync(join(tmpdir(), "agentflowctl-model-"));
     try {
@@ -33,13 +35,17 @@ export async function probeModel(def, model, timeoutMs = 30000) {
             inv = adapter.invokeModelProbe(model, dir);
         }
         const events = [];
+        const parseLine = adapter.parseModelProbe ?? adapter.parse;
         const result = await exec(inv.cmd, inv.args, {
             cwd: dir, env: inv.env, input: inv.input, timeoutMs,
             onStdoutLine: (line) => { if (def.adapter !== "command")
-                events.push(...adapter.parse(line)); },
+                events.push(...parseLine(line)); },
         });
         if (result.code !== 0)
             return { status: "failed", reason: result.code === 124 ? "模型檢查逾時" : probeFailureReason(result.stderr.trim() || result.stdout.trim() || `結束碼 ${result.code}`) };
+        const diagnostic = adapter.modelProbeFailure?.(result.stderr);
+        if (diagnostic)
+            return { status: "failed", reason: diagnostic };
         if (def.adapter === "command") {
             try {
                 const data = JSON.parse(result.stdout.trim());
@@ -54,11 +60,12 @@ export async function probeModel(def, model, timeoutMs = 30000) {
         }
         if (events.some((e) => e.kind === "tool"))
             return { status: "failed", reason: "模型檢查期間出現工具呼叫，未通過無工具驗證" };
+        const failed = events.find((e) => e.kind === "done" && !e.ok);
+        if (failed?.kind === "done")
+            return { status: "failed", reason: probeFailureReason(failed.summary ?? "CLI 回報失敗") };
         const done = events.filter((e) => e.kind === "done").at(-1);
         if (done?.kind !== "done")
             return { status: "failed", reason: "CLI 沒有回報完成" };
-        if (!done.ok)
-            return { status: "failed", reason: done.summary ?? "CLI 回報失敗" };
         if (!events.some((e) => e.kind === "text" && e.text.trim()))
             return { status: "failed", reason: "CLI 沒有回傳文字內容" };
         const resolved = events.find((e) => e.kind === "model");

package/dist/proc.js

@@ -1,13 +1,45 @@
 import { spawn } from "node:child_process";
 export function exec(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
+        const processGroup = Boolean(opts.timeoutMs) && process.platform !== "win32";
         const child = spawn(cmd, args, {
             cwd: opts.cwd,
             env: { ...process.env, ...opts.env },
             shell: opts.shell ?? false,
+            detached: processGroup,
         });
+        // npm 安裝的 CLI 常再啟動原生執行檔；只殺啟動器會留下持續呼叫模型的程序。
+        const killTree = () => {
+            if (processGroup && child.pid) {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch {
+                    child.kill("SIGKILL");
+                }
+            }
+            else
+                child.kill("SIGKILL");
+        };
+        // 獨立程序群組收不到終端機的 Ctrl-C，要自己轉達；處理完再把訊號交回原本的處理方式。
+        const onSignal = (signal) => {
+            killTree();
+            detachSignals();
+            if (!process.listenerCount(signal))
+                process.kill(process.pid, signal);
+        };
+        const detachSignals = () => {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            process.off("exit", killTree);
+        };
+        if (processGroup) {
+            process.once("SIGINT", onSignal);
+            process.once("SIGTERM", onSignal);
+            process.once("exit", killTree);
+        }
         let timedOut = false;
-        const timer = opts.timeoutMs ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, opts.timeoutMs) : undefined;
+        const timer = opts.timeoutMs ? setTimeout(() => { timedOut = true; killTree(); }, opts.timeoutMs) : undefined;
         let stdout = "";
         let stderr = "";
         let pending = "";
@@ -25,10 +57,11 @@ export function exec(cmd, args, opts = {}) {
             stderr += d.toString();
         });
         child.on("error", (error) => { if (timer)
-            clearTimeout(timer); reject(error); });
+            clearTimeout(timer); detachSignals(); reject(error); });
         child.on("close", (code) => {
             if (timer)
                 clearTimeout(timer);
+            detachSignals();
             if (opts.onStdoutLine && pending)
                 opts.onStdoutLine(pending);
             resolve({ code: timedOut ? 124 : code ?? 1, stdout, stderr: timedOut ? `${stderr}\n執行逾時` : stderr });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",