TechSpecs搜尋

Theme / v5.3.0

Oh My ClaudeCode

Claude Code 多代理編排系統

主題首頁GitHub ↗
實戰範例

實戰範例 002：OMC HUD 預算熔斷保護與長任務斷點恢復

實戰演示當 AI 助手在大規模重構中遇到死鎖陷入 Token 暴走時，OMC HUD 預算防線如何安全熔斷並在恢復後繼續任務。

實戰背景

在大規模、自主駕駛（Autopilot）的代碼重構中，AI 助手在背景默默運行，有可能因為程式碼邏輯中的「循環依賴」或「編譯死鎖」，導致 AI 陷入死循環。

痛點與問題描述： 我們正在對一個龐大的微服務系統進行全域 DTO 重構，這需要修改 80 個檔案。我們啟動了 OMC 的 Autopilot 模式。在執行到第 40 個檔案時，AI 因為某個複雜的介面定義衝突，陷入了「修改 -> 報錯 -> 重新嘗試 -> 再次報錯」的無盡循環中。如果任由其在背景運行，可能會在幾個小時內燒掉數百美元的 API 額度。

本範例將實戰演示 Oh My Claude Code (OMC) 的 預算防禦熔斷器 (Budget Safeguard) 如何在會話花費達到設定的 $10 USD 時立即進行安全攔截，並在開發者介入修改後，無縫進行斷點任務恢復 (Resume)。

規格定義

本次變更計畫的 ID 為 omc-budget-safeguard。我們在 OpenSpec 中定義了以下規格：

# 實戰範例 002：openspec/changes/omc-budget-safeguard/specs/budget-control/spec.md

## ADDED/MODIFIED Requirements

### Requirement: Session cost budget limit
OMC 執行期必須（SHALL）強制監控單次會話 API 累計開銷。
- 預算上限設定為 10.00 美元。
- 當花費達到 85% ($8.50) 時，必須（SHALL）發出黃色警告；達到 100% ($10.00) 時，必須（SHALL）強行熔斷暫停，封存當前工作區。

#### Scenario: Verify budget cutoff and resume
- **WHEN** 背景開銷累計達 $10.00 USD
- **THEN** 系統必須（SHALL）安全暫停，並在開發者修改規則後，支援 `omc sisyphus --resume` 繼續未完成的任務。

端到端 8 輪 AI 協作紀錄

以下是 You (開發者) 與 OMC 預算監控器之間的完整對話歷史。

── 第 1 輪：設定預算防線與啟動重構 ──

  • You: 
    /opsx:explore "我需要進行全域 DTO 大重構，這非常耗 Token。請幫我設定 10 美元預算上限，並在背景啟動 sisyphus 自動駕駛。"
  • AI:

    好的，已進入探索模式。為了解決 Token 暴走的隱憂，我將調用 omc config 將本次會話的最高開銷限制在 $10 美元，並啟用終端 HUD 面板。

    OMC 呼叫:

    omc_config(maxCostUsd: 10.0, warningThreshold: 0.85);

    OMC 回傳: [OMC] Budget Guard active. Session limit: $10.00 USD.

    接下來，我啟動全域重構任務的 Autopilot 模式。 OMC 呼叫: omc sisyphus --build-cmd="dotnet build" --loop
    OMC 回傳: Autopilot started. Monitoring progress via HUD.

── 第 2 輪：重構進度與 Token 正常累積 ──

  • You: 
    請報告目前的重構進度與 HUD 中的 Token 花費。
  • AI:

    目前重構工作已進行了 10 分鐘，進度與開銷如下：

    OMC 呼叫: omc status
    OMC 回傳:

    • Active Change: omc-budget-safeguard
    • Completed Files: 34/80
    • Current Session Cost: $4.20 USD (佔預算 42%)
    • Status: Refactoring src/Billing/Dto/PaymentDto.cs

    分析：
    前 34 個檔案的重構非常順利，平均每個檔案花費 $0.12 美元，預算非常充裕。Sisyphus 正在繼續處理下一批檔案。

── 第 3 輪：遭遇死鎖與預算警告 ──

  • You: 
    背景好像卡住了，我看到 HUD 狀態列在閃爍黃色。請拉取最新的日誌。
  • AI:

    好的，我將調用 omc team log 拉取最新的 Worker 日誌。

    OMC 呼叫: omc team log --worker=sisyphus --lines=10
    OMC 回傳:

    [sisyphus] [Loop 12] dotnet build failed: DtoConflictException at OrderDto.cs
