agentflowctl 0.13.1 → 0.15.0

package/README.md

@@ -31,13 +31,13 @@ npx agentflowctl run --req-file ./requirement.md
 ## 執行時會發生什麼
 
 1. agent 整理需求與驗收條件，接著寫計畫，交給其他 agent 審查。
-2. 依計畫逐個任務寫出會失敗的測試，再由另一位 agent 實作到測試通過；每個任務都會經過審查與驗證。
+2. 依計畫逐個任務寫出會失敗的測試，再由另一位 agent 實作到測試通過；每個任務都會經過審查與驗證。計畫 agent 會依改動內容在任務標記 `tdd`：建置流程、設定、文件、型別、純重構這類不適合先寫失敗測試的任務，會略過紅綠燈直接實作，改由任務審查與驗證把關。專案沒有測試框架時，所有任務都略過紅綠燈，也不跑 `test` 檢查。
 3. 全部任務完成後，再執行專案檢查與整體程式碼審查。未通過的項目會交回修正。
 4. 有 `origin` 時會推送分支；若 `gh` 可用，會嘗試建立 PR。沒有 `origin` 時，完成的分支留在本機。
 
 流程預設會自動往下走。想在計畫通過審查後親自確認，可加 `--manual-plan`；確認後執行 `agentflowctl approve <id>`。
 
-agentflowctl 會依專案的 `packageManager`、lockfile 與 `package.json` scripts 選擇安裝、測試及檢查指令。第一次執行時，請留意終端機印出的偵測結果；需要調整可在 `flow.config.json` 指定 `install`、`test` 或 `checks`。
+agentflowctl 會依專案的 `packageManager`、lockfile 與 `package.json` scripts 選擇安裝、測試及檢查指令。第一次執行時，請留意終端機印出的偵測結果；需要調整可在 `flow.config.json` 指定 `install`、`test` 或 `checks`。`package.json` 的依賴或 `test` script 看不出測試框架（且沒有手動設定 `test`）時，終端機會提示「未偵測到測試框架」，並略過紅綠燈；要改回來，在 `flow.config.json` 設定 `test`。
 
 ## 查看進度
 
@@ -49,6 +49,7 @@ agentflowctl status f-xxxx         # 看進度、結果與下一步
 agentflowctl logs f-xxxx           # 列出各步驟的 log
 agentflowctl logs f-xxxx --latest  # 看最新一份 log
 agentflowctl stats f-xxxx          # 各步驟耗時、執行與失敗次數
