agentflowctl 0.1.2 → 0.3.0

package/README.md

@@ -93,11 +93,25 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `--base` | 基底分支，預設為目前分支 |
 | `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
 | `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
-| `--budget` | 估計花費上限（美元）；使用 API 計費時才需要 |
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
 
 `status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
 
+### 執行中的終端機輸出
+
+agent 每次使用工具，都會印出完整的指令或主要參數，不截斷。多行指令的後續行會縮排對齊。install、測試、verify 這些專案指令也會以 `$ ` 開頭印出來：
+
+```
+    💬 [claude] 先讀現有的表單元件
+    🔧 [claude] Read: /repo/.agentflowctl/worktrees/f-xxxx/src/LoginForm.tsx
+    🔧 [claude] Bash: pnpm vitest run src/LoginForm.test.tsx
+    🔧 [codex] shell: bash -lc 'pnpm test'
+    🔧 [gemini] run_shell_command: npm run lint
+    $ pnpm install
+```
+
+工具參數依序取 command、檔案路徑、path、pattern、url、query，都沒有時印出整包 JSON。每次執行的完整輸出都在 `agentflowctl logs <id>`。
+
 ## 設定
 
 專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設（安裝指令、測試指令、檢查清單預設對應 Vite + TypeScript + Vitest）。
@@ -109,7 +123,7 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
   "tddSplit": true,
   "tieBreak": "proceed",
   "agents": {
-    "codex": { "adapter": "codex", "model": "你要用的模型", "pricing": { "inputPerMTok": 1.25, "outputPerMTok": 10 } },
+    "codex": { "adapter": "codex", "model": "你要用的模型" },
     "aider": { "adapter": "command", "command": ["aider", "--yes-always", "--no-auto-commits", "--message", "{prompt}"] }
   }
 }
@@ -124,13 +138,37 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者都 `approve` |
 | `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
 | `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
-| `auth` | `subscription` | `subscription` 移除子程序裡的 API key；`api` 保留，給 CI 用 |
 | `maxAgentRuns` | `60` | 單一 run 最多執行幾次 agent |
 | `install` / `test` / `checks` | 見 `src/schemas.ts` | verify 階段實際執行的指令 |
 | `agents` | 內建 claude、codex、gemini | 覆寫內建 agent，或用 `command` adapter 接上其他 CLI |
+| `removedAgents` | `[]` | 移除的內建 agent，不會被自動偵測、不能放進輪替。通常用 `agent remove` 寫入 |
 
 verify 失敗（型別、lint、建置）一律交回最後作者。審查意見才依 `fixStrategy` 決定修正者。
 
+### 用指令管理 agent
+
+`agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
+
+```bash
+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 remove gemini                          # 內建的也能移除
+agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯示目前的順序
+```
+
+修改會連帶更新相關設定，並在終端機列出：
+
+- `set --adapter` 換 adapter 時，會清掉舊 adapter 的 `model`、`extraArgs`、`command`，這次有重新指定的除外。
+- `remove` 會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回自動偵測。
+- 內建的 claude、codex、gemini 也能 `remove`：覆寫設定會一起刪掉，名稱記在 `removedAgents`，之後自動偵測會跳過它，也不能放進 `cycle`。要加回來用 `agent add gemini --adapter gemini`。
+- `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
+
+已建立的 run 會沿用建立時的輪替順序，不受這些修改影響。
+
 ## 計畫怎麼在沒有人的情況下通過
 
 人工確認計畫是為了擋住方向錯了還一路做下去。預設用三層機制取代它；加上 `--manual-plan` 時，三層都過了仍會停下來等你。
@@ -169,6 +207,23 @@ verify 失敗（型別、lint、建置）一律交回最後作者。審查意見
 
 驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
 
+## Prompt 結構
+
+每個階段的 prompt 都有專屬角色：需求分析師、軟體架構師、計畫審查者、計畫修訂者、中立仲裁者、測試工程師、實作工程師、除錯工程師、程式碼審查者。內容用 XML 標籤分段：`<role>`、`<context>`、`<inputs>`、`<steps>`、`<constraints>`、`<output_format>`、`<reply_format>`。
+
+Agent 的最後回覆要附上 XML 中繼資料：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>做了什麼</summary>
+  <files_changed><file>src/form.ts</file></files_changed>
+  <concerns>對規格或測試的疑慮</concerns>
+</result>
+```
+
+`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
+
 ## Adapter
 
 | adapter | 執行方式 | 權限 |
@@ -184,11 +239,11 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 ## 登入、額度與代打
 
-預設 `auth: "subscription"`，只用各家 CLI 的訂閱登入。
+只支援各家 CLI 的訂閱登入。
 
-執行 agent 時，會從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
+執行 agent 時，一律從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
 
-上限是執行次數（`maxAgentRuns`，預設 60），不是金額。Claude Code 回報的美元金額是 API 價格的估計值。
+上限是執行次數（`maxAgentRuns`，預設 60），不是金額。`status` 會列出各 agent 的執行次數與 token 數。
 
 額度用完時：
 
@@ -204,8 +259,6 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 額度錯誤靠錯誤訊息辨識（usage limit、rate limit、quota、429 等），只在 agent 執行失敗時判斷。辨識不到時，會當成一般失敗重試。
 
-CI 無法使用訂閱登入時，設 `"auth": "api"` 保留 API key，並用 `--budget` 設估計花費上限。Codex、Gemini 只回報 token，要在 `agents.<name>.pricing` 設定價格才會算進預算。GitHub Actions 範例見 `examples/github-actions.yml`。
-
 ## 在哪裡跑
 
 agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell 執行。
@@ -213,7 +266,7 @@ agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell
 | 環境 | 適合的用法 |
 |---|---|
 | 自己的電腦 | 自己的專案、自己寫的需求。剛開始可以加 `--manual-plan`，確認審查品質後再拿掉 |
-| CI、容器、遠端開發機 | 無人值守。見 `examples/github-actions.yml`：issue 加上標籤就跑完並開 PR |
+| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的訂閱登入 |
 | Claude Code、Codex 裡面 | 讓它們用 shell 執行 `npx agentflowctl` |
 
 沒有容器隔離時，verify 會在你的電腦上執行 agent 寫出來的程式碼。Gemini 在無人值守時是 yolo 模式。處理外部 issue，或需求文字不是你自己寫的，放到可丟棄的環境。AI 審查計畫擋不住夾在需求裡的指示。
@@ -228,7 +281,7 @@ src/
   runner.ts         執行 agent、正規化結果、執行專案指令
   agents/           claude、codex、gemini、command
   git.ts            worktree 與 git 操作
-  store.ts          狀態、花費、代打紀錄
+  store.ts          狀態、用量、代打紀錄
   tasks.ts          任務 DAG
   schemas.ts        zod schema
 prompts/            各階段 prompt

package/dist/agentConfig.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { builtinAgents, DEFAULT_CYCLE } from "./agents/index.js";
+import { AgentDef, RepoConfig } from "./schemas.js";
+/** 這些欄位的意義取決於 adapter，換 adapter 時要清掉 */
+const ADAPTER_FIELDS = ["model", "extraArgs", "command"];
+const isBuiltin = (name) => DEFAULT_CYCLE.includes(name);
+const agentsOf = (cfg) => ({ ...(cfg.agents ?? {}) });
+const removedOf = (cfg) => (cfg.removedAgents ?? []);
+const isDefined = (cfg, name) => builtinAgents(removedOf(cfg)).includes(name) || name in agentsOf(cfg);
+/** 寫回 removedAgents；清單變空就刪掉欄位 */
+function withRemoved(cfg, removed) {
+    const next = { ...cfg, removedAgents: removed };
+    if (!removed.length)
+        delete next.removedAgents;
+    return next;
+}
+/** 只留下有值的欄位，驗證後回傳 */
+function buildAgent(base, patch) {
+    const next = { ...base };
+    for (const [k, v] of Object.entries(patch))
+        if (v !== undefined)
+            next[k] = v;
+    const parsed = AgentDef.safeParse(next);
+    if (!parsed.success)
+        throw new Error(`agent 設定不合法：\n${z.prettifyError(parsed.error)}`);
+    if (parsed.data.adapter === "command" && !parsed.data.command?.length) {
+        throw new Error("command adapter 需要指令，請寫在 -- 後面，例如：-- aider --message {prompt}");
+    }
+    if (parsed.data.adapter !== "command" && parsed.data.command)
+        throw new Error("只有 command adapter 可以設定 command");
+    return next;
+}
+export function addAgent(cfg, name, def) {
+    if (!/^[\w-]+$/.test(name))
+        throw new Error(`agent 名稱只能用英數字、底線與連字號：${name}`);
+    if (isDefined(cfg, name))
+        throw new Error(`agent ${name} 已存在，要修改請用 agent set`);
+    const { adapter, ...patch } = def;
+    const next = { ...cfg, agents: { ...agentsOf(cfg), [name]: buildAgent({ adapter }, patch) } };
+    // 加回先前移除的內建 agent
+    const removed = removedOf(cfg);
+    return { cfg: removed.includes(name) ? withRemoved(next, removed.filter((n) => n !== name)) : next, changes: [] };
+}
+export function setAgent(cfg, name, patch) {
+    if (!isDefined(cfg, name))
+        throw new Error(`未定義的 agent：${name}`);
+    if (Object.values(patch).every((v) => v === undefined)) {
+        throw new Error("沒有要修改的欄位（--adapter、--model、--extra-arg 或 -- <command>）");
+    }
+    const agents = agentsOf(cfg);
+    // 內建 agent 第一次修改時，新增一筆覆寫設定
+    const base = { ...(agents[name] ?? { adapter: name }) };
+    const changes = [];
+    if (patch.adapter !== undefined && patch.adapter !== base.adapter) {
+        const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && patch[f] === undefined);
+        for (const f of cleared)
+            delete base[f];
+        if (cleared.length)
+            changes.push(`adapter 從 ${String(base.adapter)} 換成 ${patch.adapter}，已清掉舊的 ${cleared.join("、")}`);
+    }
+    return { cfg: { ...cfg, agents: { ...agents, [name]: buildAgent(base, patch) } }, changes };
+}
+export function removeAgent(cfg, name) {
+    if (!isDefined(cfg, name))
+        throw new Error(`未定義的 agent：${name}`);
+    const agents = agentsOf(cfg);
+    delete agents[name];
+    // 內建 agent 沒有設定也存在，要記在 removedAgents 才算移除；覆寫設定一併刪掉
+    let next = { ...cfg, agents };
+    if (isBuiltin(name))
+        next = withRemoved(next, [...removedOf(cfg), name]);
+    const changes = [];
+    const cycle = cfg.cycle;
+    if (cycle?.includes(name)) {
+        const rest = cycle.filter((n) => n !== name);
+        if (rest.length) {
+            next.cycle = rest;
+            changes.push(`已從輪替順序移除，現在是 ${rest.join(" → ")}`);
+        }
+        else {
+            delete next.cycle;
+            changes.push("輪替順序因此變空，已刪除 cycle，改回自動偵測已安裝的 CLI");
+        }
+    }
+    return { cfg: next, changes };
+}
+export function setCycle(cfg, names) {
+    if (!names.length)
+        throw new Error("輪替順序至少要有一個 agent");
+    const dup = names.find((n, i) => names.indexOf(n) !== i);
+    if (dup)
+        throw new Error(`輪替順序裡 ${dup} 重複了`);
+    const missing = names.filter((n) => !isDefined(cfg, n));
+    if (missing.length)
+        throw new Error(`未定義的 agent：${missing.join("、")}（先用 agent add 新增）`);
+    return { cfg: { ...cfg, cycle: names }, changes: [] };
+}
+export function readRawConfig(path) {
+    if (!existsSync(path))
+        return {};
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** 先用 RepoConfig 驗證整份設定，通過才寫入 */
+export function writeRawConfig(path, cfg) {
+    const parsed = RepoConfig.safeParse(cfg);
+    if (!parsed.success)
+        throw new Error(`設定不合法，未寫入：\n${z.prettifyError(parsed.error)}`);
+    writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`);
+}
+//# sourceMappingURL=agentConfig.js.map

