agentflowctl 0.3.0 → 0.4.0

package/README.md

@@ -10,15 +10,33 @@
 
 ## 快速開始
 
-需要 Node.js 22 以上與 git。不需要全域安裝，直接用 `npx` 執行。先讓各家 CLI 完成訂閱登入，再檢查環境：
+需要 Node.js 22 以上與 git。不需要全域安裝，直接用 `npx` 執行。先讓各家 CLI 完成登入：
 
 ```bash
 claude    # 完成登入
 codex     # 完成登入
+```
+
+沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會偵測本機的 `claude`、`codex`、`gemini`，逐一詢問要不要加入、名稱與 model，再設定輪替順序；確認後才一次寫入，最後自動跑一次 `doctor`：
+
+```bash
+npx agentflowctl agent setup
+```
+
+也可以不經互動，直接用指令新增：
+
+```bash
+npx agentflowctl agent add claude --adapter claude
+npx agentflowctl agent add codex --adapter codex
+```
+
+之後改了設定或換了環境，用 `doctor` 檢查。它會列出設定的 agent 的 CLI 是否已安裝，並印出即將使用的輪替順序。沒有設定 `cycle` 時，依 `agents` 的順序取已安裝的；一個都沒偵測到就無法執行。
+
+```bash
 npx agentflowctl doctor
 ```
 
-`doctor` 會列出已安裝的 CLI，並印出即將使用的輪替順序。沒有 `flow.config.json` 時，會自動採用偵測到的 CLI。
+從舊版升級：以前沒寫 `agents` 時會自動使用內建的 claude、codex、gemini，現在不會了，要先用 `agent setup` 或 `agent add` 補上。舊設定裡的 `removedAgents` 已不再使用，可以刪掉。
 
 在專案資料夾內開始一次 run：
 
@@ -81,10 +99,13 @@ agentflowctl run --req "..." --manual-plan   # 計畫通過 AI 審查後，仍
 agentflowctl approve f-xxxx        # 搭配 --manual-plan
 agentflowctl status f-xxxx         # 階段、任務進度、各 agent 用量、代打紀錄
 agentflowctl list
-agentflowctl logs f-xxxx --latest
+agentflowctl logs f-xxxx           # 列出每一份 log 的編號、結果、階段、步驟、agent
+agentflowctl logs f-xxxx 7         # 解析第 7 份 log，最後附上錯誤整理（--latest 看最新一份）
+agentflowctl logs f-xxxx 7 --raw   # 原始內容（agent 的 JSON 行）
 agentflowctl resume f-xxxx         # 從暫停、Ctrl-C 或失敗處接續
 agentflowctl cancel f-xxxx
 agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保留
+agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留下的 worktree
 ```
 
 | 選項 | 作用 |
@@ -94,12 +115,31 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
 | `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
+| `-v` / `--verbose` | 執行時印出 agent 的文字、工具呼叫與專案指令；`run`、`resume`、`approve` 都適用，也可設 `AGENTFLOWCTL_VERBOSE=1` |
 
 `status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
 
+### 清除 worktree
+
+`run` 建好 worktree 就會寫入 run 紀錄，所以不論在哪一步中斷（包括安裝相依套件時），都能用 `resume` 接續，或用 `clean` 清掉。
+
+- `clean <id>`：移除該 run 的 worktree 與 `.agentflowctl/runs/<id>/`，並清掉 git 裡已失效的 worktree 登記。沒有 run 紀錄的 worktree 也能清，worktree 資料夾被手動刪掉時也一樣。
+- `clean --all`：清掉所有 `done`、`failed` 的 run，以及沒有 run 紀錄的 worktree。進行中、`paused`、`awaiting_approval` 的不動；Ctrl-C 中斷、之後不打算接續的 run，先 `cancel` 再 `clean --all`，或直接 `clean <id>`。
+
+兩者都保留 `flow/<id>` 分支，不需要時用 `git branch -D` 刪除。
+
 ### 執行中的終端機輸出
 
-agent 每次使用工具，都會印出完整的指令或主要參數，不截斷。多行指令的後續行會縮排對齊。install、測試、verify 這些專案指令也會以 `$ ` 開頭印出來：
+預設是安靜模式，只印出 `[run-id]` 開頭的階段進度（📝 🧐 ✓ ✗ ⚠️ 等）。agent 執行失敗、測試或檢查沒過時，會附上對應 log 的查看指令：
+
+```
+[f-xxxx] 🔍 執行驗證
+[f-xxxx]    ✓ typecheck
+[f-xxxx]    ✗ lint（agentflowctl logs f-xxxx 15）
+    ✗ codex 執行失敗（結束碼 1），可用 agentflowctl logs f-xxxx 16 查看
+```
+
+加上 `-v` 會另外印出 agent 每一段文字的第一行、每次工具呼叫的完整指令或主要參數（不截斷，多行指令的後續行縮排對齊），以及 install、測試、verify 這些以 `$ ` 開頭的專案指令：
 
 ```
     💬 [claude] 先讀現有的表單元件
@@ -110,11 +150,75 @@ agent 每次使用工具，都會印出完整的指令或主要參數，不截
     $ pnpm install
 ```
 
-工具參數依序取 command、檔案路徑、path、pattern、url、query，都沒有時印出整包 JSON。每次執行的完整輸出都在 `agentflowctl logs <id>`。
+工具參數依序取 command、檔案路徑、path、pattern、url、query，都沒有時印出整包 JSON。
+
+### Log
+
+每次執行 agent 或專案指令都會留一份 log，放在 `.agentflowctl/runs/<id>/logs/`，檔名是「序號-階段-步驟-agent」，專案指令的 agent 欄位是 `cmd`：
+
+```
+001-setup-install-cmd.log
+002-spec-spec-claude.log
+007-implement-T1-tests-codex.log
+008-implement-T1-red-cmd.log
+015-verify-lint-cmd.log
+```
+
+檔案保留 agent 的原始輸出，也就是各家 CLI 的 JSON 行。第一行 `# agentflowctl {...}` 記錄階段、步驟、agent 與開始時間；stderr 接在 `[stderr]` 之後；最後一行 `# exit {...}` 記錄結束碼與是否成功，沒有這行就代表還在執行或被中斷。
+
+`agentflowctl logs <id>` 列出所有 log。結果欄的 ✓ 是成功，✗ 是失敗，… 代表沒有結束紀錄：
+
+```
+  #  結果  階段          步驟                 agent       開始時間
+  1  ✓     setup         install              cmd         2026-09-26 11:29:04
+  2  ✓     spec          spec                 claude      2026-09-26 11:29:05
+  3  ✗     plan          plan                 codex       2026-09-26 11:31:40
+```
+
+`agentflowctl logs <id> <編號>` 會把原始 JSON 解析成易讀的格式：
+
+| 標記 | 內容 |
+|---|---|
+| 💬 | agent 的完整文字，不截斷 |
+| 🔧 | 工具呼叫與完整參數 |
+| 📊 | token 用量 |
+| 🏁 | 最後結果 |
+| ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
+| ❌ | adapter 不認得的錯誤事件 |
+| 📄 | 不是 JSON 的輸出行 |
+
+adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+
+最後一段「錯誤」整理出結束碼、agent 回報的失敗、錯誤事件與 stderr：
+
+```
+#3  plan / plan / codex
+開始 2026-09-26 11:31:40　結束 2026-09-26 11:31:52　結束碼 1　✗ 失敗
+檔案 /repo/.agentflowctl/runs/f-xxxx/logs/003-plan-plan-codex.log
+
+💬 先讀 spec.md 與 acceptance.json
+🔧 shell: bash -lc 'cat .flow/spec.md'
+🏁 失敗：stream disconnected before completion
+
+── 錯誤 ──
+結束碼 1
+agent 回報失敗：stream disconnected before completion
+stderr：
+   Error: stream disconnected before completion
+```
+
+執行成功時，stderr 會放在「其他輸出」段落，不算錯誤。
+
+### 出錯時怎麼查
+
+1. run 停下時印出的摘要，或 `agentflowctl status <id>`，會列出失敗的階段、原因、最後一份 log，以及最近失敗的那一份。
+2. `agentflowctl logs <id> <編號>` 看那份 log 的錯誤段落。
+3. 解析結果看不出原因時，加 `--raw` 看原始輸出。
+4. 必要時直接在 worktree（`.agentflowctl/worktrees/<id>`）裡修正，再執行 `agentflowctl resume <id>`。
 
 ## 設定
 
