TechSpecs搜尋

Theme / v4.19.4

Oh My OpenAgent

AI 代理編排系統

主題首頁GitHub ↗
實戰範例

實戰範例 001：Hermes 與 Athena 平行設計 API 與測試

實戰演示 OMO 的 Hermes 溝通代理與 Athena 測試代理如何平行協同，在 Git Worktree 中同時設計 API 接口與撰寫單元測試。

實戰背景

在傳統的「單執行緒」開發流程中，我們必須先等工程師把 API 介面和實體方法全部寫好，編譯通過後，測試工程師才能開始編寫單元測試。這種線性開發（Waterfall-like）會拉長開發週期。

痛點與問題描述： 我們需要在項目中新增一個複雜的 ReportGenerator 報表生成器模組。 如果能實現：

  • AI 代理 A 在分支 feat/report-api 中設計並實作 ReportGenerator.cs 接口。
  • AI 代理 B 同時在分支 feat/report-tests 中，根據接口定義撰寫 ReportGeneratorTests.cs 測試。 這將會大幅壓縮開發週期。然而，兩者在並行時如果接口發生變動（例如修改了參數），兩端會產生嚴重的代碼衝突。

本範例將展示如何利用 Oh My OpenAgent (OMO) 的 Hermes (協調官) 與 Athena (測試官)，在 Team Mode 下平行推進 API 實作與測試編寫，並自動同步接口修改。

規格定義

本次變更計畫的 ID 為 omo-parallel-api-test。我們在 OpenSpec 中定義了以下規格：

# 實戰範例 001：openspec/changes/omo-parallel-api-test/specs/parallel-dev/spec.md

## ADDED/MODIFIED Requirements

### Requirement: Parallel report generator design
系統必須（SHALL）包含 `ReportGenerator` 模組，並配齊對應測試。
- 接口必須（SHALL）暴露 `GeneratePdf()` 方法。
- 單元測試必須（SHALL）在 Mock 環境下達到 80% 以上的覆蓋率。

#### Scenario: Verify automated parallel integration
- **WHEN** 在 main 分支執行全域建置與測試 `dotnet test`
- **THEN** API 實作與單元測試必須（SHALL）編譯通過且測試 100% 成功。

端到端 8 輪 AI 協作紀錄

以下是 You (開發者) 與 OMO 並行小組之間的對話歷史。

── 第 1 輪：啟動 Team Mode 並指派任務 ──

  • You: 
    請用 Team Mode 啟動兩個背景 Worker：api（設計 API）與 tests（寫測試），各自在獨立的 Git Worktree 中作業。
  • AI:

    [OMO] Team Mode Initialized

    成功在本地 tmux 分配兩個背景 Worktree 分支：

    1. Worker: api -> 分支 temp/wt-api，指派 Sisyphus 負責設計 ReportGenerator.cs API。
    2. Worker: tests -> 分支 temp/wt-tests，指派 Athena 負責設計 ReportGeneratorTests.cs 測試。

    雙端已完全隔離！我將指派 Hermes 作為通訊協調官在背景監控兩端的接口一致性。

── 第 2 輪：API 端初次設計 ──

  • You: 
    請報告 api 端 Sisyphus 代理的第一版 ReportGenerator 介面設計。
  • AI:

    好的，在 temp/wt-api 分支下，Sisyphus 建立了 IReportGenerator.cs：

    Sisyphus 呼叫: write_to_file(TargetFile: "IReportGenerator.cs", Overwrite: true)
    Sisyphus 回傳: File created.

    介面設計代碼：

    public interface IReportGenerator
{
    // 第一版設計：僅接收 reportId
    Task<byte[]> GeneratePdf(int reportId);
}

    Sisyphus 已完成初次提交，並觸發了本地 Git commit。

── 第 3 輪：Hermes 跨分支廣播與 tests 端接收 ──

  • You: 
    此時 tests 端的 Athena 代理是如何知道這個介面定義並開始寫測試的？
  • AI:

    這正是 Hermes 的強大之處！

    Hermes 監聽日誌：
    [hermes] Detected change in IReportGenerator.cs on branch temp/wt-api.
    [hermes] Action: Broad-casting AST signature IReportGenerator::GeneratePdf(int) to temp/wt-tests.

    Athena 代理在背景自動接收到了這個指紋，並在其 context 中「虛擬掛載」了該 interface 聲明。它立刻開始在 temp/wt-tests 分支撰寫測試代碼：

    [Fact]
