refactor(layout): consolidate backend codebase into backend/ package and clean root directory

- Moved cmd/, core/, plugins/, pkg/, downstream/, and main.go into backend/ directory
- Batch updated all Go source files to import github.com/Rain-kl/Wavelet/backend/...
- Updated Makefile, scripts/swagger.sh, architecture guards, and platform skills
- Passed all quality gates (100% tests, 0 lint issues, clean build)

backend/plugins/drivers/driver_asynq_worker/constants.go

@@ -0,0 +1,13 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+// 任务队列名称
+const (
+	QueueDefault = "default"
+)
+
+// DefaultMaxRetry 任务默认最大重试次数
+const DefaultMaxRetry = 3

backend/plugins/drivers/driver_asynq_worker/errs.go

@@ -0,0 +1,17 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+const (
+	errUnknownTaskType            = "未知的任务类型: %s"
+	errCreateTaskExecutionFailed  = "创建任务执行记录失败: %w"
+	errTaskEnqueueFailed          = "任务入队失败: %w"
+	errTaskExecutionNotFound      = "任务执行记录不存在: %w"
+	errRetryOnlyFailedTask        = "只有失败的任务才能重试，当前状态: %s"
+	errTaskNotRetryable           = "该任务不支持重试"
+	errTaskMaxRetryExceeded       = "已达到最大重试次数 %d"
+	errCreateRetryExecutionFailed = "创建重试任务执行记录失败: %w"
+	errRetryTaskEnqueueFailed     = "重试任务入队失败: %w"
+	errUnregisteredTaskHandler    = "未注册的任务处理器: %s"
+)

backend/plugins/drivers/driver_asynq_worker/executor.go

