agentflowctl 0.11.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>` 分支會保留。
 
 ## 執行停下來時怎麼做
@@ -87,6 +90,7 @@ agentflowctl resume f-xxxx
 | `run --req "..."` / `--req-file <檔案>` | 二選一，直接輸入需求或讀取檔案 |
 | `run --manual-plan` | 計畫通過審查後等待你確認，再用 `approve <id>` 繼續 |
 | `run --cycle <名單>` | 指定這次參與的 agent，例如 `--cycle claude,codex`；優先於設定檔的 `cycle` |
+| `run --model-mode balanced\|adaptive` | 只覆蓋這次 run 的模型模式；`resume` 沿用建立時的模式 |
 | `run --base <分支>` | 指定起始分支；未設定時使用目前分支 |
 | `run --max-agent-runs <次數>` | 覆蓋這次的 `maxAgentRuns`；上限不夠時可用 `resume <id> --max-agent-runs <次數>` 調高 |
 | `-v` / `--verbose` | 執行時顯示 agent 文字、工具呼叫與專案指令，適用於 `run`、`resume`、`approve` |
@@ -112,6 +116,28 @@ agentflowctl agent cycle claude,codex
 
 `agent add` 的 `--adapter` 可填 `claude`、`codex`、`gemini` 或 `command`。`--model` 指定個別 agent 的模型；`--extra-arg=--參數` 可重複使用，傳給該 CLI。使用 `command` adapter 時，把指令寫在 `--` 後，例如 `agentflowctl agent add aider --adapter command -- aider --message {prompt}`。`agent remove <名稱>` 會移除設定與參與名單；`agent cycle` 不帶名單則顯示目前參與者。
 
+`model add/set/remove` 只修改指定 agent 的模型清單；`model remove` 移除最後一個模型時，會檢查參與的 agent 是否仍有模型，不論目前使用哪種模型模式。同一 adapter 的 `agent set` 會保留清單；換 adapter 時會清掉舊 adapter 的模型設定。`agent setup` 遇到同名 agent 會先詢問是否覆寫。
+
+### 依階段與任務難度選模型
+
+預設是 `balanced`：沿用每個 agent 的 `model`、`defaultModels` 或 CLI 預設。想啟用自動選模，先為**每個參與的 agent** 登記可用模型與強度，再切換模式：
+
+```bash
+agentflowctl model add claude MODEL_NAME --strength low
+agentflowctl model add claude ANOTHER_MODEL --strength high
+agentflowctl model list
+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` 可暫時回到原設定。
+
+`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#模型設定與自動選模)。
+
 ### 專案設定
 
 你也可以直接編輯 `flow.config.json`。這是可用的最小範例；沒有寫的欄位會使用預設值：
@@ -132,6 +158,8 @@ agentflowctl agent cycle claude,codex
 | `agents` | `{}` | 以名稱為 key 定義 agent；每個都要有 `adapter`，可加 `model`、`extraArgs`；`command` adapter 另需 `command` 指令陣列 |
 | `cycle` | 自動偵測 | 填 agent 名稱陣列，例如 `["claude", "codex"]`；未填時使用已設定且可執行的 agent；順序不決定角色 |
 | `defaultModels` | `{}` | 依 adapter 設預設模型，例如 `{ "claude": "模型名稱" }`；個別 agent 的 `model` 優先 |
+| `modelSelection` | `balanced` | `mode` 可為 `balanced` 或 `adaptive`；`stageStrength` 可覆蓋各 LLM 階段強度 |
+| `agents.<名稱>.models` | 無 | 自動選模時使用；每筆有 `name` 與 `strength`，建議用 `model add` 設定並實際驗證 |
 | `fixStrategy` | `"ring"` | `"ring"` 由審查者以外的 agent 修正；`"author"` 交回最後作者 |
 | `tddSplit` | `true` | 有多位 agent 時，`true` 會把同一任務的測試與實作分給不同 agent |
 | `reviewQuorum` | `1` | 任務與最終程式碼審查需要幾位不同審查者核准 |
