OpenSpecX

OpenSpec Extensions - Module Rules Management

Overview

OpenSpecX is an extension to OpenSpec that helps manage module-specific rules (RULE documents) and generate AI assistant commands for Cursor and other tools.

Features

• Init Command: Initialize new module rules with code analysis and AI prompt generation
• Validate Command: Validate RULE.md files against specifications
• Cursor Integration: Generate Cursor command files that read RULE documents

Installation

方式 1: 本地开发安装

# 从 openspecx 目录
cd openspecx
pnpm install
pnpm build

# 全局链接（使 openspecx 命令可用）
pnpm link --global

方式 2: 从 npm 安装（如果已发布）

npm install -g @fission-ai/openspecx
# 或
pnpm add -g @fission-ai/openspecx

方式 3: 从本地打包文件安装

# 在 openspecx 目录下
pnpm build
npm pack
# 这会生成一个 .tgz 文件

# 安装打包文件
npm install -g ./fission-ai-openspecx-0.1.0.tgz

详细安装说明请参考 INSTALL.md。

验证安装

openspecx --version

Usage

查看帮助

# 查看主帮助
openspecx --help
# 或
openspecx help

# 查看特定命令的帮助
openspecx init --help
openspecx validate --help

# 查看版本
openspecx --version

Initialize a Module Rule

语法：

openspecx init <modulePath> <ruleName> [options]

参数：

• <modulePath> - 模块路径（例如：api/multi_language）
• <ruleName> - 规则名称（例如：generate_multi_language）

选项：

• --tool <tool> - 目标工具（默认：cursor）
• --skip-analysis - 跳过模块代码分析

示例：

# 基本用法
openspecx init api/multi_language generate_multi_language

# 指定工具
openspecx init api/multi_language generate_multi_language --tool cursor

# 跳过代码分析
openspecx init api/multi_language generate_multi_language --skip-analysis

功能说明：

1. 提示选择 AI 工具（目前仅支持 Cursor）
2. 分析模块代码结构
3. 在 .cursor/commands/ 目录生成 Cursor 命令文件
4. 在 .cursor/rule/ 目录生成集中管理的 RULE 模板文件
5. 显示用于生成 RULE 内容的 AI 提示词

Validate a RULE File

重要说明：openspecx validate 命令主要设计为由 AI 助手自动调用，而不是用户手动执行。当您让 AI 填充 RULE 文件时，AI 会自动调用此命令进行验证和自我修正。

语法：

openspecx validate <ruleFile> [options]

参数：

• <ruleFile> - RULE.md 文件路径

选项：

• --strict - 严格模式（警告视为错误）
• --json - 输出 JSON 格式（AI 使用此选项获取结构化验证结果）

AI 自动调用示例： 当您使用提示词让 AI 填充 RULE 文件时，AI 会自动执行：

# AI 自动调用（在 RULE 文件的 AI 指令中已包含）
openspecx validate .cursor/rule/generate_multi_language-RULE.md --json

手动调用（仅在需要时）：

# 基本验证（查看验证结果）
openspecx validate .cursor/rule/generate_multi_language-RULE.md

# 严格模式（CI/CD 场景）
openspecx validate .cursor/rule/generate_multi_language-RULE.md --strict

# JSON 输出（用于脚本处理）
openspecx validate .cursor/rule/generate_multi_language-RULE.md --json

全局选项

# 禁用彩色输出
openspecx --no-color init api/test test_rule

Project Structure

openspecx/
├── bin/              # CLI entry point
├── src/              # Source code
│   ├── cli/          # CLI definitions
│   ├── commands/     # Command implementations
│   ├── core/         # Core functionality
│   │   ├── analyzers/    # Module code analyzers
│   │   ├── generators/   # File generators
│   │   ├── parsers/      # Markdown parsers
│   │   ├── schemas/      # Zod schemas
│   │   └── validation/  # Validators
│   └── utils/        # Utility functions
├── openspecx/        # Specification documents
│   └── specs/        # Spec definitions
└── test/             # Tests

Development

开发命令

# 构建项目
pnpm build

# 监听模式（自动重新编译）
pnpm dev

# 运行测试
pnpm test
pnpm test:watch    # 监听模式
pnpm test:ui       # UI 模式
pnpm test:coverage # 覆盖率报告

# 开发模式运行 CLI（自动构建后运行）
pnpm dev:cli init api/multi_language test_rule
pnpm dev:cli validate .cursor/rule/test_rule-RULE.md

开发时使用 OpenSpecX 命令

开发过程中可以直接使用全局安装的命令，或通过 pnpm dev:cli 运行：

# 方式 1: 使用全局命令（如果已链接）
openspecx init api/test_module test_rule
# 注意：validate 命令通常由 AI 自动调用，无需手动执行

# 方式 2: 使用开发模式（自动构建）
pnpm dev:cli init api/test_module test_rule
# AI 会在填充 RULE 文件时自动调用 validate 命令

Implementation Status

✅ Completed Features

• Core Data Structures: Type definitions, validation constants, RULE Zod Schema
• Parsing & Validation: RULE parser with bilingual support, comprehensive validator with error enhancement
• Code Analysis: Module analyzer supporting TypeScript, JavaScript, Python with design pattern detection
• Generators: Cursor command generator, RULE template generator, AI prompt generator
• Commands: Full implementation of init and validate commands
• Testing: 43 tests across 8 test files, all passing ✅

📋 Future Enhancements

• Support for more AI tools (currently only Cursor)
• Enhanced code analysis with AST parsing
• More design pattern detection
• Additional documentation and examples

Integration with OpenSpec

OpenSpecX is designed to work alongside OpenSpec:

• Shares the same code style and structure
• Can be merged into OpenSpec as a sub-command
• Can be published as a separate package

License

MIT