SuperAPI AI 工具集

openspec-explore

编程与开发

查看项目

更新于 11-11 23:22

技能介绍

openspec-explore 是一个 OpenSpec 技能,核心定位是“探索模式”:AI 代理在此模式下扮演思考伙伴,而不是实现者。它适合在动手写代码前,先把问题想清楚、把需求聊透。

主要用途

  • 探索问题空间:围绕用户提出的想法提出问题、挑战假设、重新定义问题、寻找类比。
  • 调查代码库:读取文件、搜索代码,梳理现有架构、找出集成点与既有模式,暴露隐藏的复杂度。
  • 比较方案:头脑风暴多种做法,制作对比表格,勾勒取舍,必要时给出建议路径。
  • 可视化思考:使用 ASCII 图绘制系统图、状态机、数据流、架构草图、依赖关系图与对比表。
  • 识别风险与未知:指出可能出错的地方、理解上的缺口,建议做探索性验证(spike)。

使用方式

  • 触发方式:在 Codex 中使用 $openspec-explore,在其他代理中使用 /openspec-explore;可附带变更名称,例如 /openspec-explore add-auth-system。
  • 上下文检查:开始时运行 openspec list --json,了解是否存在活跃变更及其名称、schema 和状态;并从解析出的根目录读取 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 时,命令作用于最近的本地 openspec/ 根目录。
  • 无变更时:自由思考,灵感成熟时可提议创建变更提案;若用户要求把探索结果记录为新变更,则先运行 openspec new change "<name>"(适用时带 --store <id>)搭建脚手架,不得手工在 openspec/changes/ 下创建目录;随后运行 openspec status --change "<name>" --json,按依赖顺序处理用户请求的工件,对每个就绪工件运行 openspec instructions "<artifact-id>" --change "<name>" --json,按返回的模板与说明写入 resolvedOutputPath,并遵守 context 与 rules;若某工件自身说明中的条件不适用于本次变更,记录为有意跳过。若某请求工件被用户未请求的前置工件阻塞,且该前置工件带条件,先评估条件,不适用则记录跳过;适用或无条件时视为正常前置,需先征得用户同意再扩展记录范围。每次创建工件后重新运行 status 检查进度。
  • 有变更时:运行 openspec status --change "<name>" --json,使用其中的 changeRoot、artifactPaths、actionContext,从 artifactPaths.<artifact>.existingOutputPaths 读取既有文件,并在对话中自然引用;当做出决定时,询问是否记录到对应工件:新需求或需求变更写入 specs/<capability-path>/spec.md,设计决策写入 design.md,范围变更写入 proposal.md,新工作写入 tasks.md,假设被推翻则更新相关工件。

适用场景

  • 用户只有一个模糊想法(例如“想加实时协作”)时,帮助厘清方向与复杂度。
  • 用户带着具体问题(例如“认证系统很乱”)时,结合代码库画出当前流程并定位症结。
  • 实现中途卡住时,读取变更工件,追踪任务涉及内容,探讨选项并建议更新设计或增加 spike 任务。
  • 需要做技术选型对比(例如 SQLite 与 Postgres)时,结合具体约束给出对照分析。

限制与边界

  • 探索模式只用于思考,不实现:可以读文件、搜代码、调查代码库,但绝不写代码或实现功能;用户要求实现时,应提醒其先退出探索模式并创建变更提案。创建 OpenSpec 工件(提案、设计、规格)属于记录思考,是允许的。
  • 没有固定步骤、必选顺序或强制产出;结尾可以是转入提案、更新工件、仅获得清晰结论或稍后继续。
  • 不自动记录:提出保存建议即可,不施压、不擅自写入。
  • 不臆造理解:不清楚就深入挖掘;不赶进度,让问题形态自然浮现。

该技能的具体收费、价格与平台支持等信息暂未提供。