@@ -0,0 +1,500 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/idgen"
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	otel_trace "github.com/Rain-kl/Wavelet/backend/pkg/trace"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+)
+
+var (
+	handlerRegistryMutex sync.RWMutex
+	handlerRegistry      = make(map[string]TaskHandler)
+
+	completedHandlersMutex sync.RWMutex
+	taskCompletedHandlers  []CompletedHandler
+)
+
+// CompletedHandler is called when a task execution completes.
+type CompletedHandler func(ctx context.Context, execution *TaskExecution, result *TaskResult, execErr error)
+
+// OnTaskCompleted registers a handler for task completion events.
+// Handlers must be registered during application bootstrap before processing tasks.
+func OnTaskCompleted(handler CompletedHandler) {
+	completedHandlersMutex.Lock()
+	defer completedHandlersMutex.Unlock()
+	taskCompletedHandlers = append(taskCompletedHandlers, handler)
+}
+
+// RegisterHandler 注册任务处理器
+// 传入任务类型标识（对应 AsynqTask 常量）和 TaskHandler 实现
+func RegisterHandler(asynqTaskType string, handler TaskHandler) {
+	handlerRegistryMutex.Lock()
+	defer handlerRegistryMutex.Unlock()
+	handlerRegistry[asynqTaskType] = handler
+}
+
+// getHandler 获取已注册的处理器
+func getHandler(asynqTaskType string) (TaskHandler, bool) {
+	handlerRegistryMutex.RLock()
+	defer handlerRegistryMutex.RUnlock()
+	h, ok := handlerRegistry[asynqTaskType]
+	return h, ok
+}
+
+// ValidateAndNormalizePayload 校验并标准化任务参数。
+// 如果 Handler 实现了 PayloadValidator，调用其 ValidatePayload 方法；
+// 否则直接返回原始 payload。
+func ValidateAndNormalizePayload(asynqTaskType string, payload []byte) ([]byte, error) {
+	handler, ok := getHandler(asynqTaskType)
+	if !ok {
+		return payload, nil
+	}
+	if validator, ok := handler.(PayloadValidator); ok {
+		return validator.ValidatePayload(payload)
+	}
+	return payload, nil
+}
+
+// contextKey 用于 context 存取 taskID
+type contextKey string
+
+const taskIDKey contextKey = "task_execution_task_id"
+const traceEnvelopeVersion = 1
+
+type traceEnvelope struct {
+	WaveletTraceEnvelope bool              `json:"_wavelet_trace_envelope"`
+	Version              int               `json:"version"`
+	TraceContext         map[string]string `json:"trace_context,omitempty"`
+	Payload              []byte            `json:"payload"`
+}
+
+// withTaskID 将 taskID 注入 context
+func withTaskID(ctx context.Context, taskID string) context.Context {
+	return context.WithValue(ctx, taskIDKey, taskID)
+}
+
+// GetTaskID 从 context 中获取 taskID
+func GetTaskID(ctx context.Context) string {
+	if v, ok := ctx.Value(taskIDKey).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// IsFinalAttempt 判断当前任务执行是否为最后一次重试尝试（若再次失败即为最终失败）
+func IsFinalAttempt(ctx context.Context) bool {
+	retryCount, hasRetryCount := asynq.GetRetryCount(ctx)
+	maxRetry, hasMaxRetry := asynq.GetMaxRetry(ctx)
+	if !hasRetryCount || !hasMaxRetry {
+		return true
+	}
+	return retryCount >= maxRetry
+}
+
+// AppendLog 追加日志到任务执行记录
+// 在 TaskHandler.Execute 中调用，日志会自动追加到 TaskExecution.Log 字段
+func AppendLog(ctx context.Context, format string, args ...interface{}) {
+	taskID := GetTaskID(ctx)
+	if taskID == "" {
+		// 上下文中没有 taskID，降级到普通日志
+		logger.InfoF(ctx, format, args...)
+		return
+	}
+
+	logLine := fmt.Sprintf(format, args...)
+	if err := appendTaskExecutionLog(ctx, taskID, logLine); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加任务日志失败 taskID=%s: %v", taskID, err)
+	}
+}
+
+// DispatchTask 下发任务（创建 TaskExecution 记录 → 入队 Asynq）
+func DispatchTask(ctx context.Context, taskType string, payload []byte, triggeredBy string) (string, error) {
+	meta := GetTaskMeta(taskType)
+	if meta == nil {
+		return "", fmt.Errorf(errUnknownTaskType, taskType)
+	}
+
+	// 生成唯一的 TaskID
+	taskID := generateTaskID(taskType, triggeredBy)
+
+	// 创建任务执行记录
+	execution := &TaskExecution{
+		TaskID:      taskID,
+		TaskType:    meta.AsynqTask,
+		TaskName:    meta.Name,
+		Status:      TaskExecutionStatusPending,
+		Retryable:   meta.Retryable,
+		MaxRetry:    meta.MaxRetry,
+		RetryCount:  0,
+		Payload:     string(payload),
+		TriggeredBy: triggeredBy,
+	}
+
+	if err := createTaskExecution(ctx, execution); err != nil {
+		return "", fmt.Errorf(errCreateTaskExecutionFailed, err)
+	}
+
+	// 入队 Asynq
+	taskInfo := asynq.NewTask(meta.AsynqTask, injectTaskTraceContext(ctx, payload))
+	if _, err := AsynqClient.Enqueue(
+		taskInfo,
+		asynq.TaskID(taskID),
+		asynq.MaxRetry(meta.MaxRetry),
+		asynq.Queue(meta.Queue),
+	); err != nil {
+		// 入队失败，更新执行记录状态
+		execution.Status = TaskExecutionStatusFailed
+		execution.ErrorMessage = fmt.Sprintf("入队失败: %v", err)
+		now := time.Now()
+		execution.StartedAt = &now
+		execution.FinishedAt = &now
+		_ = updateTaskExecution(ctx, execution)
+		return "", fmt.Errorf(errTaskEnqueueFailed, err)
+	}
+
+	if err := appendTaskExecutionLog(ctx, taskID, fmt.Sprintf("[系统] 任务已成功入队，等待调度执行 (队列: %s, 最大重试次数: %d)", meta.Queue, meta.MaxRetry)); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加入队日志失败 taskID=%s: %v", taskID, err)
+	}
+
+	return taskID, nil
+}
+
+// RetryTask 重试失败的任务
+func RetryTask(ctx context.Context, id uint64) (string, error) {
+	execution, err := getTaskExecutionByID(ctx, id)
+	if err != nil {
+		return "", fmt.Errorf(errTaskExecutionNotFound, err)
+	}
+
+	if execution.Status != TaskExecutionStatusFailed {
+		return "", fmt.Errorf(errRetryOnlyFailedTask, execution.Status)
+	}
+
+	if !execution.Retryable {
+		return "", errors.New(errTaskNotRetryable)
+	}
+
+	// 生成新的 TaskID
+	newTaskID := generateRetryTaskID(execution.TaskID, execution.RetryCount+1)
+
+	// 创建新的执行记录
+	newExecution := &TaskExecution{
+		TaskID:      newTaskID,
+		TaskType:    execution.TaskType,
+		TaskName:    execution.TaskName,
+		Status:      TaskExecutionStatusPending,
+		Retryable:   execution.Retryable,
+		MaxRetry:    execution.MaxRetry,
+		RetryCount:  execution.RetryCount + 1,
+		Payload:     execution.Payload,
+		TriggeredBy: "retry",
+	}
+
+	if err := createTaskExecution(ctx, newExecution); err != nil {
+		return "", fmt.Errorf(errCreateRetryExecutionFailed, err)
+	}
+
+	meta := GetTaskMeta(execution.TaskType)
+	queueName := QueueDefault
+	if meta != nil {
+		queueName = meta.Queue
+	}
+
+	// 入队 Asynq
+	taskInfo := asynq.NewTask(execution.TaskType, injectTaskTraceContext(ctx, []byte(execution.Payload)))
+	if _, err := AsynqClient.Enqueue(
+		taskInfo,
+		asynq.TaskID(newTaskID),
+		asynq.MaxRetry(execution.MaxRetry),
+		asynq.Queue(queueName),
+	); err != nil {
+		newExecution.Status = TaskExecutionStatusFailed
+		newExecution.ErrorMessage = fmt.Sprintf("重试入队失败: %v", err)
+		now := time.Now()
+		newExecution.StartedAt = &now
+		newExecution.FinishedAt = &now
+		_ = updateTaskExecution(ctx, newExecution)
+		return "", fmt.Errorf(errRetryTaskEnqueueFailed, err)
+	}
+
+	if err := appendTaskExecutionLog(ctx, newTaskID, fmt.Sprintf("[系统] 手动触发重试，已重新创建任务并入队 (原任务ID: %s, 重试次数: %d/%d)", execution.TaskID, execution.RetryCount+1, execution.MaxRetry)); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加重试日志失败 taskID=%s: %v", newTaskID, err)
+	}
+
+	return newTaskID, nil
+}
+
+// ProcessTask Asynq 实际调用的统一处理函数
+// Worker 注册时统一使用此函数，内部自动分发到对应的 TaskHandler
+func ProcessTask(ctx context.Context, t *asynq.Task) error {
+	taskPayload := t.Payload()
+	ctx, taskPayload, hasRemoteTraceContext := extractTaskTraceContext(ctx, taskPayload)
+
+	// 初始化 Trace
+	ctx, span := otel_trace.Start(ctx, "TaskProcess_"+t.Type(), trace.WithSpanKind(trace.SpanKindConsumer))
+	defer span.End()
+
+	// 添加任务信息到 Span
+	span.SetAttributes(
+		attribute.String("task.type", t.Type()),
+		attribute.Int("task.payload_size", len(taskPayload)),
+		attribute.Bool("task.trace_context_propagated", hasRemoteTraceContext),
+		attribute.String("task.id", t.ResultWriter().TaskID()),
+	)
+
+	taskID := t.ResultWriter().TaskID()
+
+	// 注入 taskID 到 context
+	ctx = withTaskID(ctx, taskID)
+
+	// 查找处理器
+	handler, ok := getHandler(t.Type())
+	if !ok {
+		err := fmt.Errorf(errUnregisteredTaskHandler, t.Type())
+		logger.ErrorF(ctx, "[TaskExecutor] %v", err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	// 加载或动态创建执行记录
+	now := time.Now()
+	execution, err := getOrCreateTaskExecution(ctx, taskID, t, taskPayload, now)
+	if err == nil {
+		updateExecutionOnStart(ctx, execution, now)
+	}
+
+	if execution != nil {
+		AppendLog(ctx, "[系统] 开始执行异步任务 [名称: %s, 类型: %s]，重试次数: %d/%d",
+			execution.TaskName, t.Type(), execution.RetryCount, execution.MaxRetry)
+	} else {
+		AppendLog(ctx, "[系统] 开始执行异步任务 [类型: %s]", t.Type())
+	}
+
+	// 开始计时
+	start := time.Now()
+
+	// 执行业务逻辑
+	result, execErr := handler.Execute(ctx, taskPayload)
+
+	// 计算耗时并归档记录
+	duration := time.Since(start)
+	finishTime := time.Now()
+
+	completeTaskExecution(ctx, execution, t, duration, finishTime, result, execErr, span)
+
+	if execution == nil && execErr != nil {
+		span.SetStatus(codes.Error, execErr.Error())
+		return execErr
+	}
+
+	return execErr
+}
+
+func injectTaskTraceContext(ctx context.Context, payload []byte) []byte {
+	carrier := propagation.MapCarrier{}
+	otel.GetTextMapPropagator().Inject(ctx, carrier)
+	if len(carrier) == 0 {
+		return payload
+	}
+
+	envelope := traceEnvelope{
+		WaveletTraceEnvelope: true,
+		Version:              traceEnvelopeVersion,
+		TraceContext:         map[string]string(carrier),
+		Payload:              payload,
+	}
+	data, err := json.Marshal(envelope)
+	if err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 序列化任务 Trace 上下文失败: %v", err)
+		return payload
+	}
+	return data
+}
+
+func extractTaskTraceContext(ctx context.Context, payload []byte) (context.Context, []byte, bool) {
+	var envelope traceEnvelope
+	if err := json.Unmarshal(payload, &envelope); err != nil {
+		return ctx, payload, false
+	}
+	if !envelope.WaveletTraceEnvelope || envelope.Version != traceEnvelopeVersion {
+		return ctx, payload, false
+	}
+	if len(envelope.TraceContext) == 0 {
+		return ctx, envelope.Payload, false
+	}
+
+	extractedCtx := otel.GetTextMapPropagator().Extract(ctx, propagation.MapCarrier(envelope.TraceContext))
+	return extractedCtx, envelope.Payload, true
+}
+
+func updateExecutionOnStart(ctx context.Context, execution *TaskExecution, now time.Time) {
+	if execution == nil {
+		return
+	}
+	dirty := false
+	if retryCount, hasRetry := asynq.GetRetryCount(ctx); hasRetry && execution.RetryCount != retryCount {
+		execution.RetryCount = retryCount
+		dirty = true
+	}
+	if execution.Status != TaskExecutionStatusRunning {
+		execution.Status = TaskExecutionStatusRunning
+		execution.StartedAt = &now
+		dirty = true
+	}
+	if dirty {
+		if updateErr := updateTaskExecution(ctx, execution); updateErr != nil {
+			logger.ErrorF(ctx, "[TaskExecutor] 更新执行状态失败 taskID=%s: %v", execution.TaskID, updateErr)
+		}
+	}
+}
+
+// getOrCreateTaskExecution 获取已有的任务执行记录，如果不存在则针对已知任务类型动态创建记录
+func getOrCreateTaskExecution(ctx context.Context, taskID string, t *asynq.Task, payload []byte, now time.Time) (*TaskExecution, error) {
+	execution, err := getTaskExecutionByTaskID(ctx, taskID)
+	if err == nil {
+		return execution, nil
+	}
+
+	meta := GetTaskMetaByAsynqTask(t.Type())
+	if meta == nil {
+		return nil, err
+	}
+
+	execution = &TaskExecution{
+		TaskID:      taskID,
+		TaskType:    meta.AsynqTask,
+		TaskName:    meta.Name,
+		Status:      TaskExecutionStatusRunning,
+		Retryable:   meta.Retryable,
+		MaxRetry:    meta.MaxRetry,
+		RetryCount:  0,
+		Payload:     string(payload),
+		TriggeredBy: "schedule",
+		StartedAt:   &now,
+	}
+
+	if createErr := createTaskExecution(ctx, execution); createErr != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 动态创建执行记录失败 taskID=%s: %v", taskID, createErr)
+		return nil, createErr
+	}
+
+	return execution, nil
+}
+
+// completeTaskExecution 完成并更新任务执行记录的状态和执行结果
+func completeTaskExecution(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, finishTime time.Time, result *TaskResult, execErr error, span trace.Span) {
+	if execution == nil {
+		return
+	}
+
+	execution.Duration = duration.Milliseconds()
+	execution.FinishedAt = &finishTime
+
+	if execErr != nil {
+		handleFailedTask(ctx, execution, t, duration, execErr, span)
+	} else {
+		handleSuccessfulTask(ctx, execution, t, duration, result)
+	}
+
+	if err := updateTaskExecution(ctx, execution); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 更新执行记录失败 taskID=%s: %v", execution.TaskID, err)
+	}
+	if shouldFlushTaskExecutionLog(ctx, execErr) {
+		if err := flushTaskExecutionLog(ctx, execution.TaskID); err != nil {
+			logger.ErrorF(ctx, "[TaskExecutor] 持久化任务日志失败 taskID=%s: %v", execution.TaskID, err)
+		}
+	}
+
+	notifyTaskCompleted(ctx, execution, result, execErr)
+}
+
+func notifyTaskCompleted(ctx context.Context, execution *TaskExecution, result *TaskResult, execErr error) {
+	completedHandlersMutex.RLock()
+	defer completedHandlersMutex.RUnlock()
+
+	if len(taskCompletedHandlers) == 0 {
+		return
+	}
+
+	asyncCtx := context.WithoutCancel(ctx)
+	for _, handler := range taskCompletedHandlers {
+		h := handler
+		util.Go(func() {
+			h(asyncCtx, execution, result, execErr)
+		})
+	}
+}
+
+func shouldFlushTaskExecutionLog(ctx context.Context, execErr error) bool {
+	if isTerminalTaskExecutionError(execErr) {
+		return true
+	}
+
+	retryCount, hasRetryCount := asynq.GetRetryCount(ctx)
+	maxRetry, hasMaxRetry := asynq.GetMaxRetry(ctx)
+	if !hasRetryCount || !hasMaxRetry {
+		return true
+	}
+	return retryCount >= maxRetry
+}
+
+func isTerminalTaskExecutionError(execErr error) bool {
+	return execErr == nil || errors.Is(execErr, asynq.SkipRetry)
+}
+
+func handleFailedTask(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, execErr error, span trace.Span) {
+	execution.Status = TaskExecutionStatusFailed
+	execution.ErrorMessage = execErr.Error()
+	logger.ErrorF(ctx, "[TaskExecutor] 任务处理失败 Type: %s TaskID: %s Duration: %d ms Error: %v", t.Type(), execution.TaskID, duration.Milliseconds(), execErr)
+	span.SetStatus(codes.Error, execErr.Error())
+	span.RecordError(execErr)
+
+	AppendLog(ctx, "[系统] 任务执行失败，耗时: %d ms，错误原因: %v", duration.Milliseconds(), execErr)
+}
+
+func handleSuccessfulTask(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, result *TaskResult) {
+	execution.Status = TaskExecutionStatusSucceeded
+	execution.ErrorMessage = "" // 清除历史重试失败遗留的错误信息
+	if result != nil {
+		execution.Result = result.Message
+		if result.Detail != "" {
+			execution.Result = fmt.Sprintf("%s\n%s", result.Message, result.Detail)
+		}
+	}
+	logger.InfoF(ctx, "[TaskExecutor] 任务处理完成 Type: %s TaskID: %s Duration: %d ms", t.Type(), execution.TaskID, duration.Milliseconds())
+
+	resultMsg := "成功"
+	if result != nil {
+		resultMsg = result.Message
+	}
+	AppendLog(ctx, "[系统] 任务执行成功，耗时: %d ms，执行结果: %s", duration.Milliseconds(), resultMsg)
+}
+
+// generateTaskID 生成任务 ID
+func generateTaskID(taskType string, triggeredBy string) string {
+	return fmt.Sprintf("%s_%s_%d", triggeredBy, taskType, idgen.NextUint64ID())
+}
+
+// generateRetryTaskID 生成重试任务 ID
+func generateRetryTaskID(originalTaskID string, retryCount int) string {
+	return fmt.Sprintf("retry_%d_%s", retryCount, originalTaskID)
+}

