指令詳解

/opsx:bulk-archive 指令詳解

如何使用 /opsx:bulk-archive 批次歸檔多個變更計畫並智慧排解規格衝突

指令用途

/opsx:bulk-archive 是用於批次歸檔多個變更計畫的進階指令。當專案進入疊代尾聲，有多個分支或功能變更計畫 (Changes) 同時完成實作時，逐一執行歸檔會耗費大量時間。/opsx:bulk-archive 允許你一次挑選多個計畫，整批進行驗證、規格同步與歸檔清理。

此指令最具備價值的特性是 「智慧衝突排解 (Agentic Conflict Resolution)」：當多個計畫修改了同一個能力規格書 (Capability Specs) 時，AI 助手會主動檢查程式碼庫，判定實際代碼中誰被落實了，以此決定規格同步的先後順序或捨棄無用規格。

運作流程

  1. 取得計畫列表：執行 openspec list --json 找出所有進行中的 Change。
  2. 互動多選：使用問答工具（支援多選 Multi-select）供開發者挑選要批次歸檔的計畫。
  3. 批次狀態檢核：逐一檢查所選計畫的檔案狀態、任務勾選情形，並列出待同步的規格增量 (Spec Delta)。
  4. 衝突偵測與 codebase 檢索：
    • 比對這些計畫所修改的能力規格書，若有 2 個以上計畫修改了同一個 Capability，即判定為「規格衝突」。
    • AI 會主動搜尋專案程式碼，檢驗哪一個計畫的 Requirement 有實體程式碼與測試作為佐證。
  5. 衝突解決決策：
    • 若僅其中一個計畫實作了 $\rightarrow$ 僅同步該計畫之規格。
    • 若皆有實作 $\rightarrow$ 依時間先後順序依序套用合併，新者覆蓋舊者。
    • 若皆無實作 $\rightarrow$ 發出警告，跳過該規格同步。
  6. 整合報表呈現：向使用者展示所有計畫的狀態對照表與衝突為了解決方案的 rationale (決策依據)，確認後批量執行搬移。

實戰對話範例

範例一：無衝突批次歸檔

  • You: 
    /opsx:bulk-archive
  • AI (提供多選框):

    請問您想要批次歸檔哪些變更計畫？

    • schema-management (Ready, 5/5 tasks)
    • project-config (Ready, 3/3 tasks)
    • add-verify-skill (In Progress, 2/5 tasks)

    [使用者勾選前兩項並點選送出]

    好的，正在進行批次歸檔：

    變更計畫名稱規劃狀態任務完成度規格增量衝突狀態
    schema-managementDone5/51 條無
    project-configDone3/30 條無

    執行搬移與同步⋯

    • ✓ schema-management 歸檔成功。
    • ✓ project-config 歸檔成功。

範例二：偵測到同能力規格衝突

  • You: 
    /opsx:bulk-archive
  • AI:

    已偵測到您選擇了 add-oauth 與 add-jwt 兩個變更計畫。

    ⚠️ 偵測到規格衝突 (Conflict)：

    • 兩個計畫皆修改了相同能力：user-authentication 規格書。

    AI 執行 Codebase 檢索中：

    1. 檢索 src/auth/oauth.ts 發現 OAuth 邏輯已完整實作，且包含測試 oauth.test.ts。
    2. 檢索 src/auth/jwt.ts 發現 JWT 邏輯亦已實作。

    衝突解決決策：

    • 判定為兩者皆已實作。將依據時間順序，先同步 add-oauth 之規格，隨後同步 add-jwt 覆蓋並追加規格。

    請問是否同意此決策並執行批次歸檔？ (Y/N)

範例三：批次歸檔時有未完成任務的警告

  • You: 
    /opsx:bulk-archive
  • AI:

    您選擇了 schema-management 與 add-verify-skill 進行歸檔。

    ⚠️ 進度警告：

    • add-verify-skill 尚有 3 個任務未完成，且有 1 個規劃文件未就緒。

    建議操作：

    1. 強制歸檔（將略過其規格同步）。
    2. 剔除此計畫，僅歸檔已 Ready 的 schema-management。

    請問您想要如何處理？