0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
canonical-entropycanonical-entropy修改常量名，规范化checkstyle
3ea27ca5创建于 1月6日历史提交

Nop Platform - OpenSpec 快速开始指南

本指南帮助你在 5 分钟内开始使用 OpenSpec 进行规范驱动的开发。

前置条件

  • ✅ Node.js >= 20.19.0（运行 node --version 检查）
  • ✅ OpenCode AI 编码助手（推荐最新版本）
  • ✅ Git 已安装并配置

30秒快速检查

# 检查 OpenSpec 是否已安装
openspec --version

# 应该看到：0.17.2（或其他版本号）

# 查看活动变更
openspec list

# 应该看到示例变更：add-2fa

如果命令不存在，请先运行：

npm install -g @fission-ai/openspec@latest

场景1：创建第一个变更（推荐新手）

步骤1：告诉 AI 你想要做什么

在 OpenCode 中输入：

请创建一个 OpenSpec 变更提案，添加用户资料编辑功能

或者使用斜杠命令：

/openspec-proposal 添加用户资料编辑功能

步骤2：AI 会自动创建

AI 会：

  1. 阅读 openspec/project.md 了解项目上下文
  2. 检查是否已有相关规格
  3. 创建 openspec/changes/add-profile-edit/ 目录
  4. 生成 proposal.md（变更提案）
  5. 生成 tasks.md（任务清单）
  6. 生成 design.md（技术设计）
  7. 生成规格变更 specs/user/spec.md

步骤3：审查提案

# 查看创建的变更
openspec list

# 查看详细信息
openspec show add-profile-edit

AI 会提示你审查生成的文件：

  • proposal.md: 确认需求是否完整
  • tasks.md: 确认任务是否合理
  • design.md: 技术方案是否可行
  • specs/user/spec.md: 规格变更是否正确

步骤4：修改和优化

如果需要修改，告诉 AI：

请修改 proposal.md，添加头像上传功能

或者：

请在 tasks.md 中增加国际化支持的任务

步骤5：验证变更

openspec validate add-profile-edit --strict

修复任何验证错误。

步骤6：实施变更

请开始实施 add-profile-edit 变更

或者使用斜杠命令：

/openspec-apply add-profile-edit

AI 会按照 tasks.md 逐个完成任务。

步骤7：完成和归档

当所有任务完成后：

请归档 add-profile-edit 变更

或者使用斜杠命令：

/openspec-archive add-profile-edit

场景2：修改现有功能

步骤1：告诉 AI 你想修改什么

我想要修改用户登录流程，添加验证码功能

步骤2：AI 会自动识别

AI 会：

  1. 查找现有的认证规格 openspec/specs/auth/spec.md
  2. 创建 openspec/changes/add-captcha/ 目录
  3. 使用 MODIFIED 部分更新现有需求
  4. 添加新的需求

步骤3：审查和批准

审查生成的规格 Delta，确认：

  • MODIFIED 的部分是否正确反映了变更
  • ADDED 的部分是否完整
  • REMOVED 的部分（如有）是否合理

步骤4：实施和归档

与场景1相同。

场景3：查看示例学习

查看示例变更

我们已经为你创建了一个完整的示例：

# 查看所有变更
openspec list

# 查看示例变更详情
openspec show add-2fa

# 查看示例文件
cat openspec/changes/add-2fa/proposal.md
cat openspec/changes/add-2fa/tasks.md
cat openspec/changes/add-2fa/design.md
cat openspec/changes/add-2fa/specs/auth/spec.md

学习示例

这个示例展示了：

  • ✅ 如何编写详细的提案（purpose、motivation、proposed changes）
  • ✅ 如何分解任务（150+任务，12个主要部分）
  • ✅ 如何进行技术设计（架构、数据库、安全、性能）
  • ✅ 如何编写规格 Delta（ADDED、MODIFIED、REMOVED）
  • ✅ 如何处理非功能性需求
  • ✅ 如何考虑迁移和兼容性

常用命令速查

查看和搜索

# 查看所有活动变更
openspec list

# 查看所有规格
openspec list --specs

# 显示变更详情
openspec show <change-id>

# 显示规格详情
openspec show <spec-id> --type spec

验证

# 验证变更
openspec validate <change-id>

# 严格验证（推荐）
openspec validate <change-id> --strict

# 验证规格
openspec validate <spec-id> --type spec

归档

# 归档变更（交互式）
openspec archive <change-id>

# 归档变更（自动确认）
openspec archive <change-id> --yes

# 只归档不更新规格
openspec archive <change-id> --skip-specs --yes

其他

# 查看帮助
openspec --help

# 查看特定命令帮助
openspec validate --help

# 查看版本
openspec --version

# 更新 OpenSpec 配置
openspec update

OpenCode 斜杠命令

在 OpenCode 中，你可以使用以下斜杠命令：

创建提案

/openspec-proposal <功能描述>

示例：

/openspec-proposal 添加用户批量导入功能
/openspec-proposal 实现订单状态机
/openspec-proposal 优化搜索性能

应用变更

/openspec-apply <change-id>

示例：

/openspec-apply add-batch-import
/openspec-apply order-state-machine

归档变更

