SuperAPI AI 工具集

openspec-sync-specs

编程与开发

查看项目

更新于 10-19 16:18

技能介绍

用途

将某个变更(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 中查找增量规格;若未找到则告知用户并停止。

使用方式

  1. 若未提供变更名,提示用户从可用变更中选择。
  2. 定位增量规格文件。
  3. 对每个带增量规格的能力:读取增量规格理解意图;读取主规格(可能尚不存在);按上述规则智能应用改动。
  4. 完成后输出摘要,列出更新的能力及各需求的新增/修改/移除/重命名情况。

成功输出示例格式为“Specs Synced: <change-name>”,列出各能力的具体改动,并提示主规格已更新、变更仍处于活跃状态,实现完成后可归档。

适用场景

需要在实现过程中或完成后、归档变更之前,把规格改动同步到主规格库时使用。

限制与约束

  • 修改前必须同时阅读增量规格与主规格。
  • 保留增量中未提及的现有内容。
  • 遇到不清楚之处需请求澄清。
  • 操作应具备幂等性:运行两次应得到相同结果。
  • 增量代表意图而非整体替换,需按判断合理合并。