fix: upgrade deps

* feat: show upload progress for file tasks

* feat: show upload progress for batch file tasks

* style: distinguish download and upload phases

* style: mark successful task completion

* fix: preserve storage save error context

* fix: serialize single-file progress updates

* fix: stabilize batch upload progress reporting

Correct batch upload totals, completion state, actual file sizes, and synchronized progress snapshots. Add regression coverage for concurrent updates and phase transitions.

* feat: show per-file transfer progress

Format single-file and batch download and upload states with Telegram entities, blockquotes, speeds, transferred sizes, progress bars, concise counters, and accurate confirmation handling. Cover upload retries plus final, error, and cancellation messages with regression tests.

* chore: remove transfer progress tests

* test: restore critical transfer progress coverage

* test: cover interleaved batch transfers

* fix: declare progress styles in locale templates

.gitignore

@@ -11,4 +11,5 @@ temp/
 playwright/
 testplugins/
 *.exe
-tmp-*
+tmp-*
+saveany-bot

Dockerfile

@@ -26,7 +26,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
 
 FROM alpine:latest
 
-RUN apk add --no-cache curl ffmpeg
+RUN apk add --no-cache curl ffmpeg yt-dlp
 
 WORKDIR /app
 

Dockerfile.pico

@@ -7,6 +7,8 @@ ARG BuildTime="Unknown"
 
 WORKDIR /app
 
+RUN apk add --no-cache ca-certificates
+
 COPY go.mod go.sum ./
 RUN --mount=type=cache,target=/go/pkg/mod \
     go mod download
@@ -31,5 +33,9 @@ FROM scratch
 WORKDIR /app
 
 COPY --from=builder /app/saveany-bot .
+COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
+
+ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
+ENV SSL_CERT_DIR=/etc/ssl/certs
 
 ENTRYPOINT ["/app/saveany-bot"]

README.md

@@ -26,12 +26,16 @@
 - Multi-user support
 - Auto organize files based on storage rules
 - Watch specified chats and auto-save messages, with filters
+- Transfer files between different storage backends
+- Integrate with yt-dlp to download and save media from 1000+ websites
+- Aria2 integration to download files from URLs/magnets and save to storages
 - Write JS parser plugins to save files from almost any website
 - Storage backends:
   - Alist
   - S3
   - WebDAV
   - Local filesystem
+  - Rclone (via command line)
   - Telegram (re-upload to specified chats)
 
 ## 📦 Quick Start

README_zh.md

@@ -24,12 +24,16 @@
 - 多用户使用
 - 基于存储规则的自动整理
 - 监听并自动转存指定聊天的消息, 支持过滤
+- 在不同存储端之间转存文件
+- 集成 yt-dlp, 从所支持的网站下载并转存媒体文件
+- 集成 Aria2, 支持直链/磁力下载和转存
 - 使用 js 编写解析器插件以转存任意网站的文件
 - 存储端支持:
   - Alist
   - S3
   - WebDAV
   - 本地磁盘
+  - Rclone
   - Telegram (重传回指定聊天)
 
 ## 快速开始

api/auth.go

@@ -0,0 +1,48 @@
+package api
+
+import (
+	"context"
+	"crypto/subtle"
+	"net/http"
+	"strings"
+
+	"github.com/krau/SaveAny-Bot/config"
+)
+
+// tokenContextKey 用于在 context 中存储 token
+type tokenContextKey struct{}
+
+// AuthMiddleware 返回认证中间件
+func AuthMiddleware() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			cfg := config.C().API
+
+			// 从请求头获取 token
+			authHeader := r.Header.Get("Authorization")
+			if authHeader == "" {
+				WriteError(w, http.StatusUnauthorized, "unauthorized", "missing authorization header")
+				return
+			}
+
+			// 提取 Bearer token
+			parts := strings.SplitN(authHeader, " ", 2)
+			if len(parts) != 2 || strings.ToLower(parts[0]) != "bearer" {
+				WriteError(w, http.StatusUnauthorized, "unauthorized", "invalid authorization header format")
+				return
+			}
+
+			token := parts[1]
+
+			// 验证 token
+			if subtle.ConstantTimeCompare([]byte(token), []byte(cfg.Token)) != 1 {
+				WriteError(w, http.StatusUnauthorized, "unauthorized", "invalid token")
+				return
+			}
+
+			// 将 token 添加到 context
+			ctx := context.WithValue(r.Context(), tokenContextKey{}, token)
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}

api/factory.go

@@ -0,0 +1,382 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/krau/SaveAny-Bot/config"
+	"github.com/krau/SaveAny-Bot/core"
+	"github.com/krau/SaveAny-Bot/core/tasks/aria2dl"
+	"github.com/krau/SaveAny-Bot/core/tasks/batchtfile"
+	"github.com/krau/SaveAny-Bot/core/tasks/directlinks"
+	"github.com/krau/SaveAny-Bot/core/tasks/parsed"
+	tphtask "github.com/krau/SaveAny-Bot/core/tasks/telegraph"
+	"github.com/krau/SaveAny-Bot/core/tasks/tfile"
+	"github.com/krau/SaveAny-Bot/core/tasks/transfer"
+	"github.com/krau/SaveAny-Bot/core/tasks/ytdlp"
+	"github.com/krau/SaveAny-Bot/parsers/parsers"
+	"github.com/krau/SaveAny-Bot/pkg/aria2"
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+	"github.com/krau/SaveAny-Bot/pkg/parser"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
+	"github.com/krau/SaveAny-Bot/pkg/telegraph"
+	"github.com/krau/SaveAny-Bot/storage"
+	"github.com/rs/xid"
+)
+
+// TaskFactory 任务工厂
+type TaskFactory struct {
+	ctx context.Context
+}
+
+// NewTaskFactory 创建任务工厂
+func NewTaskFactory(ctx context.Context) *TaskFactory {
+	return &TaskFactory{ctx: ctx}
+}
+
+// CreateTask 创建任务
+func (f *TaskFactory) CreateTask(req *CreateTaskRequest) (*CreateTaskResponse, error) {
+	// 验证存储
+	stor, ok := storage.Storages[req.Storage]
+	if !ok {
+		return nil, fmt.Errorf("storage not found: %s", req.Storage)
+	}
+
+	taskID := xid.New().String()
+	createdAt := time.Now()
+
+	switch req.Type {
+	case tasktype.TaskTypeDirectlinks:
+		return f.createDirectLinksTask(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeYtdlp:
+		return f.createYTDLPTask(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeAria2:
+		return f.createAria2Task(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeParseditem:
+		return f.createParsedTask(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeTgfiles:
+		return f.createTGFilesTask(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeTphpics:
+		return f.createTPHPicsTask(taskID, createdAt, req, stor)
+	case tasktype.TaskTypeTransfer:
+		return f.createTransferTask(taskID, createdAt, req)
+	default:
+		return nil, fmt.Errorf("unsupported task type: %s", req.Type)
+	}
+}
+
+func (f *TaskFactory) registerAndEnqueueTask(task core.Executable, taskType tasktype.TaskType, storageName, path, webhook string) error {
+	taskID := task.TaskID()
+	info := RegisterTask(taskID, string(taskType), storageName, path, task.Title(), webhook)
+
+	// Inject the progress sink into the context so the task's Emit calls update
+	// the API store (and fire the webhook on terminal states) without the task
+	// knowing about the API.
+	taskCtx := taskevent.WithSink(f.ctx, info)
+
+	err := core.AddTask(taskCtx, task)
+	if err != nil {
+		DeleteTask(taskID)
+		return fmt.Errorf("failed to add task: %w", err)
+	}
+
+	return nil
+}
+
+// createDirectLinksTask 创建直链下载任务
+func (f *TaskFactory) createDirectLinksTask(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params DirectLinksParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if len(params.URLs) == 0 {
+		return nil, fmt.Errorf("no URLs provided")
+	}
+
+	task := directlinks.NewTask(taskID, f.ctx, params.URLs, stor, req.Path, nil)
+
+	err := f.registerAndEnqueueTask(task, tasktype.TaskTypeDirectlinks, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeDirectlinks,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createYTDLPTask 创建 yt-dlp 任务
+func (f *TaskFactory) createYTDLPTask(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params YTDLPParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if len(params.URLs) == 0 {
+		return nil, fmt.Errorf("no URLs provided")
+	}
+
+	task := ytdlp.NewTask(taskID, f.ctx, params.URLs, params.Flags, stor, req.Path, nil)
+
+	err := f.registerAndEnqueueTask(task, tasktype.TaskTypeYtdlp, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeYtdlp,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createAria2Task 创建 Aria2 任务
+func (f *TaskFactory) createAria2Task(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params Aria2Params
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if len(params.URLs) == 0 {
+		return nil, fmt.Errorf("no URLs provided")
+	}
+
+	// 检查 Aria2 是否启用
+	cfg := config.C().Aria2
+	if !cfg.Enable {
+		return nil, fmt.Errorf("aria2 is not enabled")
+	}
+
+	aria2Client, err := aria2.NewClient(cfg.Url, cfg.Secret)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create aria2 client: %w", err)
+	}
+
+	// 添加下载任务到 Aria2
+	gid, err := aria2Client.AddURI(f.ctx, params.URLs, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to add aria2 task: %w", err)
+	}
+
+	task := aria2dl.NewTask(taskID, f.ctx, gid, params.URLs, aria2Client, stor, req.Path, nil)
+
+	err = f.registerAndEnqueueTask(task, tasktype.TaskTypeAria2, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeAria2,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createParsedTask 创建解析任务
+func (f *TaskFactory) createParsedTask(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params ParsedParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if params.URL == "" {
+		return nil, fmt.Errorf("no URL provided")
+	}
+
+	// 查找合适的解析器
+	var p parser.Parser
+	for _, parserItem := range parsers.Get() {
+		if parserItem.CanHandle(params.URL) {
+			p = parserItem
+			break
+		}
+	}
+
+	if p == nil {
+		return nil, fmt.Errorf("no parser found for URL: %s", params.URL)
+	}
+
+	// 解析 URL
+	item, err := p.Parse(f.ctx, params.URL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse URL: %w", err)
+	}
+
+	task := parsed.NewTask(taskID, f.ctx, stor, req.Path, item, nil)
+
+	err = f.registerAndEnqueueTask(task, tasktype.TaskTypeParseditem, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeParseditem,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createTGFilesTask 创建 Telegram 文件下载任务
+func (f *TaskFactory) createTGFilesTask(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params TGFilesParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if len(params.MessageLinks) == 0 {
+		return nil, fmt.Errorf("no message links provided")
+	}
+
+	// 提取文件
+	files, err := ExtractFilesFromLinks(f.ctx, params.MessageLinks)
+	if err != nil {
+		return nil, fmt.Errorf("failed to extract files: %w", err)
+	}
+
+	if len(files) == 0 {
+		return nil, fmt.Errorf("no files found in provided links")
+	}
+
+	var task core.Executable
+
+	if len(files) == 1 {
+		// 单个文件任务
+		tfileTask, err := tfile.NewTGFileTask(taskID, f.ctx, files[0], stor, req.Path, nil)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create tfile task: %w", err)
+		}
+		task = tfileTask
+	} else {
+		// 批量文件任务
+		elems := make([]batchtfile.TaskElement, 0, len(files))
+		for _, file := range files {
+			elem, err := batchtfile.NewTaskElement(stor, req.Path, file)
+			if err != nil {
+				return nil, fmt.Errorf("failed to create task element: %w", err)
+			}
+			elems = append(elems, *elem)
+		}
+
+		task = batchtfile.NewBatchTGFileTask(taskID, f.ctx, elems, nil, true)
+	}
+
+	err = f.registerAndEnqueueTask(task, tasktype.TaskTypeTgfiles, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeTgfiles,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createTPHPicsTask 创建 Telegraph 图片下载任务
+func (f *TaskFactory) createTPHPicsTask(taskID string, createdAt time.Time, req *CreateTaskRequest, stor storage.Storage) (*CreateTaskResponse, error) {
+	var params TPHPicsParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	if params.TelegraphURL == "" {
+		return nil, fmt.Errorf("no telegraph URL provided")
+	}
+
+	// 提取图片
+	pics, phPath, err := ExtractTelegraphImages(f.ctx, params.TelegraphURL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to extract telegraph images: %w", err)
+	}
+
+	if len(pics) == 0 {
+		return nil, fmt.Errorf("no images found in telegraph page")
+	}
+
+	client := telegraph.NewClient()
+	task := tphtask.NewTask(taskID, f.ctx, phPath, pics, stor, req.Path, client, nil)
+
+	err = f.registerAndEnqueueTask(task, tasktype.TaskTypeTphpics, req.Storage, req.Path, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeTphpics,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}
+
+// createTransferTask 创建存储间传输任务
+func (f *TaskFactory) createTransferTask(taskID string, createdAt time.Time, req *CreateTaskRequest) (*CreateTaskResponse, error) {
+	var params TransferParams
+	if err := json.Unmarshal(req.Params, &params); err != nil {
+		return nil, fmt.Errorf("invalid params: %w", err)
+	}
+
+	// 验证源存储和目标存储
+	sourceStor, ok := storage.Storages[params.SourceStorage]
+	if !ok {
+		return nil, fmt.Errorf("source storage not found: %s", params.SourceStorage)
+	}
+
+	targetStor, ok := storage.Storages[params.TargetStorage]
+	if !ok {
+		return nil, fmt.Errorf("target storage not found: %s", params.TargetStorage)
+	}
+
+	// 检查源存储是否可读
+	sourceReadable, ok := sourceStor.(storage.StorageReadable)
+	if !ok {
+		return nil, fmt.Errorf("source storage does not support reading: %s", params.SourceStorage)
+	}
+
+	// 检查源存储是否可列
+	sourceListable, ok := sourceStor.(storage.StorageListable)
+	if !ok {
+		return nil, fmt.Errorf("source storage does not support listing: %s", params.SourceStorage)
+	}
+
+	// 列出源文件
+	files, err := sourceListable.ListFiles(f.ctx, params.SourcePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list source files: %w", err)
+	}
+
+	if len(files) == 0 {
+		return nil, fmt.Errorf("no files found at source path: %s", params.SourcePath)
+	}
+
+	// 创建传输元素
+	elems := make([]transfer.TaskElement, 0, len(files))
+	for _, file := range files {
+		elem := transfer.NewTaskElement(sourceReadable, file, targetStor, params.TargetPath)
+		elems = append(elems, *elem)
+	}
+
+	task := transfer.NewTransferTask(taskID, f.ctx, elems, nil, true)
+
+	err = f.registerAndEnqueueTask(task, tasktype.TaskTypeTransfer, params.TargetStorage, params.TargetPath, req.Webhook)
+	if err != nil {
+		return nil, err
+	}
+
+	return &CreateTaskResponse{
+		TaskID:    taskID,
+		Type:      tasktype.TaskTypeTransfer,
+		Status:    TaskStatusQueued,
+		CreatedAt: createdAt,
+	}, nil
+}

api/handlers.go

@@ -1,629 +1,241 @@
 package api
 
 import (
-	"bytes"
-	"context"
 	"encoding/json"
-	"fmt"
-	"io"
-	"math"
 	"net/http"
-	"net/url"
-	"path"
 	"strings"
-	"sync"
-	"sync/atomic"
 	"time"
 
-	"github.com/celestix/gotgproto/ext"
-	"github.com/charmbracelet/log"
-	"github.com/gotd/td/tg"
-	"github.com/krau/SaveAny-Bot/client/bot"
-	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/ruleutil"
-	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
-	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/core"
-	tftask "github.com/krau/SaveAny-Bot/core/tasks/tfile"
-	"github.com/krau/SaveAny-Bot/database"
-	"github.com/krau/SaveAny-Bot/pkg/queue"
-	"github.com/krau/SaveAny-Bot/pkg/tfile"
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
 	"github.com/krau/SaveAny-Bot/storage"
-	"github.com/rs/xid"
 )
 
-// Request/Response types
-type CreateTaskRequest struct {
-	TelegramURL string `json:"telegram_url"`
-	StorageName string `json:"storage_name,omitempty"`
-	DirPath     string `json:"dir_path,omitempty"`
-	UserID      int64  `json:"user_id"`
+// Handlers 处理器结构体
+type Handlers struct {
+	factory *TaskFactory
 }
 
-type CreateTaskResponse struct {
-	TaskID  string `json:"task_id"`
-	Message string `json:"message"`
+// NewHandlers 创建处理器
+func NewHandlers(factory *TaskFactory) *Handlers {
+	return &Handlers{factory: factory}
 }
 
-type TaskStatusResponse struct {
-	TaskID      string    `json:"task_id"`
-	Status      string    `json:"status"` // queued, running, completed, failed, canceled
-	Title       string    `json:"title"`
-	CreatedAt   time.Time `json:"created_at"`
-	Error       string    `json:"error,omitempty"`
-	Downloaded  int64     `json:"downloaded,omitempty"`   // Bytes downloaded
-	Total       int64     `json:"total,omitempty"`        // Total bytes
-	ProgressPct float64   `json:"progress_pct,omitempty"` // Progress percentage (0-100)
-}
+// CreateTaskHandler 创建任务处理器
+func (h *Handlers) CreateTaskHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only POST method is allowed")
+		return
+	}
 
-type ListTasksResponse struct {
-	Queued  []TaskInfo `json:"queued"`
-	Running []TaskInfo `json:"running"`
-}
-
-type TaskInfo struct {
-	ID    string `json:"id"`
-	Title string `json:"title"`
-}
-
-type ErrorResponse struct {
-	Error string `json:"error"`
-}
-
-// Task tracking
-var (
-	taskStatuses   = make(map[string]*taskStatus)
-	taskStatusesMu sync.RWMutex
-)
-
-type taskStatus struct {
-	ID          string
-	Status      string
-	Title       string
-	CreatedAt   time.Time
-	Error       string
-	Downloaded  atomic.Int64 // Use atomic for lock-free updates
-	Total       atomic.Int64 // Use atomic for lock-free updates
-	ProgressPct uint64       // Store as uint64 bits of float64 for atomic access
-}
-
-func handleHealth(w http.ResponseWriter, r *http.Request) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(http.StatusOK)
-	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-}
-
-func handleCreateTask(w http.ResponseWriter, r *http.Request) {
 	var req CreateTaskRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		respondError(w, "invalid request body", http.StatusBadRequest)
+		WriteError(w, http.StatusBadRequest, "invalid_request", "failed to decode request body: "+err.Error())
 		return
 	}
 
-	// Validate request
-	if req.TelegramURL == "" {
-		respondError(w, "telegram_url is required", http.StatusBadRequest)
-		return
-	}
-	if req.UserID <= 0 {
-		respondError(w, "user_id is required and must be positive", http.StatusBadRequest)
+	// 验证请求
+	if req.Type == "" {
+		WriteError(w, http.StatusBadRequest, "invalid_request", "task type is required")
 		return
 	}
 
-	logger := log.FromContext(r.Context()).WithPrefix("api")
+	if req.Storage == "" {
+		WriteError(w, http.StatusBadRequest, "invalid_request", "storage is required")
+		return
+	}
 
-	// Get user from database
-	userDB, err := database.GetUserByChatID(r.Context(), req.UserID)
+	// 创建任务
+	resp, err := h.factory.CreateTask(&req)
 	if err != nil {
-		logger.Errorf("Failed to get user: %v", err)
-		respondError(w, "user not found", http.StatusBadRequest)
+		WriteError(w, http.StatusBadRequest, "task_creation_failed", err.Error())
 		return
 	}
 
-	// Get storage
-	var stor storage.Storage
-	if req.StorageName != "" {
-		stor, err = storage.GetStorageByUserIDAndName(r.Context(), req.UserID, req.StorageName)
-		if err != nil {
-			logger.Errorf("Failed to get storage: %v", err)
-			respondError(w, "storage not found", http.StatusBadRequest)
-			return
-		}
-	} else {
-		// Use first available storage for the user
-		storages := storage.GetUserStorages(r.Context(), req.UserID)
-		if len(storages) == 0 {
-			respondError(w, "no storage available for user", http.StatusBadRequest)
-			return
-		}
-		stor = storages[0]
-	}
-
-	// Parse Telegram URL
-	botCtx := bot.ExtContext()
-	if botCtx == nil {
-		respondError(w, "bot not initialized", http.StatusInternalServerError)
-		return
-	}
-
-	linkUrl, err := url.Parse(req.TelegramURL)
-	if err != nil {
-		logger.Errorf("Failed to parse URL: %v", err)
-		respondError(w, "invalid telegram URL format", http.StatusBadRequest)
-		return
-	}
-
-	chatID, msgID, err := tgutil.ParseMessageLink(botCtx, req.TelegramURL)
-	if err != nil {
-		logger.Errorf("Failed to parse Telegram URL: %v", err)
-		respondError(w, "invalid telegram URL format", http.StatusBadRequest)
-		return
-	}
-
-	// Get message from Telegram
-	msg, err := tgutil.GetMessageByID(botCtx, chatID, msgID)
-	if err != nil {
-		logger.Errorf("Failed to get message: %v", err)
-		respondError(w, "failed to retrieve message", http.StatusBadRequest)
-		return
-	}
-
-	// Check if message has media
-	media, ok := msg.GetMedia()
-	if !ok {
-		respondError(w, "message has no media", http.StatusBadRequest)
-		return
-	}
-
-	// Collect files - handle both single and grouped messages
-	files := make([]tfile.TGFileMessage, 0)
-
-	// Check for grouped messages (media group)
-	groupID, isGroup := msg.GetGroupedID()
-	if isGroup && groupID != 0 && !linkUrl.Query().Has("single") {
-		// Handle media group
-		gmsgs, err := tgutil.GetGroupedMessages(botCtx, chatID, msg)
-		if err != nil {
-			logger.Errorf("Failed to get grouped messages: %v", err)
-			// Fall back to single message
-			file, err := createTGFileWithMedia(botCtx, msg, media, userDB)
-			if err != nil {
-				logger.Errorf("Failed to create TGFile: %v", err)
-				respondError(w, "invalid message format", http.StatusBadRequest)
-				return
-			}
-			files = append(files, file)
-		} else {
-			// Process all messages in the group
-			for _, gmsg := range gmsgs {
-				if gmsg.Media == nil {
-					continue
-				}
-				gMedia, ok := gmsg.GetMedia()
-				if !ok {
-					continue
-				}
-				file, err := createTGFileWithMedia(botCtx, gmsg, gMedia, userDB)
-				if err != nil {
-					logger.Warnf("Failed to create TGFile for grouped message: %v", err)
-					continue
-				}
-				files = append(files, file)
-			}
-		}
-	} else {
-		// Single message
-		file, err := createTGFileWithMedia(botCtx, msg, media, userDB)
-		if err != nil {
-			logger.Errorf("Failed to create TGFile: %v", err)
-			respondError(w, "invalid message format", http.StatusBadRequest)
-			return
-		}
-		files = append(files, file)
-	}
-
-	if len(files) == 0 {
-		respondError(w, "no savable files found", http.StatusBadRequest)
-		return
-	}
-
-	// Create tasks for all files with proper album handling
-	taskIDs := make([]string, 0, len(files))
-	baseDirPath := req.DirPath
-	if baseDirPath == "" {
-		baseDirPath = "/"
-	}
-
-	// Create context with bot extension
-	injectCtx := tgutil.ExtWithContext(r.Context(), botCtx)
-
-	// Apply storage rules if enabled for the user
-	useRule := userDB.ApplyRule && userDB.Rules != nil
-
-	// Helper to apply rules to a file
-	applyRule := func(file tfile.TGFileMessage) (storage.Storage, ruleutil.MatchedDirPath) {
-		fileStor := stor
-		dirPath := ruleutil.MatchedDirPath(baseDirPath)
-		
-		if useRule {
-			matched, matchedStorName, matchedDirPath := ruleutil.ApplyRule(injectCtx, userDB.Rules, ruleutil.NewInput(file))
-			if matched {
-				// Rule matched, apply overrides
-				if matchedDirPath != "" {
-					dirPath = matchedDirPath
-				}
-				if matchedStorName.Usable() {
-					var err error
-					fileStor, err = storage.GetStorageByUserIDAndName(injectCtx, userDB.ChatID, matchedStorName.String())
-					if err != nil {
-						logger.Errorf("Failed to get storage from rule: %v", err)
-						// Fall back to original storage
-						fileStor = stor
-					}
-				}
-			}
-		}
-		return fileStor, dirPath
-	}
-
-	// Separate files into regular and album files
-	type albumFile struct {
-		file    tfile.TGFileMessage
-		storage storage.Storage
-		dirPath ruleutil.MatchedDirPath
-	}
-	albumFiles := make(map[int64][]albumFile)
-	
-	for _, tgFile := range files {
-		fileStor, dirPath := applyRule(tgFile)
-		
-		// Check if this needs album handling (NEW-FOR-ALBUM rule)
-		if dirPath.NeedNewForAlbum() {
-			groupId, isGroup := tgFile.Message().GetGroupedID()
-			if !isGroup || groupId == 0 {
-				logger.Warnf("File %s has NEW-FOR-ALBUM rule but is not in a group, treating as regular file", tgFile.Name())
-				// Treat as regular file with base dir path
-				storagePath := fileStor.JoinStoragePath(path.Join(baseDirPath, tgFile.Name()))
-				taskID := xid.New().String()
-
-				task, err := tftask.NewTGFileTask(taskID, injectCtx, tgFile, fileStor, storagePath, &apiProgressTracker{
-					taskID: taskID,
-				})
-				if err != nil {
-					logger.Errorf("Failed to create task: %v", err)
-					respondError(w, "failed to create task", http.StatusInternalServerError)
-					return
-				}
-
-				trackTask(taskID, task.Title(), "queued")
-				if err := core.AddTask(injectCtx, task); err != nil {
-					logger.Errorf("Failed to add task: %v", err)
-					updateTaskStatus(taskID, "failed", err.Error())
-					respondError(w, "failed to add task to queue", http.StatusInternalServerError)
-					return
-				}
-
-				taskIDs = append(taskIDs, taskID)
-				continue
-			}
-			
-			// Group by album ID
-			if _, ok := albumFiles[groupId]; !ok {
-				albumFiles[groupId] = make([]albumFile, 0)
-			}
-			albumFiles[groupId] = append(albumFiles[groupId], albumFile{
-				file:    tgFile,
-				storage: fileStor,
-				dirPath: dirPath,
-			})
-		} else {
-			// Regular file - create task immediately
-			storagePath := fileStor.JoinStoragePath(path.Join(dirPath.String(), tgFile.Name()))
-			taskID := xid.New().String()
-
-			task, err := tftask.NewTGFileTask(taskID, injectCtx, tgFile, fileStor, storagePath, &apiProgressTracker{
-				taskID: taskID,
-			})
-			if err != nil {
-				logger.Errorf("Failed to create task: %v", err)
-				respondError(w, "failed to create task", http.StatusInternalServerError)
-				return
-			}
-
-			trackTask(taskID, task.Title(), "queued")
-			if err := core.AddTask(injectCtx, task); err != nil {
-				logger.Errorf("Failed to add task: %v", err)
-				updateTaskStatus(taskID, "failed", err.Error())
-				respondError(w, "failed to add task to queue", http.StatusInternalServerError)
-				return
-			}
-
-			taskIDs = append(taskIDs, taskID)
-		}
-	}
-
-	// Handle album files - group them into subdirectories
-	for _, afiles := range albumFiles {
-		if len(afiles) <= 1 {
-			// Single file in album, treat as regular
-			for _, af := range afiles {
-				storagePath := af.storage.JoinStoragePath(path.Join(baseDirPath, af.file.Name()))
-				taskID := xid.New().String()
-
-				task, err := tftask.NewTGFileTask(taskID, injectCtx, af.file, af.storage, storagePath, &apiProgressTracker{
-					taskID: taskID,
-				})
-				if err != nil {
-					logger.Errorf("Failed to create task: %v", err)
-					respondError(w, "failed to create task", http.StatusInternalServerError)
-					return
-				}
-
-				trackTask(taskID, task.Title(), "queued")
-				if err := core.AddTask(injectCtx, task); err != nil {
-					logger.Errorf("Failed to add task: %v", err)
-					updateTaskStatus(taskID, "failed", err.Error())
-					respondError(w, "failed to add task to queue", http.StatusInternalServerError)
-					return
-				}
-
-				taskIDs = append(taskIDs, taskID)
-			}
-			continue
-		}
-
-		// Multiple files in album - create subdirectory named after first file
-		// Remove extension from first file's name to use as directory name
-		albumDir := strings.TrimSuffix(path.Base(afiles[0].file.Name()), path.Ext(afiles[0].file.Name()))
-		albumStor := afiles[0].storage
-
-		for _, af := range afiles {
-			// All files go into the album subdirectory
-			storagePath := albumStor.JoinStoragePath(path.Join(baseDirPath, albumDir, af.file.Name()))
-			taskID := xid.New().String()
-
-			task, err := tftask.NewTGFileTask(taskID, injectCtx, af.file, albumStor, storagePath, &apiProgressTracker{
-				taskID: taskID,
-			})
-			if err != nil {
-				logger.Errorf("Failed to create task for album file: %v", err)
-				respondError(w, "failed to create task", http.StatusInternalServerError)
-				return
-			}
-
-			trackTask(taskID, task.Title(), "queued")
-			if err := core.AddTask(injectCtx, task); err != nil {
-				logger.Errorf("Failed to add task: %v", err)
-				updateTaskStatus(taskID, "failed", err.Error())
-				respondError(w, "failed to add task to queue", http.StatusInternalServerError)
-				return
-			}
-
-			taskIDs = append(taskIDs, taskID)
-		}
-	}
-
-	// Send success response
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(http.StatusCreated)
-
-	// Return first task ID for single file, or all task IDs for media group
-	if len(taskIDs) == 1 {
-		json.NewEncoder(w).Encode(CreateTaskResponse{
-			TaskID:  taskIDs[0],
-			Message: "task created successfully",
-		})
-	} else {
-		json.NewEncoder(w).Encode(map[string]interface{}{
-			"task_ids": taskIDs,
-			"message":  fmt.Sprintf("%d tasks created successfully", len(taskIDs)),
-		})
-	}
+	WriteJSON(w, http.StatusCreated, resp)
 }
 
-// createTGFileWithMedia creates a TGFile with proper filename handling using user's strategy
-func createTGFileWithMedia(botCtx *ext.Context, msg *tg.Message, media tg.MessageMediaClass, userDB *database.User) (tfile.TGFileMessage, error) {
-	// Use the same filename generation logic as bot handlers
-	opts := []tfile.TGFileOption{tfile.WithNameIfEmpty(tgutil.GenFileNameFromMessage(*msg))}
-	return tfile.FromMediaMessage(media, botCtx.Raw, msg, opts...)
-}
-
-func handleGetTask(w http.ResponseWriter, r *http.Request) {
-	taskID := r.PathValue("id")
-	if taskID == "" {
-		respondError(w, "task_id is required", http.StatusBadRequest)
+// ListTasksHandler 列出任务处理器
+func (h *Handlers) ListTasksHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only GET method is allowed")
 		return
 	}
 
-	taskStatusesMu.RLock()
-	status, exists := taskStatuses[taskID]
-	taskStatusesMu.RUnlock()
+	tasks := GetAllTasks()
+	response := make([]TaskInfoResponse, 0, len(tasks))
 
-	if !exists {
-		respondError(w, "task not found", http.StatusNotFound)
-		return
+	for _, task := range tasks {
+		info := convertTaskProgressToResponse(task)
+		response = append(response, info)
 	}
 
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(TaskStatusResponse{
-		TaskID:      status.ID,
-		Status:      status.Status,
-		Title:       status.Title,
-		CreatedAt:   status.CreatedAt,
-		Error:       status.Error,
-		Downloaded:  status.Downloaded.Load(),
-		Total:       status.Total.Load(),
-		ProgressPct: math.Float64frombits(atomic.LoadUint64((*uint64)(&status.ProgressPct))),
+	WriteJSON(w, http.StatusOK, TasksListResponse{
+		Tasks: response,
+		Total: len(response),
 	})
 }
 
-func handleListTasks(w http.ResponseWriter, r *http.Request) {
-	queued := core.GetQueuedTasks(r.Context())
-	running := core.GetRunningTasks(r.Context())
-
-	response := ListTasksResponse{
-		Queued:  convertTaskInfos(queued),
-		Running: convertTaskInfos(running),
+// GetTaskHandler 获取单个任务处理器
+func (h *Handlers) GetTaskHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only GET method is allowed")
+		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(response)
-}
-
-func handleCancelTask(w http.ResponseWriter, r *http.Request) {
-	taskID := r.PathValue("id")
+	taskID := extractTaskIDFromPath(r.URL.Path)
 	if taskID == "" {
-		respondError(w, "task_id is required", http.StatusBadRequest)
+		WriteError(w, http.StatusBadRequest, "invalid_request", "task ID is required")
 		return
 	}
 
+	task, ok := GetTask(taskID)
+	if !ok {
+		WriteError(w, http.StatusNotFound, "task_not_found", "task not found: "+taskID)
+		return
+	}
+
+	resp := convertTaskProgressToResponse(task)
+	WriteJSON(w, http.StatusOK, resp)
+}
+
+// CancelTaskHandler 取消任务处理器
+func (h *Handlers) CancelTaskHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodDelete {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only DELETE method is allowed")
+		return
+	}
+
+	taskID := extractTaskIDFromPath(r.URL.Path)
+	if taskID == "" {
+		WriteError(w, http.StatusBadRequest, "invalid_request", "task ID is required")
+		return
+	}
+
+	task, ok := GetTask(taskID)
+	if !ok {
+		WriteError(w, http.StatusNotFound, "task_not_found", "task not found: "+taskID)
+		return
+	}
+
+	// Cancel the task; the terminal status is set via the task event stream.
 	if err := core.CancelTask(r.Context(), taskID); err != nil {
-		log.FromContext(r.Context()).Errorf("Failed to cancel task %s: %v", taskID, err)
-		respondError(w, "failed to cancel task", http.StatusInternalServerError)
+		WriteError(w, http.StatusInternalServerError, "cancel_failed", "failed to cancel task: "+err.Error())
 		return
 	}
 
-	updateTaskStatus(taskID, "canceled", "")
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{"message": "task canceled"})
+	task.UpdateStatus(TaskStatusCancelled)
+	WriteJSON(w, http.StatusOK, map[string]string{"message": "task cancelled successfully"})
 }
 
-// Helper functions
+// ListStoragesHandler 列出存储处理器
+func (h *Handlers) ListStoragesHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only GET method is allowed")
+		return
+	}
 
-func respondError(w http.ResponseWriter, message string, statusCode int) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(statusCode)
-	json.NewEncoder(w).Encode(ErrorResponse{Error: message})
+	storages := make([]StorageInfo, 0, len(storage.Storages))
+	for name, stor := range storage.Storages {
+		storages = append(storages, StorageInfo{
+			Name: name,
+			Type: string(stor.Type()),
+		})
+	}
+
+	WriteJSON(w, http.StatusOK, StoragesResponse{Storages: storages})
 }
 
-func trackTask(taskID, title, status string) {
-	taskStatusesMu.Lock()
-	defer taskStatusesMu.Unlock()
-	taskStatuses[taskID] = &taskStatus{
-		ID:        taskID,
+// GetTaskTypesHandler 获取支持的任务类型
+func (h *Handlers) GetTaskTypesHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "only GET method is allowed")
+		return
+	}
+
+	types := []tasktype.TaskType{
+		tasktype.TaskTypeDirectlinks,
+		tasktype.TaskTypeYtdlp,
+		tasktype.TaskTypeAria2,
+		tasktype.TaskTypeParseditem,
+		tasktype.TaskTypeTgfiles,
+		tasktype.TaskTypeTphpics,
+		tasktype.TaskTypeTransfer,
+	}
+
+	WriteJSON(w, http.StatusOK, map[string]any{
+		"types": types,
+	})
+}
+
+// HealthCheckHandler 健康检查处理器
+func (h *Handlers) HealthCheckHandler(w http.ResponseWriter, r *http.Request) {
+	WriteJSON(w, http.StatusOK, map[string]string{
+		"status": "ok",
+	})
+}
+
+// extractTaskIDFromPath 从路径中提取任务 ID
+// 路径格式: /api/v1/tasks/:id
+func extractTaskIDFromPath(path string) string {
+	parts := strings.Split(strings.Trim(path, "/"), "/")
+	if len(parts) < 4 {
+		return ""
+	}
+	return parts[3]
+}
+
+// convertTaskProgressToResponse renders a task's current state, computing
+// percent and speed from the snapshot taken under the task's mutex.
+func convertTaskProgressToResponse(task *TaskProgressInfo) TaskInfoResponse {
+	status, total, downloaded, totalFiles, downloadedFiles, startedAt, errMsg, updatedAt := task.snapshot()
+
+	resp := TaskInfoResponse{
+		TaskID:    task.TaskID,
+		Type:      tasktype.TaskType(task.Type),
 		Status:    status,
-		Title:     title,
-		CreatedAt: time.Now(),
+		Title:     task.Title,
+		Storage:   task.Storage,
+		Path:      task.Path,
+		Error:     errMsg,
+		CreatedAt: task.CreatedAt,
+		UpdatedAt: updatedAt,
 	}
-}
 
-func updateTaskStatus(taskID, status, errorMsg string) {
-	taskStatusesMu.Lock()
-	defer taskStatusesMu.Unlock()
-	if ts, exists := taskStatuses[taskID]; exists {
-		ts.Status = status
-		ts.Error = errorMsg
+	var percent float64
+	var speedMBPS float64
+	if total > 0 {
+		percent = float64(downloaded) * 100 / float64(total)
+	} else if totalFiles > 0 {
+		percent = float64(downloadedFiles) * 100 / float64(totalFiles)
 	}
-}
-
-func convertTaskInfos(tasks []queue.TaskInfo) []TaskInfo {
-	result := make([]TaskInfo, len(tasks))
-	for i, t := range tasks {
-		result[i] = TaskInfo{
-			ID:    t.ID,
-			Title: t.Title,
+	if !startedAt.IsZero() {
+		elapsed := time.Since(startedAt).Seconds()
+		if elapsed > 0 {
+			speedMBPS = float64(downloaded) / elapsed / (1024 * 1024)
 		}
 	}
-	return result
-}
 
-// apiProgressTracker implements tftask.ProgressTracker for API tasks
-type apiProgressTracker struct {
-	taskID string
-}
-
-func (a *apiProgressTracker) OnStart(ctx context.Context, info tftask.TaskInfo) {
-	updateTaskStatus(a.taskID, "running", "")
-}
-
-func (a *apiProgressTracker) OnProgress(ctx context.Context, info tftask.TaskInfo, downloaded int64, total int64) {
-	// Use atomic operations to avoid mutex locks for better performance
-	// OnProgress is called very frequently during downloads
-	taskStatusesMu.RLock()
-	ts, exists := taskStatuses[a.taskID]
-	taskStatusesMu.RUnlock()
-	
-	if exists {
-		ts.Downloaded.Store(downloaded)
-		ts.Total.Store(total)
-		if total > 0 {
-			progressPct := float64(downloaded) / float64(total) * 100.0
-			atomic.StoreUint64((*uint64)(&ts.ProgressPct), math.Float64bits(progressPct))
+	if total > 0 || totalFiles > 0 {
+		resp.Progress = &TaskProgress{
+			TotalBytes:      total,
+			DownloadedBytes: downloaded,
+			TotalFiles:      totalFiles,
+			DownloadedFiles: downloadedFiles,
+			Percent:         percent,
+			SpeedMBPS:       speedMBPS,
 		}
 	}
+
+	return resp
 }
 
-func (a *apiProgressTracker) OnDone(ctx context.Context, info tftask.TaskInfo, err error) {
-	if err != nil {
-		updateTaskStatus(a.taskID, "failed", err.Error())
-		sendWebhook(a.taskID, "failed", err.Error())
-	} else {
-		updateTaskStatus(a.taskID, "completed", "")
-		sendWebhook(a.taskID, "completed", "")
-	}
+// NotFoundHandler 404 处理器
+func NotFoundHandler(w http.ResponseWriter, r *http.Request) {
+	WriteError(w, http.StatusNotFound, "not_found", "endpoint not found: "+r.URL.Path)
 }
 
-// sendWebhook sends a callback to the configured webhook URL
-func sendWebhook(taskID, status, errorMsg string) {
-	cfg := config.C()
-	if cfg.API.WebhookURL == "" {
-		return
-	}
-
-	taskStatusesMu.RLock()
-	ts, exists := taskStatuses[taskID]
-	taskStatusesMu.RUnlock()
-
-	if !exists {
-		return
-	}
-
-	logger := log.WithPrefix("webhook")
-
-	payload := TaskStatusResponse{
-		TaskID:      ts.ID,
-		Status:      status,
-		Title:       ts.Title,
-		CreatedAt:   ts.CreatedAt,
-		Error:       errorMsg,
-		Downloaded:  ts.Downloaded.Load(),
-		Total:       ts.Total.Load(),
-		ProgressPct: math.Float64frombits(atomic.LoadUint64((*uint64)(&ts.ProgressPct))),
-	}
-
-	body, err := json.Marshal(payload)
-	if err != nil {
-		logger.Errorf("Failed to marshal webhook payload: %v", err)
-		return
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, "POST", cfg.API.WebhookURL, bytes.NewReader(body))
-	if err != nil {
-		logger.Errorf("Failed to create webhook request: %v", err)
-		return
-	}
-
-	req.Header.Set("Content-Type", "application/json")
-	if cfg.API.Token != "" {
-		req.Header.Set("Authorization", "Bearer "+cfg.API.Token)
-	}
-
-	resp, err := http.DefaultClient.Do(req)
-	if err != nil {
-		logger.Errorf("Failed to send webhook: %v", err)
-		return
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode >= 400 {
-		body, err := io.ReadAll(resp.Body)
-		if err != nil {
-			logger.Errorf("Webhook returned error status %d, failed to read response body: %v", resp.StatusCode, err)
-		} else {
-			logger.Errorf("Webhook returned error status %d: %s", resp.StatusCode, string(body))
-		}
-	}
+// MethodNotAllowedHandler 405 处理器
+func MethodNotAllowedHandler(w http.ResponseWriter, r *http.Request) {
+	WriteError(w, http.StatusMethodNotAllowed, "method_not_allowed", "method not allowed: "+r.Method)
 }

api/handlers_test.go

@@ -0,0 +1,695 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
+)
+
+// setupTestServer creates a test server with handlers
+func setupTestServer(t *testing.T) (*Handlers, *TaskFactory) {
+	factory := NewTaskFactory(t.Context())
+	handlers := NewHandlers(factory)
+	return handlers, factory
+}
+
+// TestCreateTaskHandler tests the create task endpoint
+func TestCreateTaskHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	tests := []struct {
+		name       string
+		method     string
+		body       any
+		wantStatus int
+		wantErr    bool
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodGet,
+			body:       nil,
+			wantStatus: http.StatusMethodNotAllowed,
+			wantErr:    true,
+		},
+		{
+			name:       "Invalid JSON body",
+			method:     http.MethodPost,
+			body:       "invalid json",
+			wantStatus: http.StatusBadRequest,
+			wantErr:    true,
+		},
+		{
+			name:   "Empty request body",
+			method: http.MethodPost,
+			body:   CreateTaskRequest{},
+			// Will fail validation for missing type
+			wantStatus: http.StatusBadRequest,
+			wantErr:    true,
+		},
+		{
+			name:   "Missing type",
+			method: http.MethodPost,
+			body: CreateTaskRequest{
+				Storage: "test-storage",
+				Path:    "downloads",
+			},
+			wantStatus: http.StatusBadRequest,
+			wantErr:    true,
+		},
+		{
+			name:   "Missing storage",
+			method: http.MethodPost,
+			body: CreateTaskRequest{
+				Type: tasktype.TaskTypeDirectlinks,
+				Path: "downloads",
+			},
+			wantStatus: http.StatusBadRequest,
+			wantErr:    true,
+		},
+		{
+			name:   "Storage not found",
+			method: http.MethodPost,
+			body: CreateTaskRequest{
+				Type:    tasktype.TaskTypeDirectlinks,
+				Storage: "non-existent-storage",
+				Path:    "downloads",
+				Params:  json.RawMessage(`{"urls":["https://example.com/file.zip"]}`),
+			},
+			wantStatus: http.StatusBadRequest,
+			wantErr:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var bodyBytes []byte
+			var err error
+
+			if tt.body != nil {
+				switch v := tt.body.(type) {
+				case string:
+					bodyBytes = []byte(v)
+				default:
+					bodyBytes, err = json.Marshal(tt.body)
+					if err != nil {
+						t.Fatalf("failed to marshal body: %v", err)
+					}
+				}
+			}
+
+			req := httptest.NewRequest(tt.method, "/api/v1/tasks", bytes.NewReader(bodyBytes))
+			if tt.body != nil {
+				req.Header.Set("Content-Type", "application/json")
+			}
+
+			rr := httptest.NewRecorder()
+			handlers.CreateTaskHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+
+			if tt.wantErr {
+				var errResp ErrorResponse
+				if err := json.Unmarshal(rr.Body.Bytes(), &errResp); err != nil {
+					t.Errorf("expected error response, got: %s", rr.Body.String())
+				}
+			}
+		})
+	}
+}
+
+// TestListTasksHandler tests the list tasks endpoint
+func TestListTasksHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	tests := []struct {
+		name       string
+		method     string
+		wantStatus int
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodPost,
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "Success",
+			method:     http.MethodGet,
+			wantStatus: http.StatusOK,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(tt.method, "/api/v1/tasks", nil)
+			rr := httptest.NewRecorder()
+			handlers.ListTasksHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+
+			if tt.method == http.MethodGet {
+				var resp TasksListResponse
+				if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+					t.Errorf("failed to unmarshal response: %v", err)
+				}
+				if resp.Tasks == nil {
+					t.Error("expected non-nil tasks array")
+				}
+			}
+		})
+	}
+}
+
+// TestGetTaskHandler tests the get task endpoint
+func TestGetTaskHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	// Register a test task
+	testTaskID := "test-get-task"
+	RegisterTask(testTaskID, "directlinks", "local", "downloads", "Test", "")
+	defer DeleteTask(testTaskID)
+
+	tests := []struct {
+		name       string
+		method     string
+		path       string
+		wantStatus int
+		wantFound  bool
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodPost,
+			path:       "/api/v1/tasks/test-id",
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "Missing task ID",
+			method:     http.MethodGet,
+			path:       "/api/v1/tasks",
+			wantStatus: http.StatusBadRequest,
+		},
+		{
+			name:       "Task not found",
+			method:     http.MethodGet,
+			path:       "/api/v1/tasks/non-existent-task",
+			wantStatus: http.StatusNotFound,
+		},
+		{
+			name:       "Task found",
+			method:     http.MethodGet,
+			path:       "/api/v1/tasks/" + testTaskID,
+			wantStatus: http.StatusOK,
+			wantFound:  true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			rr := httptest.NewRecorder()
+			handlers.GetTaskHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+
+			if tt.wantFound {
+				var resp TaskInfoResponse
+				if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+					t.Errorf("failed to unmarshal response: %v", err)
+				}
+				if resp.TaskID != testTaskID {
+					t.Errorf("expected task ID %s, got %s", testTaskID, resp.TaskID)
+				}
+			}
+		})
+	}
+}
+
+// TestCancelTaskHandler tests the cancel task endpoint
+func TestCancelTaskHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	// Register a test task
+	testTaskID := "test-cancel-task"
+	RegisterTask(testTaskID, "directlinks", "local", "downloads", "Test", "")
+	defer DeleteTask(testTaskID)
+
+	tests := []struct {
+		name       string
+		method     string
+		path       string
+		wantStatus int
+		skipCore   bool // Skip if core is not initialized
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodGet,
+			path:       "/api/v1/tasks/test-id",
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "Missing task ID",
+			method:     http.MethodDelete,
+			path:       "/api/v1/tasks",
+			wantStatus: http.StatusBadRequest,
+		},
+		{
+			name:       "Task not found",
+			method:     http.MethodDelete,
+			path:       "/api/v1/tasks/non-existent-task",
+			wantStatus: http.StatusNotFound,
+		},
+		{
+			name:       "Cancel task",
+			method:     http.MethodDelete,
+			path:       "/api/v1/tasks/" + testTaskID,
+			wantStatus: http.StatusOK,
+			skipCore:   true, // Requires initialized core task queue
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.skipCore {
+				t.Skip("Skipping test: requires initialized core")
+			}
+
+			req := httptest.NewRequest(tt.method, tt.path, nil)
+			rr := httptest.NewRecorder()
+			handlers.CancelTaskHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+		})
+	}
+}
+
+// TestListStoragesHandler tests the list storages endpoint
+func TestListStoragesHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	tests := []struct {
+		name       string
+		method     string
+		wantStatus int
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodPost,
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "Success",
+			method:     http.MethodGet,
+			wantStatus: http.StatusOK,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(tt.method, "/api/v1/storages", nil)
+			rr := httptest.NewRecorder()
+			handlers.ListStoragesHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+
+			if tt.method == http.MethodGet {
+				var resp StoragesResponse
+				if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+					t.Errorf("failed to unmarshal response: %v", err)
+				}
+				if resp.Storages == nil {
+					t.Error("expected non-nil storages array")
+				}
+			}
+		})
+	}
+}
+
+// TestConcurrentProgressStore tests concurrent access to progress store
+func TestConcurrentProgressStore(t *testing.T) {
+	// Clear store before test
+	t.Cleanup(func() {
+		tasks := GetAllTasks()
+		for _, task := range tasks {
+			if strings.HasPrefix(task.TaskID, "concurrent-test-") {
+				DeleteTask(task.TaskID)
+			}
+		}
+	})
+
+	var wg sync.WaitGroup
+	numGoroutines := 100
+
+	// Concurrent registrations
+	for i := range numGoroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			taskID := fmt.Sprintf("concurrent-test-%d", id)
+			RegisterTask(taskID, "directlinks", "local", "downloads", "Test", "")
+		}(i)
+	}
+
+	// Concurrent reads
+	for i := range numGoroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			taskID := fmt.Sprintf("concurrent-test-%d", id)
+			GetTask(taskID)
+		}(i)
+	}
+
+	// Concurrent updates
+	for i := range numGoroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			taskID := fmt.Sprintf("concurrent-test-%d", id)
+			info, ok := GetTask(taskID)
+			if ok {
+				info.UpdateStatus(TaskStatusRunning)
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	// Verify all tasks exist
+	for i := range numGoroutines {
+		taskID := fmt.Sprintf("concurrent-test-%d", i)
+		if _, ok := GetTask(taskID); !ok {
+			t.Errorf("task %s not found after concurrent operations", taskID)
+		}
+	}
+}
+
+// TestProgressTrackerConcurrentUpdates tests concurrent progress updates
+func TestProgressTrackerConcurrentUpdates(t *testing.T) {
+	info := RegisterTask("concurrent-progress", "directlinks", "local", "downloads", "Test", "")
+	info.Emit(taskevent.Event{TaskID: "concurrent-progress", Phase: taskevent.PhaseStart, TotalBytes: 10000})
+
+	var wg sync.WaitGroup
+	numGoroutines := 50
+	updatesPerGoroutine := 100
+
+	// Concurrent progress updates via the Sink interface
+	for i := range numGoroutines {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := range updatesPerGoroutine {
+				info.Emit(taskevent.Event{
+					TaskID:          "concurrent-progress",
+					Phase:           taskevent.PhaseProgress,
+					DownloadedBytes: int64(id*updatesPerGoroutine + j),
+					TotalBytes:      10000,
+				})
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	status, _, downloaded, _, _, _, _, _ := info.snapshot()
+	if status != TaskStatusRunning {
+		t.Errorf("expected status Running after concurrent updates, got %s", status)
+	}
+	if downloaded <= 0 {
+		t.Errorf("expected downloaded bytes > 0 after concurrent updates, got %d", downloaded)
+	}
+}
+
+// TestTaskFactoryValidation tests TaskFactory parameter validation
+func TestTaskFactoryValidation(t *testing.T) {
+	factory := NewTaskFactory(context.Background())
+
+	tests := []struct {
+		name    string
+		request *CreateTaskRequest
+		wantErr bool
+		errMsg  string
+	}{
+		{
+			name: "Storage not found",
+			request: &CreateTaskRequest{
+				Type:    tasktype.TaskTypeDirectlinks,
+				Storage: "non-existent",
+				Path:    "downloads",
+				Params:  json.RawMessage(`{"urls":["https://example.com/file.zip"]}`),
+			},
+			wantErr: true,
+			errMsg:  "storage not found",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := factory.CreateTask(tt.request)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("CreateTask() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if err != nil && tt.errMsg != "" {
+				if !strings.Contains(strings.ToLower(err.Error()), tt.errMsg) {
+					t.Errorf("error message %q does not contain %q", err.Error(), tt.errMsg)
+				}
+			}
+		})
+	}
+}
+
+// TestEdgeCases tests various edge cases
+func TestEdgeCases(t *testing.T) {
+	tests := []struct {
+		name string
+		fn   func(t *testing.T)
+	}{
+		{
+			name: "Empty request body",
+			fn: func(t *testing.T) {
+				handlers, _ := setupTestServer(t)
+				req := httptest.NewRequest(http.MethodPost, "/api/v1/tasks", nil)
+				rr := httptest.NewRecorder()
+				handlers.CreateTaskHandler(rr, req)
+				if rr.Code != http.StatusBadRequest {
+					t.Errorf("expected %d, got %d", http.StatusBadRequest, rr.Code)
+				}
+			},
+		},
+		{
+			name: "Very long task ID in path",
+			fn: func(t *testing.T) {
+				handlers, _ := setupTestServer(t)
+				longID := strings.Repeat("a", 1000)
+				req := httptest.NewRequest(http.MethodGet, "/api/v1/tasks/"+longID, nil)
+				rr := httptest.NewRecorder()
+				handlers.GetTaskHandler(rr, req)
+				if rr.Code != http.StatusNotFound {
+					t.Errorf("expected %d, got %d", http.StatusNotFound, rr.Code)
+				}
+			},
+		},
+		{
+			name: "Path with special characters",
+			fn: func(t *testing.T) {
+				path := "/api/v1/tasks/test%20id/with/slashes"
+				got := extractTaskIDFromPath(path)
+				expected := "test%20id"
+				if got != expected {
+					t.Errorf("expected %q, got %q", expected, got)
+				}
+			},
+		},
+		{
+			name: "Double slashes in path",
+			fn: func(t *testing.T) {
+				path := "/api/v1/tasks//task-id"
+				got := extractTaskIDFromPath(path)
+				expected := ""
+				if got != expected {
+					t.Errorf("expected %q, got %q", expected, got)
+				}
+			},
+		},
+		{
+			name: "Progress tracker with empty webhook",
+			fn: func(t *testing.T) {
+				info := RegisterTask("test-empty-webhook", "type", "storage", "path", "title", "")
+				if info.Webhook != "" {
+					t.Error("expected empty webhook")
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, tt.fn)
+	}
+}
+
+// TestHealthCheckHandler tests the health check endpoint
+func TestHealthCheckHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rr := httptest.NewRecorder()
+	handlers.HealthCheckHandler(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Errorf("expected status %d, got %d", http.StatusOK, rr.Code)
+	}
+
+	var resp map[string]string
+	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal response: %v", err)
+	}
+
+	if resp["status"] != "ok" {
+		t.Errorf("expected status 'ok', got %q", resp["status"])
+	}
+}
+
+// TestGetTaskTypesHandler tests the task types endpoint
+func TestGetTaskTypesHandler(t *testing.T) {
+	handlers, _ := setupTestServer(t)
+
+	tests := []struct {
+		name       string
+		method     string
+		wantStatus int
+	}{
+		{
+			name:       "Method not allowed",
+			method:     http.MethodPost,
+			wantStatus: http.StatusMethodNotAllowed,
+		},
+		{
+			name:       "Success",
+			method:     http.MethodGet,
+			wantStatus: http.StatusOK,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := httptest.NewRequest(tt.method, "/api/v1/task-types", nil)
+			rr := httptest.NewRecorder()
+			handlers.GetTaskTypesHandler(rr, req)
+
+			if rr.Code != tt.wantStatus {
+				t.Errorf("expected status %d, got %d", tt.wantStatus, rr.Code)
+			}
+
+			if tt.method == http.MethodGet {
+				var resp map[string]any
+				if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+					t.Errorf("failed to unmarshal response: %v", err)
+				}
+				if _, ok := resp["types"]; !ok {
+					t.Error("expected 'types' field in response")
+				}
+			}
+		})
+	}
+}
+
+// TestNotFoundHandler tests the 404 handler
+func TestNotFoundHandler(t *testing.T) {
+	req := httptest.NewRequest(http.MethodGet, "/non-existent-path", nil)
+	rr := httptest.NewRecorder()
+	NotFoundHandler(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Errorf("expected status %d, got %d", http.StatusNotFound, rr.Code)
+	}
+
+	var resp ErrorResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal response: %v", err)
+	}
+
+	if resp.Error != "not_found" {
+		t.Errorf("expected error 'not_found', got %q", resp.Error)
+	}
+}
+
+// TestMethodNotAllowedHandler tests the 405 handler
+func TestMethodNotAllowedHandler(t *testing.T) {
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tasks", nil)
+	rr := httptest.NewRecorder()
+	MethodNotAllowedHandler(rr, req)
+
+	if rr.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, rr.Code)
+	}
+
+	var resp ErrorResponse
+	if err := json.Unmarshal(rr.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal response: %v", err)
+	}
+
+	if resp.Error != "method_not_allowed" {
+		t.Errorf("expected error 'method_not_allowed', got %q", resp.Error)
+	}
+}
+
+// TestTaskProgressInfoTimeUpdate tests that timestamps are updated correctly
+func TestTaskProgressInfoTimeUpdate(t *testing.T) {
+	info := RegisterTask("time-test", "directlinks", "local", "downloads", "Test", "")
+	defer DeleteTask("time-test")
+
+	originalTime := info.UpdatedAt
+	time.Sleep(10 * time.Millisecond) // Ensure time difference
+
+	info.UpdateStatus(TaskStatusRunning)
+	if !info.UpdatedAt.After(originalTime) {
+		t.Error("expected UpdatedAt to be updated")
+	}
+}
+
+// TestWebhookPayloadWithNilCompletedAt tests webhook payload with nil completed_at
+func TestWebhookPayloadWithNilCompletedAt(t *testing.T) {
+	payload := WebhookPayload{
+		TaskID:      "test-id",
+		Type:        "directlinks",
+		Status:      TaskStatusRunning,
+		Storage:     "local",
+		Path:        "downloads/file.zip",
+		CompletedAt: nil,
+		Error:       "",
+	}
+
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal: %v", err)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("failed to unmarshal: %v", err)
+	}
+
+	// completed_at should be omitted when nil
+	if _, ok := decoded["completed_at"]; ok {
+		t.Error("expected completed_at to be omitted when nil")
+	}
+}

api/middleware.go

@@ -1,66 +0,0 @@
-package api
-
-import (
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/charmbracelet/log"
-	"github.com/krau/SaveAny-Bot/config"
-)
-
-// authMiddleware validates API token
-func authMiddleware(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		// Skip auth for health check
-		if r.URL.Path == "/health" {
-			next.ServeHTTP(w, r)
-			return
-		}
-
-		cfg := config.C()
-
-		// Check token if configured
-		if cfg.API.Token != "" {
-			authHeader := r.Header.Get("Authorization")
-			if authHeader == "" {
-				http.Error(w, `{"error":"unauthorized: missing token"}`, http.StatusUnauthorized)
-				return
-			}
-
-			token := strings.TrimPrefix(authHeader, "Bearer ")
-			if token != cfg.API.Token {
-				http.Error(w, `{"error":"unauthorized: invalid token"}`, http.StatusUnauthorized)
-				return
-			}
-		}
-
-		next.ServeHTTP(w, r)
-	})
-}
-
-// loggingMiddleware logs HTTP requests
-func loggingMiddleware(logger *log.Logger) func(http.Handler) http.Handler {
-	return func(next http.Handler) http.Handler {
-		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			start := time.Now()
-
-			// Wrap response writer to capture status code
-			wrapper := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
-
-			next.ServeHTTP(wrapper, r)
-
-			logger.Infof("%s %s %d %s", r.Method, r.URL.Path, wrapper.statusCode, time.Since(start))
-		})
-	}
-}
-
-type responseWriter struct {
-	http.ResponseWriter
-	statusCode int
-}
-
-func (rw *responseWriter) WriteHeader(code int) {
-	rw.statusCode = code
-	rw.ResponseWriter.WriteHeader(code)
-}

api/middleware_test.go

@@ -1,47 +0,0 @@
-package api
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"testing"
-)
-
-func TestAuthMiddleware_NoAuth(t *testing.T) {
-	// Create a test handler
-	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		w.Write([]byte("OK"))
-	})
-
-	// Create request
-	req := httptest.NewRequest("GET", "/api/v1/tasks", nil)
-	rec := httptest.NewRecorder()
-
-	// Apply middleware
-	authMiddleware(handler).ServeHTTP(rec, req)
-
-	// When no token is configured, request should succeed or be unauthorized
-	if rec.Code != http.StatusOK && rec.Code != http.StatusUnauthorized {
-		t.Errorf("Expected status 200 or 401, got %d", rec.Code)
-	}
-}
-
-func TestAuthMiddleware_HealthCheck(t *testing.T) {
-	// Create a test handler
-	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		w.Write([]byte("OK"))
-	})
-
-	// Create request to health endpoint
-	req := httptest.NewRequest("GET", "/health", nil)
-	rec := httptest.NewRecorder()
-
-	// Apply middleware
-	authMiddleware(handler).ServeHTTP(rec, req)
-
-	// Health check should always work without auth
-	if rec.Code != http.StatusOK {
-		t.Errorf("Expected status 200 for health check, got %d", rec.Code)
-	}
-}

api/progress.go

@@ -0,0 +1,216 @@
+package api
+
+import (
+	"sync"
+	"time"
+
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
+)
+
+// TaskProgressInfo stores the progress of an API-submitted task. All fields are
+// guarded by mu. It implements taskevent.Sink so the task layer can update it
+// without knowing about the API.
+type TaskProgressInfo struct {
+	mu              sync.Mutex
+	TaskID          string
+	Type            string
+	Status          TaskStatus
+	Title           string
+	TotalBytes      int64
+	DownloadedBytes int64
+	TotalFiles      int
+	DownloadedFiles int
+	Storage         string
+	Path            string
+	Error           string
+	CreatedAt       time.Time
+	UpdatedAt       time.Time
+	StartedAt       time.Time
+	Webhook         string
+	webhookNotified bool
+}
+
+// progressStore holds all API tasks. Entries are removed a fixed duration after
+// they reach a terminal state to bound memory usage.
+type progressStore struct {
+	mu        sync.RWMutex
+	tasks     map[string]*TaskProgressInfo
+	retention time.Duration
+}
+
+var store = &progressStore{
+	tasks:     make(map[string]*TaskProgressInfo),
+	retention: 24 * time.Hour,
+}
+
+// RegisterTask registers a new API task and returns its progress info.
+func RegisterTask(taskID, taskType, storage, path, title, webhook string) *TaskProgressInfo {
+	info := &TaskProgressInfo{
+		TaskID:    taskID,
+		Type:      taskType,
+		Status:    TaskStatusQueued,
+		Title:     title,
+		Storage:   storage,
+		Path:      path,
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+		Webhook:   webhook,
+	}
+
+	store.mu.Lock()
+	store.tasks[taskID] = info
+	store.mu.Unlock()
+
+	return info
+}
+
+// GetTask returns the progress info for a task.
+func GetTask(taskID string) (*TaskProgressInfo, bool) {
+	store.mu.RLock()
+	defer store.mu.RUnlock()
+	info, ok := store.tasks[taskID]
+	return info, ok
+}
+
+// GetAllTasks returns all tracked tasks.
+func GetAllTasks() []*TaskProgressInfo {
+	store.mu.RLock()
+	defer store.mu.RUnlock()
+
+	tasks := make([]*TaskProgressInfo, 0, len(store.tasks))
+	for _, info := range store.tasks {
+		tasks = append(tasks, info)
+	}
+	return tasks
+}
+
+// DeleteTask removes a task record.
+func DeleteTask(taskID string) {
+	store.mu.Lock()
+	defer store.mu.Unlock()
+	delete(store.tasks, taskID)
+}
+
+// CleanupExpired removes tasks that reached a terminal state more than the
+// store's retention duration ago. It is safe to call periodically.
+func CleanupExpired() {
+	now := time.Now()
+	store.mu.Lock()
+	defer store.mu.Unlock()
+	for id, info := range store.tasks {
+		info.mu.Lock()
+		terminal := info.Status == TaskStatusCompleted || info.Status == TaskStatusFailed || info.Status == TaskStatusCancelled
+		stale := terminal && now.Sub(info.UpdatedAt) > store.retention
+		info.mu.Unlock()
+		if stale {
+			delete(store.tasks, id)
+		}
+	}
+}
+
+// StartCleanupLoop runs CleanupExpired on a fixed interval until ctx is done.
+// It should be started once during API server initialization.
+func StartCleanupLoop(ctx interface{ Done() <-chan struct{} }) {
+	go func() {
+		ticker := time.NewTicker(10 * time.Minute)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				CleanupExpired()
+			}
+		}
+	}()
+}
+
+// UpdateStatus sets the task status.
+func (t *TaskProgressInfo) UpdateStatus(status TaskStatus) {
+	t.mu.Lock()
+	t.Status = status
+	t.UpdatedAt = time.Now()
+	if status == TaskStatusRunning && t.StartedAt.IsZero() {
+		t.StartedAt = t.UpdatedAt
+	}
+	t.mu.Unlock()
+}
+
+// SetError marks the task failed with an error message.
+func (t *TaskProgressInfo) SetError(err string) {
+	t.mu.Lock()
+	t.Error = err
+	t.Status = TaskStatusFailed
+	t.UpdatedAt = time.Now()
+	t.mu.Unlock()
+}
+
+// snapshot returns a point-in-time copy of the fields needed to render a
+// response, so callers never touch the mutex directly.
+func (t *TaskProgressInfo) snapshot() (status TaskStatus, total, downloaded int64, totalFiles, downloadedFiles int, startedAt time.Time, err string, updatedAt time.Time) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.Status, t.TotalBytes, t.DownloadedBytes, t.TotalFiles, t.DownloadedFiles, t.StartedAt, t.Error, t.UpdatedAt
+}
+
+// Emit implements taskevent.Sink. It translates task lifecycle events into
+// status/progress updates and fires the webhook on terminal transitions.
+func (t *TaskProgressInfo) Emit(e taskevent.Event) {
+	t.mu.Lock()
+	switch e.Phase {
+	case taskevent.PhaseStart:
+		t.Status = TaskStatusRunning
+		if t.StartedAt.IsZero() {
+			t.StartedAt = time.Now()
+		}
+		if e.TotalBytes > 0 {
+			t.TotalBytes = e.TotalBytes
+		}
+	case taskevent.PhaseProgress:
+		t.Status = TaskStatusRunning
+		if e.TotalBytes > 0 {
+			t.TotalBytes = e.TotalBytes
+		}
+		t.DownloadedBytes = e.DownloadedBytes
+		if e.TotalFiles > 0 {
+			t.TotalFiles = e.TotalFiles
+		}
+		if e.DownloadedFiles > 0 {
+			t.DownloadedFiles = e.DownloadedFiles
+		}
+	case taskevent.PhaseDone:
+		if e.Err != nil {
+			t.Status = TaskStatusFailed
+			t.Error = e.Err.Error()
+		} else {
+			t.Status = TaskStatusCompleted
+		}
+	}
+	t.UpdatedAt = time.Now()
+	notify := t.Webhook != "" && !t.webhookNotified && (t.Status == TaskStatusCompleted || t.Status == TaskStatusFailed)
+	if notify {
+		t.webhookNotified = true
+	}
+	t.mu.Unlock()
+
+	if notify {
+		payload := CreateWebhookPayload(t.TaskID, t.Type, t.Status, t.Storage, t.Path, e.Err)
+		SendWebhook(nil, payload)
+	}
+}
+
+// ProgressTracker is retained for compatibility but is no longer the primary
+// progress path; taskevent drives updates now. These methods are safe no-ops
+// when called on a nil receiver.
+type ProgressTracker struct{}
+
+func NewProgressTracker(taskID, taskType, storage, path, title, webhook string) *ProgressTracker {
+	return &ProgressTracker{}
+}
+
+func (p *ProgressTracker) OnStart(totalBytes int64, totalFiles int)              {}
+func (p *ProgressTracker) OnProgress(downloadedBytes int64, downloadedFiles int) {}
+func (p *ProgressTracker) OnDone(err error)                                      {}
+func (p *ProgressTracker) GetInfo() *TaskProgressInfo                            { return nil }
+func (p *ProgressTracker) UpdateProgressBytes(bytes int64)                       {}
+func (p *ProgressTracker) UpdateProgressFiles(files int)                         {}

api/server.go

@@ -10,68 +10,161 @@ import (
 	"github.com/krau/SaveAny-Bot/config"
 )
 
-var server *http.Server
+// Server API 服务器
+type Server struct {
+	httpServer *http.Server
+	factory    *TaskFactory
+}
 
-// Init initializes and starts the HTTP API server
-func Init(ctx context.Context) error {
-	cfg := config.C()
-	if !cfg.API.Enable {
-		return nil
-	}
+// NewServer 创建新的 API 服务器
+func NewServer(ctx context.Context) *Server {
+	cfg := config.C().API
 
-	// Validate that token is configured when API is enabled
-	if cfg.API.Token == "" {
-		return fmt.Errorf("API is enabled but token is not configured. Please set 'api.token' in your configuration file for security")
-	}
-
-	logger := log.FromContext(ctx).WithPrefix("api")
+	factory := NewTaskFactory(ctx)
+	handlers := NewHandlers(factory)
 
+	// 设置路由
 	mux := http.NewServeMux()
 
-	// Register API routes
-	registerRoutes(mux)
+	// 健康检查
+	mux.HandleFunc("/health", handlers.HealthCheckHandler)
 
-	// Wrap with middleware
-	handler := loggingMiddleware(logger)(authMiddleware(mux))
+	// API v1 路由
+	mux.HandleFunc("/api/v1/tasks", func(w http.ResponseWriter, r *http.Request) {
+		switch r.Method {
+		case http.MethodGet:
+			handlers.ListTasksHandler(w, r)
+		case http.MethodPost:
+			handlers.CreateTaskHandler(w, r)
+		default:
+			MethodNotAllowedHandler(w, r)
+		}
+	})
+	mux.HandleFunc("/api/v1/tasks/", func(w http.ResponseWriter, r *http.Request) {
+		// 根据方法和路径分发
+		switch r.Method {
+		case http.MethodGet:
+			handlers.GetTaskHandler(w, r)
+		case http.MethodDelete:
+			handlers.CancelTaskHandler(w, r)
+		default:
+			MethodNotAllowedHandler(w, r)
+		}
+	})
+	mux.HandleFunc("/api/v1/storages", handlers.ListStoragesHandler)
+	mux.HandleFunc("/api/v1/task-types", handlers.GetTaskTypesHandler)
 
-	server = &http.Server{
-		Addr:         fmt.Sprintf(":%d", cfg.API.Port),
-		Handler:      handler,
-		ReadTimeout:  15 * time.Second,
-		WriteTimeout: 15 * time.Second,
-		IdleTimeout:  60 * time.Second,
+	// 404 处理
+	mux.HandleFunc("/", NotFoundHandler)
+
+	// Apply middleware chain.
+	var handler http.Handler = mux
+
+	// Apply auth middleware when a token is configured.
+	token := cfg.Token
+	if token != "" {
+		handler = AuthMiddleware()(handler)
 	}
 
+	// Add logging middleware.
+	handler = loggingMiddleware(handler)
+
+	// Add recovery middleware.
+	handler = recoveryMiddleware(handler)
+
+	return &Server{
+		httpServer: &http.Server{
+			Addr:         fmt.Sprintf("%s:%d", cfg.Host, cfg.Port),
+			Handler:      handler,
+			ReadTimeout:  30 * time.Second,
+			WriteTimeout: 30 * time.Second,
+			IdleTimeout:  120 * time.Second,
+		},
+		factory: factory,
+	}
+}
+
+// Start 启动服务器
+func (s *Server) Start(ctx context.Context) error {
+	logger := log.FromContext(ctx).With("module", "api")
+
+	logger.Infof("Starting API server on %s", s.httpServer.Addr)
+
+	// 在 goroutine 中启动服务器
 	go func() {
-		logger.Infof("Starting API server on port %d", cfg.API.Port)
-		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+		if err := s.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			logger.Errorf("API server error: %v", err)
 		}
 	}()
 
-	// Graceful shutdown on context cancellation
+	// 监听 context 取消
 	go func() {
 		<-ctx.Done()
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 		defer cancel()
-
-		if err := server.Shutdown(shutdownCtx); err != nil {
-			logger.Errorf("Failed to shutdown API server: %v", err)
-		} else {
-			logger.Info("API server stopped")
+		if err := s.httpServer.Shutdown(shutdownCtx); err != nil {
+			logger.Errorf("API server shutdown error: %v", err)
 		}
 	}()
 
 	return nil
 }
 
-func registerRoutes(mux *http.ServeMux) {
-	// Health check endpoint (no auth required)
-	mux.HandleFunc("/health", handleHealth)
+// loggingMiddleware 日志中间件
+func loggingMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
 
-	// API v1 endpoints
-	mux.HandleFunc("POST /api/v1/tasks", handleCreateTask)
-	mux.HandleFunc("GET /api/v1/tasks/{id}", handleGetTask)
-	mux.HandleFunc("GET /api/v1/tasks", handleListTasks)
-	mux.HandleFunc("DELETE /api/v1/tasks/{id}", handleCancelTask)
+		// 包装 ResponseWriter 以获取状态码
+		wrapped := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
+
+		next.ServeHTTP(wrapped, r)
+
+		log.Infof("%s %s %d %s", r.Method, r.URL.Path, wrapped.statusCode, time.Since(start))
+	})
+}
+
+// recoveryMiddleware 恢复中间件
+func recoveryMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if err := recover(); err != nil {
+				log.Errorf("Panic recovered: %v", err)
+				WriteError(w, http.StatusInternalServerError, "internal_error", "internal server error")
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
+
+// responseWriter 包装 http.ResponseWriter 以捕获状态码
+type responseWriter struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	rw.ResponseWriter.WriteHeader(code)
+}
+
+// Start initializes and starts the API server. It refuses to start without a
+// token, since an open download proxy is a security risk.
+func Start(ctx context.Context) error {
+	cfg := config.C().API
+
+	if !cfg.Enable {
+		return nil
+	}
+
+	if cfg.Token == "" {
+		return fmt.Errorf("API server is enabled but no token is set; refusing to start insecurely")
+	}
+
+	server := NewServer(ctx)
+	if err := server.Start(ctx); err != nil {
+		return err
+	}
+	StartCleanupLoop(ctx)
+	return nil
 }

api/tgfiles.go

@@ -0,0 +1,283 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/celestix/gotgproto/ext"
+	"github.com/charmbracelet/log"
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/client/bot"
+	userclient "github.com/krau/SaveAny-Bot/client/user"
+	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
+	"github.com/krau/SaveAny-Bot/pkg/tfile"
+)
+
+// MessageContext 保存消息和获取它所用的 context
+type MessageContext struct {
+	Message *tg.Message
+	Client  *ext.Context
+}
+
+// getClientContext 获取可用的客户端上下文
+// 优先使用 Bot，失败后回退到 Userbot
+func getClientContext() (*ext.Context, error) {
+	// 首先尝试获取 Bot context
+	if botCtx := bot.ExtContext(); botCtx != nil {
+		return botCtx, nil
+	}
+
+	// 回退到 Userbot
+	if uc := userclient.GetCtx(); uc != nil {
+		return uc, nil
+	}
+
+	return nil, fmt.Errorf("no client available (bot and userbot are not initialized)")
+}
+
+// resolveChatID 解析聊天 ID
+func resolveChatID(_ context.Context, idOrUsername string) (int64, error) {
+	// 如果是数字 ID
+	if id, err := strconv.ParseInt(idOrUsername, 10, 64); err == nil {
+		// 私有频道 ID 需要加上 -100 前缀
+		if id > 0 {
+			return -1000000000000 - id, nil
+		}
+		return id, nil
+	}
+
+	// 获取可用的客户端上下文
+	clientCtx, err := getClientContext()
+	if err != nil {
+		return 0, err
+	}
+
+	// 使用 tgutil 的 ParseChatID
+	return tgutil.ParseChatID(clientCtx, idOrUsername)
+}
+
+// ParseMessageLink 解析 Telegram 消息链接
+// 支持的域名: t.me, telegram.me
+// 支持格式:
+// - https://t.me/username/123
+// - https://t.me/c/123456789/123
+// - https://t.me/c/123456789/111/456 (topic id)
+// - https://t.me/username/123?comment=2 (评论)
+func ParseMessageLink(ctx context.Context, link string) (int64, int, error) {
+	u, err := url.Parse(link)
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid URL: %w", err)
+	}
+	paths := strings.Split(strings.TrimPrefix(u.Path, "/"), "/")
+
+	if cmt := u.Query().Get("comment"); cmt != "" {
+		// 频道评论的消息链接
+		if len(paths) < 1 {
+			return 0, 0, fmt.Errorf("invalid message link format: %s", link)
+		}
+		// 简化处理：返回错误，提示不支持评论链接
+		return 0, 0, fmt.Errorf("comment links are not supported")
+	}
+
+	switch len(paths) {
+	case 2: // https://t.me/username/123
+		chatID, err := resolveChatID(ctx, paths[0])
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to resolve chat ID: %w", err)
+		}
+		msgID, err := strconv.Atoi(paths[1])
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to parse message ID: %w", err)
+		}
+		return chatID, msgID, nil
+	case 3:
+		// https://t.me/c/123456789/123
+		// https://t.me/username/123/456 , 123: topic id
+		chatPart, msgPart := paths[1], paths[2]
+		if paths[0] != "c" {
+			chatPart = paths[0]
+		}
+		chatID, err := resolveChatID(ctx, chatPart)
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to resolve chat ID: %w", err)
+		}
+		msgID, err := strconv.Atoi(msgPart)
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to parse message ID: %w", err)
+		}
+		return chatID, msgID, nil
+	case 4:
+		// https://t.me/c/123456789/111/456 111: topic id
+		if paths[0] != "c" {
+			return 0, 0, fmt.Errorf("invalid message link format: %s", link)
+		}
+		chatID, err := resolveChatID(ctx, paths[1])
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to resolve chat ID: %w", err)
+		}
+		msgID, err := strconv.Atoi(paths[3])
+		if err != nil {
+			return 0, 0, fmt.Errorf("failed to parse message ID: %w", err)
+		}
+		return chatID, msgID, nil
+	}
+	return 0, 0, fmt.Errorf("invalid message link format: %s", link)
+}
+
+// getMessageWithContext 通过 ID 获取消息，返回消息和使用的 context
+// 确保消息获取和后续文件创建使用同一个 context
+func getMessageWithContext(_ context.Context, chatID int64, msgID int) (*MessageContext, error) {
+	// 首先尝试使用 Bot
+	if botCtx := bot.ExtContext(); botCtx != nil {
+		msg, err := tgutil.GetMessageByID(botCtx, chatID, msgID)
+		if err == nil {
+			return &MessageContext{Message: msg, Client: botCtx}, nil
+		}
+	}
+
+	// 回退到 Userbot
+	uc := userclient.GetCtx()
+	if uc == nil {
+		return nil, fmt.Errorf("userbot not initialized and bot cannot access this message")
+	}
+
+	msg, err := tgutil.GetMessageByID(uc, chatID, msgID)
+	if err != nil {
+		return nil, err
+	}
+
+	return &MessageContext{Message: msg, Client: uc}, nil
+}
+
+// getGroupedMessagesWithContext 获取媒体组消息，返回消息列表和使用的 context
+// 确保消息获取和后续文件创建使用同一个 context
+func getGroupedMessagesWithContext(ctx *MessageContext, chatID int64) ([]*tg.Message, error) {
+	msg := ctx.Message
+	clientCtx := ctx.Client
+
+	groupID, ok := msg.GetGroupedID()
+	if !ok || groupID == 0 {
+		return []*tg.Message{msg}, nil
+	}
+
+	// 使用获取原始消息的同一个 client 获取媒体组
+	msgs, err := tgutil.GetGroupedMessages(clientCtx, chatID, msg)
+	if err != nil || len(msgs) == 0 {
+		// 如果获取失败，至少返回原始消息
+		return []*tg.Message{msg}, nil
+	}
+
+	return msgs, nil
+}
+
+// ExtractFilesFromLinks 从消息链接中提取文件
+// 每个文件的处理流程：解析链接 -> 获取消息 -> 获取媒体组 -> 创建文件对象
+// 对于单个文件，全程使用同一个 client context，不会交叉
+func ExtractFilesFromLinks(ctx context.Context, links []string) ([]tfile.TGFileMessage, error) {
+	logger := log.FromContext(ctx)
+	var files []tfile.TGFileMessage
+
+	for _, link := range links {
+		link = strings.TrimSpace(link)
+		if link == "" {
+			continue
+		}
+
+		// 验证链接格式
+		if !isValidMessageLink(link) {
+			logger.Errorf("Invalid message link format: %s", link)
+			continue
+		}
+
+		chatID, msgID, err := ParseMessageLink(ctx, link)
+		if err != nil {
+			logger.Errorf("Failed to parse message link %s: %v", link, err)
+			continue
+		}
+
+		// 解析链接 URL 检查是否有 single 参数
+		u, _ := url.Parse(link)
+		single := u != nil && u.Query().Has("single")
+
+		// 获取消息和使用的 context（Bot 优先，失败回退 Userbot）
+		msgCtx, err := getMessageWithContext(ctx, chatID, msgID)
+		if err != nil {
+			logger.Errorf("Failed to get message %d from chat %d: %v", msgID, chatID, err)
+			continue
+		}
+
+		msg := msgCtx.Message
+		clientCtx := msgCtx.Client
+
+		if msg.Media == nil {
+			logger.Warnf("Message %d has no media", msgID)
+			continue
+		}
+
+		media, ok := msg.GetMedia()
+		if !ok {
+			logger.Warnf("Failed to get media from message %d", msgID)
+			continue
+		}
+
+		// 检查是否是媒体组
+		groupID, isGroup := msg.GetGroupedID()
+		if isGroup && groupID != 0 && !single {
+			// 使用同一个 client context 获取媒体组
+			groupMsgs, err := getGroupedMessagesWithContext(msgCtx, chatID)
+			if err != nil {
+				logger.Errorf("Failed to get grouped messages: %v", err)
+			} else {
+				for _, gmsg := range groupMsgs {
+					if gmsg.Media == nil {
+						continue
+					}
+					gmedia, ok := gmsg.GetMedia()
+					if !ok {
+						continue
+					}
+					// 使用获取消息时使用的同一个 client context 创建文件
+					file, err := tfile.FromMediaMessage(gmedia, clientCtx.Raw, gmsg)
+					if err != nil {
+						logger.Errorf("Failed to create file from media: %v", err)
+						continue
+					}
+					files = append(files, file)
+				}
+				continue
+			}
+		}
+
+		// 单个文件 - 使用获取消息时使用的同一个 client context 创建文件
+		file, err := tfile.FromMediaMessage(media, clientCtx.Raw, msg)
+		if err != nil {
+			logger.Errorf("Failed to create file from media: %v", err)
+			continue
+		}
+		files = append(files, file)
+	}
+
+	if len(files) == 0 {
+		return nil, fmt.Errorf("no files found in provided links")
+	}
+
+	return files, nil
+}
+
+// isValidMessageLink 检查是否是有效的 Telegram 消息链接
+func isValidMessageLink(link string) bool {
+	for _, prefix := range []string{
+		"https://t.me/",
+		"http://t.me/",
+		"https://telegram.me/",
+		"http://telegram.me/",
+	} {
+		if strings.HasPrefix(link, prefix) {
+			return true
+		}
+	}
+	return false
+}

api/tphpics.go

@@ -0,0 +1,80 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/charmbracelet/log"
+	"github.com/krau/SaveAny-Bot/common/utils/tphutil"
+	"github.com/krau/SaveAny-Bot/pkg/telegraph"
+)
+
+// ExtractTelegraphImages 从 Telegraph URL 提取图片
+func ExtractTelegraphImages(ctx context.Context, pageURL string) ([]string, string, error) {
+	logger := log.FromContext(ctx)
+
+	// 验证 URL 格式
+	if !isValidTelegraphURL(pageURL) {
+		return nil, "", fmt.Errorf("invalid telegraph URL format: %s", pageURL)
+	}
+
+	// 解析 URL 获取页面路径
+	pagepath, err := parseTelegraphPath(pageURL)
+	if err != nil {
+		return nil, "", err
+	}
+
+	logger.Debugf("Fetching telegraph page: %s", pagepath)
+
+	client := telegraph.NewClient()
+	page, err := client.GetPage(ctx, pagepath)
+	if err != nil {
+		return nil, "", fmt.Errorf("failed to get telegraph page: %w", err)
+	}
+
+	var imgs []string
+	for _, elem := range page.Content {
+		imgs = append(imgs, tphutil.GetNodeImages(elem)...)
+	}
+
+	if len(imgs) == 0 {
+		return nil, "", fmt.Errorf("no images found in telegraph page")
+	}
+
+	return imgs, pagepath, nil
+}
+
+// parseTelegraphPath 解析 Telegraph URL 获取页面路径
+func parseTelegraphPath(pageURL string) (string, error) {
+	u, err := url.Parse(pageURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid telegraph URL: %w", err)
+	}
+
+	if !strings.HasSuffix(u.Host, "telegra.ph") && !strings.HasSuffix(u.Host, "telegraph.co") {
+		return "", fmt.Errorf("invalid telegraph URL host: %s", u.Host)
+	}
+
+	paths := strings.Split(strings.TrimPrefix(u.Path, "/"), "/")
+	if len(paths) == 0 || paths[0] == "" {
+		return "", fmt.Errorf("invalid telegraph URL path: %s", u.Path)
+	}
+
+	pagepath := paths[len(paths)-1]
+	pagepath, err = url.PathUnescape(pagepath)
+	if err != nil {
+		return "", fmt.Errorf("failed to unescape telegraph path: %w", err)
+	}
+
+	return strings.TrimSpace(pagepath), nil
+}
+
+// isValidTelegraphURL 检查是否是有效的 Telegraph URL
+func isValidTelegraphURL(url string) bool {
+	return strings.HasPrefix(url, "https://telegra.ph/") ||
+		strings.HasPrefix(url, "http://telegra.ph/") ||
+		strings.HasPrefix(url, "https://telegraph.co/") ||
+		strings.HasPrefix(url, "http://telegraph.co/")
+}

api/types.go

@@ -0,0 +1,163 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+)
+
+// TaskStatus 表示任务状态
+type TaskStatus string
+
+const (
+	TaskStatusQueued    TaskStatus = "queued"
+	TaskStatusRunning   TaskStatus = "running"
+	TaskStatusCompleted TaskStatus = "completed"
+	TaskStatusFailed    TaskStatus = "failed"
+	TaskStatusCancelled TaskStatus = "cancelled"
+)
+
+// CreateTaskRequest 创建任务请求
+type CreateTaskRequest struct {
+	Type    tasktype.TaskType `json:"type"`
+	Storage string            `json:"storage"`
+	Path    string            `json:"path"`
+	Webhook string            `json:"webhook,omitempty"`
+	Params  json.RawMessage   `json:"params"`
+}
+
+// CreateTaskResponse 创建任务响应
+type CreateTaskResponse struct {
+	TaskID    string            `json:"task_id"`
+	Type      tasktype.TaskType `json:"type"`
+	Status    TaskStatus        `json:"status"`
+	CreatedAt time.Time         `json:"created_at"`
+}
+
+// TaskProgress 任务进度
+type TaskProgress struct {
+	TotalBytes      int64   `json:"total_bytes,omitempty"`
+	DownloadedBytes int64   `json:"downloaded_bytes,omitempty"`
+	TotalFiles      int     `json:"total_files,omitempty"`
+	DownloadedFiles int     `json:"downloaded_files,omitempty"`
+	Percent         float64 `json:"percent,omitempty"`
+	SpeedMBPS       float64 `json:"speed_mbps,omitempty"`
+}
+
+// TaskInfoResponse 任务信息响应
+type TaskInfoResponse struct {
+	TaskID    string            `json:"task_id"`
+	Type      tasktype.TaskType `json:"type"`
+	Status    TaskStatus        `json:"status"`
+	Title     string            `json:"title"`
+	Progress  *TaskProgress     `json:"progress,omitempty"`
+	Storage   string            `json:"storage"`
+	Path      string            `json:"path"`
+	Error     string            `json:"error,omitempty"`
+	CreatedAt time.Time         `json:"created_at"`
+	UpdatedAt time.Time         `json:"updated_at"`
+}
+
+// TasksListResponse 任务列表响应
+type TasksListResponse struct {
+	Tasks []TaskInfoResponse `json:"tasks"`
+	Total int                `json:"total"`
+}
+
+// StoragesResponse 存储列表响应
+type StoragesResponse struct {
+	Storages []StorageInfo `json:"storages"`
+}
+
+// StorageInfo 存储信息
+type StorageInfo struct {
+	Name string `json:"name"`
+	Type string `json:"type"`
+}
+
+// WebhookPayload Webhook 回调负载
+type WebhookPayload struct {
+	TaskID      string     `json:"task_id"`
+	Type        string     `json:"type"`
+	Status      TaskStatus `json:"status"`
+	Storage     string     `json:"storage"`
+	Path        string     `json:"path"`
+	CompletedAt *time.Time `json:"completed_at,omitempty"`
+	Error       string     `json:"error,omitempty"`
+}
+
+// ErrorResponse 错误响应
+type ErrorResponse struct {
+	Error   string `json:"error"`
+	Message string `json:"message,omitempty"`
+}
+
+// APIError API 错误
+type APIError struct {
+	StatusCode int
+	ErrorCode  string
+	Message    string
+}
+
+func (e *APIError) Error() string {
+	return e.Message
+}
+
+// WriteJSON 写入 JSON 响应
+func WriteJSON(w http.ResponseWriter, statusCode int, data any) error {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	return json.NewEncoder(w).Encode(data)
+}
+
+// WriteError 写入错误响应
+func WriteError(w http.ResponseWriter, statusCode int, errCode, message string) error {
+	return WriteJSON(w, statusCode, ErrorResponse{
+		Error:   errCode,
+		Message: message,
+	})
+}
+
+// Task 参数结构体
+
+// DirectLinksParams directlinks 任务参数
+type DirectLinksParams struct {
+	URLs []string `json:"urls"`
+}
+
+// YTDLPParams ytdlp 任务参数
+type YTDLPParams struct {
+	URLs  []string `json:"urls"`
+	Flags []string `json:"flags,omitempty"`
+}
+
+// Aria2Params aria2 任务参数
+type Aria2Params struct {
+	URLs    []string          `json:"urls"`
+	Options map[string]string `json:"options,omitempty"`
+}
+
+// ParsedParams parsed 任务参数
+type ParsedParams struct {
+	URL string `json:"url"`
+}
+
+// TransferParams transfer 任务参数
+type TransferParams struct {
+	SourceStorage string `json:"source_storage"`
+	SourcePath    string `json:"source_path"`
+	TargetStorage string `json:"target_storage"`
+	TargetPath    string `json:"target_path"`
+}
+
+// TGFilesParams tgfiles 任务参数
+type TGFilesParams struct {
+	MessageLinks []string `json:"message_links"`
+}
+
+// TPHPicsParams tphpics 任务参数
+type TPHPicsParams struct {
+	TelegraphURL string `json:"telegraph_url"`
+}

api/webhook.go

@@ -0,0 +1,99 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/charmbracelet/log"
+)
+
+// webhookClient Webhook 客户端
+var webhookClient = &http.Client{
+	Timeout: 30 * time.Second,
+}
+
+// SendWebhook 发送 Webhook 回调
+func SendWebhook(ctx context.Context, payload *WebhookPayload) {
+	if payload == nil || payload.TaskID == "" {
+		return
+	}
+
+	// 获取任务信息以获取 webhook URL
+	info, ok := GetTask(payload.TaskID)
+	if !ok || info.Webhook == "" {
+		return
+	}
+
+	webhookURL := info.Webhook
+
+	// Async send with retries.
+	go func() {
+		var logger *log.Logger
+		if ctx != nil {
+			logger = log.FromContext(ctx).With("task_id", payload.TaskID)
+		} else {
+			logger = log.Default().With("task_id", payload.TaskID)
+		}
+
+		payloadBytes, err := json.Marshal(payload)
+		if err != nil {
+			logger.Errorf("Failed to marshal webhook payload: %v", err)
+			return
+		}
+
+		// 重试 3 次
+		for i := range 3 {
+			req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, webhookURL, bytes.NewBuffer(payloadBytes))
+			if err != nil {
+				logger.Errorf("Failed to create webhook request: %v", err)
+				return
+			}
+
+			req.Header.Set("Content-Type", "application/json")
+			req.Header.Set("User-Agent", "SaveAny-Bot/1.0")
+
+			resp, err := webhookClient.Do(req)
+			if err != nil {
+				logger.Warnf("Webhook request failed (attempt %d/3): %v", i+1, err)
+				time.Sleep(time.Second * time.Duration(i+1))
+				continue
+			}
+			resp.Body.Close()
+
+			if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+				logger.Debugf("Webhook sent successfully: %s", webhookURL)
+				return
+			}
+
+			logger.Warnf("Webhook returned non-2xx status (attempt %d/3): %d", i+1, resp.StatusCode)
+			time.Sleep(time.Second * time.Duration(i+1))
+		}
+
+		logger.Errorf("Failed to send webhook after 3 attempts")
+	}()
+}
+
+// CreateWebhookPayload creates a Webhook payload.
+func CreateWebhookPayload(taskID string, taskType string, status TaskStatus, storage, path string, err error) *WebhookPayload {
+	payload := &WebhookPayload{
+		TaskID:  taskID,
+		Type:    taskType,
+		Status:  status,
+		Storage: storage,
+		Path:    path,
+	}
+
+	if status == TaskStatusCompleted || status == TaskStatusFailed {
+		now := time.Now()
+		payload.CompletedAt = &now
+	}
+
+	if err != nil {
+		payload.Error = err.Error()
+	}
+
+	return payload
+}

client/bot/handlers/add_task.go

@@ -73,14 +73,16 @@ func handleAddCallback(ctx *ext.Context, update *ext.Update) error {
 			return dispatcher.EndGroups
 		}
 		dirPath = dir.Path
+	} else if data.SelectedDirPath != "" {
+		dirPath = data.SelectedDirPath
 	}
 
 	switch data.TaskType {
 	case tasktype.TaskTypeTgfiles:
 		if data.AsBatch {
-			return shortcut.CreateAndAddBatchTGFileTaskWithEdit(ctx, userID, selectedStorage, dirPath, data.Files, msgID)
+			return shortcut.CreateAndAddBatchTGFileTaskWithEdit(ctx, userID, selectedStorage, dirPath, data.Files, msgID, data.ConflictStrategy)
 		}
-		return shortcut.CreateAndAddTGFileTaskWithEdit(ctx, userID, selectedStorage, dirPath, data.Files[0], msgID)
+		return shortcut.CreateAndAddTGFileTaskWithEdit(ctx, userID, selectedStorage, dirPath, data.Files[0], msgID, data.ConflictStrategy)
 	case tasktype.TaskTypeTphpics:
 		return shortcut.CreateAndAddtelegraphWithEdit(ctx, userID, data.TphPageNode, data.TphDirPath, data.TphPics, selectedStorage, msgID)
 	case tasktype.TaskTypeParseditem:
@@ -100,7 +102,9 @@ func handleAddCallback(ctx *ext.Context, update *ext.Update) error {
 		}
 		shortcut.CreateAndAddAria2TaskWithEdit(ctx, selectedStorage, dirPath, data.Aria2URIs, client, msgID, userID)
 	case tasktype.TaskTypeYtdlp:
-		shortcut.CreateAndAddYtdlpTaskWithEdit(ctx, selectedStorage, dirPath, data.YtdlpURLs, msgID, userID)
+		shortcut.CreateAndAddYtdlpTaskWithEdit(ctx, selectedStorage, dirPath, data.YtdlpURLs, data.YtdlpFlags, msgID, userID)
+	case tasktype.TaskTypeTransfer:
+		return handleTransferCallback(ctx, userID, selectedStorage, dirPath, data, msgID)
 	default:
 		return fmt.Errorf("unexcept task type: %s", data.TaskType)
 	}

client/bot/handlers/config.go

@@ -8,6 +8,7 @@ import (
 	"github.com/celestix/gotgproto/dispatcher"
 	"github.com/celestix/gotgproto/ext"
 	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/conflictutil"
 	"github.com/krau/SaveAny-Bot/common/i18n"
 	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
 	"github.com/krau/SaveAny-Bot/config"
@@ -26,6 +27,10 @@ func handleConfigCmd(ctx *ext.Context, update *ext.Update) error {
 							Text: i18n.T(i18nk.BotMsgConfigButtonFilenameStrategy),
 							Data: fmt.Appendf(nil, "%s %s", tcbdata.TypeConfig, "fnamest"),
 						},
+						&tg.KeyboardButtonCallback{
+							Text: i18n.T(i18nk.BotMsgConfigButtonConflictStrategy),
+							Data: fmt.Appendf(nil, "%s %s", tcbdata.TypeConfig, "conflictst"),
+						},
 					},
 				},
 			},
@@ -51,6 +56,8 @@ func handleConfigCallback(ctx *ext.Context, update *ext.Update) error {
 	switch args[1] {
 	case "fnamest":
 		return handleConfigFnameSTCallback(ctx, update)
+	case "conflictst":
+		return handleConfigConflictSTCallback(ctx, update)
 	default:
 		return invaildDataAnswer()
 	}
@@ -110,6 +117,55 @@ func handleConfigFnameSTCallback(ctx *ext.Context, update *ext.Update) error {
 	return dispatcher.EndGroups
 }
 
+func handleConfigConflictSTCallback(ctx *ext.Context, update *ext.Update) error {
+	userID := update.CallbackQuery.GetUserID()
+	user, err := database.GetUserByChatID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	args := strings.Fields(string(update.CallbackQuery.Data))
+	if len(args) == 3 {
+		selected := args[2]
+		if !tcbdata.IsConflictStrategy(selected) {
+			return fmt.Errorf("invalid conflict strategy: %s", selected)
+		}
+		user.ConflictStrategy = selected
+		if err := database.UpdateUser(ctx, user); err != nil {
+			return err
+		}
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID: update.CallbackQuery.GetMsgID(),
+			Message: i18n.T(i18nk.BotMsgConfigInfoConflictStrategySet, map[string]any{
+				"Strategy": conflictutil.Display(selected),
+			}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	opts := tcbdata.ConflictStrategyValues()
+	rows := make([]tg.KeyboardButtonRow, 0, len(opts))
+	for _, opt := range opts {
+		rows = append(rows, tg.KeyboardButtonRow{
+			Buttons: []tg.KeyboardButtonClass{
+				&tg.KeyboardButtonCallback{
+					Text: conflictutil.Display(opt),
+					Data: fmt.Appendf(nil, "%s %s %s", tcbdata.TypeConfig, "conflictst", opt),
+				},
+			},
+		})
+	}
+	markup := &tg.ReplyInlineMarkup{Rows: rows}
+	currentSt := conflictutil.EffectiveStrategy(user)
+	ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+		ID: update.CallbackQuery.GetMsgID(),
+		Message: i18n.T(i18nk.BotMsgConfigPromptSelectConflictStrategy, map[string]any{
+			"Strategy": conflictutil.Display(currentSt),
+		}),
+		ReplyMarkup: markup,
+	})
+	return dispatcher.EndGroups
+}
+
 func handleConfigFnameTmpl(ctx *ext.Context, update *ext.Update) error {
 	userID := update.GetUserChat().GetID()
 	user, err := database.GetUserByChatID(ctx, userID)

client/bot/handlers/dl.go

@@ -84,7 +84,7 @@ func handleAria2DlCmd(ctx *ext.Context, update *ext.Update) error {
 		return nil
 	}
 	logger.Debug("Preparing aria2 download", "links", links)
-	
+
 	// Initialize aria2 client to check connection
 	aria2ClientInitOnce.Do(func() {
 		aria2Client, aria2ClientInitErr = aria2.NewClient(config.C().Aria2.Url, config.C().Aria2.Secret)

client/bot/handlers/media_group.go

@@ -13,8 +13,8 @@ import (
 	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/shortcut"
 	"github.com/krau/SaveAny-Bot/common/i18n"
 	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
-	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
 	"github.com/krau/SaveAny-Bot/config"
+	"github.com/krau/SaveAny-Bot/database"
 	"github.com/krau/SaveAny-Bot/pkg/tcbdata"
 	"github.com/krau/SaveAny-Bot/pkg/tfile"
 	"github.com/krau/SaveAny-Bot/storage"
@@ -53,9 +53,13 @@ func handleGroupMediaMessage(ctx *ext.Context, update *ext.Update, message *tg.M
 	if !supported {
 		return dispatcher.EndGroups
 	}
-	file, err := tfile.FromMediaMessage(media, ctx.Raw, message, tfile.WithNameIfEmpty(
-		tgutil.GenFileNameFromMessage(*message),
-	))
+	userId := update.GetUserChat().GetID()
+	userDB, err := database.GetUserByChatID(ctx, userId)
+	if err != nil {
+		return err
+	}
+	tfOpts := mediautil.TfileOptions(ctx, userDB, message)
+	file, err := tfile.FromMediaMessage(media, ctx.Raw, message, tfOpts...)
 	if err != nil {
 		logger.Errorf("Failed to get file from media: %s", err)
 		return dispatcher.EndGroups
@@ -114,7 +118,7 @@ func processMediaGroup(ctx *ext.Context, update *ext.Update, groupID int64) {
 	if err != nil {
 		logger.Errorf("Failed to build storage selection keyboard: %s", err)
 		ctx.EditMessage(userId, &tg.MessagesEditMessageRequest{
-			ID:      msg.ID,
+			ID: msg.ID,
 			Message: i18n.T(i18nk.BotMsgMediaGroupErrorBuildStorageSelectKeyboardFailed, map[string]any{
 				"Error": err.Error(),
 			}),

client/bot/handlers/register.go

@@ -31,6 +31,7 @@ var CommandHandlers = []DescCommandHandler{
 	{"dl", i18nk.BotMsgCmdDl, handleDlCmd},
 	{"aria2dl", i18nk.BotMsgCmdAria2dl, handleAria2DlCmd},
 	{"ytdlp", i18nk.BotMsgCmdYtdlp, handleYtdlpCmd},
+	{"transfer", i18nk.BotMsgCmdTransfer, handleTransferCmd},
 	{"task", i18nk.BotMsgCmdTask, handleTaskCmd},
 	{"cancel", i18nk.BotMsgCmdCancel, handleCancelCmd},
 	{"config", i18nk.BotMsgCmdConfig, handleConfigCmd},

client/bot/handlers/rule.go

@@ -13,6 +13,7 @@ import (
 	"github.com/krau/SaveAny-Bot/common/i18n"
 	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
 	"github.com/krau/SaveAny-Bot/common/utils/strutil"
+	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/database"
 	"github.com/krau/SaveAny-Bot/pkg/rule"
 )
@@ -84,6 +85,46 @@ func handleRuleCmd(ctx *ext.Context, update *ext.Update) error {
 			return dispatcher.EndGroups
 		}
 		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgRuleInfoCreateRuleSuccess, nil)), nil)
+	case "preset":
+		// /rule preset <storage> [base_path]
+		if len(args) < 3 {
+			ctx.Reply(update, ext.ReplyTextStyledTextArray(msgelem.BuildRuleHelpStyling(user.ApplyRule, user.Rules)), nil)
+			return dispatcher.EndGroups
+		}
+		storageName := args[2]
+		if !config.C().HasStorage(user.ChatID, storageName) {
+			ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgRuleErrorStorageNotFound, map[string]any{
+				"Storage": storageName,
+			})), nil)
+			return dispatcher.EndGroups
+		}
+		basePath := ""
+		if len(args) >= 4 {
+			basePath = args[3]
+		}
+		presets := rule.PresetCategories(basePath)
+		imported := 0
+		for _, p := range presets {
+			rd := &database.Rule{
+				Type:        rule.FileNameRegex.String(),
+				Data:        p.Regex,
+				StorageName: storageName,
+				DirPath:     p.Dir,
+				UserID:      user.ID,
+			}
+			if err := database.CreateRule(ctx, rd); err != nil {
+				logger.Errorf("failed to create preset rule %s: %s", p.Name, err)
+				continue
+			}
+			imported++
+		}
+		if imported == 0 {
+			ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgRuleErrorCreateRuleFailed, nil)), nil)
+			return dispatcher.EndGroups
+		}
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgRuleInfoPresetImported, map[string]any{
+			"Count": imported,
+		})), nil)
 	case "del":
 		// /rule del <id>
 		if len(args) < 3 {

client/bot/handlers/tasks.go

@@ -38,7 +38,7 @@ func handleTaskCmd(ctx *ext.Context, update *ext.Update) error {
 			return dispatcher.EndGroups
 		}
 		ctx.Reply(update, ext.ReplyTextStyledTextArray([]styling.StyledTextOption{
-				styling.Plain(i18n.T(i18nk.BotMsgTasksCancelRequestedPrefix)),
+			styling.Plain(i18n.T(i18nk.BotMsgTasksCancelRequestedPrefix)),
 			styling.Code(taskID),
 		}), nil)
 	default:

client/bot/handlers/transfer.go

@@ -0,0 +1,257 @@
+package handlers
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/celestix/gotgproto/dispatcher"
+	"github.com/celestix/gotgproto/ext"
+	"github.com/charmbracelet/log"
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/msgelem"
+	"github.com/krau/SaveAny-Bot/common/i18n"
+	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
+	"github.com/krau/SaveAny-Bot/common/utils/strutil"
+	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
+	"github.com/krau/SaveAny-Bot/core"
+	"github.com/krau/SaveAny-Bot/core/tasks/transfer"
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+	"github.com/krau/SaveAny-Bot/pkg/storagetypes"
+	"github.com/krau/SaveAny-Bot/pkg/tcbdata"
+	"github.com/krau/SaveAny-Bot/storage"
+	"github.com/rs/xid"
+)
+
+func handleTransferCmd(ctx *ext.Context, update *ext.Update) error {
+	logger := log.FromContext(ctx)
+	args := strutil.ParseArgsRespectQuotes(update.EffectiveMessage.Text)
+
+	if len(args) < 2 {
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferUsage, nil)), nil)
+		return dispatcher.EndGroups
+	}
+
+	// Parse source: storage_name:/path
+	sourceParts := strings.SplitN(args[1], ":", 2)
+	if len(sourceParts) != 2 {
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferErrorInvalidSource, nil)), nil)
+		return dispatcher.EndGroups
+	}
+	sourceStorageName := sourceParts[0]
+	sourcePath := sourceParts[1]
+
+	userID := update.GetUserChat().GetID()
+
+	// Get source storage
+	sourceStorage, err := storage.GetStorageByUserIDAndName(ctx, userID, sourceStorageName)
+	if err != nil {
+		logger.Errorf("Failed to get source storage by user ID and name: %s", err)
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferErrorStorageNotFound, map[string]any{
+			"StorageName": sourceStorageName,
+			"Error":       err,
+		})), nil)
+		return dispatcher.EndGroups
+	}
+
+	// Check if source storage supports listing
+	listable, ok := sourceStorage.(storage.StorageListable)
+	if !ok {
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferErrorStorageNotListable, map[string]any{
+			"StorageName": sourceStorageName,
+		})), nil)
+		return dispatcher.EndGroups
+	}
+
+	// Check if source storage supports reading
+	_, ok = sourceStorage.(storage.StorageReadable)
+	if !ok {
+		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferErrorStorageNotReadable, map[string]any{
+			"StorageName": sourceStorageName,
+		})), nil)
+		return dispatcher.EndGroups
+	}
+
+	// Fetch file list
+	replied, err := ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgTransferInfoFetchingFiles, nil)), nil)
+	if err != nil {
+		logger.Errorf("Failed to reply: %s", err)
+		return dispatcher.EndGroups
+	}
+
+	files, err := listable.ListFiles(ctx, sourcePath)
+	if err != nil {
+		ctx.EditMessage(update.EffectiveChat().GetID(), &tg.MessagesEditMessageRequest{
+			ID:      replied.ID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorListFilesFailed, map[string]any{"Error": err}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Optional filter
+	var filter *regexp.Regexp
+	if len(args) >= 3 {
+		filter, err = regexp.Compile(args[2])
+		if err != nil {
+			ctx.EditMessage(update.EffectiveChat().GetID(), &tg.MessagesEditMessageRequest{
+				ID:      replied.ID,
+				Message: i18n.T(i18nk.BotMsgTransferErrorInvalidRegex, map[string]any{"Error": err}),
+			})
+			return dispatcher.EndGroups
+		}
+	}
+
+	// Filter files
+	filteredFiles := make([]storagetypes.FileInfo, 0)
+	for _, file := range files {
+		if file.IsDir {
+			continue
+		}
+		if filter != nil && !filter.MatchString(file.Name) {
+			continue
+		}
+		filteredFiles = append(filteredFiles, file)
+	}
+
+	if len(filteredFiles) == 0 {
+		ctx.EditMessage(update.EffectiveChat().GetID(), &tg.MessagesEditMessageRequest{
+			ID:      replied.ID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorNoFilesToTransfer, nil),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Prepare file paths for callback data
+	filePaths := make([]string, 0, len(filteredFiles))
+	var totalSize int64
+	for _, file := range filteredFiles {
+		filePaths = append(filePaths, file.Path)
+		totalSize += file.Size
+	}
+
+	// Build storage selection keyboard
+	markup, err := msgelem.BuildAddSelectStorageKeyboard(storage.GetUserStorages(ctx, userID), tcbdata.Add{
+		TaskType:               tasktype.TaskTypeTransfer,
+		TransferSourceStorName: sourceStorageName,
+		TransferSourcePath:     sourcePath,
+		TransferFiles:          filePaths,
+	})
+	if err != nil {
+		logger.Errorf("Failed to build storage selection keyboard: %s", err)
+		ctx.EditMessage(update.EffectiveChat().GetID(), &tg.MessagesEditMessageRequest{
+			ID:      replied.ID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorBuildStorageSelectKeyboardFailed, map[string]any{"Error": err}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	ctx.EditMessage(update.EffectiveChat().GetID(), &tg.MessagesEditMessageRequest{
+		ID: replied.ID,
+		Message: i18n.T(i18nk.BotMsgTransferInfoFilesSelectStorage, map[string]any{
+			"Count":  len(filteredFiles),
+			"SizeMB": fmt.Sprintf("%.2f", float64(totalSize)/(1024*1024)),
+		}),
+		ReplyMarkup: markup,
+	})
+
+	return dispatcher.EndGroups
+}
+
+func handleTransferCallback(ctx *ext.Context, userID int64, targetStorage storage.Storage, dirPath string, data tcbdata.Add, msgID int) error {
+	logger := log.FromContext(ctx)
+
+	// Get source storage
+	sourceStorage, err := storage.GetStorageByUserIDAndName(ctx, userID, data.TransferSourceStorName)
+	if err != nil {
+		logger.Errorf("Failed to get source storage: %s", err)
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID:      msgID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorStorageNotFound, map[string]any{"StorageName": data.TransferSourceStorName, "Error": err}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Check if source storage supports listing
+	listable, ok := sourceStorage.(storage.StorageListable)
+	if !ok {
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID:      msgID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorStorageNotListable, map[string]any{"StorageName": data.TransferSourceStorName}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Re-fetch files to get FileInfo (since we only stored paths)
+	// This is necessary to get size and other metadata
+	ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+		ID:      msgID,
+		Message: i18n.T(i18nk.BotMsgTransferInfoFetchingFiles, nil),
+	})
+
+	allFiles, err := listable.ListFiles(ctx, data.TransferSourcePath)
+	if err != nil {
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID:      msgID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorListFilesFailed, map[string]any{"Error": err}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Create a map for quick lookup
+	fileMap := make(map[string]storagetypes.FileInfo)
+	for _, file := range allFiles {
+		fileMap[file.Path] = file
+	}
+
+	// Build task elements for the selected files
+	elems := make([]transfer.TaskElement, 0, len(data.TransferFiles))
+	var totalSize int64
+	for _, filePath := range data.TransferFiles {
+		fileInfo, ok := fileMap[filePath]
+		if !ok {
+			logger.Warnf("File not found in source storage: %s", filePath)
+			continue
+		}
+		elem := transfer.NewTaskElement(sourceStorage, fileInfo, targetStorage, dirPath)
+		elems = append(elems, *elem)
+		totalSize += fileInfo.Size
+	}
+
+	if len(elems) == 0 {
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID:      msgID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorNoFilesToTransfer, nil),
+		})
+		return dispatcher.EndGroups
+	}
+
+	// Create and add task
+	taskID := xid.New().String()
+	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
+	task := transfer.NewTransferTask(
+		taskID,
+		injectCtx,
+		elems,
+		transfer.NewProgressTracker(msgID, userID),
+		true, // IgnoreErrors
+	)
+
+	if err := core.AddTask(injectCtx, task); err != nil {
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID:      msgID,
+			Message: i18n.T(i18nk.BotMsgTransferErrorAddTaskFailed, map[string]any{"Error": err}),
+		})
+		return dispatcher.EndGroups
+	}
+
+	ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+		ID: msgID,
+		Message: i18n.T(i18nk.BotMsgTransferInfoTaskAdded, map[string]any{
+			"Count":  len(elems),
+			"SizeMB": fmt.Sprintf("%.2f", float64(totalSize)/(1024*1024)),
+			"TaskID": taskID,
+		}),
+	})
+
+	return dispatcher.EndGroups
+}

client/bot/handlers/update.go

@@ -103,7 +103,7 @@ func handleUpdateCallback(ctx *ext.Context, u *ext.Update) error {
 		return err
 	}
 	ctx.EditMessage(u.GetUserChat().GetID(), &tg.MessagesEditMessageRequest{
-		ID:      u.CallbackQuery.GetMsgID(),
+		ID: u.CallbackQuery.GetMsgID(),
 		Message: i18n.T(i18nk.BotMsgUpdateInfoUpgradingWithVersion, map[string]any{
 			"Current": config.Version,
 		}),
@@ -111,7 +111,7 @@ func handleUpdateCallback(ctx *ext.Context, u *ext.Update) error {
 	latest, err := ghselfupdate.UpdateSelf(currentV, config.GitRepo)
 	if err != nil {
 		ctx.EditMessage(u.GetUserChat().GetID(), &tg.MessagesEditMessageRequest{
-			ID:      u.CallbackQuery.GetMsgID(),
+			ID: u.CallbackQuery.GetMsgID(),
 			Message: i18n.T(i18nk.BotMsgUpdateErrorUpgradeFailed, map[string]any{
 				"Error": err.Error(),
 			}),
@@ -119,7 +119,7 @@ func handleUpdateCallback(ctx *ext.Context, u *ext.Update) error {
 		return dispatcher.EndGroups
 	}
 	ctx.EditMessage(u.GetUserChat().GetID(), &tg.MessagesEditMessageRequest{
-		ID:      u.CallbackQuery.GetMsgID(),
+		ID: u.CallbackQuery.GetMsgID(),
 		Message: i18n.T(i18nk.BotMsgUpdateInfoUpgradeSuccess, map[string]any{
 			"Version": latest.Version.String(),
 		}),

client/bot/handlers/utils/conflictutil/conflict.go

@@ -0,0 +1,55 @@
+package conflictutil
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/krau/SaveAny-Bot/common/i18n"
+	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
+	"github.com/krau/SaveAny-Bot/database"
+	"github.com/krau/SaveAny-Bot/pkg/tcbdata"
+)
+
+const maxConflictLines = 10
+
+func EffectiveStrategy(user *database.User) string {
+	if user != nil && tcbdata.IsConflictStrategy(user.ConflictStrategy) {
+		return user.ConflictStrategy
+	}
+	return tcbdata.ConflictStrategyRename
+}
+
+func ResolveStrategy(user *database.User, override string) string {
+	if tcbdata.IsConflictStrategy(override) {
+		return override
+	}
+	return EffectiveStrategy(user)
+}
+
+func Display(strategy string) string {
+	switch strategy {
+	case tcbdata.ConflictStrategyRename:
+		return i18n.T(i18nk.BotMsgConfigConflictStrategyRename, nil)
+	case tcbdata.ConflictStrategyAsk:
+		return i18n.T(i18nk.BotMsgConfigConflictStrategyAsk, nil)
+	case tcbdata.ConflictStrategyOverwrite:
+		return i18n.T(i18nk.BotMsgConfigConflictStrategyOverwrite, nil)
+	case tcbdata.ConflictStrategySkip:
+		return i18n.T(i18nk.BotMsgConfigConflictStrategySkip, nil)
+	default:
+		return strategy
+	}
+}
+
+func FormatPaths(conflicts []string) string {
+	if len(conflicts) <= maxConflictLines {
+		return strings.Join(conflicts, "\n")
+	}
+	return strings.Join(conflicts[:maxConflictLines], "\n") + "\n" + i18n.T(i18nk.BotMsgCommonPromptConflictMoreFiles, map[string]any{
+		"Count": len(conflicts) - maxConflictLines,
+	})
+}
+
+func FormatPath(storageName, storagePath string) string {
+	return fmt.Sprintf("[%s]:%s", storageName, storagePath)
+}

client/bot/handlers/utils/mediautil/media.go

@@ -112,7 +112,7 @@ func BuildFilenameTemplateData(message *tg.Message) map[string]string {
 		}(),
 		MsgRaw: message.GetMessage(),
 		ChatID: func() string {
-			// 如果消息是频道的(从消息链接中fetch的) 直接使用其chat id, 
+			// 如果消息是频道的(从消息链接中fetch的) 直接使用其chat id,
 			// 无论它是否是从其他来源转发的
 			if message.GetPost() {
 				peer := message.GetPeerID()

client/bot/handlers/utils/msgelem/rule.go

@@ -24,6 +24,8 @@ func BuildRuleHelpStyling(enabled bool, rules []database.Rule) []styling.StyledT
 		styling.Plain(i18n.T(i18nk.BotMsgRuleHelpSwitchSuffix, nil)),
 		styling.Code("add"),
 		styling.Plain(i18n.T(i18nk.BotMsgRuleHelpAddSuffix, nil)),
+		styling.Code("preset"),
+		styling.Plain(i18n.T(i18nk.BotMsgRuleHelpPresetSuffix, nil)),
 		styling.Code("del"),
 		styling.Plain(i18n.T(i18nk.BotMsgRuleHelpDelSuffix, nil)),
 		styling.Plain(i18n.T(i18nk.BotMsgRuleHelpExistingRulesPrefix, nil)),

client/bot/handlers/utils/msgelem/storage.go

@@ -38,6 +38,8 @@ func BuildAddSelectStorageKeyboard(stors []storage.Storage, adddata tcbdata.Add)
 		data := tcbdata.Add{
 			TaskType:         taskType,
 			SelectedStorName: storage.Name(),
+			SelectedDirPath:  adddata.SelectedDirPath,
+			ConflictStrategy: adddata.ConflictStrategy,
 
 			Files:   adddata.Files,
 			AsBatch: len(adddata.Files) > 1,
@@ -50,8 +52,13 @@ func BuildAddSelectStorageKeyboard(stors []storage.Storage, adddata tcbdata.Add)
 
 			DirectLinks: adddata.DirectLinks,
 
-			Aria2URIs: adddata.Aria2URIs,
-			YtdlpURLs: adddata.YtdlpURLs,
+			Aria2URIs:  adddata.Aria2URIs,
+			YtdlpURLs:  adddata.YtdlpURLs,
+			YtdlpFlags: adddata.YtdlpFlags,
+
+			TransferSourceStorName: adddata.TransferSourceStorName,
+			TransferSourcePath:     adddata.TransferSourcePath,
+			TransferFiles:          adddata.TransferFiles,
 		}
 		dataid := xid.New().String()
 		err := cache.Set(dataid, data)
@@ -104,6 +111,38 @@ func BuildAddOneSelectStorageMessage(ctx context.Context, stors []storage.Storag
 	}, nil
 }
 
+func BuildConflictStrategyMarkup(adddata tcbdata.Add) (*tg.ReplyInlineMarkup, error) {
+	type option struct {
+		text     string
+		strategy string
+	}
+	options := []option{
+		{text: i18n.T(i18nk.BotMsgCommonButtonConflictRename, nil), strategy: tcbdata.ConflictStrategyRename},
+		{text: i18n.T(i18nk.BotMsgCommonButtonConflictOverwrite, nil), strategy: tcbdata.ConflictStrategyOverwrite},
+		{text: i18n.T(i18nk.BotMsgCommonButtonConflictSkip, nil), strategy: tcbdata.ConflictStrategySkip},
+	}
+	buttons := make([]tg.KeyboardButtonClass, 0, len(options))
+	for _, opt := range options {
+		data := adddata
+		data.ConflictStrategy = opt.strategy
+		dataid := xid.New().String()
+		if err := cache.Set(dataid, data); err != nil {
+			return nil, err
+		}
+		buttons = append(buttons, &tg.KeyboardButtonCallback{
+			Text: opt.text,
+			Data: fmt.Appendf(nil, "%s %s", tcbdata.TypeAdd, dataid),
+		})
+	}
+	rows := make([]tg.KeyboardButtonRow, 0, len(buttons))
+	for _, button := range buttons {
+		rows = append(rows, tg.KeyboardButtonRow{
+			Buttons: []tg.KeyboardButtonClass{button},
+		})
+	}
+	return &tg.ReplyInlineMarkup{Rows: rows}, nil
+}
+
 // Builds the inline keyboard for setting default storage
 func BuildSetDefaultStorageMarkup(
 	ctx context.Context,

client/bot/handlers/utils/re/regexp.go

@@ -3,8 +3,8 @@ package re
 import "regexp"
 
 var (
-	TgMessageLinkRegexString = `https?://t\.me/(?:c/\d+|[A-Za-z0-9_]+)/\d+(?:/\d+)?(?:\?[^\s#]*[A-Za-z0-9_])?\b`
+	TgMessageLinkRegexString = `https?://(?:t|telegram)\.me/(?:c/\d+|[A-Za-z0-9_]+)/\d+(?:/\d+)?(?:\?[^\s#]*[A-Za-z0-9_])?\b`
 	TgMessageLinkRegexp      = regexp.MustCompile(TgMessageLinkRegexString)
-	TelegraphUrlRegexString  = `https://telegra.ph/.*`
+	TelegraphUrlRegexString  = `https://telegra\.ph/[^\s]+`
 	TelegraphUrlRegexp       = regexp.MustCompile(TelegraphUrlRegexString)
 )

client/bot/handlers/utils/shortcut/aria2.go

@@ -46,7 +46,7 @@ func CreateAndAddAria2TaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPa
 	logger.Infof("Aria2 download added with GID: %s", gid)
 
 	// Create task with the GID
-	task := aria2dl.NewTask(xid.New().String(), injectCtx, gid, uris, aria2Client, stor, stor.JoinStoragePath(dirPath), aria2dl.NewProgress(msgID, userID))
+	task := aria2dl.NewTask(xid.New().String(), injectCtx, gid, uris, aria2Client, stor, dirPath, aria2dl.NewProgress(msgID, userID))
 	if err := core.AddTask(injectCtx, task); err != nil {
 		logger.Errorf("Failed to add task: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{

client/bot/handlers/utils/shortcut/directlinks.go

@@ -16,7 +16,7 @@ import (
 
 func CreateAndAddDirectTaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPath string, links []string, msgID int, userID int64) error {
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
-	task := directlinks.NewTask(xid.New().String(), injectCtx, links, stor, stor.JoinStoragePath(dirPath), directlinks.NewProgress(msgID, userID))
+	task := directlinks.NewTask(xid.New().String(), injectCtx, links, stor, dirPath, directlinks.NewProgress(msgID, userID))
 	if err := core.AddTask(injectCtx, task); err != nil {
 		log.FromContext(ctx).Errorf("Failed to add task: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{

client/bot/handlers/utils/shortcut/message.go

@@ -3,6 +3,7 @@ package shortcut
 
 import (
 	"encoding/json"
+	"fmt"
 	"net/url"
 	"strings"
 
@@ -179,21 +180,19 @@ type TelegraphResult struct {
 // return replied message, image urls, telegraph path(unescaped), error
 func GetTphPicsFromMessageWithReply(ctx *ext.Context, update *ext.Update) (*types.Message, *TelegraphResult, error) {
 	logger := log.FromContext(ctx)
-	tphurl := re.TelegraphUrlRegexp.FindString(tgutil.ExtractMessageEntityUrlsText(update.EffectiveMessage.Message))
+	tphurl := findTelegraphURL(update.EffectiveMessage.Message)
 	if tphurl == "" {
 		logger.Warnf("No telegraph url found but called handleTelegraph")
 		return nil, nil, dispatcher.ContinueGroups
 	}
-	pagepath := strings.Split(tphurl, "/")[len(strings.Split(tphurl, "/"))-1]
-	tphdir, err := url.PathUnescape(pagepath)
+	pagepath, err := parseTelegraphPagePath(tphurl)
 	if err != nil {
-		logger.Errorf("Failed to unescape telegraph path: %s", err)
+		logger.Errorf("Failed to parse telegraph path: %s", err)
 		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgCommonErrorParseTelegraphPathFailed, map[string]any{
 			"Error": err.Error(),
 		})), nil)
 		return nil, nil, dispatcher.EndGroups
 	}
-	tphdir = strings.TrimSpace(tphdir)
 	msg, err := ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgCommonInfoFetchingTelegraphPage, nil)), nil)
 	if err != nil {
 		logger.Errorf("Failed to reply to update: %s", err)
@@ -244,7 +243,57 @@ func GetTphPicsFromMessageWithReply(ctx *ext.Context, update *ext.Update) (*type
 	}
 	return msg, &TelegraphResult{
 		Pics:   imgs,
-		TphDir: tphdir,
+		TphDir: pagepath,
 		Page:   page,
 	}, nil
 }
+
+func findTelegraphURL(msg *tg.Message) string {
+	if msg == nil {
+		return ""
+	}
+	var firstMatch string
+	findValid := func(text string) string {
+		for _, tphurl := range re.TelegraphUrlRegexp.FindAllString(text, -1) {
+			if firstMatch == "" {
+				firstMatch = tphurl
+			}
+			if _, err := parseTelegraphPagePath(tphurl); err == nil {
+				return tphurl
+			}
+		}
+		return ""
+	}
+	for _, entityURL := range tgutil.ExtractMessageEntityUrls(msg) {
+		if tphurl := findValid(entityURL); tphurl != "" {
+			return tphurl
+		}
+	}
+	if tphurl := findValid(msg.GetMessage()); tphurl != "" {
+		return tphurl
+	}
+	return firstMatch
+}
+
+func parseTelegraphPagePath(pageURL string) (string, error) {
+	u, err := url.Parse(pageURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid telegraph URL: %w", err)
+	}
+	if u.Scheme != "https" || !strings.EqualFold(u.Hostname(), "telegra.ph") {
+		return "", fmt.Errorf("invalid telegraph URL host: %s", u.Host)
+	}
+	pagepath := strings.Trim(u.EscapedPath(), "/")
+	if pagepath == "" || strings.Contains(pagepath, "/") {
+		return "", fmt.Errorf("invalid telegraph URL path: %s", u.Path)
+	}
+	pagepath, err = url.PathUnescape(pagepath)
+	if err != nil {
+		return "", fmt.Errorf("failed to unescape telegraph path: %w", err)
+	}
+	pagepath = strings.TrimSpace(pagepath)
+	if pagepath == "" || strings.Contains(pagepath, "/") {
+		return "", fmt.Errorf("invalid telegraph URL path: %s", u.Path)
+	}
+	return pagepath, nil
+}

client/bot/handlers/utils/shortcut/message_telegraph_test.go

@@ -0,0 +1,163 @@
+package shortcut
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestFindTelegraphURL(t *testing.T) {
+	tests := []struct {
+		name string
+		msg  *tg.Message
+		want string
+	}{
+		{
+			name: "single URL entity",
+			msg: &tg.Message{
+				Message: "https://telegra.ph/Example-01-02",
+				Entities: []tg.MessageEntityClass{
+					&tg.MessageEntityURL{Offset: 0, Length: 32},
+				},
+			},
+			want: "https://telegra.ph/Example-01-02",
+		},
+		{
+			name: "Telegraph URL before another URL",
+			msg: &tg.Message{
+				Message: "https://telegra.ph/Example-01-02 https://example.com/",
+				Entities: []tg.MessageEntityClass{
+					&tg.MessageEntityURL{Offset: 0, Length: 32},
+					&tg.MessageEntityURL{Offset: 33, Length: 20},
+				},
+			},
+			want: "https://telegra.ph/Example-01-02",
+		},
+		{
+			name: "hidden Telegraph URL",
+			msg: &tg.Message{
+				Message: "article",
+				Entities: []tg.MessageEntityClass{
+					&tg.MessageEntityTextURL{
+						Offset: 0,
+						Length: 7,
+						URL:    "https://telegra.ph/Hidden-01-02",
+					},
+				},
+			},
+			want: "https://telegra.ph/Hidden-01-02",
+		},
+		{
+			name: "URL entity after non-BMP character",
+			msg: &tg.Message{
+				Message: "😀 https://telegra.ph/Emoji-01-02",
+				Entities: []tg.MessageEntityClass{
+					&tg.MessageEntityURL{Offset: 3, Length: 30},
+				},
+			},
+			want: "https://telegra.ph/Emoji-01-02",
+		},
+		{
+			name: "valid Telegraph URL after invalid candidate",
+			msg: &tg.Message{
+				Message: "https://telegra.ph/nested/Bad https://telegra.ph/Valid-01-02",
+				Entities: []tg.MessageEntityClass{
+					&tg.MessageEntityURL{Offset: 0, Length: 29},
+					&tg.MessageEntityURL{Offset: 30, Length: 30},
+				},
+			},
+			want: "https://telegra.ph/Valid-01-02",
+		},
+		{
+			name: "plain message fallback",
+			msg:  &tg.Message{Message: "read https://telegra.ph/Plain-01-02 now"},
+			want: "https://telegra.ph/Plain-01-02",
+		},
+		{
+			name: "nil message",
+			msg:  nil,
+			want: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := findTelegraphURL(tt.msg); got != tt.want {
+				t.Fatalf("findTelegraphURL() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseTelegraphPagePath(t *testing.T) {
+	tests := []struct {
+		name    string
+		pageURL string
+		want    string
+		wantErr bool
+	}{
+		{
+			name:    "plain path",
+			pageURL: "https://telegra.ph/Example-01-02",
+			want:    "Example-01-02",
+		},
+		{
+			name:    "escaped path with query and fragment",
+			pageURL: "https://telegra.ph/%E6%B5%8B%E8%AF%95-01-02?source=telegram#top",
+			want:    "测试-01-02",
+		},
+		{
+			name:    "trailing slash",
+			pageURL: "https://telegra.ph/Example-01-02/",
+			want:    "Example-01-02",
+		},
+		{
+			name:    "root URL",
+			pageURL: "https://telegra.ph/",
+			wantErr: true,
+		},
+		{
+			name:    "wrong host",
+			pageURL: "https://example.com/Example-01-02",
+			wantErr: true,
+		},
+		{
+			name:    "wrong scheme",
+			pageURL: "http://telegra.ph/Example-01-02",
+			wantErr: true,
+		},
+		{
+			name:    "invalid percent escape",
+			pageURL: "https://telegra.ph/Invalid-%zz",
+			wantErr: true,
+		},
+		{
+			name:    "nested path",
+			pageURL: "https://telegra.ph/nested/Example-01-02",
+			wantErr: true,
+		},
+		{
+			name:    "encoded slash",
+			pageURL: "https://telegra.ph/nested%2FExample-01-02",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseTelegraphPagePath(tt.pageURL)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("parseTelegraphPagePath(%q) returned no error", tt.pageURL)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("parseTelegraphPagePath(%q) failed: %v", tt.pageURL, err)
+			}
+			if got != tt.want {
+				t.Fatalf("parseTelegraphPagePath(%q) = %q, want %q", tt.pageURL, got, tt.want)
+			}
+		})
+	}
+}

client/bot/handlers/utils/shortcut/parsed.go

@@ -18,11 +18,11 @@ import (
 
 func CreateAndAddParsedTaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPath string, item *parser.Item, msgID int, userID int64) error {
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
-	task := parsed.NewTask(xid.New().String(), injectCtx, stor, stor.JoinStoragePath(dirPath), item, parsed.NewProgress(msgID, userID))
+	task := parsed.NewTask(xid.New().String(), injectCtx, stor, dirPath, item, parsed.NewProgress(msgID, userID))
 	if err := core.AddTask(injectCtx, task); err != nil {
 		log.FromContext(ctx).Errorf("Failed to add task: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      msgID,
+			ID: msgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorTaskAddFailed, map[string]any{
 				"Error": err.Error(),
 			}),

client/bot/handlers/utils/shortcut/tftask.go

@@ -8,6 +8,7 @@ import (
 	"github.com/celestix/gotgproto/ext"
 	"github.com/charmbracelet/log"
 	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/conflictutil"
 	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/msgelem"
 	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/ruleutil"
 	"github.com/krau/SaveAny-Bot/common/i18n"
@@ -17,25 +18,29 @@ import (
 	"github.com/krau/SaveAny-Bot/core/tasks/batchtfile"
 	tftask "github.com/krau/SaveAny-Bot/core/tasks/tfile"
 	"github.com/krau/SaveAny-Bot/database"
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+	"github.com/krau/SaveAny-Bot/pkg/tcbdata"
 	"github.com/krau/SaveAny-Bot/pkg/tfile"
 	"github.com/krau/SaveAny-Bot/storage"
 	"github.com/rs/xid"
 )
 
 // 创建一个 tfile.TGFileTask 并添加到任务队列中, 以编辑消息的方式反馈结果
-func CreateAndAddTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage.Storage, dirPath string, file tfile.TGFileMessage, trackMsgID int) error {
+func CreateAndAddTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage.Storage, dirPath string, file tfile.TGFileMessage, trackMsgID int, conflictStrategy ...string) error {
 	logger := log.FromContext(ctx)
+	strategy := selectedConflictStrategy(conflictStrategy)
 	user, err := database.GetUserByChatID(ctx, userID)
 	if err != nil {
 		logger.Errorf("Failed to get user by chat ID: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorGetUserWithErrFailed, map[string]any{
 				"Error": err.Error(),
 			}),
 		})
 		return dispatcher.EndGroups
 	}
+	strategy = conflictutil.ResolveStrategy(user, strategy)
 	if user.ApplyRule && user.Rules != nil {
 		matched, matchedStorageName, matchedDirPath := ruleutil.ApplyRule(ctx, user.Rules, ruleutil.NewInput(file))
 		if !matched {
@@ -49,7 +54,7 @@ func CreateAndAddTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage
 			if err != nil {
 				logger.Errorf("Failed to get storage by user ID and name: %s", err)
 				ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-					ID:      trackMsgID,
+					ID: trackMsgID,
 					Message: i18n.T(i18nk.BotMsgCommonErrorGetStorageFailed, map[string]any{
 						"Error": err.Error(),
 					}),
@@ -59,8 +64,27 @@ func CreateAndAddTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage
 		}
 	}
 startCreateTask:
-	storagePath := stor.JoinStoragePath(path.Join(dirPath, file.Name()))
+	storagePath := path.Join(dirPath, file.Name())
+	if strategy == tcbdata.ConflictStrategyAsk || strategy == tcbdata.ConflictStrategySkip {
+		exists := stor.Exists(ctx, storagePath)
+		if exists && strategy == tcbdata.ConflictStrategyAsk {
+			return promptTGFileConflictStrategy(ctx, userID, stor.Name(), dirPath, []tfile.TGFileMessage{file}, false, []string{conflictutil.FormatPath(stor.Name(), storagePath)}, trackMsgID)
+		}
+		if exists {
+			ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+				ID: trackMsgID,
+				Message: i18n.T(i18nk.BotMsgCommonInfoAllConflictFilesSkipped, map[string]any{
+					"Skipped": file.Name(),
+				}),
+				ReplyMarkup: nil,
+			})
+			return dispatcher.EndGroups
+		}
+	}
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
+	if strategy == tcbdata.ConflictStrategyOverwrite {
+		injectCtx = storage.WithOverwrite(injectCtx)
+	}
 	taskid := xid.New().String()
 	task, err := tftask.NewTGFileTask(taskid, injectCtx, file, stor, storagePath,
 		tftask.NewProgressTrack(
@@ -69,7 +93,7 @@ startCreateTask:
 	if err != nil {
 		logger.Errorf("create task failed: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorTaskCreateFailed, map[string]any{
 				"Error": err.Error(),
 			}),
@@ -79,7 +103,7 @@ startCreateTask:
 	if err := core.AddTask(injectCtx, task); err != nil {
 		logger.Errorf("add task failed: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorTaskAddFailed, map[string]any{
 				"Error": err.Error(),
 			}),
@@ -97,19 +121,21 @@ startCreateTask:
 }
 
 // 创建一个 batchtfile.BatchTGFileTask 并添加到任务队列中, 以编辑消息的方式反馈结果
-func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage.Storage, dirPath string, files []tfile.TGFileMessage, trackMsgID int) error {
+func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor storage.Storage, dirPath string, files []tfile.TGFileMessage, trackMsgID int, conflictStrategy ...string) error {
 	logger := log.FromContext(ctx)
+	strategy := selectedConflictStrategy(conflictStrategy)
 	user, err := database.GetUserByChatID(ctx, userID)
 	if err != nil {
 		logger.Errorf("Failed to get user by chat ID: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorGetUserWithErrFailed, map[string]any{
 				"Error": err.Error(),
 			}),
 		})
 		return dispatcher.EndGroups
 	}
+	strategy = conflictutil.ResolveStrategy(user, strategy)
 
 	useRule := user.ApplyRule && user.Rules != nil
 
@@ -128,21 +154,24 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 		return storname, dirP
 	}
 
+	skipped := make([]string, 0)
+	conflicts := make([]string, 0)
 	elems := make([]batchtfile.TaskElement, 0, len(files))
 	type albumFile struct {
 		file    tfile.TGFileMessage
 		storage storage.Storage
+		dirPath string
 	}
 	albumFiles := make(map[int64][]albumFile, 0)
 	for _, file := range files {
-		storName, dirPath := applyRule(file)
+		storName, matchedDirPath := applyRule(file)
 		fileStor := stor
 		if storName != stor.Name() && storName != "" {
 			fileStor, err = storage.GetStorageByUserIDAndName(ctx, user.ChatID, storName)
 			if err != nil {
 				logger.Errorf("Failed to get storage by user ID and name: %s", err)
 				ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-					ID:      trackMsgID,
+					ID: trackMsgID,
 					Message: i18n.T(i18nk.BotMsgCommonErrorGetStorageFailed, map[string]any{
 						"Error": err.Error(),
 					}),
@@ -150,16 +179,27 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 				return dispatcher.EndGroups
 			}
 		}
-		if !dirPath.NeedNewForAlbum() {
-			storPath := fileStor.JoinStoragePath(path.Join(dirPath.String(), file.Name()))
+		if !matchedDirPath.NeedNewForAlbum() {
+			storPath := path.Join(matchedDirPath.String(), file.Name())
+			if strategy == tcbdata.ConflictStrategyAsk || strategy == tcbdata.ConflictStrategySkip {
+				exists := fileStor.Exists(ctx, storPath)
+				if exists && strategy == tcbdata.ConflictStrategyAsk {
+					conflicts = append(conflicts, conflictutil.FormatPath(fileStor.Name(), storPath))
+					continue
+				}
+				if exists {
+					skipped = append(skipped, file.Name())
+					continue
+				}
+			}
 			elem, err := batchtfile.NewTaskElement(fileStor, storPath, file)
 			if err != nil {
 				logger.Errorf("Failed to create task element: %s", err)
 				ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-					ID:      trackMsgID,
-						Message: i18n.T(i18nk.BotMsgCommonErrorTaskCreateFailed, map[string]any{
-							"Error": err.Error(),
-						}),
+					ID: trackMsgID,
+					Message: i18n.T(i18nk.BotMsgCommonErrorTaskCreateFailed, map[string]any{
+						"Error": err.Error(),
+					}),
 				})
 				return dispatcher.EndGroups
 			}
@@ -170,12 +210,17 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 				logger.Warnf("File %s is not in a group, skipping album handling", file.Name())
 				continue
 			}
+			fileDirPath := matchedDirPath.String()
+			if matchedDirPath.NeedNewForAlbum() {
+				fileDirPath = dirPath
+			}
 			if _, ok := albumFiles[groupId]; !ok {
 				albumFiles[groupId] = make([]albumFile, 0)
 			}
 			albumFiles[groupId] = append(albumFiles[groupId], albumFile{
 				file:    file,
 				storage: fileStor,
+				dirPath: fileDirPath,
 			})
 		}
 	}
@@ -188,12 +233,23 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 		albumDir := strings.TrimSuffix(path.Base(afiles[0].file.Name()), path.Ext(afiles[0].file.Name()))
 		albumStor := afiles[0].storage
 		for _, af := range afiles {
-			afstorPath := af.storage.JoinStoragePath(path.Join(dirPath, albumDir, af.file.Name()))
+			afstorPath := path.Join(af.dirPath, albumDir, af.file.Name())
+			if strategy == tcbdata.ConflictStrategyAsk || strategy == tcbdata.ConflictStrategySkip {
+				exists := albumStor.Exists(ctx, afstorPath)
+				if exists && strategy == tcbdata.ConflictStrategyAsk {
+					conflicts = append(conflicts, conflictutil.FormatPath(albumStor.Name(), afstorPath))
+					continue
+				}
+				if exists {
+					skipped = append(skipped, af.file.Name())
+					continue
+				}
+			}
 			elem, err := batchtfile.NewTaskElement(albumStor, afstorPath, af.file)
 			if err != nil {
 				logger.Errorf("Failed to create task element for album file: %s", err)
 				ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-					ID:      trackMsgID,
+					ID: trackMsgID,
 					Message: i18n.T(i18nk.BotMsgCommonErrorTaskCreateFailed, map[string]any{
 						"Error": err.Error(),
 					}),
@@ -204,13 +260,30 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 		}
 	}
 
+	if strategy == tcbdata.ConflictStrategyAsk && len(conflicts) > 0 {
+		return promptTGFileConflictStrategy(ctx, userID, stor.Name(), dirPath, files, true, conflicts, trackMsgID)
+	}
+
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
+	if strategy == tcbdata.ConflictStrategyOverwrite {
+		injectCtx = storage.WithOverwrite(injectCtx)
+	}
+	if len(elems) == 0 {
+		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+			ID: trackMsgID,
+			Message: i18n.T(i18nk.BotMsgCommonInfoAllConflictFilesSkipped, map[string]any{
+				"Skipped": strings.Join(skipped, "\n"),
+			}),
+			ReplyMarkup: nil,
+		})
+		return dispatcher.EndGroups
+	}
 	taskid := xid.New().String()
-	task := batchtfile.NewBatchTGFileTask(taskid, injectCtx, elems, batchtfile.NewProgressTracker(trackMsgID, userID), true)
+	task := batchtfile.NewBatchTGFileTask(taskid, injectCtx, elems, batchtfile.NewProgressTrackerWithSkipped(trackMsgID, userID, skipped), true)
 	if err := core.AddTask(injectCtx, task); err != nil {
 		logger.Errorf("Failed to add batch task: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorTaskAddFailed, map[string]any{
 				"Error": err.Error(),
 			}),
@@ -219,10 +292,47 @@ func CreateAndAddBatchTGFileTaskWithEdit(ctx *ext.Context, userID int64, stor st
 	}
 	ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
 		ID:          trackMsgID,
-		Message:     i18n.T(i18nk.BotMsgCommonInfoBatchTasksAdded, map[string]any{
-			"Count": len(files),
-		}),
+		Message:     buildBatchAddedMessage(len(elems), skipped),
 		ReplyMarkup: nil,
 	})
 	return dispatcher.EndGroups
 }
+
+func promptTGFileConflictStrategy(ctx *ext.Context, userID int64, storageName, dirPath string, files []tfile.TGFileMessage, asBatch bool, conflicts []string, trackMsgID int) error {
+	markup, err := msgelem.BuildConflictStrategyMarkup(tcbdata.Add{
+		TaskType:         tasktype.TaskTypeTgfiles,
+		SelectedStorName: storageName,
+		SettedDir:        true,
+		SelectedDirPath:  dirPath,
+		Files:            files,
+		AsBatch:          asBatch,
+	})
+	if err != nil {
+		return err
+	}
+	ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
+		ID:          trackMsgID,
+		Message:     i18n.T(i18nk.BotMsgCommonPromptSelectConflictStrategy, map[string]any{"Files": conflictutil.FormatPaths(conflicts)}),
+		ReplyMarkup: markup,
+	})
+	return dispatcher.EndGroups
+}
+
+func selectedConflictStrategy(strategies []string) string {
+	if len(strategies) == 0 {
+		return ""
+	}
+	return strategies[0]
+}
+
+func buildBatchAddedMessage(count int, skipped []string) string {
+	if len(skipped) == 0 {
+		return i18n.T(i18nk.BotMsgCommonInfoBatchTasksAdded, map[string]any{
+			"Count": count,
+		})
+	}
+	return i18n.T(i18nk.BotMsgCommonInfoBatchTasksAddedWithSkipped, map[string]any{
+		"Count":   count,
+		"Skipped": strings.Join(skipped, "\n"),
+	})
+}

client/bot/handlers/utils/shortcut/tphtask.go

@@ -25,21 +25,21 @@ func CreateAndAddtelegraphWithEdit(
 	pics []string,
 	stor storage.Storage,
 	trackMsgID int) error {
-		
+
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
 	task := tphtask.NewTask(xid.New().String(),
 		injectCtx,
 		tphpage.Path,
 		pics,
 		stor,
-		stor.JoinStoragePath(dirPath),
+		dirPath,
 		tphutil.DefaultClient(),
 		tphtask.NewProgress(trackMsgID, userID),
 	)
 	if err := core.AddTask(injectCtx, task); err != nil {
 		log.FromContext(ctx).Errorf("Failed to add task: %s", err)
 		ctx.EditMessage(userID, &tg.MessagesEditMessageRequest{
-			ID:      trackMsgID,
+			ID: trackMsgID,
 			Message: i18n.T(i18nk.BotMsgCommonErrorTaskAddFailed, map[string]any{
 				"Error": err.Error(),
 			}),

client/bot/handlers/utils/shortcut/ytdlp.go

@@ -15,7 +15,7 @@ import (
 	"github.com/krau/SaveAny-Bot/storage"
 )
 
-func CreateAndAddYtdlpTaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPath string, urls []string, msgID int, userID int64) error {
+func CreateAndAddYtdlpTaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPath string, urls []string, flags []string, msgID int, userID int64) error {
 	logger := log.FromContext(ctx)
 	injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
 
@@ -29,15 +29,16 @@ func CreateAndAddYtdlpTaskWithEdit(ctx *ext.Context, stor storage.Storage, dirPa
 		return dispatcher.EndGroups
 	}
 
-	logger.Infof("Creating yt-dlp task for %d URL(s)", len(urls))
+	logger.Infof("Creating yt-dlp task for %d URL(s) with %d flag(s)", len(urls), len(flags))
 
 	// Create yt-dlp task
 	task := ytdlp.NewTask(
 		xid.New().String(),
 		injectCtx,
 		urls,
+		flags,
 		stor,
-		stor.JoinStoragePath(dirPath),
+		dirPath,
 		ytdlp.NewProgress(msgID, userID),
 	)
 

client/bot/handlers/watch.go

@@ -252,6 +252,16 @@ func listenMediaMessageEvent(ch chan userclient.MediaMessageEvent) {
 				logger.Errorf("Failed to get storage by user ID %d and name %s: %v", user.ChatID, user.DefaultStorage, err)
 				continue
 			}
+			// Resolve the default directory path from user.DefaultDir
+			var defaultDirPath string
+			if user.DefaultDir != 0 {
+				dir, err := database.GetDirByID(ctx, user.DefaultDir)
+				if err != nil {
+					logger.Warnf("Failed to get default dir for user %d: %v, using root", user.ChatID, err)
+				} else {
+					defaultDirPath = dir.Path
+				}
+			}
 			switch user.FilenameStrategy {
 			case fnamest.Message.String():
 				file.SetName(tgutil.GenFileNameFromMessage(*file.Message()))
@@ -286,14 +296,14 @@ func listenMediaMessageEvent(ch chan userclient.MediaMessageEvent) {
 
 			if needAlbumHandling {
 				// For media groups with NEW-FOR-ALBUM rule, collect all files of the same group
-				watchMediaGroupMgr.addFile(event.ChatID, user.ID, file, time.Duration(config.C().Telegram.MediaGroupTimeout)*time.Second, func(files []tfile.TGFileMessage) {
-					processWatchMediaGroup(ctx, user, stor, "", files)
+				watchMediaGroupMgr.addFile(event.ChatID, user.ID, file, time.Duration(max(config.C().Telegram.MediaGroupTimeout, 1))*time.Second, func(files []tfile.TGFileMessage) {
+					processWatchMediaGroup(ctx, user, stor, defaultDirPath, files)
 				})
 				continue
 			}
 
 			// Process single file or media group without album folder creation
-			var dirPath string
+			dirPath := defaultDirPath
 			if user.ApplyRule && user.Rules != nil {
 				matched, matchedStorageName, matchedDirPath := ruleutil.ApplyRule(ctx, user.Rules, ruleutil.NewInput(file))
 				if !matched {
@@ -309,7 +319,7 @@ func listenMediaMessageEvent(ch chan userclient.MediaMessageEvent) {
 				}
 			}
 		startCreateTask:
-			storagePath := stor.JoinStoragePath(path.Join(dirPath, file.Name()))
+			storagePath := path.Join(dirPath, file.Name())
 			injectCtx := tgutil.ExtWithContext(ctx.Context, ctx)
 			taskid := xid.New().String()
 			task, err := coretfile.NewTGFileTask(taskid, injectCtx, file, stor, storagePath, nil)
@@ -352,6 +362,7 @@ func processWatchMediaGroup(ctx *ext.Context, user *database.User, stor storage.
 	type albumFile struct {
 		file    tfile.TGFileMessage
 		storage storage.Storage
+		dirPath string
 	}
 	albumFiles := make(map[int64][]albumFile)
 
@@ -374,9 +385,11 @@ func processWatchMediaGroup(ctx *ext.Context, user *database.User, stor storage.
 			continue
 		}
 
-		if !ruleDirPath.NeedNewForAlbum() {
-			logger.Warnf("File %s does not need album folder, skipping", file.Name())
-			continue
+		// Use the effective dirPath: if rule returns NEW-FOR-ALBUM sentinel, fall back to the
+		// base dirPath passed in (which is defaultDirPath from the caller).
+		effectiveDirPath := string(ruleDirPath)
+		if ruleDirPath.NeedNewForAlbum() {
+			effectiveDirPath = dirPath
 		}
 
 		if _, ok := albumFiles[groupId]; !ok {
@@ -385,6 +398,7 @@ func processWatchMediaGroup(ctx *ext.Context, user *database.User, stor storage.
 		albumFiles[groupId] = append(albumFiles[groupId], albumFile{
 			file:    file,
 			storage: fileStor,
+			dirPath: effectiveDirPath,
 		})
 	}
 
@@ -403,7 +417,7 @@ func processWatchMediaGroup(ctx *ext.Context, user *database.User, stor storage.
 		logger.Infof("Creating album folder for group %d: %s with %d files", groupID, albumDir, len(afiles))
 
 		for _, af := range afiles {
-			afstorPath := af.storage.JoinStoragePath(path.Join(dirPath, albumDir, af.file.Name()))
+			afstorPath := path.Join(af.dirPath, albumDir, af.file.Name())
 			taskid := xid.New().String()
 			task, err := coretfile.NewTGFileTask(taskid, injectCtx, af.file, albumStor, afstorPath, nil)
 			if err != nil {

client/bot/handlers/ytdlp.go

@@ -7,7 +7,6 @@ import (
 	"github.com/celestix/gotgproto/dispatcher"
 	"github.com/celestix/gotgproto/ext"
 	"github.com/charmbracelet/log"
-	"github.com/duke-git/lancet/v2/slice"
 
 	"github.com/krau/SaveAny-Bot/client/bot/handlers/utils/msgelem"
 	"github.com/krau/SaveAny-Bot/common/i18n"
@@ -25,29 +24,59 @@ func handleYtdlpCmd(ctx *ext.Context, update *ext.Update) error {
 		return dispatcher.EndGroups
 	}
 
-	urls := args[1:]
-	// Validate and clean URLs
-	for i, link := range urls {
-		urls[i] = strings.TrimSpace(link)
-		u, err := url.Parse(link)
-		if err != nil || u.Scheme == "" || u.Host == "" {
-			logger.Warnf("Invalid URL: %s", link)
-			urls[i] = ""
+	// Separate URLs and flags from arguments
+	var urls []string
+	var flags []string
+
+	for i := 1; i < len(args); i++ {
+		arg := strings.TrimSpace(args[i])
+		if arg == "" {
+			continue
+		}
+
+		// Check if it's a flag (starts with - or --)
+		if strings.HasPrefix(arg, "-") {
+			flags = append(flags, arg)
+			// Check if the next argument might be a value for this flag
+			// Don't consume it if it starts with - or looks like a URL with scheme
+			if i+1 < len(args) {
+				nextArg := strings.TrimSpace(args[i+1])
+				if nextArg != "" && !strings.HasPrefix(nextArg, "-") {
+					// Check if it's clearly a URL (has ://)
+					// This handles common video URLs (http://, https://)
+					// For other yt-dlp inputs, users should ensure proper formatting
+					if strings.Contains(nextArg, "://") {
+						// It's a URL, don't consume it as a flag value
+						continue
+					}
+					// Otherwise, treat it as a flag value
+					flags = append(flags, nextArg)
+					i++ // Skip the next argument as it's been consumed
+				}
+			}
+		} else {
+			// Try to parse as URL
+			u, err := url.Parse(arg)
+			if err != nil || u.Scheme == "" || u.Host == "" {
+				logger.Warnf("Invalid URL: %s", arg)
+				continue
+			}
+			urls = append(urls, arg)
 		}
 	}
-	urls = slice.Compact(urls)
 
 	if len(urls) == 0 {
 		ctx.Reply(update, ext.ReplyTextString(i18n.T(i18nk.BotMsgYtdlpErrorNoValidUrls)), nil)
 		return dispatcher.EndGroups
 	}
 
-	logger.Debugf("Preparing yt-dlp download for %d URL(s)", len(urls))
+	logger.Debugf("Preparing yt-dlp download for %d URL(s) with %d flag(s)", len(urls), len(flags))
 
 	// Build storage selection keyboard
 	markup, err := msgelem.BuildAddSelectStorageKeyboard(storage.GetUserStorages(ctx, update.GetUserChat().GetID()), tcbdata.Add{
-		TaskType:  tasktype.TaskTypeYtdlp,
-		YtdlpURLs: urls,
+		TaskType:   tasktype.TaskTypeYtdlp,
+		YtdlpURLs:  urls,
+		YtdlpFlags: flags,
 	})
 	if err != nil {
 		return err

client/bot/handlers/ytdlp_test.go

@@ -0,0 +1,129 @@
+package handlers
+
+import (
+	"net/url"
+	"strings"
+	"testing"
+)
+
+// TestYtdlpArgumentParsing tests the URL and flag separation logic
+func TestYtdlpArgumentParsing(t *testing.T) {
+	tests := []struct {
+		name          string
+		input         string
+		expectedURLs  []string
+		expectedFlags []string
+	}{
+		{
+			name:          "Single URL without flags",
+			input:         "/ytdlp https://example.com/video",
+			expectedURLs:  []string{"https://example.com/video"},
+			expectedFlags: []string{},
+		},
+		{
+			name:          "Multiple URLs without flags",
+			input:         "/ytdlp https://example.com/v1 https://example.com/v2",
+			expectedURLs:  []string{"https://example.com/v1", "https://example.com/v2"},
+			expectedFlags: []string{},
+		},
+		{
+			name:          "URL with format flag",
+			input:         "/ytdlp --format best https://example.com/video",
+			expectedURLs:  []string{"https://example.com/video"},
+			expectedFlags: []string{"--format", "best"},
+		},
+		{
+			name:          "URL with extract-audio flag",
+			input:         "/ytdlp --extract-audio --audio-format mp3 https://example.com/video",
+			expectedURLs:  []string{"https://example.com/video"},
+			expectedFlags: []string{"--extract-audio", "--audio-format", "mp3"},
+		},
+		{
+			name:          "Multiple URLs with flags",
+			input:         "/ytdlp --format best https://example.com/v1 https://example.com/v2",
+			expectedURLs:  []string{"https://example.com/v1", "https://example.com/v2"},
+			expectedFlags: []string{"--format", "best"},
+		},
+		{
+			name:          "Flags mixed with URLs",
+			input:         "/ytdlp https://example.com/v1 --format best https://example.com/v2",
+			expectedURLs:  []string{"https://example.com/v1", "https://example.com/v2"},
+			expectedFlags: []string{"--format", "best"},
+		},
+		{
+			name:          "Short flag",
+			input:         "/ytdlp -f best https://example.com/video",
+			expectedURLs:  []string{"https://example.com/video"},
+			expectedFlags: []string{"-f", "best"},
+		},
+		{
+			name:          "Boolean flag",
+			input:         "/ytdlp --extract-audio https://example.com/video",
+			expectedURLs:  []string{"https://example.com/video"},
+			expectedFlags: []string{"--extract-audio"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			args := strings.Split(tt.input, " ")
+
+			// Simulate the parsing logic from handleYtdlpCmd
+			var urls []string
+			var flags []string
+
+			for i := 1; i < len(args); i++ {
+				arg := strings.TrimSpace(args[i])
+				if arg == "" {
+					continue
+				}
+
+				// Check if it's a flag (starts with - or --)
+				if strings.HasPrefix(arg, "-") {
+					flags = append(flags, arg)
+					// Check if the next argument might be a value for this flag
+					if i+1 < len(args) {
+						nextArg := strings.TrimSpace(args[i+1])
+						if nextArg != "" && !strings.HasPrefix(nextArg, "-") {
+							// Check if it's clearly a URL (has ://)
+							if strings.Contains(nextArg, "://") {
+								// It's a URL, don't consume it as a flag value
+								continue
+							}
+							// Otherwise, treat it as a flag value
+							flags = append(flags, nextArg)
+							i++ // Skip the next argument as it's been consumed
+						}
+					}
+				} else {
+					// Try to parse as URL
+					u, err := url.Parse(arg)
+					if err != nil || u.Scheme == "" || u.Host == "" {
+						continue
+					}
+					urls = append(urls, arg)
+				}
+			}
+
+			// Verify URLs
+			if len(urls) != len(tt.expectedURLs) {
+				t.Errorf("Expected %d URLs, got %d", len(tt.expectedURLs), len(urls))
+			}
+			for i, expectedURL := range tt.expectedURLs {
+				if i >= len(urls) || urls[i] != expectedURL {
+					t.Errorf("Expected URL[%d] to be '%s', got '%s'", i, expectedURL, urls[i])
+				}
+			}
+
+			// Verify flags
+			if len(flags) != len(tt.expectedFlags) {
+				t.Errorf("Expected %d flags, got %d", len(tt.expectedFlags), len(flags))
+			}
+			for i, expectedFlag := range tt.expectedFlags {
+				if i >= len(flags) || flags[i] != expectedFlag {
+					t.Errorf("Expected flag[%d] to be '%s', got '%s'", i, expectedFlag, flags[i])
+				}
+			}
+		})
+	}
+}

client/middleware/default.go

@@ -15,7 +15,7 @@ import (
 // https://github.com/iyear/tdl/blob/master/core/tclient/tclient.go
 func NewDefaultMiddlewares(ctx context.Context, timeout time.Duration) []telegram.Middleware {
 	return []telegram.Middleware{
-		recovery.New(ctx, newBackoff(timeout)),
+		recovery.New(ctx, func() backoff.BackOff { return newBackoff(timeout) }),
 		retry.New(config.C().Telegram.RpcRetry),
 		floodwait.NewSimpleWaiter(),
 	}

client/middleware/recovery/recovery.go

@@ -14,19 +14,28 @@ import (
 )
 
 type recovery struct {
-	ctx     context.Context
-	backoff backoff.BackOff
+	ctx        context.Context
+	newBackoff func() backoff.BackOff
 }
 
-func New(ctx context.Context, backoff backoff.BackOff) telegram.Middleware {
+// New returns a recovery middleware.
+//
+// newBackoff is a factory that must return a fresh backoff.BackOff on every call: backoff implementations in
+// cenkalti/backoff/v4 (notably ExponentialBackOff) are not safe for concurrent
+// use, and the Telegram client invokes RPCs from many goroutines in parallel.
+//
+// Sharing a single instance corrupts its internal counters, breaks the
+// exponential interval, and defeats MaxElapsedTime - see issue #218.
+func New(ctx context.Context, newBackoff func() backoff.BackOff) telegram.Middleware {
 	return &recovery{
-		ctx:     ctx,
-		backoff: backoff,
+		ctx:        ctx,
+		newBackoff: newBackoff,
 	}
 }
 
 func (r *recovery) Handle(next tg.Invoker) telegram.InvokeFunc {
 	return func(ctx context.Context, input bin.Encoder, output bin.Decoder) error {
+		b := r.newBackoff()
 
 		return backoff.RetryNotify(func() error {
 			if err := next.Invoke(ctx, input, output); err != nil {
@@ -38,7 +47,7 @@ func (r *recovery) Handle(next tg.Invoker) telegram.InvokeFunc {
 			}
 
 			return nil
-		}, r.backoff, func(err error, duration time.Duration) {
+		}, b, func(err error, duration time.Duration) {
 			log.FromContext(ctx).Debug("Wait for connection recovery", "error", err, "duration", duration)
 		})
 	}

cmd/root.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"github.com/krau/SaveAny-Bot/cmd/upload"
+	"github.com/krau/SaveAny-Bot/cmd/watch"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/spf13/cobra"
 )
@@ -18,6 +19,7 @@ var rootCmd = &cobra.Command{
 func init() {
 	config.RegisterFlags(rootCmd)
 	upload.Register(rootCmd)
+	watch.Register(rootCmd)
 }
 
 func Execute(ctx context.Context) {

cmd/run.go

@@ -2,9 +2,9 @@ package cmd
 
 import (
 	"context"
-	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"time"
 
 	"slices"
@@ -27,14 +27,27 @@ import (
 func Run(cmd *cobra.Command, _ []string) {
 	ctx, cancel := context.WithCancel(cmd.Context())
 	logger := log.NewWithOptions(os.Stdout, log.Options{
-		Level:           log.DebugLevel,
+		Level:           log.InfoLevel,
 		ReportTimestamp: true,
 		TimeFormat:      time.TimeOnly,
 		ReportCaller:    true,
 	})
+	log.SetDefault(logger)
 	ctx = log.WithContext(ctx, logger)
 
-	exitChan, err := initAll(ctx, cmd)
+	configFile := config.GetConfigFile(cmd)
+	if err := config.Init(ctx, configFile); err != nil {
+		logger.Fatal("Init failed", "error", err)
+	}
+
+	level, err := log.ParseLevel(strings.TrimSpace(config.C().Log.Level))
+	if err != nil {
+		logger.Warn("Invalid log level, fallback to debug", "level", config.C().Log.Level, "error", err)
+		level = log.DebugLevel
+	}
+	logger.SetLevel(level)
+
+	exitChan, err := initAll(ctx)
 	if err != nil {
 		logger.Fatal("Init failed", "error", err)
 	}
@@ -51,11 +64,7 @@ func Run(cmd *cobra.Command, _ []string) {
 	cleanCache()
 }
 
-func initAll(ctx context.Context, cmd *cobra.Command) (<-chan struct{}, error) {
-	configFile := config.GetConfigFile(cmd)
-	if err := config.Init(ctx, configFile); err != nil {
-		return nil, fmt.Errorf("failed to load config: %w", err)
-	}
+func initAll(ctx context.Context) (<-chan struct{}, error) {
 	cache.Init()
 	logger := log.FromContext(ctx)
 	i18n.Init(config.C().Lang)
@@ -77,11 +86,10 @@ func initAll(ctx context.Context, cmd *cobra.Command) (<-chan struct{}, error) {
 			logger.Fatal("User login failed", "error", err)
 		}
 	}
-	exitChan := bot.Init(ctx)
-	if err := api.Init(ctx); err != nil {
-		return nil, fmt.Errorf("failed to init API server: %w", err)
+	if err := api.Start(ctx); err != nil {
+		logger.Error("Failed to start API server", "error", err)
 	}
-	return exitChan, nil
+	return bot.Init(ctx), nil
 }
 
 func cleanCache() {

cmd/upload/cmd.go

@@ -90,7 +90,7 @@ func Upload(cmd *cobra.Command, args []string) error {
 	fileName := fileInfo.Name()
 	fileSize := fileInfo.Size()
 
-	uploadPath := stor.JoinStoragePath(path.Join(dirPath, fileName))
+	uploadPath := path.Join(dirPath, fileName)
 
 	ctx = context.WithValue(ctx, ctxkey.ContentLength, fileSize)
 	ctx = tgutil.ExtWithContext(ctx, bot.ExtContext())

cmd/watch/cmd.go

@@ -0,0 +1,145 @@
+package watch
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/charmbracelet/log"
+	"github.com/krau/SaveAny-Bot/client/bot"
+	"github.com/krau/SaveAny-Bot/common/cache"
+	"github.com/krau/SaveAny-Bot/common/i18n"
+	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
+	"github.com/krau/SaveAny-Bot/config"
+	"github.com/krau/SaveAny-Bot/database"
+	stortype "github.com/krau/SaveAny-Bot/pkg/enums/storage"
+	"github.com/krau/SaveAny-Bot/storage"
+	"github.com/spf13/cobra"
+)
+
+var watchCmd = &cobra.Command{
+	Use:   "watch",
+	Short: "watch a local directory and auto-upload changed files to storage",
+	Long: `Watch a local directory and automatically upload created or modified files
+to the specified storage backend, preserving the relative directory structure.
+
+Example:
+  saveany-bot watch -p /data/inbox -s mystorage -d backup --recursive`,
+	RunE: runWatch,
+}
+
+func Register(root *cobra.Command) {
+	flags := watchCmd.Flags()
+	flags.StringP("path", "p", "", "local directory path to watch")
+	watchCmd.MarkFlagRequired("path")
+	flags.StringP("storage", "s", "", "storage name to upload to")
+	watchCmd.MarkFlagRequired("storage")
+	flags.StringP("dir", "d", "", "storage dir to upload to, default is the base_path of the storage")
+	flags.BoolP("recursive", "r", false, "watch subdirectories recursively")
+	flags.Bool("overwrite", false, "overwrite existing files on storage instead of skipping")
+	flags.Bool("initial-scan", false, "upload existing files in the directory on startup")
+	flags.Duration("debounce", 2*time.Second, "wait time after the last change before uploading a file")
+	flags.Int("upload-workers", 0, "number of concurrent uploads, default is config.workers")
+	flags.Duration("retry-delay", 3*time.Second, "delay between upload retries")
+	root.AddCommand(watchCmd)
+}
+
+func runWatch(cmd *cobra.Command, _ []string) error {
+	watchPath, err := cmd.Flags().GetString("path")
+	if err != nil {
+		return err
+	}
+	storName, err := cmd.Flags().GetString("storage")
+	if err != nil {
+		return err
+	}
+	destDir, err := cmd.Flags().GetString("dir")
+	if err != nil {
+		return err
+	}
+	recursive, err := cmd.Flags().GetBool("recursive")
+	if err != nil {
+		return err
+	}
+	overwrite, err := cmd.Flags().GetBool("overwrite")
+	if err != nil {
+		return err
+	}
+	initialScan, err := cmd.Flags().GetBool("initial-scan")
+	if err != nil {
+		return err
+	}
+	debounce, err := cmd.Flags().GetDuration("debounce")
+	if err != nil {
+		return err
+	}
+	uploadWorkers, err := cmd.Flags().GetInt("upload-workers")
+	if err != nil {
+		return err
+	}
+	retryDelay, err := cmd.Flags().GetDuration("retry-delay")
+	if err != nil {
+		return err
+	}
+
+	ctx := cmd.Context()
+	logger := log.FromContext(ctx)
+
+	configFile := config.GetConfigFile(cmd)
+	if err := config.Init(ctx, configFile); err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+	i18n.Init(config.C().Lang)
+	cache.Init()
+	database.Init(ctx)
+
+	stor, err := storage.GetStorageByName(ctx, storName)
+	if err != nil {
+		return fmt.Errorf("failed to get storage %q: %w", storName, err)
+	}
+
+	// Telegram storage needs the bot client and its ext context injected into ctx.
+	if stor.Type() == stortype.Telegram {
+		bot.Init(ctx)
+		ctx = tgutil.ExtWithContext(ctx, bot.ExtContext())
+	}
+
+	if uploadWorkers < 1 {
+		uploadWorkers = config.C().Workers
+	}
+
+	uploader := NewUploader(ctx, UploaderOptions{
+		Storage:    stor,
+		DestDir:    destDir,
+		Overwrite:  overwrite,
+		Workers:    uploadWorkers,
+		Retry:      config.C().Retry,
+		RetryDelay: retryDelay,
+	})
+
+	watcher, err := NewWatcher(ctx, WatcherOptions{
+		Root:      watchPath,
+		Recursive: recursive,
+		Debounce:  debounce,
+		Uploader:  uploader,
+	})
+	if err != nil {
+		uploader.Close()
+		return fmt.Errorf("failed to create watcher: %w", err)
+	}
+
+	if initialScan {
+		watcher.ScanExisting(ctx)
+	}
+
+	logger.Infof("watch started: %s -> storage %q dir %q", watchPath, storName, destDir)
+
+	// Run blocks until ctx is cancelled (e.g. SIGINT).
+	runErr := watcher.Run(ctx)
+
+	// Wait for in-flight uploads to finish before exiting.
+	logger.Info("waiting for in-flight uploads to finish...")
+	uploader.Close()
+	logger.Info("watch stopped")
+
+	return runErr
+}

cmd/watch/uploader.go

@@ -0,0 +1,227 @@
+package watch
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/charmbracelet/log"
+	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/storage"
+)
+
+type uploadJob struct {
+	// localPath is the absolute path of the local file.
+	localPath string
+	// relPath is relative to the watch root, used to preserve directory structure on storage.
+	relPath string
+}
+
+// Uploader uploads local files to the target storage via a worker pool.
+// If a file changes while being uploaded, it is re-uploaded once after the
+// current upload finishes, instead of being queued multiple times.
+type Uploader struct {
+	stor       storage.Storage
+	destDir    string
+	overwrite  bool
+	retry      int
+	retryDelay time.Duration
+	logger     *log.Logger
+
+	jobs chan uploadJob
+	wg   sync.WaitGroup
+
+	mu sync.Mutex
+	// inflight maps in-progress (or queued) file paths. A true value means the
+	// file changed during upload and must be re-queued once done.
+	inflight map[string]bool
+}
+
+type UploaderOptions struct {
+	Storage    storage.Storage
+	DestDir    string
+	Overwrite  bool
+	Workers    int
+	Retry      int
+	RetryDelay time.Duration
+	QueueSize  int
+}
+
+// NewUploader creates and starts an Uploader. The caller must call Close when done.
+func NewUploader(ctx context.Context, opts UploaderOptions) *Uploader {
+	if opts.Workers < 1 {
+		opts.Workers = 1
+	}
+	if opts.Retry < 1 {
+		opts.Retry = 1
+	}
+	if opts.RetryDelay <= 0 {
+		opts.RetryDelay = 3 * time.Second
+	}
+	if opts.QueueSize < opts.Workers {
+		opts.QueueSize = opts.Workers * 64
+	}
+
+	u := &Uploader{
+		stor:       opts.Storage,
+		destDir:    opts.DestDir,
+		overwrite:  opts.Overwrite,
+		retry:      opts.Retry,
+		retryDelay: opts.RetryDelay,
+		logger:     log.FromContext(ctx).WithPrefix("uploader"),
+		jobs:       make(chan uploadJob, opts.QueueSize),
+		inflight:   make(map[string]bool),
+	}
+
+	for i := 0; i < opts.Workers; i++ {
+		u.wg.Add(1)
+		go u.worker(ctx)
+	}
+
+	return u
+}
+
+// Submit enqueues an upload job. If the same file is already in flight, it is
+// marked for re-upload instead of being queued again. Returns false if ctx is
+// cancelled before the job can be enqueued.
+func (u *Uploader) Submit(ctx context.Context, job uploadJob) bool {
+	u.mu.Lock()
+	if _, ok := u.inflight[job.localPath]; ok {
+		u.inflight[job.localPath] = true
+		u.mu.Unlock()
+		u.logger.Debugf("file %s already in flight, marked for re-upload", job.localPath)
+		return true
+	}
+	u.inflight[job.localPath] = false
+	u.mu.Unlock()
+
+	select {
+	case u.jobs <- job:
+		return true
+	case <-ctx.Done():
+		u.mu.Lock()
+		delete(u.inflight, job.localPath)
+		u.mu.Unlock()
+		return false
+	}
+}
+
+func (u *Uploader) worker(ctx context.Context) {
+	defer u.wg.Done()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case job, ok := <-u.jobs:
+			if !ok {
+				return
+			}
+			u.process(ctx, job)
+		}
+	}
+}
+
+func (u *Uploader) process(ctx context.Context, job uploadJob) {
+	if err := u.uploadWithRetry(ctx, job); err != nil {
+		if ctx.Err() != nil {
+			u.clearInflight(job.localPath)
+			return
+		}
+		u.logger.Errorf("failed to upload %s after %d attempt(s): %v", job.localPath, u.retry, err)
+	}
+
+	// Re-queue if the file changed again while it was being uploaded.
+	u.mu.Lock()
+	needReupload := u.inflight[job.localPath]
+	if needReupload {
+		u.inflight[job.localPath] = false
+	} else {
+		delete(u.inflight, job.localPath)
+	}
+	u.mu.Unlock()
+
+	if needReupload {
+		select {
+		case u.jobs <- job:
+			u.logger.Debugf("re-queued %s due to changes during upload", job.localPath)
+		case <-ctx.Done():
+			u.clearInflight(job.localPath)
+		}
+	}
+}
+
+func (u *Uploader) clearInflight(localPath string) {
+	u.mu.Lock()
+	delete(u.inflight, localPath)
+	u.mu.Unlock()
+}
+
+func (u *Uploader) uploadWithRetry(ctx context.Context, job uploadJob) error {
+	var lastErr error
+	for attempt := 1; attempt <= u.retry; attempt++ {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		err := u.upload(ctx, job)
+		if err == nil {
+			return nil
+		}
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		lastErr = err
+		u.logger.Warnf("upload %s failed (attempt %d/%d): %v", job.localPath, attempt, u.retry, err)
+		if attempt < u.retry {
+			select {
+			case <-time.After(u.retryDelay):
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+	}
+	return lastErr
+}
+
+func (u *Uploader) upload(ctx context.Context, job uploadJob) error {
+	file, err := os.Open(filepath.Clean(job.localPath))
+	if err != nil {
+		return fmt.Errorf("failed to open file: %w", err)
+	}
+	defer file.Close()
+
+	info, err := file.Stat()
+	if err != nil {
+		return fmt.Errorf("failed to stat file: %w", err)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("path is a directory, not a file")
+	}
+
+	// Keep the relative directory structure on the storage side.
+	storagePath := path.Join(u.destDir, filepath.ToSlash(job.relPath))
+
+	uploadCtx := context.WithValue(ctx, ctxkey.ContentLength, info.Size())
+	if u.overwrite {
+		uploadCtx = storage.WithOverwrite(uploadCtx)
+	} else if u.stor.Exists(uploadCtx, storagePath) {
+		u.logger.Infof("skip existing file: %s", storagePath)
+		return nil
+	}
+
+	u.logger.Infof("uploading %s -> %s (%d bytes)", job.localPath, storagePath, info.Size())
+	if err := u.stor.Save(uploadCtx, file, storagePath); err != nil {
+		return fmt.Errorf("failed to save to storage: %w", err)
+	}
+	u.logger.Infof("uploaded %s", storagePath)
+	return nil
+}
+
+// Close stops accepting jobs and waits for in-flight uploads to finish.
+func (u *Uploader) Close() {
+	close(u.jobs)
+	u.wg.Wait()
+}

cmd/watch/watcher.go

@@ -0,0 +1,269 @@
+package watch
+
+import (
+	"context"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/charmbracelet/log"
+	"github.com/fsnotify/fsnotify"
+)
+
+// Watcher watches a local directory and submits stable files to the Uploader.
+//
+// Write-completion detection: fsnotify emits Write events throughout a write.
+// Watcher debounces per file and only uploads once the file size stays
+// unchanged across a debounce window, avoiding uploads of partial files.
+type Watcher struct {
+	root      string
+	recursive bool
+	debounce  time.Duration
+	uploader  *Uploader
+	logger    *log.Logger
+
+	fsw *fsnotify.Watcher
+
+	mu      sync.Mutex
+	pending map[string]*time.Timer
+	// lastSize is the last observed file size, used to detect a stable write.
+	lastSize map[string]int64
+}
+
+type WatcherOptions struct {
+	Root      string
+	Recursive bool
+	Debounce  time.Duration
+	Uploader  *Uploader
+}
+
+// NewWatcher creates a Watcher.
+func NewWatcher(ctx context.Context, opts WatcherOptions) (*Watcher, error) {
+	if opts.Debounce <= 0 {
+		opts.Debounce = 2 * time.Second
+	}
+	root, err := filepath.Abs(opts.Root)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve root path: %w", err)
+	}
+	info, err := os.Stat(root)
+	if err != nil {
+		return nil, fmt.Errorf("failed to stat root path: %w", err)
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("watch path must be a directory: %s", root)
+	}
+
+	fsw, err := fsnotify.NewWatcher()
+	if err != nil {
+		return nil, fmt.Errorf("failed to create fsnotify watcher: %w", err)
+	}
+
+	w := &Watcher{
+		root:      root,
+		recursive: opts.Recursive,
+		debounce:  opts.Debounce,
+		uploader:  opts.Uploader,
+		logger:    log.FromContext(ctx).WithPrefix("watcher"),
+		fsw:       fsw,
+		pending:   make(map[string]*time.Timer),
+		lastSize:  make(map[string]int64),
+	}
+	return w, nil
+}
+
+// Run starts watching and blocks until ctx is cancelled.
+func (w *Watcher) Run(ctx context.Context) error {
+	if err := w.addDir(w.root); err != nil {
+		w.fsw.Close()
+		return fmt.Errorf("failed to watch root: %w", err)
+	}
+	w.logger.Infof("watching %s (recursive=%v, debounce=%s)", w.root, w.recursive, w.debounce)
+
+	defer w.cleanup()
+
+	for {
+		select {
+		case <-ctx.Done():
+			w.logger.Info("stopping watcher")
+			return nil
+		case event, ok := <-w.fsw.Events:
+			if !ok {
+				return nil
+			}
+			w.handleEvent(ctx, event)
+		case err, ok := <-w.fsw.Errors:
+			if !ok {
+				return nil
+			}
+			w.logger.Errorf("watch error: %v", err)
+		}
+	}
+}
+
+func (w *Watcher) handleEvent(ctx context.Context, event fsnotify.Event) {
+	// Remove/Rename: cancel any pending upload for this path.
+	if event.Has(fsnotify.Remove) || event.Has(fsnotify.Rename) {
+		w.cancelPending(event.Name)
+		return
+	}
+
+	if !event.Has(fsnotify.Create) && !event.Has(fsnotify.Write) {
+		return
+	}
+
+	info, err := os.Stat(event.Name)
+	if err != nil {
+		// File may have been removed or moved; ignore.
+		return
+	}
+
+	if info.IsDir() {
+		// New directory: watch it recursively and scan files already inside.
+		if event.Has(fsnotify.Create) && w.recursive {
+			if err := w.addDir(event.Name); err != nil {
+				w.logger.Errorf("failed to watch new dir %s: %v", event.Name, err)
+			}
+			w.scanExisting(ctx, event.Name)
+		}
+		return
+	}
+
+	w.scheduleUpload(ctx, event.Name)
+}
+
+// scheduleUpload schedules a debounced upload for a file.
+func (w *Watcher) scheduleUpload(ctx context.Context, file string) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+
+	if t, ok := w.pending[file]; ok {
+		t.Stop()
+	}
+	w.pending[file] = time.AfterFunc(w.debounce, func() {
+		w.maybeUpload(ctx, file)
+	})
+}
+
+// maybeUpload submits the upload once the debounce window passes and the file
+// size is stable; otherwise it waits another window.
+func (w *Watcher) maybeUpload(ctx context.Context, file string) {
+	if ctx.Err() != nil {
+		return
+	}
+
+	info, err := os.Stat(file)
+	if err != nil {
+		w.cancelPending(file)
+		return
+	}
+	if info.IsDir() {
+		w.cancelPending(file)
+		return
+	}
+
+	w.mu.Lock()
+	prevSize, seen := w.lastSize[file]
+	curSize := info.Size()
+	if !seen || prevSize != curSize {
+		// Size still changing: likely still being written, wait another window.
+		w.lastSize[file] = curSize
+		w.pending[file] = time.AfterFunc(w.debounce, func() {
+			w.maybeUpload(ctx, file)
+		})
+		w.mu.Unlock()
+		return
+	}
+	// Size stable: treat write as complete.
+	delete(w.pending, file)
+	delete(w.lastSize, file)
+	w.mu.Unlock()
+
+	relPath, err := filepath.Rel(w.root, file)
+	if err != nil {
+		w.logger.Errorf("failed to compute relative path for %s: %v", file, err)
+		return
+	}
+
+	w.uploader.Submit(ctx, uploadJob{localPath: file, relPath: relPath})
+}
+
+func (w *Watcher) cancelPending(file string) {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if t, ok := w.pending[file]; ok {
+		t.Stop()
+		delete(w.pending, file)
+	}
+	delete(w.lastSize, file)
+}
+
+// addDir adds a directory to the watch list, recursively when enabled.
+func (w *Watcher) addDir(dir string) error {
+	if !w.recursive {
+		return w.fsw.Add(dir)
+	}
+	return filepath.WalkDir(dir, func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			w.logger.Warnf("skip path %s: %v", p, err)
+			return nil
+		}
+		if d.IsDir() {
+			if addErr := w.fsw.Add(p); addErr != nil {
+				w.logger.Warnf("failed to watch dir %s: %v", p, addErr)
+			} else {
+				w.logger.Debugf("watching dir %s", p)
+			}
+		}
+		return nil
+	})
+}
+
+// scanExisting submits files already present under dir (initial sync and new-dir backfill).
+func (w *Watcher) scanExisting(ctx context.Context, dir string) {
+	walkFn := func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			w.logger.Warnf("skip path %s: %v", p, err)
+			return nil
+		}
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		if d.IsDir() {
+			if !w.recursive && p != dir {
+				return fs.SkipDir
+			}
+			return nil
+		}
+		relPath, relErr := filepath.Rel(w.root, p)
+		if relErr != nil {
+			w.logger.Errorf("failed to compute relative path for %s: %v", p, relErr)
+			return nil
+		}
+		w.uploader.Submit(ctx, uploadJob{localPath: p, relPath: relPath})
+		return nil
+	}
+	if err := filepath.WalkDir(dir, walkFn); err != nil && ctx.Err() == nil {
+		w.logger.Errorf("failed to scan dir %s: %v", dir, err)
+	}
+}
+
+// ScanExisting triggers a one-time scan and upload of existing files under the watch root.
+func (w *Watcher) ScanExisting(ctx context.Context) {
+	w.logger.Info("scanning existing files for initial sync")
+	w.scanExisting(ctx, w.root)
+}
+
+func (w *Watcher) cleanup() {
+	w.mu.Lock()
+	for _, t := range w.pending {
+		t.Stop()
+	}
+	w.pending = make(map[string]*time.Timer)
+	w.lastSize = make(map[string]int64)
+	w.mu.Unlock()
+	w.fsw.Close()
+}

common/i18n/i18nk/keys.go

@@ -21,6 +21,7 @@ const (
 	BotMsgCmdDl                                           Key = "bot.msg.cmd.dl"
 	BotMsgCmdFnametmpl                                    Key = "bot.msg.cmd.fnametmpl"
 	BotMsgCmdHelp                                         Key = "bot.msg.cmd.help"
+	BotMsgCmdImport                                       Key = "bot.msg.cmd.import"
 	BotMsgCmdLswatch                                      Key = "bot.msg.cmd.lswatch"
 	BotMsgCmdParser                                       Key = "bot.msg.cmd.parser"
 	BotMsgCmdRule                                         Key = "bot.msg.cmd.rule"
@@ -30,10 +31,14 @@ const (
 	BotMsgCmdStorage                                      Key = "bot.msg.cmd.storage"
 	BotMsgCmdSyncpeers                                    Key = "bot.msg.cmd.syncpeers"
 	BotMsgCmdTask                                         Key = "bot.msg.cmd.task"
+	BotMsgCmdTransfer                                     Key = "bot.msg.cmd.transfer"
 	BotMsgCmdUnwatch                                      Key = "bot.msg.cmd.unwatch"
 	BotMsgCmdUpdate                                       Key = "bot.msg.cmd.update"
 	BotMsgCmdWatch                                        Key = "bot.msg.cmd.watch"
 	BotMsgCmdYtdlp                                        Key = "bot.msg.cmd.ytdlp"
+	BotMsgCommonButtonConflictOverwrite                   Key = "bot.msg.common.button_conflict_overwrite"
+	BotMsgCommonButtonConflictRename                      Key = "bot.msg.common.button_conflict_rename"
+	BotMsgCommonButtonConflictSkip                        Key = "bot.msg.common.button_conflict_skip"
 	BotMsgCommonCancelButtonText                          Key = "bot.msg.common.cancel_button_text"
 	BotMsgCommonErrorBuildDirSelectKeyboardFailed         Key = "bot.msg.common.error_build_dir_select_keyboard_failed"
 	BotMsgCommonErrorBuildStorageSelectKeyboardFailed     Key = "bot.msg.common.error_build_storage_select_keyboard_failed"
@@ -61,7 +66,10 @@ const (
 	BotMsgCommonErrorTaskAddFailed                        Key = "bot.msg.common.error_task_add_failed"
 	BotMsgCommonErrorTaskCreateFailed                     Key = "bot.msg.common.error_task_create_failed"
 	BotMsgCommonErrorUpdateUserInfoFailed                 Key = "bot.msg.common.error_update_user_info_failed"
+	BotMsgCommonInfoAllConflictFilesSkipped               Key = "bot.msg.common.info_all_conflict_files_skipped"
 	BotMsgCommonInfoBatchTasksAdded                       Key = "bot.msg.common.info_batch_tasks_added"
+	BotMsgCommonInfoBatchTasksAddedWithSkipped            Key = "bot.msg.common.info_batch_tasks_added_with_skipped"
+	BotMsgCommonInfoConflictFilesSkipped                  Key = "bot.msg.common.info_conflict_files_skipped"
 	BotMsgCommonInfoDefaultStorageSet                     Key = "bot.msg.common.info_default_storage_set"
 	BotMsgCommonInfoDefaultStorageWithDirSet              Key = "bot.msg.common.info_default_storage_with_dir_set"
 	BotMsgCommonInfoFetchingFileInfo                      Key = "bot.msg.common.info_fetching_file_info"
@@ -71,16 +79,25 @@ const (
 	BotMsgCommonInfoSilentModeOff                         Key = "bot.msg.common.info_silent_mode_off"
 	BotMsgCommonInfoSilentModeOn                          Key = "bot.msg.common.info_silent_mode_on"
 	BotMsgCommonInfoTaskAdded                             Key = "bot.msg.common.info_task_added"
+	BotMsgCommonPromptConflictMoreFiles                   Key = "bot.msg.common.prompt_conflict_more_files"
+	BotMsgCommonPromptSelectConflictStrategy              Key = "bot.msg.common.prompt_select_conflict_strategy"
 	BotMsgCommonPromptSelectDefaultDir                    Key = "bot.msg.common.prompt_select_default_dir"
 	BotMsgCommonPromptSelectDefaultStorage                Key = "bot.msg.common.prompt_select_default_storage"
 	BotMsgCommonPromptSelectDir                           Key = "bot.msg.common.prompt_select_dir"
+	BotMsgConfigButtonConflictStrategy                    Key = "bot.msg.config.button_conflict_strategy"
 	BotMsgConfigButtonFilenameStrategy                    Key = "bot.msg.config.button_filename_strategy"
+	BotMsgConfigConflictStrategyAsk                       Key = "bot.msg.config.conflict_strategy_ask"
+	BotMsgConfigConflictStrategyOverwrite                 Key = "bot.msg.config.conflict_strategy_overwrite"
+	BotMsgConfigConflictStrategyRename                    Key = "bot.msg.config.conflict_strategy_rename"
+	BotMsgConfigConflictStrategySkip                      Key = "bot.msg.config.conflict_strategy_skip"
 	BotMsgConfigErrorInvalidCallbackData                  Key = "bot.msg.config.error_invalid_callback_data"
 	BotMsgConfigErrorInvalidTemplate                      Key = "bot.msg.config.error_invalid_template"
 	BotMsgConfigFnametmplHelp                             Key = "bot.msg.config.fnametmpl_help"
+	BotMsgConfigInfoConflictStrategySet                   Key = "bot.msg.config.info_conflict_strategy_set"
 	BotMsgConfigInfoCurrentTemplatePrefix                 Key = "bot.msg.config.info_current_template_prefix"
 	BotMsgConfigInfoFilenameStrategySet                   Key = "bot.msg.config.info_filename_strategy_set"
 	BotMsgConfigInfoTemplateUpdated                       Key = "bot.msg.config.info_template_updated"
+	BotMsgConfigPromptSelectConflictStrategy              Key = "bot.msg.config.prompt_select_conflict_strategy"
 	BotMsgConfigPromptSelectFilenameStrategy              Key = "bot.msg.config.prompt_select_filename_strategy"
 	BotMsgConfigPromptSelectOption                        Key = "bot.msg.config.prompt_select_option"
 	BotMsgDirButtonDefault                                Key = "bot.msg.dir.button_default"
@@ -133,34 +150,70 @@ const (
 	BotMsgProgressAria2Downloading                        Key = "bot.msg.progress.aria2_downloading"
 	BotMsgProgressAria2Start                              Key = "bot.msg.progress.aria2_start"
 	BotMsgProgressAvgSpeedPrefix                          Key = "bot.msg.progress.avg_speed_prefix"
-	BotMsgProgressBatchDonePrefix                         Key = "bot.msg.progress.batch_done_prefix"
-	BotMsgProgressBatchProcessingPrefix                   Key = "bot.msg.progress.batch_processing_prefix"
-	BotMsgProgressBatchStartPrefix                        Key = "bot.msg.progress.batch_start_prefix"
+	BotMsgProgressBatchCanceled                           Key = "bot.msg.progress.batch_canceled"
+	BotMsgProgressBatchDone                               Key = "bot.msg.progress.batch_done"
+	BotMsgProgressBatchDoneWithSkipped                    Key = "bot.msg.progress.batch_done_with_skipped"
+	BotMsgProgressBatchFailedGroup                        Key = "bot.msg.progress.batch_failed_group"
+	BotMsgProgressBatchFailedItem                         Key = "bot.msg.progress.batch_failed_item"
+	BotMsgProgressBatchFailedTask                         Key = "bot.msg.progress.batch_failed_task"
+	BotMsgProgressBatchFailureStageBatchUpload            Key = "bot.msg.progress.batch_failure_stage_batch_upload"
+	BotMsgProgressBatchFailureStageCache                  Key = "bot.msg.progress.batch_failure_stage_cache"
+	BotMsgProgressBatchFailureStageConfirm                Key = "bot.msg.progress.batch_failure_stage_confirm"
+	BotMsgProgressBatchFailureStageDownload               Key = "bot.msg.progress.batch_failure_stage_download"
+	BotMsgProgressBatchFailureStageInternal               Key = "bot.msg.progress.batch_failure_stage_internal"
+	BotMsgProgressBatchFailureStageUpload                 Key = "bot.msg.progress.batch_failure_stage_upload"
+	BotMsgProgressBatchItemConfirming                     Key = "bot.msg.progress.batch_item_confirming"
+	BotMsgProgressBatchItemDownloading                    Key = "bot.msg.progress.batch_item_downloading"
+	BotMsgProgressBatchItemDownloadingUnknown             Key = "bot.msg.progress.batch_item_downloading_unknown"
+	BotMsgProgressBatchItemRetrying                       Key = "bot.msg.progress.batch_item_retrying"
+	BotMsgProgressBatchItemTransferring                   Key = "bot.msg.progress.batch_item_transferring"
+	BotMsgProgressBatchItemTransferringUnknown            Key = "bot.msg.progress.batch_item_transferring_unknown"
+	BotMsgProgressBatchItemUploading                      Key = "bot.msg.progress.batch_item_uploading"
+	BotMsgProgressBatchStatusHeader                       Key = "bot.msg.progress.batch_status_header"
+	BotMsgProgressBatchSummaryConfirming                  Key = "bot.msg.progress.batch_summary_confirming"
+	BotMsgProgressBatchSummaryFailed                      Key = "bot.msg.progress.batch_summary_failed"
+	BotMsgProgressBatchSummaryHiddenActive                Key = "bot.msg.progress.batch_summary_hidden_active"
+	BotMsgProgressBatchSummarySkipped                     Key = "bot.msg.progress.batch_summary_skipped"
 	BotMsgProgressCurrentProgressPrefix                   Key = "bot.msg.progress.current_progress_prefix"
 	BotMsgProgressCurrentSpeedPrefix                      Key = "bot.msg.progress.current_speed_prefix"
 	BotMsgProgressDirectDonePrefix                        Key = "bot.msg.progress.direct_done_prefix"
 	BotMsgProgressDirectStart                             Key = "bot.msg.progress.direct_start"
-	BotMsgProgressDownloadDonePrefix                      Key = "bot.msg.progress.download_done_prefix"
-	BotMsgProgressDownloadFailedPrefix                    Key = "bot.msg.progress.download_failed_prefix"
 	BotMsgProgressDownloadedPrefix                        Key = "bot.msg.progress.downloaded_prefix"
 	BotMsgProgressDownloadingPrefix                       Key = "bot.msg.progress.downloading_prefix"
 	BotMsgProgressErrorPrefix                             Key = "bot.msg.progress.error_prefix"
-	BotMsgProgressFileNamePrefix                          Key = "bot.msg.progress.file_name_prefix"
-	BotMsgProgressFileProcessingPrefix                    Key = "bot.msg.progress.file_processing_prefix"
-	BotMsgProgressFileSizePrefix                          Key = "bot.msg.progress.file_size_prefix"
-	BotMsgProgressFileStartPrefix                         Key = "bot.msg.progress.file_start_prefix"
 	BotMsgProgressParsedDonePrefix                        Key = "bot.msg.progress.parsed_done_prefix"
 	BotMsgProgressParsedStartPrefix                       Key = "bot.msg.progress.parsed_start_prefix"
 	BotMsgProgressProcessingListPrefix                    Key = "bot.msg.progress.processing_list_prefix"
 	BotMsgProgressProcessingNone                          Key = "bot.msg.progress.processing_none"
 	BotMsgProgressSavePathPrefix                          Key = "bot.msg.progress.save_path_prefix"
-	BotMsgProgressTaskCanceled                            Key = "bot.msg.progress.task_canceled"
+	BotMsgProgressSingleCanceled                          Key = "bot.msg.progress.single_canceled"
+	BotMsgProgressSingleDone                              Key = "bot.msg.progress.single_done"
+	BotMsgProgressSingleDownloading                       Key = "bot.msg.progress.single_downloading"
+	BotMsgProgressSingleDownloadingUnknown                Key = "bot.msg.progress.single_downloading_unknown"
+	BotMsgProgressSingleFailed                            Key = "bot.msg.progress.single_failed"
+	BotMsgProgressSingleStatusHeader                      Key = "bot.msg.progress.single_status_header"
+	BotMsgProgressSingleUploading                         Key = "bot.msg.progress.single_uploading"
+	BotMsgProgressSingleUploadRetrying                    Key = "bot.msg.progress.single_upload_retrying"
 	BotMsgProgressTaskCanceledWithId                      Key = "bot.msg.progress.task_canceled_with_id"
 	BotMsgProgressTaskFailedWithError                     Key = "bot.msg.progress.task_failed_with_error"
 	BotMsgProgressTelegraphDonePrefix                     Key = "bot.msg.progress.telegraph_done_prefix"
 	BotMsgProgressTelegraphProgressPrefix                 Key = "bot.msg.progress.telegraph_progress_prefix"
 	BotMsgProgressTelegraphStartPrefix                    Key = "bot.msg.progress.telegraph_start_prefix"
 	BotMsgProgressTotalSizePrefix                         Key = "bot.msg.progress.total_size_prefix"
+	BotMsgProgressTransferAvgSpeedPrefix                  Key = "bot.msg.progress.transfer_avg_speed_prefix"
+	BotMsgProgressTransferElapsedTimePrefix               Key = "bot.msg.progress.transfer_elapsed_time_prefix"
+	BotMsgProgressTransferFailedFilesPrefix               Key = "bot.msg.progress.transfer_failed_files_prefix"
+	BotMsgProgressTransferFailedPrefix                    Key = "bot.msg.progress.transfer_failed_prefix"
+	BotMsgProgressTransferProcessingMore                  Key = "bot.msg.progress.transfer_processing_more"
+	BotMsgProgressTransferProcessingPrefix                Key = "bot.msg.progress.transfer_processing_prefix"
+	BotMsgProgressTransferProgressPrefix                  Key = "bot.msg.progress.transfer_progress_prefix"
+	BotMsgProgressTransferRemainingTimePrefix             Key = "bot.msg.progress.transfer_remaining_time_prefix"
+	BotMsgProgressTransferSpeedPrefix                     Key = "bot.msg.progress.transfer_speed_prefix"
+	BotMsgProgressTransferStartPrefix                     Key = "bot.msg.progress.transfer_start_prefix"
+	BotMsgProgressTransferSuccessPrefix                   Key = "bot.msg.progress.transfer_success_prefix"
+	BotMsgProgressTransferTotalFilesPrefix                Key = "bot.msg.progress.transfer_total_files_prefix"
+	BotMsgProgressTransferTotalSizePrefix                 Key = "bot.msg.progress.transfer_total_size_prefix"
+	BotMsgProgressTransferUploadedPrefix                  Key = "bot.msg.progress.transfer_uploaded_prefix"
 	BotMsgProgressYtdlpDone                               Key = "bot.msg.progress.ytdlp_done"
 	BotMsgProgressYtdlpDownloading                        Key = "bot.msg.progress.ytdlp_downloading"
 	BotMsgProgressYtdlpStart                              Key = "bot.msg.progress.ytdlp_start"
@@ -169,6 +222,7 @@ const (
 	BotMsgRuleErrorGetUserRulesFailed                     Key = "bot.msg.rule.error_get_user_rules_failed"
 	BotMsgRuleErrorInvalidRuleId                          Key = "bot.msg.rule.error_invalid_rule_id"
 	BotMsgRuleErrorInvalidRuleType                        Key = "bot.msg.rule.error_invalid_rule_type"
+	BotMsgRuleErrorStorageNotFound                        Key = "bot.msg.rule.error_storage_not_found"
 	BotMsgRuleErrorUpdateUserFailed                       Key = "bot.msg.rule.error_update_user_failed"
 	BotMsgRuleHelpAddSuffix                               Key = "bot.msg.rule.help_add_suffix"
 	BotMsgRuleHelpAvailableOps                            Key = "bot.msg.rule.help_available_ops"
@@ -176,13 +230,16 @@ const (
 	BotMsgRuleHelpCurrentModeEnabled                      Key = "bot.msg.rule.help_current_mode_enabled"
 	BotMsgRuleHelpDelSuffix                               Key = "bot.msg.rule.help_del_suffix"
 	BotMsgRuleHelpExistingRulesPrefix                     Key = "bot.msg.rule.help_existing_rules_prefix"
+	BotMsgRuleHelpPresetSuffix                            Key = "bot.msg.rule.help_preset_suffix"
 	BotMsgRuleHelpSwitchSuffix                            Key = "bot.msg.rule.help_switch_suffix"
 	BotMsgRuleHelpUsage                                   Key = "bot.msg.rule.help_usage"
 	BotMsgRuleInfoCreateRuleSuccess                       Key = "bot.msg.rule.info_create_rule_success"
 	BotMsgRuleInfoDeleteRuleSuccess                       Key = "bot.msg.rule.info_delete_rule_success"
+	BotMsgRuleInfoPresetImported                          Key = "bot.msg.rule.info_preset_imported"
 	BotMsgRuleInfoRuleModeDisabled                        Key = "bot.msg.rule.info_rule_mode_disabled"
 	BotMsgRuleInfoRuleModeEnabled                         Key = "bot.msg.rule.info_rule_mode_enabled"
 	BotMsgRulePromptProvideRuleId                         Key = "bot.msg.rule.prompt_provide_rule_id"
+	BotMsgRulePromptProvideStorageName                    Key = "bot.msg.rule.prompt_provide_storage_name"
 	BotMsgSaveErrorInvalidIdOrUsername                    Key = "bot.msg.save.error_invalid_id_or_username"
 	BotMsgSaveHelpText                                    Key = "bot.msg.save_help_text"
 	BotMsgStorageInfoFilenamePrefix                       Key = "bot.msg.storage.info_filename_prefix"
@@ -216,6 +273,22 @@ const (
 	BotMsgTelegraphInfoPicCountPrefix                     Key = "bot.msg.telegraph.info_pic_count_prefix"
 	BotMsgTelegraphInfoPromptSelectStorage                Key = "bot.msg.telegraph.info_prompt_select_storage"
 	BotMsgTelegraphInfoTitlePrefix                        Key = "bot.msg.telegraph.info_title_prefix"
+	BotMsgTransferErrorAddTaskFailed                      Key = "bot.msg.transfer.error_add_task_failed"
+	BotMsgTransferErrorBuildStorageSelectKeyboardFailed   Key = "bot.msg.transfer.error_build_storage_select_keyboard_failed"
+	BotMsgTransferErrorInvalidRegex                       Key = "bot.msg.transfer.error_invalid_regex"
+	BotMsgTransferErrorInvalidSource                      Key = "bot.msg.transfer.error_invalid_source"
+	BotMsgTransferErrorInvalidTarget                      Key = "bot.msg.transfer.error_invalid_target"
+	BotMsgTransferErrorListFilesFailed                    Key = "bot.msg.transfer.error_list_files_failed"
+	BotMsgTransferErrorNoFilesToTransfer                  Key = "bot.msg.transfer.error_no_files_to_transfer"
+	BotMsgTransferErrorStorageNotFound                    Key = "bot.msg.transfer.error_storage_not_found"
+	BotMsgTransferErrorStorageNotListable                 Key = "bot.msg.transfer.error_storage_not_listable"
+	BotMsgTransferErrorStorageNotReadable                 Key = "bot.msg.transfer.error_storage_not_readable"
+	BotMsgTransferErrorTargetNotFound                     Key = "bot.msg.transfer.error_target_not_found"
+	BotMsgTransferInfoFetchingFiles                       Key = "bot.msg.transfer.info_fetching_files"
+	BotMsgTransferInfoFilesSelectStorage                  Key = "bot.msg.transfer.info_files_select_storage"
+	BotMsgTransferInfoTaskAdded                           Key = "bot.msg.transfer.info_task_added"
+	BotMsgTransferStartStats                              Key = "bot.msg.transfer.start_stats"
+	BotMsgTransferUsage                                   Key = "bot.msg.transfer.usage"
 	BotMsgUpdateButtonUpgrade                             Key = "bot.msg.update.button_upgrade"
 	BotMsgUpdateErrorCheckLatestFailed                    Key = "bot.msg.update.error_check_latest_failed"
 	BotMsgUpdateErrorNoReleaseFound                       Key = "bot.msg.update.error_no_release_found"

common/i18n/locale/en.yaml

@@ -29,6 +29,7 @@ bot:
       /silent - Toggle silent mode
       /storage - Set default storage
       /save [custom filename] - Save file
+      /import <storage_name> <dir_path> [channel_id] [filter] - Import files from storage to Telegram
       /dir - Manage storage directories
       /rule - Manage rules
       /config - Modify configuration
@@ -52,6 +53,8 @@ bot:
       dl: "Download files from given links"
       aria2dl: "Download files using Aria2"
       ytdlp: "Download video/audio using yt-dlp"
+      import: "Import files from storage to Telegram"
+      transfer: "Transfer files between storages"
       task: "Manage task queue"
       cancel: "Cancel task"
       watch: "Watch chats (UserBot)"
@@ -109,9 +112,17 @@ bot:
       error_task_add_failed: "Failed to add task: {{.Error}}"
       info_task_added: "Task added"
       info_batch_tasks_added: "Batch tasks added, total {{.Count}} files"
+      info_batch_tasks_added_with_skipped: "Batch tasks added, total {{.Count}} files\nSkipped conflicting files:\n{{.Skipped}}"
+      info_all_conflict_files_skipped: "All conflicting files were skipped:\n{{.Skipped}}"
+      info_conflict_files_skipped: "Skipped conflicting files:\n{{.Skipped}}"
       error_task_create_failed: "Failed to create task: {{.Error}}"
       error_get_dir_failed: "Failed to get directory: {{.Error}}"
       prompt_select_dir: "Please select a directory to store to"
+      prompt_select_conflict_strategy: "Files with the same name already exist. Please select a save strategy:\n{{.Files}}"
+      prompt_conflict_more_files: "...and {{.Count}} more files"
+      button_conflict_rename: "Rename"
+      button_conflict_overwrite: "Overwrite"
+      button_conflict_skip: "Skip"
       prompt_select_default_dir: "Please select a default directory to save to"
       info_default_storage_set: "Default storage set to: {{.Name}}"
       info_default_storage_with_dir_set: "Default storage set to: {{.Name}}:/{{.Dir}}"
@@ -185,7 +196,11 @@ bot:
       help_switch_suffix: " - Toggle rule mode\n"
       help_add_suffix: " <type> <data> <storage_name> <path> - Add rule\n"
       help_del_suffix: " <rule_id> - Delete rule\n"
+      help_preset_suffix: " <storage_name> [base_path] - Import built-in filetype rules (video/image/audio/document/archive)\n"
       help_existing_rules_prefix: "\nCurrent rules:\n"
+      prompt_provide_storage_name: "Please provide a storage name"
+      error_storage_not_found: "Storage not found: {{.Storage}}"
+      info_preset_imported: "Imported {{.Count}} built-in classification rules into storage {{.Storage}}"
     dir:
       error_get_user_dirs_failed: "Failed to get user directories"
       error_get_user_failed: "Failed to get user"
@@ -263,10 +278,17 @@ bot:
     config:
       prompt_select_option: "Please select an option to configure"
       button_filename_strategy: "Filename strategy"
+      button_conflict_strategy: "Duplicate file strategy"
       error_invalid_callback_data: "Invalid callback data"
       error_invalid_template: "Invalid template, please check syntax\n{{.Error}}"
       info_filename_strategy_set: "Filename strategy set to: {{.Strategy}}"
+      info_conflict_strategy_set: "Duplicate file strategy set to: {{.Strategy}}"
       prompt_select_filename_strategy: "Please select filename strategy, current strategy: {{.Strategy}}"
+      prompt_select_conflict_strategy: "Please select duplicate file strategy, current strategy: {{.Strategy}}"
+      conflict_strategy_rename: "Always rename"
+      conflict_strategy_ask: "Ask every time"
+      conflict_strategy_overwrite: "Always overwrite"
+      conflict_strategy_skip: "Always skip"
       fnametmpl_help: |-
         Use this command to set filename template, for example:
         /fnametmpl Image_{{"{{.msgid}}"}}_{{"{{.msgdate}}"}}.jpg
@@ -289,11 +311,33 @@ bot:
       error_no_valid_links: "No valid links to download"
       info_files_select_storage: "Total {{.Count}} files, please select storage"
     ytdlp:
-      usage: "Usage: /ytdlp <URL1> <URL2> ..."
+      usage: "Usage: /ytdlp [OPTIONS] <URL1> [URL2] ...\nExamples:\n  /ytdlp https://example.com/video\n  /ytdlp --format best https://example.com/video\n  /ytdlp --extract-audio --audio-format mp3 https://example.com/video"
       error_no_valid_urls: "No valid URLs"
       info_urls_select_storage: "Found {{.Count}} links, please select storage"
       info_downloading: "Downloading via yt-dlp..."
       error_download_failed: "yt-dlp download failed: {{.Error}}"
+    transfer:
+      usage: |
+        Usage: /transfer <source_storage>:/<source_path> [filter]
+        Examples:
+        /transfer local1:/downloads
+        /transfer alist1:/media/photos
+        /transfer webdav1:/files ".*\.mp4$"
+      error_invalid_source: "Invalid source path format, should be: storage_name:/path"
+      error_invalid_target: "Invalid target path format, should be: storage_name:/path"
+      error_storage_not_found: "Storage '{{.StorageName}}' not found or access denied: {{.Error}}"
+      error_storage_not_listable: "Storage '{{.StorageName}}' does not support listing files"
+      error_storage_not_readable: "Storage '{{.StorageName}}' does not support reading files"
+      error_target_not_found: "Target storage '{{.StorageName}}' not found or access denied: {{.Error}}"
+      info_fetching_files: "Fetching file list..."
+      error_list_files_failed: "Failed to list files: {{.Error}}"
+      error_invalid_regex: "Invalid regular expression: {{.Error}}"
+      error_no_files_to_transfer: "No files to transfer in directory"
+      error_add_task_failed: "Failed to add task: {{.Error}}"
+      info_task_added: "Added {{.Count}} files to transfer queue\nTotal size: {{.SizeMB}} MB\nTask ID: {{.TaskID}}"
+      start_stats: "Total files: {{.Count}}\nTotal size: {{.SizeMB}} MB"
+      info_files_select_storage: "Total {{.Count}} files ({{.SizeMB}} MB), please select target storage"
+      error_build_storage_select_keyboard_failed: "Failed to build storage selection keyboard: {{.Error}}"
     cancel:
       usage: "Usage: /cancel <task_id>"
       error_cancel_failed: "Failed to cancel task: {{.Error}}"
@@ -307,32 +351,54 @@ bot:
       info_filename_prefix: "Filename: "
       info_prompt_select_storage: "\nPlease select storage"
     progress:
-      batch_start_prefix: "Starting batch download task\nTotal size: "
-      batch_processing_prefix: "Processing batch download task\nTotal size: "
+      batch_status_header: "<b>📦 Processing</b>\n\nFiles: <code>{{.Total}}</code>\nStatus: ✅ <code>{{.Completed}}</code> | 📥 <code>{{.Downloaded}}</code> | ⏳ <code>{{.Waiting}}</code>\nTotal speed: ⬇️ <code>{{.DownloadSpeed}}</code> | ⬆️ <code>{{.UploadSpeed}}</code>"
+      batch_item_downloading: "<blockquote><b>⬇️ {{.Index}}/{{.Total}} Downloading</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_downloading_unknown: "<blockquote><b>⬇️ {{.Index}}/{{.Total}} Downloading</b>\n<code>{{.Name}}</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / unknown</blockquote>"
+      batch_item_transferring: "<blockquote><b>↕️ {{.Index}}/{{.Total}} Transferring</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_transferring_unknown: "<blockquote><b>↕️ {{.Index}}/{{.Total}} Transferring</b>\n<code>{{.Name}}</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / unknown</blockquote>"
+      batch_item_uploading: "<blockquote><b>⬆️ {{.Index}}/{{.Total}} Uploading</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_retrying: "<blockquote><b>🔁 {{.Index}}/{{.Total}} Retrying upload</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nRetry: <code>{{.Attempt}}/{{.Limit}}</code>\nSpeed before failure: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code>\nReason: <code>{{.Reason}}</code></blockquote>"
+      batch_item_confirming: "<blockquote><b>⏳ {{.Index}}/{{.Total}} Waiting</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n<i>Uploaded, awaiting remote confirmation</i></blockquote>"
+      batch_summary_hidden_active: "🔄 <code>{{.Count}}</code> more files are active"
+      batch_summary_confirming: "☁️ Uploaded, awaiting group send: <code>{{.Count}}</code>"
+      batch_summary_failed: "❌ Failed: <code>{{.Count}}</code>"
+      batch_summary_skipped: "⏭️ Skipped: <code>{{.Count}}</code>"
+      batch_done: "<b>✅ Completed</b>\n\nFiles: <code>{{.Count}}</code>\nTotal size: <code>{{.Size}}</code>"
+      batch_done_with_skipped: "<b>⚠️ Completed</b>\n\nSucceeded: <code>{{.Success}}</code>\nSkipped: <code>{{.Skipped}}</code>\nTotal size: <code>{{.Size}}</code>"
+      batch_canceled: "<b>🚫 Task canceled</b>\n\nFiles: <code>{{.Total}}</code>\nCompleted: <code>{{.Completed}}</code>\nIncomplete: <code>{{.Incomplete}}</code>\nSkipped: <code>{{.Skipped}}</code>"
+      batch_failed_item: "<b>❌ Processing failed</b>\n\nFailed file: <code>{{.Index}}. {{.Name}}</code>\nStage: <code>{{.Stage}}</code>\nProgress: <code>{{.Progress}}</code>\nSpeed before failure: <code>{{.Speed}}</code>\nReason: <code>{{.Reason}}</code>\n\n✅ Completed: <code>{{.Completed}}</code>\n❌ Failed: <code>{{.Failed}}</code>\n⏹️ Incomplete: <code>{{.Incomplete}}</code>"
+      batch_failed_group: "<b>❌ Batch upload failed</b>\n\nAffected files: <code>{{.Affected}}</code>\nReason: <code>{{.Reason}}</code>\n\n✅ Completed: <code>{{.Completed}}</code>\n❌ Batch failed: <code>{{.Failed}}</code>\n⏹️ Incomplete: <code>{{.Incomplete}}</code>"
+      batch_failed_task: "<b>❌ Processing failed</b>\n\nReason: <code>{{.Reason}}</code>\n\n✅ Completed: <code>{{.Completed}}</code>\n⏹️ Incomplete: <code>{{.Incomplete}}</code>"
+      batch_failure_stage_download: "download"
+      batch_failure_stage_cache: "local cache"
+      batch_failure_stage_upload: "upload"
+      batch_failure_stage_confirm: "remote confirmation"
+      batch_failure_stage_batch_upload: "batch upload"
+      batch_failure_stage_internal: "internal task"
+      single_status_header: "<b>📦 Processing</b>"
+      single_downloading: "<blockquote><b>⬇️ Downloading</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code>\nSave to: <code>{{.Destination}}</code></blockquote>"
+      single_downloading_unknown: "<blockquote><b>⬇️ Downloading</b>\n<code>{{.Name}}</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / unknown\nSave to: <code>{{.Destination}}</code></blockquote>"
+      single_uploading: "<blockquote><b>⬆️ Uploading</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code>\nSave to: <code>{{.Destination}}</code></blockquote>"
+      single_upload_retrying: "<blockquote><b>🔁 Retrying upload</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\nAttempt: <code>{{.Attempt}}</code>\nSpeed: <code>{{.Speed}}</code>\nSize: <code>{{.Current}}</code> / <code>{{.Size}}</code>\nSave to: <code>{{.Destination}}</code></blockquote>"
+      single_done: "<b>✅ Completed</b>\n\nFilename: <code>{{.Name}}</code>\nTotal size: <code>{{.Size}}</code>\nSave to: <code>{{.Destination}}</code>"
+      single_canceled: "<b>🚫 Task canceled</b>\n\nFilename: <code>{{.Name}}</code>"
+      single_failed: "<b>❌ Processing failed</b>\n\nFilename: <code>{{.Name}}</code>\nReason: <code>{{.Reason}}</code>"
       downloading_prefix: "Downloading\nTotal size: "
       processing_list_prefix: "\nProcessing:\n"
       processing_none: "  - None"
       avg_speed_prefix: "\nAverage speed: "
       current_progress_prefix: "\nCurrent progress: "
-      task_canceled: "Task canceled"
       task_canceled_with_id: "Processing canceled: {{.TaskID}}"
       task_failed_with_error: "Processing failed: {{.Error}}"
-      batch_done_prefix: "Completed\nFile count: "
       direct_done_prefix: "Completed, file count: "
       parsed_start_prefix: "Starting download from {{.Site}}\nTotal size: "
       parsed_done_prefix: "Completed, resource count: "
       telegraph_start_prefix: "Starting Telegraph download\nImage count: "
       telegraph_progress_prefix: "Downloading\nCurrent progress: "
       telegraph_done_prefix: "Completed\nImage count: "
-      file_start_prefix: "Starting download\nFilename: "
-      file_processing_prefix: "Processing download task\nFilename: "
-      download_failed_prefix: "Download failed\nFilename: "
-      download_done_prefix: "Download completed\nFilename: "
-      file_size_prefix: "\nFile size: "
       save_path_prefix: "\nSave path: "
       total_size_prefix: "\nTotal size: "
       direct_start: "Starting download, total size: {{.SizeMB}} MB ({{.Count}} files)"
-      file_name_prefix: "Filename: "
       error_prefix: "\nError: "
       aria2_start: "Waiting for Aria2 to complete download (GID: {{.GID}})..."
       aria2_downloading: "Aria2 downloading (GID: {{.GID}})\n"
@@ -342,6 +408,20 @@ bot:
       ytdlp_done: "yt-dlp download completed and transferred ({{.Count}} files)\n"
       downloaded_prefix: "\nDownloaded: "
       current_speed_prefix: "\nCurrent speed: "
+      transfer_start_prefix: "Transfering: "
+      transfer_progress_prefix: "Transfer progress: "
+      transfer_uploaded_prefix: "\nUploaded: "
+      transfer_speed_prefix: "\nSpeed: "
+      transfer_remaining_time_prefix: "\nRemaining time: "
+      transfer_processing_prefix: "\nProcessing:\n"
+      transfer_processing_more: "...and {{.Count}} more files\n"
+      transfer_failed_prefix: "Transfer failed\n"
+      transfer_success_prefix: "Transfer completed\n"
+      transfer_total_files_prefix: "\nTotal files: "
+      transfer_total_size_prefix: "\nTotal size: "
+      transfer_elapsed_time_prefix: "\nElapsed time: "
+      transfer_avg_speed_prefix: "\nAverage speed: "
+      transfer_failed_files_prefix: "\nFailed files: "
     syncpeers:
       start: "Starting to sync peers..."
       done: "Peer sync completed, total {{.Count}} chats synced"

common/i18n/locale/zh-Hans.yaml

@@ -30,6 +30,7 @@ bot:
       /storage - 设置默认存储位置
       /save [自定义文件名] - 保存文件
       /dl <链接1> <链接2> ... - 下载给定链接的文件
+      /import <存储名> <目录路径> [频道ID] [过滤器] - 从存储端导入文件到 Telegram
       /dir - 管理存储目录
       /rule - 管理规则
       /config - 修改配置
@@ -53,6 +54,8 @@ bot:
       dl: "下载给定链接的文件"
       aria2dl: "使用 Aria2 下载给定链接的文件"
       ytdlp: "使用 yt-dlp 下载视频/音频"
+      import: "从存储端导入文件到 Telegram"
+      transfer: "在存储端之间传输文件"
       task: "管理任务队列"
       cancel: "取消任务"
       watch: "监听聊天(UserBot)"
@@ -110,9 +113,17 @@ bot:
       error_task_add_failed: "任务添加失败: {{.Error}}"
       info_task_added: "任务已添加"
       info_batch_tasks_added: "已添加批量任务, 共 {{.Count}} 个文件"
+      info_batch_tasks_added_with_skipped: "已添加批量任务, 共 {{.Count}} 个文件\n已跳过同名文件:\n{{.Skipped}}"
+      info_all_conflict_files_skipped: "全部同名文件已跳过:\n{{.Skipped}}"
+      info_conflict_files_skipped: "已跳过同名文件:\n{{.Skipped}}"
       error_task_create_failed: "任务创建失败: {{.Error}}"
       error_get_dir_failed: "获取目录失败: {{.Error}}"
       prompt_select_dir: "请选择要存储到的目录"
+      prompt_select_conflict_strategy: "检测到同名文件, 请选择保存策略:\n{{.Files}}"
+      prompt_conflict_more_files: "...还有 {{.Count}} 个文件"
+      button_conflict_rename: "重命名"
+      button_conflict_overwrite: "覆盖"
+      button_conflict_skip: "跳过"
       prompt_select_default_dir: "请选择要保存到的默认文件夹"
       info_default_storage_set: "已将默认存储位置设为: {{.Name}}"
       info_default_storage_with_dir_set: "已将默认存储位置设为: {{.Name}}:/{{.Dir}}"
@@ -186,7 +197,11 @@ bot:
       help_switch_suffix: " - 开关规则模式\n"
       help_add_suffix: " <类型> <数据> <存储名> <路径> - 添加规则\n"
       help_del_suffix: " <规则ID> - 删除规则\n"
+      help_preset_suffix: " <存储名> [基础路径] - 导入内置文件类型分类规则(视频/图片/音频/文档/压缩包)\n"
       help_existing_rules_prefix: "\n当前已添加的规则:\n"
+      prompt_provide_storage_name: "请提供存储名称"
+      error_storage_not_found: "未找到存储: {{.Storage}}"
+      info_preset_imported: "已导入 {{.Count}} 条内置分类规则到存储 {{.Storage}}"
     dir:
       error_get_user_dirs_failed: "获取用户文件夹失败"
       error_get_user_failed: "获取用户失败"
@@ -264,10 +279,17 @@ bot:
     config:
       prompt_select_option: "请选择要配置的选项"
       button_filename_strategy: "文件名策略"
+      button_conflict_strategy: "重名文件保存策略"
       error_invalid_callback_data: "无效的回调数据"
       error_invalid_template: "无效的模板, 请检查语法\n{{.Error}}"
       info_filename_strategy_set: "已将文件名策略设置为: {{.Strategy}}"
+      info_conflict_strategy_set: "已将重名文件保存策略设置为: {{.Strategy}}"
       prompt_select_filename_strategy: "请选择文件名策略, 当前策略: {{.Strategy}}"
+      prompt_select_conflict_strategy: "请选择重名文件保存策略, 当前策略: {{.Strategy}}"
+      conflict_strategy_rename: "始终重命名"
+      conflict_strategy_ask: "每次询问"
+      conflict_strategy_overwrite: "始终覆盖"
+      conflict_strategy_skip: "始终跳过"
       fnametmpl_help: |-
         使用该命令设置文件名模板, 示例:
         /fnametmpl 图片_{{"{{.msgid}}"}}_{{"{{.msgdate}}"}}.jpg
@@ -290,11 +312,33 @@ bot:
       error_no_valid_links: "没有有效的链接可供下载"
       info_files_select_storage: "共 {{.Count}} 个文件, 请选择存储位置"
     ytdlp:
-      usage: "用法: /ytdlp <URL1> <URL2> ..."
+      usage: "用法: /ytdlp [选项] <URL1> [URL2] ...\n示例:\n  /ytdlp https://example.com/video\n  /ytdlp --format best https://example.com/video\n  /ytdlp --extract-audio --audio-format mp3 https://example.com/video"
       error_no_valid_urls: "没有有效的 URL"
       info_urls_select_storage: "共 {{.Count}} 个链接, 请选择存储位置"
       info_downloading: "正在通过 yt-dlp 下载..."
       error_download_failed: "yt-dlp 下载失败: {{.Error}}"
+    transfer:
+      usage: |
+        用法: /transfer <source_storage>:/<source_path> [filter]
+        示例:
+        /transfer local1:/downloads
+        /transfer alist1:/media/photos
+        /transfer webdav1:/files ".*\.mp4$"
+      error_invalid_source: "源路径格式无效，应为: storage_name:/path"
+      error_invalid_target: "目标路径格式无效，应为: storage_name:/path"
+      error_storage_not_found: "存储端 '{{.StorageName}}' 不存在或您无权访问: {{.Error}}"
+      error_storage_not_listable: "存储端 '{{.StorageName}}' 不支持列举文件功能"
+      error_storage_not_readable: "存储端 '{{.StorageName}}' 不支持读取文件功能"
+      error_target_not_found: "目标存储端 '{{.StorageName}}' 不存在或您无权访问: {{.Error}}"
+      info_fetching_files: "正在获取文件列表..."
+      error_list_files_failed: "获取文件列表失败: {{.Error}}"
+      error_invalid_regex: "正则表达式无效: {{.Error}}"
+      error_no_files_to_transfer: "目录中没有可传输的文件"
+      error_add_task_failed: "添加任务失败: {{.Error}}"
+      info_task_added: "已添加 {{.Count}} 个文件到传输队列\n总大小: {{.SizeMB}} MB\n任务 ID: {{.TaskID}}"
+      start_stats: "总文件数: {{.Count}}\n总大小: {{.SizeMB}} MB"
+      info_files_select_storage: "共 {{.Count}} 个文件 (总大小: {{.SizeMB}} MB)，请选择目标存储位置"
+      error_build_storage_select_keyboard_failed: "构建存储选择键盘失败: {{.Error}}"
     cancel:
       usage: "用法: /cancel <task_id>"
       error_cancel_failed: "取消任务失败: {{.Error}}"
@@ -308,32 +352,54 @@ bot:
       info_filename_prefix: "文件名: "
       info_prompt_select_storage: "\n请选择存储位置"
     progress:
-      batch_start_prefix: "开始执行批量下载任务\n总大小: "
-      batch_processing_prefix: "正在处理批量下载任务\n总大小: "
+      batch_status_header: "<b>📦 正在处理</b>\n\n文件：<code>{{.Total}}</code>\n状态：✅ <code>{{.Completed}}</code> ｜ 📥 <code>{{.Downloaded}}</code> ｜ ⏳ <code>{{.Waiting}}</code>\n总速度：⬇️ <code>{{.DownloadSpeed}}</code> ｜ ⬆️ <code>{{.UploadSpeed}}</code>"
+      batch_item_downloading: "<blockquote><b>⬇️ {{.Index}}/{{.Total}} 下载中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_downloading_unknown: "<blockquote><b>⬇️ {{.Index}}/{{.Total}} 下载中</b>\n<code>{{.Name}}</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / 未知</blockquote>"
+      batch_item_transferring: "<blockquote><b>↕️ {{.Index}}/{{.Total}} 传输中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_transferring_unknown: "<blockquote><b>↕️ {{.Index}}/{{.Total}} 传输中</b>\n<code>{{.Name}}</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / 未知</blockquote>"
+      batch_item_uploading: "<blockquote><b>⬆️ {{.Index}}/{{.Total}} 上传中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code></blockquote>"
+      batch_item_retrying: "<blockquote><b>🔁 {{.Index}}/{{.Total}} 上传重试</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n重试次数：<code>{{.Attempt}}/{{.Limit}}</code>\n失败前速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code>\n原因：<code>{{.Reason}}</code></blockquote>"
+      batch_item_confirming: "<blockquote><b>⏳ {{.Index}}/{{.Total}} 等待中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n<i>文件已上传，正在等待远端确认</i></blockquote>"
+      batch_summary_hidden_active: "🔄 另有 <code>{{.Count}}</code> 个文件正在处理"
+      batch_summary_confirming: "☁️ 已上传，等待整组发送：<code>{{.Count}}</code>"
+      batch_summary_failed: "❌ 失败：<code>{{.Count}}</code>"
+      batch_summary_skipped: "⏭️ 已跳过：<code>{{.Count}}</code>"
+      batch_done: "<b>✅ 处理完成</b>\n\n文件数: <code>{{.Count}}</code>\n总大小: <code>{{.Size}}</code>"
+      batch_done_with_skipped: "<b>⚠️ 处理完成</b>\n\n成功: <code>{{.Success}}</code>\n已跳过: <code>{{.Skipped}}</code>\n总大小: <code>{{.Size}}</code>"
+      batch_canceled: "<b>🚫 任务已取消</b>\n\n文件数: <code>{{.Total}}</code>\n已完成: <code>{{.Completed}}</code>\n未完成: <code>{{.Incomplete}}</code>\n已跳过: <code>{{.Skipped}}</code>"
+      batch_failed_item: "<b>❌ 处理失败</b>\n\n失败文件: <code>{{.Index}}. {{.Name}}</code>\n失败阶段: <code>{{.Stage}}</code>\n失败进度: <code>{{.Progress}}</code>\n失败前速度: <code>{{.Speed}}</code>\n原因: <code>{{.Reason}}</code>\n\n✅ 已完成: <code>{{.Completed}}</code>\n❌ 失败: <code>{{.Failed}}</code>\n⏹️ 未完成: <code>{{.Incomplete}}</code>"
+      batch_failed_group: "<b>❌ 批量上传失败</b>\n\n受影响文件: <code>{{.Affected}} 个</code>\n原因: <code>{{.Reason}}</code>\n\n✅ 已完成: <code>{{.Completed}}</code>\n❌ 批次失败: <code>{{.Failed}}</code>\n⏹️ 未完成: <code>{{.Incomplete}}</code>"
+      batch_failed_task: "<b>❌ 处理失败</b>\n\n原因: <code>{{.Reason}}</code>\n\n✅ 已完成: <code>{{.Completed}}</code>\n⏹️ 未完成: <code>{{.Incomplete}}</code>"
+      batch_failure_stage_download: "下载"
+      batch_failure_stage_cache: "本地缓存"
+      batch_failure_stage_upload: "上传"
+      batch_failure_stage_confirm: "云端确认"
+      batch_failure_stage_batch_upload: "批量上传"
+      batch_failure_stage_internal: "任务内部"
+      single_status_header: "<b>📦 正在处理</b>"
+      single_downloading: "<blockquote><b>⬇️ 下载中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code>\n保存至：<code>{{.Destination}}</code></blockquote>"
+      single_downloading_unknown: "<blockquote><b>⬇️ 下载中</b>\n<code>{{.Name}}</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / 未知\n保存至：<code>{{.Destination}}</code></blockquote>"
+      single_uploading: "<blockquote><b>⬆️ 上传中</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code>\n保存至：<code>{{.Destination}}</code></blockquote>"
+      single_upload_retrying: "<blockquote><b>🔁 上传重试</b>\n<code>{{.Name}}</code>\n{{.Bar}} <code>{{.Progress}}%</code>\n尝试次数：<code>{{.Attempt}}</code>\n速度：<code>{{.Speed}}</code>\n大小：<code>{{.Current}}</code> / <code>{{.Size}}</code>\n保存至：<code>{{.Destination}}</code></blockquote>"
+      single_done: "<b>✅ 处理完成</b>\n\n文件名：<code>{{.Name}}</code>\n总大小：<code>{{.Size}}</code>\n保存至：<code>{{.Destination}}</code>"
+      single_canceled: "<b>🚫 任务已取消</b>\n\n文件名：<code>{{.Name}}</code>"
+      single_failed: "<b>❌ 处理失败</b>\n\n文件名：<code>{{.Name}}</code>\n原因：<code>{{.Reason}}</code>"
       downloading_prefix: "正在下载\n总大小: "
       processing_list_prefix: "\n正在处理:\n"
       processing_none: "  - 无"
       avg_speed_prefix: "\n平均速度: "
       current_progress_prefix: "\n当前进度: "
-      task_canceled: "任务已取消"
       task_canceled_with_id: "处理已取消: {{.TaskID}}"
       task_failed_with_error: "处理失败: {{.Error}}"
-      batch_done_prefix: "处理完成\n文件数: "
       direct_done_prefix: "处理完成, 文件数量: "
       parsed_start_prefix: "开始下载 {{.Site}} 的资源\n总大小: "
       parsed_done_prefix: "处理完成, 资源数量: "
       telegraph_start_prefix: "开始下载Telegraph\n图片数量: "
       telegraph_progress_prefix: "正在下载\n当前进度: "
       telegraph_done_prefix: "处理完成\n图片数量: "
-      file_start_prefix: "开始下载\n文件名: "
-      file_processing_prefix: "正在处理下载任务\n文件名: "
-      download_failed_prefix: "下载失败\n文件名: "
-      download_done_prefix: "下载完成\n文件名: "
-      file_size_prefix: "\n文件大小: "
       save_path_prefix: "\n保存路径: "
       total_size_prefix: "\n总大小: "
       direct_start: "开始下载, 总大小: {{.SizeMB}} MB ({{.Count}} 个文件)"
-      file_name_prefix: "文件名: "
       error_prefix: "\n错误: "
       aria2_start: "等待 Aria2 下载完成 (GID: {{.GID}})..."
       aria2_downloading: "Aria2 正在下载 (GID: {{.GID}})\n"
@@ -343,6 +409,20 @@ bot:
       ytdlp_done: "yt-dlp 下载完成并已转存 ({{.Count}} 个文件)\n"
       downloaded_prefix: "\n已下载: "
       current_speed_prefix: "\n当前速度: "
+      transfer_start_prefix: "正在转存: "
+      transfer_progress_prefix: "转存进度: "
+      transfer_uploaded_prefix: "\n已上传: "
+      transfer_speed_prefix: "\n速度: "
+      transfer_remaining_time_prefix: "\n剩余时间: "
+      transfer_processing_prefix: "\n正在处理:\n"
+      transfer_processing_more: "...和其他 {{.Count}} 个文件\n"
+      transfer_failed_prefix: "转存失败\n"
+      transfer_success_prefix: "转存完成\n"
+      transfer_total_files_prefix: "\n总文件数: "
+      transfer_total_size_prefix: "\n总大小: "
+      transfer_elapsed_time_prefix: "\n耗时: "
+      transfer_avg_speed_prefix: "\n平均速度: "
+      transfer_failed_files_prefix: "\n失败文件数: "
     syncpeers:
       start: "正在同步对话列表..."
       success: "对话列表同步完成, 共同步 {{.Count}} 个对话"
@@ -353,4 +433,4 @@ bot:
       info_adding_aria2_download: "正在添加 Aria2 下载任务..."
       error_adding_aria2_download: "添加 Aria2 下载任务失败: {{.Error}}"
       info_aria2_download_added: "Aria2 下载任务已添加, GID: {{.GID}}"
-      info_select_storage: "请选择存储位置, 选择后将添加到 Aria2 下载队列"
+      info_select_storage: "请选择存储位置, 选择后将添加到 Aria2 下载队列"

common/utils/dlutil/dl.go

@@ -1,6 +1,9 @@
 package dlutil
 
-import "time"
+import (
+	"fmt"
+	"time"
+)
 
 var threadsLevels = []struct {
 	threads int
@@ -31,3 +34,23 @@ func GetSpeed(downloaded int64, startTime time.Time) float64 {
 	}
 	return float64(downloaded) / elapsed
 }
+
+// FormatSize formats a byte size as a human-readable string
+func FormatSize(bytes int64) string {
+	const (
+		KB = 1024
+		MB = KB * 1024
+		GB = MB * 1024
+	)
+
+	switch {
+	case bytes >= GB:
+		return fmt.Sprintf("%.2f GB", float64(bytes)/float64(GB))
+	case bytes >= MB:
+		return fmt.Sprintf("%.2f MB", float64(bytes)/float64(MB))
+	case bytes >= KB:
+		return fmt.Sprintf("%.2f KB", float64(bytes)/float64(KB))
+	default:
+		return fmt.Sprintf("%d B", bytes)
+	}
+}

common/utils/fsutil/file_test.go

@@ -0,0 +1,42 @@
+package fsutil_test
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/krau/SaveAny-Bot/common/utils/fsutil"
+)
+
+func TestCloseAndRemove(t *testing.T) {
+	tests := []struct {
+		name     string
+		preClose bool
+	}{
+		{name: "open file"},
+		{name: "already closed file", preClose: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filePath := filepath.Join(t.TempDir(), "cache-file")
+			file, err := fsutil.CreateFile(filePath)
+			if err != nil {
+				t.Fatalf("CreateFile() failed: %v", err)
+			}
+			if tt.preClose {
+				if err := file.Close(); err != nil {
+					t.Fatalf("Close() failed: %v", err)
+				}
+			}
+
+			if err := file.CloseAndRemove(); err != nil {
+				t.Fatalf("CloseAndRemove() failed: %v", err)
+			}
+			if _, err := os.Stat(filePath); !errors.Is(err, os.ErrNotExist) {
+				t.Fatalf("cache file still exists after CloseAndRemove(): %v", err)
+			}
+		})
+	}
+}

common/utils/fsutil/fs.go

@@ -1,6 +1,7 @@
 package fsutil
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"strings"
@@ -41,10 +42,11 @@ func (f *File) Remove() error {
 }
 
 func (f *File) CloseAndRemove() error {
-	if err := f.Close(); err != nil {
-		return err
+	closeErr := f.Close()
+	if errors.Is(closeErr, os.ErrClosed) {
+		closeErr = nil
 	}
-	return f.Remove()
+	return errors.Join(closeErr, f.Remove())
 }
 
 func CreateFile(fp string) (*File, error) {

common/utils/ioutil/progress_reader.go

@@ -17,7 +17,11 @@ type ProgressReadSeeker struct {
 
 // Seek implements io.ReadSeeker.
 func (pr *ProgressReadSeeker) Seek(offset int64, whence int) (int64, error) {
-	return pr.reader.Seek(offset, whence)
+	position, err := pr.reader.Seek(offset, whence)
+	if err == nil {
+		pr.read.Store(position)
+	}
+	return position, err
 }
 
 // NewProgressReader creates a new ProgressReader
@@ -54,7 +58,7 @@ func (pr *ProgressReadSeeker) Progress() float64 {
 	return float64(pr.read.Load()) / float64(pr.total.Load())
 }
 
-// Read returns the number of bytes read so far
+// BytesRead returns the current tracked reader position.
 func (pr *ProgressReadSeeker) BytesRead() int64 {
 	return pr.read.Load()
 }

common/utils/ioutil/progress_reader_test.go

@@ -0,0 +1,50 @@
+package ioutil
+
+import (
+	"bytes"
+	"io"
+	"testing"
+)
+
+func TestProgressReadSeekerTracksReads(t *testing.T) {
+	var gotRead, gotTotal int64
+	reader := NewProgressReader(bytes.NewReader([]byte("abcdef")), 6, func(read, total int64) {
+		gotRead = read
+		gotTotal = total
+	})
+
+	buffer := make([]byte, 4)
+	if _, err := io.ReadFull(reader, buffer); err != nil {
+		t.Fatalf("read failed: %v", err)
+	}
+
+	if gotRead != 4 || gotTotal != 6 {
+		t.Fatalf("progress = %d/%d, want 4/6", gotRead, gotTotal)
+	}
+	if reader.BytesRead() != 4 {
+		t.Fatalf("BytesRead() = %d, want 4", reader.BytesRead())
+	}
+}
+
+func TestProgressReadSeekerResetsPositionOnSeek(t *testing.T) {
+	reader := NewProgressReader(bytes.NewReader([]byte("abcdef")), 6, nil)
+	buffer := make([]byte, 4)
+	if _, err := io.ReadFull(reader, buffer); err != nil {
+		t.Fatalf("read failed: %v", err)
+	}
+
+	position, err := reader.Seek(0, io.SeekStart)
+	if err != nil {
+		t.Fatalf("seek failed: %v", err)
+	}
+	if position != 0 || reader.BytesRead() != 0 {
+		t.Fatalf("position after seek = %d (tracked %d), want 0", position, reader.BytesRead())
+	}
+
+	if _, err := io.ReadFull(reader, buffer[:2]); err != nil {
+		t.Fatalf("read after seek failed: %v", err)
+	}
+	if reader.BytesRead() != 2 {
+		t.Fatalf("BytesRead() after seek and read = %d, want 2", reader.BytesRead())
+	}
+}

common/utils/ioutil/writer.go

@@ -48,4 +48,4 @@ func NewProgressWriter(
 		wr:      wr,
 		onWrite: onWrite,
 	}
-}
+}

common/utils/tgutil/html.go

@@ -0,0 +1,35 @@
+package tgutil
+
+import (
+	stdhtml "html"
+
+	"github.com/gotd/td/telegram/message/entity"
+	messagehtml "github.com/gotd/td/telegram/message/html"
+	"github.com/gotd/td/telegram/message/styling"
+	"github.com/gotd/td/tg"
+)
+
+// EscapeHTMLTemplateData returns a copy of data with string values escaped for
+// interpolation into Telegram HTML templates.
+func EscapeHTMLTemplateData(data map[string]any) map[string]any {
+	escaped := make(map[string]any, len(data))
+	for key, value := range data {
+		if text, ok := value.(string); ok {
+			escaped[key] = stdhtml.EscapeString(text)
+			continue
+		}
+		escaped[key] = value
+	}
+	return escaped
+}
+
+// RenderHTML renders Telegram-compatible HTML into plain text and message
+// entities.
+func RenderHTML(markup string) (string, []tg.MessageEntityClass, error) {
+	var builder entity.Builder
+	if err := styling.Perform(&builder, messagehtml.String(nil, markup)); err != nil {
+		return "", nil, err
+	}
+	text, entities := builder.Complete()
+	return text, entities, nil
+}

common/utils/tgutil/html_test.go

@@ -0,0 +1,54 @@
+package tgutil
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestEscapeHTMLTemplateDataDoesNotMutateInput(t *testing.T) {
+	input := map[string]any{
+		"Text":  `<b>A&B</b>`,
+		"Count": 2,
+	}
+	escaped := EscapeHTMLTemplateData(input)
+
+	if got, want := escaped["Text"], "&lt;b&gt;A&amp;B&lt;/b&gt;"; got != want {
+		t.Fatalf("escaped text = %q, want %q", got, want)
+	}
+	if got := input["Text"]; got != `<b>A&B</b>` {
+		t.Fatalf("input was mutated: %q", got)
+	}
+	if got := escaped["Count"]; got != 2 {
+		t.Fatalf("non-string value = %v, want 2", got)
+	}
+}
+
+func TestRenderHTMLUsesTemplateStylesAndDecodesValues(t *testing.T) {
+	data := EscapeHTMLTemplateData(map[string]any{"Name": `<b>A&B</b>.bin`})
+	markup := `<blockquote><b>Uploading</b>
+<code>` + data["Name"].(string) + `</code></blockquote>`
+
+	text, entities, err := RenderHTML(markup)
+	if err != nil {
+		t.Fatalf("RenderHTML() failed: %v", err)
+	}
+	if want := "Uploading\n<b>A&B</b>.bin"; text != want {
+		t.Fatalf("rendered text = %q, want %q", text, want)
+	}
+
+	var bold, code, blockquote int
+	for _, messageEntity := range entities {
+		switch messageEntity.(type) {
+		case *tg.MessageEntityBold:
+			bold++
+		case *tg.MessageEntityCode:
+			code++
+		case *tg.MessageEntityBlockquote:
+			blockquote++
+		}
+	}
+	if bold != 1 || code != 1 || blockquote != 1 {
+		t.Fatalf("entity counts = bold:%d code:%d blockquote:%d", bold, code, blockquote)
+	}
+}

common/utils/tgutil/message.go

@@ -2,6 +2,7 @@ package tgutil
 
 import (
 	"fmt"
+	"sort"
 	"strconv"
 	"strings"
 	"unicode"
@@ -359,9 +360,16 @@ func GetGroupedMessages(ctx *ext.Context, chatID int64, msg *tg.Message) ([]*tg.
 			groupedMessages = append(groupedMessages, m)
 		}
 	}
+	sortMessagesByID(groupedMessages)
 	return groupedMessages, nil
 }
 
+func sortMessagesByID(messages []*tg.Message) {
+	sort.Slice(messages, func(i, j int) bool {
+		return messages[i].GetID() < messages[j].GetID()
+	})
+}
+
 func ExtractMessageEntityUrls(msg *tg.Message) []string {
 	if len(msg.Entities) == 0 {
 		return nil

common/utils/tgutil/message_test.go

@@ -0,0 +1,18 @@
+package tgutil
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+)
+
+func TestSortMessagesByID(t *testing.T) {
+	messages := []*tg.Message{{ID: 9}, {ID: 3}, {ID: 7}}
+	sortMessagesByID(messages)
+	want := []int{3, 7, 9}
+	for i := range messages {
+		if messages[i].GetID() != want[i] {
+			t.Fatalf("message %d has ID %d, want %d", i, messages[i].GetID(), want[i])
+		}
+	}
+}

config.example.toml

@@ -5,6 +5,10 @@ retry = 3      # 下载失败重试次数
 threads = 4    # 单个任务下载使用的最大线程数
 stream = false # 使用流式传输模式, 建议仅在硬盘空间十分有限时使用.
 
+[log]
+# 日志级别, 可选: debug, info, warn, error, fatal
+level = "debug"
+
 [telegram]
 # Bot Token
 # 更换 Bot Token 后请删除会话数据库文件 (默认路径为 data/session.db )
@@ -29,16 +33,27 @@ secret = ""
 # 转存完成后删除 Aria2 下载的本地文件
 remove_after_transfer = true
 
+# yt-dlp 视频下载配置
+[ytdlp]
+# 默认下载的最高视频清晰度 (按高度限制), 如 1080, 720, 480; 0 表示不限制 (下载最佳画质)
+# 仅在使用 /ytdlp 命令且未手动指定任何参数时生效
+max_height = 1080
+# 直接指定 yt-dlp format 选择表达式, 留空则使用 max_height
+# 设置后优先级高于 max_height, 例如: "bv*[height<=720]+ba/b"
+format = ""
+# 下载后转封装的视频容器格式, 留空则不转封装. 默认 mp4
+recode = "mp4"
+
 # HTTP API 配置
 [api]
-# 启用 HTTP API 服务
+# 启用 HTTP API
 enable = false
-# API 服务监听端口
+# 监听地址
+host = "0.0.0.0"
+# 监听端口
 port = 8080
-# API 访问令牌 (留空则不验证)
+# 认证 Token (必需)
 token = ""
-# 任务完成回调 Webhook URL (留空则不回调)
-webhook_url = ""
 
 # 存储列表
 [[storages]]
@@ -73,4 +88,4 @@ blacklist = true
 [[users]]
 id = 123456
 storages = ["本机1"]
-blacklist = false  # 使用白名单模式，此时，用户 123456 仅可使用标识名为 '本地1' 的存储
+blacklist = false  # 使用白名单模式，此时，用户 123456 仅可使用标识名为 '本地1' 的存储

config/flags.go

@@ -17,6 +17,7 @@ func RegisterFlags(cmd *cobra.Command) {
 	flags.Bool("stream", false, "enable stream mode")
 	flags.Bool("no-clean-cache", false, "do not clean cache on exit")
 	flags.String("proxy", "", "proxy URL (http, https, socks5, socks5h)")
+	flags.String("log-level", "", "log level (trace/debug, info, warn, error, fatal)")
 
 	// Telegram 配置
 	flags.String("telegram-token", "", "telegram bot token")
@@ -54,6 +55,7 @@ func bindFlags(cmd *cobra.Command) {
 	viper.BindPFlag("stream", flags.Lookup("stream"))
 	viper.BindPFlag("no_clean_cache", flags.Lookup("no-clean-cache"))
 	viper.BindPFlag("proxy", flags.Lookup("proxy"))
+	viper.BindPFlag("log.level", flags.Lookup("log-level"))
 
 	// Telegram
 	viper.BindPFlag("telegram.token", flags.Lookup("telegram-token"))

config/log.go

@@ -0,0 +1,5 @@
+package config
+
+type logConfig struct {
+	Level string `toml:"level" mapstructure:"level" json:"level"`
+}

config/storage/factory.go

@@ -16,6 +16,7 @@ var storageFactories = map[storenum.StorageType]func(cfg *BaseConfig) (StorageCo
 	storenum.Minio:    createStorageConfig(&MinioStorageConfig{}),
 	storenum.S3:       createStorageConfig(&S3StorageConfig{}),
 	storenum.Telegram: createStorageConfig(&TelegramStorageConfig{}),
+	storenum.Rclone:   createStorageConfig(&RcloneStorageConfig{}),
 }
 
 func createStorageConfig(configType StorageConfig) func(cfg *BaseConfig) (StorageConfig, error) {

config/storage/rclone.go

@@ -0,0 +1,33 @@
+package storage
+
+import (
+	"fmt"
+
+	storenum "github.com/krau/SaveAny-Bot/pkg/enums/storage"
+)
+
+type RcloneStorageConfig struct {
+	BaseConfig
+	// The name of the remote as defined in rclone config
+	Remote   string `toml:"remote" mapstructure:"remote" json:"remote"`
+	BasePath string `toml:"base_path" mapstructure:"base_path" json:"base_path"`
+	// The path to the rclone config file, if not using the default
+	ConfigPath string `toml:"config_path" mapstructure:"config_path" json:"config_path"`
+	// Additional flags to pass to rclone commands
+	Flags []string `toml:"flags" mapstructure:"flags" json:"flags"`
+}
+
+func (r *RcloneStorageConfig) Validate() error {
+	if r.Remote == "" {
+		return fmt.Errorf("remote is required for rclone storage")
+	}
+	return nil
+}
+
+func (r *RcloneStorageConfig) GetType() storenum.StorageType {
+	return storenum.Rclone
+}
+
+func (r *RcloneStorageConfig) GetName() string {
+	return r.Name
+}

config/storage/telegram.go

@@ -8,14 +8,16 @@ import (
 
 type TelegramStorageConfig struct {
 	BaseConfig
-	ChatID    int64 `toml:"chat_id" mapstructure:"chat_id" json:"chat_id"`
-	ForceFile bool  `toml:"force_file" mapstructure:"force_file" json:"force_file"`
-	RateLimit int   `toml:"rate_limit" mapstructure:"rate_limit" json:"rate_limit"`
-	RateBurst int   `toml:"rate_burst" mapstructure:"rate_burst" json:"rate_burst"`
-	SkipLarge bool  `toml:"skip_large" mapstructure:"skip_large" json:"skip_large"` // skip files larger than Telegram limit(2GB)
-	// split files larger than Telegram limit(2GB) into parts of specified size, in MB, leave 0 to set default(2000MB)
+	ChatID          int64 `toml:"chat_id" mapstructure:"chat_id" json:"chat_id"`
+	ForceFile       bool  `toml:"force_file" mapstructure:"force_file" json:"force_file"`
+	RateLimit       int   `toml:"rate_limit" mapstructure:"rate_limit" json:"rate_limit"`
+	RateBurst       int   `toml:"rate_burst" mapstructure:"rate_burst" json:"rate_burst"`
+	SkipLarge       bool  `toml:"skip_large" mapstructure:"skip_large" json:"skip_large"` // skip files larger than Telegram limit(2GB)
+	SplitLargeVideo bool  `toml:"split_large_video" mapstructure:"split_large_video" json:"split_large_video"`
+	// split files larger than the uploader account limit into parts of specified size, in MB
+	// leave 0 to use the account limit (2000MB for bots/regular users, 4000MB for Premium users)
 	// only effective when SkipLarge is false
-	// use zip when splitting
+	// use zip when splitting non-video files or when lossless video splitting is disabled/unavailable
 	SplitSizeMB int64 `toml:"split_size_mb" mapstructure:"split_size_mb" json:"split_size_mb"`
 }
 

config/viper.go

@@ -23,7 +23,9 @@ type Config struct {
 	Threads      int         `toml:"threads" mapstructure:"threads" json:"threads"`
 	Stream       bool        `toml:"stream" mapstructure:"stream" json:"stream"`
 	Proxy        string      `toml:"proxy" mapstructure:"proxy" json:"proxy"`
+	Log          logConfig   `toml:"log" mapstructure:"log" json:"log"`
 	Aria2        aria2Config `toml:"aria2" mapstructure:"aria2" json:"aria2"`
+	API          apiConfig   `toml:"api" mapstructure:"api" json:"api"`
 
 	Cache    cacheConfig             `toml:"cache" mapstructure:"cache" json:"cache"`
 	Users    []userConfig            `toml:"users" mapstructure:"users" json:"users"`
@@ -33,7 +35,7 @@ type Config struct {
 	Storages []storage.StorageConfig `toml:"-" mapstructure:"-" json:"storages"`
 	Parser   parserConfig            `toml:"parser" mapstructure:"parser" json:"parser"`
 	Hook     hookConfig              `toml:"hook" mapstructure:"hook" json:"hook"`
-	API      apiConfig               `toml:"api" mapstructure:"api" json:"api"`
+	Ytdlp    YtdlpConfig             `toml:"ytdlp" mapstructure:"ytdlp" json:"ytdlp"`
 }
 
 type aria2Config struct {
@@ -44,10 +46,10 @@ type aria2Config struct {
 }
 
 type apiConfig struct {
-	Enable     bool   `toml:"enable" mapstructure:"enable" json:"enable"`
-	Port       int    `toml:"port" mapstructure:"port" json:"port"`
-	Token      string `toml:"token" mapstructure:"token" json:"token"`
-	WebhookURL string `toml:"webhook_url" mapstructure:"webhook_url" json:"webhook_url"`
+	Enable bool   `toml:"enable" mapstructure:"enable" json:"enable"`
+	Host   string `toml:"host" mapstructure:"host" json:"host"`
+	Port   int    `toml:"port" mapstructure:"port" json:"port"`
+	Token  string `toml:"token" mapstructure:"token" json:"token"`
 }
 
 var cfg = &Config{}
@@ -100,10 +102,11 @@ func Init(ctx context.Context, configFile ...string) error {
 
 	defaultConfigs := map[string]any{
 		// 基础配置
-		"lang":    "zh-Hans",
-		"workers": 3,
-		"retry":   3,
-		"threads": 4,
+		"lang":      "zh-Hans",
+		"workers":   3,
+		"retry":     3,
+		"threads":   4,
+		"log.level": "debug",
 
 		// 缓存配置
 		"cache.ttl":          86400,
@@ -125,22 +128,19 @@ func Init(ctx context.Context, configFile ...string) error {
 		"db.session": "data/session.db",
 
 		// API
-		"api.enable":      false,
-		"api.port":        8080,
-		"api.token":       "",
-		"api.webhook_url": "",
+		"api.enable": false,
+		"api.host":   "0.0.0.0",
+		"api.port":   8080,
+		"api.token":  "",
+
+		// yt-dlp
+		"ytdlp.recode": "mp4",
 	}
 
 	for key, value := range defaultConfigs {
 		viper.SetDefault(key, value)
 	}
 
-	if err := viper.SafeWriteConfigAs("config.toml"); err != nil {
-		if _, ok := err.(viper.ConfigFileAlreadyExistsError); !ok {
-			return fmt.Errorf("error saving default config: %w", err)
-		}
-	}
-
 	if err := viper.ReadInConfig(); err != nil {
 		fmt.Println("Error reading config file, ", err)
 		return err

config/ytdlp.go

@@ -0,0 +1,13 @@
+package config
+
+type YtdlpConfig struct {
+	// MaxHeight limits the video resolution by height in pixels (e.g. 1080, 720).
+	// 0 means no limit (best available). Ignored when Format is set.
+	MaxHeight int `toml:"max_height" mapstructure:"max_height" json:"max_height"`
+	// Format is a raw yt-dlp format selector (-f). When set, it takes precedence
+	// over MaxHeight and gives the user full control.
+	Format string `toml:"format" mapstructure:"format" json:"format"`
+	// Recode is the target video container yt-dlp recodes into (e.g. mp4).
+	// Empty disables recoding.
+	Recode string `toml:"recode" mapstructure:"recode" json:"recode"`
+}

core/core.go

@@ -8,6 +8,7 @@ import (
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
 	"github.com/krau/SaveAny-Bot/pkg/queue"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 )
 
 var queueInstance *queue.TaskQueue[Executable]
@@ -30,11 +31,14 @@ func worker(ctx context.Context, qe *queue.TaskQueue[Executable], semaphore chan
 			break // queue closed and empty
 		}
 		exe := qtask.Data
+		taskCtx := qtask.Context()
 		logger.Infof("Processing task: %s", exe.TaskID())
-		if err := ExecCommandString(qtask.Context(), execHooks.TaskBeforeStart); err != nil {
+		taskevent.Emit(taskCtx, taskevent.Event{TaskID: exe.TaskID(), Phase: taskevent.PhaseStart})
+		if err := ExecCommandString(taskCtx, execHooks.TaskBeforeStart); err != nil {
 			logger.Errorf("Failed to execute before start hook for task %s: %v", exe.TaskID(), err)
 		}
-		if err := exe.Execute(qtask.Context()); err != nil {
+		err = exe.Execute(taskCtx)
+		if err != nil {
 			if errors.Is(err, context.Canceled) {
 				logger.Infof("Task %s was canceled", exe.TaskID())
 				if err := ExecCommandString(ctx, execHooks.TaskCancel); err != nil {
@@ -52,6 +56,7 @@ func worker(ctx context.Context, qe *queue.TaskQueue[Executable], semaphore chan
 				logger.Errorf("Failed to execute success hook for task %s: %v", exe.TaskID(), err)
 			}
 		}
+		taskevent.Emit(taskCtx, taskevent.Event{TaskID: exe.TaskID(), Phase: taskevent.PhaseDone, Err: err})
 		qe.Done(qtask.ID)
 		<-semaphore
 	}

core/tasks/aria2dl/execute.go

@@ -6,12 +6,14 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strconv"
 	"time"
 
 	"github.com/charmbracelet/log"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/aria2"
 	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 )
 
 // Execute implements core.Executable.
@@ -77,6 +79,12 @@ func (t *Task) waitForDownload(ctx context.Context) error {
 			if t.Progress != nil {
 				t.Progress.OnProgress(ctx, t, status)
 			}
+			taskevent.Emit(ctx, taskevent.Event{
+				TaskID:          t.ID,
+				Phase:           taskevent.PhaseProgress,
+				TotalBytes:      parseInt64(status.TotalLength),
+				DownloadedBytes: parseInt64(status.CompletedLength),
+			})
 
 			// Check if download is complete
 			if status.IsDownloadComplete() {
@@ -248,3 +256,16 @@ func (t *Task) cancelAria2Download() {
 		logger.Debugf("Failed to remove download result for %s: %v", t.GID, err)
 	}
 }
+
+// parseInt64 parses an aria2 status string (decimal bytes) into int64,
+// returning 0 on failure so it can be used directly in progress events.
+func parseInt64(s string) int64 {
+	if s == "" {
+		return 0
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	if err != nil {
+		return 0
+	}
+	return n
+}

core/tasks/batchtfile/execute.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"path"
+	"time"
 
 	"github.com/charmbracelet/log"
 	"github.com/duke-git/lancet/v2/retry"
@@ -14,44 +15,269 @@ import (
 	"github.com/krau/SaveAny-Bot/common/utils/ioutil"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/pkg/storagetypes"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
+	"github.com/krau/SaveAny-Bot/storage"
 	"golang.org/x/sync/errgroup"
 )
 
+type executionGroup struct {
+	elems      []*TaskElement
+	batchSaver storage.StorageBatchSaver
+}
+
+func (g executionGroup) usesBatchSaver() bool {
+	return g.batchSaver != nil
+}
+
 func (t *Task) Execute(ctx context.Context) error {
 	logger := log.FromContext(ctx).WithPrefix(fmt.Sprintf("batch_file[%s]", t.ID))
 	logger.Info("Starting batch file task")
 	t.Progress.OnStart(ctx, t)
-	workers := config.C().Workers
-	eg, gctx := errgroup.WithContext(ctx)
-	eg.SetLimit(workers)
-	for _, elem := range t.elems {
-		eg.Go(func() error {
-			t.processingMu.RLock()
-			if t.processing[elem.ID] != nil {
-				return fmt.Errorf("element with ID %s is already being processed", elem.ID)
+	groups := t.executionGroups()
+	var err error
+	for i := 0; i < len(groups); {
+		if groups[i].usesBatchSaver() {
+			err = t.processBatch(ctx, groups[i])
+			i++
+		} else {
+			end := i + 1
+			for end < len(groups) && !groups[end].usesBatchSaver() {
+				end++
 			}
-			t.processingMu.RUnlock()
-			t.processingMu.Lock()
-			t.processing[elem.ID] = &elem
-			t.processingMu.Unlock()
-			defer func() {
-				t.processingMu.Lock()
-				delete(t.processing, elem.ID)
-				t.processingMu.Unlock()
-			}()
-			return t.processElement(gctx, elem)
-		})
+			elems := make([]*TaskElement, 0, end-i)
+			for _, group := range groups[i:end] {
+				elems = append(elems, group.elems...)
+			}
+			err = t.processElements(ctx, elems)
+			i = end
+		}
+		if err != nil {
+			break
+		}
 	}
-	err := eg.Wait()
 	if err != nil {
 		logger.Errorf("Error during batch file processing: %v", err)
 	} else {
 		logger.Info("Batch file task completed successfully")
 	}
+	t.finishItems(err)
 	t.Progress.OnDone(ctx, t, err)
 	return err
 }
 
+func (t *Task) executionGroups() []executionGroup {
+	groups := make([]executionGroup, 0, len(t.elems))
+	for i := 0; i < len(t.elems); {
+		elem := &t.elems[i]
+		batchSaver, batchCapable := elem.Storage.(storage.StorageBatchSaver)
+		if !batchCapable || elem.sourceGroupKey == "" {
+			groups = append(groups, executionGroup{elems: []*TaskElement{elem}})
+			i++
+			continue
+		}
+
+		end := i + 1
+		for end < len(t.elems) {
+			next := &t.elems[end]
+			if next.Storage != elem.Storage || next.sourceGroupKey != elem.sourceGroupKey {
+				break
+			}
+			end++
+		}
+		elems := make([]*TaskElement, 0, end-i)
+		for j := i; j < end; j++ {
+			elems = append(elems, &t.elems[j])
+		}
+		groups = append(groups, executionGroup{elems: elems, batchSaver: batchSaver})
+		i = end
+	}
+	return groups
+}
+
+func (t *Task) processElements(ctx context.Context, elems []*TaskElement) error {
+	eg, gctx := errgroup.WithContext(ctx)
+	eg.SetLimit(config.C().Workers)
+	for _, elem := range elems {
+		eg.Go(func() error {
+			if err := t.markProcessing(ctx, elem); err != nil {
+				return err
+			}
+			defer t.unmarkProcessing(elem.ID)
+			return t.processElement(gctx, *elem)
+		})
+	}
+	return eg.Wait()
+}
+
+func (t *Task) processBatch(ctx context.Context, group executionGroup) error {
+	defer func() {
+		for _, elem := range group.elems {
+			if err := os.Remove(elem.localPath); err != nil && !os.IsNotExist(err) {
+				log.FromContext(ctx).Warnf("Failed to cleanup batch cache file %s: %v", elem.localPath, err)
+			}
+		}
+	}()
+
+	eg, gctx := errgroup.WithContext(ctx)
+	eg.SetLimit(config.C().Workers)
+	for _, elem := range group.elems {
+		eg.Go(func() error {
+			if err := t.markProcessing(ctx, elem); err != nil {
+				return err
+			}
+			defer t.unmarkProcessing(elem.ID)
+			return t.downloadElement(gctx, elem)
+		})
+	}
+	if err := eg.Wait(); err != nil {
+		return err
+	}
+
+	items := make([]storagetypes.BatchItem, 0, len(group.elems))
+	openFiles := make([]*os.File, 0, len(group.elems))
+	defer func() {
+		for _, file := range openFiles {
+			if err := file.Close(); err != nil {
+				log.FromContext(ctx).Warnf("Failed to close batch cache file %s: %v", file.Name(), err)
+			}
+		}
+	}()
+	for _, elem := range group.elems {
+		file, err := os.Open(elem.localPath)
+		if err != nil {
+			t.markItemFailed(elem.ID, FailureStageCache, err)
+			return fmt.Errorf("failed to open cache file: %w", err)
+		}
+		stat, err := file.Stat()
+		if err != nil {
+			file.Close()
+			t.markItemFailed(elem.ID, FailureStageCache, err)
+			return fmt.Errorf("failed to get cache file stat: %w", err)
+		}
+		openFiles = append(openFiles, file)
+		items = append(items, storagetypes.BatchItem{
+			Reader:          file,
+			StoragePath:     elem.Path,
+			Size:            stat.Size(),
+			SourceGroupKey:  elem.sourceGroupKey,
+			Caption:         elem.sourceCaption,
+			PreserveCaption: elem.preserveCaption,
+		})
+	}
+	for index, item := range items {
+		t.recordDownloadComplete(group.elems[index].ID, item.Size)
+	}
+	return t.saveBatchItems(ctx, group, items)
+}
+
+func (t *Task) saveBatchItems(ctx context.Context, group executionGroup, items []storagetypes.BatchItem) error {
+	t.startUpload(ctx)
+	if progressSaver, ok := group.batchSaver.(storage.StorageBatchProgressSaver); ok {
+		err := progressSaver.SaveBatchWithProgress(ctx, items, func(index int, uploaded, total int64) {
+			if index < 0 || index >= len(group.elems) {
+				return
+			}
+			t.uploadCallback(ctx, group.elems[index].ID)(uploaded, total)
+		})
+		if err != nil {
+			for _, elem := range group.elems {
+				t.markItemFailed(elem.ID, FailureStageBatchUpload, err)
+			}
+			t.notifyStateChange(ctx)
+			return fmt.Errorf("failed to save batch: %w", err)
+		}
+		for index, elem := range group.elems {
+			t.uploadCallback(ctx, elem.ID)(items[index].Size, items[index].Size)
+			t.markItemCompleted(elem.ID)
+		}
+		t.notifyStateChange(ctx)
+		return nil
+	}
+	for i := range items {
+		items[i].Reader = ioutil.NewProgressReader(
+			items[i].Reader,
+			items[i].Size,
+			t.uploadCallback(ctx, group.elems[i].ID),
+		)
+	}
+	if err := group.batchSaver.SaveBatch(ctx, items); err != nil {
+		for _, elem := range group.elems {
+			t.markItemFailed(elem.ID, FailureStageBatchUpload, err)
+		}
+		t.notifyStateChange(ctx)
+		return fmt.Errorf("failed to save batch: %w", err)
+	}
+	for index, elem := range group.elems {
+		t.uploadCallback(ctx, elem.ID)(items[index].Size, items[index].Size)
+		t.markItemCompleted(elem.ID)
+	}
+	t.notifyStateChange(ctx)
+	return nil
+}
+
+func (t *Task) markProcessing(ctx context.Context, elem *TaskElement) error {
+	t.processingMu.Lock()
+	if t.processing[elem.ID] != nil {
+		t.processingMu.Unlock()
+		return fmt.Errorf("element with ID %s is already being processed", elem.ID)
+	}
+	t.processing[elem.ID] = elem
+	t.processingMu.Unlock()
+	t.markItemActive(elem.ID, elem.stream, time.Now())
+	t.Progress.OnProgress(ctx, t)
+	return nil
+}
+
+func (t *Task) unmarkProcessing(id string) {
+	t.processingMu.Lock()
+	delete(t.processing, id)
+	t.processingMu.Unlock()
+}
+
+func (t *Task) downloadElement(ctx context.Context, elem *TaskElement) error {
+	logger := log.FromContext(ctx).WithPrefix(fmt.Sprintf("file[%s]", elem.File.Name()))
+	logger.Info("Starting file download")
+	localFile, err := fsutil.CreateFile(elem.localPath)
+	if err != nil {
+		t.markItemFailed(elem.ID, FailureStageCache, err)
+		t.notifyStateChange(ctx)
+		return fmt.Errorf("failed to create local file: %w", err)
+	}
+	wrAt := ioutil.NewProgressWriterAt(localFile, func(n int) {
+		t.recordItemDownload(elem.ID, int64(n), time.Now())
+		downloaded := t.downloaded.Add(int64(n))
+		t.Progress.OnProgress(ctx, t)
+		taskevent.Emit(ctx, taskevent.Event{
+			TaskID:          t.ID,
+			Phase:           taskevent.PhaseProgress,
+			TotalBytes:      t.totalSize,
+			DownloadedBytes: downloaded,
+		})
+	})
+	_, downloadErr := tdler.NewDownloader(elem.File).Parallel(ctx, wrAt)
+	closeErr := localFile.Close()
+	if downloadErr != nil {
+		t.markItemFailed(elem.ID, FailureStageDownload, downloadErr)
+		t.notifyStateChange(ctx)
+		return fmt.Errorf("failed to download file: %w", downloadErr)
+	}
+	if closeErr != nil {
+		t.markItemFailed(elem.ID, FailureStageCache, closeErr)
+		t.notifyStateChange(ctx)
+		return fmt.Errorf("failed to close cache file: %w", closeErr)
+	}
+	logger.Info("File downloaded successfully")
+	if path.Ext(elem.FileName()) == "" {
+		if ext := fsutil.DetectFileExt(elem.localPath); ext != "" {
+			elem.Path += ext
+		}
+	}
+	t.markItemDownloaded(elem.ID)
+	t.Progress.OnProgress(ctx, t)
+	return nil
+}
+
 func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 	logger := log.FromContext(ctx).WithPrefix(fmt.Sprintf("file[%s]", elem.File.Name()))
 	if elem.stream {
@@ -59,11 +285,23 @@ func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 		defer pr.Close()
 		errg, uploadCtx := errgroup.WithContext(ctx)
 		errg.Go(func() error {
-			return elem.Storage.Save(uploadCtx, pr, elem.Path)
+			err := elem.Storage.Save(uploadCtx, pr, elem.Path)
+			if err != nil {
+				t.markItemFailed(elem.ID, FailureStageUpload, err)
+				t.notifyStateChange(ctx)
+			}
+			return err
 		})
 		wr := ioutil.NewProgressWriter(pw, func(n int) {
-			t.downloaded.Add(int64(n))
+			t.recordItemDownload(elem.ID, int64(n), time.Now())
+			downloaded := t.downloaded.Add(int64(n))
 			t.Progress.OnProgress(ctx, t)
+			taskevent.Emit(ctx, taskevent.Event{
+				TaskID:          t.ID,
+				Phase:           taskevent.PhaseProgress,
+				TotalBytes:      t.totalSize,
+				DownloadedBytes: downloaded,
+			})
 		})
 		errg.Go(func() error {
 			defer pw.Close()
@@ -71,6 +309,8 @@ func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 			_, err := tdler.NewDownloader(elem.File).Stream(uploadCtx, wr)
 			if err != nil {
 				logger.Errorf("Failed to download file: %v", err)
+				t.markItemFailed(elem.ID, FailureStageDownload, err)
+				t.notifyStateChange(ctx)
 				pw.CloseWithError(err)
 			}
 			return err
@@ -78,12 +318,17 @@ func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 		if err := errg.Wait(); err != nil {
 			return fmt.Errorf("failed to download file in stream mode: %w", err)
 		}
+		t.recordDownloadComplete(elem.ID, 0)
+		t.markItemCompleted(elem.ID)
+		t.notifyStateChange(ctx)
 		logger.Info("File downloaded successfully in stream mode")
 		return nil
 	}
 	logger.Info("Starting file download")
 	localFile, err := fsutil.CreateFile(elem.localPath)
 	if err != nil {
+		t.markItemFailed(elem.ID, FailureStageCache, err)
+		t.notifyStateChange(ctx)
 		return fmt.Errorf("failed to create local file: %w", err)
 	}
 	defer func() {
@@ -92,11 +337,20 @@ func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 		}
 	}()
 	wrAt := ioutil.NewProgressWriterAt(localFile, func(n int) {
-		t.downloaded.Add(int64(n))
+		t.recordItemDownload(elem.ID, int64(n), time.Now())
+		downloaded := t.downloaded.Add(int64(n))
 		t.Progress.OnProgress(ctx, t)
+		taskevent.Emit(ctx, taskevent.Event{
+			TaskID:          t.ID,
+			Phase:           taskevent.PhaseProgress,
+			TotalBytes:      t.totalSize,
+			DownloadedBytes: downloaded,
+		})
 	})
 	_, err = tdler.NewDownloader(elem.File).Parallel(ctx, wrAt)
 	if err != nil {
+		t.markItemFailed(elem.ID, FailureStageDownload, err)
+		t.notifyStateChange(ctx)
 		return fmt.Errorf("failed to download file: %w", err)
 	}
 	logger.Info("File downloaded successfully")
@@ -109,21 +363,50 @@ func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
 	var fileStat os.FileInfo
 	fileStat, err = os.Stat(elem.localPath)
 	if err != nil {
+		t.markItemFailed(elem.ID, FailureStageCache, err)
+		t.notifyStateChange(ctx)
 		return fmt.Errorf("failed to get file stat: %w", err)
 	}
+	t.recordDownloadComplete(elem.ID, fileStat.Size())
 	vctx := context.WithValue(ctx, ctxkey.ContentLength, fileStat.Size())
+	t.startUpload(vctx)
+	onProgress := t.uploadCallback(vctx, elem.ID)
+	attempt := 0
+	retryLimit := int(config.C().Retry)
+	lastFailureStage := FailureStageUpload
 	err = retry.Retry(func() error {
+		attempt++
 		var file *os.File
 		file, err = os.Open(elem.localPath)
 		if err != nil {
+			lastFailureStage = FailureStageCache
+			t.markItemRetry(elem.ID, lastFailureStage, attempt, retryLimit, err)
+			t.notifyStateChange(vctx)
 			return fmt.Errorf("failed to open cache file: %w", err)
 		}
 		defer file.Close()
-		if err = elem.Storage.Save(vctx, file, elem.Path); err != nil {
+		onProgress(0, fileStat.Size())
+		if progressSaver, ok := elem.Storage.(storage.StorageProgressSaver); ok {
+			err = progressSaver.SaveWithProgress(vctx, file, elem.Path, onProgress)
+		} else {
+			err = elem.Storage.Save(vctx, ioutil.NewProgressReader(file, fileStat.Size(), onProgress), elem.Path)
+		}
+		if err != nil {
 			logger.Errorf("Failed to save file: %s, retrying...", err)
+			lastFailureStage = t.itemFailureStage(elem.ID)
+			t.markItemRetry(elem.ID, lastFailureStage, attempt, retryLimit, err)
+			t.notifyStateChange(vctx)
 			return err
 		}
 		return nil
 	}, retry.Context(vctx), retry.RetryTimes(uint(config.C().Retry)))
+	if err == nil {
+		onProgress(fileStat.Size(), fileStat.Size())
+		t.markItemCompleted(elem.ID)
+		t.notifyStateChange(vctx)
+	} else {
+		t.markItemFailed(elem.ID, lastFailureStage, err)
+		t.notifyStateChange(vctx)
+	}
 	return err
 }

core/tasks/batchtfile/execute_group_test.go

@@ -0,0 +1,57 @@
+package batchtfile
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/pkg/tfile"
+	tgstorage "github.com/krau/SaveAny-Bot/storage/telegram"
+)
+
+func TestExecutionGroupsPreserveSourceAlbums(t *testing.T) {
+	stor := new(tgstorage.Telegram)
+	otherStor := new(tgstorage.Telegram)
+	task := Task{elems: []TaskElement{
+		{Storage: stor, sourceGroupKey: "album-1"},
+		{Storage: stor, sourceGroupKey: "album-1"},
+		{Storage: stor},
+		{Storage: stor, sourceGroupKey: "album-2"},
+		{Storage: stor, sourceGroupKey: "album-2"},
+		{Storage: otherStor, sourceGroupKey: "album-2"},
+	}}
+
+	groups := task.executionGroups()
+	wantSizes := []int{2, 1, 2, 1}
+	wantBatch := []bool{true, false, true, true}
+	if len(groups) != len(wantSizes) {
+		t.Fatalf("got %d groups, want %d", len(groups), len(wantSizes))
+	}
+	for i := range groups {
+		if got := len(groups[i].elems); got != wantSizes[i] {
+			t.Errorf("group %d has %d elements, want %d", i, got, wantSizes[i])
+		}
+		if got := groups[i].usesBatchSaver(); got != wantBatch[i] {
+			t.Errorf("group %d batch=%v, want %v", i, got, wantBatch[i])
+		}
+	}
+}
+
+func TestSourceMetadataPreservesAlbumIdentityAndCaption(t *testing.T) {
+	msg := &tg.Message{
+		PeerID:  &tg.PeerChannel{ChannelID: 77},
+		Message: "original caption",
+	}
+	msg.SetGroupedID(42)
+	file := tfile.NewTGFile(nil, nil, 0, "photo.jpg", tfile.WithMessage(msg))
+
+	groupKey, caption, preserveCaption := sourceMetadata(file)
+	if groupKey != "*tg.PeerChannel:77:42" {
+		t.Fatalf("group key = %q, want %q", groupKey, "*tg.PeerChannel:77:42")
+	}
+	if caption != "original caption" {
+		t.Fatalf("caption = %q, want original caption", caption)
+	}
+	if !preserveCaption {
+		t.Fatal("preserveCaption = false, want true")
+	}
+}

core/tasks/batchtfile/item_progress.go

@@ -0,0 +1,360 @@
+package batchtfile
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+)
+
+const (
+	transferSpeedWindow  = 5 * time.Second
+	transferSamplePeriod = 250 * time.Millisecond
+)
+
+// ItemPhase describes the current lifecycle stage of one batch item.
+type ItemPhase uint8
+
+const (
+	ItemPhaseWaiting ItemPhase = iota
+	ItemPhaseDownloading
+	ItemPhaseTransferring
+	ItemPhaseDownloaded
+	ItemPhaseUploading
+	ItemPhaseRetrying
+	ItemPhaseConfirming
+	ItemPhaseCompleted
+	ItemPhaseFailed
+	ItemPhaseStopped
+)
+
+// FailureStage identifies the operation that failed for one batch item.
+type FailureStage uint8
+
+const (
+	FailureStageNone FailureStage = iota
+	FailureStageDownload
+	FailureStageCache
+	FailureStageUpload
+	FailureStageConfirm
+	FailureStageBatchUpload
+	FailureStageInternal
+)
+
+// TaskItemProgress is an immutable progress snapshot for one batch item.
+type TaskItemProgress struct {
+	Index         int
+	ID            string
+	Name          string
+	Size          int64
+	Downloaded    int64
+	Uploaded      int64
+	DownloadSpeed float64
+	UploadSpeed   float64
+	Phase         ItemPhase
+	FailureStage  FailureStage
+	RetryAttempt  int
+	RetryLimit    int
+	Error         string
+}
+
+type transferSample struct {
+	at    time.Time
+	bytes int64
+}
+
+type transferMeter struct {
+	samples []transferSample
+	latest  transferSample
+	hasData bool
+}
+
+func (m *transferMeter) record(now time.Time, transferred int64) {
+	if m.hasData && transferred < m.latest.bytes {
+		m.reset()
+	}
+	if m.hasData && now.Before(m.latest.at) {
+		now = m.latest.at
+	}
+	sample := transferSample{at: now, bytes: transferred}
+	m.latest = sample
+	m.hasData = true
+	if len(m.samples) == 0 {
+		m.samples = append(m.samples, sample)
+		return
+	}
+	if now.Sub(m.samples[len(m.samples)-1].at) >= transferSamplePeriod {
+		m.samples = append(m.samples, sample)
+	}
+	cutoff := now.Add(-transferSpeedWindow)
+	for len(m.samples) > 1 && m.samples[0].at.Before(cutoff) {
+		m.samples = m.samples[1:]
+	}
+}
+
+func (m *transferMeter) speed() float64 {
+	if !m.hasData || len(m.samples) == 0 {
+		return 0
+	}
+	first := m.samples[0]
+	last := m.latest
+	elapsed := last.at.Sub(first.at).Seconds()
+	if elapsed <= 0 || last.bytes <= first.bytes {
+		return 0
+	}
+	return float64(last.bytes-first.bytes) / elapsed
+}
+
+func (m *transferMeter) reset() {
+	m.samples = m.samples[:0]
+	m.latest = transferSample{}
+	m.hasData = false
+}
+
+type itemProgressState struct {
+	index         int
+	id            string
+	name          string
+	expectedSize  int64
+	actualSize    int64
+	downloaded    int64
+	uploaded      int64
+	phase         ItemPhase
+	failureStage  FailureStage
+	retryAttempt  int
+	retryLimit    int
+	err           string
+	downloadMeter transferMeter
+	uploadMeter   transferMeter
+}
+
+func newItemProgressStates(elems []TaskElement) ([]itemProgressState, map[string]int) {
+	states := make([]itemProgressState, 0, len(elems))
+	index := make(map[string]int, len(elems))
+	for i, elem := range elems {
+		name := ""
+		size := int64(0)
+		if elem.File != nil {
+			name = elem.File.Name()
+			size = elem.File.Size()
+		}
+		states = append(states, itemProgressState{
+			index:        i + 1,
+			id:           elem.ID,
+			name:         name,
+			expectedSize: size,
+			phase:        ItemPhaseWaiting,
+		})
+		index[elem.ID] = i
+	}
+	return states, index
+}
+
+func (t *Task) updateItem(id string, update func(*itemProgressState)) bool {
+	t.itemMu.Lock()
+	defer t.itemMu.Unlock()
+	index, ok := t.itemIndex[id]
+	if !ok || index < 0 || index >= len(t.itemStates) {
+		return false
+	}
+	update(&t.itemStates[index])
+	return true
+}
+
+func (t *Task) markItemActive(id string, stream bool, now time.Time) {
+	t.updateItem(id, func(item *itemProgressState) {
+		if stream {
+			item.phase = ItemPhaseTransferring
+		} else {
+			item.phase = ItemPhaseDownloading
+		}
+		item.failureStage = FailureStageNone
+		item.err = ""
+		item.downloadMeter.record(now, item.downloaded)
+		if stream {
+			item.uploadMeter.record(now, item.uploaded)
+		}
+	})
+}
+
+func (t *Task) recordItemDownload(id string, n int64, now time.Time) {
+	if n <= 0 {
+		return
+	}
+	t.updateItem(id, func(item *itemProgressState) {
+		item.downloaded += n
+		item.downloadMeter.record(now, item.downloaded)
+		if item.phase == ItemPhaseTransferring {
+			item.uploaded += n
+			item.uploadMeter.record(now, item.uploaded)
+		}
+	})
+}
+
+func (t *Task) markItemDownloaded(id string) {
+	t.updateItem(id, func(item *itemProgressState) {
+		item.phase = ItemPhaseDownloaded
+	})
+}
+
+func (t *Task) recordItemDownloaded(id string, actualSize int64) {
+	t.updateItem(id, func(item *itemProgressState) {
+		if actualSize > 0 {
+			item.actualSize = actualSize
+		}
+		if item.actualSize == 0 {
+			item.actualSize = item.downloaded
+		}
+		if item.phase != ItemPhaseTransferring {
+			item.phase = ItemPhaseDownloaded
+			item.uploadMeter.reset()
+		}
+	})
+}
+
+func (t *Task) recordItemUpload(id string, uploaded, total int64, now time.Time) bool {
+	becameConfirming := false
+	t.updateItem(id, func(item *itemProgressState) {
+		if uploaded < item.uploaded {
+			if item.phase != ItemPhaseRetrying {
+				return
+			}
+			item.uploadMeter.reset()
+		}
+		if total > 0 {
+			item.actualSize = total
+		}
+		item.uploaded = uploaded
+		item.uploadMeter.record(now, uploaded)
+		if total > 0 && uploaded >= total {
+			becameConfirming = item.phase != ItemPhaseConfirming
+			item.phase = ItemPhaseConfirming
+			return
+		}
+		item.phase = ItemPhaseUploading
+		item.failureStage = FailureStageNone
+		item.err = ""
+	})
+	return becameConfirming
+}
+
+func (t *Task) markItemRetry(id string, stage FailureStage, attempt, limit int, err error) {
+	t.updateItem(id, func(item *itemProgressState) {
+		item.phase = ItemPhaseRetrying
+		item.failureStage = stage
+		item.retryAttempt = attempt
+		item.retryLimit = limit
+		item.err = compactError(err)
+	})
+}
+
+func (t *Task) markItemFailed(id string, stage FailureStage, err error) {
+	t.updateItem(id, func(item *itemProgressState) {
+		if item.phase == ItemPhaseFailed || item.phase == ItemPhaseCompleted {
+			return
+		}
+		if errors.Is(err, context.Canceled) {
+			item.phase = ItemPhaseStopped
+			return
+		}
+		item.phase = ItemPhaseFailed
+		item.failureStage = stage
+		item.err = compactError(err)
+	})
+}
+
+func (t *Task) markItemCompleted(id string) {
+	t.updateItem(id, func(item *itemProgressState) {
+		item.phase = ItemPhaseCompleted
+		item.failureStage = FailureStageNone
+		item.err = ""
+		item.retryAttempt = 0
+		item.retryLimit = 0
+		if item.actualSize == 0 {
+			item.actualSize = max(item.downloaded, item.uploaded)
+		}
+	})
+}
+
+func (t *Task) finishItems(err error) {
+	if err == nil {
+		return
+	}
+	t.itemMu.Lock()
+	defer t.itemMu.Unlock()
+	for i := range t.itemStates {
+		item := &t.itemStates[i]
+		if item.phase == ItemPhaseCompleted || item.phase == ItemPhaseFailed {
+			continue
+		}
+		item.phase = ItemPhaseStopped
+	}
+}
+
+func (t *Task) itemFailureStage(id string) FailureStage {
+	t.itemMu.RLock()
+	defer t.itemMu.RUnlock()
+	index, ok := t.itemIndex[id]
+	if !ok || index < 0 || index >= len(t.itemStates) {
+		return FailureStageUpload
+	}
+	if t.itemStates[index].phase == ItemPhaseConfirming {
+		return FailureStageConfirm
+	}
+	return FailureStageUpload
+}
+
+func (t *Task) Items() []TaskItemProgress {
+	t.itemMu.RLock()
+	defer t.itemMu.RUnlock()
+	items := make([]TaskItemProgress, 0, len(t.itemStates))
+	for i := range t.itemStates {
+		item := &t.itemStates[i]
+		size := item.actualSize
+		if size == 0 {
+			size = item.expectedSize
+		}
+		items = append(items, TaskItemProgress{
+			Index:         item.index,
+			ID:            item.id,
+			Name:          item.name,
+			Size:          size,
+			Downloaded:    item.downloaded,
+			Uploaded:      item.uploaded,
+			DownloadSpeed: item.downloadMeter.speed(),
+			UploadSpeed:   item.uploadMeter.speed(),
+			Phase:         item.phase,
+			FailureStage:  item.failureStage,
+			RetryAttempt:  item.retryAttempt,
+			RetryLimit:    item.retryLimit,
+			Error:         item.err,
+		})
+	}
+	return items
+}
+
+func (t *Task) ActualTotalSize() int64 {
+	items := t.Items()
+	var total int64
+	for _, item := range items {
+		total += item.Size
+	}
+	return total
+}
+
+type stateProgressTracker interface {
+	OnStateChange(ctx context.Context, info TaskInfo)
+}
+
+func (t *Task) notifyStateChange(ctx context.Context) {
+	if tracker, ok := t.Progress.(stateProgressTracker); ok {
+		tracker.OnStateChange(ctx, t)
+	}
+}
+
+func compactError(err error) string {
+	if err == nil {
+		return ""
+	}
+	return strings.Join(strings.Fields(err.Error()), " ")
+}

core/tasks/batchtfile/progress.go

@@ -4,19 +4,19 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"strconv"
-	"sync/atomic"
+	"path"
+	"strings"
+	"sync"
 	"time"
+	"unicode/utf8"
 
 	"github.com/charmbracelet/log"
-	"github.com/duke-git/lancet/v2/slice"
-	"github.com/gotd/td/telegram/message/entity"
-	"github.com/gotd/td/telegram/message/styling"
 	"github.com/gotd/td/tg"
 	"github.com/krau/SaveAny-Bot/common/i18n"
 	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
 	"github.com/krau/SaveAny-Bot/common/utils/dlutil"
 	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
+	"github.com/krau/SaveAny-Bot/config"
 )
 
 type ProgressTracker interface {
@@ -26,155 +26,481 @@ type ProgressTracker interface {
 }
 
 type Progress struct {
-	MessageID         int
-	ChatID            int64
-	start             time.Time
-	lastUpdatePercent atomic.Int32
+	MessageID    int
+	ChatID       int64
+	updateMu     sync.Mutex
+	lastUpdateAt time.Time
+	lastText     string
+	done         bool
+	skippedFiles []string
 }
 
+type renderedBatchMessage struct {
+	Text     string
+	Entities []tg.MessageEntityClass
+	Err      error
+}
+
+const (
+	progressRenderInterval = time.Second
+	maxVisibleActiveItems  = 5
+	progressBarWidth       = 10
+	maxDisplayNameRunes    = 36
+	maxDisplayErrorRunes   = 240
+)
+
 func (p *Progress) OnStart(ctx context.Context, info TaskInfo) {
-	p.start = time.Now()
-	p.lastUpdatePercent.Store(0)
-	log.FromContext(ctx).Debugf("Batch task progress tracking started for message %d in chat %d", p.MessageID, p.ChatID)
-	entityBuilder := entity.Builder{}
-	var entities []tg.MessageEntityClass
-	if err := styling.Perform(&entityBuilder,
-		styling.Plain(i18n.T(i18nk.BotMsgProgressBatchStartPrefix, nil)),
-		styling.Code(fmt.Sprintf("%.2f MB (%d个文件)", float64(info.TotalSize())/(1024*1024), info.Count())),
-	); err != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
-		return
-	}
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
-	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
-	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
-		Rows: []tg.KeyboardButtonRow{
-			{
-				Buttons: []tg.KeyboardButtonClass{
-					tgutil.BuildCancelButton(info.TaskID()),
-				},
-			},
-		}},
-	)
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
-		return
-	}
+	p.render(ctx, info, true)
 }
 
 func (p *Progress) OnProgress(ctx context.Context, info TaskInfo) {
-	if !shouldUpdateProgress(info.TotalSize(), info.Downloaded(), int(p.lastUpdatePercent.Load())) {
+	p.render(ctx, info, false)
+}
+
+func (p *Progress) OnStateChange(ctx context.Context, info TaskInfo) {
+	p.render(ctx, info, true)
+}
+
+func (p *Progress) OnUploadStart(ctx context.Context, info TaskInfo, _ int64) {
+	p.render(ctx, info, true)
+}
+
+func (p *Progress) OnUploadProgress(ctx context.Context, info TaskInfo, _, _ int64) {
+	p.render(ctx, info, false)
+}
+
+func (p *Progress) render(ctx context.Context, info TaskInfo, priority bool) {
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
+	if p.done {
 		return
 	}
-	percent := int((info.Downloaded() * 100) / info.TotalSize())
-	if p.lastUpdatePercent.Load() == int32(percent) {
+	now := time.Now()
+	if !priority && !p.lastUpdateAt.IsZero() && now.Sub(p.lastUpdateAt) < progressRenderInterval {
 		return
 	}
-	p.lastUpdatePercent.Store(int32(percent))
-	log.FromContext(ctx).Debugf("Progress update: %s, %d/%d", info.TaskID(), info.Downloaded(), info.TotalSize())
-	entityBuilder := entity.Builder{}
-	var entities []tg.MessageEntityClass
-	if err := styling.Perform(&entityBuilder,
-		styling.Plain(i18n.T(i18nk.BotMsgProgressBatchProcessingPrefix, nil)),
-		styling.Code(fmt.Sprintf("%.2f MB (%d个文件)", float64(info.TotalSize())/(1024*1024), info.Count())),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressProcessingListPrefix, nil)),
-		func() styling.StyledTextOption {
-			var lines []string
-			for _, elem := range info.Processing() {
-				lines = append(lines, fmt.Sprintf("  - %s (%.2f MB)", elem.FileName(), float64(elem.FileSize())/(1024*1024)))
-			}
-			if len(lines) == 0 {
-				lines = append(lines, i18n.T(i18nk.BotMsgProgressProcessingNone, nil))
-			}
-			return styling.Plain(slice.Join(lines, "\n"))
-		}(),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressAvgSpeedPrefix, nil)),
-		styling.Bold(fmt.Sprintf("%.2f MB/s", dlutil.GetSpeed(info.Downloaded(), p.start)/(1024*1024))),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressCurrentProgressPrefix, nil)),
-		styling.Bold(fmt.Sprintf("%.2f%%", float64(info.Downloaded())/float64(info.TotalSize())*100)),
-	); err != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
+	message := buildBatchProgressMessage(info, p.skippedFiles, visibleActiveItems())
+	if message.Err != nil {
+		log.FromContext(ctx).Errorf("Failed to render batch progress message: %v", message.Err)
 		return
 	}
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
-	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
-	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
-		Rows: []tg.KeyboardButtonRow{
-			{
-				Buttons: []tg.KeyboardButtonClass{
-					tgutil.BuildCancelButton(info.TaskID()),
-				},
-			},
-		}},
-	)
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
+	if message.Text == p.lastText {
 		return
 	}
+	p.lastText = message.Text
+	p.lastUpdateAt = now
+	p.editMessage(ctx, info.TaskID(), message, true)
 }
 
 func (p *Progress) OnDone(ctx context.Context, info TaskInfo, err error) {
-	if err != nil {
-		log.FromContext(ctx).Errorf("Batch task %s failed: %s", info.TaskID(), err)
-	} else {
-		log.FromContext(ctx).Debugf("Batch task %s completed successfully", info.TaskID())
-	}
-	entityBuilder := entity.Builder{}
-	var stylingErr error
-
-	if err != nil {
-		if errors.Is(err, context.Canceled) {
-			stylingErr = styling.Perform(&entityBuilder,
-				styling.Plain(i18n.T(i18nk.BotMsgProgressTaskCanceled, nil)),
-			)
-		} else {
-			stylingErr = styling.Perform(&entityBuilder,
-				styling.Plain(i18n.T(i18nk.BotMsgProgressTaskFailedWithError, map[string]any{
-					"Error": "",
-				})),
-				styling.Code(err.Error()),
-			)
-		}
-	} else {
-		stylingErr = styling.Perform(&entityBuilder,
-			styling.Plain(i18n.T(i18nk.BotMsgProgressBatchDonePrefix, nil)),
-			styling.Code(strconv.Itoa(info.Count())),
-			styling.Plain(i18n.T(i18nk.BotMsgProgressTotalSizePrefix, nil)),
-			styling.Code(fmt.Sprintf("%.2f MB", float64(info.TotalSize())/(1024*1024))),
-		)
-	}
-
-	if stylingErr != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", stylingErr)
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
+	if p.done {
 		return
 	}
-
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
+	p.done = true
+	message := buildBatchDoneMessage(info, p.skippedFiles, err)
+	if message.Err != nil {
+		log.FromContext(ctx).Errorf("Failed to render final batch progress message: %v", message.Err)
+		return
 	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
+	p.lastText = message.Text
+	p.editMessage(ctx, info.TaskID(), message, false)
+}
 
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
+func (p *Progress) editMessage(ctx context.Context, taskID string, message renderedBatchMessage, cancellable bool) {
+	if message.Err != nil {
+		log.FromContext(ctx).Errorf("Failed to render batch progress message: %v", message.Err)
+		return
 	}
+	req := buildBatchEditMessageRequest(p.MessageID, taskID, message, cancellable)
+	if ext := tgutil.ExtFromContext(ctx); ext != nil {
+		if _, err := ext.EditMessage(p.ChatID, req); err != nil {
+			log.FromContext(ctx).Errorf("Failed to edit batch progress message: %v", err)
+		}
+	}
+}
+
+func buildBatchEditMessageRequest(messageID int, taskID string, message renderedBatchMessage, cancellable bool) *tg.MessagesEditMessageRequest {
+	req := &tg.MessagesEditMessageRequest{ID: messageID}
+	req.SetMessage(message.Text)
+	if len(message.Entities) > 0 {
+		req.SetEntities(message.Entities)
+	}
+	if cancellable {
+		req.SetReplyMarkup(&tg.ReplyInlineMarkup{Rows: []tg.KeyboardButtonRow{{
+			Buttons: []tg.KeyboardButtonClass{tgutil.BuildCancelButton(taskID)},
+		}}})
+	}
+	return req
+}
+
+func buildBatchProgressText(info TaskInfo, skipped []string, activeLimit int) string {
+	return buildBatchProgressMessage(info, skipped, activeLimit).Text
+}
+
+func buildBatchProgressMessage(info TaskInfo, skipped []string, activeLimit int) renderedBatchMessage {
+	items := info.Items()
+	completed, waiting, downloaded, failed := itemCounts(items)
+	downloadSpeed, uploadSpeed := aggregateSpeeds(items)
+	if activeLimit < 1 {
+		activeLimit = 1
+	}
+
+	total := len(items) + len(skipped)
+	downloadSpeedText := formatSpeed(downloadSpeed)
+	uploadSpeedText := formatSpeed(uploadSpeed)
+	header := localizedProgressMarkup(i18nk.BotMsgProgressBatchStatusHeader, map[string]any{
+		"Total":         total,
+		"Completed":     completed,
+		"Downloaded":    downloaded,
+		"Waiting":       waiting,
+		"DownloadSpeed": downloadSpeedText,
+		"UploadSpeed":   uploadSpeedText,
+	})
+
+	var markup strings.Builder
+	markup.WriteString(header)
+
+	visibleItems, hiddenTransfers, summarizedConfirming := visibleBatchItems(items, activeLimit)
+	for _, item := range visibleItems {
+		markup.WriteString("\n\n")
+		markup.WriteString(formatActiveItemMarkup(item, len(items)))
+	}
+
+	if hiddenTransfers > 0 {
+		markup.WriteString("\n\n")
+		markup.WriteString(localizedProgressMarkup(i18nk.BotMsgProgressBatchSummaryHiddenActive, map[string]any{"Count": hiddenTransfers}))
+	}
+	if summarizedConfirming > 0 {
+		markup.WriteString("\n\n")
+		markup.WriteString(localizedProgressMarkup(i18nk.BotMsgProgressBatchSummaryConfirming, map[string]any{"Count": summarizedConfirming}))
+	}
+	if failed > 0 {
+		markup.WriteString("\n")
+		markup.WriteString(localizedProgressMarkup(i18nk.BotMsgProgressBatchSummaryFailed, map[string]any{"Count": failed}))
+	}
+	if len(skipped) > 0 {
+		markup.WriteString("\n")
+		markup.WriteString(localizedProgressMarkup(i18nk.BotMsgProgressBatchSummarySkipped, map[string]any{"Count": len(skipped)}))
+	}
+	return completeBatchMessage(markup.String())
+}
+
+func buildBatchDoneMarkup(info TaskInfo, skipped []string, err error) string {
+	items := info.Items()
+	totalSize := info.ActualTotalSize()
+	if totalSize == 0 {
+		totalSize = info.TotalSize()
+	}
+	if err == nil {
+		if len(skipped) > 0 {
+			return localizedProgressMarkup(i18nk.BotMsgProgressBatchDoneWithSkipped, map[string]any{
+				"Success": len(items),
+				"Skipped": len(skipped),
+				"Size":    dlutil.FormatSize(totalSize),
+			})
+		}
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchDone, map[string]any{
+			"Count": len(items),
+			"Size":  dlutil.FormatSize(totalSize),
+		})
+	}
+	completed, _, _, failed := itemCounts(items)
+	incomplete := max(len(items)-completed-failed, 0)
+	if errors.Is(err, context.Canceled) {
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchCanceled, map[string]any{
+			"Total":      len(items) + len(skipped),
+			"Completed":  completed,
+			"Incomplete": incomplete,
+			"Skipped":    len(skipped),
+		})
+	}
+
+	failedItems := make([]TaskItemProgress, 0, failed)
+	for _, item := range items {
+		if item.Phase == ItemPhaseFailed {
+			failedItems = append(failedItems, item)
+		}
+	}
+	if len(failedItems) > 1 && failedItems[0].FailureStage == FailureStageBatchUpload {
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchFailedGroup, map[string]any{
+			"Affected":   len(failedItems),
+			"Reason":     displayError(firstError(failedItems), err),
+			"Completed":  completed,
+			"Failed":     len(failedItems),
+			"Incomplete": incomplete,
+		})
+	}
+	if len(failedItems) == 0 {
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchFailedTask, map[string]any{
+			"Reason":     displayError("", err),
+			"Completed":  completed,
+			"Incomplete": incomplete,
+		})
+	}
+	item := failedItems[0]
+	return localizedProgressMarkup(i18nk.BotMsgProgressBatchFailedItem, map[string]any{
+		"Index":      item.Index,
+		"Name":       truncateFilename(item.Name, maxDisplayNameRunes),
+		"Stage":      failureStageLabel(item.FailureStage),
+		"Progress":   failureProgress(item),
+		"Speed":      failureSpeed(item),
+		"Reason":     displayError(item.Error, err),
+		"Completed":  completed,
+		"Failed":     failed,
+		"Incomplete": incomplete,
+	})
+}
+
+func buildBatchDoneMessage(info TaskInfo, skipped []string, err error) renderedBatchMessage {
+	return completeBatchMessage(buildBatchDoneMarkup(info, skipped, err))
+}
+
+func formatActiveItemMarkup(item TaskItemProgress, total int) string {
+	data := map[string]any{
+		"Index":    item.Index,
+		"Total":    total,
+		"Name":     truncateFilename(item.Name, maxDisplayNameRunes),
+		"Speed":    formatSpeed(itemSpeed(item)),
+		"Progress": itemPercent(item),
+		"Bar":      textProgressBar(itemPercent(item)),
+		"Current":  dlutil.FormatSize(itemBytes(item)),
+		"Size":     dlutil.FormatSize(item.Size),
+		"Attempt":  min(max(item.RetryAttempt, 1), max(item.RetryLimit, 1)),
+		"Limit":    max(item.RetryLimit, 1),
+		"Reason":   truncateRunes(item.Error, maxDisplayErrorRunes),
+	}
+	switch item.Phase {
+	case ItemPhaseDownloading:
+		if item.Size <= 0 {
+			return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemDownloadingUnknown, data)
+		}
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemDownloading, data)
+	case ItemPhaseTransferring:
+		if item.Size <= 0 {
+			return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemTransferringUnknown, data)
+		}
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemTransferring, data)
+	case ItemPhaseUploading:
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemUploading, data)
+	case ItemPhaseRetrying:
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemRetrying, data)
+	case ItemPhaseConfirming:
+		return localizedProgressMarkup(i18nk.BotMsgProgressBatchItemConfirming, data)
+	default:
+		return ""
+	}
+}
+
+func localizedProgressMarkup(key i18nk.Key, data map[string]any) string {
+	return i18n.T(key, tgutil.EscapeHTMLTemplateData(data))
+}
+
+func visibleBatchItems(items []TaskItemProgress, limit int) (visible []TaskItemProgress, hiddenTransfers, summarizedConfirming int) {
+	visible = make([]TaskItemProgress, 0, limit)
+	transferCount := 0
+	confirmingCount := 0
+	for _, item := range items {
+		switch {
+		case isTransferPhase(item.Phase):
+			transferCount++
+			if len(visible) < limit {
+				visible = append(visible, item)
+			}
+		case item.Phase == ItemPhaseConfirming:
+			confirmingCount++
+		}
+	}
+	hiddenTransfers = transferCount - len(visible)
+	if confirmingCount == 1 && len(visible) < limit {
+		for _, item := range items {
+			if item.Phase == ItemPhaseConfirming {
+				visible = append(visible, item)
+				return visible, hiddenTransfers, 0
+			}
+		}
+	}
+	return visible, hiddenTransfers, confirmingCount
+}
+
+func completeBatchMessage(markup string) renderedBatchMessage {
+	text, entities, err := tgutil.RenderHTML(markup)
+	return renderedBatchMessage{Text: text, Entities: entities, Err: err}
+}
+
+func itemCounts(items []TaskItemProgress) (completed, waiting, downloaded, failed int) {
+	for _, item := range items {
+		switch item.Phase {
+		case ItemPhaseCompleted:
+			completed++
+		case ItemPhaseWaiting:
+			waiting++
+		case ItemPhaseDownloaded:
+			downloaded++
+		case ItemPhaseFailed:
+			failed++
+		}
+	}
+	return
+}
+
+func aggregateSpeeds(items []TaskItemProgress) (download, upload float64) {
+	for _, item := range items {
+		switch item.Phase {
+		case ItemPhaseDownloading:
+			download += item.DownloadSpeed
+		case ItemPhaseTransferring:
+			download += item.DownloadSpeed
+			upload += item.UploadSpeed
+		case ItemPhaseUploading:
+			upload += item.UploadSpeed
+		}
+	}
+	return
+}
+
+func isTransferPhase(phase ItemPhase) bool {
+	switch phase {
+	case ItemPhaseDownloading, ItemPhaseTransferring, ItemPhaseUploading, ItemPhaseRetrying:
+		return true
+	default:
+		return false
+	}
+}
+
+func itemBytes(item TaskItemProgress) int64 {
+	switch item.Phase {
+	case ItemPhaseDownloading, ItemPhaseTransferring:
+		return item.Downloaded
+	default:
+		return item.Uploaded
+	}
+}
+
+func itemSpeed(item TaskItemProgress) float64 {
+	switch item.Phase {
+	case ItemPhaseDownloading, ItemPhaseTransferring:
+		return item.DownloadSpeed
+	case ItemPhaseUploading:
+		return item.UploadSpeed
+	case ItemPhaseRetrying:
+		return item.UploadSpeed
+	default:
+		return 0
+	}
+}
+
+func itemPercent(item TaskItemProgress) int {
+	if item.Size <= 0 {
+		return 0
+	}
+	return int(min(itemBytes(item), item.Size) * 100 / item.Size)
+}
+
+func textProgressBar(percent int) string {
+	percent = min(max(percent, 0), 100)
+	filled := percent * progressBarWidth / 100
+	return strings.Repeat("🟩", filled) + strings.Repeat("⬜️", progressBarWidth-filled)
+}
+
+func formatSpeed(speed float64) string {
+	if speed <= 0 {
+		return "0 B/s"
+	}
+	return dlutil.FormatSize(int64(speed)) + "/s"
+}
+
+func truncateFilename(name string, limit int) string {
+	if utf8.RuneCountInString(name) <= limit {
+		return name
+	}
+	ext := path.Ext(name)
+	if utf8.RuneCountInString(ext) >= limit-2 {
+		return truncateRunes(name, limit-1) + "…"
+	}
+	base := strings.TrimSuffix(name, ext)
+	baseLimit := limit - utf8.RuneCountInString(ext) - 1
+	return truncateRunes(base, baseLimit) + "…" + ext
+}
+
+func truncateRunes(value string, limit int) string {
+	if limit <= 0 {
+		return ""
+	}
+	runes := []rune(value)
+	if len(runes) <= limit {
+		return value
+	}
+	return string(runes[:limit])
+}
+
+func displayError(itemError string, fallback error) string {
+	if itemError == "" && fallback != nil {
+		itemError = compactError(fallback)
+	}
+	return truncateRunes(itemError, maxDisplayErrorRunes)
+}
+
+func firstError(items []TaskItemProgress) string {
+	for _, item := range items {
+		if item.Error != "" {
+			return item.Error
+		}
+	}
+	return ""
+}
+
+func failureStageLabel(stage FailureStage) string {
+	switch stage {
+	case FailureStageDownload:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageDownload, nil)
+	case FailureStageCache:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageCache, nil)
+	case FailureStageUpload:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageUpload, nil)
+	case FailureStageConfirm:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageConfirm, nil)
+	case FailureStageBatchUpload:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageBatchUpload, nil)
+	default:
+		return i18n.T(i18nk.BotMsgProgressBatchFailureStageInternal, nil)
+	}
+}
+
+func failureProgress(item TaskItemProgress) string {
+	if item.Size <= 0 {
+		return dlutil.FormatSize(failureBytes(item))
+	}
+	return fmt.Sprintf("%d%%", min(failureBytes(item), item.Size)*100/item.Size)
+}
+
+func failureSpeed(item TaskItemProgress) string {
+	if item.FailureStage == FailureStageDownload || item.FailureStage == FailureStageCache {
+		return formatSpeed(item.DownloadSpeed)
+	}
+	return formatSpeed(item.UploadSpeed)
+}
+
+func failureBytes(item TaskItemProgress) int64 {
+	if item.FailureStage == FailureStageDownload || item.FailureStage == FailureStageCache {
+		return item.Downloaded
+	}
+	return item.Uploaded
+}
+
+func visibleActiveItems() int {
+	return min(max(config.C().Workers, 1), maxVisibleActiveItems)
 }
 
 func NewProgressTracker(messageID int, chatID int64) ProgressTracker {
+	return NewProgressTrackerWithSkipped(messageID, chatID, nil)
+}
+
+func NewProgressTrackerWithSkipped(messageID int, chatID int64, skippedFiles []string) ProgressTracker {
 	return &Progress{
-		MessageID: messageID,
-		ChatID:    chatID,
+		MessageID:    messageID,
+		ChatID:       chatID,
+		skippedFiles: skippedFiles,
 	}
 }

core/tasks/batchtfile/progress_regression_test.go

@@ -0,0 +1,311 @@
+package batchtfile
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/common/i18n"
+	"github.com/krau/SaveAny-Bot/pkg/tfile"
+)
+
+type progressRegressionRecorder struct {
+	mu            sync.Mutex
+	startTotal    int64
+	notifications []int64
+}
+
+func (*progressRegressionRecorder) OnStart(context.Context, TaskInfo)       {}
+func (*progressRegressionRecorder) OnProgress(context.Context, TaskInfo)    {}
+func (*progressRegressionRecorder) OnDone(context.Context, TaskInfo, error) {}
+
+func (r *progressRegressionRecorder) OnUploadStart(_ context.Context, _ TaskInfo, total int64) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.startTotal = total
+}
+
+func (r *progressRegressionRecorder) OnUploadProgress(_ context.Context, _ TaskInfo, uploaded, _ int64) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.notifications = append(r.notifications, uploaded)
+}
+
+type orderedProgressRegressionRecorder struct {
+	firstEntered  chan struct{}
+	releaseFirst  chan struct{}
+	secondEntered chan struct{}
+	mu            sync.Mutex
+	notifications []int64
+}
+
+func (*orderedProgressRegressionRecorder) OnStart(context.Context, TaskInfo)       {}
+func (*orderedProgressRegressionRecorder) OnProgress(context.Context, TaskInfo)    {}
+func (*orderedProgressRegressionRecorder) OnDone(context.Context, TaskInfo, error) {}
+func (*orderedProgressRegressionRecorder) OnUploadStart(context.Context, TaskInfo, int64) {
+}
+
+func (r *orderedProgressRegressionRecorder) OnUploadProgress(_ context.Context, _ TaskInfo, uploaded, _ int64) {
+	if uploaded == 100 {
+		close(r.firstEntered)
+		<-r.releaseFirst
+	}
+	if uploaded == 200 {
+		close(r.secondEntered)
+	}
+	r.mu.Lock()
+	r.notifications = append(r.notifications, uploaded)
+	r.mu.Unlock()
+}
+
+func TestBatchProgressShowsTransferSpeedAndSize(t *testing.T) {
+	useProgressRegressionLocale(t)
+	task := newProgressRegressionTask(nil,
+		progressRegressionFile{"downloading", 1000},
+		progressRegressionFile{"uploading", 1000},
+		progressRegressionFile{"waiting", 1000},
+	)
+	started := time.Unix(100, 0)
+	task.markItemActive("downloading", false, started)
+	task.recordItemDownload("downloading", 500, started.Add(time.Second))
+	task.recordItemDownloaded("uploading", 1000)
+	task.recordItemUpload("uploading", 0, 1000, started.Add(time.Second))
+	task.recordItemUpload("uploading", 250, 1000, started.Add(2*time.Second))
+
+	message := buildBatchProgressMessage(task, nil, 2)
+	if message.Err != nil {
+		t.Fatalf("buildBatchProgressMessage() failed: %v", message.Err)
+	}
+	assertProgressRegressionContains(t, message.Text,
+		"状态：✅ 0 ｜ 📥 0 ｜ ⏳ 1",
+		"⬇️ 1/3 下载中",
+		"速度：500 B/s",
+		"大小：500 B / 1000 B",
+		"⬆️ 2/3 上传中",
+		"速度：250 B/s",
+		"大小：250 B / 1000 B",
+	)
+	bold, _, blockquote, _ := batchEntityCounts(message.Entities)
+	if bold != 3 || blockquote != 2 {
+		t.Fatalf("entity counts = bold:%d blockquote:%d, want bold:3 blockquote:2", bold, blockquote)
+	}
+}
+
+func TestBatchProgressLimitsRowsWithoutHidingActiveUpload(t *testing.T) {
+	useProgressRegressionLocale(t)
+	task := newProgressRegressionTask(nil,
+		progressRegressionFile{"confirm-01", 100},
+		progressRegressionFile{"confirm-02", 100},
+		progressRegressionFile{"uploading", 100},
+		progressRegressionFile{"downloading", 100},
+	)
+	started := time.Unix(100, 0)
+	task.recordItemUpload("confirm-01", 100, 100, started)
+	task.recordItemUpload("confirm-02", 100, 100, started)
+	task.recordItemUpload("uploading", 40, 100, started.Add(time.Second))
+	task.markItemActive("downloading", false, started)
+
+	message := buildBatchProgressText(task, nil, 2)
+	assertProgressRegressionContains(t, message,
+		"uploading.bin",
+		"downloading.bin",
+		"☁️ 已上传，等待整组发送：2",
+	)
+	if strings.Contains(message, "confirm-01.bin") || strings.Contains(message, "confirm-02.bin") {
+		t.Fatalf("confirmation rows displaced active transfers:\n%s", message)
+	}
+}
+
+func TestBatchProgressTemplateOwnsStylesAndEscapesValues(t *testing.T) {
+	useProgressRegressionLocale(t)
+	fileID := `<b>A&B</b>`
+	task := newProgressRegressionTask(nil, progressRegressionFile{fileID, 100})
+	task.markItemRetry(fileID, FailureStageUpload, 1, 3, errors.New(`<i>remote & failed</i>`))
+
+	message := buildBatchProgressMessage(task, nil, 1)
+	if message.Err != nil {
+		t.Fatalf("buildBatchProgressMessage() failed: %v", message.Err)
+	}
+	assertProgressRegressionContains(t, message.Text,
+		`<b>A&B</b>.bin`,
+		`<i>remote & failed</i>`,
+	)
+	bold, _, blockquote, italic := batchEntityCounts(message.Entities)
+	if bold != 2 || blockquote != 1 || italic != 0 {
+		t.Fatalf("entity counts = bold:%d blockquote:%d italic:%d", bold, blockquote, italic)
+	}
+
+	i18n.Init("en")
+	english := buildBatchProgressMessage(task, nil, 1)
+	if english.Err != nil {
+		t.Fatalf("English batch template failed: %v", english.Err)
+	}
+	assertProgressRegressionContains(t, english.Text, "📦 Processing", "Retrying upload", `<b>A&B</b>.bin`)
+}
+
+func TestDownloadProgressContinuesAfterUploadStarts(t *testing.T) {
+	useProgressRegressionLocale(t)
+	progress := new(Progress)
+	task := newProgressRegressionTask(progress,
+		progressRegressionFile{"uploading", 100},
+		progressRegressionFile{"downloading", 100},
+	)
+	progress.OnStart(t.Context(), task)
+	task.recordDownloadComplete("uploading", 100)
+	task.uploadCallback(t.Context(), "uploading")(50, 100)
+
+	started := time.Unix(100, 0)
+	task.markItemActive("downloading", false, started)
+	task.recordItemDownload("downloading", 50, started.Add(time.Second))
+	progress.updateMu.Lock()
+	progress.lastUpdateAt = time.Now().Add(-progressRenderInterval)
+	progress.updateMu.Unlock()
+	progress.OnProgress(t.Context(), task)
+
+	progress.updateMu.Lock()
+	text := progress.lastText
+	progress.updateMu.Unlock()
+	assertProgressRegressionContains(t, text,
+		"uploading.bin",
+		"🟩🟩🟩🟩🟩⬜️⬜️⬜️⬜️⬜️ 50%",
+		"总速度：⬇️ 50 B/s ｜ ⬆️ 0 B/s",
+		"🔄 另有 1 个文件正在处理",
+	)
+}
+
+func TestBatchUploadIgnoresOutOfOrderBytesAndAllowsRetryReset(t *testing.T) {
+	recorder := new(progressRegressionRecorder)
+	task := newProgressRegressionTask(recorder, progressRegressionFile{"file", 100})
+	task.recordDownloadComplete("file", 100)
+	callback := task.uploadCallback(t.Context(), "file")
+	callback(80, 100)
+	callback(10, 100)
+
+	if got := task.Items()[0].Uploaded; got != 80 {
+		t.Fatalf("out-of-order callback regressed item to %d, want 80", got)
+	}
+	task.markItemRetry("file", FailureStageUpload, 1, 3, context.DeadlineExceeded)
+	callback(0, 100)
+	callback(10, 100)
+	if got := task.Items()[0].Uploaded; got != 10 {
+		t.Fatalf("retry did not reset item progress: got %d, want 10", got)
+	}
+
+	recorder.mu.Lock()
+	defer recorder.mu.Unlock()
+	for index := 1; index < len(recorder.notifications); index++ {
+		if recorder.notifications[index] < recorder.notifications[index-1] {
+			t.Fatalf("aggregate progress regressed: %v", recorder.notifications)
+		}
+	}
+}
+
+func TestUploadProgressNotificationsRemainOrdered(t *testing.T) {
+	recorder := &orderedProgressRegressionRecorder{
+		firstEntered:  make(chan struct{}),
+		releaseFirst:  make(chan struct{}),
+		secondEntered: make(chan struct{}),
+	}
+	task := newProgressRegressionTask(recorder,
+		progressRegressionFile{"first", 100},
+		progressRegressionFile{"second", 100},
+	)
+	task.recordDownloadComplete("first", 100)
+	task.recordDownloadComplete("second", 100)
+	first := task.uploadCallback(t.Context(), "first")
+	second := task.uploadCallback(t.Context(), "second")
+
+	var wait sync.WaitGroup
+	wait.Go(func() {
+		first(100, 100)
+	})
+	<-recorder.firstEntered
+	wait.Go(func() {
+		second(100, 100)
+	})
+
+	overtook := false
+	select {
+	case <-recorder.secondEntered:
+		overtook = true
+	case <-time.After(100 * time.Millisecond):
+	}
+	close(recorder.releaseFirst)
+	wait.Wait()
+	if overtook {
+		t.Fatal("later aggregate notification overtook the first callback")
+	}
+
+	recorder.mu.Lock()
+	defer recorder.mu.Unlock()
+	if got := recorder.notifications; len(got) != 2 || got[0] != 100 || got[1] != 200 {
+		t.Fatalf("upload notifications = %v, want [100 200]", got)
+	}
+}
+
+func TestBatchUploadUsesActualSizeWhenMetadataIsUnknown(t *testing.T) {
+	recorder := new(progressRegressionRecorder)
+	task := newProgressRegressionTask(recorder, progressRegressionFile{"photo", 0})
+	task.recordDownloadComplete("photo", 25)
+	task.uploadCallback(t.Context(), "photo")(25, 25)
+
+	recorder.mu.Lock()
+	defer recorder.mu.Unlock()
+	if recorder.startTotal != 25 {
+		t.Fatalf("upload start total = %d, want actual size 25", recorder.startTotal)
+	}
+	if got := task.ActualTotalSize(); got != 25 {
+		t.Fatalf("actual total size = %d, want 25", got)
+	}
+}
+
+type progressRegressionFile struct {
+	id   string
+	size int64
+}
+
+func newProgressRegressionTask(progress ProgressTracker, files ...progressRegressionFile) *Task {
+	elems := make([]TaskElement, 0, len(files))
+	for _, file := range files {
+		elems = append(elems, TaskElement{
+			ID:   file.id,
+			File: tfile.NewTGFile(nil, nil, file.size, file.id+".bin"),
+		})
+	}
+	return NewBatchTGFileTask("progress-regression", context.Background(), elems, progress, true)
+}
+
+func useProgressRegressionLocale(t *testing.T) {
+	t.Helper()
+	i18n.Init("zh-Hans")
+	t.Cleanup(func() { i18n.Init("zh-Hans") })
+}
+
+func assertProgressRegressionContains(t *testing.T, value string, wants ...string) {
+	t.Helper()
+	for _, want := range wants {
+		if !strings.Contains(value, want) {
+			t.Fatalf("text does not contain %q:\n%s", want, value)
+		}
+	}
+}
+
+func batchEntityCounts(entities []tg.MessageEntityClass) (bold, code, blockquote, italic int) {
+	for _, messageEntity := range entities {
+		switch messageEntity.(type) {
+		case *tg.MessageEntityBold:
+			bold++
+		case *tg.MessageEntityCode:
+			code++
+		case *tg.MessageEntityBlockquote:
+			blockquote++
+		case *tg.MessageEntityItalic:
+			italic++
+		}
+	}
+	return
+}

core/tasks/batchtfile/task.go

@@ -7,6 +7,7 @@ import (
 	"sync"
 	"sync/atomic"
 
+	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/core"
 	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
@@ -18,25 +19,35 @@ import (
 var _ core.Executable = (*Task)(nil)
 
 type TaskElement struct {
-	ID        string
-	Storage   storage.Storage
-	Path      string
-	File      tfile.TGFile
-	localPath string
-	stream    bool
+	ID              string
+	Storage         storage.Storage
+	Path            string
+	File            tfile.TGFile
+	localPath       string
+	stream          bool
+	sourceGroupKey  string
+	sourceCaption   string
+	preserveCaption bool
 }
 
 type Task struct {
-	ID           string
-	ctx          context.Context
-	elems        []TaskElement
-	Progress     ProgressTracker
-	IgnoreErrors bool // if true, errors during processing will be ignored
-	downloaded   atomic.Int64
-	totalSize    int64
-	processing   map[string]TaskElementInfo
-	processingMu sync.RWMutex
-	failed       map[string]error // [TODO] errors for each element
+	ID              string
+	ctx             context.Context
+	elems           []TaskElement
+	Progress        ProgressTracker
+	IgnoreErrors    bool // if true, errors during processing will be ignored
+	downloaded      atomic.Int64
+	totalSize       int64
+	uploadTotalSize atomic.Int64
+	processing      map[string]TaskElementInfo
+	processingMu    sync.RWMutex
+	itemStates      []itemProgressState
+	itemIndex       map[string]int
+	itemMu          sync.RWMutex
+	uploadOnce      sync.Once
+	uploadMu        sync.Mutex
+	uploaded        map[string]int64
+	failed          map[string]error // [TODO] errors for each element
 }
 
 // Title implements core.Exectable.
@@ -54,6 +65,7 @@ func NewTaskElement(
 	file tfile.TGFile,
 ) (*TaskElement, error) {
 	id := xid.New().String()
+	groupKey, caption, preserveCaption := sourceMetadata(file)
 	_, ok := stor.(storage.StorageCannotStream)
 	if !config.C().Stream || ok {
 		cachePath, err := filepath.Abs(filepath.Join(config.C().Temp.BasePath, fmt.Sprintf("%s_%s", id, file.Name())))
@@ -61,22 +73,42 @@ func NewTaskElement(
 			return nil, fmt.Errorf("failed to get absolute path for cache: %w", err)
 		}
 		return &TaskElement{
-			ID:        id,
-			Storage:   stor,
-			Path:      path,
-			File:      file,
-			localPath: cachePath,
+			ID:              id,
+			Storage:         stor,
+			Path:            path,
+			File:            file,
+			localPath:       cachePath,
+			sourceGroupKey:  groupKey,
+			sourceCaption:   caption,
+			preserveCaption: preserveCaption,
 		}, nil
 	}
 	return &TaskElement{
-		ID:      id,
-		Storage: stor,
-		Path:    path,
-		File:    file,
-		stream:  true,
+		ID:              id,
+		Storage:         stor,
+		Path:            path,
+		File:            file,
+		stream:          true,
+		sourceGroupKey:  groupKey,
+		sourceCaption:   caption,
+		preserveCaption: preserveCaption,
 	}, nil
 }
 
+func sourceMetadata(file tfile.TGFile) (groupKey, caption string, preserveCaption bool) {
+	messageFile, ok := file.(tfile.TGFileMessage)
+	if !ok || messageFile.Message() == nil {
+		return "", "", false
+	}
+	msg := messageFile.Message()
+	groupID, grouped := msg.GetGroupedID()
+	if !grouped || groupID == 0 {
+		return "", "", false
+	}
+	chatID := tgutil.ChatIdFromPeer(msg.GetPeerID())
+	return fmt.Sprintf("%T:%d:%d", msg.GetPeerID(), chatID, groupID), msg.GetMessage(), true
+}
+
 func NewBatchTGFileTask(
 	id string,
 	ctx context.Context,
@@ -84,6 +116,7 @@ func NewBatchTGFileTask(
 	progress ProgressTracker,
 	ignoreErrors bool,
 ) *Task {
+	itemStates, itemIndex := newItemProgressStates(files)
 	task := &Task{
 		ID:         id,
 		ctx:        ctx,
@@ -98,6 +131,9 @@ func NewBatchTGFileTask(
 			return total
 		}(),
 		processing:   make(map[string]TaskElementInfo),
+		itemStates:   itemStates,
+		itemIndex:    itemIndex,
+		uploaded:     make(map[string]int64),
 		IgnoreErrors: ignoreErrors,
 		processingMu: sync.RWMutex{},
 		failed:       make(map[string]error),

core/tasks/batchtfile/taskinfo.go

@@ -27,8 +27,10 @@ type TaskInfo interface {
 	TaskID() string
 	TotalSize() int64
 	Downloaded() int64
+	ActualTotalSize() int64
 	Count() int
 	Processing() []TaskElementInfo
+	Items() []TaskItemProgress
 }
 
 func (t *Task) TaskID() string {

core/tasks/batchtfile/upload_progress.go

@@ -0,0 +1,70 @@
+package batchtfile
+
+import (
+	"context"
+	"time"
+)
+
+// UploadProgressTracker optionally extends a batch progress tracker with a
+// distinct aggregate upload phase.
+type UploadProgressTracker interface {
+	OnUploadStart(ctx context.Context, info TaskInfo, total int64)
+	OnUploadProgress(ctx context.Context, info TaskInfo, uploaded, total int64)
+}
+
+func (t *Task) startUpload(ctx context.Context) {
+	tracker, ok := t.Progress.(UploadProgressTracker)
+	if !ok {
+		return
+	}
+	t.uploadMu.Lock()
+	defer t.uploadMu.Unlock()
+	t.uploadOnce.Do(func() {
+		tracker.OnUploadStart(ctx, t, t.uploadTotalSize.Load())
+	})
+}
+
+func (t *Task) uploadCallback(ctx context.Context, id string) func(uploaded, total int64) {
+	return func(uploaded, total int64) {
+		tracker, ok := t.Progress.(UploadProgressTracker)
+		if !ok || uploaded < 0 {
+			return
+		}
+		t.startUpload(ctx)
+		if total > 0 && uploaded > total {
+			uploaded = total
+		}
+
+		t.uploadMu.Lock()
+		defer t.uploadMu.Unlock()
+		becameConfirming := t.recordItemUpload(id, uploaded, total, time.Now())
+		if t.uploaded == nil {
+			t.uploaded = make(map[string]int64)
+		}
+		previous, tracked := t.uploaded[id]
+		if !tracked || uploaded > previous {
+			t.uploaded[id] = uploaded
+		}
+		var aggregate int64
+		for _, current := range t.uploaded {
+			aggregate += current
+		}
+		uploadTotal := t.uploadTotalSize.Load()
+		if aggregate > uploadTotal {
+			aggregate = uploadTotal
+		}
+		tracker.OnUploadProgress(ctx, t, aggregate, uploadTotal)
+		if becameConfirming {
+			t.notifyStateChange(ctx)
+		}
+	}
+}
+
+func (t *Task) recordDownloadComplete(id string, uploadSize int64) {
+	t.uploadMu.Lock()
+	defer t.uploadMu.Unlock()
+	if uploadSize > 0 {
+		t.uploadTotalSize.Add(uploadSize)
+	}
+	t.recordItemDownloaded(id, uploadSize)
+}

core/tasks/directlinks/execute.go

@@ -15,6 +15,7 @@ import (
 	"github.com/krau/SaveAny-Bot/common/utils/ioutil"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -45,9 +46,17 @@ func (t *Task) Execute(ctx context.Context) error {
 			fetchedTotalBytes.Add(resp.ContentLength)
 			file.Size = resp.ContentLength
 			if name := resp.Header.Get("Content-Disposition"); name != "" {
-				// Set file name
 				filename := parseFilename(name)
-				file.Name = filename
+				if filename != "" {
+					file.Name = filename
+				}
+			}
+			// extract filename from URL if Content-Disposition is empty or invalid
+			if file.Name == "" {
+				file.Name = parseFilenameFromURL(file.URL)
+			}
+			if file.Name == "" {
+				return fmt.Errorf("failed to determine filename for %s: Content-Disposition header is empty and URL does not contain a valid filename", file.URL)
 			}
 
 			return nil
@@ -135,10 +144,16 @@ func (t *Task) processLink(ctx context.Context, file *File) error {
 			}
 		}()
 		wr := ioutil.NewProgressWriter(cacheFile, func(n int) {
-			t.downloadedBytes.Add(int64(n))
+			downloaded := t.downloadedBytes.Add(int64(n))
 			if t.Progress != nil {
 				t.Progress.OnProgress(ctx, t)
 			}
+			taskevent.Emit(ctx, taskevent.Event{
+				TaskID:          t.ID,
+				Phase:           taskevent.PhaseProgress,
+				TotalBytes:      t.totalBytes,
+				DownloadedBytes: downloaded,
+			})
 		})
 
 		copyResultCh := make(chan error, 1)

core/tasks/directlinks/task.go

@@ -76,6 +76,9 @@ func (t *Task) StorageName() string {
 
 // StoragePath implements TaskInfo.
 func (t *Task) StoragePath() string {
+	if len(t.files) == 1 {
+		return t.StorPath + "/" + t.files[0].Name
+	}
 	return t.StorPath
 }
 

core/tasks/directlinks/util.go

@@ -144,6 +144,41 @@ func tryDecodeGBK(s string) string {
 	return ""
 }
 
+// parseFilenameFromURL extracts filename from URL path
+// This is used as a fallback when Content-Disposition is not available
+func parseFilenameFromURL(rawURL string) string {
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return ""
+	}
+
+	// Get the path part and extract the last segment
+	path := parsed.Path
+	if path == "" {
+		return ""
+	}
+
+	// URL decode the path first
+	decodedPath, err := url.PathUnescape(path)
+	if err != nil {
+		decodedPath = path
+	}
+
+	// Get the last segment of the path
+	lastSlash := strings.LastIndex(decodedPath, "/")
+	if lastSlash == -1 {
+		return decodedPath
+	}
+	filename := decodedPath[lastSlash+1:]
+
+	// Remove query string if somehow still present
+	if idx := strings.Index(filename, "?"); idx != -1 {
+		filename = filename[:idx]
+	}
+
+	return filename
+}
+
 // parseFilenameFallback manually parses filename= when mime.ParseMediaType fails
 func parseFilenameFallback(cd string) string {
 	// Look for filename= (case-insensitive)

core/tasks/directlinks/util_test.go

@@ -0,0 +1,73 @@
+package directlinks
+
+import (
+	"testing"
+)
+
+func TestParseFilenameFromURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		url      string
+		expected string
+	}{
+		{
+			name:     "simple filename",
+			url:      "https://example.com/files/document.pdf",
+			expected: "document.pdf",
+		},
+		{
+			name:     "filename with encoded characters",
+			url:      "https://example.com/files/%E6%B5%8B%E8%AF%95.zip",
+			expected: "测试.zip",
+		},
+		{
+			name:     "filename with query string in URL",
+			url:      "https://example.com/files/image.png?token=abc123",
+			expected: "image.png",
+		},
+		{
+			name:     "nested path",
+			url:      "https://example.com/a/b/c/file.txt",
+			expected: "file.txt",
+		},
+		{
+			name:     "URL with port",
+			url:      "https://example.com:8080/downloads/archive.tar.gz",
+			expected: "archive.tar.gz",
+		},
+		{
+			name:     "empty path",
+			url:      "https://example.com",
+			expected: "",
+		},
+		{
+			name:     "root path only",
+			url:      "https://example.com/",
+			expected: "",
+		},
+		{
+			name:     "filename with spaces encoded",
+			url:      "https://example.com/my%20file%20name.pdf",
+			expected: "my file name.pdf",
+		},
+		{
+			name:     "complex encoded filename",
+			url:      "https://example.com/downloads/%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6.docx",
+			expected: "中文文件.docx",
+		},
+		{
+			name:     "invalid URL",
+			url:      "://invalid-url",
+			expected: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := parseFilenameFromURL(tt.url)
+			if result != tt.expected {
+				t.Errorf("parseFilenameFromURL(%q) = %q, want %q", tt.url, result, tt.expected)
+			}
+		})
+	}
+}

core/tasks/parsed/execute.go

@@ -16,6 +16,7 @@ import (
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
 	"github.com/krau/SaveAny-Bot/pkg/parser"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -107,10 +108,16 @@ func (t *Task) processResource(ctx context.Context, resource parser.Resource) er
 			}
 		}()
 		wr := ioutil.NewProgressWriter(cacheFile, func(n int) {
-			t.downloadedBytes.Add(int64(n))
+			downloaded := t.downloadedBytes.Add(int64(n))
 			if t.progress != nil {
 				t.progress.OnProgress(ctx, t)
 			}
+			taskevent.Emit(ctx, taskevent.Event{
+				TaskID:          t.ID,
+				Phase:           taskevent.PhaseProgress,
+				TotalBytes:      t.totalBytes,
+				DownloadedBytes: downloaded,
+			})
 		})
 
 		copyResultCh := make(chan error, 1)

core/tasks/telegraph/execute.go

@@ -11,6 +11,7 @@ import (
 	"github.com/duke-git/lancet/v2/retry"
 	"github.com/krau/SaveAny-Bot/common/utils/fsutil"
 	"github.com/krau/SaveAny-Bot/config"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -27,8 +28,14 @@ func (t *Task) Execute(ctx context.Context) error {
 				logger.Errorf("Error processing picture %s: %v", pic, err)
 				return fmt.Errorf("failed to process picture %s: %w", pic, err)
 			}
-			t.downloaded.Add(1)
+			downloaded := t.downloaded.Add(1)
 			t.progress.OnProgress(gctx, t)
+			taskevent.Emit(gctx, taskevent.Event{
+				TaskID:          t.ID,
+				Phase:           taskevent.PhaseProgress,
+				TotalFiles:      t.totalpics,
+				DownloadedFiles: int(downloaded),
+			})
 			return nil
 		})
 	}

core/tasks/tfile/caption_test.go

@@ -0,0 +1,42 @@
+package tfile
+
+import (
+	"testing"
+
+	"github.com/gotd/td/tg"
+	tfilepkg "github.com/krau/SaveAny-Bot/pkg/tfile"
+)
+
+func TestSourceCaption(t *testing.T) {
+	tests := []struct {
+		name string
+		file tfilepkg.TGFile
+		want string
+		ok   bool
+	}{
+		{
+			name: "original caption",
+			file: tfilepkg.NewTGFile(nil, nil, 0, "video.mov", tfilepkg.WithMessage(&tg.Message{Message: "original caption"})),
+			want: "original caption",
+			ok:   true,
+		},
+		{
+			name: "empty caption suppresses storage fallback",
+			file: tfilepkg.NewTGFile(nil, nil, 0, "video.mov", tfilepkg.WithMessage(&tg.Message{})),
+			ok:   true,
+		},
+		{
+			name: "file without source message",
+			file: tfilepkg.NewTGFile(nil, nil, 0, "video.mov"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := sourceCaption(tt.file)
+			if ok != tt.ok || got != tt.want {
+				t.Fatalf("sourceCaption() = (%q, %v), want (%q, %v)", got, ok, tt.want, tt.ok)
+			}
+		})
+	}
+}

core/tasks/tfile/execute.go

@@ -3,6 +3,7 @@ package tfile
 import (
 	"context"
 	"fmt"
+	"io"
 	"os"
 	"path"
 
@@ -10,8 +11,12 @@ import (
 	"github.com/duke-git/lancet/v2/retry"
 	"github.com/krau/SaveAny-Bot/common/tdler"
 	"github.com/krau/SaveAny-Bot/common/utils/fsutil"
+	"github.com/krau/SaveAny-Bot/common/utils/ioutil"
 	"github.com/krau/SaveAny-Bot/config"
 	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/pkg/storagetypes"
+	tfilepkg "github.com/krau/SaveAny-Bot/pkg/tfile"
+	"github.com/krau/SaveAny-Bot/storage"
 )
 
 func (t *Task) Execute(ctx context.Context) error {
@@ -57,13 +62,34 @@ func (t *Task) Execute(ctx context.Context) error {
 		return fmt.Errorf("failed to get file stat: %w", err)
 	}
 	vctx := context.WithValue(ctx, ctxkey.ContentLength, fileStat.Size())
+	if caption, ok := sourceCaption(t.File); ok {
+		vctx = storagetypes.WithSourceCaption(vctx, caption)
+	}
 	err = retry.Retry(func() error {
 		file, err := os.Open(t.localPath)
 		if err != nil {
 			return fmt.Errorf("failed to open cache file: %w", err)
 		}
 		defer file.Close()
-		if err = t.Storage.Save(vctx, file, t.Path); err != nil {
+		uploadProgress, tracksUpload := t.Progress.(UploadProgressTracker)
+		if !tracksUpload {
+			if err = t.Storage.Save(vctx, file, t.Path); err != nil {
+				return fmt.Errorf("failed to save file: %w", err)
+			}
+			return nil
+		}
+
+		uploadProgress.OnUploadStart(vctx, t, fileStat.Size())
+		onProgress := func(uploaded, total int64) {
+			uploadProgress.OnUploadProgress(vctx, t, uploaded, total)
+		}
+		if progressSaver, ok := t.Storage.(storage.StorageProgressSaver); ok {
+			err = progressSaver.SaveWithProgress(vctx, file, t.Path, onProgress)
+		} else {
+			var reader io.Reader = ioutil.NewProgressReader(file, fileStat.Size(), onProgress)
+			err = t.Storage.Save(vctx, reader, t.Path)
+		}
+		if err != nil {
 			return fmt.Errorf("failed to save file: %w", err)
 		}
 		return nil
@@ -73,3 +99,11 @@ func (t *Task) Execute(ctx context.Context) error {
 	}
 	return nil
 }
+
+func sourceCaption(file tfilepkg.TGFile) (string, bool) {
+	messageFile, ok := file.(tfilepkg.TGFileMessage)
+	if !ok || messageFile.Message() == nil {
+		return "", false
+	}
+	return messageFile.Message().GetMessage(), true
+}

core/tasks/tfile/progress.go

@@ -4,12 +4,12 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
+	"sync"
 	"sync/atomic"
 	"time"
 
 	"github.com/charmbracelet/log"
-	"github.com/gotd/td/telegram/message/entity"
-	"github.com/gotd/td/telegram/message/styling"
 	"github.com/gotd/td/tg"
 	"github.com/krau/SaveAny-Bot/common/i18n"
 	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
@@ -23,153 +23,319 @@ type ProgressTracker interface {
 	OnDone(ctx context.Context, info TaskInfo, err error)
 }
 
+// UploadProgressTracker optionally extends a task progress tracker with a
+// distinct upload phase. Keeping it separate preserves compatibility with
+// custom download-only trackers.
+type UploadProgressTracker interface {
+	OnUploadStart(ctx context.Context, info TaskInfo, total int64)
+	OnUploadProgress(ctx context.Context, info TaskInfo, uploaded, total int64)
+}
+
 type Progress struct {
 	MessageID         int
 	ChatID            int64
 	start             time.Time
 	lastUpdatePercent atomic.Int32
+	lastUpdateAt      atomic.Int64
+	updateMu          sync.Mutex
+	uploadAttempt     int
+	uploadedBytes     int64
+	actualSize        int64
+	hasActualSize     bool
+}
+
+const (
+	uploadProgressMinInterval = time.Second
+	uploadProgressMaxInterval = 3 * time.Second
+	singleProgressBarWidth    = 10
+	maxSingleErrorRunes       = 240
+)
+
+type singleProgressPhase int
+
+const (
+	singlePhaseDownloading singleProgressPhase = iota
+	singlePhaseUploading
+	singlePhaseRetrying
+)
+
+type renderedSingleMessage struct {
+	Text     string
+	Entities []tg.MessageEntityClass
+	Err      error
 }
 
 func (p *Progress) OnStart(ctx context.Context, info TaskInfo) {
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
 	p.start = time.Now()
 	p.lastUpdatePercent.Store(0)
+	p.lastUpdateAt.Store(0)
+	p.uploadAttempt = 0
+	p.uploadedBytes = 0
+	p.actualSize = 0
+	p.hasActualSize = false
 	log.FromContext(ctx).Debugf("Progress tracking started for message %d in chat %d", p.MessageID, p.ChatID)
-	entityBuilder := entity.Builder{}
-	var entities []tg.MessageEntityClass
-	if err := styling.Perform(&entityBuilder,
-		styling.Plain(i18n.T(i18nk.BotMsgProgressFileStartPrefix, nil)),
-		styling.Code(info.FileName()),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressSavePathPrefix, nil)),
-		styling.Code(fmt.Sprintf("[%s]:%s", info.StorageName(), info.StoragePath())),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressFileSizePrefix, nil)),
-		styling.Code(fmt.Sprintf("%.2f MB", float64(info.FileSize())/(1024*1024))),
-	); err != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
-		return
-	}
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
-	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
-	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
-		Rows: []tg.KeyboardButtonRow{
-			{
-				Buttons: []tg.KeyboardButtonClass{
-					tgutil.BuildCancelButton(info.TaskID()),
-				},
-			},
-		}},
-	)
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
-		return
-	}
+	p.editMessage(ctx, info.TaskID(), buildSingleProgressMessage(info, singlePhaseDownloading, 0, info.FileSize(), 0, 0), true)
 }
 
 func (p *Progress) OnProgress(ctx context.Context, info TaskInfo, downloaded, total int64) {
-	if !shouldUpdateProgress(total, downloaded, int(p.lastUpdatePercent.Load())) {
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
+	now := time.Now()
+	elapsed := uploadProgressMaxInterval
+	if lastUpdateAt := p.lastUpdateAt.Load(); lastUpdateAt > 0 {
+		elapsed = now.Sub(time.Unix(0, lastUpdateAt))
+	}
+	if !shouldUpdateSingleDownloadProgress(total, downloaded, int(p.lastUpdatePercent.Load()), elapsed) {
 		return
 	}
-	percent := int32((downloaded * 100) / total)
-	if p.lastUpdatePercent.Load() == percent {
-		return
+	if total > 0 {
+		percent := int32((downloaded * 100) / total)
+		if p.lastUpdatePercent.Load() == percent {
+			return
+		}
+		p.lastUpdatePercent.Store(percent)
 	}
-	p.lastUpdatePercent.Store(percent)
+	p.lastUpdateAt.Store(now.UnixNano())
 	log.FromContext(ctx).Debugf("Progress update: %s, %d/%d", info.FileName(), downloaded, total)
-	entityBuilder := entity.Builder{}
-	var entities []tg.MessageEntityClass
-	if err := styling.Perform(&entityBuilder,
-		styling.Plain(i18n.T(i18nk.BotMsgProgressFileProcessingPrefix, nil)),
-		styling.Code(info.FileName()),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressSavePathPrefix, nil)),
-		styling.Code(fmt.Sprintf("[%s]:%s", info.StorageName(), info.StoragePath())),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressFileSizePrefix, nil)),
-		styling.Code(fmt.Sprintf("%.2f MB", float64(total)/(1024*1024))),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressAvgSpeedPrefix, nil)),
-		styling.Bold(fmt.Sprintf("%.2f MB/s", dlutil.GetSpeed(downloaded, p.start)/(1024*1024))),
-		styling.Plain(i18n.T(i18nk.BotMsgProgressCurrentProgressPrefix, nil)),
-		styling.Bold(fmt.Sprintf("%.2f%%", float64(downloaded)/float64(total)*100)),
-	); err != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
+	p.editMessage(ctx, info.TaskID(), buildSingleProgressMessage(
+		info,
+		singlePhaseDownloading,
+		downloaded,
+		total,
+		dlutil.GetSpeed(downloaded, p.start),
+		0,
+	), true)
+}
+
+func shouldUpdateSingleDownloadProgress(total, downloaded int64, lastPercent int, elapsed time.Duration) bool {
+	if total > 0 {
+		return shouldUpdateProgress(total, downloaded, lastPercent)
+	}
+	return downloaded > 0 && elapsed >= uploadProgressMaxInterval
+}
+
+func (p *Progress) OnUploadStart(ctx context.Context, info TaskInfo, total int64) {
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
+	p.start = time.Now()
+	p.lastUpdatePercent.Store(0)
+	p.lastUpdateAt.Store(p.start.UnixNano())
+	p.uploadAttempt++
+	p.uploadedBytes = 0
+	p.actualSize = max(total, 0)
+	p.hasActualSize = true
+	log.FromContext(ctx).Debugf("Upload progress tracking started: %s", info.FileName())
+	phase := singleUploadPhase(p.uploadAttempt)
+	p.editMessage(ctx, info.TaskID(), buildSingleProgressMessage(info, phase, 0, total, 0, p.uploadAttempt), true)
+}
+
+func (p *Progress) OnUploadProgress(ctx context.Context, info TaskInfo, uploaded, total int64) {
+	if total <= 0 || uploaded <= 0 {
 		return
 	}
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
+	if uploaded > total {
+		uploaded = total
 	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
-	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
-		Rows: []tg.KeyboardButtonRow{
-			{
-				Buttons: []tg.KeyboardButtonClass{
-					tgutil.BuildCancelButton(info.TaskID()),
-				},
-			},
-		}},
-	)
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
+	if uploaded < p.uploadedBytes {
+		return
+	}
+	p.uploadedBytes = uploaded
+
+	now := time.Now()
+	lastUpdateAt := time.Unix(0, p.lastUpdateAt.Load())
+	lastPercent := int(p.lastUpdatePercent.Load())
+	if !shouldUpdateUploadProgress(total, uploaded, lastPercent, now.Sub(lastUpdateAt)) {
 		return
 	}
 
+	percent := int32((uploaded * 100) / total)
+	p.lastUpdatePercent.Store(percent)
+	p.lastUpdateAt.Store(now.UnixNano())
+	log.FromContext(ctx).Debugf("Upload progress update: %s, %d/%d", info.FileName(), uploaded, total)
+	p.editMessage(ctx, info.TaskID(), buildSingleProgressMessage(
+		info,
+		singleUploadPhase(p.uploadAttempt),
+		uploaded,
+		total,
+		dlutil.GetSpeed(uploaded, p.start),
+		p.uploadAttempt,
+	), true)
+}
+
+func shouldUpdateUploadProgress(total, uploaded int64, lastPercent int, elapsed time.Duration) bool {
+	if total <= 0 || uploaded <= 0 {
+		return false
+	}
+	if uploaded >= total {
+		return lastPercent < 100 && elapsed >= uploadProgressMinInterval
+	}
+	percent := int((uploaded * 100) / total)
+	if percent < lastPercent {
+		return false
+	}
+	if elapsed < uploadProgressMinInterval {
+		return false
+	}
+	if percent == lastPercent {
+		return elapsed >= uploadProgressMaxInterval
+	}
+	return shouldUpdateProgress(total, uploaded, lastPercent) || elapsed >= uploadProgressMaxInterval
+}
+
+func singleUploadPhase(attempt int) singleProgressPhase {
+	if attempt > 1 {
+		return singlePhaseRetrying
+	}
+	return singlePhaseUploading
 }
 
 func (p *Progress) OnDone(ctx context.Context, info TaskInfo, err error) {
+	p.updateMu.Lock()
+	defer p.updateMu.Unlock()
 	if err != nil {
 		log.FromContext(ctx).Errorf("Progress error for file [%s]: %v", info.FileName(), err)
 	} else {
 		log.FromContext(ctx).Debugf("Progress done for file [%s]", info.FileName())
 	}
 
-	entityBuilder := entity.Builder{}
-	var stylingErr error
+	p.editMessage(ctx, info.TaskID(), buildSingleDoneMessage(info, p.doneSize(info), err), false)
+}
 
-	if err != nil {
-		if errors.Is(err, context.Canceled) {
-			stylingErr = styling.Perform(&entityBuilder,
-				styling.Plain(i18n.T(i18nk.BotMsgProgressTaskCanceled, nil)),
-				styling.Plain("\n"),
-				styling.Plain(i18n.T(i18nk.BotMsgProgressFileNamePrefix, nil)),
-				styling.Code(info.FileName()),
-			)
-		} else {
-			stylingErr = styling.Perform(&entityBuilder,
-				styling.Plain(i18n.T(i18nk.BotMsgProgressDownloadFailedPrefix, nil)),
-				styling.Code(info.FileName()),
-				styling.Plain(i18n.T(i18nk.BotMsgProgressErrorPrefix, nil)),
-				styling.Bold(err.Error()),
-			)
-		}
-	} else {
-		stylingErr = styling.Perform(&entityBuilder,
-			styling.Plain(i18n.T(i18nk.BotMsgProgressDownloadDonePrefix, nil)),
-			styling.Code(info.FileName()),
-			styling.Plain(i18n.T(i18nk.BotMsgProgressSavePathPrefix, nil)),
-			styling.Code(fmt.Sprintf("[%s]:%s", info.StorageName(), info.StoragePath())),
-		)
+func (p *Progress) doneSize(info TaskInfo) int64 {
+	if p.hasActualSize {
+		return p.actualSize
 	}
+	return max(info.FileSize(), 0)
+}
 
-	if stylingErr != nil {
-		log.FromContext(ctx).Errorf("Failed to build entities: %s", stylingErr)
+func (p *Progress) editMessage(ctx context.Context, taskID string, message renderedSingleMessage, cancellable bool) {
+	if message.Err != nil {
+		log.FromContext(ctx).Errorf("Failed to render file progress message: %v", message.Err)
 		return
 	}
-
-	text, entities := entityBuilder.Complete()
-	req := &tg.MessagesEditMessageRequest{
-		ID: p.MessageID,
+	req := buildSingleEditMessageRequest(p.MessageID, taskID, message, cancellable)
+	if ext := tgutil.ExtFromContext(ctx); ext != nil {
+		if _, err := ext.EditMessage(p.ChatID, req); err != nil {
+			log.FromContext(ctx).Errorf("Failed to edit file progress message: %v", err)
+		}
 	}
-	req.SetMessage(text)
-	req.SetEntities(entities)
+}
 
-	ext := tgutil.ExtFromContext(ctx)
-	if ext != nil {
-		ext.EditMessage(p.ChatID, req)
+func buildSingleEditMessageRequest(messageID int, taskID string, message renderedSingleMessage, cancellable bool) *tg.MessagesEditMessageRequest {
+	req := &tg.MessagesEditMessageRequest{ID: messageID}
+	req.SetMessage(message.Text)
+	if len(message.Entities) > 0 {
+		req.SetEntities(message.Entities)
 	}
+	if cancellable {
+		req.SetReplyMarkup(&tg.ReplyInlineMarkup{Rows: []tg.KeyboardButtonRow{{
+			Buttons: []tg.KeyboardButtonClass{tgutil.BuildCancelButton(taskID)},
+		}}})
+	}
+	return req
+}
+
+func buildSingleProgressMessage(
+	info TaskInfo,
+	phase singleProgressPhase,
+	current int64,
+	total int64,
+	speed float64,
+	attempt int,
+) renderedSingleMessage {
+	if current < 0 {
+		current = 0
+	}
+	if total > 0 && current > total {
+		current = total
+	}
+	percent := singleProgressPercent(current, total)
+	destination := fmt.Sprintf("[%s]:%s", info.StorageName(), info.StoragePath())
+	data := map[string]any{
+		"Name":        info.FileName(),
+		"Bar":         singleProgressBar(percent),
+		"Progress":    percent,
+		"Speed":       singleProgressSpeed(speed),
+		"Current":     dlutil.FormatSize(current),
+		"Size":        dlutil.FormatSize(total),
+		"Destination": destination,
+		"Attempt":     max(attempt, 1),
+	}
+
+	var key i18nk.Key
+	switch phase {
+	case singlePhaseUploading:
+		key = i18nk.BotMsgProgressSingleUploading
+	case singlePhaseRetrying:
+		key = i18nk.BotMsgProgressSingleUploadRetrying
+	default:
+		key = i18nk.BotMsgProgressSingleDownloading
+		if total <= 0 {
+			key = i18nk.BotMsgProgressSingleDownloadingUnknown
+		}
+	}
+	markup := i18n.T(i18nk.BotMsgProgressSingleStatusHeader, nil) + "\n\n" + localizedProgressMarkup(key, data)
+	return completeSingleMessage(markup)
+}
+
+func buildSingleDoneMessage(info TaskInfo, size int64, err error) renderedSingleMessage {
+	data := map[string]any{
+		"Name":        info.FileName(),
+		"Size":        dlutil.FormatSize(max(size, 0)),
+		"Destination": fmt.Sprintf("[%s]:%s", info.StorageName(), info.StoragePath()),
+	}
+	var key i18nk.Key
+	switch {
+	case err == nil:
+		key = i18nk.BotMsgProgressSingleDone
+	case errors.Is(err, context.Canceled):
+		key = i18nk.BotMsgProgressSingleCanceled
+	default:
+		data["Reason"] = truncateSingleError(err.Error())
+		key = i18nk.BotMsgProgressSingleFailed
+	}
+	return completeSingleMessage(localizedProgressMarkup(key, data))
+}
+
+func localizedProgressMarkup(key i18nk.Key, data map[string]any) string {
+	return i18n.T(key, tgutil.EscapeHTMLTemplateData(data))
+}
+
+func completeSingleMessage(markup string) renderedSingleMessage {
+	text, entities, err := tgutil.RenderHTML(markup)
+	return renderedSingleMessage{Text: text, Entities: entities, Err: err}
+}
+
+func singleProgressPercent(current, total int64) int {
+	if total <= 0 {
+		return 0
+	}
+	return int(min(max(current, 0), total) * 100 / total)
+}
+
+func singleProgressBar(percent int) string {
+	percent = min(max(percent, 0), 100)
+	filled := percent * singleProgressBarWidth / 100
+	return strings.Repeat("🟩", filled) + strings.Repeat("⬜️", singleProgressBarWidth-filled)
+}
+
+func singleProgressSpeed(speed float64) string {
+	if speed <= 0 {
+		return "0 B/s"
+	}
+	return dlutil.FormatSize(int64(speed)) + "/s"
+}
+
+func truncateSingleError(value string) string {
+	runes := []rune(value)
+	if len(runes) <= maxSingleErrorRunes {
+		return value
+	}
+	return string(runes[:maxSingleErrorRunes])
 }
 
 type ProgressOption func(*Progress)

core/tasks/tfile/progress_test.go

@@ -0,0 +1,178 @@
+package tfile
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/common/i18n"
+)
+
+type progressTestTaskInfo struct{}
+
+func (progressTestTaskInfo) TaskID() string      { return "task" }
+func (progressTestTaskInfo) FileName() string    { return "file.bin" }
+func (progressTestTaskInfo) FileSize() int64     { return 100 << 20 }
+func (progressTestTaskInfo) StoragePath() string { return "file.bin" }
+func (progressTestTaskInfo) StorageName() string { return "test" }
+
+func TestShouldUpdateUploadProgress(t *testing.T) {
+	tests := []struct {
+		name        string
+		total       int64
+		uploaded    int64
+		lastPercent int
+		elapsed     time.Duration
+		want        bool
+	}{
+		{name: "invalid total", total: 0, uploaded: 1, want: false},
+		{name: "no uploaded bytes", total: 100, uploaded: 0, want: false},
+		{name: "percentage threshold", total: 100 << 20, uploaded: 10 << 20, elapsed: uploadProgressMinInterval, want: true},
+		{name: "percentage threshold rate limited", total: 100 << 20, uploaded: 10 << 20, elapsed: uploadProgressMinInterval - time.Millisecond, want: false},
+		{name: "maximum time threshold", total: 100 << 20, uploaded: 1 << 20, elapsed: uploadProgressMaxInterval, want: true},
+		{name: "below thresholds", total: 100 << 20, uploaded: 1 << 20, elapsed: uploadProgressMaxInterval - time.Millisecond, want: false},
+		{name: "completion", total: 100, uploaded: 100, lastPercent: 99, elapsed: uploadProgressMinInterval, want: true},
+		{name: "completion rate limited", total: 100, uploaded: 100, lastPercent: 99, elapsed: uploadProgressMinInterval - time.Millisecond, want: false},
+		{name: "completion already reported", total: 100, uploaded: 100, lastPercent: 100, elapsed: uploadProgressMinInterval, want: false},
+		{name: "out of order callback", total: 100, uploaded: 40, lastPercent: 60, elapsed: uploadProgressMaxInterval, want: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := shouldUpdateUploadProgress(tt.total, tt.uploaded, tt.lastPercent, tt.elapsed)
+			if got != tt.want {
+				t.Fatalf("shouldUpdateUploadProgress() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUploadProgressConcurrentCallbacks(t *testing.T) {
+	progress := new(Progress)
+	ctx := context.Background()
+	info := progressTestTaskInfo{}
+	const total = int64(100 << 20)
+
+	progress.OnUploadStart(ctx, info, total)
+	progress.lastUpdateAt.Store(time.Now().Add(-uploadProgressMaxInterval).UnixNano())
+
+	var wg sync.WaitGroup
+	for uploaded := int64(1 << 20); uploaded <= total; uploaded += 1 << 20 {
+		uploaded := uploaded
+		wg.Go(func() {
+			progress.OnUploadProgress(ctx, info, uploaded, total)
+		})
+	}
+	wg.Wait()
+
+	percent := progress.lastUpdatePercent.Load()
+	if percent <= 0 || percent > 100 {
+		t.Fatalf("last upload percentage = %d, want a value in (0, 100]", percent)
+	}
+	if progress.uploadedBytes != total {
+		t.Fatalf("maximum uploaded bytes = %d, want %d", progress.uploadedBytes, total)
+	}
+}
+
+func TestSingleUploadRetryKeepsRichProgressLayout(t *testing.T) {
+	i18n.Init("zh-Hans")
+	t.Cleanup(func() { i18n.Init("zh-Hans") })
+
+	message := buildSingleProgressMessage(
+		progressTestTaskInfo{},
+		singleUploadPhase(2),
+		25<<20,
+		100<<20,
+		5<<20,
+		2,
+	)
+	if message.Err != nil {
+		t.Fatalf("buildSingleProgressMessage() failed: %v", message.Err)
+	}
+	for _, want := range []string{
+		"🔁 上传重试",
+		"🟩🟩⬜️⬜️⬜️⬜️⬜️⬜️⬜️⬜️ 25%",
+		"尝试次数：2",
+		"速度：5.00 MB/s",
+		"大小：25.00 MB / 100.00 MB",
+	} {
+		if !strings.Contains(message.Text, want) {
+			t.Fatalf("retry progress does not contain %q:\n%s", want, message.Text)
+		}
+	}
+}
+
+func TestSingleProgressTemplateOwnsStylesAndEscapesValues(t *testing.T) {
+	i18n.Init("en")
+	t.Cleanup(func() { i18n.Init("zh-Hans") })
+	info := htmlProgressTestTaskInfo{}
+
+	message := buildSingleProgressMessage(info, singlePhaseDownloading, 50, 100, 25, 0)
+	if message.Err != nil {
+		t.Fatalf("buildSingleProgressMessage() failed: %v", message.Err)
+	}
+	for _, want := range []string{
+		`<b>A&B</b>.bin`,
+		`[store<&>]:dir/<i>x</i>&`,
+		"Speed: 25 B/s",
+	} {
+		if !strings.Contains(message.Text, want) {
+			t.Fatalf("progress text does not contain %q:\n%s", want, message.Text)
+		}
+	}
+	bold, code, blockquote, italic := singleEntityCounts(message.Entities)
+	if bold != 2 || code != 6 || blockquote != 1 || italic != 0 {
+		t.Fatalf("progress entity counts = bold:%d code:%d blockquote:%d italic:%d", bold, code, blockquote, italic)
+	}
+
+	failure := buildSingleDoneMessage(info, 100, errors.New(`<i>remote & failed</i>`))
+	if failure.Err != nil {
+		t.Fatalf("buildSingleDoneMessage() failed: %v", failure.Err)
+	}
+	if !strings.Contains(failure.Text, `<i>remote & failed</i>`) {
+		t.Fatalf("failure reason was not preserved literally:\n%s", failure.Text)
+	}
+	bold, code, blockquote, italic = singleEntityCounts(failure.Entities)
+	if bold != 1 || code != 2 || blockquote != 0 || italic != 0 {
+		t.Fatalf("failure entity counts = bold:%d code:%d blockquote:%d italic:%d", bold, code, blockquote, italic)
+	}
+}
+
+func TestSingleDoneSizeUsesActualUploadSize(t *testing.T) {
+	progress := new(Progress)
+	info := progressTestTaskInfo{}
+	progress.OnStart(context.Background(), info)
+	progress.OnUploadStart(context.Background(), info, 2048)
+
+	if got := progress.doneSize(info); got != 2048 {
+		t.Fatalf("done size = %d, want actual upload size 2048", got)
+	}
+}
+
+type htmlProgressTestTaskInfo struct{}
+
+func (htmlProgressTestTaskInfo) TaskID() string      { return "html-task" }
+func (htmlProgressTestTaskInfo) FileName() string    { return `<b>A&B</b>.bin` }
+func (htmlProgressTestTaskInfo) FileSize() int64     { return 100 }
+func (htmlProgressTestTaskInfo) StoragePath() string { return `dir/<i>x</i>&` }
+func (htmlProgressTestTaskInfo) StorageName() string { return `store<&>` }
+
+func singleEntityCounts(entities []tg.MessageEntityClass) (bold, code, blockquote, italic int) {
+	for _, messageEntity := range entities {
+		switch messageEntity.(type) {
+		case *tg.MessageEntityBold:
+			bold++
+		case *tg.MessageEntityCode:
+			code++
+		case *tg.MessageEntityBlockquote:
+			blockquote++
+		case *tg.MessageEntityItalic:
+			italic++
+		}
+	}
+	return
+}

core/tasks/tfile/writer.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"io"
 	"sync/atomic"
+
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
 )
 
 type ProgressWriterAt struct {
@@ -20,9 +22,16 @@ func (w *ProgressWriterAt) WriteAt(p []byte, off int64) (int, error) {
 	if err != nil {
 		return 0, err
 	}
+	downloaded := w.downloaded.Add(int64(at))
 	if w.progress != nil {
-		w.progress.OnProgress(w.ctx, w.info, w.downloaded.Add(int64(at)), w.total)
+		w.progress.OnProgress(w.ctx, w.info, downloaded, w.total)
 	}
+	taskevent.Emit(w.ctx, taskevent.Event{
+		TaskID:          w.info.TaskID(),
+		Phase:           taskevent.PhaseProgress,
+		TotalBytes:      w.total,
+		DownloadedBytes: downloaded,
+	})
 	return at, nil
 }
 
@@ -56,9 +65,16 @@ func (w *ProgressWriter) Write(p []byte) (int, error) {
 	if err != nil {
 		return 0, err
 	}
+	downloaded := w.downloaded.Add(int64(at))
 	if w.progress != nil {
-		w.progress.OnProgress(w.ctx, w.info, w.downloaded.Add(int64(at)), w.total)
+		w.progress.OnProgress(w.ctx, w.info, downloaded, w.total)
 	}
+	taskevent.Emit(w.ctx, taskevent.Event{
+		TaskID:          w.info.TaskID(),
+		Phase:           taskevent.PhaseProgress,
+		TotalBytes:      w.total,
+		DownloadedBytes: downloaded,
+	})
 	return at, nil
 }
 

core/tasks/transfer/execute.go

@@ -0,0 +1,149 @@
+package transfer
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path"
+	"path/filepath"
+
+	"github.com/charmbracelet/log"
+	"github.com/krau/SaveAny-Bot/config"
+	"github.com/krau/SaveAny-Bot/pkg/enums/ctxkey"
+	"github.com/krau/SaveAny-Bot/pkg/taskevent"
+	"github.com/krau/SaveAny-Bot/storage"
+	"golang.org/x/sync/errgroup"
+)
+
+// Execute implements core.Executable.
+func (t *Task) Execute(ctx context.Context) error {
+	logger := log.FromContext(ctx).WithPrefix(fmt.Sprintf("transfer[%s]", t.ID))
+	logger.Info("Starting transfer task")
+	t.Progress.OnStart(ctx, t)
+
+	workers := config.C().Workers
+	eg, gctx := errgroup.WithContext(ctx)
+	eg.SetLimit(workers)
+
+	for _, elem := range t.elems {
+		eg.Go(func() error {
+			t.processingMu.RLock()
+			if t.processing[elem.ID] != nil {
+				t.processingMu.RUnlock()
+				return fmt.Errorf("element with ID %s is already being processed", elem.ID)
+			}
+			t.processingMu.RUnlock()
+
+			t.processingMu.Lock()
+			t.processing[elem.ID] = &elem
+			t.processingMu.Unlock()
+
+			defer func() {
+				t.processingMu.Lock()
+				delete(t.processing, elem.ID)
+				t.processingMu.Unlock()
+			}()
+
+			err := t.processElement(gctx, elem)
+			if err != nil && !t.IgnoreErrors {
+				return err
+			}
+			if err != nil {
+				t.processingMu.Lock()
+				t.failed[elem.ID] = err
+				t.processingMu.Unlock()
+				logger.Errorf("Failed to process file %s: %v", elem.FileInfo.Name, err)
+			}
+			return nil
+		})
+	}
+
+	err := eg.Wait()
+	if err != nil {
+		logger.Errorf("Error during transfer processing: %v", err)
+	} else {
+		logger.Info("Transfer task completed successfully")
+	}
+
+	t.Progress.OnDone(ctx, t, err)
+	return err
+}
+
+func (t *Task) processElement(ctx context.Context, elem TaskElement) error {
+	logger := log.FromContext(ctx).WithPrefix(fmt.Sprintf("file[%s]", elem.FileInfo.Name))
+
+	// Check whether the source storage supports reading
+	readableStorage, ok := elem.SourceStorage.(storage.StorageReadable)
+	if !ok {
+		return fmt.Errorf("source storage %s does not support reading", elem.SourceStorage.Name())
+	}
+
+	logger.Info("Opening file from source storage")
+	reader, size, err := readableStorage.OpenFile(ctx, elem.SourcePath)
+	if err != nil {
+		return fmt.Errorf("failed to open file: %w", err)
+	}
+	defer reader.Close()
+
+	// Build target storage path: /target_path/filename
+	storagePath := path.Join(elem.TargetPath, elem.FileInfo.Name)
+
+	// Inject file size into context
+	ctx = context.WithValue(ctx, ctxkey.ContentLength, size)
+
+	if config.C().Stream {
+		if err := elem.TargetStorage.Save(ctx, reader, storagePath); err != nil {
+			return fmt.Errorf("failed to upload file to storage: %w", err)
+		}
+	} else {
+		logger.Info("Downloading to temporary file for ReadSeeker support")
+		tempFile, err := t.downloadToTemp(reader, elem.FileInfo.Name)
+		if err != nil {
+			return fmt.Errorf("failed to download to temp: %w", err)
+		}
+		defer os.Remove(tempFile.Name())
+		defer tempFile.Close()
+
+		if _, err := tempFile.Seek(0, io.SeekStart); err != nil {
+			return fmt.Errorf("failed to seek temp file: %w", err)
+		}
+
+		logger.Infof("Uploading file to storage (size: %d bytes)", size)
+		if err := elem.TargetStorage.Save(ctx, tempFile, storagePath); err != nil {
+			return fmt.Errorf("failed to upload file to storage: %w", err)
+		}
+	}
+
+	t.uploaded.Add(size)
+	t.Progress.OnProgress(ctx, t)
+	taskevent.Emit(ctx, taskevent.Event{
+		TaskID:          t.ID,
+		Phase:           taskevent.PhaseProgress,
+		TotalBytes:      t.totalSize,
+		DownloadedBytes: t.uploaded.Load(),
+	})
+
+	logger.Info("File uploaded successfully")
+	return nil
+}
+
+func (t *Task) downloadToTemp(reader io.Reader, filename string) (*os.File, error) {
+	tempDir := config.C().Temp.BasePath
+	if tempDir == "" {
+		tempDir = os.TempDir()
+	}
+
+	tempFile, err := os.CreateTemp(tempDir, filepath.Base(filename)+"-*.tmp")
+	if err != nil {
+		return nil, fmt.Errorf("failed to create temp file: %w", err)
+	}
+
+	if _, err := io.Copy(tempFile, reader); err != nil {
+		tempFile.Close()
+		os.Remove(tempFile.Name())
+		return nil, fmt.Errorf("failed to copy to temp file: %w", err)
+	}
+
+	return tempFile, nil
+}

core/tasks/transfer/progress.go

@@ -0,0 +1,247 @@
+package transfer
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"github.com/charmbracelet/log"
+	"github.com/gotd/td/telegram/message/entity"
+	"github.com/gotd/td/telegram/message/styling"
+	"github.com/gotd/td/tg"
+	"github.com/krau/SaveAny-Bot/common/i18n"
+	"github.com/krau/SaveAny-Bot/common/i18n/i18nk"
+	"github.com/krau/SaveAny-Bot/common/utils/dlutil"
+	"github.com/krau/SaveAny-Bot/common/utils/tgutil"
+)
+
+type ProgressTracker interface {
+	OnStart(ctx context.Context, info TaskInfo)
+	OnProgress(ctx context.Context, info TaskInfo)
+	OnDone(ctx context.Context, info TaskInfo, err error)
+}
+
+type Progress struct {
+	MessageID         int
+	ChatID            int64
+	start             time.Time
+	lastUpdatePercent atomic.Int32
+}
+
+func NewProgressTracker(messageID int, chatID int64) ProgressTracker {
+	return &Progress{
+		MessageID: messageID,
+		ChatID:    chatID,
+	}
+}
+
+func (p *Progress) OnStart(ctx context.Context, info TaskInfo) {
+	p.start = time.Now()
+	p.lastUpdatePercent.Store(0)
+	log.FromContext(ctx).Debugf("Transfer task progress tracking started for message %d in chat %d", p.MessageID, p.ChatID)
+
+	sizeMB := float64(info.TotalSize()) / (1024 * 1024)
+	statsText := i18n.T(i18nk.BotMsgTransferStartStats, map[string]any{
+		"SizeMB": fmt.Sprintf("%.2f", sizeMB),
+		"Count":  info.Count(),
+	})
+
+	entityBuilder := entity.Builder{}
+	if err := styling.Perform(&entityBuilder,
+		styling.Plain(i18n.T(i18nk.BotMsgProgressTransferStartPrefix, nil)),
+		styling.Code(statsText),
+	); err != nil {
+		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
+		return
+	}
+
+	text, entities := entityBuilder.Complete()
+	req := &tg.MessagesEditMessageRequest{
+		ID: p.MessageID,
+	}
+	req.SetMessage(text)
+	req.SetEntities(entities)
+	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
+		Rows: []tg.KeyboardButtonRow{
+			{
+				Buttons: []tg.KeyboardButtonClass{
+					tgutil.BuildCancelButton(info.TaskID()),
+				},
+			},
+		},
+	})
+
+	ext := tgutil.ExtFromContext(ctx)
+	if ext != nil {
+		_, err := ext.EditMessage(p.ChatID, req)
+		if err != nil {
+			log.FromContext(ctx).Errorf("Failed to send progress start message: %s", err)
+		}
+	}
+}
+
+func (p *Progress) OnProgress(ctx context.Context, info TaskInfo) {
+	if !shouldUpdateProgress(info.TotalSize(), info.Uploaded(), int(p.lastUpdatePercent.Load())) {
+		return
+	}
+	percent := int((info.Uploaded() * 100) / info.TotalSize())
+	if p.lastUpdatePercent.Load() == int32(percent) {
+		return
+	}
+	p.lastUpdatePercent.Store(int32(percent))
+
+	log.FromContext(ctx).Debugf("Progress update: %s, %d/%d", info.TaskID(), info.Uploaded(), info.TotalSize())
+
+	entityBuilder := entity.Builder{}
+	var progressText strings.Builder
+
+	progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferProgressPrefix, nil))
+	fmt.Fprintf(&progressText, "%d%%", percent)
+	progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferUploadedPrefix, nil))
+	fmt.Fprintf(&progressText, "%.2f MB / %.2f MB",
+		float64(info.Uploaded())/(1024*1024),
+		float64(info.TotalSize())/(1024*1024))
+
+	if p.start.Unix() > 0 {
+		elapsed := time.Since(p.start)
+		speed := float64(info.Uploaded()) / elapsed.Seconds()
+		progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferSpeedPrefix, nil))
+		progressText.WriteString(dlutil.FormatSize(int64(speed)) + "/s")
+
+		if info.Uploaded() > 0 {
+			remaining := time.Duration(float64(info.TotalSize()-info.Uploaded()) / speed * float64(time.Second))
+			progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferRemainingTimePrefix, nil))
+			progressText.WriteString(formatDuration(remaining))
+		}
+	}
+
+	processing := info.Processing()
+	if len(processing) > 0 {
+		progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferProcessingPrefix, nil))
+		for i, elem := range processing {
+			if i >= 3 {
+				progressText.WriteString(i18n.T(i18nk.BotMsgProgressTransferProcessingMore, map[string]any{"Count": len(processing) - 3}))
+				break
+			}
+			fmt.Fprintf(&progressText, "- %s\n", elem.FileName())
+		}
+	}
+
+	if err := styling.Perform(&entityBuilder,
+		styling.Plain(progressText.String()),
+	); err != nil {
+		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
+		return
+	}
+
+	text, entities := entityBuilder.Complete()
+	req := &tg.MessagesEditMessageRequest{
+		ID: p.MessageID,
+	}
+	req.SetMessage(text)
+	req.SetEntities(entities)
+	req.SetReplyMarkup(&tg.ReplyInlineMarkup{
+		Rows: []tg.KeyboardButtonRow{
+			{
+				Buttons: []tg.KeyboardButtonClass{
+					tgutil.BuildCancelButton(info.TaskID()),
+				},
+			},
+		},
+	})
+
+	ext := tgutil.ExtFromContext(ctx)
+	if ext != nil {
+		ext.EditMessage(p.ChatID, req)
+	}
+}
+
+func (p *Progress) OnDone(ctx context.Context, info TaskInfo, err error) {
+	log.FromContext(ctx).Debugf("Transfer task progress tracking done for message %d in chat %d", p.MessageID, p.ChatID)
+
+	entityBuilder := entity.Builder{}
+	var resultText strings.Builder
+
+	if err != nil {
+		resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferFailedPrefix, nil))
+		resultText.WriteString(i18n.T(i18nk.BotMsgProgressErrorPrefix, nil))
+		fmt.Fprintf(&resultText, "%v\n", err)
+	} else {
+		resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferSuccessPrefix, nil))
+	}
+
+	elapsed := time.Since(p.start)
+	resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferTotalFilesPrefix, nil))
+	fmt.Fprintf(&resultText, "%d\n", info.Count())
+	resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferTotalSizePrefix, nil))
+	fmt.Fprintf(&resultText, "%.2f MB\n", float64(info.TotalSize())/(1024*1024))
+	resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferUploadedPrefix, nil))
+	fmt.Fprintf(&resultText, "%.2f MB\n", float64(info.Uploaded())/(1024*1024))
+	resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferElapsedTimePrefix, nil))
+	fmt.Fprintf(&resultText, "%s\n", formatDuration(elapsed))
+
+	if elapsed.Seconds() > 0 {
+		avgSpeed := float64(info.Uploaded()) / elapsed.Seconds()
+		resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferAvgSpeedPrefix, nil))
+		fmt.Fprintf(&resultText, "%s/s\n", dlutil.FormatSize(int64(avgSpeed)))
+	}
+
+	failedFiles := info.FailedFiles()
+	if len(failedFiles) > 0 {
+		resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferFailedFilesPrefix, nil))
+		fmt.Fprintf(&resultText, "%d\n", len(failedFiles))
+		for i, name := range failedFiles {
+			if i >= 5 {
+				resultText.WriteString(i18n.T(i18nk.BotMsgProgressTransferProcessingMore, map[string]any{"Count": len(failedFiles) - 5}))
+				break
+			}
+			fmt.Fprintf(&resultText, "- %s\n", name)
+		}
+	}
+
+	if err := styling.Perform(&entityBuilder,
+		styling.Plain(resultText.String()),
+	); err != nil {
+		log.FromContext(ctx).Errorf("Failed to build entities: %s", err)
+		return
+	}
+
+	text, entities := entityBuilder.Complete()
+	req := &tg.MessagesEditMessageRequest{
+		ID: p.MessageID,
+	}
+	req.SetMessage(text)
+	req.SetEntities(entities)
+
+	ext := tgutil.ExtFromContext(ctx)
+	if ext != nil {
+		ext.EditMessage(p.ChatID, req)
+	}
+}
+
+func shouldUpdateProgress(total, current int64, lastPercent int) bool {
+	if total == 0 {
+		return false
+	}
+	currentPercent := int((current * 100) / total)
+	return currentPercent > lastPercent && currentPercent%5 == 0
+}
+
+func formatDuration(d time.Duration) string {
+	d = d.Round(time.Second)
+	h := d / time.Hour
+	d -= h * time.Hour
+	m := d / time.Minute
+	d -= m * time.Minute
+	s := d / time.Second
+
+	if h > 0 {
+		return fmt.Sprintf("%dh%dm%ds", h, m, s)
+	}
+	if m > 0 {
+		return fmt.Sprintf("%dm%ds", m, s)
+	}
+	return fmt.Sprintf("%ds", s)
+}

core/tasks/transfer/task.go

@@ -0,0 +1,97 @@
+package transfer
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"sync/atomic"
+
+	"github.com/krau/SaveAny-Bot/core"
+	"github.com/krau/SaveAny-Bot/pkg/enums/tasktype"
+	"github.com/krau/SaveAny-Bot/pkg/storagetypes"
+	"github.com/krau/SaveAny-Bot/storage"
+	"github.com/rs/xid"
+)
+
+var _ core.Executable = (*Task)(nil)
+
+type TaskElement struct {
+	ID            string
+	SourceStorage storage.Storage
+	SourcePath    string
+	FileInfo      storagetypes.FileInfo
+	TargetStorage storage.Storage
+	TargetPath    string
+}
+
+type Task struct {
+	ID           string
+	ctx          context.Context
+	elems        []TaskElement
+	Progress     ProgressTracker
+	IgnoreErrors bool
+	uploaded     atomic.Int64
+	totalSize    int64
+	processing   map[string]TaskElementInfo
+	processingMu sync.RWMutex
+	failed       map[string]error
+}
+
+// Title implements core.Executable.
+func (t *Task) Title() string {
+	return fmt.Sprintf("[%s](%d files/%.2fMB)", t.Type(), len(t.elems), float64(t.totalSize)/(1024*1024))
+}
+
+// Type implements core.Executable.
+func (t *Task) Type() tasktype.TaskType {
+	return tasktype.TaskTypeTransfer
+}
+
+// TaskID implements core.Executable.
+func (t *Task) TaskID() string {
+	return t.ID
+}
+
+func NewTaskElement(
+	sourceStorage storage.Storage,
+	fileInfo storagetypes.FileInfo,
+	targetStorage storage.Storage,
+	targetPath string,
+) *TaskElement {
+	id := xid.New().String()
+	return &TaskElement{
+		ID:            id,
+		SourceStorage: sourceStorage,
+		SourcePath:    fileInfo.Path,
+		FileInfo:      fileInfo,
+		TargetStorage: targetStorage,
+		TargetPath:    targetPath,
+	}
+}
+
+func NewTransferTask(
+	id string,
+	ctx context.Context,
+	elems []TaskElement,
+	progress ProgressTracker,
+	ignoreErrors bool,
+) *Task {
+	task := &Task{
+		ID:       id,
+		ctx:      ctx,
+		elems:    elems,
+		Progress: progress,
+		uploaded: atomic.Int64{},
+		totalSize: func() int64 {
+			var total int64
+			for _, elem := range elems {
+				total += elem.FileInfo.Size
+			}
+			return total
+		}(),
+		processing:   make(map[string]TaskElementInfo),
+		IgnoreErrors: ignoreErrors,
+		failed:       make(map[string]error),
+	}
+	return task
+}

core/tasks/transfer/taskinfo.go

@@ -0,0 +1,73 @@
+package transfer
+
+type TaskElementInfo interface {
+	FileName() string
+	FileSize() int64
+	GetSourcePath() string
+	SourceStorageName() string
+}
+
+func (e *TaskElement) FileName() string {
+	return e.FileInfo.Name
+}
+
+func (e *TaskElement) FileSize() int64 {
+	return e.FileInfo.Size
+}
+
+func (e *TaskElement) GetSourcePath() string {
+	return e.SourcePath
+}
+
+func (e *TaskElement) SourceStorageName() string {
+	return e.SourceStorage.Name()
+}
+
+type TaskInfo interface {
+	TaskID() string
+	TotalSize() int64
+	Uploaded() int64
+	Count() int
+	Processing() []TaskElementInfo
+	FailedFiles() []string
+}
+
+func (t *Task) TotalSize() int64 {
+	return t.totalSize
+}
+
+func (t *Task) Uploaded() int64 {
+	return t.uploaded.Load()
+}
+
+func (t *Task) Count() int {
+	return len(t.elems)
+}
+
+func (t *Task) Processing() []TaskElementInfo {
+	t.processingMu.RLock()
+	defer t.processingMu.RUnlock()
+
+	result := make([]TaskElementInfo, 0, len(t.processing))
+	for _, elem := range t.processing {
+		result = append(result, elem)
+	}
+	return result
+}
+
+func (t *Task) FailedFiles() []string {
+	t.processingMu.RLock()
+	defer t.processingMu.RUnlock()
+
+	result := make([]string, 0, len(t.failed))
+	for id := range t.failed {
+		// Find the element by ID
+		for _, elem := range t.elems {
+			if elem.ID == id {
+				result = append(result, elem.FileInfo.Name)
+				break
+			}
+		}
+	}
+	return result
+}

core/tasks/ytdlp/execute.go

@@ -80,22 +80,32 @@ func (t *Task) Execute(ctx context.Context) error {
 func (t *Task) downloadFiles(ctx context.Context, tempDir string) ([]string, error) {
 	logger := log.FromContext(ctx)
 
-	// Configure yt-dlp command
+	// Configure yt-dlp command with essential settings
+	// Always set output path to ensure files go to temp directory
 	cmd := ytdlp.New().
-		FormatSort("res,ext:mp4:m4a").
-		RecodeVideo("mp4").
-		Output(filepath.Join(tempDir, "%(title)s.%(ext)s")).
-		RestrictFilenames()
+		Output(filepath.Join(tempDir, "%(title)s.%(ext)s"))
+
+	// Apply config-based format/quality defaults only when the user passes no
+	// custom flags. Any user flag means they take full control of yt-dlp.
+	if len(t.Flags) == 0 {
+		cmd = applyFormatConfig(cmd, config.C().Ytdlp)
+	}
+	// Note: If custom flags are provided, users have full control over format/quality
+	// The output path is always set above to ensure downloads go to the correct directory
 
 	if t.Progress != nil {
 		t.Progress.OnProgress(ctx, t, "Downloading...")
 	}
 
-	// Execute download with URLs as arguments
-	logger.Infof("Executing yt-dlp for %d URL(s)", len(t.URLs))
+	// Execute download with URLs and custom flags
+	logger.Infof("Executing yt-dlp for %d URL(s) with %d custom flag(s)", len(t.URLs), len(t.Flags))
+
+	// Combine flags and URLs as arguments (flags first, then URLs)
+	// yt-dlp accepts: yt-dlp [OPTIONS] URL [URL...]
+	args := append(t.Flags, t.URLs...)
 
 	// Run with context for cancellation support
-	result, err := cmd.Run(ctx, t.URLs...)
+	result, err := cmd.Run(ctx, args...)
 	if err != nil {
 		// Check if context was canceled
 		if errors.Is(err, context.Canceled) {

core/tasks/ytdlp/format.go

@@ -0,0 +1,40 @@
+package ytdlp
+
+import (
+	"strconv"
+
+	ytdlp "github.com/lrstanley/go-ytdlp"
+
+	"github.com/krau/SaveAny-Bot/config"
+)
+
+// buildFormatSelector translates a max height into a yt-dlp format selector.
+// It prefers merging the best video+audio within the height limit, then falls
+// back to a single muxed stream. An empty result means "no explicit selector".
+func buildFormatSelector(maxHeight int) string {
+	if maxHeight <= 0 {
+		return ""
+	}
+	h := strconv.Itoa(maxHeight)
+	return "bv*[height<=" + h + "]+ba/b[height<=" + h + "]/b"
+}
+
+// applyFormatConfig configures format/quality on the yt-dlp command according to
+// the ytdlp config. It is only meant to be called when the user did not supply
+// any custom flags, so config-driven defaults never conflict with user input.
+func applyFormatConfig(cmd *ytdlp.Command, cfg config.YtdlpConfig) *ytdlp.Command {
+	switch {
+	case cfg.Format != "":
+		cmd = cmd.Format(cfg.Format)
+	case cfg.MaxHeight > 0:
+		cmd = cmd.Format(buildFormatSelector(cfg.MaxHeight))
+	default:
+		// Preserve the original default: prefer highest resolution mp4/m4a.
+		cmd = cmd.FormatSort("res,ext:mp4:m4a")
+	}
+	if cfg.Recode != "" {
+		cmd = cmd.RecodeVideo(cfg.Recode)
+	}
+	cmd = cmd.RestrictFilenames()
+	return cmd
+}

core/tasks/ytdlp/format_test.go

@@ -0,0 +1,23 @@
+package ytdlp
+
+import "testing"
+
+func TestBuildFormatSelector(t *testing.T) {
+	tests := []struct {
+		name      string
+		maxHeight int
+		want      string
+	}{
+		{"no limit", 0, ""},
+		{"negative", -1, ""},
+		{"1080p", 1080, "bv*[height<=1080]+ba/b[height<=1080]/b"},
+		{"720p", 720, "bv*[height<=720]+ba/b[height<=720]/b"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := buildFormatSelector(tt.maxHeight); got != tt.want {
+				t.Errorf("buildFormatSelector(%d) = %q, want %q", tt.maxHeight, got, tt.want)
+			}
+		})
+	}
+}

core/tasks/ytdlp/task.go

@@ -15,6 +15,7 @@ type Task struct {
 	ID       string
 	ctx      context.Context
 	URLs     []string
+	Flags    []string
 	Storage  storage.Storage
 	StorPath string
 	Progress ProgressTracker
@@ -43,6 +44,7 @@ func NewTask(
 	id string,
 	ctx context.Context,
 	urls []string,
+	flags []string,
 	stor storage.Storage,
 	storPath string,
 	progressTracker ProgressTracker,
@@ -51,6 +53,7 @@ func NewTask(
 		ID:       id,
 		ctx:      ctx,
 		URLs:     urls,
+		Flags:    flags,
 		Storage:  stor,
 		StorPath: storPath,
 		Progress: progressTracker,