用途
将某个变更(change)的增量规格(delta specs)同步到主规格(main specs),同时保留该变更为活跃状态(不归档)。这是一项由智能体驱动的操作:读取增量规格,并直接编辑主规格来应用改动,从而实现智能合并,例如新增一个场景时无需复制整条需求。
主要能力
- 处理四类增量:ADDED Requirements(新增需求)、MODIFIED Requirements(修改需求)、REMOVED Requirements(移除需求)、RENAMED Requirements(重命名需求,FROM:/TO: 格式)。
- 对 ADDED:主规格中不存在则新增;已存在则更新为匹配内容(视为隐式 MODIFIED)。
- 对 MODIFIED:在主规格中找到对应需求后应用修改,可新增场景、修改现有场景、更改需求描述,并保留增量中未提及的场景与内容。
- 对 REMOVED:从主规格中删除整个需求块。
- 对 RENAMED:找到 FROM 需求并重命名为 TO。
- 主规格中若尚无对应能力,则新建 openspec/specs/<capability>/spec.md,加入 Purpose 段(可简略并标记 TBD)以及包含 ADDED 需求的 Requirements 段。
- 变更名未提供时,运行 openspec list --json 获取可用变更,并通过 AskUserQuestion 工具让用户选择;只展示带有增量规格(specs/ 目录下)的变更,不猜测或自动选择。
- 在 openspec/changes/<name>/specs/*/spec.md 中查找增量规格;若未找到则告知用户并停止。
使用方式
- 若未提供变更名,提示用户从可用变更中选择。
- 定位增量规格文件。
- 对每个带增量规格的能力:读取增量规格理解意图;读取主规格(可能尚不存在);按上述规则智能应用改动。
- 完成后输出摘要,列出更新的能力及各需求的新增/修改/移除/重命名情况。
成功输出示例格式为“Specs Synced: <change-name>”,列出各能力的具体改动,并提示主规格已更新、变更仍处于活跃状态,实现完成后可归档。
适用场景
需要在实现过程中或完成后、归档变更之前,把规格改动同步到主规格库时使用。
限制与约束
- 修改前必须同时阅读增量规格与主规格。
- 保留增量中未提及的现有内容。
- 遇到不清楚之处需请求澄清。
- 操作应具备幂等性:运行两次应得到相同结果。
- 增量代表意图而非整体替换,需按判断合理合并。