@@ -153,7 +181,7 @@ agentflowctl agent cycle claude,codex
 | `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/agentConfig.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { z } from "zod";
 import { AgentDef, RepoConfig } from "./schemas.js";
 /** 這些欄位的意義取決於 adapter，換 adapter 時要清掉 */
-const ADAPTER_FIELDS = ["model", "extraArgs", "command"];
+const ADAPTER_FIELDS = ["model", "models", "modelProbe", "extraArgs", "command"];
 const agentsOf = (cfg) => ({ ...(cfg.agents ?? {}) });
 const isDefined = (cfg, name) => name in agentsOf(cfg);
 /** 只留下有值的欄位，驗證後回傳 */
@@ -33,13 +33,14 @@ export function setAgent(cfg, name, patch) {
     if (!isDefined(cfg, name))
         throw new Error(`未定義的 agent：${name}`);
     if (Object.values(patch).every((v) => v === undefined)) {
-        throw new Error("沒有要修改的欄位（--adapter、--model、--extra-arg 或 -- <command>）");
+        throw new Error("沒有要修改的欄位（--adapter、--model、--model-probe-arg、--extra-arg 或 -- <command>）");
     }
     const agents = agentsOf(cfg);
     const base = { ...agents[name] };
     const changes = [];
     if (patch.adapter !== undefined && patch.adapter !== base.adapter) {
-        const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && patch[f] === undefined);
+        const given = patch;
+        const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && given[f] === undefined);
         for (const f of cleared)
             delete base[f];
         if (cleared.length)

package/dist/agents/claude.js

@@ -24,6 +24,11 @@ function settingsFile(o) {
 }
 export const claude = {
     probe: () => ({ cmd: "claude", args: ["--version"] }),
+    invokeModelProbe: (model) => ({
+        cmd: "claude",
+        args: ["-p", "只回答 OK", "--model", model, "--output-format", "stream-json", "--verbose",
+            "--tools", "", "--strict-mcp-config", "--disable-slash-commands"],
+    }),
     invoke: (o) => ({
         cmd: "claude",
         args: [
@@ -40,7 +45,10 @@ export const claude = {
         if (!ev)
             return [];
         const out = [];
-        if (ev.type === "assistant") {
+        if (ev.type === "system" && ev.subtype === "init" && str(ev.model)) {
+            out.push({ kind: "model", id: str(ev.model) });
+        }
+        else if (ev.type === "assistant") {
             const content = ev.message?.content ?? [];
             for (const b of content) {
                 if (b.type === "text" && str(b.text)?.trim())
@@ -51,11 +59,19 @@ export const claude = {
         }
         else if (ev.type === "result") {
             const usage = (ev.usage ?? {});
-            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) });
         }
         return out;

package/dist/agents/codex.js

@@ -30,7 +30,11 @@ export const codex = {
         }
         else if (ev.type === "turn.completed") {
             const usage = (ev.usage ?? {});
-            out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens) });
+            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 ?? {});

package/dist/agents/command.js

@@ -10,9 +10,11 @@ export const command = {
         if (!cmd)
             throw new Error("command adapter 需要設定 command 陣列");
         const hasPlaceholder = rest.some((a) => a.includes("{prompt}"));
+        if (o.command?.some((a) => a.includes("{model}")) && !o.model)
+            throw new Error("command 含 {model}，但沒有設定 model");
         return {
-            cmd,
-            args: [...rest.map((a) => a.replaceAll("{prompt}", o.prompt)), ...o.extraArgs],
+            cmd: cmd.replaceAll("{model}", o.model ?? ""),
+            args: [...rest.map((a) => a.replaceAll("{prompt}", o.prompt).replaceAll("{model}", o.model ?? "")), ...o.extraArgs],
             input: hasPlaceholder ? undefined : o.prompt,
         };
     },

package/dist/agents/gemini.js

@@ -1,3 +1,5 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { num, str, toolDetail, tryJson } from "./types.js";
 /**
  * Google Gemini CLI：`gemini -p ... --output-format stream-json`。
@@ -7,6 +9,13 @@ import { num, str, toolDetail, tryJson } from "./types.js";
  */
 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');
+        return { cmd: "gemini", args: ["-p", "只回答 OK", "--model", model, "--output-format", "stream-json",
+                "--approval-mode", "default", "--extensions", "none", "--policy", policy],
+            env: { GEMINI_CLI_TRUST_WORKSPACE: "true" } };
+    },
     invoke: (o) => ({
         cmd: "gemini",
         args: ["-p", o.prompt, "--output-format", "stream-json", "--approval-mode", "yolo", ...(o.model ? ["-m", o.model] : []), ...o.extraArgs],
@@ -17,7 +26,10 @@ export const gemini = {
         if (!ev)
             return [];
         const out = [];
-        if (ev.type === "message" && ev.role === "assistant" && str(ev.content)?.trim()) {
+        if (ev.type === "init" && str(ev.model)) {
+            out.push({ kind: "model", id: str(ev.model) });
+        }
+        else if (ev.type === "message" && ev.role === "assistant" && str(ev.content)?.trim()) {
             out.push({ kind: "text", text: str(ev.content) });
         }
         else if (ev.type === "tool_use") {
@@ -25,11 +37,10 @@ export const gemini = {
         }
         else if (ev.type === "result") {
             const stats = (ev.stats ?? {});
-            out.push({
-                kind: "usage",
-                inputTokens: num(stats.input_tokens) ?? num(stats.inputTokens),
-                outputTokens: num(stats.output_tokens) ?? num(stats.outputTokens),
-            });
+            const inputTokens = num(stats.input_tokens) ?? num(stats.inputTokens);
+            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) });
         }
         else if (ev.type === "error") {

package/dist/cli.js

@@ -12,13 +12,27 @@ import { cleanableRuns, cleanRun } from "./cleanup.js";
 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 { TaskList } from "./schemas.js";
-import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent } from "./store.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";
 import { stopReport } from "./stopReport.js";
 import { runSetup, SETUP_ADAPTERS } from "./setup.js";
 import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
+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}${cacheNote(c)}、輸出 ${c.outputTokens}、合計 ${c.tokens} tokens` : "未回報或回報狀態不明";
+        console.log(`  ${key}: ${value}；${c.runs} 次（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}）`);
+    }
+}
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -107,6 +121,7 @@ program
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
     .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
+    .option("--model-mode <mode>", "這次 run 的模型模式：balanced 或 adaptive")
     .action(async (opts) => {
     const requirement = opts.reqFile ? readFileSync(opts.reqFile, "utf8") : opts.req;
     if (!requirement?.trim())
@@ -116,12 +131,17 @@ program
     if (!base)
         throw new Error("目前不在任何分支上，請用 --base 指定基底分支");
     const cycle = await resolveCycle(opts.cycle);
+    const cfg = loadRepoConfig();
+    const modelMode = opts.modelMode ?? cfg.modelSelection.mode;
+    if (modelMode !== "balanced" && modelMode !== "adaptive")
+        throw new Error(`未知的模型模式：${modelMode}`);
+    if (modelMode === "adaptive")
+        validateAdaptiveConfig(cfg, cycle);
     const id = `f-${Date.now().toString(36)}`;
     const branch = `flow/${id}`;
     console.log(`[${id}] 🌿 從 ${base} 建立 worktree（分支 ${branch}）`);
     await addWorktree(root, worktreeDir(id), base, branch);
     console.log(`[${id}] 🤝 參與的 agent：${cycle.join("、")}（角色隨機分配）`);
-    const cfg = loadRepoConfig();
     const now = new Date().toISOString();
     // worktree 一建好就寫入紀錄：之後在任何地方中斷，都能用 resume 接續或用 clean 清掉
     const run = saveRun({
@@ -134,6 +154,7 @@ program
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
         cycle,
         attempts: {},
+        modelMode,
         taskIndex: 0,
         taskPhase: "tests",
         createdAt: now,
@@ -162,13 +183,15 @@ program
     .option("--max-agent-runs <n>", "調整 agent 執行次數上限")
     .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 (run.stage === "paused") {
         run = { ...run, stage: run.pausedStage ?? "spec", pausedStage: undefined, pauseReason: undefined };
     }
     if (run.stage === "failed") {
-        run = { ...run, stage: run.failedStage ?? "spec", attempts: {}, failedStage: undefined, failureReason: undefined };
+        run = { ...run, stage: run.failedStage ?? "spec", attempts: {}, modelRetryAttempts: {}, failedStage: undefined, failureReason: undefined };
     }
     await drive(saveRun(run));
 });
@@ -215,8 +238,27 @@ 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`);
+            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);
+    const stageOrder = [...Object.keys(DEFAULT_STAGE_STRENGTH), "其他"];
+    printUsage("各階段用量（同一步驟的所有任務合計）", Object.entries(byStage).sort(([a], [b]) => stageOrder.indexOf(a) - stageOrder.indexOf(b)));
+    const taskNo = (key) => /^T-(\d+)$/.exec(key) ? Number(key.slice(2)) : Infinity;
+    printUsage("各任務用量（寫測試、實作、任務審查、任務修正）", Object.entries(usageByTask(id)).sort(([a], [b]) => taskNo(a) - taskNo(b)));
+    printUsage("各模型與步驟用量（只加總明確回報）", Object.entries(usageByModelStage(id)));
+    const byStrength = usageByStrength(id);
+    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 subs = listSubstitutions(id);
     if (subs.length) {
@@ -237,6 +279,18 @@ program
 // ───────────── agent 管理：讀寫 flow.config.json 的 agents 與 cycle ─────────────
 const configPath = () => join(projectRoot(), "flow.config.json");
 const collect = (value, prev = []) => [...prev, value];
+const parseStrength = (value) => {
+    const result = ModelStrength.safeParse(value);
+    if (!result.success)
+        throw new Error(`未知的模型強度：${value}（請使用 low、medium 或 high）`);
+    return result.data;
+};
+const parseModelStage = (value) => {
+    const result = ModelStage.safeParse(value);
+    if (!result.success)
+        throw new Error(`未知的 LLM 階段：${value}`);
+    return result.data;
+};
 function applyEdit(edit, done) {
     const before = readRawConfig(configPath());
     const { cfg, changes } = edit(before);
@@ -279,8 +333,9 @@ agent
     .requiredOption("--adapter <adapter>", "claude、codex、gemini 或 command")
     .option("--model <model>", "模型名稱")
     .option("--extra-arg <arg>", "額外參數，可重複；以 - 開頭時寫成 --extra-arg=--sandbox", collect)
+    .option("--model-probe-arg <arg>", "自訂 command 的模型探測命令參數，可重複", collect)
     .action((name, command, opts) => {
-    applyEdit((cfg) => addAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已新增 ${name}；要讓它參與請用 agent cycle`);
+    applyEdit((cfg) => addAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, modelProbe: opts.modelProbeArg, command: command.length ? command : undefined }), `已新增 ${name}；要讓它參與請用 agent cycle`);
 });
 agent
     .command("set <name> [command...]")
