SuperAPI AI 工具集

openspec-apply-change

编程与开发

查看项目

更新于 11-13 09:26

技能介绍

openspec-apply-change 是一个用于实现 OpenSpec 变更的 AI 技能。它的核心用途是:当用户希望开始实现、继续实现或逐项完成某个 OpenSpec 变更中的任务时,按任务列表推进代码修改,并在任务文件中更新完成状态。

主要能力:

  1. 选择变更:可显式指定变更名称;若未指定,则尝试从对话上下文推断,只有一个活跃变更时自动选择,存在歧义时运行 openspec list --json 并请用户选择。选择后会提示“Using change: ”及覆盖方式。
  2. 查询状态与指令:运行 openspec status --change "<name>" --json 了解 schemaName、planningHome、changeRoot、actionContext 以及包含任务的文件;运行 openspec instructions apply --change "<name>" --json 获取 contextFiles、进度、任务列表、动态指令、可选的 context 与 operationGuidance。
  3. 状态处理:若状态为 blocked(缺少制品),提示使用 openspec-continue-change 或查看下一制品;若为 all_done,则祝贺并建议归档;否则进入实现。
  4. 读取上下文文件:读取 apply 指令输出中 contextFiles 列出的每个文件路径,文件依 schema 而定,例如 spec-driven 下为 proposal、specs、design、tasks。
  5. 展示进度:显示所用 schema、进度“N/M tasks complete”、剩余任务概览及 CLI 动态指令。
  6. 逐项实现:对每个待办任务显示正在处理的任务,进行所需代码修改,保持最小且聚焦,完成后立即将任务文件中的 - [ ] 改为 - [x],继续下一任务。遇到任务不明确、实现暴露设计问题、错误或阻塞、用户中断时暂停并等待指示。
  7. 完成或暂停时输出状态:显示本次完成的任务、总体进度;全部完成则建议归档,暂停则说明原因并等待指示。

使用方式:可以通过 $openspec-apply-change(Codex)或 /openspec-apply-change(其他 agent)调用,并可附带变更名称,如 add-auth。若用户指定了 store(本机注册的独立 OpenSpec 仓库),先运行 openspec store list --json 发现已注册的 store id,然后在读取或写入 specs/changes 的命令上附加 --store <id>,并在此后工作流中保持该标志。未指定 store 时,命令作用于最近的本地 openspec/ 根目录。

适用场景:适用于已有 OpenSpec 变更任务清单、需要按清单逐步实现代码的开发者;支持在制品尚未全部完成(只要任务存在)、部分实现之后、与其他操作交错时随时调用;实现中发现设计问题时建议更新制品,而非严格阶段锁定。

限制与注意事项:必须始终先读取 contextFiles 中的上下文文件;任务存在歧义时应暂停询问而非猜测;代码修改应最小且限定在任务范围内;每完成一个任务立即更新复选框;遇到错误、阻塞或不明确要求时暂停;context 与 operationGuidance 是提示级行为约定,不得作为任务完成的证据,也不得替代内置指令或绕过 blocked 状态;若上下文与内置指令、用户明确选择或 CLI 控制值冲突,应报告冲突并保留控制值;不得将运行时上下文或操作指导原文复制到实现文件或规划制品中,除非用户另行要求。