feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误 refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到 Wavelet/pkg/cache/disk，同步后与上游零漂移。验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与 232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。 docs(cordis): 记录 T1 清理结果与五个复用阻塞点 refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import： shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→ 上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异： httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort* 一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。两处非等价差异按语义处理： - batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，避免 model 反向依赖基础设施类型； - 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地副本，待与 infra 初始化一并迁移（已登记在清理计划）。验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异； make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为 response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。 chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被 gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与 driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh 现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。 AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、 internal/cmd）改到当前插件路径。验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条操作与基线逐条一致；make build-all 四进制；gofmt 干净。 feat(cordis): server 插件化并改由内核挂载控制面路由新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix) 声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为 core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。删除 router.Serve 与 registerRoutes，装配根改为 core.App + driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条 (方法路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的 openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend 标签编译通过；前端零改动。已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。 feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由 server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达 /resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list 端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增 HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，新增路由表导出 harness，固化 256 条 (方法路径) 基线供插件化对拍。上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录前缀输出差异并在同步后提醒确认补丁是否仍在。验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。 docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口 feat(cordis): agent/relay/flared 落地为内核驱动插件三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver （自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入 Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、 openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式 runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持 -config 旗标、默认路径、退出码与启动/停止日志不变。验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。 refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层 backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared} 加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与 repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与 2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon 入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且 232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制 strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0 时报错（防门禁静默失效）；前端零改动。 feat(cordis): 落地 backend/share 共享层与上游同步脚本跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖 backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。 go build 通过，go test ./... exit 0（142 包 ok），前端零改动。 refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare 全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持 Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至 backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API 操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，待 P4 挂载上游路由后再纳入 plugins/。 style: 修正模块路径改写导致的 import 分组排序漂移 refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare 对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend， swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费， Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，四进制产物正常，前端零改动。 chore(cordis): 落地改造计划与 schema/路由基线新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单与 foundation 实施计划。 docs(cordis): add OpenFlare Cordis 架构改造设计明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件 (server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose 迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，确保已部署库不重跑历史、不丢数据。
2026-10-06 23:56:37 +08:00 · 2026-08-29 19:28:39 +08:00
parent 9f79fb9969
commit dbaa3bf140
1327 changed files with 91634 additions and 4157 deletions
@@ -0,0 +1,28 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+type queueConfig struct {
+	Name     string `config:"name"`
+	Priority int    `config:"priority"`
+}
+
+type workerConfig struct {
+	Concurrency    int           `config:"concurrency" env:"WORKER_CONCURRENCY" default:"10"`
+	StrictPriority bool          `config:"strict_priority" env:"WORKER_STRICT_PRIORITY" default:"false"`
+	Queues         []queueConfig `config:"queues"`
+}
+
+type redisWorkerConfig struct {
+	Enabled            bool     `config:"enabled" env:"REDIS_ENABLED" default:"false" autoEnable:"REDIS_ADDR"`
+	Addrs              []string `config:"addrs" env:"REDIS_ADDR"`
+	Username           string   `config:"username" env:"REDIS_USERNAME"`
+	Password           string   `config:"password" env:"REDIS_PASSWORD" secret:"true"`
+	DB                 int      `config:"db" env:"REDIS_DB"`
+	ClusterMode        bool     `config:"cluster_mode" env:"REDIS_CLUSTER_MODE"`
+	MasterName         string   `config:"master_name" env:"REDIS_MASTER_NAME"`
+	KeyPrefix          string   `config:"key_prefix" env:"REDIS_KEY_PREFIX"`
+	PoolSize           int      `config:"pool_size" env:"REDIS_POOL_SIZE"`
+	MaintNotifications bool     `config:"maint_notifications" env:"REDIS_MAINT_NOTIFICATIONS" default:"false"`
+}
@@ -0,0 +1,12 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+// 任务队列名称
+const (
+	QueueDefault = "default"
+)
+
+// DefaultMaxRetry 任务默认最大重试次数
+const DefaultMaxRetry = 3
@@ -0,0 +1,55 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"sync"
+
+	"github.com/redis/go-redis/v9"
+	"gorm.io/gorm"
+)
+
+var (
+	dbMu      sync.RWMutex
+	dbSvc     contracts.DBService
+	redisMu   sync.RWMutex
+	rdbClient redis.UniversalClient
+)
+
+func setDBService(s contracts.DBService) {
+	dbMu.Lock()
+	defer dbMu.Unlock()
+	dbSvc = s
+}
+
+// SetRedisClient sets the redis client used for task logs.
+func SetRedisClient(c redis.UniversalClient) {
+	redisMu.Lock()
+	defer redisMu.Unlock()
+	rdbClient = c
+}
+
+func getDB(ctx context.Context) *gorm.DB {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.DBService](c); err == nil && s != nil {
+			return s.DB(ctx)
+		}
+	}
+	dbMu.RLock()
+	s := dbSvc
+	dbMu.RUnlock()
+	if s != nil {
+		return s.DB(ctx)
+	}
+	return nil
+}
+
+func getRedisClient() redis.UniversalClient {
+	redisMu.RLock()
+	defer redisMu.RUnlock()
+	return rdbClient
+}
@@ -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"
+)
@@ -0,0 +1,502 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/util"
+	"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"
+
+	otel_trace "Wavelet/pkg/trace"
+)
+
+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"
+
+	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 := GetAsynqClient().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 := GetAsynqClient().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, 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)
+}
@@ -0,0 +1,431 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/testhelper"
+	"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/redis/go-redis/v9"
+	"gorm.io/gorm"
+)
+
+func init() {
+	_ = idgen.Init(1)
+}
+
+type mockDBService struct {
+	db *gorm.DB
+}
+
+func (m *mockDBService) GORM() *gorm.DB {
+	return m.db
+}
+
+func (m *mockDBService) DB(ctx context.Context) *gorm.DB {
+	return m.db.WithContext(ctx)
+}
+
+func (m *mockDBService) Named(_ string) *gorm.DB {
+	return m.db
+}
+
+// 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() {
+	testDB, mr, cleanup := testhelper.SetupTestEnvironment(t)
+	setDBService(&mockDBService{db: testDB})
+	rdb := redis.NewClient(&redis.Options{Addr: mr.Addr()})
+	SetRedisClient(rdb)
+
+	AsynqClient = asynq.NewClient(asynq.RedisClientOpt{
+		Addr: mr.Addr(),
+	})
+	// 注册测试用 handler
+	RegisterHandler(testTaskType, successHandler())
+	return func() {
+		if AsynqClient != nil {
+			_ = AsynqClient.Close()
+			AsynqClient = nil
+		}
+		_ = rdb.Close()
+		setDBService(nil)
+		SetRedisClient(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)
+}
@@ -0,0 +1,36 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import "context"
+
+// TaskResult 任务执行结果
+//
+// 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, ...) 追加执行日志。
+// 任务的创建、状态更新、错误记录、重试计数全部由框架透明处理。
+//
+// TaskHandler 保留完整名称以避免与通用 Handler 混淆
+type TaskHandler interface {
+	// Execute 执行任务业务逻辑
+	//   - ctx: 已注入 Trace Span 和 taskID 的上下文
+	//   - payload: 调度时传入的原始参数（可为 nil）
+	//   - 返回 TaskResult 描述执行结果，或 error 表示执行失败
+	Execute(ctx context.Context, payload []byte) (*TaskResult, error)
+}
@@ -0,0 +1,194 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/core/extpoints"
+	"sync"
+)
+
+// TaskParam 任务参数定义
+//
+// 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 任务元数据
+//
+// TaskMeta 保留完整名称以避免与通用 Meta 混淆
+type TaskMeta struct {
+	Type         string      `json:"type"`
+	AsynqTask    string      `json:"asynq_task"`
+	Name         string      `json:"name"`
+	Description  string      `json:"description"`
+	Category     string      `json:"category,omitempty"`
+	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 获取所有已注册的元数据列表（优先结合 activeTaskReg 和 dispatchableTasks）
+func GetDispatchableTasks() []TaskMeta {
+	activeTaskRegMutex.RLock()
+	reg := activeTaskReg
+	activeTaskRegMutex.RUnlock()
+
+	var metas []TaskMeta
+	seen := make(map[string]bool)
+
+	if reg != nil {
+		for _, td := range reg.Tasks() {
+			dto := td.ToDTO()
+			m := toInternalTaskMeta(dto)
+			metas = append(metas, m)
+			seen[m.Type] = true
+			seen[m.AsynqTask] = true
+		}
+	}
+
+	dispatchableTasksMutex.RLock()
+	for _, t := range dispatchableTasks {
+		if !seen[t.Type] && !seen[t.AsynqTask] {
+			metas = append(metas, t)
+			seen[t.Type] = true
+			seen[t.AsynqTask] = true
+		}
+	}
+	dispatchableTasksMutex.RUnlock()
+
+	return metas
+}
+
+func toInternalTaskMeta(dto contracts.TaskMetaDTO) TaskMeta {
+	params := make([]TaskParam, 0, len(dto.Params))
+	for _, p := range dto.Params {
+		params = append(params, TaskParam{
+			Name:        p.Name,
+			Label:       p.Label,
+			Type:        p.Type,
+			Required:    p.Required,
+			Placeholder: p.Placeholder,
+			Description: p.Description,
+		})
+	}
+	taskType := dto.Type
+	if taskType == "" {
+		taskType = dto.AsynqTask
+	}
+	if taskType == "" {
+		taskType = dto.Name
+	}
+	asynqTask := dto.AsynqTask
+	if asynqTask == "" {
+		asynqTask = taskType
+	}
+	name := dto.Name
+	if name == "" {
+		name = dto.DisplayName
+	}
+	if name == "" {
+		name = taskType
+	}
+	return TaskMeta{
+		Type:         taskType,
+		AsynqTask:    asynqTask,
+		Name:         name,
+		Description:  dto.Description,
+		Category:     dto.Category,
+		SupportsTime: dto.SupportsTime,
+		MaxRetry:     dto.MaxRetry,
+		Queue:        dto.Queue,
+		Retryable:    dto.Retryable,
+		Params:       params,
+	}
+}
+
+var (
+	activeTaskRegMutex sync.RWMutex
+	activeTaskReg      extpoints.TaskExtension
+)
+
+// SetActiveTaskExtension sets the active task extension registry for task resolution.
+func SetActiveTaskExtension(reg extpoints.TaskExtension) {
+	activeTaskRegMutex.Lock()
+	defer activeTaskRegMutex.Unlock()
+	activeTaskReg = reg
+}
+
+func getFromActiveTaskExtension(taskType string) *TaskMeta {
+	activeTaskRegMutex.RLock()
+	defer activeTaskRegMutex.RUnlock()
+	if activeTaskReg == nil {
+		return nil
+	}
+	for _, td := range activeTaskReg.Tasks() {
+		if td.Type == taskType || td.Pattern == taskType {
+			m := toInternalTaskMeta(td.ToDTO())
+			return &m
+		}
+	}
+	return nil
+}
+
+// GetTaskMeta 根据任务类型获取元数据
+func GetTaskMeta(taskType string) *TaskMeta {
+	if m := getFromActiveTaskExtension(taskType); m != nil {
+		return m
+	}
+
+	dispatchableTasksMutex.RLock()
+	for _, t := range dispatchableTasks {
+		if t.Type == taskType || t.AsynqTask == taskType {
+			copied := t
+			dispatchableTasksMutex.RUnlock()
+			return &copied
+		}
+	}
+	dispatchableTasksMutex.RUnlock()
+
+	return nil
+}
+
+// GetTaskMetaByAsynqTask 根据 Asynq 任务名称获取元数据
+func GetTaskMetaByAsynqTask(asynqTask string) *TaskMeta {
+	return GetTaskMeta(asynqTask)
+}
+
+// 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
+}
@@ -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)
+	}
+}
@@ -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
+}
@@ -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")
+	}
+}
@@ -0,0 +1,496 @@
+// 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 (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	defaultConcurrency     = 10
+	defaultShutdownTimeout = 10 * time.Second
+)
+
+// 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
+	taskSvc         contracts.TaskService
+}
+
+// New creates a new Asynq Worker driver plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{
+		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"
+}
+
+// DeclareConfig declares configuration bindings consumed by the Asynq worker driver.
+func (p *Plugin) DeclareConfig() []core.ConfigBinding {
+	return []core.ConfigBinding{
+		{Prefix: "worker", Target: &workerConfig{}},
+		{Prefix: "redis", Target: &redisWorkerConfig{}},
+	}
+}
+
+// ConfigEnabled gates plugin activation when Redis is enabled.
+func (p *Plugin) ConfigEnabled(view core.ConfigView) bool {
+	return view.Bool("redis.enabled", false)
+}
+
+// Apply mounts the Asynq Worker driver into the micro-kernel Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	var wCfg workerConfig
+	_ = ctx.Config().Bind("worker", &wCfg)
+	var rCfg redisWorkerConfig
+	_ = ctx.Config().Bind("redis", &rCfg)
+
+	p.mu.Lock()
+	p.coreCtx = ctx
+	if p.concurrency == defaultConcurrency && wCfg.Concurrency > 0 {
+		p.concurrency = wCfg.Concurrency
+	}
+	p.strictPriority = wCfg.StrictPriority
+	if len(p.queues) == 1 && p.queues["default"] == 1 && len(wCfg.Queues) > 0 {
+		qMap := make(map[string]int, len(wCfg.Queues))
+		for _, q := range wCfg.Queues {
+			qMap[q.Name] = q.Priority
+		}
+		p.queues = qMap
+	}
+	if p.redisOpt == nil {
+		p.redisOpt = NewRedisConnOptWithConfig(rCfg)
+	}
+	RedisOpt = p.redisOpt
+	ResetAsynqClient()
+	p.mu.Unlock()
+
+	// 0. Bind DBService
+	if db, err := core.Inject[contracts.DBService](ctx); err == nil && db != nil {
+		setDBService(db)
+	} else {
+		core.When[contracts.DBService](ctx, func(db contracts.DBService) {
+			setDBService(db)
+		})
+	}
+	ctx.OnDispose(func() error {
+		setDBService(nil)
+		return nil
+	})
+
+	// 1. Provide contracts.TaskService
+	p.taskSvc = &taskServiceImpl{}
+	core.Provide[contracts.TaskService](ctx, p.taskSvc)
+	SetActiveTaskExtension(ctx.Tasks())
+
+	ctx.OnDispose(func() error {
+		SetActiveTaskExtension(nil)
+		SetRedisClient(nil)
+		ResetAsynqClient()
+		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)
+		}
+	}
+
+	opt := p.redisOpt
+	if opt == nil {
+		opt = NewRedisConnOpt()
+	}
+	RedisOpt = opt
+
+	if getRedisClient() == nil {
+		if mk, ok := opt.(interface{ MakeRedisClient() interface{} }); ok {
+			if client, ok := mk.MakeRedisClient().(redis.UniversalClient); ok {
+				SetRedisClient(client)
+			}
+		}
+	}
+
+	if p.server == nil {
+		p.server = asynq.NewServer(
+			opt,
+			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 {
+			c, payload, _ := extractTaskTraceContext(c, t.Payload())
+			return fn(c, 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(c context.Context, t *asynq.Task) error {
+			_, payload, _ := extractTaskTraceContext(c, t.Payload())
+			return fn(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)
+	}
+}
+
+type taskServiceImpl struct{}
+
+func (s *taskServiceImpl) Dispatch(ctx context.Context, taskType string, payload []byte, triggeredBy string) (string, error) {
+	return DispatchTask(ctx, taskType, payload, triggeredBy)
+}
+
+func (s *taskServiceImpl) ListTasks() []contracts.TaskMetaDTO {
+	all := GetDispatchableTasks()
+	res := make([]contracts.TaskMetaDTO, 0, len(all))
+	for _, m := range all {
+		params := make([]contracts.TaskParamDTO, 0, len(m.Params))
+		for _, param := range m.Params {
+			params = append(params, contracts.TaskParamDTO{
+				Name:        param.Name,
+				Label:       param.Label,
+				Type:        param.Type,
+				Description: param.Description,
+				Placeholder: param.Placeholder,
+				Required:    param.Required,
+			})
+		}
+		taskType := m.Type
+		if taskType == "" {
+			taskType = m.AsynqTask
+		}
+		if taskType == "" {
+			taskType = m.Name
+		}
+		asynqTask := m.AsynqTask
+		if asynqTask == "" {
+			asynqTask = taskType
+		}
+		name := m.Name
+		if name == "" {
+			name = taskType
+		}
+		res = append(res, contracts.TaskMetaDTO{
+			Type:         taskType,
+			AsynqTask:    asynqTask,
+			Name:         name,
+			DisplayName:  name,
+			Description:  m.Description,
+			Category:     m.Category,
+			SupportsTime: m.SupportsTime,
+			Params:       params,
+			MaxRetry:     m.MaxRetry,
+			Queue:        m.Queue,
+			Retryable:    m.Retryable,
+		})
+	}
+	return res
+}
+
+func (s *taskServiceImpl) GetTaskMeta(taskType string) (contracts.TaskMetaDTO, bool) {
+	m := GetTaskMeta(taskType)
+	if m == nil {
+		return contracts.TaskMetaDTO{}, false
+	}
+	params := make([]contracts.TaskParamDTO, 0, len(m.Params))
+	for _, param := range m.Params {
+		params = append(params, contracts.TaskParamDTO{
+			Name:        param.Name,
+			Label:       param.Label,
+			Type:        param.Type,
+			Description: param.Description,
+			Placeholder: param.Placeholder,
+			Required:    param.Required,
+		})
+	}
+	tType := m.Type
+	if tType == "" {
+		tType = m.AsynqTask
+	}
+	if tType == "" {
+		tType = m.Name
+	}
+	asynqTask := m.AsynqTask
+	if asynqTask == "" {
+		asynqTask = tType
+	}
+	name := m.Name
+	if name == "" {
+		name = tType
+	}
+	return contracts.TaskMetaDTO{
+		Type:         tType,
+		AsynqTask:    asynqTask,
+		Name:         name,
+		DisplayName:  name,
+		Description:  m.Description,
+		Category:     m.Category,
+		SupportsTime: m.SupportsTime,
+		Params:       params,
+		MaxRetry:     m.MaxRetry,
+		Queue:        m.Queue,
+		Retryable:    m.Retryable,
+	}, true
+}
+
+func (s *taskServiceImpl) ListExecutions(ctx context.Context, taskType, status string, page, pageSize int) ([]contracts.TaskExecutionDTO, int64, error) {
+	db := getDB(ctx)
+	if db == nil {
+		return nil, 0, errors.New("db not initialized")
+	}
+	query := db.Model(&TaskExecution{})
+	if taskType != "" {
+		query = query.Where("task_type = ?", taskType)
+	}
+	if status != "" {
+		query = query.Where("status = ?", status)
+	}
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	var rows []TaskExecution
+	offset := (page - 1) * pageSize
+	if err := query.Order("id DESC").Offset(offset).Limit(pageSize).Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	res := make([]contracts.TaskExecutionDTO, 0, len(rows))
+	for i := range rows {
+		res = append(res, toTaskExecutionDTO(&rows[i]))
+	}
+	return res, total, nil
+}
+
+func (s *taskServiceImpl) Retry(ctx context.Context, id uint64) (string, error) {
+	return RetryTask(ctx, id)
+}
+
+func (s *taskServiceImpl) ValidatePayload(taskType string, payload []byte) ([]byte, error) {
+	meta := GetTaskMeta(taskType)
+	if meta == nil {
+		return payload, nil
+	}
+	return ValidateAndNormalizePayload(meta.AsynqTask, payload)
+}
+
+func (s *taskServiceImpl) ReloadScheduler() error {
+	return nil
+}
+
+func (s *taskServiceImpl) AppendLog(ctx context.Context, format string, args ...any) {
+	AppendLog(ctx, format, args...)
+}
+
+func (s *taskServiceImpl) GetExecution(ctx context.Context, id uint64) (*contracts.TaskExecutionDTO, error) {
+	exec, err := GetTaskExecutionByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	dto := toTaskExecutionDTO(exec)
+	return &dto, nil
+}
+
+func toTaskExecutionDTO(exec *TaskExecution) contracts.TaskExecutionDTO {
+	return contracts.TaskExecutionDTO{
+		ID:           exec.ID,
+		TaskID:       exec.TaskID,
+		TaskType:     exec.TaskType,
+		TaskName:     exec.TaskName,
+		Status:       string(exec.Status),
+		Retryable:    exec.Retryable,
+		MaxRetry:     exec.MaxRetry,
+		RetryCount:   exec.RetryCount,
+		Log:          exec.Log,
+		ErrorMessage: exec.ErrorMessage,
+		Result:       exec.Result,
+		StartedAt:    exec.StartedAt,
+		FinishedAt:   exec.FinishedAt,
+		Duration:     exec.Duration,
+		Payload:      exec.Payload,
+		TriggeredBy:  exec.TriggeredBy,
+		CreatedAt:    exec.CreatedAt,
+		UpdatedAt:    exec.UpdatedAt,
+	}
+}
@@ -0,0 +1,126 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/pkg/idgen"
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+const (
+	taskExecutionLogRedisKeyPrefix = "task:execution:log:"
+	taskExecutionLogExpiration     = 24 * time.Hour
+	taskExecutionLogMaxLines       = 1000
+)
+
+func taskExecutionLogRedisKey(taskID string) string {
+	return taskExecutionLogRedisKeyPrefix + taskID
+}
+
+func createTaskExecution(ctx context.Context, execution *TaskExecution) error {
+	if execution.ID == 0 {
+		execution.ID = idgen.NextUint64ID()
+	}
+	return getDB(ctx).Create(execution).Error
+}
+
+func updateTaskExecution(ctx context.Context, execution *TaskExecution) error {
+	return getDB(ctx).Omit("log").Save(execution).Error
+}
+
+func getTaskExecutionByID(ctx context.Context, id uint64) (*TaskExecution, error) {
+	var execution TaskExecution
+	if err := getDB(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 := getDB(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, logLine string) error {
+	rdb := getRedisClient()
+	if rdb == 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 := rdb.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 {
+	rdb := getRedisClient()
+	if rdb == nil {
+		return errors.New("redis client is not initialized")
+	}
+
+	key := taskExecutionLogRedisKey(taskID)
+	logLines, err := rdb.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 := getDB(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 := rdb.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 {
+	rdb := getRedisClient()
+	if rdb == nil {
+		return nil
+	}
+
+	logLines, err := rdb.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
+}
@@ -0,0 +1,147 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// TaskExecutionStatus 任务执行状态
+type TaskExecutionStatus string
+
+// Task execution status constants.
+const (
+	TaskExecutionStatusPending   TaskExecutionStatus = "pending"
+	TaskExecutionStatusRunning   TaskExecutionStatus = "running"
+	TaskExecutionStatusSucceeded TaskExecutionStatus = "succeeded"
+	TaskExecutionStatusFailed    TaskExecutionStatus = "failed"
+)
+
+// TaskExecution 任务执行记录
+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 getDB(ctx).Create(exec).Error
+}
+
+// GetTaskExecutionByTaskID 根据 TaskID 查询执行记录
+func GetTaskExecutionByTaskID(ctx context.Context, taskID string) (*TaskExecution, error) {
+	var exec TaskExecution
+	if err := getDB(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 := getDB(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 := getDB(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.
+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 := getDB(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 := getDB(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 := getDB(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
+}
@@ -0,0 +1,169 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"sync"
+
+	"github.com/hibiken/asynq"
+	"github.com/redis/go-redis/v9"
+	"github.com/redis/go-redis/v9/maintnotifications"
+)
+
+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
+
+var asynqClientMu sync.RWMutex
+
+// GetAsynqClient returns the active Asynq client, dynamically creating or refreshing it if needed.
+func GetAsynqClient() *asynq.Client {
+	asynqClientMu.RLock()
+	if AsynqClient != nil {
+		asynqClientMu.RUnlock()
+		return AsynqClient
+	}
+	asynqClientMu.RUnlock()
+
+	asynqClientMu.Lock()
+	defer asynqClientMu.Unlock()
+	if AsynqClient != nil {
+		return AsynqClient
+	}
+
+	opt := RedisOpt
+	if opt == nil {
+		opt = NewRedisConnOpt()
+		RedisOpt = opt
+	}
+	AsynqClient = asynq.NewClient(opt)
+	return AsynqClient
+}
+
+// ResetAsynqClient resets the Asynq client so it will be re-created with current config.
+func ResetAsynqClient() {
+	asynqClientMu.Lock()
+	defer asynqClientMu.Unlock()
+	if AsynqClient != nil {
+		_ = AsynqClient.Close()
+		AsynqClient = nil
+	}
+}
+
+var (
+	keyPrefixMu sync.RWMutex
+	keyPrefix   string
+)
+
+// SetKeyPrefix sets the redis key prefix for queue names.
+func SetKeyPrefix(prefix string) {
+	keyPrefixMu.Lock()
+	defer keyPrefixMu.Unlock()
+	keyPrefix = prefix
+}
+
+// GetKeyPrefix returns the redis key prefix for queue names.
+func GetKeyPrefix() string {
+	keyPrefixMu.RLock()
+	defer keyPrefixMu.RUnlock()
+	return keyPrefix
+}
+
+// NewRedisConnOpt 根据配置返回对应的 asynq Redis 连接选项
+func NewRedisConnOpt() asynq.RedisConnOpt {
+	return NewRedisConnOptWithConfig(redisWorkerConfig{})
+}
+
+// NewRedisConnOptWithConfig returns the asynq RedisConnOpt based on the provided configuration.
+func NewRedisConnOptWithConfig(cfg redisWorkerConfig) asynq.RedisConnOpt {
+	SetKeyPrefix(cfg.KeyPrefix)
+	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 := GetKeyPrefix()
+	if prefix == "" {
+		return queue
+	}
+	return prefix + queue
+}
@@ -0,0 +1,58 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"testing"
+
+	"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 := GetKeyPrefix()
+	defer func() {
+		SetKeyPrefix(oldPrefix)
+	}()
+
+	SetKeyPrefix("test:")
+	if got := PrefixedQueue("default"); got != "test:default" {
+		t.Fatalf("PrefixedQueue() = %q, want %q", got, "test:default")
+	}
+
+	SetKeyPrefix("")
+	if got := PrefixedQueue("default"); got != "default" {
+		t.Fatalf("PrefixedQueue() = %q, want %q", got, "default")
+	}
+}