@@ -288,8 +343,9 @@ agent
     .option("--adapter <adapter>", "claude、codex、gemini 或 command")
     .option("--model <model>", "模型名稱")
     .option("--extra-arg <arg>", "額外參數，可重複，會整個取代原本的設定", collect)
+    .option("--model-probe-arg <arg>", "自訂 command 的模型探測命令參數，可重複，會整個取代", collect)
     .action((name, command, opts) => {
-    applyEdit((cfg) => setAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已更新 ${name}`);
+    applyEdit((cfg) => setAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, modelProbe: opts.modelProbeArg, command: command.length ? command : undefined }), `已更新 ${name}`);
 });
 agent
     .command("remove <name>")
@@ -346,6 +402,86 @@ agent
     console.log("");
     await doctor();
 });
+// ───────────── 模型清單與各階段強度 ─────────────
+const model = program.command("model").description("設定模型強度並檢查目前帳號能否呼叫模型");
+model.command("add <agent> <name>")
+    .requiredOption("--strength <strength>", "low、medium 或 high")
+    .action(async (agent, name, opts) => {
+    const strength = parseStrength(opts.strength);
+    const before = readRawConfig(configPath());
+    const cfg = loadRepoConfig();
+    const def = cfg.agents[agent];
+    if (!def)
+        throw new Error(`未定義的 agent：${agent}`);
+    const next = addModel(before, agent, name, strength);
+    console.log("模型檢查會送出最短請求，可能耗用少量 token。");
+    const checked = await probeModel(def, name);
+    if (checked.status !== "ok")
+        throw new Error(`${agent} 的模型 ${name} 未加入：${checked.reason}`);
+    writeRawConfig(configPath(), next);
+    console.log(`✅ 已新增 ${agent} 的模型 ${name}（${strength}）${checked.resolvedModel ? ` → ${checked.resolvedModel}` : ""}${def.adapter === "command" ? "（由自訂探測命令回報）" : ""}；探測可能耗用少量 token`);
+});
+model.command("set <agent> <name>")
+    .requiredOption("--strength <strength>", "low、medium 或 high")
+    .action((agent, name, opts) => {
+    writeRawConfig(configPath(), setModelStrength(readRawConfig(configPath()), agent, name, parseStrength(opts.strength)));
+    console.log(`✅ 已將 ${agent} 的模型 ${name} 強度設為 ${opts.strength}；此指令不重驗可用性`);
+});
+model.command("remove <agent> <name>").action((agent, name) => {
+    writeRawConfig(configPath(), removeModel(readRawConfig(configPath()), agent, name));
+    console.log(`✅ 已移除 ${agent} 的模型 ${name}`);
+});
+model.command("list [agent]").action((agent) => {
+    const cfg = loadRepoConfig();
+    const names = agent ? [agent] : Object.keys(cfg.agents);
+    for (const name of names) {
+        const def = cfg.agents[name];
+        if (!def)
+            throw new Error(`未定義的 agent：${name}`);
+        console.log(`${name}（${def.adapter}）`);
+        for (const item of def.models ?? [])
+            console.log(`  ${item.name}  ${item.strength}`);
+        if (!def.models?.length)
+            console.log("  尚未設定模型");
+    }
+    console.log("清單只顯示設定內容；要確認當前帳號是否可用，請執行 model check。");
+});
+model.command("check [agent]").action(async (agent) => {
+    const cfg = loadRepoConfig();
+    const names = agent ? [agent] : Object.keys(cfg.agents);
+    console.log("模型重驗會逐一送出短請求，可能耗用少量 token。");
+    for (const name of names) {
+        const def = cfg.agents[name];
+        if (!def)
+            throw new Error(`未定義的 agent：${name}`);
+        for (const item of def.models ?? []) {
+            const checked = await probeModel(def, item.name);
+            const at = new Date().toISOString();
+            const mark = checked.status === "ok" ? "✅" : checked.status === "unverifiable" ? "⚪" : "❌";
+            const result = checked.status === "ok" ? `可呼叫${checked.resolvedModel ? ` → ${checked.resolvedModel}` : ""}${def.adapter === "command" ? "（由自訂探測命令回報）" : ""}` : checked.reason;
+            console.log(`${mark} ${at} ${name} ${item.name}: ${result}`);
+        }
+    }
+});
+model.command("mode [mode]").action((mode) => {
+    if (!mode)
+        return console.log(`模型模式：${loadRepoConfig().modelSelection.mode}`);
+    if (mode !== "balanced" && mode !== "adaptive")
+        throw new Error(`未知的模型模式：${mode}`);
+    writeRawConfig(configPath(), setModelMode(readRawConfig(configPath()), mode));
+    console.log(`✅ 模型模式已設為 ${mode}`);
+});
+model.command("stage [stage] [strength]").action((stage, strength) => {
+    if (!stage || !strength) {
+        const all = effectiveStageStrengths(loadRepoConfig());
+        const stages = stage ? [parseModelStage(stage)] : Object.keys(all);
+        for (const s of stages)
+            console.log(`${s}: ${all[s].strength}${all[s].custom ? "（自訂）" : "（預設）"}`);
+        return;
+    }
+    writeRawConfig(configPath(), setStageStrength(readRawConfig(configPath()), parseModelStage(stage), parseStrength(strength)));
+    console.log(`✅ ${stage} 的最低強度已設為 ${strength}`);
+});
 /** 檢查設定的 agent 是否已安裝，印出參與的 agent 與主要設定 */
 async function doctor() {
     const cfg = loadRepoConfig();
@@ -403,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

@@ -14,7 +14,8 @@ import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, review
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
 import { AcceptanceList, ArbiterResult, ConsistentReviewResult, RepoConfig, TaskList, } from "./schemas.js";
 import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
-import { orderTasks, taskAcceptance } from "./tasks.js";
+import { clearModelReviewFailure, clearModelReviewStage, recordModelReviewFailure, selectModel } from "./modelSelection.js";
+import { orderTasks, taskAcceptance, validateTaskComplexity } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
 const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
@@ -60,10 +61,16 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
+        const selected = selectModel(run, cfg, agent, step, /^T-\d+-/.test(step) ? loadOrderedTasks(run)[run.taskIndex]?.complexity : undefined, mode.kind === "review" ? agent : undefined);
+        info(run, `🤖 ${step}：${agent} 使用 ${selected.name ?? "CLI 預設（名稱未知）"}${selected.insufficient ? `（低於目標 ${selected.targetStrength}）` : ""}`);
         const callKey = handoffKey(run, step, mode.slot ?? 0, agent);
         prepareHandoff(run.id, callKey, handoffTarget(run), mode.blind ?? false);
-        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, step, agent), prompt);
-        addUsage(run.id, { stage: step, agent, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
+        const r = await runAgent(agent, { ...resolveAgent(cfg, agent), model: selected.name }, { ...target(run, step, agent), strength: selected.strength, targetStrength: selected.targetStrength }, prompt);
+        if (r.resolvedModel && r.resolvedModel !== selected.name)
+            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, cacheReadTokens: r.cacheReadTokens, cacheWriteTokens: r.cacheWriteTokens });
         if (!r.quotaExhausted) {
             reportMeta(run, agent, r);
             return { r, agent, step, callKey };
@@ -205,6 +212,9 @@ function validatePlan(run) {
     const tasks = readJsonFile(flowFile(run, "tasks.json"), TaskList);
     if (!tasks.ok)
         return tasks.error;
+    const complexityError = validateTaskComplexity(tasks.data, run.modelMode ?? "balanced");
+    if (complexityError)
+        return complexityError;
     return orderTasks(tasks.data, new Set(ids));
 }
 function acceptPlan(run, ordered) {
@@ -272,13 +282,14 @@ async function planReviewStage(run) {
         if (tampered.length)
             info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
         if (!r.ok)
-            return retry(run, "plan-review-run", `Agent 執行失敗：${r.summary}`, "plan_review");
+            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", `Agent 執行失敗：${r.summary}`, "plan_review");
         const review = readJsonFile(flowFile(run, "plan-review.json"), ConsistentReviewResult);
         if (!review.ok)
-            return retry(run, "plan-review-run", review.error, "plan_review");
+            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", review.error, "plan_review");
         const handoffError = finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: review.data.verdict });
         if (handoffError)
-            return retry(run, "plan-review-run", handoffError, "plan_review");
+            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", handoffError, "plan_review");
+        run = clearModelReviewFailure(run, "plan-review", reviewer);
         // 審查紀錄移到 worktree 外面：之後的仲裁者看不到是哪一家提的意見
         mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
         renameSync(flowFile(run, "plan-review.json"), join(runDir(run.id), "reviews", `plan-review-${round}-${reviewer}.json`));
@@ -294,6 +305,10 @@ async function planReviewStage(run) {
         issueLines.push(...lines);
         issues.push(opinion(reviewer, lines));
     }
+    run = clearModelReviewStage(run, "plan-review");
+    const attempts = { ...run.attempts };
+    delete attempts["plan-review-run"];
+    run = { ...run, attempts };
     if (!firstObjector)
         return planSettled(run, "plan-review");
     const report = `計畫審查要求修改：\n\n${issues.join("\n\n")}`;
@@ -539,7 +554,7 @@ async function taskReviewStep(run, task, progress, taskJson, acceptanceJson) {
     });
     if ("run" in result)
         return result.run;
-    const reviewed = succeed(run, `${task.id}:review-run`, "implement");
+    const reviewed = succeed(result.state, `${task.id}:review-run`, "implement");
     if (!result.objector)
         return { ...succeed(reviewed, key, "implement"), taskPhase: "verify" };
     return {
@@ -665,7 +680,7 @@ async function fixStage(run) {
     if ("run" in result)
         return result.run;
     // 修正者成為新的作者，下一輪審查會換成別人
-    return { ...to(run, "verify"), lastWriter: result.agent };
+    return { ...succeed(run, "fix", "verify"), lastWriter: result.agent };
 }
 /**
  * 由作者以外的審查小組審查 base 之後的變更；回傳第一位要求修改的審查者與所有意見，
@@ -694,14 +709,16 @@ async function codeReview(run, opts) {
         if (tampered.length)
             info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
         if (!r.ok)
-            return { run: retry(run, opts.runKey, `Agent 執行失敗：${r.summary}`, opts.backTo) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, `Agent 執行失敗：${r.summary}`, opts.backTo) };
         const review = readJsonFile(flowFile(run, "review.json"), ConsistentReviewResult);
         if (!review.ok)
-            return { run: retry(run, opts.runKey, review.error, opts.backTo) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, review.error, opts.backTo) };
         const gate = opts.gate ? { target: "code", verdict: review.data.verdict } : undefined;
         const handoffError = finishHandoff(run, outcome, "reviewer", gate);
         if (handoffError)
-            return { run: retry(run, opts.runKey, handoffError, opts.backTo) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, handoffError, opts.backTo) };
+        if (opts.step === "review")
+            run = clearModelReviewFailure(run, "review", reviewer);
         renameSync(flowFile(run, "review.json"), flowFile(run, opts.saveAs(reviewer)));
         if (review.data.verdict === "approve") {
             info(run, `   ✓ ${reviewer} 核准`);
@@ -713,7 +730,11 @@ async function codeReview(run, opts) {
             .filter((i) => i.status !== "met")
             .map((i) => reviewIssue(i.criterion, i.status, i.note))));
     }
-    return { objector, issues };
+    if (opts.step === "review")
+        run = clearModelReviewStage(run, "review");
+    const attempts = { ...run.attempts };
+    delete attempts[opts.runKey];
+    return { state: { ...run, attempts }, objector, issues };
 }
 async function reviewStage(run) {
     const result = await codeReview(run, {
@@ -730,9 +751,9 @@ async function reviewStage(run) {
     if ("run" in result)
         return result.run;
     if (!result.objector)
-        return succeed(run, "review", "pr");
+        return succeed(result.state, "review", "pr");
     return {
-        ...retry(run, "review", `程式碼審查要求修改：\n\n${result.issues.join("\n\n")}`, "fix"),
+        ...retry(result.state, "review", `程式碼審查要求修改：\n\n${result.issues.join("\n\n")}`, "fix"),
         fixSource: "review",
         lastReviewer: result.objector,
     };

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/modelConfig.js

@@ -0,0 +1,74 @@
+import { ModelStage, ModelStrength, RepoConfig } from "./schemas.js";
+const agentsOf = (cfg) => ({ ...(cfg.agents ?? {}) });
+const modelsOf = (agent) => [...(agent.models ?? [])];
+function withAgent(cfg, agent, edit) {
+    const agents = agentsOf(cfg);
+    if (!agents[agent])
+        throw new Error(`未定義的 agent：${agent}`);
+    agents[agent] = edit({ ...agents[agent] });
+    const next = { ...cfg, agents };
+    RepoConfig.parse(next);
+    return next;
+}
+export function addModel(cfg, agent, name, strength) {
+    ModelStrength.parse(strength);
+    if (!name.trim())
+        throw new Error("模型名稱不可為空");
+    if (name !== name.trim())
+        throw new Error("模型名稱前後不可有空白");
+    return withAgent(cfg, agent, (def) => {
+        const models = modelsOf(def);
+        if (models.some((m) => m.name === name))
+            throw new Error(`agent ${agent} 的模型名稱 ${name} 重複`);
+        return { ...def, models: [...models, { name, strength }] };
+    });
+}
+export function setModelStrength(cfg, agent, name, strength) {
+    ModelStrength.parse(strength);
+    return withAgent(cfg, agent, (def) => {
+        const models = modelsOf(def);
+        if (!models.some((m) => m.name === name))
+            throw new Error(`agent ${agent} 沒有模型 ${name}`);
+        return { ...def, models: models.map((m) => m.name === name ? { ...m, strength } : m) };
+    });
+}
+/** 有 cycle 時看 cycle，否則看全部 agent；只做設定層的保守檢查。 */
+function assertModelsPresent(cfg) {
+    const agents = agentsOf(cfg);
+    const affected = cfg.cycle ?? Object.keys(agents);
+    const missing = affected.filter((name) => !agents[name] || !modelsOf(agents[name]).length);
+    if (missing.length)
+        throw new Error(`以下 agent 缺少模型：${missing.join("、")}`);
+}
+export function removeModel(cfg, agent, name) {
+    const next = withAgent(cfg, agent, (def) => {
+        const models = modelsOf(def);
+        if (!models.some((m) => m.name === name))
+            throw new Error(`agent ${agent} 沒有模型 ${name}`);
+        return { ...def, models: models.filter((m) => m.name !== name) };
+    });
+    const lastModelRemoved = !modelsOf(agentsOf(next)[agent]).length;
+    if (lastModelRemoved || (cfg.modelSelection ?? {}).mode === "adaptive")
+        assertModelsPresent(next);
+    return next;
+}
+export function setModelMode(cfg, mode) {
+    if (mode !== "balanced" && mode !== "adaptive")
+        throw new Error(`未知的模型模式：${mode}`);
+    if (mode === "adaptive")
+        assertModelsPresent(cfg);
+    const next = { ...cfg, modelSelection: { ...(cfg.modelSelection ?? {}), mode } };
+    RepoConfig.parse(next);
+    return next;
+}
+export function setStageStrength(cfg, stage, strength) {
+    const parsed = ModelStage.safeParse(stage);
+    if (!parsed.success)
+        throw new Error(`未知的 LLM 階段：${stage}`);
+    ModelStrength.parse(strength);
+    const selection = (cfg.modelSelection ?? {});
+    const next = { ...cfg, modelSelection: { ...selection, stageStrength: { ...(selection.stageStrength ?? {}), [stage]: strength } } };
+    RepoConfig.parse(next);
+    return next;
+}
+//# sourceMappingURL=modelConfig.js.map

package/dist/modelProbe.js

@@ -0,0 +1,74 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ADAPTERS } from "./agents/index.js";
+import { exec } from "./proc.js";
+export function probeFailureReason(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))
+        return `模型名稱無效或目前不可用：${message}`;
+    if (/auth|unauthori[sz]ed|forbidden|\b401\b|\b403\b/i.test(message))
+        return `認證或權限失敗：${message}`;
+    if (/network|connect|timed? out|dns|enotfound/i.test(message))
+        return `網路連線失敗：${message}`;
+    return message;
+}
+/** 在獨立暫存目錄對指定模型送出最短請求；安全能力不足時直接拒絕。 */
+export async function probeModel(def, model, timeoutMs = 30000) {
+    const dir = mkdtempSync(join(tmpdir(), "agentflowctl-model-"));
+    try {
+        const adapter = ADAPTERS[def.adapter];
+        let inv;
+        if (def.adapter === "command") {
+            if (!def.modelProbe?.length || !def.modelProbe.some((arg) => arg.includes("{model}"))) {
+                return { status: "unverifiable", reason: "command agent 缺少含 {model} 的 modelProbe" };
+            }
+            const [cmd, ...rest] = def.modelProbe;
+            inv = { cmd: cmd.replaceAll("{model}", model), args: rest.map((arg) => arg.replaceAll("{model}", model)) };
+        }
+        else {
+            if (!adapter.invokeModelProbe)
+                return { status: "unverifiable", reason: `${def.adapter} CLI 無法安全停用工具，因此不能驗證模型` };
+            inv = adapter.invokeModelProbe(model, dir);
+        }
+        const events = [];
+        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)); },
+        });
+        if (result.code !== 0)
+            return { status: "failed", reason: result.code === 124 ? "模型檢查逾時" : probeFailureReason(result.stderr.trim() || result.stdout.trim() || `結束碼 ${result.code}`) };
+        if (def.adapter === "command") {
+            try {
+                const data = JSON.parse(result.stdout.trim());
+                if (data.requestedModel !== model || typeof data.resolvedModel !== "string" || !data.resolvedModel.trim()) {
+                    return { status: "failed", reason: "自訂探測命令回報的模型名稱不符" };
+                }
+                return { status: "ok", resolvedModel: data.resolvedModel };
+            }
+            catch {
+                return { status: "failed", reason: "自訂探測命令未輸出有效 JSON" };
+            }
+        }
+        if (events.some((e) => e.kind === "tool"))
+            return { status: "failed", reason: "模型檢查期間出現工具呼叫，未通過無工具驗證" };
+        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");
+        return { status: "ok", resolvedModel: resolved?.kind === "model" ? resolved.id : undefined };
+    }
+    catch (error) {
+        return { status: "failed", reason: error.message };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=modelProbe.js.map

package/dist/modelSelection.js

@@ -0,0 +1,107 @@
+const LEVEL = { low: 0, medium: 1, high: 2 };
+const STRENGTHS = ["low", "medium", "high"];
+export const DEFAULT_STAGE_STRENGTH = {
+    spec: "medium", plan: "high", planReview: "high", planFix: "medium", planArbiter: "high",
+    taskTests: "low", taskCode: "low", taskReview: "medium", taskFix: "low", fix: "medium", review: "high",
+};
+export function effectiveStageStrengths(cfg) {
+    const custom = cfg.modelSelection.stageStrength;
+    return Object.fromEntries(Object.keys(DEFAULT_STAGE_STRENGTH).map((stage) => [stage, { strength: custom[stage] ?? DEFAULT_STAGE_STRENGTH[stage], custom: custom[stage] !== undefined }]));
+}
+/** 小組審查失敗只影響該審查者的下一次選模。 */
+export function recordModelReviewFailure(run, step, reviewer) {
+    const key = `${step}:${reviewer}`;
+    return { ...run, modelRetryAttempts: { ...run.modelRetryAttempts, [key]: (run.modelRetryAttempts?.[key] ?? 0) + 1 } };
+}
+export function clearModelReviewFailure(run, step, reviewer) {
+    const attempts = { ...run.modelRetryAttempts };
+    delete attempts[`${step}:${reviewer}`];
+    return { ...run, modelRetryAttempts: attempts };
+}
+export function clearModelReviewStage(run, step) {
+    const attempts = Object.fromEntries(Object.entries(run.modelRetryAttempts ?? {}).filter(([key]) => !key.startsWith(`${step}:`)));
+    return { ...run, modelRetryAttempts: attempts };
+}
+/** 把步驟名稱（例如 `T-1-code`、`plan-review`）對應到階段鍵；不認得時回傳 undefined。 */
+export function stageOfStep(step) {
+    const task = /^T-\d+-(tests|code|review|fix)$/.exec(step);
+    if (task)
+        return { tests: "taskTests", code: "taskCode", review: "taskReview", fix: "taskFix" }[task[1]];
+    const stage = {
+        spec: "spec", plan: "plan", "plan-review": "planReview", "plan-fix": "planFix",
+        "plan-arbiter": "planArbiter", fix: "fix", review: "review",
+    };
+    return stage[step];
+}
+function stepStage(step) {
+    const found = stageOfStep(step);
+    if (!found)
+        throw new Error(`未知的 LLM 步驟：${step}`);
+    return found;
+}
+function escalation(run, stage, step, reviewer) {
+    const a = run.attempts;
+    if (stage === "planReview" || stage === "review")
+        return run.modelRetryAttempts?.[`${step}:${reviewer ?? ""}`] ?? 0;
+    if (stage === "planArbiter")
+        return 0;
+    if (stage === "planFix")
+        return (a["plan-fix"] ?? 0) + Math.max((a["plan-review"] ?? 0) + (a["plan-handoff"] ?? 0) - 1, 0);
+    if (stage === "taskFix") {
+        const id = step.slice(0, -4);
+        return (a[`${id}:fix`] ?? 0) + Math.max((a[`${id}:review`] ?? 0) + (a[`${id}:verify`] ?? 0) - 1, 0);
+    }
+    if (stage === "fix")
+        return (a.fix ?? 0) + Math.max((a.verify ?? 0) + (a.review ?? 0) - 1, 0);
+    if (stage === "taskTests" || stage === "taskCode" || stage === "taskReview") {
+        const id = step.slice(0, step.lastIndexOf("-"));
+        const suffix = step.slice(step.lastIndexOf("-") + 1);
+        return a[`${id}:${suffix === "review" ? "review-run" : suffix}`] ?? 0;
+    }
+    return a[step] ?? 0;
+}
+/** 每次呼叫前依目前設定與 run 狀態選擇模型；不修改任何狀態。 */
+export function selectModel(run, cfg, agent, step, complexity, reviewer) {
+    const def = cfg.agents[agent];
+    if (!def)
+        throw new Error(`未定義的 agent：${agent}`);
+    const mode = run.modelMode ?? "balanced";
+    if (mode === "balanced") {
+        const fallback = def.adapter === "command" ? undefined : cfg.defaultModels[def.adapter];
+        return { mode, name: def.model ?? fallback, insufficient: false };
+    }
+    if (!def.models?.length)
+        throw new Error(`agent ${agent} 沒有設定 models`);
+    const stage = stepStage(step);
+    const floor = effectiveStageStrengths(cfg)[stage].strength;
+    const baseline = stage.startsWith("task") ? Math.max(LEVEL[floor], LEVEL[complexity ?? "medium"]) : LEVEL[floor];
+    const targetStrength = STRENGTHS[Math.min(2, baseline + escalation(run, stage, step, reviewer))];
+    const candidates = def.models.filter((m) => LEVEL[m.strength] >= LEVEL[targetStrength]);
+    const min = Math.min(...candidates.map((m) => LEVEL[m.strength]));
+    const chosen = candidates.find((m) => LEVEL[m.strength] === min)
+        ?? def.models.reduce((best, current) => LEVEL[current.strength] > LEVEL[best.strength] ? current : best);
+    return { mode, name: chosen.name, strength: chosen.strength, targetStrength, insufficient: LEVEL[chosen.strength] < LEVEL[targetStrength] };
+}
+/** 啟用 adaptive 前檢查本次實際參與的 agent。 */
+export function validateAdaptiveConfig(cfg, cycle) {
+    for (const name of cycle) {
+        const def = cfg.agents[name];
+        if (!def)
+            throw new Error(`未定義的 agent：${name}`);
+        if (!def.models?.length)
+            throw new Error(`agent ${name} 的 models 至少要有一個模型`);
+        const names = def.models.map((m) => m.name);
+        if (new Set(names).size !== names.length)
+            throw new Error(`agent ${name} 的 models 有重複名稱`);
+        if (def.adapter === "command") {
+            if (!def.command?.some((arg) => arg.includes("{model}")))
+                throw new Error(`agent ${name} 的 command 缺少 {model}`);
+            if (!def.modelProbe?.length || !def.modelProbe.some((arg) => arg.includes("{model}")))
+                throw new Error(`agent ${name} 的 modelProbe 缺少 {model}`);
+        }
+        else if (def.extraArgs.some((arg) => arg === "--model" || arg === "-m" || arg.startsWith("--model="))) {
+            throw new Error(`agent ${name} 的 extraArgs 與 adaptive 模型參數衝突`);
+        }
+    }
+}
+//# sourceMappingURL=modelSelection.js.map

package/dist/proc.js

@@ -6,6 +6,8 @@ export function exec(cmd, args, opts = {}) {
             env: { ...process.env, ...opts.env },
             shell: opts.shell ?? false,
         });
+        let timedOut = false;
+        const timer = opts.timeoutMs ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, opts.timeoutMs) : undefined;
         let stdout = "";
         let stderr = "";
         let pending = "";
@@ -22,11 +24,14 @@ export function exec(cmd, args, opts = {}) {
         child.stderr.on("data", (d) => {
             stderr += d.toString();
         });
-        child.on("error", reject);
+        child.on("error", (error) => { if (timer)
+            clearTimeout(timer); reject(error); });
         child.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
             if (opts.onStdoutLine && pending)
                 opts.onStdoutLine(pending);
-            resolve({ code: code ?? 1, stdout, stderr });
+            resolve({ code: timedOut ? 124 : code ?? 1, stdout, stderr: timedOut ? `${stderr}\n執行逾時` : stderr });
         });
         child.stdin.on("error", () => { }); // 子程序不讀 stdin 時忽略 EPIPE
         child.stdin.end(opts.input ?? "");

package/dist/runner.js

@@ -63,11 +63,16 @@ export async function runAgent(name, def, t, prompt) {
         projectRoot: projectRoot(),
         command: def.command,
     });
-    appendLog(t.logFile, headerLine({ stage: t.stage, step: t.step, agent: name, adapter: def.adapter, startedAt: new Date().toISOString() }));
+    appendLog(t.logFile, headerLine({ stage: t.stage, step: t.step, agent: name, adapter: def.adapter, model: def.model, strength: t.strength, targetStrength: t.targetStrength, startedAt: new Date().toISOString() }));
     let done;
     let lastText = "";
     let inputTokens = 0;
     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,
         env: inv.env,
@@ -87,8 +92,21 @@ export async function runAgent(name, def, t, prompt) {
                         console.log(formatToolLine(name, ev));
                 }
                 else if (ev.kind === "usage") {
-                    inputTokens += ev.inputTokens ?? 0;
-                    outputTokens += ev.outputTokens ?? 0;
+                    if (ev.inputTokens !== undefined) {
+                        inputReported = true;
+                        inputTokens += ev.inputTokens;
+                    }
+                    if (ev.outputTokens !== undefined) {
+                        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;
                 }
                 else if (ev.kind === "done") {
                     done = { ok: ev.ok, summary: ev.summary };
@@ -105,7 +123,8 @@ export async function runAgent(name, def, t, prompt) {
     const summary = done?.summary || lastText || tail(r.stdout, 2000) || tail(r.stderr, 2000);
     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, inputTokens, outputTokens };
+    return { ok, quotaExhausted, summary, meta, usageReported: inputReported && outputReported,
+        inputTokens: inputReported ? inputTokens : undefined, outputTokens: outputReported ? outputTokens : undefined, cacheReadTokens, cacheWriteTokens, resolvedModel };
 }
 /**
  * 在 worktree 內執行專案指令（安裝、測試、建置）。

package/dist/schemas.js

@@ -71,6 +71,7 @@ export const TaskItem = z.object({
     description: z.string().min(1),
     dependsOn: z.array(z.string()).default([]),
     acceptance: z.array(z.string()).min(1, "每個任務至少要對應一條驗收條件"),
+    complexity: z.enum(["low", "medium", "high"]).optional(),
 });
 /** Agent 在 plan 階段產出的 .flow/tasks.json */
 export const TaskList = z.array(TaskItem).min(1);
@@ -97,12 +98,17 @@ export const ArbiterResult = ReviewResult.extend({
         .transform((verdict) => verdict === "reject" ? "changes_requested" : verdict),
 });
 /** 一個 agent 的定義；名稱（agents 的 key）用在 cycle 裡 */
+export const ModelStrength = z.enum(["low", "medium", "high"]);
+export const ModelStage = z.enum(["spec", "plan", "planReview", "planFix", "planArbiter", "taskTests", "taskCode", "taskReview", "taskFix", "fix", "review"]);
+export const ModelEntry = z.object({ name: z.string().trim().min(1), strength: ModelStrength });
 export const AgentDef = z.object({
     adapter: z.enum(["claude", "codex", "gemini", "command"]),
     model: z.string().optional(),
+    models: z.array(ModelEntry).optional(),
     extraArgs: z.array(z.string()).default([]),
     /** 只有 command adapter 使用，`{prompt}` 會被替換成 prompt */
     command: z.array(z.string()).optional(),
+    modelProbe: z.array(z.string()).optional(),
 });
 /** 目標專案可選的 flow.config.json，預設值對應 Vite + TypeScript + Vitest 專案 */
 export const RepoConfig = z.object({
@@ -114,6 +120,15 @@ export const RepoConfig = z.object({
         codex: z.string().trim().min(1).optional(),
         gemini: z.string().trim().min(1).optional(),
     }).default({}),
+    modelSelection: z.object({
+        mode: z.enum(["balanced", "adaptive"]).default("balanced"),
+        stageStrength: z.strictObject({
+            spec: ModelStrength.optional(), plan: ModelStrength.optional(), planReview: ModelStrength.optional(),
+            planFix: ModelStrength.optional(), planArbiter: ModelStrength.optional(), taskTests: ModelStrength.optional(),
+            taskCode: ModelStrength.optional(), taskReview: ModelStrength.optional(), taskFix: ModelStrength.optional(),
+            fix: ModelStrength.optional(), review: ModelStrength.optional(),
+        }).default({}),
+    }).default({ mode: "balanced", stageStrength: {} }),
     /** 參與的 agent（順序不影響分工）；未設定時取 agents 裡已安裝的 CLI */
     cycle: z.array(z.string()).min(1).optional(),
     /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
@@ -171,6 +186,8 @@ export const FlowRun = z.object({
     fixSource: z.enum(["verify", "review"]).optional(),
     /** 各關卡的連續失敗次數 */
     attempts: z.record(z.string(), z.number()),
+    modelMode: z.enum(["balanced", "adaptive"]).optional(),
+    modelRetryAttempts: z.record(z.string(), z.number().int().nonnegative()).optional(),
     taskIndex: z.number().int().nonnegative(),
     /** 目前任務進行到哪一步：寫測試 → 實作 → 審查 → 驗證，審查或驗證未通過時進入修正 */
     taskPhase: z.enum(["tests", "code", "review", "verify", "fix"]),

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

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { stageOfStep } from "./modelSelection.js";
 import { agentflowctlDir, runDir } from "./paths.js";
 import { FlowRun } from "./schemas.js";
 const statePath = (id) => join(runDir(id), "state.json");
@@ -34,21 +35,42 @@ export function addUsage(id, entry) {
     mkdirSync(runDir(id), { recursive: true });
     appendFileSync(usagePath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
 }
-/** 依 agent 加總 token 與執行次數，方便比較各家模型 */
-export function usageByAgent(id) {
+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);
-    const out = {};
-    if (!existsSync(p))
-        return out;
-    for (const line of readFileSync(p, "utf8").split("\n").filter(Boolean)) {
-        const e = JSON.parse(line);
-        const key = e.agent ?? "?";
-        const acc = (out[key] ??= { tokens: 0, runs: 0 });
+    return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)) : [];
+}
+function addSummary(acc, e) {
+    acc.runs += 1;
+    if (e.usageReported === true && typeof e.inputTokens === "number" && typeof e.outputTokens === "number") {
+        acc.reportedRuns += 1;
+        acc.inputTokens += e.inputTokens ?? 0;
+        acc.outputTokens += e.outputTokens ?? 0;
         acc.tokens += (e.inputTokens ?? 0) + (e.outputTokens ?? 0);
-        acc.runs += 1;
+        acc.cacheReadTokens += e.cacheReadTokens ?? 0;
+        acc.cacheWriteTokens += e.cacheWriteTokens ?? 0;
     }
+    else if (e.usageReported === false || e.usageReported === true)
+        acc.unreportedRuns += 1;
+    else {
+        acc.legacyRuns += 1;
+        acc.legacyTokens += (e.inputTokens ?? 0) + (e.outputTokens ?? 0);
+    }
+}
+/** 只加總明確回報的 token，舊資料的 0 不視為已回報。 */
+function groupUsage(id, keyOf) {
+    const out = {};
+    for (const e of listUsage(id))
+        addSummary(out[keyOf(e)] ??= emptySummary(), e);
     return out;
 }
+export const usageByAgent = (id) => groupUsage(id, (e) => e.agent);
+export const usageByModelStage = (id) => groupUsage(id, (e) => `${e.model ?? "CLI 預設（名稱未知）"} / ${e.stage}`);
+export const usageByStrength = (id) => groupUsage(id, (e) => e.strength ?? "未知");
+/** 依階段鍵加總（所有任務的同一步合在一起）；認不得的步驟歸為「其他」。 */
+export const usageByStage = (id) => groupUsage(id, (e) => stageOfStep(e.stage) ?? "其他");
+/** 依任務加總寫測試、實作、任務審查與任務修正；規格、計畫與整體階段歸為「非任務步驟」。 */
+export const usageByTask = (id) => groupUsage(id, (e) => /^(T-\d+)-/.exec(e.stage)?.[1] ?? "非任務步驟");
 /** 這個 run 已執行 agent 的次數（每次執行都會記一筆用量） */
 export function agentRuns(id) {
     const p = usagePath(id);

package/dist/tasks.js

@@ -1,5 +1,12 @@
 /** 一個任務最多做兩件事：對應的驗收條件超過這個數量就要再拆 */
 export const MAX_TASK_ACCEPTANCE = 2;
+/** adaptive 的新計畫必須明確標註難度；舊 run 仍可讀取缺少欄位的 task。 */
+export function validateTaskComplexity(tasks, mode) {
+    if (mode === "balanced")
+        return undefined;
+    const missing = tasks.filter((task) => !task.complexity).map((task) => task.id);
+    return missing.length ? `任務缺少 complexity：${missing.join("、")}` : undefined;
+}
 /** 只取目前任務負責的驗收條件，避免每次實作都重讀整份清單。 */
 export function taskAcceptance(task, acceptance) {
     const byId = new Map(acceptance.map((item) => [item.id, item]));

package/package.json

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

package/prompts/plan-fix.md

@@ -32,6 +32,7 @@
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
 - 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為。修改時若任務變大，請拆開，不要合併。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
+- 修改 task 時保留或補上 `complexity`（`low`、`medium`、`high`）。依影響範圍、技術不確定性與失敗後果重新判定，取最高等級；同步更新 .flow/plan.md 中該 task 的逐項證據與最終等級。若不同意審查者建議的等級，在「## 審查回應」引用具體程式碼或測試依據。
 </output_format>
 
 <constraints>

package/prompts/plan-review.md

@@ -30,6 +30,8 @@
 1. **需求覆蓋**：規格是否完整涵蓋原始需求？有沒有遺漏、誤解，或加入需求沒要求的範圍？
 2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
 3. **任務拆解**：每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試？任務太大、一次要動很多檔案或驗證很多行為的，要求拆成更小的任務。相依順序是否合理？
+   同時依 .flow/plan.md 的逐項理由及實際程式碼，獨立核對每個 task 的 `complexity`：分別看影響範圍、技術不確定性與失敗後果，取最高等級。`low` 須是沿用既有做法、侷限單一行為或模組且失敗可由局部測試發現；`medium` 包括多模組或介面協調、非典型邊界、相容性或狀態遷移風險；`high` 包括跨系統契約、架構或資料模型變更、未知的關鍵技術路徑，或資料遺失、權限、難以回復的風險。不要只憑檔案數、程式碼行數或驗收條件數判定。
+   理由缺漏、與程式碼不符，或高低估會影響選模時，要求修正；在 `note` 指出 task ID、具體證據、建議等級及須修改的 .flow/plan.md／.flow/tasks.json 部分。不要為缺少高價值證據的細微措辭差異要求修改。
 4. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？
 
 措辭、格式這類不影響實作結果的小問題，不需要要求修改。

package/prompts/plan.md

@@ -25,7 +25,7 @@
 <steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正前次的產出。
 2. 閱讀規格與相關程式碼。
-3. 撰寫 .flow/plan.md：整體實作方式、要新增或修改的模組、任務順序的理由。
+3. 撰寫 .flow/plan.md：整體實作方式、要新增或修改的模組、任務順序的理由；逐一記錄 task 的難度判定依據。
 4. 撰寫 .flow/tasks.json。
 </steps>
 
@@ -38,6 +38,7 @@
     "id": "T-1",
     "title": "建立表單驗證 schema",
     "description": "具體要做什麼、要動哪些檔案、測試要驗證什麼行為",
+    "complexity": "low",
     "dependsOn": [],
     "acceptance": ["AC-1"]
   }
@@ -51,6 +52,11 @@
 - `title` 用一句話說出這件事；需要用「並且」「以及」串起來的，就是兩個任務。
 - `description` 寫清楚要動哪些檔案、測試要驗證哪個行為，以及這個任務不做什麼。
 - 每個任務都必須能寫出「在實作前會失敗」的測試；純設定或重構類工作請併入相關任務。
+- 每個任務先檢查預計修改的程式碼，再依「影響範圍、技術不確定性、失敗後果」三個面向判定 `complexity`，取其中最高的等級；不要只憑檔案數、程式碼行數或驗收條件數判定。
+- `low`：沿用現有做法，變更侷限在單一行為或模組，失敗容易由局部測試發現且不影響既有資料或對外契約。
+- `medium`：需要協調多個模組或既有介面、處理非典型邊界，或有相容性與狀態遷移風險，但可依已知做法實作與驗證。
+- `high`：涉及跨系統契約、架構或資料模型變更；關鍵技術路徑尚不確定；或失敗可能造成資料遺失、權限問題或難以回復的影響。任一面向符合就標 `high`。
+- 在 .flow/plan.md 逐一列出 task ID、三個面向的具體證據與最終等級；缺少證據時先查閱相關程式碼，不要一律標 `low` 或憑猜測調高。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
 </guidelines>