OpenSpec 使用手册

node --version

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

# pnpm（推荐，速度更快）
pnpm add -g @fission-ai/openspec@latest

# yarn
yarn global add @fission-ai/openspec@latest

# bun
bun install -g @fission-ai/openspec@latest

# 查看版本号
openspec --version

# 查看帮助信息
openspec --help

OpenSpec v0.x.x
Spec-Driven Development for AI Coding Assistants

cd your-project
openspec init

? Which AI tools do you want to configure? (Press <space> to select)
❯◉ Claude Code
 ◯ Cursor
 ◯ GitHub Copilot
 ◯ Cline
 ◯ Windsurf
 ...

# 跳过所有工具配置
openspec init --tools none

# 配置所有支持的 AI 工具
openspec init --tools all

# 只配置特定工具（逗号分隔）
openspec init --tools claude,cursor

your-project/
├── .openspec/                    # OpenSpec 内部配置目录（自动生成）
├── openspec/                     # OpenSpec 工作目录
│   ├── agent-instructions.md     # AI 代理指导文件（告诉 AI 如何使用 OpenSpec）
│   ├── project-context.md        # 项目上下文（项目背景、技术栈等）
│   ├── changes/                  # 变更提案目录（每个功能/变更一个文件夹）
│   └── specs/                    # 主规范目录（已归档的规范）
└── ... (项目其他文件)

openspec new change <change-name>

# 好的命名示例
openspec new change user-authentication
openspec new change add-payment-module
openspec new change fix-login-timeout

# 不好的命名示例
openspec new change feature1          # 太模糊
openspec new change addUserAuth       # 应使用 kebab-case

openspec new change ai-infra-cmdb-core

✓ Created change directory: openspec/changes/ai-infra-cmdb-core
✓ Created proposal.md
✓ Created design.md
✓ Created tasks.md
✓ Created specs/ directory
✓ Created .openspec.yaml

Change 'ai-infra-cmdb-core' created successfully!

openspec/changes/<change-name>/
├── .openspec.yaml     # 变更元数据（ID、状态、创建时间等，由 CLI 自动管理）
├── proposal.md        # 提案文档【必填】描述 Why 和 What
├── design.md          # 技术设计文档（架构、数据模型、API 设计等）
├── tasks.md           # 实现任务清单（按里程碑组织的待办事项）
└── specs/             # 规范目录（存放能力规范文件）
    ├── <capability-1>/
    │   └── spec.md    # 能力规范（使用 Requirement + Scenario 格式）
    ├── <capability-2>/
    │   └── spec.md
    └── schemas/       # 模式定义（可选，存放 .proto 文件等）
        └── *.proto

创建 (new) → 编写规范 → 验证 (validate) → 实现 → 归档 (archive)

proposal.md 结构：
├── ## Summary（摘要，可选）
├── ## Why 【必需】
│   ├── ### Background（背景）
│   ├── ### Problem Statement（问题描述）
│   └── ### Alternatives Considered（备选方案）
├── ## What Changes 【必需】
│   ├── ### New Resources Added（新增资源）
│   └── ### New Capabilities（新增能力）
├── ## Success Criteria（成功标准，可选）
├── ## Scope（范围，可选）
├── ## Timeline（时间线，可选）
└── ## References（参考链接，可选）

specs/
├── accelerator-management/     # 能力一：加速器管理
│   └── spec.md
├── training-job-lifecycle/     # 能力二：训练任务生命周期
│   └── spec.md
├── inference-service/          # 能力三：推理服务
│   └── spec.md
└── relationship-management/    # 能力四：关系管理
    └── spec.md

spec.md 结构：
├── # 能力名称
├── ## Overview（概述，推荐）
│   - 能力简介
│   - 解决的问题
└── ## ADDED/MODIFIED/REMOVED Requirements 【必需】
    ├── ### Requirement: <标题>
    │   ├── **Priority**: P0/P1/P2
    │   ├── **Rationale**: ...
    │   └── #### Scenario: <标题>
    │       └── Given/When/Then

## ADDED Requirements

### Requirement: GPU 自动发现

系统应通过 DaemonSet 部署的代理自动发现集群节点上的 GPU/NPU 设备。

**Priority**: P0 (Critical)

**Rationale**: 自动发现是 CMDB 的核心能力，没有它就无法管理 AI 基础设施资源。

#### Scenario: NVIDIA GPU 发现

Given 一个包含 NVIDIA GPU 节点的 Kubernetes 集群
When 发现代理以 DaemonSet 方式部署到集群
Then 所有 NVIDIA GPU 通过 NVML/DCGM 被枚举
And 每个 GPU 的型号、显存、驱动版本被记录到 CMDB

## ADDED Requirements

### REQ-001: GPU Discovery    # 错误：使用了自定义编号

System SHALL discover GPUs.

#### Scenario: Discovery    # 错误：场景标题太模糊

## ADDED Requirements

### Requirement: GPU 自动发现    # 正确：使用标准格式

