深蓝词库转换 OPSX 变更工作流实战：`/opsx:new` 命令完整解析与落地指南

• 桌面应用
• CLI
• 开发工具

导读

本文以深蓝词库转换（IME WL Converter）仓库中.codebuddy/commands/opsx/new.md为骨架，系统讲解如何通过 OPSX（实验性产出物工作流）的/opsx:new命令，将"一个想法或 Bug 修复需求"转化为结构化的 OpenSpec 变更。读完本文，你将掌握：变更命名规范、工作流 Schema 的选择规则、openspec-cn系列 CLI 命令的完整调用链、产出物状态机的运转方式，以及如何借助仓库内真实归档变更（如命令行参数重构）理解产出物如何一步步落地为可运行的代码。

OPSX 在深蓝词库转换项目中的定位

深蓝词库转换是一款跨平台的输入法词库转换工具，支持 50+ 种输入法格式（搜狗、QQ 拼音、Rime、微软拼音等），同时提供 GUI 与命令行两种形态。面对如此复杂的格式生态，任何新功能（例如新增一种词库格式）都会牵动 核心转换库、命令行入口 与 集成测试 等多个模块。

为此，仓库引入了 OpenSpec 规格化开发体系，并在.codebuddy/commands/opsx/目录下注册了 10 个 Agent 命令（new、continue、apply、archive、explore、ff、sync、verify等）与对应的 skills 技能定义。这套工作流的目标是：在动手写代码之前，先把"为什么改、改什么、怎么设计、拆成哪些任务"沉淀成可审查、可追溯的产出物（artifact），避免 AI 与人类开发者协作时凭感觉编码。

命令定义与输入约定

/opsx:new的命令定义位于.codebuddy/commands/opsx/new.md，其 Frontmatter 声明如下：

--- name: OPSX: 新建 description: "使用实验性的产出物工作流 (OPSX) 启动新变更" argument-hint: "[command arguments] ---

它接收的输入是/opsx:new之后的所有参数，可以是：

• 变更名称（必须为 kebab-case，即小写字母与连字符，例如add-user-auth）；
• 或用户对想要构建内容的自然语言描述，例如"我想让命令行支持把词库导出为 JSON 格式"。

变更命名规范：kebab-case

无论用户给出哪种输入，最终都必须归一化为一个 kebab-case 变更名称。这是整个工作流的第一步约束，也是后续所有openspec-cn命令的参数基础：

护栏明确要求：如果不了解用户想要构建什么，绝不能继续；如果名称不是合法的 kebab-case，必须请求用户提供有效名称。这保证了openspec/changes/<name>/目录名的稳定与可排序性。

六步工作流详解

/opsx:new的核心是一个严格分步的引导流程，其目的是只完成"变更脚手架搭建与第一个产出物的指令获取"，而绝不直接产出内容。

步骤 1：如果没有输入，询问用户想构建什么

当用户只敲了/opsx:new而没有附带参数时，Agent 必须使用AskUserQuestion 工具（开放式、无预设选项）询问：

"您想要处理什么变更？请描述您想要构建或修复的内容。"

随后根据描述推导 kebab-case 名称。这一步骤的意义在于：变更的方向必须由用户确认，避免 Agent 擅自臆测需求。

步骤 2：确定工作流 Schema

除非用户明确要求，否则使用默认 Schema（即省略--schema参数）。仅在两种情况下切换到其他 Schema：

• 用户提到了特定 Schema 名称→ 使用openspec-cn new change "<name>" --schema <name>；
• 用户说"显示工作流/有哪些工作流" → 运行openspec-cn schemas --json让用户选择。

在深蓝词库转换仓库中，默认 Schema 由 openspec/config.yaml 的第 1 行显式声明为schema: spec-driven。这意味着默认情况下，一次变更会按proposal（提案）→ specs（规格说明）→ design（设计）→ tasks（任务清单）的顺序产出 4 类产出物——这与仓库归档区中2026-01-31-refactor-cmd-args-format变更的目录结构完全吻合（详见后文"真实案例"）。

步骤 3：创建变更目录（脚手架）

执行创建命令：

openspec-cn new change "<name>"

仅在用户请求特定工作流时追加--schema <name>。该命令会在openspec/changes/<name>/下使用所选 Schema 生成一个脚手架变更。仓库中现存的实际产物位于 openspec/changes/archive/，每个归档变更都遵循2026-01-31-<变更主题>/的命名（日期前缀 + kebab-case 主题），内部包含proposal.md、design.md、tasks.md与可选的specs/子目录。

步骤 4：显示产出物状态

openspec-cn status --change "<name>"

该命令会列出当前变更中哪些产出物需要创建、哪些已就绪（即依赖项已满足）。产出物之间存在依赖关系：例如在spec-driven工作流中，proposal未完成时，specs与design通常处于blocked（受阻）状态；只有前序产出物完成后，后续产出物才会变为ready。这也是"产出物驱动（Artifact-Driven）"名称的由来——每一步都被前一步解锁，而不是凭感觉乱序推进。

步骤 5：获取第一个产出物的指令

第一个产出物取决于所选 Schema。查看状态输出，找到第一个status: "ready"的产出物，然后执行：

openspec-cn instructions <first-artifact-id> --change "<name>"

该命令会输出创建第一个产出物所需的模板（template）与上下文（context）。以spec-driven为例，第一个产出物通常是proposal（提案），指令会给出其章节骨架：为什么（Why）、变更内容（What changes）、能力（Capabilities）、影响（Impact）。对照仓库中真实的 归档提案 可以看到，这些章节最终被完整填写：从"当前 CLI 使用-i:scel冒号分隔格式违背 Unix 哲学"的动机陈述，到参数对照表、能力清单（cmd-args-parsing）、乃至对 Program.cs / ConsoleRun.cs / 集成测试的逐项影响分析。