backend/plugins/drivers/driver_asynq_worker/executor_test.go

@@ -0,0 +1,402 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/testhelper"
+)
+
+// mockHandler 用于测试的模拟任务处理器
+type mockHandler struct {
+	executeFunc func(ctx context.Context, payload []byte) (*TaskResult, error)
+}
+
+func (h *mockHandler) Execute(ctx context.Context, payload []byte) (*TaskResult, error) {
+	if h.executeFunc != nil {
+		return h.executeFunc(ctx, payload)
+	}
+	return &TaskResult{Message: "mock success"}, nil
+}
+
+// successHandler 返回成功的处理器
+func successHandler() *mockHandler {
+	return &mockHandler{
+		executeFunc: func(ctx context.Context, payload []byte) (*TaskResult, error) {
+			AppendLog(ctx, "执行成功，处理了 %d 条数据", 100)
+			return &TaskResult{Message: "处理完成，共 100 条"}, nil
+		},
+	}
+}
+
+// failHandler 返回失败的处理器
+func failHandler() *mockHandler {
+	return &mockHandler{
+		executeFunc: func(ctx context.Context, payload []byte) (*TaskResult, error) {
+			AppendLog(ctx, "开始执行任务")
+			return nil, fmt.Errorf("模拟执行失败: 数据库连接超时")
+		},
+	}
+}
+
+const testTaskType = "test:mock_task"
+
+func setupTest(t *testing.T) func() {
+	_, mr, cleanup := testhelper.SetupTestEnvironment(t)
+	AsynqClient = asynq.NewClient(asynq.RedisClientOpt{
+		Addr: mr.Addr(),
+	})
+	// 注册测试用 handler
+	RegisterHandler(testTaskType, successHandler())
+	return func() {
+		if AsynqClient != nil {
+			_ = AsynqClient.Close()
+			AsynqClient = nil
+		}
+		cleanup()
+	}
+}
+
+func TestRegisterAndGetHandler(t *testing.T) {
+	_ = testTaskType
+	cleanup := setupTest(t)
+	defer cleanup()
+
+	// 验证 handler 已注册
+	h, ok := getHandler(testTaskType)
+	assert.True(t, ok, "handler should be registered")
+	assert.NotNil(t, h)
+
+	// 未注册的 handler
+	_, ok = getHandler("nonexistent")
+	assert.False(t, ok, "non-existent handler should return false")
+}
+
+func TestGetTaskIDFromContext(t *testing.T) {
+	ctx := context.Background()
+
+	// 空 context
+	taskID := GetTaskID(ctx)
+	assert.Equal(t, "", taskID)
+
+	// 注入 taskID
+	ctx = withTaskID(ctx, "test_task_123")
+	taskID = GetTaskID(ctx)
+	assert.Equal(t, "test_task_123", taskID)
+}
+
+func TestAppendLogWithoutTaskID(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 没有 taskID 的 context，应降级到普通日志，不报错
+	AppendLog(ctx, "这条日志应该降级处理，不会报错")
+}
+
+func TestAppendLogWithTaskID(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 先创建一条执行记录
+	execution := &TaskExecution{
+		TaskID:      "log_test_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusRunning,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	// 注入 taskID 并追加日志
+	ctx = withTaskID(ctx, "log_test_001")
+	AppendLog(ctx, "第一条日志")
+	AppendLog(ctx, "处理了 %d 条数据", 50)
+
+	// 验证日志
+	found, err := GetTaskExecutionByTaskID(ctx, "log_test_001")
+	require.NoError(t, err)
+	assert.Contains(t, found.Log, "第一条日志")
+	assert.Contains(t, found.Log, "处理了 50 条数据")
+}
+
+func TestTaskTraceContextEnvelope(t *testing.T) {
+	payload := []byte(`{"hello":"wavelet"}`)
+	traceID := "4bf92f3577b34da6a3ce929d0e0e4736"
+	parentCtx := otel.GetTextMapPropagator().Extract(
+		context.Background(),
+		propagation.MapCarrier{
+			"traceparent": "00-" + traceID + "-00f067aa0ba902b7-01",
+		},
+	)
+
+	wrappedPayload := injectTaskTraceContext(parentCtx, payload)
+	require.NotEqual(t, string(payload), string(wrappedPayload))
+
+	gotCtx, gotPayload, ok := extractTaskTraceContext(context.Background(), wrappedPayload)
+	require.True(t, ok)
+	assert.Equal(t, payload, gotPayload)
+	assert.Equal(t, traceID, trace.SpanContextFromContext(gotCtx).TraceID().String())
+}
+
+func TestTaskTraceContextEnvelopeKeepsLegacyPayload(t *testing.T) {
+	payload := []byte(`{"legacy":true}`)
+
+	gotCtx, gotPayload, ok := extractTaskTraceContext(context.Background(), payload)
+	require.False(t, ok)
+	assert.Equal(t, context.Background(), gotCtx)
+	assert.Equal(t, payload, gotPayload)
+}
+
+func TestTaskTraceContextEnvelopeSkipsEmptyContext(t *testing.T) {
+	payload := []byte(`{"background":true}`)
+
+	wrappedPayload := injectTaskTraceContext(context.Background(), payload)
+	assert.Equal(t, payload, wrappedPayload)
+}
+
+func TestProcessTaskSuccess(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 注册成功 handler
+	RegisterHandler(testTaskType, successHandler())
+
+	// 创建执行记录
+	execution := &TaskExecution{
+		TaskID:      "process_success_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusPending,
+		Retryable:   true,
+		MaxRetry:    3,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	// 直接通过 handler 测试
+	handler, ok := getHandler(testTaskType)
+	require.True(t, ok)
+
+	ctx = withTaskID(ctx, "process_success_001")
+	result, err := handler.Execute(ctx, nil)
+	require.NoError(t, err)
+	assert.Equal(t, "处理完成，共 100 条", result.Message)
+
+	// 验证日志被追加
+	found, err := GetTaskExecutionByTaskID(ctx, "process_success_001")
+	require.NoError(t, err)
+	assert.Contains(t, found.Log, "执行成功，处理了 100 条数据")
+}
+
+func TestProcessTaskFailure(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 注册失败 handler
+	RegisterHandler(testTaskType, failHandler())
+
+	// 创建执行记录
+	execution := &TaskExecution{
+		TaskID:      "process_fail_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusPending,
+		Retryable:   true,
+		MaxRetry:    3,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	// 直接调用 handler
+	handler, ok := getHandler(testTaskType)
+	require.True(t, ok)
+
+	ctx = withTaskID(ctx, "process_fail_001")
+	_, err = handler.Execute(ctx, nil)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "模拟执行失败")
+
+	// 验证日志
+	found, err := GetTaskExecutionByTaskID(ctx, "process_fail_001")
+	require.NoError(t, err)
+	assert.Contains(t, found.Log, "开始执行任务")
+}
+
+func TestCompleteTaskExecutionFlushesLog(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	execution := &TaskExecution{
+		TaskID:      "complete_flush_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusRunning,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	ctx = withTaskID(ctx, execution.TaskID)
+	AppendLog(ctx, "任务执行中的日志")
+
+	finishTime := time.Now()
+	completeTaskExecution(
+		ctx,
+		execution,
+		asynq.NewTask(testTaskType, nil),
+		100*time.Millisecond,
+		finishTime,
+		&TaskResult{Message: "处理完成"},
+		nil,
+		trace.SpanFromContext(ctx),
+	)
+
+	found, err := GetTaskExecutionByTaskID(ctx, execution.TaskID)
+	require.NoError(t, err)
+	assert.Equal(t, TaskExecutionStatusSucceeded, found.Status)
+	assert.Contains(t, found.Log, "任务执行中的日志")
+	assert.Contains(t, found.Log, "任务执行成功")
+}
+
+func TestPermanentErrorIsTerminalForLogFlush(t *testing.T) {
+	assert.True(t, isTerminalTaskExecutionError(PermanentError("配置无效")))
+	assert.False(t, isTerminalTaskExecutionError(errors.New("temporary failure")))
+}
+
+func TestRetryTask(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 创建一条失败的执行记录（可重试）
+	now := time.Now()
+	execution := &TaskExecution{
+		TaskID:       "retry_test_001",
+		TaskType:     testTaskType,
+		TaskName:     "测试任务",
+		Status:       TaskExecutionStatusFailed,
+		Retryable:    true,
+		MaxRetry:     3,
+		RetryCount:   0,
+		ErrorMessage: "首次执行失败",
+		StartedAt:    &now,
+		FinishedAt:   &now,
+		Duration:     100,
+		TriggeredBy:  "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	// 重试
+	newTaskID, err := RetryTask(ctx, execution.ID)
+	require.NoError(t, err)
+	assert.NotEmpty(t, newTaskID)
+	assert.Contains(t, newTaskID, "retry_1_")
+
+	// 验证新记录
+	newExecution, err := GetTaskExecutionByTaskID(ctx, newTaskID)
+	require.NoError(t, err)
+	assert.Equal(t, TaskExecutionStatusPending, newExecution.Status)
+	assert.Equal(t, 1, newExecution.RetryCount)
+	assert.Equal(t, "retry", newExecution.TriggeredBy)
+	assert.Equal(t, execution.TaskType, newExecution.TaskType)
+	assert.True(t, newExecution.Retryable)
+
+	// 原记录不变
+	original, err := GetTaskExecutionByID(ctx, execution.ID)
+	require.NoError(t, err)
+	assert.Equal(t, TaskExecutionStatusFailed, original.Status)
+	assert.Equal(t, 0, original.RetryCount)
+}
+
+func TestRetryTaskNotFailed(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// 创建一条成功的记录
+	execution := &TaskExecution{
+		TaskID:      "retry_not_failed_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusSucceeded,
+		Retryable:   true,
+		MaxRetry:    3,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	// 尝试重试成功的任务
+	_, err = RetryTask(ctx, execution.ID)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "只有失败的任务才能重试")
+}
+
+func TestRetryTaskNotRetryable(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	execution := &TaskExecution{
+		TaskID:      "retry_not_allowed_001",
+		TaskType:    testTaskType,
+		TaskName:    "测试任务",
+		Status:      TaskExecutionStatusFailed,
+		Retryable:   false,
+		MaxRetry:    0,
+		TriggeredBy: "manual",
+	}
+	err := CreateTaskExecution(ctx, execution)
+	require.NoError(t, err)
+
+	_, err = RetryTask(ctx, execution.ID)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "不支持重试")
+}
+
+func TestRetryTaskNonExistent(t *testing.T) {
+	cleanup := setupTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	_, err := RetryTask(ctx, 99999999)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "不存在")
+}
+
+func TestGenerateTaskID(t *testing.T) {
+	id1 := generateTaskID("test_type", "manual")
+	id2 := generateTaskID("test_type", "manual")
+
+	// 两个 ID 应不同（包含 Snowflake ID）
+	assert.NotEqual(t, id1, id2)
+	assert.Contains(t, id1, "manual_test_type_")
+}
+
+func TestGenerateRetryTaskID(t *testing.T) {
+	id := generateRetryTaskID("original_task_123", 2)
+	assert.Equal(t, "retry_2_original_task_123", id)
+}

backend/plugins/drivers/driver_asynq_worker/handler.go

@@ -0,0 +1,37 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import "context"
+
+// TaskResult 任务执行结果
+//
+//nolint:revive // TaskResult 保留完整名称以避免与通用 Result 混淆
+type TaskResult struct {
+	Message string // 结果摘要，如 "共清理 120 个文件，耗时 3.2s"
+	Detail  string // 可选的详细结果 JSON
+}
+
+// PayloadValidator 可选接口，带参数的任务 Handler 应实现此接口。
+// 框架在 Admin 下发时自动调用，完成参数校验和标准化（如 Trim 空白）。
+// 无参数的任务无需实现，框架会直接透传 payload。
+type PayloadValidator interface {
+	ValidatePayload(payload []byte) ([]byte, error)
+}
+
+// TaskHandler 异步任务处理器接口
+// 所有异步任务必须实现此接口，框架将自动管理任务执行记录的创建、状态流转和日志写入。
+//
+// 开发者只需实现 Execute 方法编写业务逻辑，在方法内通过 driver_asynq_worker.AppendLog(ctx, ...) 追加执行日志。
+// 任务的创建、状态更新、错误记录、重试计数全部由框架透明处理。
+//
+//nolint:revive // TaskHandler 保留完整名称以避免与通用 Handler 混淆
+type TaskHandler interface {
+	// Execute 执行任务业务逻辑
+	//   - ctx: 已注入 Trace Span 和 taskID 的上下文
+	//   - payload: 调度时传入的原始参数（可为 nil）
+	//   - 返回 TaskResult 描述执行结果，或 error 表示执行失败
+	Execute(ctx context.Context, payload []byte) (*TaskResult, error)
+}

backend/plugins/drivers/driver_asynq_worker/meta.go

@@ -0,0 +1,100 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"sync"
+)
+
+// TaskParam 任务参数定义
+//
+//nolint:revive // TaskParam 保留完整名称以避免与通用 Param 混淆
+type TaskParam struct {
+	Name        string `json:"name"`        // 参数键名
+	Label       string `json:"label"`       // 显示名称
+	Type        string `json:"type"`        // 类型：string, text, number, boolean
+	Required    bool   `json:"required"`    // 是否必填
+	Placeholder string `json:"placeholder"` // 占位符
+	Description string `json:"description"` // 描述
+}
+
+// TaskMeta 任务元数据
+//
+//nolint:revive // TaskMeta 保留完整名称以避免与通用 Meta 混淆
+type TaskMeta struct {
+	Type         string      `json:"type"`
+	AsynqTask    string      `json:"asynq_task"`
+	Name         string      `json:"name"`
+	Description  string      `json:"description"`
+	SupportsTime bool        `json:"supports_time"`
+	MaxRetry     int         `json:"max_retry"`
+	Queue        string      `json:"queue"`
+	Retryable    bool        `json:"retryable"` // 是否支持手动重试
+	Params       []TaskParam `json:"params,omitempty"`
+}
+
+var (
+	dispatchableTasksMutex sync.RWMutex
+	dispatchableTasks      []TaskMeta
+)
+
+// RegisterTaskMeta 注册任务元数据到全局列表
+func RegisterTaskMeta(meta TaskMeta) {
+	dispatchableTasksMutex.Lock()
+	defer dispatchableTasksMutex.Unlock()
+	for _, t := range dispatchableTasks {
+		if t.Type == meta.Type {
+			return
+		}
+	}
+	dispatchableTasks = append(dispatchableTasks, meta)
+}
+
+// GetDispatchableTasks 获取所有已注册的元数据列表（返回副本以避免并发读写冲突）
+func GetDispatchableTasks() []TaskMeta {
+	dispatchableTasksMutex.RLock()
+	defer dispatchableTasksMutex.RUnlock()
+
+	metas := make([]TaskMeta, len(dispatchableTasks))
+	copy(metas, dispatchableTasks)
+	return metas
+}
+
+// GetTaskMeta 根据任务类型获取元数据
+func GetTaskMeta(taskType string) *TaskMeta {
+	dispatchableTasksMutex.RLock()
+	defer dispatchableTasksMutex.RUnlock()
+	for _, t := range dispatchableTasks {
+		if t.Type == taskType {
+			copied := t
+			return &copied
+		}
+	}
+	return nil
+}
+
+// GetTaskMetaByAsynqTask 根据 Asynq 任务名称获取元数据
+func GetTaskMetaByAsynqTask(asynqTask string) *TaskMeta {
+	dispatchableTasksMutex.RLock()
+	defer dispatchableTasksMutex.RUnlock()
+	for _, t := range dispatchableTasks {
+		if t.AsynqTask == asynqTask {
+			copied := t
+			return &copied
+		}
+	}
+	return nil
+}
+
+// GetRegisteredAsynqTasks 返回所有已注册的 Asynq 任务名称，以便动态注册路由
+func GetRegisteredAsynqTasks() []string {
+	handlerRegistryMutex.RLock()
+	defer handlerRegistryMutex.RUnlock()
+
+	keys := make([]string, 0, len(handlerRegistry))
+	for k := range handlerRegistry {
+		keys = append(keys, k)
+	}
+	return keys
+}

backend/plugins/drivers/driver_asynq_worker/meta_test.go

@@ -0,0 +1,98 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"sync"
+	"testing"
+)
+
+func resetDispatchableTasks() {
+	dispatchableTasksMutex.Lock()
+	defer dispatchableTasksMutex.Unlock()
+	dispatchableTasks = nil
+}
+
+func TestRegisterTaskMeta_ThreadSafe(t *testing.T) {
+	resetDispatchableTasks()
+	defer resetDispatchableTasks()
+
+	var wg sync.WaitGroup
+	workers := 20
+	iterations := 100
+
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				RegisterTaskMeta(TaskMeta{
+					Type:      "task_type_a",
+					AsynqTask: "asynq_task_a",
+					Name:      "Task A",
+				})
+				RegisterTaskMeta(TaskMeta{
+					Type:      "task_type_b",
+					AsynqTask: "asynq_task_b",
+					Name:      "Task B",
+				})
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	tasks := GetDispatchableTasks()
+	if len(tasks) != 2 {
+		t.Fatalf("expected 2 unique tasks, got %d", len(tasks))
+	}
+}
+
+func TestGetTaskMeta_Isolation(t *testing.T) {
+	resetDispatchableTasks()
+	defer resetDispatchableTasks()
+
+	RegisterTaskMeta(TaskMeta{
+		Type:      "task_isolated",
+		AsynqTask: "asynq_isolated",
+		Name:      "Original Name",
+	})
+
+	meta := GetTaskMeta("task_isolated")
+	if meta == nil {
+		t.Fatal("expected task to be found")
+	}
+
+	// Modify returned struct
+	meta.Name = "Modified Name"
+
+	// Fetch again and verify original data is unaffected
+	meta2 := GetTaskMeta("task_isolated")
+	if meta2.Name != "Original Name" {
+		t.Fatalf("expected name to be 'Original Name', got %s", meta2.Name)
+	}
+}
+
+func TestGetTaskMetaByAsynqTask_Isolation(t *testing.T) {
+	resetDispatchableTasks()
+	defer resetDispatchableTasks()
+
+	RegisterTaskMeta(TaskMeta{
+		Type:      "task_isolated",
+		AsynqTask: "asynq_isolated",
+		Name:      "Original Name",
+	})
+
+	meta := GetTaskMetaByAsynqTask("asynq_isolated")
+	if meta == nil {
+		t.Fatal("expected task to be found")
+	}
+
+	meta.Name = "Modified Name"
+
+	meta2 := GetTaskMetaByAsynqTask("asynq_isolated")
+	if meta2.Name != "Original Name" {
+		t.Fatalf("expected name to be 'Original Name', got %s", meta2.Name)
+	}
+}

