將變更中的 Delta 規格同步至主要規格。
這是一個 agent 驅動 的操作——你將讀取 Delta 規格並直接編輯主要規格以套用變更。這允許智慧合併(例如,新增情境而不複製整個需求)。
Store 選擇: 如果使用者指定一個 store(store 是這台機器上註冊的獨立 OpenSpec 儲存庫),或者工作位於其中,請執行 openspec store list --json 來發現已註冊的 store ID,然後對讀取或寫入規格和變更的命令(new change、status、instructions、list、show、validate、archive、doctor、context)傳遞 --store <id>。其他命令不接受此旗標。命令輸出的提示已包含該旗標;後續操作請保持使用。如果沒有 store,命令將作用於最近的本地 openspec/ 根目錄。
輸入:可選地指定一個變更名稱。如果省略,檢查是否能從對話情境推斷。如果模糊或不明確,你必須提示使用者提供可用的變更。
步驟
-
如果未提供變更名稱,提示使用者選擇
執行
openspec list --json取得可用的變更。使用 AskUserQuestion 工具 讓使用者選擇。顯示具有 Delta 規格(位於
specs/目錄下)的變更。重要:不要猜測或自動選擇變更。始終讓使用者選擇。
-
解析變更上下文
執行:
openspec status --change "<name>" --json -
查找 Delta 規格
使用狀態 JSON 中的
artifactPaths.specs.existingOutputPaths作為 Delta 規格檔案清單。每個 Delta 規格檔案包含以下區段:
## ADDED Requirements- 要新增的需求## MODIFIED Requirements- 對現有需求的變更## REMOVED Requirements- 要移除的需求## RENAMED Requirements- 要重新命名的需求(FROM:/TO: 格式)
如果未找到 Delta 規格,通知使用者並停止。
-
對於每個 Delta 規格,將變更套用到主要規格
對於 CLI 回傳的每個 repository 本地功能 Delta 規格路徑:
a. 讀取 Delta 規格 以了解預期的變更
b. 讀取主要規格 位於
openspec/specs/<capability>/spec.md(可能還不存在)c. 智慧地套用變更:
ADDED Requirements:
- 如果需求不存在於主要規格中 → 新增它
- 如果需求已存在 → 更新以匹配(視為隱含的 MODIFIED)
MODIFIED Requirements:
- 在主要規格中找到該需求
- 套用變更——這可以是:
- 新增情境(無需複製現有情境)
- 修改現有情境
- 變更需求描述
- 保留 Delta 中未提及的情境/內容
REMOVED Requirements:
- 從主要規格中移除整個需求區塊
RENAMED Requirements:
- 找到 FROM 需求,重新命名為 TO
d. 如果功能尚不存在,建立新的主要規格:
- 建立
openspec/specs/<capability>/spec.md - 新增 Purpose 區段(可以簡短,標記為 TBD)
- 新增包含 ADDED 需求的 Requirements 區段
-
顯示摘要
套用所有變更後,總結:
- 哪些功能已更新
- 進行了哪些變更(新增/修改/移除/重新命名了哪些需求)
Delta 規格格式參考
## ADDED Requirements
### Requirement: 新功能
系統應執行某個新動作。
#### Scenario: 基本案例
- **WHEN** 使用者執行 X
- **THEN** 系統執行 Y
## MODIFIED Requirements
### Requirement: 現有功能
#### Scenario: 要新增的情境
- **WHEN** 使用者執行 A
- **THEN** 系統執行 B
## REMOVED Requirements
### Requirement: 已棄用的功能
## RENAMED Requirements
- FROM: `### Requirement: 舊名稱`
- TO: `### Requirement: 新名稱`
關鍵原則:智慧合併
與程式化合併不同,你可以套用 部分更新:
- 要新增情境,只需在 MODIFIED 下包含該情境——不要複製現有情境
- Delta 代表 意圖,而不是全面替換
- 使用你的判斷合理合併變更
成功輸出
## 規格已同步:<變更名稱>
已更新主要規格:
**<功能-1>**:
- 已新增需求:「新功能」
- 已修改需求:「現有功能」(新增了 1 個情境)
**<功能-2>**:
- 已建立新的規格檔案
- 已新增需求:「另一個功能」
主要規格已更新。變更仍保持活躍——實作完成後請歸檔。
護欄
- 在進行變更之前,請同時讀取 Delta 和主要規格
- 保留 Delta 中未提及的現有內容
- 如果某件事不清楚,請要求澄清
- 邊進行邊顯示你正在變更的內容
- 操作應該是冪等的——執行兩次應得到相同結果