TechSpecs搜尋

Theme / v5.3.0

Oh My ClaudeCode

Claude Code 多代理編排系統

主題首頁GitHub ↗
實戰範例

實戰範例 001：利用 OMC Autopilot 全自動升級第三方依賴套件

實戰演示如何利用 Oh My Claude Code (OMC) 的 Sisyphus 引擎，全自動升級多個過期 NPM 套件並解決所有連鎖編譯錯誤。

實戰背景

在前端與 Node.js 開發中，定期升級第三方 NPM 依賴套件是一項極其繁瑣且容易出錯的任務。

痛點與問題描述： 我們需要將專案中的 20 個核心套件（包含 Astro 從 v3 升級到 v4，以及 Zod 的大版本升級）進行升級。大版本升級（Major Upgrades）必然會引入 Breaking Changes，導致專案中的多處 API 調用在建置時發生編譯錯誤。如果讓人手動去跑 pnpm build，再根據幾十個編譯報錯一個一個去改程式碼，需要經歷無數次「修改-建置-失敗」的繁瑣過程。

本範例將展示如何利用 Oh My Claude Code (OMC) 的 Sisyphus 自主自適應修復引擎，全自動地執行升級、捕捉編譯錯誤並遞歸修復，直到專案順利通過建置。

規格定義

本次變更計畫的 ID 为 omc-dependency-upgrade。我們在 OpenSpec 規格中定義了以下驗收標準：

# 實戰範例 001：openspec/changes/omc-dependency-upgrade/specs/upgrade-policy/spec.md

## ADDED/MODIFIED Requirements

### Requirement: Full Astro v4 and Zod migration
專案核心依賴必須（SHALL）安全升級至 Astro v4.x 與 Zod v3.x。
- 升級後，系統必須（SHALL）通過全域靜態建置 `pnpm run build`，不得有任何 Zod schema 驗證錯誤。

#### Scenario: Verify automated migration success
- **WHEN** 執行全量建置 `pnpm run build`
- **THEN** 系統必須（SHALL）無編譯錯誤地建置成功，且 Pagefind 搜尋索引順利生成。

端到端 8 輪 AI 協作紀錄

以下是 You (開發者) 與 OMC 實作代理人 Sisyphus 之間的完整升級日誌。

── 第 1 輪：初始套件升級與編譯中斷 ──

  • You: 
    /opsx:explore "我需要升級 Astro 到 v4 且 Zod 升到最新。請幫我執行安裝，然後看看建置報錯。"
  • AI:

    好的，已進入探索模式。我將首先在本地執行 pnpm update，更新 package.json 中 Astro 與 Zod 的版本。

    OMC 呼叫: run_command(CommandLine: "pnpm add astro@latest zod@latest")
    OMC 回傳: Dependencies updated successfully.

    接下來，我嘗試執行初次建置以查找受影響的編譯錯誤。 OMC 呼叫: run_command(CommandLine: "pnpm run build")
    OMC 回傳:
    [InvalidContentEntryDataError] examples → themes/codebase-memory data does not match collection schema.
    zod.error: difficulty: z.enum(...) expected one of ...

    分析：
    果然，Zod 升級後對 schema 的嚴格校驗導致了原有的 difficulty 欄位（原本寫了數字 3）不合規，阻礙了 Astro 建置。接下來我將啟用 Sisyphus 自動駕駛引擎，對全站的 examples 進行自動修復。

── 第 2 輪：啟動 Sisyphus 自主循環 ──

  • You: 
    在專案中啟動 Sisyphus 循環。指令為 `omc sisyphus --build-cmd="pnpm run build" --max-loops=10`。
  • AI:

    好的，我將在背景啟動 omc sisyphus 自主自適應修復，設定最大 10 輪循環，直至 pnpm run build 成功。

    OMC 呼叫: omc sisyphus --build-cmd="pnpm run build"
    OMC 回傳: Autopilot engaged. Sisyphus loop started.

    目前 OMC HUD 面板顯示狀態如下：

    • [HUD Status]: Loop 1/10 | Resolving Zod verification error in legacy-codebase-bug-hunting.mdx

── 第 3 輪：Sisyphus 任務 1 執行 (修正 Zod 欄位) ──

  • You: 
    請拉取目前 Sisyphus 的詳細自修復步驟日誌。
  • AI:

    好的，以下是 Sisyphus 在 Loop 1 與 Loop 2 中運行的詳細軌跡：

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

    [sisyphus] [Loop 1] Astro build failed due to schema mismatch in examples.
