agentflowctl 0.4.0 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ claude    # 完成登入
 codex     # 完成登入
 ```
 
-沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會偵測本機的 `claude`、`codex`、`gemini`，逐一詢問要不要加入、名稱與 model，再設定輪替順序；確認後才一次寫入，最後自動跑一次 `doctor`：
+沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會偵測本機的 `claude`、`codex`、`gemini`，逐一詢問要不要加入、名稱與 model，再設定參與的 agent；確認後才一次寫入，最後自動跑一次 `doctor`：
 
 ```bash
 npx agentflowctl agent setup
@@ -30,7 +30,7 @@ npx agentflowctl agent add claude --adapter claude
 npx agentflowctl agent add codex --adapter codex
 ```
 
-之後改了設定或換了環境，用 `doctor` 檢查。它會列出設定的 agent 的 CLI 是否已安裝，並印出即將使用的輪替順序。沒有設定 `cycle` 時，依 `agents` 的順序取已安裝的；一個都沒偵測到就無法執行。
+之後改了設定或換了環境，用 `doctor` 檢查。它會列出設定的 agent 的 CLI 是否已安裝，並印出即將參與的 agent。沒有設定 `cycle` 時，依 `agents` 的順序取已安裝的；一個都沒偵測到就無法執行。
 
 ```bash
 npx agentflowctl doctor
@@ -64,26 +64,28 @@ pnpm run build
 pnpm link --global
 ```
 
-## 輪替怎麼打破同溫層
+## 角色分配怎麼打破同溫層
 
 同一個模型審查自己的程式碼，容易放過自己的寫法；測試和實作出自同一個模型，也容易寫出剛好會過的測試。角色分配只有三條規則，定義在 `src/roles.ts`：
 
 | 規則 | 效果 |
 |---|---|
-| 審查者永遠不是最後寫程式的 agent | 每一輪審查都由另一家看 |
+| 審查者永遠不是最後寫程式的 agent，多位審查者彼此不重複 | 每一輪審查都由另一家看 |
 | 同一個任務的測試與實作由不同 agent 負責（`tddSplit`） | A 寫的測試，B 實作到通過，而且不能改測試 |
-| 所有角色沿著同一個輪替順序前進 | 各家輪流當作者、審查者、修正者 |
+| 人選隨機決定，不依 `cycle` 的順序 | 各家輪流當作者、審查者、修正者，不會固定由同一家起頭 |
 
-兩家時是乒乓。輪替順序 `claude → codex` 會跑成：
+`cycle` 只決定哪些 agent 參與。隨機以 run id 為種子，同一個 run 的同一步驟 `resume` 後仍是同一家。寫測試的人每 N 個任務（N 為參與的家數）洗一次牌，每家各輪一次，換輪時也不會連續兩個任務由同一家寫測試。
+
+兩家時是乒乓，例如：
 
 ```
-計畫：claude 撰寫 → codex 審查（要求修改）→ claude 修改 → codex 審查（核准）
+計畫：codex 撰寫 → claude 審查（要求修改）→ codex 修改 → claude 審查（核准）
 T-1  測試：claude   實作：codex
 T-2  測試：codex    實作：claude
 審查：codex（最後作者是 claude）→ 要求修改 → claude 修正 → codex 審查（核准）
 ```
 
-三家時，修正與審查會一直換人。例如 codex 寫、gemini 審、claude 修；仲裁交給沒寫過這份計畫、也沒審過它的那一家。
+三家時，每一輪的審查者從作者以外隨機挑，修正者從審查者以外隨機挑；仲裁交給沒寫過這份計畫、也沒審過它的那一家（有多家時隨機挑一家）。
 
 每個 commit 訊息結尾會標上實際作者，例如 `feat(T-2): 匯出 [gemini]`。
 
@@ -112,7 +114,7 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 |---|---|
 | `--req` / `--req-file` | 需求文字，或從檔案讀取 |
 | `--base` | 基底分支，預設為目前分支 |
-| `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
+| `--cycle` | 這次 run 參與的 agent，例如 `claude,codex,gemini`；順序不影響分工；建立後就固定，`resume` 沿用 |
 | `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
 | `-v` / `--verbose` | 執行時印出 agent 的文字、工具呼叫與專案指令；`run`、`resume`、`approve` 都適用，也可設 `AGENTFLOWCTL_VERBOSE=1` |
@@ -226,6 +228,7 @@ stderr：
   "fixStrategy": "ring",
   "tddSplit": true,
   "tieBreak": "proceed",
+  "defaultModels": { "claude": "Claude 模型名稱", "codex": "Codex 模型名稱", "gemini": "Gemini 模型名稱" },
   "agents": {
     "claude": { "adapter": "claude" },
     "codex": { "adapter": "codex", "model": "你要用的模型" },
@@ -236,8 +239,9 @@ stderr：
 
 | 設定 | 預設 | 說明 |
 |---|---|---|
-| `cycle` | 自動偵測 | 輪替順序。未設定時依 `agents` 的順序取已安裝的 CLI。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
-| `fixStrategy` | `ring` | `ring`：審查意見交給審查者的下一位；`author`：交回最後作者 |
+| `cycle` | 自動偵測 | 參與的 agent，順序不影響分工（人選隨機決定）。未設定時依 `agents` 的順序取已安裝的 CLI。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
+| `defaultModels` | `{}` | 依 `claude`、`codex`、`gemini` adapter 指定全域預設 model；agent 的 `model` 優先，兩者都沒設時使用各 CLI 的預設。`command` adapter 不套用 |
+| `fixStrategy` | `ring` | `ring`：審查意見隨機交給審查者以外的一家；`author`：交回最後作者 |
 | `tddSplit` | `true` | 測試與實作是否分開 |
 | `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve` |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者都 `approve` |
@@ -271,14 +275,14 @@ verify 失敗（型別、lint、建置）一律交回最後作者。審查意見
 `agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
 
 ```bash
-agentflowctl agent setup                                  # 互動設定 claude、codex、gemini 與輪替順序
-agentflowctl agent list                                   # 設定的 agent、是否已安裝、輪替位置
+agentflowctl agent setup                                  # 互動設定 claude、codex、gemini 與參與的 agent
+agentflowctl agent list                                   # 設定的 agent、是否已安裝、是否參與
 agentflowctl agent add claude-strong --adapter claude --model opus
 agentflowctl agent add aider --adapter command -- aider --yes-always --message {prompt}
 agentflowctl agent set codex --model 你要用的模型 --extra-arg=--search
 agentflowctl agent set aider --adapter gemini             # 換 adapter
 agentflowctl agent remove aider
-agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯示目前的順序
+agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯示目前參與的 agent
 ```
 
 修改會連帶更新相關設定，並在終端機列出：
