Chapter 2：OpenSpec 快速上手

Chapter 2：OpenSpec 快速上手

学习目标

1. 掌握 OpenSpec 的安装和环境配置
2. 理解 OpenSpec 的目录结构
3. 熟练使用init、validate、view等核心命令
4. 能够初始化一个 OpenSpec 项目

概念讲解（Why）

为什么需要 OpenSpec CLI

在上一章中，我们理解了 SDD 的核心理念：让规范成为项目的单一事实来源。但理念需要工具支撑才能落地。OpenSpec CLI（命令行工具）就是这样一个将 SDD 理念工程化的工具。

OpenSpec CLI 提供了以下核心能力：

• 项目初始化：快速搭建符合 SDD 规范的目录结构
• 规范验证：确保规范文件的格式正确、可解析
• 变更追踪：管理规范的版本和变更历史
• 工作流驱动：通过 DAG 引擎协调 proposal→specs→design→tasks 的开发流程

环境要求

OpenSpec 基于 Node.js 开发，使用 npm 进行包管理。在安装之前，需要确保环境满足以下要求：

• Node.js：20.19.0 或更高版本
• npm：随 Node.js 一同安装
• 操作系统：macOS、Linux、Windows 均支持

原理分析（How）

安装机制

OpenSpec 通过 npm 全局安装，安装后会在系统中注册openspec命令。其核心包名为@fission-ai/openspec。

npminstall-g@fission-ai/openspec

安装过程会自动处理依赖关系，包括 Commander.js（命令行框架）、chalk（终端着色）、ora（加载动画）等工具库。

命令解析架构

OpenSpec CLI 采用 Commander.js 框架进行命令解析和路由。其内部架构如下：

┌─────────────────────────────────────────────────────────────┐ │ CLI Layer (Commander.js) │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ init │ │validate │ │ view │ │ list │ ... │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ └───────┼────────────┼────────────┼────────────┼──────────────┘ │ │ │ │ └────────────┴────────────┼────────────┘ │ ┌─────────────▼─────────────┐ │ Command Layer │ │ (命令执行器) │ └─────────────┬─────────────┘ │ ┌─────────────▼─────────────┐ │ Core Layer │ │ (Artifact Graph) │ └───────────────────────────┘

工作目录结构

OpenSpec 对项目结构有明确的约定。一个标准的 OpenSpec 项目包含以下目录：

project/ ├── openspec/ # OpenSpec 根目录 │ ├── project.md # 项目级规范 │ ├── specs/ # 功能规范目录 │ │ └── <domain>/ # 按领域组织 │ │ └── spec.md # 该领域的规范文件 │ ├─