ROD CLI - Rule-Oriented Development toolkit for specification-driven development
npm install rod-cli> 规则导向开发工具包,用于规范驱动开发
English | 中文


ROD CLI(规则导向开发)是一个现代的、基于 TypeScript 的工具包,强调规则驱动和规范驱动的开发。它通过结构化规范和清晰的开发规则,提供了完整的软件功能创建、规划和实施工作流程。
- 🚀 本地模板生成:无网络依赖,离线工作
- 🌐 跨平台支持:Windows、macOS 和 Linux
- 🤖 多 AI 助手支持:Claude、GitHub Copilot、Gemini、Cursor、Codebuddy
- ⚡ 闪电般快速:本地模板生成 vs 网络下载
- 🔧 TypeScript 优先:完整类型安全和现代开发体验
- 🧪 测试驱动开发:Jest 全面测试覆盖
- 📦 零网络依赖:在企业/内部网络中工作
``bash`
npm install -g rod-cli
`bash`
git clone https://github.com/Rainmen-xia/rod-cli.git
cd rod-cli
npm install
npm run build
`bash使用 Claude 助手创建新项目
rod init my-project --ai claude
$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 claudeNode.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` 选项路径解析#### 🚀 性能
- 80% 更快 项目初始化
- 40% 更少 内存使用
- 100% 可靠 离线环境
本项目受到优秀的 spec-kit 项目启发和参考。我们向 GitHub 团队表示感谢,感谢他们在规范驱动开发工作流程方面的开创性工作,并提供了使 ROD CLI 成为可能的基础概念。
ROD CLI 基于 SDD (Specification-Driven Development) 方法论,但针对大型项目进行了增强:
| 特性 | SDD 原版 | ROD CLI |
|------|----------|---------|
| 架构 | 单特性分支 | 模块化架构 |
| 工作流 | 3步 (specify→plan→tasks) | 5步 (module→specify→plan→tasks→progress) |
| 依赖管理 | 独立特性 | 跨模块依赖协调 |
| 进度跟踪 | 无 | 项目级进度聚合 |
| 适用场景 | 中小型项目 | 大型项目 |
| 模块接口 | 无 | 专门的接口设计阶段 |
| 并行开发 | 有限支持 | 完整的模块并行开发 |
---
用 ❤️ 由 ROD 团队构建
在全球范围内增强规则导向和规范驱动开发