项目简介
OpenSpec 为 AI 编码工作流添加轻量级规范层，确保人与 AI 在编写代码前对齐需求。提供 20+ 种 AI 助手的斜杠命令，并按功能组织变更。
README 预览
\n \n \n \n \n \n \n\n\n\n \n \n \n \n\n\n\nThe most loved spec framework.\n\n[](https://github.com/Fission-AI/OpenSpec/stargazers)\n[](https://www.npmjs.com/package/@fission-ai/openspec)\n[](https://github.com/Fission-AI/OpenSpec/graphs/contributors)\n\n\n\nOur philosophy:\n\n```text\n→ fluid not rigid\n→ iterative not waterfall\n→ easy not complex\n→ built for brownfield not just greenfield\n→ scalable from personal projects to enterprises\n```\n\n> [!TIP]\n> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.\n>\n> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)\n\n\n Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.\n\n\n\n\n## See it in action\n\n```text\nYou: /opsx:explore\nAI: What would you like to explore?\nYou: I want dark mode but I'm not sure how to do it cleanly.\nAI: Let me look at your styling setup...\n Cleanest path here: CSS variables + a small theme context,\n with system-preference detection. No new dependencies. Scope it?\nYou: Yes, let's do it.\n\nYou: /opsx:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n\nYou: /opsx:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n\nYou: /opsx:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n\nOpenSpec Dashboard\n\n\n \n\n\n\n\n## Quick Start\n\n**Requires Node.js 20.19.0 or higher.**\n\nInstall OpenSpec globally:\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\nThen navigate to
常见问题 (5)
操作指南如何在不使用 Node.js 的情况下安装 OpenSpec（独立二进制文件）？
自 v1.15.0 起,OpenSpec 提供了独立的二进制文件,无需 Node.js。安装方式如下:
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex如果你之前是通过 npm 安装的,请运行 openspec install 切换到独立二进制版本。完整详情请参阅仓库中 docs/installation.md 里的安装指南。
故障排除为什么 `openspec validate --strict` 在需求超过 500 个字符时仍然通过，以及如何在 CI 中强制执行该限制？
升级到 OpenSpec **1.14.1 或更高版本**。此前,超长需求(overlong-requirement)的检查结果被报告为 INFO,因此 openspec validate --all --strict 会以状态码 0 退出。在 1.14.1+ 中,需求描述超过 **500 个字符**会导致严格校验失败。请使用以下命令运行质量门禁:
openspec validate --all --strict要修复已有的检查结果,请将过长的需求拆分为多个更小的需求,同时不改变其语义;不要简单地将其截断。代理(agent)编写说明现在也已记录了 500 字符的限制,以防止出现新的超长需求。
故障排除如何在 `openspec view` 中隐藏已归档的 changes，让活跃的 changes 保持可见？
这是一个由 PR #399 引入的回归问题，该 PR 将已归档的变更添加到了 openspec view 仪表板中。此问题已由 PR fix(view): keep archived changes off the dashboard 修复（同时关闭 issue #2030）。请将 OpenSpec 升级到包含该修复的版本，然后再次运行 openspec view；已归档的变更将不再把进行中的工作挤出屏幕。作为临时解决方案，可以使用 openspec list。
故障排除如何修复 OpenSpec apply skill 因 allowedEditRoots 与声明该变更的仓库冲突而拒绝 store 支持的变更？
在 OpenSpec 1.13.1 中，openspec status --change <name> --json --store plans 可能会错误地将 actionContext.allowedEditRoots 仅设置为 store 根目录，例如 /path/to/plans，尽管实现编辑必须在声明仓库（declaring repo）中进行，例如 /path/to/app。生成的 apply skill 随后会将仓库上下文视为与 CLI 控制的值相冲突，并在 0/N 个任务处停止。
修复方法：升级到包含 PR fix(status): include the declaring repo in store-backed edit roots 的 OpenSpec 版本（或从提交 0d814f39 或之后的版本构建）。修复后，使用以下命令验证：
openspec status --change <name> --json --store plansactionContext.allowedEditRoots 应同时包含两个根目录：
["/path/to/app", "/path/to/plans"]store 根目录存放规划产物（planning artifacts），而声明仓库根目录存放实现编辑。mode 和输出契约保持不变。
临时解决方法：手动覆盖 agent 的拒绝行为，并明确授权在声明仓库和 store 根目录中都进行编辑，同时阐明存在问题的 status 输出中的 allowedEditRoots 并不仅限于规划产物。
故障排除如何修复因 'Archive the change' 和 'Verify archived result' 任务阻塞归档而导致的 OpenSpec 循环依赖问题？
升级到 OpenSpec 1.14.1+，其中 openspec instructions apply 仅报告已跟踪任务的完成情况，而不再声明变更已准备好归档。在 tasks.md 中，仅将可在归档前完成的工作保留为 - [ ] 复选框。将依赖归档的步骤移至普通项目符号列表部分，使其不影响任务计数：
## 工作流后续事项
- 在项目的审查要求得到满足后归档该变更。
- 验证归档结果。完成消息现在为："All tracked tasks are complete. Review or verify the change as appropriate before archiving." state: "all_done"、任务解析、验证、归档行为和标志均保持不变。在较旧的原版 OpenSpec 上，你可以确认该警告或使用 --yes；要求零未完成任务的更严格自定义策略必须更新，否则必须将依赖归档的任务移出已跟踪列表。