第二章:安装与配置
环境要求
- Node.js: 20.19.0 或更高版本
- npm: 10.x 或更高版本
检查 Node.js 版本:
node --version
如果版本不够,请先升级 Node.js:
- 官网下载:https://nodejs.org/
- 或使用 nvm/fnm 管理版本
安装 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
下一步
→ 第三章:核心命令