SuperAPI AI 工具集

openspec-propose

编程与开发

查看项目

更新于 10-16 05:40

技能介绍

用途

openspec-propose 用于在 OpenSpec 规范驱动开发流程中提出一个新的变更。当用户想快速描述要构建或修复的内容,并希望一次性获得完整提案时使用。该工作流只创建规划产物,不编辑项目代码。

主要能力

  • 根据用户描述推导 kebab-case 变更名称(例如“add user authentication”对应 add-user-auth)。
  • 使用默认规范驱动 schema 生成以下产物:
    • proposal.md:做什么与为什么
    • specs/<capability-path>/spec.md:系统必须做什么,是增量而非主规范
    • design.md:如何实现
    • tasks.md:实现步骤
  • 支持通过 --schema 指定其他工作流 schema。
  • 支持已注册的 store:通过 openspec store list --json 发现 store id,并在读写规范与变更的命令上附加 --store <id>,选定后在该工作流剩余步骤中保持粘性。
  • 通过 openspec status --change "<name>" --json 获取产物构建顺序、依赖边、路径与作用域上下文。
  • 通过 openspec instructions <artifact-id> --change "<name>" --json 获取每个产物的上下文、规则、模板、指令、输出路径与依赖。

使用方式

  1. 理解请求并澄清实质性歧义。若未提供明确输入,询问用户想处理什么变更。
  2. 确定工作流 schema:默认使用已配置的默认 schema;仅当用户明确按名称请求时才使用 --schema <schema-name>。
  3. 创建变更目录:
    • 默认:openspec new change "<name>"
    • 指定 schema:openspec new change "<name>" --schema "<schema-name>"
  4. 获取产物构建顺序:openspec status --change "<name>" --json,解析 applyRequires、artifacts、planningHome、changeRoot、artifactPaths 和 actionContext。
  5. 按依赖顺序创建所需集合中的每个产物:
    • 获取指令:openspec instructions <artifact-id> --change "<name>" --json
    • 从磁盘重新读取已完成的依赖文件作为上下文
    • 若 instruction 字段委托给特定技能或命令,则调用它生成产物,并验证文件存在于 resolvedOutputPath
    • 否则按 template 结构写入 resolvedOutputPath;若为 glob,按 instruction 选择具体路径
    • context 和 rules 是约束,不得复制进文件
    • 每创建一个产物后重新运行 openspec status --change "<name>" --json
  6. 所需集合为 applyRequires 加上从这些产物沿 requires 边可达的所有产物(规范驱动会闭包到 proposal、specs、design、tasks)。
  7. 仅当 status 已报告 skipped,或其自身 instruction 标记为可选时才跳过。
  8. 展示最终状态:openspec status --change "<name>"。
  9. 汇总变更名称与位置、已创建产物及简要说明、跳过的条件产物及原因,并提示用户产物已可供审阅,准备好后运行 $openspec-apply-change(Codex)或 /openspec-apply-change(其他代理)或要求应用该变更。

适用场景

  • 用户希望快速描述要构建或修复的内容并获得完整提案。
  • 需要在实现前生成规划产物,包括提案、增量规范、设计与任务。
  • 使用 OpenSpec 规范驱动开发流程,并希望按 schema 定义的产物结构推进。

限制

  • 该工作流仅授权规划,不实现变更、不启动 apply 工作流、不编辑项目代码。
  • 即使初始请求要求构建或修复,也不得在同一响应中开始实现;需等待用户在产物呈现后提出新请求,再启动 apply 工作流。
  • 必须创建 apply 阶段传递依赖的每个产物,而不仅是 apply.requires 中列出的 id。
  • 创建新产物前必须从磁盘重新读取依赖产物,而非依赖对话记忆。
  • 对会实质性改变范围、外部可观察行为、兼容性或验收标准的歧义必须询问用户;次要细节可做合理假设并记录。
  • 若同名变更已存在,询问用户是继续还是新建。
  • 写入后需验证每个产物文件存在再继续。
  • status 仅检查文件是否存在,applyRequires 产物显示 done 不代表其依赖存在;应使用 requires 边构建所需集合。
  • 已标记 skipped 的产物视为满足,不得创建其文件。
  • 依赖是使能条件而非门禁:若必需产物仅因跳过了条件依赖而被阻塞,仍应写入。
  • 关于收费、价格、平台、效果等事实,资料未提供。