5.1 OpenSpec 安装与配置

环境要求

在开始安装 OpenSpec 之前，请确保你的系统满足以下要求：

必要条件

要求	最低版本	检查命令
Node.js	20.19.0	`node --version`
npm	8.0.0	`npm --version`

检查 Node.js 版本

bash

# 检查当前版本
node --version
# 输出示例: v20.19.0

# 如果版本过低，使用 nvm 升级
nvm install 20
nvm use 20

如果你没有安装 Node.js，推荐使用 nvm（Node Version Manager）进行安装：

bash

# 安装 nvm（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 20
nvm install 20
nvm use 20

安装 OpenSpec CLI

全局安装（推荐）

bash

# 使用 npm 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version
# 输出示例: 0.1.x

项目级安装（可选）

如果你希望在特定项目中锁定 OpenSpec 版本：

bash

# 在项目目录中安装为开发依赖
npm install --save-dev @fission-ai/openspec@latest

# 通过 npx 运行
npx openspec --version

安装故障排除

问题 1：权限错误

bash

# 如果遇到 EACCES 错误
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @fission-ai/openspec@latest

问题 2：网络问题

bash

# 使用淘宝镜像（中国大陆）
npm config set registry https://registry.npmmirror.com
npm install -g @fission-ai/openspec@latest

# 恢复官方源
npm config set registry https://registry.npmjs.org

问题 3：版本冲突

bash

# 清除 npm 缓存后重新安装
npm cache clean --force
npm install -g @fission-ai/openspec@latest

初始化项目

基本初始化

bash

# 进入项目目录
cd my-project

# 运行初始化命令
openspec init

初始化向导会询问你几个问题：

? Select AI tools to configure (use space to select, enter to confirm)
❯ ◯ Claude Code
  ◯ Cursor
  ◯ GitHub Copilot
  ◯ Windsurf
  ◯ Cline
  ◯ RooCode
  ◯ Other (AGENTS.md only)

初始化选项

bash

# 指定目录初始化
openspec init /path/to/project

# 非交互模式（使用默认配置）
openspec init --non-interactive

# 查看帮助
openspec init --help

初始化后的目录结构

my-project/
├── AGENTS.md                 # AI 助手指令（自动生成）
├── openspec/
│   ├── AGENTS.md             # 详细的 OpenSpec 工作流指令
│   ├── project.md            # 项目约定和上下文
│   ├── specs/                # 规格目录（已实现的功能）
│   │   └── .gitkeep
│   └── changes/              # 变更目录（提案中的功能）
│       └── archive/          # 已归档的变更
│           └── .gitkeep
└── .claude/                  # Claude Code 配置（如果选择）
    └── commands/
        └── openspec/
            ├── proposal.md
            ├── apply.md
            └── archive.md

理解生成的文件

1. 根目录 `AGENTS.md`

这是 AI 助手的入口点，包含指向 OpenSpec 工作流的引用：

markdown

<!-- OPENSPEC:START -->
# Project Instructions

This project uses OpenSpec for spec-driven development.

**AI Assistants**: Please read `openspec/AGENTS.md` for detailed workflow instructions.
<!-- OPENSPEC:END -->

2. `openspec/project.md`

用于定义项目级别的约定：

markdown

# Project Context

## Tech Stack
- Language: [Your language]
- Framework: [Your framework]
- Database: [Your database]

## Conventions
- [Your coding conventions]
- [Your naming conventions]

## Architecture
- [Your architecture patterns]

建议：初始化后，使用 AI 助手填充这个文件：

请帮我填充 openspec/project.md，分析我的项目并补充技术栈、约定和架构信息

3. `openspec/AGENTS.md`

详细的 AI 工作流指令，包括：

三阶段工作流（创建、实现、归档）
规格格式规范
CLI 命令参考
最佳实践

AI 工具配置详解

Claude Code 配置

选择 Claude Code 后，OpenSpec 会创建斜杠命令：

.claude/
└── commands/
    └── openspec/
        ├── proposal.md    # /openspec:proposal 命令
        ├── apply.md       # /openspec:apply 命令
        └── archive.md     # /openspec:archive 命令

使用方式：

bash

# 在 Claude Code 中
/openspec:proposal Add user authentication

# 或直接对话
创建一个 OpenSpec 提案，添加用户认证功能

Cursor 配置

选择 Cursor 后，OpenSpec 会创建：

.cursor/
└── prompts/
    └── openspec/
        ├── openspec-proposal.md
        ├── openspec-apply.md
        └── openspec-archive.md

