@xgjktech/xg_cwork_im 1.0.6 → 1.0.8

package/src/types.ts

@@ -1,206 +1,287 @@
-/**
- * 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";
-}
-
-export interface XgImConfig extends OpenClawConfig {
-    /** 多账户列表 */
-    accounts?: 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 回复超时时间（毫秒）。
-     *
-     * - 未配置时默认 5 分钟（300_000ms）。
-     * - 仅用于保护「思考中」占位消息，避免长时间不被更新。
-     */
-    firstReplyTimeoutMs?: number;
-}
-
-// ─── 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;
-}
-
-/** robotMention 消息的 params */
-export interface WsMessageParams {
-    msgId: string;
-    groupId: string;
-    /** 发送人信息 */
-    userInfo: {
-        /** 发送人 ID */
-        id: string;
-        /** 发送人显示名 */
-        name: string;
-        /**
-         * 用户背景信息。
-         * - 若非空，需要透传给 AI（可能是一段 JSON 字符串）。
-         */
-        background?: string;
-    };
-    msgContent: {
-        text: string;
-        type: string;
-        url?: string;
-        ext?: Record<string, any>;
-    };
-    /** 服务端可能返回 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;
-}
-
-export interface SendMessageBody {
-    type: "TEXT" | "RICH_TEXT" | "VOICE";
-    groupId?: string;
-    toUserId?: string;
-    text: string;
-    atUserIds?: string[];
-    /**
-     * 业务侧生成的消息 ID。
-     *
-     * - 若不传：服务端按普通“新消息”处理。
-     * - 若传入：服务端可根据 msgId 更新已有的流式占位消息内容。
-     */
-    msgId?: string;
-
-    /**
-     * 被回复消息信息。
-     *
-     * - 若不传：视为普通消息。
-     * - 若传入：服务端可按 targetMsgId 建立“回复某条消息”的关联。
-     */
-    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;
+}
+
+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;
+}
+
+// ─── 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;
+}
+
+/** @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** 可为配文（同时上传多文件 + 一句话）。
+ * - 语音在 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 };