企业官网建设流程全解析

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

深蓝词库转换（IME WL Converter）仓库在openspec/目录下采用 OpenSpec 风格的规范驱动（spec-driven）开发工作流：每个变更（change）先在openspec/changes/<name>/下生成提案（proposal）、设计（design）、增量规格说明（specs）与任务清单（tasks），待实现完成后通过/opsx:archive命令归档。本文以 .claude/commands/opsx/archive.md 为骨架，完整讲解归档工作流的六个步骤、三条 CLI 探测命令、标准输出模板与防护措施，并结合仓库中已有的归档实例（如2026-05-12-export-scel）说明其在真实项目中的落地方案。读完本文，你将掌握如何安全地把一个已完成变更移动到openspec/changes/archive/，并正确处理未完成产出物、未完成任务与增量规格说明同步三大分支场景。

一、OPSX 归档工作流在项目中的定位

在深入步骤之前，先理解归档在 OPSX 生命周期中的位置。OPSX（产出物驱动的 OpenSpec 工作流）由一组 Claude Code slash command 组成，全部位于 .claude/commands/opsx/ 目录，形成一个完整闭环：

仓库中的工作区结构完全支撑这套流程：openspec/config.yaml 声明schema: spec-driven并提供项目上下文（技术栈、约定、领域知识）；openspec/project.md 描述项目目的与约束；openspec/changes/存放活动变更，openspec/specs/存放各能力（capability）的主规范（如 cmd-args-parsing/spec.md、llm-configuration-cli/spec.md），openspec/changes/archive/则是归档的最终归宿。

/opsx:archive的核心职责一句话概括：把实现完成的变更目录从openspec/changes/<name>移动到openspec/changes/archive/YYYY-MM-DD-<name>，并在移动前完成三类健康检查。移动而非删除，保证了历史规格说明可追溯——这一点对深蓝词库转换这类长期维护、格式众多（搜狗 scel、百度 bdict、QQ qpyd、Rime 等数十种）的项目尤为重要。

二、输入约定：变更名称从哪来

归档命令的输入格式为/opsx:archive <change-name>，变更名称采用 kebab-case（例如add-auth、export-scel）。规则如下：

• 如果参数中指定了变更名称，直接使用；
• 如果省略，先检查是否可以从对话上下文中推断出来；
• 如果模糊或不明确，必须提示用户选择可用变更，严禁猜测或自动选择。

"始终让用户选择"是贯穿整个工作流的第一原则，防止误归档正在开发的变更。

三、步骤一：列出活动变更并让用户选择

当变更名称缺失时，运行：

openspec-cn list --json

该命令返回所有活动（未归档）变更的 JSON 列表。随后使用AskUserQuestion tool让用户选择，选择面板中应：

• 仅显示活动变更（已归档的变更不出现）；
• 如果可用，包含每个变更使用的 Schema（从产出物图解析）。

四、步骤二：检查产出物完成状态

选定变更后，运行状态探测命令：

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

解析返回的 JSON，重点关注两个字段：

• schemaName：当前变更使用的工作流；
• artifacts：产出物列表及其状态（done或其他）。

从源码结构看，openspec-cn status输出的正是产出物图（artifact graph）的完成情况，这与/opsx:new中"显示哪些产出物需要创建、哪些已就绪"的状态模型同源。归档前读取该图，本质是在做一次"规格说明层面"的收尾确认。

分支处理：如果存在任何产出物状态不是done：

1. 显示列出所有未完成产出物的警告；
2. 提示用户确认是否继续归档；
3. 用户确认后继续，否则中止。

关键原则：警告不阻断归档，只负责告知与确认。

五、步骤三：检查任务完成状态

产出物检查之外，还需阅读任务文件（通常是openspec/changes/<name>/tasks.md），统计未完成任务：

• 统计标记为- [ ]（未完成）与- [x]（已完成）的任务数量；
• 如果发现未完成的任务，显示包含未完成任务数量的警告，并提示用户确认是否继续；
• 如果不存在任务文件，直接继续，无需任务相关警告。

仓库中已有归档实例印证了任务文件的真实格式。以 openspec/changes/archive/2026-05-12-export-scel/tasks.md 为例，该变更（scel 格式导出能力）的任务清单按"接口与基础架构 / 核心导出实现 / 拼音处理 / 测试"四个分组组织，所有条目均标记为- [x]完成状态，例如"1.1 新增IBinaryWordLibraryExport接口""2.4 实现文件头写入：magic number（8字节）、保留区域（填充至 0x011F）""4.3 编写往返测试：导出为 scel 后重新导入，验证词条数据一致性"。任务粒度如此之细，正是为了归档时能一目了然地核对完成度——对应实现的 SougouScelExporter.cs 与SougouScelImporter.cs均在仓库src/ImeWlConverter.Formats/SougouScel/下可查证。

六、步骤四：评估增量规格说明同步状态

这是归档前最具技术含量的一步，处理变更期间产生的增量规格说明（delta specs）。

6.1 检查增量规格说明是否存在

在openspec/changes/<name>/specs/下检查是否存在增量规格说明文件（每个 capability 一个spec.md）：

• 如果不存在，不提示同步，直接继续归档；
• 如果存在，进入同步评估流程。

6.2 与主规范逐条比对

将每个增量规格说明与其在openspec/specs/<capability>/spec.md的相应主规范进行比较，确定将应用哪些更改（添加、修改、删除、重命名），并在提示用户之前显示合并摘要。

仓库中两个目录的对应关系清晰可验证：

