openspec-update-change

修订变更现有的规划文档，并确保它们相互一致。切勿编辑代码。

存储选择： 如果用户指定了存储库（存储库是指在此计算机上注册的独立 OpenSpec 仓库），或者工作所在位置属于某个存储库，请运行 openspec store list --json 查找已注册的存储库 ID，然后在读取或写入规范和变更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中传入 --store <id>。选定后，在工作流的其余部分始终使用 --store <id>。下文中这些命令未指定存储库的示例均为简写形式：运行前请追加此标志。例如，运行 openspec status --change "<name>" --json --store "<id>"，不要使用下文所示的未指定存储库的形式。其他命令不接受此标志。命令打印出的提示已包含此标志；后续命令也要保留它。未指定存储库时，命令会作用于最近的本地 openspec/ 根目录。

输入： 可以选择指定一个变更名称。如果省略，请检查是否能从对话上下文中推断出来。如果含糊不清或存在歧义，你必须询问用户可选的变更。

/openspec-continue-change 是可选工作流，可能尚未安装。在下文任何地方建议使用它之前，请先确认其可用。如果不可用，openspec status --change "<name>" --json 会显示下一个文档，而 openspec instructions "<artifact-id>" --change "<name>" --json 会说明如何创建该文档。

步骤

1. 选择变更

   如果提供了名称，就使用该名称。否则：

   • 如果用户在对话上下文中提到过某个变更，则从中推断
   • 如果只有一个进行中的变更，则自动选择
   • 如果存在歧义，运行 openspec list --json，获取按最近修改时间排序的可用变更，并让用户选择一个

   提示用户时，将最近修改的 3–4 个变更作为选项展示，并显示：

   • 变更名称
   • 方案（如果存在 schema 字段，则取其值；否则为“spec-driven”）
   • 状态（例如“0/5 个任务”“已完成”或“无任务”）
   • 距上次修改的时间（取自 lastModified 字段）

   在最近修改的变更后标注“（推荐）”，因为用户很可能想更新它。

   始终告知用户：“使用变更：”，并说明如何切换（例如 /openspec-update-change <other>）。

2. 获取变更的文档

   openspec status --change "<name>" --json
   

   解析 JSON 以了解当前状态。响应包含：

   • schemaName：所用工作流方案（例如“spec-driven”）
   • artifacts：文档数组，包含各自的状态（“done”“skipped”“ready”或“blocked”）
   • isPlanningComplete：布尔值，表示所有规划文档是否都已完成。较旧版本的 CLI 使用同一值，但字段名为 isComplete。
   • planningHome、changeRoot、artifactPaths 和 actionContext：路径和作用域上下文。请使用这些值，不要假定路径位于仓库本地。

   文档 ID 和路径由当前启用的方案决定——不要假定它们，也不要针对硬编码的文档名称编写分支逻辑。自定义方案必须能够原样使用。

   要编辑的文件是 artifactPaths.<id>.existingOutputPaths——磁盘上实际存在的文件；对于 glob 文档，这些路径已展开为具体文件（例如 specs/**/*.md）。不要写入 resolvedOutputPath：对于 glob 文档，它仍是 glob 模式，并非真实文件。

3. 理解请求

   • 如果用户提出了具体修订要求（例如“现在的设计使用 X”），则从该修改入手。
   • 如果用户只是说“更新”或“让内容保持一致”，则进行一致性审查：阅读现有文档，并相互对照检查矛盾、遗漏和重复内容。

4. 阅读并协调

   • 阅读请求涉及的制品，以及变更中的其他现有制品。
   • 应用请求的编辑。然后检查所有其他现有制品，确认它们与之保持一致——方向不限：修改较后的制品可能需要修订较早的制品，而不只是反过来。构建顺序是有用的阅读顺序，但不限制可以修订哪些制品。
   • 记录现在所有不一致、缺失或相互矛盾之处。
   • 只修订已存在的文件（existingOutputPaths）。不要创建尚不存在的制品，也不要在 glob 制品下创建新文件——记录这些事项，并指引用户使用 /openspec-continue-change 创建它们。
   • 如果变更已经协调一致，则说明这一点并且不做任何修改。

5. 逐个确认并应用制品

   • 展示每项拟议修订及其原因。仅在用户确认后写入。
   • 如果用户拒绝某项修订，不要写入——保持该制品不变。
   • 如果需要进行大幅重写，应先获取该制品的规则和模板：

     openspec instructions "<artifact-id>" --change "<name>" --json
     

6. 指引下一步（仅提供指引——绝不执行）

   • 仍有制品缺失 -> 建议使用 /openspec-continue-change 创建它们。
   • 变更已实施（任务已勾选 / 已应用）-> 代码可能已与修订后的计划不符；建议使用 /openspec-apply-change 将差异应用到代码中。
   • 所有工作均已完成且已实施 -> 建议使用 /openspec-archive-change。

输出

每次调用后，展示：

• 修订了哪些制品（以及哪些拟议修订遭到拒绝）
• 延后至 /openspec-continue-change 处理的事项（尚未创建的制品或文件）
• 变更进展状态以及建议的下一条命令

防护规则

• 仅处理规划制品——绝不编辑实现代码。如果修订后的计划意味着需要更改代码，请停止并指引用户使用 /openspec-apply-change。
• 使用 openspec status 报告的制品 ID 和路径；绝不基于硬编码的制品名称进行判断。
• 只编辑 existingOutputPaths 中的具体文件；绝不写入 glob 制品的 resolvedOutputPath。
• 不得推进构建前沿：不得创建新制品，也不得在 glob 制品下创建新文件——这是 /openspec-continue-change 的工作。
• 写入前，须先征得用户对每项编辑的确认。
• 如果请求改变的是变更的意图，而不是对其进行细化，首先确认是否提供可选的 /openspec-new-change 工作流。如果提供，建议使用 /openspec-new-change 重新开始（“更新还是重新开始”判断法）。如果无法使用，则请用户提供一个未使用过的独立变更名称，并建议使用 openspec new change "<new-change-name>"。