@xgjktech/xg_cwork_im 1.0.9 → 1.10.0

package/README.md

@@ -232,7 +232,8 @@ openclaw gateway restart
 | `maxReconnectDelay` | number | `60000` | 最大重连延迟（ms） |
 | `reconnectJitter` | number | `0.3` | 重连抖动因子（0-1） |
 | `firstReplyTimeoutMs` | number | `300000` | **首条 AI 回复超时时间（毫秒）**。用于保护「思考中」占位消息：若在该时间窗口内 AI 没有任何回复，则自动将占位消息更新为「当前请求处理超时，请稍后重试」。|
-| `inboundMediaWorkspaceSubdir` | string | — | **可选**。非空时，将入站附件先下载到**当前 Agent workspace** 下该**相对子目录**（如 `xg_im_inbound`），路径约定：`{子目录}/{发送者 userId}/{YYYY-MM-DD}/{文件名}_{HHmmssmmm}.ext`（时间为本机写入时刻），再向 OpenClaw 传入本地 `file://` 路径；未配置则仍使用 IM 返回的 URL。需 OpenClaw runtime 提供 `resolveAgentWorkspaceDir`。 |
+| `inboundMediaWorkspaceSubdir` | string | — | **可选**。非空时，将入站附件先下载到**当前 Agent workspace** 下该**相对子目录**（如 `xg_im_inbound`），路径约定：`{子目录}/{发送者 userId}/{YYYY-MM-DD}/{文件名}_{HHmmssmmm}.ext`（时间为本机写入时刻），再向 OpenClaw 传入 **MediaPath**；默认使用 **workspace 相对路径**（如 `./xg_im_inbound/...`），便于 **沙箱** 将 `/workspace` 映射到同一套目录树；未配置则仍使用 IM 返回的 URL。需 runtime 提供 `resolveAgentWorkspaceDir`。 |
+| `inboundMediaOpenClawPath` | string | `workspaceRelative`（默认） | `workspaceRelative`：入站落盘后 `MediaPath` 为 `./子目录/...`；`absoluteFileUrl`：宿主机 `file://...`（仅适合无沙箱、网关与 Agent 同盘场景）。 |
 
 ### 账户配置（`accounts.<accountId>` / `accounts[n]`）
 
@@ -243,6 +244,7 @@ openclaw gateway restart
 | `name` | string | — | 账户显示名称（仅用于日志标识） |
 | `groupPolicy` | string | 继承顶层 | 可覆盖顶层的 groupPolicy |
 | `inboundMediaWorkspaceSubdir` | string | 继承顶层 | 可覆盖顶层的入站附件落盘子目录 |