+agentflowctl insights              # 這個專案所有 run 的結果、失敗原因、用量、步驟失敗、重試原因與改善建議
 agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 ```
 
@@ -56,7 +57,9 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 
 `stats` 依 log 的開始與結束時間統計每個步驟的執行次數、失敗次數、總耗時與最長一次，並分開列出 agent 與專案指令（install、測試、checks）各占多少時間，最耗時的步驟排在最前面。沒有結束紀錄的 log 列為未完成，不計入耗時；總經過時間包含暫停與等待核准。
 
-執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`flow/<id>` 分支會保留。
+`insights` 把所有 run 分成獨立區塊彙總：最終狀態、失敗原因（重試達上限、仲裁停止、agent 次數用完等）、用量（輸入／輸出／cache、強度占比、階段／agent，各 run 用量最高的任務）、各模型與步驟、步驟執行與失敗（與 `stats` 相同取 log 的檔頭檔尾，跨 run 不計總經過時間）、關卡重試原因。任務關卡與任務步驟不分 task id 合併計算。最後列出最多五則建議，規則由程式套門檻，不是再請 agent 分析。合計 token 不是主指標。覆蓋不足時會先警告占比可能失真。各分組是同一批呼叫的不同切片，不要跨組相加。舊 run 沒有重試或失敗原因紀錄，不會回填。單一 run 的全量明細仍用 `status <id>` 與 `stats <id>`。
+
+執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`agentflowctl clean --all` 一次清除所有 done、failed 的 run，以及沒有紀錄的 worktree（進行中、暫停、等待核准的不動）。`flow/<id>` 分支會保留。
 
 ## 執行停下來時怎麼做
 
@@ -66,8 +69,8 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 | --- | --- |
 | 按 Ctrl-C，或終端機意外關閉 | 執行 `agentflowctl resume <id>`；沒有結束紀錄的步驟會重跑 |
 | `awaiting_approval`：計畫等你確認 | 閱讀 `.agentflowctl/worktrees/<id>/.flow/plan.md`，確認後執行 `agentflowctl approve <id>` |
-| `paused`：agent 額度用完 | 等額度恢復後執行 `agentflowctl resume <id>`；審查步驟不會換 agent 代審 |
-| `paused`：仲裁沒有產生有效裁決 | 依 `status` 的原因查看 log；若有 `.flow/plan-arbiter.json`，也檢查其內容，處理後執行 `agentflowctl resume <id>` |
+| `paused`：agent 額度用完 | 等額度恢復後執行 `agentflowctl resume <id>`；審查步驟不會換 agent 代審。在仲裁途中暫停時，resume 直接回到仲裁，不重跑計畫審查；暫停期間若改了計畫檔，或在 `flow.config.json` 把 `planArbiter` 關掉，就改成重新審查 |
+| `failed`：仲裁連續沒有產生有效裁決 | 仲裁者沒寫出 `.flow/plan-arbiter.json`、格式錯誤或交接無效時不會暫停，會把原因寫進 `.flow/feedback.md` 並自動重跑仲裁（不重跑計畫審查）；無效的檔案移到 `.agentflowctl/runs/<id>/reviews/plan-arbiter-<輪>-<agent>-invalid.json`。連續達重試上限才失敗，查看 log 後執行 `agentflowctl resume <id>` 會再回到仲裁 |
 | `failed`：測試、檢查、審查或 agent 執行失敗 | 依 `status` 提示查看失敗的 log，處理原因後執行 `agentflowctl resume <id>`；失敗階段會重試 |
 | `failed`：已達 agent 執行次數上限 | 用 `agentflowctl resume <id> --max-agent-runs 100` 調高上限後接續，數字須大於已執行次數 |
 
@@ -94,6 +97,7 @@ agentflowctl resume f-xxxx
 | `run --cycle <名單>` | 指定這次參與的 agent，例如 `--cycle claude,codex`；優先於設定檔的 `cycle` |
 | `run --model-mode balanced\|adaptive` | 只覆蓋這次 run 的模型模式；`resume` 沿用建立時的模式 |
 | `run --base <分支>` | 指定起始分支；未設定時使用目前分支 |
+| `run --max-attempts <次數>` | 覆蓋這次的重試上限（至少 3；預設取 `AGENTFLOWCTL_MAX_ATTEMPTS`，未設定為 5）；失敗後可用 `resume <id> --max-attempts <次數>` 調高 |
 | `run --max-agent-runs <次數>` | 覆蓋這次的 `maxAgentRuns`；上限不夠時可用 `resume <id> --max-agent-runs <次數>` 調高 |
 | `-v` / `--verbose` | 執行時顯示 agent 文字、工具呼叫與專案指令，適用於 `run`、`resume`、`approve` |
 
@@ -102,6 +106,7 @@ agentflowctl resume f-xxxx
 ```bash
 agentflowctl run --req-file ./requirement.md --cycle claude,codex --max-agent-runs 80 --manual-plan
 agentflowctl resume f-xxxx --max-agent-runs 100