@@ -286,9 +290,9 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 - `set --adapter` 換 adapter 時，會清掉舊 adapter 的 `model`、`extraArgs`、`command`，這次有重新指定的除外。
 - `remove` 會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回從 `agents` 自動偵測。
 - `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
-- `setup` 遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍放進這次的輪替順序。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
+- `setup` 遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍會參與。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
 
-已建立的 run 會沿用建立時的輪替順序，不受這些修改影響。
+已建立的 run 會沿用建立時參與的 agent，不受這些修改影響。
 
 ## 計畫怎麼在沒有人的情況下通過
 
@@ -303,27 +307,27 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 有幾家 | 誰來仲裁 | 結果 |
 | --- | --- | --- |
 | 三家以上 | 沒參與這次討論的那一家 | 核准就繼續，否則 run 失敗 |
-| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就停下；分歧依 `tieBreak` |
+| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查，仲裁達重試上限才停下；分歧依 `tieBreak` |
 | 一家 | 同一家 | 由它自己仲裁 |
 
 兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含模型名稱的爭議清單（`.flow/dispute.md`）。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
 
-裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。原始審查與仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。
+計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。仲裁最多進行 `AGENTFLOWCTL_MAX_ATTEMPTS` 次，預設三次。
 
 ## 階段與通過條件
 
 | 階段 | 負責的 agent | 程式認定通過的條件 | 失敗時 |
 |---|---|---|---|
-| spec | 輪替順序第 1 位 | 檔案存在、zod 驗證、id 不重複 | 重試 |
-| plan | 輪替順序第 1 位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
-| plan_review | 非計畫作者的下一位（可多位） | 所有審查者都 `approve` | 進入 plan_fix |
+| spec | 隨機一位 | 檔案存在、zod 驗證、id 不重複 | 重試 |
+| plan | 與 spec 同一位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
+| plan_review | 計畫作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 進入 plan_fix |
 | plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
-| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 都不核准，或 `tieBreak: stop` 時 run 失敗 |
+| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時先進入 plan_fix，達仲裁上限才失敗；第三方不核准或 `tieBreak: stop` 時失敗 |
 | 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
-| implement 紅燈 | 第 i 個任務由第 i 位 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
-| implement 綠燈 | 測試作者的下一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
+| implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
+| implement 綠燈 | 測試作者以外隨機一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
 | verify | — | `install` 與所有 `checks` 通過 | 交回作者修正 |
-| review | 非作者的下一位（可多位） | 所有審查者都 `approve` | 依 `fixStrategy` 交給下一位修正 |
+| review | 作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 依 `fixStrategy` 交給他人修正 |
 | pr | — | push 成功；有 `gh` 就開 PR | — |
 
 驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
@@ -367,7 +371,7 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 | 步驟 | 行為 |
 | --- | --- |
 | 計畫審查、程式碼審查、仲裁 | 暫停。額度恢復後 `agentflowctl resume`。換人代審會變成作者審自己 |
-| 規格、計畫、修改計畫、寫測試、寫實作、修正 | 由輪替順序上下一位還有額度的 agent 代打 |
+| 規格、計畫、修改計畫、寫測試、寫實作、修正 | 隨機由另一家還有額度的 agent 代打 |
 | 每家都用完 | 暫停 |
 
 換人或暫停前，額度用完的 agent 留下的半成品會先清掉。代打寫在 `.agentflowctl/runs/<id>/substitutions.jsonl`，`status` 會列出。commit 結尾標的是實際執行的模型。
@@ -394,7 +398,7 @@ agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell
 src/
   cli.ts            指令列（run、doctor、status……）
   engine.ts         狀態機與各階段
-  roles.ts          輪替規則（含計畫修正者與仲裁者）
+  roles.ts          角色分配規則（含計畫修正者與仲裁者）
   runner.ts         執行 agent、正規化結果、執行專案指令
   logs.ts           log 檔名、檔頭檔尾、列表與解析
   agents/           claude、codex、gemini、command

package/dist/agentConfig.js

@@ -59,21 +59,21 @@ export function removeAgent(cfg, name) {
         const rest = cycle.filter((n) => n !== name);
         if (rest.length) {
             next.cycle = rest;
-            changes.push(`已從輪替順序移除，現在是 ${rest.join(" → ")}`);
+            changes.push(`已從參與的 agent 移除，現在是 ${rest.join("、")}`);
         }
         else {
             delete next.cycle;
-            changes.push("輪替順序因此變空，已刪除 cycle，改回從 agents 自動偵測已安裝的 CLI");
+            changes.push("參與的 agent 因此變空，已刪除 cycle，改回從 agents 自動偵測已安裝的 CLI");
         }
     }
     return { cfg: next, changes };
 }
 export function setCycle(cfg, names) {
     if (!names.length)
-        throw new Error("輪替順序至少要有一個 agent");
+        throw new Error("參與的 agent 至少要有一個");
     const dup = names.find((n, i) => names.indexOf(n) !== i);
     if (dup)
-        throw new Error(`輪替順序裡 ${dup} 重複了`);
+        throw new Error(`參與的 agent 裡 ${dup} 重複了`);
     const missing = names.filter((n) => !isDefined(cfg, n));
     if (missing.length)
         throw new Error(`未定義的 agent：${missing.join("、")}（先用 agent add 新增）`);

package/dist/arbitration.js

@@ -0,0 +1,10 @@
+/** 仲裁沒有共識時，兩家先依裁決意見修訂計畫；重複仲裁仍受次數上限約束。 */
+export function arbitrationDecision(verdicts, tieBreak, round, maxAttempts) {
+    const approvals = verdicts.filter((v) => v === "approve").length;
+    if (approvals === verdicts.length)
+        return "proceed";
+    if (approvals > 0)
+        return tieBreak;
+    return verdicts.length === 2 && round < maxAttempts ? "revise" : "stop";
+}
+//# sourceMappingURL=arbitration.js.map

package/dist/cli.js

@@ -36,7 +36,7 @@ function printSummary(run) {
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
     console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次`);
