# nworkflow

**Repository Path**: colid/nworkflow

## Basic Information

- **Project Name**: nworkflow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nworkflow

Nworkflow 是一个轻量级的工作流自动化工具，支持事件驱动的工作流执行，可在多种操作系统和桌面环境中运行。

## 功能特性

- **事件驱动架构**: 支持多种事件类型，包括系统事件、文件事件、HTTP事件、Git事件等
- **工作流引擎**: 支持YAML配置的工作流定义，支持条件执行和上下文传递
- **全局事件代理**: 支持文件监听、定时任务、心跳机制
- **跨平台兼容**: 支持 Windows、macOS、Linux 及多种桌面环境
- **Python扩展**: 支持编写Python脚本来扩展事件处理和自定义步骤
- **多平台工作流**: 自动为不同平台选择对应的工作流配置

## 支持的事件类型

Nworkflow 提供了丰富的标准事件类型，可用于触发工作流执行。

### 系统事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `system.start` | 系统启动事件 | `{platform, desktop, os_version}` | 事件代理启动时自动触发 |
| `system.shutdown` | 系统关闭事件 | `{}` | 事件代理停止时自动触发 |
| `system.heartbeat` | 系统心跳事件 | `{timestamp}` | 每分钟自动触发一次 |

**数据字段说明**：
- `platform`: 当前操作系统 (win/linux/mac)
- `desktop`: 当前桌面环境 (gnome/kde/xfce/windows/macos)
- `os_version`: 操作系统版本信息
- `timestamp`: ISO格式时间戳

### 文件事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `file.create` | 文件创建事件 | `{path, platform}` | 文件被创建时 |
| `file.modify` | 文件修改事件 | `{path, mtime, platform}` | 文件内容被修改时 |
| `file.delete` | 文件删除事件 | `{path, platform}` | 文件被删除时 |
| `file.rename` | 文件重命名事件 | `{path, old_path, platform}` | 文件被重命名时 |

**数据字段说明**：
- `path`: 文件路径
- `old_path`: 原文件路径（仅rename事件）
- `mtime`: 文件修改时间戳
- `platform`: 当前操作系统

### HTTP事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `http.request` | HTTP请求事件 | `{method, path, status_code, headers, body, platform}` | HTTP请求成功时 |
| `http.response` | HTTP响应事件 | `{method, path, status_code, headers, body, platform}` | HTTP响应完成时 |

**数据字段说明**：
- `method`: HTTP方法 (GET/POST/PUT/DELETE等)
- `path`: 请求路径
- `status_code`: HTTP状态码
- `headers`: 请求头字典
- `body`: 请求/响应体

### 工作流事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `workflow.start` | 工作流开始事件 | `{workflow_name}` | 工作流开始执行时 |
| `workflow.complete` | 工作流完成事件 | `{workflow_name, success}` | 工作流执行完成时 |
| `workflow.error` | 工作流错误事件 | `{workflow_name, error, step}` | 工作流执行出错时 |
| `workflow.step` | 步骤执行事件 | `{workflow_name, step_name, step_type}` | 每个步骤执行时 |

**数据字段说明**：
- `workflow_name`: 工作流名称
- `success`: 是否成功完成
- `error`: 错误信息
- `step`: 出错步骤名称
- `step_name`: 步骤名称
- `step_type`: 步骤类型

### 定时器事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `timer.tick` | 定时器触发事件 | `{interval}` | 定时器触发时 |
| `timer.scheduled` | 定时任务事件 | `{event_name, data}` | 定时任务执行时 |

**数据字段说明**：
- `interval`: 定时器间隔（秒）
- `event_name`: 关联的事件名称
- `data`: 自定义数据

### Git事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `git.commit` | Git提交事件 | `{repo_path, commit_hash, branch, platform}` | 检测到git commit时 |
| `git.push` | Git推送事件 | `{repo_path, branch, platform}` | 检测到git push时 |
| `git.pull` | Git拉取事件 | `{repo_path, branch, platform}` | 检测到git pull时 |

**数据字段说明**：
- `repo_path`: 仓库路径
- `commit_hash`: 提交哈希值
- `branch`: 分支名称

### 桌面事件

| 事件名称 | 说明 | 数据结构 | 触发场景 |
|---------|------|---------|---------|
| `desktop.*` | 桌面事件 | `{desktop, platform, os_version, ...}` | 桌面环境相关操作 |

### 自定义事件

除了标准事件外，您还可以创建自定义事件：

```bash
# 通过命令行触发自定义事件
python main.py event custom.my_event --data '{"key": "value"}'

# 通过代理触发自定义事件
python main.py proxy emit custom.my_event
```

### 事件匹配模式

