Note

本项目为中文汉化分支：openspec-cn（npm：@studyzy/openspec-cn）。

原版项目：OpenSpec 仓库：https://github.com/Fission-AI/OpenSpec npm：@fission-ai/openspec

最受喜爱的规范（spec）框架。

我们的理念：

→ 灵活，而非僵化
→ 迭代，而非瀑布式
→ 简单，而非复杂
→ 面向存量项目（brownfield），而不只是新项目（greenfield）
→ 从个人项目到企业规模都可扩展

Tip

全新工作流现已上线！ 我们用一种全新的“以制品（artifact）���导向”的工作流重构了 OpenSpec。

运行 /opsx:propose "你的想法" 开始使用。→ 在此了解更多

关注 X 上的 @0xTab 获取更新 · 加入 OpenSpec Discord 获取帮助与答疑。

看看效果

你：/opsx:explore
AI：  你想探索什么？
你：我想做深色模式，但不确定怎么搞才干净。
AI：  让我看看你的样式方案...
     最干净的路径：CSS 变量 + 一个小型主题上下文，
     加上系统偏好检测。不需要新依赖。要划定范围吗？
你：好，开始吧。

你：/opsx:propose add-dark-mode
AI：已创建 openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么要做这个，什么在变
     ✓ specs/       — 需求和���景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单
     准备好开始实现了！

你：/opsx:apply
AI：开始实现任务...
    ✓ 1.1 添加主题上下文 Provider
    ✓ 1.2 创建切换组件
    ✓ 2.1 添加 CSS 变量
    ✓ 2.2 接入 localStorage
    所有任务已完成！

你：/opsx:archive
AI：已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/
    Specs 已更新。可以开始下一个功能了。

OpenSpec 仪表盘

快速开始

需要 Node.js 20.19.0 或更高版本。

全局安装 openspec-cn：

npm install -g @studyzy/openspec-cn@latest

然后进入你的项目目录并初始化：

cd your-project
openspec-cn init

现在告诉你的 AI：

• 还不确定要构建什么？ 先用 /opsx:explore，一个无风险的思考伙伴，它会阅读你的代码、权衡方案、在写任何东西之前帮你理清思路。（探索指南）
• 已经知道自己想要什么？ 直接用 /opsx:propose <你想要构建的内容>。

这两者都在默认 profile 中。如果你想要扩展工作流（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard），请通过 openspec-cn config profile 选择，然后运行 openspec-cn update 应用。

Note

不确定你的工具是否支持？查看完整列表 – 我们支持 25+ 种工具且持续增加。

同样支持 pnpm、yarn、bun 和 nix。可查看 安装选项。

文档

从这里开始： 查看 文档首页 获取全貌。刚接触 OpenSpec？先读 快速入门，然后看 命令如何工作（了解 /opsx:propose 在哪里输入）。

→ 快速入门：第一步
→ 先探索：用 /opsx:explore 想清楚再动手
→ 命令如何工作：斜杠命令在哪运行 vs CLI
→ 核心概念一览：一页看懂整个心智模型
→ 示例与菜谱：真实变更，从开始到完成
→ 工作流：组合与模式
→ 存量项目：在已有代码库中引入 OpenSpec
→ 编辑变更：更新制品、回退、处理手动编辑
→ 命令：斜杠命令与技能
→ CLI：终端参考手册
→ Stores：在独立仓库中规划，团队共享（Beta）
→ 支持的工具：工具集成与安装路径
→ 概念：整体如何运转
→ 多语言：多语言支持
→ 自定义：打造你的版本
→ FAQ · 故障排查 · 术语表：快速帮助

社区 Schema

通过独立仓库分发的第三方 Schema 包 —— 它们提供了将 OpenSpec 与其他工具集成的特定工作流，类似于 github/spec-kit 的社区扩展目录 处理工具集成的方式。

→ 浏览目录，详见自定义文档。

为什么选择 OpenSpec？

AI 编程助手很强大，但当需求只存在于聊天记录里时，结果往往难以预测。OpenSpec 增加了一层轻量的规范（spec）机制，让你在写任何代码前先对齐要做什么。

• 先对齐，再开工 —— 人类与 AI 在写代码前先在规范上达成一致
• 保持有序 —— 每个变更都有自己的目录：proposal、specs、design、tasks
• 流式协作 —— 任意制品都可以随时更新，不设僵硬的阶段门槛
• 用你现有的工具 —— 通过斜杠命令支持 20+ AI 助手

我们如何对比

对比 Spec Kit（GitHub）—— 很全面但偏厚重：阶段门槛严格、Markdown 很多、需要 Python 环境。OpenSpec 更轻量，也更适合自由迭代。

对比 Kiro（AWS）—— 功能强大，但��被锁定在他们的 IDE 中，并且模型选择受限（主要是 Claude）。OpenSpec 可与您已有的工具协作。

对比“什么都不用” —— 只靠聊天做 AI 编程容易产生模糊需求和不可预测的实现。OpenSpec 在不增加太多仪式感的前提下，带来更可预期的结果。

更新 OpenSpec

升级包版本

npm install -g @studyzy/openspec-cn@latest

刷新代理指令（agent instructions）

在每个项目里运行一次，用于重新生成 AI 指引，并确保最新斜杠命令可用：

openspec-cn update

使用注意事项

模型选择：OpenSpec 更适合高推理模型。我们推荐在规划与实现阶段都使用 Codex 5.5 和 Opus 4.7。

上下文卫生：OpenSpec 受益于更干净的上下文窗口。在开始实现前清理上下文，并在整个会话中保持良好的上下文卫生。

参与贡献

小修小补 —— Bug 修复、错别字修正与小型改进可以直接提交 PR。

汉化问题 —— 因为汉化导致的 Bug 修复、错别字修正与小型改进建议可以直接提交 Issue。

较大改动 —— 对于新功能、重大重构或架构调整，请先提交一个 OpenSpec 变更提案，以便在实现前对齐意图与目标。

撰写提案时，请牢记 OpenSpec 的��念：我们服务于各种不同的编码代理、模型与使用场景。改动应对所有人都工作良好。

欢迎 AI 生成代码 —— 只要经过测试与验证即可。包含 AI 生成代码的 PR 应注明使用的编码代理与模型（例如："Generated with Claude Code using claude-opus-4-5-20251101"）。

开发

• 安装依赖：pnpm install
• 构建：pnpm run build
• 测试：pnpm test
• 本地开发 CLI：pnpm run dev 或 pnpm run dev:cli
• 约定式提交（单行）：type(scope): subject

其他

遥测（Telemetry）

OpenSpec 会收集匿��使用统计。

我们只收集命令名与版本号，用于理解使用模式；不会收集参数、路径、内容或任何个人信息。CI 中会自动禁用。

退出（Opt-out）： export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1

维护者与顾问

核心维护者与顾问列表见 MAINTAINERS.md。

许可证

MIT