agentflowctl 0.7.0 → 0.8.0

package/README.md

@@ -103,7 +103,7 @@ agentflowctl status f-xxxx         # 階段、上一步結果、未結交接事
 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 --full  # 逐條顯示 shell 指令，完整顯示多行內容與絕對路徑
 agentflowctl logs f-xxxx 7 --raw   # 原始內容（agent 的 JSON 行）
 agentflowctl resume f-xxxx         # 從暫停、Ctrl-C 或失敗處接續
 agentflowctl cancel f-xxxx
@@ -183,14 +183,14 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 | 標記 | 內容 |
 |---|---|
 | 💬 | agent 的完整文字，不截斷 |
-| 🔧 | 工具呼叫。只顯示第一行，多行時註明共幾行；去掉 `/bin/zsh -lc '…'` 這類 shell 包裝，worktree 內的絕對路徑改成相對路徑 |
+| 🔧 | 工具呼叫。連續的 shell 指令（多半是讀檔、搜尋）收成一行 `🔧 shell 指令 ×N`；其他工具只顯示第一行，多行時註明共幾行，worktree 內的絕對路徑改成相對路徑 |
 | 📊 | token 用量 |
 | 🏁 | 最後結果。與最後一則 💬 相同時不再重印 |
 | ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
 | ❌ | adapter 不認得的錯誤事件 |
 | 📄 | 不是 JSON 的輸出行 |
 
-要看完整的工具內容與重複的最後結果，加 `--full`。adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+要逐條看 shell 指令、完整的工具內容與重複的最後結果，加 `--full`。adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
 
 最後一段「錯誤」整理出結束碼、agent 回報的失敗、錯誤事件與 stderr：
 
@@ -200,7 +200,7 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 檔案 /repo/.agentflowctl/runs/f-xxxx/logs/003-plan-plan-codex.log
 
 💬 先讀 spec.md 與 acceptance.json
-🔧 shell: cat .flow/spec.md
+🔧 shell 指令 ×1（--full 查看）
 🏁 失敗：stream disconnected before completion
 
 ── 錯誤 ──
@@ -323,9 +323,9 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 
 人工確認計畫是為了擋住方向錯了還一路做下去。預設用三層機制取代它；加上 `--manual-plan` 時，三層都過了仍會停下來等你。
 
-**格式與覆蓋率。** 每次撰寫或修改計畫之後，都要重新通過 zod、任務相依、無循環、每條驗收條件都有任務負責。沒過就還原。
+**格式與覆蓋率。** 每次撰寫或修改計畫之後，都要重新通過 zod、任務相依、無循環、每條驗收條件都有任務負責，而且每個任務最多對應兩條驗收條件（一次只做一件事，最多兩件）。沒過就還原。
 
-**跨模型審查。** 審查看需求覆蓋、驗收條件能不能測、任務大小與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
+**跨模型審查。** 審查看需求覆蓋、驗收條件能不能測且一條只寫一個行為、任務是否只做一件事（最多兩件）與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
 
 **僵持時仲裁。** 兩種情況會觸發：這輪審查意見和上一輪一樣，或已達重試上限。仲裁者只判斷一件事：照這份計畫實作，能不能滿足需求。
 
@@ -346,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` 時失敗 |

package/dist/cli.js

@@ -369,7 +369,7 @@ program
     .command("logs <id> [seq]")
     .description("列出 log；指定編號（或 --latest）時顯示解析後的內容，最後附上錯誤整理")
     .option("--latest", "顯示最新一份 log", false)
-    .option("--full", "完整顯示工具內容（多行指令、絕對路徑）與重複的最後回覆", false)
+    .option("--full", "逐條顯示 shell 指令，完整顯示工具內容（多行指令、絕對路徑）與重複的最後回覆", false)
     .option("--raw", "顯示原始內容（agent 的 JSON 行）", false)
     .action((id, seq, opts) => {
     mustGetRun(id);

package/dist/engine.js

@@ -35,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();

package/dist/logs.js

@@ -99,25 +99,15 @@ function findError(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 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":
@@ -151,12 +141,25 @@ function analyzeLog(text, full) {
     }
     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) {
+                    if (!full && isShellTool(ev)) {
+                        shells++;
+                        continue;
+                    }
+                    if (ev.kind !== "usage")
+                        flushShells();
                     const s = renderEvent(ev, full, lastText);
                     if (s)
                         lines.push(s);
@@ -171,6 +174,7 @@ function analyzeLog(text, full) {
             }
             const json = tryJson(line);
             if (!json) {
+                flushShells();
                 lines.push(`📄 ${line}`);
                 continue;
             }
@@ -179,10 +183,12 @@ function analyzeLog(text, full) {
                 skipped++;
                 continue;
             }
+            flushShells();
             lines.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
             if (err.fatal)
                 errors.push(`錯誤事件：${indent(err.message)}`);
         }
+        flushShells();
         if (skipped)
             lines.push(`（另有 ${skipped} 行其他事件未顯示，可用 --raw 查看）`);
     }

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.7.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 的格式：