SuperAPI AI 工具集

openspec-sync-specs

编程与开发

查看项目

更新于 10-16 20:01

技能介绍

openspec-sync-specs 是一个由智能体驱动的操作型技能,用于将 OpenSpec 变更(change)中的增量规格(delta spec)同步到主规格(main spec),且不归档该变更。

用途方面,当用户希望用增量规格中的改动更新主规格、但又不想归档变更时,可使用该技能。它强调“智能合并”而非程序化覆盖:例如只添加一个场景,而不必复制整条需求。

主要能力包括:选定变更(可通过名称、对话上下文推断,或从活动变更中选择);解析变更上下文(运行 openspec status --change "<name>" --json,其中包含 planningHome.root,主规格位于 <planningHome.root>/openspec/specs/ 下);定位增量规格(仅使用 status JSON 中 artifactPaths.specs.existingOutputPaths 作为增量规格路径来源);对每个增量规格应用 ADDED、MODIFIED、REMOVED、RENAMED 变更到主规格;在写入主规格前获取 specs 规则快照(direct sync 时运行 openspec instructions specs --change "<name>" --json,或在 archive 内联调用时复用其提供的有效快照);最后运行 openspec validate --specs 校验并输出摘要。

使用方式上,技能支持 store 选择:若用户指定了 store 或工作位于某个 store 中,先运行 openspec store list --json 发现已注册 store id,然后在读取或写入规格与变更的相关命令(如 new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view)上附带 --store <id>。选定后该标志在工作流后续步骤中保持粘性;其他命令不接受该标志。未选择 store 时,命令作用于最近的本地 openspec/ 根目录。

在首次写入前需进行项目检查:运行 openspec list --json(选定 store 时附带 --store <id>)并读取 root。存在 root 对象表示项目已配置;"root": null 表示未配置,且该命令会非零退出,这属于正常回答而非 CLI 故障。若状态错误信息以 Declared in 或 Invalid store declaration in 开头并指向本项目的 openspec/config.yaml(或 config.yml),说明项目通过其声明的 store 使用 OpenSpec,但本机无法解析该 store,此时不应视为未初始化并跳过,而应在写入前停止并展示该错误信息与修复方式。

适用场景:已在 OpenSpec 中管理的项目,需要将变更中的增量规格同步进主规格时;包括批量归档中内联调用(archive 会排除找不到实现的增量,并可能向本工作流传入现有的 OutputPaths 子集),或用户自行指定增量规格条目子集。若指名的路径不在 existingOutputPaths 中,则不应同步该路径,而应报告并停止。

限制与注意事项:增量规格操作包括 ADDED、MODIFIED、REMOVED、RENAMED(FROM:/TO: 格式)四类。若不存在增量规格,应告知用户并停止。对新能力(主规格尚不存在)仅允许应用 ADDED 需求;若存在 MODIFIED 或 RENAMED,则应停止该能力的同步并报告;REMOVED 无需求可删则跳过并警告。删除整个 spec.md(以及目录)需同时满足多项条件,包括本次删除后不再有需求块、文件其余部分格式良好(仍有 ## Purpose)、主规格此前非空、文件所有其他非空行可归类、变更的 .openspec.yaml 声明 retire_capabilities: true,且 spec.md 解析在真实 specs 根目录内(不得跟随符号链接删除外部文件)。若删空后不满足任一退休条件,则不要修改主规格,而应停止该能力的同步并报告阻塞条件及解决方式。不得写入或留下空的 ## Requirements 分区。增量中的 ## Purpose 不会覆盖主规格已有的 Purpose(主规格的 Purpose 为准,会警告并跳过)。校验失败时不应声称同步成功。技能还要求:先阅读增量与主规格再改动、保留增量未提及的内容、不得把增量文件原样复制进主规格(需合并并保持主规格格式,不含 delta 操作头)、操作应幂等、仅在获取 specs 指令返回有效 JSON 时才写入,非零退出或无效 JSON 应在写入前停止并报告。

具体收费、价格、平台支持等信息暂未提供。