package/dist/agents/claude.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { num, str, tryJson } from "./types.js";
+import { num, str, toolDetail, tryJson } from "./types.js";
 /**
  * Claude Code 的權限設定：acceptEdits 只自動允許工作目錄內的修改，
  * 版本控制交給 agentflowctl，並啟用內建沙箱限制 shell 指令。
@@ -46,7 +46,7 @@ export const claude = {
                 if (b.type === "text" && str(b.text)?.trim())
                     out.push({ kind: "text", text: str(b.text) });
                 if (b.type === "tool_use")
-                    out.push({ kind: "tool", name: str(b.name) ?? "tool" });
+                    out.push({ kind: "tool", name: str(b.name) ?? "tool", detail: toolDetail(b.input) });
             }
         }
         else if (ev.type === "result") {
@@ -55,7 +55,6 @@ export const claude = {
                 kind: "usage",
                 inputTokens: num(usage.input_tokens),
                 outputTokens: num(usage.output_tokens),
-                costUsd: num(ev.total_cost_usd),
             });
             out.push({ kind: "done", ok: ev.is_error !== true, summary: str(ev.result) });
         }

package/dist/agents/codex.js

@@ -21,9 +21,12 @@ export const codex = {
             if (item.type === "agent_message" && str(item.text)?.trim())
                 out.push({ kind: "text", text: str(item.text) });
             else if (item.type === "command_execution")
-                out.push({ kind: "tool", name: `shell: ${str(item.command) ?? ""}`.slice(0, 80) });
-            else if (item.type === "file_change")
-                out.push({ kind: "tool", name: "edit" });
+                out.push({ kind: "tool", name: "shell", detail: str(item.command) });
+            else if (item.type === "file_change") {
+                const changes = Array.isArray(item.changes) ? item.changes : [];
+                const paths = changes.map((c) => str(c.path)).filter(Boolean);
+                out.push({ kind: "tool", name: "edit", detail: paths.length ? paths.join(", ") : undefined });
+            }
         }
         else if (ev.type === "turn.completed") {
             const usage = (ev.usage ?? {});

package/dist/agents/gemini.js

@@ -1,4 +1,4 @@
-import { num, str, tryJson } from "./types.js";
+import { num, str, toolDetail, tryJson } from "./types.js";
 /**
  * Google Gemini CLI：`gemini -p ... --output-format stream-json`。
  * Gemini CLI 沒有「只允許工作目錄內的 shell 指令」這種細緻權限，
@@ -21,7 +21,7 @@ export const gemini = {
             out.push({ kind: "text", text: str(ev.content) });
         }
         else if (ev.type === "tool_use") {
-            out.push({ kind: "tool", name: str(ev.tool_name) ?? "tool" });
+            out.push({ kind: "tool", name: str(ev.tool_name) ?? "tool", detail: toolDetail(ev.parameters) });
         }
         else if (ev.type === "result") {
             const stats = (ev.stats ?? {});

package/dist/agents/index.js

@@ -5,4 +5,6 @@ import { gemini } from "./gemini.js";
 export const ADAPTERS = { claude, codex, gemini, command };
 /** 沒有設定時，依序偵測這些已安裝的 CLI 組成輪替順序 */
 export const DEFAULT_CYCLE = ["claude", "codex", "gemini"];
