agentflowctl 0.12.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 審查。
 
 ## 開始使用
@@ -46,11 +48,14 @@ agentflowctl list                  # 列出 run
 agentflowctl status f-xxxx         # 看進度、結果與下一步
 agentflowctl logs f-xxxx           # 列出各步驟的 log
 agentflowctl logs f-xxxx --latest  # 看最新一份 log
+agentflowctl stats f-xxxx          # 各步驟耗時、執行與失敗次數
 agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 ```
 
 `status` 會列出目前階段、未結的交接事項與下一步指令；失敗或暫停時也會顯示原因。要看某一步的詳細輸出，可用 `logs <id> <編號>`；加 `--full` 看完整工具內容，或加 `--raw` 看原始輸出。
 
+`stats` 依 log 的開始與結束時間統計每個步驟的執行次數、失敗次數、總耗時與最長一次，並分開列出 agent 與專案指令（install、測試、checks）各占多少時間，最耗時的步驟排在最前面。沒有結束紀錄的 log 列為未完成，不計入耗時；總經過時間包含暫停與等待核准。
+
 執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`flow/<id>` 分支會保留。
 
 ## 執行停下來時怎麼做
@@ -127,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、階段、任務、模型與步驟、模型強度是同一批呼叫的不同分組，不應跨組相加。`model add/check` 的探測請求可能耗用 token，但不屬於 run，因此不在 `status` 內。
+`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/claude.js

@@ -59,8 +59,18 @@ export const claude = {
         }
         else if (ev.type === "result") {
             const usage = (ev.usage ?? {});
-            if (num(usage.input_tokens) !== undefined || num(usage.output_tokens) !== undefined) {
-                out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens) });
+            // Claude 的 input_tokens 不含 cache，要加回來才是實際送入量
+            const input = num(usage.input_tokens);
+            const cacheRead = num(usage.cache_read_input_tokens);
+            const cacheWrite = num(usage.cache_creation_input_tokens);
+            if (input !== undefined || num(usage.output_tokens) !== undefined) {
+                out.push({
+                    kind: "usage",
+                    inputTokens: input === undefined ? undefined : input + (cacheRead ?? 0) + (cacheWrite ?? 0),
+                    outputTokens: num(usage.output_tokens),
+                    ...(cacheRead !== undefined && { cacheReadTokens: cacheRead }),
+                    ...(cacheWrite !== undefined && { cacheWriteTokens: cacheWrite }),
+                });
             }
             out.push({ kind: "done", ok: ev.is_error !== true, summary: str(ev.result) });
         }

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,39 +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) {
-                out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens) });
-            }
-        }
-        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/cli.js

@@ -13,6 +13,7 @@ import { describeDetected, detectProjectDefaults } from "./detect.js";
 import { CMD_AGENT, listLogs, localTime, logMark, nextLogFile, renderLog } from "./logs.js";
 import { flowDir, logDir, projectRoot, worktreeDir } from "./paths.js";
 import { ModelStage, ModelStrength, TaskList } from "./schemas.js";
+import { computeStats, formatDuration } from "./stats.js";
 import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent, usageByModelStage, usageByStage, usageByStrength, usageByTask } from "./store.js";
 import { readJsonFile } from "./util.js";
 import { openActions, readHandoff } from "./handoff.js";
@@ -22,12 +23,13 @@ import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfi
 import { addModel, removeModel, setModelMode, setModelStrength, setStageStrength } from "./modelConfig.js";
 import { DEFAULT_STAGE_STRENGTH, effectiveStageStrengths, validateAdaptiveConfig } from "./modelSelection.js";
 import { probeModel } from "./modelProbe.js";
+const cacheNote = (c) => c.cacheReadTokens || c.cacheWriteTokens ? `（含 cache 讀 ${c.cacheReadTokens}、寫 ${c.cacheWriteTokens}）` : "";
 function printUsage(title, rows) {
     if (!rows.length)
         return;
     console.log(`\n${title}`);
     for (const [key, c] of rows) {
-        const value = c.reportedRuns ? `輸入 ${c.inputTokens}、輸出 ${c.outputTokens}、合計 ${c.tokens} tokens` : "未回報或回報狀態不明";
+        const value = c.reportedRuns ? `輸入 ${c.inputTokens}${cacheNote(c)}、輸出 ${c.outputTokens}、合計 ${c.tokens} tokens` : "未回報或回報狀態不明";
         console.log(`  ${key}: ${value}；${c.runs} 次（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}）`);
     }
 }
