@xgjktech/xg_cwork_im 1.0.7 → 1.0.9

package/src/group-history-tool.ts

@@ -8,7 +8,7 @@
 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 { toolJsonResult } from "./tool-json-result.js";
 import { getToken } from "./auth.js";
 import type { BotIdentity, WsMessageParams, XgImConfig } from "./types.js";
 
@@ -143,7 +143,7 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                 identity = await getToken(accountConfig);
                 console.log(`[cwork_im][tool] token acquired for userId=${identity.userId}`);
             } catch (err: unknown) {
-                return jsonResult({
+                return toolJsonResult({
                     ok: false,
                     error: `Failed to obtain access token: ${String(err)}`,
                     messages: [],
@@ -158,7 +158,7 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                     `[cwork_im][tool] fetched ${messages.length} messages from group ${groupId} using accountId=${accountId ?? "0"} userId=${userId ?? "N/A"}`,
                 );
             } catch (err: unknown) {
-                return jsonResult({
+                return toolJsonResult({
                     ok: false,
                     error: `Failed to fetch group history: ${String(err)}`,
                     messages: [],
@@ -167,7 +167,10 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
 
             // 格式化成对话摘要，方便 AI 理解
             const formatted = messages
-                .filter((m) => m.msgContent?.type === "text")
+                .filter((m) => {
+                    const t = m.msgContent?.type;
+                    return t === "text" || t === "file";
+                })
                 .map((m) => {
                     const senderId = m.userInfo?.id ?? "";
                     const senderName = m.userInfo?.name || senderId || "未知用户";
@@ -175,10 +178,22 @@ export function buildGroupHistoryTool(config: XgImConfig): AnyAgentTool {
                     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}`;
+                    const c = m.msgContent;
+                    const body =
+                        c?.type === "file" && c.files?.length
+                            ? [
+                                c.text?.trim(),
+                                `[附件 ${c.files.length} 个: ${c.files
+                                    .map((f) => f.name?.trim() || f.fileId || "文件")
+                                    .join("、")}]`,
+                            ]
+                                .filter(Boolean)
+                                .join(" ")
+                            : (c?.text ?? "");
+                    return `[${time}] ${sender}: ${body}`;
                 });
 
-            return jsonResult({
+            return toolJsonResult({
                 ok: true,
                 groupId,
                 count: formatted.length,

package/src/inbound-media-local.ts

@@ -0,0 +1,159 @@
+/**
+ * 入站附件：可选落盘到当前 Agent workspace 下指定子目录（相对路径）。
+ *
+ * 目录约定：{subdir}/{userId}/{YYYY-MM-DD}/{stem}_{HHmmssmmm}{ext}
+ * 时间取写入时的本地时区。
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { Log } from "./auth.js";
+import { downloadMediaBuffer, resolveMaxAttachmentBytes } from "./resource-file.js";
+import type { MsgFileVO, XgImConfig } from "./types.js";
+
+/** 校验：非空、相对路径、不含 `..` 段 */
+export function normalizeInboundWorkspaceSubdir(subdir: string): string | null {
+    const t = subdir.trim().replace(/\\/g, "/");
+    if (!t || t === "." || t === "..") return null;
+    const parts = t.split("/").filter(Boolean);
+    for (const p of parts) {
+        if (p === "..") return null;
+    }
+    if (path.isAbsolute(t)) return null;
+    return parts.join("/");
+}
+
+export function resolveAgentWorkspaceDirFromRuntime(rt: unknown, cfg: OpenClawConfig): string | undefined {
+    const agent = (rt as { agent?: { resolveAgentWorkspaceDir?: (c: OpenClawConfig) => unknown } })?.agent;
+    const fn = agent?.resolveAgentWorkspaceDir;
+    if (typeof fn !== "function") return undefined;
+    try {
+        const out = fn(cfg);
+        if (typeof out === "string" && out.trim()) return path.resolve(out.trim());
+    } catch {
+        /* ignore */
+    }
+    return undefined;
+}
+
+export async function ensureAgentWorkspaceFromRuntime(rt: unknown, cfg: OpenClawConfig): Promise<void> {
+    const agent = (rt as { agent?: { ensureAgentWorkspace?: (c: OpenClawConfig) => Promise<void> } })?.agent;
+    const fn = agent?.ensureAgentWorkspace;
+    if (typeof fn !== "function") return;
+    try {
+        await fn(cfg);
+    } catch {
+        /* 落盘前仍会 mkdir，不阻断 */
+    }
+}
+
+function sanitizeUserIdForPath(id: string): string {
+    const t = id.trim();
+    if (/^-?\d+$/.test(t) && t.length <= 32) return t;
+    const safe = t.replace(/[^\w.-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+    return safe.slice(0, 64) || "unknown";
+}
+
+function formatDateFolderLocal(d: Date): string {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+
+/** `HHmmss` + 三位毫秒，如 `120459237` */
+export function formatInboundTimeSuffix(d: Date): string {
+    const h = String(d.getHours()).padStart(2, "0");
+    const min = String(d.getMinutes()).padStart(2, "0");
+    const s = String(d.getSeconds()).padStart(2, "0");
+    const ms = String(d.getMilliseconds()).padStart(3, "0");
+    return `${h}${min}${s}${ms}`;
+}
+
+const MAX_STEM_LEN = 120;
+
+function sanitizeStem(stem: string): string {
+    const s = stem
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^\.+|\.+$/g, "")
+        .trim();
+    const out = s || "file";
+    return out.length > MAX_STEM_LEN ? out.slice(0, MAX_STEM_LEN) : out;
+}
+
+/** `report_120459237.pdf` */
+export function buildInboundStoredFilename(originalFilename: string, at: Date): string {
+    const base = path.basename(originalFilename) || "file";
+    const ext = path.extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    const suffix = formatInboundTimeSuffix(at);
+    return `${sanitizeStem(stem)}_${suffix}${ext.toLowerCase()}`;
+}
+
+/**
+ * 将入站附件下载到 workspace 下子目录；失败项保留原 URL。
+ */
+export async function saveInboundFilesToWorkspace(args: {
+    rt: unknown;
+    cfg: OpenClawConfig;
+    config: XgImConfig;
+    workspaceSubdir: string;
+    senderUserId: string | undefined;
+    fileItems: MsgFileVO[];
+    log?: Log;
+}): Promise<MsgFileVO[]> {
+    const { rt, cfg, config, workspaceSubdir, senderUserId, fileItems, log } = args;
+    const normalized = normalizeInboundWorkspaceSubdir(workspaceSubdir);
+    if (!normalized || fileItems.length === 0) return fileItems;
+
+    const workspaceRoot = resolveAgentWorkspaceDirFromRuntime(rt, cfg);
+    if (!workspaceRoot) {
+        log?.warn?.(
+            "[cwork_im:inbound-local] resolveAgentWorkspaceDir unavailable, skip inbound download; keep remote URLs",
+        );
+        return fileItems;
+    }
+
+    await ensureAgentWorkspaceFromRuntime(rt, cfg);
+
+    const maxBytes = resolveMaxAttachmentBytes(config);
+    const userSeg = sanitizeUserIdForPath(senderUserId ?? "unknown");
+    const relParts = normalized.split("/");
+
+    const out: MsgFileVO[] = [];
+    for (const item of fileItems) {
+        const srcUrl = item.url?.trim();
+        if (!srcUrl) {
+            out.push(item);
+            continue;
+        }
+        const now = new Date();
+        const dateFolder = formatDateFolderLocal(now);
+        const localName = buildInboundStoredFilename(item.name?.trim() || "file", now);
+        const dir = path.join(workspaceRoot, ...relParts, userSeg, dateFolder);
+        const absPath = path.join(dir, localName);
+
+        try {
+            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}`);
+            out.push({
+                ...item,
+                url: fileUrl,
+                size: buffer.length,
+                name: localName,
+            });
+        } catch (e: unknown) {
+            log?.warn?.(
+                `[cwork_im:inbound-local] download/save failed, keep original URL: ${String(e)} ref=${srcUrl.slice(0, 80)}`,
+            );
+            out.push(item);
+        }
+    }
+    return out;
+}

package/src/resource-file.ts

@@ -0,0 +1,253 @@
+/**
+ * 资源中心整文件上传 + OpenClaw deliver 媒体 URL 拉取
+ *
+ * 上传地址固定为 `baseUrl + /file/upDownload/uploadWholeFile`，与 IM 同域，使用与发消息相同的 access-token。
+ */
+
+import axios from "axios";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Log } from "./auth.js";
+
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+
+/** 整文件上传接口路径（拼在 channels.xg_cwork_im.baseUrl 上） */
+export const RESOURCE_UPLOAD_PATH = "/file/upDownload/uploadWholeFile";
+
+export function resolveResourceUploadUrl(baseUrl: string): string {
+    const b = baseUrl.trim();
+    if (!b) throw new Error("[cwork_im] baseUrl is required for resource upload");
+    return new URL(RESOURCE_UPLOAD_PATH, b.endsWith("/") ? b : `${b}/`).href;
+}
+
+/** 从上传接口 JSON 中解析 fileId（兼容常见嵌套 data） */
+export function extractFileIdFromUploadResponse(data: unknown): string | undefined {
+    if (data == null) return undefined;
+    if (typeof data === "string" && data.trim().length > 0) return data.trim();
+    if (typeof data !== "object") return undefined;
+    const o = data as Record<string, unknown>;
+    for (const key of ["fileId", "id", "resourceId", "file_id"]) {
+        const v = o[key];
+        if (typeof v === "string" && v.length > 0) return v;
+    }
+    if (o.data != null) {
+        const nested = extractFileIdFromUploadResponse(o.data);
+        if (nested) return nested;
+    }
+    return undefined;
+}
+
+export function formatFromFilename(filename: string): string {
+    const ext = path.extname(filename).replace(/^\./, "").toLowerCase();
+    if (ext && ext.length <= 16 && /^[a-z0-9]+$/i.test(ext)) return ext;
+    return "bin";
+}
+
+export function displayNameFromUrl(url: string): string {
+    try {
+        if (url.startsWith("file://")) {
+            return path.basename(fileURLToPath(url)) || "file";
+        }
+        const u = new URL(url);
+        const seg = path.basename(u.pathname) || "attachment";
+        return seg.split("?")[0] || "attachment";
+    } catch {
+        return "attachment";
+    }
+}
+
+/** 日志用：截断过长路径/URL */
+export function summarizeMediaRef(ref: string, maxLen = 160): string {
+    const t = ref.trim().replace(/\s+/g, " ");
+    if (t.length <= maxLen) return t;
+    return `${t.slice(0, maxLen)}…(len=${t.length})`;
+}
+
+function isHttpOrHttps(ref: string): boolean {
+    try {
+        const u = new URL(ref.trim());
+        return u.protocol === "http:" || u.protocol === "https:";
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * 将字符串解析为可交给 readFile 的本机路径（兼容 Windows / macOS / Linux）。
+ * - 使用当前进程的 path.isAbsolute（各 OS 语义正确）。
+ * - Windows：Git Bash / MSYS 的 `/c/Users/...`、Cygwin `/cygdrive/c/...`。
+ * - 非 Windows：若传入 `D:\...` 形式仍做一次规范化（多用于日志/失败提示，读文件通常会失败）。
+ */
+export function resolveLocalFsPath(ref: string): { fsPath: string; via: string } | null {
+    const raw = ref.trim();
+    if (!raw) return null;
+
+    if (process.platform === "win32") {
+        // MSYS/Git Bash: /c/Users/foo → C:\Users\foo（要求 /<盘符>/ 后仍有路径，避免误伤 /Users）
+        const msys = /^\/([a-zA-Z])\/(.+)$/.exec(raw.replace(/\\/g, "/"));
+        if (msys) {
+            const letter = msys[1].toUpperCase();
+            const rest = msys[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "git-bash-msys" };
+        }
+        const cyg = /^\/cygdrive\/([a-zA-Z])\/(.+)$/i.exec(raw.replace(/\\/g, "/"));
+        if (cyg) {
+            const letter = cyg[1].toUpperCase();
+            const rest = cyg[2].split("/").join(path.win32.sep);
+            const fsPath = path.win32.normalize(`${letter}:${path.win32.sep}${rest}`);
+            return { fsPath, via: "cygwin" };
+        }
+    }
+
+    if (path.isAbsolute(raw)) {
+        return { fsPath: path.normalize(raw), via: `native-${process.platform}` };
+    }
+
+    // Linux/macOS 上 WSL 互操作常见：/mnt/c/... 已是 posix 绝对路径，上面已命中
+
+    if (process.platform !== "win32" && /^[a-zA-Z]:[/\\]/.test(raw)) {
+        return { fsPath: path.win32.normalize(raw), via: "win-style-path" };
+    }
+
+    return null;
+}
+
+async function readLocalFsIntoBuffer(fsPath: string, maxBytes: number, log?: Log): Promise<{ buffer: Buffer; filename: string }> {
+    const buffer = await readFile(fsPath);
+    if (buffer.length > maxBytes) {
+        throw new Error(`local file size ${buffer.length} exceeds maxAttachmentBytes=${maxBytes}`);
+    }
+    const filename = path.basename(fsPath) || "file";
+    log?.info(`[cwork_im:media] local ok bytes=${buffer.length} name=${filename}`);
+    return { buffer, filename };
+}
+
+export async function downloadMediaBuffer(
+    url: string,
+    maxBytes: number,
+    log?: Log,
+): Promise<{ buffer: Buffer; filename: string }> {
+    const raw = url.trim();
+    log?.info(`[cwork_im:media] resolve ref=${summarizeMediaRef(raw)}`);
+
+    if (raw.startsWith("file://")) {
+        let fsPath: string;
+        try {
+            fsPath = fileURLToPath(raw);
+        } catch (e) {
+            log?.error(`[cwork_im:media] invalid file:// URL: ${summarizeMediaRef(raw)} ${String(e)}`);
+            throw e;
+        }
+        log?.info(`[cwork_im:media] read file:// -> ${summarizeMediaRef(fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(fsPath, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed file:// ${summarizeMediaRef(fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
+    if (isHttpOrHttps(raw)) {
+        log?.info(`[cwork_im:media] GET ${summarizeMediaRef(raw)}`);
+        try {
+            const res = await axios.get(raw, {
+                responseType: "arraybuffer",
+                timeout: 120_000,
+                maxContentLength: maxBytes,
+                maxBodyLength: maxBytes,
+                validateStatus: (s) => s >= 200 && s < 300,
+            });
+            const buffer = Buffer.from(res.data as ArrayBuffer);
+            let filename = displayNameFromUrl(raw);
+            const cd = res.headers["content-disposition"];
+            if (typeof cd === "string") {
+                const m = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(cd);
+                if (m?.[1]) {
+                    try {
+                        filename = decodeURIComponent(m[1].trim());
+                    } catch {
+                        filename = m[1].trim();
+                    }
+                }
+            }
+            log?.info(`[cwork_im:media] http ok bytes=${buffer.length} name=${filename}`);
+            return { buffer, filename };
+        } catch (err: unknown) {
+            const detail = axios.isAxiosError(err)
+                ? `${err.message}${err.code ? ` axiosCode=${err.code}` : ""}${err.response?.status != null ? ` httpStatus=${err.response.status}` : ""}`
+                : String(err);
+            log?.error(`[cwork_im:media] http failed ref=${summarizeMediaRef(raw)}: ${detail}`);
+            throw err;
+        }
+    }
+
+    const resolved = resolveLocalFsPath(raw);
+    if (resolved) {
+        log?.info(`[cwork_im:media] local via=${resolved.via} -> ${summarizeMediaRef(resolved.fsPath)}`);
+        try {
+            return await readLocalFsIntoBuffer(resolved.fsPath, maxBytes, log);
+        } catch (err: unknown) {
+            log?.error(`[cwork_im:media] readFile failed ${summarizeMediaRef(resolved.fsPath)}: ${String(err)}`);
+            throw err;
+        }
+    }
+
+    const hint =
+        "请使用 http(s)、file://（三系统通用），或本机绝对路径：Windows C:\\\\... / UNC；macOS/Linux /Users、/home、/mnt/c/...（WSL）；Windows 下 Git Bash 可用 /c/...";
+    log?.error(`[cwork_im:media] unsupported ref=${summarizeMediaRef(raw)} (${hint})`);
+    throw new Error(`[cwork_im] 无法读取媒体（${hint}）: ${summarizeMediaRef(raw)}`);
+}
+
+/**
+ * multipart 上传整文件，返回 fileId 与字节数。
+ */
+export async function uploadWholeResourceFile(args: {
+    fileUploadUrl: string;
+    token: string;
+    buffer: Buffer;
+    filename: string;
+    formField: string;
+    log?: Log;
+}): Promise<{ fileId: string; size: number }> {
+    const { fileUploadUrl, token, buffer, filename, formField, log } = args;
+    const blob = new Blob([new Uint8Array(buffer)]);
+    const form = new FormData();
+    form.append(formField, blob, filename);
+
+    log?.info(`[cwork_im:upload] POST ${fileUploadUrl} field=${formField} name=${filename} bytes=${buffer.length}`);
+
+    const res = await fetch(fileUploadUrl, {
+        method: "POST",
+        headers: {
+            "access-token": token,
+        },
+        body: form,
+    });
+
+    const rawText = await res.text();
+    let json: unknown;
+    try {
+        json = rawText ? JSON.parse(rawText) : undefined;
+    } catch {
+        json = undefined;
+    }
+
+    if (!res.ok) {
+        log?.error(`[cwork_im:upload] HTTP ${res.status} body=${rawText.slice(0, 500)}`);
+        throw new Error(`upload HTTP ${res.status}: ${rawText.slice(0, 500)}`);
+    }
+
+    const fileId = extractFileIdFromUploadResponse(json ?? rawText);
+    if (!fileId) {
+        log?.error(`[cwork_im:upload] missing fileId in body=${rawText.slice(0, 500)}`);
+        throw new Error(`upload response missing fileId: ${rawText.slice(0, 500)}`);
+    }
+
+    return { fileId, size: buffer.length };
+}
+
+export function resolveMaxAttachmentBytes(config: { maxAttachmentBytes?: number }): number {
+    return config.maxAttachmentBytes ?? DEFAULT_MAX_BYTES;
+}

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

@@ -1,98 +1,98 @@
-/**
- * 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";
-import { resolveAccountConfig } from "./group-history-tool.js";
-
-// ─── 工具参数 Schema ─────────────────────────────────────────────────────────
-
-const SendGroupMessageParams = Type.Object({
-    groupId: Type.String({
-        description: "目标群聊 ID（IM 系统的群组唯一标识符，即 groupId / gid）",
-    }),
-    accountId: Type.Optional(
-        Type.String({
-            description:
-                "（可选）要使用的 xg_cwork_im 账户 ID（即 accounts 的 key，例如 main/orchestrator）。",
-        }),
-    ),
-    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: "【xg_cwork_im】发送群聊消息",
-        description: [
-            "【仅限 xg_cwork_im 通道】向指定 IM 群聊发送一条消息。",
-            "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
-            "消息将以机器人身份发出，可选择 @ 特定用户。",
-            "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 = [], accountId } = params;
-
-            console.log(`[cwork_im][tool] xg_cwork_im_send_group_message called: groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);
-
-            let identity: BotIdentity;
-            try {
-                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,
-                    error: `Failed to obtain access token: ${String(err)}`,
-                });
-            }
-
-            try {
-                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,
-                    error: `Failed to send message to group ${groupId}: ${String(err)}`,
-                });
-            }
-
-            return jsonResult({
-                ok: true,
-                groupId,
-                sentBy: identity.userId,
-            });
-        },
-    };
-}
+/**
+ * XG-IM 发送群消息工具（供 AI 按需调用）
+ *
+ * 适用场景：
+ * - Cron 定时任务主动推送通知
+ * - AI 分析后需要主动发起提醒（无需用户先 @ 机器人）
+ *
+ * 通过 api.registerTool() 注入，工具内部自动获取机器人 token，AI 无需感知鉴权细节。
+ */
+
+import { Type, type Static } from "@sinclair/typebox";
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { toolJsonResult } from "./tool-json-result.js";
+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 ─────────────────────────────────────────────────────────
+
+const SendGroupMessageParams = Type.Object({
+    groupId: Type.String({
+        description: "目标群聊 ID（IM 系统的群组唯一标识符，即 groupId / gid）",
+    }),
+    accountId: Type.Optional(
+        Type.String({
+            description:
+                "（可选）要使用的 xg_cwork_im 账户 ID（即 accounts 的 key，例如 main/orchestrator）。",
+        }),
+    ),
+    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: "【xg_cwork_im】发送群聊消息",
+        description: [
+            "【仅限 xg_cwork_im 通道】向指定 IM 群聊发送一条消息。",
+            "适用于定时任务主动推送通知、AI 分析后发起提醒等场景。",
+            "消息将以机器人身份发出，可选择 @ 特定用户。",
+            "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 = [], accountId } = params;
+
+            console.log(`[cwork_im][tool] xg_cwork_im_send_group_message called: groupId=${groupId} atUsers=${JSON.stringify(atUserIds)}`);
+
+            let identity: BotIdentity;
+            try {
+                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 toolJsonResult({
+                    ok: false,
+                    error: `Failed to obtain access token: ${String(err)}`,
+                });
+            }
+
+            try {
+                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 toolJsonResult({
+                    ok: false,
+                    error: `Failed to send message to group ${groupId}: ${String(err)}`,
+                });
+            }
+
+            return toolJsonResult({
+                ok: true,
+                groupId,
+                sentBy: identity.userId,
+            });
+        },
+    };
+}