工作流配置支持灵活的事件匹配：

```yaml
workflows:
  - name: all_events
    when:
      event: "*"           # 匹配所有事件
  
  - name: git_events
    when:
      event: "git.*"       # 匹配所有git事件
  
  - name: specific_event
    when:
      event: "git.commit"  # 精确匹配
      data:                # 数据条件匹配
        branch: "main"
```

## 安装

```bash
# 克隆项目
git clone https://github.com/yourname/nworkflow.git
cd nworkflow

# 安装依赖（如果有）
pip install pyyaml
```

## 快速开始

### 创建工作流配置

创建 `.nworkflow/.workflow.yml` 文件（通用配置）：

```yaml
workflows:
  - name: git_commit
    when:
      event: git.commit
  - name: system_cleanup
    when:
      event: system.cleanup
```

#### 多平台配置

为不同平台创建特定配置：

- `.nworkflow/.workflow.win.yml` - Windows配置
- `.nworkflow/.workflow.linux.yml` - Linux配置
- `.nworkflow/.workflow.mac.yml` - macOS配置

系统会自动选择对应平台的配置文件，如果没有特定平台的配置，则使用默认的 `.workflow.yml`。

### 创建工作流定义

同样支持多平台的工作流定义：

- `.nworkflow/git_commit.yml` - 通用工作流
- `.nworkflow/git_commit.win.yml` - Windows专用
- `.nworkflow/git_commit.linux.yml` - Linux专用
- `.nworkflow/git_commit.mac.yml` - macOS专用

Linux示例工作流（`.nworkflow/git_commit.linux.yml`）：

```yaml
name: git_commit
description: Linux Git commit workflow
when:
  event: git.commit

steps:
  - name: Check git status
    type: shell
    run: git status

  - name: Stage all changes
    type: shell
    run: git add -A

  - name: Create commit
    type: shell
    run: git commit -m "${message}"

  - name: Push to remote
    type: shell
    run: git push

  - name: Send desktop notification
    type: shell
    run: notify-send "Nworkflow" "Commit successful"
```

### 运行工作流

```bash
# 列出可用工作流
python main.py list

# 查看当前平台
python main.py platform

# 运行工作流
python main.py run git_commit --data '{"message": "Initial commit"}'

# 触发事件
python main.py event git.commit --data '{"message": "Test commit"}'
```

## 命令行接口

### 基本命令

```bash
python main.py list                    # 列出工作流
python main.py run <workflow>          # 运行工作流
python main.py show <workflow>         # 显示工作流详情
python main.py event <name>            # 触发事件
python main.py history                 # 查看事件历史
python main.py extensions              # 列出加载的扩展
python main.py platform                # 显示当前平台
```

### 代理服务命令

```bash
python main.py proxy start             # 启动事件代理
python main.py proxy stop              # 停止事件代理
python main.py proxy status            # 查看代理状态
python main.py proxy watch <path>      # 监听文件变化
python main.py proxy timer <interval> <event>  # 创建定时任务
python main.py proxy emit <type>       # 发射事件
```

## 工作流定义

### Step 类型

1. **shell**: 执行 shell 命令
2. **python**: 执行 Python 代码
3. **copy**: 复制文件/目录
4. **delete**: 删除文件/目录
5. **mkdir**: 创建目录
6. **move**: 移动文件/目录
7. **extension**: 执行自定义扩展

### 扩展步骤

使用 `extension` 类型来调用自定义Python扩展：

```yaml
steps:
  - name: Custom notification
    type: extension
    extension: notification
```

### 条件执行

```yaml
steps:
  - name: Conditional Step
    type: shell
    run: echo "Hello World"
    when:
      condition: "${environment} == 'production'"
```

### 变量替换

工作流支持通过 `${variable}` 语法进行变量替换：

```yaml
steps:
  - name: Print Message
    type: shell
    run: echo "Message: ${message}"
```

## Python扩展

### 编写扩展

在 `.nworkflow/extensions/` 目录下创建Python文件，例如 `example.py`：

```python
from typing import Dict, Any


def custom_event_handler(event, runner) -> bool:
    """
    自定义事件处理器
    
    Args:
        event: 事件对象
        runner: WorkflowRunner实例
    
    Returns:
        bool: 处理是否成功
    """
    print(f"Custom extension handling event: {event.name}")
    
    # 访问上下文
    context = runner.context.get_all()
    print(f"Context data: {context}")
    
    # 可以在这里执行自定义逻辑
    # 例如发送通知、调用API、处理数据等
    
    return True


def register_extensions():
    """
    注册扩展的标准函数
    
    Returns:
        List[Dict]: 扩展定义列表
    """
    return [
        {
            "name": "custom.event",
            "handler": custom_event_handler,
            "description": "自定义事件处理示例",
            "priority": 10
        },
        {
            "name": "notification",
            "handler": lambda event, runner: (
                print(f"Notification: {event.data.get('message', 'Hello')}"),
                True
            )[1],
            "description": "简单通知扩展",
            "priority": 5
        }
    ]
```

