SuperAPI AI 工具集

openspec-apply-change

编程与开发

查看项目

更新于 10-16 10:15

技能介绍

用途

openspec-apply-change 是一个用于实施 OpenSpec 变更(change)中任务的技能。当用户希望开始实施、继续实施或逐项推进任务时使用。

主要能力

  • 选择变更:用户可提供变更名称,否则根据对话上下文推断;若只有一个活动变更则自动选择;若模糊不清则运行 openspec list --json 获取可用变更并请用户选择。选定后需宣布 "Using change: " 并说明如何覆盖。
  • 检查状态:运行 openspec status --change "<name>" --json,解析 JSON 了解 schemaName(如 "spec-driven")、planningHome、changeRoot、actionContext,以及哪个产物包含任务(通常为 spec-driven 的 "tasks")。
  • 获取 apply 指令:运行 openspec instructions apply --change "<name>" --json,返回 contextFiles(产物 ID 到具体文件路径的映射)、进度(total、complete、remaining)、带状态的任务列表、基于当前状态的动态指令,以及可选的必需项目指令输入和 operationGuidance。
  • 处理状态:若 state 为 "blocked"(缺少产物),显示消息并建议使用 $openspec-continue-change 或 /openspec-continue-change;若 state 为 "all_done",祝贺并建议归档;否则继续实施。
  • 读取上下文文件:读取 apply 指令输出中 contextFiles 下列出的每个文件路径。spec-driven 包括 proposal、specs、design、tasks;其他 schema 遵循 CLI 输出。
  • 展示进度:显示所用 schema、进度 "N/M tasks complete"、剩余任务概览和 CLI 动态指令。
  • 实施任务:循环处理每个待办任务,显示正在处理哪个任务,进行所需代码更改,保持更改最小且聚焦,在任务文件中将 - [ ] 标记为 - [x],然后继续下一个任务。

使用方式

  • 指定变更名称:$openspec-apply-change (Codex) 或 /openspec-apply-change (其他智能体) add-auth。
  • 若未指定,检查是否可从对话上下文推断;若模糊,必须提示可用变更。
  • Store 选择:若用户指定 store(本机注册的独立 OpenSpec 仓库)或工作位于其中,运行 openspec store list --json 发现已注册 store id,然后在读写 specs 与 changes 的命令上传递 --store <id>(new change、status、instructions、list、show、validate、archive、doctor、context、view)。选定后,--store <id> 在其余工作流中保持生效。不带 store 时,命令作用于最近的本地 openspec/ 根目录。
  • 阻塞时暂停:任务不明确时请求澄清;实施中发现设计问题建议更新产物;遇到错误或阻塞时报告并等待指引;用户中断时暂停。

适用场景

  • 用户希望开始实施、继续实施或推进 OpenSpec 变更中的任务。
  • 可在所有产物完成前调用(若任务已存在)、部分实施后调用,或与其他操作交错进行。
  • 允许产物更新:若实施中发现设计问题,建议更新产物,不锁定阶段,灵活工作。

限制与护栏

  • 持续处理任务直到完成或阻塞。
  • 开始前始终读取上下文文件(来自 apply 指令输出)。
  • 任务模糊时暂停并在实施前询问。
  • 实施中发现问题时暂停并建议更新产物。
  • 代码更改保持最小并限定在每个任务范围内。
  • 每个任务完成后立即更新任务复选框。
  • 遇到错误、阻塞或需求不清时暂停,不要猜测。
  • 使用 CLI 输出的 contextFiles,不要假设具体文件名。
  • 不要将 context 或 operation guidance 作为任务完成的证据。
  • 应用相关项目上下文;报告与控制性工作流输入的冲突。
  • 考虑每条 guidance 条目;解释不适用或冲突的建议。
  • 不要将运行时上下文或操作指南复制到实施文件或规划产物中。
  • 保留 CLI 控制的 blocked/ready/all-done 行为和完成标准。
  • context 与 operationGuidance 是提示级行为契约,不是可强制执行的检查。
  • 未提供官方定价、平台支持范围等具体信息。