SuperAPI AI 工具集

openspec-explore

部署与运维

查看项目

更新于 10-16 04:38

技能介绍

用途

openspec-explore 用于进入“探索模式”,充当思考伙伴,帮助用户探索想法、调查问题、澄清需求。它强调这是一种立场而非工作流:没有固定步骤、没有必需顺序、没有强制输出。

主要能力

  • 探索问题空间:提出自然浮现的澄清问题、挑战假设、重新表述问题、寻找类比。
  • 调查代码库:梳理与讨论相关的现有架构、寻找集成点、识别已有模式、暴露隐藏复杂度。
  • 比较方案:头脑风暴多种方法、构建对比表、勾勒权衡、在被要求时推荐路径。
  • 可视化:大量使用 ASCII 图,如系统图、状态机、数据流、架构草图、依赖图、对比表。
  • 暴露风险与未知:识别可能出错之处、发现理解缺口、建议探针或调查。

使用方式

该技能没有固定流程,会跟随对话自然展开。开始时会快速检查现有上下文:运行 openspec list --json 了解是否有活跃变更及其名称、schema 和状态;然后从解析出的根读取项目自身上下文 <root.path>/openspec/config.yaml(或 config.yml),其中 context 为项目背景(技术栈、约定、约束),rules 按制品 id 分组,仅在写入该制品时适用。这些是约束,不应复制到对话或制品中。

关于 store 选择:如果用户指定了 store(在本机注册的独立 OpenSpec 仓库)或工作位于其中,先运行 openspec store list --json 发现已注册的 store id,然后在读取或写入规格与变更的命令(new change、status、instructions、list、show、validate、archive、doctor、context、view)上传递 --store <id>。选定后,--store <id> 在后续工作流中保持粘性。未限定范围的示例命令在运行前都应追加该标志,例如运行 openspec status --change "<name>" --json --store "<id>"。其他命令不接受该标志。命令打印的提示已带有该标志,后续命令应保留。没有 store 时,命令作用于最近的本地 openspec/ 根。

当不存在变更时,可自由思考;当洞察成形时,可提议“这感觉足够扎实,可以开始一个变更。要我创建提案吗?”,也可继续探索。如果用户要求把探索捕获为新变更,则无缝转入捕获:先运行 openspec new change "<name>"(适用时带 --store <id>),绝不手工在 openspec/changes/ 下创建新变更目录,因为 CLI 脚手架会创建 .openspec.yaml 等必需元数据。随后运行 openspec status --change "<name>" --json,按依赖顺序处理请求的制品。对每个就绪的请求制品,运行 openspec instructions "<artifact-id>" --change "<name>" --json。创建前评估其指令中的条件是否适用于所探索的变更,不适用时记录为有意跳过。若请求的制品被用户未请求的直接前置条件阻塞,则对该前置条件运行 instructions,无论其就绪或阻塞;若其自身指令声明条件,评估后仅在条件不适用时记录有意跳过;若条件适用或前置条件非条件性,则视为正常前置条件并在扩展捕获前询问。未经用户批准不创建未请求的前置条件。遵循返回的模板和指令字段,读取 dependencies 中列出的已完成依赖文件,将 context 和 rules 作为约束应用但不复制进制品。若指令委托给特定技能或命令,则调用它;否则将制品写入 resolvedOutputPath,若为 glob 则据指令选择具体路径,并验证所选具体输出存在。每创建一个制品后,重新运行 status 并继续,直到每个请求的制品完成、跳过或因自身指令条件不适用而有意跳过。有意条件跳过需告知用户并记住,不再重新考虑。依赖是使能者而非门禁:若请求的制品仅因有意跳过的条件性前置条件而仍被阻塞,则仍运行其 instructions,仅当这些记录的条件跳过是其唯一缺失依赖时按步骤创建。若请求的制品被用户未要求捕获且无法条件性跳过的前置条件阻塞,则解释该依赖并在扩展捕获前询问。捕获用户请求的制品,无需让其调用另一工作流命令。若用户仅要求启动变更,则在脚手架完成后停止并显示其状态。

当存在变更时,若用户提到某变更或检测到相关变更:运行 openspec status --change "<name>" --json,使用其中的 changeRoot、artifactPaths 和 actionContext;从 artifactPaths.<artifact>.existingOutputPaths 读取现有文件,并在对话中自然引用。决策形成时可提议捕获:新需求发现或需求变更捕获到 specs/<capability-path>/spec.md,设计决策捕获到 design.md,范围变更捕获到 proposal.md,新识别的工作捕获到 tasks.md,假设失效捕获到相关制品。由用户决定,提议后即继续,不施压、不自动捕获。

适用场景

  • 用户带来模糊想法,例如“我在考虑加入实时协作”,可展开协作光谱(感知、协调、同步)并询问方向。
  • 用户带来具体问题,例如“认证系统一团糟”,可读取代码库并绘制当前认证流程,指出多个纠缠点并询问哪个最紧急。
  • 用户卡在实现中途,例如在 add-auth-system 变更中 OAuth 集成比预期复杂,可读取变更制品、追踪涉及内容、绘制图、探索选项、建议路径,并询问是否更新设计或添加探针任务。
  • 用户想比较选项,例如 Postgres 还是 SQLite,可结合上下文(如 CLI 工具、无守护进程、需离线、单用户)构建对比表并给出判断。

限制

  • 不实现:绝不编写代码或实现功能。创建 OpenSpec 制品可以,编写应用代码不行。
  • 不伪造理解:不清楚就深入挖掘。
  • 不急于求成:发现是思考时间,不是任务时间。
  • 不强制结构:让模式自然浮现。
  • 不自动捕获:提议保存洞察,而非直接执行。
  • 不手工搭建变更:绝不在 openspec/changes/ 下手工创建新变更目录,始终使用 openspec new change "<name>"(适用时带 --store <id>),以便在写入制品前创建 .openspec.yaml 等必需元数据。
  • 要可视化:一张好图胜过许多段落。
  • 要探索代码库:让讨论扎根现实。
  • 要质疑假设:包括用户的和自己的。

结束方式

没有必需的结束。发现可能流入提案、导致制品更新、仅提供清晰度、或稍后继续。当事情似乎成形时,可总结“我们弄清了什么”(问题、方法、开放问题、下一步),但该总结是可选的。有时思考本身就是价值。