agentflowctl 0.6.0 → 0.8.0

package/README.md

@@ -99,10 +99,11 @@ agentflowctl run --req-file ./req.md --cycle codex,claude --max-agent-runs 40
 agentflowctl run --req "..." --manual-plan   # 計畫通過 AI 審查後，仍停下來等你確認
 
 agentflowctl approve f-xxxx        # 搭配 --manual-plan
-agentflowctl status f-xxxx         # 階段、任務進度、各 agent 用量、代打紀錄
+agentflowctl status f-xxxx         # 階段、上一步結果、未結交接事項、下一步指令、任務進度、各 agent 用量、代打紀錄
 agentflowctl list
 agentflowctl logs f-xxxx           # 列出每一份 log 的編號、結果、階段、步驟、agent
 agentflowctl logs f-xxxx 7         # 解析第 7 份 log，最後附上錯誤整理（--latest 看最新一份）
+agentflowctl logs f-xxxx 7 --full  # 逐條顯示 shell 指令，完整顯示多行內容與絕對路徑
 agentflowctl logs f-xxxx 7 --raw   # 原始內容（agent 的 JSON 行）
 agentflowctl resume f-xxxx         # 從暫停、Ctrl-C 或失敗處接續
 agentflowctl cancel f-xxxx
@@ -182,14 +183,14 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 | 標記 | 內容 |
 |---|---|
 | 💬 | agent 的完整文字，不截斷 |
-| 🔧 | 工具呼叫與完整參數 |
+| 🔧 | 工具呼叫。連續的 shell 指令（多半是讀檔、搜尋）收成一行 `🔧 shell 指令 ×N`；其他工具只顯示第一行，多行時註明共幾行，worktree 內的絕對路徑改成相對路徑 |
 | 📊 | token 用量 |
-| 🏁 | 最後結果 |
+| 🏁 | 最後結果。與最後一則 💬 相同時不再重印 |
 | ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
 | ❌ | adapter 不認得的錯誤事件 |
 | 📄 | 不是 JSON 的輸出行 |
 
-adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+要逐條看 shell 指令、完整的工具內容與重複的最後結果，加 `--full`。adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
 
 最後一段「錯誤」整理出結束碼、agent 回報的失敗、錯誤事件與 stderr：
 
@@ -199,7 +200,7 @@ adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出
 檔案 /repo/.agentflowctl/runs/f-xxxx/logs/003-plan-plan-codex.log
 
 💬 先讀 spec.md 與 acceptance.json
-🔧 shell: bash -lc 'cat .flow/spec.md'
+🔧 shell 指令 ×1（--full 查看）
 🏁 失敗：stream disconnected before completion
 
 ── 錯誤 ──
@@ -211,9 +212,33 @@ stderr：
 
 執行成功時，stderr 會放在「其他輸出」段落，不算錯誤。
 
+### 停下來時的結果與下一步
+
+run 因 Ctrl-C、失敗、額度暫停或等待核准而停下時，終端機會直接印出三段；`agentflowctl status <id>` 也會印同樣的內容：
+
+- **結果**：被中斷、還沒有結束紀錄的步驟，以及上一步的結果。agent 的步驟取回覆 `<result>` 的摘要與疑慮；失敗時優先顯示失敗的那一步，並附上結束碼、錯誤事件、stderr 或指令輸出的最後幾行。
+- **未結交接事項**：交接紀錄裡還沒結案的 action 事項（open 或 proposed_resolved）。
+- **下一步**：依狀態列出可以執行的指令，例如 `logs`、`cd` 到 worktree、`resume`、`cancel`、`approve`。
+
+```
+── 結果 ──
+  中斷於 #20 plan_review / plan-review / codex（沒有結束紀錄，resume 時會重跑這一步）
+  #19 plan_fix / plan-fix / claude ✓
+     摘要：接受三條審查意見，拆分 T-3、T-5
+     疑慮：T-15 可能仍太大
+
+── 未結交接事項 ──
+  [plan] c9c730b280e87178 T-3、T-5 各混合多個獨立行為（proposed_resolved）
+
+── 下一步 ──
+  agentflowctl logs f-xxxx 19              看上一步的完整 log
+  agentflowctl resume f-xxxx               從 plan_review 接續
+  agentflowctl cancel f-xxxx               放棄這個 run
+```
+
 ### 出錯時怎麼查
 
