SuperAPI AI 工具集

openspec-apply-change

编程与开发

查看项目

更新于 10-16 04:06

技能介绍

用途

openspec-apply-change 用于实现某个 OpenSpec 变更(change)中的任务。当用户想要开始实现、继续实现,或逐项推进某个变更的任务时使用该技能。

主要能力

  • 选择目标变更:可显式指定变更名称,也可从对话上下文推断;若只有一个活动变更则自动选择;若含糊不清则列出可用变更并请用户选择。
  • 读取变更状态:通过 openspec status --change "<name>" --json 了解所用 schema(如 spec-driven)、planningHome、changeRoot、actionContext,以及哪个产物包含任务。
  • 获取 apply 指令:通过 openspec instructions apply --change "<name>" --json 获取 contextFiles、进度(总数/完成/剩余)、任务列表及状态、基于当前状态的动态指令,以及可选的 context 与 operationGuidance。
  • 处理状态:若状态为 blocked(缺少产物),提示使用 continue-change 技能或查看下一产物;若为 all_done,则祝贺并建议归档;否则进入实现。
  • 读取上下文文件:读取 apply 指令输出中 contextFiles 列出的每个文件路径(spec-driven 下通常为 proposal、specs、design、tasks)。
  • 展示进度:显示所用 schema、进度“N/M tasks complete”、剩余任务概览及 CLI 动态指令。
  • 逐项实现任务:显示当前任务、进行所需代码改动、保持改动最小且聚焦、在任务文件中将 - [ ] 标记为 - [x],然后继续下一项。
  • 暂停条件:任务不清晰时请求澄清;实现中发现设计问题则建议更新产物;遇到错误或阻塞则报告并等待指引;用户中断时暂停。
  • 完成或暂停时展示状态:本次完成的任务、总体进度;全部完成则建议归档,暂停则说明原因并等待指引。

使用方式

输入时可选择指定变更名称,例如 $openspec-apply-change (Codex) 或 /openspec-apply-change (other agents) add-auth。若省略,则检查是否可从对话上下文推断;若含糊或歧义,必须提示可用的变更。

Store 选择:若用户指定了 store(本机注册的独立 OpenSpec 仓库)或工作位于某个 store 中,先运行 openspec store list --json 发现已注册的 store id,然后在读取或写入 specs 与 changes 的命令(new change、status、instructions、list、show、validate、archive、doctor、context、view)上传入 --store <id>。选定后,--store <id> 在后续工作流中保持粘性。命令打印的提示已带有该标志,后续命令应保留。未指定 store 时,命令作用于最近的本地 openspec/ 根目录。

主要步骤:

  1. 选择变更。若提供了名称则使用;否则从上下文推断、自动选择唯一活动变更,或在歧义时运行 openspec list --json 并请用户选择。始终宣布“Using change: ”及如何覆盖。
  2. 检查状态以了解 schema:openspec status --change "<name>" --json。
  3. 获取 apply 指令:openspec instructions apply --change "<name>" --json。
  4. 处理状态:blocked 时提示;all_done 时建议归档;否则继续实现。
  5. 读取上下文文件:读取 contextFiles 中列出的每个路径。
  6. 展示当前进度。
  7. 循环实现任务,直到完成或阻塞。
  8. 完成或暂停时展示状态。

适用场景

  • 需要按 OpenSpec 变更中的任务清单逐项落地实现。
  • 在部分实现后继续推进剩余任务。
  • 与其他“针对变更的操作”交错使用,支持流体工作流。

限制与约束

  • 必须始终在开始前读取上下文文件(来自 apply 指令输出)。
  • 任务含糊时暂停并询问,不猜测。
  • 实现中发现问题时暂停并建议更新产物。
  • 代码改动保持最小并限定在每项任务范围内。
  • 每完成一项任务后立即更新任务复选框。
  • 遇到错误、阻塞或需求不清时暂停。
  • 使用 CLI 输出中的 contextFiles,不假设具体文件名。
  • 不得将 context 或 operationGuidance 当作任务完成的证据,也不得将其逐字复制到实现文件或规划产物中(除非用户另行要求)。
  • 若 context 与内置指令、用户明确选择或 CLI 控制值冲突,应报告冲突并保留控制值;若 guidance 不适用或冲突,则不遵循并说明原因。
  • 保留 CLI 控制的 blocked/ready/all-done 行为与完成标准。
  • 该技能支持“针对变更的操作”模型:可在所有产物完成前(若任务已存在)、部分实现后、与其他操作交错时随时调用;允许更新产物,不锁定阶段,可流体推进。