Skip to content

Qin-0422/workflow-cli

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

6 Commits
examples
examples
 
 
src
src
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 

Repository files navigation

workflow-cli

workflow-cli 是一个使用 Rust 实现的终端工作流自动化工具。

用户可以通过编写 YAML 配置文件描述一组带依赖关系的任务，程序负责：

  • 读取并校验工作流配置
  • 构建任务依赖图
  • 生成执行顺序
  • 执行 command / file / http 三类任务
  • 处理失败、重试与超时
  • 处理条件执行与失败策略
  • 支持变量替换、环境变量与并行执行
  • 生成 JSON / Markdown 报告
  • 以 CLI 和 TUI 两种方式展示与操作

1. 项目简介

在很多自动化场景中，我们需要按顺序执行多步操作，例如：

  1. 创建输出目录
  2. 下载远程数据
  3. 调用本地命令处理数据
  4. 保存结果并输出报告

如果直接写脚本，往往需要手动处理：

  • 执行顺序
  • 依赖关系
  • 错误传播
  • 超时与重试
  • 环境变量传递
  • 结果汇总

workflow-cli 将这类自动化过程抽象成“工作流”，使用户只需要关注“要做什么”，程序负责“如何安全、有序地执行”。

2. 核心功能

当前版本已经支持：

  • validate 校验 YAML 配置是否合法，检查缺失依赖和环依赖

  • dry-run 只展示任务执行顺序，不真正执行任务

  • run 实际执行工作流并生成 JSON / Markdown 报告

  • report 读取 JSON 报告并输出格式化摘要

  • command 任务 执行本地命令，支持超时、重试和环境变量注入

  • file 任务 支持基础文件操作：

    • mkdir
    • remove
    • copy
    • move

  • http 任务 支持：

    • 自定义 HTTP 方法
    • 请求头 headers
    • 查询参数 query_params
    • 请求体 body
    • JSON 请求体 json_body
    • 期望状态码 expected_statuses
    • 将响应保存到本地 save_to

  • 工作流增强能力

    • 条件执行 run_if
    • 失败策略 failure_policy
    • 工作流变量 vars
    • ${var_name} 占位符替换
    • 全局环境变量 env
    • 任务级环境变量 env
    • 按依赖层的并行执行

  • TUI 支持：

    • 在界面中输入工作流路径
    • 执行输入的工作流
    • 校验输入路径工作流
    • 对输入路径执行 dry-run
    • 快速运行 examples/pipeline.yaml
    • 浏览最近生成的报告
    • 选中最近报告并查看摘要
    • 滚动报告摘要内容

3. 技术栈

  • Rust edition = 2024
  • clap 命令行参数解析
  • serde / serde_yaml / serde_json 配置与报告序列化
  • thiserror 错误类型定义
  • reqwest HTTP 请求
  • tracing / tracing-subscriber 日志初始化
  • ratatui / crossterm TUI 实现
  • assert_cmd / tempfile / predicates 测试支持

4. 项目结构