public async Task GeneratePdf_ValidId_ReturnsBytes()
{
    var mockGen = new Mock<IReportGenerator>();
    mockGen.Setup(x => x.GeneratePdf(1)).ReturnsAsync(new byte[] { 1, 2, 3 });
    
    var result = await mockGen.Object.GeneratePdf(1);
    Assert.NotEmpty(result);
}

    兩端成功在不依賴對手實體代碼編譯的情況下，平行推進！

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

  • You: 
    /opsx:propose "並行開發 ReportGenerator 報表生成器與其單元測試，利用 Hermes 進行實時接口同步"
  • AI:

    好的，提案 omo-parallel-api-test 已經在 OpenSpec 註冊！

    • proposal.md: 說明平行開發流程的優勢。
    • specs/parallel-dev/spec.md: 定義 API 介面與 Mock 測試覆蓋率的驗收Scenario。
    • tasks.md: 已與兩端背景 Worker 進度完成對齊。

    請輸入 /opsx:apply 讓 Sisyphus 與 Athena 繼續推進各自的任務。

── 第 5 輪：API 端介面修改與 Hermes 衝突預防 ──

  • You: 
    /opsx:apply
  • AI:

    Implementing: omo-parallel-api-test (schema: spec-driven)

    API 端突發接口修改：
    Sisyphus 在實作 ReportGenerator 時，發現需要傳入額外的用戶配置參數，於是修改了介面定義：

    // 修改為接收兩個參數
Task<byte[]> GeneratePdf(int reportId, ReportOptions options);

    Hermes 衝突自愈處理：
    Hermes 立即檢測到了這一變更，分析發現這會破壞 tests 分支下的 Mock 測試。

    • 自動同步：Hermes 強制在 temp/wt-tests 分支下，將 Athena 正在編寫的測試代碼中的 Mock 設置，自動進行了增量 Patch 修改，補齊了 ReportOptions 參數，防止在合併時發生編譯崩潰！

    雙端代碼已安全同步。

── 第 6 輪：雙端任務完成與合併驗收 ──

  • You: 
    請執行合併，並在 main 分支執行全域建置與測試。
  • AI:

    Implementing: omo-parallel-api-test

兩端 Worker 已全部完成開發，HUD 顯示「Missions Ready」。我將透過 Team Mode 觸發 Hash-Anchored 合併，把兩個 Worktree 分支織回主分支。

Hermes 動作: 以 Hash-Anchored Edit 協定執行三方合併
Hermes 結果: Merge Succeeded. 0 Conflict(s).

合併完成後，我在主分支啟動了 dotnet test。 建置與測試狀態：
Build Succeeded.
Total Tests: 12. Passed: 12. Failed: 0.
ReportGeneratorTests 覆蓋率: 87.2%

✓ 全量代碼成功合併，單元測試 100% 通過！平行開發計畫圓滿交付。

── 第 7 輪：執行歸檔 ──

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

    Implementing: omo-parallel-api-test

    執行驗證與歸檔：

    1. 確認並行開發的 API 與測試成功在 main 分支編譯通過。
    2. 將並行開發規格合併至主 specs。
    3. 刪除背景臨時 worktree 並關閉 tmux panes。
    4. 計畫歸檔。

    Archive Complete

    變更計畫已成功歸檔！

── 第 8 輪：平行協作效益總結 ──

  • You: 
    這比我們以前一個人寫完代碼再讓另一個人補測試快多了。
  • AI:

    確實如此！本次平行開發的效益對比如下：

    指標維度 串聯開發 (瀑布式) OMO 平行協作
    開發總耗時 60 分鐘 (35 分鐘寫 API + 25 分鐘補測試) 35 分鐘 (API 與測試平行進行)
    接口修改摩擦 高 (修改參數後需要通知對方手動修正測試) 0% (由 Hermes 背景自動廣播 Patch 同步)
    合併衝突解決 人工手動解決衝突 (約 5-10 分鐘) 自動解決 (0 秒)

    透過 Team Mode 雙執行緒與 Hermes 自動同步，團隊能在一半的時間內交付同等高質量的代碼。