ROD CLI - 规则导向开发

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

English | 中文


概述

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

$3

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

安装

$3

``bash
npm install -g rod-cli
`

$3

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

快速开始

$3

`bash


使用 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
`

$3

`bash


基本系统检查

rod check

详细系统信息

rod check --verbose
`

架构

$3

`
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 # 文件操作契约
`

$3

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

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

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

#### 本地生成的优势

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

配置

$3

#### Claude Code
`bash
rod init --ai claude
`
- 生成 .claude-config.json
- 优化文件操作
- 内置命令集成

#### GitHub Copilot
`bash
rod init --ai copilot
`
- 生成 COPILOT.md 指南
- 工作区感知命令
- @workspace 集成提示

#### Gemini CLI
`bash
rod init --ai gemini
`
- 生成 .gemini-config.json
- 上下文感知提示
- 结构化工作流支持

#### Cursor IDE
`bash
rod init --ai cursor
`
- 生成 CURSOR.md 指南
- Ctrl+K/Cmd+K 集成
- IDE 优化工作流

#### Codebuddy
`bash
rod init --ai codebuddy
`
- 生成 .codebuddy/commands/ 目录
- 代码助手最佳实践
- 结构化工作流支持

$3

#### Bash (Unix/Linux/macOS)
`bash
rod init --script sh
`
- POSIX 兼容脚本
- 自动可执行权限
- Unix 风格路径处理

#### PowerShell (Windows/跨平台)
`bash
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 阶段开发工作流，专为大型项目的模块化开发设计：

$3


`bash

创建新的功能模块

/module auth/login
`
- 创建模块目录结构
- 初始化规范模板
- 支持分层模块组织

$3

`bash

分析和记录需求

/specify "实现基于 JWT 的认证"
`
- 创建详细的功能规范文档
- 支持模块间依赖关系声明
- 包含业务规则和验收标准
- 生成结构化的需求文档

$3

`bash

生成全面的设计文档

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

$3

`bash

分解为可操作的开发任务

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

$3

`bash

同步进度到项目路线图

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

命令参考

$3

初始化新的 ROD 项目。

`bash
rod init [project-name] [options]
`

#### 选项

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

#### 示例

`bash


使用 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
`

$3

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

`bash
rod check [options]
`

#### 选项

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

#### 输出

`bash
🔍 检查系统要求...

系统信息：
平台：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 工具可用
`

开发

$3

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

$3

`bash


克隆仓库

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
`

$3

| 脚本 | 描述 |
|--------|-------------|
| 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 格式化代码 |

$3

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

`bash


运行所有测试

npm test

运行覆盖率测试

npm run test:coverage

运行特定测试套件

npm test -- --testNamePattern="InitCommand"

开发监视模式

npm run test:watch
`

#### 测试结构

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

从 Python 版本迁移

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

$3

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

$3

`bash


Python 版本

specify init my-project --ai claude

Node.js ROD CLI（相同接口）

rod init my-project --ai claude
`

$3

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

贡献

$3

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

$3

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

$3

`typescript
// 示例：契约测试（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);
});
});
`

故障排除

$3

#### 1. 权限错误
`bash


在 Unix 系统上，确保脚本权限

chmod +x scripts/bash/*.sh

或使用内置权限设置器

rod init --debug # 显示权限操作
`

#### 2. 缺失工具
`bash


检查缺失内容

rod check --verbose

安装缺失工具（macOS 示例）

brew install git gh claude-cli
`

#### 3. 项目名称冲突
`bash


使用当前目录

rod init --here --ai claude

或指定不同名称

rod init my-unique-project-name --ai claude
`

#### 4. 调试模式
`bash


启用详细输出进行诊断


rod init test-project --debug --ai claude
`

性能基准

$3

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

$3

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

许可证

MIT 许可证 - 详见 LICENSE 文件。

支持

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

更新日志

$3

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

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

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

#### 🚀 性能
- 80% 更快 项目初始化
- 40% 更少 内存使用
- 100% 可靠 离线环境

致谢

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

$3

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

$3

- 🔄 基于 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 团队构建

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