agentflowctl 0.3.0 → 0.5.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 { 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);
@@ -30,7 +36,7 @@ function printSummary(run) {
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
     console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次`);
-    console.log(`agent    ${run.cycle.join(" → ")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
+    console.log(`agent    ${run.cycle.join("、")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
     console.log(`分支     ${run.branch}`);
     console.log(`worktree ${worktreeDir(run.id)}`);
     if (run.prUrl)
@@ -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 ?? "?"}`);
@@ -50,7 +63,7 @@ function printSummary(run) {
     if (run.stage === "awaiting_approval")
         console.log(`\n確認計畫後執行 agentflowctl approve ${run.id}`);
 }
-/** 決定輪替順序：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
+/** 決定參與的 agent：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
 async function resolveCycle(flag) {
     const cfg = loadRepoConfig();
     const wanted = flag ? flag.split(",").map((s) => s.trim()).filter(Boolean) : cfg.cycle;
@@ -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")
@@ -80,7 +102,7 @@ program
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
-    .option("--cycle <agents>", "agent 輪替順序，例如 claude,codex,gemini")
+    .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
     .action(async (opts) => {
     const requirement = opts.reqFile ? readFileSync(opts.reqFile, "utf8") : opts.req;
     if (!requirement?.trim())
@@ -94,13 +116,10 @@ program
     const branch = `flow/${id}`;
     console.log(`[${id}] 🌿 從 ${base} 建立 worktree（分支 ${branch}）`);
     await addWorktree(root, worktreeDir(id), base, branch);
-    console.log(`[${id}] 🤝 agent 輪替順序：${cycle.join(" → ")}`);
-    // 先裝好相依套件：有些 agent 的沙箱不能連網，無法自己安裝
+    console.log(`[${id}] 🤝 參與的 agent：${cycle.join("、")}（角色隨機分配）`);
     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>")
@@ -201,34 +241,33 @@ function applyEdit(edit, done) {
     for (const c of changes)
         console.log(`   ↳ ${c}`);
     if (JSON.stringify(before.cycle) !== JSON.stringify(cfg.cycle)) {
-        console.log("   已建立的 run 會沿用建立時的輪替順序，不受影響");
+        console.log("   已建立的 run 會沿用建立時參與的 agent，不受影響");
     }
 }
 const agent = program.command("agent").description("管理 agent 與 adapter 設定（寫入 flow.config.json）");
 agent
     .command("list")
-    .description("列出內建與自訂 agent、是否已安裝、在輪替中的位置")
+    .description("列出設定的 agent、是否已安裝、是否參與")
     .action(async () => {
     const cfg = loadRepoConfig();
     const cycle = await resolveCycle().catch(() => cfg.cycle ?? []);
-    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 ? "參與" : "不參與"}  ${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：${cycle.length ? cycle.join("、") : "（沒有可用的 agent）"}${cfg.cycle ? "" : "（自動偵測）"}`);
 });
 agent
     .command("add <name> [command...]")
@@ -237,7 +276,7 @@ agent
     .option("--model <model>", "模型名稱")
     .option("--extra-arg <arg>", "額外參數，可重複；以 - 開頭時寫成 --extra-arg=--sandbox", collect)
     .action((name, command, opts) => {
-    applyEdit((cfg) => addAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已新增 ${name}；要加進輪替請用 agent cycle`);
+    applyEdit((cfg) => addAgent(cfg, name, { adapter: opts.adapter, model: opts.model, extraArgs: opts.extraArg, command: command.length ? command : undefined }), `已新增 ${name}；要讓它參與請用 agent cycle`);
 });
 agent
     .command("set <name> [command...]")
@@ -250,51 +289,71 @@ agent
 });
 agent
     .command("remove <name>")
-    .description("刪除 agent（含內建的 claude、codex、gemini），一併從輪替移除；內建的可用 agent add 加回")
+    .description("刪除 agent，一併從參與的 agent 移除")
     .action((name) => applyEdit((cfg) => removeAgent(cfg, name), `已移除 ${name}`));
 agent
     .command("cycle [names]")
-    .description("顯示輪替順序，或用逗號分隔設定新的順序")
+    .description("顯示參與的 agent，或用逗號分隔設定新的名單")
     .action(async (names) => {
     if (!names) {
         const cfg = loadRepoConfig();
-        console.log(`${(await resolveCycle()).join(" → ")}${cfg.cycle ? "" : "（自動偵測）"}`);
+        console.log(`${(await resolveCycle()).join("、")}${cfg.cycle ? "" : "（自動偵測）"}`);
         return;
     }
     const list = names.split(",").map((s) => s.trim()).filter(Boolean);
-    applyEdit((cfg) => setCycle(cfg, list), `輪替順序設為 ${list.join(" → ")}`);
+    applyEdit((cfg) => setCycle(cfg, list), `參與的 agent 設為 ${list.join("、")}`);
     const cfg = loadRepoConfig();
     for (const n of list) {
         if (!(await probeAgent(resolveAgent(cfg, n))))
             console.log(`⚠️  ${n} 目前找不到可執行的 CLI，run 會失敗，請先安裝或用 agent set 修正`);
     }
 });
-program
-    .command("doctor")
-    .description("檢查可用的 agent CLI 與目前的輪替設定")
+agent
+    .command("setup")
+    .description("互動式設定：偵測已安裝的 claude、codex、gemini，逐一選擇要不要加入並設定參與的 agent")
     .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 是否已安裝，印出參與的 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);
         console.log(`${ok ? "✅" : "❌"} ${name.padEnd(10)} adapter=${def.adapter}${def.model ? ` model=${def.model}` : ""}`);
     }
     try {
-        console.log(`\n輪替順序：${(await resolveCycle()).join(" → ")}`);
+        console.log(`\n參與的 agent：${(await resolveCycle()).join("、")}`);
     }
     catch (e) {
         console.log(`\n${e.message}`);
     }
-    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 與目前參與的 agent").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

@@ -1,9 +1,9 @@
 export const config = {
-    /** 指定 Claude Code 使用的模型；未設定則用 Claude Code 預設值 */
-    model: process.env.AGENTFLOWCTL_MODEL,
     /** 單一 Agent 執行最多幾輪工具迴圈，避免卡在迴圈裡 */
     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