OpenSpec 深度解析：最佳实践四步法，让 AI 编码从"黑盒"变"白盒"的规范引擎

# spec-driven schema (默认工作流)
artifacts:
-id:proposal
    generates:proposal.md
    requires:[]
    
-id:specs
    generates:"specs/**/*.md"
    requires:[proposal]
    
-id:design
    generates:design.md
    requires:[proposal]
    
-id:tasks
    generates:tasks.md
    requires:[specs,design]

# Authentication Specification

## Purpose
描述系统的认证机制，确保用户身份验证安全可靠。

## Requirements

### Requirement: User Login
系统 SHALL 允许用户使用用户名和密码登录。

#### Scenario: Successful Login
- **GIVEN** 用户输入有效的用户名和密码
- **WHEN** 用户点击登录按钮
- **THEN** 系统返回认证 token
- **AND** 重定向到用户首页

#### Scenario: Failed Login
- **GIVEN** 用户输入错误的密码
- **WHEN** 用户点击登录按钮
- **THEN** 显示错误提示
- **AND** 不返回 token

## ADDED Requirements

### Requirement: Two-Factor Authentication
系统 MUST 支持 TOTP 双因素认证。

#### Scenario: 2FA Enrollment
- **GIVEN** 用户在设置中启用 2FA
- **WHEN** 用户配置认证器应用
- **THEN** 系统显示 QR 码供扫描

## MODIFIED Requirements

### Requirement: Session Expiration
系统 MUST 在 15 分钟无活动后过期会话。

## REMOVED Requirements

### Requirement: Legacy Export
**Reason**: 被新的导出系统替代
**Migration**: 使用新端点 /api/v2/export

## Why
现有会话管理存在安全隐患，需要增加双因素认证。

## What Changes
- 添加 TOTP 双因素认证
- 缩短会话过期时间
- 移除旧的导出功能

## Capabilities
### New Capabilities
- `two-factor-auth`: TOTP 双因素认证支持

### Modified Capabilities
- `session-management`: 会话过期时间从 30 分钟改为 15 分钟

## Impact
- 后端：添加 OTP 生成和验证端点
- 前端：创建 OTP 输入组件
- 数据库：users 表添加 otp_secret 列

name: spec-driven
version:1
description:DefaultOpenSpecworkflow

artifacts:
-id:proposal
    generates:proposal.md
    description:Initialproposaldocument
    template:proposal.md
    requires:[]
    
-id:specs
    generates:"specs/**/*.md"
    requires:[proposal]
    
-id:design
    generates:design.md
    requires:[proposal]
    
-id:tasks
    generates:tasks.md
    requires:[specs,design]

apply:
requires:[tasks]
tracks:tasks.md

const ScenarioSchema = z.object({
  rawText: z.string().min(1),
});

const RequirementSchema = z.object({
  text: z.string().min(1).refine(
    (text) => text.includes('SHALL') || text.includes('MUST'),
    'Requirement must contain SHALL or MUST keyword'
  ),
  scenarios: z.array(ScenarioSchema).min(1),
});

const SpecSchema = z.object({
  name: z.string().min(1),
  overview: z.string().min(1),
  requirements: z.array(RequirementSchema).min(1),
  metadata: z.object({
    version: z.string().default('1.0.0'),
    format: z.literal('openspec'),
    sourcePath: z.string().optional(),
  }).optional(),
});

const DeltaOperationType = z.enum(['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED']);

const DeltaSchema = z.object({
  spec: z.string().min(1),
  operation: DeltaOperationType,
  description: z.string().min(1),
  requirement: RequirementSchema.optional(),
  requirements: z.array(RequirementSchema).optional(),
  rename: z.object({ from: z.string(), to: z.string() }).optional(),
});

const ChangeSchema = z.object({
  name: z.string().min(1),
  why: z.string().min(50).max(1000),
  whatChanges: z.string().min(1),
  deltas: z.array(DeltaSchema).min(1).max(10),
  metadata: z.object({
    version: z.string().default('1.0.0'),
    format: z.literal('openspec-change'),
    sourcePath: z.string().optional(),
  }).optional(),
});

const ProjectConfigSchema = z.object({
  schema: z.string().min(1),
  context: z.string().optional(),              // 50KB 硬限制
  rules: z.record(z.string(), z.array(z.string())).optional(),
});

你：/opsx:propose add-dark-mode

AI：已创建 openspec/changes/add-dark-mode/
    ✓ proposal.md — 为什么要做，改什么
    ✓ specs/      — 需求和场景
    ✓ design.md   — 技术方案
    ✓ tasks.md    — 实现清单
    准备好实现了！运行 /opsx:apply

# 实现任务：深色模式

## 任务列表

