refactor(media): add MediaStore for unified media file lifecycle management

Channels previously deleted downloaded media files via defer os.Remove,
racing with the async Agent consumer. Introduce MediaStore to decouple
file ownership: channels register files on download, Agent releases them
after processing via ReleaseAll(scope).

- New pkg/media with MediaStore interface + FileMediaStore implementation
- InboundMessage gains MediaScope field for lifecycle tracking
- BaseChannel gains SetMediaStore/GetMediaStore + BuildMediaScope helper
- Manager injects MediaStore into channels; AgentLoop releases on completion
- Telegram, Discord, Slack, OneBot, LINE channels migrated from defer
  os.Remove to store.Store() with media:// refs

pkg/channels/base.go

@@ -5,7 +5,10 @@ import (
 	"strings"
 	"sync/atomic"
 
+	"github.com/google/uuid"
+
 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
 type Channel interface {
@@ -41,6 +44,7 @@ type BaseChannel struct {
 	name             string
 	allowList        []string
 	maxMessageLength int
+	mediaStore       media.MediaStore
 }
 
 func NewBaseChannel(
@@ -125,15 +129,18 @@ func (c *BaseChannel) HandleMessage(
 		return
 	}
 
+	scope := BuildMediaScope(c.name, chatID, messageID)
+
 	msg := bus.InboundMessage{
-		Channel:   c.name,
-		SenderID:  senderID,
-		ChatID:    chatID,
-		Content:   content,
-		Media:     media,
-		Peer:      peer,
-		MessageID: messageID,
-		Metadata:  metadata,
+		Channel:    c.name,
+		SenderID:   senderID,
+		ChatID:     chatID,
+		Content:    content,
+		Media:      media,
+		Peer:       peer,
+		MessageID:  messageID,
+		MediaScope: scope,
+		Metadata:   metadata,
 	}
 
 	c.bus.PublishInbound(msg)
@@ -142,3 +149,18 @@ func (c *BaseChannel) HandleMessage(
 func (c *BaseChannel) SetRunning(running bool) {
 	c.running.Store(running)
 }
+
+// SetMediaStore injects a MediaStore into the channel.
+func (c *BaseChannel) SetMediaStore(s media.MediaStore) { c.mediaStore = s }
+
+// GetMediaStore returns the injected MediaStore (may be nil).
+func (c *BaseChannel) GetMediaStore() media.MediaStore { return c.mediaStore }
+
+// BuildMediaScope constructs a scope key for media lifecycle tracking.
+func BuildMediaScope(channel, chatID, messageID string) string {
+	id := messageID
+	if id == "" {
+		id = uuid.New().String()
+	}
+	return channel + ":" + chatID + ":" + id
+}

pkg/channels/discord/discord.go

@@ -3,7 +3,6 @@ package discord
 import (
 	"context"
 	"fmt"
-	"os"
 	"strings"
 	"sync"
 	"time"
@@ -14,6 +13,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 	"github.com/sipeed/picoclaw/pkg/voice"
 )
@@ -202,19 +202,22 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 	content := m.Content
 	content = c.stripBotMention(content)
 	mediaPaths := make([]string, 0, len(m.Attachments))
-	localFiles := make([]string, 0, len(m.Attachments))
 
-	// Ensure temp files are cleaned up when function returns
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("discord", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("discord", m.ChannelID, m.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "discord",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}
 
 	for _, attachment := range m.Attachments {
 		isAudio := utils.IsAudioFile(attachment.Filename, attachment.ContentType)
@@ -222,8 +225,6 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		if isAudio {
 			localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
 			if localPath != "" {
-				localFiles = append(localFiles, localPath)
-
 				transcribedText := ""
 				if c.transcriber != nil && c.transcriber.IsAvailable() {
 					ctx, cancel := context.WithTimeout(c.ctx, transcriptionTimeout)
@@ -245,6 +246,7 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 					transcribedText = fmt.Sprintf("[audio: %s]", attachment.Filename)
 				}
 
+				mediaPaths = append(mediaPaths, storeMedia(localPath, attachment.Filename))
 				content = appendContent(content, transcribedText)
 			} else {
 				logger.WarnCF("discord", "Failed to download audio attachment", map[string]any{

pkg/channels/line/line.go

@@ -10,7 +10,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 	"strings"
 	"sync"
 	"time"
@@ -19,6 +18,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
@@ -308,18 +308,22 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 
 	var content string
 	var mediaPaths []string
-	localFiles := []string{}
 
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("line", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("line", chatID, msg.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "line",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}
 
 	switch msg.Type {
 	case "text":
@@ -331,22 +335,19 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 	case "image":
 		localPath := c.downloadContent(msg.ID, "image.jpg")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "image.jpg"))
 			content = "[image]"
 		}
 	case "audio":
 		localPath := c.downloadContent(msg.ID, "audio.m4a")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "audio.m4a"))
 			content = "[audio]"
 		}
 	case "video":
 		localPath := c.downloadContent(msg.ID, "video.mp4")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "video.mp4"))
 			content = "[video]"
 		}
 	case "file":

pkg/channels/manager.go

@@ -15,6 +15,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
@@ -31,6 +32,7 @@ type Manager struct {
 	workers      map[string]*channelWorker
 	bus          *bus.MessageBus
 	config       *config.Config
+	mediaStore   media.MediaStore
 	dispatchTask *asyncTask
 	mu           sync.RWMutex
 }
@@ -39,12 +41,13 @@ type asyncTask struct {
 	cancel context.CancelFunc
 }
 
-func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error) {
+func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.MediaStore) (*Manager, error) {
 	m := &Manager{
-		channels: make(map[string]Channel),
-		workers:  make(map[string]*channelWorker),
-		bus:      messageBus,
-		config:   cfg,
+		channels:   make(map[string]Channel),
+		workers:    make(map[string]*channelWorker),
+		bus:        messageBus,
+		config:     cfg,
+		mediaStore: store,
 	}
 
 	if err := m.initChannels(); err != nil {
@@ -73,6 +76,12 @@ func (m *Manager) initChannel(name, displayName string) {
 			"error":   err.Error(),
 		})
 	} else {
+		// Inject MediaStore if channel supports it
+		if m.mediaStore != nil {
+			if setter, ok := ch.(interface{ SetMediaStore(s media.MediaStore) }); ok {
+				setter.SetMediaStore(m.mediaStore)
+			}
+		}
 		m.channels[name] = ch
 		m.workers[name] = &channelWorker{
 			ch:    ch,

pkg/channels/onebot/onebot.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"strconv"
 	"strings"
 	"sync"
@@ -17,6 +16,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 	"github.com/sipeed/picoclaw/pkg/voice"
 )
@@ -575,11 +575,15 @@ type parseMessageResult struct {
 	Text           string
 	IsBotMentioned bool
 	Media          []string
-	LocalFiles     []string
 	ReplyTo        string
 }
 
-func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64) parseMessageResult {
+func (c *OneBotChannel) parseMessageSegments(
+	raw json.RawMessage,
+	selfID int64,
+	store media.MediaStore,
+	scope string,
+) parseMessageResult {
 	if len(raw) == 0 {
 		return parseMessageResult{}
 	}
@@ -606,10 +610,23 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 	var textParts []string
 	mentioned := false
 	selfIDStr := strconv.FormatInt(selfID, 10)
-	var media []string
-	var localFiles []string
+	var mediaRefs []string
 	var replyTo string
 
+	// Helper to register a local file with the media store
+	storeFile := func(localPath, filename string) string {
+		if store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "onebot",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath // fallback
+	}
+
 	for _, seg := range segments {
 		segType, _ := seg["type"].(string)
 		data, _ := seg["data"].(map[string]any)
@@ -645,8 +662,7 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						media = append(media, localPath)
-						localFiles = append(localFiles, localPath)
+						mediaRefs = append(mediaRefs, storeFile(localPath, filename))
 						textParts = append(textParts, fmt.Sprintf("[%s]", segType))
 					}
 				}
@@ -660,7 +676,6 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						localFiles = append(localFiles, localPath)
 						if c.transcriber != nil && c.transcriber.IsAvailable() {
 							tctx, tcancel := context.WithTimeout(c.ctx, 30*time.Second)
 							result, err := c.transcriber.Transcribe(tctx, localPath)
@@ -670,13 +685,15 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 									"error": err.Error(),
 								})
 								textParts = append(textParts, "[voice (transcription failed)]")
-								media = append(media, localPath)
+								mediaRefs = append(mediaRefs, storeFile(localPath, "voice.amr"))
 							} else {
 								textParts = append(textParts, fmt.Sprintf("[voice transcription: %s]", result.Text))
+								// Still store the file so it can be released later
+								storeFile(localPath, "voice.amr")
 							}
 						} else {
 							textParts = append(textParts, "[voice]")
-							media = append(media, localPath)
+							mediaRefs = append(mediaRefs, storeFile(localPath, "voice.amr"))
 						}
 					}
 				}