+agentflowctl resume f-xxxx --max-attempts 8
 ```
 
 ### Agent 設定
@@ -186,24 +191,29 @@ Codex 另有幾點差異：
 | `tddSplit` | `true` | 有多位 agent 時，`true` 會把同一任務的測試與實作分給不同 agent |
 | `reviewQuorum` | `1` | 任務與最終程式碼審查需要幾位不同審查者核准 |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者核准 |
-| `planArbiter` | `true` | 計畫審查僵持時是否啟用仲裁 |
+| `planArbiter` | `true` | 計畫審查僵持，或修訂一次後仍被要求修改時是否啟用仲裁 |
+| `planReviewLayers` | `{ "enabled": true, "minTasks": 7, "maxGroups": 5, "tasksPerGroup": 3 }` | 任務夠多時把計畫審查拆成索引與任務群；說明見表格下方 |
 | `tieBreak` | `"proceed"` | 兩位仲裁者意見分歧時，`"proceed"` 繼續、`"stop"` 停止 |
 | `maxAgentRuns` | `60` | 一次 run 最多執行幾次 agent；可用指令選項覆蓋 |
 | `install`、`test` | 依專案偵測 | 寫成指令字串，例如 `"install": "pnpm install"` |
 | `checks` | 依專案偵測 | 檢查清單，例如 `[{ "name": "test", "cmd": "pnpm test" }]`；提供時會取代整份預設清單 |
 | `testPattern` | 常見的 `.test.`、`.spec.` 檔名 | 辨識測試檔的正規表示式字串；非標準檔名時調整 |
 
+計畫審查會依任務規模選做法。同時符合下列條件時，每輪先做一次索引審查，再只審查有變動的任務群：任務達到 `planReviewLayers.minTasks` 個；依 description 寫的檔案路徑能分成至少兩群，而且最大一群不超過三分之二；`plan.md` 每個任務都有 `## T-<數字>` 標題。索引審查讀規格、全部任務描述、驗收條件與整體做法，人數是 `planReviewQuorum`。群數最多 `maxGroups`，也不超過任務數除以 `tasksPerGroup`；每群一位審查者，含 `high` 任務的群改由 `planReviewQuorum` 位審查。改了 `plan.md` 的整體做法時所有群都重審；某一次審查失敗時只重跑還沒完成的部分。已達門檻卻不符其他條件時，終端機會印出原因並改由審查者讀完整份規格與計畫。`"planReviewLayers": { "enabled": false }` 可以關閉，`doctor` 會顯示目前的設定。
+
+審查意見的處理寫在 `.flow/plan-replies.md`，每輪覆寫，不寫進 `plan.md` 文末。下一輪索引會看到整份回應；任務群只看到自己的 `## T-<數字>` 節。
+
 `install`、`test`、`checks` 未設定時，會依 `packageManager`、lockfile 和 `package.json` scripts 偵測。完整範例見 [examples/flow.config.json](examples/flow.config.json)。專案設定每一步都會重新讀取，但已建立 run 的參與 agent 與執行次數上限會沿用建立時的值；要調高後者請用 `resume --max-agent-runs`。
 
 ### 環境變數
 
 | 變數 | 預設 | 設定方式與用途 |
 | --- | --- | --- |
-| `AGENTFLOWCTL_MAX_ATTEMPTS` | `3` | 同一關連續失敗幾次後停止；例如 `AGENTFLOWCTL_MAX_ATTEMPTS=10 agentflowctl run --req "..."` |
+| `AGENTFLOWCTL_MAX_ATTEMPTS` | `5` | 同一關連續失敗幾次後停止，至少 3（設得更小以 3 計）；例如 `AGENTFLOWCTL_MAX_ATTEMPTS=10 agentflowctl run --req "..."` |
 | `AGENTFLOWCTL_VERBOSE` | 未開啟 | 設為 `1` 顯示詳細輸出，效果同 `-v` |
-| `AGENTFLOWCTL_MAX_TURNS` | `80` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
+| `AGENTFLOWCTL_MAX_TURNS` | `200` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
 
-環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。
+環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限（至少 3），單一 run 可用 `run`／`resume` 的 `--max-attempts` 覆蓋；計畫審查何時交付仲裁與它無關：意見沒有變化，或第 2 輪（修訂過一次）仍被要求修改時就交付，兩家 agent 時自動進入雙盲交叉仲裁，有第三方時由第三方單獨仲裁；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
 
 ## 更多文件
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
-import { config } from "./config.js";
+import { MIN_ATTEMPTS, config } from "./config.js";
 import { advance, loadRepoConfig } from "./engine.js";
 import { probeAgent, resolveAgent, runCommand } from "./runner.js";
 import { addWorktree, git } from "./git.js";
