ROD CLI - 规则导向开发

规则导向开发工具包，用于规范驱动开发

English | 中文

概述

ROD CLI（规则导向开发）是一个现代的、基于 TypeScript 的工具包，强调规则驱动和规范驱动的开发。它通过结构化规范和清晰的开发规则，提供了完整的软件功能创建、规划和实施工作流程。

主要特性

• 🚀 本地模板生成：无网络依赖，离线工作
• 🌐 跨平台支持：Windows、macOS 和 Linux
• 🤖 多 AI 助手支持：Claude、GitHub Copilot、Gemini、Cursor、Codebuddy
• ⚡ 闪电般快速：本地模板生成 vs 网络下载
• 🔧 TypeScript 优先：完整类型安全和现代开发体验
• 🧪 测试驱动开发：Jest 全面测试覆盖
• 📦 零网络依赖：在企业/内部网络中工作

安装

全局安装（推荐）

npm install -g rod-cli

本地开发

git clone https://github.com/Rainmen-xia/rod-cli.git
cd rod-cli
npm install
npm run build

快速开始

初始化新的 ROD 项目

# 使用 Claude 助手创建新项目
rod init my-project --ai claude

# 在当前目录使用 GitHub Copilot 初始化
rod init --here --ai copilot  

# 使用 Gemini 和 bash 脚本创建项目
rod init my-app --ai gemini

# 使用 Codebuddy 助手初始化
rod init my-project --ai codebuddy

检查系统要求

# 基本系统检查
rod check

# 详细系统信息
rod check --verbose

架构

核心组件

src/
├── cli.ts                    # 主 CLI 入口点
├── commands/                 # 命令实现
│   ├── init.ts              # 项目初始化
│   └── check.ts             # 系统验证
├── lib/                     # 核心业务逻辑
│   ├── local-template-generator.ts  # 模板生成
│   ├── config-manager.ts    # 配置管理
│   └── tool-checker.ts      # 系统工具验证
├── types/                   # TypeScript 类型定义
│   ├── cli-config.ts        # 配置类型
│   ├── project-template.ts  # 模板类型
│   └── results.ts           # 结果格式化
└── contracts/               # 接口契约
    ├── cli-interface.ts     # CLI 契约
    └── file-operations.ts   # 文件操作契约

本地模板系统

Node.js 版本使用革命性的本地模板生成方法：

// 旧方式：依赖网络
await downloadFromGitHub(template)

// 新方式：本地生成
const generator = new LocalTemplateGenerator()
await generator.generateTemplate({
  aiAssistant: 'claude',
  scriptType: 'sh',
  projectPath: './my-project'
})

本地生成的优势

| 特性 | GitHub 下载 | 本地生成 | |---------|----------------|------------------| | 网络依赖 | ❌ 必需 | ✅ 无 | | 企业网络 | ❌ 经常被阻止 | ✅ 始终工作 | | 速度 | 🐌 慢（网络 I/O） | ⚡ 快（本地 I/O） | | 可靠性 | 🔄 速率限制 | ✅ 100% 可靠 | | 自定义 | 🔒 有限 | 🎯 完全控制 | | 离线使用 | ❌ 不可能 | ✅ 完整 |

配置

AI 助手支持

Claude Code

rod init --ai claude

• 生成 .claude-config.json
• 优化文件操作
• 内置命令集成

GitHub Copilot

rod init --ai copilot

• 生成 COPILOT.md 指南
• 工作区感知命令
• @workspace 集成提示

Gemini CLI

rod init --ai gemini

• 生成 .gemini-config.json
• 上下文感知提示
• 结构化工作流支持

Cursor IDE

rod init --ai cursor

• 生成 CURSOR.md 指南
• Ctrl+K/Cmd+K 集成
• IDE 优化工作流

Codebuddy

rod init --ai codebuddy

• 生成 .codebuddy/commands/ 目录
• 代码助手最佳实践
• 结构化工作流支持

跨平台脚本

Bash (Unix/Linux/macOS)

rod init --script sh

• POSIX 兼容脚本
• 自动可执行权限
• Unix 风格路径处理

PowerShell (Windows/跨平台)

rod init --script ps

• 现代 PowerShell 语法
• 跨平台兼容性
• Windows 优化操作

生成的项目结构

