WorkBuddy 创建任务：从入门到实战的完整指南

1. 引言

WorkBuddy 是一款面向团队协作与自动化的工作流管理工具，它通过「任务」这一核心概念，把零散的工作项、审批流程和自动化动作串联起来。无论是日常待办、跨部门协作，还是定时触发的自动化任务，WorkBuddy 都提供了统一且可扩展的创建与管理方式。

本文将从 WorkBuddy 任务模型的基本概念出发，逐步讲解如何通过界面、命令行以及 API 三种方式创建任务，并给出丰富的代码实例，帮助你在实际项目中快速落地。

2. 任务模型与核心概念

在动手创建任务之前，先理解 WorkBuddy 的任务模型。一个任务由以下核心字段组成：

• 任务名称（name）：任务的唯一标识，建议使用语义化命名，例如「订单超时自动提醒」。
• 任务类型（type）：决定任务的执行方式，常见类型包括一次性任务、定时任务和事件触发任务。
• 执行动作（action）：任务实际执行的操作，例如发送通知、调用接口、更新数据库记录等。
• 调度规则（schedule）：对于定时任务，定义触发的时间表达式或周期。
• 优先级（priority）：控制任务在队列中的执行顺序，取值从 0（最低）到 10（最高）。
• 超时时间（timeout）：任务允许运行的最长秒数，超过后将被强制终止。
• 重试策略（retry）：任务失败后的重试次数与间隔。

下面是一个任务对象的 JSON 结构示例，它清晰地展示了各字段的层级关系：

{ "name": "order_timeout_alert", "type": "scheduled", "action": { "kind": "webhook", "url": "https://api.example.com/notify", "method": "POST", "headers": { "Authorization": "Bearer ${TOKEN}" }, "payload": { "message": "订单超时，请及时处理" } }, "schedule": { "cron": "0 */5 * * * ?" }, "priority": 5, "timeout": 60, "retry": { "max_attempts": 3, "backoff_seconds": 10 } }

3. 通过 Web 控制台创建任务

对于不熟悉编程的团队成员，Web 控制台是最直观的创建方式。登录 WorkBuddy 后，进入「任务管理」页面，点击右上角的「新建任务」按钮，即可打开创建向导。

创建向导分为四个步骤：

1. 基本信息：填写任务名称、描述，并选择任务类型。
2. 配置动作：选择动作类型（Webhook、脚本、消息通知等），并填写对应参数。
3. 设置调度：对于定时任务，选择 Cron 表达式或使用可视化周期选择器。
4. 确认并发布：检查所有配置，点击「发布」后任务立即生效。

控制台创建的任务会自动生成对应的 API 配置，你可以在任务详情页的「导出配置」中查看其 JSON 表示，方便后续迁移到代码中管理。

4. 使用命令行工具创建任务

WorkBuddy 提供了官方命令行工具wb，适合在开发环境或 CI/CD 流水线中快速创建任务。首先安装 CLI 工具：

npm install -g @workbuddy/cli

安装完成后，使用wb login进行身份认证：

wb login --api-key YOUR_API_KEY

接下来，通过wb task create命令创建任务。以下示例创建一个每 10 分钟执行一次的定时任务：

wb task create \ --name "health_check" \ --type scheduled \ --action '{"kind":"http","url":"https://api.example.com/ping","method":"GET"}' \ --schedule '{"cron":"0 */10 * * * ?"}' \ --priority 3 \ --timeout 30

命令执行成功后，CLI 会返回新任务的任务 ID 和状态：

Task created successfully: ID: task_8f3a2b9c Name: health_check Status: active

如果需要批量创建任务，可以将多个任务定义写入一个 YAML 文件，然后使用wb task apply一次性导入：

tasks: - name: daily_report type: scheduled action: kind: script language: python code: | print("Generating daily report...") schedule: cron: "0 0 9 * * ?" - name: data_sync type: event action: kind: webhook url: "https://api.example.com/sync" method: POST event: source: "database.change" filter: "table == 'orders'"

wb task apply --file tasks.yaml

5. 使用 REST API 创建任务

对于需要深度集成到业务系统中的场景，WorkBuddy 提供了完整的 REST API。创建任务的接口为POST /api/v1/tasks，请求体为任务对象的 JSON 表示。

下面是一个使用 cURL 创建任务的示例：

curl -X POST "https://api.workbuddy.io/api/v1/tasks" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "invoice_reminder", "type": "scheduled", "action": { "kind": "email", "to": "[e-mail]", "subject": "发票待处理提醒", "body": "本月尚有 3 张发票未处理，请及时跟进。" }, "schedule": { "cron": "0 0 18 * * ?" }, "priority": 7 }'

接口返回 201 状态码，响应体包含创建后的完整任务对象：

{ "id": "task_9c1d4e7f", "name": "invoice_reminder", "type": "scheduled", "status": "active", "created_at": "2026-08-29T08:30:00Z", "schedule": { "cron": "0 0 18 * * ?" } }

6. 使用 SDK 创建任务（Python 示例）

WorkBuddy 官方提供了 Python SDK，封装了底层 API 调用，让任务创建更加简洁。首先安装 SDK：

pip install workbuddy-sdk

以下代码演示了如何使用 Python SDK 创建一个定时任务：

