agentflowctl 0.2.0 → 0.4.0

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 { DEFAULT_CYCLE } 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 DEFAULT_CYCLE)
+    for (const name of defined)
         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（${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,23 +247,24 @@ 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([...DEFAULT_CYCLE, ...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 = DEFAULT_CYCLE.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(" ")}`);
     }
     console.log(`
 輪替順序：${cycle.length ? cycle.join(" → ") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
@@ -248,8 +289,8 @@ agent
 });
 agent
     .command("remove <name>")
-    .description("刪除自訂 agent（一併從輪替移除），或刪除內建 agent 的覆寫設定")
-    .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已刪除 ${name} 的設定`));
+    .description("刪除 agent，一併從輪替移除")
+    .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已移除 ${name}`));
 agent
     .command("cycle [names]")
     .description("顯示輪替順序，或用逗號分隔設定新的順序")
@@ -267,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([...DEFAULT_CYCLE, ...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);
@@ -284,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")
@@ -303,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