-專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設（安裝指令、測試指令、檢查清單預設對應 Vite + TypeScript + Vitest）。
+專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設；`install`、`test`、`checks` 沒寫時，會依專案現況偵測（見下方「專案指令的偵測」）。
 
 ```json
 {
@@ -123,6 +227,7 @@ agent 每次使用工具，都會印出完整的指令或主要參數，不截
   "tddSplit": true,
   "tieBreak": "proceed",
   "agents": {
+    "claude": { "adapter": "claude" },
     "codex": { "adapter": "codex", "model": "你要用的模型" },
     "aider": { "adapter": "command", "command": ["aider", "--yes-always", "--no-auto-commits", "--message", "{prompt}"] }
   }
@@ -131,7 +236,7 @@ agent 每次使用工具，都會印出完整的指令或主要參數，不截
 
 | 設定 | 預設 | 說明 |
 |---|---|---|
-| `cycle` | 自動偵測 | 輪替順序。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
+| `cycle` | 自動偵測 | 輪替順序。未設定時依 `agents` 的順序取已安裝的 CLI。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
 | `fixStrategy` | `ring` | `ring`：審查意見交給審查者的下一位；`author`：交回最後作者 |
 | `tddSplit` | `true` | 測試與實作是否分開 |
 | `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve` |
@@ -139,33 +244,49 @@ agent 每次使用工具，都會印出完整的指令或主要參數，不截
 | `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
 | `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
 | `maxAgentRuns` | `60` | 單一 run 最多執行幾次 agent |
-| `install` / `test` / `checks` | 見 `src/schemas.ts` | verify 階段實際執行的指令 |
-| `agents` | 內建 claude、codex、gemini | 覆寫內建 agent，或用 `command` adapter 接上其他 CLI |
-| `removedAgents` | `[]` | 移除的內建 agent，不會被自動偵測、不能放進輪替。通常用 `agent remove` 寫入 |
+| `install` / `test` / `checks` | 依專案偵測 | 安裝、測試與 verify 階段實際執行的指令 |
+| `agents` | `{}` | 可用的 agent，沒有內建的。每個都要指定 adapter（`claude`、`codex`、`gemini`，或用 `command` 接上其他 CLI） |
 
 verify 失敗（型別、lint、建置）一律交回最後作者。審查意見才依 `fixStrategy` 決定修正者。
 
+### 專案指令的偵測
+
+`install`、`test`、`checks` 沒寫在 `flow.config.json` 時，每次讀設定都會依專案現況推出指令，不寫檔。有寫的欄位一律照你的設定。
+
+- 套件管理器：先看 `package.json` 的 `packageManager`，再看 lockfile（`pnpm-lock.yaml`、`yarn.lock`、`bun.lock`／`bun.lockb`、`package-lock.json`），都沒有就用 npm。
+- `install`：`pnpm install`、`yarn install`、`bun install` 或 `npm install --no-audit --no-fund`。不鎖 lockfile，因為實作時 agent 可能新增依賴。
+- `checks`：typecheck、lint、test、build 四項。`package.json` 有對應的 script（`typecheck`／`type-check`、`lint`、`test`、`build`）就用 `<pm> run <script>`，否則用 `tsc --noEmit`、`eslint .`、`vitest run`、`vite build`，前面加上 `npx`、`pnpm exec`、`yarn` 或 `bunx`。
+- `test`：`vitest run`，前綴同上。
+
+`run` 建立 worktree 後會印出這次偵測到的指令：
+
+```
+[f-xxxx] 🔧 依專案偵測指令：pnpm（依 package.json 的 packageManager）
+[f-xxxx]    install：pnpm install
+[f-xxxx]    checks.typecheck：pnpm run type-check
+```
+
 ### 用指令管理 agent
 
 `agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
 
 ```bash
-agentflowctl agent list                                   # 內建與自訂 agent、是否已安裝、輪替位置
+agentflowctl agent setup                                  # 互動設定 claude、codex、gemini 與輪替順序
+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`。
+- `remove` 會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回從 `agents` 自動偵測。
 - `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
+- `setup` 遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍放進這次的輪替順序。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
 
 已建立的 run 會沿用建立時的輪替順序，不受這些修改影響。
 
@@ -222,7 +343,7 @@ Agent 的最後回覆要附上 XML 中繼資料：
 </result>
 ```
 
-`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
+`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log，可用 `agentflowctl logs` 查看。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
 
 ## Adapter
 
@@ -237,11 +358,7 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 各家讀的專案說明檔不同：Claude Code 讀 `CLAUDE.md`，Codex 讀 `AGENTS.md`，Gemini 讀 `GEMINI.md`。把專案慣例寫在 `AGENTS.md`，另外兩個檔案各用一行引用它。agentflowctl 的 prompt 在 `prompts/`，不依賴任何一家的 skills 或 plugins。
 
-## 登入、額度與代打
-
-只支援各家 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）不受影響。
+## 額度與代打
 
 上限是執行次數（`maxAgentRuns`，預設 60），不是金額。`status` 會列出各 agent 的執行次數與 token 數。
 
@@ -266,7 +383,7 @@ agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell
 | 環境 | 適合的用法 |
 |---|---|
 | 自己的電腦 | 自己的專案、自己寫的需求。剛開始可以加 `--manual-plan`，確認審查品質後再拿掉 |
-| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的訂閱登入 |
+| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的登入 |
 | Claude Code、Codex 裡面 | 讓它們用 shell 執行 `npx agentflowctl` |
 
 沒有容器隔離時，verify 會在你的電腦上執行 agent 寫出來的程式碼。Gemini 在無人值守時是 yolo 模式。處理外部 issue，或需求文字不是你自己寫的，放到可丟棄的環境。AI 審查計畫擋不住夾在需求裡的指示。
@@ -279,8 +396,11 @@ src/
   engine.ts         狀態機與各階段
   roles.ts          輪替規則（含計畫修正者與仲裁者）
   runner.ts         執行 agent、正規化結果、執行專案指令
+  logs.ts           log 檔名、檔頭檔尾、列表與解析
   agents/           claude、codex、gemini、command
+  setup.ts          agent setup 互動精靈
   git.ts            worktree 與 git 操作
+  cleanup.ts        clean：移除 worktree 與 run 紀錄
   store.ts          狀態、用量、代打紀錄
   tasks.ts          任務 DAG
   schemas.ts        zod schema

package/dist/agentConfig.js