@@ -236,7 +238,7 @@ program
     if (Object.keys(byAgent).length) {
         console.log("\n各 agent 用量");
         for (const [agent, c] of Object.entries(byAgent)) {
-            console.log(`  ${agent.padEnd(10)} ${String(c.runs).padStart(3)} 次  ${String(c.tokens).padStart(9)} 已回報 tokens（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}${c.legacyTokens ? `，原始數字 ${c.legacyTokens} tokens` : ""}）`);
+            console.log(`  ${agent.padEnd(10)} ${String(c.runs).padStart(3)} 次  ${String(c.tokens).padStart(9)} 已回報 tokens${cacheNote(c)}（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}${c.legacyTokens ? `，原始數字 ${c.legacyTokens} tokens` : ""}）`);
         }
     }
     const byStage = usageByStage(id);
@@ -537,6 +539,27 @@ program
     const text = readFileSync(entry.file, "utf8");
     console.log(opts.raw ? text : renderLog(text, entry.file, { full: opts.full }));
 });
+program
+    .command("stats <id>")
+    .description("依步驟統計耗時、執行次數與失敗次數，找出最花時間與最常重試的地方")
+    .action((id) => {
+    mustGetRun(id);
+    const stats = computeStats(listLogs(logDir(id)));
+    if (!stats.steps.length)
+        return console.log("還沒有 log");
+    const total = stats.agentMs + stats.cmdMs;
+    const share = (ms) => (total ? `${(ms / total * 100).toFixed(0)}%` : "-");
+    console.log(`總經過時間 ${formatDuration(stats.wallMs)}（含暫停與等待核准）`);
+    console.log(`  agent    ${formatDuration(stats.agentMs).padStart(7)}  ${share(stats.agentMs)}`);
+    console.log(`  專案指令 ${formatDuration(stats.cmdMs).padStart(7)}  ${share(stats.cmdMs)}`);
+    if (stats.unfinished)
+        console.log(`  未完成 ${stats.unfinished} 份（沒有結束紀錄，不計入耗時）`);
+    console.log("\n  步驟                 類型   次數  失敗   總耗時     最長   占比");
+    for (const s of stats.steps) {
+        console.log(`  ${s.step.padEnd(19)}  ${s.kind === "cmd" ? "指令 " : "agent"}  ${String(s.runs).padStart(4)}  ${String(s.failed).padStart(4)}  ${formatDuration(s.totalMs).padStart(7)}  ${formatDuration(s.maxMs).padStart(7)}  ${share(s.totalMs).padStart(5)}${s.unfinished ? `  （未完成 ${s.unfinished}）` : ""}`);
+    }
+    console.log(`\n次數多或失敗多的步驟可用 agentflowctl logs ${id} 找出編號查看原因；token 用量見 agentflowctl status ${id}`);
+});
 program.parseAsync().catch((err) => {
     console.error(`錯誤：${err.message}`);
     process.exit(1);

package/dist/engine.js

@@ -70,7 +70,7 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `   ↳ CLI 回報實際模型：${r.resolvedModel}`);
         addUsage(run.id, { stage: step, agent, model: selected.name, resolvedModel: r.resolvedModel,
             strength: selected.strength, targetStrength: selected.targetStrength, usageReported: r.usageReported,
-            inputTokens: r.inputTokens, outputTokens: r.outputTokens });
+            inputTokens: r.inputTokens, outputTokens: r.outputTokens, cacheReadTokens: r.cacheReadTokens, cacheWriteTokens: r.cacheWriteTokens });
         if (!r.quotaExhausted) {
             reportMeta(run, agent, r);
             return { r, agent, step, callKey };

package/dist/logs.js

@@ -119,7 +119,9 @@ function renderEvent(ev, full, lastText) {
             return `🔧 ${ev.name}: ${full ? indent(detail) : compactDetail(detail)}`;
         }
         case "usage":
-            return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens`;
+            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/dist/runner.js

@@ -70,6 +70,8 @@ export async function runAgent(name, def, t, prompt) {
     let outputTokens = 0;
     let inputReported = false;
     let outputReported = false;
+    let cacheReadTokens;
+    let cacheWriteTokens;
     let resolvedModel;
     const r = await exec(inv.cmd, inv.args, {
         cwd: t.cwd,
@@ -98,6 +100,10 @@ export async function runAgent(name, def, t, prompt) {
                         outputReported = true;
                         outputTokens += ev.outputTokens;
                     }
+                    if (ev.cacheReadTokens !== undefined)
+                        cacheReadTokens = (cacheReadTokens ?? 0) + ev.cacheReadTokens;
+                    if (ev.cacheWriteTokens !== undefined)
+                        cacheWriteTokens = (cacheWriteTokens ?? 0) + ev.cacheWriteTokens;
                 }
                 else if (ev.kind === "model") {
                     resolvedModel = ev.id;
@@ -118,7 +124,7 @@ export async function runAgent(name, def, t, prompt) {
     const quotaExhausted = !ok && isQuotaError(`${summary}\n${done?.summary ?? ""}\n${r.stderr}\n${tail(r.stdout, 4000)}`);
     const meta = parseResultMeta(summary) ?? parseResultMeta(lastText);
     return { ok, quotaExhausted, summary, meta, usageReported: inputReported && outputReported,
-        inputTokens: inputReported ? inputTokens : undefined, outputTokens: outputReported ? outputTokens : undefined, resolvedModel };
+        inputTokens: inputReported ? inputTokens : undefined, outputTokens: outputReported ? outputTokens : undefined, cacheReadTokens, cacheWriteTokens, resolvedModel };
 }
 /**
  * 在 worktree 內執行專案指令（安裝、測試、建置）。

package/dist/stats.js

@@ -0,0 +1,53 @@
+import { CMD_AGENT } from "./logs.js";
+const time = (iso) => (iso ? new Date(iso).getTime() : NaN);
+/** 從 log 的檔頭與檔尾算出每個步驟的次數、失敗與耗時，不讀 log 內容 */
+export function computeStats(entries) {
+    const byKey = new Map();
+    let agentMs = 0;
+    let cmdMs = 0;
+    let unfinished = 0;
+    let first = Infinity;
+    let last = -Infinity;
+    for (const { header, footer } of entries) {
+        if (!header)
+            continue;
+        const kind = header.agent === CMD_AGENT ? "cmd" : "agent";
+        const key = `${kind}:${header.step}`;
+        const s = byKey.get(key) ?? { step: header.step, kind, runs: 0, failed: 0, unfinished: 0, totalMs: 0, maxMs: 0 };
+        byKey.set(key, s);
+        s.runs += 1;
+        const start = time(header.startedAt);
+        const end = time(footer?.endedAt);
+        if (!footer || Number.isNaN(start) || Number.isNaN(end)) {
+            s.unfinished += 1;
+            unfinished += 1;
+            continue;
+        }
+        if (!footer.ok)
+            s.failed += 1;
+        const ms = Math.max(0, end - start);
+        s.totalMs += ms;
+        s.maxMs = Math.max(s.maxMs, ms);
+        if (kind === "cmd")
+            cmdMs += ms;
+        else
+            agentMs += ms;
+        first = Math.min(first, start);
+        last = Math.max(last, end);
+    }
+    const steps = [...byKey.values()].sort((a, b) => b.totalMs - a.totalMs);
+    return { steps, agentMs, cmdMs, wallMs: last > first ? last - first : 0, unfinished };
+}
+/** 毫秒轉成 1h02m、3m05s、12s */
+export function formatDuration(ms) {
+    const sec = Math.round(ms / 1000);
+    const h = Math.floor(sec / 3600);
+    const m = Math.floor((sec % 3600) / 60);
+    const s = sec % 60;
+    if (h)
+        return `${h}h${String(m).padStart(2, "0")}m`;
+    if (m)
+        return `${m}m${String(s).padStart(2, "0")}s`;
+    return `${s}s`;
+}
+//# sourceMappingURL=stats.js.map

package/dist/store.js

@@ -35,7 +35,7 @@ export function addUsage(id, entry) {
     mkdirSync(runDir(id), { recursive: true });
     appendFileSync(usagePath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
 }
-const emptySummary = () => ({ tokens: 0, inputTokens: 0, outputTokens: 0, runs: 0, reportedRuns: 0, unreportedRuns: 0, legacyRuns: 0, legacyTokens: 0 });
+const emptySummary = () => ({ tokens: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, runs: 0, reportedRuns: 0, unreportedRuns: 0, legacyRuns: 0, legacyTokens: 0 });
 export function listUsage(id) {
     const p = usagePath(id);
     return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)) : [];
@@ -47,6 +47,8 @@ function addSummary(acc, e) {
         acc.inputTokens += e.inputTokens ?? 0;
         acc.outputTokens += e.outputTokens ?? 0;
         acc.tokens += (e.inputTokens ?? 0) + (e.outputTokens ?? 0);
+        acc.cacheReadTokens += e.cacheReadTokens ?? 0;
+        acc.cacheWriteTokens += e.cacheWriteTokens ?? 0;
     }
     else if (e.usageReported === false || e.usageReported === true)
         acc.unreportedRuns += 1;

package/package.json

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