简介

OpenSpec 是一个轻量级的规范（Specification）管理框架，专为 AI 编程助手设计。其核心目标是在编写代码之前让人类和 AI 就需求规范达成一致，从而提高 AI 代码助手的可预测性和可靠性。

资料来源：README.md:25-30

设计理念

资料来源：README.md:72-78

核心架构

系统组件

graph TD
    A[用户/AI助手] --> B[OpenSpec CLI]
    B --> C[Change 目录]
    C --> D[proposal.md]
    C --> E[specs/]
    C --> F[design.md]
    C --> G[tasks.md]
    B --> H[Schema 系统]
    H --> I[模板定义]
    H --> J[工件序列]

工件类型

OpenSpec 使用结构化的工件（Artifact）来组织变更：

资料来源：README.md:150-165

工作流程

标准工作流

graph LR
    A[提出变更] --> B[编写规范]
    B --> C[设计方案]
    C --> D[创建任务]
    D --> E[实施任务]
    E --> F[归档变更]

#### 步骤 1：提出变更

用户通过自然语言或斜杠命令提出变更需求：

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist

资料来源：README.md:96-105

#### 步骤 2：实施任务

规范确认后开始实现：

You: The specs look good. Let's implement this change.
AI:  I'll work through the tasks in the add-profile-filters change.
     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*

资料来源：README.md:140-145

#### 步骤 3：归档变更

实现完成后归档变更：

openspec archive add-profile-filters --yes

归档后的变更会被移至 openspec/changes/archive/<date>-<change-name>/ 目录。

实验性工作流 (/opsx)

新版实验性工作流提供更简化的命令：

启用方式：openspec experimental

资料来源：README.md:85-92

支持的工具

原生斜杠命令支持

资料来源：README.md:40-70

AGENTS.md 兼容工具

以下工具通过读取 openspec/AGENTS.md 自动发现工作流程：

• Amp
• Jules
• 其他支持 AGENTS.md 约定的工具

安装与配置

系统要求

• Node.js: >= 20.19.0

资料来源：README.md:107-108

安装步骤

#### 方式 A：npm 全局安装

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

验证安装：

openspec --version

#### 方式 B：Nix 安装

# 直接运行
nix run github:Fission-AI/OpenSpec -- init

# 安装到用户 profile
nix profile install github:Fission-AI/OpenSpec

#### 方式 C：pnpm/yarn/bun

OpenSpec 同时支持 pnpm、yarn、bun 等包管理器。

资料来源：README.md:110-125

初始化项目

cd your-project
openspec init

初始化后会创建基础目录结构：

openspec/
├── config.yaml          # 项目配置
├── specs/               # 规范源文件
│   └── <capability>/
│       └── spec.md
└── changes/             # 变更目录

CLI 命令参考

资料来源：README.md:155-165

项目配置

config.yaml 结构

context: |
  # 项目上下文信息
  # 将自动注入到所有工件中

rules:
  proposal:
    - 遵循简洁原则
  specs:
    - 使用 WHEN/THEN 格式

上下文注入

openspec instructions specs --change my-feature

输出包含：

<context>
[项目上下文]
</context>

<rules>
- 特定工件的规则
</rules>

<template>
[Schema 模板]
</template>

资料来源：openspec/changes/archive/2026-02-17-project-config/proposal.md:15-35

规范格式

需求格式

### Requirement: <需求名称>
系统应该在特定条件下执行特定行为。

#### Scenario: <场景名称>
- **WHEN** <触发条件>
- **THEN** <预期结果>

格式要求：

• 使用 SHALL/MUST 表示规范性需求
• 场景标题必须使用 4 个 # (####)
• 每个需求必须至少包含一个场景

资料来源：schemas/spec-driven/schema.yaml:1-25

MODIFIED 需求工作流

修改现有需求时：

1. 在原规范文件中定位需求
2. 复制完整需求块
3. 粘贴到 ## MODIFIED Requirements 下
4. 编辑以反映新行为

## MODIFIED Requirements

### Requirement: User can export data
The system SHALL allow users to export their data in CSV format.

#### Scenario: Successful export
- **WHEN** user clicks "Export" button
- **THEN** system downloads a CSV file

变更目录结构

AI 创建的文件结构

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 当前规范（源）
└── changes/
    └── add-2fa/              # 变更目录
        ├── proposal.md       # 变更原因
        ├── tasks.md          # 实现检查清单
        ├── design.md         # 技术决策（可选）
        └── specs/
            └── auth/
                └── spec.md   # 增量规范

资料来源：README.md:150-165

遥测与隐私

OpenSpec 收集匿名使用统计（可选退出）：

• 仅收集命令名称和版本
• 不收集参数、路径、内容或 PII
• CI 环境中自动禁用

退出方式：

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

开发指南

本地开发

# 安装依赖
pnpm install

# 构建
pnpm run build

# 测试
pnpm test

# 开发 CLI
pnpm run dev
# 或
pnpm run dev:cli

# 提交规范
git commit -m "type(scope): subject"

资料来源：README.md:190-196

工作空间功能

多仓库支持

OpenSpec 支持跨多个仓库的工作空间管理：

openspec workspace explore <repo>

状态查询

openspec status
openspec status --change integrate-docs

输出示例：

Change: integrate-docs
Scope: openspec, landing
Proposal: present
Design: present
Tasks: present
Ready for apply: yes/no

状态检查会捕获结构性问题：

• specs/ 下未知的仓库文件夹
• 缺失的任务文件
• 未确认的受影响仓库
• 缺失的仓库链接或路径

资料来源：WORKSPACE_REIMPLEMENTATION_DIRECTION.md:1-50

总结

OpenSpec 提供了一个轻量级但结构化的规范管理框架，其核心价值在于：

1. 前置对齐：在编码前达成共识
2. 组织化：每个变更都有独立文件夹
3. 灵活性：可随时更新工件，无需僵化的阶段门控
4. 工具兼容性：支持 25+ AI 编程助手

无论是个人项目还是企业级开发，OpenSpec 都能帮助团队更高效、更可靠地进行 AI 辅助开发。

概述

OpenSpec 是一个基于 AI 的规范框架，用于在 AI 编码助手项目中建立结构化的变更管理流程。安装与初始化是用户首次使用 OpenSpec 的关键步骤，涉及 CLI 工具安装、项目目录配置、配置文件生成以及与 AI 工具的集成设置。

