agentflowctl 0.12.0 → 0.13.0

package/README.md

@@ -46,11 +46,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>` 分支會保留。
 
 ## 執行停下來時怎麼做
@@ -129,7 +132,7 @@ 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` 可暫時回到原設定。
 
-`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 自動評分。
 

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

@@ -31,7 +31,9 @@ export const codex = {
         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) });
+                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") {

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,7 @@ 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 "done": {
             const summary = ev.summary?.trim();
             // 最後一則回覆通常就是 summary，精簡模式不再重印一次

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.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",