my-project/
├── .claude-config.json           # AI 特定配置
├── .claude/commands/             # AI 助手命令（五步工作流）
│   ├── module.md                # 模块创建和导航
│   ├── specify.md               # 需求规范分析
│   ├── plan.md                  # 技术设计和规划
│   ├── tasks.md                 # 任务分解和生成
│   └── progress.md              # 进度同步管理
├── .specify/                    # 共享资源
│   ├── scripts/                 # 跨平台自动化
│   │   └── bash/                # 或 powershell/
│   │       ├── analyze-modules.sh
│   │       ├── create-module-spec.sh
│   │       ├── setup-module-plan.sh
│   │       ├── generate-module-tasks.sh
│   │       └── sync-progress.sh
│   ├── templates/               # 文档模板
│   │   ├── spec-template.md     # 功能规范模板
│   │   ├── plan-template.md     # 技术设计模板
│   │   ├── tasks-template.md    # 任务列表模板
│   │   └── roadmap-template.md  # 项目路线图模板
│   └── memory/                  # 项目宪法
│       ├── constitution.md      # 项目原则
│       └── constitution_update_checklist.md
└── specs/                       # 项目规范
    ├── roadmap.md              # 项目路线图
    └── modules/                # 功能模块
        └── [模块路径]/          # 模块目录
            └── [功能名称]/      # 具体功能
                ├── spec.md           # 功能规范
                ├── plan.md           # 技术设计
                ├── research.md       # 技术调研
                ├── data-model.md     # 数据模型
                ├── contracts/        # API契约
                ├── quickstart.md     # 测试场景
                ├── module-interfaces.md  # 模块接口(如有依赖)
                └── tasks.md          # 开发任务

路线图驱动工作流

ROD CLI 提供结构化的 5 阶段开发工作流，专为大型项目的模块化开发设计：

1. 模块创建 (/module)

# 创建新的功能模块
/module auth/login

• 创建模块目录结构
• 初始化规范模板
• 支持分层模块组织

2. 规范分析 (/specify)

# 分析和记录需求
/specify "实现基于 JWT 的认证"

• 创建详细的功能规范文档
• 支持模块间依赖关系声明
• 包含业务规则和验收标准
• 生成结构化的需求文档

3. 技术设计 (/plan)

# 生成全面的设计文档
/plan

• 创建架构和组件设计
• 定义 API、数据模型和接口
• 生成跨模块接口设计 (如有依赖)
• 将需求映射到技术实现

4. 任务规划 (/tasks)

# 分解为可操作的开发任务
/tasks

• 将设计转换为开发任务
• 创建测试驱动开发计划
• 支持模块集成任务生成
• 提供并行执行的实施路线图

5. 进度同步 (/progress)

# 同步进度到项目路线图
/progress

• 更新模块完成状态
• 聚合项目整体进度
• 同步进度到项目路线图
• 跟踪模块间依赖关系和里程碑
• 支持大型项目进度管理

命令参考

rod init

初始化新的 ROD 项目。

rod init [project-name] [options]

选项

| 选项 | 描述 | 值 | |--------|-------------|---------| | --ai <assistant> | 要使用的 AI 助手 | claude, copilot, gemini, cursor, codebuddy | | --script <type> | 脚本类型 | sh (bash), ps (powershell) | | --here | 在当前目录初始化 | boolean | | --no-git | 跳过 git 仓库初始化 | boolean | | --ignore-agent-tools | 跳过 AI 工具验证 | boolean | | --debug | 显示详细诊断输出 | boolean |

示例

# 使用 Claude 的标准项目
rod init my-project --ai claude

# 在当前目录使用 Copilot 和 PowerShell
rod init --here --ai copilot --script ps

# 跳过 git 初始化
rod init my-app --ai gemini --no-git

# 调试模式和详细输出
rod init test-project --debug

rod check

验证系统要求和工具可用性。

rod check [options]

选项

| 选项 | 描述 | |--------|-------------| | --verbose, -v | 显示包括路径在内的详细信息 |

输出

🔍 检查系统要求...

系统信息：
  平台：darwin (arm64)
  Node.js：v20.19.0
  npm：10.8.2
  Git：2.39.5

工具可用性：
  ✅ 可用：
    node (20.19.0)
    npm (10.8.2)
    git (2.39.5)
    claude-cli (1.0.110)

  ❌ 缺失：
    gh [AI-特定] - brew install gh

总体状态：
  ✅ 所有必需工具都可用
     4/5 工具可用

开发

先决条件

• Node.js 18+
• npm 8+
• TypeScript 5+

设置

# 克隆仓库
git clone https://github.com/Rainmen-xia/rod-cli.git
cd rod-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 开发模式
npm run dev -- init test-project --ai claude --debug

可用脚本

| 脚本 | 描述 | |--------|-------------| | npm run build | 将 TypeScript 编译为 JavaScript | | npm run dev | 在开发模式下运行 CLI | | npm test | 运行 Jest 测试套件 | | npm run test:watch | 在监视模式下运行测试 | | npm run test:coverage | 生成测试覆盖率报告 | | npm run lint | 运行 ESLint | | npm run format | 使用 Prettier 格式化代码 |

测试

项目遵循测试驱动开发原则：

# 运行所有测试
npm test

# 运行覆盖率测试
npm run test:coverage

# 运行特定测试套件
npm test -- --testNamePattern="InitCommand"

# 开发监视模式
npm run test:watch

测试结构

tests/
├── contract/          # 契约测试（TDD）
├── unit/             # 单元测试
├── integration/      # 集成测试
└── performance/      # 性能测试

从 Python 版本迁移

Node.js 版本提供与 Python 版本完全功能对等：

主要改进