@@ -13,9 +13,11 @@ 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 { computeInsights, failureLabel, retryLabel } from "./insights.js";
+import { computeUsageInsights } from "./usageInsights.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 { agentRuns, getRun, listRetries, listRuns, listSubstitutions, listUsage, saveRun, usageByAgent, usageByModelStage, usageByStage, usageByStrength, usageByTask } from "./store.js";
+import { padDisplay, readJsonFile } from "./util.js";
 import { openActions, readHandoff } from "./handoff.js";
 import { stopReport } from "./stopReport.js";
 import { runSetup, SETUP_ADAPTERS } from "./setup.js";
@@ -33,6 +35,12 @@ function printUsage(title, rows) {
         console.log(`  ${key}: ${value}；${c.runs} 次（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}）`);
     }
 }
+function positiveInt(text, flag, min = 1) {
+    const n = Number(text);
+    if (!Number.isInteger(n) || n < min)
+        throw new Error(`${flag} 必須是不小於 ${min} 的整數：${text}`);
+    return n;
+}
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -119,6 +127,7 @@ program
     .option("--req-file <file>", "從檔案讀取需求")
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
+    .option("--max-attempts <n>", "同一關連續失敗幾次後停止（預設取 AGENTFLOWCTL_MAX_ATTEMPTS，未設定為 5）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
     .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
     .option("--model-mode <mode>", "這次 run 的模型模式：balanced 或 adaptive")
@@ -152,6 +161,7 @@ program
         stage: "spec",
         autopilot: !opts.manualPlan,
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
+        maxAttempts: opts.maxAttempts ? positiveInt(opts.maxAttempts, "--max-attempts", MIN_ATTEMPTS) : undefined,
         cycle,
         attempts: {},
         modelMode,
@@ -181,17 +191,20 @@ program
     .command("resume <id>")
     .description("從暫停、中斷或失敗的階段接續")
     .option("--max-agent-runs <n>", "調整 agent 執行次數上限")
+    .option("--max-attempts <n>", "調整同一關連續失敗的上限")
     .action(async (id, opts) => {
     let run = mustGetRun(id);
     if (run.modelMode === "adaptive")
         validateAdaptiveConfig(loadRepoConfig(), run.cycle);
     if (opts.maxAgentRuns)
         run = { ...run, maxAgentRuns: Number(opts.maxAgentRuns) };
+    if (opts.maxAttempts)
+        run = { ...run, maxAttempts: positiveInt(opts.maxAttempts, "--max-attempts", MIN_ATTEMPTS) };
     if (run.stage === "paused") {
         run = { ...run, stage: run.pausedStage ?? "spec", pausedStage: undefined, pauseReason: undefined };
     }
     if (run.stage === "failed") {
-        run = { ...run, stage: run.failedStage ?? "spec", attempts: {}, modelRetryAttempts: {}, failedStage: undefined, failureReason: undefined };
+        run = { ...run, stage: run.failedStage ?? "spec", attempts: {}, modelRetryAttempts: {}, failedStage: undefined, failureReason: undefined, failureCategory: undefined };
     }
     await drive(saveRun(run));
 });
@@ -200,7 +213,7 @@ program
     .description("標記 run 為失敗（執行中的 run 請直接在該終端機按 Ctrl-C）")
     .action((id) => {
     const run = mustGetRun(id);
-    saveRun({ ...run, stage: "failed", failedStage: run.stage, failureReason: "使用者取消" });
+    saveRun({ ...run, stage: "failed", failedStage: run.stage, failureCategory: "cancelled", failureReason: "使用者取消" });
     console.log(`已取消 ${id}`);
 });
 program
@@ -266,6 +279,13 @@ program
         for (const sub of subs)
             console.log(`  ${sub.at.slice(0, 16)}  ${sub.step.padEnd(14)} ${sub.planned} → ${sub.actual}${sub.note ? `（${sub.note}）` : ""}`);
     }
