[[[[Switch to English]]]]

迁移指南

本指南将帮助您从旧版 OpenSpec 工作流（v0.x）迁移到新的工件驱动工作流（OPSX）。

概述

新的 OpenSpec 体验（OPSX）带来了一些重要的变化：

1. 更简单的命令：用 /opsx:new 替代复杂的斜杠命令。
2. 工件驱动：工作流现在围绕创建和完成工件（提案、规格、设计、任务）展开。
3. 增量进度：不再是一次性生成所有内容，您可以逐步构建（/opsx:continue）。
4. 更清晰的配置：project.md 已被 config.yaml 替代。

主要变化

CLI 命令

旧版	新版 (OPSX)
/openspec:new	/opsx:new
/openspec:proposal	/opsx:continue (逐步) 或 /opsx:ff (一次性)
/openspec:design	/opsx:continue
/openspec:tasks	/opsx:continue
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

文件结构

• 配置：openspec/project.md → openspec/config.yaml
• 变更：变更为文件夹结构保持不变，但内容文件（工件）现在更加标准化。
• Skills：.claude/skills/openspec.md 已被新的 openspec-cli.md 和 openspec-slash.md 替代。

---

迁移步骤

1. 更新 CLI

首先，确保您拥有最新版本的 OpenSpec CLI：

npm install -g @fission-ai/openspec

检查版本（应为 1.0.0 或更高）：

openspec --version

2. 初始化 OPSX

在您的项目根目录下运行初始化命令：

openspec init --force

这将：

• 创建新的 openspec/config.yaml
• 更新 AI 工具配置文件（例如 .claude/skills）
• 设置默认的 Schema (spec-driven)
• 您的现有 specs/ 和 changes/ 文件夹将保持安全。

3. 迁移配置

如果您在 openspec/project.md 中有自定义上下文，请将其移至 openspec/config.yaml。

旧版 (project.md):

# Project Context
We are building a React Native app...

# Conventions
- Use functional components
- Use TypeScript

新版 (config.yaml):

project:
  name: my-app
  context: |
    We are building a React Native app...
    
    Conventions:
    - Use functional components
    - Use TypeScript

完成后，您可以删除 openspec/project.md。

4. 继续现有变更

您可以使用新命令继续处理旧工作流中创建的变更。

如果处于规划阶段： 运行 /opsx:status 查看 OpenSpec 对该变更的看法。它可能会建议运行 /opsx:continue 来生成任何缺失的工件。

如果处于实施阶段： 运行 /opsx:apply 像往常一样继续处理任务。任务列表格式是兼容的。

如果准备归档： 运行 /opsx:verify 检查是否一切正常，然后运行 /opsx:archive。

5. 清理旧 Skill 文件

openspec init 应该会自动处理此步骤，但您可以手动检查并删除旧的 skill 文件以避免混淆：

• 删除 .claude/skills/openspec.md（如果存在）
• 确保存在 .claude/skills/openspec-cli.md 和 .claude/skills/openspec-slash.md

---

常见问题

我的自定义提示去哪了？

如果您自定义了工件生成的提示，您现在可以通过 Schemas 来管理它们。

1. 运行 openspec schema fork spec-driven my-workflow
2. 编辑 openspec/schemas/my-workflow/templates/ 中的模板
3. 在 config.yaml 中将 my-workflow 设置为默认 Schema

我还可以使用旧命令吗？

可以。旧的 /openspec: 命令仍然作为别名存在，以实现向后兼容性。但是，新功能（如 status、verify 和增量生成）仅通过 /opsx: 命令可用。

我必须转换之前的完成的变更吗？

不用。已归档的变更 (openspec/changes/archive/) 只是历史记录。您不需要为了使用新工作流而迁移它们。

---

故障排除

错误：command not found: opsx

• 确保您已运行 openspec init 来生成新的 skill 文件。
• 重启您的 AI 助手（重新加载窗口或重启进程）以获取新 skills。

错误：Schema not found

• 检查 config.yaml 中的 default_schema。它通常应该也是 spec-driven。
• 如果您使用的是自定义 Schema，请确保它存在于 openspec/schemas/ 中。

变更看起来“卡住”了

• 运行 openspec status --change <name> 查看原因。
• 如果工件丢失（例如 design.md），运行 /opsx:continue 来创建它。