第二章:安装与配置

环境要求

检查 Node.js 版本:

node --version

如果版本不够,请先升级 Node.js:


安装 OpenSpec

全局安装(推荐)

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 add -g @fission-ai/openspec@latest

验证安装

openspec -V

应该输出类似:1.2.0


初始化项目

全新项目

# 创建项目目录
mkdir my-project
cd my-project

# 初始化 OpenSpec
openspec init

输出示例:

✓ Created openspec/ directory
✓ Created openspec/changes/ directory
✓ Created openspec/archive/ directory
✓ Created AGENTS.md
✓ Initialized OpenSpec in my-project/

已有项目

# 直接进入已有项目目录
cd existing-project

# 初始化(不会覆盖现有文件)
openspec init

OpenSpec 是非侵入式的,不会修改你的现有代码。


项目结构

初始化后,你的项目会有:

my-project/
├── openspec/                 # OpenSpec 目录
│   ├── changes/             # 正在进行的变更
│   │   └── (空)
│   └── archive/             # 已完成的变更
│       └── (空)
├── AGENTS.md                # AI 助手配置
└── (你的原有项目文件)

AGENTS.md 文件

这是给 AI 助手看的配置文件,包含 OpenSpec 的 AI-native 命令定义。


配置工作流

查看当前配置

openspec config list

选择工作流

OpenSpec 支持通过 --profile 选择工作流模式:

# 查看可用的工作流预设
openspec config profile

# 应用预设(如 core)
openspec init --profile core
openspec init --profile <preset-name>

查看所有可用配置项

openspec config list
openspec config get <key>     # 查看某个配置值
openspec config set <key> <value>  # 设置某个配置值
openspec config path          # 查看配置文件路径

配置 AI 工具

初始化时指定 AI 工具

openspec init --tools claude,cursor,github-copilot

支持的 AI 工具(逗号分隔): amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae, windsurf

查看变更状态

# 查看当前项目中所有变更的状态
openspec status

# 查看指定变更的完成状态
openspec status --change <change-name>

第一个命令

安装完成后,试试第一个命令:

# 在项目目录中,创建新的变更
openspec new change "add-readme"

或者在 AI 工具中使用 AI-native 命令:

/opsx:propose "添加一个 README 文件"

AI 会创建:

openspec/changes/add-readme/
├── proposal.md
├── specs/
├── design.md
└── tasks.md

查看生成的文件,了解 OpenSpec 的文档结构。


常见问题

Q: 安装失败,提示权限错误

# macOS/Linux
sudo npm install -g @fission-ai/openspec@latest

# 或使用 npx(无需安装)
npx @fission-ai/openspec@latest

Q: 命令找不到

# 检查 npm 全局安装路径
npm config get prefix

# 确保路径在 PATH 中
export PATH="$PATH:$(npm config get prefix)/bin"

Q: 如何更新 OpenSpec

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

下一步

→ 第三章:核心命令