cucumber-openspec
cucumber-openspec 将 OpenSpec 的 spec.md 文件转换为确定性的 Cucumber / Gherkin .feature 文件。
它使用零 AI、确定性的 TypeScript 脚本——一个状态机解析器与生成器——来生成正确的 .feature 文件，支持全部 80 种 Gherkin 语言。除了 Node.js 外没有其他运行时依赖。
快速开始
# 为你的 AI 代理安装此技能
npx skills add neurono-ml/cucumber-openspec
# 将项目的规范转换为 Gherkin
npx tsx scripts/index.ts -i ./openspec -o ./features
功能特性
- 确定性解析器——状态机，零依赖
- 80 种 Gherkin 语言——英语、葡萄牙语、简体中文、阿拉伯语、日语等 76 种语言
- 标签——
@smoke、@regression、@critical，支持功能层、规则层和场景层 - 背景（Background）——通过
## Background章节共享步骤 - 场景大纲 + 示例（Scenario Outline + Examples）——数据驱动的参数化场景
- 数据表格（DataTables）——管道表格作为步骤参数
- 文档字符串（Doc Strings）——子项目符号转换为
"""代码块 - 增量规范（Delta specs）——ADDED / MODIFIED / REMOVED 章节用于变更管理
- Gherkin 语法验证——所有输出通过
@cucumber/gherkin验证 - 本地化——通过官方 Gherkin 翻译支持 80 种语言的关键词
- 智能体技能——可通过
skills.sh安装，支持 Claude Code、Cursor、OpenCode、Codex
工作原理
OpenSpec spec.md → Gherkin .feature
───────────────────── ─────────────────
# [@tag] 领域名称 [@tag]
## Purpose 功能：领域名称
## Background 背景：
- **GIVEN** 步骤 假如 步骤
### [@tag] Requirement: 名称 [@tag]
#### [@tag] Scenario: 名称 规则：名称
- **GIVEN** 文本 [@tag]
| 列 | 列 | 场景：名称
- **WHEN** 文本 假如 文本
- **THEN** 文本 | 列 | 列 |
当 文本
那么 文本
安装
作为智能体技能安装（推荐）
通过 skills.sh 为任何兼容 SKILL.md 的智能体安装：
npx skills add neurono-ml/cucumber-openspec
支持以下平台：
| 平台 | 技能目录 |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Cursor | ~/.cursor/skills/ |
| OpenCode | ~/.config/opencode/skills/ |
| Codex | ~/.agents/skills/ |
安装后，下次对话时即可使用该技能。
从 GitHub 克隆（手动方式）
git clone https://github.com/neurono-ml/cucumber-openspec.git ~/.agents/skills/cucumber-openspec
使用 npm / npx（直接使用）
无需全局安装。项目使用 npx tsx 直接运行 TypeScript：
# 克隆仓库
git clone https://github.com/neurono-ml/cucumber-openspec.git
cd cucumber-openspec
# 安装依赖
npm ci
# 使用
npx tsx scripts/index.ts -i ./openspec -o ./features
系统要求
使用方法
CLI 参考
npx tsx scripts/index.ts [options]
选项
| 标志 | 别名 | 描述 | 默认值 |
|---|---|---|---|
--input | -i | 规范文件或 openspec 目录的路径 | （必填） |
--output | -o | .feature 文件的输出目录 | ./features |
--language | -l | Gherkin 语言代码 | en |
输出路径
| 输入 | 输出 |
|---|---|
openspec/specs/auth/spec.md | features/auth.feature |
openspec/changes/add-auth/specs/auth/spec.md | features/add-auth_auth.feature |
示例
转换单个规范文件
npx tsx scripts/index.ts -i openspec/specs/auth/spec.md -o features
生成 features/auth.feature。
转换整个 OpenSpec 目录
npx tsx scripts/index.ts -i ./openspec -o ./features
遍历 openspec/specs/<domain>/spec.md 以及所有 openspec/changes/<change>/specs/<domain>/spec.md 文件。
转换为其他语言
# 葡萄牙语
npx tsx scripts/index.ts -i ./openspec -o ./features -l pt
# 简体中文
npx tsx scripts/index.ts -i ./openspec -o ./features -l zh-CN
# 阿拉伯语（从右到左）
npx tsx scripts/index.ts -i ./openspec -o ./features -l ar
转换增量变更
npx tsx scripts/index.ts -i openspec/changes/add-auth/specs/auth/spec.md -o features
生成带有 ADDED/MODIFIED/REMOVED 注释的 features/add-auth_auth.feature。
工作目录结构
project/
├── openspec/
│ ├── specs/
│ │ ├── auth/
│ │ │ └── spec.md
│ │ └── billing/
│ │ └── spec.md
│ └── changes/
│ └── add-auth/
│ └── specs/
│ └── auth/
│ └── spec.md
└── features/ # ← 生成目录
├── auth.feature
├── billing.feature
└── add-auth_auth.feature