FinalHW/
|- Cargo.toml
|- README.md
|- PROJECT_PLAN.md
|- examples/
|  |- pipeline.yaml
|  `- invalid_cycle.yaml
|- src/
|  |- main.rs
|  |- lib.rs
|  |- cli.rs
|  |- error.rs
|  |- config/
|  |- workflow/
|  |- executor/
|  |- model/
|  |- logging/
|  |- tui/
|  `- utils/
`- tests/

各模块职责如下：

  • config/ 负责 YAML 配置解析

  • workflow/ 负责依赖校验、环检测、拓扑排序和变量替换

  • executor/ 负责执行不同类型任务

  • model/ 定义工作流、任务、报告等核心数据结构

  • logging/ 负责日志初始化和执行报告落盘

  • tui/ 负责终端交互界面

  • tests/ 存放集成测试

5. 如何编译与运行

5.1 进入项目目录

cd C:\Users\Lenovo\Desktop\rust\FinalHW

5.2 编译项目

cargo build

5.3 运行测试

cargo test

5.4 代码格式化

cargo fmt

5.5 推荐的质量检查

cargo clippy --all-targets --all-features -- -D warnings

6. CLI 使用说明

6.1 校验工作流

cargo run -- validate examples/pipeline.yaml

6.2 查看 dry-run 执行计划

cargo run -- dry-run examples/pipeline.yaml

6.3 执行工作流

cargo run -- run examples/pipeline.yaml

执行完成后会输出：

  • 成功/失败/跳过任务统计
  • 工作流整体结果
  • 总耗时
  • JSON 报告路径

6.4 查看执行报告

cargo run -- report .flow\runs\run-20260619-xxxxxx.json

该命令会输出格式化报告摘要，而不是直接打印原始 JSON。

7. TUI 使用说明

启动方式：

cargo run -- tui

7.1 TUI 当前支持的能力

  • 在界面中输入工作流路径
  • 运行输入路径对应的工作流
  • 校验输入路径工作流
  • 对输入路径执行 dry-run
  • 快速运行 examples/pipeline.yaml
  • 查看最近 5 份报告
  • 在界面中查看最近报告摘要
  • 滚动浏览较长摘要

7.2 TUI 面板说明

TUI 当前包含这些面板：

  1. 概览
  2. 快捷操作
  3. 输入工作流
  4. 最近报告
  5. 报告摘要
  6. 运行反馈

7.3 TUI 按键说明

  • j / ↓ 向下移动焦点

  • k / ↑ 向上移动焦点

  • r 快速运行 examples/pipeline.yaml

  • v 校验输入框中的工作流路径

  • d 对输入框中的工作流路径执行 dry-run

  • x 清空输入框

  • Enter 根据当前焦点执行不同动作：

    • 当焦点在 输入工作流 面板时：执行输入框中的工作流路径
    • 当焦点在 最近报告 面板时：读取当前高亮报告并显示摘要

  • Backspace 删除输入框中的一个字符

  • q / Esc 退出 TUI

8. YAML 配置格式

工作流使用 YAML 描述。

顶层结构：

name: workflow_name
vars:
  output_dir: "./output"
env:
  API_TOKEN: "demo-token"
failure_policy: continue
tasks:
  - id: task_1
    type: command
    ...

8.1 顶层字段

  • name 工作流名称

  • vars 工作流级变量表

  • env 工作流级环境变量

  • failure_policy 工作流失败策略：

    • continue
    • continue_on_error
    • fail_fast

  • tasks 任务列表

8.2 通用任务字段

每个任务至少需要：

  • id 任务唯一标识
  • type 任务类型

可选通用字段：

  • depends_on 当前任务依赖的任务列表
  • retry 重试配置
  • timeout_secs 超时时间，单位秒
  • run_if 执行条件：
    • on_success
    • always
    • on_failure
    • on_skipped
  • env 任务级环境变量，会覆盖同名全局环境变量

9. 变量替换

当前版本支持工作流级变量替换。

你可以在顶层 vars 中定义变量，然后在多个字符串字段中使用 ${...} 引用。

例如：

name: variable_pipeline
vars:
  output_dir: "./output"
  output_file: "${output_dir}/message.txt"

tasks:
  - id: create_output
    type: file
    operation: mkdir
    path: "${output_dir}"

  - id: write_file
    type: command
    program: cmd
    args:
      - /C
      - echo hello from vars > ${output_file}
    depends_on:
      - create_output

当前支持变量替换的字段包括：

  • 工作流 name
  • 任务 id
  • depends_on
  • command.program
  • command.args
  • file.operation
  • file.path
  • file.destination
  • http.method
  • http.url
  • http.headers
  • http.body
  • http.json_body
  • http.query_params
  • http.save_to
  • 全局与任务级 env

支持嵌套变量解析，例如：

vars:
  base_dir: "./output"
  nested_file: "${base_dir}/nested.txt"

如果引用了未定义变量，工作流会在加载阶段直接失败。

10. 工作流增强能力

10.1 条件执行 run_if

支持：

  • on_success 默认值，依赖成功后执行
  • always 无论依赖是否失败都允许执行
  • on_failure 依赖失败时执行
  • on_skipped 依赖被跳过时执行

10.2 失败策略 failure_policy

支持：

  • continue 默认策略，失败后继续推进，是否执行由依赖和条件决定
  • continue_on_error 明确表示即使某些任务失败，也尽量继续执行不相关任务
  • fail_fast 一旦某个任务失败，后续剩余任务直接跳过

10.3 并行执行

当前已实现按依赖层的并行执行：

  • 拓扑排序会生成 execution_layers
  • 同一层中互不依赖的任务可并行执行
  • 层与层之间仍按顺序推进

11. 任务类型说明

11.1 command 任务

用于执行本地命令。

支持：

  • 执行本地命令
  • 捕获输出
  • 超时控制
  • 重试策略
  • 任务级环境变量注入

11.2 file 任务

用于执行基础文件系统操作。

支持操作：

  • mkdir
  • remove
  • copy
  • move

11.3 http 任务

用于发送 HTTP 请求。

支持字段：

  • method
  • url
  • headers
  • query_params
  • body
  • json_body
  • expected_statuses
  • save_to

POST 示例：

- id: create_remote_resource
  type: http
  method: POST
  url: "http://127.0.0.1:8080/resource"
  query_params:
    mode: "create"
  headers:
    Content-Type: "application/json"
  json_body: '{"name":"demo"}'
  expected_statuses: [200]

12. 示例工作流

项目内置两个示例：

  • examples/pipeline.yaml 一个合法、可运行的工作流

  • examples/invalid_cycle.yaml 一个带依赖环的非法工作流

13. 运行结果与报告

执行 run 后，程序会：

  1. 校验工作流
  2. 生成执行顺序
  3. 执行任务
  4. 将报告保存到：
.flow/runs/

当前会同时生成：

  • JSON 报告
  • Markdown 报告

报告中包含：

  • 工作流名称
  • 工作流整体结果
  • 开始/结束时间
  • 工作流总耗时
  • 每个任务的状态
  • 每个任务的尝试次数
  • 每个任务的耗时
  • 任务结果信息

使用 report 命令可以把 JSON 报告转成终端可读摘要。

TUI 中也支持查看最近报告的摘要。

14. 当前测试覆盖

当前项目已经包含这些集成测试：

  • dry-run 输出测试
  • file 任务执行测试
  • http 任务执行测试
  • http 请求头 / 请求体 / 状态码配置测试
  • http 查询参数 / JSON 请求体测试
  • http 失败状态测试
  • report 格式化输出测试
  • Markdown 报告生成测试
  • command 超时测试
  • 合法工作流校验测试
  • 重复任务 ID 检测测试
  • 变量替换成功测试
  • 嵌套变量解析测试
  • 未定义变量报错测试
  • run_if: on_failure 测试
  • run_if: always 测试
  • run_if: on_success 测试
  • continue_on_error 测试
  • fail_fast 测试
  • fail_fast 多层任务测试
  • 并行执行测试
  • 多层并行测试

运行方式：

cargo test

15. 已完成与待扩展内容

已完成

  • CLI 核心功能
  • YAML 配置解析
  • DAG 依赖校验与拓扑排序
  • command / file / http 三类任务执行
  • 失败、跳过、重试、超时处理
  • 条件执行与失败策略
  • 变量替换
  • 全局与任务级环境变量
  • 按层并行执行
  • JSON / Markdown 报告输出
  • 增强版 TUI
  • 集成测试

待扩展

  • 更复杂的条件表达式系统
  • 更细粒度并发控制，例如最大并发数
  • 插件化执行器
  • 更丰富的报告筛选和导出格式

16. 课程项目亮点

这个项目适合用于课程作业展示的点包括：

  • 不是简单 CRUD，也不是纯前端项目
  • Rust 代码是核心逻辑而不是配角
  • 能体现模块化设计、依赖调度和错误处理
  • 具备真实工具软件的工程结构
  • 有文档、有测试、有报告输出
  • 还具备一个可交互的 TUI 演示界面
  • 工作流本身支持条件执行、失败策略、变量替换、环境变量和并行执行

17. 后续建议

如果继续完善本项目，优先建议：

  1. 在 TUI 中增加更多动作按钮，如快速查看 Markdown 报告
  2. 增加最大并发数限制
  3. 增加更复杂的条件表达式
  4. 保持 cargo clippy 无告警

18. 作者说明

本项目为 Rust 课程期末项目，聚焦于“终端工作流自动化工具”的设计与实现。

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages