SuperAPI AI 工具集

openspec-update-change

编程与开发

查看项目

更新于 10-16 20:01

技能介绍

用途

openspec-update-change 是一个用于修订 OpenSpec 变更(change)既有规划产物、并让它们彼此保持一致的技能。它的目标是:当用户想修改某个变更的规划文档,或希望让现有产物之间协调一致时,帮助完成修订。该技能只处理规划产物,从不编辑实现代码。

主要能力

  • 修订变更中已经存在的规划产物(planning artifacts),并检查各产物之间是否存在矛盾、遗漏或重复。
  • 在对话中草拟修订内容,逐项与用户确认后再写入文件。
  • 支持独立存储(store):如果用户指定了某个 store,或工作位于某个 store 中,可先运行 openspec store list --json 发现已注册的 store id,再在读写 specs 与 changes 的命令上附加 --store <id>。选定后,该 flag 在整个工作流中保持有效。
  • 支持自定义 schema:产物的 id 和路径来自当前启用的 schema,不假定固定名称,也不依赖硬编码的产物名。
  • 指出尚未创建的产物,并引导用户使用 openspec instructions 了解如何创建,但本技能自身不创建它们。

使用方式

  1. 选择变更:如果提供了名称则使用;否则从对话上下文推断,或当只有一个活跃变更时自动选择;若有歧义,运行 openspec list --json 获取按最近修改排序的变更,让用户选择(一般给出最近修改的 3-4 个,显示名称、schema、状态、修改时间,并把最近修改的标记为“(Recommended)”)。同时会提示“Using change: ”以及如何覆盖(如 /openspec-update-change <other>)。
  2. 获取产物:运行 openspec status --change "<name>" --json,解析 JSON 了解当前状态,包括 schemaName、artifacts(状态为 done、skipped、ready、blocked)、isPlanningComplete(旧版 CLI 为 isComplete)、以及 planningHome、changeRoot、artifactPaths、actionContext 等路径与作用域上下文。需要编辑的文件是 artifactPaths.<id>.existingOutputPaths。
  3. 理解请求:如果用户提出了具体修订,将其作为起始编辑;如果只说“update”或“make this coherent”,则视为一致性审查,检查各产物之间的矛盾、缺口和重复。
  4. 阅读并协调:阅读请求涉及的产物以及该变更的其他现有产物,在对话中草拟编辑,检查其他产物是否需要相应修订(任意方向,不只是后向前的顺序)。记录所有不一致、缺失或矛盾之处。只对已存在的文件提出修订,不创建尚不存在的产物,也不在 glob 产物下虚构新文件。
  5. 确认并应用:本步骤执行所有产物写入,展示每项修订及其理由,用户确认后才写入;被拒绝的修订不写入。若需大幅重写,先获取该产物的规则与模板:openspec instructions "<artifact-id>" --change "<name>" --json。
  6. 指向下一步(仅供参考,绝不执行):产物仍缺失则提示下一步;变更已实现则建议 /openspec-apply-change;全部完成并实现则建议 /openspec-archive-change。

适用场景

  • 用户希望修订某个变更的设计、规格等规划文档,并保持各产物一致。
  • 用户希望检查某个变更的现有规划产物之间是否存在矛盾、缺口或重复。
  • 需要针对已使用 OpenSpec 的项目进行操作,项目需已有根目录(openspec/)。

限制

  • 只处理规划产物,绝不编辑实现代码。如果修订后的规划暗示需要改代码,会停止并指向 /openspec-apply-change。
  • 不推进构建前沿:不新建产物、不在 glob 产物下新建文件。
  • 每次编辑都必须先经用户确认。
  • 如果请求改变的是变更的意图(而非细化),会要求提供一个未使用的新变更名,并建议改用 openspec new change "<new-change-name>"。
  • 项目检查:预期项目已使用 OpenSpec。在首次写入前需确认存在根目录(运行 openspec list --json 并读取 root)。root 为 null 表示未初始化,命令也会以非零退出,这是正常回答而非 CLI 故障。但若状态错误信息以 “Declared in” 或 “Invalid store declaration in” 开头并指向本项目的 openspec/config.yaml(或 config.yml),说明项目通过一个本机无法解析的 store 来使用 OpenSpec,不应视为未初始化,应在写入前停止并向用户展示该错误及修复方式。若确实没有根目录:在自动选中该工作流的情况下,停止使用 OpenSpec、按常规回答,不提示设置;在用户明确请求 OpenSpec 的情况下,写入前停止并询问如何继续(openspec init、使用已有 store,或本次不使用 OpenSpec)。两种情况下都不得擅自创建根目录。
  • 部分命令与行为依赖具体环境与 OpenSpec 版本;本介绍中未提供的细节(如具体收费、平台支持等)暂未提供。

输出

每次调用后展示:修订了哪些产物(以及哪些修订被拒绝)、因尚不存在而推迟处理的内容、变更当前所处阶段及建议的下一条命令。