+/** 扣掉設定裡 removedAgents 之後，仍可使用的內建 agent */
+export const builtinAgents = (removed = []) => DEFAULT_CYCLE.filter((n) => !removed.includes(n));
 //# sourceMappingURL=index.js.map

package/dist/agents/types.js

@@ -9,4 +9,18 @@ export function tryJson(line) {
 }
 export const num = (v) => (typeof v === "number" ? v : undefined);
 export const str = (v) => (typeof v === "string" ? v : undefined);
+/** 從工具參數挑出最能代表「正在做什麼」的欄位；都沒有時以 JSON 顯示全部參數 */
+export function toolDetail(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const o = input;
+    for (const key of ["command", "cmd", "file_path", "absolute_path", "path", "pattern", "url", "query"]) {
+        const v = o[key];
+        if (typeof v === "string" && v.trim())
+            return v;
+        if (Array.isArray(v) && v.length)
+            return v.join(" ");
+    }
+    return Object.keys(o).length ? JSON.stringify(o) : undefined;
+}
 //# sourceMappingURL=types.js.map

package/dist/cli.js

@@ -2,14 +2,15 @@
 import { Command } from "commander";
 import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { DEFAULT_CYCLE } from "./agents/index.js";
+import { builtinAgents } from "./agents/index.js";
 import { advance, loadRepoConfig } from "./engine.js";
 import { API_KEY_VARS, probeAgent, resolveAgent, runCommand } from "./runner.js";
 import { addWorktree, git, removeWorktree } from "./git.js";
 import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.js";
 import { TaskList } from "./schemas.js";
