# rnx

**Repository Path**: MM-Q/rnx

## Basic Information

- **Project Name**: rnx
- **Description**: 简单高效的跨平台任务编排工具
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 任务编排, 运行器

## README

<div align="center">

# Rnx

[![Go Version](https://img.shields.io/badge/Go-1.25+-blue.svg)](https://golang.org) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)](https://gitee.com/MM-Q/rnx) [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20Darwin-lightgrey.svg)](https://gitee.com/MM-Q/rnx)

*简单高效的跨平台任务编排工具*

</div>

## 📖 项目简介

rnx 是一个强大的任务编排工具，通过直观的配置文件，让您轻松定义、管理和执行各种任务，支持依赖关系、环境变量、平台特定执行等高级功能。

## ✨ 核心特性

- 🚀 **简单易用** - 通过直观的 TOML 配置文件定义任务
- 🔗 **依赖管理** - 支持任务间复杂依赖关系，自动解析执行顺序
- 🌍 **跨平台** - 支持 Windows、Linux 和 macOS 平台
- 🎯 **平台特定执行** - 可以为任务指定特定运行平台
- 🌳 **环境变量** - 支持全局和任务级环境变量配置
- 🔄 **变量替换** - 支持全局变量和任务变量的动态替换
- ⏱️ **超时控制** - 为任务设置执行超时时间
- 📝 **详细日志** - 提供清晰的执行日志和错误信息
- 🛡️ **错误处理** - 灵活的错误处理策略，可选择失败时退出或继续
- 🎨 **模板支持** - 提供多种任务模板，快速开始项目

## 📦 安装指南

### 从源码构建安装

```bash
# 克隆仓库
git clone https://gitee.com/MM-Q/rnx.git
cd rnx

# 构建应用
python3 build.py

# 安装到系统路径 (可选)
python3 build.py -s -ai -f
```

### 使用 Go 安装

```bash
go install gitee.com/MM-Q/rnx@latest
```

### 验证安装

```bash
rnx --help
```

## 🚀 快速开始

### 1. 初始化配置文件

```bash
# 创建默认配置文件
rnx init

# 创建开发环境配置文件
rnx init --type dev
```

### 2. 基础配置示例

创建 `Rnx.toml` 配置文件：

```toml
# rnx 任务编排文件
# 项目地址: https://gitee.com/MM-Q/rnx.git
# 使用方法: rnx --run <任务名>

# ==================== 全局配置 ====================
[global]
# 工作目录 (默认: .) 
work_dir = '.'

# 超时时间 (默认: 30s) 
timeout = '30s'

# 是否显示输出 (默认: true) 
show_output = true

# 任务执行失败时是否退出程序 (默认: true) 
exit_on_error = true

# 是否显示执行的命令 (默认: false) 
show_cmd = false

# 全局环境变量 (可选) 
[global.envs]
GOOS = "linux"
GOARCH = "amd64"

# 全局变量 (可选) 
[global.vars]
app_name = "myapp"
version = "1.0.0"

# ==================== 任务定义 ====================
# 构建任务
[task.build]
desc = '构建应用程序'
cmds = [
    'echo "开始构建 {{app_name}} v{{version}}..."',
    'go build -o {{app_name}} main.go',
    'echo "构建完成"'
]
platform = ["linux", "darwin"]  # 仅在 Linux 和 macOS 上执行

# 测试任务
[task.test]
desc = '运行测试套件'
cmds = [
    'echo "运行单元测试..."',
    'go test ./...',
    'echo "测试通过"'
]
depends_on = ["build"]  # 依赖构建任务

# 部署任务
[task.deploy]
desc = '部署应用程序'
cmds = [
    'echo "部署到生产环境..."',
    './deploy.sh',
    'echo "部署完成"'
]
depends_on = ["test"]  # 依赖测试任务
platform = ["linux"]   # 仅在 Linux 上执行

# 完整流程
[task.all]
desc = '执行完整构建流程'
cmds = [
    'echo "执行完整流程..."'
]
depends_on = ["build", "test", "deploy"]
```

### 3. 执行任务

```bash
# 执行单个任务
rnx --run build

# 执行带依赖的任务（会自动先执行 build）
rnx --run test

# 执行完整流程
rnx --run all

# 列出所有可用任务
rnx --list

# 检查配置文件
rnx check

# 格式化配置文件
rnx fmt
```

## 📚 高级用法

### 变量替换

rnx 支持在命令中使用变量，变量会在执行前被替换：

```toml
[global.vars]
app_name = "myapp"
version = "1.0.0"

[task.build]
cmds = [
    'echo "构建 {{app_name}} 版本 {{version}}"',
    'go build -o {{app_name}}-{{version}} .'
]

[task.deploy]
vars = { deploy_path = "/opt/apps" }
cmds = [
    'echo "部署到 {{deploy_path}}"',
    'cp {{app_name}} {{deploy_path}}/'
]
```

#### 变量优先级

当任务变量和全局变量同名时，优先使用任务变量：

```toml
[global.vars]
version = "1.0.0"

[task.release]
vars = { version = "2.0.0" }  # 覆盖全局变量
cmds = [
    'echo "发布版本: {{version}}"',  # 输出 2.0.0 (任务变量)
    'echo "应用名称: {{app_name}}"'   # 输出 myapp (全局变量)
]
```

#### 环境变量引用

rnx 支持在环境变量中引用变量，实现动态环境变量配置：

```toml
[global.vars]
app_name = "myapp"
version = "1.0.0"

# 全局环境变量
[global.envs]
APP_VERSION = '应用版本: {{version}}'
APP_NAME = '应用名称: {{app_name}}'

[task.build]
# 任务环境变量
envs = {
    "BUILD_DIR": "构建目录: {{app_name}}-{{version}}",
    "OUTPUT_FILE": "输出文件: {{app_name}}.exe"
}
cmds = [
    'echo "环境变量 APP_VERSION: $APP_VERSION"',
    'echo "环境变量 APP_NAME: $APP_NAME"',
    'echo "环境变量 BUILD_DIR: $BUILD_DIR"',
    'echo "环境变量 OUTPUT_FILE: $OUTPUT_FILE"'
]
```

#### 变量引用规则

1. **全局环境变量**：
   - 可以引用全局变量
   - 不能引用自己或其他环境变量
   - 引用格式：`{{变量名}}`

2. **任务环境变量**：
   - 可以引用任务变量和全局变量
   - 不能引用自己或其他环境变量
   - 引用格式：`{{变量名}}`
   - 变量查找优先级：先查找任务变量，再查找全局变量

3. **循环引用检测**：
   - 系统会自动检测变量之间的循环引用
   - 如果发现循环引用，会在校验阶段报错

4. **环境变量命名规范**：
   - 只能包含字母、数字和下划线
   - 不能以数字开头
   - 不能为空

### 动态变量获取

支持通过命令动态获取变量值：

```toml
[global.vars]
# 使用命令获取动态值
git_commit = "@git rev-parse --short HEAD"
build_time = "@date +%Y%m%d%H%M%S"

[task.build]
cmds = [
    'echo "构建版本: {{git_commit}}"',
    'echo "构建时间: {{build_time}}"'
]
```

## 🌍 平台支持

rnx 支持为任务指定特定运行平台，实现跨平台的任务管理。

### 支持的平台

- `windows` - Windows 系统
- `linux` - Linux 系统
- `darwin` - macOS 系统

### 平台配置

在任务的 `platform` 配置项中指定支持的平台：

```toml
[task.build_windows]
desc = 'Windows 平台构建'
cmds = [
    'go build -o app.exe main.go',
    'echo Windows 构建完成'
]
platform = ["windows"]

[task.build_linux]
desc = 'Linux 平台构建'
cmds = [
    'go build -o app main.go',
    'echo Linux 构建完成'
]
platform = ["linux"]

[task.build_all]
desc = '构建所有平台'
cmds = ['echo 所有平台构建完成']
depends_on = ["build_windows", "build_linux"]
```

### 平台检测

rnx 自动检测当前运行平台，只执行支持当前平台的任务。如果任务没有指定平台，则默认支持所有平台。

## 🖥️ 执行环境

rnx 使用 `gitee.com/MM-Q/shellx` 库的 `shx` 子包执行 Shell 命令，该子包基于 `mvdan.cc/sh/v3`（mvdan/sh）实现。mvdan/sh 是用 Go 语言编写的 Shell 解析器和解释器，不依赖系统级 Shell 程序，因此在 Windows、Linux 和 macOS 上具有一致的执行行为。

### 技术实现

- **命令解析**：使用 `mvdan.cc/sh/v3/syntax` 进行命令语法解析
- **环境变量**：使用 `mvdan.cc/sh/v3/expand` 处理环境变量展开
- **执行引擎**：纯 Go 实现，无需外部 Shell 依赖

### 主要特性

- **跨平台一致性**：相同的命令在不同操作系统上表现一致
- **链式 API**：支持流畅的配置方法链
- **超时控制**：支持上下文超时和执行超时
- **环境隔离**：支持独立的工作目录和环境变量配置

### 使用示例

```toml
# 标准命令语法（跨平台一致）
[task.example]
cmds = [
    "echo 'Hello World'",
    "ls -la | grep .toml",
    "cat config.toml | grep desc",
]

# 支持管道和重定向
[task.process]
cmds = [
    "echo 'log entry' >> output.log",
    "cat output.log | tail -n 10",
]
```

### 环境变量配置

支持全局和任务级环境变量：

```toml
[global.envs]
GOOS = "linux"
GOARCH = "amd64"
CGO_ENABLED = "0"

[task.build]
envs = {
    "LDFLAGS": "-s -w",
    "OUTPUT_NAME": "myapp"
}
cmds = [
    'go build -ldflags="$LDFLAGS" -o "$OUTPUT_NAME" .'
]
```

#### 环境变量引用

环境变量可以引用变量，实现动态配置：

```toml
[global.vars]
version = "1.0.0"
app_name = "myapp"

[global.envs]
# 全局环境变量引用全局变量
APP_VERSION = '应用版本: {{version}}'
APP_FULL_NAME = '应用全名: {{app_name}}-v{{version}}'

[task.build]
envs = {
    # 任务环境变量引用全局变量
    "BUILD_DIR": "build-{{version}}",
    "OUTPUT_NAME": "{{app_name}}-{{version}}",
    # 任务环境变量引用任务变量
    "CONFIG_FILE": "配置文件: {{config_path}}"
}
vars = {
    "config_path": "/etc/{{app_name}}/config.toml"
}
cmds = [
    'echo "构建目录: $BUILD_DIR"',
    'echo "输出文件: $OUTPUT_NAME"',
    'echo "配置文件: $CONFIG_FILE"'
]
```

## 📋 API 文档概述

### 命令行参数

| 命令/参数 | 描述 | 示例 |
|------|------|------|
| `--run` 或 `-r` | 执行指定任务 | `rnx --run build` 或 `rnx -r build` |
| `--list` 或 `-l` | 列出所有任务 | `rnx --list` 或 `rnx -l` |
| `init` | 初始化配置文件 | `rnx init` |
| `check` | 检查配置文件 | `rnx check` |
| `fmt` | 格式化配置文件 | `rnx fmt` |
| `--path` 或 `-p` | 指定任务文件路径 | `rnx --run build --path custom.toml` |
| `--force` 或 `-f` | 强制执行操作 | `rnx init --force` |
| `--parallel` 或 `-P` | 并行执行任务 | `rnx --parallel` |

### 子命令详细说明

#### init 子命令
```bash
# 初始化默认配置文件
rnx init

# 指定模板类型
rnx init --type dev

# 强制覆盖已存在文件
rnx init --force
```

#### check 子命令
```bash
# 检查默认配置文件
rnx check

# 检查指定文件
rnx check --path custom.toml
```

#### fmt 子命令
```bash
# 格式化默认配置文件
rnx fmt

# 格式化指定文件
rnx fmt --path custom.toml

# 强制格式化
rnx fmt --force
```

### 配置文件结构

rnx 使用 TOML 格式的配置文件，支持以下主要部分：

- `[global]` - 全局配置
- `[global.envs]` - 全局环境变量
- `[global.vars]` - 全局变量
- `[task.task_name]` - 任务定义
- `[task.task_name.envs]` - 任务环境变量
- `[task.task_name.vars]` - 任务变量

### 核心数据结构

```go
// 全局配置
type GlobalConfig struct {
    Envs        map[string]string // 全局环境变量
    Vars        map[string]string // 全局变量
    WorkDir     string            // 工作目录
    Timeout     string            // 超时时间
    ShowOutput  bool              // 是否显示输出
    ExitOnError bool              // 任务执行失败时是否退出程序
    ShowCmd     bool              // 是否显示执行的命令
    Blacklist   []string          // 命令黑名单
}

// 任务配置
type TaskConfig struct {
    Desc      string            // 任务描述
    Cmds      []string          // 命令列表
    Envs      map[string]string // 任务环境变量
    Vars      map[string]string // 任务变量
    WorkDir   string            // 任务工作目录
    DependsOn []string          // 依赖任务列表
    Platform  []string          // 支持的平台列表
}
```

## 🛠️ 支持的功能/格式

### 配置文件格式

- **主配置文件**: `Rnx.toml` (推荐)
- **备选配置文件**: `rnx.toml`
- **兼容旧版**: `task.toml`, `Task.toml`

### 支持的平台

- Windows
- Linux
- Darwin (macOS)

### 变量引用格式

- 全局变量: `{{变量名}}`
- 任务变量: `{{变量名}}`
- 环境变量引用: `{{变量名}}`（在环境变量值中引用变量）

### 变量查找优先级

1. 当前任务变量（最高优先级）
2. 全局变量（次优先级）

### 变量引用限制

- 任务变量可以引用全局变量和当前任务内的其他变量
- 全局变量之间可以互相引用
- 全局环境变量可以引用全局变量
- 任务环境变量可以引用任务变量和全局变量
- 环境变量不能引用自己或其他环境变量
- 变量系统支持循环依赖检测，自动防止无限递归

## 🧪 测试说明

### 运行测试

```bash
# 运行所有测试
go test ./...

# 运行特定包的测试
go test ./internal/utils

# 运行测试并显示覆盖率
go test -cover ./...

# 生成覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### 测试配置

可以使用提供的示例配置文件进行测试：

```bash
# 检查示例配置
rnx --check --config example/task.toml

# 列出示例任务
rnx --list --config example/task.toml

# 运行示例任务
rnx --run clean --config example/task.toml
```

## 📄 许可证和贡献指南

### 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

### 贡献指南

我们欢迎各种形式的贡献！如果您想为 rnx 项目做出贡献，请遵循以下步骤：

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

### 开发环境设置

```bash
# 克隆仓库
git clone https://gitee.com/MM-Q/rnx.git
cd rnx

# 安装依赖
go mod tidy

# 运行测试
go test ./...

# 构建项目
go build -o rnx main.go
```

## 📞 联系方式和相关链接

- **项目仓库**: [https://gitee.com/MM-Q/rnx](https://gitee.com/MM-Q/rnx)
- **问题反馈**: [Issues](https://gitee.com/MM-Q/rnx/issues)
- **功能请求**: [Issues](https://gitee.com/MM-Q/rnx/issues)

## 🙏 致谢

感谢所有为 rnx 项目做出贡献的开发者和用户！

---

<div align="center">
  <p>如果 rnx 对您有帮助，请给我们一个 ⭐️</p>
  <p>返回顶部: <a href="#rnx">Rnx</a></p>
</div>