• 增量侧：openspec/changes/archive/2026-02-03-replace-search-word-freq-with-llm/specs/ 下含llm-configuration-cli/、llm-configuration-ui/、llm-word-rank-generation/、word-rank-management/四个能力；
• 主规范侧：openspec/specs/ 下存在同名四个能力目录（llm-configuration-cli、llm-configuration-ui、llm-word-rank-generation、word-rank-management），一一对应，正是增量同步到主规范后的结果。

6.3 提示选项与分支

根据比对结果，提示选项不同：

• 如果需要更改："立即同步（推荐）"、"不同步直接归档"；
• 如果已同步："立即归档"、"仍要同步"、"取消"。

若用户选择同步，则执行/opsx:sync逻辑（对应 .claude/commands/opsx/sync.md），即读取增量规格说明并按"新增需求 / 修改需求 / 移除需求 / 重命名需求"四类操作智能合并进主规范。无论同步选择如何，都继续执行归档——同步与否只影响摘要中的状态标注。

七、步骤五：执行归档

同步评估结束后进入实际归档操作，分三步：

1. 确保归档目录存在：

mkdir -p openspec/changes/archive

2. 用当前日期生成目标名称：YYYY-MM-DD-<change-name>（例如2026-05-12-export-scel）。

3. 检查目标是否存在后移动：

mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

• 如果目标已存在：失败并报错，建议重命名现有归档或使用不同日期；
• 如果不存在：执行移动。

一个容易忽略但重要的细节：移动到归档时保留.openspec.yaml，它与目录一起移动，确保归档后的变更仍保留 Schema 元信息，随时可以回溯其工作流类型。

仓库中 4 个已归档实例（2026-01-31-refactor-cmd-args-format、2026-01-31-refactor-version-automation、2026-02-03-replace-search-word-freq-with-llm、2026-05-12-export-scel）的命名全部遵循YYYY-MM-DD-<name>规范，且每个实例都完整保留了proposal.md、design.md、tasks.md及specs/子目录，印证了"整目录移动、信息零丢失"的执行方式。

八、步骤六：显示归档摘要

归档完成后输出结构化摘要，包含四类信息：变更名称、使用的 Schema、归档位置、规格说明同步状态，以及任何警告的注释（未完成的产出物/任务）。

成功时的输出模板：

## 归档完成 **变更：** <change-name> **Schema：** <schema-name> **归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/ **规范：** ✓ 已同步到主规范 所有产出物已完成。所有任务已完成。

成功时（无增量规范）的输出模板：

## 归档完成 **变更：** <change-name> **Schema：** <schema-name> **归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/ **规范：** 无增量规范 所有产出物已完成。所有任务已完成。

带警告的成功输出模板：

## 归档完成（带警告） **变更：** <change-name> **Schema：** <schema-name> **归档至：** openspec/changes/archive/YYYY-MM-DD-<name>/ **规格说明：** 跳过同步（用户选择跳过） **警告：** - 带有 2 个未完成产出物的归档 - 带有 3 个未完成任务的归档 - 增量规格说明同步已跳过（用户选择跳过） 如果这不是故意的，请检查归档。

错误时的输出模板（目标已存在）：

## 归档失败 **变更：** <change-name> **目标：** openspec/changes/archive/YYYY-MM-DD-<name>/ 目标归档目录已存在。 **选项：** 1. 重命名现有归档 2. 如果是重复的，删除现有归档 3. 等待不同的日期再归档

九、防护措施清单

原文档末尾给出了六条核心防护措施，是整个工作流的纪律红线：

1. 如果未提供变更，始终提示选择——严禁自动猜测；
2. 使用产出物图（openspec status --json）进行完成度检查——以机器可读的 JSON 为准，而非肉眼判断；
3. 不要在警告时阻止归档——只需告知并确认，尊重用户对未完成项的处理决定；
4. 移动到归档时保留.openspec.yaml——元信息随目录一起移动；
5. 显示清晰的操作摘要——让用户对归档结果一目了然；
6. 如果请求同步，使用/opsx:sync方法（代理驱动）；如果存在增量规格说明，始终运行同步评估，并在提示前显示综合摘要。

十、与相邻工作流的协作关系

归档不是孤立的终点操作，它与 OPSX 家族其他命令协同：

• 上游：变更由/opsx:new创建（见 new.md），在openspec/changes/<name>/下用openspec-cn new change "<name>"搭建脚手架，产出物依 Schema 逐步生成；
• 同步：归档中的"增量规范同步"步骤直接复用/opsx:sync（见 sync.md）的代理驱动智能合并逻辑——读取增量规范、对比主规范、按新增/修改/移除/重命名四类需求操作应用变更，操作应当幂等；
• 批量场景：当有多个变更同时完成时，可用/opsx:bulk-archive（见 bulk-archive.md）一次归档多个，其通过构建capability -> [涉及它的变更]映射检测规格说明冲突，并以"检查代码库寻找实现证据"的方式代理式解决冲突；单个变更的归档命令（mkdir -p+mv）与命名规范（YYYY-MM-DD-<name>）在批量场景中完全复用。

十一、写在最后

归档的本质是状态迁移而非数据删除：把变更从"活动区"迁入"历史区"，同时保留全部产出物与元信息。对深蓝词库转换这样同时维护 WinForm GUI、Avalonia macOS 客户端、CLI 命令行工具与大量格式插件的仓库而言，OPSX 归档保证了每一次功能演进（如 scel 导出、LLM 词频生成）都留有完整的规格说明审计轨迹，openspec/changes/archive/下的每个YYYY-MM-DD-<name>目录就是一部可回放的变更史。如需深入，可继续阅读 archive 命令定义、对应的技能实现 openspec-archive-change/SKILL.md，以及 openspec/config.yaml 中声明的完整项目上下文。

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