核心设计理念

数据流向

schema.yaml ──→ ArtifactGraph ──→ getBuildOrder()
                     │                    │
                     │              getNextArtifacts()
                     │                    │
config.yaml ──→ instructions ◀── template + instruction
                     │
                     ▼
              AI 创作 artifact
                     │
                     ▼
              detectCompleted() ──→ 文件系统扫描
                     │
                     ▼
              archive ──→ Delta Spec 合并 ──→ 主 specs/

命令路径解析

嵌套命令通过 getCommandPath 函数转化为 : 分隔的路径：

// openspec change show → "change:show"
// openspec schema fork → "schema:fork"
function getCommandPath(command: Command): string {
  const names: string[] = [];
  let current: Command | null = command;

  while (current) {
    const name = current.name();
    if (name && name !== 'openspec') {
      names.unshift(name);
    }
    current = current.parent;
  }

  return names.join(':') || 'openspec';
}

命令注册一览

工具常量定义：core/config.ts

AI_TOOLS 是一个数组，定义了所有支持的 AI 工具：

export const AI_TOOLS: AIToolOption[] = [
  { name: 'Claude Code', value: 'claude', skillsDir: '.claude/skills' },
  { name: 'Cursor',      value: 'cursor', skillsDir: '.cursor/skills' },
  { name: 'GitHub Copilot', value: 'github-copilot', skillsDir: '.github/prompts' },
  { name: 'Windsurf',    value: 'windsurf', skillsDir: '.windsurf/workflows' },
  { name: 'Gemini CLI',  value: 'gemini', skillsDir: '.gemini/commands' },
  // ... 20+ 更多工具
];

工作流 → Skill 目录映射

// core/init.ts
const WORKFLOW_TO_SKILL_DIR: Record<string, string> = {
  'explore':      'openspec-explore',
  'new':          'openspec-new-change',
  'continue':     'openspec-continue-change',
  'apply':        'openspec-apply-change',
  'ff':           'openspec-ff-change',
  'sync':         'openspec-sync-specs',
  'archive':      'openspec-archive-change',
  'bulk-archive': 'openspec-bulk-archive-change',
  'verify':       'openspec-verify-change',
  'onboard':      'openspec-onboard',
  'propose':      'openspec-propose',
};

每个工作流对应一个 skill 目录，init 时根据 profile (core/custom) 选择生成哪些。

commands/workflow/index.ts

Workflow 命令是 OpenSpec 的核心交互接口，所有命令共享同一套 artifact-graph 引擎：

// status 命令：查询 artifact 状态
export async function statusCommand(options: StatusOptions) {
  const context = loadChangeContext(projectRoot, changeName, options.schema);
  const status = formatChangeStatus(context);
  // 输出 JSON 或人类可读格式
}

// instructions 命令：获取富化指令
export async function instructionsCommand(
  artifactId: string,
  options: InstructionsOptions
) {
  const context = loadChangeContext(projectRoot, changeName, options.schema);
  const instructions = generateInstructions(context, artifactId, projectRoot);
  // 返回 template + instruction + context + rules + dependencies
}

// new change 命令：创建变更目录
export async function newChangeCommand(
  changeName: string,
  options: NewChangeOptions
) {
  // 创建 openspec/changes/<name>/
  // 写入 .openspec.yaml 元数据
}

命令间的数据流

new change → 创建目录 + .openspec.yaml
     │
     ▼
  status → loadChangeContext() → ArtifactGraph + detectCompleted()
     │
     ▼
instructions → generateInstructions() → 富化指令 JSON
     │
     ▼
  (AI 创建 artifact 文件)
     │
     ▼
  status → detectCompleted() 重新检测 → 更新状态
     │
     ▼
  archive → 合并 Delta Specs + 移动到 archive/

Artifact 类型定义