backend/plugins/drivers/driver_asynq_worker/migrations/00001_initial.sql

@@ -0,0 +1,28 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS w_task_executions (
+    id BIGINT PRIMARY KEY,
+    task_id VARCHAR(128) NOT NULL UNIQUE,
+    task_type VARCHAR(64) NOT NULL,
+    task_name VARCHAR(128),
+    status VARCHAR(32) NOT NULL,
+    retryable BOOLEAN NOT NULL DEFAULT FALSE,
+    max_retry INTEGER NOT NULL DEFAULT 0,
+    retry_count INTEGER NOT NULL DEFAULT 0,
+    log TEXT,
+    error_message TEXT,
+    result TEXT,
+    started_at TIMESTAMPTZ,
+    finished_at TIMESTAMPTZ,
+    duration BIGINT,
+    payload TEXT,
+    triggered_by VARCHAR(32) NOT NULL DEFAULT 'system',
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_task_executions_task_type ON w_task_executions (task_type);
+CREATE INDEX IF NOT EXISTS idx_w_task_executions_status ON w_task_executions (status);
+CREATE INDEX IF NOT EXISTS idx_w_task_executions_started_at ON w_task_executions (started_at);
+CREATE INDEX IF NOT EXISTS idx_w_task_executions_created_at ON w_task_executions (created_at);
+
+-- +goose Down
+DROP TABLE IF EXISTS w_task_executions;

backend/plugins/drivers/driver_asynq_worker/permanent_error.go

@@ -0,0 +1,35 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"strings"
+
+	"github.com/hibiken/asynq"
+)
+
+const defaultPermanentErrorMessage = "任务无法继续执行"
+
+type permanentTaskError struct {
+	message string
+}
+
+// PermanentError marks a safe domain message as a non-retryable task failure.
+// It intentionally accepts no underlying error so Error never exposes provider,
+// URL, header, response-body, or other sensitive implementation details.
+func PermanentError(message string) error {
+	message = strings.TrimSpace(message)
+	if message == "" {
+		message = defaultPermanentErrorMessage
+	}
+	return &permanentTaskError{message: message}
+}
+
+func (e *permanentTaskError) Error() string {
+	return e.message
+}
+
+func (e *permanentTaskError) Unwrap() error {
+	return asynq.SkipRetry
+}

