OpenSpec 中文教程：先审 proposal 和 specs，再让代理写代码
OpenSpec 把一次代码改动拆成 proposal、specs、design 和 tasks。它们保存在项目的 openspec 目录里，可以和代码一起审查。代理在实现前先把需求和方案写清楚，完成后再归档该变更。
1. 安装并在测试项目初始化
node --version
npm install -g @fission-ai/openspec@latest
openspec --version
cd your-test-project
openspec initNode.js 必须是 20.19.0 或更高版本。初始化时选择实际使用的编码助手，并保存命令输出。OpenSpec 会按客户端生成不同调用形式，所以不要从别人的教程复制 slash command。
2. 从 explore 或 propose 开始
想法还不明确时先用 /opsx:explore。范围已经清楚时，使用 init 输出里的 propose 命令。官方示例会创建 proposal.md、specs、design.md 和 tasks.md。逐项检查动机、边界、验收场景、技术方案与任务顺序，确认后才进入 apply。
Codex 里可能显示 $openspec-propose，Cursor 或 GitHub Copilot 可能显示 /opsx-propose。官方文档把 /opsx:propose 当作规范名称，真实输入形式由客户端决定。
3. apply、validate 与 archive
apply 让代理按 tasks 实现。完成后既要运行项目自己的测试，也要用 OpenSpec 校验规格结构。确认需求、实现和任务状态一致后再 archive。v1.13.1 会拒绝部分大小写冲突、无效 rename 和未读取的 delta，并加强空场景、任务标记和 schema 依赖检查。
扩展 profile 另有 new、continue、ff、verify 等命令。切换 profile 后要运行 openspec update 重新生成项目指引，不能假定默认 profile 包含全部命令。
4. 和 GitHub Spec Kit 怎么选
相比 GitHub Spec Kit，OpenSpec 更集中在单项变更的 proposal、specs、design、tasks 和归档，并以 Node CLI 适配多种编码助手。Spec Kit 把规格驱动开发、修复和想法评估做成独立流程入口，要求 Python 3.11+ 与 uv。Node 项目想先采用轻量变更目录，可从 OpenSpec 开始；需要更宽的流程、extension 和 preset 体系时，再评估 Spec Kit。
5. 验证状态与验证边界
验证边界：生成目录、客户端命令、propose/apply/archive、validate、安全修复和 Stores 都未本机实测。Stores 在官方 README 中仍标为 beta，生产使用前应另测权限、同步和回滚。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
AI 编码任务一旦跨多个文件或会话，仅靠聊天历史很难保留需求边界。OpenSpec 用可提交的变更目录把计划与实现分开，还能覆盖已有代码库和多种编码助手。这些累计值不能解释为独立用户。
原教程未展开的系统信息
核心功能
多工具命令生成
同一动作会按客户端采用不同调用形式，openspec init 会打印已选择工具的实际命令；官方当前称支持 30 多种工具。
校验与安全归档
v1.13.1 加强配置注入、卡死文件和 .npmrc 更新重定向防护，并让 validate 检查缺失 delta、空场景和任务复选框等问题。
架构与数据流
Node.js CLI 通过 openspec init 在项目中建立 openspec 目录和客户端命令。变更材料以 Markdown 保存，schema 定义产物及其依赖；代理命令负责生成、继续、应用、校验和归档。项目代码是 TypeScript，发布为 @fission-ai/openspec，package.json 当前版本与 Latest release 都是 1.13.1。
常见问题
OpenSpec 在 Codex 里为什么不是 /opsx:propose？
官方说明不同客户端会改写命令形式，Codex 可能显示 $openspec-propose，Cursor 或 GitHub Copilot 可能使用 /opsx-propose。以 openspec init 为所选工具打印的命令为准。
OpenSpec 的 propose、apply 和 archive 分别做什么？
propose 建立提案、规格、设计和任务；apply 按已审查的任务实现；archive 在完成验证后归档变更并更新规格。不要跳过人工审查直接把 propose 接到 apply。
OpenSpec v1.13.1 改了哪些安全问题？
官方 release notes 记录了 config.yaml 指令注入、恶意文件让 update/archive 卡死，以及仓库 .npmrc 重定向更新检查等加固，同时加强归档和规格校验。
OpenSpec Stores 适合直接用于生产团队吗？
官方当前仍把 Stores 标为 beta。可以先在非关键跨仓库需求上验证权限、同步、回滚和代理读取方式，再决定是否纳入正式流程。