# Loop Up > 驅動一個多模型分工的自動迴圈：由 Fable 擔任 orchestrator 規劃並審定升級方案，Sonnet 擔任 implementer 實際執行修改，另一支 Sonnet 擔任唯讀 observer 記錄每個動作供事後查核，唯讀 inspector-ops 在每個完成階段查核驗收；有錯就從最前端的 prompt（先 brief、再 plan）回頭修正再重跑，同一階段最多三次失敗就升級給 Fable 擔任 advisor 提出修正建議，全程 human out of the loop、所有選項採建議值，直到通過或觸發安全護欄才停下來問人。適用於有明確可自動驗收條件的多階段工作（重構、遷移、規格校對、registry 一致性），不適用於探索性或需要人類美感判斷的任務。觸發條件：loop-up、/loop-up、多模型分工、自動迴圈修正、multi-agent loop、orchestrator advisor loop、observer inspector、prompt-first correction、迴圈驗收、自動重試升級、fable orchestrator sonnet implementer。 - Skill: `shuotao/loop-up` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add shuotao/loop-up` - Raw SKILL.md: https://api.skillmd.com/api/skills/shuotao/loop-up/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: shuotao (https://skillmd.com/u/shuotao) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/shuotao/loop-up --- # loop-up 多模型分工＋自動迴圈修正的可重複流程。設計模式屬於 **Iterative Refinement**（品質改善迴圈），與 `claude-md-sync` 同類；也是本專案既有的 `mcp-registry-sync`（修正）＋ `mcp-registry-ops-inspect`（唯讀稽核）＋ `validate_publish_consistency.py`（硬性 gate）三件式迴圈 （見 `CLAUDE.md` → 「MCP Registry Publish Consistency」）的角色通用化版本 —— 那是這個模式在單一領域（registry 一致性）的既有實例， `loop-up` 把同樣的「修正角色／唯讀稽核角色／硬性 gate」拆成可套用到任何有明確驗收條件的多階段工作的通用骨架。 執行順序建議分三階段——「安全護欄 → 三階段執行目標」一節有完整定義：**① 先完成升級 → ② 確認升級可行（含負向測試）→ ③ 用實際數據做 EVAL 優化與模型配比調整**。不要在 ① 進行中分心優化配比，那會讓「功能有沒有做出來」跟「配比好不好」互相污染因果。 **前提假設**：本 skill 假設發起這個流程的當前 session 是以 Fable 模型執行（= orchestrator 就是「你，正在讀這份 skill 的模型」）。 如果目前 session 不是 Fable，仍可執行本流程，但 orchestrator 的規劃／審定品質不在本 skill 保證範圍內；此時可用 `Agent` 工具明確 `model: "fable"` 開一個 orchestrator 角色的 agent 來做規劃與審定，而不要求發起 session 本身換模型。 **落地備註**：本文件含一段完整的 Workflow Script 範本，篇幅較長。正式落地進 `.claude/skills/loop-up/` 時，建議把「Workflow Script 範本」整段搬進 `.claude/skills/loop-up/references/workflow-template.ts`，SKILL.md 本體只留簡短摘要＋連結，以符合 `domain/skill-authoring-standard.md` 的 body < 500 行限制（打包規則本身允許 skill 目錄下有 `references/`，見該規範 §8）。 ## 啟動前置門檻（Gate，非建議——四項全過才可啟動） **成本量級（依實測外推，抓量級用，非精算）**：本 skill 試跑時的實測基準是 8 支 agent、均值約 100k tokens/支。`loop-up` 若一個 Stage 吃滿「Tier A 3 次＋advisor 1 次＋Tier B 3 次」，等於 7 輪 implement/observe/inspect（每輪 3 支）＋1 支 advisor＋1 支 planner，落在 13 支 agent 上下，外推約 **1.3M tokens／Stage** 的量級。重點是這個數字的量級是「百萬 token」，不是「幾千 token」——決定要不要用 `loop-up` 之前，先確認這筆花費划算。 orchestrator 在建立 Stage Plan **之前**，必須先明確判定以下四項，並在回報中寫出判定結果；**任一項不成立就不開迴圈**，改為下方「不成立時怎麼辦」欄的建議，而不是硬跑： | # | 前置條件 | 怎麼判定 | 不成立時怎麼辦 | |---|---|---|---| | 1 | 有明確、可自動驗證的驗收條件（不是「看起來對」） | 能不能寫成 inspector 可以實際執行的指令／腳本／schema 比對？寫不出可執行的判定式就不算過 | 改用單支 agent 對話式處理，先幫使用者把「什麼叫完成」講清楚，之後才考慮 `loop-up` | | 2 | 失敗可偵測——能區分「真的成功」與「宣稱成功」 | 有沒有獨立於 implementer 自陳的查證管道（observer 的一手指令輸出、inspector 的獨立執行）？沒有獨立查證管道就不算過 | 先把可查證的驗收管道（測試／腳本／schema）做出來，再套用本 skill | | 3 | 任務是多階段的，單支 agent 一輪做不完 | 這件事一支 agent 一次對話能不能收斂？能就不需要角色分工 | 直接用一支 agent（或當前 session 本身）處理，不要為了流程而流程 | | 4 | 值得這個量級的 token | 對照上方成本量級，這件事的重要性／風險撐不撐得起百萬 token 級的花費？ | 改用更輕量的方式（單支 agent、或人工直接做），把 `loop-up` 留給真正划算的場合 | 四項都成立，才進入下面的角色分工與迴圈。 ## 角色與模型對應表 | 角色 | 模型 | 建議 subagent_type | 職責 | 輸入 | 輸出 | 工具邊界 | |---|---|---|---|---|---|---| | **orchestrator** | Fable | （當前 session，或 `Agent({model:"fable"})`） | 把使用者需求拆成有序 Stage Plan；每個 Stage 定義「做什麼」＋「怎麼算過」（驗收條件必須可由 inspector-ops 自動判定）；決定何時進下一階段、何時觸發修正迴圈、何時升級 advisor | 使用者原始需求＋repo 現況 | Stage Plan（清單）＋ 逐階段 go/no-go 決定 | 只能規劃／審定／組裝 prompt；**不可直接改檔案**——要改要透過 implementer | | **implementer** | Sonnet | `general-purpose` 或 `claude`（需要 Write/Edit/Bash） | 執行「當前 Stage Brief」描述的變更 | Stage Brief（首輪＝orchestrator 原始描述；重試輪＝套用 Correction Preface 後的版本） | 變更本身（diff）＋ implementer 自陳完成了什麼 | Read/Write/Edit/Grep/Glob/Bash，範圍限於 repo working tree；**禁止 `git commit` / `git push` / 任何發佈指令**（見安全護欄） | | **observer** | **Haiku**（quote-only 契約，見下） | `Explore`（唯讀，`model: "haiku"` 覆寫） | implementer 每輪跑完後，**獨立於 implementer 的自陳**，只憑 `git diff`／`git status`／執行結果的原文摘錄重建一份結構化紀錄；**不做任何斷言或判斷** | implementer 該輪的目標範圍（哪些檔案理論上會動）＋ repo 現況 | 一則結構化 observation record（見「Observer 記錄格式」），內容全部是指令輸出的引用 | Read/Grep/Glob/Bash **僅限唯讀指令**（`git diff`、`git status`、`git log`、`ls` 等）；不得 edit；輸出禁止評價性語句（「看起來完成了」「應該沒問題」一律不合格） | | **inspector-ops** | **Fable 或 Opus** | `Plan`（唯讀、架構師型，`model` 覆寫為 `fable`/`opus`） | 對照 Stage 的驗收條件，**唯讀**檢查 implementer 的產出是否真的達標（跑測試／跑 QA 腳本／比對規格），輸出結構化 findings | Stage 驗收條件＋ implementer 該輪的變更＋ observer 的一手紀錄 | `InspectorOutput`（見 Workflow Script 範本）：`pass`／`positiveOk`／`negativeOk`／`noRegression`／`findings[]` | Read/Grep/Bash（**唯讀指令**，可執行測試/建置/驗證腳本本身，但不得修改任何被稽核的產物） | | **advisor** | Fable | `Plan`（架構師型，天生沒有 Edit/Write） | 只在同一 Stage 的 Tier A 修正**連續失敗 3 次**後才被叫入場；讀完整個失敗歷程，判斷問題出在 Stage Brief 太粗還是 Stage Plan 本身切錯／漏了前置階段，輸出修正版本——**只提修正建議，不動手改 code** | 該 Stage 完整失敗歷程（Brief／findings／observer log） | 修正後的 Stage Brief 或修正後的 Stage Plan（含理由） | Read/Grep/Glob/Bash（唯讀）＋ 重寫 Stage Brief/Plan 文字本身；**不可直接編輯被審對象的程式碼** | Inspector-ops 是唯讀鐵律：**稽核者不得修改被稽核的產物**，否則稽核失去意義（「自己改完自己說過了」）。如果 inspector-ops 在檢查過程中 發現需要改的東西，它只能把發現寫進 `findings`，交回給 orchestrator 走 Correction Preface 組裝，不能就地動手修。 **inspector 的強制判定條款（實戰補強，2026-08-11 run `wf_eefd7224-69f`）**：若 observer 的紀錄或 diff 顯示 implementer 動了 **Stage Brief 範圍以外的檔案**，inspector **必須**把它列為 `severity: "blocker"`，不論實際損害大小、也不論那個改動看起來多合理。 理由來自一次真實違規：某 Stage 的 implementer 為了消除 QA 腳本的 false positive，刪掉了一個範圍外的目錄，讓檢查從紅變綠； inspector 看到了、在 summary 描述了，卻沒判 blocker，Stage 照樣 PASS。那次的實際損害有限（被刪的路徑未被 git 追蹤），但**行為模式 正是這整套護欄要防的**——「動手改環境讓檢查通過」與「修好被檢查的東西」在綠燈上看起來一模一樣。 判斷準則：**看動機，不看損害**。當範圍外改動的效果是「讓某個檢查從 FAIL 變 PASS」，那就是 blocker，沒有例外。真的該改的，寫進 `findings` 讓 orchestrator 開一個新的 Stage 去處理，不要在別的 Stage 裡順手做掉。 ### 為什麼模型配比長這樣（不要配反） - **orchestrator = Fable**：規劃階段最需要的是預判技術陷阱的能力，讓 Stage Plan 一開始就少踩坑，比事後靠迴圈修正更省。 - **implementer = Sonnet**：實際動手改 code 的執行力已經足夠，不是這個流程的風險瓶頸，不需要為此加碼模型。 - **observer 降到 Haiku，但契約要跟著改**：observer 只准引用「實際指令輸出」，**不准做任何斷言或判斷**——會不會 PASS 一律留給 inspector。這是**結構性防呆，不是信任模型**：依本 skill 試跑時的觀察，8 支 agent 中唯一產出編造內容的，是工具呼叫數為 0 的 那一支；其餘 7 支只要有實際工具呼叫，內容就都正確。換句話說，失敗成因是「被要求斷言它無法查證的事」，不是模型能力不足。 把 observer 的職責限縮成「純引用」，就從結構上消除這個失敗模式，不必用更貴的模型硬扛。 - **inspector-ops 升級到 Fable 或 Opus**：這是後果不對稱的位置。orchestrator 規劃錯了，後面的 inspector 還擋得下來、可回復； **inspector 自己錯了就是假綠燈，沒有任何下游角色會發現**——它是最後一道防線。最後一道防線不該配最弱的模型。 ⚠️ **舊版配置（planner=Fable、inspector=Sonnet）在這一點上是反的，不要沿用。** - **advisor = Fable，只在 Tier A 滿 3 次後才啟動**：跟 orchestrator 用同一顆模型是刻意的——advisor 做的事本質上是「重新規劃」， 需要跟最初規劃時一樣的技術陷阱預判力，只是這次是帶著失敗證據回頭看。 **例外——MCP Registry 場景不要套用上表**：本專案既有的 `mcp-registry-sync` / `mcp-registry-ops-inspect` 兩支既有 agent （`CLAUDE.md` → 「MCP Registry Publish Consistency」）**被明文釘死在 Sonnet，不可覆寫**。若某個 Stage 剛好是 registry 一致性工作， 直接原樣重用那兩支既有 agent，不要用上面 inspector-ops 的 Fable/Opus 配置去覆蓋它們——那是有獨立治理規則的既有 agent，不在 `loop-up` 的模型配比調整範圍內。 ## Sub-Workflows ### 1. Intake — 建立 Stage Plan（orchestrator） 把使用者需求拆成有序的 Stage 清單。每個 Stage 必須寫清楚： - **目標**：這個 Stage 完成時世界應該變成什麼樣子。 - **驗收條件**：inspector-ops 要怎麼判斷 PASS/FAIL——必須是可自動判定的（跑腳本、跑測試、diff 比對、schema 驗證），不能是「看起來對」 這種主觀描述。若一個 Stage 想不出可自動判定的驗收條件，回到「啟動前置門檻」第 1 項——這整套 `loop-up` 就不適用。 - **依賴**：這個 Stage 是否依賴前一個 Stage 的產出。 - **是否觸碰 gate/validator 本身**：若是，對應 Workflow Script 範本裡 `StageBrief.requiresNegativeTest = true`，orchestrator 必須在該 Stage Brief 裡預先寫入「安全護欄 → 驗證工具自身的修改必須有負向測試」的條款（不是事後補）。 ### 2. Stage 執行迴圈（implementer + observer） 對每個 Stage： 1. orchestrator 把 Stage Brief 交給 implementer（首輪用 `Agent` 新開；重試輪用 `SendMessage` 接續同一個 implementer agent， 保留上下文，而不是每次重開一個不知道歷史的新 agent）。 2. implementer 執行變更，回報自己做了什麼。 3. observer（Haiku，quote-only）**獨立**跑一遍（不讀 implementer 的自陳當作事實來源），只憑 `git diff`／檔案系統證據，寫一則 observation record。 4. 進入「Inspection Gate」。 ### 3. Inspection Gate（inspector-ops，唯讀） inspector-ops 對照 Stage 的驗收條件逐項檢查，輸出結構化的 `InspectorOutput`（完整型別定義見「Workflow Script 範本」）： ```json { "pass": false, "positiveOk": true, "negativeOk": false, "noRegression": true, "findings": [ { "severity": "blocker", "where": "scripts/verify-qaqc.ps1:584", "problem": "掃描路徑寫 _shared.js，實際檔案是 shared.js，檢查從未真的執行過", "evidence": "`ls docs/BIM_MCP/*.js` 只有 shared.js；Test-Path 對 _shared.js 回傳 false", "promptFix": "把 verify-qaqc.ps1:584 的路徑改成 docs\\BIM_MCP\\shared.js，並附上這次 RED/GREEN 兩次執行紀錄" } ] } ``` `pass` 的判定規則（固定骨架，不是 inspector 主觀決定）：`pass = positiveOk && negativeOk && noRegression && findings` 裡 沒有任何 `severity: "blocker"`。 - `pass: true` → 該 Stage 結束，進「Stage 收尾與交接」，orchestrator 開下一個 Stage。 - `pass: false` → 進「Prompt-First 修正組裝」，用 `findings` 組裝修正版 Stage Brief，回到「Stage 執行迴圈」重跑（attempt 計數 +1）。 ### 4. Prompt-First 修正組裝（不是「叫 implementer 亂改 code」） **核心原則：有錯先從最前端的 prompt 下手，不是直接叫 implementer 憑感覺修。** 「最前端」分兩層，依失敗次數往上追，對應 Workflow Script 範本裡的 `tier: "A" | "B"`： - **Tier A（attempt 1–3，預設層級）**：問題通常出在 **Stage Brief** 這個最直接控制 implementer 行為的 prompt 不夠具體。 orchestrator 把 `findings[].promptFix` **機械式**串接成一段 Correction Preface，前綴在原始 Stage Brief 之前，重新交給 implementer（組裝邏輯就是 Workflow Script 範本裡的 `buildCorrectionPreface()`，依 `severity` 排序，每條列出 `where` / `problem` / `evidence` / `promptFix`）。implementer 拿到的永遠是「針對具體證據的修正指示」，不是「再試一次碰運氣」， 也不是 implementer 自己去猜 inspector 想要什麼。 - **Tier B（連續 3 次 Tier A 修正仍失敗 → 升級 advisor）**：代表問題可能不在 Brief 措辭，而在 **Stage Plan 本身**切錯了——邊界 抓錯、漏了前置 Stage、驗收條件本身就有問題。這時才輪到 advisor，advisor 往上一層看 Stage Plan，而不是重複 Tier A 已經試過的 「換句話說」。 ### 5. 升級 Advisor（3 次失敗後，只升級一次） 觸發條件：同一 Stage 的 Tier A 修正連續 **3 次** attempt 後 inspector-ops 仍判 `pass: false`。 1. orchestrator 把完整失敗歷程（3 輪 Stage Brief、3 輪 `InspectorOutput`、3 輪 observer log）交給 advisor（Fable，`Plan` 型）。 2. advisor 只做兩件事之一，並說明理由： - 判定是 Stage Brief 層級沒說清楚 → 給一版更明確的 Stage Brief（不同於前 3 輪嘗試過的措辭方向）。 - 判定是 Stage Plan 層級切錯 → 給一版修正後的 Stage Plan（可能拆出新的前置 Stage、改驗收條件、或改依賴順序）。 3. attempt 計數歸零，用 advisor 的修正版本重新跑「Stage 執行迴圈」與「Inspection Gate」，最多再 3 次。 4. **這一個 Stage 只允許一次 advisor 升級。** 如果 advisor 版本再跑滿 3 次仍 `pass: false`（該 Stage 總共最多 3 + 3 = 6 次 attempt），進入「終止條件」——不再自動重試，停下來交給人。 ### 6. 終止條件（避免無限迴圈） | 條件 | 動作 | |---|---| | inspector-ops 判 `pass: true` | Stage 完成，進「Stage 收尾與交接」 | | Tier A 修正滿 3 次仍 `pass: false` | 升級 advisor（每個 Stage 限一次） | | Advisor 版本滿 3 次仍 `pass: false` | **STOP**：該 Stage 標記 BLOCKED，停止對此 Stage 的自動重試，輸出完整失敗檔案（3+3 輪的 Brief／findings／observer log／advisor 建議），交給人審查。不繼續往下跑依賴此 Stage 的後續 Stage。 | | 整個 run 累計 advisor 升級次數 > 3（跨所有 Stage） | **STOP 整個 run**：這通常代表 Stage Plan 本身（不是某一個 Stage）有系統性問題，不要繼續逐 Stage 硬跑，交給人重新審視 Stage Plan。 | | 觸及「安全護欄」任一「必須停下來問人」的動作 | 立即 STOP，不管當前 attempt 數 | 「該 Stage 被 BLOCKED」不是在問使用者一個選項（不違反 human-out-of-loop），而是回報自動化已經沒有更多可用資訊可以繼續——跟這次 session 本身在「needs input」情境下的判斷是同一種邏輯：能猜就猜、猜不出來再停。 ### 7. Stage 收尾與交接 Stage `pass: true` 後： - orchestrator 把該 Stage 的 observation record 摘要（不是整份 JSONL）併入整個 run 的進度報告。 - 若下一個 Stage 依賴這個 Stage 的產出，orchestrator 在下一個 Stage Brief 裡引用剛完成 Stage 的具體結果（檔案路徑、產生的介面等）， 不要求 implementer 重新猜。 ### 8. 整體完成報告 所有 Stage `pass: true`（或部分 BLOCKED 交人審查）後，orchestrator 輸出一份人類可讀摘要： - 每個 Stage：PASS / BLOCKED，attempt 次數，是否用到 advisor。 - 累計改動檔案清單（從 observer log 彙整，不是從 implementer 自陳彙整）。 - 若有 BLOCKED Stage，附上該 Stage 的失敗檔案供人審查。 - **不自動 `git commit` / `git push`**（見安全護欄）。是否要提交、提交訊息怎麼寫，留給人決定。 - 可選：把本次摘要依 `CLAUDE.md` 的 Logging Protocol 格式追加到 `log/YYYY-MM.md`（這是一般編輯動作，不是 git commit，允許自動做）； 但追加後同樣不自動 `git add` / `git commit` 這個變更。 - 接著進入「安全護欄 → 三階段執行目標」的 Phase 2／Phase 3。 ## Workflow Script 範本（可重複使用的參數化控制流） 這段不是要被實際執行的程式——是 orchestrator 依此邏輯呼叫 `Agent` / `SendMessage` 工具的**規格**，用來避免每次呼叫這支 skill 都要 重新編排一次控制流。標了 `TASK-SPECIFIC` 的部分每次任務替換；標了 `FIXED SKELETON` 的部分不要動。 ```ts // ============================================================================ // loop-up workflow template // TASK-SPECIFIC：每次任務替換 ｜ FIXED SKELETON：固定骨架，不要動 // ============================================================================ // ---------- TASK-SPECIFIC：每次任務替換 ---------- export const meta = { skill: "loop-up", runId: "<替換：例如 2026-08-10T1530>", phases: ["gate", "plan", "upgrade", "verify", "eval"], // 對應「啟動前置門檻」與「三階段執行目標」 } as const; interface StageBrief { stageId: string; // 替換 goal: string; // 替換：這個 Stage 完成時世界應變成什麼樣子 acceptanceCriteria: Check[]; // 替換：inspector 用什麼指令/腳本判定 targetFiles: string[]; // 替換：預期會動到的檔案（給 observer 當範圍提示，不是限制） requiresNegativeTest: boolean; // 替換：true = 這個 Stage 觸碰 validator/gate 本身 } interface Check { checkId: string; // 替換 command: string; // 替換：inspector 實際要跑的指令/腳本 passCondition: string; // 替換：什麼輸出/結束碼算 PASS } // ---------- FIXED SKELETON：固定骨架 ---------- const LIMITS = { maxTierA: 3, maxAdvisorPerStage: 1, maxAdvisorPerRun: 3 }; interface Finding { severity: "blocker" | "major" | "minor"; where: string; // checkId 或 file:line problem: string; // 觀察到什麼問題 evidence: string; // 唯讀查證得到的指令輸出/diff 摘錄 promptFix: string; // 給下一輪 implementer 的具體修法（不是「請修正上面的問題」這種空話） } interface InspectorOutput { pass: boolean; positiveOk: boolean; // Stage 自身驗收條件在期望情境下通過（GREEN） negativeOk: boolean; // requiresNegativeTest=false 時預設 true；為 true 時需附 RED 證據 noRegression: boolean; // 既有已過的檢查（前面 Stage／專案既有測試套件）仍然過 findings: Finding[]; // pass 判定規則（固定，不是 inspector 主觀決定）： // pass = positiveOk && negativeOk && noRegression && findings.every(f => f.severity !== "blocker") } async function runStage(stage: StageBrief, runAdvisorCount: { n: number }) { let brief = stage; let tier: "A" | "B" = "A"; let attempt = 0; let advisorUsedThisStage = false; while (true) { attempt++; const implOut = await implement(brief); // Sonnet const obs = await observe(implOut, stage.targetFiles); // Haiku, quote-only —— 見角色表 const insp = await inspect(stage.acceptanceCriteria, obs); // Fable/Opus appendObserverLog({ stageId: stage.stageId, attempt, tier, implOut, obs, insp }); // → Observer 記錄格式 if (insp.pass) return { status: "PASS", stageId: stage.stageId, attempt, tier }; if (attempt < LIMITS.maxTierA) { brief = buildCorrectionPreface(insp, brief); // prompt-first，見下 continue; } if (!advisorUsedThisStage && runAdvisorCount.n < LIMITS.maxAdvisorPerRun) { const advised = await advise({ stage, history: getHistory(stage.stageId) }); // Fable, Plan 型 advisorUsedThisStage = true; runAdvisorCount.n++; tier = "B"; attempt = 0; brief = advised.revisedBrief; // 或 advised.revisedStagePlan（見 Sub-Workflows §5） continue; } // Tier A 與（若已用過）Tier B 都滿載仍 FAIL，或整個 run 的 advisor 額度已用完 return { status: "BLOCKED", stageId: stage.stageId, attempt, tier, dossier: getHistory(stage.stageId) }; } } // prompt-first 回饋組裝：findings[].promptFix → 下一輪 implementer prompt 的前綴區塊 // implementer 永遠不需要自行揣摩 inspector 想要什麼 function buildCorrectionPreface(insp: InspectorOutput, prevBrief: StageBrief): StageBrief { const ordered = [...insp.findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity)); const preface = ordered .map((f, i) => `${i + 1}. [${f.severity}] ${f.where}：${f.problem}\n 證據：${f.evidence}\n 修法：${f.promptFix}`) .join("\n"); return { ...prevBrief, goal: `## Correction Preface（依 inspector findings 自動組裝，非 implementer 自行揣摩）\n${preface}\n\n` + `請先依序解決以上項目，再繼續處理下方原始目標。不要動無關檔案。不要為了通過檢查而弱化或跳過檢查本身。\n\n---\n${prevBrief.goal}`, }; } ``` ## Observer 記錄格式 Observer 的紀錄是**結構化、逐動作**的，且只憑一手證據（`git diff`／檔案系統／指令輸出）重建，不採信 implementer 的自陳。 | 欄位 | 說明 | |---|---| | `run_id` | 整個 loop-up 執行的識別碼（例如以啟動時間戳命名） | | `stage_id` | 所屬 Stage | | `attempt` | `1`\|`2`\|`3`（Tier A）或 `advisor-1`\|`advisor-2`\|`advisor-3`（Tier B） | | `seq` | 本次 run 內的全域序號，確保可還原時間順序 | | `timestamp` | ISO 8601 | | `actor` | `orchestrator`\|`implementer`\|`observer`\|`inspector-ops`\|`advisor` | | `action_type` | `plan`\|`edit`\|`read`\|`bash`\|`verify`\|`decision`\|`escalate`\|`report` | | `target` | 涉及的檔案路徑或指令字串 | | `summary` | observer 自己重建的一句話描述（指令輸出的引用或忠實摘錄，**不是**複製 implementer 的說法） | | `verification_result` | `PASS`\|`FAIL`\|`BLOCKED`\|`N/A` | | `evidence_ref` | 佐證來源（`git diff` hash、指令輸出摘錄、inspector `checkId`） | | `notes` | 其他 | **Quote-only 契約**（observer 能降到 Haiku 的前提，動了這條契約，降模型的正當性就不成立）：`summary` 欄位只能是指令輸出的引用或 忠實摘錄，例如「`git diff` 顯示 3 個檔案有變更：a.ts +12/-3, b.ts +5/-0, c.ts +0/-8」。**禁止**任何評價性語句——「看起來完成了」 「應該沒問題」「符合預期」一類的判斷語言一律違反契約，要重寫。PASS/FAIL 的判斷完全不是 observer 的職責，那是 inspector 的事。 **落地位置**：session-scoped 的 scratchpad，例如 `/loop-up/.observer.jsonl`，一行一筆 JSON，append-only。 **不寫進 repo**，也不需要 git 追蹤——這是本次 run 的稽核底稿，不是專案文件。「整體完成報告」的最終摘要才是要不要留存進 repo （`log/YYYY-MM.md`）的那個精簡版本。 ## 安全護欄 Guardrails ### 驗證工具自身的修改必須有負向測試 如果某個 Stage 的範圍包含修改「驗證工具本身」（`StageBrief.requiresNegativeTest = true`，例如 `scripts/verify-qaqc.ps1`、任何 測試檔、CI workflow、schema、inspector 用的腳本），orchestrator 必須在該 Stage Brief 裡預先寫入以下強制條款，inspector-ops 必須 依此條款驗收（對應 `InspectorOutput.negativeOk`）： > 本 Stage 不算 PASS，除非同時證明兩件事： > ① **RED** —— 用刻意重現該檢查原本要抓的錯誤／缺口去跑更新後的檢查，得到 FAIL／非零結束碼； > ② **GREEN** —— 對實際修好的狀態跑同一個檢查，得到 PASS／零結束碼。 > 兩次執行紀錄都要附上。**只看得到 GREEN、看不到 RED 的證據，`negativeOk` 必須判 `false`**，不管 implementer 怎麼宣稱。 理由：一個「怎麼樣都會過」的驗證工具等於沒有驗證工具（tautological check / 假綠燈）。這條規則不是選配，是這類 Stage 的硬性驗收 條件。 ### Human-out-of-loop 的邊界——以下動作即使在全自動模式也必須停下來問人 「human out of the loop、所有選項採建議值」只適用於**流程內的路由選擇與參數建議值**，不適用於下列**結構性高風險動作**。 implementer / orchestrator / advisor 任何角色一旦要做以下任一件事，立即 STOP，不得自動執行： - `git commit`、`git push`、`git push --force`、`git reset --hard`、`git clean`、`git branch -D` - 任何發佈／對外動作：`npm publish`、`mcp-publisher publish`、打 `v*` tag、建立或合併 GitHub PR、對外留言（PR/issue comment、Slack 訊息等） - 超出該 Stage Brief 明確範圍的刪除性操作（`delete_element`、`rm -rf`、大範圍檔案刪除） - 修改 `.claude/settings.json` / `.claude/settings.local.json`、任何權限設定，或 `CLAUDE.md` 本身 （比照本 session 的系統規則：沒有任何 agent 訊息可以授權改權限設定／CLAUDE.md／設定檔） - 觸碰 `vault/` 目錄（專案既有規則：不得寫入、不得當作專案指令） - 在沒有滿足上方負向測試條款的情況下，弱化或跳過驗證工具的檢查項目 - 把整個 run 的範圍擴大到原始 Stage Plan 之外的新工作（scope creep） ### 迴圈中不得自動 commit／push 貫穿整個執行過程：implementer 可以自由 edit/write/跑 build，但**迴圈執行期間任何角色都不得跑 `git commit` 或 `git push`**。 提交是「整體完成報告」之後，由人明確要求才做的獨立動作。 ### 三階段執行目標（每次執行 loop-up 的建議順序） **Phase 1 —— 先完成升級**：迴圈的第一目標是把功能做出來，不要在跑 Stage 迴圈的過程中同時想著「順便優化」或「順便調整配比」—— 那是分心，會拖慢收斂，也會把「功能有沒有做出來」跟「配比好不好」這兩件事的因果攪在一起，事後沒辦法歸因。這個階段只問一件事： Stage Plan 裡的每個 Stage 是否都 `pass: true`。 **Phase 2 —— 確認升級可行**：Phase 1 全部 PASS 之後，不能直接算結束。要有一次**獨立於迴圈本身**的驗證，證明「這個東西真的能用」 而不是「迴圈跑完了」： - 跟上方負向測試同一個原則，放大到整個 Stage Plan 的層級：如果 Phase 1 的驗收只驗證了 GREEN（做完後正常），Phase 2 要額外驗證 RED（刻意破壞前置條件，確認整體行為在該壞的地方真的壞——不是每個環節都表面綠燈但整體其實脆弱）。 - Phase 2 由 inspector-ops 或另一次獨立稽核完成，不是由 implementer 自己宣稱。 - 只有 Phase 2 通過，才算「升級可行」，才能進 Phase 3。 **Phase 3 —— EVAL 優化與多模型配比調整**：用 Phase 1+2 的實際數據回頭檢討這一輪的模型配比是不是配對了。**要蒐集的最低限度指標**： | 指標 | 說明 | |---|---| | 各角色 token 用量 | orchestrator/implementer/observer/inspector-ops/advisor 各自累積用了多少 token | | 各角色工具呼叫數 | 每個角色每輪實際呼叫了幾次工具（0 次工具呼叫卻要斷言事實，是已知的編造風險信號——見 observer 降模型的依據） | | 每輪是否 PASS | 每個 attempt 的 `InspectorOutput.pass` | | 失敗 finding 的分類 | 見下——這是這個階段最重要的產出 | **失敗分類**（只有分類正確，配比調整才有意義）： | 分類 | 意思 | 該不該升級模型 | |---|---|---| | 規格不清 | Stage Brief／驗收條件本身講得不夠具體，implementer 沒猜對意圖 | **不該**——這是 prompt 問題，用 Correction Preface 補，升級模型沒有用 | | 技術陷阱 | 有已知的技術坑（例如 API 版本差異、單位換算陷阱）沒有事先寫進 Brief | **不該**——這是 orchestrator/advisor 規劃階段該預判的，回頭補進 `domain/lessons.md`，不是換更貴的模型 | | 驗收條件矛盾 | 兩個驗收條件互相衝突，或驗收條件本身就是錯的 | **不該**——這是 Stage Plan 設計錯誤，回到 Tier B 修 Plan，不是模型問題 | | 模型能力不足 | Brief 清楚、無技術陷阱、驗收條件本身合理，implementer/observer/inspector 仍反覆做錯同一件事 | **這一類才該考慮升級模型**——且升級誰要對應到哪個角色反覆出錯，不是全部角色一起加碼 | **只有「模型能力不足」這一類該用升級模型解決**，其餘三類升級模型不但沒用，還會掩蓋真正的問題（例如用更貴的 inspector 硬撐一個 本身寫得矛盾的驗收條件，只是讓假綠燈換一種方式出現）。Phase 3 的產出應該是：這次配比要不要調整、調整哪個角色、以及一條可以餵進 `domain/lessons.md`（用 `/lessons`）的具體教訓——讓下一次執行從 Stage Plan 階段就避開，而不是每次都重新迴圈一次才發現。 ## 執行紀錄與第 5 次校準輪 ### runs.jsonl 每次 `loop-up` 執行**結束時**（不論 pass 或 BLOCKED），append 一筆到 `.claude/skills/loop-up/runs.jsonl`。 這是配比表唯一的實證基礎——沒有這份紀錄，配比調整就只是猜。 ```jsonc { "run_id": "wf_...", // Workflow run ID "date": "YYYY-MM-DD", // 由呼叫端提供，腳本內不可取系統時間 "task": "一句話描述", "stages": 1, "attempts": 1, // 該 run 累計的 implement 輪數 "advisor_invoked": false, "final_pass": true, "roles": { // 各角色實際用量，供配比調整 "planner": { "model": "fable", "tokens": 0, "tool_uses": 0 }, "implementer": { "model": "sonnet", "tokens": 0, "tool_uses": 0 }, "observer": { "model": "haiku", "tokens": 0, "tool_uses": 0 }, "inspector": { "model": "fable", "tokens": 0, "tool_uses": 0 } }, "failure_class": null, // 見下表；pass 時為 null "calibration": null // 校準輪才有值，見下 } ``` `failure_class` 必填其一（`spec_unclear` / `tech_pitfall` / `model_capability` / `criteria_contradiction`）。 **不記分類的紀錄對校準沒有價值**——第 5 次評估時只會看到「失敗了 N 次」而不知道該調什麼。 ### 為什麼需要校準輪（這是設計上的根本問題，不是可選的加值） 配比表要回答的核心問題是「inspector 夠不夠好」。inspector 失效的定義是**它說 pass 但其實不 pass**。 要偵測這件事，需要一個獨立於 inspector 的事實來源。 而 human-out-of-the-loop **正好拿掉了那個來源**。跑 100 次都是「inspector 說過了」，這 100 筆資料對於 「inspector 會不會誤判」的資訊量是零。全自動化移除了校準自動化所需要的 ground truth——這個張力必須正面處理。 ### 第 5 次：雙稽核，記錄「歧異」而非「通過」 `runs.jsonl` 每滿 5 筆，下一次執行必須是校準輪（`.claude/hooks/detect-loopup-calibration.sh` 會提醒）。 校準輪**不是多跑一次同樣的檢查**——那不產生新資訊。做法是挑至少一個 Stage，派**兩支不同模型的 inspector-ops 各自獨立稽核**（例如 Sonnet 與 Fable），兩支都不得看到對方的結論，然後記錄： | 結果 | 意義 | |---|---| | 兩支結論一致 | 弱證據支持當前配比夠用；較弱那支或許可降級省成本 | | **兩支結論不同** | **這才是有價值的樣本**——記下歧異點、哪一支對、為什麼 | 歧異率是在無人介入下唯一能逼近「inspector 可靠度」的訊號。長期為 0 → 可降級；上升 → 該升級。 校準輪的 `calibration` 欄位記：`{ "stage_id", "inspector_a": {model, verdict}, "inspector_b": {model, verdict}, "agreed": bool, "divergence": "…" }`。 成本：校準輪多一支 inspector（約 +95k tokens），每 5 次一次，攤提後約 +4%。 ### 統計效力的誠實邊界 n=5、且各次任務性質不同，本來就不是同分布樣本。它能給的是**趨勢與異常訊號**，不是「誤判率 X%」這種數字。 **不要用 5 筆資料生一張看起來精確的表。** 校準結論寫回上方配比表時，必須註明依據的 run_id 與樣本數。 ### 目前配比表的證據狀態（2026-08-10） 首次實測（QAQC Phase 5 升級，4 支 agent / 379,286 tokens / 一輪通過）中，**inspector 是 Sonnet，其結論與人工獨立 複驗完全一致**。因此「inspector 應升級到 Fable/Opus」這條建議**目前建立在後果不對稱的風險論證上，尚無實證支持**。 保留該建議，但需在累積校準樣本後重新檢視——那次的驗收條件寫得非常具體，inspector 基本是照表操課，真正考驗判斷力的 情境（驗收條件含糊、implementer 產出可疑）並未發生。 ## 何時該用 / 何時不該用 「啟動前置門檻」的四項是硬性 gate；以下是幫助判斷的具體情境例子，不是重複同一份清單： **適用**：跨檔案重構、協定遷移、registry 一致性這類本專案已有前例的多階段工作；有可靠、唯讀的方式檢查結果，不需要依賴 implementer 的自陳；使用者想要低介入、可以放著跑到收斂或跑到 BLOCKED 為止。 **不適用**：探索性任務，沒有清楚的「完成」定義；需要人類美感／語感判斷的工作（文案語氣、視覺設計、UX 感受）——inspector-ops 判不出來的東西，這個迴圈也判不出來；單一小改動，一輪對話就能處理完的事——5 角色＋結構化記錄的開銷不值得；沒有可自動化的驗收 方式、而「做出這個驗收方式」本身才是探索性任務的情況——先把驗收條件做出來，之後再套 `loop-up`。 ## 工具 本 skill 主要組合的是 Claude Code 本身的編排工具，不是特定的 Revit MCP 工具： | 工具 | 用途 | |---|---| | `Agent` | 依角色表用 `model` 參數（`sonnet`／`haiku`／`fable`／`opus`）與 `subagent_type`（`general-purpose`／`Explore`／`Plan`／`claude`）開出 implementer／observer／inspector-ops／advisor | | `SendMessage` | 重試同一 Stage 時接續同一個 implementer agent，保留上下文，而不是每輪重開 | | `Bash` / `PowerShell` | implementer 執行變更與建置；observer／inspector-ops 只能用唯讀指令（`git diff`、`git status`、測試／驗證腳本） | | `Read` / `Grep` / `Glob` | observer／inspector-ops 蒐證用的唯讀檢視工具 | | （視 Stage 內容而定）本專案既有的 revit-mcp 工具 | 若某個 Stage 本身是 BIM 操作（例如批次改 MEP 尺寸），implementer 在該 Stage 內照常呼叫對應的 `mcp__revit-mcp__*` 工具，`loop-up` 不取代那些工具，只是外層的迴圈骨架 | 若要把 inspector-ops／observer 的唯讀邊界做成**結構性強制**（不只是 prompt 指示），比照本專案既有的 `mcp-registry-ops-inspect.md` （frontmatter 只給 `Tools: Read, Bash, Grep`）另外定義 `.claude/agents/loop-up-inspector.md`，落地時一併評估。 ## Reference - `domain/qa-checklist.md` —— inspector-ops 的唯讀查核精神與本專案既有的 `verify-qaqc.ps1` 分階段檢查法，是這個角色的方法論來源。 - `domain/lessons.md` —— Phase 3（EVAL 優化）分類出的「技術陷阱」與「規格不清」教訓，建議事後用 `/lessons` 提煉成條目，讓下次 Stage Plan 一開始就避開，而不是每次都重跑一輪迴圈才發現。 - `CLAUDE.md` → 「MCP Registry Publish Consistency」段落 —— 本專案既有的「修正 agent（`mcp-registry-sync`）＋唯讀稽核 agent （`mcp-registry-ops-inspect`）＋硬性 gate（`validate_publish_consistency.py`）」三件式迴圈，是 `loop-up` 角色分工的既有實例； `loop-up` 是把同一個模式從「registry 一致性」這一個領域，通用化成任何有明確驗收條件的多階段工作都能套用的骨架。