agentflowctl 0.10.0 → 0.12.0

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,9 @@ 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),
-            });
+            if (num(usage.input_tokens) !== undefined || num(usage.output_tokens) !== undefined) {
+                out.push({ kind: "usage", inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens) });
+            }
             out.push({ kind: "done", ok: ev.is_error !== true, summary: str(ev.result) });
         }
         return out;

package/dist/agents/codex.js

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

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,25 @@ 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 { 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";
+function printUsage(title, rows) {
+    if (!rows.length)
+        return;
+    console.log(`\n${title}`);
+    for (const [key, c] of rows) {
+        const value = c.reportedRuns ? `輸入 ${c.inputTokens}、輸出 ${c.outputTokens}、合計 ${c.tokens} tokens` : "未回報或回報狀態不明";
+        console.log(`  ${key}: ${value}；${c.runs} 次（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}）`);
+    }
+}
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -107,6 +119,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 +129,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 +152,7 @@ program
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
         cycle,
         attempts: {},
+        modelMode,
         taskIndex: 0,
         taskPhase: "tests",
         createdAt: now,
@@ -162,13 +181,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 +236,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（未回報 ${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 +277,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 +331,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 +341,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 +400,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();

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 });
         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) {
@@ -215,7 +225,7 @@ function announceTasks(run, ordered) {
     info(run, `📋 共 ${ordered.length} 個任務：${ordered.map((t) => t.id).join(" → ")}`);
     ordered.forEach((t, i) => {
         const a = taskAgents(run.cycle, i, cfg.tddSplit, run.id);
-        info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}`);
+        info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}　審查：${a.review}`);
     });
 }
 /** 計畫定案後：預設直接開始實作；--manual-plan 時才停下來等人 */
@@ -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")}`;
@@ -341,7 +356,8 @@ async function planFixStage(run) {
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         restorePlan(run, snap);
-        return retry(run, "plan-fix", handoffError, "plan_fix");
+        // 計畫已還原，要保留原本的審查意見，否則下一次修正不知道要改什麼
+        return retry(run, "plan-fix", `${feedback}\n\n另外，交接回覆不合格，本次修改已還原：${handoffError}`, "plan_fix");
     }
     acceptPlan(run, ordered);
     writeFileSync(flowFile(run, "feedback.md"), feedback); // 保留審查意見，讓下一輪審查者知道上次提了什麼
@@ -529,6 +545,8 @@ async function taskReviewStep(run, task, progress, taskJson, acceptanceJson) {
         prompt: (reviewer, authors) => renderPrompt("task-review", { reviewer, authors, task: taskJson, acceptance: acceptanceJson }),
         saveAs: (reviewer) => `review-${task.id}-${reviewer}.json`,
         testAuthor: run.lastTestsAuthor,
+        // 輪流交換角色：優先由排定的審查者審查，讓各家用量平均
+        prefer: taskAgents(run.cycle, run.taskIndex, loadRepoConfig().tddSplit, run.id).review,
         // 未結交接事項可能屬於後面的任務，由最後的整體審查把關
         gate: false,
         runKey: `${task.id}:review-run`,
@@ -536,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 {
@@ -646,7 +664,7 @@ async function applyFix(run, opts) {
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         await resetTo(repo, before);
-        return again(handoffError);
+        return again(`${feedback}\n\n另外，交接回覆不合格，本次修正已還原：${handoffError}`);
     }
     return { agent: actual };
 }
@@ -662,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 之後的變更；回傳第一位要求修改的審查者與所有意見，
@@ -672,7 +690,7 @@ async function fixStage(run) {
 async function codeReview(run, opts) {
     const cfg = loadRepoConfig();
     const repo = worktreeDir(run.id);
-    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, opts.seed, opts.testAuthor);
+    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, opts.seed, opts.testAuthor, opts.prefer);
     writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${opts.base}...HEAD`));
     const authors = [...new Set((await git(repo, "log", "--format=%s", `${opts.base}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
         .map((s) => s.slice(1, -1));
@@ -691,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} 核准`);
@@ -710,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, {
@@ -727,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/handoff.js

@@ -52,10 +52,9 @@ export function previewHandoff(ledger, callKey, source, response, role) {
         const issue = issues.find((item) => item.id === disposition.id);
         if (!issue)
             throw new Error(`找不到交接事項：${disposition.id}`);
-        if (issue.kind !== "action")
-            throw new Error(`參考資訊不可結案：${disposition.id}`);
-        if (issue.status === "resolved" || issue.status === "accepted")
-            throw new Error(`交接事項已結案：${disposition.id}`);
+        // 參考資訊沒有結案流程，已結案的事項也不需再處置：略過即可，不讓整個步驟因此重試
+        if (issue.kind !== "action" || issue.status === "resolved" || issue.status === "accepted")
+            continue;
         if (role === "writer" && disposition.status !== "proposed_resolved")
             throw new Error("作者只能提出已修正，不能自行結案");
         if (role === "reviewer" && disposition.status === "proposed_resolved")
@@ -74,13 +73,20 @@ export function mergeHandoff(id, callKey, source, response, role) {
 /** 只把目前步驟需要處理的事項投影給 agent。 */
 export function prepareHandoff(id, _callKey, target, blind) {
     const items = readHandoff(id).issues.filter((item) => item.targetStage === target && (item.kind === "info" || item.status === "open" || item.status === "proposed_resolved"));
-    const lines = items.map((item) => {
+    const render = (item) => {
         const source = blind ? "" : `\n來源：${item.source.stage}／${item.source.agent}`;
         const resolution = item.resolution ? `\n處理理由：${item.resolution.reason}\n處理證據：${item.resolution.evidence}` : "";
-        return `## ${item.id}：${item.summary}\n證據：${item.evidence}\n狀態：${item.status}${resolution}${source}`;
-    });
+        const status = item.kind === "action" ? `\n狀態：${item.status}` : "";
+        return `### ${item.id}：${item.summary}\n類型：${item.kind}\n證據：${item.evidence}${status}${resolution}${source}`;
+    };
+    const actions = items.filter((item) => item.kind === "action").map(render);
+    const infos = items.filter((item) => item.kind !== "action").map(render);
+    const sections = [
+        actions.length ? `## 待處理事項（action，可在 dispositions 處置）\n\n${actions.join("\n\n")}` : "",
+        infos.length ? `## 參考資訊（info，只供參考，不要放進 dispositions）\n\n${infos.join("\n\n")}` : "",
+    ].filter(Boolean);
     mkdirSync(flowDir(id), { recursive: true });
-    writeFileSync(join(flowDir(id), "handoff-context.md"), `# 待處理交接事項\n\n${lines.length ? lines.join("\n\n") : "目前沒有待處理事項。"}\n`);
+    writeFileSync(join(flowDir(id), "handoff-context.md"), `# 待處理交接事項\n\n${sections.length ? sections.join("\n\n") : "目前沒有待處理事項。"}\n`);
     rmSync(responsePath(id), { force: true });
 }
 export function validateHandoffResponse(id) {

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