-    console.log(`agent    ${run.cycle.join(" → ")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
+    console.log(`agent    ${run.cycle.join("、")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
     console.log(`分支     ${run.branch}`);
     console.log(`worktree ${worktreeDir(run.id)}`);
     if (run.prUrl)
@@ -63,7 +63,7 @@ function printSummary(run) {
     if (run.stage === "awaiting_approval")
         console.log(`\n確認計畫後執行 agentflowctl approve ${run.id}`);
 }
-/** 決定輪替順序：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
+/** 決定參與的 agent：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
 async function resolveCycle(flag) {
     const cfg = loadRepoConfig();
     const wanted = flag ? flag.split(",").map((s) => s.trim()).filter(Boolean) : cfg.cycle;
@@ -102,7 +102,7 @@ program
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
-    .option("--cycle <agents>", "agent 輪替順序，例如 claude,codex,gemini")
+    .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
     .action(async (opts) => {
     const requirement = opts.reqFile ? readFileSync(opts.reqFile, "utf8") : opts.req;
     if (!requirement?.trim())
@@ -116,7 +116,7 @@ program
     const branch = `flow/${id}`;
     console.log(`[${id}] 🌿 從 ${base} 建立 worktree（分支 ${branch}）`);
     await addWorktree(root, worktreeDir(id), base, branch);
-    console.log(`[${id}] 🤝 agent 輪替順序：${cycle.join(" → ")}`);
+    console.log(`[${id}] 🤝 參與的 agent：${cycle.join("、")}（角色隨機分配）`);
     const cfg = loadRepoConfig();
     const now = new Date().toISOString();
     // worktree 一建好就寫入紀錄：之後在任何地方中斷，都能用 resume 接續或用 clean 清掉
@@ -241,13 +241,13 @@ function applyEdit(edit, done) {
     for (const c of changes)
         console.log(`   ↳ ${c}`);
     if (JSON.stringify(before.cycle) !== JSON.stringify(cfg.cycle)) {
-        console.log("   已建立的 run 會沿用建立時的輪替順序，不受影響");
+        console.log("   已建立的 run 會沿用建立時參與的 agent，不受影響");
     }
 }
 const agent = program.command("agent").description("管理 agent 與 adapter 設定（寫入 flow.config.json）");
 agent
     .command("list")
-    .description("列出設定的 agent、是否已安裝、在輪替中的位置")
+    .description("列出設定的 agent、是否已安裝、是否參與")
     .action(async () => {
     const cfg = loadRepoConfig();
     const cycle = await resolveCycle().catch(() => cfg.cycle ?? []);
@@ -264,10 +264,10 @@ agent
             def.extraArgs.length && `extraArgs=${def.extraArgs.join(" ")}`,
             def.command && `command=${def.command.join(" ")}`,
         ].filter(Boolean);
-        console.log(`${ok ? "✅" : "❌"} ${name.padEnd(14)} ${pos >= 0 ? `輪替 #${pos + 1}` : "不在輪替"}  ${detail.join(" ")}`);
+        console.log(`${ok ? "✅" : "❌"} ${name.padEnd(14)} ${pos >= 0 ? "參與" : "不參與"}  ${detail.join(" ")}`);
     }
     console.log(`
-輪替順序：${cycle.length ? cycle.join(" → ") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
+參與的 agent：${cycle.length ? cycle.join("、") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
 });
 agent
     .command("add <name> [command...]")
@@ -276,7 +276,7 @@ agent
     .option("--model <model>", "模型名稱")
     .option("--extra-arg <arg>", "額外參數，可重複；以 - 開頭時寫成 --extra-arg=--sandbox", 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, command: command.length ? command : undefined }), `已新增 ${name}；要讓它參與請用 agent cycle`);
 });
 agent
     .command("set <name> [command...]")
@@ -289,19 +289,19 @@ agent
 });
 agent
     .command("remove <name>")
-    .description("刪除 agent，一併從輪替移除")
+    .description("刪除 agent，一併從參與的 agent 移除")
     .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已移除 ${name}`));
 agent
     .command("cycle [names]")
-    .description("顯示輪替順序，或用逗號分隔設定新的順序")
+    .description("顯示參與的 agent，或用逗號分隔設定新的名單")
     .action(async (names) => {
     if (!names) {
         const cfg = loadRepoConfig();
-        console.log(`${(await resolveCycle()).join(" → ")}${cfg.cycle ? "" : "（自動偵測）"}`);
+        console.log(`${(await resolveCycle()).join("、")}${cfg.cycle ? "" : "（自動偵測）"}`);
         return;
     }
     const list = names.split(",").map((s) => s.trim()).filter(Boolean);
-    applyEdit((cfg) => setCycle(cfg, list), `輪替順序設為 ${list.join(" → ")}`);
+    applyEdit((cfg) => setCycle(cfg, list), `參與的 agent 設為 ${list.join("、")}`);
     const cfg = loadRepoConfig();
     for (const n of list) {
         if (!(await probeAgent(resolveAgent(cfg, n))))
@@ -310,7 +310,7 @@ agent
 });
 agent
     .command("setup")
-    .description("互動式設定：偵測已安裝的 claude、codex、gemini，逐一選擇要不要加入並設定輪替順序")
+    .description("互動式設定：偵測已安裝的 claude、codex、gemini，逐一選擇要不要加入並設定參與的 agent")
     .action(async () => {
     if (!stdin.isTTY)
         throw new Error("agent setup 需要互動式終端機，請改用 agent add");
@@ -332,7 +332,7 @@ agent
     console.log("");
     await doctor();
 });
-/** 檢查設定的 agent 是否已安裝，印出輪替順序與主要設定 */
+/** 檢查設定的 agent 是否已安裝，印出參與的 agent 與主要設定 */
 async function doctor() {
     const cfg = loadRepoConfig();
     const names = Object.keys(cfg.agents);
@@ -344,7 +344,7 @@ async function doctor() {
         console.log(`${ok ? "✅" : "❌"} ${name.padEnd(10)} adapter=${def.adapter}${def.model ? ` model=${def.model}` : ""}`);
     }
     try {
-        console.log(`\n輪替順序：${(await resolveCycle()).join(" → ")}`);
+        console.log(`\n參與的 agent：${(await resolveCycle()).join("、")}`);
     }
     catch (e) {
         console.log(`\n${e.message}`);
@@ -353,7 +353,7 @@ async function doctor() {
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
     console.log(`程式碼審查人數：${cfg.reviewQuorum}　計畫審查人數：${cfg.planReviewQuorum}　計畫仲裁：${cfg.planArbiter ? "開啟" : "關閉"}`);
 }
-program.command("doctor").description("檢查可用的 agent CLI 與目前的輪替設定").action(doctor);
+program.command("doctor").description("檢查可用的 agent CLI 與目前參與的 agent").action(doctor);
 program
     .command("list")
     .description("列出這個專案的所有 run")

package/dist/config.js

@@ -1,6 +1,4 @@
 export const config = {
-    /** 指定 Claude Code 使用的模型；未設定則用 Claude Code 預設值 */
-    model: process.env.AGENTFLOWCTL_MODEL,
     /** 單一 Agent 執行最多幾輪工具迴圈，避免卡在迴圈裡 */
     maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 80),
     /** 同一個關卡連續失敗幾次後停止 */

package/dist/engine.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { join } from "node:path";
 import { z } from "zod";
 import { config } from "./config.js";
+import { arbitrationDecision } from "./arbitration.js";
 import { detectProjectDefaults, withProjectDefaults } from "./detect.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
 import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.js";
@@ -38,7 +39,7 @@ async function agentStep(run, planned, step, prompt, mode) {
             if (mode.kind === "review") {
                 throw new QuotaPause(`${agent} 的額度已用完；${step} 是審查步驟，不由另一家代打`);
             }
-            const sub = availableAgent(run.cycle, agent, [...exhausted]);
+            const sub = availableAgent(run.cycle, agent, [...exhausted], `${run.id}:${step}:sub`);
             if (!sub)
                 throw new QuotaPause(`所有 agent 的額度都已用完（${[...exhausted].join("、")}）`);
             const note = step.endsWith("-code") && sub === run.lastTestsAuthor ? "測試與實作由同一家負責" : undefined;
@@ -110,7 +111,7 @@ function loadOrderedTasks(run) {
 }
 // ───────────────────────── 各階段 ─────────────────────────
 async function specStage(run) {
-    const agent = specAgent(run.cycle);
+    const agent = specAgent(run.cycle, run.id);
     info(run, `📝 產生規格（${agent}）`);
     const { r } = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
     await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
@@ -170,7 +171,7 @@ function announceTasks(run, ordered) {
     const cfg = loadRepoConfig();
     info(run, `📋 共 ${ordered.length} 個任務：${ordered.map((t) => t.id).join(" → ")}`);
     ordered.forEach((t, i) => {
-        const a = taskAgents(run.cycle, i, cfg.tddSplit);
+        const a = taskAgents(run.cycle, i, cfg.tddSplit, run.id);
         info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}`);
     });
 }
@@ -182,10 +183,13 @@ function planSettled(run, key) {
     if (!run.autopilot) {
         info(run, `✋ 計畫已通過審查，請檢視 ${flowFile(run, "plan.md")}，確認後執行 agentflowctl approve ${run.id}`);
     }
-    return { ...succeed(run, key, next), taskIndex: 0, taskPhase: "tests" };
+    const settled = succeed(run, key, next);
+    const attempts = { ...settled.attempts };
+    delete attempts["plan-arbitration"];
+    return { ...settled, attempts, taskIndex: 0, taskPhase: "tests" };
 }
 async function planStage(run) {
-    const agent = planAgent(run.cycle);
+    const agent = planAgent(run.cycle, run.id);
     info(run, `🗺️  拆解任務（${agent}）`);
     const cfg = loadRepoConfig();
     const { r, agent: actual } = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
@@ -201,9 +205,9 @@ async function planStage(run) {
 }
 async function planReviewStage(run) {
     const cfg = loadRepoConfig();
-    const author = run.planWriter ?? planAgent(run.cycle);
-    const panel = reviewers(run.cycle, author, cfg.planReviewQuorum);
+    const author = run.planWriter ?? planAgent(run.cycle, run.id);
     const round = (run.attempts["plan-review"] ?? 0) + 1;
+    const panel = reviewers(run.cycle, author, cfg.planReviewQuorum, `${run.id}:plan-review:${round}`);
     const issues = [];
     const issueLines = []; // 只含意見內容、不含審查者名稱，用來偵測僵持
     let firstObjector;
@@ -259,7 +263,12 @@ async function planReviewStage(run) {
 }
 async function planFixStage(run) {
     const cfg = loadRepoConfig();
-    const agent = planFixAgent(run.cycle, { strategy: cfg.fixStrategy, planWriter: run.planWriter, planReviewer: run.planReviewer });
+    const agent = planFixAgent(run.cycle, {
+        strategy: cfg.fixStrategy,
+        planWriter: run.planWriter,
+        planReviewer: run.planReviewer,
+        seed: `${run.id}:plan-fix:${run.attempts["plan-review"] ?? 0}`,
+    });
     info(run, `✏️  依 ${run.planReviewer ?? "審查者"} 的意見修改計畫（${agent}）`);
     const feedback = readFeedback(run);
     const snap = snapshotPlan(run);
@@ -286,7 +295,8 @@ async function planFixStage(run) {
  */
 async function arbitratePlan(run) {
     const cfg = loadRepoConfig();
-    const panel = arbiterPanel(run.cycle, run.planWriter, run.planReviewer);
+    const arbitrationRound = (run.attempts["plan-arbitration"] ?? 0) + 1;
+    const panel = arbiterPanel(run.cycle, `${run.id}:arbiter`, run.planWriter, run.planReviewer);
     const mode = panel.length > 1 ? "雙盲交叉仲裁" : "第三方仲裁";
     const verdicts = [];
     for (const arbiter of panel) {
@@ -302,7 +312,7 @@ async function arbitratePlan(run) {
         const result = r.ok ? readJsonFile(flowFile(run, "plan-arbiter.json"), ReviewResult) : undefined;
         if (result?.ok) {
             mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
-            renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbiter}.json`));
+            renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
         }
         const verdict = result?.ok ? result.data.verdict : "abstain";
         const notes = result?.ok ? result.data.items.map((i) => `- ${i.criterion}：${i.note}`) : [`- 未產生有效裁決（${r.ok ? "輸出格式錯誤" : r.summary}）`];
@@ -312,13 +322,21 @@ async function arbitratePlan(run) {
     rmSync(flowFile(run, "dispute.md"), { force: true });
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
     const unanimous = approvals === verdicts.length;
-    const decision = unanimous ? "proceed" : approvals === 0 ? "stop" : cfg.tieBreak;
+    const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak, arbitrationRound, config.maxAttempts);
     const summary = unanimous
         ? `${mode}一致核准`
         : approvals === 0
-            ? `${mode}沒有任何一方核准`
+            ? `${mode}沒有任何一方核准${decision === "revise" ? "，交回計畫修訂" : ""}`
             : `${mode}意見分歧，依 tieBreak=${cfg.tieBreak} ${cfg.tieBreak === "proceed" ? "繼續實作" : "停止"}`;
     const record = verdicts.map((v) => `### ${v.arbiter}（${v.verdict}）\n\n${v.notes.join("\n")}`).join("\n\n");
+    if (decision === "revise") {
+        const attempts = { ...run.attempts, "plan-arbitration": arbitrationRound };
+        delete attempts["plan-review"];
+        rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
+        writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${record}\n`);
+        info(run, `   → ${summary}`);
+        return { ...run, attempts, stage: "plan_fix" };
+    }
     writeFileSync(flowFile(run, "plan.md"), `${readFileSync(flowFile(run, "plan.md"), "utf8")}\n\n## 仲裁紀錄\n\n**結果：${summary}**\n\n${record}\n`);
     if (decision === "proceed") {
         info(run, `   → ${summary}`);
@@ -339,7 +357,7 @@ async function implementStage(run) {
     const testCmd = `${cfg.install} && ${cfg.test}`;
     const progress = `${run.taskIndex + 1}/${tasks.length} ${task.id} ${task.title}`;
     const taskJson = JSON.stringify(task, null, 2);
-    const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit);
+    const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit, run.id);
     // ── 紅燈：只寫測試，而且測試必須失敗 ──
     if (run.taskPhase === "tests") {
         const key = `${task.id}:tests`;
@@ -424,7 +442,13 @@ async function verifyStage(run) {
 async function fixStage(run) {
     const cfg = loadRepoConfig();
     const source = run.fixSource ?? "verify";
-    const agent = fixAgent(run.cycle, { source, strategy: cfg.fixStrategy, lastWriter: run.lastWriter, lastReviewer: run.lastReviewer });
+    const agent = fixAgent(run.cycle, {
+        source,
+        strategy: cfg.fixStrategy,
+        lastWriter: run.lastWriter,
+        lastReviewer: run.lastReviewer,
+        seed: `${run.id}:fix:${run.attempts.review ?? 0}`,
+    });
     const why = source === "review" ? `依 ${run.lastReviewer ?? "reviewer"} 的審查意見` : "修正驗證錯誤";
     info(run, `🩹 ${why}（${agent}）`);
     const repo = worktreeDir(run.id);
@@ -449,7 +473,7 @@ async function fixStage(run) {
 async function reviewStage(run) {
     const cfg = loadRepoConfig();
     const repo = worktreeDir(run.id);
-    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum);
+    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, `${run.id}:review:${run.attempts.review ?? 0}`);
     writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${run.baseBranch}...HEAD`));
     const authors = [...new Set((await git(repo, "log", "--format=%s", `${run.baseBranch}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
         .map((s) => s.slice(1, -1));

package/dist/roles.js

@@ -2,78 +2,109 @@
  * 決定每個步驟由哪個 agent 執行。
  *
  * 規則只有三條：
- * 1. 審查者不能是最後寫程式的 agent。
+ * 1. 審查者不能是最後寫程式的 agent，多位審查者彼此不重複。
  * 2. 開啟 tddSplit 時，同一個任務的測試與實作由不同 agent 負責。
- * 3. 所有選擇都沿著同一個輪替順序（cycle）前進，所以不同公司的模型會輪流扮演各個角色。
+ * 3. 人選隨機決定，不依 cycle 的順序。cycle 只代表有哪些 agent 參與。
+ *
+ * 隨機以 seed（run id 加上步驟與輪次）決定：同一個 run 的同一步驟重算時會得到同樣的人，
+ * 所以 resume、或同一步驟在不同地方重算時結果一致。
  */
-/** 從 from 的下一位開始，找第一個不在 exclude 裡的 agent；全部被排除時退回下一位（單一 agent 也能運作） */
-export function nextAfter(cycle, from, exclude = []) {
-    const n = cycle.length;
-    const start = from === undefined ? -1 : cycle.indexOf(from);
-    for (let i = 1; i <= n; i++) {
-        const candidate = cycle[(start + i + n) % n];
-        if (!exclude.includes(candidate))
-            return candidate;
+/** FNV-1a 雜湊：把 seed 字串轉成 32 位元整數 */
+function hash(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
     }
-    return cycle[(start + 1 + n) % n];
+    return h >>> 0;
 }
-export const specAgent = (cycle) => cycle[0];
-export const planAgent = (cycle) => cycle[0];
-/** 第 i 個任務的測試由輪替順序的第 i 位負責，實作交給下一位 */
-export function taskAgents(cycle, taskIndex, tddSplit) {
-    const tests = cycle[taskIndex % cycle.length];
-    return { tests, code: tddSplit ? nextAfter(cycle, tests, [tests]) : tests };
+/** mulberry32：由 seed 決定的亂數產生器 */
+function rng(seed) {
+    let a = hash(seed);
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
 }
-/** 從最後寫程式的 agent 之後，依序挑出 quorum 位不重複、而且不是作者的 reviewer */
-export function reviewers(cycle, lastWriter, quorum) {
-    const picked = [];
-    let cursor = lastWriter;
-    for (let i = 0; i < cycle.length && picked.length < quorum; i++) {
-        const next = nextAfter(cycle, cursor, [...(lastWriter ? [lastWriter] : []), ...picked]);
-        if (picked.includes(next) || (next === lastWriter && cycle.length > 1))
-            break;
-        picked.push(next);
-        cursor = next;
+/** 由 seed 決定的洗牌，不改動原陣列 */
+export function shuffled(items, seed) {
+    const out = [...items];
+    const rand = rng(seed);
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
     }
-    return picked.length ? picked : [nextAfter(cycle, lastWriter)];
+    return out;
+}
+/** 隨機挑一位不在 exclude 裡的 agent；全部被排除時退回任一位（單一 agent 也能運作） */
+export function pick(cycle, seed, exclude = []) {
+    const order = shuffled(cycle, seed);
+    return order.find((c) => !exclude.includes(c)) ?? order[0];
+}
+/** 規格與計畫由同一位撰寫，計畫審查才能同時避開兩者的作者 */
+export const specAgent = (cycle, seed) => pick(cycle, `${seed}:author`);
+export const planAgent = specAgent;
+/**
+ * 每 cycle.length 個任務為一輪，每輪洗一次牌，所以每家輪完一次才會再輪到；
+ * 換輪時若新一輪第一位和上一輪最後一位相同，就把它往後移，避免同一家連續撰寫測試。
+ */
+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 };
+}
+/** 隨機挑出 quorum 位彼此不重複、而且不是作者的 reviewer */
+export function reviewers(cycle, lastWriter, quorum, seed) {
+    const picked = shuffled(cycle.filter((c) => c !== lastWriter), seed).slice(0, quorum);
+    return picked.length ? picked : [lastWriter ?? cycle[0]];
 }
 /**
  * 誰來修正：
  * - verify 失敗（型別、lint、建置這類機械性錯誤）：交給最後寫程式的 agent
- * - review 要求修改：ring 策略輪到 reviewer 的下一位；author 策略交回作者
+ * - review 要求修改：ring 策略隨機挑一位 reviewer 以外的 agent；author 策略交回作者
  */
 export function fixAgent(cycle, opts) {
     if (opts.source === "verify" || opts.strategy === "author")
         return opts.lastWriter ?? cycle[0];
-    return nextAfter(cycle, opts.lastReviewer, opts.lastReviewer ? [opts.lastReviewer] : []);
+    return pick(cycle, opts.seed, opts.lastReviewer ? [opts.lastReviewer] : []);
 }
-/** 計畫修正者：ring 策略輪到審查者的下一位；author 策略交回計畫作者 */
+/** 計畫修正者：ring 策略隨機挑一位審查者以外的 agent；author 策略交回計畫作者 */
 export function planFixAgent(cycle, opts) {
     if (opts.strategy === "author")
         return opts.planWriter ?? cycle[0];
-    return nextAfter(cycle, opts.planReviewer, opts.planReviewer ? [opts.planReviewer] : []);
+    return pick(cycle, opts.seed, opts.planReviewer ? [opts.planReviewer] : []);
 }
 /**
  * 仲裁小組：
- * - 有第三方（作者與最後審查者以外的 agent）→ 由第三方單獨仲裁
+ * - 有第三方（作者與最後審查者以外的 agent）→ 隨機挑一位第三方單獨仲裁
  * - 只有兩家 → 兩家各自在全新 context 中雙盲仲裁，避免讓一直反對的審查者同時當裁判
  * - 只有一家 → 只能由它自己仲裁
  */
-export function arbiterPanel(cycle, writer, reviewer) {
+export function arbiterPanel(cycle, seed, writer, reviewer) {
     const involved = [writer, reviewer].filter((x) => Boolean(x));
-    const third = cycle.find((c) => !involved.includes(c));
+    const third = shuffled(cycle, seed).find((c) => !involved.includes(c));
     if (third)
         return [third];
     return [...new Set(cycle)];
 }
 /**
- * 代打人選：原本的 agent 可用就用它；額度用完時，沿輪替順序找下一位還有額度的 agent。
+ * 代打人選：原本的 agent 可用就用它；額度用完時，隨機挑一位還有額度的 agent。
  * 全部都用完時回傳 undefined。
  */
-export function availableAgent(cycle, preferred, exhausted) {
+export function availableAgent(cycle, preferred, exhausted, seed) {
     if (!exhausted.includes(preferred))
         return preferred;
-    const next = nextAfter(cycle, preferred, exhausted);
-    return exhausted.includes(next) ? undefined : next;
+    return shuffled(cycle, seed).find((c) => !exhausted.includes(c));
 }
 //# sourceMappingURL=roles.js.map

package/dist/runner.js

@@ -59,7 +59,8 @@ export function resolveAgent(cfg, name) {
     const def = cfg.agents[name];
     if (!def)
         throw new Error(`未定義的 agent：${name}（請先用 agent add ${name} --adapter <adapter> 新增）`);
-    return def;
+    const defaultModel = def.adapter === "command" ? undefined : cfg.defaultModels[def.adapter];
+    return { ...def, model: def.model ?? defaultModel };
 }
 /** 確認某個 agent 的 CLI 是否可以執行 */
 export async function probeAgent(def) {

package/dist/schemas.js

@@ -39,7 +39,7 @@ export const ReviewResult = z.object({
         note: z.string().default(""),
     })),
 });
-/** 一個 agent 的定義；名稱（agents 的 key）用在輪替順序裡 */
+/** 一個 agent 的定義；名稱（agents 的 key）用在 cycle 裡 */
 export const AgentDef = z.object({
     adapter: z.enum(["claude", "codex", "gemini", "command"]),
     model: z.string().optional(),
@@ -51,7 +51,13 @@ export const AgentDef = z.object({
 export const RepoConfig = z.object({
     /** 可用的 agent；沒有內建，全部都要在這裡定義（通常用 agent add） */
     agents: z.record(z.string(), AgentDef).default({}),
-    /** 輪替順序；未設定時依 agents 的順序，取已安裝的 CLI */
+    /** 各 CLI adapter 的預設模型；agent 自己指定 model 時優先使用個別設定 */
+    defaultModels: z.strictObject({
+        claude: z.string().trim().min(1).optional(),
+        codex: z.string().trim().min(1).optional(),
+        gemini: z.string().trim().min(1).optional(),
+    }).default({}),
+    /** 參與的 agent（順序不影響分工）；未設定時取 agents 裡已安裝的 CLI */
     cycle: z.array(z.string()).min(1).optional(),
     /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
     fixStrategy: z.enum(["ring", "author"]).default("ring"),
@@ -94,7 +100,7 @@ export const FlowRun = z.object({
     /** 暫停前所在的階段與原因（額度用完時） */
     pausedStage: Stage.optional(),
     pauseReason: z.string().optional(),
-    /** 這個 run 的 agent 輪替順序（建立時決定，resume 時沿用） */
+    /** 這個 run 參與的 agent（建立時決定，resume 時沿用） */
     cycle: z.array(z.string()).min(1),
     /** 最後一個寫程式的 agent，reviewer 不可以是它 */
     lastWriter: z.string().optional(),

package/dist/setup.js

@@ -46,7 +46,7 @@ export async function runSetup(initial, deps) {
         return null;
     }
     for (;;) {
-        const list = (await ask("輪替順序，用逗號分隔", chosen.join(","))).split(",").map((s) => s.trim()).filter(Boolean);
+        const list = (await ask("參與的 agent，用逗號分隔", chosen.join(","))).split(",").map((s) => s.trim()).filter(Boolean);
         try {
             cfg = setCycle(cfg, list).cfg;
             break;
@@ -59,7 +59,7 @@ export async function runSetup(initial, deps) {
     log("\n即將寫入：");
     for (const name of chosen)
         log(`  ${name.padEnd(14)} adapter=${agents[name].adapter}${agents[name].model ? ` model=${agents[name].model}` : ""}`);
-    log(`  輪替順序：${cfg.cycle.join(" → ")}`);
+    log(`  參與的 agent：${cfg.cycle.join("、")}`);
     log("  需要自訂指令的 CLI 請改用 agent add <name> --adapter command -- <指令>");
     if (!(await confirm("寫入 flow.config.json？", true))) {
         log("已取消，設定沒有變更");

package/examples/flow.config.json

@@ -7,6 +7,7 @@
   "planArbiter": true,
   "tieBreak": "proceed",
   "maxAgentRuns": 60,
+  "defaultModels": { "claude": "Claude 模型名稱", "codex": "Codex 模型名稱" },
   "agents": {
     "claude": { "adapter": "claude" },
     "codex": { "adapter": "codex" }

package/package.json

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