本章节详细说明 OpenSpec 的各种安装方式、系统要求、初始化流程以及配置选项，帮助用户快速上手并在团队中推广使用。

系统要求

资料来源：README.md:67

安装方式

npm 全局安装

通过 npm 将 OpenSpec 安装为全局 CLI 工具：

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

安装完成后验证版本：

openspec --version

资料来源：README.md:69-75

pnpm 安装

pnpm add -g @fission-ai/openspec

yarn 安装

yarn global add @fission-ai/openspec

bun 安装

bun add -g @fission-ai/openspec

资料来源：README.md:56

Nix 安装（无安装方式）

对于使用 Nix 或 NixOS 的用户，可以直接运行而不安装：

nix run github:Fission-AI/OpenSpec -- init

或安装到用户 profile：

nix profile install github:Fission-AI/OpenSpec

或添加到 flake.nix 的 inputs 中：

inputs.openspec.url = "github:Fission-AI/OpenSpec";

资料来源：README.md:80-91

项目初始化流程

基本初始化

初始化是创建 OpenSpec 项目结构的核心步骤。在项目根目录下运行：

cd your-project
openspec init

该命令会创建以下目录结构：

project-root/
├── openspec/
│   ├── config.yaml          # 项目配置文件
│   ├── specs/               # 规范文件目录
│   │   └── <schema-name>/
│   │       └── spec.md
│   ├── AGENTS.md            # AI 代理指令文件
│   └── changes/             # 变更记录目录
└── .openspec/               # 内部状态目录

交互式初始化选项

初始化过程支持多种命令行参数：

资料来源：openspec/changes/archive/2025-08-06-add-init-command/design.md

初始化事务机制

OpenSpec 使用原子化目录创建机制，包含事务回滚功能：

interface InitTransaction {
  createdPaths: string[];
  rollback(): Promise<void>;
  commit(): Promise<void>;
}

事务保障：

• 如果创建过程中失败，已创建的文件会被回滚清除
• 防止部分安装导致的脏状态
• 确保初始化要么完全成功，要么完全回滚

资料来源：openspec/changes/archive/2025-08-06-add-init-command/design.md:28-35

项目配置

config.yaml 结构

初始化后生成的 openspec/config.yaml 是项目的核心配置文件：

schema: spec-driven
context:
  projectName: "My Project"
  techStack: []
  conventions: ""
rules: {}

配置字段说明

资料来源：openspec/changes/archive/2026-02-17-project-config/proposal.md

动态指令系统

新版本 OpenSpec 采用三层指令架构：

graph TD
    A[用户运行命令] --> B[Context 上下文层]
    A --> C[Rules 规则层]
    A --> D[Template 模板层]
    B --> E[config.yaml 项目背景]
    C --> F[Artifact-specific 约束]
    D --> G[Schema 定义的模板]
    E --> H[CLI 动态组装]
    F --> H
    G --> H
    H --> I[AI 接收实时指令]

三层职责：

1. Context（上下文）：从 config.yaml 读取项目背景信息
2. Rules（规则）：Artifact 特定的约束条件
3. Template（模板）：Schema 定义的输出文件结构

资料来源：CHANGELOG.md:15-30

Schema 管理

Schema 加载优先级

OpenSpec 按以下顺序查找 Schema：

项目本地的 Schema 会覆盖同名的内置 Schema，实现团队定制化。

资料来源：openspec/changes/archive/2026-02-17-project-local-schemas/design.md

查看可用 Schema

openspec schemas

输出示例：

Available schemas:
  - spec-driven (built-in)
  - custom-schema (project)

更新与维护

升级 CLI

npm update -g @fission-ai/openspec

更新项目配置

当 OpenSpec 发布新版本或项目结构需要同步时：

openspec update

更新操作会：

• 刷新 openspec/AGENTS.md 文件
• 更新现有 artifact 模板
• 清理过时的配置文件

切换实验性工作流

新版 OpenSpec 引入了基于 artifact 的实验性工作流：

openspec experimental

实验性工作流提供以下命令：

资料来源：README.md:55-60

配置文件选择

查看当前使用的配置文件类型：

openspec config profile

可选配置文件类型：

• 旧版配置：生成 CLAUDE.md、.cursorrules 等工具配置文件
• 新版配置：使用 openspec/AGENTS.md 和 config.yaml

资料来源：README.md:50-55

与 AI 工具集成

支持的工具类型

主要支持的 AI 助手

资料来源：README.md:99-130

安全性与最佳实践

安全考量

1. 路径遍历防护：所有用户提供的路径都经过清理验证
2. 文件权限检查：写入前验证目录权限
3. 现有文件保护：未使用 --force 不会覆盖已有文件
4. 模板注入防护：用户输入在模板中被清理

遥测数据收集

OpenSpec 默认收集匿名使用统计：

• 仅收集命令名称和版本号
• 不收集参数、路径、内容或个人信息
• CI 环境中自动禁用

禁用遥测：

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

资料来源：README.md:60-67

快速入门工作流

graph LR
    A[安装 CLI] --> B[初始化项目]
    B --> C[运行 openspec init]
    C --> D[配置 AI 助手]
    D --> E[使用 /opsx:propose 开始]
    E --> F[创建提案]
    F --> G[实现任务]
    G --> H[归档变更]

标准快速入门步骤：

1. 安装 OpenSpec：npm install -g @fission-ai/openspec@latest
2. 进入项目目录：cd your-project
3. 初始化：openspec init
4. 向 AI 助手发送指令：/opsx:propose <你想要构建的功能>

资料来源：README.md:68-78

常见问题

Q: Node.js 版本不满足要求

# 检查版本
node --version

# 使用 nvm 升级
nvm install 20.19.0
nvm use 20.19.0

Q: 初始化失败权限错误

# 检查目录权限
ls -la

# 使用 sudo（不推荐）
sudo openspec init

Q: 想使用实验性工作流

openspec experimental

Q: 想要查看所有可用命令

openspec --help

贡献开发

如需为 OpenSpec 贡献代码：

# 克隆仓库
git clone https://github.com/Fission-AI/OpenSpec.git
cd OpenSpec

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 运行测试
pnpm test

# 本地开发 CLI
pnpm run dev
# 或
pnpm run dev:cli

提交代码使用 conventional commits 格式：type(scope): subject

资料来源：README.md:145-150

