OpenSpec 完整从零搭建部署流程

前置说明

OpenSpec 官方包：@fission-ai/openspec，基于 Node.js 开发，跨平台（Windows/macOS/Linux），支持前端、Go、Java、Python 全栈项目。 环境要求：

1. Node.js ≥ 18.16.0（LTS 版本）
2. npm /pnpm/yarn 包管理器
3. Git（规范文件随仓库托管）
4. VSCode / Cursor / JetBrains IDE（推荐搭配 AI 插件使用）

一、全局安装 OpenSpec CLI

1. 安装命令

2. 验证安装成功

二、项目初始化（两种方式：新建项目 / 已有老项目接入）

方式 1：已有存量项目接入（90% 场景）

进入你的项目根目录执行初始化：

执行后交互式问答配置：

1. Project name：项目名称（自定义）
2. Tech stack：技术栈（go/java/ts/python/html 多选）
3. Enable git sync：是否绑定 Git（输入 y）
4. Enable CI lint check：是否开启流水线校验（按需 y/n）
5. Enable MCP AI 服务：是否开启 AI 规范自动解析（推荐 y）

执行完成后自动生成标准目录：

方式 2：全新空白项目创建

自动生成基础项目结构 + 预置示例 spec 模板。

三、核心配置文件 openspec/config.yaml 详解

初始化后自动生成，按需修改配置：

四、IDE 插件配置（Cursor/VSCode 必备，AI 联动）

1. VSCode / Cursor 安装扩展

搜索插件：OpenSpec Helper 安装后自动识别项目内 openspec/ 目录，提供：

• 侧边栏规范树浏览
• /opsx:* 斜杠指令快捷输入
• spec 文件语法高亮、自动补全
• 一键校验、一键归档按钮

2. IDE 本地 MCP 服务启动（AI 读取规范）

服务默认端口：3128，在 AI 工具 MCP 配置中填入地址： http://localhost:3128/mcp

五、标准开发完整流程（从需求到归档闭环）

步骤 1：创建变更提案（新增功能 / 迭代需求）

自动生成文件： openspec/changes/20260703-user-login-lock/

• delta.md：本次改动范围、新旧差异
• task.md：AI 编码执行任务清单
• draft_spec.md：草稿规范文档

打开 draft_spec.md 填写完整需求、场景、验收用例。

步骤 2：AI 根据规范生成代码

在 IDE AI 对话框输入斜杠指令：

AI 会自动读取当前变更目录下所有规范，严格按照需求编写代码，不会超出规范实现额外逻辑。

步骤 3：规范与代码一致性校验

代码写完后执行校验命令，自动对比代码逻辑是否匹配 spec：

输出校验报告：

• 通过：All code match spec standard
• 不匹配：列出文件、不满足的场景、修复建议

步骤 4：修正代码后同步规范

自动修正简单不匹配问题，复杂逻辑人工修改代码后重新 check。

步骤 5：验收通过，归档规范（闭环）

功能自测、评审完成后执行归档，将本次变更合并至全局基准 specs：

效果：

1. changes 下本次变更归档至历史备份
2. 完整规范合并进 openspec/specs/ 永久保存
3. 更新版本号，写入 Git 提交记录

六、Git 协作配置（团队多人开发）

1. 提交时自动校验（可选）

安装 husky 配合 OpenSpec 实现提交拦截：

配置后每次 git commit 自动校验代码与规范一致性。

2. 团队拉取更新规范

其他开发人员拉取代码后，同步本地规范索引：

七、CI/CD 流水线集成（以 GitHub Actions 为例）

在 .github/workflows/openspec-lint.yml 添加流水线校验：

PR 提交自动校验代码与规范是否匹配，不匹配直接阻断合并。

八、常用核心命令速查表

九、常见问题排查

1. 命令找不到：Node 全局路径未加入系统环境变量，重装 Node 后重新全局安装
2. MCP 服务启动端口占用：修改 config.yaml 中 mcp_port 更换端口
3. 校验一直不通过：检查 spec 中场景、入参、异常逻辑与代码是否一致
4. 初始化无目录权限：使用管理员终端执行初始化命令

十、卸载（如需）