系统应自动发现集群中的 GPU 设备。

**Priority**: P0 (Critical)

**Rationale**: 核心功能需求。

#### Scenario: NVIDIA GPU 发现    # 正确：场景标题具体

Given 一个包含 NVIDIA GPU 节点的 Kubernetes 集群
When 发现代理部署到集群
Then 所有 NVIDIA GPU 被枚举并记录到 CMDB

├── ## Why 【必需】
│   ├── ### Background
│   ├── ### Problem Statement
│   └── ### Alternatives Considered
└── ## What Changes 【必需】
    ├── ### New Resources Added
    └── ### New Capabilities

├── # 能力名称
├── ## Overview（推荐）
└── ## ADDED/MODIFIED/REMOVED Requirements 【必需】
    ├── ### Requirement: <标题>
    │   ├── **Priority**: P0/P1/P2
    │   ├── **Rationale**: ...
    │   └── #### Scenario: <标题>
    │       └── Given/When/Then

openspec validate <change-name>

✓ Change '<change-name>' is valid

✗ [ERROR] Change must have a Why section. Missing required sections.
Expected headers: "## Why" and "## What Changes"

✗ [ERROR] file: Change must have at least one delta. No deltas found.
Ensure your change has a specs/ directory with capability folders

specs/
└── your-capability/      # 能力文件夹
    └── spec.md           # 规范文件

## ADDED Requirements

### Requirement: 某个需求
...

specs/
└── spec.md              # ❌ 错误：直接放在 specs/ 根目录

✗ [ERROR] Delta sections ## ADDED Requirements were found, 
but no requirement entries parsed. Ensure each section includes 
at least one "### Requirement:" block

## ADDED Requirements

### REQ-001: GPU Discovery      # ❌ 错误：使用了自定义编号
### GPU Discovery               # ❌ 错误：缺少 "Requirement:" 前缀
### requirement: GPU Discovery  # ❌ 错误："requirement" 应首字母大写

## ADDED Requirements

### Requirement: GPU 自动发现    # ✓ 正确格式

✗ [ERROR] Each requirement MUST include at least one #### Scenario: block

### Requirement: GPU 自动发现

系统应自动发现 GPU 设备。

# ❌ 没有场景块

### Requirement: GPU 自动发现

系统应自动发现 GPU 设备。

**Priority**: P0 (Critical)

**Rationale**: 核心功能需求。

#### Scenario: NVIDIA GPU 发现

Given 一个包含 NVIDIA GPU 节点的 Kubernetes 集群
When 发现代理部署到集群
Then 所有 NVIDIA GPU 被枚举并记录到 CMDB

openspec change show <change-id> --json --deltas-only

openspec status --change <change-name>

Change: ai-infra-cmdb-core
Status: active
Artifacts:
  ✓ proposal.md - Valid
  ✓ design.md - Present
  ✓ tasks.md - Present
  ✓ specs/accelerator-management/spec.md - Valid (2 requirements, 3 scenarios)
  ✓ specs/training-job-lifecycle/spec.md - Valid (2 requirements, 4 scenarios)
  ✗ specs/inference-service/spec.md - Invalid (missing scenarios)

openspec [options] <command>

选项：
  -v, --version     显示版本号
  -h, --help        显示帮助信息
  --no-color        禁用彩色输出
  --json            以 JSON 格式输出

# 初始化项目
openspec init --tools none

# 创建变更
openspec new change <name>

# 验证变更
openspec validate <name>

# 查看状态
openspec status --change <name>

# 归档变更
openspec archive <name>

## Why

我们需要添加用户认证功能。

## Why

### Background

当前系统没有用户认证功能，任何人都可以访问所有数据和功能。
这导致：
- 无法追踪操作日志的责任人
- 敏感数据缺乏保护
- 无法实现细粒度的权限控制

### Problem Statement

系统需要一个安全可靠的用户认证机制，支持：
- 用户名密码登录
- 第三方 OAuth 登录（GitHub、Google）
- 会话管理和安全退出

### Alternatives Considered

1. **自建认证系统**：完全控制，但开发维护成本高
2. **使用 Auth0**：功能完善，但费用较高
3. **使用 Keycloak**：开源免费，支持多种协议 ✓ 已选择此方案

Scenario: 使用信用卡支付订单

Given 用户已登录系统
And 购物车中有 2 件商品，总价 299 元
And 用户已绑定信用卡
When 用户选择"信用卡支付"并确认
Then 订单创建成功
And 从信用卡扣除 299 元
And 用户收到支付成功通知
And 库存减少 2 件

Scenario: 支付

Given 系统
When 支付
Then 成功

# 方法一：设置环境变量
export OPENSPEC_TELEMETRY=0

# 方法二：使用通用遥测禁用标志
export DO_NOT_TRACK=1

# 方法三：在 shell 配置文件中永久设置
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.zshrc  # Zsh
echo 'export OPENSPEC_TELEMETRY=0' >> ~/.bashrc # Bash