概述

OpenSpec 是一个轻量级的规范框架，专为 AI 编程助手设计。其核心目标是让人类开发者和 AI 在编写代码之前先就规范达成共识，从而提高代码质量和项目可预测性。

技术栈要求：

• Node.js 20.19.0 或更高版本
• 支持 pnpm、yarn、bun、nix 等包管理器

资料来源：README.md:1

核心架构分层

OpenSpec 采用分层架构设计，主要分为以下几层：

graph TD
    A[用户/AI 助手] --> B[CLI 交互层]
    B --> C[核心业务层]
    C --> D[Schema 管理]
    C --> E[工件图引擎]
    C --> F[模板系统]
    D --> G[文件系统]
    E --> G
    F --> G

资料来源：openspec/changes/archive/2025-08-06-add-init-command/design.md:1

Schema 系统

Schema 分层结构

OpenSpec 采用三级 Schema 存储策略，优先级从高到低：

graph TD
    A[Schema 解析请求] --> B{检查项目目录}
    B -->|存在| C[openspec/schemas/]
    B -->|不存在| D{检查用户目录}
    D -->|存在| E[~/.local/share/openspec/schemas/]
    D -->|不存在| F[npm 包内置 schemas/]

优先级规则： 当项目本地 schema 与内置 schema 名称相同时，项目本地版本优先。

资料来源：openspec/changes/archive/2026-02-17-project-local-schemas/design.md:3

Schema 解析顺序

工件 Schema 的解析遵循明确的优先级顺序：

1. --schema CLI 参数（显式覆盖）
2. openspec/changes/<name>/.openspec.yaml（变更级别绑定）
3. openspec/config.yaml 的 schema 字段（项目默认）
4. "spec-driven"（硬编码回退值）

资料来源：openspec/changes/archive/2026-02-17-project-config/design.md:4

工件图系统

工件类型

OpenSpec 定义了标准化工件类型，每个变更包含以下工件：

资料来源：schemas/spec-driven/schema.yaml:1

工件状态追踪

工件图引擎负责追踪每个工件的状态，状态包括：

• ready：可以开始创建
• blocked：等待前置依赖完成
• done：已完成

graph LR
    A[proposal] --> B[specs]
    B --> C[design]
    C --> D[tasks]
    D --> E[apply]
    
    A --> C
    B --> D

资料来源：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:5

指令加载机制

指令加载器负责组装动态指令，包含三个层次：

1. Context（上下文）：来自 config.yaml 的项目背景信息
2. Rules（规则）：工件特定的约束条件
3. Template（模板）：输出文件的实际结构

// 指令组装流程
let enrichedInstruction = '';

// 添加上下文（所有工件）
if (projectConfig?.context) {
  enrichedInstruction += `<context>\n${projectConfig.context}\n</context>\n\n`;
}

// 添加规则（仅限匹配的工件）
const rulesForArtifact = projectConfig?.rules?.[artifactId];
if (rulesForArtifact) {
  enrichedInstruction += `<rules>\n${rulesForArtifact.join('\n')}\n</rules>\n\n`;
}

// 添加原始模板
enrichedInstruction += `<template>\n${baseInstructions.template}\n</template>`;

资料来源：openspec/changes/archive/2026-02-17-project-config/design.md:1

命令生成系统

斜杠命令架构

OpenSpec 通过适配器模式支持 25+ AI 工具的斜杠命令：

graph TD
    A[TemplateManager] --> B[SlashCommandConfigurator]
    B --> C[Claude Code 适配器]
    B --> D[Cursor 适配器]
    B --> E[Codex 适配器]
    B --> F[其他工具适配器...]
    
    C --> G[.claude/commands/openspec/]
    D --> H[.cursor/commands/]
    E --> I[项目配置]

命令命名约定：

• Claude Code：使用命名空间 /openspec/proposal、/openspec/apply
• Cursor：使用扁平命名 /openspec-proposal

资料来源：openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1

文件标记规范

斜杠命令文件必须包含特定标记以确保可被正确识别和更新：

概述

OpenSpec 的核心模块围绕变更工件图（Artifact Graph） 构建，提供了从规范定义、工件管理到指令生成的完整技术栈。核心模块采用 TypeScript/Zod 实现类型安全，使用 YAML 定义规范结构，通过模块化设计支持多 schema 扩展。

核心模块的架构设计遵循以下原则：

• 无模板引擎依赖：使用简单的字符串拼接实现上下文注入
• Schema 驱动的资源解析：支持项目级、用户级、包级三层 Schema 解析顺序
• 动态状态检测：基于工件文件存在性自动判断阻塞状态
• Zod Schema 验证：运行时类型检查确保数据完整性

资料来源：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md

核心模块架构

模块目录结构

src/core/artifact-graph/
├── index.ts              # 模块导出入口
├── types.ts              # 类型定义（Zod Schema）
├── schema.ts             # Schema YAML 解析器
├── graph.ts              # 工件图与拓扑排序
├── state.ts              # 状态检测逻辑
├── template.ts           # 模板加载器
├── context.ts            # ChangeContext 加载器
└── instructions.ts       # 指令丰富化与格式化

核心组件关系图

graph TD
    A[Schema.yaml] -->|解析| B[ArtifactGraph]
    B -->|拓扑排序| C[getBuildOrder]
    B -->|状态检测| D[State Detection]
    D --> E{工件状态}
    
    F[Change Context] -->|注入| G[Instructions]
    H[Project Config] -->|上下文| G
    I[Template] -->|内容| G
    
    E -->|done/ready/blocked| J[Status Output]
    G -->|富化指令| K[Agent Output]

Schema 系统

Schema 解析层级

OpenSpec 采用三级 Schema 解析顺序，从高优先级到低优先级排列：

资料来源：openspec/changes/archive/2026-02-17-project-local-schemas/design.md

工件依赖模型

每个 Schema 定义一组工件及其依赖关系：

name: spec-driven
version: 1
artifacts:
  - id: proposal
    generates: "proposal.md"
    template: "proposal.md"
    requires: []
    
  - id: specs
    generates: "specs/*.md"
    template: "specs.md"
    requires:
      - proposal
      
  - id: design
    generates: "design.md"
    template: "design.md"
    requires:
      - proposal
      - specs
      
  - id: tasks
    generates: "tasks.md"
    template: "tasks.md"
    requires:
      - specs
      - design