-import { agentRuns, costByAgent, getCost, getRun, listRuns, listSubstitutions, saveRun } from "./store.js";
+import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent } from "./store.js";
 import { readJsonFile } from "./util.js";
+import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -28,7 +29,7 @@ function printSummary(run) {
     console.log("");
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
-    console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次（估計花費 $${getCost(run.id).toFixed(2)}${run.budgetUsd ? ` / $${run.budgetUsd}` : "，訂閱登入時僅供參考"}）`);
+    console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次`);
     console.log(`agent    ${run.cycle.join(" → ")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
     console.log(`分支     ${run.branch}`);
     console.log(`worktree ${worktreeDir(run.id)}`);
@@ -61,11 +62,11 @@ async function resolveCycle(flag) {
         return wanted;
     }
     const found = [];
-    for (const name of DEFAULT_CYCLE)
+    for (const name of builtinAgents(cfg.removedAgents))
         if (await probeAgent(resolveAgent(cfg, name)))
             found.push(name);
     if (!found.length)
-        throw new Error("沒有偵測到任何 agent CLI（claude、codex、gemini），可用 agentflowctl doctor 檢查");
+        throw new Error(`沒有偵測到任何 agent CLI（${builtinAgents(cfg.removedAgents).join("、") || "內建 agent 都已移除"}），可用 agentflowctl doctor 檢查`);
     return found;
 }
 const program = new Command()
@@ -78,7 +79,6 @@ program
     .option("--req-file <file>", "從檔案讀取需求")
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
-    .option("--budget <usd>", "選用：估計花費上限（美元），使用 API 計費時才需要")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
     .option("--cycle <agents>", "agent 輪替順序，例如 claude,codex,gemini")
     .action(async (opts) => {
@@ -108,7 +108,6 @@ program
         requirement: requirement.trim(),
         stage: "spec",
         autopilot: !opts.manualPlan,
-        budgetUsd: opts.budget ? Number(opts.budget) : undefined,
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
         cycle,
         attempts: {},
@@ -132,11 +131,8 @@ program
     .command("resume <id>")
     .description("從暫停、中斷或失敗的階段接續")
     .option("--max-agent-runs <n>", "調整 agent 執行次數上限")
-    .option("--budget <usd>", "調整估計花費上限（美元）")
     .action(async (id, opts) => {
     let run = mustGetRun(id);
-    if (opts.budget)
-        run = { ...run, budgetUsd: Number(opts.budget) };
     if (opts.maxAgentRuns)
         run = { ...run, maxAgentRuns: Number(opts.maxAgentRuns) };
     if (run.stage === "paused") {
@@ -171,11 +167,11 @@ program
     .action((id) => {
     const run = mustGetRun(id);
     printSummary(run);
-    const byAgent = costByAgent(id);
+    const byAgent = usageByAgent(id);
     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  $${c.usd.toFixed(2)}`);