| 特性 | Python 版本 | Node.js 版本 | |---------|---------------|-----------------| | 安装 | pip install + Python 设置 | npm install -g（单命令） | | 依赖 | 多个 Python 包 | 最小 npm 依赖 | | 启动时间 | ~500ms（Python 导入） | ~100ms（Node.js） | | 跨平台 | 好 | 优秀 | | 网络问题 | 依赖 GitHub API | 完全离线 | | 模板更新 | 需要发布周期 | 即时（内置） |

迁移命令

# Python 版本
specify init my-project --ai claude

# Node.js ROD CLI（相同接口）
rod init my-project --ai claude

配置兼容性

两个版本生成相同的项目结构，完全可互换。

贡献

开发工作流程

1. Fork 仓库
2. 克隆 您的 fork
3. 创建 功能分支
4. 先写 测试（TDD）
5. 实现 功能
6. 运行 测试和 linting
7. 提交 pull request

代码标准

• TypeScript：启用严格模式
• 测试：Jest，>90% 覆盖率
• Linting：ESLint 与 TypeScript 规则
• 格式化：Prettier 一致风格
• 提交：约定式提交消息

测试指南

// 示例：契约测试（TDD）
describe('InitCommand', () => {
  it('应该使用本地模板初始化项目', async () => {
    // 准备
    const initCommand = new InitCommand();
    const args = { projectName: 'test', ai: 'claude' };
    
    // 执行
    await initCommand.execute(args);
    
    // 断言
    expect(fs.existsSync('test/templates')).toBe(true);
    expect(fs.existsSync('test/scripts')).toBe(true);
  });
});

故障排除

常见问题

1. 权限错误

# 在 Unix 系统上，确保脚本权限
chmod +x scripts/bash/*.sh

# 或使用内置权限设置器
rod init --debug  # 显示权限操作

2. 缺失工具

# 检查缺失内容
rod check --verbose

# 安装缺失工具（macOS 示例）
brew install git gh claude-cli

3. 项目名称冲突

# 使用当前目录
rod init --here --ai claude

# 或指定不同名称
rod init my-unique-project-name --ai claude

4. 调试模式

# 启用详细输出进行诊断
rod init test-project --debug --ai claude

性能基准

初始化速度比较

| 方法 | 平均时间 | 需要网络 | |--------|-------------|------------------| | Python + GitHub | 3.2秒 | ✅ 是 | | Node.js 本地 | 0.8秒 | ❌ 否 |

内存使用

| 版本 | 内存峰值 | 启动内存 | |---------|-------------|----------------| | Python | 45MB | 25MB | | Node.js | 28MB | 15MB |

许可证

MIT 许可证 - 详见 LICENSE 文件。

支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 文档：Spec Kit Docs

更新日志

v1.0.0（最新）

🎉 主要功能

• 本地模板生成：完全离线功能
• 多 AI 支持：Claude、Copilot、Gemini、Cursor、Codebuddy
• 跨平台脚本：Bash 和 PowerShell 支持
• TypeScript 重写：完整类型安全和现代工具

🔧 改进

• 零网络依赖：在任何网络环境中工作
• 更快初始化：比 Python 版本快 4 倍
• 更小包大小：减少依赖占用
• 更好错误消息：清晰、可操作的错误报告

🐛 Bug 修复

• 修复 --here 选项路径解析
• 改进 Windows 脚本权限处理
• 增强跨平台路径处理

🚀 性能

• 80% 更快 项目初始化
• 40% 更少 内存使用
• 100% 可靠 离线环境

致谢

本项目受到优秀的 spec-kit 项目启发和参考。我们向 GitHub 团队表示感谢，感谢他们在规范驱动开发工作流程方面的开创性工作，并提供了使 ROD CLI 成为可能的基础概念。

来自 spec-kit 的关键启发：

• 📋 规范驱动工作流程模式
• 🤖 多 AI 助手集成方法
• 📁 项目结构和模板组织
• 🔧 基于命令的开发方法

ROD CLI 改进：

• 🔄 基于 NPM 的版本控制：无 GitHub 下载，避免企业网络限制
• 🏢 企业网络友好：完全离线工作，在受限环境中运行
• ⚡ 本地模板生成：内置模板消除网络依赖
• 🎯 TypeScript 实现：完整类型安全和现代开发体验
• 🌐 增强跨平台支持：更好的 Windows/Unix 兼容性
• 🏗️ 模块化架构：专为大型项目设计的五步工作法
• 📊 进度管理：项目级进度跟踪和模块依赖管理

ROD vs SDD 对比

ROD CLI 基于 SDD (Specification-Driven Development) 方法论，但针对大型项目进行了增强：

| 特性 | SDD 原版 | ROD CLI | |------|----------|---------| | 架构 | 单特性分支 | 模块化架构 | | 工作流 | 3步 (specify→plan→tasks) | 5步 (module→specify→plan→tasks→progress) | | 依赖管理 | 独立特性 | 跨模块依赖协调 | | 进度跟踪 | 无 | 项目级进度聚合 | | 适用场景 | 中小型项目 | 大型项目 | | 模块接口 | 无 | 专门的接口设计阶段 | | 并行开发 | 有限支持 | 完整的模块并行开发 |

用 ❤️ 由 ROD 团队构建

在全球范围内增强规则导向和规范驱动开发