backend/plugins/drivers/driver_asynq_worker/permanent_error_test.go

@@ -0,0 +1,37 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/hibiken/asynq"
+)
+
+func TestPermanentError(t *testing.T) {
+	err := PermanentError("自定义永久错误")
+	if err == nil {
+		t.Fatal("PermanentError returned nil")
+	}
+	if err.Error() != "自定义永久错误" {
+		t.Fatalf("Error() = %q, want %q", err.Error(), "自定义永久错误")
+	}
+	if !errors.Is(err, asynq.SkipRetry) {
+		t.Fatal("PermanentError does not unwrap to asynq.SkipRetry")
+	}
+}
+
+func TestPermanentErrorDefaultMessage(t *testing.T) {
+	err := PermanentError("   ")
+	if err == nil {
+		t.Fatal("PermanentError returned nil")
+	}
+	if err.Error() != defaultPermanentErrorMessage {
+		t.Fatalf("Error() = %q, want default %q", err.Error(), defaultPermanentErrorMessage)
+	}
+	if !errors.Is(err, asynq.SkipRetry) {
+		t.Fatal("PermanentError does not unwrap to asynq.SkipRetry")
+	}
+}

backend/plugins/drivers/driver_asynq_worker/plugin.go

@@ -0,0 +1,256 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package driver_asynq_worker provides the Asynq worker driver plugin for Cordis.
+package driver_asynq_worker
+
+import (
+	"context"
+	"embed"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/hibiken/asynq"
+
+	"github.com/Rain-kl/Wavelet/backend/core"
+)
+
+const (
+	defaultConcurrency     = 10
+	defaultShutdownTimeout = 10 * time.Second
+)
+
+//go:embed migrations/*.sql
+var workerMigrations embed.FS
+
+// Option configures the Asynq worker driver plugin.
+type Option func(*Plugin)
+
+// WithRedisOpt sets the Redis connection options for Asynq.
+func WithRedisOpt(opt asynq.RedisConnOpt) Option {
+	return func(p *Plugin) {
+		p.redisOpt = opt
+	}
+}
+
+// WithConcurrency sets the worker concurrency limit.
+func WithConcurrency(concurrency int) Option {
+	return func(p *Plugin) {
+		p.concurrency = concurrency
+	}
+}
+
+// WithQueues sets the queue priorities mapping.
+func WithQueues(queues map[string]int) Option {
+	return func(p *Plugin) {
+		p.queues = queues
+	}
+}
+
+// WithStrictPriority sets whether to process queues strictly in priority order.
+func WithStrictPriority(strict bool) Option {
+	return func(p *Plugin) {
+		p.strictPriority = strict
+	}
+}
+
+// WithShutdownTimeout sets the timeout for graceful worker shutdown.
+func WithShutdownTimeout(d time.Duration) Option {
+	return func(p *Plugin) {
+		p.shutdownTimeout = d
+	}
+}
+
+// WithServer injects an existing Asynq server instance.
+func WithServer(srv *asynq.Server) Option {
+	return func(p *Plugin) {
+		p.server = srv
+	}
+}
+
+// Plugin implements core.Plugin and core.Driver for Asynq background worker server.
+type Plugin struct {
+	mu              sync.RWMutex
+	redisOpt        asynq.RedisConnOpt
+	concurrency     int
+	queues          map[string]int
+	strictPriority  bool
+	shutdownTimeout time.Duration
+	server          *asynq.Server
+	mux             *asynq.ServeMux
+	running         bool
+	coreCtx         *core.Context
+}
+
+// New creates a new Asynq Worker driver plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{
+		redisOpt:        RedisOpt,
+		concurrency:     defaultConcurrency,
+		shutdownTimeout: defaultShutdownTimeout,
+		queues:          map[string]int{"default": 1},
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+
+	return p
+}
+
+// Name returns the unique plugin identifier.
+func (p *Plugin) Name() string {
+	return "driver_asynq_worker"
+}
+
+// Apply mounts the Asynq Worker driver into the micro-kernel Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	p.mu.Lock()
+	p.coreCtx = ctx
+	p.mu.Unlock()
+
+	// Register migrations for w_task_executions table
+	ctx.Migrations().Register("driver_asynq_worker", workerMigrations)
+
+	ctx.OnDispose(func() error {
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), p.shutdownTimeout)
+		defer cancel()
+		return p.Stop(shutdownCtx)
+	})
+
+	return ctx.RegisterDriver(p)
+}
+
+// Type returns DriverTypeWorker.
+func (p *Plugin) Type() core.DriverType {
+	return core.DriverTypeWorker
+}
+
+// Start boots the Asynq worker server and starts processing background tasks.
+func (p *Plugin) Start(_ context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.running {
+		return nil
+	}
+
+	mux := asynq.NewServeMux()
+
+	if p.coreCtx != nil && p.coreCtx.Tasks() != nil {
+		for _, td := range p.coreCtx.Tasks().Tasks() {
+			handler, err := toAsynqHandler(td.Handler)
+			if err != nil {
+				return fmt.Errorf("driver_asynq_worker: invalid handler for task pattern %q: %w", td.Pattern, err)
+			}
+			mux.Handle(td.Pattern, handler)
+		}
+	}
+
+	for _, taskName := range GetRegisteredAsynqTasks() {
+		mux.HandleFunc(taskName, ProcessTask)
+	}
+
+	if p.server == nil {
+		p.server = asynq.NewServer(
+			p.redisOpt,
+			asynq.Config{
+				Concurrency:     p.concurrency,
+				Queues:          p.queues,
+				StrictPriority:  p.strictPriority,
+				ShutdownTimeout: p.shutdownTimeout,
+			},
+		)
+	}
+
+	if err := p.server.Start(mux); err != nil {
+		return fmt.Errorf("driver_asynq_worker: start server failed: %w", err)
+	}
+
+	p.mux = mux
+	p.running = true
+	return nil
+}
+
+// Stop gracefully shuts down the Asynq worker server.
+func (p *Plugin) Stop(_ context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if !p.running {
+		return nil
+	}
+
+	p.running = false
+
+	if p.server != nil {
+		p.server.Stop()
+		p.server.Shutdown()
+		p.server = nil
+	}
+
+	return nil
+}
+
+// IsRunning returns whether the worker server is running.
+func (p *Plugin) IsRunning() bool {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.running
+}
+
+// Server returns the underlying Asynq server instance.
+func (p *Plugin) Server() *asynq.Server {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.server
+}
+
+// Mux returns the underlying Asynq serve mux.
+func (p *Plugin) Mux() *asynq.ServeMux {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.mux
+}
+
+func toAsynqHandler(h any) (asynq.Handler, error) {
+	if h == nil {
+		return nil, errors.New("nil handler")
+	}
+
+	switch fn := h.(type) {
+	case asynq.HandlerFunc:
+		return fn, nil
+	case asynq.Handler:
+		return fn, nil
+	case TaskHandler:
+		return asynq.HandlerFunc(func(c context.Context, t *asynq.Task) error {
+			RegisterHandler(t.Type(), fn)
+			return ProcessTask(c, t)
+		}), nil
+	case func(context.Context, *asynq.Task) error:
+		return asynq.HandlerFunc(fn), nil
+	case func(context.Context, []byte) error:
+		return asynq.HandlerFunc(func(c context.Context, t *asynq.Task) error {
+			return fn(c, t.Payload())
+		}), nil
+	case func(context.Context) error:
+		return asynq.HandlerFunc(func(c context.Context, _ *asynq.Task) error {
+			return fn(c)
+		}), nil
+	case func([]byte) error:
+		return asynq.HandlerFunc(func(_ context.Context, t *asynq.Task) error {
+			return fn(t.Payload())
+		}), nil
+	case func() error:
+		return asynq.HandlerFunc(func(_ context.Context, _ *asynq.Task) error {
+			return fn()
+		}), nil
+	default:
+		return nil, fmt.Errorf("unsupported task handler type: %T", h)
+	}
+}