// core/artifact-graph/types.ts
export interface Artifact {
  id: string;           // 唯一标识，如 "proposal"
  generates: string;    // 产出路径，如 "proposal.md" 或 "specs/**/*.md"
  description: string;  // 描述
  template: string;     // 模板文件相对路径
  instruction?: string; // 创作指导
  requires: string[];   // 依赖的 artifact ID 列表
}

export interface SchemaYaml {
  name: string;
  version: number;
  description: string;
  artifacts: Artifact[];
  apply?: {
    requires: string[];   // apply 前置条件
    tracks: string;       // 进度追踪文件
    instruction?: string; // 实现指导
  };
}

export type CompletedSet = Set<string>;
export type BlockedArtifacts = Record<string, string[]>;

核心查询方法

算法执行过程可视化

以默认 spec-driven schema 为例：

依赖关系：
  proposal → (无依赖)
  specs    → [proposal]
  design   → [proposal]
  tasks    → [specs, design]

初始入度：
  proposal=0  specs=1  design=1  tasks=2

第 1 轮：取出 proposal (入度=0)
  → specs 入度 1→0, design 入度 1→0
  → queue: [design, specs]  (排序后)

第 2 轮：取出 design (入度=0)
  → tasks 入度 2→1
  → queue: [specs]

第 3 轮：取出 specs (入度=0)
  → tasks 入度 1→0
  → queue: [tasks]

第 4 轮：取出 tasks (入度=0)
  → queue: []

结果：[proposal, design, specs, tasks]

getNextArtifacts() — 就绪节点查询

getNextArtifacts(completed: CompletedSet): string[] {
  const ready: string[] = [];

  for (const artifact of this.artifacts.values()) {
    if (completed.has(artifact.id)) continue; // 已完成，跳过

    // 所有依赖都在 completed 中 → ready
    const allDepsCompleted = artifact.requires.every(
      req => completed.has(req)
    );
    if (allDepsCompleted) {
      ready.push(artifact.id);
    }
  }

  return ready.sort(); // 确定性排序
}

时间复杂度：O(V × D)，V = artifact 数量，D = 平均依赖数。对于典型的 4-6 个 artifact 场景，性能微不足道。

两种检测模式

function isArtifactComplete(generates: string, changeDir: string): boolean {
  const fullPattern = path.join(changeDir, generates);

  if (isGlobPattern(generates)) {
    // Glob 模式：specs/**/*.md → 有匹配文件即完成
    return hasGlobMatches(fullPattern);
  }

  // 简单路径：proposal.md → 文件存在即完成
  return fs.existsSync(fullPattern);
}

function isGlobPattern(pattern: string): boolean {
  // 检测 *, ?, [ 三种通配符
  return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
}

function hasGlobMatches(pattern: string): boolean {
  // 跨平台：Windows 反斜杠 → POSIX 正斜杠
  const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
  const matches = fg.sync(normalizedPattern, { onlyFiles: true });
  return matches.length > 0;
}

设计决策：为什么用文件系统而非数据库

getSchemaDir() 解析实现

export function getSchemaDir(
  name: string,
  projectRoot?: string
): string | null {
  // 1. 检查项目本地目录
  if (projectRoot) {
    const projectDir = path.join(
      getProjectSchemasDir(projectRoot), name
    );
    if (fs.existsSync(path.join(projectDir, 'schema.yaml'))) {
      return projectDir;
    }
  }

  // 2. 检查用户覆盖目录
  const userDir = path.join(getUserSchemasDir(), name);
  if (fs.existsSync(path.join(userDir, 'schema.yaml'))) {
    return userDir;
  }

  // 3. 检查包内置目录
  const packageDir = path.join(getPackageSchemasDir(), name);
  if (fs.existsSync(path.join(packageDir, 'schema.yaml'))) {
    return packageDir;
  }

  return null; // 未找到
}

路径定位函数

// 包内置 schemas 路径：通过 import.meta.url 定位
export function getPackageSchemasDir(): string {
  const currentFile = fileURLToPath(import.meta.url);
  // 从 dist/core/artifact-graph/ 向上导航到 schemas/
  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
}

