@workclaw/openclaw-workclaw 1.0.17 → 1.0.18

package/src/gateway/message-context.ts

@@ -1,275 +1,408 @@
-import type { PluginRuntime } from 'openclaw/plugin-sdk'
+import type { WorkclawConfig } from "../types.js";
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import https from "node:https";
+import http from "node:http";
+
+// 附件接口
+export interface Attachment {
+    url: string
+    fileId: string
+    type: 'image' | 'file'
+    name?: string
+}
 
 /** Channel/plugin name constant */
-export const OPENCLAW_WORKCLAW_CHANNEL = 'openclaw-workclaw'
+export const OPENCLAW_WORKCLAW_CHANNEL = "openclaw-workclaw";
 
 export interface InboundMessage {
-  text: string
-  to: string
-  from: string
-  chatType: 'dm' | 'group'
-  messageId: string
-  rawPayload: string
-  timestamp: number
+    text: string;
+    to: string;
+    from: string;
+    chatType: "dm" | "group";
+    messageId: string;
+    rawPayload: string;
+    timestamp: number;
+    attachments?: Attachment[]  // 文件 URL 列表
 }
 
 export interface InboundContextPayload {
-  [key: string]: unknown
-  Body: string
-  BodyForAgent: string
-  RawBody: string
-  From: string
-  To: string
-  ChatType: 'dm' | 'group'
-  Provider: string
-  Surface: string
-  Timestamp: number
-  AccountId: string
-  AgentId?: string
-  MessageSid?: string
-  OriginatingChannel: string
-  OriginatingTo: string
+    [key: string]: unknown;
+    Body: string;
+    BodyForAgent: string;
+    RawBody: string;
+    From: string;
+    To: string;
+    ChatType: "dm" | "group";
+    Provider: string;
+    Surface: string;
+    Timestamp: number;
+    AccountId: string;
+    AgentId?: string;
+    MessageSid?: string;
+    OriginatingChannel: string;
+    OriginatingTo: string;
 }
 