backend/plugins/drivers/driver_asynq_worker/task_repo.go

@@ -0,0 +1,126 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/idgen"
+	cachepkg "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+const (
+	taskExecutionLogRedisKeyPrefix = "task:execution:log:"
+	taskExecutionLogExpiration     = 24 * time.Hour
+	taskExecutionLogMaxLines       = 1000
+)
+
+func taskExecutionLogRedisKey(taskID string) string {
+	return cachepkg.PrefixedKey(taskExecutionLogRedisKeyPrefix + taskID)
+}
+
+func createTaskExecution(ctx context.Context, execution *TaskExecution) error {
+	if execution.ID == 0 {
+		execution.ID = idgen.NextUint64ID()
+	}
+	return db.DB(ctx).Create(execution).Error
+}
+
+func updateTaskExecution(ctx context.Context, execution *TaskExecution) error {
+	return db.DB(ctx).Omit("log").Save(execution).Error
+}
+
+func getTaskExecutionByID(ctx context.Context, id uint64) (*TaskExecution, error) {
+	var execution TaskExecution
+	if err := db.DB(ctx).Where("id = ?", id).First(&execution).Error; err != nil {
+		return nil, err
+	}
+	_ = loadTaskExecutionLog(ctx, &execution)
+	return &execution, nil
+}
+
+func getTaskExecutionByTaskID(ctx context.Context, taskID string) (*TaskExecution, error) {
+	var execution TaskExecution
+	if err := db.DB(ctx).Where("task_id = ?", taskID).First(&execution).Error; err != nil {
+		return nil, err
+	}
+	_ = loadTaskExecutionLog(ctx, &execution)
+	return &execution, nil
+}
+
+func appendTaskExecutionLog(ctx context.Context, taskID string, logLine string) error {
+	if cachepkg.Redis == nil {
+		return errors.New("redis client is not initialized")
+	}
+
+	now := time.Now().Format("15:04:05")
+	line := fmt.Sprintf("[%s] %s\n", now, logLine)
+	key := taskExecutionLogRedisKey(taskID)
+
+	_, err := cachepkg.Redis.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
+		pipe.RPush(ctx, key, line)
+		pipe.LTrim(ctx, key, -taskExecutionLogMaxLines, -1)
+		pipe.Expire(ctx, key, taskExecutionLogExpiration)
+		return nil
+	})
+	if err != nil {
+		return fmt.Errorf("append task execution log to redis: %w", err)
+	}
+	return nil
+}
+
+func flushTaskExecutionLog(ctx context.Context, taskID string) error {
+	if cachepkg.Redis == nil {
+		return errors.New("redis client is not initialized")
+	}
+
+	key := taskExecutionLogRedisKey(taskID)
+	logLines, err := cachepkg.Redis.LRange(ctx, key, 0, -1).Result()
+	if err != nil {
+		return fmt.Errorf("get task execution log from redis: %w", err)
+	}
+	if len(logLines) == 0 {
+		return nil
+	}
+	logText := strings.Join(logLines, "")
+
+	result := db.DB(ctx).Model(&TaskExecution{}).
+		Where("task_id = ?", taskID).
+		Update("log", logText)
+	if result.Error != nil {
+		return fmt.Errorf("persist task execution log: %w", result.Error)
+	}
+	if result.RowsAffected == 0 {
+		return fmt.Errorf("persist task execution log: task %q not found", taskID)
+	}
+
+	if err := cachepkg.Redis.Del(ctx, key).Err(); err != nil {
+		return fmt.Errorf("delete persisted task execution log from redis: %w", err)
+	}
+	return nil
+}
+
+func loadTaskExecutionLog(ctx context.Context, execution *TaskExecution) error {
+	if cachepkg.Redis == nil {
+		return nil
+	}
+
+	logLines, err := cachepkg.Redis.LRange(ctx, taskExecutionLogRedisKey(execution.TaskID), 0, -1).Result()
+	if err != nil {
+		return fmt.Errorf("get task execution log from redis: %w", err)
+	}
+	if len(logLines) == 0 {
+		return nil
+	}
+
+	execution.Log = strings.Join(logLines, "")
+	return nil
+}

