Druid OPSX 工作流详解使用 /opsx:new 命令开启一个 OpenSpec 变更【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid本篇技术指南围绕 Druid 仓库中的 OPSX: New 命令定义 展开完整讲解如何通过该命令以实验性的“制品驱动artifact-driven”方式发起一个新变更从变更命名、工作流 Schema 选择、目录脚手架创建到制品状态查询与首个制品模板获取的每一步命令与规则。读完后你可以直接在 Druid 仓库中规范化地启动一个结构化的变更流程并理解 openspec/config.yaml 中配置的项目上下文与规则是如何驱动整个流程的。一、命令定位OPSX 工作流的入口.qoder/commands/opsx/new.md 是 Druid 仓库内置的一个 Qoder 斜杠命令slash command定义文件对应命令为/opsx:new。其文件头部front-matter声明了命令的元信息字段值含义nameOPSX: New命令展示名descriptionStart a new change using the experimental artifact workflow (OPSX)功能描述categoryWorkflow命令分类tagsworkflow,artifacts,experimental标签表明这是实验性制品工作流从源码结构看该命令与 openspec-new-change 技能文件 是同一工作流的两个入口一个是斜杠命令供交互式触发一个是 Skill供 Agent 按需调用。两者步骤完全一致仅最终提示语略有差异命令版提示运行/opsx:continueSkill 版提示直接描述变更内容。技能文件明确声明了运行前提Requires openspec CLI即整个 OPSX 工作流依赖 OpenSpec 命令行工具。OPSX 系列的完整命令集合位于 .qoder/commands/opsx/ 目录包括new、continue、apply、archive、bulk-archive、explore、ff、onboard、sync、verify。/opsx:new是其中的起点负责创建变更目录并停在“展示首个制品模板”处后续推进则由/opsx:continue接力。二、输入规范变更名或变更描述命令的输入即/opsx:new之后的参数有两种合法形式kebab-case 变更名例如add-user-auth。若输入不是合法的 kebab-case命令的护栏规则要求向用户索要一个合法名称而不是自行猜测。变更的自然语言描述命令会基于描述推导出一个 kebab-case 名称。文档中给出的示例是“add user authentication” 描述被推导为add-user-auth。第一步的关键约束如果用户没有提供任何输入必须使用 AskUserQuestion 工具开放式提问不带预设选项询问What change do you want to work on? Describe what you want to build or fix.并且文档以IMPORTANT强调在真正理解用户要构建什么之前不得继续推进。这保证了后续生成的 proposal、spec 等制品都有明确的业务意图基础。三、完整执行流程六个步骤步骤 1确认构建意图如上所述无输入时先询问有输入时从描述推导 kebab-case 名称。步骤 2确定工作流 Schema默认情况下省略--schema参数使用默认 Schema。仅当用户明确提到以下内容时才使用非默认 Schema用户给出了具体的 Schema 名称 → 使用--schema name用户说 “show workflows” 或 “what workflows” → 运行openspec schemas --json列出所有工作流让用户选择。在 Druid 仓库中默认 Schema 实际是什么可以直接从 openspec/config.yaml 的第一行确认schema: spec-driven即 Druid 采用的是spec-driven规格驱动工作流其制品序列为proposal → specs → design → tasks。该序列在 openspec-new-change 技能文件 的“Artifact Creation Guidelines”一节中有明确说明各制品的职责分别是proposal.md填写 Why动机、What Changes变更内容、Capabilities能力清单每个能力对应一个 spec 文件、Impact影响面specs/capability/spec.md按 proposal 的 Capabilities 清单为每个能力写规格使用 WHEN/THEN 格式的场景描述design.md记录技术决策、架构与实现方案tasks.md把实现拆解为带复选框checkbox的任务清单。步骤 3创建变更目录openspec new change name仅在用户要求特定工作流时才追加--schema name。执行后会在openspec/changes/name/下创建按照所选 Schema 组织的变更脚手架目录。仓库中 openspec/changes/archive/ 目录下保留了大量历史变更如2026-02-20-split-sql-expr-parser-primary-method、2026-03-06-optimize-odps-dialect等它们正是经过该流程创建、完成并归档的实例每个归档目录内都包含proposal.md、design.md、tasks.md和specs/子目录与上述制品序列一一对应。步骤 4查看制品状态openspec status --change name该命令输出两个关键信息哪些制品尚需创建哪些制品已经ready依赖满足可以开始创建。步骤 5获取首个制品的指引首个制品取决于 Schemaspec-driven下即proposal。从状态输出中找出第一个状态为ready的制品然后运行openspec instructions first-artifact-id --change name该命令会输出创建首个制品所需的模板与上下文。步骤 6停止并等待用户指示命令在展示完首个制品的模板后必须停下来不擅自创建任何制品文件。这是/opsx:new与/opsx:continue的职责分界线。四、输出摘要格式命令完成六个步骤后要求输出一个包含以下要素的总结变更名与位置例如openspec/changes/name/正在使用的 Schema/工作流及其制品序列如spec-driven下的 proposal → specs → design → tasks当前状态形如0/N artifacts complete首个制品的模板即openspec instructions输出的模板内容后续提示“Ready to create the first artifact? Run/opsx:continueor just describe what this change is about and Ill draft it.”五、护栏Guardrails规则文档末尾列出了四条硬性护栏约束 Agent 的执行边界不要创建任何制品—— 只展示指引instructions不要推进到首个制品模板之外的阶段名称非法时不是 kebab-case要求用户给出合法名称同名变更已存在时建议改用/opsx:continue继续该变更而不是重复创建使用非默认工作流时必须传递--schema参数。这些护栏保证了/opsx:new的副作用被严格限制在“创建脚手架目录 展示模板”这一最小范围内制品的实际内容编写完全交由后续的/opsx:continue按“每次只创建一个制品”的节奏推进。六、底层支撑openspec/config.yaml 的配置如何生效/opsx:new创建的变更并非凭空运转其行为大量受 openspec/config.yaml 驱动。该文件包含三类关键配置openspec instructions输出的上下文即来源于此1. 项目上下文contextcontext字段以 Markdown 形式注入了 Druid 的项目画像在创建制品时展示给 AI包括项目概述Druid 是阿里云开发的高性能 JDBC 连接池具备监控与统计能力技术栈Java 8目标 JDK 1.8、Maven 多模块构建、JUnit 4.x 测试项目结构core/下的pool/、sql/、stat/、wall/、filter/、util/六大核心包以及 Spring Boot 2.x/3.x/4.x 三个 starter 模块、druid-wrapper与druid-demo-petclinic编码规范Checkstyle 强制规则尾随空白、import 顺序、修饰符顺序等、命名约定PascalCase 类名、camelCase 方法名等、Apache License 文件头要求、测试命名约定Issue{number}.java、BVT 目录等架构能力基线Architecture Capability Baselineopenspec/specs/下的主规格与架构域的映射关系。2. 架构能力基线与增量规格openspec/specs/README.md 定义了当前 Druid 的基线能力规格capability specs/opsx:new启动的每个变更最终都要通过增量规格delta spec来演进这些基线sql-parser-core词法/语法/AST 管线与方言分发行为connection-pool-core池容量、生命周期任务与并发安全filter-chain有序拦截与可扩展过滤器集成wall-security基于 AST 的 SQL 安全校验monitoring-stat运行时统计收集与暴露通道。其演进方式明确为三步在openspec/changes/change-name/下创建变更 → 在openspec/changes/change-name/specs/capability/spec.md下添加增量规格 → 运行同步工作流例如/opsx:sync把增量合并回主规格。3. 分制品规则rulesconfig.yaml的rules段为每个制品类型定义了硬性检查项例如proposal必须说明受影响的模块core、starter 等、变更类型feature/enhancement/bug fix/refactoring、向后兼容性影响、受影响的公共 APIspecs场景必须使用 WHEN/THEN 格式主规格必须保持稳定重构类变更需捕获“行为等价”场景而非实现细节必须覆盖 null 处理、空输入、并发访问等边界情况design复杂变更需包含类图/流程图架构级变更需用MySqlPerf*基准测试制定前后对比的验证计划tasks需包含 checkstyle 合规检查、每个功能变更的单元测试架构变更必须添加MySqlPerfTest与内存测试并在任务执行前采集基线性能数据。这些规则通过openspec instructions以rules字段注入到每个制品的创建过程中。需要特别注意的是 openspec-new-change 技能文件 末尾的强调context与rules是对 AI 的约束条件而非制品文件的内容——不得把它们拷贝进制品文件。七、与相邻命令的衔接/opsx:new只是 OPSX 生命周期中的第一步完整链路为/opsx:new创建变更停在首个制品模板 → /opsx:continue每次创建一个制品直到 N/N 完成 → /opsx:apply按 tasks.md 实施变更 → /opsx:archive归档到 openspec/changes/archive/其中 /opsx:continue 命令定义 补充了/opsx:new停止之后的行为细节通过openspec status --change name --json解析 JSON 状态包含schemaName、artifacts数组、isComplete布尔值每次只创建第一个ready的制品写完立即 STOP并再次提示运行/opsx:continue创建下一个制品。仓库中 openspec/changes/archive/ 下十余个带日期前缀的归档变更即为该完整链路真实运行过的产物证据。八、实操要点小结前置条件安装 OpenSpec CLI并在 Druid 仓库根目录下操作openspec/目录必须存在命名始终使用 kebab-case例如fix-grouping-sets-comma可参照归档目录 2026-05-12-fix-grouping-sets-comma 的命名方式SchemaDruid 默认使用spec-driven除非用户显式指定否则不加--schema参数最小副作用/opsx:new只创建目录骨架并展示模板不写任何制品内容同名冲突变更目录已存在时直接走/opsx:continue继续推进不要重建规则来源所有制品的检查要求以 openspec/config.yaml 的rules段和 openspec/templates/ 目录下的四个模板proposal、spec、design、tasks为准。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考