Druid OPSX 工作流详解：使用 /opsx:new 命令开启一个 OpenSpec 变更

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）声明了命令的元信息：

从源码结构看，该命令与 openspec-new-change 技能文件 是同一工作流的两个入口：一个是斜杠命令（供交互式触发），一个是 Skill（供 Agent 按需调用）。两者步骤完全一致，仅最终提示语略有差异（命令版提示运行/opsx:continue，Skill 版提示直接描述变更内容）。技能文件明确声明了运行前提：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之后的参数）有两种合法形式：

1. kebab-case 变更名：例如add-user-auth。若输入不是合法的 kebab-case，命令的护栏规则要求向用户索要一个合法名称，而不是自行猜测。
2. 变更的自然语言描述：命令会基于描述推导出一个 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：获取首个制品的指引

首个制品取决于 Schema（spec-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 I'll draft it.”

五、护栏（Guardrails）规则

文档末尾列出了四条硬性护栏，约束 Agent 的执行边界：

1. 不要创建任何制品—— 只展示指引（instructions）；
2. 不要推进到首个制品模板之外的阶段；
3. 名称非法时（不是 kebab-case），要求用户给出合法名称；
4. 同名变更已存在时，建议改用/opsx:continue继续该变更，而不是重复创建；
5. 使用非默认工作流时，必须传递--schema参数。

这些护栏保证了/opsx:new的副作用被严格限制在“创建脚手架目录 + 展示模板”这一最小范围内，制品的实际内容编写完全交由后续的/opsx:continue按“每次只创建一个制品”的节奏推进。

六、底层支撑：openspec/config.yaml 的配置如何生效

/opsx:new创建的变更并非凭空运转，其行为大量受 openspec/config.yaml 驱动。该文件包含三类关键配置，openspec instructions输出的上下文即来源于此：

1. 项目上下文（context）

context字段以 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 Baseline）：openspec/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. 分制品规则（rules）

config.yaml的rules段为每个制品类型定义了硬性检查项，例如：

• proposal：必须说明受影响的模块（core、starter 等）、变更类型（feature/enhancement/bug fix/refactoring）、向后兼容性影响、受影响的公共 API；
• specs：场景必须使用 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/ 下十余个带日期前缀的归档变更，即为该完整链路真实运行过的产物证据。

八、实操要点小结

1. 前置条件：安装 OpenSpec CLI，并在 Druid 仓库根目录下操作（openspec/目录必须存在）；
2. 命名：始终使用 kebab-case，例如fix-grouping-sets-comma（可参照归档目录 2026-05-12-fix-grouping-sets-comma 的命名方式）；
3. Schema：Druid 默认使用spec-driven，除非用户显式指定，否则不加--schema参数；
4. 最小副作用：/opsx:new只创建目录骨架并展示模板，不写任何制品内容；
5. 同名冲突：变更目录已存在时，直接走/opsx:continue继续推进，不要重建；
6. 规则来源：所有制品的检查要求以 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