-1. run 停下時印出的摘要，或 `agentflowctl status <id>`，會列出失敗的階段、原因、最後一份 log，以及最近失敗的那一份。
+1. 先看 run 停下時印出的「結果」與「下一步」，或執行 `agentflowctl status <id>`。
 2. `agentflowctl logs <id> <編號>` 看那份 log 的錯誤段落。
 3. 解析結果看不出原因時，加 `--raw` 看原始輸出。
 4. 必要時直接在 worktree（`.agentflowctl/worktrees/<id>`）裡修正，再執行 `agentflowctl resume <id>`。
@@ -298,9 +323,9 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 
 人工確認計畫是為了擋住方向錯了還一路做下去。預設用三層機制取代它；加上 `--manual-plan` 時，三層都過了仍會停下來等你。
 
-**格式與覆蓋率。** 每次撰寫或修改計畫之後，都要重新通過 zod、任務相依、無循環、每條驗收條件都有任務負責。沒過就還原。
+**格式與覆蓋率。** 每次撰寫或修改計畫之後，都要重新通過 zod、任務相依、無循環、每條驗收條件都有任務負責，而且每個任務最多對應兩條驗收條件（一次只做一件事，最多兩件）。沒過就還原。
 
-**跨模型審查。** 審查看需求覆蓋、驗收條件能不能測、任務大小與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
+**跨模型審查。** 審查看需求覆蓋、驗收條件能不能測且一條只寫一個行為、任務是否只做一件事（最多兩件）與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
 
 **僵持時仲裁。** 兩種情況會觸發：這輪審查意見和上一輪一樣，或已達重試上限。仲裁者只判斷一件事：照這份計畫實作，能不能滿足需求。
 
@@ -310,7 +335,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查；分歧依 `tieBreak` |
 | 一家 | 同一家 | 由它自己仲裁 |
 
-兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含模型名稱的爭議清單（`.flow/dispute.md`）。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
+兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含審查者名稱的爭議清單（`.flow/dispute.md`）。爭議清單用 `<issue>` 包住每則意見；給修訂者的 `.flow/feedback.md` 則用 `<opinion author="…">` 包住每位審查者的意見，避免意見內文與外層結構混淆。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
 
 計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。兩家都要求修改時不因仲裁輪數而直接失敗；整個 run 仍受 `maxAgentRuns` 限制。
 
@@ -321,7 +346,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 階段 | 負責的 agent | 程式認定通過的條件 | 失敗時 |
 |---|---|---|---|
 | spec | 隨機一位 | 檔案存在、zod 驗證、id 不重複 | 重試 |
-| plan | 與 spec 同一位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
+| plan | 與 spec 同一位 | zod、相依存在、無循環、每條驗收條件都有任務、每個任務最多兩條驗收條件 | 重試 |
 | plan_review | 計畫作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 進入 plan_fix |
 | plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
 | 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時進入 plan_fix 再審查；第三方不核准或 `tieBreak: stop` 時失敗 |
@@ -411,6 +436,7 @@ src/
   roles.ts          角色分配規則（含計畫修正者與仲裁者）
   runner.ts         執行 agent、正規化結果、執行專案指令
   logs.ts           log 檔名、檔頭檔尾、列表與解析
+  stopReport.ts     run 停下時的結果、未結交接事項與下一步指令
   agents/           claude、codex、gemini、command
   setup.ts          agent setup 互動精靈
   git.ts            worktree 與 git 操作

package/dist/cli.js

