SuperAPI AI 工具集

openspec-apply-change

编程与开发

查看项目

更新于 10-16 05:40

技能介绍

用途

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

主要能力

  • 选择要处理的变更(change):支持显式指定变更名,也可从对话上下文推断;若只有一个活跃变更则自动选择;若含糊则列出可用变更并请用户选择。
  • 读取变更状态以理解所用 schema:通过 openspec status --change "<name>" --json 获取 schemaName、planningHome、changeRoot、actionContext,以及包含任务的 artifact(spec-driven 通常为 tasks)。
  • 获取实现指令:通过 openspec instructions apply --change "<name>" --json 返回 contextFiles(artifact ID 到具体文件路径的映射)、进度(总数、已完成、剩余)、带状态的任务列表、基于当前状态的动态指令,以及可选的 context(项目指令输入)和 operationGuidance(实现建议)。
  • 处理状态:若 state 为 blocked(缺少 artifact),提示使用 continue-change 技能或查看下一个 artifact;若 state 为 all_done,则祝贺并建议归档;否则进入实现。
  • 读取上下文文件:读取 apply 指令输出中 contextFiles 列出的每个文件路径(spec-driven 为 proposal、specs、design、tasks;其他 schema 以 CLI 输出为准)。
  • 展示当前进度:显示所用 schema、进度(N/M 任务完成)、剩余任务概览、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> 在后续工作流中保持粘性。下方每个未加作用域的示例都是简写:运行前需追加该标志。例如运行 openspec status --change "<name>" --json --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 时提示使用 continue-change(若未安装,运行 openspec status --change "<name>" --json 查看下一个 artifact,并用 openspec instructions <artifact-id> --change "<name>" --json 了解如何创建);all_done 时祝贺并建议归档;否则进入实现。
  5. 将 context 视为必需的提示级输入,读取并考虑,在实现时应用相关项目事实、约定和约束。将 operationGuidance 视为可选附加建议,读取并考虑每一条,遵循适用且与内置工作流兼容的条目。
  6. 读取上下文文件:读取 apply 指令输出中 contextFiles 列出的每个文件路径。
  7. 展示当前进度。
  8. 实现任务(循环直至完成或阻塞)。
  9. 完成或暂停时展示状态。

适用场景

  • 开始实现某个 OpenSpec 变更中的任务。
  • 继续之前未完成的实现。
  • 逐项推进变更任务清单。
  • 可在所有 artifact 完成前(若任务已存在)、部分实现后、与其他操作交错时随时调用。

限制

  • 不得将 context 或 operationGuidance 逐字复制到实现文件或规划 artifact 中,除非用户另行要求。
  • context 和 operationGuidance 与 CLI 返回的状态、缺失 artifact、任务、进度、contextFiles 及内置指令保持分离;它们不是任务完成的证据,不替代内置指令,也不允许绕过 blocked 状态。
  • 若 context 与内置指令、用户明确选择或 CLI 控制值冲突,报告冲突并保留控制值。若 guidance 不适用或与这些控制输入冲突,则不遵循并解释原因。
  • 这些是提示级行为契约,不是可强制执行的检查。
  • 任务含糊时暂停并询问;实现暴露问题时暂停并建议更新 artifact;保持代码改动最小且限定于每个任务;每完成一个任务立即更新任务复选框;遇到错误、阻塞或需求不清时暂停,不要猜测;使用 CLI 输出中的 contextFiles,不要假设具体文件名;不要用 context 或操作指导作为任务完成的证明;保留 CLI 控制的 blocked/ready/all-done 行为与完成标准。