agentflowctl 0.6.0 → 0.7.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  # 完整顯示多行指令與絕對路徑
 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 的完整文字，不截斷 |
-| 🔧 | 工具呼叫與完整參數 |
+| 🔧 | 工具呼叫。只顯示第一行，多行時註明共幾行；去掉 `/bin/zsh -lc '…'` 這類 shell 包裝，worktree 內的絕對路徑改成相對路徑 |
 | 📊 | token 用量 |
-| 🏁 | 最後結果 |
+| 🏁 | 最後結果。與最後一則 💬 相同時不再重印 |
 | ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
 | ❌ | adapter 不認得的錯誤事件 |
 | 📄 | 不是 JSON 的輸出行 |
 
-adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+要看完整的工具內容與重複的最後結果，加 `--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: cat .flow/spec.md
 🏁 失敗：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>`。
@@ -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` 限制。
 
@@ -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", "完整顯示工具內容（多行指令、絕對路徑）與重複的最後回覆", 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";
@@ -284,9 +285,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 +376,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 +392,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 +584,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,35 +97,57 @@ 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 ? "" : "."));
+/** 去掉 codex 這類 CLI 包在指令外面的 `/bin/zsh -lc '...'` */
+function unwrapShell(cmd) {
+    const m = cmd.match(/^\/bin\/(?:ba|z)?sh\s+-l?c\s+(['"])([\s\S]*)\1$/);
+    if (!m)
+        return cmd;
+    const [, quote, inner] = m;
+    // 單引號包裝裡的 '"'"' 或 '\'' 是被跳脫的單引號，內容太複雜時保留原樣
+    if (quote === "'" && inner.includes("'"))
+        return cmd;
+    if (quote === '"' && /(^|[^\\])"/.test(inner))
+        return cmd;
+    return inner;
+}
+/** 精簡顯示的工具內容：只留第一行，並註明原本有幾行 */
+function compactDetail(detail) {
+    const lines = relativeToWorktree(unwrapShell(detail.trim())).split("\n");
+    const first = clip(lines[0], 200);
+    return lines.length > 1 ? `${first}　…（共 ${lines.length} 行）` : first;
+}
+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;
@@ -134,9 +157,13 @@ export function renderLog(text, file = "") {
             const events = adapter.parse(line);
             if (events.length) {
                 for (const ev of events) {
-                    const s = renderEvent(ev);
+                    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 +171,7 @@ export function renderLog(text, file = "") {
             }
             const json = tryJson(line);
             if (!json) {
-                out.push(`📄 ${line}`);
+                lines.push(`📄 ${line}`);
                 continue;
             }
             const err = findError(json);
@@ -152,22 +179,51 @@ export function renderLog(text, file = "") {
                 skipped++;
                 continue;
             }
-            out.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
+            lines.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
             if (err.fatal)
                 errors.push(`錯誤事件：${indent(err.message)}`);
         }
         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/package.json

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