@xgjktech/xg_cwork_im 1.0.0 → 1.0.2

package/src/connection.ts

@@ -4,18 +4,33 @@
  * 功能：
  * - 建立 wss://<baseUrl>/ws-notify/websocket?accessToken=<token> 长连接
  * - 接收 robotMention 消息并回调
+ * - 支持基于 WebSocket 的 AI 回复流式推送（START/CHUNK/END 协议）
  * - 指数退避 + 抖动的自动重连机制
  * - 主动发送 WebSocket ping 保活，超时自动重连
  */
 
+import { randomUUID } from "node:crypto";
 import WebSocket from "ws";
 import type { Log } from "./auth.js";
-import type { WsMessage, WsMessageParams, XgImConfig } from "./types.js";
+import type { WsMessage, XgImConfig } from "./types.js";
 
 export type OnMessageCallback = (msg: WsMessage) => void;
 
-/** 心跳间隔（ms）：每 30 秒发一次 ping，防止连接被后台剔除 */
-const PING_INTERVAL_MS = 30_000;
+/**
+ * 基于 WebSocket 的流式消息客户端。
+ *
+ * - start(): 发送 START，等待 ack，返回 msgId。
+ * - chunk(): 基于 msgId 发送增量文本。
+ * - end(): 发送 END，通知服务端结束本次流式消息。
+ */
+export interface ImStreamClient {
+    start: (opts: { groupId?: string; toUserId?: string }) => Promise<{ msgId: string }>;
+    chunk: (msgId: string, data: { isThinking: boolean; content: string }) => Promise<void>;
+    end: (msgId: string, reason: string) => Promise<void>;
+}
+
+/** 心跳间隔（ms）：每 20 秒发一次 ping，防止连接被后台剔除 */
+const PING_INTERVAL_MS = 20_000;
 
 /** 计算指数退避延迟（带随机抖动） */
 function calcDelay(
@@ -39,8 +54,8 @@ export function startWebSocket(
     token: string,
     onMessage: OnMessageCallback,
     log: Log,
-): { stop: () => void } {
-    const maxAttempts = config.maxConnectionAttempts ?? 10;
+): { stop: () => void; streamClient: ImStreamClient } {
+    const maxAttempts = config.maxConnectionAttempts ?? 200;
     const initialDelay = config.initialReconnectDelay ?? 1_000;
     const maxDelay = config.maxReconnectDelay ?? 60_000;
     const jitter = config.reconnectJitter ?? 0.3;
@@ -64,6 +79,14 @@ export function startWebSocket(
     let pingTimer: ReturnType<typeof setInterval> | null = null;
     let attempt = 0;
 
+    /**
+     * clientMsgId -> resolver(msgId)
+     *
+     * - 当发送 START 时，会生成一个 clientMsgId，并在此处挂一个 resolver。
+     * - 收到 im_stream_msg_ack 后，根据 clientMsgId 触发 resolver，返回服务端生成的 msgId。
+     */
+    const pendingAcks = new Map<string, (msgId: string) => void>();
+
     /** 清除心跳定时器 */
     function clearHeartbeat(): void {
         if (pingTimer !== null) {
@@ -97,6 +120,17 @@ export function startWebSocket(
         }, PING_INTERVAL_MS);
     }
 
+    /**
+     * 确保当前存在可用的 WebSocket 连接。
+     * 若不存在或未处于 OPEN 状态，则抛出错误，由上层决定是否回退为非流式模式。
+     */
+    function ensureSocketReady(): WebSocket {
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            throw new Error(`${logPrefix} WebSocket is not ready for sending stream message`);
+        }
+        return ws;
+    }
+
     function connect(): void {
         if (stopped) return;
 
@@ -119,9 +153,9 @@ export function startWebSocket(
                 return;
             }
 
-            let parsed: WsMessage;
+            let parsed: any;
             try {
-                parsed = JSON.parse(rawString) as WsMessage;
+                parsed = JSON.parse(rawString) as unknown;
             } catch {
                 // 如果不是 JSON，说明是心跳或者其他内容，忽略即可
                 // 如果开启 debug 还是可以打印日志
@@ -133,8 +167,24 @@ export function startWebSocket(
 
             log.info(`${logPrefix} ⇐ WS message received: cmd=${parsed.cmd}`);
 
-            // 这块不需要了，因为上面已经处理了纯文本 pong
-
+            // 处理流式消息 ack：im_stream_msg_ack
+            if (parsed.cmd === "im_stream_msg_ack" && parsed.params) {
+                const clientMsgId: string | undefined = parsed.params.clientMsgId;
+                const msgId: string | undefined = parsed.params.msgId;
+                if (clientMsgId && msgId) {
+                    const resolver = pendingAcks.get(clientMsgId);
+                    if (resolver) {
+                        pendingAcks.delete(clientMsgId);
+                        resolver(msgId);
+                        log.info(`${logPrefix} ⇐ im_stream_msg_ack received: clientMsgId=${clientMsgId} msgId=${msgId}`);
+                    } else if (config.debug) {
+                        log.debug?.(`${logPrefix} im_stream_msg_ack with unknown clientMsgId=${clientMsgId}`);
+                    }
+                } else if (config.debug) {
+                    log.debug?.(`${logPrefix} im_stream_msg_ack missing clientMsgId or msgId`);
+                }
+                return;
+            }
 
             // 处理包含 params 的事件（无论是 robotMention 还是普通 message）
             if (parsed.params && (parsed.cmd === "robotMention" || parsed.cmd === "groupMessage")) {
@@ -143,7 +193,7 @@ export function startWebSocket(
                 }
                 // onMessage 是 async 函数，必须用 .catch() 捕获异步错误
                 // 否则 await 之后的错误会变成未处理的 Promise rejection 被静默丢弃
-                Promise.resolve(onMessage(parsed)).catch((err: unknown) => {
+                Promise.resolve(onMessage(parsed as WsMessage)).catch((err: unknown) => {
                     log.error(`${logPrefix} onMessage async error: ${String(err)}`);
                 });
             }
@@ -190,6 +240,78 @@ export function startWebSocket(
     // 首次连接
     connect();
 
+    const streamClient: ImStreamClient = {
+        async start(opts: { groupId?: string; toUserId?: string }): Promise<{ msgId: string }> {
+            const socket = ensureSocketReady();
+            const clientMsgId = randomUUID();
+
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "START",
+                    clientMsgId,
+                    data: {
+                        groupId: opts.groupId,
+                        toUserId: opts.toUserId,
+                    },
+                },
+            };
+
+            log.info(`${logPrefix} ⇒ WS START stream: clientMsgId=${clientMsgId} groupId=${opts.groupId ?? ""} toUserId=${opts.toUserId ?? ""}`);
+
+            const msgId = await new Promise<string>((resolve, reject) => {
+                pendingAcks.set(clientMsgId, resolve);
+
+                socket.send(JSON.stringify(payload), (err) => {
+                    if (err) {
+                        pendingAcks.delete(clientMsgId);
+                        reject(err);
+                    }
+                });
+
+                // 简单超时保护，避免 ack 永远不到导致 Promise 悬挂
+                setTimeout(() => {
+                    if (pendingAcks.has(clientMsgId)) {
+                        pendingAcks.delete(clientMsgId);
+                        reject(new Error(`${logPrefix} START stream ack timeout for clientMsgId=${clientMsgId}`));
+                    }
+                }, 10_000);
+            });
+
+            return { msgId };
+        },
+
+        async chunk(msgId: string, data: { isThinking: boolean; content: string }): Promise<void> {
+            const socket = ensureSocketReady();
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "CHUNK",
+                    msgId,
+                    data,
+                },
+            };
+            if (config.debug) {
+                log.debug?.(`${logPrefix} ⇒ WS CHUNK stream: msgId=${msgId} isThinking=${data.isThinking} length=${data.content.length}`);
+            }
+            socket.send(JSON.stringify(payload));
+        },
+
+        async end(msgId: string, reason: string): Promise<void> {
+            const socket = ensureSocketReady();
+            const payload = {
+                cmd: "im_stream_msg",
+                params: {
+                    event: "END",
+                    msgId,
+                    data: { reason },
+                },
+            };
+            log.info(`${logPrefix} ⇒ WS END stream: msgId=${msgId} reason=${reason}`);
+            socket.send(JSON.stringify(payload));
+        },
+    };
+
     return {
         stop(): void {
             if (stopped) return;
@@ -208,5 +330,6 @@ export function startWebSocket(
             }
             ws = null;
         },
+        streamClient,
     };
 }

package/src/group-history-tool.ts

@@ -18,6 +18,11 @@ const GroupHistoryParams = Type.Object({
     groupId: Type.String({
         description: "群聊 ID，即当前消息来自的群组唯一标识符",
     }),
+    accountId: Type.Optional(
+        Type.String({
+            description: "（可选）要使用的 xg_cwork_im 账户下标（数字字符串，默认 0）",
+        }),
+    ),
     limit: Type.Optional(
         Type.Number({
             description: "需要获取的消息条数（5~30），默认 10",
@@ -30,17 +35,33 @@ const GroupHistoryParams = Type.Object({
 
 // ─── 内部 HTTP 工具 ──────────────────────────────────────────────────────────
 
-/** 从 OpenClaw 配置中提取 xg_cwork_im 配置（支持多账户取第一个） */
+/** 从 OpenClaw 配置中提取 xg_cwork_im 顶层配置（保留 accounts 以便多账户路由） */
 export function extractXgCworkImConfig(cfg: unknown): XgImConfig | null {
     const raw = (cfg as Record<string, Record<string, unknown>>)?.channels?.xg_cwork_im as XgImConfig | undefined;
     if (!raw?.baseUrl) return null;
+    return raw;
+}
 
-    // 如果有多账户，把 accounts[0] 的 appKey 合并到顶层（用于查询历史）
-    if (raw.accounts && raw.accounts.length > 0) {
-        const first = raw.accounts[0];
-        return { ...raw, ...first };
+/**
+ * 根据 accountId 解析具体账号配置。
+ *
+ * - 若传入 accountId 且能解析为有效下标，则优先使用对应 accounts[accountId]。
+ * - 否则：有 accounts 时默认使用 accounts[0]；无 accounts 时使用顶层配置。
+ */
+export function resolveAccountConfig(base: XgImConfig, accountId?: string | null): XgImConfig {
+    const accounts = base.accounts ?? [];
+    if (accounts.length === 0) {
+        return base;
     }
-    return raw;
+    let idx = 0;
+    if (accountId && accountId !== "default") {
+        const parsed = Number.parseInt(accountId, 10);
+        if (!Number.isNaN(parsed) && parsed >= 0 && parsed < accounts.length) {
+            idx = parsed;
+        }
+    }
+    const acc = accounts[idx] ?? accounts[0];
+    return { ...base, ...acc };
 }
 
 /** 调用 IM 接口拉取群聊最近 N 条消息 */
@@ -78,9 +99,9 @@ async function fetchGroupHistory(
 export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
     return {
         name: "xg_cwork_im_get_group_chat_history",
-        label: "获取群聊历史记录",
+        label: "【xg_cwork_im】获取群聊历史记录",
         description: [
-            "【必须遵守】获取此 IM 群聊的最近消息历史，用于理解对话上下文背景。",
+            "【仅限 xg_cwork_im 通道】获取当前 IM 群聊的最近消息历史，用于理解对话上下文背景。",
             "",
             "以下情况你必须先调用此工具，不得直接向用户反问或要求澄清：",
             "- 用户使用了指代词却没说清楚指的是什么（如'这'、'那'、'上面说的'、'刚才提到的'、'这两家公司'等）",
@@ -88,20 +109,21 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
             "- 你不确定用户问题的背景或主语时",
             "",
             "调用此工具后你会获得最近 N 条消息，用于还原上下文再给出回答。",
-            "groupId 从会话元数据 group_channel 字段中解析（格式：agent:main:xgim:group:<groupId>）。",
+            "groupId 必须从会话元数据 group_channel 字段中解析，当且仅当其前缀为 agent:main:xg_cwork_im:group:<groupId> 时才可以调用本工具。",
             "",
             "【只有在以下情况才可以不调用】：用户的问题明确且自洽，不依赖任何历史对话。",
         ].join("\n"),
         parameters: GroupHistoryParams,
         async execute(_toolCallId: string, params: Static<typeof GroupHistoryParams>) {
             const limit = params.limit ?? 10;
-            const { groupId } = params;
+            const { groupId, accountId } = params;
 
             console.log(`[cwork_im][tool] xg_cwork_im_get_group_chat_history called: groupId=${groupId} limit=${limit}`);
 
             let identity: BotIdentity;
             try {
-                identity = await getToken(config);
+                const accountConfig = resolveAccountConfig(config, accountId);
+                identity = await getToken(accountConfig);
                 console.log(`[cwork_im][tool] token acquired for userId=${identity.userId}`);
             } catch (err: unknown) {
                 return jsonResult({
@@ -113,8 +135,11 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
 
             let messages: WsMessageParams[];
             try {
-                messages = await fetchGroupHistory(config, identity.token, groupId, limit);
-                console.log(`[cwork_im][tool] fetched ${messages.length} messages from group ${groupId}`);
+                const accountConfig = resolveAccountConfig(config, accountId);
+                messages = await fetchGroupHistory(accountConfig, identity.token, groupId, limit);
+                console.log(
+                    `[cwork_im][tool] fetched ${messages.length} messages from group ${groupId} using accountId=${accountId ?? "0"}`,
+                );
             } catch (err: unknown) {
                 return jsonResult({
                     ok: false,
@@ -127,8 +152,10 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
             const formatted = messages
                 .filter((m) => m.msgContent?.type === "text")
                 .map((m) => {
-                    const isBot = m.fromUserId === identity.userId;
-                    const sender = isBot ? "[AI]" : m.fromUserName || m.fromUserId;
+                    const senderId = m.userInfo?.id ?? "";
+                    const senderName = m.userInfo?.name || senderId || "未知用户";
+                    const isBot = senderId === identity.userId;
+                    const sender = isBot ? "[AI]" : senderName;
                     const ts = m.timestamp ?? m.msgSendTime ?? 0;
                     const time = new Date(ts).toLocaleTimeString("zh-CN", { hour12: false });
                     return `[${time}] ${sender}: ${m.msgContent.text}`;

package/src/send-group-message-tool.ts

@@ -14,6 +14,7 @@ import { jsonResult } from "openclaw/plugin-sdk";
 import { getToken } from "./auth.js";
 import { sendTextMessage } from "./send-service.js";
 import type { BotIdentity, XgImConfig } from "./types.js";
+import { resolveAccountConfig } from "./group-history-tool.js";
 
 // ─── 工具参数 Schema ─────────────────────────────────────────────────────────
 
@@ -21,6 +22,11 @@ const SendGroupMessageParams = Type.Object({
     groupId: Type.String({
         description: "目标群聊 ID（IM 系统的群组唯一标识符，即 groupId / gid）",
     }),
+    accountId: Type.Optional(
+        Type.String({
+            description: "（可选）要使用的 xg_cwork_im 账户下标（数字字符串，默认 0）",
+        }),
+    ),
     text: Type.String({
         description: "要发送的消息内容（纯文本）",
     }),
@@ -41,23 +47,26 @@ const SendGroupMessageParams = Type.Object({
 export function buildSendGroupMessageTool(config: XgImConfig): AnyAgentTool {
     return {
         name: "xg_cwork_im_send_group_message",
-        label: "发送群聊消息",
+        label: "【xg_cwork_im】发送群聊消息",
         description: [
-            "向指定 IM 群聊发送一条消息。",
+            "【仅限 xg_cwork_im 通道】向指定 IM 群聊发送一条消息。",
             "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
             "消息将以机器人身份发出，可选择 @ 特定用户。",
-            "groupId 为 IM 群组的唯一 ID（不是群名称）。",
+            "groupId 为 IM 群组的唯一 ID（不是群名称），通常从当前对话的 group_channel 字段中解析（格式：agent:main:xg_cwork_im:group:<groupId>）。",
         ].join("\n"),
         parameters: SendGroupMessageParams,
         async execute(_toolCallId: string, params: Static<typeof SendGroupMessageParams>) {
-            const { groupId, text, atUserIds = [] } = params;
+            const { groupId, text, atUserIds = [], accountId } = params;
 
             console.log(`[cwork_im][tool] xg_cwork_im_send_group_message called: groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);
 
             let identity: BotIdentity;
             try {
-                identity = await getToken(config);
-                console.log(`[cwork_im][tool] xg_cwork_im_send_group_message token acquired for userId=${identity.userId}`);
+                const accountConfig = resolveAccountConfig(config, accountId);
+                identity = await getToken(accountConfig);
+                console.log(
+                    `[cwork_im][tool] xg_cwork_im_send_group_message token acquired for userId=${identity.userId} using accountId=${accountId ?? "0"}`,
+                );
             } catch (err: unknown) {
                 return jsonResult({
                     ok: false,
@@ -66,8 +75,11 @@ export function buildSendGroupMessageTool(config: XgImConfig): AnyAgentTool {
             }
 
             try {
-                await sendTextMessage(config, identity.token, groupId, text, atUserIds);
-                console.log(`[cwork_im][tool] xg_cwork_im_send_group_message success: groupId=${groupId}`);
+                const accountConfig = resolveAccountConfig(config, accountId);
+                await sendTextMessage(accountConfig, identity.token, groupId, text, atUserIds);
+                console.log(
+                    `[cwork_im][tool] xg_cwork_im_send_group_message success: groupId=${groupId} using accountId=${accountId ?? "0"}`,
+                );
             } catch (err: unknown) {
                 return jsonResult({
                     ok: false,

package/src/send-service.ts

@@ -17,6 +17,8 @@ import type { GetLatestMsgListResponse, SendMessageBody, WsMessageParams, XgImCo
  * @param content    消息内容文本
  * @param atUserIds  需要 @ 的用户 ID 列表（可为空）
  * @param log        日志接口
+ * @param msgId      可选的业务消息 ID（用于覆盖/更新已有消息）
+ * @param reply      可选的被回复消息信息（用于在 IM 中建立“回复某条消息”的关联）
  */
 export async function sendTextMessage(
     config: XgImConfig,
@@ -25,6 +27,8 @@ export async function sendTextMessage(
     content: string,
     atUserIds: string[] = [],
     log?: Log,
+    msgId?: string,
+    reply?: SendMessageBody["reply"],
 ): Promise<void> {
     const url = `${config.baseUrl}/im/message/send`;
 
@@ -33,6 +37,8 @@ export async function sendTextMessage(
         groupId,
         text: content,
         ...(atUserIds.length > 0 ? { atUserIds } : {}),
+        ...(msgId ? { msgId } : {}),
+        ...(reply ? { reply } : {}),
     };
 
     log?.info(`[cwork_im:send] POST ${url} groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);

package/src/types.ts

@@ -110,8 +110,18 @@ export interface WsMessage {
 export interface WsMessageParams {
     msgId: string;
     groupId: string;
-    fromUserId: string;
-    fromUserName: string;
+    /** 发送人信息 */
+    userInfo: {
+        /** 发送人 ID */
+        id: string;
+        /** 发送人显示名 */
+        name: string;
+        /**
+         * 用户背景信息。
+         * - 若非空，需要透传给 AI（可能是一段 JSON 字符串）。
+         */
+        background?: string;
+    };
     msgContent: {
         text: string;
         type: string;
@@ -128,12 +138,38 @@ export interface WsMessageParams {
 // ─── 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 响应 */