Druid OPSX 工作流详解：Archive 命令如何安全归档 OpenSpec 中已完成的变更-北京尧图网络

Druid OPSX 工作流详解Archive 命令如何安全归档 OpenSpec 中已完成的变更【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid本文基于 Druid 仓库中的 OPSX Archive 命令定义系统讲解该命令在 OpenSpec 实验性工作流OPSX中归档已完成变更change的完整流程从变更选择、制品与任务完成度校验到 delta spec 同步评估再到带日期前缀的归档目录落盘与结果摘要输出。读完本文你将掌握该命令的六步执行逻辑、四类标准输出模板与护栏规则并能结合仓库中真实的归档产物openspec/changes/archive/下 16 个历史变更验证每一步的实际效果。1. 背景Druid 仓库中的 OpenSpec 变更体系在理解 Archive 命令之前需要先了解它所服务的目录结构。从 openspec/config.yaml 可以看到本项目采用schema: spec-driven工作流整个openspec/目录承担“架构规格变更文档”的职责见 AGENTS.md 中对openspec/的定位说明。其核心分层为主规格baseline specs位于openspec/specs/capability/spec.md是架构能力的稳定基线。仓库中目前有 8 个能力目录包括sql-parser-core、connection-pool-core、filter-chain、wall-security、monitoring-stat、dialect-registration、feature-gate-naming、test-infrastructure-core能力地图与演进方式见 openspec/specs/README.md。活动变更active changes位于openspec/changes/change-name/每个变更包含proposal.md、design.md、tasks.md三类制品以及可选的 delta 规格目录specs/capability/spec.md。归档区archive位于openspec/changes/archive/已完成变更的变更目录整体迁入此处并以YYYY-MM-DD-change-name重命名。模板openspec/templates/ 提供了proposal.md、design.md、spec.md、tasks.md四份骨架其中 tasks 模板定义了“预处理 → 核心实现 → 监控/MBean → Spring Boot 集成 → 测试 → 代码质量 → 文档 → 构建发布”的标准任务分组任务项统一使用- [ ]/- [x]复选框标记——这正是 Archive 命令第 3 步统计任务完成度的格式基础。Archive 命令命令名OPSX: Archive分类Workflow标签[workflow, archive, experimental]见其 frontmatter就是这条流水线的终点当一个变更实现完成后由它负责校验完成度、同步 delta 规格并把变更目录安全地移入归档区。该命令同时有一份镜像的 Skill 定义 openspec-archive-change要求openspecCLI 可用两者的步骤与护栏基本一致差异仅在于同步动作的表述命令版调用/opsx:sync逻辑Skill 版调用openspec-sync-specs技能。2. 输入约定变更名可选但禁止猜测命令输入格式为/opsx:archive change-name例如/opsx:archive add-auth。文档对输入的处理规则非常明确提供了变更名直接使用该变更名进入后续流程未提供先从对话上下文推断上下文模糊或有歧义必须文档原文使用大写 MUST提示用户选择可用变更并特别强调 “Do NOT guess or auto-select a change”——绝不允许 Agent 代替用户做选择。这种“宁可追问、不可猜错”的约定贯穿整个命令因为归档是一个移动文件目录的破坏性操作选错对象无法通过简单回退解决。3. 六步归档流程3.1 第一步列出并选择活动变更未提供变更名时命令会执行openspec list --json随后用 AskUserQuestion 工具把**仅处于活动状态尚未归档**的变更列表交给用户选择并尽可能附上每个变更所使用的 schema。注意“只展示活动变更”这一过滤规则openspec/changes/archive/下的历史归档不会出现在候选列表中。3.2 第二步检查制品artifact完成状态执行openspec status --change name --json解析返回的 JSON重点理解两个字段schemaName该变更使用的工作流 schemaartifacts制品列表及其状态done或其他状态。如果存在任何未done的制品命令会列出未完成项并显示警告然后提示用户确认是否继续用户确认后即继续而不是直接中止。这体现了文档护栏中“Dont block archive on warnings - just inform and confirm”警告只告知、不阻断的原则。以仓库中真实归档的变更 dialect-registration-mechanism 为例其制品齐备proposal.md说明动机、变更内容、能力影响、design.md、tasks.md以及两个 delta 规格specs/dialect-registration/spec.md与specs/sql-parser-core/spec.md——这类变更在第 2 步通常全部done可以直接进入下一步。3.3 第三步检查任务task完成状态读取变更目录下的任务文件通常是tasks.md统计两类复选框的数量- [ ]未完成任务- [x]已完成任务。发现未完成任务时显示未完成数量的警告请用户确认是否继续用户确认则继续。没有 tasks 文件时不做任务相关的警告直接继续。对照 fix-grouping-sets-comma 变更的 tasks.md 可以看到该统计的实际意义该文件包含“Summary、核心实现3 项、测试3 项、代码质量3 项、构建验证、Verification Checklist”等分节其中绝大多数是- [x]但也存在一个合法的- [ ]项——“N/A — not an architecture change, no MySqlPerfTest / memory baselines required.”。这一项在语义上是“不适用”但形式上仍是未勾选框因此归档时会被命令计入“未完成任务数”并触发确认警告。这正是把警告权交给用户、而非用硬编码规则一刀切的原因。任务的分组结构本身来自 tasks 模板其中架构级变更还要求MysqlPerfTest与内存基线对比这与 openspec/config.yaml 中tasks制品规则“For architecture changes, MUST add MySqlPerfTest and memory tests”一一对应。3.4 第四步评估 delta spec 的同步状态这是整个流程中最复杂的一步目的是回答“这个变更引入的规格修改是否已经合入主规格基线”。检查 delta 规格是否存在查看openspec/changes/name/specs/目录。若不存在不做同步提示直接进入归档对应“Output On Success (No Delta Specs)”模板。若存在 delta 规格将每个 delta 规格与对应的主规格openspec/specs/capability/spec.md逐一比对判定将要应用的变更类型adds / modifications / removals / renames——即 delta 规格中## ADDED Requirements、## MODIFIED Requirements、## REMOVED Requirements、## RENAMED Requirements四个分节格式详见 sync 命令文档在提示前先展示一份合并摘要combined summary让用户看清将要发生什么。随后根据比对结果给出不同的选项组合场景提示选项仍有变更需要同步“Sync now (recommended)” / “Archive without syncing”已处于同步状态“Archive now” / “Sync anyway” / “Cancel”若用户选择同步则执行/opsx:sync的逻辑——该同步是agent-driven智能合并而非程序化拼接例如只需给某个需求新增一个 scenario 时delta 中只写新 scenario 即可不必复制既有内容参见 sync 命令的“Intelligent Merging”原则。无论用户做何选择流程都会继续走向归档——同步与否只影响摘要中的 “Specs” 状态标注。3.5 第五步执行归档目录移动核心操作只有三条# 1. 确保归档目录存在 mkdir -p openspec/changes/archive # 2. 目标名当前日期变更名YYYY-MM-DD-change-name # 3. 目标已存在则报错不存在则移动 mv openspec/changes/name openspec/changes/archive/YYYY-MM-DD-name关键细节日期前缀目标目录名使用“当前日期”生成因此同一变更在 2026-05-12 与 2026-05-13 归档会得到不同目录名。仓库中现有的 16 个归档目录从2026-02-13-dialect-registration-mechanism到2026-05-12-fix-grouping-sets-comma完整印证了这一命名规则。冲突处理若openspec/changes/archive/YYYY-MM-DD-name/已存在例如同一天二次归档同一变更命令不会覆盖而是直接失败并给出错误输出提示的可选方案为重命名现有归档、若为重复件则删除、或换一个日期再归档对应第 4.4 节的错误模板。.openspec.yaml随目录一起迁移护栏中明确要求 “Preserve .openspec.yaml when moving to archive (it moves with the directory)”即归档元数据文件不丢失随整个变更目录一并进入归档区。3.6 第六步输出归档摘要归档完成后展示一份摘要必须包含五个要素变更名Change name所用 schemaSchema归档位置Archived to规格同步状态synced / sync skipped / no delta specs所有警告的说明未完成的制品/任务等。4. 四类标准输出模板命令文档为不同结局定义了四套输出模板实际使用时应按需选择。成功有 delta 规格且已同步## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** ✓ Synced to main specs All artifacts complete. All tasks complete.成功无 delta 规格## Archive Complete **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** No delta specs All artifacts complete. All tasks complete.成功带警告## Archive Complete (with warnings) **Change:** change-name **Schema:** schema-name **Archived to:** openspec/changes/archive/YYYY-MM-DD-name/ **Specs:** Sync skipped (user chose to skip) **Warnings:** - Archived with 2 incomplete artifacts - Archived with 3 incomplete tasks - Delta spec sync was skipped (user chose to skip) Review the archive if this was not intentional.失败归档目标已存在## Archive Failed **Change:** change-name **Target:** openspec/changes/archive/YYYY-MM-DD-name/ Target archive directory already exists. **Options:** 1. Rename the existing archive 2. Delete the existing archive if its a duplicate 3. Wait until a different date to archive这四类模板覆盖了“正常 / 无规格 / 有警告 / 冲突”的全部结局使归档结果对人和 Agent 都是可解析的摘要字段用加粗键值对呈现警告用列表呈现失败时附带可操作的选项清单。5. 护栏Guardrails逐条解读文档末尾列出的护栏是整个命令行为契约的浓缩值得逐条对照理解Always prompt for change selection if not provided未提供变更名时必须走选择流程第 3.1 节呼应“禁止猜测”原则。Use artifact graph (openspec status --json) for completion checking制品完成度以 CLI 返回的 JSON 制品图为唯一依据而不是靠读取目录内容猜。Dont block archive on warnings - just inform and confirm未完成的制品/任务只是警告不阻断归档但必须经用户确认。这条护栏让“80% 完成也想先归档留档”的场景成为可能同时保留用户否决权。Preserve.openspec.yamlwhen moving to archive归档是mv整目录元数据文件自然随迁不得在移动过程中单独删除或遗漏。Show clear summary of what happened无论成功失败都必须有摘要输出第 4 节模板。If sync is requested, use /opsx:sync approach (agent-driven)同步走智能合并不做文本级覆盖替换。If delta specs exist, always run the sync assessment and show the combined summary before prompting只要存在 delta 规格就必须先做同步评估并展示合并摘要然后才允许提示用户——评估先行、提示在后顺序不可颠倒。6. 用仓库中的真实归档产物验证流程openspec/changes/archive/下的历史变更可以当作 Archive 命令的“验收样例”命名规则如 2026-05-12-fix-grouping-sets-comma、2026-02-13-split-giant-sqlstatementparser-method、2026-03-06-optimize-odps-dialect等全部符合YYYY-MM-DD-change-name。目录内容以2026-05-12-fix-grouping-sets-comma为例归档目录内保留了proposal.md、tasks.md、verification-notes.md与 delta 规格specs/sql-parser-core/spec.md说明归档保留了变更的全部制品与 delta 规格即.openspec.yaml及制品“随目录迁移”的护栏效果。该变更的 proposal 与 tasks 还展示了变更与core模块源码SQLGroupingSetExpr、SQLSelectParser、SQLASTOutputVisitor及回归测试的对应关系验证了归档区是“可追溯的历史规格库”。与主规格的关系openspec/specs/README.md 中的 “How to Evolve” 明确描述了三步演进法在openspec/changes/change-name/创建变更 → 按openspec/changes/change-name/specs/capability/spec.md添加 delta 规格 → 通过同步工作流例如/opsx:sync把 delta 合入主规格。Archive 命令正处于这条演进链的末端变更落地 → delta 同步 → 目录归档。批量场景当需要一次性归档多个变更时仓库提供了 bulk-archive 命令它在单变更归档校验artifact 状态、tasks 统计、delta 规格提取之外增加了“同能力capabilitydelta 冲突检测与 agentic 消解”可视为 Archive 命令在批量场景下的扩展。7. 小结OPSX Archive 命令用六步选择变更 → 校验制品 → 校验任务 → 评估 delta 同步 → 移动目录 → 输出摘要加一套护栏把“归档”这一文件系统操作收敛成了一个对用户透明、对 Agent 可解析、对历史可追溯的确定性流程。它的几个设计取向值得借鉴选择权始终在用户禁止猜测变更名、警告只确认不阻断、状态检查依赖结构化输出--json而非文本猜测、同步与归档解耦不同步也能归档但必须先展示同步评估摘要、命名冲突显式失败日期前缀重名时给出三个可操作选项而不是覆盖。在 Druid 仓库中配合 openspec/config.yaml 的spec-driven配置、specs 能力基线与 tasks 模板Archive 命令与同族的 new、continue、ff、apply、sync、verify、explore、onboard 共同构成了一条完整的“规格驱动开发”闭环而openspec/changes/archive/下按日期排布的 16 个历史变更就是这条闭环最直观的产物证明。【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Druid OPSX 工作流详解：Archive 命令如何安全归档 OpenSpec 中已完成的变更

相关推荐

深入解析 Terraform AWS Provider 的 aws_elb 数据源：读取 Classic Load Balancer 配置

ants三种池型怎么选？Pool、PoolWithFunc与泛型PoolWithFuncGeneric实战对比指南

SeaTunnel Email Sink 连接器详解：将数据以附件形式发送邮件

更多资讯

装备体系作战试验分布式仿真系统：架构选型、模型集成与排错验证

高通Chromatix 7 ISP调优实战：从环境搭建到模块参数详解

汽车零部件物流系统集成与实时协同技术实践

多租户AI智能客服系统架构实战：从Dify到Spring AI的隔离与编排

AI大模型就业黄金期：岗位需求与转型指南

MATLAB实现一维信号分类的CNN实战指南

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？