@@ -706,8 +723,7 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 	return parseMessageResult{
 		Text:           strings.TrimSpace(strings.Join(textParts, "")),
 		IsBotMentioned: mentioned,
-		Media:          media,
-		LocalFiles:     localFiles,
+		Media:          mediaRefs,
 		ReplyTo:        replyTo,
 	}
 }
@@ -799,7 +815,17 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		selfID = atomic.LoadInt64(&c.selfID)
 	}
 
-	parsed := c.parseMessageSegments(raw.Message, selfID)
+	// Compute scope for media store before parsing (parsing may download files)
+	var chatIDForScope string
+	switch raw.MessageType {
+	case "group":
+		chatIDForScope = "group:" + strconv.FormatInt(groupID, 10)
+	default:
+		chatIDForScope = "private:" + strconv.FormatInt(userID, 10)
+	}
+	scope := channels.BuildMediaScope("onebot", chatIDForScope, messageID)
+
+	parsed := c.parseMessageSegments(raw.Message, selfID, c.GetMediaStore(), scope)
 	isBotMentioned := parsed.IsBotMentioned
 
 	content := raw.RawMessage
@@ -828,20 +854,6 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		}
 	}
 
-	// Clean up temp files when done
-	if len(parsed.LocalFiles) > 0 {
-		defer func() {
-			for _, f := range parsed.LocalFiles {
-				if err := os.Remove(f); err != nil {
-					logger.DebugCF("onebot", "Failed to remove temp file", map[string]any{
-						"path":  f,
-						"error": err.Error(),
-					})
-				}
-			}
-		}()
-	}
-
 	if c.isDuplicate(messageID) {
 		logger.DebugCF("onebot", "Duplicate message, skipping", map[string]any{
 			"message_id": messageID,

pkg/channels/slack/slack.go

@@ -3,7 +3,6 @@ package slack
 import (
 	"context"
 	"fmt"
-	"os"
 	"strings"
 	"sync"
 	"time"
@@ -16,6 +15,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 	"github.com/sipeed/picoclaw/pkg/voice"
 )
@@ -233,19 +233,22 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 	content = c.stripBotMention(content)
 
 	var mediaPaths []string
-	localFiles := []string{} // 跟踪需要清理的本地文件
 
-	// 确保临时文件在函数返回时被清理
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("slack", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("slack", chatID, messageTS)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "slack",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}
 
 	if ev.Message != nil && len(ev.Message.Files) > 0 {
 		for _, file := range ev.Message.Files {
@@ -253,8 +256,7 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 			if localPath == "" {
 				continue
 			}
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, file.Name))
 
 			if utils.IsAudioFile(file.Name, file.Mimetype) && c.transcriber != nil && c.transcriber.IsAvailable() {
 				ctx, cancel := context.WithTimeout(c.ctx, 30*time.Second)

pkg/channels/telegram/telegram.go

@@ -20,6 +20,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 	"github.com/sipeed/picoclaw/pkg/voice"
 )
@@ -251,19 +252,24 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 
 	content := ""
 	mediaPaths := []string{}
-	localFiles := []string{} // 跟踪需要清理的本地文件
 
-	// 确保临时文件在函数返回时被清理
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("telegram", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	chatIDStr := fmt.Sprintf("%d", chatID)
+	messageIDStr := fmt.Sprintf("%d", message.MessageID)
+	scope := channels.BuildMediaScope("telegram", chatIDStr, messageIDStr)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "telegram",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback: use raw path
+	}
 
 	if message.Text != "" {
 		content += message.Text
@@ -280,8 +286,7 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 		photo := message.Photo[len(message.Photo)-1]
 		photoPath := c.downloadPhoto(ctx, photo.FileID)
 		if photoPath != "" {
-			localFiles = append(localFiles, photoPath)
-			mediaPaths = append(mediaPaths, photoPath)
+			mediaPaths = append(mediaPaths, storeMedia(photoPath, "photo.jpg"))
 			if content != "" {
 				content += "\n"
 			}
@@ -292,8 +297,7 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 	if message.Voice != nil {
 		voicePath := c.downloadFile(ctx, message.Voice.FileID, ".ogg")
 		if voicePath != "" {
-			localFiles = append(localFiles, voicePath)
-			mediaPaths = append(mediaPaths, voicePath)
+			mediaPaths = append(mediaPaths, storeMedia(voicePath, "voice.ogg"))
 
 			transcribedText := ""
 			if c.transcriber != nil && c.transcriber.IsAvailable() {
@@ -327,8 +331,7 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 	if message.Audio != nil {
 		audioPath := c.downloadFile(ctx, message.Audio.FileID, ".mp3")
 		if audioPath != "" {
-			localFiles = append(localFiles, audioPath)
-			mediaPaths = append(mediaPaths, audioPath)
+			mediaPaths = append(mediaPaths, storeMedia(audioPath, "audio.mp3"))
 			if content != "" {
 				content += "\n"
 			}
@@ -339,8 +342,7 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 	if message.Document != nil {
 		docPath := c.downloadFile(ctx, message.Document.FileID, "")
 		if docPath != "" {
-			localFiles = append(localFiles, docPath)
-			mediaPaths = append(mediaPaths, docPath)
+			mediaPaths = append(mediaPaths, storeMedia(docPath, "document"))
 			if content != "" {
 				content += "\n"
 			}
@@ -367,7 +369,6 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 	}
 
 	// Stop any previous thinking animation
-	chatIDStr := fmt.Sprintf("%d", chatID)
 	if prevStop, ok := c.stopThinking.Load(chatIDStr); ok {
 		if cf, ok := prevStop.(*thinkingCancel); ok && cf != nil {
 			cf.Cancel()