[sisyphus] [Loop 12] Action: Trying to merge OrderDto and ClientDto
[sisyphus] [Loop 13] dotnet build failed: DtoConflictException
[sisyphus] [Loop 13] Action: Retrying merge with different namespace...

    HUD 即時顯示：
    [OMC HUD] WARNING: Session Cost $8.75 / $10.00 (87.5%) [BUDGET WARNING]

    診斷：
    Sisyphus 代理在處理 OrderDto.cs 時遇到了嚴重的介面衝突，已經在 Loop 12 與 Loop 13 中陷入了重複修改的死循環。當前開銷已達到 $8.75 美元，觸發了 85% 的黃色警戒線！

── 第 4 輪：預算熔斷攔截 (Safeguard Cutoff) ──

  • You: 
    靜觀其變，看它達到 10 美元時會發生什麼。
  • AI:

    好的。背景 Sisyphus 在 Loop 14 中繼續嘗試，API 費用再次累積。

    OMC 呼叫: None (Process interrupted by Daemon)
    OMC 輸出 (終端機警報音)：

    🛑🛑🛑 [OMC BUDGET SAFEGUARD] 🛑🛑🛑
Current session cost: $10.15 USD has exceeded the limit of $10.00 USD.
Autopilot execution has been FORCIBLY SUSPENDED to prevent billing run-away.

Current State:
- Target File: src/Core/Dto/OrderDto.cs (Locked in Loop 14)
- Unfinished Tasks: 45 files remaining.
- Workspace state saved to .omx/checkpoint_state.json

Please review the conflict in OrderDto.cs manually, then run 'omc sisyphus --resume' to continue.

    安全分析：
    預算熔斷器已完美執行！AI 進程已被強制終止，未完成的 45 個任務與工作區狀態已被安全封存。這成功防止了 AI 持續在背景盲目嘗試。

── 第 5 輪：手動介入修改衝突 ──

  • You: 
    我已經看了 OrderDto.cs，發現是因為型別轉換錯誤。我手動把這裡的 String 改為 Guid 了。現在請幫我執行恢復任務。
  • AI:

    好的，感謝您的人工介入！這正是預算防線的設計意圖——「AI 走投無路時，轉交人類決策」。

    既然您已手動解決了 OrderDto.cs 的類型衝突，我將調用 omc sisyphus --resume 命令，從封存的 .omx/checkpoint_state.json 斷點恢復任務。

    OMC 呼叫: omc sisyphus --resume
    OMC 回傳:

    [OMC] Restoring session from checkpoint...
[OMC] Resuming task: 45 files remaining.
[OMC] Resetting session budget to new $5.00 limit for resumed run.
[OMC] Running 'dotnet build'... Succeeded!
[OMC] Sisyphus Loop 15: Proceeding to next file: src/Core/Dto/CustomerDto.cs

    任務已成功恢復，且由於您解決了衝突，編譯順利通過！Sisyphus 正在繼續重構剩餘的 DTO 檔案。

── 第 6 輪：重構任務順利完成 ──

  • You: 
    繼續執行，看剩下 45 個檔案是否全數完成。
  • AI:

    Implementing: omc-budget-safeguard (schema: spec-driven)

    正在處理剩餘任務：
    Sisyphus 在後續的 Loop 16 到 Loop 28 中，順利完成了剩餘 45 個 DTO 檔案的修改，中途未再遇到編譯阻礙。

    建置驗收：
    Build Succeeded. 0 Warning(s), 0 Error(s).
    全域重構大功告成！已將所有任務標記為完成。

── 第 7 輪：執行驗證與歸檔 ──

  • You: 
    執行 verify 並歸檔。
  • AI:

    Implementing: omc-budget-safeguard

    執行驗收與歸檔：

    1. 確認 DTO 專案編譯無錯誤。
    2. 將預算控制規格合併至主 specs。
    3. 清理變更計畫暫存。

    Archive Complete

    變更計畫已成功歸檔！

── 第 8 輪：總結預算控制價值 ──

  • You: 
    這個預算熔斷機制太實用了。
  • AI:

    本次熔斷與恢復的效益總結如下：

    • 帳單防線：在 OrderDto.cs 衝突中，若無熔斷器，AI 在背景遞歸 100 次可能會多產生 $80+ USD 的無效帳單。熔斷器成功將開銷止損在 $10.15。
    • 無縫恢復 (State Persistence)：透過 .omx/ 快取保留進度，開發者修復完 bug 後，AI 能在 2 秒內從第 35 個檔案精確恢復，不需要從頭重新分析，極大保護了已有的開發成果。