@xgjktech/xg_cwork_im 1.0.0 → 1.0.3

package/src/channel.ts

@@ -1,471 +1,536 @@
-/**
- * XG-IM Channel Plugin — 核心定义
- *
- * 遵循 OpenClaw Channel Plugin 架构（参考 openclaw-channel-dingtalk）：
- * - config   : 账户解析
- * - outbound : AI 回复发送
- * - gateway  : 启动 WebSocket 长连接，接收 robotMention 消息后通过
- *              PluginRuntime 路由给 OpenClaw 处理
- */
-
-import { randomUUID } from "node:crypto";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
-import { z } from "zod";
-import { clearTokenCache, getToken } from "./auth.js";
-import { startWebSocket } from "./connection.js";
-import { sendTextMessage } from "./send-service.js";
-import type {
-    GatewayStartContext,
-    PluginRuntime,
-    ResolvedAccount,
-    WsMessage,
-    WsMessageParams,
-    XgImChannelPlugin,
-    XgImConfig,
-} from "./types.js";
-
-// ─── 全局 Runtime（在 index.ts 的 register 中注入）────────────────────────────
-
-let xgImRuntime: PluginRuntime | null = null;
-
-export function setXgImRuntime(rt: PluginRuntime): void {
-    xgImRuntime = rt;
-}
-
-function getXgImRuntime(): PluginRuntime {
-    if (!xgImRuntime) throw new Error("[cwork_im] Plugin runtime not initialized");
-    return xgImRuntime;
-}
-
-// ─── 配置 Schema ──────────────────────────────────────────────────────────────
-
-const XgImAccountConfigSchema = z.object({
-    appKey: z.string().min(1, "appKey is required"),
-    agentId: z.string().optional().default("main"),
-    name: z.string().optional(),
-    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
-});
-
-const XgImConfigSchema = z.object({
-    appKey: z.string().optional(),
-    agentId: z.string().optional().default("main"),
-    baseUrl: z.string().url("baseUrl must be a valid URL"),
-    wsBaseUrl: z.string().url("wsBaseUrl must be a valid URL").optional(),
-    enabled: z.boolean().optional().default(true),
-    name: z.string().optional(),
-    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
-    allowFrom: z.array(z.string()).optional().default([]),
-    debug: z.boolean().optional().default(false),
-    maxConnectionAttempts: z.number().int().positive().optional().default(10),
-    initialReconnectDelay: z.number().int().positive().optional().default(1_000),
-    maxReconnectDelay: z.number().int().positive().optional().default(60_000),
-    reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
-    accounts: z.array(XgImAccountConfigSchema).optional(),
-});
-
-// ─── 辅助函数 ─────────────────────────────────────────────────────────────────
-
-/** 从顶层 cfg 中取出 XgImConfig，支持多账户（README：channels.xg_cwork_im） */
-function getXgImConfig(cfg: OpenClawConfig, accountId?: string | null): XgImConfig {
-    const raw = (cfg as Record<string, Record<string, unknown>>)?.channels?.xg_cwork_im as XgImConfig | undefined;
-    if (!raw) throw new Error("[cwork_im] channels.xg_cwork_im config not found");
-
-    // 指定了具体账户 ID（数组下标）时，合并对应账户配置
-    if (accountId && accountId !== "default" && raw.accounts) {
-        const accIdx = parseInt(accountId, 10);
-        const sub = raw.accounts[accIdx];
-        if (sub) {
-            return { ...raw, ...sub };
-        }
-    }
-
-    // 没有指定 accountId（如 Cron outbound 场景），自动 fallback 到 accounts[0]
-    // 避免顶层 raw 没有 appKey 时 getToken 失败
-    if (raw.accounts && raw.accounts.length > 0 && !raw.appKey) {
-        return { ...raw, ...raw.accounts[0] };
-    }
-
-    return raw;
-}
-
-function isConfigured(cfg: OpenClawConfig): boolean {
-    try {
-        const c = getXgImConfig(cfg);
-        return Boolean(c?.appKey && c?.baseUrl);
-    } catch {
-        return false;
-    }
-}
-
-// ─── 日志适配器 ───────────────────────────────────────────────────────────────
-// ChannelLogSink 的 info/warn/error 方法接受单个 string
-
-interface Logger {
-    info: (msg: string) => void;
-    warn: (msg: string) => void;
-    error: (msg: string) => void;
-    debug?: (msg: string) => void;
-}
-
-function toLogger(sink: { info?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void; debug?: (msg: string) => void } | undefined): Logger {
-    return {
-        info: (msg) => sink?.info?.(msg),
-        warn: (msg) => sink?.warn?.(msg),
-        error: (msg) => sink?.error?.(msg),
-        debug: (msg) => sink?.debug?.(msg),
-    };
-}
-
-// ─── Channel Plugin 定义 ─────────────────────────────────────────────────────
-
-export const xgCworkImChannelPlugin: XgImChannelPlugin = {
-    id: "xg_cwork_im",
-    meta: {
-        id: "xg_cwork_im",
-        label: "XG CWork IM",
-        selectionLabel: "XG CWork IM (小橙工作台)",
-        docsPath: "/channels/xg_cwork_im",
-        blurb: "小橙工作台 IM 机器人，通过 WebSocket 长连接接收 @ 消息。",
-        aliases: ["xg_cwork_im", "xgim", "im"],
-    },
-    // 双重类型转换绕过 zod v3/v4 的 TS 类型不兼容
-    // buildChannelConfigSchema 会将 schema 包装成可序列化的形式，避免 DataCloneError
-    configSchema: buildChannelConfigSchema(XgImConfigSchema as unknown as Parameters<typeof buildChannelConfigSchema>[0]),
-    capabilities: {
-        chatTypes: ["group"] as Array<"direct" | "group">,
-        reactions: false,
-        threads: false,
-        media: false,
-        nativeCommands: false,
-        blockStreaming: false,
-    },
-    reload: { configPrefixes: ["channels.xg_cwork_im"] },
-
-    // ── 账户配置 ────────────────────────────────────────────────────────────────
-    config: {
-        listAccountIds: (cfg: OpenClawConfig): string[] => {
-            try {
-                const config = getXgImConfig(cfg);
-                if (config.accounts && config.accounts.length > 0) {
-                    // 使用数组下标作为 ID
-                    return config.accounts.map((_, i) => i.toString());
-                }
-                return isConfigured(cfg) ? ["default"] : [];
-            } catch {
-                return [];
-            }
-        },
-
-        resolveAccount: (cfg: OpenClawConfig, accountId?: string | null): ResolvedAccount => {
-            const id = accountId || "default";
-            try {
-                const config = getXgImConfig(cfg, id);
-                return {
-                    accountId: id,
-                    config,
-                    enabled: config.enabled !== false,
-                    configured: Boolean(config.appKey && config.baseUrl),
-                    name: config.name ?? null,
-                };
-            } catch {
-                return {
-                    accountId: id,
-                    config: {} as XgImConfig,
-                    enabled: false,
-                    configured: false,
-                    name: null,
-                };
-            }
-        },
-
-        defaultAccountId: (): string => "default",
-
-        isConfigured: (account: ResolvedAccount): boolean => account.configured,
-
-        describeAccount: (account: ResolvedAccount) => ({
-            accountId: account.accountId,
-            name: account.config?.name ?? "XG-IM",
-            enabled: account.enabled,
-            configured: account.configured,
-        }),
-    },
-
-    // ── 群聊设置 ─────────────────────────────────────────────────────────────────
-    groups: {
-        resolveRequireMention: (params): boolean => {
-            try {
-                const config = getXgImConfig(params.cfg, params.accountId);
-                return config?.groupPolicy !== "open";
-            } catch {
-                return true; // 默认需要 @
-            }
-        },
-    },
-
-    // ── 出站消息（openclaw 主动发送时调用）────────────────────────────────────────
-    outbound: {
-        deliveryMode: "direct" as const,
-
-        resolveTarget: (params) => {
-            const trimmed = params.to?.trim();
-            if (!trimmed) {
-                return {
-                    ok: false as const,
-                    error: new Error("XG-IM message requires --to <groupId>"),
-                };
-            }
-            return { ok: true as const, to: trimmed };
-        },
-
-        sendText: async (ctx) => {
-            const { cfg, to, text, accountId } = ctx;
-            const log: Logger = { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } };
-            const config = getXgImConfig(cfg, accountId);
-            const identity = await getToken(config, log);
-
-            await sendTextMessage(config, identity.token, to, text, [], log);
-
-            return {
-                channel: "xg_cwork_im",
-                messageId: randomUUID(),
-            };
-        },
-    },
-
-    // ── 网关（WebSocket 长连接）─────────────────────────────────────────────────
-    gateway: {
-        startAccount: async (ctx: GatewayStartContext): Promise<void> => {
-            const account = ctx.account;
-            const config = account.config;
-            const log = toLogger(ctx.log);
-            const logPrefix = `[${account.accountId}:${config.agentId || "main"}]`;
-
-            if (!config.appKey || !config.baseUrl) {
-                throw new Error(`${logPrefix} appKey and baseUrl are required in config`);
-            }
-
-            log.info(`${logPrefix} Starting XG-IM channel...`);
-
-            // 1. 获取机器人 token（有效期一年，缓存后无需重复请求）
-            const identity = await getToken(config, log);
-
-            // 2. 获取 PluginRuntime（用于路由消息给 OpenClaw）
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const rt = getXgImRuntime() as any;
-
-            // 3. 若 abort 信号已触发则不启动
-            if (ctx.abortSignal?.aborted) {
-                throw new Error(`${logPrefix} Connection aborted before start`);
-            }
-
-            // 4. 消息去重（按账户隔离）
-            const processedMsgIds = new Set<string>();
-            const MSG_DEDUP_MAX = 1_000;
-
-            const isDuplicate = (msgId: string): boolean => {
-                if (processedMsgIds.has(msgId)) return true;
-                if (processedMsgIds.size >= MSG_DEDUP_MAX) {
-                    const iter = processedMsgIds.values();
-                    for (let i = 0; i < MSG_DEDUP_MAX / 2; i++) {
-                        const val = iter.next().value;
-                        if (val !== undefined) processedMsgIds.delete(val);
-                    }
-                }
-                processedMsgIds.add(msgId);
-                return false;
-            };
-
-            // 5. 收到 WebSocket 消息时的处理逻辑
-            const handleMessage = async (msg: WsMessage): Promise<void> => {
-                const params = msg.params;
-                try {
-                    if (isDuplicate(params.msgId)) {
-                        log.debug?.(`${logPrefix} Duplicate msgId=${params.msgId}, skipping`);
-                        return;
-                    }
-
-                    const msgContent = params.msgContent;
-                    const msgType = msgContent?.type ?? "text";
-                    const msgUrl = msgContent?.url;
-                    const msgExt = msgContent?.ext;
-
-                    let rawText = msgContent?.text ?? "";
-                    // 如果是语音消息且没有文本内容，设为占位符
-                    if (msgType === "voice" && !rawText) {
-                        rawText = "[语音消息]";
-                    }
-                    const text = rawText;
-
-                    if (!text && !msgUrl) {
-                        log.debug?.(`${logPrefix} Empty message (no text and no url), skipping`);
-                        return;
-                    }
-
-                    log.info(
-                        `${logPrefix} Message from ${params.fromUserName}(${params.fromUserId}) in group=${params.groupId}: ${text}`,
-                    );
-
-                    // 1. 获取当前机器人身份
-                    const currentIdentity = await getToken(config, log);
-                    // 2. 判定是否真正 @ 了当前机器人
-                    const isMentioned = Array.isArray(params.mentions) &&
-                        params.mentions.includes(currentIdentity.userId);
-
-                    // (补充逻辑) 如果是 robotMention 指令，但没有 mentions 列表，则降级为老逻辑：文本正则匹配
-                    const isLegacyMentioned = msg.cmd === "robotMention" &&
-                        (!params.mentions || params.mentions.length === 0) &&
-                        new RegExp(`@${currentIdentity.name}\\b`).test(rawText);
-
-                    const actuallyMentioned = isMentioned || isLegacyMentioned;
-
-                    // 3. 构建 OpenClaw 视角的“单条纯净消息”
-
-                    // 通过 PluginRuntime 路由消息到 OpenClaw
-                    const route = rt.channel.routing.resolveAgentRoute({
-                        cfg: ctx.cfg,
-                        channel: "xg_cwork_im",
-                        accountId: account.accountId,
-                        agentId: config.agentId || "main",
-                        peer: { kind: "group", id: params.groupId },
-                    });
-                    log.info(`${logPrefix} [route] agentId=${route.agentId} sessionKey=${route.sessionKey}`);
-
-                    const storePath = rt.channel.session.resolveStorePath(ctx.cfg.session?.store, {
-                        agentId: route.agentId,
-                    });
-
-                    const envelopeOptions = rt.channel.reply.resolveEnvelopeFormatOptions(ctx.cfg);
-                    const previousTimestamp = rt.channel.session.readSessionUpdatedAt({
-                        storePath,
-                        sessionKey: route.sessionKey,
-                    });
-
-                    const msgTime = params.timestamp ?? params.msgSendTime ?? 0;
-                    const fromLabel = `${params.groupId} - ${params.fromUserName}`;
-                    const body = rt.channel.reply.formatInboundEnvelope({
-                        channel: "XG-IM",
-                        from: fromLabel,
-                        timestamp: msgTime,
-                        body: text,
-                        chatType: "group",
-                        sender: { name: params.fromUserName, id: params.fromUserId },
-                        previousTimestamp,
-                        envelope: envelopeOptions,
-                    });
-
-                    const inboundCtx = rt.channel.reply.finalizeInboundContext({
-                        Body: body,
-                        RawBody: text,
-                        CommandBody: text,
-                        From: params.groupId,
-                        To: params.groupId,
-                        SessionKey: route.sessionKey,
-                        AccountId: account.accountId,
-                        ChatType: "group",
-                        ConversationLabel: fromLabel,
-                        GroupSubject: params.groupId,
-                        SenderName: params.fromUserName,
-                        SenderId: params.fromUserId,
-                        Provider: "xg_cwork_im",
-                        Surface: "xg_cwork_im",
-                        MessageSid: params.msgId,
-                        Timestamp: msgTime,
-                        OriginatingChannel: "xg_cwork_im",
-                        OriginatingTo: params.groupId,
-                        GroupChannel: route.sessionKey,
-                        // 透传媒体信息
-                        MediaUrl: msgUrl,
-                        MediaType: msgType === "voice" ? "voice" : undefined,
-                        // 透传扩展字段给 AI (作为 UntrustedContext)
-                        UntrustedContext: msgExt ? [JSON.stringify(msgExt)] : undefined,
-                        // 同时保留原始 ext 供可能的后续逻辑使用
-                        XgImExt: msgExt,
-                    });
-
-                    // 【所有消息都必须做】记录到数据库！让 AI 产生“记忆”
-                    log.info(`${logPrefix} [session] Recording inbound session sessionKey=${inboundCtx.SessionKey || route.sessionKey}`);
-                    await rt.channel.session.recordInboundSession({
-                        storePath,
-                        sessionKey: inboundCtx.SessionKey || route.sessionKey,
-                        ctx: inboundCtx,
-                        updateLastRoute: {
-                            sessionKey: route.mainSessionKey,
-                            channel: "xg_cwork_im",
-                            to: params.groupId,
-                            accountId: account.accountId,
-                        },
-                        onRecordError: (err: unknown) => {
-                            log.error(`${logPrefix} Failed to record session: ${String(err)}`);
-                        },
-                    });
-
-                    // 【只有真 @ 我的消息才做】呼叫 AI 激活推理
-                    if (actuallyMentioned) {
-                        log.info(`${logPrefix} [dispatch] Dispatching to OpenClaw AI, sessionKey=${route.sessionKey}`);
-                        let isFirstReply = true;
-                        const dispatchStart = Date.now();
-
-                        // 分发消息给 AI，deliver 回调负责发送回复
-                        await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-                            ctx: inboundCtx,
-                            cfg: ctx.cfg,
-                            dispatcherOptions: {
-                                responsePrefix: "",
-                                deliver: async (payload: { markdown?: string; text?: string }) => {
-                                    try {
-                                        const textToSend = payload.markdown || payload.text;
-                                        if (!textToSend) return;
-
-                                        if (isFirstReply) {
-                                            const ttfr = Date.now() - dispatchStart;
-                                            log.info(`${logPrefix} [deliver] First response block received from AI (TTFB: ${ttfr}ms)`);
-                                            isFirstReply = false;
-                                        }
-
-                                        log.info(`${logPrefix} [deliver] Sending block to groupId=${params.groupId} length=${textToSend.length}`);
-                                        await sendTextMessage(
-                                            config,
-                                            currentIdentity.token,
-                                            params.groupId,
-                                            textToSend,
-                                            [params.fromUserId] as string[],
-                                            log,
-                                        );
-                                        log.info(`${logPrefix} [deliver] Block sent successfully to groupId=${params.groupId}`);
-                                    } catch (err: unknown) {
-                                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
-                                        throw err;
-                                    }
-                                },
-                            },
-                        });
-                        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
-                    } else {
-                        // 没 @ 我，仅作为旁观者缓存记忆，不打扰群里聊天
-                        log.debug?.(`${logPrefix} Not mentioned in group, quietly memorized the message context.`);
-                    }
-                } catch (err: unknown) {
-                    log.error(`${logPrefix} handleMessage error: ${String(err)}`);
-                }
-            };
-
-            // 5. 启动 WebSocket 连接
-            const wsHandle = startWebSocket(config, identity.token, handleMessage, log);
-
-            // 6. 阻塞到 abortSignal 触发
-            await new Promise<void>((resolve) => {
-                const abortHandler = (): void => {
-                    log.info(`${logPrefix} Abort signal received, stopping XG-IM channel...`);
-                    wsHandle.stop();
-                    clearTokenCache(config);
-                    resolve();
-                };
-
-                if (ctx.abortSignal) {
-                    ctx.abortSignal.addEventListener("abort", abortHandler, { once: true });
-                }
-            });
-        },
-    },
-};
+/**
+ * XG-IM Channel Plugin — 核心定义
+ *
+ * 遵循 OpenClaw Channel Plugin 架构（参考 openclaw-channel-dingtalk）：
+ * - config   : 账户解析
+ * - outbound : AI 回复发送
+ * - gateway  : 启动 WebSocket 长连接，接收 robotMention 消息后通过
+ *              PluginRuntime 路由给 OpenClaw 处理
+ */
+
+import { randomUUID } from "node:crypto";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+import { clearTokenCache, getToken } from "./auth.js";
+import { startWebSocket } from "./connection.js";
+import { sendTextMessage } from "./send-service.js";
+import type {
+    GatewayStartContext,
+    PluginRuntime,
+    ResolvedAccount,
+    WsMessage,
+    WsMessageParams,
+    XgImChannelPlugin,
+    XgImConfig,
+} from "./types.js";
+
+// ─── 全局 Runtime（在 index.ts 的 register 中注入）────────────────────────────
+
+let xgImRuntime: PluginRuntime | null = null;
+
+export function setXgImRuntime(rt: PluginRuntime): void {
+    xgImRuntime = rt;
+}
+
+function getXgImRuntime(): PluginRuntime {
+    if (!xgImRuntime) throw new Error("[cwork_im] Plugin runtime not initialized");
+    return xgImRuntime;
+}
+
+// ─── 配置 Schema ──────────────────────────────────────────────────────────────
+
+const XgImAccountConfigSchema = z.object({
+    appKey: z.string().min(1, "appKey is required"),
+    agentId: z.string().optional().default("main"),
+    name: z.string().optional(),
+    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
+});
+
+const XgImConfigSchema = z.object({
+    appKey: z.string().optional(),
+    agentId: z.string().optional().default("main"),
+    baseUrl: z.string().url("baseUrl must be a valid URL"),
+    wsBaseUrl: z.string().url("wsBaseUrl must be a valid URL").optional(),
+    enabled: z.boolean().optional().default(true),
+    name: z.string().optional(),
+    groupPolicy: z.enum(["open", "mention"]).optional().default("mention"),
+    allowFrom: z.array(z.string()).optional().default([]),
+    debug: z.boolean().optional().default(false),
+    maxConnectionAttempts: z.number().int().positive().optional().default(10),
+    initialReconnectDelay: z.number().int().positive().optional().default(1_000),
+    maxReconnectDelay: z.number().int().positive().optional().default(60_000),
+    reconnectJitter: z.number().min(0).max(1).optional().default(0.3),
+    accounts: z.array(XgImAccountConfigSchema).optional(),
+});
+
+// ─── 辅助函数 ─────────────────────────────────────────────────────────────────
+
+/** 从顶层 cfg 中取出 XgImConfig，支持多账户（README：channels.xg_cwork_im） */
+function getXgImConfig(cfg: OpenClawConfig, accountId?: string | null): XgImConfig {
+    const raw = (cfg as Record<string, Record<string, unknown>>)?.channels?.xg_cwork_im as XgImConfig | undefined;
+    if (!raw) throw new Error("[cwork_im] channels.xg_cwork_im config not found");
+
+    // 指定了具体账户 ID（数组下标）时，合并对应账户配置
+    if (accountId && accountId !== "default" && raw.accounts) {
+        const accIdx = parseInt(accountId, 10);
+        const sub = raw.accounts[accIdx];
+        if (sub) {
+            return { ...raw, ...sub };
+        }
+    }
+
+    // 没有指定 accountId（如 Cron outbound 场景），自动 fallback 到 accounts[0]
+    // 避免顶层 raw 没有 appKey 时 getToken 失败
+    if (raw.accounts && raw.accounts.length > 0 && !raw.appKey) {
+        return { ...raw, ...raw.accounts[0] };
+    }
+
+    return raw;
+}
+
+function isConfigured(cfg: OpenClawConfig): boolean {
+    try {
+        const c = getXgImConfig(cfg);
+        return Boolean(c?.appKey && c?.baseUrl);
+    } catch {
+        return false;
+    }
+}
+
+// ─── 日志适配器 ───────────────────────────────────────────────────────────────
+// ChannelLogSink 的 info/warn/error 方法接受单个 string
+
+interface Logger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+}
+
+function toLogger(sink: { info?: (msg: string) => void; warn?: (msg: string) => void; error?: (msg: string) => void; debug?: (msg: string) => void } | undefined): Logger {
+    return {
+        info: (msg) => sink?.info?.(msg),
+        warn: (msg) => sink?.warn?.(msg),
+        error: (msg) => sink?.error?.(msg),
+        debug: (msg) => sink?.debug?.(msg),
+    };
+}
+
+// ─── Channel Plugin 定义 ─────────────────────────────────────────────────────
+
+export const xgCworkImChannelPlugin: XgImChannelPlugin = {
+    id: "xg_cwork_im",
+    meta: {
+        id: "xg_cwork_im",
+        label: "XG CWork IM",
+        selectionLabel: "XG CWork IM (小橙工作台)",
+        docsPath: "/channels/xg_cwork_im",
+        blurb: "小橙工作台 IM 机器人，通过 WebSocket 长连接接收 @ 消息。",
+        aliases: ["xg_cwork_im", "im"],
+    },
+    // 双重类型转换绕过 zod v3/v4 的 TS 类型不兼容
+    // buildChannelConfigSchema 会将 schema 包装成可序列化的形式，避免 DataCloneError
+    configSchema: buildChannelConfigSchema(XgImConfigSchema as unknown as Parameters<typeof buildChannelConfigSchema>[0]),
+    capabilities: {
+        chatTypes: ["group"] as Array<"direct" | "group">,
+        reactions: false,
+        threads: false,
+        media: false,
+        nativeCommands: false,
+        blockStreaming: false,
+    },
+    reload: { configPrefixes: ["channels.xg_cwork_im"] },
+
+    // ── 账户配置 ────────────────────────────────────────────────────────────────
+    config: {
+        listAccountIds: (cfg: OpenClawConfig): string[] => {
+            try {
+                const config = getXgImConfig(cfg);
+                if (config.accounts && config.accounts.length > 0) {
+                    // 使用数组下标作为 ID
+                    return config.accounts.map((_, i) => i.toString());
+                }
+                return isConfigured(cfg) ? ["default"] : [];
+            } catch {
+                return [];
+            }
+        },
+
+        resolveAccount: (cfg: OpenClawConfig, accountId?: string | null): ResolvedAccount => {
+            const id = accountId || "default";
+            try {
+                const config = getXgImConfig(cfg, id);
+                return {
+                    accountId: id,
+                    config,
+                    enabled: config.enabled !== false,
+                    configured: Boolean(config.appKey && config.baseUrl),
+                    name: config.name ?? null,
+                };
+            } catch {
+                return {
+                    accountId: id,
+                    config: {} as XgImConfig,
+                    enabled: false,
+                    configured: false,
+                    name: null,
+                };
+            }
+        },
+
+        defaultAccountId: (): string => "default",
+
+        isConfigured: (account: ResolvedAccount): boolean => account.configured,
+
+        describeAccount: (account: ResolvedAccount) => ({
+            accountId: account.accountId,
+            name: account.config?.name ?? "xg_cwork_im",
+            enabled: account.enabled,
+            configured: account.configured,
+        }),
+    },
+
+    // ── 群聊设置 ─────────────────────────────────────────────────────────────────
+    groups: {
+        resolveRequireMention: (params): boolean => {
+            try {
+                const config = getXgImConfig(params.cfg, params.accountId);
+                return config?.groupPolicy !== "open";
+            } catch {
+                return true; // 默认需要 @
+            }
+        },
+    },
+
+    // ── 出站消息（openclaw 主动发送时调用）────────────────────────────────────────
+    outbound: {
+        deliveryMode: "direct" as const,
+
+        resolveTarget: (params) => {
+            const trimmed = params.to?.trim();
+            if (!trimmed) {
+                return {
+                    ok: false as const,
+                    error: new Error("XG-IM message requires --to <groupId>"),
+                };
+            }
+            return { ok: true as const, to: trimmed };
+        },
+
+        sendText: async (ctx) => {
+            const { cfg, to, text, accountId, log: ctxLog } = ctx as typeof ctx & { log?: Logger };
+            const log = toLogger(ctxLog);
+            const config = getXgImConfig(cfg, accountId);
+            const identity = await getToken(config, log);
+
+            await sendTextMessage(config, identity.token, to, text, [], log);
+
+            return {
+                channel: "xg_cwork_im",
+                messageId: randomUUID(),
+            };
+        },
+    },
+
+    // ── 网关（WebSocket 长连接）─────────────────────────────────────────────────
+    gateway: {
+        startAccount: async (ctx: GatewayStartContext): Promise<void> => {
+            const account = ctx.account;
+            const config = account.config;
+            const log = toLogger(ctx.log);
+            const logPrefix = `[${account.accountId}:${config.agentId || "main"}]`;
+
+            if (!config.appKey || !config.baseUrl) {
+                throw new Error(`${logPrefix} appKey and baseUrl are required in config`);
+            }
+
+            log.info(`${logPrefix} Starting xg-cwork-im channel...`);
+
+            // 1. 获取机器人 token（有效期一年，缓存后无需重复请求）
+            const identity = await getToken(config, log);
+
+            // 2. 获取 PluginRuntime（用于路由消息给 OpenClaw）
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const rt = getXgImRuntime() as any;
+
+            // 3. 若 abort 信号已触发则不启动
+            if (ctx.abortSignal?.aborted) {
+                throw new Error(`${logPrefix} Connection aborted before start`);
+            }
+
+            // 4. 消息去重（按账户隔离）
+            const processedMsgIds = new Set<string>();
+            const MSG_DEDUP_MAX = 1_000;
+
+            const isDuplicate = (msgId: string): boolean => {
+                if (processedMsgIds.has(msgId)) return true;
+                if (processedMsgIds.size >= MSG_DEDUP_MAX) {
+                    const iter = processedMsgIds.values();
+                    for (let i = 0; i < MSG_DEDUP_MAX / 2; i++) {
+                        const val = iter.next().value;
+                        if (val !== undefined) processedMsgIds.delete(val);
+                    }
+                }
+                processedMsgIds.add(msgId);
+                return false;
+            };
+
+            // 5. 收到 WebSocket 消息时的处理逻辑
+            const handleMessage = async (msg: WsMessage): Promise<void> => {
+                const params = msg.params;
+                try {
+                    if (isDuplicate(params.msgId)) {
+                        log.debug?.(`${logPrefix} Duplicate msgId=${params.msgId}, skipping`);
+                        return;
+                    }
+
+                    const msgContent = params.msgContent;
+                    const msgType = msgContent?.type ?? "text";
+                    const msgUrl = msgContent?.url;
+                    const msgExt = msgContent?.ext;
+                    const senderId = params.userInfo?.id;
+                    const senderName = params.userInfo?.name || senderId || "";
+                    const senderBackground = params.userInfo?.background;
+
+                    let rawText = msgContent?.text ?? "";
+                    // 如果是语音消息且没有文本内容，设为占位符
+                    if (msgType === "voice" && !rawText) {
+                        rawText = "[语音消息]";
+                    }
+                    const text = rawText;
+
+                    if (!text && !msgUrl) {
+                        log.debug?.(`${logPrefix} Empty message (no text and no url), skipping`);
+                        return;
+                    }
+
+                    log.info(
+                        `${logPrefix} Message from ${senderName}(${senderId ?? "unknown"}) in group=${params.groupId}: ${text}`,
+                    );
+
+                    // 1. 获取当前机器人身份
+                    const currentIdentity = await getToken(config, log);
+                    // 2. 判定是否真正 @ 了当前机器人
+                    const mentions = params.mentions;
+                    const isMentioned = Array.isArray(mentions) &&
+                        (mentions.includes(currentIdentity.userId) || mentions.includes("all"));
+
+                    // (补充逻辑) 如果是 robotMention 指令，但没有 mentions 列表，则降级为老逻辑：文本正则匹配
+                    const isLegacyMentioned = msg.cmd === "robotMention" &&
+                        (!params.mentions || params.mentions.length === 0) &&
+                        new RegExp(`@${currentIdentity.name}\\b`).test(rawText);
+
+                    const actuallyMentioned = isMentioned || isLegacyMentioned;
+
+                    // 3. 构建 OpenClaw 视角的“单条纯净消息”
+
+                    // 通过 PluginRuntime 路由消息到 OpenClaw
+                    const route = rt.channel.routing.resolveAgentRoute({
+                        cfg: ctx.cfg,
+                        channel: "xg_cwork_im",
+                        accountId: account.accountId,
+                        agentId: config.agentId || "main",
+                        peer: { kind: "group", id: params.groupId },
+                    });
+                    log.info(`${logPrefix} [route] agentId=${route.agentId} sessionKey=${route.sessionKey}`);
+
+                    const storePath = rt.channel.session.resolveStorePath(ctx.cfg.session?.store, {
+                        agentId: route.agentId,
+                    });
+
+                    const envelopeOptions = rt.channel.reply.resolveEnvelopeFormatOptions(ctx.cfg);
+                    const previousTimestamp = rt.channel.session.readSessionUpdatedAt({
+                        storePath,
+                        sessionKey: route.sessionKey,
+                    });
+
+                    const msgTime = params.timestamp ?? params.msgSendTime ?? 0;
+                    const fromLabel = `${params.groupId} - ${senderName}`;
+                    const body = rt.channel.reply.formatInboundEnvelope({
+                        channel: "xg_cwork_im",
+                        from: fromLabel,
+                        timestamp: msgTime,
+                        body: text,
+                        chatType: "group",
+                        sender: { name: senderName, id: senderId ?? "" },
+                        previousTimestamp,
+                        envelope: envelopeOptions,
+                    });
+
+                    const inboundCtx = rt.channel.reply.finalizeInboundContext({
+                        Body: body,
+                        RawBody: text,
+                        CommandBody: text,
+                        From: params.groupId,
+                        To: params.groupId,
+                        SessionKey: route.sessionKey,
+                        AccountId: account.accountId,
+                        ChatType: "group",
+                        ConversationLabel: fromLabel,
+                        GroupSubject: params.groupId,
+                        SenderName: senderName,
+                        SenderId: senderId ?? "",
+                        Provider: "xg_cwork_im",
+                        Surface: "xg_cwork_im",
+                        MessageSid: params.msgId,
+                        Timestamp: msgTime,
+                        OriginatingChannel: "xg_cwork_im",
+                        OriginatingTo: params.groupId,
+                        GroupChannel: route.sessionKey,
+                        // 透传媒体信息
+                        MediaUrl: msgUrl,
+                        MediaType: msgType === "voice" ? "voice" : undefined,
+                        // 透传扩展字段给 AI (作为 UntrustedContext)
+                        UntrustedContext: (() => {
+                            const parts: string[] = [];
+                            if (msgExt) parts.push(JSON.stringify(msgExt));
+                            if (senderBackground) parts.push(String(senderBackground));
+                            return parts.length > 0 ? parts : undefined;
+                        })(),
+                        // 同时保留原始 ext 供可能的后续逻辑使用
+                        XgImExt: msgExt,
+                    });
+
+                    // 若消息内容为 /reset，则在将其转交给 OpenClaw 之前完整打印一次入站上下文，便于排查 reset 行为
+                    if (text.trim() === "/reset") {
+                        try {
+                            log.info?.(
+                                `${logPrefix} [reset] inboundCtx payload before dispatch: ${JSON.stringify(inboundCtx)}`,
+                            );
+                        } catch {
+                            // 忽略 JSON 序列化异常，避免影响正常流程
+                        }
+                    }
+
+                    // 【所有消息都必须做】记录到数据库！让 AI 产生“记忆”
+                    log.info(`${logPrefix} [session] Recording inbound session sessionKey=${inboundCtx.SessionKey || route.sessionKey}`);
+                    await rt.channel.session.recordInboundSession({
+                        storePath,
+                        sessionKey: inboundCtx.SessionKey || route.sessionKey,
+                        ctx: inboundCtx,
+                        updateLastRoute: {
+                            sessionKey: route.mainSessionKey,
+                            channel: "xg_cwork_im",
+                            to: params.groupId,
+                            accountId: account.accountId,
+                        },
+                        onRecordError: (err: unknown) => {
+                            log.error(`${logPrefix} Failed to record session: ${String(err)}`);
+                        },
+                    });
+
+                    // 【只有真 @ 我的消息才做】呼叫 AI 激活推理
+                    if (actuallyMentioned) {
+                        log.info(`${logPrefix} [dispatch] Dispatching to OpenClaw AI, sessionKey=${route.sessionKey}`);
+                        let isFirstReply = true;
+                        const dispatchStart = Date.now();
+
+                        // 1. 先向 IM 声明“开始流式消息”，拿到 msgId
+                        const { msgId } = await wsHandle.streamClient.start({
+                            groupId: params.groupId,
+                        });
+                        log.info(`${logPrefix} [stream] START acknowledged: msgId=${msgId}`);
+
+                        // 2. 分发消息给 AI，deliver 回调负责把增量文本通过 CHUNK 推给 IM
+                        let fullText = "";
+                        // think 与 answer 阶段各自维护 seq，便于集群/跨服务按序重排
+                        let thinkSeq = 0;
+                        let answerSeq = 0;
+
+                        await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                            ctx: inboundCtx,
+                            cfg: ctx.cfg,
+                            dispatcherOptions: {
+                                responsePrefix: "",
+                                deliver: async (payload: { markdown?: string; text?: string; isThinking?: boolean }) => {
+                                    try {
+                                        const textToSend = payload.markdown || payload.text;
+                                        if (!textToSend) return;
+
+                                        const isThinking = payload.isThinking === true;
+                                        const seq = isThinking ? thinkSeq++ : answerSeq++;
+
+                                        if (isFirstReply) {
+                                            const ttfr = Date.now() - dispatchStart;
+                                            log.info(`${logPrefix} [deliver] First response block received from AI (TTFB: ${ttfr}ms)`);
+                                            isFirstReply = false;
+                                        }
+
+                                        fullText += textToSend;
+
+                                        // 将增量 block 以 CHUNK 形式推给 IM，带 seq 便于服务端按序
+                                        await wsHandle.streamClient.chunk(msgId, {
+                                            isThinking,
+                                            content: textToSend,
+                                            seq,
+                                        });
+                                        log.info(
+                                            `${logPrefix} [stream] CHUNK sent: msgId=${msgId} isThinking=${isThinking} seq=${seq} length=${textToSend.length}`,
+                                        );
+                                    } catch (err: unknown) {
+                                        log.error(`${logPrefix} Reply deliver failed: ${String(err)}`);
+                                        throw err;
+                                    }
+                                },
+                            },
+                        });
+
+                        // 3. AI 推理完成，发送 END，并用 msgId 覆盖最终消息内容
+                        await wsHandle.streamClient.end(msgId, "stop");
+                        log.info(`${logPrefix} [stream] END sent: msgId=${msgId}`);
+
+                        if (fullText) {
+                            log.info(
+                                `${logPrefix} [send] Updating final message via HTTP: groupId=${params.groupId} msgId=${msgId}`,
+                            );
+
+                            // 构造 reply 信息：回复用户刚发的这条消息
+                            const reply = {
+                                targetMsgId: params.msgId,
+                                targetUserId: senderId ?? "",
+                                targetUserName: senderName,
+                                previewText: text,
+                            };
+
+                            await sendTextMessage(
+                                config,
+                                currentIdentity.token,
+                                params.groupId,
+                                fullText,
+                                [senderId ?? ""] as string[],
+                                log,
+                                msgId,
+                                reply,
+                            );
+                        }
+
+                        log.info(`${logPrefix} [dispatch] Dispatch completed for sessionKey=${route.sessionKey}`);
+                    } else {
+                        // 没 @ 我，仅作为旁观者缓存记忆，不打扰群里聊天
+                        log.debug?.(`${logPrefix} Not mentioned in group, quietly memorized the message context.`);
+                    }
+                } catch (err: unknown) {
+                    log.error(`${logPrefix} handleMessage error: ${String(err)}`);
+                }
+            };
+
+            // 5. 启动 WebSocket 连接
+            const wsHandle = startWebSocket(config, identity.token, handleMessage, log);
+
+            // 6. 阻塞到 abortSignal 触发（若存在）；若无 abortSignal，则交由进程生命周期管理
+            if (ctx.abortSignal) {
+                await new Promise<void>((resolve) => {
+                    const abortHandler = (): void => {
+                        log.info(`${logPrefix} Abort signal received, stopping XG-IM channel...`);
+                        wsHandle.stop();
+                        clearTokenCache(config);
+                        resolve();
+                    };
+
+                    ctx.abortSignal?.addEventListener("abort", abortHandler, { once: true });
+                });
+            }
+        },
+    },
+};