+| `inboundMediaOpenClawPath` | string | 继承顶层 | 可覆盖顶层的 MediaPath 形式（相对路径 vs file://） |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgjktech/xg_cwork_im",
-  "version": "1.0.9",
+  "version": "1.10.0",
   "description": "XG CWork IM channel plugin for OpenClaw",
   "keywords": [
     "bot",

package/src/channel.ts

@@ -55,6 +55,7 @@ const XgImAccountConfigSchema = z.object({
     fileUploadFormField: z.string().min(1).optional(),
     maxAttachmentBytes: z.number().int().positive().optional(),
     inboundMediaWorkspaceSubdir: z.string().optional(),
+    inboundMediaOpenClawPath: z.enum(["workspaceRelative", "absoluteFileUrl"]).optional(),
 });
 
 const XgImConfigSchema = z.object({
@@ -75,9 +76,10 @@ const XgImConfigSchema = z.object({
     maxAttachmentBytes: z.number().int().positive().optional(),
     /**
      * 非空时：将入站附件下载到 `resolveAgentWorkspaceDir(cfg)` 下该相对子目录，
-     * 再向 OpenClaw 传本地 file:// 路径（见 inbound-media-local）。
+     * 再向 OpenClaw 传 workspace 相对路径或 file://（见 inboundMediaOpenClawPath、inbound-media-local）。
      */
     inboundMediaWorkspaceSubdir: z.string().optional(),
+    inboundMediaOpenClawPath: z.enum(["workspaceRelative", "absoluteFileUrl"]).optional(),
     // 多账户：对象 map（key 为 accountId）
     accounts: z.record(z.string(), XgImAccountConfigSchema).optional(),
 }).superRefine((val, ctx) => {

package/src/inbound-media-local.ts

@@ -84,6 +84,38 @@ function sanitizeStem(stem: string): string {
     return out.length > MAX_STEM_LEN ? out.slice(0, MAX_STEM_LEN) : out;
 }
 
+/**
+ * 将落盘绝对路径转为 OpenClaw / 沙箱可用的 workspace 相对引用（POSIX 风格，带 `./` 前缀）。
+ * 若文件不在 workspaceRoot 之下则返回 null（调用方应回退 file:// 或报错）。
+ */
+export function absPathToWorkspaceRelativeOpenClawRef(workspaceRoot: string, absPath: string): string | null {
+    const root = path.resolve(workspaceRoot.trim());
+    const abs = path.resolve(absPath);
+    const rel = path.relative(root, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+    const piece = rel.length > 0 ? rel : path.basename(abs);
+    const posix = piece.split(path.sep).join("/");
+    return posix.startsWith("./") ? posix : `./${posix}`;
+}
+
+function openClawMediaRefForSavedFile(args: {
+    workspaceRoot: string;
+    absPath: string;
+    style: "workspaceRelative" | "absoluteFileUrl" | undefined;
+    log?: Log;
+}): string {
+    const { workspaceRoot, absPath, style, log } = args;
+    if (style === "absoluteFileUrl") {
+        return pathToFileURL(absPath).href;
+    }
+    const rel = absPathToWorkspaceRelativeOpenClawRef(workspaceRoot, absPath);
+    if (rel) return rel;
+    log?.warn?.(
+        `[cwork_im:inbound-local] file not under workspace root, fallback to file:// absPath=${absPath.slice(0, 120)}`,
+    );
+    return pathToFileURL(absPath).href;
+}
+
 /** `report_120459237.pdf` */
 export function buildInboundStoredFilename(originalFilename: string, at: Date): string {
     const base = path.basename(originalFilename) || "file";
@@ -140,11 +172,19 @@ export async function saveInboundFilesToWorkspace(args: {
             await mkdir(dir, { recursive: true });
             const { buffer } = await downloadMediaBuffer(srcUrl, maxBytes, log);
             await writeFile(absPath, buffer);
-            const fileUrl = pathToFileURL(absPath).href;
-            log?.info?.(`[cwork_im:inbound-local] saved ${localName} bytes=${buffer.length} -> ${absPath}`);
+            const pathStyle = config.inboundMediaOpenClawPath ?? "workspaceRelative";
+            const mediaRef = openClawMediaRefForSavedFile({
+                workspaceRoot,
+                absPath,
+                style: pathStyle,
+                log,
+            });
+            log?.info?.(
+                `[cwork_im:inbound-local] saved ${localName} bytes=${buffer.length} abs=${absPath} openclawRef=${mediaRef.slice(0, 120)}`,
+            );
             out.push({
                 ...item,
-                url: fileUrl,
+                url: mediaRef,
                 size: buffer.length,
                 name: localName,
             });

package/src/types.ts

@@ -1,301 +1,312 @@
-/**
- * XG-IM Channel Plugin — 类型定义
- */
-
-import type {
-    OpenClawConfig,
-    OpenClawPluginApi,
-    ChannelLogSink as SDKChannelLogSink,
-    ChannelAccountSnapshot as SDKChannelAccountSnapshot,
-    ChannelGatewayContext as SDKChannelGatewayContext,
-    ChannelPlugin as SDKChannelPlugin,
-    PluginRuntime,
-} from "openclaw/plugin-sdk";
-
-// ─── 插件模块 ───────────────────────────────────────────────────────────────
-
-export interface XgImPluginModule {
-    id: string;
-    name: string;
-    description?: string;
-    configSchema?: unknown;
-    register?: (api: OpenClawPluginApi) => void | Promise<void>;
-}
-
-/** 与 openclaw.plugin.json 中 id: xg_cwork_im 对应 */
-export type XgCworkImPluginModule = XgImPluginModule;
-
-// ─── Channel 配置 ────────────────────────────────────────────────────────────
-
-/** 单个机器人账户配置 */
-export interface XgImAccountConfig {
-    /** 机器人 appKey，从 IM 后台注册获取 */
-    appKey?: string;
-    /** 对应 OpenClaw 的 Agent ID，默认为 'main' */
-    agentId?: string;
-    /** 账户显示名称 */
-    name?: string;
-    /** 群聊策略：open = 不需要 @，mention = 必须 @ 机器人才触发 */
-    groupPolicy?: "open" | "mention";
-    /** multipart 整文件上传字段名，默认 file（与 `/file/upDownload/uploadWholeFile` 约定一致时可不改） */
-    fileUploadFormField?: string;
-    maxAttachmentBytes?: number;
-    /** 覆盖顶层的入站附件 workspace 子目录（相对 Agent workspace） */
-    inboundMediaWorkspaceSubdir?: string;
-}
-
-export interface XgImConfig extends OpenClawConfig {
-    /** 多账户列表 */
-    accounts?: Record<string, XgImAccountConfig>;
-
-    /** 机器人 appKey（单账户模式） */
-    appKey?: string;
-    /** 对应 OpenClaw 的 Agent ID（单账户模式） */
-    agentId?: string;
-    /** IM 服务域名，如 https://test.xgjktech.com.cn */
-    baseUrl: string;
-    /** WebSocket 服务域名，如 wss://test.xgjktech.com.cn */
-    wsBaseUrl?: string;
-    /** 是否启用 */
-    enabled?: boolean;
-    /** 账户显示名称（单账户模式使用） */
-    name?: string;
-    /** 群聊策略：open = 不需要 @，mention = 必须 @ 机器人才触发 */
-    groupPolicy?: "open" | "mention";
-    /** 允许的发送者 userId 白名单（空表示全部允许） */
-    allowFrom?: string[];
-    /** 是否开启调试日志 */
-    debug?: boolean;
-    /** 最大重连次数（默认 10） */
-    maxConnectionAttempts?: number;
-    /** 初始重连延迟 ms（默认 1000） */
-    initialReconnectDelay?: number;
-    /** 最大重连延迟 ms（默认 60000） */
-    maxReconnectDelay?: number;
-    /** 重连延迟抖动因子 0-1（默认 0.3） */
-    reconnectJitter?: number;
-    /**
-     * 首次 AI 回复超时时间（毫秒）。
-     *
-     * - 未配置时默认 30 分钟（1800_000ms）。
-     * - 仅用于保护「思考中」占位消息，避免长时间不被更新。
-     */
-    firstReplyTimeoutMs?: number;
-
-    /**
-     * 附件上传地址固定为 `{baseUrl}/file/upDownload/uploadWholeFile`，请求头 `access-token` 与发 IM 相同。
-     * multipart 字段名默认 `file`，可通过 fileUploadFormField 覆盖。
-     */
-    fileUploadFormField?: string;
-    /** 单个附件下载/上传允许的最大字节数，默认 50MB */
-    maxAttachmentBytes?: number;
-
-    /**
-     * 若配置为非空相对路径（相对于当前 Agent workspace 根目录）：入站附件会先下载到
-     * `{workspace}/{本字段}/{userId}/{YYYY-MM-DD}/{name}_{HHmmssmmm}.ext`，再向 OpenClaw 传入本地 `file://` 路径。
-     * 未配置或为空则仍使用 IM 返回的远程 URL。
-     */
-    inboundMediaWorkspaceSubdir?: string;
-}
-
-// ─── IM 接口 Request / Response ─────────────────────────────────────────────
-
-/** GET /user/login/appkey 的响应 */
-export interface GetTokenResponse {
-    data?: {
-        xgToken: string;
-        empId: string;
-        userName?: string;
-        avatar?: string;
-        corpId?: string;
-        deptList?: unknown[];
-        appCode?: string;
-        telephone?: string;
-        personId?: string;
-    };
-    resultCode?: number;
-    resultMsg?: string | null;
-}
-
-/** 机器人身份信息（认证成功后缓存） */
-export interface BotIdentity {
-    token: string;
-    userId: string;
-    name: string;
-}
-
-// ─── WebSocket 消息 ──────────────────────────────────────────────────────────
-
-/** WebSocket 消息通知（cmd = robotMention） */
-export interface WsMessage {
-    cmd: string;
-    params: WsMessageParams;
-    ts: number;
-}
-
-/**
- * 与 IM 服务 `MsgFileVO` 对齐的附件项（WebSocket `msgContent.files[]`）。
- */
-export interface MsgFileVO {
-    /** 文件下载链接，短期有效 */
-    url: string;
-    /** 文件格式，小写：pdf、png、docx、doc、ppt、txt、md 等 */
-    format?: string;
-    /** 文件 ID；若来自七牛等无业务 id 的场景可为空 */
-    fileId?: string;
-    /** 文件大小（字节） */
-    size?: number;
-    /** 文件名称，如 xxx.pdf */
-    name?: string;
-    /**
-     * IM 侧已解析的正文（如图片 OCR/说明、文档抽取的文本等）。
-     * 非空时插件会拼入入站 `Body`/`RawBody`，一并交给 OpenClaw。
-     */
-    content?: string;
-}
-
-/** @deprecated 使用 {@link MsgFileVO} */
-export type WsInboundFileItem = MsgFileVO;
-
-/** 常见 IM format → MIME，供 OpenClaw 媒体理解；未知格式返回 undefined */
-export function imFormatToMimeType(format: string | undefined): string | undefined {
-    const f = format?.trim().toLowerCase();
-    if (!f) return undefined;
-    const map: Record<string, string> = {
-        pdf: "application/pdf",
-        png: "image/png",
-        jpg: "image/jpeg",
-        jpeg: "image/jpeg",
-        gif: "image/gif",
-        webp: "image/webp",
-        doc: "application/msword",
-        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-        ppt: "application/vnd.ms-powerpoint",
-        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-        xls: "application/vnd.ms-excel",
-        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-        txt: "text/plain",
-        md: "text/markdown",
-        csv: "text/csv",
-        zip: "application/zip",
-        mp3: "audio/mpeg",
-        wav: "audio/wav",
-        mp4: "video/mp4",
-    };
-    return map[f];
-}
-
-/**
- * 入站消息内容体（与 IM WebSocket `params.msgContent` 对齐）。
- *
- * - **type=`text`**：纯文本；**text** 建议非空。
- * - **type=`file`**：带 1..N 个文件，**files** 建议至少 1 项；**text** 可为配文（同时上传多文件 + 一句话）。**files[].content** 可由 IM 填已解析文本（如图/文档），插件会拼入入站正文。
- * - 语音在 IM 侧已转写为文字时，应以 **type=`text`** 推送转写结果，不再使用 voice。
- */
-export interface WsMessageContent {
-    /** 文本正文；纯文本消息为主内容；file 消息上为可选配文 */
-    text?: string;
-    /** `text` | `file`（可扩展其它枚举，插件对未知类型按文本兜底） */
-    type: string;
-    /** 多附件；type 为 file 时由 IM 填至少一项 */
-    files?: MsgFileVO[];
-    ext?: Record<string, any>;
-}
-
-/** robotMention 消息的 params */
-export interface WsMessageParams {
-    msgId: string;
-    groupId: string;
-    /** 发送人信息 */
-    userInfo: {
-        /** 发送人 ID */
-        id: string;
-        /** 发送人显示名 */
-        name: string;
-        /**
-         * 用户背景信息。
-         * - 若非空，需要透传给 AI（可能是一段 JSON 字符串）。
-         */
-        background?: string;
-    };
-    msgContent: WsMessageContent;
-    /** 服务端可能返回 msgSendTime 或 timestamp */
-    msgSendTime?: number;
-    timestamp?: number;
-    /** 被 @ 的人员 ID 列表 */
-    mentions?: string[] | null;
-}
-
-// ─── IM 发送消息 ─────────────────────────────────────────────────────────────
-
-/** POST /im/message/send 请求体 */
-export interface SendMessageReply {
-    /** 被回复消息ID */
-    targetMsgId: string;
-    /** 被回复消息发送者ID */
-    targetUserId: string;
-    /** 被回复消息发送者显示名 */
-    targetUserName: string;
-    /** 被回复消息摘要 */
-    previewText: string;
-}
-
-/** IM 发送 FILE 类型消息时的附件项（与发消息接口约定一致） */
-export interface SendMessageFileAttachment {
-    fileId: string;
-    /** 固定为 FILE */
-    fileType: "FILE";
-    /** 小写扩展名，如 md、pdf */
-    format: string;
-    name: string;
-    size: number;
-    /** 固定为 resource */
-    source: "resource";
-}
-
-export type SendMessageBody =
-    | {
-          type: "TEXT" | "RICH_TEXT" | "VOICE";
-          groupId?: string;
-          toUserId?: string;
-          text: string;
-          atUserIds?: string[];
-          msgId?: string;
-          reply?: SendMessageReply;
-      }
-    | {
-          type: "FILE";
-          groupId?: string;
-          toUserId?: string;
-          text: string;
-          attachments: SendMessageFileAttachment[];
-          atUserIds?: string[];
-          msgId?: string;
-          reply?: SendMessageReply;
-      };
-
-/** GET /im/message/getLatestMsgListForAI 响应 */
-export interface GetLatestMsgListResponse {
-    data?: WsMessageParams[];
-    resultCode?: number;
-    message?: string;
-}
-
-// ─── OpenClaw 插件 SDK 类型别名 ───────────────────────────────────────────────
-
-export type ChannelLogSink = SDKChannelLogSink;
-export type ChannelAccountSnapshot = SDKChannelAccountSnapshot;
-
-export interface ResolvedAccount {
-    accountId: string;
-    config: XgImConfig;
-    enabled: boolean;
-    configured: boolean;
-    name?: string | null;
-}
-
-export type GatewayStartContext = SDKChannelGatewayContext<ResolvedAccount>;
-export type XgImChannelPlugin = SDKChannelPlugin<ResolvedAccount & { configured: boolean }>;
-
-/** PluginRuntime 的类型（内部 API 丰富，用 any 表示） */
-export type { PluginRuntime };
+/**
+ * XG-IM Channel Plugin — 类型定义
+ */
+
+import type {
+    OpenClawConfig,
+    OpenClawPluginApi,
+    ChannelLogSink as SDKChannelLogSink,
+    ChannelAccountSnapshot as SDKChannelAccountSnapshot,
+    ChannelGatewayContext as SDKChannelGatewayContext,
+    ChannelPlugin as SDKChannelPlugin,
+    PluginRuntime,
+} from "openclaw/plugin-sdk";
+
+// ─── 插件模块 ───────────────────────────────────────────────────────────────
+
+export interface XgImPluginModule {
+    id: string;
+    name: string;
+    description?: string;
+    configSchema?: unknown;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+}
+
+/** 与 openclaw.plugin.json 中 id: xg_cwork_im 对应 */
+export type XgCworkImPluginModule = XgImPluginModule;
+
+// ─── Channel 配置 ────────────────────────────────────────────────────────────
+
+/** 单个机器人账户配置 */
+export interface XgImAccountConfig {
+    /** 机器人 appKey，从 IM 后台注册获取 */
+    appKey?: string;
+    /** 对应 OpenClaw 的 Agent ID，默认为 'main' */
+    agentId?: string;
+    /** 账户显示名称 */
+    name?: string;
+    /** 群聊策略：open = 不需要 @，mention = 必须 @ 机器人才触发 */
+    groupPolicy?: "open" | "mention";
+    /** multipart 整文件上传字段名，默认 file（与 `/file/upDownload/uploadWholeFile` 约定一致时可不改） */
+    fileUploadFormField?: string;
+    maxAttachmentBytes?: number;
+    /** 覆盖顶层的入站附件 workspace 子目录（相对 Agent workspace） */
+    inboundMediaWorkspaceSubdir?: string;
+    /**
+     * 覆盖顶层：入站落盘后交给 OpenClaw 的 `MediaPath` 形式。
+     * - `workspaceRelative`（默认）：`./xg_im_inbound/...`，沙箱内 `/workspace` 可解析。
+     * - `absoluteFileUrl`：宿主机 `file://...`，仅适合无沙箱、同进程读盘场景。
+     */
+    inboundMediaOpenClawPath?: "workspaceRelative" | "absoluteFileUrl";
+}
+
+export interface XgImConfig extends OpenClawConfig {
+    /** 多账户列表 */
+    accounts?: Record<string, XgImAccountConfig>;
+
+    /** 机器人 appKey（单账户模式） */
+    appKey?: string;
+    /** 对应 OpenClaw 的 Agent ID（单账户模式） */
+    agentId?: string;
+    /** IM 服务域名，如 https://test.xgjktech.com.cn */
+    baseUrl: string;
+    /** WebSocket 服务域名，如 wss://test.xgjktech.com.cn */
+    wsBaseUrl?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 账户显示名称（单账户模式使用） */
+    name?: string;
+    /** 群聊策略：open = 不需要 @，mention = 必须 @ 机器人才触发 */
+    groupPolicy?: "open" | "mention";
+    /** 允许的发送者 userId 白名单（空表示全部允许） */
+    allowFrom?: string[];
+    /** 是否开启调试日志 */
+    debug?: boolean;
+    /** 最大重连次数（默认 10） */
+    maxConnectionAttempts?: number;
+    /** 初始重连延迟 ms（默认 1000） */
+    initialReconnectDelay?: number;
+    /** 最大重连延迟 ms（默认 60000） */
+    maxReconnectDelay?: number;
+    /** 重连延迟抖动因子 0-1（默认 0.3） */
+    reconnectJitter?: number;
+    /**
+     * 首次 AI 回复超时时间（毫秒）。
+     *
+     * - 未配置时默认 30 分钟（1800_000ms）。
+     * - 仅用于保护「思考中」占位消息，避免长时间不被更新。
+     */
+    firstReplyTimeoutMs?: number;
+
+    /**
+     * 附件上传地址固定为 `{baseUrl}/file/upDownload/uploadWholeFile`，请求头 `access-token` 与发 IM 相同。
+     * multipart 字段名默认 `file`，可通过 fileUploadFormField 覆盖。
+     */
+    fileUploadFormField?: string;
+    /** 单个附件下载/上传允许的最大字节数，默认 50MB */
+    maxAttachmentBytes?: number;
+
+    /**
+     * 若配置为非空相对路径（相对于当前 Agent workspace 根目录）：入站附件会先下载到
+     * `{workspace}/{本字段}/{userId}/{YYYY-MM-DD}/{name}_{HHmmssmmm}.ext`，再向 OpenClaw 传入 **workspace 相对路径**（默认 `./子目录/...`，便于沙箱挂载 `/workspace`）或 `file://`（见 `inboundMediaOpenClawPath`）。
+     * 未配置或为空则仍使用 IM 返回的远程 URL。
+     */
+    inboundMediaWorkspaceSubdir?: string;
+    /**
+     * 入站落盘后写入 `MediaPath` 的引用形式；默认与 `workspaceRelative` 等价（未填时）。
+     * Agent 在沙箱中运行时应用 `workspaceRelative`，避免宿主机绝对 `file://` 在沙箱内不可读。
+     */
+    inboundMediaOpenClawPath?: "workspaceRelative" | "absoluteFileUrl";
+}
+
+// ─── IM 接口 Request / Response ─────────────────────────────────────────────
+
+/** GET /user/login/appkey 的响应 */
+export interface GetTokenResponse {
+    data?: {
+        xgToken: string;
+        empId: string;
+        userName?: string;
+        avatar?: string;
+        corpId?: string;
+        deptList?: unknown[];
+        appCode?: string;
+        telephone?: string;
+        personId?: string;
+    };
+    resultCode?: number;
+    resultMsg?: string | null;
+}
+
+/** 机器人身份信息（认证成功后缓存） */
+export interface BotIdentity {
+    token: string;
+    userId: string;
+    name: string;
+}
+
+// ─── WebSocket 消息 ──────────────────────────────────────────────────────────
+
+/** WebSocket 消息通知（cmd = robotMention） */
+export interface WsMessage {
+    cmd: string;
+    params: WsMessageParams;
+    ts: number;
+}
+
+/**
+ * 与 IM 服务 `MsgFileVO` 对齐的附件项（WebSocket `msgContent.files[]`）。
+ */
+export interface MsgFileVO {
+    /** 远程下载链接，或入站落盘后的 `file://` / workspace 相对引用（如 `./xg_im_inbound/...`） */
+    url: string;
+    /** 文件格式，小写：pdf、png、docx、doc、ppt、txt、md 等 */
+    format?: string;
+    /** 文件 ID；若来自七牛等无业务 id 的场景可为空 */
+    fileId?: string;
+    /** 文件大小（字节） */
+    size?: number;
+    /** 文件名称，如 xxx.pdf */
+    name?: string;
+    /**
+     * IM 侧已解析的正文（如图片 OCR/说明、文档抽取的文本等）。
+     * 非空时插件会拼入入站 `Body`/`RawBody`，一并交给 OpenClaw。
+     */
+    content?: string;
+}
+
+/** @deprecated 使用 {@link MsgFileVO} */
+export type WsInboundFileItem = MsgFileVO;
+
+/** 常见 IM format → MIME，供 OpenClaw 媒体理解；未知格式返回 undefined */
+export function imFormatToMimeType(format: string | undefined): string | undefined {
+    const f = format?.trim().toLowerCase();
+    if (!f) return undefined;
+    const map: Record<string, string> = {
+        pdf: "application/pdf",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        doc: "application/msword",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ppt: "application/vnd.ms-powerpoint",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        xls: "application/vnd.ms-excel",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        zip: "application/zip",
+        mp3: "audio/mpeg",
+        wav: "audio/wav",
+        mp4: "video/mp4",
+    };
+    return map[f];
+}
+
+/**
+ * 入站消息内容体（与 IM WebSocket `params.msgContent` 对齐）。
+ *
+ * - **type=`text`**：纯文本；**text** 建议非空。
+ * - **type=`file`**：带 1..N 个文件，**files** 建议至少 1 项；**text** 可为配文（同时上传多文件 + 一句话）。**files[].content** 可由 IM 填已解析文本（如图/文档），插件会拼入入站正文。
+ * - 语音在 IM 侧已转写为文字时，应以 **type=`text`** 推送转写结果，不再使用 voice。
+ */
+export interface WsMessageContent {
+    /** 文本正文；纯文本消息为主内容；file 消息上为可选配文 */
+    text?: string;
+    /** `text` | `file`（可扩展其它枚举，插件对未知类型按文本兜底） */
+    type: string;
+    /** 多附件；type 为 file 时由 IM 填至少一项 */
+    files?: MsgFileVO[];
+    ext?: Record<string, any>;
+}
+
+/** robotMention 消息的 params */
+export interface WsMessageParams {
+    msgId: string;
+    groupId: string;
+    /** 发送人信息 */
+    userInfo: {
+        /** 发送人 ID */
+        id: string;
+        /** 发送人显示名 */
+        name: string;
+        /**
+         * 用户背景信息。
+         * - 若非空，需要透传给 AI（可能是一段 JSON 字符串）。
+         */
+        background?: string;
+    };
+    msgContent: WsMessageContent;
+    /** 服务端可能返回 msgSendTime 或 timestamp */
+    msgSendTime?: number;
+    timestamp?: number;
+    /** 被 @ 的人员 ID 列表 */
+    mentions?: string[] | null;
+}
+
+// ─── IM 发送消息 ─────────────────────────────────────────────────────────────
+
+/** POST /im/message/send 请求体 */
+export interface SendMessageReply {
+    /** 被回复消息ID */
+    targetMsgId: string;
+    /** 被回复消息发送者ID */
+    targetUserId: string;
+    /** 被回复消息发送者显示名 */
+    targetUserName: string;
+    /** 被回复消息摘要 */
+    previewText: string;
+}
+
+/** IM 发送 FILE 类型消息时的附件项（与发消息接口约定一致） */
+export interface SendMessageFileAttachment {
+    fileId: string;
+    /** 固定为 FILE */
+    fileType: "FILE";
+    /** 小写扩展名，如 md、pdf */
+    format: string;
+    name: string;
+    size: number;
+    /** 固定为 resource */
+    source: "resource";
+}
+
+export type SendMessageBody =
+    | {
+          type: "TEXT" | "RICH_TEXT" | "VOICE";
+          groupId?: string;
+          toUserId?: string;
+          text: string;
+          atUserIds?: string[];
+          msgId?: string;
+          reply?: SendMessageReply;
+      }
+    | {
+          type: "FILE";
+          groupId?: string;
+          toUserId?: string;
+          text: string;
+          attachments: SendMessageFileAttachment[];
+          atUserIds?: string[];
+          msgId?: string;
+          reply?: SendMessageReply;
+      };
+
+/** GET /im/message/getLatestMsgListForAI 响应 */
+export interface GetLatestMsgListResponse {
+    data?: WsMessageParams[];
+    resultCode?: number;
+    message?: string;
+}
+
+// ─── OpenClaw 插件 SDK 类型别名 ───────────────────────────────────────────────
+
+export type ChannelLogSink = SDKChannelLogSink;
+export type ChannelAccountSnapshot = SDKChannelAccountSnapshot;
+
+export interface ResolvedAccount {
+    accountId: string;
+    config: XgImConfig;
+    enabled: boolean;
+    configured: boolean;
+    name?: string | null;
+}
+
+export type GatewayStartContext = SDKChannelGatewayContext<ResolvedAccount>;
+export type XgImChannelPlugin = SDKChannelPlugin<ResolvedAccount & { configured: boolean }>;
+
+/** PluginRuntime 的类型（内部 API 丰富，用 any 表示） */
+export type { PluginRuntime };