-export type WorkClawMessageType
-  = | 'agent_message' // 正常的业务消息
-    | 'ping' // 需要回复 pong 的消息
-    | 'disconnect' // 断开连接的消息
-    | 'agent_created' // 创建账户事件
-    | 'agent_updated' // 更新账户事件
-    | 'agent_deleted' // 删除账户事件
-    | 'tools_list' // 获取工具列表事件
-    | 'skills_list' // 获取 skills 列表事件
-    | 'skills_event' // skills 相关事件（create/update/delete/list/get/invoke）
-    | 'init_agent' // 初始化智能体事件
-    | 'ignored' // 忽略的消息（未知类型）
+export type WorkClawMessageType =
+    | "agent_message"   // 正常的业务消息
+    | "ping"           // 需要回复 pong 的消息
+    | "disconnect"     // 断开连接的消息
+    | "agent_created"  // 创建账户事件
+    | "agent_updated"  // 更新账户事件
+    | "agent_deleted"  // 删除账户事件
+    | "tools_list"     // 获取工具列表事件
+    | "skills_list"    // 获取 skills 列表事件
+    | "skills_event"   // skills 相关事件（create/update/delete/list/get/invoke）
+    | "init_agent"     // 初始化智能体事件
+    | "ignored";       // 忽略的消息（未知类型）
 
 export interface ParseWorkClawResult {
-  type: WorkClawMessageType
-  message?: {
-    text: string
-    userId: string
-    openConversationId: string
-    messageId: string
-    agentId?: string | number
-  }
-  pongData?: any // 用于回复 pong 的数据
-  eventData?: any // 事件数据（用于 AGENT_CREATED/UPDATED/DELETED）
-  skillsEvent?: {
-    // skills 事件数据
-    topic: string // skills/create, skills/update, skills/delete, skills/list, skills/get, skills/invoke
-    requestId: string
-    callbackUrl: string
-    authToken?: string
-    data: any
-  }
+    type: WorkClawMessageType;
+    message?: {
+        text: string;
+        userId: string;
+        openConversationId: string;
+        messageId: string;
+        agentId?: string | number;
+        attachments?: Attachment[]
+    };
+    pongData?: any;  // 用于回复 pong 的数据
+    eventData?: any; // 事件数据（用于 AGENT_CREATED/UPDATED/DELETED 及 skills 事件）
 }
 
 export function parseInboundMessage(data: string, allowRawJsonPayload?: boolean): Partial<InboundMessage> {
-  let input: any = {}
-  try {
-    input = data ? JSON.parse(data) : {}
-  }
-  catch {
-    // Not JSON, treat as plain text
-  }
-
-  const text
-    = typeof input.text === 'string'
-      ? input.text
-      : typeof input.message === 'string'
-        ? input.message
-        : typeof input.body === 'string'
-          ? input.body
-          : data
-
-  const to = String(input.to ?? input.chatId ?? input.target ?? '')
-  const from = String(input.from ?? input.senderId ?? input.userId ?? '')
-  const chatType = String(input.chatType || '').toLowerCase() === 'group' ? 'group' : 'dm'
-  const messageId = String(input.messageId ?? input.id ?? '')
-  const rawPayload = allowRawJsonPayload ? JSON.stringify(input ?? {}) : data
-
-  return {
-    text,
-    to,
-    from,
-    chatType,
-    messageId,
-    rawPayload,
-  }
+    let input: any = {};
+    try {
+        input = data ? JSON.parse(data) : {};
+    } catch {
+        // Not JSON, treat as plain text
+    }
+
+    const text =
+        typeof input.text === "string"
+            ? input.text
+            : typeof input.message === "string"
+                ? input.message
+                : typeof input.body === "string"
+                    ? input.body
+                    : data;
+
+    const to = String(input.to ?? input.chatId ?? input.target ?? "");
+    const from = String(input.from ?? input.senderId ?? input.userId ?? "");
+    const chatType = String(input.chatType || "").toLowerCase() === "group" ? "group" : "dm";
+    const messageId = String(input.messageId ?? input.id ?? "");
+    const rawPayload = allowRawJsonPayload ? JSON.stringify(input ?? {}) : data;
+
+    return {
+        text,
+        to,
+        from,
+        chatType,
+        messageId,
+        rawPayload,
+    };
 }
 
 export function parseWorkClawMessage(data: string, log?: {
-  info?: (msg: string) => void
-  warn?: (msg: string) => void
-  error?: (msg: string) => void
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
 }): ParseWorkClawResult | null {
-  // {"specVersion":"1.0","type":"EVENT","metadata":{"time":"1773749163831","event":"INIT_AGENT","contentType":"application/json"},"data":"\"12557533957824965\""}
-  let input: any = {}
-  try {
-    input = data ? JSON.parse(data) : {}
-  }
-  catch {
-    log?.info?.(`Failed to parse message data=${data}`)
-    return null
-  }
-
-  // Handle plain text ping
-  if (typeof input === 'string' && input.toLowerCase() === 'ping') {
-    return {
-      type: 'ping',
-      pongData: input,
-    }
-  }
-
-  const envelope = input && typeof input === 'object' ? input : { data: input }
-  const topic = envelope?.metadata?.topic
-  const type = String(envelope?.type || '').trim().toUpperCase()
-  const topicLower = String(topic || '').trim().toLowerCase()
-
-  if (type === 'INIT_AGENT') {
-    let parsedData = envelope?.data
-    if (typeof parsedData === 'string') {
-      try {
-        parsedData = JSON.parse(parsedData)
-      }
-      catch {
-        // 解析失败，保持原样
-      }
+    //{"specVersion":"1.0","type":"EVENT","metadata":{"time":"1773749163831","event":"INIT_AGENT","contentType":"application/json"},"data":"\"12557533957824965\""}
+    let input: any = {};
+    try {
+        input = data ? JSON.parse(data) : {};
+    } catch {
+        log?.info?.(`Failed to parse message data=${data}`);
+        return null;
     }
 
-    return {
-      type: 'init_agent',
-      eventData: parsedData,
+    // Handle plain text ping
+    if (typeof input === "string" && input.toLowerCase() === "ping") {
+        return {
+            type: "ping",
+            pongData: input,
+        };
     }
-  }
-
-  // Handle SYSTEM messages
-  if (type === 'SYSTEM') {
-    if (topicLower === 'ping') {
-      return {
-        type: 'ping',
-        pongData: envelope?.data,
-      }
+
+    const envelope = input && typeof input === "object" ? input : { data: input };
+    const topic = envelope?.metadata?.topic;
+    const type = String(envelope?.type || "").trim().toUpperCase();
+    const topicLower = String(topic || "").trim().toLowerCase();
+
+    if (type === "INIT_AGENT") {
+        let parsedData = envelope?.data;
+        if (typeof parsedData === "string") {
+            try {
+                parsedData = JSON.parse(parsedData);
+            } catch (e) {
+                // 解析失败，保持原样
+            }
+        }
+
+        return {
+            type: "init_agent",
+            eventData: parsedData,
+        };
     }
-    if (topicLower === 'disconnect') {
-      return {
-        type: 'disconnect',
-      }
+
+    // Handle SYSTEM messages
+    if (type === "SYSTEM") {
+        if (topicLower === "ping") {
+            return {
+                type: "ping",
+                pongData: envelope?.data,
+            };
+        }
+        if (topicLower === "disconnect") {
+            return {
+                type: "disconnect",
+            };
+        }
+        // Unknown system message type, ignore
+        return {
+            type: "ignored",
+        };
     }
-    // Unknown system message type, ignore
-    return {
-      type: 'ignored',
+
+    // Handle EVENT messages (AGENT_CREATED, AGENT_UPDATED, AGENT_DELETED, TOOLS_LIST, SKILLS_LIST, INIT_AGENT)
+    if (type === "EVENT") {
+        const eventType = String(envelope?.metadata?.event || "").trim().toUpperCase();
+
+        // 解析 data 字段（可能是 JSON 字符串）
+        let parsedData = envelope?.data;
+        if (typeof parsedData === "string") {
+            try {
+                parsedData = JSON.parse(parsedData);
+            } catch (e) {
+                // 解析失败，保持原样
+            }
+        }
+
+        if (eventType === "AGENT_CREATED") {
+            return {
+                type: "agent_created",
+                eventData: parsedData,
+            };
+        }
+        if (eventType === "AGENT_UPDATED") {
+            return {
+                type: "agent_updated",
+                eventData: parsedData,
+            };
+        }
+        if (eventType === "AGENT_DELETED") {
+            return {
+                type: "agent_deleted",
+                eventData: parsedData,
+            };
+        }
+        if (eventType === "TOOLS_LIST") {
+            return {
+                type: "tools_list",
+                eventData: parsedData,
+            };
+        }
+        if (eventType === "SKILLS_LIST") {
+            return {
+                type: "skills_list",
+                eventData: parsedData,
+            };
+        }
+        if (eventType === "INIT_AGENT") {
+            return {
+                type: "init_agent",
+                eventData: parsedData,
+            };
+        }
+
+        if (eventType === "SKILL_DO_REMIND") {
+            const eventTopic = String(parsedData?.dotype || "").toLowerCase();
+            return {
+                type: "skills_event",
+                eventData: {
+                    topic: "skills/" + eventTopic,
+                    requestId: "",
+                    callbackUrl: "",
+                    authToken: "",
+                    data: parsedData,
+                },
+            };
+        }
+
+        // Unknown event type, ignore
+        return {
+            type: "ignored",
+        };
     }
-  }
 
-  // Handle EVENT messages (AGENT_CREATED, AGENT_UPDATED, AGENT_DELETED, TOOLS_LIST, SKILLS_LIST, INIT_AGENT)
-  if (type === 'EVENT') {
-    const eventType = String(envelope?.metadata?.event || '').trim().toUpperCase()
+    // Only process CALLBACK type with AGENT_MESSAGE topic
+    if (type !== "CALLBACK" || String(topic || "").trim().toUpperCase() !== "AGENT_MESSAGE") {
+        return {
+            type: "ignored",
+        };
+    }
 
     // 解析 data 字段（可能是 JSON 字符串）
-    let parsedData = envelope?.data
-    if (typeof parsedData === 'string') {
-      try {
-        parsedData = JSON.parse(parsedData)
-      }
-      catch {
-        // 解析失败，保持原样
-      }
+    let payload = envelope?.data || {};
+    if (typeof payload === "string") {
+        try {
+            payload = JSON.parse(payload);
+        } catch (e) {
+            // 解析失败，保持原样
+        }
     }
 
-    if (eventType === 'AGENT_CREATED') {
-      return {
-        type: 'agent_created',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'AGENT_UPDATED') {
-      return {
-        type: 'agent_updated',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'AGENT_DELETED') {
-      return {
-        type: 'agent_deleted',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'TOOLS_LIST') {
-      return {
-        type: 'tools_list',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'SKILLS_LIST') {
-      return {
-        type: 'skills_list',
-        eventData: parsedData,
-      }
-    }
-    if (eventType === 'INIT_AGENT') {
-      return {
-        type: 'init_agent',
-        eventData: parsedData,
-      }
+    const text =
+        typeof payload?.message?.content === "string"
+            ? payload.message.content
+            : typeof payload?.message === "string"
+                ? payload.message
+                : "";
+
+    // 判断文件是否为图片
+    function isImageFile(url: string): boolean {
+        const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.svg', '.ico'];
+        const lowerUrl = url.toLowerCase();
+        return imageExtensions.some(ext => lowerUrl.endsWith(ext));
     }
 
-    if (eventType === 'SKILL_DO_REMIND') {
-      const eventTopic = String(parsedData?.dotype || '').toLowerCase()
-      return {
-        type: 'skills_event',
-        eventData: {
-          topic: `skills/${eventTopic}`,
-          requestId: '',
-          callbackUrl: '',
-          authToken: '',
-          data: parsedData,
-        },
-      }
-    }
+    // 解析 fileUrl 列表到 attachments（供 SDK 和 AI 使用）
+    const fileUrlList: string[] = Array.isArray(payload?.fileUrl) ? payload.fileUrl : [];
+    const attachments: Attachment[] = fileUrlList.map((url) => ({
+        url,
+        fileId: payload?.fileId ? String(payload.fileId) : '',
+        type: isImageFile(url) ? 'image' : 'file',
+    }));
 
-    // Unknown event type, ignore
     return {
-      type: 'ignored',
-    }
-  }
+        type: "agent_message",
+        message: {
+            text,
+            userId: String(payload?.userId ?? ""),
+            openConversationId: String(payload?.conversationId ?? ""),
+            messageId: String(payload?.msgId ?? ""),
+            agentId: payload?.agentId,
+            attachments: attachments.length > 0 ? attachments : undefined,
+        },
+    };
+}
 
-  // Only process CALLBACK type with AGENT_MESSAGE topic
-  if (type !== 'CALLBACK' || String(topic || '').trim().toUpperCase() !== 'AGENT_MESSAGE') {
-    return {
-      type: 'ignored',
+/**
+ * 从 URL 扩展名判断媒体类型
+ */
+function detectMediaType(url: string): string {
+    const lower = url.toLowerCase();
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg") || lower.endsWith(".png")
+        || lower.endsWith(".gif") || lower.endsWith(".webp") || lower.endsWith(".bmp")
+        || lower.endsWith(".svg") || lower.endsWith(".ico")) {
+        return "image";
     }
-  }
-
-  // 解析 data 字段（可能是 JSON 字符串）
-  let payload = envelope?.data || {}
-  if (typeof payload === 'string') {
-    try {
-      payload = JSON.parse(payload)
+    if (lower.endsWith(".mp3") || lower.endsWith(".wav") || lower.endsWith(".amr")
+        || lower.endsWith(".m4a") || lower.endsWith(".ogg")) {
+        return "audio";
     }
-    catch {
-      // 解析失败，保持原样
+    if (lower.endsWith(".mp4") || lower.endsWith(".avi") || lower.endsWith(".mov")
+        || lower.endsWith(".mkv") || lower.endsWith(".webm")) {
+        return "video";
     }
-  }
-
-  const text
-    = typeof payload?.message?.content === 'string'
-      ? payload.message.content
-      : typeof payload?.message === 'string'
-        ? payload.message
-        : ''
-
-  return {
-    type: 'agent_message',
-    message: {
-      text,
-      userId: String(payload?.userId ?? ''),
-      openConversationId: String(payload?.conversationId ?? ''),
-      messageId: String(payload?.msgId ?? ''),
-      agentId: payload?.agentId,
-    },
-  }
+    if (lower.endsWith(".pdf")) return "application/pdf";
+    if (lower.endsWith(".docx")) return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    if (lower.endsWith(".xlsx")) return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    if (lower.endsWith(".pptx")) return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    if (lower.endsWith(".doc")) return "application/msword";
+    if (lower.endsWith(".xls")) return "application/vnd.ms-excel";
+    if (lower.endsWith(".ppt")) return "application/vnd.ms-powerpoint";
+    if (lower.endsWith(".txt")) return "text/plain";
+    if (lower.endsWith(".zip")) return "application/zip";
+    if (lower.endsWith(".rar")) return "application/x-rar-compressed";
+    return "application/octet-stream";
+}
+
+/**
+ * 从 URL 扩展名获取人类可读的类型标签
+ */
+function getMediaTypeLabel(url: string): string {
+    const lower = url.toLowerCase();
+    if (lower.endsWith(".pdf")) return "PDF";
+    if (lower.endsWith(".docx")) return "Word";
+    if (lower.endsWith(".doc")) return "Word";
+    if (lower.endsWith(".xlsx")) return "Excel";
+    if (lower.endsWith(".xls")) return "Excel";
+    if (lower.endsWith(".pptx")) return "PowerPoint";
+    if (lower.endsWith(".ppt")) return "PowerPoint";
+    if (lower.endsWith(".txt")) return "文本";
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "JPG图片";
+    if (lower.endsWith(".png")) return "PNG图片";
+    if (lower.endsWith(".gif")) return "GIF图片";
+    if (lower.endsWith(".webp")) return "WebP图片";
+    if (lower.endsWith(".mp3")) return "音频";
+    if (lower.endsWith(".wav")) return "音频";
+    if (lower.endsWith(".mp4")) return "视频";
+    if (lower.endsWith(".zip") || lower.endsWith(".rar")) return "压缩包";
+    return "文件";
+}
+
+/**
+ * 下载文件到本地下载目录（按 accountId/peerId 隔离），返回本地路径
+ */
+async function downloadFileToLocal(
+    url: string,
+    accountId: string,
+    peerId: string,
+    log?: { info?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void },
+): Promise<string | null> {
+    const downloadsDir = path.join(os.homedir(), ".openclaw", "media", "workclaw", "downloads", accountId, peerId);
+    try {
+        await fs.mkdir(downloadsDir, { recursive: true });
+    } catch {}
+
+    const urlObj = new URL(url);
+    const fileName = path.basename(urlObj.pathname) || "file";
+    const ext = path.extname(fileName);
+    const stem = path.basename(fileName, ext);
+    const localFileName = `${stem}_${Date.now()}${ext}`;
+    const localFilePath = path.join(downloadsDir, localFileName);
+
+    return new Promise((resolve) => {
+        const client = url.startsWith("https:") ? https : http;
+        const req = client.get(url, (res) => {
+            if (res.statusCode !== 200) {
+                log?.warn?.(`downloadFile: HTTP ${res.statusCode} for ${url}`);
+                resolve(null);
+                return;
+            }
+            const chunks: Buffer[] = [];
+            res.on("data", (chunk: Buffer) => chunks.push(chunk));
+            res.on("end", async () => {
+                try {
+                    const buffer = Buffer.concat(chunks);
+                    await fs.writeFile(localFilePath, buffer);
+                    log?.info?.(`downloadFile: saved ${buffer.length} bytes -> ${localFilePath}`);
+                    resolve(localFilePath);
+                } catch (err) {
+                    log?.error?.(`downloadFile: write failed: ${String(err)}`);
+                    resolve(null);
+                }
+            });
+            res.on("error", (err) => {
+                log?.error?.(`downloadFile: read error: ${String(err)}`);
+                resolve(null);
+            });
+        });
+        req.on("error", (err) => {
+            log?.error?.(`downloadFile: request error: ${String(err)}`);
+            resolve(null);
+        });
+        req.setTimeout(30000, () => {
+            req.destroy();
+            log?.warn?.(`downloadFile: timeout for ${url}`);
+            resolve(null);
+        });
+    });
 }
 
 /**
@@ -281,142 +414,181 @@ export function parseWorkClawMessage(data: string, log?: {
  *
  * @param message - The inbound message
  * @param accountId - Account ID
- * @param config - Account config (OpenclawWorkclawConfig)
+ * @param config - Account config (WorkclawConfig)
  * @param agentId - Target agent ID (optional)
  * @param pluginRuntime - OpenClaw plugin runtime (optional, enables full session handling)
  * @param recordSession - Whether to record session (default true)
- * @param log 日志对象（可选）
- * @param {Function} [log.info] - 信息日志函数
- * @param {Function} [log.error] - 错误日志函数
- * @param {Function} [log.warn] - 警告日志函数
+ * @param log - Optional logger
  */
 export async function buildInboundContext(
-  message: InboundMessage,
-  accountId: string,
-  config: any,
-  agentId?: string,
-  pluginRuntime?: PluginRuntime,
-  recordSession: boolean = true,
-  log?: { info?: (msg: string) => void, warn?: (msg: string) => void, error?: (msg: string) => void },
+    message: InboundMessage,
+    accountId: string,
+    config: any,
+    agentId?: string,
+    pluginRuntime?: PluginRuntime,
+    recordSession: boolean = true,
+    log?: { info?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void },
 ): Promise<InboundContextPayload> {
-  // 尝试从 rawPayload 中提取已有的 sessionKey（新建话题时 openclaw 会生成新的 session）
-  let existingSessionKey: string | undefined
-  try {
-    const rawPayload = JSON.parse(message.rawPayload)
-    existingSessionKey = rawPayload.sessionKey
-  }
-  catch {
-    // ignore
-  }
-
-  const peerId = message.from
-  const computedSessionKey = existingSessionKey
-    || (agentId && agentId !== 'main'
-      ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
-      : undefined)
-
-  const sessionKey = computedSessionKey || (agentId && agentId !== 'main'
-    ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
-    : undefined)
-
-  // Basic context (used as base for both paths)
-  const result: InboundContextPayload = {
-    Body: message.text,
-    BodyForAgent: message.rawPayload || message.text,
-    RawBody: JSON.stringify(message),
-    From: message.from,
-    To: message.to,
-    ChatType: message.chatType,
-    Provider: OPENCLAW_WORKCLAW_CHANNEL,
-    Surface: OPENCLAW_WORKCLAW_CHANNEL,
-    Timestamp: message.timestamp,
-    AccountId: accountId,
-    AgentId: agentId,
-    MessageSid: message.messageId,
-    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
-    OriginatingTo: message.to,
-  }
-
-  if (sessionKey) {
-    result.SessionKey = sessionKey
-  }
-
-  // If no pluginRuntime provided, return basic context without session recording
-  if (!pluginRuntime) {
-    return result
-  }
-
-  // Full session handling path
-  const storePath = pluginRuntime.channel.session.resolveStorePath(config.session?.store, { agentId })
-  log?.info?.(`[Session] storePath=${storePath}, agentId=${agentId}, sessionKey=${sessionKey}`)
-
-  // 获取 envelope 格式选项
-  const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(config)
-
-  // 获取上次的 session 更新时间
-  const previousTimestamp = pluginRuntime.channel.session.readSessionUpdatedAt({
-    storePath,
-    sessionKey: sessionKey!,
-  })
-  log?.info?.(`[Session] previousTimestamp=${previousTimestamp}`)
-
-  // 格式化 envelope（Body 用于日志/历史，BodyForAgent 用于 AI）
-  const fromLabel = message.to
-  const body = pluginRuntime.channel.reply.formatInboundEnvelope({
-    channel: OPENCLAW_WORKCLAW_CHANNEL,
-    from: fromLabel,
-    timestamp: message.timestamp,
-    body: message.text,
-    chatType: message.chatType,
-    sender: { name: message.to, id: message.to },
-    previousTimestamp,
-    envelope: envelopeOptions,
-  })
-
-  // 构建完整的 ctx
-  const finalized = pluginRuntime.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: message.text,
-    RawBody: JSON.stringify(message),
-    CommandBody: message.text,
-    From: message.from,
-    To: message.to,
-    SessionKey: sessionKey,
-    AccountId: accountId,
-    ChatType: message.chatType,
-    ConversationLabel: fromLabel,
-    Provider: OPENCLAW_WORKCLAW_CHANNEL,
-    Surface: 'openclaw-workclaw_dm',
-    MessageSid: message.messageId,
-    Timestamp: message.timestamp,
-    OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
-    OriginatingTo: message.to,
-  })
-
-  // 记录 session（需要在 dispatchReplyWithBufferedBlockDispatcher 之前调用）
-  // 这样 OpenClaw 才能在工具执行时正确关联 session
-  if (sessionKey && recordSession) {
+    // 尝试从 rawPayload 中提取已有的 sessionKey（新建话题时 openclaw 会生成新的 session）
+    let existingSessionKey: string | undefined;
     try {
-      await pluginRuntime.channel.session.recordInboundSession({
+        const rawPayload = JSON.parse(message.rawPayload);
+        existingSessionKey = rawPayload.sessionKey;
+    } catch {
+        // ignore
+    }
+
+    const peerId = message.from;
+    const computedSessionKey = existingSessionKey
+        || (agentId && agentId !== "main"
+            ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
+            : undefined);
+
+    const sessionKey = computedSessionKey || (agentId && agentId !== "main"
+        ? `agent:${agentId}:openclaw-workclaw:${accountId}:direct:${peerId}`
+        : undefined);
+
+    // Basic context (used as base for both paths)
+    // parseWorkClawMessage 已将 fileUrl 列表追加到 message.text 中
+    const result: InboundContextPayload = {
+        Body: message.text,
+        BodyForAgent: message.text,
+        RawBody: JSON.stringify(message),
+        From: message.from,
+        To: message.to,
+        ChatType: message.chatType,
+        Provider: OPENCLAW_WORKCLAW_CHANNEL,
+        Surface: OPENCLAW_WORKCLAW_CHANNEL,
+        Timestamp: message.timestamp,
+        AccountId: accountId,
+        AgentId: agentId,
+        MessageSid: message.messageId,
+        OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
+        OriginatingTo: message.to,
+    };
+
+    if (sessionKey) {
+        result.SessionKey = sessionKey;
+    }
+
+    // If no pluginRuntime provided, return basic context without session recording
+    if (!pluginRuntime) {
+        return result;
+    }
+
+    // Full session handling path
+    const storePath = pluginRuntime.channel.session.resolveStorePath(config.session?.store, { agentId });
+    log?.info?.(`[Session] storePath=${storePath}, agentId=${agentId}, sessionKey=${sessionKey}`);
+
+    // 获取 envelope 格式选项
+    const envelopeOptions = pluginRuntime.channel.reply.resolveEnvelopeFormatOptions(config);
+
+    // 获取上次的 session 更新时间
+    const previousTimestamp = pluginRuntime.channel.session.readSessionUpdatedAt({
         storePath,
-        sessionKey: finalized.SessionKey || sessionKey,
-        ctx: finalized,
-        updateLastRoute: {
-          sessionKey,
-          channel: OPENCLAW_WORKCLAW_CHANNEL,
-          to: message.to,
-          accountId,
-        },
-        onRecordError: (err: unknown) => {
-          log?.error?.(`[Session] recordInboundSession failed: ${String(err)}`)
-        },
-      })
-      log?.info?.(`[Session] Recorded session for key=${sessionKey}`)
+        sessionKey: sessionKey!,
+    });
+    log?.info?.(`[Session] previousTimestamp=${previousTimestamp}`);
+
+    // 处理附件：下载 fileUrl 到本地，并收集媒体信息
+    let mediaUrls: string[] = [];
+    let mediaTypes: string[] = [];
+    let bodyText = message.text;
+    if (message.attachments && message.attachments.length > 0) {
+        log?.info?.(`[Attachments] Downloading ${message.attachments.length} files...`);
+
+        // 并行下载所有附件
+        const downloadResults = await Promise.all(
+            message.attachments.map(async (att) => {
+                const localPath = await downloadFileToLocal(att.url, accountId, message.from, log);
+                const mediaType = detectMediaType(att.url);
+                const typeLabel = getMediaTypeLabel(att.url);
+                return { att, localPath, mediaType, typeLabel };
+            })
+        );
+
+        // 收集下载成功的文件信息（MediaUrls 由 SDK 用于显示 [media attached]）
+        for (const { att, localPath, mediaType } of downloadResults) {
+            if (localPath) {
+                // 将绝对路径转为根相对路径（去掉 ~/.openclaw/ 前缀，转为 /.openclaw/... 形式）
+                // OpenClaw 的 skill 系统会 block 绝对路径（C:\...）和 ~ 路径
+                // 兼容 Windows 路径格式（C:\Users\用户名\.openclaw\... 或 C:\Users\用户名.openclaw\...）
+                const homeDir = os.homedir().replace(/\\/g, '/').trim();  // 统一用正斜杠，去除尾随空格
+                const normalizedLocalPath = localPath.replace(/\\/g, '/');
+                const relativePath = normalizedLocalPath.startsWith(homeDir + '/.openclaw/')
+                    ? '/' + normalizedLocalPath.slice(homeDir.length + 1)  // 用 / 开头表示根相对路径
+                    : normalizedLocalPath;
+                mediaUrls.push(relativePath);
+                mediaTypes.push(mediaType);
+                log?.info?.(`[Attachments] Downloaded: ${relativePath}`);
+            } else {
+                log?.warn?.(`[Attachments] Failed to download: ${att.url}`);
+            }
+        }
+
+        log?.info?.(`[Attachments] Downloaded ${mediaUrls.length}/${message.attachments.length} files`);
     }
-    catch (err) {
-      log?.warn?.(`[Session] recordInboundSession error: ${String(err)}`)
+    const fromLabel = message.to;
+    const body = pluginRuntime.channel.reply.formatInboundEnvelope({
+        channel: OPENCLAW_WORKCLAW_CHANNEL,
+        from: fromLabel,
+        timestamp: message.timestamp,
+        body: bodyText,
+        chatType: message.chatType,
+        sender: { name: message.to, id: message.to },
+        previousTimestamp,
+        envelope: envelopeOptions,
+    });
+
+    // 构建完整的 ctx
+    const finalized = pluginRuntime.channel.reply.finalizeInboundContext({
+        Body: body,
+        BodyForAgent: bodyText,
+        RawBody: JSON.stringify(message),
+        CommandBody: message.text,
+        From: message.from,
+        To: message.to,
+        SessionKey: sessionKey,
+        AccountId: accountId,
+        ChatType: message.chatType,
+        ConversationLabel: fromLabel,
+        Provider: OPENCLAW_WORKCLAW_CHANNEL,
+        Surface: "openclaw-workclaw_dm",
+        MessageSid: message.messageId,
+        Timestamp: message.timestamp,
+        OriginatingChannel: OPENCLAW_WORKCLAW_CHANNEL,
+        OriginatingTo: message.to,
+        // 附件媒体信息（供 skill 读取本地文件）
+        MediaPath: mediaUrls[0] || undefined,
+        MediaUrl: mediaUrls[0] || undefined,
+        MediaUrls: mediaUrls.length > 0 ? mediaUrls : undefined,
+        MediaTypes: mediaTypes.length > 0 ? mediaTypes : undefined,
+    });
+
+    // 记录 session（需要在 dispatchReplyWithBufferedBlockDispatcher 之前调用）
+    // 这样 OpenClaw 才能在工具执行时正确关联 session
+    if (sessionKey && recordSession) {
+        try {
+            await pluginRuntime.channel.session.recordInboundSession({
+                storePath,
+                sessionKey: finalized.SessionKey || sessionKey,
+                ctx: finalized,
+                updateLastRoute: {
+                    sessionKey,
+                    channel: OPENCLAW_WORKCLAW_CHANNEL,
+                    to: message.to,
+                    accountId,
+                },
+                onRecordError: (err: unknown) => {
+                    log?.error?.(`[Session] recordInboundSession failed: ${String(err)}`);
+                },
+            });
+            log?.info?.(`[Session] Recorded session for key=${sessionKey}`);
+        } catch (err) {
+            log?.warn?.(`[Session] recordInboundSession error: ${String(err)}`);
+        }
     }
-  }
 
-  return finalized
+    return finalized;
 }
+