backend/plugins/drivers/driver_asynq_worker/types.go

@@ -0,0 +1,155 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+// TaskExecutionStatus 任务执行状态
+//
+//nolint:revive
+type TaskExecutionStatus string
+
+// Task execution status constants.
+const (
+	TaskExecutionStatusPending   TaskExecutionStatus = "pending"
+	TaskExecutionStatusRunning   TaskExecutionStatus = "running"
+	TaskExecutionStatusSucceeded TaskExecutionStatus = "succeeded"
+	TaskExecutionStatusFailed    TaskExecutionStatus = "failed"
+)
+
+// TaskExecution 任务执行记录
+//
+//nolint:revive
+type TaskExecution struct {
+	ID           uint64              `json:"id,string" gorm:"primaryKey"`
+	TaskID       string              `json:"task_id" gorm:"size:128;uniqueIndex;not null"`
+	TaskType     string              `json:"task_type" gorm:"size:64;index;not null"`
+	TaskName     string              `json:"task_name" gorm:"size:128"`
+	Status       TaskExecutionStatus `json:"status" gorm:"size:32;index;not null"`
+	Retryable    bool                `json:"retryable" gorm:"not null;default:false"`
+	MaxRetry     int                 `json:"max_retry" gorm:"not null;default:0"`
+	RetryCount   int                 `json:"retry_count" gorm:"not null;default:0"`
+	Log          string              `json:"log" gorm:"type:text"`
+	ErrorMessage string              `json:"error_message" gorm:"type:text"`
+	Result       string              `json:"result" gorm:"type:text"`
+	StartedAt    *time.Time          `json:"started_at" gorm:"index"`
+	FinishedAt   *time.Time          `json:"finished_at"`
+	Duration     int64               `json:"duration" gorm:"comment:耗时毫秒"`
+	Payload      string              `json:"payload" gorm:"type:text"`
+	TriggeredBy  string              `json:"triggered_by" gorm:"size:32;not null;default:system"`
+	CreatedAt    time.Time           `json:"created_at" gorm:"autoCreateTime;index"`
+	UpdatedAt    time.Time           `json:"updated_at" gorm:"autoUpdateTime"`
+}
+
+// TableName 表名
+func (TaskExecution) TableName() string {
+	return "w_task_executions"
+}
+
+// CreateTaskExecution 创建任务执行记录
+func CreateTaskExecution(ctx context.Context, exec *TaskExecution) error {
+	return db.DB(ctx).Create(exec).Error
+}
+
+// GetTaskExecutionByTaskID 根据 TaskID 查询执行记录
+func GetTaskExecutionByTaskID(ctx context.Context, taskID string) (*TaskExecution, error) {
+	var exec TaskExecution
+	if err := db.DB(ctx).Where("task_id = ?", taskID).First(&exec).Error; err != nil {
+		return nil, err
+	}
+	_ = loadTaskExecutionLog(ctx, &exec)
+	return &exec, nil
+}
+
+// GetTaskExecutionByID 根据主键 ID 查询执行记录
+func GetTaskExecutionByID(ctx context.Context, id uint64) (*TaskExecution, error) {
+	var exec TaskExecution
+	if err := db.DB(ctx).Where("id = ?", id).First(&exec).Error; err != nil {
+		return nil, err
+	}
+	_ = loadTaskExecutionLog(ctx, &exec)
+	return &exec, nil
+}
+
+// GetLatestTaskExecutionByTaskType 获取指定任务类型的最新执行记录
+func GetLatestTaskExecutionByTaskType(ctx context.Context, taskType string) (*TaskExecution, bool, error) {
+	var exec TaskExecution
+	err := db.DB(ctx).Where("task_type = ?", taskType).Order("id DESC").First(&exec).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+	return &exec, true, nil
+}
+
+// TaskExecutionCleanupStats describes task execution log cleanup results.
+//
+//nolint:revive
+type TaskExecutionCleanupStats struct {
+	HighFrequencyDeleted int64
+	LowFrequencyDeleted  int64
+}
+
+// CleanupTaskExecutionLogs removes finished task execution logs according to frequency-based retention.
+func CleanupTaskExecutionLogs(ctx context.Context, now time.Time) (TaskExecutionCleanupStats, error) {
+	const (
+		frequencyWindowDays    = 30
+		highFrequencyThreshold = frequencyWindowDays
+	)
+
+	frequencyWindowStart := now.AddDate(0, 0, -frequencyWindowDays)
+	highFrequencyCutoff := now.AddDate(0, 0, -3)
+	lowFrequencyCutoff := now.AddDate(0, 0, -30)
+	terminalStatuses := []TaskExecutionStatus{TaskExecutionStatusSucceeded, TaskExecutionStatusFailed}
+
+	var highFrequencyTaskTypes []string
+	if err := db.DB(ctx).
+		Model(&TaskExecution{}).
+		Select("task_type").
+		Where("created_at >= ?", frequencyWindowStart).
+		Group("task_type").
+		Having("COUNT(*) > ?", highFrequencyThreshold).
+		Pluck("task_type", &highFrequencyTaskTypes).Error; err != nil {
+		return TaskExecutionCleanupStats{}, err
+	}
+
+	var highFrequencyDeleted int64
+	if len(highFrequencyTaskTypes) > 0 {
+		highFrequencyResult := db.DB(ctx).
+			Where("status IN ?", terminalStatuses).
+			Where("created_at < ?", highFrequencyCutoff).
+			Where("task_type IN ?", highFrequencyTaskTypes).
+			Delete(&TaskExecution{})
+		if highFrequencyResult.Error != nil {
+			return TaskExecutionCleanupStats{}, highFrequencyResult.Error
+		}
+		highFrequencyDeleted = highFrequencyResult.RowsAffected
+	}
+
+	lowFrequencyQuery := db.DB(ctx).
+		Where("status IN ?", terminalStatuses).
+		Where("created_at < ?", lowFrequencyCutoff)
+	if len(highFrequencyTaskTypes) > 0 {
+		lowFrequencyQuery = lowFrequencyQuery.Where("task_type NOT IN ?", highFrequencyTaskTypes)
+	}
+	lowFrequencyResult := lowFrequencyQuery.Delete(&TaskExecution{})
+	if lowFrequencyResult.Error != nil {
+		return TaskExecutionCleanupStats{}, lowFrequencyResult.Error
+	}
+
+	return TaskExecutionCleanupStats{
+		HighFrequencyDeleted: highFrequencyDeleted,
+		LowFrequencyDeleted:  lowFrequencyResult.RowsAffected,
+	}, nil
+}