+    const retries = listRetries(id);
+    if (retries.length) {
+        console.log("\n重試紀錄");
+        for (const r of retries) {
+            console.log(`  ${r.key.padEnd(19)}  ${retryLabel(r.category)}${r.final ? "（達上限）" : `（第 ${r.attempt} 次）`}`);
+        }
+    }
     const tasks = readJsonFile(join(flowDir(id), "tasks.ordered.json"), TaskList);
     if (!tasks.ok)
         return;
@@ -502,6 +522,8 @@ async function doctor() {
     console.log(`\n單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
     console.log(`程式碼審查人數：${cfg.reviewQuorum}　計畫審查人數：${cfg.planReviewQuorum}　計畫仲裁：${cfg.planArbiter ? "開啟" : "關閉"}`);
+    const layers = cfg.planReviewLayers;
+    console.log(`計畫分層審查：${layers.enabled ? `任務達 ${layers.minTasks} 個時開啟，最多 ${layers.maxGroups} 群，每群平均至少 ${layers.tasksPerGroup} 個任務` : "關閉"}`);
 }
 program.command("doctor").description("檢查可用的 agent CLI 與目前參與的 agent").action(doctor);
 program
@@ -560,6 +582,105 @@ program
     }
     console.log(`\n次數多或失敗多的步驟可用 agentflowctl logs ${id} 找出編號查看原因；token 用量見 agentflowctl status ${id}`);
 });
+program
+    .command("insights")
+    .description("彙總這個專案所有 run 的結果、失敗原因、用量、步驟失敗與重試原因，並給出改善建議")
+    .action(() => {
+    const runs = listRuns();
+    if (!runs.length)
+        return console.log("還沒有 run");
+    const rows = runs.map((r) => ({
+        id: r.id,
+        stage: r.stage,
+        failureCategory: r.failureCategory,
+        retries: listRetries(r.id),
+        usage: listUsage(r.id),
+        substitutions: listSubstitutions(r.id).length,
+        stats: computeStats(listLogs(logDir(r.id))),
+    }));
+    const insights = computeInsights(rows);
+    const usage = computeUsageInsights(rows);
+    const o = insights.byOutcome;
+    console.log(`專案彙總（${insights.runCount} 個 run）`);
+    console.log(`  完成 ${o.done}  失敗 ${o.failed}  暫停 ${o.paused}  等待核准 ${o.awaiting_approval}  進行中 ${o.active}`);
+    if (insights.byFailure.length) {
+        console.log("\n失敗原因");
+        for (const row of insights.byFailure)
+            console.log(`  ${padDisplay(failureLabel(row.category), 20)}  ${String(row.count).padStart(4)} 個 run`);
+    }
+    const t = usage.total;
+    console.log("\n用量");
+    if (t.runs) {
+        const value = t.reportedRuns
+            ? `輸入 ${t.inputTokens}${cacheNote(t)}、輸出 ${t.outputTokens}、合計 ${t.tokens} tokens`
+            : "未回報或回報狀態不明";
+        console.log(`  ${value}；${t.runs} 次（未回報 ${t.unreportedRuns}、舊紀錄不明 ${t.legacyRuns}）`);
+    }
+    else
+        console.log("  還沒有用量紀錄");
+    const byStrength = usage.byStrength;
+    const reportedTotal = Object.values(byStrength).reduce((sum, entry) => sum + entry.tokens, 0);
+    if (Object.keys(byStrength).length) {
+        console.log("\n模型強度用量（占比只計入明確回報）");
+        for (const strength of ["low", "medium", "high", "未知"]) {
+            const entry = byStrength[strength];
+            if (!entry)
+                continue;
+            const share = reportedTotal ? `${(entry.tokens / reportedTotal * 100).toFixed(1)}%` : "無法計算";
+            console.log(`  ${strength}: ${entry.tokens} tokens，占比 ${share}，呼叫 ${entry.runs} 次（未回報 ${entry.unreportedRuns}、舊紀錄不明 ${entry.legacyRuns}）`);
+        }
+        console.log(`  高強度呼叫：${byStrength.high?.runs ?? 0} 次`);
+    }
+    const byTokens = (record, n) => Object.entries(record).sort((a, b) => b[1].tokens - a[1].tokens).slice(0, n);
+    printUsage("用量最高的階段", byTokens(usage.byStage, 8));
+    printUsage("各 agent 用量", byTokens(usage.byAgent, 8));
+    printUsage("各模型與步驟用量（任務步驟不分 task id，只加總明確回報）", byTokens(usage.byModelStage, 10));
+    const ss = usage.stepStats;
+    if (ss.steps.length) {
+        const totalMs = ss.agentMs + ss.cmdMs;
+        const share = (ms) => (totalMs ? `${(ms / totalMs * 100).toFixed(0)}%` : "-");
+        console.log("\n步驟執行與失敗（跨 run，任務步驟不分 task id，依失敗次數排序，不含總經過時間）");
+        console.log(`  agent    ${formatDuration(ss.agentMs).padStart(7)}  ${share(ss.agentMs)}`);
+        console.log(`  專案指令 ${formatDuration(ss.cmdMs).padStart(7)}  ${share(ss.cmdMs)}`);
+        if (ss.unfinished)
+            console.log(`  未完成 ${ss.unfinished} 份（沒有結束紀錄，不計入耗時）`);
+        console.log("\n  步驟                 類型   次數  失敗   總耗時     最長");
+        for (const s of ss.steps.slice(0, 10)) {
+            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)}${s.unfinished ? `  （未完成 ${s.unfinished}）` : ""}`);
+        }
+    }
+    if (!insights.byCategory.length)
+        console.log("\n還沒有重試紀錄（舊 run 不會回填）");
+    else {
+        console.log("\n重試原因");
+        for (const row of insights.byCategory) {
+            const finals = row.finals ? `，其中 ${row.finals} 次達上限` : "";
+            console.log(`  ${padDisplay(retryLabel(row.category), 20)}  ${String(row.count).padStart(4)} 次${finals}`);
+        }
+        console.log("\n最常重試的關卡（任務關卡不分 task id 合併計算）");
+        for (const row of insights.byGate.slice(0, 10)) {
+            console.log(`  ${padDisplay(row.gate, 19)}  ${String(row.count).padStart(4)} 次`);
+        }
+    }
+    console.log("\n建議");
+    if (!usage.findings.length)
+        console.log("  還沒有足夠訊號");
+    else
+        usage.findings.forEach((f, i) => {
+            console.log(`  ${i + 1}. ${f.title}`);
+            console.log(`     ${f.detail}`);
+        });
+    const usageById = new Map(usage.runs.map((r) => [r.id, r]));
+    console.log("\n各 run");
+    for (const r of insights.runs) {
+        const cat = r.topCategory ? `  最多 ${retryLabel(r.topCategory)}` : "";
+        const u = usageById.get(r.id);
+        const tokens = !u?.calls ? "" : u.reportedCalls ? `  ${String(u.tokens).padStart(9)} tokens` : `  ${" ".repeat(3)}未回報${" ".repeat(7)}`;
+        const task = u?.topTask && u.topTask.tasks >= 2 ? `  最耗任務 ${u.topTask.task}（${(u.topTask.share * 100).toFixed(0)}%）` : "";
+        console.log(`  ${r.id}  ${r.stage.padEnd(17)}  重試 ${String(r.retries).padStart(3)} 次${tokens}${task}${cat}`);
+    }
+    console.log("\n建議對應可改的 prompt、model stage 或關卡；各分組是同一批呼叫的不同切片，不要跨組相加。單一 run 用 agentflowctl status <id>、stats <id> 與 logs <id>");
+});
 program.parseAsync().catch((err) => {
     console.error(`錯誤：${err.message}`);
     process.exit(1);

package/dist/config.js

@@ -1,8 +1,10 @@
+/** 重試上限的下限：低於這個值時，修正與審查來不及往返一輪 */
+export const MIN_ATTEMPTS = 3;
 export const config = {
     /** 單一 Agent 執行最多幾輪工具迴圈，避免卡在迴圈裡 */
-    maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 80),
-    /** 同一個關卡連續失敗幾次後停止 */
-    maxAttempts: Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 3),
+    maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 200),
+    /** 同一個關卡連續失敗幾次後停止；環境變數低於 3 時以 3 計 */
+    maxAttempts: Math.max(MIN_ATTEMPTS, Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 5) || 5),
     /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；預設安靜，-v 或 AGENTFLOWCTL_VERBOSE=1 開啟 */
     verbose: process.env.AGENTFLOWCTL_VERBOSE === "1",
 };