### 任务 1：组件开发
- [ ] 1.1 创建主题上下文提供者
  - 文件：`src/context/ThemeContext.tsx`
  - 测试：`src/context/ThemeContext.test.tsx`
  
- [ ] 1.2 创建切换组件
  - 文件：`src/components/ThemeToggle.tsx`
  - 测试：`src/components/ThemeToggle.test.tsx`

### 任务 2：样式实现
- [ ] 2.1 添加 CSS 变量
  - 文件：`src/styles/variables.css`
  
- [ ] 2.2 连接 localStorage
  - 文件：`src/hooks/useTheme.ts`

## 完成标准
- [ ] 所有任务完成
- [ ] 测试通过
- [ ] 代码审查通过

你：/opsx:apply

AI：正在实现任务...
    ✓ 1.1 添加主题上下文提供者
    ✓ 1.2 创建切换组件
    ✓ 2.1 添加 CSS 变量
    ✓ 2.2 连接 localStorage
    所有任务完成！

你：/opsx:archive

AI：已归档到 openspec/changes/archive/2026-03-27-add-dark-mode/
    规范已更新。准备好下一个功能。

/opsx:explore    ← 探索想法
/opsx:new        ← 创建变更脚手架
/opsx:continue   ← 继续未完成的变更
/opsx:ff         ← 快速创建所有规划文档
/opsx:apply      ← 实现任务
/opsx:verify     ← 验证实现是否符合规范
/opsx:sync       ← 同步规范与代码状态
/opsx:archive    ← 归档

你：/opsx:explore 如何实现深色模式

AI：让我调查一下你当前的 UI 设置...
    [分析代码库]
    
    我看到你的应用使用 CSS-in-JS。
    有三个主要选项：
    1. CSS 变量 + 主题切换
    2. 主题提供商模式
    3. 本地存储持久化
    
    哪个方向你感兴趣？

你：/opsx:verify

AI：验证实现是否符合文档...
    ✓ 检查 tasks.md 中的任务
    ✓ 验证代码实现
    ✓ 检查测试覆盖
    
    验证通过！所有任务正确实现。

const claudeAdapter: ToolCommandAdapter = {
  toolId: 'claude',
  getFilePath(commandId: string): string {
    return path.join('.claude', 'commands', 'opsx', `${commandId}.md`);
  },
  formatFile(content: CommandContent): string {
    return `---
name: ${escapeYamlValue(content.name)}
description: ${escapeYamlValue(content.description)}
category: ${escapeYamlValue(content.category)}
tags: ${formatTagsArray(content.tags)}
---

${content.body}
`;
  },
};

async function buildUpdatedSpec(update, changeName): Promise<{rebuilt, counts}> {
// 1. 解析 delta 规范
const plan = parseDeltaSpec(changeContent);

// 2. 预验证：检查节内重复和跨节冲突
  validateNoDuplicates(plan);
  validateNoCrossSectionConflicts(plan);

// 3. 加载或创建目标规范
let targetContent = await loadOrCreateTarget();

// 4. 提取 Requirements 区域并建立名称→块映射
const parts = extractRequirementsSection(targetContent);
const nameToBlock = new Map(parts.bodyBlocks);

// 5. 按顺序应用操作：RENAMED → REMOVED → MODIFIED → ADDED
  applyRenamed(plan.renamed, nameToBlock);
  applyRemoved(plan.removed, nameToBlock);
  applyModified(plan.modified, nameToBlock);
  applyAdded(plan.added, nameToBlock);

// 6. 重组规范文件（保持原始顺序）
const rebuilt = recompose(parts, nameToBlock);

return { rebuilt, counts };
}

class CommandAdapterRegistry {
  static register(adapter: ToolCommandAdapter): void
  static get(toolId: string): ToolCommandAdapter | undefined
  static getAll(): ToolCommandAdapter[]
  static has(toolId: string): boolean
}

const validateSpecRules = [
  checkPurposeLength,
  checkRequirementTextLength,
  checkScenariosFormat,
  // ... 可以添加更多规则
];

function generateInstructions(context, artifactId, projectRoot): ArtifactInstructions {
  // 1. 加载基础信息
  // 2. 注入项目上下文（来自 config.yaml）
  // 3. 注入工件规则（来自 config.yaml 的 rules 字段）
  // 4. 注入模板内容（来自 schema 的 templates/ 目录）
  // 5. 返回完整的指令对象
}

需要实现一个用户登录功能，用 JWT 实现，存到 localStorage 里。

### Requirement: User Login
用户应能够使用用户名和密码登录系统。

#### Scenario: Successful Login
- **GIVEN** 用户输入有效的用户名和密码
- **WHEN** 用户点击登录按钮
- **THEN** 系统返回认证 token
- **AND** 重定向到用户首页

/opsx:continue [change-name]