@@ -1,20 +1,10 @@
 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;
-}
+const isDefined = (cfg, name) => name in agentsOf(cfg);
 /** 只留下有值的欄位，驗證後回傳 */
 function buildAgent(base, patch) {
     const next = { ...base };
@@ -37,10 +27,7 @@ export function addAgent(cfg, name, def) {
     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: [] };
+    return { cfg: { ...cfg, agents: { ...agentsOf(cfg), [name]: buildAgent({ adapter }, patch) } }, changes: [] };
 }
 export function setAgent(cfg, name, patch) {
     if (!isDefined(cfg, name))
@@ -49,8 +36,7 @@ export function setAgent(cfg, name, patch) {
         throw new Error("沒有要修改的欄位（--adapter、--model、--extra-arg 或 -- <command>）");
     }
     const agents = agentsOf(cfg);
-    // 內建 agent 第一次修改時，新增一筆覆寫設定
-    const base = { ...(agents[name] ?? { adapter: name }) };
+    const base = { ...agents[name] };
     const changes = [];
     if (patch.adapter !== undefined && patch.adapter !== base.adapter) {
         const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && patch[f] === undefined);
@@ -66,10 +52,7 @@ export function removeAgent(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 next = { ...cfg, agents };
     const changes = [];
     const cycle = cfg.cycle;
     if (cycle?.includes(name)) {
@@ -80,7 +63,7 @@ export function removeAgent(cfg, name) {
         }
         else {
             delete next.cycle;
-            changes.push("輪替順序因此變空，已刪除 cycle，改回自動偵測已安裝的 CLI");
+            changes.push("輪替順序因此變空，已刪除 cycle，改回從 agents 自動偵測已安裝的 CLI");
         }
     }
     return { cfg: next, changes };

package/dist/agents/index.js

@@ -3,8 +3,4 @@ import { codex } from "./codex.js";
 import { command } from "./command.js";
 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/cleanup.js

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { git, removeWorktree } from "./git.js";
+import { projectRoot, runDir, runsDir, worktreeDir, worktreesDir } from "./paths.js";
+import { getRun } from "./store.js";
+/**
+ * 移除一個 run 的 worktree 與紀錄，分支保留。
+ * 不需要 state.json：中斷在建立 worktree 之後、寫入紀錄之前留下的孤兒也能清。
+ * 回傳是否真的找到並移除了東西。
+ */
+export async function cleanRun(id) {
+    // id 會拼進要遞迴刪除的路徑，擋掉空字串、..、斜線
+    if (!/^[\w-]+$/.test(id))
+        throw new Error(`不合法的 run id：${id}`);
+    const root = projectRoot();
+    const wt = worktreeDir(id);
+    const found = existsSync(wt) || existsSync(runDir(id));
+    if (existsSync(wt)) {
+        // git 不認得這個資料夾時（登記已被 prune、或 worktree add 做到一半）改成直接刪
+        await removeWorktree(root, wt).catch(() => rmSync(wt, { recursive: true, force: true }));
+    }
+    rmSync(runDir(id), { recursive: true, force: true });
+    // 清掉資料夾已不存在的 worktree 登記，否則同名分支之後無法再 checkout
+    const before = await git(root, "worktree", "list", "--porcelain");
+    await git(root, "worktree", "prune");
+    const pruned = before !== (await git(root, "worktree", "list", "--porcelain"));
+    return found || pruned;
+}
+/** 已結束、可以安全清掉的階段；其他階段可能還在跑，或要 resume／approve */
+const FINISHED = ["done", "failed"];
+/**
+ * `clean --all` 要清的 run：已結束的，加上沒有 state.json 的孤兒（stage 為 undefined）。
+ * 讀不懂的 state.json 不算孤兒，保留給使用者自己判斷。
+ */
+export function cleanableRuns() {
+    const ids = new Set();
+    for (const dir of [runsDir(), worktreesDir()])
+        if (existsSync(dir))
+            for (const id of readdirSync(dir))
+                ids.add(id);
+    const out = [];
+    for (const id of [...ids].sort()) {
+        let stage;
+        try {
+            stage = getRun(id)?.stage;
+        }
+        catch {
+            continue;
+        }
+        if (stage === undefined || FINISHED.includes(stage))
+            out.push({ id, stage });
+    }
+    return out;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/cli.js

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { builtinAgents } from "./agents/index.js";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { config } from "./config.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 { probeAgent, resolveAgent, runCommand } from "./runner.js";
+import { addWorktree, git } from "./git.js";
+import { cleanableRuns, cleanRun } from "./cleanup.js";
+import { describeDetected, detectProjectDefaults } from "./detect.js";
+import { CMD_AGENT, listLogs, localTime, logMark, nextLogFile, renderLog } from "./logs.js";
+import { flowDir, logDir, projectRoot, worktreeDir } from "./paths.js";
 import { TaskList } from "./schemas.js";
 import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent } from "./store.js";
 import { readJsonFile } from "./util.js";
+import { runSetup, SETUP_ADAPTERS } from "./setup.js";
 import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
 function mustGetRun(id) {
     const run = getRun(id);
@@ -40,7 +46,14 @@ function printSummary(run) {
     if (run.stage === "failed") {
         console.log(`失敗於   ${run.failedStage ?? "?"}`);
         console.log(`原因     ${run.failureReason ?? "?"}`);
-        console.log(`\n可檢查 ${logDir(run.id)}，必要時直接在 worktree 裡修正，再執行 agentflowctl resume ${run.id}`);
+        const logs = listLogs(logDir(run.id));
+        const last = logs.at(-1);
+        const lastFailed = logs.filter((e) => e.footer && !e.footer.ok).at(-1);
+        if (last)
+            console.log(`最後的 log #${last.seq} ${logMark(last)}（agentflowctl logs ${run.id} ${last.seq}）`);
+        if (lastFailed && lastFailed !== last)
+            console.log(`最近失敗的 log #${lastFailed.seq}（agentflowctl logs ${run.id} ${lastFailed.seq}）`);
+        console.log(`\n必要時直接在 worktree 裡修正，再執行 agentflowctl resume ${run.id}`);
     }
     if (run.stage === "paused") {
         console.log(`暫停於   ${run.pausedStage ?? "?"}`);
@@ -61,17 +74,26 @@ async function resolveCycle(flag) {
         }
         return wanted;
     }
+    // 沒有內建 agent：只從 agents 裡定義的挑出已安裝的
+    const defined = Object.keys(cfg.agents);
+    if (!defined.length)
+        throw new Error("還沒有設定任何 agent，請先用 agentflowctl agent setup 互動設定，或用 agent add <name> --adapter <adapter> 新增");
     const found = [];
-    for (const name of builtinAgents(cfg.removedAgents))
+    for (const name of defined)
         if (await probeAgent(resolveAgent(cfg, name)))
             found.push(name);
     if (!found.length)
-        throw new Error(`沒有偵測到任何 agent CLI（${builtinAgents(cfg.removedAgents).join("、") || "內建 agent 都已移除"}），可用 agentflowctl doctor 檢查`);
+        throw new Error(`設定的 agent（${defined.join("、")}）都沒有偵測到已安裝的 CLI，可用 agentflowctl doctor 檢查`);
     return found;
 }
 const program = new Command()
     .name("agentflowctl")
-    .description("在專案資料夾內執行的 Agent 開發流程：規格 → 計畫 → TDD 實作 → 驗證 → 審查 → PR");
+    .description("在專案資料夾內執行的 Agent 開發流程：規格 → 計畫 → TDD 實作 → 驗證 → 審查 → PR")
+    .option("-v, --verbose", "執行時印出 agent 的文字、工具呼叫與專案指令（預設只印階段進度）")
+    .hook("preAction", (cmd) => {
+    if (cmd.opts().verbose)
+        config.verbose = true;
+});
 program
     .command("run")
     .description("在目前的專案建立並執行新的 flow")
@@ -95,12 +117,9 @@ program
     console.log(`[${id}] 🌿 從 ${base} 建立 worktree（分支 ${branch}）`);
     await addWorktree(root, worktreeDir(id), base, branch);
     console.log(`[${id}] 🤝 agent 輪替順序：${cycle.join(" → ")}`);
-    // 先裝好相依套件：有些 agent 的沙箱不能連網，無法自己安裝
     const cfg = loadRepoConfig();
-    const install = await runCommand({ runId: id, cwd: worktreeDir(id), logFile: join(logDir(id), "install.log") }, cfg.install);
-    if (!install.ok)
-        console.log(`[${id}] ⚠️  安裝相依套件失敗，稍後 verify 階段會再試一次（見 ${join(logDir(id), "install.log")}）`);
     const now = new Date().toISOString();
+    // worktree 一建好就寫入紀錄：之後在任何地方中斷，都能用 resume 接續或用 clean 清掉
     const run = saveRun({
         id,
         baseBranch: base,
@@ -116,6 +135,12 @@ program
         createdAt: now,
         updatedAt: now,
     });
+    for (const line of describeDetected(readRawConfig(configPath()), detectProjectDefaults(root)))
+        console.log(`[${id}] ${line}`);
+    // 先裝好相依套件：有些 agent 的沙箱不能連網，無法自己安裝
+    const install = await runCommand({ runId: id, cwd: worktreeDir(id), logFile: nextLogFile(logDir(id), "setup", "install", CMD_AGENT), stage: "setup", step: "install" }, cfg.install);
+    if (!install.ok)
+        console.log(`[${id}] ⚠️  安裝相依套件失敗，稍後 verify 階段會再試一次（agentflowctl logs ${id} ${install.seq}）`);
     await drive(run);
 });
 program
@@ -152,14 +177,29 @@ program
     console.log(`已取消 ${id}`);
 });
 program