package/dist/detect.js

@@ -24,6 +24,16 @@ const CHECK_SCRIPTS = {
     test: ["test"],
     build: ["build"],
 };
+/** 出現在依賴裡就代表專案有測試框架 */
+const TEST_FRAMEWORKS = ["vitest", "jest", "mocha", "ava", "jasmine", "tap", "uvu", "@playwright/test", "cypress"];
+function hasTestFramework(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (TEST_FRAMEWORKS.some((name) => name in deps))
+        return true;
+    const script = pkg.scripts?.test;
+    // npm init 產生的佔位 script 不算
+    return typeof script === "string" && !/no test specified/i.test(script);
+}
 function readPackageJson(root) {
     try {
         const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -56,24 +66,31 @@ export function detectProjectDefaults(root) {
         const script = CHECK_SCRIPTS[name]?.find((s) => typeof scripts[s] === "string");
         return { name, cmd: script ? `${manager} run ${script}` : withExec(cmd, manager) };
     });
-    return { manager, source, install: INSTALL[manager], test: withExec(defaults.test, manager), checks };
+    return { manager, source, install: INSTALL[manager], test: withExec(defaults.test, manager), checks, testFramework: hasTestFramework(pkg) };
 }
+/** 手動設定 test 指令就當作有測試框架 */
+export const usesTestFramework = (raw, detected) => detected.testFramework || (!!raw && typeof raw === "object" && "test" in raw);
 /** 補上原始設定裡沒寫的 install、test、checks；不是物件就原樣回傳，交給 schema 報錯 */
 export function withProjectDefaults(raw, detected) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return raw;