[sisyphus] [Loop 1] Action: 修改 src/content/themes/codebase-memory/examples/legacy-codebase-bug-hunting.mdx。
[sisyphus] [Loop 1] Action: 將 frontmatter difficulty: 3 修改為 difficulty: advanced。
[sisyphus] [Loop 2] Running 'pnpm run build'... Failed.
[sisyphus] [Loop 2] Found Next Error: difficulty: 3 in react-native-bridge-exploration.mdx.
[sisyphus] [Loop 2] Action: 修改 src/content/themes/codegraph/examples/react-native-bridge-exploration.mdx。
[sisyphus] [Loop 2] Action: 將 difficulty: 3 修改為 difficulty: advanced。

    分析：
    Sisyphus 正在有條不紊地逐一修正 examples 中不符合新版 Zod Schema 的欄位。

── 第 4 輪：建立提案 ──

  • You: 
    /opsx:propose "全自動升級 Astro 與 Zod 依賴，利用 Sisyphus 自主循環修復 Zod 欄位衝突"
  • AI:

    好的，提案 omc-dependency-upgrade 已正式建立！

    • proposal.md: 說明升級 Astro/Zod 的必要性與防禦性修改 Zod 屬性的重要性。
    • specs/upgrade-policy/spec.md: 定義 100% 建置通過的驗收條件。
    • tasks.md: 已與 Sisyphus 當前的進度完成對齊。

    請輸入 /opsx:apply 讓 Sisyphus 繼續在背景實作後續任務。

── 第 5 輪：Sisyphus 任務 2 執行 (繼續修復欄位) ──

  • You: 
    /opsx:apply
  • AI:

    Implementing: omc-dependency-upgrade (schema: spec-driven)

    正在處理任務 2 (Autopilot)：完成所有 examples 檔案的 Zod 欄位修正。

    Sisyphus 在 Loop 3 到 Loop 6 中，自動掃描並修改了剩餘 6 個主題的 examples 檔案，將所有 difficulty: 3 或 difficulty: 2 全數改為符合 Zod 枚舉規範的 advanced 或 intermediate：

    [sisyphus] [Loop 3] Action: 修改 src/content/themes/claude-mem/examples/long-session-context-debugging.mdx -> difficulty: intermediate
[sisyphus] [Loop 4] Action: 修改 src/content/themes/oh-my-claudecode/examples/omc-team-mode-refactor.mdx -> difficulty: advanced
[sisyphus] [Loop 5] Action: 修改 src/content/themes/oh-my-codex/examples/omx-autopilot-unit-tests.mdx -> difficulty: advanced
[sisyphus] [Loop 6] Action: 修改 src/content/themes/oh-my-openagent/examples/omo-multi-agent-refactoring.mdx -> difficulty: advanced

    ✓ 任務 2 實作完成。

── 第 6 輪：Sisyphus 任務 3 執行 (全域建置驗收) ──

  • You: 
    繼續任務 3，執行全域 Astro 建置與 Pagefind 索引生成。
  • AI:

    Implementing: omc-dependency-upgrade

    正在處理任務 3 (Autopilot)：全域建置與 Pagefind。

    Sisyphus 在 Loop 7 中執行了最終建置驗收：

    [sisyphus] [Loop 7] Running 'pnpm run build'... Succeeded!
[sisyphus] [Loop 7] Pagefind indexed 158 pages successfully.
[sisyphus] Autopilot Complete! Built 158 pages in 14.2s.

    ✓ 任務 3 全數通過！無任何 Zod 錯誤殘留。

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

  • You: 
    執行 verify 並歸檔變更計畫。
  • AI:

    Implementing: omc-dependency-upgrade

    執行驗證與歸檔：

    1. 規格審查：確認 Astro v4 與 Zod v3 升級成功，無編譯錯誤。
    2. 合併規格：將升級政策規格合併至 specs。
    3. 計畫歸檔：清理 changes 目錄。

    Archive Complete

    變更計畫已成功歸檔！

── 第 8 輪：Autopilot 效益評估 ──

  • You: 
    請總結這次使用 Sisyphus 自動駕駛升級依賴的效益。
  • AI:

    本次全自動升級的效益對比如下：

    評估指標 人工升級 (傳統) Sisyphus Autopilot
    操作次數 20+ 次 (人工修改 8 個檔案，反覆手動跑 pnpm build) 1 次指令下達 (全程自動駕駛)
    耗時 (秒) 約 25 分鐘 128 秒 (縮短 91%)
    錯誤遺漏率 高 (容易遺漏某個不起眼的 examples 檔案) 0% (完全依據 Zod 編譯日誌精準掃描)

    Sisyphus 完美展現了「無人值守」在大規模 Break-fix 重構任務中的極致交付效率。