-    .command("clean <id>")
-    .description("移除 run 的 worktree 與紀錄（分支會保留）")
-    .action(async (id) => {
-    mustGetRun(id);
-    if (existsSync(worktreeDir(id)))
-        await removeWorktree(projectRoot(), worktreeDir(id));
-    rmSync(runDir(id), { recursive: true, force: true });
-    console.log(`已清除 ${id}，分支仍保留，不需要時可用 git branch -D 刪除`);
+    .command("clean [id]")
+    .description("移除 run 的 worktree 與紀錄（分支會保留）；--all 清掉所有已結束的 run 與中斷留下的孤兒 worktree")
+    .option("--all", "清除所有 done、failed 的 run，以及沒有紀錄的 worktree；進行中、暫停、等待核准的不動", false)
+    .action(async (id, opts) => {
+    if (opts.all === Boolean(id))
+        throw new Error("請指定 run id，或使用 --all（兩者擇一）");
+    if (id) {
+        if (!(await cleanRun(id)))
+            throw new Error(`找不到 run：${id}`);
+        console.log(`已清除 ${id}，分支仍保留，不需要時可用 git branch -D 刪除`);
+        return;
+    }
+    const targets = cleanableRuns();
+    if (!targets.length) {
+        await git(projectRoot(), "worktree", "prune");
+        console.log("沒有可清除的 run");
+        return;
+    }
+    for (const t of targets) {
+        await cleanRun(t.id);
+        console.log(`已清除 ${t.id}（${t.stage ?? "沒有紀錄，可能是建立時中斷"}）`);
+    }
+    console.log(`\n共清除 ${targets.length} 個，分支仍保留，不需要時可用 git branch -D 刪除`);
 });
 program
     .command("status <id>")
@@ -207,26 +247,25 @@ function applyEdit(edit, done) {
 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 ?? []);
-    const names = [...new Set([...builtinAgents(cfg.removedAgents), ...Object.keys(cfg.agents)])];
+    const names = Object.keys(cfg.agents);
+    if (!names.length)
+        console.log("還沒有設定任何 agent，請用 agent setup 互動設定，或用 agent add <name> --adapter <adapter> 新增");
     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(" ")}`);
+        console.log(`${ok ? "✅" : "❌"} ${name.padEnd(14)} ${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 ? "" : "（自動偵測）"}`);
 });
@@ -250,7 +289,7 @@ agent
 });
 agent
     .command("remove <name>")
-    .description("刪除 agent（含內建的 claude、codex、gemini），一併從輪替移除；內建的可用 agent add 加回")
+    .description("刪除 agent，一併從輪替移除")
     .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已移除 ${name}`));
 agent
     .command("cycle [names]")
@@ -269,12 +308,36 @@ agent
             console.log(`⚠️  ${n} 目前找不到可執行的 CLI，run 會失敗，請先安裝或用 agent set 修正`);
     }
 });
-program
-    .command("doctor")
-    .description("檢查可用的 agent CLI 與目前的輪替設定")
+agent
+    .command("setup")
+    .description("互動式設定：偵測已安裝的 claude、codex、gemini，逐一選擇要不要加入並設定輪替順序")
     .action(async () => {
+    if (!stdin.isTTY)
+        throw new Error("agent setup 需要互動式終端機，請改用 agent add");
+    const detected = {};
+    for (const a of SETUP_ADAPTERS)
+        detected[a] = await probeAgent({ adapter: a, extraArgs: [] });
+    const rl = createInterface({ input: stdin, output: stdout });
+    let edit;
+    try {
+        edit = await runSetup(readRawConfig(configPath()), { ask: (q) => rl.question(q), detected, log: (l) => console.log(l) });
+    }
+    finally {
+        rl.close();
+    }
+    if (!edit)
+        return;
+    const result = edit;
+    applyEdit(() => result, "設定完成");
+    console.log("");
+    await doctor();
+});
+/** 檢查設定的 agent 是否已安裝，印出輪替順序與主要設定 */
+async function doctor() {
     const cfg = loadRepoConfig();
-    const names = [...new Set([...builtinAgents(cfg.removedAgents), ...Object.keys(cfg.agents)])];
+    const names = Object.keys(cfg.agents);
+    if (!names.length)
+        console.log("還沒有設定任何 agent，請用 agent setup 互動設定，或用 agent add <name> --adapter <adapter> 新增");
     for (const name of names) {
         const def = resolveAgent(cfg, name);
         const ok = await probeAgent(def);
@@ -286,15 +349,11 @@ program
     catch (e) {
         console.log(`\n${e.message}`);
     }
-    const leaked = API_KEY_VARS.filter((k) => process.env[k]);
-    console.log("\n登入方式：訂閱登入（執行 agent 時會移除 API key）");
-    if (leaked.length) {
-        console.log(`⚠️  環境中有 ${leaked.join("、")}，agentflowctl 執行 agent 時會移除，但你自己直接執行 CLI 時仍可能改走 API 計費`);
-    }
-    console.log(`單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
+    console.log(`\n單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
     console.log(`程式碼審查人數：${cfg.reviewQuorum}　計畫審查人數：${cfg.planReviewQuorum}　計畫仲裁：${cfg.planArbiter ? "開啟" : "關閉"}`);
-});
+}
+program.command("doctor").description("檢查可用的 agent CLI 與目前的輪替設定").action(doctor);
 program
     .command("list")
     .description("列出這個專案的所有 run")
