agentflowctl 0.18.0 → 0.19.0

package/README.md

@@ -60,9 +60,9 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 
 `status` 會列出目前階段、未結的交接事項與下一步指令；失敗或暫停時也會顯示原因。任務進度與「待你確認（不進實作）」分成兩個區塊：實作任務在「任務」，`kind: confirm` 的項目在「待你確認（不進實作）」，兩邊都會列出。計畫還沒通過首次驗證時，這個區塊的標題會多帶「（計畫尚未定案，以下為草稿）」，代表清單是從尚未經檢查的草稿蒐集，項目最終可能不會定案。只想看要人眼確認的項目時，用 `confirmations <id>`。要看某一步的詳細輸出，可用 `logs <id> <編號>`；加 `--full` 看完整工具內容，或加 `--raw` 看原始輸出。
 
-`stats` 依 log 的開始與結束時間統計每個步驟的執行次數、失敗次數、總耗時與最長一次，並分開列出 agent 與專案指令（install、測試、checks）各占多少時間，最耗時的步驟排在最前面。沒有結束紀錄的 log 列為未完成，不計入耗時；總經過時間包含暫停與等待核准。
+`stats` 依 log 的開始與結束時間統計每個步驟的執行次數、失敗次數、總耗時與最長一次，並分開列出 agent 與專案指令（install、測試、checks）各占多少時間，最耗時的步驟排在最前面。沒有結束紀錄的 log 列為未完成，不計入耗時；總經過時間包含暫停與等待核准。紅燈階段的測試指令（`T-<n>-red`）失敗是預期結果，只有測試意外通過才計為失敗。
 
-`insights` 把所有 run 分成獨立區塊彙總：最終狀態、失敗原因（重試達上限、仲裁停止、agent 次數用完等）、用量（輸入／輸出／cache、強度占比、階段／agent，各 run 用量最高的任務）、各模型與步驟、步驟執行與失敗（與 `stats` 相同取 log 的檔頭檔尾，跨 run 不計總經過時間）、關卡重試原因。任務關卡與任務步驟不分 task id 合併計算。最後列出最多五則建議，規則由程式套門檻，不是再請 agent 分析。合計 token 不是主指標。覆蓋不足時會先警告占比可能失真。各分組是同一批呼叫的不同切片，不要跨組相加。舊 run 沒有重試或失敗原因紀錄，不會回填。單一 run 的全量明細仍用 `status <id>` 與 `stats <id>`。
+`insights` 把所有 run 分成獨立區塊彙總：最終狀態、失敗原因（重試達上限、仲裁停止、agent 次數用完等）、用量（輸入／輸出／cache、強度占比、階段／agent，各 run 用量最高的任務）、各模型與步驟、步驟執行與失敗（與 `stats` 相同取 log 的檔頭檔尾，跨 run 不計總經過時間）、關卡重試原因。任務關卡與任務步驟不分 task id 合併計算。最後列出最多五則建議，規則由程式套門檻，不是再請 agent 分析。「輸入遠大於輸出」不計入 cache 讀取（Claude 的 cache 寫入仍計入），門檻是非 cache 的輸入與輸出合計至少 5000 tokens 且輸入佔 85% 以上；cache 讀取量另外列在說明中。合計 token 不是主指標。覆蓋不足時會先警告占比可能失真。各分組是同一批呼叫的不同切片，不要跨組相加。舊 run 沒有重試或失敗原因紀錄，不會回填。單一 run 的全量明細仍用 `status <id>` 與 `stats <id>`。
 
 執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`agentflowctl clean --all` 一次清除所有 done、failed 的 run，以及沒有紀錄的 worktree（進行中、暫停、等待核准的不動）。`flow/<id>` 分支會保留。
 
@@ -80,6 +80,8 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 | `failed`：測試、檢查、審查或 agent 執行失敗 | 依 `status` 提示查看失敗的 log，處理原因後執行 `agentflowctl resume <id>`；失敗階段會重試 |
 | `failed`：已達 agent 執行次數上限 | 用 `agentflowctl resume <id> --max-agent-runs 100` 調高上限後接續，數字須大於已執行次數 |
 
