agentflowctl 0.13.0 → 0.14.0

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 審查。
 
 ## 開始使用
@@ -47,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         # 從暫停、中斷或失敗處接續
 ```
 
@@ -54,6 +57,8 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 
 `stats` 依 log 的開始與結束時間統計每個步驟的執行次數、失敗次數、總耗時與最長一次，並分開列出 agent 與專案指令（install、測試、checks）各占多少時間，最耗時的步驟排在最前面。沒有結束紀錄的 log 列為未完成，不計入耗時；總經過時間包含暫停與等待核准。
 
+`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 與紀錄；`flow/<id>` 分支會保留。
 
 ## 執行停下來時怎麼做
@@ -65,7 +70,7 @@ 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`：仲裁沒有產生有效裁決 | 依 `status` 的原因查看 log；若有 `.flow/plan-arbiter.json`，也檢查其內容，處理後執行 `agentflowctl resume <id>`。resume 會直接回到仲裁，不重跑計畫審查；暫停期間若改了計畫檔，或在 `flow.config.json` 把 `planArbiter` 關掉，就改成重新審查 |
 | `failed`：測試、檢查、審查或 agent 執行失敗 | 依 `status` 提示查看失敗的 log，處理原因後執行 `agentflowctl resume <id>`；失敗階段會重試 |
 | `failed`：已達 agent 執行次數上限 | 用 `agentflowctl resume <id> --max-agent-runs 100` 調高上限後接續，數字須大於已執行次數 |
 
@@ -130,13 +135,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#模型設定與自動選模)。
 
 ### 專案設定
 
@@ -165,12 +190,17 @@ agentflowctl run --req-file ./requirement.md
 | `reviewQuorum` | `1` | 任務與最終程式碼審查需要幾位不同審查者核准 |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者核准 |
 | `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`。
 
 ### 環境變數
@@ -181,7 +211,7 @@ agentflowctl run --req-file ./requirement.md
 | `AGENTFLOWCTL_VERBOSE` | 未開啟 | 設為 `1` 顯示詳細輸出，效果同 `-v` |
 | `AGENTFLOWCTL_MAX_TURNS` | `80` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
 
-環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。
+環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
 
 ## 更多文件
 

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/cli.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";
@@ -191,7 +193,7 @@ program
         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 +202,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 +268,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 +511,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 +571,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);