@@ -305,18 +364,29 @@ program
     }
 });
 program
-    .command("logs <id>")
-    .description("列出 log 檔，或顯示最新一份")
-    .option("--latest", "顯示最新一份 log 的內容", false)
-    .action((id, opts) => {
+    .command("logs <id> [seq]")
+    .description("列出 log；指定編號（或 --latest）時顯示解析後的內容，最後附上錯誤整理")
+    .option("--latest", "顯示最新一份 log", false)
+    .option("--raw", "顯示原始內容（agent 的 JSON 行）", false)
+    .action((id, seq, opts) => {
     mustGetRun(id);
-    const dir = logDir(id);
-    const files = existsSync(dir) ? readdirSync(dir).sort() : [];
-    if (!files.length)
+    const logs = listLogs(logDir(id));
+    if (!logs.length)
         return console.log("還沒有 log");
-    if (!opts.latest)
-        return files.forEach((f) => console.log(join(dir, f)));
-    console.log(readFileSync(join(dir, files.at(-1)), "utf8"));
+    if (!seq && !opts.latest) {
+        console.log("  #  結果  階段          步驟                 agent       開始時間");
+        for (const e of logs) {
+            const h = e.header;
+            console.log(`${String(e.seq).padStart(3)}  ${logMark(e).padEnd(4)}  ${(h?.stage ?? "?").padEnd(12)}  ${(h?.step ?? "?").padEnd(19)}  ${(h?.agent ?? "?").padEnd(10)}  ${localTime(h?.startedAt)}`);
+        }
+        console.log(`\n查看內容：agentflowctl logs ${id} <編號>（加 --raw 看原始 JSON）`);
+        return;
+    }
+    const entry = seq ? logs.find((e) => e.seq === Number(seq)) : logs.at(-1);
+    if (!entry)
+        throw new Error(`找不到 log #${seq}（共 ${logs.length} 份，可用 agentflowctl logs ${id} 列出）`);
+    const text = readFileSync(entry.file, "utf8");
+    console.log(opts.raw ? text : renderLog(text, entry.file));
 });
 program.parseAsync().catch((err) => {
     console.error(`錯誤：${err.message}`);

package/dist/config.js

@@ -5,5 +5,7 @@ export const config = {
     maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 80),
     /** 同一個關卡連續失敗幾次後停止 */
     maxAttempts: Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 3),
+    /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；預設安靜，-v 或 AGENTFLOWCTL_VERBOSE=1 開啟 */
+    verbose: process.env.AGENTFLOWCTL_VERBOSE === "1",
 };
 //# sourceMappingURL=config.js.map

package/dist/detect.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { RepoConfig } from "./schemas.js";
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+];
+/** 不鎖 lockfile：implement 階段 agent 可能新增依賴 */
+const INSTALL = {
+    npm: RepoConfig.parse({}).install,
+    pnpm: "pnpm install",
+    yarn: "yarn install",
+    bun: "bun install",
+};
+/** 執行專案內 bin 的前綴，取代預設指令裡的 npx */
+const EXEC = { npm: "npx", pnpm: "pnpm exec", yarn: "yarn", bun: "bunx" };
+/** 每項檢查會找的 script 名稱，依序取第一個存在的 */
+const CHECK_SCRIPTS = {
+    typecheck: ["typecheck", "type-check"],
+    lint: ["lint"],
+    test: ["test"],
+    build: ["build"],
+};
+function readPackageJson(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return pkg && typeof pkg === "object" ? pkg : {};
+    }
+    catch {
+        return {};
+    }
+}
+function detectManager(root, pkg) {
+    if (typeof pkg.packageManager === "string") {
+        const name = pkg.packageManager.split("@")[0];
+        if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") {
+            return { manager: name, source: "package.json 的 packageManager" };
+        }
+    }
+    for (const [file, manager] of LOCKFILES) {
+        if (existsSync(join(root, file)))
+            return { manager, source: file };
+    }
+    return { manager: "npm", source: "預設" };
+}
+const withExec = (cmd, manager) => cmd.replace(/^npx /, `${EXEC[manager]} `);
+export function detectProjectDefaults(root) {
+    const pkg = readPackageJson(root);
+    const { manager, source } = detectManager(root, pkg);
+    const defaults = RepoConfig.parse({});
+    const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    const checks = defaults.checks.map(({ name, cmd }) => {
+        const script = CHECK_SCRIPTS[name]?.find((s) => typeof scripts[s] === "string");
+        return { name, cmd: script ? `${manager} run ${script}` : withExec(cmd, manager) };
+    });
+    return { manager, source, install: INSTALL[manager], test: withExec(defaults.test, manager), checks };
+}
+/** 補上原始設定裡沒寫的 install、test、checks；不是物件就原樣回傳，交給 schema 報錯 */
+export function withProjectDefaults(raw, detected) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const { install, test, checks } = detected;
+    return { install, test, checks, ...raw };
+}
+/** run 開始時印出的說明：只列出這次用了偵測結果的欄位 */
+export function describeDetected(raw, detected) {
+    const lines = [];
+    if (!("install" in raw))
+        lines.push(`   install：${detected.install}`);
+    if (!("test" in raw))
+        lines.push(`   test：${detected.test}`);
+    if (!("checks" in raw))
+        lines.push(...detected.checks.map((c) => `   checks.${c.name}：${c.cmd}`));
+    if (!lines.length)
+        return [];
+    const why = detected.source === "預設" ? "預設" : `依 ${detected.source}`;
+    return [`🔧 依專案偵測指令：${detected.manager}（${why}）`, ...lines];
+}
+//# sourceMappingURL=detect.js.map

package/dist/engine.js

@@ -1,8 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { z } from "zod";
 import { config } from "./config.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";
+import { CMD_AGENT, nextLogFile } from "./logs.js";
 import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
@@ -12,11 +15,11 @@ import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
 const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
+const logHint = (run, seq) => `（agentflowctl logs ${run.id} ${seq}）`;
 const flowFile = (run, name) => join(flowDir(run.id), name);
 const to = (run, stage) => ({ ...run, stage });