使用方式：

bash

# 在 Cursor 中使用斜杠命令
/openspec-proposal Add user authentication

GitHub Copilot 配置

.github/
└── prompts/
    ├── openspec-proposal.md
    ├── openspec-apply.md
    └── openspec-archive.md

Windsurf 配置

.windsurf/
└── workflows/
    ├── openspec-proposal.md
    ├── openspec-apply.md
    └── openspec-archive.md

Cline 配置

.clinerules/
└── workflows/
    ├── openspec-proposal.md
    ├── openspec-apply.md
    └── openspec-archive.md

多工具配置

你可以同时为多个 AI 工具配置 OpenSpec：

bash

# 初始化时选择多个工具
openspec init
# 使用空格选择: Claude Code, Cursor, GitHub Copilot

这样团队成员可以使用不同的工具，但共享同一套规格。

更新 OpenSpec

升级 CLI

bash

# 检查当前版本
openspec --version

# 升级到最新版本
npm install -g @fission-ai/openspec@latest

# 验证升级
openspec --version

更新项目配置

当 OpenSpec 发布新版本时，你可能需要更新项目中的 AI 指令：

bash

# 更新 AI 工具配置和 AGENTS.md
openspec update

# 指定项目路径
openspec update /path/to/project

openspec update 会：

重新生成 AGENTS.md 文件
更新斜杠命令定义
保留你的自定义规格和变更

添加新的 AI 工具

如果团队开始使用新的 AI 工具：

bash

# 重新运行初始化，选择额外的工具
openspec init
# 选择新工具时，现有配置会被保留

配置验证

检查安装状态

bash

# 验证 CLI 可用
openspec --version

# 验证项目初始化
openspec list
# 应该输出: No active changes found.

# 验证规格列表
openspec list --specs
# 应该输出: No specifications found.

验证 AI 工具集成

Claude Code：

打开项目
输入 /openspec
应该看到命令补全建议

Cursor：

打开项目
按 Cmd+K（Mac）或 Ctrl+K（Windows/Linux）
输入 /openspec
应该看到命令选项

项目配置最佳实践

1. 填充 project.md

初始化后立即填充项目上下文：

markdown

# Project Context

## Overview
TaskFlow is a task management application built with React and Node.js.

## Tech Stack
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js 20 + Express + Prisma
- Database: PostgreSQL 15
- Auth: JWT + bcrypt
- Testing: Vitest + Playwright

## Conventions
### Code Style
- Use ESLint + Prettier for formatting
- Prefer functional components with hooks
- Use async/await over .then() chains

