WorkBuddy 快速开始：从安装到第一个自动化任务

1. 引言

WorkBuddy 是一款面向开发者和运维人员的自动化任务编排工具，它通过简洁的配置文件和命令行接口，帮助你把重复性的工作流程固化为可复用的自动化任务。本文将从零开始，带你完成 WorkBuddy 的安装、初始化、编写第一个任务，并逐步深入到参数传递、条件判断、定时调度等进阶用法。

在开始之前，请确保你的机器满足以下环境要求：

• 操作系统：Linux / macOS / Windows（WSL 推荐）
• 运行时：Python 3.9 及以上，或 Node.js 16 及以上
• 网络：可访问官方软件源，用于下载依赖包

2. 安装 WorkBuddy

WorkBuddy 提供了多种安装方式，你可以根据自己的技术栈选择最合适的一种。

2.1 使用 pip 安装（Python 环境）

如果你使用 Python，推荐通过 pip 直接安装：

pip install workbuddy

安装完成后，验证版本号：

workbuddy --version

如果输出类似 workbuddy 0.9.2 的版本信息，说明安装成功。

2.2 使用 npm 安装（Node.js 环境）

对于 Node.js 用户，可以使用 npm 全局安装：

npm install -g workbuddy

同样验证安装结果：

workbuddy --version

2.3 使用 Docker 运行

如果你希望隔离环境，也可以直接使用官方 Docker 镜像：

docker pull workbuddy/workbuddy:latest
docker run --rm -v $(pwd):/workspace workbuddy/workbuddy:latest --version

这里把当前目录挂载到容器的 /workspace，方便容器内访问你的任务文件。

3. 初始化项目

安装完成后，我们需要创建一个 WorkBuddy 项目目录，并生成基础配置文件。

3.1 创建项目目录

mkdir my-workbuddy-demo
cd my-workbuddy-demo

3.2 初始化项目

在项目根目录执行初始化命令：

workbuddy init

执行后，WorkBuddy 会自动生成以下文件结构：

my-workbuddy-demo/
├── workbuddy.yaml          # 主配置文件
├── tasks/                  # 任务目录
│   └── hello.yaml          # 示例任务
└── logs/                   # 运行日志目录

其中 workbuddy.yaml 是全局配置文件，tasks/ 目录用于存放具体的任务定义文件。

3.3 查看默认配置

打开 workbuddy.yaml，内容大致如下：

project:
  name: my-workbuddy-demo
  version: 0.1.0
runner:
default: local
timeout: 300
logging:
level: info
output: logs/

这里定义了项目名称、默认执行器、超时时间以及日志级别。你可以根据实际需求调整这些参数。

4. 编写第一个任务

初始化完成后，我们来看一下自动生成的示例任务 tasks/hello.yaml：

name: hello
description: 打印欢迎信息
steps:
  - echo:
      message: "Hello, WorkBuddy!"

这个任务非常简单：它只有一个步骤，调用内置的 echo 动作，输出一行欢迎信息。

4.1 运行任务

在项目根目录执行以下命令运行任务：

workbuddy run hello

运行结果如下：

[2026-09-12 18:00:01] INFO  Starting task: hello
[2026-09-12 18:00:01] INFO  Step 1/1: echo
Hello, WorkBuddy!
[2026-09-12 18:00:01] INFO  Task completed successfully

恭喜，你已经成功运行了第一个 WorkBuddy 任务。

4.2 任务文件结构说明

一个标准的 WorkBuddy 任务文件包含三个核心字段：

• name：任务名称，用于命令行调用。
• description：任务描述，便于阅读和维护。
• steps：步骤列表，按顺序执行的动作集合。

5. 常用动作与参数传递

WorkBuddy 内置了丰富的动作库，下面介绍几个最常用的动作，以及如何在步骤之间传递参数。

5.1 执行 Shell 命令

使用 shell 动作可以执行任意系统命令：

name: system-info
description: 收集系统信息
steps:
  - shell:
      command: "uname -a"
  - shell:
      command: "df -h"

5.2 读写文件

使用 file.read 和 file.write 动作可以读写文件：

name: file-demo
description: 文件读写示例
steps:
  - file.write:
      path: "./output.txt"
      content: "这是写入的内容"
  - file.read:
      path: "./output.txt"

5.3 步骤间传递参数

WorkBuddy 支持通过 output 字段捕获步骤结果，并在后续步骤中引用：

name: param-demo
description: 参数传递示例
steps:
  - shell:
      command: "echo 'hello from shell'"
    output: shell_result
  - echo:
      message: "上一步的输出是：${shell_result}"

这里 ${shell_result} 会引用上一步捕获的输出内容。

6. 条件判断与循环

真实场景中，任务往往需要根据条件分支执行，或者对一组数据重复处理。

6.1 条件判断

使用 when 字段可以为步骤添加执行条件：

name: conditional-demo
description: 条件判断示例
steps:
  - shell:
      command: "test -f /etc/passwd"
    output: passwd_exists
  - echo:
      message: "文件存在"
    when: "${passwd_exists} == true"
  - echo:
      message: "文件不存在"
    when: "${passwd_exists} == false"

6.2 循环处理

使用 foreach 可以对列表数据逐项处理：

name: loop-demo
description: 循环处理示例
steps:
  - foreach:
      items: ["apple", "banana", "cherry"]
      as: fruit
      do:
        - echo:
            message: "当前水果：${fruit}"

运行后，会依次输出三种水果的名称。

7. 定时调度任务

WorkBuddy 支持通过 cron 表达式配置定时任务，适合周期性执行的场景。

7.1 配置定时任务

在 workbuddy.yaml 中增加 schedule 配置：

project:
  name: my-workbuddy-demo
  version: 0.1.0
runner:
default: local
timeout: 300
logging:
level: info
output: logs/
schedule:
task: hello
cron: "0 9 * * *"

上面的配置表示每天上午 9 点执行一次 hello 任务。

7.2 启动调度器

执行以下命令启动调度器：

workbuddy schedule

调度器会常驻后台，按照 cron 表达式触发对应的任务。

8. 实战：日志清理任务

下面我们综合运用前面学到的知识，编写一个实用的日志清理任务。该任务会删除指定目录下超过 7 天的 .log 文件。

name: clean-logs
description: 清理超过 7 天的日志文件
steps:
  - shell:
      command: "find ./logs -name '*.log' -mtime +7"
    output: old_files
  - shell:
      command: "find ./logs -name '*.log' -mtime +7 -delete"
    when: "${old_files} != ''"
  - echo:
      message: "日志清理完成"

这个任务先查找符合条件的旧日志文件，如果存在则执行删除，最后输出完成提示。

9. 常见问题与排查

在使用过程中，你可能会遇到一些常见问题，这里给出对应的排查思路。

10. 总结

本文从安装、初始化、编写第一个任务开始，逐步介绍了 WorkBuddy 的常用动作、参数传递、条件判断、循环处理、定时调度等核心能力，并通过一个日志清理的实战案例串联了全部知识点。

WorkBuddy 的价值在于把零散的运维和开发操作沉淀为可复用、可调度的自动化任务。建议你从自己日常最重复的操作入手，逐步积累自己的任务库。更多高级用法，可以参考官方文档中的动作参考和最佳实践章节。