-function target(run, name) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return { runId: run.id, cwd: worktreeDir(run.id), logFile: join(logDir(run.id), `${stamp}-${name}.log`) };
+function target(run, step, agent) {
+    return { runId: run.id, cwd: worktreeDir(run.id), logFile: nextLogFile(logDir(run.id), run.stage, step, agent), stage: run.stage, step };
 }
 /** 額度用完而必須停下：審查類步驟，或所有 agent 的額度都用完 */
 export class QuotaPause extends Error {
@@ -43,7 +46,7 @@ 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);
+        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);
@@ -72,6 +75,7 @@ function readFeedback(run) {
 function retry(run, key, reason, backTo) {
     const n = (run.attempts[key] ?? 0) + 1;
     const attempts = { ...run.attempts, [key]: n };
+    mkdirSync(flowDir(run.id), { recursive: true });
     writeFileSync(flowFile(run, "feedback.md"), `# 前次嘗試未通過（第 ${n} 次）\n\n${reason}\n`);
     if (n >= config.maxAttempts) {
         return { ...run, attempts, stage: "failed", failedStage: backTo, failureReason: `${key} 連續失敗 ${n} 次：${tail(reason, 500)}` };
@@ -86,11 +90,14 @@ function succeed(run, key, next) {
     return { ...run, attempts, stage: next };
 }
 /** 設定檔放在主專案根目錄，未 commit 的修改也會生效 */
+/** 讀取 flow.config.json；沒寫的 install、test、checks 依專案現況偵測 */
 export function loadRepoConfig() {
-    const p = join(projectRoot(), "flow.config.json");
+    const root = projectRoot();
+    const detected = detectProjectDefaults(root);
+    const p = join(root, "flow.config.json");
     if (!existsSync(p))
-        return RepoConfig.parse({});
-    const r = readJsonFile(p, RepoConfig);
+        return RepoConfig.parse(withProjectDefaults({}, detected));
+    const r = readJsonFile(p, z.preprocess((raw) => withProjectDefaults(raw, detected), RepoConfig));
     if (!r.ok)
         throw new Error(r.error);
     return r.data;
@@ -351,7 +358,7 @@ async function implementStage(run) {
             await resetTo(repo, before);
             return retry(run, key, `沒有新增或修改任何符合 /${cfg.testPattern}/ 的測試檔。`, "implement");
         }
-        const red = await runCommand(target(run, `${task.id}-red`), testCmd);
+        const red = await runCommand(target(run, `${task.id}-red`, CMD_AGENT), testCmd);
         if (red.ok) {
             await resetTo(repo, before);
             return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
@@ -376,9 +383,11 @@ async function implementStage(run) {
         await resetTo(repo, testsCommit);
         return retry(run, key, `實作階段不可修改測試檔，已還原你的變更：${touched.join(", ")}`, "implement");
     }
-    const green = await runCommand(target(run, `${task.id}-green`), testCmd);
-    if (!green.ok)
+    const green = await runCommand(target(run, `${task.id}-green`, CMD_AGENT), testCmd);
+    if (!green.ok) {
+        info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
+    }
     info(run, `🟢 [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
@@ -393,14 +402,15 @@ async function verifyStage(run) {
     info(run, "🔍 執行驗證");
     const cfg = loadRepoConfig();
     const results = [];
-    const install = await runCommand(target(run, "verify-install"), cfg.install);
+    const install = await runCommand(target(run, "install", CMD_AGENT), cfg.install);
     if (!install.ok) {
+        info(run, `   ✗ install${logHint(run, install.seq)}`);
         results.push({ name: "install", ok: false, output: tail(install.output) });
     }
     else {
         for (const check of cfg.checks) {
-            const r = await runCommand(target(run, `verify-${check.name}`), check.cmd);
-            info(run, `   ${r.ok ? "✓" : "✗"} ${check.name}`);
+            const r = await runCommand(target(run, check.name, CMD_AGENT), check.cmd);
+            info(run, `   ${r.ok ? "✓" : "✗"} ${check.name}${r.ok ? "" : logHint(run, r.seq)}`);
             results.push({ name: check.name, ok: r.ok, output: tail(r.output, 3000) });
         }
     }

package/dist/logs.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ADAPTERS } from "./agents/index.js";
+import { str, tryJson } from "./agents/types.js";
+/**
+ * 每次執行 agent 或專案指令都寫成一份 log：
+ * - 檔名：<三位數序號>-<階段>-<步驟>-<agent>.log，專案指令的 agent 欄位是 cmd
+ * - 第一行：`# agentflowctl {...}`，記錄階段、步驟、agent、開始時間
+ * - 中間：agent 的原始 stdout（JSON 行）或指令輸出，原樣保存；stderr 接在 `[stderr]` 之後
+ * - 最後一行：`# exit {...}`，記錄結束碼與是否成功；沒有這行代表還在執行或被中斷
+ */
+export const HEADER_PREFIX = "# agentflowctl ";
+export const FOOTER_PREFIX = "# exit ";
+export const STDERR_MARK = "[stderr]";
+/** 專案指令（install、測試、checks）的 agent 欄位 */
+export const CMD_AGENT = "cmd";
+const segment = (s) => s.replace(/[\s/\\:*?"<>|]+/g, "_");
+/** 下一份 log 的完整路徑；序號接在目錄裡最大的序號之後 */
+export function nextLogFile(dir, stage, step, agent) {
+    const seqs = existsSync(dir) ? readdirSync(dir).map((f) => Number(f.match(/^(\d+)-/)?.[1] ?? 0)) : [];
+    const seq = Math.max(0, ...seqs) + 1;
+    return join(dir, `${String(seq).padStart(3, "0")}-${segment(stage)}-${segment(step)}-${segment(agent)}.log`);
+}
+export const logSeq = (file) => Number(file.split(/[\\/]/).at(-1)?.match(/^(\d+)-/)?.[1] ?? 0);
+export const headerLine = (h) => `${HEADER_PREFIX}${JSON.stringify(h)}`;
+export const footerLine = (f) => `${FOOTER_PREFIX}${JSON.stringify(f)}`;
+function parseLog(text) {
+    const out = { body: [], stderr: [] };
+    let inStderr = false;
+    for (const line of text.split("\n")) {
+        if (line.startsWith(HEADER_PREFIX) && !out.header)
+            out.header = tryJson(line.slice(HEADER_PREFIX.length));
+        else if (line.startsWith(FOOTER_PREFIX))
+            out.footer = tryJson(line.slice(FOOTER_PREFIX.length));
+        else if (line === STDERR_MARK)
+            inStderr = true;
+        else
+            (inStderr ? out.stderr : out.body).push(line);
+    }
+    while (out.stderr.at(-1) === "")
+        out.stderr.pop();
+    while (out.body.at(-1) === "")
+        out.body.pop();
+    return out;
+}
+/** 依序號列出 run 的所有 log，只讀檔頭與檔尾 */
+export function listLogs(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => /^\d+-.*\.log$/.test(f))
+        .map((f) => {
+        const file = join(dir, f);
+        const { header, footer } = parseLog(readFileSync(file, "utf8"));
+        return { seq: logSeq(f), file, header, footer };
+    })
+        .sort((a, b) => a.seq - b.seq);
+}
+/** 執行結果：✓ 成功、✗ 失敗、… 沒有檔尾（還在執行或被中斷） */
+export const logMark = (e) => (!e.footer ? "…" : e.footer.ok ? "✓" : "✗");
+/** ISO 時間轉成本地時間 YYYY-MM-DD HH:mm:ss */
+export function localTime(iso) {
+    const d = iso ? new Date(iso) : undefined;
+    if (!d || Number.isNaN(d.getTime()))
+        return "?";
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+const clip = (s, max = 800) => (s.length <= max ? s : `${s.slice(0, max)}…（共 ${s.length} 字）`);
+const indent = (s, pad = "   ") => s.split("\n").join(`\n${pad}`);
+/** 從沒被 adapter 認得的 JSON 事件裡找錯誤：頂層的 error 類事件算失敗，工具回報的錯誤只當作提示 */
+function findError(ev) {
+    const pick = (o) => {
+        const err = o.error;
+        const nested = err && typeof err === "object" ? str(err.message) : undefined;
+        const content = Array.isArray(o.content)
+            ? o.content.map((c) => (c && typeof c === "object" ? str(c.text) : str(c))).filter(Boolean).join("\n")
+            : str(o.content);
+        return nested ?? str(err) ?? str(o.message) ?? (content || undefined) ?? str(o.result) ?? JSON.stringify(o);
+    };
+    if (ev.is_error === true || ev.error || /error|fail/i.test(str(ev.type) ?? "") || /error|fail/i.test(str(ev.subtype) ?? "")) {
+        return { message: clip(pick(ev)), fatal: true };
+    }
+    const walk = (v, depth) => {
+        if (!v || typeof v !== "object" || depth > 4)
+            return undefined;
+        if (!Array.isArray(v) && v.is_error === true)
+            return v;
+        for (const child of Object.values(v)) {
+            const hit = walk(child, depth + 1);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    const hit = walk(ev, 0);
+    return hit ? { message: clip(pick(hit)), fatal: false } : undefined;
+}
+function renderEvent(ev) {
+    switch (ev.kind) {
+        case "text":
+            return `💬 ${indent(ev.text.trim())}`;
+        case "tool":
+            return `🔧 ${ev.name}${ev.detail ? `: ${indent(ev.detail.trim())}` : ""}`;
+        case "usage":
+            return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens`;
+        case "done":
+            return `🏁 ${ev.ok ? "完成" : "失敗"}${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`;
+    }
+}
+/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見 */
+export function renderLog(text, file = "") {
+    const { header, footer, body, stderr } = parseLog(text);
+    const out = [];
+    const errors = [];
+    const title = header
+        ? `${header.stage} / ${header.step} / ${header.agent}${header.adapter && header.adapter !== header.agent ? `（adapter ${header.adapter}）` : ""}`
+        : "（沒有檔頭）";
+    out.push(`${logSeq(file) ? `#${logSeq(file)}  ` : ""}${title}`);
+    out.push(`開始 ${localTime(header?.startedAt)}　` +
+        (footer ? `結束 ${localTime(footer.endedAt)}　結束碼 ${footer.code}　${footer.ok ? "✓ 成功" : "✗ 失敗"}` : "… 沒有結束紀錄（還在執行或被中斷）"));
+    if (file)
+        out.push(`檔案 ${file}`);
+    out.push("");
+    const adapter = header?.adapter ? ADAPTERS[header.adapter] : undefined;
+    if (!adapter || header?.agent === CMD_AGENT) {
+        out.push(...body);
+    }
+    else {
+        let skipped = 0;
+        for (const line of body) {
+            if (!line.trim())
+                continue;
+            const events = adapter.parse(line);
+            if (events.length) {
+                for (const ev of events) {
+                    const s = renderEvent(ev);
+                    if (s)
+                        out.push(s);
+                    if (ev.kind === "done" && !ev.ok)
+                        errors.push(`agent 回報失敗${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`);
+                }
+                continue;
+            }
+            const json = tryJson(line);
+            if (!json) {
+                out.push(`📄 ${line}`);
+                continue;
+            }
+            const err = findError(json);
+            if (!err) {
+                skipped++;
+                continue;
+            }
+            out.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
+            if (err.fatal)
+                errors.push(`錯誤事件：${indent(err.message)}`);
+        }
+        if (skipped)
+            out.push(`（另有 ${skipped} 行其他事件未顯示，可用 --raw 查看）`);
+    }
+    if (footer && footer.code !== 0)
+        errors.unshift(`結束碼 ${footer.code}`);
+    if (footer && !footer.ok && !errors.length)
+        errors.push("執行未通過（沒有更多錯誤訊息）");
+    const stderrText = stderr.length ? `stderr：\n   ${indent(clip(stderr.join("\n"), 4000))}` : undefined;
+    if (errors.length)
+        out.push("", "── 錯誤 ──", ...errors, ...(stderrText ? [stderrText] : []));
+    else if (stderrText)
+        out.push("", "── 其他輸出 ──", stderrText);
+    return out.join("\n");
+}
+//# sourceMappingURL=logs.js.map

package/dist/paths.js

@@ -14,9 +14,11 @@ export function projectRoot() {
     return root;
 }
 export const agentflowctlDir = () => join(projectRoot(), ".agentflowctl");
-export const runDir = (id) => join(agentflowctlDir(), "runs", id);
+export const runsDir = () => join(agentflowctlDir(), "runs");
+export const runDir = (id) => join(runsDir(), id);
 export const logDir = (id) => join(runDir(id), "logs");
 /** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
-export const worktreeDir = (id) => join(agentflowctlDir(), "worktrees", id);
+export const worktreesDir = () => join(agentflowctlDir(), "worktrees");
+export const worktreeDir = (id) => join(worktreesDir(), id);
 export const flowDir = (id) => join(worktreeDir(id), ".flow");
 //# sourceMappingURL=paths.js.map

package/dist/proc.js

@@ -1,12 +1,9 @@
 import { spawn } from "node:child_process";
 export function exec(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const env = { ...process.env, ...opts.env };
-        for (const key of opts.unsetEnv ?? [])
-            delete env[key];
         const child = spawn(cmd, args, {
             cwd: opts.cwd,
-            env,
+            env: { ...process.env, ...opts.env },
             shell: opts.shell ?? false,
         });
         let stdout = "";

package/dist/runner.js

@@ -1,20 +1,12 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
-import { ADAPTERS, builtinAgents } from "./agents/index.js";
-import { AgentDef } from "./schemas.js";
+import { ADAPTERS } from "./agents/index.js";
 import { projectRoot, runDir } from "./paths.js";
+import { config } from "./config.js";
+import { CMD_AGENT, footerLine, headerLine, logSeq, STDERR_MARK } from "./logs.js";
 import { exec, execShell } from "./proc.js";
 import { tail } from "./util.js";
-/** 會讓各家 CLI 改走 API 計費的環境變數；只用訂閱登入，執行 agent 時一律移除 */
-export const API_KEY_VARS = [
-    "ANTHROPIC_API_KEY",
-    "ANTHROPIC_AUTH_TOKEN",
-    "CODEX_API_KEY",
-    "OPENAI_API_KEY",
-    "GEMINI_API_KEY",
-    "GOOGLE_API_KEY",
-];
 /**
  * 判斷 agent 失敗是否因為方案額度或速率限制。
  * 各家的錯誤訊息會隨版本變動，這裡用寬鬆的樣式比對，且只在執行失敗時才檢查，避免誤判正常輸出。
@@ -62,17 +54,12 @@ export function formatToolLine(agent, tool) {
     const detail = tool.detail?.trim();
     return detail ? `${head}: ${detail.split("\n").join("\n       ")}` : head;
 }
-/** 內建的 claude、codex、gemini 定義，可在 flow.config.json 覆寫或新增其他 agent */
+/** 取出 flow.config.json 裡定義的 agent；沒有內建 agent */
 export function resolveAgent(cfg, name) {
-    const custom = cfg.agents[name];
-    if (custom)
-        return custom;
-    if (builtinAgents(cfg.removedAgents).includes(name)) {
-        return AgentDef.parse({ adapter: name });
-    }
-    if (cfg.removedAgents.includes(name))
-        throw new Error(`${name} 已從設定移除（removedAgents），要使用請先 agent add ${name} --adapter ${name}`);
-    throw new Error(`未定義的 agent：${name}（請在 flow.config.json 的 agents 裡設定）`);
+    const def = cfg.agents[name];
+    if (!def)
+        throw new Error(`未定義的 agent：${name}（請先用 agent add ${name} --adapter <adapter> 新增）`);
+    return def;
 }
 /** 確認某個 agent 的 CLI 是否可以執行 */
 export async function probeAgent(def) {
@@ -96,7 +83,7 @@ export async function runAgent(name, def, t, prompt) {
         projectRoot: projectRoot(),
         command: def.command,
     });
-    appendLog(t.logFile, `# agent=${name} adapter=${def.adapter} cmd=${inv.cmd}`);
+    appendLog(t.logFile, headerLine({ stage: t.stage, step: t.step, agent: name, adapter: def.adapter, startedAt: new Date().toISOString() }));
     let done;
     let lastText = "";
     let inputTokens = 0;
@@ -104,7 +91,6 @@ export async function runAgent(name, def, t, prompt) {
     const r = await exec(inv.cmd, inv.args, {
         cwd: t.cwd,
         env: inv.env,
-        unsetEnv: API_KEY_VARS,
         input: inv.input,
         onStdoutLine: (line) => {
             if (!line.trim())
@@ -113,10 +99,12 @@ export async function runAgent(name, def, t, prompt) {
             for (const ev of adapter.parse(line)) {
                 if (ev.kind === "text") {
                     lastText = ev.text;
-                    console.log(`    💬 [${name}] ${ev.text.trim().split("\n")[0]?.slice(0, 110)}`);
+                    if (config.verbose)
+                        console.log(`    💬 [${name}] ${ev.text.trim().split("\n")[0]?.slice(0, 110)}`);
                 }
                 else if (ev.kind === "tool") {
-                    console.log(formatToolLine(name, ev));
+                    if (config.verbose)
+                        console.log(formatToolLine(name, ev));
                 }
                 else if (ev.kind === "usage") {
                     inputTokens += ev.inputTokens ?? 0;
@@ -129,8 +117,11 @@ export async function runAgent(name, def, t, prompt) {
         },
     });
     if (r.stderr.trim())
-        appendLog(t.logFile, `[stderr]\n${r.stderr}`);
+        appendLog(t.logFile, `${STDERR_MARK}\n${r.stderr}`);
     const ok = r.code === 0 && (done?.ok ?? true);
+    appendLog(t.logFile, footerLine({ code: r.code, ok, endedAt: new Date().toISOString() }));
+    if (!ok)
+        console.log(`    ✗ ${name} 執行失敗（結束碼 ${r.code}），可用 agentflowctl logs ${t.runId} ${logSeq(t.logFile)} 查看`);
     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);
@@ -141,11 +132,15 @@ export async function runAgent(name, def, t, prompt) {
  * 注意：這些指令會執行 agent 寫出來的程式碼，而且不在任何沙箱內。
  */
 export async function runCommand(t, cmd) {
+    appendLog(t.logFile, headerLine({ stage: t.stage, step: t.step, agent: CMD_AGENT, startedAt: new Date().toISOString() }));
     appendLog(t.logFile, `$ ${cmd}`);
-    console.log(`    $ ${cmd.trim().split("\n").join("\n      ")}`);
+    if (config.verbose)
+        console.log(`    $ ${cmd.trim().split("\n").join("\n      ")}`);
     const r = await execShell(cmd, { cwd: t.cwd });
     const output = `${r.stdout}\n${r.stderr}`.trim();
-    appendLog(t.logFile, output);
-    return { ok: r.code === 0, output };
+    if (output)
+        appendLog(t.logFile, output);
+    appendLog(t.logFile, footerLine({ code: r.code, ok: r.code === 0, endedAt: new Date().toISOString() }));
+    return { ok: r.code === 0, output, seq: logSeq(t.logFile) };
 }
 //# sourceMappingURL=runner.js.map

package/dist/schemas.js

@@ -49,11 +49,9 @@ export const AgentDef = z.object({
 });
 /** 目標專案可選的 flow.config.json，預設值對應 Vite + TypeScript + Vitest 專案 */
 export const RepoConfig = z.object({
-    /** 自訂或覆寫 agent；claude、codex、gemini 三個名稱內建 */
+    /** 可用的 agent；沒有內建，全部都要在這裡定義（通常用 agent add） */
     agents: z.record(z.string(), AgentDef).default({}),
-    /** 移除的內建 agent：不再自動偵測，也不能放進輪替；用 agent add 加回 */
-    removedAgents: z.array(z.string()).default([]),
-    /** 輪替順序；未設定時自動偵測已安裝的 CLI */
+    /** 輪替順序；未設定時依 agents 的順序，取已安裝的 CLI */
     cycle: z.array(z.string()).min(1).optional(),
     /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
     fixStrategy: z.enum(["ring", "author"]).default("ring"),

package/dist/setup.js

@@ -0,0 +1,70 @@
+import { addAgent, setAgent, setCycle } from "./agentConfig.js";
+/**
+ * `agentflowctl agent setup` 的互動精靈。
+ * 問答與偵測結果由外部注入，這裡只負責流程；所有修改都在記憶體裡完成，確認後才交給呼叫端寫入。
+ */
+export const SETUP_ADAPTERS = ["claude", "codex", "gemini"];
+/** 回傳要寫入的設定；使用者沒選任何 agent 或最後沒確認時回傳 null */
+export async function runSetup(initial, deps) {
+    const { detected, log } = deps;
+    const ask = async (q, def = "") => (await deps.ask(def ? `${q}（${def}）：` : `${q}：`)).trim() || def;
+    const confirm = async (q, def) => {
+        const a = (await deps.ask(`${q}（${def ? "Y/n" : "y/N"}）：`)).trim().toLowerCase();
+        return a ? a.startsWith("y") : def;
+    };
+    let cfg = initial;
+    const changes = [];
+    const chosen = [];
+    const existing = () => Object.keys((cfg.agents ?? {}));
+    for (const adapter of SETUP_ADAPTERS) {
+        log(`${detected[adapter] ? "✅" : "❌"} ${adapter}${detected[adapter] ? "" : "（沒有偵測到 CLI）"}`);
+        if (!(await confirm(`  加入 ${adapter}？`, detected[adapter])))
+            continue;
+        let name;
+        for (;;) {
+            name = await ask("  名稱", adapter);
+            if (!/^[\w-]+$/.test(name))
+                log("  名稱只能用英數字、底線與連字號");
+            else if (chosen.includes(name))
+                log(`  ${name} 這次已經用過了`);
+            else
+                break;
+        }
+        const isNew = !existing().includes(name);
+        if (!isNew && !(await confirm(`  ${name} 已存在，要覆寫嗎？`, false))) {
+            chosen.push(name);
+            continue;
+        }
+        const model = (await ask("  model（Enter 不指定）")) || undefined;
+        const edit = isNew ? addAgent(cfg, name, { adapter, model }) : setAgent(cfg, name, { adapter, model });
+        cfg = edit.cfg;
+        changes.push(...edit.changes);
+        chosen.push(name);
+    }
+    if (!chosen.length) {
+        log("沒有選擇任何 agent，設定沒有變更");
+        return null;
+    }
+    for (;;) {
+        const list = (await ask("輪替順序，用逗號分隔", chosen.join(","))).split(",").map((s) => s.trim()).filter(Boolean);
+        try {
+            cfg = setCycle(cfg, list).cfg;
+            break;
+        }
+        catch (e) {
+            log(`  ${e.message}`);
+        }
+    }
+    const agents = cfg.agents;
+    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("  需要自訂指令的 CLI 請改用 agent add <name> --adapter command -- <指令>");
+    if (!(await confirm("寫入 flow.config.json？", true))) {
+        log("已取消，設定沒有變更");
+        return null;
+    }
+    return { cfg, changes };
+}
+//# sourceMappingURL=setup.js.map

package/package.json

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