/openspec-archive <change-id>

示例：

/openspec-archive add-batch-import

自然语言指令

除了斜杠命令，你还可以使用自然语言：

# 创建提案
"请创建一个 OpenSpec 变更提案"
"帮我规划这个变更"
"我想添加一个新功能"

# 应用变更
"请实施这个变更"
"开始开发这个功能"
"按照 tasks.md 实施变更"

# 归档变更
"请归档这个变更"
"这个功能已经完成了"
"变更可以归档了"

规格（Spec）格式

基本结构

# <功能名称> Specification

## Purpose
描述这个规格的目的和范围

## Requirements
### Requirement: <需求名称>
系统 SHALL/MUST/MAY <需求描述>

#### Scenario: <场景名称>
- WHEN <前置条件>
- THEN <预期结果>

变更 Delta 格式

# Delta for <功能名称>

## ADDED Requirements
新增的需求...

## MODIFIED Requirements
修改的需求（完整文本）...

## REMOVED Requirements
移除的需求...

示例

# User Profile Specification

## Purpose
管理用户的基本信息和配置

## Requirements
### Requirement: 用户信息查询
系统 SHALL 支持查询用户的基本信息。

#### Scenario: 查询自己的信息
- WHEN 用户查询自己的信息
- THEN 系统返回用户名、邮箱、头像等基本信息
- AND 隐藏敏感信息如密码、手机号

### Requirement: 用户信息更新
系统 MUST 支持用户更新自己的信息。

#### Scenario: 更新用户名
- WHEN 用户更新用户名
- AND 用户名符合格式要求
- THEN 系统更新用户名
- AND 记录修改时间

#### Scenario: 更新失败
- WHEN 用户提交重复的用户名
- THEN 系统返回错误
- AND 提示用户名已存在

常见问题

Q: 如何确定使用哪个 change-id？

A: 使用 kebab-case，动词开头：

  • add-xxx: 添加功能
  • update-xxx: 修改功能
  • remove-xxx: 删除功能
  • refactor-xxx: 重构
  • fix-xxx: 修复 bug
  • optimize-xxx: 优化

示例：

  • add-batch-import
  • update-login-flow
  • remove-legacy-api
  • refactor-auth-module
  • fix-captcha-validation
  • optimize-search-query

Q: 什么时候需要创建变更提案？

A: 需要创建提案的情况：

  • ✅ 添加新功能
  • ✅ 重大变更（API、Schema）
  • ✅ 架构或模式变更
  • ✅ 性能优化（改变行为）
  • ✅ 安全模式更新

不需要提案的情况：

  • ❌ Bug 修复（恢复预期行为）
  • ❌ 拼写、格式、注释
  • ❌ 依赖更新（非破坏性）
  • ❌ 配置变更
  • ❌ 测试现有行为

Q: 如何确保规格质量？

A: 遵循以下原则：

  1. 每个需求使用 SHALL/MUST/MAY
  2. 每个需求至少包含一个 Scenario
  3. Scenario 使用 WHEN-THEN 格式
  4. 使用明确的术语，避免模糊
  5. 覆盖正常场景和异常场景

Q: AI 生成的规格不准确怎么办？

A: 几种解决方法：

  1. 直接修改生成的文件
  2. 告诉 AI 具体问题："请在 proposal.md 中添加xxx功能"
  3. 重新生成："请重新生成 proposal.md，修正xxx问题"
  4. 参考 openspec/specs/auth/spec.md 示例

Q: 如何处理多个相关的规格？

A: 使用统一的变更目录：

openspec/changes/add-user-management/
├── proposal.md
├── tasks.md
└── specs/
    ├── user/profile/spec.md
    ├── user/role/spec.md
    └── user/permission/spec.md

Q: 什么时候使用 design.md？

A: design.md 用于复杂的技术设计，包含：

  • 架构设计
  • 数据库设计
  • API 设计
  • 安全考虑
  • 性能优化
  • 依赖关系

简单的功能可以省略 design.md。

学习资源

快速参考

示例学习

  • 📁 2FA 变更示例
    • proposal.md: 完整的变更提案
    • tasks.md: 150+ 详细任务
    • design.md: 技术设计文档
    • specs/auth/spec.md: 规格变更

详细文档

外部资源

下一步

  1. ✅ 创建你的第一个变更

    /openspec-proposal 添加简单的待办事项列表

  2. ✅ 学习示例变更

    openspec show add-2fa

  3. ✅ 阅读项目上下文

    cat openspec/project.md

  4. ✅ 实践完整工作流

    • 创建提案
    • 审查和修改
    • 实施变更
    • 归档变更

  5. ✅ 应用到实际项目

    • 选择一个真实的开发任务
    • 创建变更提案
    • 按照工作流实施

获取帮助

本地帮助

openspec --help
openspec validate --help

项目帮助

  • 📖 查看 openspec/AGENTS.md 了解完整工作流
  • 📖 参考 openspec/specs/auth/spec.md 学习规格格式
  • 📖 查看示例 openspec/changes/add-2fa/ 学习最佳实践

社区支持

开始你的 OpenSpec 之旅吧！ 🚀

记住：先写规格，再写代码。