// 用户 schemas 路径：遵循 XDG 规范
export function getUserSchemasDir(): string {
  return path.join(getGlobalDataDir(), 'schemas');
  // → ~/.local/share/openspec/schemas/ (Linux)
  // → ~/Library/Application Support/openspec/schemas/ (macOS)
}

// 项目本地 schemas 路径
export function getProjectSchemasDir(projectRoot: string): string {
  return path.join(projectRoot, 'openspec', 'schemas');
}

Schema 变更解析链

当执行命令时，schema 名称的解析经过多层：

CLI 参数 --schema <name>
  → 有值则直接使用
  → 无值则：
     .openspec.yaml 中的 schema 字段
       → 有值则使用
       → 无值则：
          openspec/config.yaml 中的 schema 字段
            → 有值则使用
            → 无值则：默认 "spec-driven"

// utils/change-metadata.ts
export function resolveSchemaForChange(
  changeDir: string,
  explicitSchema?: string
): string {
  if (explicitSchema) return explicitSchema;

  // 尝试从 .openspec.yaml 读取
  const metadata = readChangeMetadata(changeDir);
  if (metadata?.schema) return metadata.schema;

  return 'spec-driven'; // 默认值
}

依赖信息组装

function getDependencyInfo(
  artifact: Artifact,
  graph: ArtifactGraph,
  completed: CompletedSet
): DependencyInfo[] {
  return artifact.requires.map(id => {
    const depArtifact = graph.getArtifact(id);
    return {
      id,
      done: completed.has(id),              // 是否已完成
      path: depArtifact?.generates ?? id,    // 文件路径
      description: depArtifact?.description ?? '',
    };
  });
}

// 解锁计算：反向查找谁的 requires 包含当前 artifact
function getUnlockedArtifacts(graph: ArtifactGraph, artifactId: string): string[] {
  return graph.getAllArtifacts()
    .filter(a => a.requires.includes(artifactId))
    .map(a => a.id)
    .sort();
}

ChangeContext 接口

export interface ChangeContext {
  graph: ArtifactGraph;      // 依赖图实例
  completed: CompletedSet;   // 已完成 artifact ID 集合
  schemaName: string;        // 使用的 schema 名称
  changeName: string;        // 变更名称
  changeDir: string;         // 变更目录完整路径
  projectRoot: string;       // 项目根目录
}

// 由 loadChangeContext() 一次性加载
export function loadChangeContext(
  projectRoot: string,
  changeName: string,
  schemaName?: string
): ChangeContext {
  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
  const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
  const schema = resolveSchema(resolvedSchemaName, projectRoot);
  const graph = ArtifactGraph.fromSchema(schema);
  const completed = detectCompleted(graph, changeDir);

  return { graph, completed, schemaName: resolvedSchemaName,
           changeName, changeDir, projectRoot };
}

extractRequirementsSection() 核心逻辑

