TL;DR

  • 推荐使用“免安装”方式直接运行：npx openspec@latest --version
  • 首次在仓库根目录执行：openspec init 或 openspec update（会生成/刷新 openspec 指南文件）
  • 常用命令：openspec list、openspec list --specs、openspec validate <change-id> --strict

本文给出面向团队的多种安装分发方案。若你在公司/内网环境，请按团队提供的渠道优先安装；若尚未统一分发，可先用“免安装”方案快速上手。

环境要求

  • 操作系统：macOS / Linux / Windows(建议 WSL)
  • Git：2.30+
  • Node.js：建议 LTS（≥ 18）用于 npx/dlx 方式

安装方式（任选其一）

方式 A：免安装（推荐，最快速）

适合本地快速试用、CI 临时调用。

# 使用 npx（npm 自带）
npx openspec@latest --version
npx openspec@latest list

# 若使用 pnpm / yarn：
pnpm dlx openspec@latest --version
yarn dlx openspec@latest --version

说明：以上命令假设团队通过 npm 分发 OpenSpec CLI。如你们采用其它渠道，请改用下述方式。

方式 B：npm 全局安装（常驻本机）

npm i -g openspec
# 验证
openspec --version

注：包名可能因团队命名空间不同（如 @your-scope/openspec）而变化，请以实际分发为准。

方式 C：Homebrew（若团队提供 tap）

# 示例（以你们团队实际 tap 为准）
brew tap your-org/tap
brew install openspec
openspec --version

方式 D：二进制/内网分发（离线可用）

  1. 从团队内网或发布页下载与你系统匹配的二进制包（macOS/Linux/Windows）。
  2. 将可执行文件放入 PATH（如 ~/bin、/usr/local/bin 或 Windows 的 PATH 目录）。
  3. 赋予可执行权限：chmod +x ~/bin/openspec。
  4. 验证：openspec --version。

方式 E：Docker（可选）

docker run --rm -v "$(pwd)":/work -w /work your-registry/openspec:latest openspec --version

首次初始化（在仓库根目录）

# 生成/刷新指导文件与模板
openspec init        # 或
openspec update

# 验证仓库内 OpenSpec 工作流命令
openspec list
openspec list --specs

生成内容与规范请参考：openspec/AGENTS.md 与 openspec/project.md。

快速验证

# 新建或选取一个变更 ID（示例）
CHANGE=add-sample-feature

# 按需创建目录与最小示例（可手动创建文件）
mkdir -p openspec/changes/$CHANGE/specs/demo
cat > openspec/changes/$CHANGE/specs/demo/spec.md << 'EOF'
## ADDED Requirements
### Requirement: Sample Feature
系统 SHALL 提供一个示例能力，便于校验安装无误。

#### Scenario: Basic
- **WHEN** 运行校验
- **THEN** 变更通过最小语法检查
EOF

# 严格校验（提交前建议必跑）
openspec validate $CHANGE --strict

更多命令与规范细节，见 openspec/AGENTS.md 的「Quick Start / Troubleshooting」。

常见问题（FAQ）

  • 提示 “command not found: openspec”
    • 使用免安装命令：npx openspec@latest ...；或确认 PATH 已包含可执行文件目录。
  • 提示权限问题（Permission denied）
    • 为二进制赋权：chmod +x path/to/openspec；macOS 可能需要在「系统设置-隐私与安全」允许。
  • 企业代理/离线环境
    • 优先采用二进制/内网源；npm 需配置代理：npm config set proxy http://...。
  • Windows 环境
    • 推荐 WSL；或使用 Docker 方式。

下一步

  • 入门到进阶实践：参阅《AI 时代，掌握 OpenSpec：SDD 规格驱动开发完整指南》
    • 直达链接：/tutorials/openspec-sdd-intro/
  • 规范与命令权威说明：openspec/AGENTS.md、openspec/project.md

如需补充你们团队的专用安装渠道（内网地址/脚本），告诉我链接或脚本名称，我可以将其加到本文并提供一键验证脚本片段。