agentflowctl 0.10.0 → 0.12.0

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

@@ -1,10 +1,11 @@
 /**
  * 決定每個步驟由哪個 agent 執行。
  *
- * 規則只有三條：
+ * 規則只有四條：
  * 1. 審查者不能是最後寫程式的 agent，多位審查者彼此不重複。
  * 2. 開啟 tddSplit 時，同一個任務的測試與實作由不同 agent 負責。
  * 3. 人選隨機決定，不依 cycle 的順序。cycle 只代表有哪些 agent 參與。
+ * 4. 任務的測試、實作、任務審查依同一個隨機順序輪流交換，讓各家用量平均。
  *
  * 隨機以 seed（run id 加上步驟與輪次）決定：同一個 run 的同一步驟重算時會得到同樣的人，
  * 所以 resume、或同一步驟在不同地方重算時結果一致。
@@ -48,28 +49,30 @@ export function pick(cycle, seed, exclude = []) {
 export const specAgent = (cycle, seed) => pick(cycle, `${seed}:author`);
 export const planAgent = specAgent;
 /**
- * 每 cycle.length 個任務為一輪，每輪洗一次牌，所以每家輪完一次才會再輪到；
- * 換輪時若新一輪第一位和上一輪最後一位相同，就把它往後移，避免同一家連續撰寫測試。
+ * 任務的角色輪流交換，讓各家用量平均：整個 run 用同一個洗好的順序，
+ * 第 i 個任務由 order[i] 寫測試、order[i+1] 寫實作、order[i+2] 做任務審查（都取餘數）。
+ * 三家時每三個任務各家剛好把三種角色各做一次；兩家時測試與實作每個任務互換。
  */
-function taskBag(cycle, seed, bag) {
-    const order = shuffled(cycle, `${seed}:tasks:${bag}`);
-    if (bag === 0 || order.length < 2)
-        return order;
-    const prevLast = taskBag(cycle, seed, bag - 1).at(-1);
-    return order[0] === prevLast ? [...order.slice(1), order[0]] : order;
-}
-/** 第 i 個任務的測試作者從洗好的牌依序取；實作者隨機挑一位測試作者以外的 agent */
 export function taskAgents(cycle, taskIndex, tddSplit, seed) {
-    const n = cycle.length;
-    const tests = taskBag(cycle, seed, Math.floor(taskIndex / n))[taskIndex % n];
-    return { tests, code: tddSplit ? pick(cycle, `${seed}:code:${taskIndex}`, [tests]) : tests };
+    const order = shuffled(cycle, `${seed}:tasks`);
+    const at = (offset) => order[(taskIndex + offset) % order.length];
+    const tests = at(0);
+    const code = tddSplit ? at(1) : tests;
+    // 兩家時沒有第三方，任務審查只能由實作者以外的測試作者負責
+    const review = order.length >= 3 ? at(tddSplit ? 2 : 1) : order.find((c) => c !== code) ?? code;
+    return { tests, code, review };
 }
-/** 隨機挑出 quorum 位彼此不重複、而且不是最後作者的 reviewer；任務審查優先避開測試作者 */
-export function reviewers(cycle, lastWriter, quorum, seed, testAuthor) {
+/**
+ * 隨機挑出 quorum 位彼此不重複、而且不是最後作者的 reviewer；任務審查優先避開測試作者。
+ * prefer 是輪到的審查者：只要不是最後作者就排第一位（任務修正後重審仍由同一位審查）。
+ */
+export function reviewers(cycle, lastWriter, quorum, seed, testAuthor, prefer) {
     const candidates = shuffled(cycle.filter((c) => c !== lastWriter), seed);
     const preferred = testAuthor ? candidates.filter((c) => c !== testAuthor) : candidates;
     const fallback = testAuthor ? candidates.filter((c) => c === testAuthor) : [];
-    const picked = [...preferred, ...fallback].slice(0, quorum);
+    const ranked = [...preferred, ...fallback];
+    const first = prefer && ranked.includes(prefer) ? [prefer] : [];
+    const picked = [...first, ...ranked.filter((c) => c !== prefer)].slice(0, quorum);
     return picked.length ? picked : [lastWriter ?? cycle[0]];
 }
 /**

package/dist/runner.js

@@ -63,11 +63,14 @@ 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 resolvedModel;
     const r = await exec(inv.cmd, inv.args, {
         cwd: t.cwd,
         env: inv.env,
@@ -87,8 +90,17 @@ 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;
+                    }
+                }
+                else if (ev.kind === "model") {
+                    resolvedModel = ev.id;
                 }
                 else if (ev.kind === "done") {
                     done = { ok: ev.ok, summary: ev.summary };
@@ -105,7 +117,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, 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/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,40 @@ 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, 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;
     }
+    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.10.0",
+  "version": "0.12.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",

package/prompts/fix.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <inputs>

package/prompts/implement-code.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <task>

package/prompts/implement-tests.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <task>

package/prompts/plan-arbiter.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <requirement>

package/prompts/plan-fix.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <requirement>
@@ -32,6 +32,7 @@
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
 - 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為。修改時若任務變大，請拆開，不要合併。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
+- 修改 task 時保留或補上 `complexity`（`low`、`medium`、`high`）。依影響範圍、技術不確定性與失敗後果重新判定，取最高等級；同步更新 .flow/plan.md 中該 task 的逐項證據與最終等級。若不同意審查者建議的等級，在「## 審查回應」引用具體程式碼或測試依據。
 </output_format>
 
 <constraints>

package/prompts/plan-review.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <requirement>
@@ -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

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <inputs>
@@ -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>

package/prompts/review.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <inputs>

package/prompts/spec.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <requirement>

package/prompts/task-review.md

@@ -14,7 +14,7 @@
 ```
 
 新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
-處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
 </handoff>
 
 <inputs>