+            console.log(`  ${agent.padEnd(10)} ${String(c.runs).padStart(3)} 次  ${String(c.tokens).padStart(9)} tokens`);
         }
     }
     const subs = listSubstitutions(id);
@@ -194,12 +190,91 @@ program
         console.log(`  ${mark} ${t.id} ${t.title}`);
     });
 });
+// ───────────── agent 管理：讀寫 flow.config.json 的 agents 與 cycle ─────────────
+const configPath = () => join(projectRoot(), "flow.config.json");
+const collect = (value, prev = []) => [...prev, value];
+function applyEdit(edit, done) {
+    const before = readRawConfig(configPath());
+    const { cfg, changes } = edit(before);
+    writeRawConfig(configPath(), cfg);
+    console.log(`✅ ${done}（${configPath()}）`);
+    for (const c of changes)
+        console.log(`   ↳ ${c}`);
+    if (JSON.stringify(before.cycle) !== JSON.stringify(cfg.cycle)) {
+        console.log("   已建立的 run 會沿用建立時的輪替順序，不受影響");
+    }
+}
+const agent = program.command("agent").description("管理 agent 與 adapter 設定（寫入 flow.config.json）");
+agent
+    .command("list")
+    .description("列出內建與自訂 agent、是否已安裝、在輪替中的位置")
+    .action(async () => {
+    const cfg = loadRepoConfig();
+    const cycle = await resolveCycle().catch(() => cfg.cycle ?? []);
+    const names = [...new Set([...builtinAgents(cfg.removedAgents), ...Object.keys(cfg.agents)])];
+    for (const name of names) {
+        const def = resolveAgent(cfg, name);
+        const ok = await probeAgent(def);
+        const pos = cycle.indexOf(name);
+        const kind = builtinAgents(cfg.removedAgents).includes(name) ? (name in cfg.agents ? "內建（已覆寫）" : "內建") : "自訂";
+        const detail = [
+            `adapter=${def.adapter}`,
+            def.model && `model=${def.model}`,
+            def.extraArgs.length && `extraArgs=${def.extraArgs.join(" ")}`,
+            def.command && `command=${def.command.join(" ")}`,
+        ].filter(Boolean);
+        console.log(`${ok ? "✅" : "❌"} ${name.padEnd(14)} ${kind.padEnd(8)} ${pos >= 0 ? `輪替 #${pos + 1}` : "不在輪替"}  ${detail.join(" ")}`);
+    }
+    if (cfg.removedAgents.length)
+        console.log(`\n已移除的內建 agent：${cfg.removedAgents.join("、")}（可用 agent add <name> --adapter <name> 加回）`);
+    console.log(`
+輪替順序：${cycle.length ? cycle.join(" → ") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
+});
+agent
+    .command("add <name> [command...]")
+    .description("新增 agent；command adapter 的指令寫在 -- 後面")
+    .requiredOption("--adapter <adapter>", "claude、codex、gemini 或 command")
+    .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`);
+});
+agent
+    .command("set <name> [command...]")
+    .description("修改 agent；更換 adapter 時會清掉舊 adapter 的 model、extraArgs、command")
+    .option("--adapter <adapter>", "claude、codex、gemini 或 command")
+    .option("--model <model>", "模型名稱")
+    .option("--extra-arg <arg>", "額外參數，可重複，會整個取代原本的設定", 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}`);
+});
+agent
+    .command("remove <name>")
+    .description("刪除 agent（含內建的 claude、codex、gemini），一併從輪替移除；內建的可用 agent add 加回")
+    .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已移除 ${name}`));
+agent
+    .command("cycle [names]")
+    .description("顯示輪替順序，或用逗號分隔設定新的順序")
+    .action(async (names) => {
+    if (!names) {
+        const cfg = loadRepoConfig();
+        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(" → ")}`);
+    const cfg = loadRepoConfig();
+    for (const n of list) {
+        if (!(await probeAgent(resolveAgent(cfg, n))))
+            console.log(`⚠️  ${n} 目前找不到可執行的 CLI，run 會失敗，請先安裝或用 agent set 修正`);
+    }
+});
 program
     .command("doctor")
     .description("檢查可用的 agent CLI 與目前的輪替設定")
     .action(async () => {
     const cfg = loadRepoConfig();
-    const names = [...new Set([...DEFAULT_CYCLE, ...Object.keys(cfg.agents)])];
+    const names = [...new Set([...builtinAgents(cfg.removedAgents), ...Object.keys(cfg.agents)])];
     for (const name of names) {
         const def = resolveAgent(cfg, name);
         const ok = await probeAgent(def);
@@ -212,11 +287,9 @@ program
         console.log(`\n${e.message}`);
     }
     const leaked = API_KEY_VARS.filter((k) => process.env[k]);
-    console.log(`\n登入方式：${cfg.auth === "subscription" ? "訂閱登入（執行 agent 時會移除 API key）" : "API key"}`);
+    console.log("\n登入方式：訂閱登入（執行 agent 時會移除 API key）");
     if (leaked.length) {
-        console.log(cfg.auth === "subscription"
-            ? `⚠️  環境中有 ${leaked.join("、")}，agentflowctl 執行 agent 時會移除，但你自己直接執行 CLI 時仍可能改走 API 計費`
-            : `使用中的 API key：${leaked.join("、")}`);
+        console.log(`⚠️  環境中有 ${leaked.join("、")}，agentflowctl 執行 agent 時會移除，但你自己直接執行 CLI 時仍可能改走 API 計費`);
     }
     console.log(`單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
@@ -228,7 +301,7 @@ program
     .action(() => {
     for (const r of listRuns()) {
         const req = r.requirement.split("\n")[0].slice(0, 40);
-        console.log(`${r.id}  ${r.stage.padEnd(17)}  $${getCost(r.id).toFixed(2).padStart(6)}  ${r.updatedAt.slice(0, 16)}  ${req}`);
+        console.log(`${r.id}  ${r.stage.padEnd(17)}  ${String(agentRuns(r.id)).padStart(3)} 次  ${r.updatedAt.slice(0, 16)}  ${req}`);
     }
 });
 program

package/dist/engine.js

@@ -7,7 +7,7 @@ import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
 import { AcceptanceList, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
-import { addCost, addSubstitution, agentRuns, getCost, saveRun } from "./store.js";
+import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
 import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
@@ -43,18 +43,27 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
-        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, `${step}-${agent}`), prompt, {
-            stripApiKeys: cfg.auth === "subscription",
-        });
-        addCost(run.id, { stage: step, agent, usd: r.costUsd, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
-        if (!r.quotaExhausted)
+        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 });
+        if (!r.quotaExhausted) {
+            reportMeta(run, agent, r);
             return { r, agent };
+        }
         info(run, `⛽ ${agent} 的額度已用完`);
         exhausted.add(agent);
         await reset();
         // 迴圈回到開頭：review 會停下，write 會找代打
     }
 }
