@xgjktech/xg_cwork_im 1.0.0

package/src/group-history-tool.ts

@@ -0,0 +1,145 @@
+/**
+ * XG-IM 群聊历史记录工具（供 AI 按需调用）
+ *
+ * 通过 OpenClaw 的 api.registerTool() 注入，让 AI 在感知到需要上下文时
+ * 主动拉取群聊最近 N 条历史消息，而不是每次收到 @ 都强行拉取。
+ */
+
+import axios from "axios";
+import { Type, type Static } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { getToken } from "./auth.js";
+import type { BotIdentity, WsMessageParams, XgImConfig } from "./types.js";
+
+// ─── 工具参数 Schema ─────────────────────────────────────────────────────────
+
+const GroupHistoryParams = Type.Object({
+    groupId: Type.String({
+        description: "群聊 ID，即当前消息来自的群组唯一标识符",
+    }),
+    limit: Type.Optional(
+        Type.Number({
+            description: "需要获取的消息条数（5~30），默认 10",
+            minimum: 1,
+            maximum: 30,
+            default: 10,
+        }),
+    ),
+});
+
+// ─── 内部 HTTP 工具 ──────────────────────────────────────────────────────────
+
+/** 从 OpenClaw 配置中提取 xg_cwork_im 配置（支持多账户取第一个） */
+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;
+
+    // 如果有多账户，把 accounts[0] 的 appKey 合并到顶层（用于查询历史）
+    if (raw.accounts && raw.accounts.length > 0) {
+        const first = raw.accounts[0];
+        return { ...raw, ...first };
+    }
+    return raw;
+}
+
+/** 调用 IM 接口拉取群聊最近 N 条消息 */
+async function fetchGroupHistory(
+    config: XgImConfig,
+    token: string,
+    groupId: string,
+    limit: number,
+): Promise<WsMessageParams[]> {
+    const url = `${config.baseUrl}/im/message/getLatestMsgListForAI`;
+
+    const res = await axios.get<{
+        resultCode: number;
+        message?: string;
+        data?: WsMessageParams[];
+    }>(url, {
+        params: { groupId, msgCount: limit },
+        headers: { "access-token": token },
+        timeout: 8_000,
+    });
+
+    const body = res.data;
+    if ((body.resultCode !== 1 && body.resultCode !== 200) || !Array.isArray(body.data)) {
+        return [];
+    }
+    return body.data;
+}
+
+// ─── 工具构建函数（直接传 config，而非 factory 模式）──────────────────────────
+
+/**
+ * 构建群聊历史工具对象（使用注册时已知的 config，绕开 factory 工厂模式的命名限制）。
+ * 由 index.ts 在 register() 里调用，并将构建好的工具对象静态地传给 api.registerTool(tool)。
+ */
+export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
+    return {
+        name: "xg_cwork_im_get_group_chat_history",
+        label: "获取群聊历史记录",
+        description: [
+            "【必须遵守】获取此 IM 群聊的最近消息历史，用于理解对话上下文背景。",
+            "",
+            "以下情况你必须先调用此工具，不得直接向用户反问或要求澄清：",
+            "- 用户使用了指代词却没说清楚指的是什么（如'这'、'那'、'上面说的'、'刚才提到的'、'这两家公司'等）",
+            "- 用户的问题依赖之前的对话才能正确理解（如'对吗'、'怎么查的'、'分析一下'但没给出主语）",
+            "- 你不确定用户问题的背景或主语时",
+            "",
+            "调用此工具后你会获得最近 N 条消息，用于还原上下文再给出回答。",
+            "groupId 从会话元数据 group_channel 字段中解析（格式：agent:main:xgim:group:<groupId>）。",
+            "",
+            "【只有在以下情况才可以不调用】：用户的问题明确且自洽，不依赖任何历史对话。",
+        ].join("\n"),
+        parameters: GroupHistoryParams,
+        async execute(_toolCallId: string, params: Static<typeof GroupHistoryParams>) {
+            const limit = params.limit ?? 10;
+            const { groupId } = 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);
+                console.log(`[cwork_im][tool] token acquired for userId=${identity.userId}`);
+            } catch (err: unknown) {
+                return jsonResult({
+                    ok: false,
+                    error: `Failed to obtain access token: ${String(err)}`,
+                    messages: [],
+                });
+            }
+
+            let messages: WsMessageParams[];
+            try {
+                messages = await fetchGroupHistory(config, identity.token, groupId, limit);
+                console.log(`[cwork_im][tool] fetched ${messages.length} messages from group ${groupId}`);
+            } catch (err: unknown) {
+                return jsonResult({
+                    ok: false,
+                    error: `Failed to fetch group history: ${String(err)}`,
+                    messages: [],
+                });
+            }
+
+            // 格式化成对话摘要，方便 AI 理解
+            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 ts = m.timestamp ?? m.msgSendTime ?? 0;
+                    const time = new Date(ts).toLocaleTimeString("zh-CN", { hour12: false });
+                    return `[${time}] ${sender}: ${m.msgContent.text}`;
+                });
+
+            return jsonResult({
+                ok: true,
+                groupId,
+                count: formatted.length,
+                messages: formatted,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,85 @@
+/**
+ * XG-IM 发送群消息工具（供 AI 按需调用）
+ *
+ * 适用场景：
+ * - Cron 定时任务主动推送通知
+ * - AI 分析后需要主动发起提醒（无需用户先 @ 机器人）
+ *
+ * 通过 api.registerTool() 注入，工具内部自动获取机器人 token，AI 无需感知鉴权细节。
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { getToken } from "./auth.js";
+import { sendTextMessage } from "./send-service.js";
+import type { BotIdentity, XgImConfig } from "./types.js";
+
+// ─── 工具参数 Schema ─────────────────────────────────────────────────────────
+
+const SendGroupMessageParams = Type.Object({
+    groupId: Type.String({
+        description: "目标群聊 ID（IM 系统的群组唯一标识符，即 groupId / gid）",
+    }),
+    text: Type.String({
+        description: "要发送的消息内容（纯文本）",
+    }),
+    atUserIds: Type.Optional(
+        Type.Array(Type.String(), {
+            description: "需要 @ 的用户 ID 列表，可为空数组",
+        }),
+    ),
+});
+
+// ─── 工具构建函数 ─────────────────────────────────────────────────────────────
+
+/**
+ * 构建发送群消息工具对象。
+ * 由 index.ts 在 register() 里调用，config 在注册时捕获进闭包，
+ * 工具执行时自动调用 getToken(config) 获取机器人 token。
+ */
+export function buildSendGroupMessageTool(config: XgImConfig): AnyAgentTool {
+    return {
+        name: "xg_cwork_im_send_group_message",
+        label: "发送群聊消息",
+        description: [
+            "向指定 IM 群聊发送一条消息。",
+            "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
+            "消息将以机器人身份发出，可选择 @ 特定用户。",
+            "groupId 为 IM 群组的唯一 ID（不是群名称）。",
+        ].join("\n"),
+        parameters: SendGroupMessageParams,
+        async execute(_toolCallId: string, params: Static<typeof SendGroupMessageParams>) {
+            const { groupId, text, atUserIds = [] } = 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}`);
+            } catch (err: unknown) {
+                return jsonResult({
+                    ok: false,
+                    error: `Failed to obtain access token: ${String(err)}`,
+                });
+            }
+
+            try {
+                await sendTextMessage(config, identity.token, groupId, text, atUserIds);
+                console.log(`[cwork_im][tool] xg_cwork_im_send_group_message success: groupId=${groupId}`);
+            } catch (err: unknown) {
+                return jsonResult({
+                    ok: false,
+                    error: `Failed to send message to group ${groupId}: ${String(err)}`,
+                });
+            }
+
+            return jsonResult({
+                ok: true,
+                groupId,
+                sentBy: identity.userId,
+            });
+        },
+    };
+}

package/src/send-service.ts

@@ -0,0 +1,62 @@
+/**
+ * XG-IM 消息发送模块
+ *
+ * 调用 IM 接口将 AI 回复发送到指定群聊，并 @ 原始发送者。
+ */
+
+import axios from "axios";
+import type { Log } from "./auth.js";
+import type { GetLatestMsgListResponse, SendMessageBody, WsMessageParams, XgImConfig } from "./types.js";
+
+/**
+ * 发送文本消息到指定 IM 群聊。
+ *
+ * @param config     插件配置
+ * @param token      鉴权 token
+ * @param groupId    目标群聊 ID（gid / groupId）
+ * @param content    消息内容文本
+ * @param atUserIds  需要 @ 的用户 ID 列表（可为空）
+ * @param log        日志接口
+ */
+export async function sendTextMessage(
+    config: XgImConfig,
+    token: string,
+    groupId: string,
+    content: string,
+    atUserIds: string[] = [],
+    log?: Log,
+): Promise<void> {
+    const url = `${config.baseUrl}/im/message/send`;
+
+    const body: SendMessageBody = {
+        type: "TEXT",
+        groupId,
+        text: content,
+        ...(atUserIds.length > 0 ? { atUserIds } : {}),
+    };
+
+    log?.info(`[cwork_im:send] POST ${url} groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);
+    if (config.debug) {
+        log?.debug?.(`[cwork_im:send] Request body: ${JSON.stringify(body)}`);
+    }
+
+    try {
+        const res = await axios.post(url, body, {
+            headers: {
+                "Content-Type": "application/json",
+                "access-token": token,
+            },
+            timeout: 10_000,
+        });
+
+        log?.info(`[cwork_im:send] Response status=${res.status}`);
+        if (config.debug) {
+            log?.debug?.(`[cwork_im:send] Response body: ${JSON.stringify(res.data)}`);
+        }
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log?.error(`[cwork_im:send] Failed to send message to groupId=${groupId}: ${msg}`);
+        throw err;
+    }
+}
+

package/src/types.ts

@@ -0,0 +1,163 @@
+/**
+ * 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;
+}
+
+// ─── 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;
+    fromUserId: string;
+    fromUserName: 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 SendMessageBody {
+    type: "TEXT" | "RICH_TEXT" | "VOICE";
+    groupId?: string;
+    toUserId?: string;
+    text: string;
+    atUserIds?: string[];
+}
+
+/** 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 };