5.2 OpenSpec 核心概念详解
概述
本章深入讲解 OpenSpec 的核心概念，帮助你理解其设计哲学和工作原理。掌握这些概念后，你将能够高效地使用 OpenSpec 进行规格驱动开发。
1. 双文件夹模型
OpenSpec 的核心创新是双文件夹模型，它清晰地分离了"当前状态"和"提案变更"。
目录结构
openspec/
├── AGENTS.md # AI 助手工作流指令
├── project.md # 项目约定和上下文
├── specs/ # 📁 当前真相（Source of Truth）
│ ├── auth/
│ │ ├── spec.md # 认证规格
│ │ └── design.md # 技术设计（可选）
│ ├── user-profile/
│ │ └── spec.md # 用户资料规格
│ └── payment/
│ └── spec.md # 支付规格
│
└── changes/ # 📁 提案变更
├── add-2fa/ # 变更提案：添加双因素认证
│ ├── proposal.md
│ ├── tasks.md
│ ├── design.md # 可选
│ └── specs/
│ └── auth/
│ └── spec.md # 增量规格
│
├── update-profile-api/ # 另一个变更提案
│ └── ...
│
└── archive/ # 📁 已归档的变更
└── 2024-12-01-add-oauth/
└── ...specs/ 文件夹
用途：存储系统当前已实现的功能规格。
特点：
- 反映生产环境中的实际行为
- 每个能力（capability）一个子目录
- 规格文件是事实来源（source of truth）
- 只有通过归档流程才会更新
示例规格文件 specs/auth/spec.md：
markdown
# Auth Specification
## Purpose
Handle user authentication and session management.
## Requirements
### Requirement: User Login
The system SHALL authenticate users with email and password.
#### Scenario: Valid credentials
- **WHEN** user submits valid email and password
- **THEN** system returns JWT token
- **AND** token expires in 24 hours
#### Scenario: Invalid credentials
- **WHEN** user submits incorrect credentials
- **THEN** system returns 401 Unauthorized
- **AND** login attempt is logged
### Requirement: Session Management
The system SHALL maintain user sessions via JWT tokens.
#### Scenario: Valid token
- **WHEN** request includes valid JWT
- **THEN** request is authenticated
- **AND** user context is available
#### Scenario: Expired token
- **WHEN** request includes expired JWT
- **THEN** system returns 401 Unauthorized
- **AND** client should refresh tokenchanges/ 文件夹
用途：存储待实现的变更提案。
特点：
- 每个变更一个独立目录
- 包含完整的提案、任务和增量规格
- 支持并行开发多个功能
- 实现后归档到
archive/
变更目录结构：
changes/add-2fa/
├── proposal.md # 变更原因和影响
├── tasks.md # 实现任务清单
├── design.md # 技术决策（可选）
└── specs/ # 增量规格
└── auth/
└── spec.md # 对 auth 规格的变更双文件夹的优势
传统方式：
┌─────────────────────────────────────┐
│ 规格和变更混在一起 │
│ 难以区分什么是已实现的 │
│ 代码审查时不清楚变更范围 │
└─────────────────────────────────────┘
OpenSpec 方式：
┌─────────────────────────────────────┐
│ specs/ = 已实现（生产环境） │
│ changes/= 待实现（开发中） │
│ archive/= 已完成（历史记录） │
│ │
│ 清晰的状态边界，易于追踪和审计 │
└─────────────────────────────────────┘2. 变更生命周期
每个变更都经历完整的生命周期，从提案到归档：
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Draft │ ──▶ │ Review │ ──▶ │ Approve │ ──▶ │ Implement│ ──▶ │ Archive │
│ 起草提案 │ │ 审核对齐 │ │ 批准计划 │ │ 实现任务 │ │ 归档更新 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
proposal.md 反馈迭代 确认范围 编写代码 合并到 specs/
tasks.md 修改规格 冻结变更 运行测试 移至 archive/
specs/*.md阶段 1：起草提案（Draft）
触发条件：
- 添加新功能
- 修改现有行为
- 架构变更
- 性能优化（改变行为时）
创建的文件：
- proposal.md - 变更原因和影响
markdown
## Why
用户反馈表明需要更强的账户安全性。双因素认证是行业标准。
## What Changes
- 添加 OTP（一次性密码）生成和验证
- 修改登录流程，要求第二因素
- 添加备用恢复码机制
## Impact
- Affected specs: auth
- Affected code: src/auth/, src/middleware/
- Breaking changes: 登录 API 响应格式变化（需要 OTP 步骤）- tasks.md - 实现任务清单
markdown
## 1. Database Setup
- [ ] 1.1 Add `otp_secret` column to users table
- [ ] 1.2 Create `recovery_codes` table
## 2. Backend Implementation
- [ ] 2.1 Implement OTP generation service
- [ ] 2.2 Add OTP verification endpoint POST /api/auth/verify-otp
- [ ] 2.3 Modify login flow to require OTP step
- [ ] 2.4 Implement recovery code generation
## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI
- [ ] 3.3 Add 2FA settings page
## 4. Testing
- [ ] 4.1 Unit tests for OTP service
- [ ] 4.2 Integration tests for login flow
- [ ] 4.3 E2E tests for 2FA setup- specs/auth/spec.md - 增量规格
markdown
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.
#### Scenario: Enable 2FA
- **WHEN** user requests to enable 2FA
- **THEN** system generates OTP secret
- **AND** displays QR code for authenticator app
- **AND** provides 10 recovery codes
#### Scenario: Login with 2FA enabled
- **WHEN** user has 2FA enabled
- **AND** submits valid credentials
- **THEN** system prompts for OTP
- **AND** completes login after valid OTP
### Requirement: Recovery Codes
The system SHALL provide recovery codes for 2FA bypass.
#### Scenario: Use recovery code
- **WHEN** user cannot access authenticator
- **AND** provides valid recovery code
- **THEN** login is allowed
- **AND** recovery code is invalidated阶段 2：审核对齐（Review）
目标：确保规格准确、完整、可实现。
活动：
- AI 助手和人类审核规格
- 讨论边界情况和异常场景
- 补充缺失的场景
- 调整任务优先级
示例对话：
Human: 请审核 add-2fa 提案，检查是否有遗漏的场景
AI: 我审核了提案，发现几个需要补充的场景：
1. 2FA 禁用流程：用户如何关闭 2FA？
2. OTP 过期处理：OTP 的有效时间是多久？
3. 错误尝试限制：连续错误输入 OTP 是否锁定？
建议添加以下场景...阶段 3：批准计划（Approve）
标志：
- 所有利益相关者同意规格
- 任务清单完整且可执行
- 没有未解决的问题
最佳实践：
- 在 proposal.md 中记录批准状态
- 可以使用 Git 标签标记批准点
阶段 4：实现任务（Implement）
流程：
- AI 助手读取 proposal.md 理解背景
- 读取 design.md（如有）理解技术决策
- 按顺序执行 tasks.md 中的任务
- 完成一个任务后标记为
[x]
示例：
Human: /openspec:apply add-2fa
AI: 我将实现 add-2fa 变更。
首先读取提案...
理解到需要添加 TOTP 双因素认证。
开始执行任务 1.1：添加 otp_secret 列到 users 表...
[创建数据库迁移]
任务 1.1 完成 ✓
开始执行任务 1.2：创建 recovery_codes 表...阶段 5：归档更新（Archive）
触发条件：
- 所有任务完成
- 代码已部署到生产环境
执行命令：
bash
openspec archive add-2fa --yes归档操作：
- 将增量规格合并到
specs/ - 将变更目录移动到
changes/archive/YYYY-MM-DD-add-2fa/ - 更新 specs/ 中的规格文件
3. 增量规格（Delta Specs）
增量规格是 OpenSpec 的核心概念，它描述了对现有规格的变更。
增量操作类型
| 操作 | 用途 | 示例 |
|---|---|---|
## ADDED Requirements | 添加新需求 | 新功能、新能力 |
## MODIFIED Requirements | 修改现有需求 | 改变行为、更新逻辑 |
## REMOVED Requirements | 删除需求 | 废弃功能、迁移 |
## RENAMED Requirements | 重命名需求 | 术语变化、重构 |
ADDED - 添加新需求
用于引入全新的、独立的能力：
markdown
## ADDED Requirements
### Requirement: Email Notifications
The system SHALL send email notifications for important events.
#### Scenario: Password changed
- **WHEN** user changes password
- **THEN** system sends confirmation email
- **AND** email includes timestamp and IP addressMODIFIED - 修改现有需求
用于改变现有需求的行为。重要：必须包含完整的修改后内容！
错误示例（只写变化部分，会丢失原有内容）：
markdown
## MODIFIED Requirements
### Requirement: User Login
- Add rate limiting ❌ 错误！缺少完整需求正确示例（包含完整的修改后需求）：
markdown
## MODIFIED Requirements
### Requirement: User Login
The system SHALL authenticate users with email and password.
The system MUST apply rate limiting: max 5 attempts per 15 minutes.
#### Scenario: Valid credentials
- **WHEN** user submits valid email and password
- **AND** rate limit not exceeded
- **THEN** system returns JWT token
- **AND** token expires in 24 hours
#### Scenario: Rate limit exceeded
- **WHEN** user exceeds 5 login attempts in 15 minutes
- **THEN** system returns 429 Too Many Requests
- **AND** includes retry-after headerREMOVED - 删除需求
用于废弃或迁移功能：
markdown
## REMOVED Requirements
### Requirement: Legacy Basic Auth
**Reason**: 已被 JWT 认证取代，不再维护
**Migration**: 所有 API 客户端需在 2024-06-01 前迁移到 JWTRENAMED - 重命名需求
用于术语变化或重构：
markdown
## RENAMED Requirements
- FROM: `### Requirement: Login`
- TO: `### Requirement: User Authentication`如果同时修改内容，需要同时使用 RENAMED 和 MODIFIED。
4. 规格文件格式
结构化需求
每个规格文件遵循固定格式：
markdown
# [Capability] Specification
## Purpose
[一句话描述这个能力的目的]
## Requirements
### Requirement: [Name]
[需求描述，使用 SHALL/MUST 关键词]
#### Scenario: [场景名称]
- **WHEN** [触发条件]
- **AND** [附加条件]
- **THEN** [预期结果]
- **AND** [附加结果]关键词规范
| 关键词 | 含义 | 用法 |
|---|---|---|
| SHALL | 必须（规范性） | 核心功能需求 |
| MUST | 必须（强制性） | 安全或合规需求 |
| SHOULD | 应该（推荐） | 最佳实践 |
| MAY | 可以（可选） | 可选功能 |
场景格式
场景使用 BDD（行为驱动开发）风格：
markdown
#### Scenario: [描述性名称]
- **GIVEN** [前置条件 - 可选]
- **WHEN** [触发动作]
- **AND** [附加条件 - 可选]
- **THEN** [预期结果]
- **AND** [附加结果 - 可选]重要格式要求：
- 场景标题必须使用
####（4 个井号） - 条件使用
- **KEYWORD**格式 - 每个需求至少一个场景
完整示例
markdown
# Payment Specification
## Purpose
Handle payment processing and transaction management.
## Requirements
### Requirement: Payment Processing
The system SHALL process credit card payments via Stripe.
#### Scenario: Successful payment
- **GIVEN** user has valid payment method on file
- **WHEN** user submits payment for $50.00
- **AND** card has sufficient funds
- **THEN** payment is processed
- **AND** transaction ID is returned
- **AND** receipt email is sent
#### Scenario: Insufficient funds
- **GIVEN** user has valid payment method
- **WHEN** user submits payment
- **AND** card has insufficient funds
- **THEN** payment is declined
- **AND** error message is displayed
- **AND** no charge is made
### Requirement: Refund Processing
The system SHALL support full and partial refunds within 30 days.
#### Scenario: Full refund
- **WHEN** admin initiates full refund
- **AND** transaction is within 30 days
- **THEN** original amount is refunded
- **AND** customer receives notification
#### Scenario: Partial refund
- **WHEN** admin initiates partial refund for $20.00
- **AND** original transaction was $50.00
- **THEN** $20.00 is refunded
- **AND** transaction shows partial refund status5. CLI 命令详解
核心命令
bash
# 列出活跃变更
openspec list
# 列出已有规格
openspec list --specs
# 显示变更详情
openspec show <change-id>
# 显示规格详情
openspec show <spec-id> --type spec
# 验证变更
openspec validate <change-id> --strict
# 归档变更
openspec archive <change-id> --yes
# 交互式仪表盘
openspec view命令参数
| 参数 | 说明 |
|---|---|
--json | JSON 格式输出，便于脚本处理 |
--strict | 严格验证模式 |
--type change|spec | 指定类型（当名称冲突时） |
--yes / -y | 跳过确认提示 |
--no-interactive | 禁用交互模式 |
--skip-specs | 归档时跳过规格更新 |
调试命令
bash
# 查看增量规格解析结果
openspec show <change-id> --json --deltas-only
# 查看特定需求
openspec show <spec-id> --json -r 1
# 全文搜索规格
rg -n "Requirement:|Scenario:" openspec/specs6. 变更命名约定
change-id 命名规则
[动词]-[描述]
add-user-auth
update-payment-flow
remove-legacy-api
refactor-database-layer常用动词前缀：
add-：添加新功能update-：更新现有功能remove-：删除功能refactor-：重构代码fix-：修复问题（通常不需要 OpenSpec）migrate-：数据或架构迁移
能力（Capability）命名
[名词]-[名词]
user-auth
payment-processing
notification-service
file-storage命名原则：
- 使用 kebab-case（短横线分隔）
- 单一职责（如果需要"和"，应该拆分）
- 10 分钟可理解规则
本章小结
本章详细介绍了 OpenSpec 的五大核心概念：
- 双文件夹模型：
specs/（当前真相）+changes/（提案变更） - 变更生命周期：Draft → Review → Approve → Implement → Archive
- 增量规格：ADDED、MODIFIED、REMOVED、RENAMED 四种操作
- 规格文件格式：结构化的需求和场景描述
- CLI 命令：管理规格和变更的命令行工具
理解这些概念后，你就具备了使用 OpenSpec 的基础知识。下一章我们将学习如何将 OpenSpec 与 Claude Code 结合使用。
完整示例代码
以下是一个完整的 OpenSpec 变更创建和管理脚本：
bash
#!/bin/bash
# OpenSpec 变更管理脚本
# 演示完整的变更生命周期
set -e
# 颜色定义
GREEN='\033[0;32m'
BLUE='\033[0;34m'
YELLOW='\033[1;33m'
NC='\033[0m'
log() { echo -e "${BLUE}[OpenSpec]${NC} $1"; }
success() { echo -e "${GREEN}[✓]${NC} $1"; }
warn() { echo -e "${YELLOW}[!]${NC} $1"; }
# 检查 OpenSpec
if ! command -v openspec &> /dev/null; then
echo "请先安装 OpenSpec: npm install -g @fission-ai/openspec@latest"
exit 1
fi
# 创建示例项目
PROJECT_DIR="openspec-lifecycle-demo"
log "创建示例项目: $PROJECT_DIR"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"
# 初始化
if [ ! -d "openspec" ]; then
log "初始化 OpenSpec..."
openspec init --non-interactive 2>/dev/null || openspec init
fi
# ============================================
# 1. 创建初始规格（模拟已有系统）
# ============================================
log "创建初始规格..."
mkdir -p openspec/specs/auth
cat > openspec/specs/auth/spec.md << 'EOF'
# Auth Specification
## Purpose
Handle user authentication and session management.
## Requirements
### Requirement: User Login
The system SHALL authenticate users with email and password.
#### Scenario: Valid credentials
- **WHEN** user submits valid email and password
- **THEN** system returns JWT token
- **AND** token expires in 24 hours
#### Scenario: Invalid credentials
- **WHEN** user submits incorrect credentials
- **THEN** system returns 401 Unauthorized
- **AND** login attempt is logged
EOF
success "创建了 specs/auth/spec.md"
# ============================================
# 2. 创建变更提案
# ============================================
CHANGE_ID="add-two-factor-auth"
log "创建变更提案: $CHANGE_ID"
mkdir -p "openspec/changes/$CHANGE_ID/specs/auth"
# proposal.md
cat > "openspec/changes/$CHANGE_ID/proposal.md" << 'EOF'
## Why
用户反馈需要更强的账户安全保护。
双因素认证（2FA）是提升账户安全的行业标准做法。
## What Changes
- 添加 TOTP（基于时间的一次性密码）支持
- 修改登录流程，增加 2FA 验证步骤
- 添加恢复码机制，防止用户锁定
## Impact
- **Affected specs**: auth
- **Affected code**:
- `src/auth/` - 认证服务
- `src/middleware/` - JWT 中间件
- `src/routes/` - API 路由
- **Breaking changes**:
- 登录 API 响应格式变化
- 需要前端配合更新登录流程
## Timeline
- 提案评审: 2024-12-01
- 开发开始: 2024-12-05
- 预计完成: 2024-12-15
EOF
success "创建了 proposal.md"
# tasks.md
cat > "openspec/changes/$CHANGE_ID/tasks.md" << 'EOF'
# Tasks for add-two-factor-auth
## 1. Database Setup
- [ ] 1.1 Add `otp_secret` column to users table (VARCHAR(32), nullable)
- [ ] 1.2 Add `otp_enabled` column to users table (BOOLEAN, default false)
- [ ] 1.3 Create `recovery_codes` table (user_id, code, used, created_at)
- [ ] 1.4 Create database migration script
## 2. Backend Implementation
- [ ] 2.1 Implement TOTP service
- Generate secret
- Verify OTP
- Generate QR code URL
- [ ] 2.2 Add 2FA enable endpoint `POST /api/auth/2fa/enable`
- [ ] 2.3 Add 2FA verify endpoint `POST /api/auth/2fa/verify`
- [ ] 2.4 Add 2FA disable endpoint `POST /api/auth/2fa/disable`
- [ ] 2.5 Modify login endpoint to check 2FA status
- [ ] 2.6 Implement recovery code generation (10 codes per user)
- [ ] 2.7 Add recovery code verification endpoint
## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow to handle 2FA challenge
- [ ] 3.3 Create 2FA setup page with QR code display
- [ ] 3.4 Create recovery codes display modal
- [ ] 3.5 Add 2FA toggle in security settings
## 4. Testing
- [ ] 4.1 Unit tests for TOTP service
- [ ] 4.2 Integration tests for 2FA endpoints
- [ ] 4.3 E2E tests for complete 2FA flow
- [ ] 4.4 Test recovery code flow
## 5. Documentation
- [ ] 5.1 Update API documentation
- [ ] 5.2 Add 2FA setup guide for users
- [ ] 5.3 Update security best practices doc
EOF
success "创建了 tasks.md"
# design.md (可选，当变更复杂时推荐)
cat > "openspec/changes/$CHANGE_ID/design.md" << 'EOF'
# Technical Design: Two-Factor Authentication
## Context
当前系统仅使用用户名/密码认证。为提高安全性，需要添加第二因素。
## Goals
- 实现 TOTP 标准（RFC 6238）
- 兼容 Google Authenticator、Authy 等主流应用
- 提供恢复机制防止用户锁定
## Non-Goals
- 短信验证（成本和安全考虑）
- 硬件 Key 支持（后续迭代）
## Decisions
### Decision 1: TOTP 算法选择
**选择**: 使用 TOTP（RFC 6238）
**理由**:
- 行业标准，广泛支持
- 无需服务器存储 OTP 值
- 用户无需网络即可生成
**替代方案**:
- HOTP: 基于计数器，不如 TOTP 安全
- 短信: 成本高，SS7 攻击风险
### Decision 2: Secret 存储
**选择**: 使用 AES-256 加密存储 OTP secret
**理由**: 即使数据库泄露，攻击者无法直接使用 secret
### Decision 3: Recovery Codes
**选择**: 每用户 10 个一次性恢复码
**理由**:
- 足够应对大多数恢复场景
- 一次性使用提高安全性
## Implementation Notes
### OTP Secret Generation
```javascript
// 使用 speakeasy 库
const speakeasy = require('speakeasy');
const secret = speakeasy.generateSecret({ length: 20 });
```
### Database Schema
```sql
ALTER TABLE users ADD COLUMN otp_secret VARCHAR(255);
ALTER TABLE users ADD COLUMN otp_enabled BOOLEAN DEFAULT false;
CREATE TABLE recovery_codes (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id),
code VARCHAR(16) NOT NULL,
used BOOLEAN DEFAULT false,
created_at TIMESTAMP DEFAULT NOW()
);
```
### API Flow
```
1. Enable 2FA:
POST /api/auth/2fa/enable
Response: { secret, qr_url, recovery_codes }
2. Verify Setup:
POST /api/auth/2fa/verify
Body: { otp }
Response: { success, enabled }
3. Login with 2FA:
POST /api/auth/login
Response: { requires_2fa: true, challenge_token }
POST /api/auth/2fa/challenge
Body: { challenge_token, otp }
Response: { access_token }
```
## Risks & Mitigations
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| 用户丢失手机 | Medium | High | Recovery codes |
| Secret 泄露 | Low | Critical | AES 加密存储 |
| Brute force OTP | Low | Medium | Rate limiting |
## Open Questions
- [ ] 是否需要支持备用邮箱验证？
- [ ] 恢复码是否需要设置过期时间？
EOF
success "创建了 design.md"
# spec delta
cat > "openspec/changes/$CHANGE_ID/specs/auth/spec.md" << 'EOF'
# Delta for Auth Specification
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication for enhanced security.
#### Scenario: Enable 2FA
- **GIVEN** user is logged in
- **WHEN** user requests to enable 2FA
- **THEN** system generates new OTP secret
- **AND** returns QR code URL for authenticator app
- **AND** generates 10 recovery codes
- **AND** requires OTP verification before activation
#### Scenario: Login with 2FA enabled
- **GIVEN** user has 2FA enabled
- **WHEN** user submits valid credentials
- **THEN** system returns 2FA challenge token
- **AND** prompts for OTP code
- **AND** issues JWT only after valid OTP
#### Scenario: Invalid OTP attempt
- **GIVEN** user is in 2FA challenge
- **WHEN** user submits invalid OTP
- **THEN** system returns error
- **AND** allows retry
- **AND** locks account after 5 consecutive failures
### Requirement: Recovery Codes
The system SHALL provide recovery codes as backup 2FA method.
#### Scenario: Use recovery code
- **GIVEN** user has 2FA enabled
- **AND** cannot access authenticator app
- **WHEN** user submits valid recovery code
- **THEN** login is allowed
- **AND** recovery code is marked as used
- **AND** user is warned about remaining codes
#### Scenario: Regenerate recovery codes
- **GIVEN** user is logged in with 2FA
- **WHEN** user requests new recovery codes
- **THEN** all existing codes are invalidated
- **AND** 10 new codes are generated
## MODIFIED Requirements
### Requirement: User Login
The system SHALL authenticate users with email and password.
The system MUST check 2FA status after credential verification.
#### Scenario: Valid credentials without 2FA
- **WHEN** user submits valid email and password
- **AND** user does not have 2FA enabled
- **THEN** system returns JWT token
- **AND** token expires in 24 hours
#### Scenario: Valid credentials with 2FA
- **WHEN** user submits valid email and password
- **AND** user has 2FA enabled
- **THEN** system returns 2FA challenge
- **AND** does NOT issue JWT yet
#### Scenario: Invalid credentials
- **WHEN** user submits incorrect credentials
- **THEN** system returns 401 Unauthorized
- **AND** login attempt is logged
EOF
success "创建了 specs/auth/spec.md (delta)"
# ============================================
# 3. 验证变更
# ============================================
echo ""
log "验证变更..."
openspec validate "$CHANGE_ID" --strict || warn "验证有警告"
# ============================================
# 4. 显示变更信息
# ============================================
echo ""
log "变更列表:"
openspec list
echo ""
log "变更详情:"
openspec show "$CHANGE_ID" 2>/dev/null || cat "openspec/changes/$CHANGE_ID/proposal.md"
# ============================================
# 5. 模拟实现完成
# ============================================
echo ""
log "模拟实现完成（标记所有任务为完成）..."
# 更新 tasks.md 标记任务完成
sed -i.bak 's/\[ \]/[x]/g' "openspec/changes/$CHANGE_ID/tasks.md"
rm "openspec/changes/$CHANGE_ID/tasks.md.bak"
success "所有任务已标记为完成"
# ============================================
# 6. 归档变更
# ============================================
echo ""
log "归档变更..."
openspec archive "$CHANGE_ID" --yes || warn "归档可能需要手动处理"
# ============================================
# 7. 验证最终状态
# ============================================
echo ""
log "最终状态:"
echo ""
echo "=== 活跃变更 ==="
openspec list
echo ""
echo "=== 规格列表 ==="
openspec list --specs
echo ""
echo "=== 目录结构 ==="
find openspec -name "*.md" | head -20
# ============================================
# 输出总结
# ============================================
echo ""
echo "======================================"
echo " OpenSpec 变更生命周期演示完成"
echo "======================================"
echo ""
echo "演示了以下流程:"
echo "1. 创建初始规格 (specs/auth/spec.md)"
echo "2. 创建变更提案 (changes/$CHANGE_ID/)"
echo " - proposal.md: 变更原因和影响"
echo " - tasks.md: 实现任务清单"
echo " - design.md: 技术决策"
echo " - specs/: 增量规格"
echo "3. 验证变更 (openspec validate)"
echo "4. 实现任务 (标记完成)"
echo "5. 归档变更 (openspec archive)"
echo ""
echo "项目目录: $(pwd)"将此脚本保存为 openspec-lifecycle-demo.sh，然后执行：
bash
chmod +x openspec-lifecycle-demo.sh
./openspec-lifecycle-demo.sh这个脚本完整演示了：
- 创建初始规格（模拟现有系统）
- 创建完整的变更提案（包含 proposal、tasks、design、delta specs）
- 验证变更格式
- 模拟实现完成
- 归档变更到 archive/
- 展示最终项目状态