@@ -15,6 +15,8 @@ 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 { openActions, readHandoff } from "./handoff.js";
+import { stopReport } from "./stopReport.js";
 import { runSetup, SETUP_ADAPTERS } from "./setup.js";
 import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
 function mustGetRun(id) {
@@ -26,12 +28,13 @@ function mustGetRun(id) {
 async function drive(run) {
     // Ctrl-C 會同時送給子程序（claude、測試指令），狀態已經寫在 state.json，之後可用 resume 接續
     process.once("SIGINT", () => {
-        console.log(`\n已中斷，之後可用 agentflowctl resume ${run.id} 接續`);
+        console.log("\n已中斷");
+        printSummary(getRun(run.id) ?? run, true);
         process.exit(130);
     });
     printSummary(await advance(run));
 }
-function printSummary(run) {
+function printSummary(run, interrupted = false) {
     console.log("");
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
@@ -46,22 +49,21 @@ function printSummary(run) {
     if (run.stage === "failed") {
         console.log(`失敗於   ${run.failedStage ?? "?"}`);
         console.log(`原因     ${run.failureReason ?? "?"}`);
-        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 ?? "?"}`);
         console.log(`原因     ${run.pauseReason ?? "?"}`);
-        console.log(`\n額度恢復後執行 agentflowctl resume ${run.id}`);
     }
-    if (run.stage === "awaiting_approval")
-        console.log(`\n確認計畫後執行 agentflowctl approve ${run.id}`);
+    const report = stopReport({
+        run,
+        interrupted,
+        logs: listLogs(logDir(run.id)),
+        read: (file) => readFileSync(file, "utf8"),
+        open: openActions(readHandoff(run.id)),
+        worktree: worktreeDir(run.id),
+    });
+    for (const line of report)
+        console.log(line);
 }
 /** 決定參與的 agent：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
 async function resolveCycle(flag) {
@@ -367,6 +369,7 @@ program
     .command("logs <id> [seq]")
     .description("列出 log；指定編號（或 --latest）時顯示解析後的內容，最後附上錯誤整理")
     .option("--latest", "顯示最新一份 log", false)
+    .option("--full", "逐條顯示 shell 指令，完整顯示工具內容（多行指令、絕對路徑）與重複的最後回覆", false)
     .option("--raw", "顯示原始內容（agent 的 JSON 行）", false)
     .action((id, seq, opts) => {
     mustGetRun(id);
@@ -379,14 +382,14 @@ program
             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）`);
+        console.log(`\n查看內容：agentflowctl logs ${id} <編號>（加 --full 看完整工具內容、--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));
+    console.log(opts.raw ? text : renderLog(text, entry.file, { full: opts.full }));
 });
 program.parseAsync().catch((err) => {
     console.error(`錯誤：${err.message}`);

package/dist/engine.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { config } from "./config.js";
 import { arbitrationDecision } from "./arbitration.js";
 import { detectProjectDefaults, withProjectDefaults } from "./detect.js";
+import { escapeXml, opinion, reviewIssue } from "./feedback.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
 import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
 import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.js";
@@ -34,10 +35,13 @@ const exhausted = new Set();
 function handoffTarget(run) {
     return ["spec", "plan", "plan_review", "plan_fix"].includes(run.stage) ? "plan" : "code";
 }
-/** 同一輪重跑使用相同 key；重試次數或 panel 位置改變時使用新 key。 */
+/**
+ * 每次執行 agent 都用新的 key。重試次數會在後面的輪次重複出現，只靠它組 key 會撞到先前已套用的呼叫，
+ * 讓這次的處置被當成重播而略過，所以加上這個 run 已執行 agent 的次數。
+ */
 function handoffKey(run, step, slot, agent) {
     const attempts = Object.entries(run.attempts).sort(([a], [b]) => a.localeCompare(b));
-    return JSON.stringify([run.id, run.stage, step, run.taskIndex, run.taskPhase, attempts, slot, agent]);
+    return JSON.stringify([run.id, run.stage, step, run.taskIndex, run.taskPhase, attempts, slot, agent, agentRuns(run.id)]);
 }
 async function agentStep(run, planned, step, prompt, mode) {
     const cfg = loadRepoConfig();
@@ -284,9 +288,9 @@ async function planReviewStage(run) {
         firstObjector ??= reviewer;
         const lines = review.data.items
             .filter((i) => i.status !== "met")
-            .map((i) => `- **${i.criterion}**（${i.status}）：${i.note}`);
+            .map((i) => reviewIssue(i.criterion, i.status, i.note));
         issueLines.push(...lines);
-        issues.push(`### ${reviewer} 的意見\n\n${lines.join("\n")}`);
+        issues.push(opinion(reviewer, lines));
     }
     if (!firstObjector)
         return planSettled(run, "plan-review");
@@ -375,9 +379,10 @@ async function arbitratePlan(run) {
         mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
         renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
         const verdict = result.data.verdict;
-        const notes = result.data.items.map((i) => `- ${i.criterion}：${i.note}`);
+        const notes = result.data.items.map((i) => `<issue criterion="${escapeXml(i.criterion)}">${escapeXml(i.note)}</issue>`);
+        const markdownNotes = result.data.items.map((i) => `- ${i.criterion}：${i.note}`);
         info(run, `   ${verdict === "approve" ? "✓" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : "不可執行"}`);
-        verdicts.push({ arbiter, verdict, notes });
+        verdicts.push({ arbiter, verdict, notes, markdownNotes });
     }
     rmSync(flowFile(run, "dispute.md"), { force: true });
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
@@ -390,16 +395,16 @@ async function arbitratePlan(run) {
         : approvals === 0
             ? `${mode}沒有任何一方核准${decision === "revise" ? "，交回計畫修訂" : ""}`
             : `${mode}意見分歧，依 tieBreak=${cfg.tieBreak} ${cfg.tieBreak === "proceed" ? "繼續實作" : "停止"}`;
-    const record = verdicts.map((v) => `### ${v.arbiter}（${v.verdict}）\n\n${v.notes.join("\n")}`).join("\n\n");
+    const feedbackRecord = verdicts.map((v) => opinion(v.arbiter, v.notes, v.verdict)).join("\n\n");
     if (decision === "revise") {
         const attempts = { ...run.attempts, "plan-arbitration": arbitrationRound };
         delete attempts["plan-review"];
         rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
-        writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${record}\n`);
+        writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${feedbackRecord}\n`);
         info(run, `   → ${summary}`);
         return { ...run, attempts, stage: "plan_fix" };
     }
-    writeFileSync(flowFile(run, "plan.md"), `${readFileSync(flowFile(run, "plan.md"), "utf8")}\n\n## 仲裁紀錄\n\n**結果：${summary}**\n\n${record}\n`);
+    writeFileSync(flowFile(run, "plan.md"), `${readFileSync(flowFile(run, "plan.md"), "utf8")}\n\n## 仲裁紀錄\n\n**結果：${summary}**\n\n${verdicts.map((v) => `### ${v.arbiter}（${v.verdict}）\n\n${v.markdownNotes.join("\n")}`).join("\n\n")}\n`);
     if (decision === "proceed") {
         info(run, `   → ${summary}`);
         return planSettled(run, "plan-review");
@@ -582,11 +587,9 @@ async function reviewStage(run) {
         }
         info(run, `   ✗ ${reviewer} 要求修改`);
         firstObjector ??= reviewer;
-        issues.push(`### ${reviewer} 的意見\n\n` +
-            review.data.items
-                .filter((i) => i.status !== "met")
-                .map((i) => `- **${i.criterion}**（${i.status}）：${i.note}`)
-                .join("\n"));
+        issues.push(opinion(reviewer, review.data.items
+            .filter((i) => i.status !== "met")
+            .map((i) => reviewIssue(i.criterion, i.status, i.note))));
     }
     if (!firstObjector)
         return succeed(run, "review", "pr");

package/dist/feedback.js

@@ -0,0 +1,15 @@
+/** agent 提供的文字必須跳脫，才不會打斷意見的 XML 邊界。 */
+export function escapeXml(value) {
+    return value.replace(/[&<>"']/g, (char) => ({
+        "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;",
+    })[char]);
+}
+export function reviewIssue(criterion, status, note) {
+    return `<issue criterion="${escapeXml(criterion)}" status="${escapeXml(status)}">${escapeXml(note)}</issue>`;
+}
+export function opinion(author, issues, verdict) {
+    const name = escapeXml(author);
+    const outcome = verdict ? ` verdict="${escapeXml(verdict)}"` : "";
+    return `<opinion author="${name}"${outcome}>\n${issues.join("\n")}\n</opinion>`;
+}
+//# sourceMappingURL=feedback.js.map

package/dist/logs.js

@@ -2,6 +2,7 @@ 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";
+import { parseResultMeta } from "./resultMeta.js";
 /**
  * 每次執行 agent 或專案指令都寫成一份 log：
  * - 檔名：<三位數序號>-<階段>-<步驟>-<agent>.log，專案指令的 agent 欄位是 cmd
@@ -96,47 +97,76 @@ function findError(ev) {
     const hit = walk(ev, 0);
     return hit ? { message: clip(pick(hit)), fatal: false } : undefined;
 }
-function renderEvent(ev) {
+/** worktree 絕對路徑改成相對路徑：`<worktree>/x` → `x`，單獨的 `<worktree>` → `.` */
+const relativeToWorktree = (s) => s.replace(/[^\s'"=]*\/\.agentflowctl\/worktrees\/[^/\s'"]+(\/)?/g, (_m, slash) => (slash ? "" : "."));
+/** 精簡顯示的工具內容：只留第一行，並註明原本有幾行 */
+function compactDetail(detail) {
+    const lines = relativeToWorktree(detail.trim()).split("\n");
+    const first = clip(lines[0], 200);
+    return lines.length > 1 ? `${first}　…（共 ${lines.length} 行）` : first;
+}
+/** 各家 CLI 執行 shell 指令的工具名稱：codex 的 shell、claude 的 Bash、gemini 的 run_shell_command */
+const SHELL_TOOLS = new Set(["shell", "bash", "run_shell_command"]);
+const isShellTool = (ev) => ev.kind === "tool" && SHELL_TOOLS.has(ev.name.toLowerCase());
+function renderEvent(ev, full, lastText) {
     switch (ev.kind) {
         case "text":
             return `💬 ${indent(ev.text.trim())}`;
-        case "tool":
-            return `🔧 ${ev.name}${ev.detail ? `: ${indent(ev.detail.trim())}` : ""}`;
+        case "tool": {
+            const detail = ev.detail?.trim();
+            if (!detail)
+                return `🔧 ${ev.name}`;
+            return `🔧 ${ev.name}: ${full ? indent(detail) : compactDetail(detail)}`;
+        }
         case "usage":
             return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens`;
-        case "done":
-            return `🏁 ${ev.ok ? "完成" : "失敗"}${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`;
+        case "done": {
+            const summary = ev.summary?.trim();
+            // 最後一則回覆通常就是 summary，精簡模式不再重印一次
+            const show = summary && (full || summary !== lastText);
+            return `🏁 ${ev.ok ? "完成" : "失敗"}${show ? `：${indent(summary)}` : ""}`;
+        }
     }
 }
-/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見 */
-export function renderLog(text, file = "") {
+function analyzeLog(text, full) {
     const { header, footer, body, stderr } = parseLog(text);
-    const out = [];
+    const lines = [];
     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("");
+    let lastText;
+    let doneSummary;
     const adapter = header?.adapter ? ADAPTERS[header.adapter] : undefined;
     if (!adapter || header?.agent === CMD_AGENT) {
-        out.push(...body);
+        lines.push(...body);
+        lastText = body.slice(-15).join("\n").trim() || undefined;
     }
     else {
         let skipped = 0;
+        // 精簡模式下連續的 shell 指令（多半是讀檔、搜尋）收成一行，只留數量
+        let shells = 0;
+        const flushShells = () => {
+            if (shells)
+                lines.push(`🔧 shell 指令 ×${shells}（--full 查看）`);
+            shells = 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 (!full && isShellTool(ev)) {
+                        shells++;
+                        continue;
+                    }
+                    if (ev.kind !== "usage")
+                        flushShells();
+                    const s = renderEvent(ev, full, lastText);
                     if (s)
-                        out.push(s);
+                        lines.push(s);
+                    if (ev.kind === "text")
+                        lastText = ev.text.trim();
+                    if (ev.kind === "done")
+                        doneSummary = ev.summary?.trim() || undefined;
                     if (ev.kind === "done" && !ev.ok)
                         errors.push(`agent 回報失敗${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`);
                 }
@@ -144,7 +174,8 @@ export function renderLog(text, file = "") {
             }
             const json = tryJson(line);
             if (!json) {
-                out.push(`📄 ${line}`);
+                flushShells();
+                lines.push(`📄 ${line}`);
                 continue;
             }
             const err = findError(json);
@@ -152,22 +183,53 @@ export function renderLog(text, file = "") {
                 skipped++;
                 continue;
             }
-            out.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
+            flushShells();
+            lines.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
             if (err.fatal)
                 errors.push(`錯誤事件：${indent(err.message)}`);
         }
+        flushShells();
         if (skipped)
-            out.push(`（另有 ${skipped} 行其他事件未顯示，可用 --raw 查看）`);
+            lines.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;
+    return { header, footer, lines, errors, stderrText, lastText, doneSummary };
+}
+const logTitle = (header) => header
+    ? `${header.stage} / ${header.step} / ${header.agent}${header.adapter && header.adapter !== header.agent ? `（adapter ${header.adapter}）` : ""}`
+    : "（沒有檔頭）";
+/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見。預設精簡工具內容，opts.full 時完整顯示 */
+export function renderLog(text, file = "", opts = {}) {
+    const { header, footer, lines, errors, stderrText } = analyzeLog(text, opts.full ?? false);
+    const out = [];
+    out.push(`${logSeq(file) ? `#${logSeq(file)}  ` : ""}${logTitle(header)}`);
+    out.push(`開始 ${localTime(header?.startedAt)}　` +
+        (footer ? `結束 ${localTime(footer.endedAt)}　結束碼 ${footer.code}　${footer.ok ? "✓ 成功" : "✗ 失敗"}` : "… 沒有結束紀錄（還在執行或被中斷）"));
+    if (file)
+        out.push(`檔案 ${file}`);
+    out.push("", ...lines);
     if (errors.length)
         out.push("", "── 錯誤 ──", ...errors, ...(stderrText ? [stderrText] : []));
     else if (stderrText)
         out.push("", "── 其他輸出 ──", stderrText);
     return out.join("\n");
 }
+/** 一份 log 的結果摘要：給 run 停下時直接印在終端機，不用再另外查 log */
+export function summarizeLog(text) {
+    const a = analyzeLog(text, false);
+    const reply = a.doneSummary ?? a.lastText;
+    const meta = reply ? parseResultMeta(reply) ?? (a.lastText ? parseResultMeta(a.lastText) : undefined) : undefined;
+    const failed = a.footer ? !a.footer.ok : false;
+    return {
+        title: logTitle(a.header),
+        ok: a.footer?.ok,
+        meta,
+        text: meta ? undefined : reply && clip(reply, 600),
+        errors: failed ? [...a.errors, ...(a.stderrText ? [a.stderrText] : [])] : [],
+    };
+}
 //# sourceMappingURL=logs.js.map

package/dist/resultMeta.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** Agent 回覆結尾的 <result> 中繼資料（格式定義在各 prompt 的 <reply_format>） */
+export const ResultMeta = z.object({
+    status: z.enum(["done", "blocked"]),
+    summary: z.string().default(""),
+    filesChanged: z.array(z.string()).default([]),
+    concerns: z.string().default(""),
+});
+const tagText = (xml, tag) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.trim();
+/** 取回覆中最後一個 <result> 區塊；沒有或格式不合時回傳 undefined，不影響關卡判斷 */
+export function parseResultMeta(text) {
+    const block = [...text.matchAll(/<result>([\s\S]*?)<\/result>/g)].at(-1)?.[1];
+    if (block === undefined)
+        return undefined;
+    const files = tagText(block, "files_changed") ?? "";
+    const parsed = ResultMeta.safeParse({
+        status: tagText(block, "status"),
+        summary: tagText(block, "summary"),
+        filesChanged: [...files.matchAll(/<file>([\s\S]*?)<\/file>/g)].map((m) => m[1].trim()).filter(Boolean),
+        concerns: tagText(block, "concerns"),
+    });
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=resultMeta.js.map

package/dist/runner.js

@@ -1,12 +1,12 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { z } from "zod";
 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";
+import { parseResultMeta } from "./resultMeta.js";
 /**
  * 判斷 agent 失敗是否因為方案額度或速率限制。
  * 各家的錯誤訊息會隨版本變動，這裡用寬鬆的樣式比對，且只在執行失敗時才檢查，避免誤判正常輸出。
@@ -22,28 +22,7 @@ const QUOTA_PATTERNS = [
     /\b429\b/,
 ];
 export const isQuotaError = (text) => QUOTA_PATTERNS.some((p) => p.test(text));
-/** Agent 回覆結尾的 <result> 中繼資料（格式定義在各 prompt 的 <reply_format>） */
-export const ResultMeta = z.object({
-    status: z.enum(["done", "blocked"]),
-    summary: z.string().default(""),
-    filesChanged: z.array(z.string()).default([]),
-    concerns: z.string().default(""),
-});
-const tagText = (xml, tag) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.trim();
-/** 取回覆中最後一個 <result> 區塊；沒有或格式不合時回傳 undefined，不影響關卡判斷 */
-export function parseResultMeta(text) {
-    const block = [...text.matchAll(/<result>([\s\S]*?)<\/result>/g)].at(-1)?.[1];
-    if (block === undefined)
-        return undefined;
-    const files = tagText(block, "files_changed") ?? "";
-    const parsed = ResultMeta.safeParse({
-        status: tagText(block, "status"),
-        summary: tagText(block, "summary"),
-        filesChanged: [...files.matchAll(/<file>([\s\S]*?)<\/file>/g)].map((m) => m[1].trim()).filter(Boolean),
-        concerns: tagText(block, "concerns"),
-    });
-    return parsed.success ? parsed.data : undefined;
-}
+export { parseResultMeta, ResultMeta } from "./resultMeta.js";
 function appendLog(file, text) {
     mkdirSync(dirname(file), { recursive: true });
     appendFileSync(file, text.endsWith("\n") ? text : `${text}\n`);

package/dist/stopReport.js

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { summarizeLog } from "./logs.js";
+const pad = (s) => s.split("\n").join("\n     ");
+const clip = (s, max) => (s.length <= max ? s : `${s.slice(0, max)}…`);
+/** 一份 log 的結果：標題、<result> 的摘要與疑慮；失敗時附上錯誤整理 */
+function outcomeLines(entry, text) {
+    const s = summarizeLog(text);
+    const mark = s.ok === undefined ? "…" : s.ok ? "✓" : "✗";
+    const out = [`  #${entry.seq} ${s.title} ${mark}`];
+    if (s.meta) {
+        if (s.meta.status === "blocked")
+            out.push("     狀態：blocked");
+        if (s.meta.summary)
+            out.push(`     摘要：${pad(s.meta.summary)}`);
+        if (s.meta.concerns)
+            out.push(`     疑慮：${pad(s.meta.concerns)}`);
+    }
+    else if (s.text) {
+        out.push(`     ${pad(s.text)}`);
+    }
+    for (const e of s.errors)
+        out.push(`     ${pad(clip(e, 1500))}`);
+    return out;
+}
+/**
+ * run 停下來（Ctrl-C、失敗、暫停、等待核准）時要直接印在終端機的內容：
+ * 最近一步的結果、未結交接事項，以及接下來可以執行的指令。完成的 run 不印。
+ */
+export function stopReport(i) {
+    const { run, logs } = i;
+    if (run.stage === "done")
+        return [];
+    const out = [];
+    const last = logs.at(-1);
+    const running = last && !last.footer ? last : undefined;
+    const finished = logs.filter((e) => e.footer);
+    const lastFailed = finished.filter((e) => !e.footer.ok).at(-1);
+    // 失敗時優先看失敗的那一步，其餘情況看最後完成的一步
+    const shown = run.stage === "failed" && lastFailed ? lastFailed : finished.at(-1);
+    if (running || shown) {
+        out.push("", "── 結果 ──");
+        if (running) {
+            const title = summarizeLog(i.read(running.file)).title;
+            out.push(`  ${i.interrupted ? "中斷於" : "進行中"} #${running.seq} ${title}（沒有結束紀錄，resume 時會重跑這一步）`);
+        }
+        if (shown)
+            out.push(...outcomeLines(shown, i.read(shown.file)));
+    }
+    if (i.open.length) {
+        out.push("", "── 未結交接事項 ──");
+        for (const item of i.open)
+            out.push(`  [${item.targetStage}] ${item.id} ${item.summary}（${item.status}）`);
+    }
+    const cmd = (c, why) => `  ${c.padEnd(40)} ${why}`;
+    const actions = [];
+    if (run.stage === "failed") {
+        if (lastFailed)
+            actions.push(cmd(`agentflowctl logs ${run.id} ${lastFailed.seq}`, "看失敗步驟的完整 log"));
+        actions.push(cmd(`cd ${i.worktree}`, "需要時手動修正"));
+        actions.push(cmd(`agentflowctl resume ${run.id}`, `從 ${run.failedStage ?? "失敗的階段"} 重試`));
+        actions.push(cmd(`agentflowctl cancel ${run.id}`, "放棄這個 run"));
+    }
+    else if (run.stage === "paused") {
+        actions.push(cmd(`agentflowctl resume ${run.id}`, "額度恢復後接續"));
+    }
+    else if (run.stage === "awaiting_approval") {
+        actions.push(cmd(`less ${join(i.worktree, ".flow", "plan.md")}`, "檢視計畫"));
+        actions.push(cmd(`agentflowctl approve ${run.id}`, "核准並開始實作"));
+    }
+    else {
+        if (shown)
+            actions.push(cmd(`agentflowctl logs ${run.id} ${shown.seq}`, "看上一步的完整 log"));
+        actions.push(cmd(`agentflowctl resume ${run.id}`, `從 ${run.stage} 接續`));
+        actions.push(cmd(`agentflowctl cancel ${run.id}`, "放棄這個 run"));
+    }
+    out.push("", "── 下一步 ──", ...actions);
+    return out;
+}
+//# sourceMappingURL=stopReport.js.map

package/dist/tasks.js

@@ -1,3 +1,5 @@
+/** 一個任務最多做兩件事：對應的驗收條件超過這個數量就要再拆 */
+export const MAX_TASK_ACCEPTANCE = 2;
 /**
  * 檢查任務清單並依相依關係排序（Kahn 演算法）。
  * 回傳排序後的任務，或回傳一段可以直接回饋給 Agent 的錯誤說明。
@@ -12,6 +14,9 @@ export function orderTasks(tasks, acceptanceIds) {
     }
     const covered = new Set();
     for (const t of tasks) {
+        if (t.acceptance.length > MAX_TASK_ACCEPTANCE) {
+            errors.push(`${t.id} 對應 ${t.acceptance.length} 條驗收條件，一個任務最多 ${MAX_TASK_ACCEPTANCE} 條，請拆成更小的任務`);
+        }
         for (const d of t.dependsOn)
             if (!ids.has(d))
                 errors.push(`${t.id} 相依的 ${d} 不存在`);

package/package.json

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

package/prompts/plan-fix.md

@@ -31,6 +31,7 @@
 <output_format>
 - acceptance.json 與 tasks.json 的格式必須維持不變（見檔案內現有內容）。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
+- 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為。修改時若任務變大，請拆開，不要合併。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
 </output_format>
 

package/prompts/plan-review.md

@@ -32,8 +32,8 @@
 
 <review_focus>
 1. **需求覆蓋**：規格是否完整涵蓋原始需求？有沒有遺漏、誤解，或加入需求沒要求的範圍？
-2. **驗收條件**：每一條是否具體、可以用自動化測試驗證？有沒有重要的邊界情況或錯誤處理沒被列入？
-3. **任務拆解**：每個任務是否小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試？相依順序是否合理？
+2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
+3. **任務拆解**：每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試？任務太大、一次要動很多檔案或驗證很多行為的，要求拆成更小的任務。相依順序是否合理？
 4. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？
 
 措辭、格式這類不影響實作結果的小問題，不需要要求修改。

package/prompts/plan.md

@@ -46,7 +46,10 @@
 </output_format>
 
 <guidelines>
-- 每個任務是一個可獨立測試的垂直切片，小到一次 TDD 循環就能完成。
+- 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件，超過就拆成多個任務（程式會檢查，超過會被退回）。
+- 每個任務是一個可獨立測試的垂直切片，小到一次 TDD 循環就能完成；只動少數幾個檔案，測試只驗證一兩個行為。
+- `title` 用一句話說出這件事；需要用「並且」「以及」串起來的，就是兩個任務。
+- `description` 寫清楚要動哪些檔案、測試要驗證哪個行為，以及這個任務不做什麼。
 - 每個任務都必須能寫出「在實作前會失敗」的測試；純設定或重構類工作請併入相關任務。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。

package/prompts/spec.md

@@ -28,6 +28,13 @@
 4. 撰寫 .flow/acceptance.json，每一條驗收條件都必須能用自動化測試驗證。
 </steps>
 
+<guidelines>
+- 驗收條件要寫細：一條只描述一個可觀察的行為（一個輸入或情境，對應一個預期結果）。
+- 描述裡出現「並且」「同時」「以及」，或同時涵蓋成功與失敗路徑時，拆成多條。
+- 邊界情況與錯誤處理各自獨立成一條，不要附在正常路徑那一條裡。
+- 寧可多幾條小的，也不要少數幾條大的；後面每個任務最多只能對應兩條驗收條件。
+</guidelines>
+
 <output_format>
 .flow/acceptance.json 的格式：