【用途】 openspec-sync-specs 用于将某个变更(change)的 delta 规范同步到主规范(main specs),且不归档该变更。该操作由智能体驱动:读取 delta 规范后直接编辑主规范,从而实现智能合并,例如仅新增一个场景而不复制整条要求。
【主要能力】
- 从 delta 规范中应用四类变更:ADDED(新增要求)、MODIFIED(修改要求,可新增或调整场景、修改要求描述)、REMOVED(删除要求)、RENAMED(重命名要求,FROM/TO 格式)。
- 智能合并而非覆盖:保留主规范中 delta 未提及的场景与内容,维持原有顺序;MODIFIED 需携带变更后仍存活的全部场景。
- 支持 store 选择:若用户指定 store 或工作在某个 store 中,可运行 openspec store list --json 获取已注册 store id,并在读取或写入规范与变更的命令上追加 --store <id>,选定后在该工作流余下步骤中保持粘性;未指定时命令作用于最近的本地 openspec/ 根目录。
- 变更选择:可直接提供变更名;否则从对话上下文推断,或仅有一个活动变更时自动选择;模糊时运行 openspec list --json 并提示用户选择,仅展示含有 delta 规范的变更。
- 路径解析:通过 openspec status --change "<name>" --json 获取 planningHome.root,主规范位于 <planningHome.root>/openspec/specs/;delta 规范路径仅以 artifactPaths.specs.existingOutputPaths 为准。
- 支持调用方收窄的路径子集(如归档流程内联调用),只同步指定路径,不扩大回完整列表;指定的路径不在 existingOutputPaths 中时报告并停止。
- 在首次写入主规范前获取一次 specs 规则快照(openspec instructions specs --change "<name>" --json),归档内联调用时可复用其提供的快照;该命令失败或返回无效 JSON 时停止写入。
- 新建主规范:capability 不存在时创建 spec.md,有 Purpose 则逐字复制,否则写 TBD 占位符,并加入 ADDED 要求。
- 写完后运行 openspec validate --specs 校验,失败则报告问题且不声称同步成功。
- 输出成功摘要:更新了哪些 capability、做了哪些增删改重命名、是否有 TBD Purpose 占位、是否退役了某个 capability 及恢复指引。
【使用方式】 典型步骤:选择变更并宣告所用变更及覆盖方式;解析变更上下文获取 planningHome.root;依据 existingOutputPaths 找到 delta 规范;逐个读取 delta 与主规范并智能应用变更;获取规则快照并遵守其约束;校验主规范;最后汇总结果。运行两次应得到相同结果(幂等)。
【适用场景】 希望用变更中的 delta 规范更新主规范,但暂不归档变更;需要按场景粒度进行增量合并;在多个已注册 store 之间定向同步规范。
【限制】 无法从其他工件的推断 delta 规范;无 delta 规范时仅告知并停止;退役 capability 需同时满足删除后无要求块、文件格式完好且含 ## Purpose、主规范同步前非空、文件其余非空行均可归类、变更的 .openspec.yaml 声明 retire_capabilities: true、spec.md 位于真实 specs 根内(不跟随符号链接)等条件,否则停止并报告;不得留下空的 ## Requirements 段;不得把 delta 文件原样复制为主规范。