+寫作類步驟（規格、計畫、計畫修正、紅燈測試、綠燈實作、fix）完成且通過關卡後，若 `.flow/handoff-response.json` 不合格，會請同一家 agent 再呼叫一次，只補寫交接（不重做工作，也不換人代打）；補寫期間對其他檔案的變更與 commit 一律丟棄（規格與計畫類步驟沒有 commit，補寫者會被告知範圍為空，不會把事項標成已處理，補寫期間對規格與計畫檔的修改同樣丟棄）。補寫仍不合格或額度用完，才照舊還原這一步並重試。補寫呼叫記在原步驟名稱底下，`stats` 與 `logs` 會多一筆，也會計入 `--max-agent-runs` 的次數。
+
 例如失敗時，可照終端機列出的 log 編號查看原因：
 
 ```bash

package/dist/engine.js

@@ -7,7 +7,7 @@ import { escapeXml, opinion, reviewIssue } from "./feedback.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
 import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, responsePath, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
 import { flowDir, logDir, planArbitrationPath, planReviewStatePath, projectRoot, runDir, worktreeDir } from "./paths.js";
-import { CMD_AGENT, nextLogFile } from "./logs.js";
+import { CMD_AGENT, nextLogFile, redStepName } from "./logs.js";
 import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
 import { dropCall, loadCalls, openRound, runPool, saveCall, storedCallValid } from "./parallelReview.js";
@@ -57,8 +57,8 @@ async function agentStep(run, planned, step, prompt, mode) {
     let agent = planned;
     for (;;) {
         if (exhausted.has(agent)) {
-            if (mode.kind === "review") {
-                throw new QuotaPause(`${agent} 的額度已用完；${step} 是審查步驟，不由另一家代打`);
+            if (mode.kind === "review" || mode.pinned) {
+                throw new QuotaPause(`${agent} 的額度已用完；${step} ${mode.pinned ? "不由另一家代打" : "是審查步驟，不由另一家代打"}`);
             }
             const sub = availableAgent(run.cycle, agent, [...exhausted], `${run.id}:${step}:sub`);
             if (!sub)
@@ -112,6 +112,38 @@ base) {
         return error.message;
     }
 }
+/**
+ * 寫作步驟的交接：關卡已通過，交接回覆不合格時不丟掉工作，請同一家 agent 只補寫一次。
+ * 補寫前記下 HEAD 與 files 的內容，補寫後一律 reset 回去並還原這些檔案，連補寫自行建立的 commit 也丟棄，
+ * 所以補寫無法改變已通過的關卡。補寫仍失敗（或額度用完）就回傳錯誤，由呼叫端照舊還原並重試。
+ * base 是這一步開始前的 commit；沒有 commit 的步驟（規格、計畫）省略，補寫者會被告知範圍為空。
+ */
+async function settleHandoff(run, outcome, files, base) {
+    const first = finishHandoff(run, outcome, "writer");
+    if (!first)
+        return undefined;
+    const repo = worktreeDir(run.id);
+    const settled = await headCommit(repo);
+    const snap = snapshotPlan(run, files);
+    const cleanup = async () => { await resetTo(repo, settled); restorePlan(run, snap); };
+    info(run, `📎 交接回覆不合格，請 ${outcome.agent} 只補寫交接（不重做工作）：${first}`);
+    let repair;
+    try {
+        // pinned 不找代打，額度用完直接暫停，所以不需要 reset；善後一律交給 finally
+        repair = await agentStep(run, outcome.agent, outcome.step, renderPrompt("handoff-repair", { step: outcome.step, error: first, range: `${base ?? settled}..${settled}` }), { kind: "write", pinned: true, reset: () => { } });
+    }
+    catch (error) {
+        if (error instanceof QuotaPause)
+            return first;
+        throw error;
+    }
+    finally {
+        await cleanup();
+    }
+    if (!repair.r.ok)
+        return `${first}（補寫交接時 Agent 執行失敗：${repair.r.summary}）`;
+    return finishHandoff(run, repair, "writer");
+}
 /** 印出回覆裡的 XML 中繼資料；只供人檢視，關卡仍由程式檢查決定 */
 function reportMeta(run, agent, r) {
     if (!r.meta)
@@ -267,7 +299,7 @@ async function specStage(run) {
     const ids = ac.data.map((a) => a.id);
     if (new Set(ids).size !== ids.length)
         return retry(run, "spec", "驗收條件 id 有重複", "spec", "format_invalid");
-    const handoffError = finishHandoff(run, outcome, "writer");
+    const handoffError = await settleHandoff(run, outcome, PLAN_FILES);
     if (handoffError)
         return retry(run, "spec", handoffError, "spec", "handoff_invalid");
     return succeed(run, "spec", "plan");
@@ -365,7 +397,7 @@ async function planStage(run) {
     const ordered = validatePlan(run);
     if (typeof ordered === "string")
         return retry(run, "plan", ordered, "plan", "format_invalid");
-    const handoffError = finishHandoff(run, outcome, "writer");
+    const handoffError = await settleHandoff(run, outcome, PLAN_FILES);
     if (handoffError)
         return retry(run, "plan", handoffError, "plan", "handoff_invalid");
     acceptPlan(run, ordered);
@@ -730,7 +762,7 @@ async function planFixStage(run) {
         restorePlan(run, snap);
         return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix", "format_invalid");
     }
-    const handoffError = finishHandoff(run, outcome, "writer");
+    const handoffError = await settleHandoff(run, outcome, PLAN_REPLY_FILES);
     if (handoffError) {
         restorePlan(run, snap);
         // 計畫已還原，要保留原本的審查意見，否則下一次修正不知道要改什麼
@@ -888,12 +920,12 @@ async function implementStage(run) {
             await resetTo(repo, before);
             return retry(run, key, `沒有新增或修改任何符合 /${cfg.testPattern}/ 的測試檔。`, "implement", "tests_not_written");
         }
-        const red = await runCommand(target(run, `${task.id}-red`, CMD_AGENT), testCmd);
+        const red = await runCommand(target(run, redStepName(task.id), CMD_AGENT), testCmd);
         if (red.ok && !waiveRed) {
             await resetTo(repo, before);
             return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement", "tests_not_red");
         }
-        const handoffError = finishHandoff(run, outcome, "writer");
+        const handoffError = await settleHandoff(run, outcome, LOCKED_FILES, before);
         if (handoffError) {
             await resetTo(repo, before);
             return retry(run, key, handoffError, "implement", "handoff_invalid");
@@ -940,7 +972,7 @@ async function implementStage(run) {
         info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement", "tests_not_green");
     }
-    const handoffError = finishHandoff(run, outcome, "writer");
+    const handoffError = await settleHandoff(run, outcome, LOCKED_FILES, testsCommit);
     if (handoffError) {
         await resetTo(repo, testsCommit);
         return retry(run, key, handoffError, "implement", "handoff_invalid");
@@ -1082,7 +1114,7 @@ async function applyFix(run, opts) {
         await resetTo(repo, before);
         return again(`${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "tests_deleted");
     }