步骤 6：停止并等待用户指示

获取指令后，Agent 必须立即停止，不得擅自开始撰写产出物。这是本命令与/opsx:continue最核心的区别：new只负责"铺路"，产出物的实际撰写由用户确认后通过/opsx:continue逐个完成。

输出约定：向用户汇报什么

完成上述步骤后，Agent 需要向用户输出一份结构化总结，必须包含 5 个要素：

1. 变更名称和位置：如add-json-export，位于openspec/changes/add-json-export/；
2. 正在使用的 Schema/工作流及其产出物顺序：如spec-driven：proposal → specs → design → tasks；
3. 当前状态：如0/N 个产出物已完成；
4. 第一个产出物的模板：将步骤 5 获取的模板原样呈现给用户；
5. 交接提示："准备好创建第一个产出物了吗？运行/opsx:continue或描述此变更的内容，我将为您起草。"

这份输出既是给用户的进度汇报，也是 Agent 与用户之间的"契约"，确保双方对变更的起点、路径和下一步行动完全对齐。

护栏规则：不可逾越的边界

原文档定义了 4 条硬性护栏，理解它们对于正确使用该命令至关重要：

从产出物到代码：仓库中的真实落地案例

纸上得来终觉浅。仓库中 2026-01-31-refactor-cmd-args-format 是一次完整走完 OPSX 工作流的归档变更，其产出物链条如下：

• proposal.md：陈述动机（自定义-i:冒号格式与 GNU 风格不一致、难以集成 shell 工具链）、新旧参数完整对照表（-i:<format>→--input-format/-i <format>等 12 组）、能力清单与影响面分析；
• tasks.md：将实施拆分为 14 个阶段共 60+ 个可勾选任务，从"添加 System.CommandLine NuGet 依赖"到"文档更新""CI/CD 配置""回滚准备"，并附验收标准（如参数解析时间 < 10ms、发布包体积增加 < 300KB）；
• specs/ 目录：能力cmd-args-parsing的详细规格说明。

这些产出物最终变成了可运行的代码。例如 src/ImeWlConverterCmd/CommandBuilder.cs 中，System.CommandLine的RootCommand与各Option正是提案中参数表的直接实现：

var inputFormatOption = new Option<string>( aliases: new[] { "--input-format", "-i" }, description: "输入词库格式代码 (例如: scel, ggpy, qqpy, rime, bdpy)") { IsRequired = false }; var outputFormatOption = new Option<string>( aliases: new[] { "--output-format", "-o" }, description: "输出词库格式代码 (例如: ggpy, rime, self, qqpy)") { IsRequired = false }; var inputFilesArgument = new Argument<List<string>>( name: "input-files", description: "输入词库文件路径（支持多个文件和通配符）") { Arity = ArgumentArity.ZeroOrMore };

同时，README.md 中的命令行快速开始章节、docs/MIGRATION.md 的迁移指南，以及 tests/integration 下的测试用例，也都按照该变更的任务清单同步更新。这验证了 OPSX 工作流的闭环：proposal 定义"为什么" → tasks 定义"做什么" → 代码与测试落地"怎么做" → 归档沉淀为仓库资产。

与 OPSX 命令族的协同

/opsx:new只是工作流的入口，理解它需要放在命令族中看：

• /opsx:continue：承接new的成果，每次只创建一个产出物（严格遵循 schema 顺序，先读依赖产出物再写下一个），创建后显示进度（N/M 完成）与解锁的产出物；
• /opsx:apply：所有产出物就绪后，读取 proposal/specs/design/tasks 作为上下文，按任务清单逐个实现代码，并在 tasks.md 中勾选- [ ]→- [x]；
• /opsx:explore：进入"只思考不实施"的探索姿态，可自由调查代码库、绘制 ASCII 架构图，当想法成熟时再提议过渡到new或ff；
• /opsx:archive等：变更完成后归档到openspec/changes/archive/，形成本文所述的沉淀资产。

项目上下文：产出物创作的"宪法"

OPSX 产出物不是凭空撰写，而是受到 openspec/config.yaml 中context字段的约束。该文件声明了深蓝词库转换项目的技术栈（.NET 8.0 / C#、多目标框架）、项目结构（Core / Cmd / Win / Mac / CoreTest 五子项目）、编码方案知识（拼音、五笔 86/98/新世纪、郑码、仓颉、二笔、注音）、词库格式知识（文本 / 二进制 / 系统格式）、兼容性约束（.NET Framework 4.6、旧参数向后兼容）等。当 Agent 撰写 proposal 或 design 时，这些上下文会作为约束注入指令输出（context与rules字段），但不会被复制进产出物文件本身。

小结与使用建议

/opsx:new表面上是 6 步引导流程，实质上是一种工程纪律：用强制性的状态机（blocked → ready → done）防止跳过思考直接编码，用 kebab-case 命名与 Schema 声明保证变更目录的规范，用"仅显示指令、绝不擅自撰写"的护栏保护用户的决策权。

对于在深蓝词库转换仓库中协作的开发者与 Agent，建议按以下节奏使用：

1. 想法模糊时先用/opsx:explore探索与澄清；
2. 方向明确后用/opsx:new创建变更并拿到第一个产出物模板；
3. 确认模板后用/opsx:continue逐个产出 proposal → specs → design → tasks；
4. 产出物齐备后用/opsx:apply实施代码，最后用/opsx:archive归档沉淀。

这样，无论是新增一种输入法格式，还是重构命令行参数解析，变更的每个决策点都有据可查、可回滚、可复用。

• 桌面应用
• CLI
• 开发工具