@kirigaya/openclaw-onebot 1.0.0

package/dist/handlers/process-inbound.js

@@ -0,0 +1,224 @@
+/**
+ * 入站消息处理
+ */
+import { getOneBotConfig } from "../config.js";
+import { getRawText, isMentioned } from "../message.js";
+import { sendPrivateMsg, sendGroupMsg, sendPrivateImage, sendGroupImage, setMsgEmojiLike, } from "../connection.js";
+import { setActiveReplyTarget, clearActiveReplyTarget } from "../reply-context.js";
+import { loadPluginSdk, getSdk } from "../sdk.js";
+const DEFAULT_HISTORY_LIMIT = 20;
+export const sessionHistories = new Map();
+export async function processInboundMessage(api, msg) {
+    await loadPluginSdk();
+    const { buildPendingHistoryContextFromMap, recordPendingHistoryEntry, clearHistoryEntriesIfEnabled } = getSdk();
+    const runtime = api.runtime;
+    if (!runtime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+        api.logger?.warn?.("[onebot] runtime.channel.reply not available");
+        return;
+    }
+    const config = getOneBotConfig(api);
+    if (!config) {
+        api.logger?.warn?.("[onebot] not configured");
+        return;
+    }
+    const cfg = api.config;
+    const messageText = getRawText(msg);
+    if (!messageText?.trim()) {
+        api.logger?.info?.(`[onebot] ignoring empty message`);
+        return;
+    }
+    const isGroup = msg.message_type === "group";
+    const selfId = msg.self_id ?? 0;
+    const requireMention = cfg?.channels?.onebot?.requireMention ?? true;
+    if (isGroup && requireMention && !isMentioned(msg, selfId)) {
+        api.logger?.info?.(`[onebot] ignoring group message without @mention`);
+        return;
+    }
+    const userId = msg.user_id;
+    const groupId = msg.group_id;
+    const sessionId = isGroup
+        ? `onebot:group:${groupId}`.toLowerCase()
+        : `onebot:${userId}`.toLowerCase();
+    const route = runtime.channel.routing?.resolveAgentRoute?.({
+        cfg,
+        sessionKey: sessionId,
+        channel: "onebot",
+        accountId: config.accountId ?? "default",
+    }) ?? { agentId: "main" };
+    const storePath = runtime.channel.session?.resolveStorePath?.(cfg?.session?.store, {
+        agentId: route.agentId,
+    }) ?? "";
+    const envelopeOptions = runtime.channel.reply?.resolveEnvelopeFormatOptions?.(cfg) ?? {};
+    const chatType = isGroup ? "group" : "direct";
+    const fromLabel = String(userId);
+    const formattedBody = runtime.channel.reply?.formatInboundEnvelope?.({
+        channel: "OneBot",
+        from: fromLabel,
+        timestamp: Date.now(),
+        body: messageText,
+        chatType,
+        sender: { name: fromLabel, id: String(userId) },
+        envelope: envelopeOptions,
+    }) ?? { content: [{ type: "text", text: messageText }] };
+    const body = buildPendingHistoryContextFromMap
+        ? buildPendingHistoryContextFromMap({
+            historyMap: sessionHistories,
+            historyKey: sessionId,
+            limit: DEFAULT_HISTORY_LIMIT,
+            currentMessage: formattedBody,
+            formatEntry: (entry) => runtime.channel.reply?.formatInboundEnvelope?.({
+                channel: "OneBot",
+                from: fromLabel,
+                timestamp: entry.timestamp,
+                body: entry.body,
+                chatType,
+                senderLabel: entry.sender,
+                envelope: envelopeOptions,
+            }) ?? { content: [{ type: "text", text: entry.body }] },
+        })
+        : formattedBody;
+    if (recordPendingHistoryEntry) {
+        recordPendingHistoryEntry({
+            historyMap: sessionHistories,
+            historyKey: sessionId,
+            entry: {
+                sender: fromLabel,
+                body: messageText,
+                timestamp: Date.now(),
+                messageId: `onebot-${Date.now()}`,
+            },
+            limit: DEFAULT_HISTORY_LIMIT,
+        });
+    }
+    // 回复目标（参考 openclaw-feishu）：群聊用 group:群号，私聊用 user:用户号
+    // To / OriginatingTo / ConversationLabel 均表示「发送目标」，Agent 的 message 工具会据此选择 target
+    const replyTarget = isGroup ? `onebot:group:${groupId}` : `onebot:${userId}`;
+    const ctxPayload = {
+        Body: body,
+        RawBody: messageText,
+        From: isGroup ? `onebot:group:${groupId}` : `onebot:${userId}`,
+        To: replyTarget,
+        SessionKey: sessionId,
+        AccountId: config.accountId ?? "default",
+        ChatType: chatType,
+        ConversationLabel: replyTarget, // 与 Feishu 一致：表示会话/回复目标，群聊时为 group:群号，非 SenderId
+        SenderName: fromLabel,
+        SenderId: String(userId),
+        Provider: "onebot",
+        Surface: "onebot",
+        MessageSid: `onebot-${Date.now()}`,
+        Timestamp: Date.now(),
+        OriginatingChannel: "onebot",
+        OriginatingTo: replyTarget,
+        CommandAuthorized: true,
+        DeliveryContext: {
+            channel: "onebot",
+            to: replyTarget,
+            accountId: config.accountId ?? "default",
+        },
+        _onebot: { userId, groupId, isGroup },
+    };
+    if (runtime.channel.session?.recordInboundSession) {
+        await runtime.channel.session.recordInboundSession({
+            storePath,
+            sessionKey: sessionId,
+            ctx: ctxPayload,
+            updateLastRoute: !isGroup ? { sessionKey: sessionId, channel: "onebot", to: String(userId), accountId: config.accountId ?? "default" } : undefined,
+            onRecordError: (err) => api.logger?.warn?.(`[onebot] recordInboundSession: ${err}`),
+        });
+    }
+    if (runtime.channel.activity?.record) {
+        runtime.channel.activity.record({ channel: "onebot", accountId: config.accountId ?? "default", direction: "inbound" });
+    }
+    const onebotCfg = cfg?.channels?.onebot ?? {};
+    const thinkingEmojiId = onebotCfg.thinkingEmojiId ?? 60;
+    const userMessageId = msg.message_id;
+    let emojiAdded = false;
+    const clearEmojiReaction = async () => {
+        if (emojiAdded && userMessageId != null) {
+            try {
+                await setMsgEmojiLike(userMessageId, thinkingEmojiId, false);
+            }
+            catch { }
+            emojiAdded = false;
+        }
+    };
+    if (userMessageId != null) {
+        try {
+            await setMsgEmojiLike(userMessageId, thinkingEmojiId, true);
+            emojiAdded = true;
+        }
+        catch {
+            api.logger?.warn?.("[onebot] setMsgEmojiLike failed (maybe OneBot doesn't support it)");
+        }
+    }
+    api.logger?.info?.(`[onebot] dispatching message for session ${sessionId}`);
+    setActiveReplyTarget(replyTarget);
+    try {
+        await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg,
+            dispatcherOptions: {
+                deliver: async (payload, info) => {
+                    await clearEmojiReaction();
+                    const p = payload;
+                    const replyText = typeof p === "string" ? p : (p?.text ?? p?.body ?? "");
+                    const mediaUrl = typeof p === "string" ? undefined : (p?.mediaUrl ?? p?.mediaUrls?.[0]);
+                    const trimmed = (replyText || "").trim();
+                    if ((!trimmed || trimmed === "NO_REPLY" || trimmed.endsWith("NO_REPLY")) && !mediaUrl)
+                        return;
+                    const { userId: uid, groupId: gid, isGroup: ig } = ctxPayload._onebot || {};
+                    // 兜底：sessionId 格式 onebot:group:群号 为权威来源，某些实现 _onebot.groupId 可能为空
+                    const sessionKey = String(ctxPayload.SessionKey ?? sessionId);
+                    const groupMatch = sessionKey.match(/^onebot:group:(\d+)$/i);
+                    const effectiveIsGroup = groupMatch != null || Boolean(ig);
+                    const effectiveGroupId = (groupMatch ? parseInt(groupMatch[1], 10) : undefined) ?? gid;
+                    try {
+                        if (trimmed) {
+                            if (effectiveIsGroup && effectiveGroupId)
+                                await sendGroupMsg(effectiveGroupId, trimmed);
+                            else if (uid)
+                                await sendPrivateMsg(uid, trimmed);
+                        }
+                        if (mediaUrl) {
+                            if (effectiveIsGroup && effectiveGroupId)
+                                await sendGroupImage(effectiveGroupId, mediaUrl);
+                            else if (uid)
+                                await sendPrivateImage(uid, mediaUrl);
+                        }
+                        if (info.kind === "final" && clearHistoryEntriesIfEnabled) {
+                            clearHistoryEntriesIfEnabled({
+                                historyMap: sessionHistories,
+                                historyKey: sessionId,
+                                limit: DEFAULT_HISTORY_LIMIT,
+                            });
+                        }
+                    }
+                    catch (e) {
+                        api.logger?.error?.(`[onebot] deliver failed: ${e?.message}`);
+                    }
+                },
+                onError: async (err, info) => {
+                    api.logger?.error?.(`[onebot] ${info?.kind} reply failed: ${err}`);
+                    await clearEmojiReaction();
+                },
+            },
+            replyOptions: { disableBlockStreaming: true },
+        });
+    }
+    catch (err) {
+        await clearEmojiReaction();
+        api.logger?.error?.(`[onebot] dispatch failed: ${err?.message}`);
+        try {
+            const { userId: uid, groupId: gid, isGroup: ig } = ctxPayload._onebot || {};
+            if (ig && gid)
+                await sendGroupMsg(gid, `处理失败: ${err?.message?.slice(0, 80) || "未知错误"}`);
+            else if (uid)
+                await sendPrivateMsg(uid, `处理失败: ${err?.message?.slice(0, 80) || "未知错误"}`);
+        }
+        catch (_) { }
+    }
+    finally {
+        clearActiveReplyTarget();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenClaw OneBot Channel Plugin
+ *
+ * 将 OneBot v11 协议（QQ/Lagrange.Core/go-cqhttp）接入 OpenClaw Gateway。
+ *
+ * 发送逻辑（参照飞书实现）：
+ * - 由 OpenClaw 主包解析 `openclaw message send --channel onebot ...` 命令
+ * - 根据 --channel 查找已注册的 onebot 渠道，调用其 outbound.sendText / outbound.sendMedia
+ * - 不注册 Agent 工具，避免重复实现；Agent 回复时由 process-inbound 的 deliver 自动发送
+ */
+export default function register(api: any): void;

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * OpenClaw OneBot Channel Plugin
+ *
+ * 将 OneBot v11 协议（QQ/Lagrange.Core/go-cqhttp）接入 OpenClaw Gateway。
+ *
+ * 发送逻辑（参照飞书实现）：
+ * - 由 OpenClaw 主包解析 `openclaw message send --channel onebot ...` 命令
+ * - 根据 --channel 查找已注册的 onebot 渠道，调用其 outbound.sendText / outbound.sendMedia
+ * - 不注册 Agent 工具，避免重复实现；Agent 回复时由 process-inbound 的 deliver 自动发送
+ */
+import { OneBotChannelPlugin } from "./channel.js";
+import { registerService } from "./service.js";
+import { startImageTempCleanup } from "./connection.js";
+export default function register(api) {
+    globalThis.__onebotApi = api;
+    globalThis.__onebotGatewayConfig = api.config;
+    startImageTempCleanup();
+    api.registerChannel({ plugin: OneBotChannelPlugin });
+    if (typeof api.registerCli === "function") {
+        api.registerCli((ctx) => {
+            const prog = ctx.program;
+            if (prog && typeof prog.command === "function") {
+                const onebot = prog.command("onebot").description("OneBot 渠道配置");
+                onebot.command("setup").description("交互式配置 OneBot 连接参数").action(async () => {
+                    const { runOneBotSetup } = await import("./setup.js");
+                    await runOneBotSetup();
+                });
+            }
+        }, { commands: ["onebot"] });
+    }
+    registerService(api);
+    api.logger?.info?.("[onebot] plugin loaded");
+}

package/dist/load-script.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 动态加载用户脚本（支持 .js/.mjs/.ts/.mts）
+ * .ts/.mts 依赖 tsx 运行时
+ */
+export declare function loadScript(scriptPath: string): Promise<Record<string, unknown>>;

package/dist/load-script.js

@@ -0,0 +1,22 @@
+/**
+ * 动态加载用户脚本（支持 .js/.mjs/.ts/.mts）
+ * .ts/.mts 依赖 tsx 运行时
+ */
+import { resolve } from "path";
+import { pathToFileURL } from "url";
+import { extname } from "path";
+const TS_EXT = [".ts", ".mts"];
+export async function loadScript(scriptPath) {
+    const absPath = resolve(process.cwd(), scriptPath.trim());
+    const ext = extname(absPath).toLowerCase();
+    if (TS_EXT.includes(ext)) {
+        try {
+            await import("tsx/cjs");
+        }
+        catch {
+            throw new Error("执行 .ts/.mts 脚本需要安装 tsx 依赖：npm install tsx");
+        }
+    }
+    const url = pathToFileURL(absPath).href;
+    return import(url);
+}

package/dist/message.d.ts

@@ -0,0 +1,6 @@
+/**
+ * OneBot 消息解析
+ */
+import type { OneBotMessage } from "./types.js";
+export declare function getRawText(msg: OneBotMessage): string;
+export declare function isMentioned(msg: OneBotMessage, selfId: number): boolean;

package/dist/message.js

@@ -0,0 +1,24 @@
+/**
+ * OneBot 消息解析
+ */
+export function getRawText(msg) {
+    if (!msg)
+        return "";
+    if (typeof msg.raw_message === "string" && msg.raw_message) {
+        return msg.raw_message;
+    }
+    const arr = msg.message;
+    if (!Array.isArray(arr))
+        return "";
+    return arr
+        .filter((m) => m?.type === "text")
+        .map((m) => m?.data?.text ?? "")
+        .join("");
+}
+export function isMentioned(msg, selfId) {
+    const arr = msg.message;
+    if (!Array.isArray(arr))
+        return false;
+    const selfStr = String(selfId);
+    return arr.some((m) => m?.type === "at" && String(m?.data?.qq || m?.data?.id) === selfStr);
+}

package/dist/reply-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 当前回复目标上下文
+ * 当 process-inbound 处理群聊消息时设置，channel.sendMedia 可用其修正错误的 target
+ * （Agent 可能传入裸数字或 user:xxx，导致误发私聊）
+ */
+export declare function setActiveReplyTarget(to: string): void;
+export declare function clearActiveReplyTarget(): void;
+export declare function getActiveReplyTarget(): string | null;
+/**
+ * 若当前有活跃群聊回复目标，且传入的 to 可能被误判为私聊（裸数字或 user:xxx 与群号相同），则返回修正后的 target
+ */
+export declare function resolveTargetForReply(to: string): string;

package/dist/reply-context.js

@@ -0,0 +1,33 @@
+/**
+ * 当前回复目标上下文
+ * 当 process-inbound 处理群聊消息时设置，channel.sendMedia 可用其修正错误的 target
+ * （Agent 可能传入裸数字或 user:xxx，导致误发私聊）
+ */
+let activeReplyTarget = null;
+export function setActiveReplyTarget(to) {
+    activeReplyTarget = to;
+}
+export function clearActiveReplyTarget() {
+    activeReplyTarget = null;
+}
+export function getActiveReplyTarget() {
+    return activeReplyTarget;
+}
+/**
+ * 若当前有活跃群聊回复目标，且传入的 to 可能被误判为私聊（裸数字或 user:xxx 与群号相同），则返回修正后的 target
+ */
+export function resolveTargetForReply(to) {
+    const stored = activeReplyTarget;
+    if (!stored)
+        return to;
+    const m = stored.match(/group:(\d+)$/i) || stored.match(/onebot:group:(\d+)$/i);
+    if (!m)
+        return to;
+    const groupId = m[1];
+    const normalizedTo = to.replace(/^(onebot|qq|lagrange):/i, "").trim();
+    const numericPart = normalizedTo.replace(/^user:/i, "");
+    if (numericPart === groupId || normalizedTo === groupId) {
+        return stored;
+    }
+    return to;
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 内置定时任务调度器
+ * 根据配置在指定时间直接执行脚本，无需 AI 介入
+ */
+export interface CronJobConfig {
+    /** 任务名称，用于日志 */
+    name: string;
+    /** cron 表达式，如 "0 8 * * *" 表示每天 8:00 */
+    cron: string;
+    /** 时区，如 "Asia/Shanghai"，默认 "Asia/Shanghai" */
+    timezone?: string;
+    /** 脚本路径，相对 process.cwd() 或绝对路径，支持 .mjs/.ts/.mts */
+    script: string;
+    /** 要推送的群号列表 */
+    groupIds: number[];
+}
+export declare function getCronJobsFromConfig(api: any): CronJobConfig[];
+export declare function startScheduler(api: any): void;
+export declare function stopScheduler(): void;

package/dist/scheduler.js

@@ -0,0 +1,70 @@
+/**
+ * 内置定时任务调度器
+ * 根据配置在指定时间直接执行脚本，无需 AI 介入
+ */
+import { CronJob } from "cron";
+import { loadScript } from "./load-script.js";
+import { onebotClient } from "./tools.js";
+import { getWs } from "./connection.js";
+import WebSocket from "ws";
+let scheduledJobs = [];
+export function getCronJobsFromConfig(api) {
+    const cfg = api?.config ?? globalThis.__onebotGatewayConfig;
+    const jobs = cfg?.channels?.onebot?.cronJobs;
+    if (!Array.isArray(jobs) || jobs.length === 0)
+        return [];
+    return jobs.filter((j) => j &&
+        typeof j.name === "string" &&
+        typeof j.cron === "string" &&
+        typeof j.script === "string" &&
+        Array.isArray(j.groupIds));
+}
+async function runJob(api, job) {
+    const logger = api?.logger;
+    const w = getWs();
+    if (!w || w.readyState !== WebSocket.OPEN) {
+        logger?.warn?.(`[onebot] cron "${job.name}" 跳过：OneBot 未连接`);
+        return;
+    }
+    logger?.info?.(`[onebot] cron 执行: ${job.name}`);
+    try {
+        const mod = await loadScript(job.script);
+        const fn = mod?.default ?? mod?.run ?? mod?.execute;
+        if (typeof fn !== "function") {
+            logger?.error?.(`[onebot] cron "${job.name}": 脚本未导出 default/run/execute 函数`);
+            return;
+        }
+        const ctx = {
+            onebot: onebotClient,
+            groupIds: job.groupIds,
+        };
+        const result = await fn(ctx);
+        logger?.info?.(`[onebot] cron "${job.name}" 完成: ${result != null ? String(result) : "ok"}`);
+    }
+    catch (e) {
+        logger?.error?.(`[onebot] cron "${job.name}" 失败: ${e?.message}`);
+    }
+}
+export function startScheduler(api) {
+    stopScheduler();
+    const jobs = getCronJobsFromConfig(api);
+    if (jobs.length === 0)
+        return;
+    const logger = api?.logger;
+    logger?.info?.(`[onebot] 启动 ${jobs.length} 个定时任务（无 AI 介入）`);
+    for (const job of jobs) {
+        try {
+            const cronJob = new CronJob(job.cron, () => runJob(api, job), null, true, job.timezone ?? "Asia/Shanghai");
+            scheduledJobs.push(cronJob);
+        }
+        catch (e) {
+            logger?.warn?.(`[onebot] cron "${job.name}" 注册失败: ${e?.message}`);
+        }
+    }
+}
+export function stopScheduler() {
+    for (const j of scheduledJobs) {
+        j.stop();
+    }
+    scheduledJobs = [];
+}

package/dist/sdk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenClaw / ClawdBot Plugin SDK 懒加载
+ */
+export declare function loadPluginSdk(): Promise<void>;
+export declare function getSdk(): {
+    buildPendingHistoryContextFromMap: any;
+    recordPendingHistoryEntry: any;
+    clearHistoryEntriesIfEnabled: any;
+};

package/dist/sdk.js

@@ -0,0 +1,36 @@
+/**
+ * OpenClaw / ClawdBot Plugin SDK 懒加载
+ */
+let sdkLoaded = false;
+let buildPendingHistoryContextFromMap;
+let recordPendingHistoryEntry;
+let clearHistoryEntriesIfEnabled;
+export async function loadPluginSdk() {
+    if (sdkLoaded)
+        return;
+    try {
+        const sdk = await import("openclaw/plugin-sdk");
+        buildPendingHistoryContextFromMap = sdk.buildPendingHistoryContextFromMap;
+        recordPendingHistoryEntry = sdk.recordPendingHistoryEntry;
+        clearHistoryEntriesIfEnabled = sdk.clearHistoryEntriesIfEnabled;
+    }
+    catch {
+        try {
+            const sdk = await import("clawdbot/plugin-sdk");
+            buildPendingHistoryContextFromMap = sdk.buildPendingHistoryContextFromMap;
+            recordPendingHistoryEntry = sdk.recordPendingHistoryEntry;
+            clearHistoryEntriesIfEnabled = sdk.clearHistoryEntriesIfEnabled;
+        }
+        catch {
+            console.warn("[onebot] plugin-sdk not found, history features disabled");
+        }
+    }
+    sdkLoaded = true;
+}
+export function getSdk() {
+    return {
+        buildPendingHistoryContextFromMap,
+        recordPendingHistoryEntry,
+        clearHistoryEntriesIfEnabled,
+    };
+}

package/dist/send.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OneBot 消息发送 — 文本与媒体
+ * 对应 Lagrange.onebot context.ts 的 sendPrivateMsg / sendGroupMsg / 图片消息
+ */
+export interface OneBotSendResult {
+    ok: boolean;
+    messageId?: string;
+    error?: string;
+}
+import type { OneBotAccountConfig } from "./types.js";
+type OneBotConfigGetter = () => OneBotAccountConfig | null;
+/**
+ * 发送文本消息到 OneBot 目标（私聊或群聊）
+ * @param getConfig 可选，用于按需连接（forward-websocket 下 message send 可独立运行）
+ */
+export declare function sendTextMessage(to: string, text: string, getConfig?: OneBotConfigGetter): Promise<OneBotSendResult>;
+/**
+ * 发送媒体消息（图片等）到 OneBot 目标
+ * mediaUrl 支持 file:// 路径、http(s):// URL、base64://
+ * @param getConfig 可选，用于按需连接
+ */
+export declare function sendMediaMessage(to: string, mediaUrl: string, text?: string, getConfig?: OneBotConfigGetter): Promise<OneBotSendResult>;
+export {};

package/dist/send.js

@@ -0,0 +1,98 @@
+/**
+ * OneBot 消息发送 — 文本与媒体
+ * 对应 Lagrange.onebot context.ts 的 sendPrivateMsg / sendGroupMsg / 图片消息
+ */
+import { sendPrivateMsg, sendGroupMsg, sendPrivateImage, sendGroupImage, } from "./connection.js";
+import { resolveTargetForReply } from "./reply-context.js";
+function parseTarget(to) {
+    const t = to.replace(/^(onebot|qq|lagrange):/i, "").trim();
+    if (!t)
+        return null;
+    if (t.startsWith("group:")) {
+        const id = parseInt(t.slice(6), 10);
+        if (isNaN(id))
+            return null;
+        return { type: "group", id };
+    }
+    const raw = t.replace(/^user:/, "");
+    const id = parseInt(raw, 10);
+    if (isNaN(id))
+        return null;
+    if (raw === t && !t.includes(":")) {
+        return { type: id > 100000000 ? "user" : "group", id };
+    }
+    return { type: "user", id };
+}
+/**
+ * 发送文本消息到 OneBot 目标（私聊或群聊）
+ * @param getConfig 可选，用于按需连接（forward-websocket 下 message send 可独立运行）
+ */
+export async function sendTextMessage(to, text, getConfig) {
+    const resolvedTo = resolveTargetForReply(to);
+    const target = parseTarget(resolvedTo);
+    if (!target) {
+        return { ok: false, error: `Invalid target: ${to}` };
+    }
+    if (!text?.trim()) {
+        return { ok: false, error: "No text provided" };
+    }
+    try {
+        let messageId;
+        if (target.type === "group") {
+            messageId = await sendGroupMsg(target.id, text, getConfig);
+        }
+        else {
+            messageId = await sendPrivateMsg(target.id, text, getConfig);
+        }
+        return { ok: true, messageId: messageId != null ? String(messageId) : "" };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * 发送媒体消息（图片等）到 OneBot 目标
+ * mediaUrl 支持 file:// 路径、http(s):// URL、base64://
+ * @param getConfig 可选，用于按需连接
+ */
+export async function sendMediaMessage(to, mediaUrl, text, getConfig) {
+    const resolvedTo = resolveTargetForReply(to);
+    const target = parseTarget(resolvedTo);
+    if (!target) {
+        return { ok: false, error: `Invalid target: ${to}` };
+    }
+    if (!mediaUrl?.trim()) {
+        return { ok: false, error: "No mediaUrl provided" };
+    }
+    try {
+        let messageId;
+        if (text?.trim()) {
+            if (target.type === "group") {
+                messageId = await sendGroupMsg(target.id, text, getConfig);
+            }
+            else {
+                messageId = await sendPrivateMsg(target.id, text, getConfig);
+            }
+        }
+        if (target.type === "group") {
+            const id = await sendGroupImage(target.id, mediaUrl, undefined, getConfig);
+            if (id != null)
+                messageId = id;
+        }
+        else {
+            const id = await sendPrivateImage(target.id, mediaUrl, undefined, getConfig);
+            if (id != null)
+                messageId = id;
+        }
+        return { ok: true, messageId: messageId != null ? String(messageId) : "" };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/dist/service.d.ts

@@ -0,0 +1,4 @@
+/**
+ * OneBot WebSocket 服务
+ */
+export declare function registerService(api: any): void;