from workbuddy import WorkBuddyClient, Task, Action, Schedule 初始化客户端 client = WorkBuddyClient(api_key="YOUR_API_KEY") 构建任务对象 task = Task( name="weekly_summary", type="scheduled", action=Action( kind="webhook", url="https://api.example.com/summary", method="POST", payload={"channel": "#weekly"} ), schedule=Schedule(cron="0 0 10 ? * MON"), priority=4, timeout=120 ) 创建任务 created = client.tasks.create(task) print(f"任务创建成功，ID: {created.id}")

SDK 还支持异步创建，适合在异步框架（如 FastAPI）中使用：

import asyncio from workbuddy import AsyncWorkBuddyClient async def create_task_async(): client = AsyncWorkBuddyClient(api_key="YOUR_API_KEY") task = Task( name="async_cleanup", type="scheduled", action=Action(kind="script", language="python", code="print('cleaning...')"), schedule=Schedule(cron="0 0 3 * * ?") ) created = await client.tasks.create(task) print(f"异步任务创建成功，ID: {created.id}") asyncio.run(create_task_async())

7. 使用 SDK 创建任务（Java 示例）

对于 Java 技术栈的团队，WorkBuddy 同样提供了官方 Java SDK。在pom.xml中添加依赖：

<dependency> <groupId>io.workbuddy</groupId> <artifactId>workbuddy-sdk</artifactId> <version>1.4.2</version> </dependency>

下面是一个使用 Java SDK 创建任务的完整示例：

import io.workbuddy.WorkBuddyClient; import io.workbuddy.model.Task; import io.workbuddy.model.Action; import io.workbuddy.model.Schedule; public class CreateTaskExample { public static void main(String[] args) { // 初始化客户端 WorkBuddyClient client = new WorkBuddyClient.Builder() .apiKey("YOUR_API_KEY") .build(); // 构建任务对象 Task task = Task.builder() .name("order_sync") .type("scheduled") .action(Action.builder() .kind("http") .url("https://api.example.com/orders/sync") .method("POST") .build()) .schedule(Schedule.builder() .cron("0 0 */2 * * ?") .build()) .priority(6) .timeout(90) .build(); // 创建任务 Task created = client.tasks().create(task); System.out.println("任务创建成功，ID: " + created.getId()); } }

8. 创建任务的常见模式与最佳实践

在实际项目中，任务创建往往不是孤立的操作，而是与业务逻辑深度绑定。以下是几种常见模式：

8.1 幂等创建

当任务可能被重复创建时（例如服务重启后的补偿逻辑），建议先查询再创建，避免产生重复任务：

existing = client.tasks.list(name="order_timeout_alert") if not existing: task = Task(name="order_timeout_alert", type="scheduled", ...) client.tasks.create(task) else: print(f"任务已存在，ID: {existing[0].id}")

8.2 动态参数注入

任务动作中的参数往往需要动态生成，例如在创建任务时注入当前环境的 Token：

import os token = os.environ.get("WEBHOOK_TOKEN") action = Action( kind="webhook", url="https://api.example.com/notify", method="POST", headers={"Authorization": f"Bearer {token}"} )

8.3 批量创建与错误处理

当需要一次性创建多个任务时，建议逐条捕获异常，避免单条失败导致整体中断：

task_defs = [ {"name": "task_a", "type": "scheduled", "schedule": {"cron": "0 0 8 * * ?"}}, {"name": "task_b", "type": "scheduled", "schedule": {"cron": "0 0 9 * * ?"}}, {"name": "task_c", "type": "scheduled", "schedule": {"cron": "0 0 10 * * ?"}}, ] for definition in task_defs: try: task = Task(**definition) client.tasks.create(task) print(f"成功创建: {definition['name']}") except Exception as e: print(f"创建失败 {definition['name']}: {e}")

9. 任务创建后的验证与监控

任务创建成功后，建议立即验证其配置是否正确。可以通过查询接口获取任务详情，确认调度规则和动作参数无误：

curl -X GET "https://api.workbuddy.io/api/v1/tasks/task_9c1d4e7f" \ -H "Authorization: Bearer YOUR_API_TOKEN"

同时，WorkBuddy 提供了任务运行日志查询接口，用于监控任务的实际执行情况：

curl -X GET "https://api.workbuddy.io/api/v1/tasks/task_9c1d4e7f/runs?limit=10" \ -H "Authorization: Bearer YOUR_API_TOKEN"

建议在任务创建后设置一个「探针任务」，定期检查核心任务是否正常运行，并在异常时触发告警通知。

10. 总结

本文从 WorkBuddy 的任务模型出发，系统介绍了通过 Web 控制台、命令行工具、REST API 以及 Python/Java SDK 创建任务的完整流程，并给出了丰富的代码实例。核心要点总结如下：

• 理解任务模型：掌握 name、type、action、schedule 等核心字段，是正确创建任务的前提。
• 选择合适的创建方式：控制台适合日常管理，CLI 适合脚本化操作，API 和 SDK 适合深度集成。
• 遵循最佳实践：幂等创建、动态参数注入和批量错误处理能显著提升任务管理的健壮性。
• 重视验证与监控：创建后的验证和运行日志监控，是保障任务稳定运行的关键环节。

希望本文能帮助你快速上手 WorkBuddy 的任务创建，并在实际项目中灵活运用。