### 扩展结构

扩展模块必须包含 `register_extensions()` 函数，该函数返回扩展定义列表，每个定义包含：

- `name`: 扩展名称（用于在工作流中引用）
- `handler`: 处理函数，接收 `event` 和 `runner` 参数
- `description`: 扩展描述
- `priority`: 优先级（数字越大优先级越高）

### 使用扩展

在工作流中通过 `type: extension` 和 `extension: <name>` 来调用扩展：

```yaml
steps:
  - name: Send custom notification
    type: extension
    extension: notification
```

## 跨平台兼容性

### 操作系统支持

| 操作系统 | 状态 | 说明 |
|---------|------|------|
| Linux | ✅ 支持 | 完整功能 |
| macOS | ✅ 支持 | 完整功能 |
| Windows | ✅ 支持 | 完整功能 |

### 桌面环境支持

| 桌面环境 | 状态 |
|---------|------|
| GNOME | ✅ 支持 |
| KDE | ✅ 支持 |
| Xfce | ✅ 支持 |
| MATE | ✅ 支持 |
| LXQt | ✅ 支持 |
| Cinnamon | ✅ 支持 |
| macOS (Aqua) | ✅ 支持 |
| Windows (Explorer) | ✅ 支持 |

### 路径处理

Nworkflow 自动处理不同操作系统的路径格式：

- Windows: `C:\Users\user\file.txt`
- Unix-like: `/home/user/file.txt`

### 多平台工作流

为不同平台创建专用工作流文件：

```
.nworkflow/
├── .workflow.yml                # 通用配置
├── .workflow.win.yml            # Windows配置
├── .workflow.linux.yml          # Linux配置
├── .workflow.mac.yml            # macOS配置
├── git_commit.yml               # 通用工作流
├── git_commit.win.yml           # Windows工作流
├── git_commit.linux.yml         # Linux工作流
├── git_commit.mac.yml           # macOS工作流
└── extensions/
    └── example.py               # 扩展文件
```

系统会自动选择当前平台的工作流文件。

### 命令兼容性

```yaml
steps:
  - name: List files (Linux/macOS)
    type: shell
    run: ls
```

通过创建不同平台的工作流文件来实现命令兼容性。

## API 使用

```python
from workflow import WorkflowRunner, GlobalEventProxy, PlatformUtils

# 创建工作流运行器
runner = WorkflowRunner()

# 运行工作流
runner.run_workflow('git_commit', {'message': 'Test'})

# 获取当前平台
print(runner.get_platform())

# 使用全局事件代理
proxy = GlobalEventProxy.get_instance()
proxy.start()

# 监听文件
proxy.watch_file('/path/to/file.txt')

# 调度定时任务
proxy.schedule_timer(60, 'timer.minutely')

# 平台工具
print(f"Is Windows? {PlatformUtils.is_windows()}")
print(f"Is macOS? {PlatformUtils.is_macos()}")
print(f"Is Linux? {PlatformUtils.is_linux()}")
```

## 项目结构

```
nworkflow/
├── main.py                    # CLI 入口
├── workflow/                  # 核心模块
│   ├── __init__.py            # 包初始化
│   ├── cli.py                 # 命令行接口
│   ├── context.py             # 上下文管理
│   ├── event.py               # 事件系统
│   ├── parser.py              # 配置解析器
│   ├── proxy.py               # 事件代理服务
│   ├── runner.py              # 工作流引擎
│   └── step.py                # 步骤执行器
└── .nworkflow/               # 工作流配置目录
    ├── .workflow.yml          # 主配置（通用）
    ├── .workflow.win.yml      # Windows配置
    ├── .workflow.linux.yml    # Linux配置
    ├── .workflow.mac.yml      # macOS配置
    ├── git_commit.yml         # 工作流定义（通用）
    ├── git_commit.win.yml     # Windows工作流
    ├── git_commit.linux.yml   # Linux工作流
    ├── git_commit.mac.yml     # macOS工作流
    └── extensions/
        └── example.py         # Python扩展示例
```

## 开发

### 运行测试

```bash
# 运行所有测试
python -m pytest

# 运行特定测试
python -m pytest tests/test_runner.py
```

### 代码规范

```bash
# 使用 flake8 检查代码风格
flake8 workflow/

# 使用 black 格式化代码
black workflow/
```

## 许可证

MIT License