用途
openspec-sync-specs 用于在 OpenSpec 项目中,将某个变更(change)所含的 delta 规格同步写入主规格(main specs),同时保持该变更处于活动状态、不进行归档。适合在变更实现过程中提前更新主规格文档,而不必等到归档阶段。
主要能力
- 读取变更目录下的增量规格:openspec/changes/<name>/specs/*/spec.md。
- 解析 delta 规格中的四类区块:ADDED Requirements(新增需求)、MODIFIED Requirements(修改需求)、REMOVED Requirements(删除需求)、RENAMED Requirements(重命名需求,使用 FROM:/TO: 格式)。
- 对每个能力(capability),读取或新建主规格 openspec/specs/<capability>/spec.md,并智能合并变更。
- 支持部分更新:例如在 MODIFIED 下仅写新增场景,无需复制已有场景;未在 delta 中提及的场景和内容会保留。
- 若主规格不存在,则创建新文件,并可标注 Purpose 为 TBD。
- 完成后输出摘要,列出更新的能力及新增、修改、删除、重命名的需求。
- 设计上要求操作具备幂等性:重复执行应得到相同结果。
使用方式
- 提供变更名称;若省略,可从对话上下文推断。若无法确定或不明确,必须列出可用变更并让用户选择。
- 运行 openspec list --json 获取可用变更,通过 AskUserQuestion 工具让用户选择;只展示带有 delta 规格的变更,不得猜测或自动选择。
- 在 openspec/changes/<name>/specs/*/spec.md 中查找 delta 规格;若未找到,告知用户并停止。
- 对每个含 delta 规格的能力,读取 delta 与主规格,按 ADDED、MODIFIED、REMOVED、RENAMED 的语义应用变更;对已存在的 ADDED 需求视作隐式 MODIFIED 进行更新。
- 若能力主规格不存在,创建 openspec/specs/<capability>/spec.md,加入 Purpose(可简短或标为 TBD)与 Requirements。
- 最后汇总更新的能力与具体改动,并提示变更仍处于活动状态,实现完成后再归档。
适用场景
- 在 OpenSpec 变更实现过程中,希望主规格提前反映最新需求。
- 需要将增量规格中的意图按语义合并进主规格,而非整段替换。
- 需要同时处理多个能力的主规格更新,包括新建能力规格。
限制与注意事项
- 该操作由智能体驱动,需要阅读 delta 与主规格后直接编辑主规格。
- 不得猜测或自动选择变更,必须由用户确认。
- 合并时须保留 delta 未提及的现有内容;不清晰时应请求澄清。
- 不同步即归档,本技能不归档变更。
- 资料未提供安装命令、收费信息、支持平台或具体效果数据。