-    const { install, test, checks } = detected;
+    const { install, test } = detected;
+    // 沒有測試框架也沒手動設定 test 時，預設的檢查不含 test
+    const checks = usesTestFramework(raw, detected) ? detected.checks : detected.checks.filter((c) => c.name !== "test");
     return { install, test, checks, ...raw };
 }
 /** run 開始時印出的說明：只列出這次用了偵測結果的欄位 */
 export function describeDetected(raw, detected) {
     const lines = [];
+    const framework = usesTestFramework(raw, detected);
     if (!("install" in raw))
         lines.push(`   install：${detected.install}`);
-    if (!("test" in raw))
+    if (!("test" in raw) && framework)
         lines.push(`   test：${detected.test}`);
     if (!("checks" in raw))
-        lines.push(...detected.checks.map((c) => `   checks.${c.name}：${c.cmd}`));
+        lines.push(...detected.checks.filter((c) => framework || c.name !== "test").map((c) => `   checks.${c.name}：${c.cmd}`));
+    if (!framework)
+        lines.push("ℹ️  未偵測到測試框架，所有任務略過紅綠燈，也不跑 test 檢查（在 flow.config.json 設定 test 可改回來）");
     if (!lines.length)
         return [];
     const why = detected.source === "預設" ? "預設" : `依 ${detected.source}`;