OpenSpec 完整从零搭建部署流程

前置说明OpenSpec 官方包fission-ai/openspec基于 Node.js 开发跨平台Windows/macOS/Linux支持前端、Go、Java、Python 全栈项目。 环境要求Node.js ≥ 18.16.0LTS 版本npm /pnpm/yarn 包管理器Git规范文件随仓库托管VSCode / Cursor / JetBrains IDE推荐搭配 AI 插件使用一、全局安装 OpenSpec CLI1. 安装命令2. 验证安装成功二、项目初始化两种方式新建项目 / 已有老项目接入方式 1已有存量项目接入90% 场景进入你的项目根目录执行初始化执行后交互式问答配置Project name项目名称自定义Tech stack技术栈go/java/ts/python/html 多选Enable git sync是否绑定 Git输入 yEnable CI lint check是否开启流水线校验按需 y/nEnable 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.mdAI 编码执行任务清单draft_spec.md草稿规范文档打开draft_spec.md填写完整需求、场景、验收用例。步骤 2AI 根据规范生成代码在 IDE AI 对话框输入斜杠指令AI 会自动读取当前变更目录下所有规范严格按照需求编写代码不会超出规范实现额外逻辑。步骤 3规范与代码一致性校验代码写完后执行校验命令自动对比代码逻辑是否匹配 spec输出校验报告通过All code match spec standard不匹配列出文件、不满足的场景、修复建议步骤 4修正代码后同步规范自动修正简单不匹配问题复杂逻辑人工修改代码后重新 check。步骤 5验收通过归档规范闭环功能自测、评审完成后执行归档将本次变更合并至全局基准 specs效果changes 下本次变更归档至历史备份完整规范合并进openspec/specs/永久保存更新版本号写入 Git 提交记录六、Git 协作配置团队多人开发1. 提交时自动校验可选安装 husky 配合 OpenSpec 实现提交拦截配置后每次 git commit 自动校验代码与规范一致性。2. 团队拉取更新规范其他开发人员拉取代码后同步本地规范索引七、CI/CD 流水线集成以 GitHub Actions 为例在.github/workflows/openspec-lint.yml添加流水线校验PR 提交自动校验代码与规范是否匹配不匹配直接阻断合并。八、常用核心命令速查表九、常见问题排查命令找不到Node 全局路径未加入系统环境变量重装 Node 后重新全局安装MCP 服务启动端口占用修改config.yaml中 mcp_port 更换端口校验一直不通过检查 spec 中场景、入参、异常逻辑与代码是否一致初始化无目录权限使用管理员终端执行初始化命令十、卸载如需