OpenSpec 增量规范同步（sync）工作流实战：以 imewlconverter 仓库的 Agent 驱动规范合并为例

桌面应用CLI开发工具【免费下载链接】imewlconverter”深蓝词库转换“ 一款开源免费的输入法词库转换程序项目地址https://gitcode.com/gh_mirrors/im/imewlconverter点击查看免费下载本指南围绕仓库中 .claude/commands/opsx/sync.md 定义的OPSX: 同步命令系统讲解 OpenSpec 工作流中将变更change内的增量规范同步到主规范这一核心环节。你将掌握增量规范四类变更新增/修改/移除/重命名需求的解析方法、智能合并策略、幂等操作要点以及如何在 AgentClaude/CodeBuddy环境中执行/opsx:sync并正确输出同步摘要。文末以仓库内真实归档变更refactor-cmd-args-format为案例对照增量规范与同步后的主规范直观还原一次完整的 sync 操作。一、sync 命令在 OpenSpec 工作流中的定位OpenSpec 是一种规范驱动spec-driven的变更管理方法本仓库通过 openspec/config.yaml 声明schema: spec-driven并在 openspec/project.md 中维护项目上下文技术栈、约定、领域知识。其核心模型为主规范canonical specs位于 openspec/specs/ 下是某个 capability 当前事实标准的唯一来源例如 cmd-args-parsing/spec.md。变更changes位于openspec/changes/name/下包含proposal.md、design.md、tasks.md及增量规范specs/capability/spec.md。本仓库归档区 openspec/changes/archive/ 保留了多个已完成变更如2026-01-31-refactor-cmd-args-format、2026-05-12-export-scel等。sync同步命令的作用是在变更尚未归档之前将其增量规范中描述的需求变更合并回主规范。它与apply应用实现、archive归档等命令共同构成完整生命周期变更提出 → 规范同步 → 实现 → 验证 → 归档。本仓库在 .claude/commands/opsx/ 和 .codebuddy/commands/opsx/ 下均提供了全套命令的 Agent 指令文件其中 .claude/skills/openspec-sync-specs/SKILL.md 是配套的 Claude 技能Skill声明二者步骤完全一致可对照阅读。二、命令格式与输入约定在 Claude Code 或 CodeBuddy 中通过斜杠命令触发/opsx:sync [change-name]显式指定变更如/opsx:sync add-auth直接锁定目标变更省略变更名Agent 会先尝试从对话上下文推断若推断模糊或不明确必须运行openspec-cn list --json列出可用变更并使用 AskUserQuestion 工具让用户选择。该命令的元数据定义见 .claude/commands/opsx/sync.md 的文件头name: OPSX: 同步、description: 将变更中的增量规范同步到主规范、category: 工作流、tags: [workflow, specs, experimental]。硬性约束不要猜测或自动选择变更始终让用户选择这是一个Agent 驱动操作——Agent 读取增量规范后直接编辑主规范文件而非机械替换因此允许智能合并。三、增量规范的结构四类需求变更执行 sync 前Agent 需要先在openspec/changes/name/specs/*/spec.md下定位增量规范文件。每个增量规范按 capability 组织内部只包含对主规范的差异delta可能出现的段落为段落语义对主规范的动作## 新增需求要添加的新需求主规范不存在则添加已存在则更新视为隐式 MODIFIED## 修改需求对现有需求的更改在主规范中定位并应用更改加场景、改描述等## 移除需求要移除的需求删除整个需求块## 重命名需求需求改名从/到格式找到 FROM 需求重命名为 TO若目标变更没有增量规范specs/目录为空Agent 应通知用户并停止操作。增量规范的标准 Markdown 格式参考以下格式模板来自命令文档是编写增量规范即 sync 的输入的权威参考## 新增需求 ### 需求 新功能 系统 应当 实现新的能力。 #### 场景 基本场景 - **当** 用户执行 X - **那么** 系统执行 Y ## 修改需求 ### 需求 现有功能 #### 场景 需要新增的场景 - **当** 用户执行 A - **那么** 系统执行 B ## 移除需求 ### 需求 已废弃功能 ## 重命名需求 - 从 ### 需求 Old Name - 到 ### 需求 New Name注意需求描述使用系统 应当/必须 …的规范句式场景使用当… /那么…的 Given-When-Then 风格这是本仓库主规范统一遵循的书写惯例可参考 openspec/specs/cmd-args-parsing/spec.md 中#### 场景使用长选项指定输入格式等条目确认。四、sync 五步执行流程步骤 1确认变更未指定时运行openspec-cn list --json获取可用变更清单仅向用户展示具有增量规范specs/目录下存在内容的变更并通过 AskUserQuestion 让用户点选。步骤 2查找增量规范定位openspec/changes/name/specs/*/spec.md。若未找到增量规范通知用户并停止防止把不存在的规范同步进主规范。步骤 3逐 capability 应用更改对每个存在增量规范的 capability阅读增量规范理解预期变更阅读主规范openspec/specs/ /spec.md可能尚不存在首次同步时需新建智能应用变更新增需求主规范不存在则直接添加已存在则更新以匹配隐式 MODIFIED修改需求定位主规范中的需求后应用更改可只添加新场景而不复制现有场景、修改现有场景或改写需求描述保留增量中未提及的场景与内容移除需求删除主规范中整个需求块重命名需求找到 FROM 需求重命名为 TO新建主规范若该 capability 在主规范中尚不存在创建openspec/specs/capability/spec.md先写目的Purpose部分可简短并标记为待定再写需求部分并放入新增需求。步骤 4显示同步摘要应用完所有更改后按成功时的输出模板汇报更新了哪些 capability、分别做了什么类型的变更添加/修改/移除/重命名需求。步骤 5保持变更活动同步完成后变更仍保持活动状态只有在实现完成后才归档——这是与archive命令的关键分工。五、关键原则智能合并Smart Mergesync 与程序化合并如git merge式整体替换的本质区别在于 Agent 可以执行部分更新增量规范代表的是意图intent而不是整体替换例如只为某需求新增一个场景只需在## 修改需求下写入该场景主规范中既有的其他场景会被保留合并时使用 Agent 的判断力合理取舍避免重复内容。这种设计使得主规范始终是事实收敛的单一来源同时增量规范保持最小差异便于 Review。六、成功时的输出模板同步成功后Agent 应输出如下格式的摘要模板原文## 规范已同步change-name 已更新主规范 **capability-1** - 添加需求新功能 - 修改需求现有功能添加了 1 个场景 **capability-2** - 创建了新规范文件 - 添加需求另一个功能 主规范现已更新。变更保持活动状态 - 在实现完成后归档。七、护栏Guardrails与幂等性命令文档明确列出的操作护栏在进行更改之前阅读增量规范和主规范保留增量中未提及的现有内容防止误删如果不清楚询问澄清而不是猜测边做边显示正在更改的内容透明可审计操作应当是幂等的——连续运行两次应得到相同结果。幂等性意味着重复执行/opsx:sync name不会产生重复需求或重复场景这在增量规范可能被多次 Review 时尤为重要。八、实战对照refactor-cmd-args-format 的 sync 产物本仓库提供了一个完整的真实案例可以精确还原 sync 的输出效果。变更侧sync 的输入2026-01-31-refactor-cmd-args-format/specs/cmd-args-parsing/spec.md 是增量规范文件头标明**变更**: refactor-cmd-args-format正文以## 新增需求开头定义了 GNU 长选项、POSIX 短选项、位置参数、帮助信息、参数完整性/有效性验证、完整选项集合--input-format/-i、--output-format/-o、--output/-O、--code-file/-c、--filter/-f、--custom-format/-F、--rank-generator/-r、--multi-code/-m、--code-type/-t、--target-os、--ld2-encoding、批量输出模式、旧格式禁用、错误信息规范、多选项组合、使用示例等十余项需求同时通过## 移除需求声明移除冒号分隔的参数格式。主规范侧sync 的输出openspec/specs/cmd-args-parsing/spec.md 即同步后的主规范。对比可见增量规范中的所有新增需求条目均被完整并入主规范且没有被复制进修改/移除段落——这正是智能合并的体现。其目的部分保留了归档变更生成的占位说明待定 - 由归档变更 refactor-cmd-args-format 创建。归档后请更新目的。印证了 sync 步骤 3-d 中新建主规范时目的可简短标记为待定的约定。实现侧佐证该变更最终落实到源码中。入口 src/ImeWlConverterCmd/Program.cs 使用System.CommandLine库rootCommand.Invoke(args)并在入口处实现了旧格式检测凡匹配-i:、-o:、-c:、-f:、-ft:、-r:、-ct:、-os:、-mc:、-ld2:前缀的参数会输出红色错误提示、新旧格式对照表并引导查看迁移指南 docs/MIGRATION.md对应增量规范中检测到旧格式参数场景。选项与参数的定义集中在 src/ImeWlConverterCmd/CommandBuilder.cs例如--input-format/-i、--output-format/-o、--output/-O、--filter/-f含len:、rank:、rm:eng、rm:num、rm:space、rm:pun等过滤子语法、--custom-format/-F、--code-type/-t、--code-file/-c、--multi-code/-m、--list-formats等均可与规范中的完整选项集合一一对应形成增量规范 → 主规范 → 源码实现的完整证据链。九、配套资源与扩展阅读命令本体.claude/commands/opsx/sync.mdClaude 版、.codebuddy/commands/opsx/sync.mdCodeBuddy 版文件头多一个argument-hint: [command arguments]字段配套技能.claude/skills/openspec-sync-specs/SKILL.md声明了name: openspec-sync-specs、license: MIT、compatibility: 需要 openspec CLI内容与命令文档一致适合作为 Agent 技能加载工作流配置openspec/config.yamlschema: spec-driven与项目上下文、openspec/project.md项目目的、技术栈、Git 工作流、版本号管理约定同族命令apply、archive、bulk-archive、continue、explore、ff、new、onboard、verify 均位于 .claude/commands/opsx/与 sync 共同构成完整 OpenSpec 生命周期迁移指南docs/MIGRATION.md 记录了本仓库从旧参数格式到 GNU 风格命令行格式的迁移说明是 sync 后实现变更的配套文档。通过上述步骤你可以在任意采用 OpenSpec 规范驱动流程的仓库中安全、幂等地将变更增量同步回主规范保持规范先行、实现跟进、变更可归档的良性迭代节奏。赞分享桌面应用CLI开发工具【免费下载链接】imewlconverter”深蓝词库转换“ 一款开源免费的输入法词库转换程序项目地址https://gitcode.com/gh_mirrors/im/imewlconverter点击查看免费下载相关推荐深蓝词库转换 OpenSpec 工作流增量规范同步openspec-sync-specs技能全解析深蓝词库转换 OpenSpec 工作流增量规范同步openspec sync specs技能全解析 导读 本文面向在 深蓝词库转换IME WL Conv桌面应用CLI开发工具用 OpenSpec 工作流驱动变更落地imewlconverter 仓库 openspec-apply-change 技能实战解析用 OpenSpec 工作流驱动变更落地imewlconverter 仓库 openspec apply change 技能实战解析 导读 本文围绕深蓝词库转桌面应用CLI开发工具druid 项目 OpenSpec 实践Delta Spec 智能同步到主规范的 Agent 工作流druid 项目 OpenSpec 实践Delta Spec 智能同步到主规范的 Agent 工作流 导读 本文基于 openspec sync specs数据库后端上一篇BAT_interviews10个高效准备BAT面试的黄金技巧下一篇CANN/ops-transformer quant_lightning_indexer_v2算子测试框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考