@workclaw/openclaw-workclaw 1.0.18 → 1.0.20

package/{src/gateway/message-context.ts → dist/src/gateway/message-context.js}

@@ -1,594 +1,509 @@
-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 interface InboundMessage {
-    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;
-}
-
-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;
-        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,
-    };
-}
-
-export function parseWorkClawMessage(data: string, log?: {
-    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 (e) {
-                // 解析失败，保持原样
-            }
-        }
-
-        return {
-            type: "init_agent",
-            eventData: parsedData,
-        };
-    }
-
-    // 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",
-        };
-    }
-
-    // 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",
-        };
-    }
-
-    // Only process CALLBACK type with AGENT_MESSAGE topic
-    if (type !== "CALLBACK" || String(topic || "").trim().toUpperCase() !== "AGENT_MESSAGE") {
-        return {
-            type: "ignored",
-        };
-    }
-
-    // 解析 data 字段（可能是 JSON 字符串）
-    let payload = envelope?.data || {};
-    if (typeof payload === "string") {
-        try {
-            payload = JSON.parse(payload);
-        } catch (e) {
-            // 解析失败，保持原样
-        }
-    }
-
-    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));
-    }
-
-    // 解析 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',
-    }));
-
-    return {
-        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,
-        },
-    };
-}
-
-/**
- * 从 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";
-    }
-    if (lower.endsWith(".mp3") || lower.endsWith(".wav") || lower.endsWith(".amr")
-        || lower.endsWith(".m4a") || lower.endsWith(".ogg")) {
-        return "audio";
-    }
-    if (lower.endsWith(".mp4") || lower.endsWith(".avi") || lower.endsWith(".mov")
-        || lower.endsWith(".mkv") || lower.endsWith(".webm")) {
-        return "video";
-    }
-    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);
-        });
-    });
-}
-
-/**
- * Build inbound context for WorkClaw channel.
- *
- * When pluginRuntime is provided, performs full session handling:
- * - resolveStorePath, readSessionUpdatedAt, formatInboundEnvelope
- * - finalizeInboundContext, recordInboundSession
- *
- * @param message - The inbound message
- * @param accountId - Account ID
- * @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 - 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 },
-): 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)
-    // 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: 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`);
-    }
-    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;
-}
-
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import https from 'node:https';
+import os from 'node:os';
+import path from 'node:path';
+/** Channel/plugin name constant */
+export const OPENCLAW_WORKCLAW_CHANNEL = 'openclaw-workclaw';
+export function parseInboundMessage(data, allowRawJsonPayload) {
+    let input = {};
+    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, log) {
+    // {"specVersion":"1.0","type":"EVENT","metadata":{"time":"1773749163831","event":"INIT_AGENT","contentType":"application/json"},"data":"\"12557533957824965\""}
+    let input = {};
+    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 (e) {
+                // 解析失败，保持原样
+            }
+        }
+        return {
+            type: 'init_agent',
+            eventData: parsedData,
+        };
+    }
+    // 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',
+        };
+    }
+    // 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,
+                },
+            };
+        }
+        if (eventType === 'CRON_REMIND') {
+            const eventTopic = String(parsedData?.dotype || '').toLowerCase();
+            return {
+                type: 'cron_task_event',
+                cronTaskEvent: {
+                    dotype: `${eventTopic}`,
+                    data: parsedData,
+                },
+            };
+        }
+        // Unknown event type, ignore
+        return {
+            type: 'ignored',
+        };
+    }
+    // Only process CALLBACK type with AGENT_MESSAGE topic
+    if (type !== 'CALLBACK' || String(topic || '').trim().toUpperCase() !== 'AGENT_MESSAGE') {
+        return {
+            type: 'ignored',
+        };
+    }
+    // 解析 data 字段（可能是 JSON 字符串）
+    let payload = envelope?.data || {};
+    if (typeof payload === 'string') {
+        try {
+            payload = JSON.parse(payload);
+        }
+        catch (e) {
+            // 解析失败，保持原样
+        }
+    }
+    const text = typeof payload?.message?.content === 'string'
+        ? payload.message.content
+        : typeof payload?.message === 'string'
+            ? payload.message
+            : '';
+    // 判断文件是否为图片
+    function isImageFile(url) {
+        const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.svg', '.ico'];
+        const lowerUrl = url.toLowerCase();
+        return imageExtensions.some(ext => lowerUrl.endsWith(ext));
+    }
+    // 解析 fileUrl 列表到 attachments（供 SDK 和 AI 使用）
+    const fileUrlList = Array.isArray(payload?.fileUrl) ? payload.fileUrl : [];
+    const attachments = fileUrlList.map(url => ({
+        url,
+        fileId: payload?.fileId ? String(payload.fileId) : '',
+        type: isImageFile(url) ? 'image' : 'file',
+    }));
+    return {
+        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,
+        },
+    };
+}
+/**
+ * 从 URL 扩展名判断媒体类型
+ */
+function detectMediaType(url) {
+    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';
+    }
+    if (lower.endsWith('.mp3') || lower.endsWith('.wav') || lower.endsWith('.amr')
+        || lower.endsWith('.m4a') || lower.endsWith('.ogg')) {
+        return 'audio';
+    }
+    if (lower.endsWith('.mp4') || lower.endsWith('.avi') || lower.endsWith('.mov')
+        || lower.endsWith('.mkv') || lower.endsWith('.webm')) {
+        return 'video';
+    }
+    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) {
+    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, accountId, peerId, log) {
+    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 = [];
+            res.on('data', (chunk) => 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);
+        });
+    });
+}
+/**
+ * Build inbound context for WorkClaw channel.
+ *
+ * When pluginRuntime is provided, performs full session handling:
+ * - resolveStorePath, readSessionUpdatedAt, formatInboundEnvelope
+ * - finalizeInboundContext, recordInboundSession
+ *
+ * @param message - The inbound message
+ * @param accountId - Account ID
+ * @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 - Optional logger
+ */
+export async function buildInboundContext(message, accountId, config, agentId, pluginRuntime, recordSession = true, log) {
+    // 尝试从 rawPayload 中提取已有的 sessionKey（新建话题时 openclaw 会生成新的 session）
+    let existingSessionKey;
+    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)
+    // parseWorkClawMessage 已将 fileUrl 列表追加到 message.text 中
+    const result = {
+        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: sessionKey,
+    });
+    log?.info?.(`[Session] previousTimestamp=${previousTimestamp}`);
+    // 处理附件：下载 fileUrl 到本地，并收集媒体信息
+    let mediaUrls = [];
+    let mediaTypes = [];
+    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`);
+    }
+    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) => {
+                    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;
+}