### Naming
- Components: PascalCase (e.g., TaskCard.tsx)
- Utilities: camelCase (e.g., formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE

### API Design
- RESTful endpoints under /api/v1/
- Use consistent error response format
- Include pagination for list endpoints

## Architecture
### Frontend
- Feature-based folder structure
- Shared components in src/components/common/
- State management: React Query for server state, Zustand for client state

### Backend
- Controller → Service → Repository pattern
- Middleware for auth and validation
- Separate route files per resource

2. 版本控制配置

将 OpenSpec 文件加入版本控制：

bash

# .gitignore 配置（通常不需要忽略任何 OpenSpec 文件）
# OpenSpec 文件应该被版本控制，以便团队协作

建议的提交策略：

bash

# 初始化后提交
git add openspec/ AGENTS.md .claude/ .cursor/
git commit -m "chore: initialize OpenSpec for spec-driven development"

# 每个变更提案单独提交
git add openspec/changes/add-user-auth/
git commit -m "spec: propose user authentication feature"

3. 团队协作配置

在团队项目中：

bash

# 确保所有成员运行 update
openspec update

# 在 README.md 中添加说明
## Development Workflow

This project uses OpenSpec for spec-driven development.

### Setup
1. Install OpenSpec: `npm install -g @fission-ai/openspec@latest`
2. Run `openspec update` to sync AI tool configurations

### Creating Features
1. Create a proposal: `/openspec:proposal Feature description`
2. Review and refine specs
3. Implement: `/openspec:apply change-name`
4. Archive: `openspec archive change-name --yes`

本章小结

本章介绍了 OpenSpec 的完整安装和配置流程：

环境检查：确保 Node.js >= 20.19.0
安装 CLI：npm install -g @fission-ai/openspec@latest
初始化项目：openspec init，选择 AI 工具
配置项目上下文：填充 openspec/project.md
保持更新：定期运行 openspec update

配置完成后，你就可以开始使用 OpenSpec 进行规格驱动开发了。下一章我们将深入学习 OpenSpec 的核心概念。

完整示例代码

以下是一个完整的 OpenSpec 安装和配置脚本，包含所有步骤和验证：

bash

#!/bin/bash
# OpenSpec 完整安装与配置脚本
# 用法: ./install-openspec.sh [project-path]

set -e

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# 日志函数
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# 检查命令是否存在
command_exists() {
    command -v "$1" &> /dev/null
}

# 版本比较函数
version_gte() {
    # 返回 0 如果 $1 >= $2
    [ "$(printf '%s\n' "$2" "$1" | sort -V | head -n1)" = "$2" ]
}

echo "======================================"
echo "  OpenSpec 安装与配置脚本"
echo "======================================"
echo ""

# 1. 检查 Node.js
log_info "检查 Node.js 环境..."

if ! command_exists node; then
    log_error "Node.js 未安装"
    echo "请安装 Node.js >= 20.19.0"
    echo "推荐使用 nvm: https://github.com/nvm-sh/nvm"
    exit 1
fi

NODE_VERSION=$(node --version | sed 's/v//')
REQUIRED_NODE="20.19.0"

if version_gte "$NODE_VERSION" "$REQUIRED_NODE"; then
    log_success "Node.js 版本: v$NODE_VERSION (满足要求)"
else
    log_error "Node.js 版本过低: v$NODE_VERSION (需要 >= v$REQUIRED_NODE)"
    echo "请升级 Node.js:"
    echo "  nvm install 20 && nvm use 20"
    exit 1
fi

# 2. 检查 npm
log_info "检查 npm..."
if command_exists npm; then
    NPM_VERSION=$(npm --version)
    log_success "npm 版本: $NPM_VERSION"
else
    log_error "npm 未找到"
    exit 1
fi

# 3. 安装或更新 OpenSpec
log_info "安装/更新 OpenSpec..."

if command_exists openspec; then
    CURRENT_VERSION=$(openspec --version 2>/dev/null || echo "unknown")
    log_info "当前 OpenSpec 版本: $CURRENT_VERSION"
    log_info "升级到最新版本..."
fi

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

OPENSPEC_VERSION=$(openspec --version)
log_success "OpenSpec 已安装: $OPENSPEC_VERSION"

# 4. 初始化项目
PROJECT_PATH="${1:-.}"

if [ "$PROJECT_PATH" != "." ]; then
    if [ ! -d "$PROJECT_PATH" ]; then
        log_info "创建项目目录: $PROJECT_PATH"
        mkdir -p "$PROJECT_PATH"
    fi
    cd "$PROJECT_PATH"
fi

PROJECT_PATH=$(pwd)
log_info "项目目录: $PROJECT_PATH"

# 检查是否已初始化
if [ -d "openspec" ]; then
    log_warn "OpenSpec 已存在，运行更新..."
    openspec update || true
else
    log_info "初始化 OpenSpec..."
    # 尝试非交互模式，如果失败则提示用户
    if ! openspec init --non-interactive 2>/dev/null; then
        log_info "请手动完成初始化..."
        openspec init
    fi
fi

# 5. 创建示例 project.md（如果为空）
PROJECT_MD="openspec/project.md"
if [ -f "$PROJECT_MD" ]; then
    # 检查文件是否只有默认内容
    if grep -q "^\[Your" "$PROJECT_MD" 2>/dev/null; then
        log_info "填充 project.md 示例内容..."
        cat > "$PROJECT_MD" << 'EOF'
# Project Context

## Overview
<!-- 项目简介 -->

## Tech Stack
- Language: TypeScript
- Runtime: Node.js 20
- Framework: Express
- Database: PostgreSQL
- ORM: Prisma

## Conventions

### Code Style
- Use ESLint + Prettier
- Prefer async/await
- Use descriptive variable names

### Naming
- Files: kebab-case
- Classes: PascalCase
- Functions: camelCase
- Constants: SCREAMING_SNAKE_CASE

### Git
- Conventional commits
- Feature branches: feature/description
- Bugfix branches: fix/description

## Architecture
<!-- 架构说明 -->

## External Dependencies
<!-- 外部依赖说明 -->

## Security Considerations
- All user input must be validated
- Use parameterized queries
- JWT tokens expire in 24 hours
EOF
        log_success "project.md 已更新为示例内容"
    fi
fi

# 6. 验证安装
echo ""
log_info "验证安装..."

echo ""
echo "=== OpenSpec 版本 ==="
openspec --version

echo ""
echo "=== 目录结构 ==="
if command_exists tree; then
    tree openspec -L 2 2>/dev/null || find openspec -type f -name "*.md" | head -10
else
    find openspec -type f -name "*.md" | head -10
fi

echo ""
echo "=== 活跃变更 ==="
openspec list 2>/dev/null || echo "（无活跃变更）"

echo ""
echo "=== 规格列表 ==="
openspec list --specs 2>/dev/null || echo "（无规格）"

# 7. 检查 AI 工具配置
echo ""
log_info "检查 AI 工具配置..."

check_ai_config() {
    local name=$1
    local path=$2
    if [ -d "$path" ]; then
        log_success "$name: 已配置"
    else
        log_info "$name: 未配置"
    fi
}

check_ai_config "Claude Code" ".claude/commands/openspec"
check_ai_config "Cursor" ".cursor/prompts/openspec"
check_ai_config "GitHub Copilot" ".github/prompts"
check_ai_config "Windsurf" ".windsurf/workflows"
check_ai_config "Cline" ".clinerules/workflows"

# 8. 输出使用说明
echo ""
echo "======================================"
echo "  安装完成！"
echo "======================================"
echo ""
echo "下一步操作:"
echo ""
echo "1. 填充项目上下文（如果还没有）:"
echo "   请 AI 助手: '帮我分析项目并填充 openspec/project.md'"
echo ""
echo "2. 创建第一个变更提案:"
echo "   Claude Code: /openspec:proposal Your feature description"
echo "   Cursor:      /openspec-proposal Your feature description"
echo "   对话:        '创建一个 OpenSpec 提案，添加...功能'"
echo ""
echo "3. 查看 OpenSpec 状态:"
echo "   openspec list          # 查看活跃变更"
echo "   openspec list --specs  # 查看规格"
echo "   openspec view          # 交互式仪表盘"
echo ""
echo "文档: https://github.com/Fission-AI/OpenSpec"
echo ""

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227

将此脚本保存为 install-openspec.sh，然后执行：

bash

# 在当前目录安装
chmod +x install-openspec.sh
./install-openspec.sh

# 或指定项目目录
./install-openspec.sh /path/to/my-project

这个脚本会：

检查 Node.js 版本
安装/更新 OpenSpec CLI
初始化项目（或更新现有配置）
填充示例 project.md
验证所有配置
显示下一步操作指南

5.1 OpenSpec 安装与配置 ​

环境要求 ​

必要条件 ​

推荐的开发环境 ​

检查 Node.js 版本 ​

安装 OpenSpec CLI ​

全局安装（推荐） ​

项目级安装（可选） ​

安装故障排除 ​

初始化项目 ​

基本初始化 ​

初始化选项 ​

初始化后的目录结构 ​

理解生成的文件 ​

1. 根目录 AGENTS.md ​

2. openspec/project.md ​

3. openspec/AGENTS.md ​

AI 工具配置详解 ​

Claude Code 配置 ​

Cursor 配置 ​

GitHub Copilot 配置 ​

Windsurf 配置 ​

Cline 配置 ​

多工具配置 ​

更新 OpenSpec ​

升级 CLI ​

更新项目配置 ​

添加新的 AI 工具 ​

配置验证 ​

检查安装状态 ​

验证 AI 工具集成 ​

项目配置最佳实践 ​

1. 填充 project.md ​

2. 版本控制配置 ​

3. 团队协作配置 ​

本章小结 ​

完整示例代码 ​

5.1 OpenSpec 安装与配置

环境要求

必要条件

推荐的开发环境

检查 Node.js 版本

安装 OpenSpec CLI

全局安装（推荐）

项目级安装（可选）

安装故障排除

初始化项目

基本初始化

初始化选项

初始化后的目录结构

理解生成的文件

1. 根目录 `AGENTS.md`

2. `openspec/project.md`

3. `openspec/AGENTS.md`

AI 工具配置详解

Claude Code 配置

Cursor 配置

GitHub Copilot 配置

Windsurf 配置

Cline 配置

多工具配置

更新 OpenSpec

升级 CLI

更新项目配置

添加新的 AI 工具

配置验证

检查安装状态

验证 AI 工具集成

项目配置最佳实践

1. 填充 project.md

2. 版本控制配置

3. 团队协作配置

本章小结

完整示例代码