export function extractRequirementsSection(content: string):
  RequirementsSectionParts {
  const lines = normalizeLineEndings(content).split('\n');

  // 1. 定位 "## Requirements" header
  const reqHeaderIndex = lines.findIndex(
    l => /^##\s+Requirements\s*$/i.test(l)
  );

  // 2. 如果不存在，创建空 section
  if (reqHeaderIndex === -1) {
    return { before: content, headerLine: '## Requirements',
             preamble: '', bodyBlocks: [], after: '\n' };
  }

  // 3. 找到 section 结束位置（下一个 ## 级别标题）
  let endIndex = lines.length;
  for (let i = reqHeaderIndex + 1; i < lines.length; i++) {
    if (/^##\s+/.test(lines[i])) { endIndex = i; break; }
  }

  // 4. 解析 section 内的 Requirement 块
  const sectionBodyLines = lines.slice(reqHeaderIndex + 1, endIndex);
  const blocks: RequirementBlock[] = [];

  // 跳过 preamble 直到第一个 ### Requirement:
  // 然后按 ### Requirement: 切分块
  // ...

  return { before, headerLine, preamble, bodyBlocks: blocks, after };
}

Delta Spec 解析：parseDeltaSpec()

export interface DeltaPlan {
  added: RequirementBlock[];          // 新增
  modified: RequirementBlock[];       // 修改（完整替换内容）
  removed: string[];                  // 删除（Requirement 名称）
  renamed: Array<{ from: string; to: string }>; // 重命名
  sectionPresence: {                  // 各分区是否存在
    added: boolean; modified: boolean;
    removed: boolean; renamed: boolean;
  };
}

export function parseDeltaSpec(content: string): DeltaPlan {
  // 按 ## ADDED/MODIFIED/REMOVED/RENAMED Requirements 分区
  // 每个分区内再按 ### Requirement: 切分块
  // 返回结构化的 DeltaPlan
}

合并操作示意

主 spec (openspec/specs/auth/spec.md):
  ## Requirements
  ### Requirement: Login
  ### Requirement: Session Timeout (60min)
  ### Requirement: Remember Me

Delta spec (changes/add-2fa/specs/auth/spec.md):
  ## ADDED Requirements
  ### Requirement: Two-Factor Authentication
  ## MODIFIED Requirements
  ### Requirement: Session Timeout (改为 30min)
  ## REMOVED Requirements
  ### Requirement: Remember Me

合并后的主 spec:
  ## Requirements
  ### Requirement: Login                     ← 保留不变
  ### Requirement: Session Timeout (30min)   ← 被 MODIFIED 替换
  ### Requirement: Two-Factor Authentication ← ADDED 追加

安全检查

• 重名检测：ADDED 分区内不允许重复名称，也不允许与已有 Requirement 重名
• MODIFIED 完整性：必须包含完整的 Requirement 内容（非差异），因为是整块替换
• 归档前验证：合并后的 spec 会经过 Validator 再次验证格式

验证报告结构

export interface ValidationIssue {
  level: 'ERROR' | 'WARNING';  // 严重级别
  path: string;                 // 问题路径
  message: string;              // 错误描述
}

export interface ValidationReport {
  valid: boolean;        // 是否通过
  issues: ValidationIssue[];
  errors: number;
  warnings: number;
}

自定义规则示例

• Purpose 长度：spec 的 Purpose 描述不能少于 MIN_PURPOSE_LENGTH 字符
• Requirement 文本长度：不能超过 MAX_REQUIREMENT_TEXT_LENGTH
• Scenario 格式：必须使用 #### (4 个 #)，不是 3 个
• RFC 2119 关键字：检查 SHALL/MUST/SHOULD/MAY 的使用

生成流程

getCommandContents()        获取所有命令内容 (CommandContent[])
        │
        ▼
CommandAdapterRegistry      查找目标工具的适配器
        │
        ▼
adapter.getFilePath(id)     计算输出文件路径
        │
        ▼
adapter.formatFile(content) 按工具格式渲染文件
        │
        ▼
写入文件系统                 .claude/commands/opsx/propose.md
                            .cursor/rules/opsx/propose.md
                            .github/prompts/opsx-propose.prompt.md

适配器工厂

// core/command-generation/adapters/factory.ts
// 适配器注册表，按 toolId 查找
const adapters: Map<string, ToolCommandAdapter> = new Map([
  ['claude', claudeAdapter],
  ['cursor', cursorAdapter],
  ['github-copilot', copilotAdapter],
  ['windsurf', windsurfAdapter],
  ['gemini', geminiAdapter],
  ['codex', codexAdapter],
  // ... 20+ 更多
]);

export function getAdapter(toolId: string): ToolCommandAdapter | undefined {
  return adapters.get(toolId);
}

各适配器输出路径对比

工作流模板：core/templates/workflows/

每个工作流都有一个 TypeScript 文件，返回结构化的 SkillTemplate：

// core/templates/workflows/propose.ts
export function getOpsxProposeSkillTemplate(): SkillTemplate {
  return {
    name: 'openspec-propose',
    description: 'Propose a new change with all artifacts...',
    instructions: `
      Propose a new change...

      **Steps**
      1. Ask what they want to build
      2. Create change directory: openspec new change "<name>"
      3. Get artifact build order: openspec status --change "<name>" --json
      4. Create artifacts in dependency order:
         a. Get instructions: openspec instructions <id> --change "<name>" --json
         b. Read template, instruction, context, rules
         c. Create artifact file
      5. Continue until all applyRequires are done
    `,
  };
}

Profile 系统

// core/profiles.ts
export const CORE_WORKFLOWS = [
  'propose', 'apply', 'archive'
];

export const ALL_WORKFLOWS = [
  'explore', 'new', 'continue', 'apply', 'ff',
  'sync', 'archive', 'bulk-archive', 'verify', 'onboard', 'propose'
];

export function getProfileWorkflows(profile: Profile): string[] {
  if (profile === 'core') return CORE_WORKFLOWS;
  return ALL_WORKFLOWS;
}

core profile：只生成 propose/apply/archive 三个核心命令。
custom profile：生成全部 11 个工作流命令。

双层配置架构

全局配置 (core/global-config.ts)
  → ~/.config/openspec/config.json (XDG 规范)
  → 存储：profile, delivery, workflows, featureFlags
  → 影响：所有项目

项目配置 (core/project-config.ts)
  → openspec/config.yaml
  → 存储：schema, context, rules
  → 影响：当前项目

项目配置解析：core/project-config.ts

export interface ProjectConfig {
  schema?: string;
  context?: string;                    // 最大 50KB
  rules?: Record<string, string[]>;    // artifactId → rules[]
}

export function readProjectConfig(projectRoot: string): ProjectConfig | null {
  const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
  if (!fs.existsSync(configPath)) return null;

  const content = fs.readFileSync(configPath, 'utf-8');
  const parsed = yaml.parse(content);
  // Zod 验证 + 类型安全
  return ProjectConfigSchema.parse(parsed);
}

// 验证 rules 中的 artifact ID 是否存在于当前 schema
export function validateConfigRules(
  rules: Record<string, string[]>,
  validArtifactIds: Set<string>,
  schemaName: string
): string[] {
  const warnings: string[] = [];
  for (const key of Object.keys(rules)) {
    if (!validArtifactIds.has(key)) {
      warnings.push(
        `Warning: rules key "${key}" is not a valid artifact ID in schema "${schemaName}"`
      );
    }
  }
  return warnings;
}

匿名遥测：src/telemetry/

OpenSpec 使用 PostHog 收集匿名使用统计：

• 收集内容：命令名称 + CLI 版本号
• 不收集：命令参数、文件路径、用户数据 (PII)
• 首次运行提示：通过 maybeShowTelemetryNotice() 显示一次

// 每个命令执行前自动追踪
program.hook('preAction', async (thisCommand, actionCommand) => {
  await maybeShowTelemetryNotice();
  const commandPath = getCommandPath(actionCommand);
  await trackCommand(commandPath, version);
});

// 命令完成后关闭客户端
program.hook('postAction', async () => {
  await shutdown();
});

# 退出遥测
export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

架构亮点

• 文件即状态：用文件系统代替数据库，零依赖且 Git 友好
• Schema 驱动：schema.yaml 定义工作流，修改 YAML 即改变行为
• 三级覆盖：项目 > 用户 > 内置，满足个性化需求
• 内容与格式分离：CommandContent 统一内容，Adapter 负责格式转换
• 确定性排序：Kahn 算法中双重 sort()，保证相同输入相同输出
• 渐进式采纳：brownfield 优先设计，通过隔离的 change 目录避免侵入

延伸阅读

• 使用教程：OpenSpec 完全使用教程
• SDD 实操：Claude Code + SDD 实操落地教程
• GitHub 源码：Fission-AI/OpenSpec