-    const handoffError = finishHandoff(run, outcome, "writer");
+    const handoffError = await settleHandoff(run, outcome, LOCKED_FILES, before);
     if (handoffError) {
         await resetTo(repo, before);
         return again(`${feedback}\n\n另外，交接回覆不合格，本次修正已還原：${handoffError}`, "handoff_invalid");

package/dist/logs.js

@@ -15,6 +15,9 @@ export const FOOTER_PREFIX = "# exit ";
 export const STDERR_MARK = "[stderr]";
 /** 專案指令（install、測試、checks）的 agent 欄位 */
 export const CMD_AGENT = "cmd";
+/** 紅燈測試指令的步驟名稱；engine 寫 log 與 stats 判斷預期失敗都用這裡，命名不會各改各的 */
+export const redStepName = (taskId) => `${taskId}-red`;
+export const isRedStep = (step) => /^T-\d+-red$/.test(step);
 const segment = (s) => s.replace(/[\s/\\:*?"<>|]+/g, "_");
 /** 下一份 log 的完整路徑；序號接在目錄裡最大的序號之後 */
 export function nextLogFile(dir, stage, step, agent) {

package/dist/stats.js

@@ -1,5 +1,7 @@
-import { CMD_AGENT } from "./logs.js";
+import { CMD_AGENT, isRedStep } from "./logs.js";
 const time = (iso) => (iso ? new Date(iso).getTime() : NaN);
+/** 紅燈階段的測試指令：失敗才是預期結果，意外通過才代表這一步沒過關 */
+const isRedCommand = (kind, step) => kind === "cmd" && isRedStep(step);
 /** 從 log 的檔頭與檔尾算出每個步驟的次數、失敗與耗時，不讀 log 內容 */
 export function computeStats(entries) {
     const byKey = new Map();
@@ -23,7 +25,7 @@ export function computeStats(entries) {
             unfinished += 1;
             continue;
         }
-        if (!footer.ok)
+        if (isRedCommand(kind, header.step) ? footer.ok : !footer.ok)
             s.failed += 1;
         const ms = Math.max(0, end - start);
         s.totalMs += ms;

package/dist/usageInsights.js

@@ -63,10 +63,12 @@ export function usageFindings(input) {
             detail: `重試 ${retries.length} 次（不含審查要求修改與仲裁要求修訂），最多「${top ? retryLabel(top[0]) : "未知"}」（${top?.[1] ?? 0} 次）。以平均每次 ${avg} tokens 估算，重試約 ${waste} tokens。先改該關卡，再縮 prompt。`,
         });
     }
-    if (total.tokens >= 5000 && total.inputTokens / total.tokens >= 0.85) {
+    const freshInput = Math.max(0, total.inputTokens - total.cacheReadTokens);
+    const freshTotal = freshInput + total.outputTokens;
+    if (freshTotal >= 5000 && freshInput / freshTotal >= 0.85) {
         out.push({
-            code: "input_heavy", impactTokens: total.inputTokens, title: FINDING_LABEL.input_heavy,
-            detail: `輸入 ${total.inputTokens}、輸出 ${total.outputTokens}（輸入佔 ${pct(total.inputTokens, total.tokens)}）。上下文可能太大：規格、計畫、測試輸出或一次讀太多檔。`,
+            code: "input_heavy", impactTokens: freshInput, title: FINDING_LABEL.input_heavy,
+            detail: `不含 cache 讀取的輸入 ${freshInput}、輸出 ${total.outputTokens}（輸入佔 ${pct(freshInput, freshTotal)}）；另有 cache 讀取 ${total.cacheReadTokens} 未計入。上下文可能太大：規格、計畫、測試輸出或一次讀太多檔。`,
         });
     }
     const stagesWithTokens = Object.values(byStage).filter((s) => s.tokens > 0).length;

package/package.json

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

package/prompts/handoff-repair.md

@@ -0,0 +1,51 @@
+<role>
+你是交接紀錄員，只負責補寫上一個步驟沒有寫好的 .flow/handoff-response.json。工作本身已經完成並通過檢查，不要重做。
+</role>
+
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
+步驟 {{step}} 的工作已完成，變更範圍是 `{{range}}`，但交接回覆沒有通過檢查，原因：
+
+{{error}}
+</context>
+
+<handoff>
+先閱讀 .flow/handoff-context.md，確認有哪些待處理事項。再寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。只有「待處理事項」（action）可以處置，而且這個步驟的作者只能用 proposed_resolved；「參考資訊」（info）不要放進 dispositions。
+</handoff>
+
+<inputs>
+- .flow/handoff-context.md：待處理事項與參考資訊
+- `git log {{range}}` 與 `git diff {{range}}`：這一步實際做了什麼，處置的理由與證據要以它為準。範圍兩端相同代表這一步沒有產生 commit，這時不要把任何事項標成已處理
+</inputs>
+
+<steps>
+1. 讀 .flow/handoff-context.md 與上述 git 範圍，判斷每個待處理事項這一步有沒有真的處理；沒有把握的事項不要處置。
+2. 只寫入 .flow/handoff-response.json，格式如上。
+</steps>
+
+<constraints>
+- 只能建立或修改 .flow/handoff-response.json。其他檔案的變更與任何 git commit 都會在你結束後被自動丟棄，不會生效。
+- 不要重做或改善這一步的工作，也不要重新跑完整測試。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明補寫了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>.flow/handoff-response.json</file>
+  </files_changed>
+  <concerns>沒有就留空</concerns>
+</result>
+```
+</reply_format>