资料来源：schemas/spec-driven/schema.yaml

类型系统

核心类型定义

types.ts 使用 Zod 定义所有类型约束：

// 工件定义 Schema
const ArtifactSchema = z.object({
  id: z.string(),
  generates: z.string(),
  template: z.string(),
  requires: z.array(z.string()),
});

// Schema YAML 主结构
const SchemaYamlSchema = z.object({
  name: z.string(),
  version: z.number(),
  artifacts: z.array(ArtifactSchema),
});

运行时状态类型

资料来源：openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md

工件图核心

ArtifactGraph 类

工件图类封装所有图相关操作：

export class ArtifactGraph {
  // 从 YAML 文件加载
  static fromYaml(path: string): ArtifactGraph;
  
  // 获取拓扑排序后的构建顺序
  getBuildOrder(): string[];
  
  // 获取单个工件定义
  getArtifact(id: string): ArtifactSchema | undefined;
  
  // 列出所有工件
  getAllArtifacts(): ArtifactSchema[];
}

拓扑排序算法

使用 Kahn 算法实现拓扑排序：

graph LR
    A[proposal] --> B[specs]
    A --> C[design]
    B --> D[tasks]
    C --> D
    
    E[Kahn排序] --> F[proposal]
    F --> G[specs/design]
    G --> H[tasks]

排序特性：

• 保证依赖永远在被依赖项之前
• 循环依赖检测："Cyclic dependency detected: A → B → C → A"
• 无环图验证

资料来源：openspec/changes/archive/2025-12-24-add-artifact-graph-core/tasks.md

Schema 解析器

schema.ts 功能

验证规则

// 依赖引用验证伪代码
for (const artifact of artifacts) {
  for (const reqId of artifact.requires) {
    if (!artifacts.find(a => a.id === reqId)) {
      throw new Error(`Invalid reference: ${artifact.id} requires ${reqId}`);
    }
  }
}

状态检测系统

状态枚举

状态输出格式

## Change: add-auth (spec-driven)