+/** 印出回覆裡的 XML 中繼資料；只供人檢視，關卡仍由程式檢查決定 */
+function reportMeta(run, agent, r) {
+    if (!r.meta)
+        return;
+    if (r.meta.status === "blocked")
+        info(run, `   🚧 ${agent} 回報卡住：${r.meta.summary}`);
+    if (r.meta.concerns)
+        info(run, `   💭 ${agent} 的疑慮：${r.meta.concerns}`);
+}
 function readFeedback(run) {
     const p = flowFile(run, "feedback.md");
     return existsSync(p) ? readFileSync(p, "utf8") : "";
@@ -481,7 +490,7 @@ async function prStage(run) {
     const title = run.requirement.split("\n")[0].slice(0, 72);
     const spec = existsSync(flowFile(run, "spec.md")) ? readFileSync(flowFile(run, "spec.md"), "utf8") : "";
     const bodyPath = join(runDir(run.id), "pr-body.md");
-    writeFileSync(bodyPath, `> 由 agentflowctl 自動產生（run: ${run.id}，參與的 agent：${run.cycle.join("、")}，花費約 $${getCost(run.id).toFixed(2)}）\n\n${spec}`);
+    writeFileSync(bodyPath, `> 由 agentflowctl 自動產生（run: ${run.id}，參與的 agent：${run.cycle.join("、")}，執行 agent ${agentRuns(run.id)} 次）\n\n${spec}`);
     const r = await exec("gh", ["pr", "create", "--head", run.branch, "--base", run.baseBranch, "--title", title, "--body-file", bodyPath], { cwd: repo });
     if (r.code !== 0) {
         info(run, `⚠️  gh pr create 失敗，分支已推送，請手動建立 PR：${r.stderr.trim()}`);
@@ -516,15 +525,6 @@ export async function advance(initial) {
                 failureReason: `已執行 agent ${runs} 次，達到上限 ${run.maxAgentRuns}（可用 resume --max-agent-runs 調高）`,
             });
         }
-        const cost = getCost(run.id);
-        if (run.budgetUsd !== undefined && cost >= run.budgetUsd) {
-            return saveRun({
-                ...run,
-                stage: "failed",
-                failedStage: stage,
-                failureReason: `估計花費 $${cost.toFixed(2)}，超過預算 $${run.budgetUsd}`,
-            });
-        }
         try {
             run = saveRun(await STAGES[stage](run));
         }