backend/plugins/drivers/driver_asynq_worker/utils.go

@@ -0,0 +1,115 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"github.com/redis/go-redis/v9/maintnotifications"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/config"
+)
+
+type redisClientConnOpt struct {
+	options redis.Options
+}
+
+func (opt redisClientConnOpt) MakeRedisClient() interface{} {
+	return redis.NewClient(&opt.options)
+}
+
+type redisClusterConnOpt struct {
+	options redis.ClusterOptions
+}
+
+func (opt redisClusterConnOpt) MakeRedisClient() interface{} {
+	return redis.NewClusterClient(&opt.options)
+}
+
+type redisFailoverConnOpt struct {
+	options                   redis.FailoverOptions
+	maintNotificationsEnabled bool
+}
+
+func (opt redisFailoverConnOpt) MakeRedisClient() interface{} {
+	client := redis.NewFailoverClient(&opt.options)
+	// go-redis v9.16 does not expose maintenance notification settings on
+	// FailoverOptions, so apply the configured mode before the client is used.
+	client.Options().MaintNotificationsConfig = maintNotificationsConfig(opt.maintNotificationsEnabled)
+	return client
+}
+
+func maintNotificationsConfig(enabled bool) *maintnotifications.Config {
+	mode := maintnotifications.ModeDisabled
+	if enabled {
+		mode = maintnotifications.ModeAuto
+	}
+	return &maintnotifications.Config{Mode: mode}
+}
+
+// RedisOpt asynq Redis 连接配置（兼容 Standalone/Sentinel/Cluster）
+var RedisOpt asynq.RedisConnOpt
+
+// AsynqClient asynq 客户端，用于任务入队
+var AsynqClient *asynq.Client
+
+func init() {
+	RedisOpt = NewRedisConnOpt()
+	AsynqClient = asynq.NewClient(RedisOpt)
+}
+
+// NewRedisConnOpt 根据配置返回对应的 asynq Redis 连接选项
+func NewRedisConnOpt() asynq.RedisConnOpt {
+	cfg := config.Config.Redis
+	addrs := cfg.Addrs
+
+	if cfg.ClusterMode {
+		return redisClusterConnOpt{
+			options: redis.ClusterOptions{
+				Addrs:                    addrs,
+				Username:                 cfg.Username,
+				Password:                 cfg.Password,
+				MaintNotificationsConfig: maintNotificationsConfig(cfg.MaintNotifications),
+			},
+		}
+	}
+
+	if cfg.MasterName != "" {
+		return redisFailoverConnOpt{
+			maintNotificationsEnabled: cfg.MaintNotifications,
+			options: redis.FailoverOptions{
+				MasterName:    cfg.MasterName,
+				SentinelAddrs: addrs,
+				Username:      cfg.Username,
+				Password:      cfg.Password,
+				DB:            cfg.DB,
+			},
+		}
+	}
+
+	addr := "localhost:6379"
+	if len(addrs) > 0 {
+		addr = addrs[0]
+	}
+	return redisClientConnOpt{
+		options: redis.Options{
+			Addr:                     addr,
+			Username:                 cfg.Username,
+			Password:                 cfg.Password,
+			DB:                       cfg.DB,
+			PoolSize:                 cfg.PoolSize,
+			MaintNotificationsConfig: maintNotificationsConfig(cfg.MaintNotifications),
+		},
+	}
+}
+
+// PrefixedQueue 返回带前缀的队列名，用于 Cluster 模式隔离
+func PrefixedQueue(queue string) string {
+	prefix := config.Config.Redis.KeyPrefix
+	if prefix == "" {
+		return queue
+	}
+	return prefix + queue
+}

backend/plugins/drivers/driver_asynq_worker/utils_test.go

@@ -0,0 +1,59 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/config"
+	"github.com/redis/go-redis/v9/maintnotifications"
+)
+
+func TestMaintNotificationsConfig(t *testing.T) {
+	tests := []struct {
+		name     string
+		enabled  bool
+		wantMode maintnotifications.Mode
+	}{
+		{
+			name:     "disabled mode when flag is false",
+			enabled:  false,
+			wantMode: maintnotifications.ModeDisabled,
+		},
+		{
+			name:     "auto mode when flag is true",
+			enabled:  true,
+			wantMode: maintnotifications.ModeAuto,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := maintNotificationsConfig(tt.enabled)
+			if cfg == nil {
+				t.Fatalf("maintNotificationsConfig(%v) = nil, want non-nil", tt.enabled)
+			}
+			if cfg.Mode != tt.wantMode {
+				t.Fatalf("maintNotificationsConfig(%v).Mode = %v, want %v", tt.enabled, cfg.Mode, tt.wantMode)
+			}
+		})
+	}
+}
+
+func TestPrefixedQueue(t *testing.T) {
+	oldPrefix := config.Config.Redis.KeyPrefix
+	defer func() {
+		config.Config.Redis.KeyPrefix = oldPrefix
+	}()
+
+	config.Config.Redis.KeyPrefix = "test:"
+	if got := PrefixedQueue("default"); got != "test:default" {
+		t.Fatalf("PrefixedQueue() = %q, want %q", got, "test:default")
+	}
+
+	config.Config.Redis.KeyPrefix = ""
+	if got := PrefixedQueue("default"); got != "default" {
+		t.Fatalf("PrefixedQueue() = %q, want %q", got, "default")
+	}
+}