| Artifact | Status | Output |
|----------|--------|--------|
| proposal | done | proposal.md |
| specs | ready | specs/*.md |
| design | blocked (needs: proposal) | design.md |
| tasks | blocked (needs: specs, design) | tasks.md |

资料来源：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md

指令加载系统

指令生成流程

graph TD
    A[loadInstructions] --> B[resolveSchema]
    B --> C[loadTemplate]
    C --> D[loadChangeContext]
    D --> E[loadProjectConfig]
    E --> F[injectContext]
    F --> G[injectRules]
    G --> H[formatXML]
    H --> I[返回富化指令]

上下文注入格式

<context>
Tech stack: TypeScript, React
Project conventions: ...
</context>

<rules>
- Use Given/When/Then format for scenarios
- Reference existing patterns before inventing new ones
</rules>

<template>
## Summary
...
</template>

指令丰富化逻辑

资料来源：openspec/changes/archive/2026-02-17-project-config/design.md

包路径解析

跨环境路径解析

function getPackageSchemasDir(): string {
  const currentFile = fileURLToPath(import.meta.url);
  // 从 src/core/artifact-graph/ 导航到包根目录
  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
}

设计决策：

• 使用 import.meta.url 而非硬编码路径
• 适配 ESM 模块系统
• 相对路径计算确保包内引用正确

项目配置集成

配置 Schema 验证

项目配置文件 openspec/config.yaml 结构：

schema: spec-driven          # 默认 schema
context: |                   # 注入到所有工件的上下文
  Tech stack: TypeScript
  Database: PostgreSQL
rules:                       # 规则（按工件 ID）
  specs:
    - Use Given/When/Then format
  design:
    - Include rollback plan

Schema 解析优先级

1. --schema CLI 参数 (最高优先级)
2. .openspec.yaml (change 目录内)
3. openspec/config.yaml schema 字段
4. "spec-driven" (硬编码默认值)

Schema 解析器详情

schema.ts 核心实现

循环依赖检测算法

function detectCycles(artifacts: Artifact[]): string[] | null {
  const visited = new Set<string>();
  const recursionStack = new Set<string>();
  
  for (const artifact of artifacts) {
    if (hasCycle(artifact.id, artifacts, visited, recursionStack)) {
      return buildCyclePath(recursionStack);
    }
  }
  return null;
}

状态检测实现

state.ts 文件结构

// 状态检测核心逻辑
export interface StateDetectionResult {
  completed: CompletedSet;
  blocked: BlockedArtifacts;
  ready: string[];
}

// 文件存在性检查
function checkArtifactExists(artifact: Artifact, changeDir: string): boolean {
  const path = path.join(changeDir, artifact.generates);
  return fs.existsSync(path);
}

状态计算伪代码

function detectState(graph: ArtifactGraph, changeDir: string): StateResult {
  const completed = new Set<string>();
  const blocked: Record<string, string[]> = {};
  const ready: string[] = [];
  
  for (const artifact of graph.getAllArtifacts()) {
    if (fileExists(artifact, changeDir)) {
      completed.add(artifact.id);
    } else if (canBuild(artifact, completed)) {
      ready.push(artifact.id);
    } else {
      blocked[artifact.id] = getMissingDeps(artifact, completed);
    }
  }
  
  return { completed, blocked, ready };
}

Apply 阶段支持

ApplyPhase Schema 扩展

artifacts:
  - id: proposal
    # ...
apply:
  requires:
    - proposal
    - specs
    - design
    - tasks
  tracks: progress
  instruction: "All artifacts complete. Proceed with implementation."

动态工件检测

与硬编码路径不同，Apply 指令检查逻辑：

// 从 schema 加载要求，而非硬编码
const schema = await resolveSchema(schemaName);
const applyConfig = schema.apply;

// 动态检查所有要求的工件
for (const requiredId of applyConfig.requires) {
  if (!completed.has(requiredId)) {
    return { ready: false, missing: requiredId };
  }
}

最佳实践

Schema 设计原则

1. 最小依赖：每个工件只依赖真正需要的前置项
2. 清晰命名：artifact ID 使用 kebab-case
3. 模板分离：每个 schema 拥有独立的 templates/ 目录
4. 版本控制：schema.yaml 包含 version 字段便于迁移

指令注入最佳实践

错误处理

总结

OpenSpec 的核心模块通过工件图（Artifact Graph） 这一核心概念，将变更管理抽象为工件的有向无环图（DAG）。配合 Zod 类型系统、YAML Schema 定义和模块化的解析器架构，实现了：

• 声明式规范：通过 schema.yaml 定义工件结构和依赖
• 运行时验证：状态检测确保按序创建工件
• 灵活扩展：支持项目级、用户级、包级三层 Schema 定制
• 上下文感知：项目配置和变更上下文自动注入到指令中

这套架构既保持了简单性（无模板引擎依赖），又提供了足够的灵活性来支持复杂的团队工作流程。

概述

变更工作流（Change Workflow）是 OpenSpec 框架的核心功能，它定义了一套标准化的流程，用于管理项目变更的生命周期。该工作流涵盖从变更提议、规格编写、设计文档、任务规划到实现完成并归档的全过程。

OpenSpec 的变更工作流采用 提案 → 应用 → 归档 的三阶段模式，每个阶段都有明确的输入、输出和验收标准，确保人类开发者和 AI 助手之间能够高效协作。

工作流架构

整体流程图

graph TD
    A[开始新变更] --> B{选择工具}
    B --> C[Claude Code]
    B --> D[Cursor]
    B --> E[VS Code]
    B --> F[其他工具]
    
    C --> G[/opsx:propose]
    D --> H[/openspec-proposal]
    E --> I[自然语言请求]
    F --> I
    
    G --> J[创建变更目录]
    H --> J
    I --> J
    
    J --> K[proposal.md]
    K --> L[specs/ 目录]
    L --> M[design.md]
    M --> N[tasks.md]
    N --> O{实现完成?}
    O -->|否| P[继续开发]
    P --> N
    O -->|是| Q[/opsx:archive]
    Q --> R[归档到 archive/]
    R --> S[更新主规格文档]
    
    style G fill:#e1f5fe
    style H fill:#e1f5fe
    style I fill:#fff3e0
    style Q fill:#c8e6c9

变更目录结构

每个变更在 openspec/changes/{change-id}/ 目录下创建完整的工作空间：

归档后，变更目录移至 openspec/changes/archive/{date}-{change-id}/。

提案阶段（Propose）

触发方式

不同 AI 工具通过不同的命令触发提案创建：

提案模板内容

提案文件包含以下标准结构：

概述

工件图系统（Artifact Graph System）是 OpenSpec 的核心子系统，负责管理软件开发变更中的工件（Artifact）及其依赖关系。该系统通过图结构建模工件的创建顺序、依赖状态和生成路径，实现动态指令生成和状态追踪。

核心能力：

• 将工件定义为节点，依赖关系定义为边，构建有向无环图（DAG）
• 基于拓扑排序确定工件创建顺序
• 实时检测工件完成状态（已完成、就绪、阻塞）
• 动态加载模式匹配的指令模板

资料来源：openspec/changes/archive/2025-12-24-add-artifact-graph-core/design.md

概述

OpenSpec 的 AI工具集成系统是一套统一框架，用于将 OpenSpec 工作流程（提案、应用、归档）与多种 AI 编码助手深度整合。通过为每个受支持的 AI 工具生成专用的斜杠命令（Slash Commands）文件，开发者可以在任何主流 AI 辅助编程环境中使用一致的操作方式发起和管理 OpenSpec 变更。

核心设计原则：

• 模板驱动：命令体内容从共享模板生成，保持跨工具一致性
• 最小适配：每个工具只需添加特有的 frontmatter 和路径配置
• 幂等性：支持重复初始化而不破坏现有文件
• 按需更新：更新时仅刷新已存在的文件，不创建新的

资料来源：README.md

支持的AI工具

OpenSpec 目前支持以下 AI 编程助手的斜杠命令集成：

资料来源：README.md:支持AI工具列表

核心架构

组件结构

src/core/command-generation/
├── registry.ts      # 命令注册表，定义所有工具的配置
├── generator.ts     # 命令文件生成器
├── types.ts         # 类型定义
└── adapters/
    └── index.ts     # 工具特定适配器

架构采用适配器模式，每个 AI 工具对应一个适配器，负责处理：

• 目录结构创建
• 文件命名规则
• Frontmatter 格式
• 命令体包装

资料来源：openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:设计理念

工作流程图

graph TD
    A[openspec init] --> B{检测已安装工具}
    B -->|Claude Code| C[生成 .claude/commands/openspec/]
    B -->|Cursor| D[生成 .cursor/commands/]
    B -->|其他工具| E[生成对应目录结构]
    C --> F[复制共享模板]
    D --> F
    E --> F
    F --> G[添加工具特定 frontmatter]
    G --> H[验证标记位置]
    H --> I[初始化完成]
    
    J[openspec update] --> K[扫描已存在的命令文件]
    K --> L{每个已存在文件}
    L -->|更新| M[仅刷新标记内内容]
    L -->|跳过| N[不创建新文件]
    M --> O[报告更新结果]

命令文件格式

标准结构

每个斜杠命令文件遵循统一的 Markdown 格式：

概述

OpenSpec CLI 是项目的核心命令行工具，提供了一套完整的命令集用于管理项目规格、工作流程和变更过程。CLI 采用模块化架构设计，通过子命令模式组织功能，支持交互式操作和脚本化使用两种模式。

CLI 的主要职责包括：

• 初始化 OpenSpec 项目结构
• 创建和管理变更（changes）
• 验证规格文档格式和结构
• 生成和应用 AI 指令
• 管理配置和方案（schemas）

命令架构

OpenSpec CLI 采用树形命令结构，通过 openspec 主命令调用各类子命令和子组。以下是完整的命令层次结构：

graph TD
    A[openspec] --> B[change 子命令组]
    A --> C[spec 子命令组]
    A --> D[config 子命令组]
    A --> E[schema 子命令组]
    A --> F[validate]
    A --> F2[view]
    A --> F3[list]
    A --> F4[instructions]
    A --> F5[status]
    A --> F6[next]
    A --> F7[templates]
    A --> F8[init]
    A --> F9[update]
    A --> F10[archive]
    A --> F11[completion]
    
    B --> B1[new]
    B --> B2[show]
    B --> B3[list]
    B --> B4[archive]
    
    C --> C1[show]
    C --> C2[list]
    C --> C3[validate]
    
    D --> D1[show]
    D --> D2[init]
    
    E --> E1[init]
    E --> E2[list]
    E --> E3[which]
    E --> E4[fork]

全局选项

所有 OpenSpec 命令支持以下全局选项：

变更管理命令

变更（Change）是 OpenSpec 工作流程的核心概念，每个变更代表一个需要实现的功能或修复。

change new - 创建新变更

创建新的变更目录和基础文件结构。

openspec change new <change-name> [options]

可选参数：

示例：

# 创建新变更
openspec change new add-dark-mode

# 指定 schema
openspec change new add-auth --schema tdd

# 非交互模式
openspec change new fix-login-bug --yes

创建完成后会生成以下文件结构：

openspec/changes/<change-name>/
├── proposal.md       # 变更提案
├── specs/           # 规格文档目录
├── design.md       # 技术设计方案
├── tasks.md        # 实现任务清单
└── .openspec.yaml  # 变更元数据

change show - 查看变更详情

显示指定变更的详细信息，包括各制品的状态和内容。

openspec change show <change-name> [options]

change list - 列出所有变更

列出所有活跃的变更（未归档）。

openspec change list [options]

change archive - 归档变更

将完成的变更移动到归档目录。

openspec change archive <change-name> [options]

归档后的变更会被移动到 openspec/changes/archive/ 目录。

制品工作流命令

制品（Artifact）是 OpenSpec 方案定义的核心产物，每个制品有独立的状态和依赖关系。

status - 查看制品状态

显示变更中所有制品的状态和依赖关系。

openspec status <change-name> [options]

输出格式示例：

状态说明：

• done - 制品已完成
• ready - 制品可以开始
• blocked - 等待依赖制品完成

next - 查看下一个可执行制品

显示当前可以开始工作的制品列表。

openspec next <change-name> [options]

instructions - 获取 AI 指令

为指定制品生成 AI 助手指令。

openspec instructions <artifact> --change <change-name> [options]

输出示例：

<context>
Tech stack: TypeScript, React
</context>

<rules>
- Use Given/When/Then format for scenarios
- Reference existing patterns before inventing new ones
</rules>

<template>
[Schema's template content]
</template>

templates - 查看模板

显示指定制品的模板内容。

openspec templates <artifact> [options]

规格命令

规格（Spec）命令用于管理和验证项目规格文档。

spec show - 显示规格

显示指定规格文档的内容。

openspec spec show <spec-name> [options]

spec list - 列出规格

列出所有已定义的规格。

openspec spec list [options]

spec validate - 验证规格

验证规格文档的格式和结构。

openspec spec validate [spec-name] [options]

配置命令

配置命令用于管理项目级配置。

config show - 显示配置

显示当前项目的 OpenSpec 配置。

openspec config show [options]

config init - 初始化配置

创建项目配置文件。

openspec config init [options]

Schema 管理命令

Schema 定义了制品的结构、工作流程和验证规则。

schema init - 创建新 Schema

创建新的 schema 方案。

openspec schema init <name> [options]

示例：

# 交互式创建
openspec schema init my-schema

# 非交互式创建
openspec schema init tdd --description "Test-driven development workflow" --artifacts "proposal,specs,tests,design,tasks" --default

schema list - 列出 Schema

列出所有可用的 schema。

openspec schema list [options]

schema which - 显示当前 Schema

显示当前变更或项目使用的 schema。

openspec schema which [change-name] [options]

schema fork - 派生 Schema

从现有 schema 派生新的 schema。

openspec schema fork <source> --name <new-name> [options]

项目命令

init - 初始化项目

在当前目录初始化 OpenSpec 项目结构。

openspec init [options]

初始化后生成的文件结构：

├── openspec/
│   ├── config.yaml          # 项目配置
│   ├── specs/               # 规格目录
│   │   └── <capability>/    # 能力子目录
│   │       └── spec.md
│   └── changes/             # 变更目录
│       └── archive/         # 归档目录
├── AGENTS.md               # AI 助手说明
└── CLAUDE.md               # Claude Code 集成

view - 可视化仪表板

启动交互式命令行仪表板查看项目状态。

openspec view [options]

list - 列出变更

显示所有活跃变更的概览。

openspec list [options]

archive - 归档变更

归档指定的变更。

openspec archive <change-name> [options]

validate - 验证变更

验证变更文档的格式和结构。

openspec validate <change-name> [options]

update - 更新配置

刷新 AI 工具的斜杠命令配置文件。

openspec update [options]

Shell 补全

生成 shell 补全脚本以支持命令自动补全。

openspec completion <shell> [options]

安装示例：

# Bash
openspec completion bash >> ~/.bashrc

# Zsh
openspec completion zsh >> ~/.zshrc

# Fish
openspec completion fish > ~/.config/fish/completions/openspec.fish

工作流程示例

完整变更工作流程

graph LR
    A[1. openspec change new<br/>add-login-feature] --> B[2. 创建制品]
    B --> C[3. openspec instructions<br/>proposal --change<br/>add-login-feature]
    C --> D[4. AI 生成 proposal.md]
    D --> E[5. openspec instructions<br/>specs --change<br/>add-login-feature]
    E --> F[6. AI 生成 specs]
    F --> G[7. openspec instructions<br/>design --change<br/>add-login-feature]
    G --> H[8. AI 生成 design.md]
    H --> I[9. openspec instructions<br/>tasks --change<br/>add-login-feature]
    I --> J[10. AI 生成 tasks.md]
    J --> K[11. openspec archive<br/>add-login-feature]

Schema 创建工作流程

# 1. 创建新 schema
openspec schema init tdd \
  --description "Test-driven development workflow" \
  --artifacts "proposal,specs,tests,design,tasks" \
  --default

# 2. 在新变更中使用
openspec change new feature-x --schema tdd

# 3. 派生自定义 schema
openspec schema fork tdd --name my-tdd

错误处理

CLI 命令可能返回以下常见错误：

资料来源

• 命令架构设计：README.md
• 变更管理命令：openspec/changes/archive/2025-12-28-add-artifact-workflow-cli/tasks.md
• Schema 管理：openspec/changes/archive/2026-02-17-schema-management-cli/tasks.md
• 配置系统：openspec/changes/archive/2026-02-17-project-config/design.md
• 制品工作流：openspec/changes/archive/2025-12-28-add-instruction-loader/design.md

概述

工作流模板是 OpenSpec 框架中用于标准化 AI 代理与用户之间交互的核心组件。它们定义了从项目构思到实现完成的完整开发周期中的各个阶段指导。OpenSpec 采用流体而非僵化的哲学，工作流模板允许团队在任何阶段灵活更新产物，无需严格的阶段门控。

工作流模板系统的主要作用包括：

• 标准化交互模式：为 AI 代理提供一致的指令格式和执行步骤
• 阶段引导：将复杂项目分解为可管理的阶段（提议、规格说明、设计、任务、实现、验证）
• 工具集成：支持 20+ AI 助手通过斜杠命令进行交互
• 工件驱动：每个变更（change）拥有独立的文件夹，包含提议、规格说明、设计和任务

资料来源：docs/workflows.md

工作流类型

OpenSpec 定义了六种核心工作流类型，每种工作流对应项目开发周期的不同阶段：

资料来源：src/core/templates/index.ts

工作流执行流程

标准开发周期

graph TD
    A[用户发起需求] --> B[Propose 工作流]
    B --> C[创建变更文件夹]
    C --> D[生成 Proposal]
    D --> E[用户确认提议]
    E --> F[Apply 工作流]
    F --> G[规格说明 & 设计]
    G --> H[Continue 工作流]
    H --> I[任务执行]
    I --> J[Verify 工作流]
    J --> K{验证通过?}
    K -->|是| L[归档变更]
    K -->|否| H
    L --> M[项目更新完成]

工作流切换流程

stateDiagram-v2
    [*] --> Propose: 用户输入需求
    Propose --> Apply: 规格确认
    Apply --> Continue: 开始实现
    Continue --> Verify: 任务完成
    Verify --> Continue: 需要修改
    Verify --> Archive: 验证通过
    Archive --> Propose: 新需求

资料来源：docs/workflows.md

提议工作流 (Propose)

提议工作流是项目开发的起点，用于在编写任何代码之前对齐需求。

执行步骤

提议工作流包含以下标准步骤：

1. 理解需求：AI 代理确认理解用户的需求描述
2. 澄清问题：如有必要，提出 1-2 个澄清性问题
3. 遵循复杂度规则：遵循最小复杂度原则，使用 pnpm 作为包管理器
4. 创建变更结构：创建 openspec/changes/<change-name>/ 目录
5. 生成提议文件：创建 proposal.md 文档
6. 验证：运行验证命令确保结构正确
7. 确认：等待用户确认后再继续

提议文件格式

提议文件包含以下标准结构：

系统架构

配置系统采用分层架构设计，区分全局配置与项目配置两个层级。全局配置位于用户主目录的固定位置，用于存储用户级别的偏好设置；项目配置则位于每个仓库的 openspec/config.yaml，用于定义团队共识的开发规范。

graph TD
    A[CLI 命令] --> B{配置解析层}
    B --> C[全局配置<br/>~/.config/openspec/config.yaml]
    B --> D[项目配置<br/>openspec/config.yaml]
    B --> E[变更元数据<br/>.openspec.yaml]
    B --> F[CLI 参数]
    
    C --> G[Schema 解析器]
    D --> G
    E --> G
    F --> G
    
    G --> H[Instruction Loader]
    H --> I[上下文注入<br/>&lt;context&gt;]
    H --> J[规则注入<br/>&lt;rules&gt;]
    H --> K[模板输出<br/>&lt;template&gt;]

配置类型

全局配置

全局配置存储在用户主目录的 OpenSpec 配置目录中，适用于用户个人的偏好设置。当前实现中，全局配置主要用于用户级别的路径和默认行为管理。

// 资料来源：src/core/global-config.ts
export function getGlobalConfigPath(): string {
  const home = os.homedir();
  return path.join(home, '.config', 'openspec', 'config.yaml');
}

项目配置

项目配置通过 openspec/config.yaml 文件管理，是配置系统的核心组成部分。该文件定义了项目使用的 schema、上下文信息、以及针对不同 artifact 的规则。

# 资料来源：openspec/config.yaml
schema: spec-driven
context: |
  Tech stack: TypeScript, React, Node.js
  Team conventions: PR requires 2 approvals

rules:
  proposal:
    - Include impact analysis
    - Reference related issues
  specs:
    - Use Given/When/Then format
    - Every requirement needs scenarios

Schema 解析机制

解析优先级

OpenSpec 采用明确的优先级顺序解析 schema，确保最具体的配置优先生效：

graph LR
    A[1. CLI --schema 参数] -->|最高优先级| Z[最终 Schema]
    B[2. 变更元数据<br/>.openspec.yaml] -->|次高| Z
    C[3. 项目配置<br/>openspec/config.yaml] -->|项目默认| Z
    D[4. 硬编码默认值<br/>spec-driven] -->|最低优先级| Z

1. CLI 参数：--schema <name> 显式指定的 schema 拥有最高优先级
2. 变更元数据：每个变更目录下的 .openspec.yaml 中的 schema 字段
3. 项目配置：openspec/config.yaml 中定义的 schema 作为项目默认值
4. 硬编码默认值：若以上均未指定，使用 spec-driven 作为 fallback

// 资料来源：src/core/project-config.ts
export function resolveSchemaForChange(
  changeName: string,
  cliSchema?: string
): string {
  // 1. CLI flag wins
  if (cliSchema) {
    return cliSchema;
  }

  // 2. Change metadata (.openspec.yaml)
  const metadata = readChangeMetadata(changeName);
  if (metadata?.schema) {
    return metadata.schema;
  }

  // 3. Project config
  const projectConfig = readProjectConfig();
  if (projectConfig?.schema) {
    return projectConfig.schema;
  }

  // 4. Hardcoded default
  return 'spec-driven';
}

Schema 存储位置

Schema 文件可从三个位置加载，优先级依次递减：

graph TD
    A[Schema 解析请求] --> B{查找项目本地}
    B -->|存在| C[使用项目本地版本]
    B -->|不存在| D{查找用户覆盖}
    D -->|存在| E[使用用户覆盖版本]
    D -->|不存在| F{查找包内置}
    F -->|存在| G[使用包内置版本]
    F -->|不存在| H[错误：Schema 不存在]

冲突处理原则：若项目本地 schema 与内置 schema 名称相同，项目本地版本会覆盖（shadow）内置版本，这是有意为之的设计，允许团队自定义内置行为同时保持命名一致性。

上下文与规则注入

注入格式

配置系统使用 XML 风格标签将上下文和规则注入到生成的 artifacts 中：

<context>
[项目上下文内容]
</context>

<rules>
- [规则1]
- [规则2]
</rules>

<template>
[原始模板内容]
</template>

这种格式选择基于以下考虑：清晰的边界分隔符避免与 Markdown 内容冲突，便于 AI Agent 解析结构，同时保持良好的可读性。

上下文注入（Context）

上下文信息会自动添加到所有 artifacts 的说明中，用于向 AI 提供项目级背景知识：

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JWT auth
  Team size: 5 developers

生成的 artifacts 会包含：

<context>
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JWT auth
Team size: 5 developers
</context>

<template>
## Summary
...
</template>

规则注入（Rules）

规则配置针对特定 artifact 类型生效，仅当加载对应 artifact 的说明时才会注入：

rules:
  proposal:
    - Include impact analysis
    - Reference related issues
  specs:
    - Use Given/When/Then format
    - Every requirement needs scenarios
  design:
    - Include rollback plan

# 获取 specs artifact 的说明（包含 rules）
openspec instructions specs --change my-feature
# 输出包含 <context>、<rules> 和 <template>

# 获取 design artifact 的说明（不包含 rules）
openspec instructions design --change my-feature
# 输出包含 <context> 和 <template>，无 <rules>

规则验证

规则配置中的 artifact ID 会进行懒加载验证，验证时机在 instruction 加载时而非 config 加载时，这样可以避免循环依赖并提供更好的用户体验。

// 资料来源：openspec/changes/archive/2026-02-17-project-config/design.md
// 验证时机选择理由：
// 1. Schema 在 config 加载时未知（循环依赖）
// 2. 用户实际使用功能时显示警告更友好
// 3. 警告信息按会话缓存避免重复提示

配置验证

Schema 名称验证

系统会验证配置中引用的 schema 名称是否有效：

// 资料来源：src/core/project-config.ts
export function validateProjectConfig(config: ProjectConfig): ValidationResult {
  // ... 验证逻辑
  
  const allSchemas = [...builtIn, ...projectLocal];
  if (config.schema && !allSchemas.includes(config.schema)) {
    return {
      valid: false,
      error: `Invalid schema: ${config.schema}`,
      hint: `Built-in: ${builtIn.join(', ')}\nProject-local: ${projectLocal.join(', ')}`
    };
  }
}

错误消息格式

验证失败时的错误消息包含以下信息：

{
  "valid": false,
  "error": "Invalid schema: custom-schema",
  "hint": "Available schemas:\n  Built-in: spec-driven, tdd\n  Project-local: (none found)\n\nFix: Edit openspec/config.yaml and change 'schema: custom-schema' to a valid schema name"
}

团队协作

共享配置

配置文件的协作流程如下：

# 提交配置到版本控制
git add openspec/config.yaml
git commit -m "Add project config with context and rules"

# 团队成员自动获得相同的上下文和规则

所有团队成员克隆仓库后会立即获得相同的项目上下文和规范要求，无需手动同步或口头传达。

配置迁移

旧的 openspec/project.md 文件不会自动删除，系统会提示用户手动迁移内容到 config.yaml 的 context: 字段：

openspec/project.md still exists - migrate content to config.yaml's context: field, then delete

手动迁移的原因：

• project.md 可能包含用户编写的详细文档
• 自动压缩为 context 字段需要 LLM 协助
• 避免意外丢失有价值的内容

命令行集成

配置系统与 CLI 命令深度集成：

# 使用项目配置的 schema 创建变更
openspec create add-auth

# 使用显式 schema 覆盖项目配置
openspec create add-auth --schema tdd

# 验证配置有效性
openspec validate

最佳实践

配置组织建议

1. 保持 context 简洁：context 字段应保持简洁精炼，避免冗长的说明文字
2. 规则按 artifact 分类：将规则按对应的 artifact 类型组织，便于理解和维护
3. 使用具体场景描述：规则应描述具体场景而非抽象原则

示例配置

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React 18, Node.js 20
  API: RESTful with JWT authentication
  Testing: Vitest + React Testing Library
  Deployment: Docker, Kubernetes

rules:
  proposal:
    - Include estimated effort (hours)
    - Reference related issues or PRs
  specs:
    - Use Given/When/Then format
    - Minimum one scenario per requirement
    - Reference existing patterns before inventing new ones
  design:
    - Include error handling strategy
    - Document API contracts with examples

相关资源

• 自定义文档 - 包含社区 schema 和扩展配置
• Schema 开发指南 - 如何创建项目本地 schema
• 项目配置提案 - 配置系统设计背景

Pitfall Log / 踩坑日志

项目：Fission-AI/OpenSpec

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas。

1. 配置坑 · 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。

2. 维护坑 · 来源证据：open:sync messed up my spec.md files

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：First steps don't work

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：v1.2.0 - Profiles, Pi & Kiro Support

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.2.0 - Profiles, Pi & Kiro Support
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cb21ca0230d94a0daf4eb6cf43c4a361 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.2.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：v1.3.0 - New Tool Integrations

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.0 - New Tool Integrations
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_382a148d0b88420396bb7da33461ab12 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.0 | 来源类型 github_release 暴露的待验证使用条件。

7. 安装坑 · 来源证据：v1.3.1 - Path & Telemetry Fixes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：Incomplete artifacts marked as "done" after workflow interruption

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as "done" after workflow interruption
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。

9. 配置坑 · 来源证据：OpenCode sync missing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。

10. 配置坑 · 来源证据：v0.22.0 - Project Configuration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。

11. 配置坑 · 来源证据：v1.0.0 - The OPSX Release

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。

12. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.

13. 运行坑 · 来源证据：v1.0.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。

14. 运行坑 · 来源证据：v1.0.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。

15. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing

16. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium

17. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | No sandbox install has been executed yet; downstream must verify before user use.

18. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium

19. 安全/权限坑 · 来源证据：Protect OpenSpec from AI slop PRs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect OpenSpec from AI slop PRs
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a941eca296774492b16583764132d1f8 | https://github.com/Fission-AI/OpenSpec/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。

20. 安全/权限坑 · 来源证据：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_abcb3cf5661b4a19862619c854eb531d | https://github.com/Fission-AI/OpenSpec/issues/1081 | 来源类型 github_issue 暴露的待验证使用条件。

21. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | release_recency=unknown