SuperAPI AI 工具集

openspec-apply-change

编程与开发

查看项目

更新于 10-15 09:59

技能介绍

用途

本技能用于实现 OpenSpec 变更(change)中的任务。当用户希望开始实现、继续实现或逐项推进任务时使用。

主要能力

  • 选择变更:可指定变更名称;若未指定,则尝试从对话上下文推断,或在仅有一个活跃变更时自动选择;若含糊不清,则运行 openspec list --json 获取可用变更并通过 AskUserQuestion 工具让用户选择。选定后始终提示 "Using change: " 及覆盖方式(如 /opsx:apply <other>)。
  • 检查状态以理解 schema:运行 openspec status --change "<name>" --json,解析 JSON 获取 schemaName(所用工作流,如 "spec-driven")以及包含任务的 artifact(spec-driven 通常为 "tasks",其他 schema 需查看状态)。
  • 获取应用指令:运行 openspec instructions apply --change "<name>" --json,返回上下文文件路径(随 schema 变化,可能是 proposal/specs/design/tasks 或 spec/tests/implementation/docs)、进度(总数、已完成、剩余)、带状态的任务列表,以及基于当前状态的动态指令。
  • 处理状态:若 state 为 "blocked"(缺少 artifact),显示消息并建议使用 openspec-continue-change;若为 "all_done",表示祝贺并建议归档;否则继续实现。
  • 读取上下文文件:读取应用指令输出中 contextFiles 列出的文件。文件取决于所用 schema:spec-driven 为 proposal、specs、design、tasks;其他 schema 遵循 CLI 输出的 contextFiles。
  • 展示当前进度:显示所用 schema、进度("N/M tasks complete")、剩余任务概览,以及来自 CLI 的动态指令。
  • 实现任务(循环直至完成或阻塞):对每个待处理任务,显示正在处理的任务、进行所需代码更改、保持更改最小且聚焦、在任务文件中将 - [ ] 标记为 - [x],然后继续下一任务。

使用方式

在以下情况暂停:任务不明确时请求澄清;实现中发现设计问题时建议更新 artifact;遇到错误或阻塞时报告并等待指示;用户中断时。

完成或暂停时展示状态:本次会话完成的任务、总体进度("N/M tasks complete");若全部完成则建议归档;若暂停则解释原因并等待指示。

实现过程中的输出格式示例:

## Implementing: <change-name> (schema: <schema-name>)

Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete

Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete

完成时的输出格式示例:

## Implementation Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓

### Completed This Session
- [x] Task 1
- [x] Task 2
...

All tasks complete! Ready to archive this change.

暂停(遇到问题)时的输出格式示例:

## Implementation Paused

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete

### Issue Encountered
<description of the issue>

**Options:**
1. <option 1>
2. <option 2>
3. Other approach

What would you like to do?

适用场景

适用于需要按 OpenSpec 变更中的任务清单逐项落地实现的开发流程,支持在 artifact 尚未全部完成(若任务已存在)、部分实现之后,或与其他操作交错时随时调用。

限制与约束(Guardrails)

  • 持续处理任务直至完成或阻塞。
  • 开始前始终读取上下文文件(来自应用指令输出)。
  • 若任务含糊,先暂停询问再实现。
  • 若实现暴露问题,暂停并建议更新 artifact。
  • 保持代码更改最小且限定在每个任务范围内。
  • 每完成一个任务后立即更新任务复选框。
  • 遇到错误、阻塞或需求不清时暂停,不要猜测。
  • 使用 CLI 输出中的 contextFiles,不要假设具体文件名。

流式工作流集成

本技能支持 "actions on a change" 模型:可在任意时间调用(所有 artifact 完成前,若任务已存在;部分实现后;与其他操作交错);允许更新 artifact:若实现暴露设计问题,建议更新 artifact——不锁定阶段,灵活工作。